Dataflow Analysis (DANA)

Dataflow analysis tool DANA to recover word-level structures such as registers from gate-level netlists.

dataflow.analyze(config: dataflow.Configuration) → Optional[hal::dataflow::Result]

Analyze the gate-level netlist to identify word-level structures such as registers. Reconstructs word-level structures such as registers based on properties such as the control inputs of their flip-flops and common successors/predecessors. Operates on an abstraction of the netlist that contains only flip-flops and connections between two flip-flops only if they are connected through combinational logic.

Parameters: config (dataflow.Dataflow.Configuration) – The dataflow analysis configuration.
Returns: The dataflow analysis result on success, None otherwise.
Return type: dataflow.Dataflow.Result or None

class dataflow.Configuration

This class holds all information relevant for the configuration of a dataflow analysis run, including the netlist to analyze.

__init__(self: dataflow.Configuration, nl: hal_py.Netlist) → None

Construct a new dataflow analysis configuration for the given netlist.

Parameters: nl (hal_py.Netlist) – The netlist.

property control_pin_types

The pin types of the pins to be considered control pins. Defaults to an empty set.

Type: set[hal_py.PinType]

property enable_stages

Enable stage identification as part of dataflow analysis. Defaults to False.

Type: bool

property enforce_type_consistency

Enforce gate type consistency inside of a group. Defaults to False.

Type: bool

property expected_sizes

Expected group sizes. Groups of these sizes will be prioritized. Defaults to an empty list.

Type: list[int]

property gate_types

The gate types to be grouped by dataflow analysis. Defaults to an empty set.

Type: set[hal_py.GateType]

property known_gate_groups

Groups of gates that have already been identified as word-level groups beforehand. All gates of a group must be of one of the target gate types. Defaults to an empty list.

Type: list[list[hal_py.Gate]]

property known_net_groups

Groups of nets that have been identified as word-level datapathes beforehand. Defaults to an empty list.

Type: list[list[hal_py.Net]]

property min_group_size

Minimum size of a group. Smaller groups will be penalized during analysis. Defaults to 8.

Type: int

with_control_pin_types(self: dataflow.Configuration, types: Set[hal_py.PinType], overwrite: bool = False) → dataflow.Configuration

Set the pin types of the pins to be considered control pins by dataflow analysis. Overwrite the existing set of pin types by setting the optional overwrite flag to True.

Parameters

types (set[hal_py.PinType]) – A set of pin types.
enable (bool) – Set True to overwrite existing set of pin types, False otherwise. Defaults to False.

Returns

The updated dataflow analysis configuration.

Return type

dataflow.Dataflow.Configuration

with_expected_sizes(self: dataflow.Configuration, sizes: List[int]) → dataflow.Configuration

Set the expected group sizes. Groups of these sizes will be prioritized.

Parameters: sizes (list[int]) – The expected group sizes.
Returns: The updated dataflow analysis configuration.
Return type: dataflow.Dataflow.Configuration

with_flip_flops(self: dataflow.Configuration) → dataflow.Configuration

Use the default detection configuration for flip-flops. Includes all flip-flop types as target gate types and sets clock, enable, set, and reset pins as control pins. Overwrites any existing gate type and control pin configuration.

Returns: The updated dataflow analysis configuration.
Return type: dataflow.Dataflow.Configuration

with_gate_types(*args, **kwargs)

Overloaded function.

with_gate_types(self: dataflow.Configuration, types: Set[hal_py.GateType], overwrite: bool = False) -> dataflow.Configuration

Add the gate types to the set of gate types to be grouped by dataflow analysis. Overwrite the existing set of gate types by setting the optional overwrite flag to True.

param set[hal_py.GateType] types

A set of gate types.

param bool overwrite

Set True to overwrite existing set of gate types, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_gate_types(self: dataflow.Configuration, type_properties: Set[hal_py.GateTypeProperty], overwrite: bool = False) -> dataflow.Configuration

