HAL Py

https://emsec.github.io/hal/pydoc/
Admin
HAL Py is a Python interface for the HAL hardware analysis framework, providing access to HAL core...
Tokens:270,671
Snippets:1,089
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Python Netlist Traversal Example

Source: https://emsec.github.io/hal/pydoc/netlist_traversal_decorator

Demonstrates how to use the NetlistTraversalDecorator to find combinational gates starting from a given net.

```python
from typing import Set, Optional, Callable

# Assume hal_py module and its classes (Netlist, Net, Gate, PinType, Endpoint) are defined elsewhere
# class Netlist:
#     pass
# class Net:
#     pass
# class Gate:
#     pass
# class PinType:
#     pass
# class Endpoint:
#     pass

class NetlistTraversalDecorator:
    def __init__(self, netlist: 'Netlist'):
        self.netlist = netlist

    def get_next_combinational_gates(self, net: 'Net', successors: bool, forbidden_pins: Set['PinType']) -> Optional[Set['Gate']]:
        # Placeholder for actual implementation
        print(f"Traversing from net: {net}, successors: {successors}, forbidden_pins: {forbidden_pins}")
        return set() # Example return

    def get_next_matching_gates(self, net: 'Net', successors: bool, target_gate_filter: Callable[['Gate'], bool], continue_on_match: bool = False, exit_endpoint_filter: Callable[['Endpoint', int], bool] = None, entry_endpoint_filter: Callable[['Endpoint', int], bool] = None) -> Optional[Set['Gate']]:
        # Placeholder for actual implementation
        print(f"Traversing from net: {net}, successors: {successors}, continue_on_match: {continue_on_match}")
        return set() # Example return

# Example Usage:
# Assuming 'my_netlist' is an instance of hal_py.Netlist
# Assuming 'start_net' is an instance of hal_py.Net
# Assuming 'forbidden_pin_types' is a set of hal_py.PinType

# decorator = NetlistTraversalDecorator(my_netlist)
# combinational_gates = decorator.get_next_combinational_gates(start_net, True, forbidden_pin_types)

# def my_filter(gate: 'Gate') -> bool:
#     # Define your gate filtering logic here
#     return True

# matching_gates = decorator.get_next_matching_gates(start_net, True, my_filter)

```

--------------------------------

### HAL Py SMT Module Initialization

Source: https://emsec.github.io/hal/pydoc/genindex

Documentation for the initialization methods of various classes within the hal_py.SMT module, covering constraints, models, queries, solvers, and symbolic execution.

```APIDOC
hal_py.SMT.Constraint:
  __init__(self, expression: str)
    Initializes an SMT Constraint.
    Parameters:
      expression: The SMT expression string.

hal_py.SMT.Model:
  __init__(self, model_data: Dict[str, Any])
    Initializes an SMT Model.
    Parameters:
      model_data: A dictionary containing the model data.

hal_py.SMT.QueryConfig:
  __init__(self, timeout: Optional[int] = None, logic: str = 'QF_BV')
    Initializes an SMT Query Configuration.
    Parameters:
      timeout: The query timeout in seconds.
      logic: The SMT logic to use (default is 'QF_BV').

hal_py.SMT.Solver:
  __init__(self, solver_type: SolverType, config: Optional[QueryConfig] = None)
    Initializes an SMT Solver.
    Parameters:
      solver_type: The type of SMT solver to use.
      config: The query configuration for the solver.

hal_py.SMT.SolverResult:
  __init__(self, result_type: SolverResultType, model: Optional[Model] = None, unsat_core: Optional[List[str]] = None)
    Initializes an SMT Solver Result.
    Parameters:
      result_type: The type of the solver result.
      model: The model returned by the solver, if any.
      unsat_core: The unsat core, if applicable.

hal_py.SMT.SolverResultType:
  __init__(self)
    Represents the type of an SMT solver result.

hal_py.SMT.SolverType:
  __init__(self)
    Represents the type of an SMT solver.

hal_py.SMT.SymbolicExecution:
  __init__(self, netlist: Netlist, entry_point: str)
    Initializes a Symbolic Execution object.
    Parameters:
      netlist: The netlist to analyze.
      entry_point: The entry point for the symbolic execution.

hal_py.SMT.SymbolicState:
  __init__(self, state: Dict[str, Any])
    Initializes a Symbolic State.
    Parameters:
      state: A dictionary representing the symbolic state.
```

--------------------------------

### Get Shortest Path Between Gates

Source: https://emsec.github.io/hal/pydoc/netlist_utils

Finds the shortest path connecting a start gate to an end gate. The path is returned as a list of gates, starting with the start gate and ending with the end gate. If no path exists, an empty list is returned. If multiple shortest paths exist, only the first one found is returned.

