Module Identification

Plugin for module classification against a library of predefined types.

module_identification.execute(config: module_identification.Configuration) → Optional[module_identification.Result]

Perform a full run of the module identification process on the given netlist with the provided configuration.

This function executes the complete module identification process on the specified netlist. It uses the provided configuration to guide the identification process and returns a result object containing information about all analyzed candidates.

Parameters: config (module_identification.Configuration) – The configuration to guide the identification process.
Returns: The result of the run containing all computed results and options for further processing on success, None otherwise.
Return type: module_identification.Result or None

module_identification.execute_on_gates(gates: List[hal_py.Gate], config: module_identification.Configuration) → Optional[module_identification.Result]

Perform a module identification run on the specified gates with the provided configuration.

This function executes the module identification process on a specific set of gates. It uses the provided configuration to guide the identification process and returns a result object containing information about all analyzed candidates.

Parameters

gates (list[hal_py.Gate]) – The gates to be analyzed.
config (module_identification.Configuration) – The configuration to guide the identification process.

Returns

The result of the run containing all computed results and options for further processing on success, None otherwise.

Return type

module_identification.Result or None

class module_identification.Configuration

Configuration for the module identification analysis. This struct holds important parameters that configure the module identification analysis, including netlist to analyze, known registers, candidate types to check, threading options, etc.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: module_identification.Configuration, nl: hal_py.Netlist) -> None

Constructs a new ModuleIdentification analysis configuration for the given netlist.

param hal_py.Netlist nl

The netlist to be analyzed.
__init__(self: module_identification.Configuration) -> None

Constructs an empty configuration.

property already_classified_candidates

Gates to ignore during processing.

Type: list[list[hal_py.Gate]]

property blocked_base_candidates

Base candidates to block during analysis.

Type: list[set[hal_py.Gate]]

property known_registers

A vector handling possibly known registers.

Type: list[list[hal_py.Gate]]

property max_control_signals

Maximum number of control signals to be tested. Defaults to 3.

Type: int

property max_thread_count

Maximum number of concurrent threads created during execution. Defaults to 1.

Type: int

property multithreading_priority

Choose which MultithreadingPriority to use for the analysis. Defaults to memory priority

Type: module_identification.MultithreadingPriority

property netlist

The netlist to be analyzed.

Type: hal_py.Netlist

property types_to_check

CandidateTypes that shall be checked. Defaults to all checkable candidate types.

Type: list[module_identification.CandidateType]

with_already_classified_candidates(self: module_identification.Configuration, already_classified_candidates: List[List[hal_py.Gate]]) → module_identification.Configuration

Add gates to be ignored during processing.

All candidates that are build during the module identification run that contain any gates that overlap with any already classified candidate are discarded to avoid conflicts.

Parameters: already_classified_candidates (list[list[hal_py.Gate]]) – Candidates to be ignored.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_blocked_base_candidates(self: module_identification.Configuration, blocked_base_candidates: List[Set[hal_py.Gate]]) → module_identification.Configuration

Add base candidates to be blocked during analysis.

Parameters: blocked_base_candidates (list[set[hal_py.Gate]]) – Base candidates to be ignored.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_known_registers(self: module_identification.Configuration, registers: List[List[hal_py.Gate]]) → module_identification.Configuration

Set the known registers for prioritization.

Parameters: registers (list[list[hal_py.Gate]]) – The groups provided by a dana run.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_max_control_signals(self: module_identification.Configuration, max_control_signals: int) → module_identification.Configuration

Set the maximum number of control signals to be tested.

Parameters: max_control_signals (int) – The number of control signals checked.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_max_thread_count(self: module_identification.Configuration, max_thread_count: int) → module_identification.Configuration

Set the maximum number of threads.

Parameters: max_thread_count (int) – The number of threads to be started at max.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_multithreading_priority(self: module_identification.Configuration, priority: hal::module_identification::MultithreadingPriority) → module_identification.Configuration

Set the multithreading priority type.

Parameters: priority (module_identification.MultithreadingPriority) – The type of multithreading used during execution.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

with_types_to_check(self: module_identification.Configuration, types_to_check: List[hal::module_identification::CandidateType]) → module_identification.Configuration

Set the candidate types to be checked.

Parameters: types_to_check (list[module_identification.CandidateType]) – A list of candidate types to be checked for.
Returns: The updated module identification configuration.
Return type: module_identification.Configuration

class module_identification.Result