Add the gate types featuring the specified properties to the set of gate types to be grouped by dataflow analysis. Overwrite the existing set of gate types by setting the optional overwrite flag to True.

param set[hal_py.GateTypeProperty] type_properties

A set of gate type properties.

param bool overwrite

Set True to overwrite existing set of gate types, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration

with_known_groups(*args, **kwargs)

Overloaded function.

with_known_groups(self: dataflow.Configuration, groups: List[hal_py.Module], overwrite: bool = False) -> dataflow.Configuration

Add modules to the set of previously identified word-level groups. These groups must only contain gates of the target gate types specified for analysis and will otherwise be ignored. The groups will be used to guide dataflow analysis, but will remain unaltered in the process.

param list[hal_py.Module] groups

A list of modules.

param bool overwrite

Set True to overwrite the existing previously identified word-level groups, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_groups(self: dataflow.Configuration, groups: List[List[hal_py.Gate]], overwrite: bool = False) -> dataflow.Configuration

Add lists of gates to the set of previously identified word-level groups. These groups must only contain gates of the target gate types specified for analysis and will otherwise be ignored. The groups will be used to guide dataflow analysis, but will remain unaltered in the process.

param list[list[hal_py.Gate]] groups

A list of groups, each of them given as a list of gates.

param bool overwrite

Set True to overwrite the existing previously identified word-level groups, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_groups(self: dataflow.Configuration, groups: List[List[int]], overwrite: bool = False) -> dataflow.Configuration

Add lists of gate IDs to the set of previously identified word-level groups. These groups must only contain gates of the target gate types specified for analysis and will otherwise be ignored. The groups will be used to guide dataflow analysis, but will remain unaltered in the process.

param list[list[int]] groups

A list of groups, each of them given as a list of gate IDs.

param bool overwrite

Set True to overwrite the existing previously identified word-level groups, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_groups(self: dataflow.Configuration, groups: Dict[int, Set[hal_py.Gate]], overwrite: bool = False) -> dataflow.Configuration

Add groups from a previous dataflow analysis run to the set of previously identified word-level groups. These groups must only contain gates of the target gate types specified for analysis and will otherwise be ignored. The groups will be used to guide dataflow analysis, but will remain unaltered in the process. The group IDs will be ignored during analysis and the same group may be assigned a new ID.

param dict[int,set[hal_py.Gate]] groups

A dict from group IDs to groups, each of them given as a set of gates.

param bool overwrite

Set True to overwrite the existing previously identified word-level groups, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration

with_known_structures(*args, **kwargs)

Overloaded function.

with_known_structures(self: dataflow.Configuration, structures: List[hal_py.Module], overwrite: bool = False) -> dataflow.Configuration

Add modules to the set of previously identified word-level structures. The gates contained in the modules do not have to be of the target gate types. The input and output pin groups of these modules will be used to guide datapath analysis. Only pin groups larger than min_group_size will be considered.

param list[hal_py.Module] structures

A list of modules.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_structures(self: dataflow.Configuration, structures: List[Tuple[hal_py.Module, List[hal_py.ModulePinGroup]]], overwrite: bool = False) -> dataflow.Configuration

Add modules to the set of previously identified word-level structures. The gates contained in the modules do not have to be of the target gate types. The input and output pin groups of these modules will be used to guide datapath analysis. For each module, the input and output pin groups to be considered for analysis must be specified. An empty pin group vector results in all pin groups of the module being considered. Only pin groups larger than min_group_size will be considered.

param list[tuple(hal_py.Module,list[hal_py.ModulePinGroup])] structures

A list of modules, each of them with a list of module pin groups.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_structures(self: dataflow.Configuration, structures: List[hal_py.Gate], overwrite: bool = False) -> dataflow.Configuration

Add (typically large) gates to the set of previously identified word-level structures. The gates do not have to be of the target gate types. The input and output pin groups of these gates will be used to guide datapath analysis. Only pin groups larger than min_group_size will be considered.