```APIDOC
get_shortest_path(start_gate: hal::Gate, end_gate: hal::Gate, search_both_directions: bool = False) -> List[hal::Gate]
    Find the shortest path (i.e., the result set with the lowest number of gates) that connects the start gate with the end gate.
    The gate where the search started from will be the first in the result vector, the end gate will be the last.
    If there is no such path an empty vector is returned.
    If there is more than one path with the same length only the first one is returned.

    Parameters:
      start_gate: The start gate for the path (might be the end if searching both directions).
      end_gate: The end gate for the path (might be the start if searching both directions).
      search_both_directions: If true, checks start <-> end, whichever direction is shorter.

    Returns:
      A list of gates that form a chain on success, an empty list on error.
```

```APIDOC
get_shortest_path(start_gate: hal::Gate, end_module: hal::Module, forward_direction: bool) -> List[hal::Gate]
    Finds the shortest path between a start gate and a module.
```

--------------------------------

### Netlist Simulator Documentation

Source: https://emsec.github.io/hal/pydoc/bitorder_propagation

Documentation for the Netlist Simulator plugin, explaining its use for simulating hardware netlists.

```APIDOC
Netlist Simulator:
  Documentation for the Netlist Simulator plugin, explaining its use for simulating hardware netlists.
```

--------------------------------

### HAL Plugin Documentation Overview

Source: https://emsec.github.io/hal/pydoc/_sources/plugins.rst

This section outlines the available plugins for the HAL project, categorized by their functionality. Each link leads to detailed documentation for a specific plugin.

```markdown
.. toctree::
   :maxdepth: 1

   bitorder_propagation
   boolean_influence
   dataflow
   graph_algorithm
   gui
   hawkeye
   module_identification
   netlist_preprocessing
   resynthesis
   netlist_simulator
   netlist_simulator_controller
   verilator
   solve_fsm
   xilinx_toolbox

```

--------------------------------

### Get All Shortest Paths (Gate to Gates)

Source: https://emsec.github.io/hal/pydoc/graph_algorithm

Computes all shortest paths from a single start gate to multiple end gates in a specified direction within a netlist graph. Returns paths as lists of vertices.

```python
graph_algorithm.get_all_shortest_paths(graph: graph_algorithm.NetlistGraph, from_gate: hal_py.Gate, to_gates: List[hal_py.Gate], direction: graph_algorithm.NetlistGraph.Direction) -> Optional[List[List[int]]]
```

--------------------------------

### Project Navigation and Indices

Source: https://emsec.github.io/hal/pydoc/index

Links to various navigational and utility pages for the hal_py documentation, including general index, module index, and search.

```markdown
* [Index](https://emsec.github.io/hal/pydoc/genindex.html)
* [Module Index](https://emsec.github.io/hal/pydoc/py-modindex.html)
* [Search Page](https://emsec.github.io/hal/pydoc/search.html)
```

--------------------------------

### Get All Shortest Paths (Vertex to Vertices)

Source: https://emsec.github.io/hal/pydoc/graph_algorithm

Computes all shortest paths from a single start vertex to multiple end vertices in a specified direction within a netlist graph. Returns paths as lists of vertices.

```python
graph_algorithm.get_all_shortest_paths(graph: graph_algorithm.NetlistGraph, from_vertex: int, to_vertices: List[int], direction: graph_algorithm.NetlistGraph.Direction) -> Optional[List[List[int]]]
```

--------------------------------

### Get Next Gates (Predecessors/Successors)

Source: https://emsec.github.io/hal/pydoc/netlist_utils

Finds predecessors or successors of a given gate in the netlist. Supports recursive searching with a specified depth and an optional filter function to control recursion. The result does not include the starting gate.

```APIDOC
hal_py.NetlistUtils.get_next_gates(_* args_, _** kwargs_)
    Overloaded function.
      1. get_next_gates(gate: hal::Gate, get_successors: bool, depth: int = 0, filter: Callable[[hal::Gate], bool] = None) -> List[hal::Gate]
        Find predecessors or successors of a gate. If depth is set to 1 only direct predecessors/successors will be returned. Higher number of depth causes as many steps of recursive calls. If depth is set to 0 there is no limitation and the loop continues until no more predecessors/successors are found. If a filter function is given, the recursion stops whenever the filter function evaluates to False. Only gates matching the filter will be added to the result vector. The result will not include the provided gate itself.

        param hal_py.Gate gate
            The initial gate.
        param bool get_successors
```

--------------------------------

### HAL Plugins Documentation Overview

Source: https://emsec.github.io/hal/pydoc/netlist_preprocessing

Provides an overview of the HAL plugins, including links to specific documentation for various functionalities like Bit-Order Propagation, Boolean Influence, Dataflow Analysis, Graph Algorithms, GUI API, HAWKEYE, Module Identification, Netlist Preprocessing, Resynthesis, Netlist Simulator, Netlist Simulator Controller, Verilator Simulator, Solve FSM, and Xilinx Toolbox.

