HAL  v4.5.0-83-g30c8f0afc
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
hal::module_identification Namespace Reference

Namespaces

 lattice_ice40
 
 xilinx_unisim
 

Classes

struct  Configuration
 Configuration for the module identification analysis. More...
 
struct  Result
 The result of a module identification run containing the candidates. More...
 
class  BaseCandidate
 Represents a base candidate in the module identification process. More...
 
struct  CandidateContext
 This struct manages the context of a candidate during module identification, including caches for all Boolean function related and expensive oprations that are populated during the functional candidate generation. More...
 
class  FunctionalCandidate
 Represents a functional candidate derived from structural candidates. More...
 
class  StructuralCandidate
 A class representing a structural candidate for module identification. More...
 
struct  WordLevelOperation
 Represents a word-level operation with its operands, control signals, and the operation implemented as a HAL Boolean function. More...
 
class  VerifiedCandidate
 Represents a verified candidate for module identification. More...
 
class  GuiLayoutLocker
 
struct  Statistics
 

Enumerations

enum class  Architecture { lattice_ice40 , xilinx_unisim }
 Defines supported FPGA architectures. More...
 
enum class  CandidateType {
  addition = 0 , addition_offset , subtraction , counter ,
  negation , absolute , constant_multiplication , constant_multiplication_offset ,
  equal , less_than , less_equal , signed_less_than ,
  signed_less_equal , value_check , none , mixed
}
 Enumeration of the different candidate types for module identification. More...
 
enum class  MultithreadingPriority { time_priority , memory_priority }
 Specifies the strategy for multithreading in the module identification process. More...
 

Functions

hal::Result< Resultexecute (const Configuration &config)
 Perform a full run of the module identification process on the given netlist with the provided configuration. More...
 
hal::Result< Resultexecute_on_gates (const std::vector< Gate * > &gates, const Configuration &config)
 Perform a module identification run on the specified gates with the provided configuration. More...
 
VerifiedCandidate post_processing (const std::vector< VerifiedCandidate > &verified_candidates, const Netlist *nl, const std::vector< std::vector< Gate * >> &dana_cache)
 Performs post-processing on a set of verified candidates to identify the best candidate for module identification. More...
 
std::set< u32find_neighboring_registers (const Net *n, const std::vector< std::vector< Gate * >> &registers)
 Find neighboring registers connected to a given net. More...
 
std::set< u32find_neighboring_registers (const std::vector< Net * > nets, const std::vector< std::vector< Gate * >> &registers)
 Find neighboring registers connected to a list of nets. More...
 
std::vector< std::vector< Net * > > reorder_commutative_operands (const std::vector< std::vector< Net * >> &operands, const std::vector< std::vector< Gate * >> &registers, const u32 permute_start_index=0)
 Reorder commutative operands based on a permutation cache. More...
 
std::vector< Net * > get_input_nets (const std::vector< Gate * > &gates)
 Get input nets from a list of gates. More...
 
std::vector< Net * > get_output_nets (const std::vector< Gate * > &gates, bool only_external_destinations=true)
 Get output nets from a list of gates. More...
 
hal::Result< std::vector< std::pair< std::unique_ptr< BaseCandidate >, std::vector< std::unique_ptr< StructuralCandidate > > > > > generate_structural_candidates (const Netlist *nl, const Configuration &config)
 
hal::Result< std::vector< FunctionalCandidate > > generate_functional_candidates (StructuralCandidate *sc, const Configuration &config, Statistics &stats)
 
bool has_constant_value (const z3::expr &e, const u64 &val)
 
bool has_constant_value (const BooleanFunction &bf, const u64 &val)
 
