hlsfactory.utils

Module Contents

Classes

CallToolResult	Represents the result of a tool call using call_tool.
ExecutionDataStatus	Standard statuses for a flow execution result.
FlowExecutionData	Execution result and timing data for one flow.
ExecutionData	Execution results keyed by flow name.
FlowTimer	A class for measuring the execution time of a flow.
DirSource	Enum class representing different sources for directories.
ToolPathsSource	Enumeration representing the source of tool paths.

Functions

call_tool
terminate_process_and_children	Terminate a process and all its child processes.
wait_for_files_creation
find_bin_path	Find the path of a binary executable.
update_execution_data_with_flow_results	Add or replace a flow result in execution_data.json.
read_execution_data	Reads execution_data.json from a design directory.
flow_already_completed	Checks whether a flow has already been recorded for a design.
serialize_methods_for_dataclass	Decorator function that adds serialization methods to a dataclass.
timeout_not_supported	Raises a RuntimeError indicating that timeout is not supported for the current flow.
get_work_dir	Get the working directory path based on the specified directory source.
get_tool_paths	Get the paths for Vitis HLS and Vivado tools based on the specified source.
get_tool_path_vitis_modern	Get the install path for the modern (post Vitis HLS/Vitis merge) Vitis Unified toolchain, e.g. /tools/software/xilinx/2026.1/Vitis.
remove_dir_if_exists	Remove a directory if it exists.
remove_and_make_new_dir_if_exists	Removes the directory at the given path if it exists, and then creates a new directory at the same path.
unwrap

Data

T
T_unwrap

API

class hlsfactory.utils.CallToolResult(*args, **kwds)

Bases: enum.Enum

Represents the result of a tool call using call_tool.

Initialization

SUCCESS = 'auto(...)'

TIMEOUT = 'auto(...)'

ERROR = 'auto(...)'

hlsfactory.utils.call_tool(cmd: str, cwd: pathlib.Path, shell: bool = False, timeout: float | None = None, log_output: bool = False, raise_on_error: bool = False) → hlsfactory.utils.CallToolResult

hlsfactory.utils.terminate_process_and_children(pid: int) → None

Terminate a process and all its child processes.

Args:

pid (int): The process ID of the parent process.

hlsfactory.utils.wait_for_files_creation(file_paths: list[pathlib.Path], timeout: float, poll_interval: float = 1) → bool

hlsfactory.utils.find_bin_path(cmd: str) → str

Find the path of a binary executable.

Args:

cmd (str): The name of the binary executable.

Returns:

str: The path of the binary executable.

Raises:

RuntimeError: If the binary executable cannot be found.

class hlsfactory.utils.ExecutionDataStatus

Bases: str, enum.Enum

Standard statuses for a flow execution result.

Initialization

Initialize self. See help(type(self)) for accurate signature.

SUCCESS = 'success'

ERROR = 'error'

TIMEOUT = 'timeout'

OTHER = 'other'

class hlsfactory.utils.FlowExecutionData

Execution result and timing data for one flow.

status: hlsfactory.utils.ExecutionDataStatus = None

t_start: float = None

t_end: float = None

dt: float = None

core: int | None = None

error_message: str | None = None

to_dict() → dict[str, Any]

classmethod from_dict(data: dict[str, Any]) → hlsfactory.utils.FlowExecutionData

to_json() → str

classmethod from_json(json_str: str) → hlsfactory.utils.FlowExecutionData

class hlsfactory.utils.ExecutionData

Execution results keyed by flow name.

flows: dict[str, hlsfactory.utils.FlowExecutionData] = None

to_dict() → dict[str, Any]

classmethod from_dict(data: dict[str, Any]) → hlsfactory.utils.ExecutionData

to_json() → str

classmethod from_json(json_str: str) → hlsfactory.utils.ExecutionData

hlsfactory.utils.update_execution_data_with_flow_results(design_dir: pathlib.Path, flow_name: str, status: hlsfactory.utils.ExecutionDataStatus, t_start: float, t_end: float, core: int | None = None, error_message: str | None = None) → None

Add or replace a flow result in execution_data.json.

Args:

design_dir (Path): The directory where the design is located. flow_name (str): The name of the flow (e.g. VitisHLSSynthFlow). status (ExecutionDataStatus): The result status for the flow. t_start (float): Start timestamp. t_end (float): End timestamp. core (int, optional): CPU core ID (defaults to current core). error_message (str, optional): Optional error message string.

Raises:

RuntimeError: If the design directory does not exist.

hlsfactory.utils.read_execution_data(design_dir: pathlib.Path, flow_name: str | None = None) → hlsfactory.utils.ExecutionData | hlsfactory.utils.FlowExecutionData | None

Reads execution_data.json from a design directory.

Args:

design_dir (Path): Directory containing execution_data.json. flow_name (str, optional): If provided, returns that flow’s execution data.

Returns:

The full execution data or the specific flow’s execution data.

hlsfactory.utils.flow_already_completed(design_dir: pathlib.Path, flow_name: str) → bool

Checks whether a flow has already been recorded for a design.

Args:

design_dir (Path): The directory where the design is located. flow_name (str): The name of the flow to check.

Returns:

bool: True if the flow has an entry in execution_data.json, False otherwise.

class hlsfactory.utils.FlowTimer(flow_name: str, dir_path: pathlib.Path)