param list[hal_py.Gate] structures

A list of gates.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_structures(self: dataflow.Configuration, structures: List[Tuple[hal_py.Gate, List[hal_py.GatePinGroup]]], overwrite: bool = False) -> dataflow.Configuration

Add (typically large) gates to the set of previously identified word-level structures. The gates do not have to be of the target gate types. The input and output pin groups of these gates will be used to guide datapath analysis. For each gate, the input and output pin groups to be considered for analysis must be specified. An empty pin group vector results in all pin groups of the gate being considered. Only pin groups larger than min_group_size will be considered.

param list[tuple(hal_py.Gate,list[hal_py.GatePinGroup])] structures

A list of gates, each of them with a list of gate pin groups.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_structures(self: dataflow.Configuration, structures: Set[hal_py.GateType], overwrite: bool = False) -> dataflow.Configuration

Add all gates of a (typically large) gate type to the set of previously identified word-level structures. The gate types do not have to be part of the target gate types. The input and output pin groups of the gates of these types will be used to guide datapath analysis. Only pin groups larger than min_group_size will be considered.

param set[hal_py.GateType] structures

A set of gates.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration
with_known_structures(self: dataflow.Configuration, structures: Dict[hal_py.GateType, List[hal_py.GatePinGroup]], overwrite: bool = False) -> dataflow.Configuration

Add all gates of a (typically large) gate type to the set of previously identified word-level structures. The gate types do not have to be part of the target gate types. The input and output pin groups of the gates of these types will be used to guide datapath analysis. For each gate type, the input and output pin groups to be considered for analysis must be specified. An empty pin group vector results in all pin groups of the gate type being considered. Only pin groups larger than min_group_size will be considered.

param dict[hal_py.GateType,list[hal_py.GatePinGroup]] structures

A dict from gates to a vector of a subset of their pin groups.

param bool overwrite

Set True to overwrite the existing known word-level structures, False otherwise. Defaults to False.

returns

The updated dataflow analysis configuration.

rtype

dataflow.Dataflow.Configuration

with_min_group_size(self: dataflow.Configuration, size: int) → dataflow.Configuration

Set the minimum size of a group. Smaller groups will be penalized during analysis.

Parameters: size (int) – The minimum group size.
Returns: The updated dataflow analysis configuration.
Return type: dataflow.Dataflow.Configuration

with_stage_identification(self: dataflow.Configuration, enable: bool = True) → dataflow.Configuration

Enable stage identification as part of dataflow analysis.

Parameters: enable (bool) – Set True to enable stage identification, False otherwise. Defaults to True.
Returns: The updated dataflow analysis configuration.
Return type: dataflow.Dataflow.Configuration

with_type_consistency(self: dataflow.Configuration, enable: bool = True) → dataflow.Configuration

Enable type consistency as part of dataflow analysis when deciding whether two gates are allowed to merge into the same group.

Parameters: enable (bool) – Set True to enable type consistency inside of a group, False otherwise. Defaults to True.
Returns: The updated dataflow analysis configuration.
Return type: dataflow.Dataflow.Configuration

class dataflow.Result

This class holds result of a dataflow analysis run, which contains the identified groups of sequential gates and their interconnections. Each such group is assigned a unique ID by which it can be addressed in many of the member functions of this class. Please note that this ID is not related to any other HAL ID.

create_modules(*args, **kwargs)

Overloaded function.

create_modules(self: dataflow.Result, group_ids: Set[int] = set()) -> Optional[Dict[int, hal_py.Module]]

Create modules for the dataflow analysis result.

param set[int] group_ids

The group IDs to consider. If an empty set is provided, all groups will be considered. Defaults to an empty set.

returns

A map from group IDs to Modules on success, None otherwise.

rtype