```APIDOC
HAL Core Documentation: https://emsec.github.io/hal/pydoc/hal_py.html

Plugins Documentation:
- Bit-Order Propagation: https://emsec.github.io/hal/pydoc/bitorder_propagation.html
- Boolean Influence: https://emsec.github.io/hal/pydoc/boolean_influence.html
- Dataflow Analysis (DANA): https://emsec.github.io/hal/pydoc/dataflow.html
- Graph Algorithms: https://emsec.github.io/hal/pydoc/graph_algorithm.html
- GUI API: https://emsec.github.io/hal/pydoc/gui.html
- HAWKEYE: https://emsec.github.io/hal/pydoc/hawkeye.html
- Module Identification: https://emsec.github.io/hal/pydoc/module_identification.html
- Netlist Preprocessing: https://emsec.github.io/hal/pydoc/netlist_preprocessing.html
- Resynthesis: https://emsec.github.io/hal/pydoc/resynthesis.html
- Netlist Simulator: https://emsec.github.io/hal/pydoc/netlist_simulator.html
- Netlist Simulator Controller: https://emsec.github.io/hal/pydoc/netlist_simulator_controller.html
- Verilator Simulator: https://emsec.github.io/hal/pydoc/verilator.html
- Solve FSM: https://emsec.github.io/hal/pydoc/solve_fsm.html
- Xilinx Toolbox: https://emsec.github.io/hal/pydoc/xilinx_toolbox.html
```

--------------------------------

### Get Subgraph Boolean Function

Source: https://emsec.github.io/hal/pydoc/subgraph_netlist_decorator

Calculates the combined Boolean function for a subgraph of combinational gates. It starts from a specified output net and uses input nets to create variables. An optional cache can be provided for performance optimization on repeated calls.

```APIDOC
get_subgraph_function(_* args_, _** kwargs_)
    Overloaded function.
  1. get_subgraph_function(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate], subgraph_output: hal_py.Net, cache: Dict[Tuple[int, hal_py.GatePin], hal_py.BooleanFunction]) -> Optional[hal_py.BooleanFunction]
> Get the combined Boolean function of a subgraph of combinational gates starting at the source of the provided subgraph output net. The variables of the resulting Boolean function are created from the subgraph input nets using ‘BooleanFunctionNetDecorator.get_boolean_variable’. Utilizes a cache for speedup on consecutive calls. 

param list[hal_py.Gate] subgraph_gates
    
> The gates making up the subgraph to consider. 

param hal_py.Net subgraph_output
    
> The subgraph oputput net for which to generate the Boolean function. 

param dict[tuple(int,hal_py.GatePin),hal_py.BooleanFunction] cache
    
> Cache to speed up computations. The cache is filled by this function. 

returns
    
> The combined Boolean function of the subgraph on success, None otherwise. 

rtype
    
> hal_py.BooleanFunction or None
  2. get_subgraph_function(self: hal_py.SubgraphNetlistDecorator, subgraph_gates: List[hal_py.Gate], subgraph_output: hal_py.Net) -> Optional[hal_py.BooleanFunction]
> Get the combined Boolean function of a subgraph of combinational gates starting at the source of the provided subgraph output net. The variables of the resulting Boolean function are created from the subgraph input nets using ‘BooleanFunctionNetDecorator.get_boolean_variable’. 

param list[hal_py.Gate] subgraph_gates
    
> The gates making up the subgraph to consider. 

param hal_py.Net subgraph_output
    
> The subgraph oputput net for which to generate the Boolean function. 

returns
    
```

--------------------------------

### HAL Python Simulation Initialization

Source: https://emsec.github.io/hal/pydoc/genindex

Documentation for methods related to initializing the simulation environment. This includes general initialization and specific initialization for sequential gates.

```APIDOC
initialize():
  Description: Initializes the netlist simulator.
  Applies to: netlist_simulator.NetlistSimulator, netlist_simulator_controller.NetlistSimulatorController

initialize_sequential_gates():
  Description: Initializes sequential gates within the simulator.
  Applies to: netlist_simulator.NetlistSimulator
```

--------------------------------

### NetlistSimulatorController API Documentation

Source: https://emsec.github.io/hal/pydoc/netlist_simulator_controller

Provides comprehensive documentation for the NetlistSimulatorController class, including methods for accessing simulation data, gates, nets, and controller properties. This includes details on return types, parameters, and descriptions for each method.

```APIDOC
NetlistSimulatorController:
  get_gates(_self: NetlistSimulatorController) -> Set[hal_py.Gate]
    Get all gates that are in the simulation set.
    Returns: The set of gates.
    Return type: Set[hal_py.Gate]

  get_id(_self: NetlistSimulatorController) -> int
    Get unique controller id.
    Returns: The unique id of the controller.
    Return type: int

  get_input_nets(_self: NetlistSimulatorController) -> Set[hal_py.Net]
    Get all nets that are considered inputs, i.e., not driven by a gate in the simulation set or global inputs.
    Returns: The input nets.
    Return type: list[hal_py.Net]

  get_max_simulated_time(_self: NetlistSimulatorController) -> int
    Get the last time covered by simulation. This is the last transition found in waveforms.
    Returns: Maximum of simulated time.
    Return type: int

  get_name(_self: NetlistSimulatorController) -> str
    Get controller name.
    Returns: The name of the controller.
    Return type: str

  get_output_nets(_self: NetlistSimulatorController) -> List[hal_py.Net]
    Get all output nets of gates in the simulation set that have a destination outside of the set or that are global outputs.
    Returns: The output nets.
    Return type: list[hal_py.Net]
```