The result of a module identification run containing the candidates.

__init__(self: module_identification.Result, nl: hal_py.Netlist, result: List[Tuple[hal::module_identification::BaseCandidate, hal::module_identification::VerifiedCandidate]], timing_stats_json: str = '') → None

Constructor for Result.

Parameters

nl (hal_py.Netlist) – The netlist on which module identification has been performed.
result (list[tuple(module_identification.BaseCandidate, module_identification.VerifiedCandidate)]) – A vector of pairs containing base candidates and their verified candidates.
timing_stats_json (str) – A JSON string containing timing statistics. Defaults to an empty string.

static assign_base_candidates_to_iterations(iteration_results: List[module_identification.Result], create_block_lists: bool = False) → List[List[Set[hal_py.Gate]]]

For different runs of the plugin figure out in which iteration the plugin found the highest quality result for each candidate.

This is used to compare the results of different runs of the plugin and afterwards get a list of base candidates for each execution for which this execution gave the best results.

Parameters

iteration_results (list[module_identification.Result]) – A vector of all the execution results.
create_block_lists (bool) – A parameter to determine whether to create allow or block lists.

Returns

A vector of allow or block lists for each plugin execution iteration.

Return type

list[list[set[hal_py.Gate]]]

create_modules_in_netlist(self: module_identification.Result) → Optional[bool]

Creates a HAL module for each candidate of the result.

Returns: `True` on success, `False` otherwise.
Return type: bool

get_all_gates(self: module_identification.Result) → Set[hal_py.Gate]

Get all gates contained in any of the candidates.

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

get_all_verified_gates(self: module_identification.Result) → Set[hal_py.Gate]

Get all gates contained in any of the verified candidates.

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

get_candidate_by_id(self: module_identification.Result, id: int) → Optional[hal::module_identification::VerifiedCandidate]

Get the candidate with the corresponding ID.

Parameters: id (int) – The ID of the requested candidate.
Returns: The verified candidate on success, None otherwise.
Return type: module_identification.VerifiedCandidate or None

get_candidate_gates(self: module_identification.Result) → Dict[int, List[hal_py.Gate]]

Get a map of the candidate IDs to the gates contained inside the candidate.

This map contains all checked candidates, even the ones not verified. The ID is only unique for this result.

Returns: A map of candidate IDs to a vector of gates.
Return type: dict[int, list[hal_py.Gate]]

get_candidate_gates_by_id(self: module_identification.Result, id: int) → Optional[List[hal_py.Gate]]

Get the gates of the candidate with the corresponding ID.

Parameters: id (int) – The ID of the requested candidate.
Returns: The gates of the candidate on success, None otherwise.
Return type: list[hal_py.Gate] or None

get_candidates(self: module_identification.Result) → Dict[int, hal::module_identification::VerifiedCandidate]

Get a map of the candidate IDs to the candidates.

This map contains all checked candidates, even the ones not verified. The ID is only unique for this result.

Returns: A map of candidate IDs to candidates.
Return type: dict[int, module_identification.VerifiedCandidate]

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

Get the netlist on which module identification has been performed.

Returns: The netlist.
Return type: hal_py.Netlist

get_timing_stats(self: module_identification.Result) → str

Get the collected timing information formatted as a JSON string.

Returns: A JSON formatted string.
Return type: str

get_verified_candidate_gates(self: module_identification.Result) → Dict[int, List[hal_py.Gate]]

Get a map of the candidate IDs to the gates contained inside the verified candidates.

This map only contains verified candidates that are fully verified. The ID is only unique for this result.

Returns: A map of candidate IDs to a vector of gates.
Return type: dict[int, list[hal_py.Gate]]

get_verified_candidates(self: module_identification.Result) → Dict[int, hal::module_identification::VerifiedCandidate]

Get a map of the candidate IDs to the verified candidates.

This map only contains verified candidates that are fully verified. The ID is only unique for this result.

Returns: A map of candidate IDs to verified candidates.
Return type: dict[int, module_identification.VerifiedCandidate]

merge(self: module_identification.Result, other: module_identification.Result, registers: List[List[hal_py.Gate]]) → Optional[module_identification.Result]

Merges two results by combining the found verified candidates.

When both results contain a verified candidate for the same base candidate, the better one is chosen via the same post-processing used in the original module identification process. This requires that the base candidates are identical and that all gates of all candidates still exist in the netlist!

Parameters