dict[int,hal_py.Module] or None
create_modules(self: dataflow.Result, module_suffixes: Dict[hal_py.GateType, str], pin_prefixes: Dict[Tuple[hal_py.PinDirection, str], str], group_ids: Set[int]) -> Optional[Dict[int, hal_py.Module]]

Create modules for the dataflow analysis result.

param dict[hal_py.GateType,str] module_suffixes

The suffixes to use for modules containing only gates of a specific gate type. Defaults to "module" for mixed and unspecified gate types.

param dict[tuple(hal_py.PinDirection,str),str] pin_prefixes

The prefixes to use for the module pins that (within the module) only connect to gate pins of a specific name.

param set[int] group_ids

The group IDs to consider. If no IDs are provided, all groups will be considered.

returns

A map from group IDs to Modules on success, None otherwise.

rtype

dict[int,hal_py.Module] or None
create_modules(self: dataflow.Result, module_suffixes: Dict[hal_py.GateTypeProperty, str], pin_prefixes: Dict[Tuple[hal_py.PinDirection, str], str], group_ids: Set[int]) -> Optional[Dict[int, hal_py.Module]]

Create modules for the dataflow analysis result.

param dict[hal_py.GateTypeProperty,str] module_suffixes

The suffixes to use for modules containing only gates of a specific gate type. All gate types featuring the specified gate type property are considered, but the module must still be pure (i.e., all gates must be of the same type) for the suffix to be used. Defaults to "module" for mixed and unspecified gate types.

param dict[tuple(hal_py.PinDirection,str),str] pin_prefixes

The prefixes to use for the module pins that (within the module) only connect to gate pins of a specific name.

param set[int] group_ids

The group IDs to consider. If no IDs are provided, all groups will be considered.

returns

A map from group IDs to Modules on success, None otherwise.

rtype

dict[int,hal_py.Module] or None

get_gate_control_nets(self: dataflow.Result, gate: hal_py.Gate, type: hal_py.PinType) → Optional[Set[hal_py.Net]]

Get the control nets of the given gate that are connected to a pin of the specified type.

Parameters

gate (hal_py.Gate) – The gate.
type (hal_py.PinType) – The pin type.

Returns

A set of control nets of the gate on success, None otherwise.

Return type

set[hal_py.Net] or None

get_gate_predecessors(self: dataflow.Result, gate: hal_py.Gate) → Optional[Set[hal_py.Gate]]

Get the sequential predecessor gates of the given sequential gate.

Parameters: gate (hal_py.Gate) – The gate.
Returns: The predecessors of the gate as a set of gates on success, None otherwise.
Return type: set[hal_py.Gate] or None

get_gate_successors(self: dataflow.Result, gate: hal_py.Gate) → Optional[Set[hal_py.Gate]]

Get the sequential successor gates of the given sequential gate.

Parameters: gate (hal_py.Gate) – The gate.
Returns: The successors of the gate as a set of gates on success, None otherwise.
Return type: set[hal_py.Gate] or None

get_gates(self: dataflow.Result) → List[hal_py.Gate]

Get all gates contained in any of the groups groups.

Returns: A list of gates.
Return type: list[hal_py.Gate]

get_gates_of_group(self: dataflow.Result, group_id: int) → Optional[Set[hal_py.Gate]]

Get the gates of the specified group of sequential gates.

Parameters: group_id (int) – The ID of the group.
Returns: The gates of the group as a set on success, None otherwise.
Return type: set[hal_py.Gate] or None

get_group_control_nets(self: dataflow.Result, group_id: int, type: hal_py.PinType) → Optional[Set[hal_py.Net]]

Get the control nets of the group with the given group ID that are connected to a pin of the specified type.

Parameters

group_id (int) – The group ID.
type (hal_py.PinType) – The pin type.

Returns

A set of control nets of the group on success, None otherwise.

Return type

set[hal_py.Net] or None

get_group_id_of_gate(self: dataflow.Result, gate: hal_py.Gate) → Optional[int]

Get the group ID of the group that contains the given gate.

