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.

  1. 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

  2. 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.

  1. 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

  2. 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

  3. 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

  4. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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.

  1. 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

  2. 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

  3. 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
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
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