--------------------------------

### Get Shortest Path Distance Between Gates

Source: https://emsec.github.io/hal/pydoc/netlist_traversal_decorator

Calculates the length of the shortest path (minimum number of gates) between a start and end gate. This method is more efficient than `get_shortest_path` as it avoids tracking the path itself. It returns the distance as an integer or None if no path exists.

```APIDOC
get_shortest_path_distance(_self : NetlistTraversalDecorator, _start_gate : Gate, _end_gate : Gate, _direction : PinDirection, _exit_endpoint_filter : Callable[[Endpoint, int], bool] = None, _entry_endpoint_filter : Callable[[Endpoint, int], bool] = None) -> Optional[int]
    Find the length of the shortest path (i.e., the smallest number of gates) that connects the start gate with the end gate. If there is no such path, `None` is returned. Computing only the shortest distance to a gate is faster than computing the shortest path, since it does not have to keep track of the path to reach each gate.

    Parameters:
      start_gate (Gate): The gate to start from.
      end_gate (Gate): The gate to connect to.
      direction (PinDirection): The direction to search in. Can be hal_py.PinDirection.input, hal_py.PinDirection.output, or hal_py.PinDirection.inout to search both directions and return the shorter one.
      exit_endpoint_filter (lambda): Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
      entry_endpoint_filter (lambda): Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

    Returns:
      The shortest distance between the start and end gate, `None` otherwise.

    Return type:
      int or None
```

--------------------------------

### HAL Py Simulation Functions

Source: https://emsec.github.io/hal/pydoc/genindex

Documentation for the NetlistSimulator class and its methods for loading initial values for simulation.

```APIDOC
NetlistSimulator.load_initial_values(initial_values: dict)
  Loads initial values for simulation.
  Parameters:
    initial_values: A dictionary mapping signal names to their initial values.

NetlistSimulator.load_initial_values_from_netlist()
  Loads initial values directly from the netlist configuration.
```

--------------------------------

### Get Next Sequential Gates from Net

Source: https://emsec.github.io/hal/pydoc/netlist_traversal_decorator

Traverses a netlist starting from a given net to find the next layer of sequential successor or predecessor gates. It bypasses non-sequential gates until a sequential one is found, excluding those reached via forbidden pin types.

```APIDOC
get_next_sequential_gates(net: hal_py.Net, successors: bool, forbidden_pins: set[hal_py.PinType]) -> Optional[set[hal_py.Gate]]
    Starting from the given net, traverse the netlist and return only the next layer of sequential successor/predecessor gates. Traverse over gates that are not sequential until a sequential gate is found. Stop traversal at all sequential gates, but only adds those to the result that have not been reached through a pin of one of the forbidden types.

    Parameters:
      net: Start net.
      successors: Set `True` to get successors, set `False` to get predecessors.
      forbidden_pins: Sequential gates reached through these pins will not be part of the result. Defaults to an empty set.

    Returns:
      The next sequential gates on success, `None` otherwise.

    Return type:
      set[hal_py.Gate] or None
```

--------------------------------

### Netlist Simulator Controller API

Source: https://emsec.github.io/hal/pydoc/netlist_simulator_controller

This section details the API for the Netlist Simulator Controller, covering its methods for managing netlist simulations, loading designs, setting up simulation environments, and controlling the simulation process. It includes function signatures, parameter descriptions, return values, and usage examples.

```APIDOC
NetlistSimulatorController:
  __init__(self, design: Design)
    Initializes the NetlistSimulatorController with a given Design object.
    Parameters:
      design: The Design object to associate with the controller.

  load_netlist(self, netlist_file: str, format: str = 'verilog')
    Loads a netlist file into the simulator.
    Parameters:
      netlist_file: Path to the netlist file.
      format: The format of the netlist file (e.g., 'verilog', 'vhdl'). Defaults to 'verilog'.
    Returns: True if loading was successful, False otherwise.

  set_top_module(self, module_name: str)
    Sets the top-level module for simulation.
    Parameters:
      module_name: The name of the top-level module.

  run_simulation(self, duration: int, inputs: dict = None)
    Runs the netlist simulation for a specified duration.
    Parameters:
      duration: The simulation duration in time units.
      inputs: A dictionary of input signal values at the start of the simulation.
    Returns: A dictionary containing simulation results (e.g., output signals).

  get_signal_value(self, signal_name: str, time: int)
    Retrieves the value of a signal at a specific simulation time.
    Parameters:
      signal_name: The name of the signal.
      time: The simulation time at which to retrieve the value.
    Returns: The signal's value at the specified time.

  get_all_signal_values(self, time: int)
    Retrieves the values of all signals at a specific simulation time.
    Parameters:
      time: The simulation time at which to retrieve the values.
    Returns: A dictionary of all signal names and their values.

  get_simulation_time(self)
    Returns the current simulation time.

  reset_simulation(self)
    Resets the simulation to its initial state.

  close_simulation(self)
    Closes the simulation and releases resources.
```