Result< VerifiedCandidatecheck_leq (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_addition (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_addition_offset (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_sub (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions, const std::vector< std::vector< Gate * >> &registers)
 
Result< VerifiedCandidatecheck_sliced_add (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_add_sub (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions, const std::vector< std::vector< Gate * >> &registers)
 
Result< VerifiedCandidatecheck_add_sub_offset (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions, const std::vector< std::vector< Gate * >> &registers)
 
Result< VerifiedCandidatecheck_value_check (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_constant_multiplication (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_constant_multiplication_offset (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_counter (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_absolute (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 
Result< VerifiedCandidatecheck_equal (FunctionalCandidate &fc, const std::vector< BooleanFunction > &output_functions)
 

Variables

const std::vector< CandidateTypeall_checkable_candidate_types
 A list of all candidate types that are selectable to be checked. More...
 
const std::map< CandidateType, u32candidate_type_max_operands
 A mapping of candidate types to their maximum number of operands. More...
 

Detailed Description

Identifies word-level operations such as adders, multipliers, and comparators within a gate-level netlist.

Enumeration Type Documentation

◆ Architecture

Defines supported FPGA architectures.

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

Enumerator
lattice_ice40 

Lattice iCE40 FPGA architecture.

xilinx_unisim 

Xilinx Unisim FPGA architecture.

Definition at line 40 of file architecture_types.h.

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

Enumerator
addition 

Addition operation.

addition_offset 

Addition operation with a constant offset.

subtraction 

Subtraction operation.

counter 

Counter operation.

negation 

Negation operation.

absolute 

Absolute value operation.

constant_multiplication 

Constant multiplication operation.

constant_multiplication_offset 

Constant multiplication operation with a constant offset.

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.

Definition at line 46 of file candidate_types.h.

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

Enumerator
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. This means that first all structural candidates are processed and afterwards all functional candidates are checked. In doing so we prevent threads waiting for the generation of functional candidates to check when there are no more stuctural candidates in the quque. However, generating all functional candidates first can lead to massive(!) RAM overhead.

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. This means that as soon as any functional candidates are generated they are prioritized to get verified to get them out of memory.

Definition at line 46 of file multithreading_types.h.

Function Documentation

◆ check_absolute()

◆ check_add_sub()

Result<VerifiedCandidate> hal::module_identification::check_add_sub ( FunctionalCandidate fc,
const std::vector< BooleanFunction > &  output_functions,
const std::vector< std::vector< Gate * >> &  registers 
)

◆ check_add_sub_offset()

Result<VerifiedCandidate> hal::module_identification::check_add_sub_offset ( FunctionalCandidate fc,
const std::vector< BooleanFunction > &  output_functions,
const std::vector< std::vector< Gate * >> &  registers 
)

◆ check_addition()

Result<VerifiedCandidate> hal::module_identification::check_addition ( FunctionalCandidate fc,
const std::vector< BooleanFunction > &  output_functions 
)

◆ check_addition_offset()

◆ check_constant_multiplication()

◆ check_constant_multiplication_offset()

◆ check_counter()

◆ check_equal()

◆ check_leq()

◆ check_sliced_add()

◆ check_sub()

Result<VerifiedCandidate> hal::module_identification::check_sub ( FunctionalCandidate fc,
const std::vector< BooleanFunction > &  output_functions,
const std::vector< std::vector< Gate * >> &  registers 
)

◆ check_value_check()

◆ execute()

hal::Result< Result > hal::module_identification::execute ( const Configuration config)

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
[in]config- The configuration to guide the identification process.
Returns
OK() and the result of the run containing all computed results and options for further processing on success, an error otherwise.

Definition at line 526 of file module_identification.cpp.

References ERR_APPEND, generate_structural_candidates(), hal::Netlist::get_design_name(), hal::Netlist::get_device_name(), hal::Netlist::get_gate_library(), hal::GateLibrary::get_name(), hal::Module::get_name(), hal::Netlist::get_top_module(), log_info, and hal::module_identification::Configuration::m_netlist.

Referenced by hal::GuiExtensionModuleIdentification::execute_function(), and hal::PYBIND11_PLUGIN().

◆ execute_on_gates()

hal::Result< Result > hal::module_identification::execute_on_gates ( const std::vector< Gate * > &  gates,
const Configuration config 
)

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
[in]gates- The gates to be analyzed.
[in]config- The configuration to guide the identification process.
Returns
OK() and the result of the run containing all computed results and options for further processing on success, an error otherwise.

Definition at line 547 of file module_identification.cpp.

References ERR.

Referenced by hal::GuiExtensionModuleIdentification::execute_function(), and hal::PYBIND11_PLUGIN().

◆ find_neighboring_registers() [1/2]

std::set< u32 > hal::module_identification::find_neighboring_registers ( const Net n,
const std::vector< std::vector< Gate * >> &  registers 
)

Find neighboring registers connected to a given net.

Parameters
[in]n- The net to analyze.
[in]registers- A vector of vectors containing sets of gates representing registers.
Returns
A set of indices representing the neighboring registers.

Definition at line 113 of file utils.cpp.

References hal::Net::get_netlist(), hal::NetlistTraversalDecorator::get_next_matching_gates(), log_error, and hal::sequential.

Referenced by find_neighboring_registers(), and reorder_commutative_operands().

◆ find_neighboring_registers() [2/2]

std::set< u32 > hal::module_identification::find_neighboring_registers ( const std::vector< Net * >  nets,
const std::vector< std::vector< Gate * >> &  registers 
)

Find neighboring registers connected to a list of nets.

Parameters
[in]nets- A vector of nets to analyze.
[in]registers- A vector of vectors containing sets of gates representing registers.
Returns
A set of indices representing the neighboring registers.

Definition at line 142 of file utils.cpp.

References find_neighboring_registers().

◆ generate_functional_candidates()

◆ generate_structural_candidates()

◆ get_input_nets()

std::vector< Net * > hal::module_identification::get_input_nets ( const std::vector< Gate * > &  gates)

Get input nets from a list of gates.

This function retrieves the input nets connected to a specified list of gates.

Parameters
[in]gates- A vector of gates to analyze.
Returns
A vector of nets representing the inputs to the specified gates.

Definition at line 25 of file utils.cpp.

References log_error.

Referenced by hal::module_identification::FunctionalCandidate::FunctionalCandidate().

◆ get_output_nets()

std::vector< Net * > hal::module_identification::get_output_nets ( const std::vector< Gate * > &  gates,
bool  only_external_destinations = true 
)

Get output nets from a list of gates.

This function retrieves the output nets connected to a specified list of gates. By default, only nets with external destinations are considered.

Parameters
[in]gates- A vector of gates to analyze.
[in]only_external_destinations- Boolean flag indicating whether to consider only external destinations (default is true).
Returns
A vector of nets representing the outputs from the specified gates.

Definition at line 61 of file utils.cpp.

Referenced by hal::module_identification::FunctionalCandidate::check_output_size(), hal::module_identification::FunctionalCandidate::create_output_net_variant(), hal::module_identification::FunctionalCandidate::FunctionalCandidate(), and generate_functional_candidates().

◆ has_constant_value() [1/2]

bool hal::module_identification::has_constant_value ( const BooleanFunction bf,
const u64 val 
)

◆ has_constant_value() [2/2]

bool hal::module_identification::has_constant_value ( const z3::expr &  e,
const u64 val 
)

◆ post_processing()

VerifiedCandidate hal::module_identification::post_processing ( const std::vector< VerifiedCandidate > &  verified_candidates,
const Netlist nl,
const std::vector< std::vector< Gate * >> &  dana_cache 
)

Performs post-processing on a set of verified candidates to identify the best candidate for module identification.

This function processes the provided verified candidates and selects the best candidate based on several criteria, such as the number of input and output signals, the number of control signals, and the number of gates in the candidate. The best candidate is then merged with other candidates sharing the same control mapping to create a final verified candidate.

Parameters
[in]verified_candidates- A vector of verified candidates to process.
[in]nl- The netlist containing the candidates.
[in]dana_cache- A cache of gate vectors used for various calculations during the selection and merging process.
Returns
OK() and the best verified candidate on success, an error otherwise.

Definition at line 953 of file post_processing.cpp.

References log_info.

Referenced by hal::module_identification::Result::merge().

◆ reorder_commutative_operands()

std::vector< std::vector< Net * > > hal::module_identification::reorder_commutative_operands ( const std::vector< std::vector< Net * >> &  operands,
const std::vector< std::vector< Gate * >> &  registers,
const u32  permute_start_index = 0 
)

Reorder commutative operands based on a permutation cache.

This function reorders the operands of a commutative operation based on the provided permutation cache. This can optimize the operand order for specific calculations or verifications.

Parameters
[in]operands- A vector of vectors containing nets representing operands.
[in]registers- A vector of vectors containing gates used for permutation.
[in]permute_start_index- The starting index for permutations (default is 0).
Returns
A reordered vector of vectors containing the operands.

Definition at line 194 of file utils.cpp.

References find_neighboring_registers(), log_warning, and size.

Referenced by hal::module_identification::FunctionalCandidate::create_candidates().

Variable Documentation

◆ all_checkable_candidate_types

const std::vector<CandidateType> hal::module_identification::all_checkable_candidate_types
Initial value:
= {
CandidateType::addition,
CandidateType::addition_offset,
CandidateType::counter,
CandidateType::absolute,
CandidateType::constant_multiplication,
CandidateType::constant_multiplication_offset,
CandidateType::equal,
CandidateType::less_equal,
CandidateType::value_check,
}

A list of all candidate types that are selectable to be checked.

This list does not contain all of the types that we can verify since some of the types are verified in the same way, like addition and subtraction, so selecting one implicitly selects the other. This selection is not meant to filter the types you want to verify for quality of results (for example if you want to prevent an addition that you consider would be more suitable identified as a subtrataction). The purpose of disableing some types for checking is for perfomance reasons.

Definition at line 104 of file candidate_types.h.

Referenced by hal::GuiExtensionModuleIdentification::execute_function(), generate_functional_candidates(), hal::GuiExtensionModuleIdentification::get_parameter(), and hal::GuiExtensionModuleIdentification::set_parameter().

◆ candidate_type_max_operands

const std::map<CandidateType, u32> hal::module_identification::candidate_type_max_operands
Initial value:
= {
{CandidateType::counter, 1},
{CandidateType::absolute, 1},
{CandidateType::constant_multiplication, 1},
{CandidateType::constant_multiplication_offset, 1},
{CandidateType::equal, 2},
{CandidateType::less_equal, 2},
{CandidateType::addition, 3},
{CandidateType::addition_offset, 3},
}

A mapping of candidate types to their maximum number of operands.

This map provides the maximum number of operands for each candidate type that the module identification process can handle.

Definition at line 124 of file candidate_types.h.

Referenced by hal::module_identification::FunctionalCandidate::realize_control_signals().