Parameters: gate (hal_py.Gate) – The gate.
Returns: The group ID on success, None otherwise.
Return type: int or None

get_group_list(self: dataflow.Result, group_ids: Set[int] = set()) → List[List[hal_py.Gate]]

Get the groups of the dataflow analysis result as a list.

Parameters: group_ids (set[int]) – The group IDs to consider. If no IDs are provided, all groups will be considered. Defaults to an empty set.
Returns: A list of groups with each group being a list of gates.
Return type: list[list[hal_py.Gate]]

get_group_predecessors(self: dataflow.Result, group_id: int) → Optional[Set[int]]

Get the predecessor groups of the group with the given ID.

Parameters: group_id (int) – The ID of the group.
Returns: The predecessors of the group as a set of group IDs on success, None otherwise.
Return type: set[int] or None

get_group_successors(self: dataflow.Result, group_id: int) → Optional[Set[int]]

Get the successor groups of the group with the given ID.

Parameters: group_id (int) – The group ID.
Returns: The successors of the group as a set of group IDs on success, None otherwise.
Return type: set[int] or None

get_groups(self: dataflow.Result) → Dict[int, Set[hal_py.Gate]]

Get the groups of sequential gates resulting from dataflow analysis.

Returns: A dict from group ID to a set of gates belonging to the respective group.
Return type: dict[int,set[hal_py.Gate]]

get_netlist(self: dataflow.Result) → hal_py.Netlist

Get the netlist on which dataflow analysis has been performed.

Returns: The netlist.
Return type: hal_py.Netlist

merge_groups(self: dataflow.Result, group_ids: List[int]) → Optional[int]

Merge multiple groups specified by ID. All specified groups are merged into the first group of the provided vector and are subsequently deleted.

Parameters: group_ids (set[int]) – The group IDs of the groups to merge.
Returns: The ID of the group that all other groups have been merged into on success, None otherwise.
Return type: int or None

split_group(self: dataflow.Result, group_id: int, new_groups: List[Set[hal_py.Gate]]) → Optional[List[int]]

Split a group into multiple smaller groups specified by sets of gates. All gates of the group to split must be contained in the sets exactly once and all gates in the sets must be contained in the group to split. The group that is being split is deleted in the process.

Parameters

group_id (int) – The group ID of the group to split.
new_groups (list[set[hal_py.Gate]]) – A list of groups specified as unordered sets of gates.

Returns

The group IDs of the newly created groups in the order of the provided sets.

Return type

list[int]

write_dot(self: dataflow.Result, out_path: os.PathLike, group_ids: Set[int] = set()) → bool

Write the dataflow graph as a DOT graph to the specified location.

Parameters

out_path (pathlib.Path) – The output path.
group_ids (set[int]) – The group IDs to consider. If no IDs are provided, all groups will be considered. Defaults to an empty set.

Returns

True on success, False otherwise.

Return type

bool

write_txt(self: dataflow.Result, out_path: os.PathLike, group_ids: Set[int] = set()) → bool

Write the groups resulting from dataflow analysis to a .txt file.

Parameters

out_path (pathlib.Path) – The output path.
group_ids (set[int]) – The group IDs to consider. If no IDs are provided, all groups will be considered. Defaults to an empty set.

Returns

True on success, False otherwise.

Return type

bool

class dataflow.DataflowPlugin

This class provides an interface to integrate the DANA tool as a plugin within the HAL framework.

property description

The short description of the plugin.

Type: str

get_description(self: dataflow.DataflowPlugin) → str

Get the short description of the plugin.

Returns: The short description of the plugin.
Return type: str

get_name(self: dataflow.DataflowPlugin) → str

Get the name of the plugin.

Returns: The name of the plugin.
Return type: str

get_version(self: dataflow.DataflowPlugin) → str

Get the version of the plugin.

Returns: The version of the plugin.
Return type: str

property name

The name of the plugin.

Type: str

property version

The version of the plugin.

Type: str