--------------------------------

### Get Next Sequential Gates from Gate

Source: https://emsec.github.io/hal/pydoc/netlist_traversal_decorator

Traverses a netlist starting from a given gate to find the next layer of sequential successor or predecessor gates. It bypasses non-sequential gates until a sequential one is found, excluding those reached via forbidden pin types.

```APIDOC
get_next_sequential_gates(self: hal_py.NetlistTraversalDecorator, gate: hal_py.Gate, successors: bool, forbidden_pins: Set[hal_py.PinType]) -> Optional[Set[hal_py.Gate]]
    Starting from the given gate, traverse the netlist and return only the next layer of sequential successor/predecessor gates. Traverse over gates that are not sequential until a sequential gate is found. Stop traversal at all sequential gates, but only adds those to the result that have not been reached through a pin of one of the forbidden types.

    Parameters:
      gate: Start gate.
      successors: Set `True` to get successors, set `False` to get predecessors.
      forbidden_pins: Sequential gates reached through these pins will not be part of the result.

    Returns:
      The next sequential gates on success, `None` otherwise.

    Return type:
      set[hal_py.Gate] or None
```

--------------------------------

### Get Complex Gate Chain

Source: https://emsec.github.io/hal/pydoc/netlist_utils

Finds a sequence of gates matching specified types and connection criteria. It can start from any gate within the sequence and allows filtering based on specific input/output pins and a custom gate filter. This is useful for identifying specific structural patterns in a netlist.

```python
def get_complex_gate_chain(_start_gate: hal::Gate, chain_types: List[hal_py.GateType], input_pins: Dict[hal_py.GateType, List[hal::GatePin]], output_pins: Dict[hal_py.GateType, List[hal::GatePin]], filter: Callable[[hal::Gate], bool] = None) -> List[hal::Gate]:
    """Find a sequence of gates (of the specified sequence of gate types) that are connected via the specified input and output pins. The start gate may be any gate within a such a sequence, it is not required to be the first or the last gate. However, the start gate must be of the first gate type within the repeating sequence. If input and/or output pins are specified for a gate type, the gates must be connected through one of the input pins and/or one of the output pins. The optional filter is evaluated on every gate such that the result only contains gates matching the specified condition.

    Parameters:
        start_gate (hal_py.Gate): The gate at which to start the chain detection.
        chain_types (list[hal_py.GateType]): The sequence of gate types that is expected to make up the gate chain.
        input_pins (dict[hal_py.GateType, set[str]]): The input pins through which the gates are allowed to be connected.
        output_pins (dict[hal_py.GateType, set[str]]): The output pins through which the gates are allowed to be connected.
        filter (lambda, optional): A filter that is evaluated on all candidates.

    Returns:
        list[hal_py.Gate]: A list of gates that form a chain.
    """
    pass
```

--------------------------------

### Netlist Simulator Controller API

Source: https://emsec.github.io/hal/pydoc/netlist_simulator_controller

API documentation for the NetlistSimulatorController class, covering methods for simulation control.

```APIDOC
NetlistSimulatorController:
  set_no_clock_used(_self)
    Prepare simulation where no net is defined as clock input.

  set_saleae_timescale(_self, _timescale: int = 1000000000)
    Set timescale when parsing SALEAE float values.
    Parameters:
      filename: filename of CSV file to be parsed.
      timescale: multiplicator for values in time column.

  set_timeframe(_self, _tmin: int = 0, _tmax: int = 0)
    Set timeframe for viewer.
    Parameters:
      tmin: Lower limit for time scale in wave viewer.
      tmax: Upper limit for time scale in wave viewer.
```

--------------------------------

### HAL Plugins Overview

Source: https://emsec.github.io/hal/pydoc/resynthesis

This section provides an overview of the various plugins available within the HAL framework. It links to detailed documentation for each plugin, covering functionalities such as bit-order propagation, boolean influence, dataflow analysis, graph algorithms, GUI API, HAWKEYE, module identification, netlist preprocessing, resynthesis, netlist simulation, and specific tool integrations like Verilator and Xilinx Toolbox.

```APIDOC
HAL Core Documentation: https://emsec.github.io/hal/pydoc/hal_py.html

Plugins:
  - Bit-Order Propagation: https://emsec.github.io/hal/pydoc/bitorder_propagation.html
  - Boolean Influence: https://emsec.github.io/hal/pydoc/boolean_influence.html
  - Dataflow Analysis (DANA): https://emsec.github.io/hal/pydoc/dataflow.html
  - Graph Algorithms: https://emsec.github.io/hal/pydoc/graph_algorithm.html
  - GUI API: https://emsec.github.io/hal/pydoc/gui.html
  - HAWKEYE: https://emsec.github.io/hal/pydoc/hawkeye.html
  - Module Identification: https://emsec.github.io/hal/pydoc/module_identification.html
  - Netlist Preprocessing: https://emsec.github.io/hal/pydoc/netlist_preprocessing.html
  - Resynthesis: https://emsec.github.io/hal/pydoc/resynthesis.html
  - Netlist Simulator: https://emsec.github.io/hal/pydoc/netlist_simulator.html
  - Netlist Simulator Controller: https://emsec.github.io/hal/pydoc/netlist_simulator_controller.html
  - Verilator Simulator: https://emsec.github.io/hal/pydoc/verilator.html
  - Solve FSM: https://emsec.github.io/hal/pydoc/solve_fsm.html
  - Xilinx Toolbox: https://emsec.github.io/hal/pydoc/xilinx_toolbox.html
```