other (module_identification.Result) – Another module identification result that is merged with this one.
registers (list[list[hal_py.Gate]]) – A list of previously identified register groupings that is used in the post-processing.

Returns

The merged module identification result on success, None otherwise.

Return type

module_identification.Result or None

class module_identification.Architecture

Defines supported FPGA architectures. This enum specifies the FPGA architectures that are supported by the module identification plugin.

Members:

lattice_ice40 : Lattice iCE40 FPGA architecture.

xilinx_unisim : Xilinx Unisim FPGA architecture.

property name

class module_identification.CandidateType

Enumeration of the different candidate types for module identification. This enum specifies the types of operations that the module identification process can recognize and verify, such as arithmetic operations and comparisons.

Members:

addition : Addition operation.

addition_offset : Addition with constant offset operation.

subtraction : Subtraction operation.

counter : Counter operation.

negation : Negation operation.

absolute : Absolute value operation.

constant_multiplication : Constant multiplication operation.

constant_multiplication_offset : Constant multiplication with constant offset operation.

equal : Equality comparison.

less_than : Less-than comparison.

less_equal : Less-than-or-equal comparison.

signed_less_than : Signed less-than comparison.

signed_less_equal : Signed less-than-or-equal comparison.

value_check : Value check against a constant operation.

none : No operation.

mixed : Mixed operation, for merged VerifiedCandidates that contain multiple candidate types.

property name

class module_identification.MultithreadingPriority

Specifies the strategy for multithreading in the module identification process. This enum class defines the strategies for managing multithreading in the module identification plugin. The strategies determine how resources are allocated and prioritized when performing multithreaded operations.

Members:

time_priority
Prioritize time efficiency in multithreading. This option specifies that multithreading should be handled with a priority on time efficiency, aiming to complete tasks as quickly as possible.

memory_priority
Prioritize memory efficiency in multithreading. This option specifies that multithreading should be handled with a priority on memory efficiency, aiming to minimize memory usage even if it results in longer execution times.

property name

class module_identification.WordLevelOperation

Represents a word-level operation with its operands, control signals, and the operation implemented as a HAL Boolean function. This struct is used to store the information related to a word-level operation, which includes the operands, control signals, and the Boolean function representing the operation.

__init__(self: module_identification.WordLevelOperation) → None

property ctrl_signals

A vector of control signals as Boolean functions.

Type: list[hal_py.BooleanFunction]

property operands

A map of operand names to their corresponding Boolean functions.

Type: dict[str, hal_py.BooleanFunction]

property operation

The Boolean function representing the word-level operation.

Type: hal_py.BooleanFunction

class module_identification.VerifiedCandidate

This class is used to represent a verified candidate within the module identification process, providing methods for their creation, manipulation, and verification.

property base_gates

A vector of base gates associated with the candidate.

Type: list[hal_py.Gate]

property control_signal_mappings

A vector of all control mappings covered by this candidate.

Type: list[dict[hal_py.Net, hal_py.BooleanFunction.Value]]

property control_signals

A vector of control signal nets.

Type: list[hal_py.Net]

property gates

A vector of gates associated with the candidate.

Type: list[hal_py.Gate]

get_candidate_info(self: module_identification.VerifiedCandidate) → str

Get the candidate information as a string.

Returns: A string containing the candidate information.
Return type: str

get_merged_word_level_operation(self: module_identification.VerifiedCandidate) → hal_py.BooleanFunction

Get the merged word-level operation for the candidate.

The mergred word-level operation includes all word-level oprations that we were able to verify for different control mappings of the candidate.

Returns: The merged word-level operation as a Boolean function.
Return type: hal_py.BooleanFunction

get_name(self: module_identification.VerifiedCandidate) → str

Get the name of the candidate that represents the functionality of the candidate.

Returns: A string containing the name of the candidate.
Return type: str

is_verified(self: module_identification.VerifiedCandidate) → bool

Check if the candidate is verified.

Returns: True if the candidate is verified, False otherwise.
Return type: bool

static merge(candidates: List[module_identification.VerifiedCandidate]) → hal::Result<hal::module_identification::VerifiedCandidate>

Merge multiple verified candidates into a single candidate.

This function merges a vector of verified candidates into a single candidate.

Parameters: candidates (list[module_identification.VerifiedCandidate]) – A vector of verified candidates to merge.
Returns: The merged verified candidate on success.
Return type: module_identification.VerifiedCandidate