A class for measuring the execution time of a flow.

Attributes:

flow_name (str): The name of the flow. dir_path (Path): The directory path where the execution time will be logged. t_0 (float | None): The start time of the flow execution. t_1 (float | None): The stop time of the flow execution.

Initialization

start() → None

Start the timer for measuring the flow execution time.

stop() → None

Stop the timer for measuring the flow execution time.

log(status: hlsfactory.utils.ExecutionDataStatus = ExecutionDataStatus.SUCCESS, error_message: str | None = None) → None

Log the execution data of the flow to execution_data.json.

Raises:

RuntimeError: If either t_0 or t_1 is None.

__enter__() → hlsfactory.utils.FlowTimer

Start the timer when entering a context.

Returns:

FlowTimer: The FlowTimer instance.

__exit__(_exc_type, _exc_value, _traceback) → None

Stop the timer and log the execution time when exiting a context.

hlsfactory.utils.T = 'TypeVar(...)'

hlsfactory.utils.serialize_methods_for_dataclass(cls: type[hlsfactory.utils.T]) → type[hlsfactory.utils.T]

Decorator function that adds serialization methods to a dataclass.

The serialization methods added are: - from_json: A class method that creates a dataclass instance from a JSON file. - to_json: An instance method that writes the dataclass instance to a JSON file. - from_yaml: A class method that creates a dataclass instance from a YAML file. - to_yaml: An instance method that writes the dataclass instance to a YAML file.

Args:

cls (type[T]): The dataclass to decorate.

Returns:

type[T]: The decorated dataclass.

Raises:

TypeError: If the decorated class is not a dataclass.

hlsfactory.utils.timeout_not_supported(flow_name: str) → None

Raises a RuntimeError indicating that timeout is not supported for the current flow.

Args:

flow_name (str): The name of the current flow.

Raises:

RuntimeError: Indicates that timeout is not supported for the current flow.

class hlsfactory.utils.DirSource(*args, **kwds)

Bases: enum.Enum

Enum class representing different sources for directories.

Used by get_work_dir to determine the source to look for a specific work directory to use.

Options: - ENVFILE: Look for the directory in the .env file. - ENV: Look for the directory in the environment variables. - TEMP: Create a temporary directory.

Initialization

ENVFILE = 'auto(...)'

ENV = 'auto(...)'

TEMP = 'auto(...)'

hlsfactory.utils.get_work_dir(dir_source: hlsfactory.utils.DirSource = DirSource.ENVFILE, env_file_path: pathlib.Path | None = None, use_cwd: bool = True) → pathlib.Path

Get the working directory path based on the specified directory source.

Args:

dir_source (DirSource, optional): The directory source to use. Defaults to DirSource.ENVFILE.

Returns:

pathlib.Path: The path to the working directory.

Raises:

ValueError: If the specified directory source is invalid or the working directory path is not found.

class hlsfactory.utils.ToolPathsSource(*args, **kwds)

Bases: enum.Enum

Enumeration representing the source of tool paths.

Used by get_tool_paths to determine the source to look for the paths of the tools to use.

Options: - ENVFILE: Look for the paths in the .env file. - ENV: Look for the paths in the environment variables.

Initialization

ENVFILE = 'auto(...)'

ENV = 'auto(...)'

hlsfactory.utils.get_tool_paths(tool_paths_source: hlsfactory.utils.ToolPathsSource, env_file_path: pathlib.Path | None = None, use_cwd: bool = True) → tuple[pathlib.Path, pathlib.Path]

Get the paths for Vitis HLS and Vivado tools based on the specified source.

Args:

tool_paths_source (ToolPathsSource): The source from which to retrieve the tool paths.

Returns:

tuple[pathlib.Path, pathlib.Path]: A tuple containing the paths for Vitis HLS and Vivado tools.

Raises:

ValueError: If the tool paths are not found in the specified source.

hlsfactory.utils.get_tool_path_vitis_modern(tool_paths_source: hlsfactory.utils.ToolPathsSource, env_file_path: pathlib.Path | None = None, use_cwd: bool = True) → pathlib.Path

Get the install path for the modern (post Vitis HLS/Vitis merge) Vitis Unified toolchain, e.g. /tools/software/xilinx/2026.1/Vitis.

This is a separate install root from the classic HLSFACTORY_VITIS_HLS_PATH / HLSFACTORY_VIVADO_PATH pair, since the merged Vitis toolchain ships its own bin/v++ and bin/vitis-run binaries under a single directory.

Args:

tool_paths_source (ToolPathsSource): The source from which to retrieve the tool path.

Returns:

pathlib.Path: The path to the modern Vitis install root.

Raises:

ValueError: If the tool path is not found in the specified source.

hlsfactory.utils.remove_dir_if_exists(dir_path: pathlib.Path) → None

Remove a directory if it exists.

Args:

dir_path (pathlib.Path): The path to the directory.

hlsfactory.utils.remove_and_make_new_dir_if_exists(dir_path: pathlib.Path) → None

Removes the directory at the given path if it exists, and then creates a new directory at the same path.

Args:

dir_path (pathlib.Path): The path to the directory.

hlsfactory.utils.T_unwrap = 'TypeVar(...)'

hlsfactory.utils.unwrap(value: hlsfactory.utils.T_unwrap | None, error_message: str | None = None) → hlsfactory.utils.T_unwrap