--------------------------------

### Get Shortest Path Between Gates

Source: https://emsec.github.io/hal/pydoc/netlist_traversal_decorator

Finds the shortest path (minimum number of gates) between a start and end gate in a netlist. It supports specifying search direction and filtering endpoints. Returns a list of gates forming the path or None if no path exists. If multiple shortest paths exist, only one is returned.

```APIDOC
get_shortest_path(_self : NetlistTraversalDecorator, _start_gate : Gate, _end_gate : Gate, _direction : PinDirection, _exit_endpoint_filter : Callable[[Endpoint, int], bool] = None, _entry_endpoint_filter : Callable[[Endpoint, int], bool] = None) -> Optional[List[Gate]]
    Find the shortest path (i.e., the smallest number of gates) that connects the start gate with the end gate. The gate where the search started from will be the first in the result list, the end gate will be the last. If there is no such path, `None` is returned. If there is more than one path with the same length, only the first one is returned.

    Parameters:
      start_gate (Gate): The gate to start from.
      end_gate (Gate): The gate to connect to.
      direction (PinDirection): The direction to search in. Can be hal_py.PinDirection.input, hal_py.PinDirection.output, or hal_py.PinDirection.inout to search both directions and return the shorter one.
      exit_endpoint_filter (lambda): Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
      entry_endpoint_filter (lambda): Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

    Returns:
      A list of gates that connect the start with end gate on success, `None` otherwise.

    Return type:
      list[Gate] or None
```

--------------------------------

### NetlistSimulator Methods

Source: https://emsec.github.io/hal/pydoc/netlist_simulator

Provides an overview of the core methods available in the NetlistSimulator class for controlling and executing simulations.

```APIDOC
NetlistSimulator:
  set_iteration_timeout(_self: NetlistSimulator, _iterations: int) -> None
    Sets the iteration timeout, the maximum number of events processed for a single point in time. A value of 0 disables the timeout.
    Parameters:
      iterations (int): The iteration timeout.

  set_simulation_state(_self: NetlistSimulator, _state: hal::Simulation) -> None
    Sets the simulator state, including net signals, to a given state. Does not influence gates/nets added to the simulation set.
    Parameters:
      state (netlist_simulator.Simulation): The state to apply.

  simulate(_self: NetlistSimulator, _picoseconds: int) -> None
    Simulates for a specific period, advancing the internal state. Automatically initializes the simulation if 'initialize' has not yet been called. Use set_input to control specific signals.
    Parameters:
      picoseconds (int): The duration to simulate.
```

--------------------------------

### HAL Python Pin Group Start Index

Source: https://emsec.github.io/hal/pydoc/genindex

Retrieves the starting index for pin groups in both GatePinGroup and ModulePinGroup.

```APIDOC
hal_py.GatePinGroup.get_start_index()
  Returns the starting index of the GatePinGroup.

hal_py.ModulePinGroup.get_start_index()
  Returns the starting index of the ModulePinGroup.
```

--------------------------------

### GatePinGroup and ModulePinGroup Start Index

Source: https://emsec.github.io/hal/pydoc/genindex

Documentation for the 'start_index' property for GatePinGroup and ModulePinGroup, indicating the starting index within a group.

```APIDOC
hal_py.GatePinGroup.start_index
  Property returning the starting index of the pin group.

hal_py.ModulePinGroup.start_index
  Property returning the starting index of the pin group.
```

--------------------------------

### NetlistSimulatorControllerPlugin Class

Source: https://emsec.github.io/hal/pydoc/_sources/netlist_simulator_controller.rst

Documentation for the NetlistSimulatorControllerPlugin class, detailing its members and functionalities within the netlist simulation context.

```python
class NetlistSimulatorControllerPlugin:
    """Plugin for the Netlist Simulator Controller."""
    pass
```

--------------------------------

### Initialization and Configuration Methods

Source: https://emsec.github.io/hal/pydoc/genindex

Methods related to the initialization and configuration of components, such as retrieving initialization data, categories, and identifiers.

```APIDOC
hal_py.InitComponent.get_init_category()
  Retrieves the initialization category for an InitComponent.

hal_py.Gate.get_init_data()
  Retrieves the initialization data for a Gate.

hal_py.InitComponent.get_init_identifier()
  Retrieves the initialization identifier for an InitComponent.
```

--------------------------------

### Find Shortest Path in Netlist

Source: https://emsec.github.io/hal/pydoc/netlist_utils

Finds the shortest path between a start gate and any gate within a specified module. The path is returned as a list of gates, starting with the start gate and ending with the found gate. If multiple paths have the same shortest length, the first one found is returned. An empty list is returned if no path exists.

```python
def find_shortest_path(start_gate: hal_py.Gate, end_module: hal_py.Module, forward_direction: bool) -> list[hal_py.Gate]:
    """
    Finds the shortest path (i.e., the result set with the lowest number of gates) that connects the start gate with any gate for the given module.
    The gate where the search started from will be the first in the result vector, the end gate will be the last.
    If there is no such path an empty vector is returned.
    If there is more than one path with the same length only the first one is returned.

    Args:
        start_gate (hal_py.Gate): The start gate for the path.
        end_module (hal_py.Module): The module which contains the end gate for the path.
        forward_direction (bool): Search successor module to gate if true, else search predecessor module.

    Returns:
        list[hal_py.Gate]: A list of gates that form a chain on success, an empty list on error.
    """
    pass
```

--------------------------------

### Get Nets (Overloaded)

Source: https://emsec.github.io/hal/pydoc/module

Provides two ways to get nets: either all nets with sources/destinations within the module, or a filtered and potentially recursive set of nets. Useful for detailed net analysis.

```python
get_nets(_* args_, _** kwargs_)[](https://emsec.github.io/hal/pydoc/module.html#hal_py.Module.get_nets "Permalink to this definition") 
    
Overloaded function.
  1. get_nets(self: hal_py.Module) -> Set[hal_py.Net]
> Get all nets that have at least one source or one destination within the module. 

returns
    
> An unordered set of nets. 

rtype
    
> set[hal_py.Net]
  2. get_nets(self: hal_py.Module, filter: Callable[[hal_py.Net], bool], recursive: bool = False) -> Set[hal_py.Net]
> Get all nets that have at least one source or one destination within the module. The filter is evaluated on every candidate such that the result only contains those matching the specified condition. If `recursive` is `True`, nets in submodules are considered as well. 

param lambda filter
    
> Filter function to be evaluated on each net. 

param bool recursive
    
> `True` to also consider nets in submodules, `False` otherwise. 

returns
    
> An unordered set of nets. 

rtype
    
> set[hal_py.Net]
```

--------------------------------

### NetlistSimulator Class

Source: https://emsec.github.io/hal/pydoc/_sources/netlist_simulator.rst

Documentation for the NetlistSimulator class, outlining its members and capabilities for performing netlist simulations.

```python
class NetlistSimulator:
    """Core class for managing and executing netlist simulations."""
    pass
```

--------------------------------

### HAL Py GateLibrary Class Initialization

Source: https://emsec.github.io/hal/pydoc/genindex

Documentation for the __init__ method of the GateLibrary class, used for managing gate libraries.

```APIDOC
hal_py.GateLibrary:
  __init__(self, name: str)
    Initializes a GateLibrary object.
    Parameters:
      name: The name of the gate library.
```

--------------------------------

### NetlistGraph: Get Netlist

Source: https://emsec.github.io/hal/pydoc/graph_algorithm

Retrieves the netlist associated with the netlist graph.

```APIDOC
get_netlist(self: graph_algorithm.NetlistGraph) -> hal_py.Netlist
    Get the netlist associated with the netlist graph.

    Returns:
        The netlist.

    Return type:
        hal_py.Netlist
```

--------------------------------

### ModulePinGroup Properties

Source: https://emsec.github.io/hal/pydoc/module_pin_group

Exposes properties of the ModulePinGroup, such as its name, ordered status, pins, start index, and type.

```APIDOC
_property_ name[](https://emsec.github.io/hal/pydoc/module_pin_group.html#hal_py.ModulePinGroup.name "Permalink to this definition") 
    
The name of the pin group. 

Type
    
[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") 

_property_ ordered[](https://emsec.github.io/hal/pydoc/module_pin_group.html#hal_py.ModulePinGroup.ordered "Permalink to this definition") 
    
`True` if the pin group is inherently ordered, `False` otherwise. 

Type
    
[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") 

_property_ pins[](https://emsec.github.io/hal/pydoc/module_pin_group.html#hal_py.ModulePinGroup.pins "Permalink to this definition") 
    
The (ordered) pins of the pin groups. 

Type
    
[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")[[hal_py.ModulePin](https://emsec.github.io/hal/pydoc/module_pin.html#hal_py.ModulePin "hal_py.ModulePin")] 

_property_ start_index[](https://emsec.github.io/hal/pydoc/module_pin_group.html#hal_py.ModulePinGroup.start_index "Permalink to this definition") 
    
The start index of the pin group. Commonly, pin groups start at index 0, but this may not always be the case. Note that the start index for a pin group comprising n pins is 0 independent of whether it is ascending or descending. 

Type
    
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") 

_property_ type[](https://emsec.github.io/hal/pydoc/module_pin_group.html#hal_py.ModulePinGroup.type "Permalink to this definition") 
    
The type of the pin group. 

Type
    
[hal_py.PinType](https://emsec.github.io/hal/pydoc/pin_type.html#hal_py.PinType "hal_py.PinType")
```

--------------------------------

### HAL GUI API - GridPlacement Methods

Source: https://emsec.github.io/hal/pydoc/gui

Provides methods for managing the placement of nodes (gates and modules) on a GUI grid. Includes functions to get and set positions, with an option to swap positions.

```APIDOC
class hal_gui.GuiApi.GridPlacement:
    """Helper class to determine placement of nodes on gui grid."""

    gatePosition(_self: hal_gui.GuiApi.GridPlacement, _gateId: int) -> Tuple[int, int] | None
        """Query position for gate identified by ID."""
        Parameters:
            gateId (int): Gate ID.
        Returns:
            Position of gate or None if gate not found in hash.
        Return type:
            tuple(int, int) or None

    modulePosition(_self: hal_gui.GuiApi.GridPlacement, _moduleId: int) -> Tuple[int, int] | None
        """Query position for module identified by ID."""
        Parameters:
            moduleId (int): Module ID.
        Returns:
            Position of module or None if module not found in hash.
        Return type:
            tuple(int, int) or None

    setGatePosition(_self: hal_gui.GuiApi.GridPlacement, _gateId: int, _point: Tuple[int, int], _swap: bool = False) -> None
        """Set position for gate identified by ID."""
        Parameters:
            gateId (int): Gate ID.
            pos (tuple(int, int)): New position.
            swap (bool): Set the swap of positions of the nodes

    setModulePosition(_self: hal_gui.GuiApi.GridPlacement, _moduleId: int, _point: Tuple[int, int], _swap: bool = False) -> None
        """Set position for module identified by ID."""
        Parameters:
            moduleId (int): Module ID.
            pos (tuple(int, int)): New position.
            swap (bool): Set the swap of positions of the nodes
```

--------------------------------

### NetlistGraph: Get Number of Edges

Source: https://emsec.github.io/hal/pydoc/graph_algorithm

Retrieves the total number of edges present in the netlist graph.

```APIDOC
get_num_edges(self: graph_algorithm.NetlistGraph) -> int
    Get the number of edges in the netlist graph.

    Returns:
        The number of edges in the netlist graph.

    Return type:
        int
```

--------------------------------

### Netlist Simulator Controller Documentation

Source: https://emsec.github.io/hal/pydoc/bitorder_propagation

Documentation for the Netlist Simulator Controller plugin, likely managing the operations of the netlist simulator.

```APIDOC
Netlist Simulator Controller:
  Documentation for the Netlist Simulator Controller plugin, likely managing the operations of the netlist simulator.
```

--------------------------------

### Get Subgraph

Source: https://emsec.github.io/hal/pydoc/graph_algorithm

Extracts a subgraph from a given netlist graph based on a list of specified gates.

```APIDOC
get_subgraph(graph: graph_algorithm.NetlistGraph, subgraph_gates: List[hal_py.Gate]) -> Optional[graph_algorithm.NetlistGraph]
    Extracts a subgraph from a given netlist graph based on a list of specified gates.
```

--------------------------------

### NetlistSimulatorController API Documentation

Source: https://emsec.github.io/hal/pydoc/netlist_simulator_controller

Provides detailed information on the methods available within the NetlistSimulatorController class for managing simulation inputs and working directories.

```APIDOC
NetlistSimulatorController:
  get_working_directory() -> str
    Description: Get the working directory.
    Returns: The working directory of the controller.

  import_csv(filename: str, filter: netlist_simulator_controller.FilterInputFlag, timescale: int = 1000000000) -> None
    Description: Parse CSV data as simulation input.
    Parameters:
      filename (str): filename of CSV file to be parsed.
      filter (netlist_simulator_controller.FilterInputFlag): filter to select waveform data from file.
      timescale (int): multiplicator for values in time column.

  import_saleae(dirname: str, lookupTable: Dict[hal_py.Net, int], timescale: int = 1000000000) -> None
    Description: Import nets given by lookup table from SALEAE directory.
    Parameters:
      dirname (str): directory to import files from.
      lookupTable (dict[hal_py.Net, int]): mapping nets to be imported with saleae file index.
      timescale (int): multiplication factor for time value if SALEAE data in float format.

  import_simulation(dirname: str, filter: netlist_simulator_controller.FilterInputFlag, timescale: int = 1000000000) -> None
    Description: Imports nets from simulation working directory. Existing saleae directory required to nets with binary data.
    Parameters:
      dirname (str): directory to import files from.
      filter (netlist_simulator_controller.FilterInputFlag): filter to select waveform data for import.
      timescale (int): multiplication factor for time value if SALEAE data in float format.
```

--------------------------------

### Get Module

Source: https://emsec.github.io/hal/pydoc/genindex

Retrieves a module from the HAL Gate object. This is a fundamental method for accessing module information.

```APIDOC
hal_py.Gate.get_module()
  - Retrieves the module associated with the Gate object.
  - Returns: The module object.
```
Tokens:
Raw