Skip to content

netlist_carpentry.core.netlist_elements.instance

Module for handling of instances inside a circuit module.

Classes:

Instance

Bases: NetlistElement, BaseModel

Methods:

  • all_connections –

    Returns a dictionary mapping port names to their corresponding connection paths.

  • connect –

    Add connections to the specified port of this instance.

  • disconnect –

    Remove an existing connection from a specified port of this instance.

  • get_connection –

    Retrieve the connection path associated with a specified port and bit index.

  • modify_connection –

    Modify an existing connection within a specified port of this instance.

  • connect_modify –

    Add a new connection or modify an existing one within the specified port of this instance.

  • tie_port –

    Set a constant signal value for the specified port and bit index.

  • has_tied_ports –

    Checks the ports of this instance whether any are tied to constant values.

  • has_tied_inputs –

    Checks the input ports of this instance whether any are tied to constant values.

  • has_tied_outputs –

    Checks the output ports of this instance whether any are tied to constant values.

  • update_signedness –

    Retrieves the signedness of the given port and updates it in this gate instance's parameter dictionary.

  • split –

    Performs a bit-wise split on this instance.

  • change_mutability –

    Change the mutability status of this instance and optionally its ports.

  • evaluate –

    Evaluate the element depending on the incoming signals.

Attributes:

instance_type instance-attribute 

instance_type: str

Name of the module this instance represents.

For primitives (such as gates or flip-flops), the name references a cell from the built-in library.

path property 

path: InstancePath

Returns the InstancePath of the netlist element.

The InstancePath object is constructed using the element's type and its raw hierarchical path.

Returns:

  • InstancePath ( InstancePath ) –

    The hierarchical path of the netlist element.

type property 

type: EType

The type of the element, which is an instance.

connections property 

connections: Dict[str, Dict[int, WireSegmentPath]]

A dictionary mapping port names to their corresponding connection paths.

The keys of the outer dictionary are the names of the ports. The values are dictionaries where the keys are the port bit numbers and the values are WireSegmentPath objects. The element paths are the paths of the wires connected to the corresponding bits of the port. Elements with no connection (i.e. the path is None) are excluded. In case these are needed, use Instance.get_connections() instead.

Example

{ 'port1': {1: WireSegmentPath('path/to/element1'), 2: WireSegmentPath('path/to/element2')}, 'port2': {1: WireSegmentPath('path/to/element3')} }

connection_str_paths property 

connection_str_paths: Dict[str, Dict[int, str]]

Returns a dictionary mapping port names to their corresponding connection paths as strings.

The keys are the names of the ports. The values are dictionaries where the keys are the port bit numbers and the values are the raw string paths.

Example

{ 'port1': {0: 'path.to.element1', 1: 'path.to.element2'}, 'port2': {0: 'path.to.element3'} }

ports property 

ports: CustomDict[str, Port[Instance]]

A dictionary mapping port names to their corresponding Port objects.

The keys of the dictionary are the names of the ports. The values are Port objects representing the ports.

Returns:

input_ports property 

input_ports: Tuple[Port[Instance], ...]

Returns a tuple of input ports associated with this instance.

This property filters the ports based on their direction, returning only those that are marked as inputs.

Returns:

  • Tuple[Port[Instance], ...] –

    A tuple of Port objects representing the input ports.

output_ports property 

output_ports: Tuple[Port[Instance], ...]

Returns a tuple of output ports associated with this instance.

This property filters the ports based on their direction, returning only those that are marked as outputs.

Returns:

  • Tuple[Port[Instance], ...] –

    A tuple of Port objects representing the output ports.

has_unconnected_port_segments property 

has_unconnected_port_segments: bool

Returns True if the instance has at least one unconnected port segment.

signals property 

signals: Dict[str, Dict[int, Signal]]

A dictionary with all signals currently present on all ports of this instance.

is_blackbox property 

is_blackbox: bool

Flag indicating whether the instance represents neither a primitive element nor a module instance.

If True, this instance does not have a module definition, and is also not a basic component (i.e. a primitive gate instance) from the internal gate library, such as a gate or flip-flop.

is_module_instance property 

is_module_instance: bool

Checks whether this instance represents a module instance.

This property returns True if a module definition exists for this instance, indicating that it corresponds to a higher-level module composed of other instances.

is_primitive property 

is_primitive: bool

Check if the instance type is a primitive from the gate library.

This property checks if the instance exists in the gate library. The property is True if the instance is a primitive from the gate library, False otherwise.

splittable property 

splittable: bool

Whether n-bit wide instances of this type can be split into n 1-bit wide instances.

Supported for gate instances, where splitting does not change the overall behavior, e.g. splitting an 8-bit AND gate into 8 1-bit AND gates works fine, but an 8bit OR-REDUCE gate cannot be split, as this would change the behavior of the circuit.

verilog_template property 

verilog_template: str

Verilog template string for instantiating this instance.

This property returns a template string in the format of a Verilog module instantiation. The string contains placeholders for the instance type, name, and ports. The syntax is as follows: <instance_type> <instance_name> (<port_connections>); where: - <instance_type> is the type of the instance (e.g., a module or primitive), - <instance_name> is the unique identifier for this instance, - <port_connections> is a list of port connections in the format .port_name(wire_name).

For example, if we have an instance of type my_module with ports input_port and output_port, connected to wires input_wire and output_wire, respectively, the resulting Verilog code would be: my_module my_instance (.input_port(input_wire), .output_port(output_wire));

Returns:

  • str ( str ) –

    The Verilog template string.

verilog property 

verilog: str

Generates the Verilog code for this instance.

This property uses the verilog_template to generate the actual Verilog code by replacing the placeholders with the instance type, name, and port connections. It returns a string that can be used directly in a Verilog file.

Returns:

  • str ( str ) –

    The generated Verilog code.

name instance-attribute 

name: str

The name of the element.

!!! Do not modify this variable after instantiating it. Use NetlistElement.set_name() instead. Modifying this variable might lead to inconsistencies later on.

parameters class-attribute instance-attribute 

parameters: TypedParams = {}

Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).

metadata class-attribute instance-attribute 

metadata: MetadataMixin = MetadataMixin()

Metadata of a netlist element.

Can be user-defined, or e. g. by Yosys (such as src for the HDL source). Is also grouped by categories, i.e. all metadata from Yosys can be accessed via Module.metadata["yosys"], or via Module.metadata.yosys, which both return a dictionary of all metadata. Read the documentation of MetaDataMixin for more information.

hierarchy_level property 

hierarchy_level: int

The level of hierarchy of the element in the design.

The hierarchy level is the number of separators in the element's raw path. For example, a top-level instance has a hierarchy level of 0, while a direct submodule instance has a hierarchy level of 1.

Returns:

  • int ( int ) –

    The hierarchy level of the element.

has_parent property 

has_parent: bool

Whether this object has a parent.

circuit property 

circuit: 'Circuit'

The circuit object to which this netlist element belongs to.

  • For a module, returns the circuit to which the module belongs.
  • For any other netlist element, recursively returns the circuit of the parent, which ultimately leads to a module, to which the netlist element belongs.

Raises:

  • ParentNotFoundError –

    If a parent cannot be resolved somewhere in the hierarchical chain.

  • ObjectNotFoundError –

    If for a module no circuit is set.

has_circuit property 

has_circuit: bool

Whether this netlist element has a defined circuit it belongs to.

Tries to access self.circuit and returns whether the call was successful. Can be used instead of a try-except clause around the call to NetlistElement.circuit.

locked property 

locked: bool

True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.

Can be changed via NetlistElement.change_mutability(bool).

Immutability is used to prevent accidental changes to the design.

is_placeholder_instance property 

is_placeholder_instance: bool

A placeholder represents an element that does not have a specific path.

True if this NetlistElement instance represents a placeholder, False otherwise.

can_carry_signal property 

can_carry_signal: bool

Whether this exact object is able to receive, pass or hold signal values.

True for ports (as they drive or receive values) and wires (as they pass the signals from driver to load ports) as well as their respective segments. False for instances and modules.

all_connections 

all_connections(
    include_unconnected: bool,
) -> Dict[str, Dict[int, WireSegmentPath]]

Returns a dictionary mapping port names to their corresponding connection paths.

The keys of the outer dictionary are the names of the ports. The values are dictionaries where the keys are the port bit numbers and the values are WireSegmentPath objects. The element paths are the paths of the wires connected to the corresponding bits of the port.

Parameters:

  • include_unconnected

    (bool) –

    Whether to include unconnected ports in the result.

Returns:

connect 

connect(
    port_name: str,
    ws_path: Optional[WireSegmentPath],
    direction: Direction = UNKNOWN,
    index: NonNegativeInt = 0,
    width: PositiveInt = 1,
) -> None

Add connections to the specified port of this instance.

This method can establish multiple connections if a range of indices is provided.

Parameters:

  • port_name

    (str) –

    The name of the port where the connection(s) should be established.

  • ws_path

    (Optional[WireSegmentPath]) –

    The path of the wire segment that will be connected to this port. If None, the associated port (segment) remains unconnected.

  • direction

    (Direction, default: UNKNOWN ) –

    The direction of the port. Defaults to Direction.UNKNOWN.

  • index

    (NonNegativeInt, default: 0 ) –

    The starting bit index within the port for these connections. Defaults to 0.

  • width

    (PositiveInt, default: 1 ) –

    The number of consecutive bits in the port that should be connected. Defaults to 1.

Raises:

  • ObjectLockedError –

    If this instance is currently locked, and no connection can be made.

disconnect 

disconnect(port_name: str, index: Optional[int] = None) -> None

Remove an existing connection from a specified port of this instance.

This method disconnects the wire segment at the given index within the specified port_name.

Parameters:

  • port_name

    (str) –

    The name of the port where the connection should be removed.

  • index

    (Optional[int], default: None ) –

    The bit index within the port for this disconnection. Defaults to None, which completely disconnects the port.

Raises:

get_connection 

get_connection(
    port_name: str, index: Optional[NonNegativeInt] = None
) -> Union[WireSegmentPath, Dict[int, WireSegmentPath], None]

Retrieve the connection path associated with a specified port and bit index.

If index is provided, this method returns the wire segment path connected to that specific bit within the port. Otherwise, it returns all connections for the given port as a dictionary mapping indices to WireSegmentPaths.

Parameters:

  • port_name

    (str) –

    The name of the port for which to retrieve the connection(s).

  • index

    (Optional[NonNegativeInt], default: None ) –

    The bit index within the port. Defaults to None.

Returns:

modify_connection 

modify_connection(
    port_name: str, ws_path: WireSegmentPath, index: NonNegativeInt = 0
) -> None

Modify an existing connection within a specified port of this instance.

This method updates the wire segment path at the given index within the specified port_name. If the index does not exist yet, it is newly added, changing the width of the port.

Parameters:

  • port_name

    (str) –

    The name of the port where the connection should be modified.

  • ws_path

    (WireSegmentPath) –

    The new wire segment path for this connection.

  • index

    (NonNegativeInt, default: 0 ) –

    The bit index within the port. Defaults to 0.

connect_modify 

connect_modify(
    port_name: str,
    ws_path: WireSegmentPath,
    direction: Direction = UNKNOWN,
    index: NonNegativeInt = 0,
    width: PositiveInt = 1,
) -> None

Add a new connection or modify an existing one within the specified port of this instance.

If the connection already exists at the given index and port_name, it will be modified. Otherwise, a new connection is added.

Parameters:

  • port_name

    (str) –

    The name of the port where the connection should be established or updated.

  • ws_path

    (WireSegmentPath) –

    The path of the wire segment that will be connected to this port.

  • direction

    (Direction, default: UNKNOWN ) –

    The direction of the port. Defaults to Direction.UNKNOWN.

  • index

    (NonNegativeInt, default: 0 ) –

    The starting bit index within the port for these connections. Defaults to 0.

  • width

    (PositiveInt, default: 1 ) –

    The number of consecutive bits in the port that should be connected. Defaults to 1.

tie_port 

tie_port(name: str, index: NonNegativeInt, sig_value: LogicLevel) -> None

Set a constant signal value for the specified port and bit index.

If the specified port does not exist, an error message is logged and the function returns False. Otherwise, the method tries to set the constant signal value for that port and returns True if successful.

Does not work for instance output ports, as they are always driven by their parent instances.

Parameters:

  • name

    (str) –

    The name of the port.

  • index

    (NonNegativeInt) –

    The bit index within the port.

  • sig_value

    (LogicLevel) –

    The constant signal value to be set ('0', '1', or 'Z').

Raises:

  • ObjectNotFoundError –

    If no such port or port segment exists.

  • AlreadyConnectedError –

    (raised by: PortSegment.tie_signal) If this segment is belongs to a load port and is already connected to a wire, from which it receives its value.

  • InvalidDirectionError –

    (raised by: PortSegment.tie_signal) If this port segment belongs to an instance output port, which is driven by the instance inputs and the instance's internal logic.

  • InvalidSignalError –

    (raised by: PortSegment.tie_signal) If an invalid value is provided.

has_tied_ports 

has_tied_ports() -> bool

Checks the ports of this instance whether any are tied to constant values.

Instance ports can be tied to a constant value for several reasons, but if all input or all output ports are tied, the instance is rendered useless.

Returns:

  • bool ( bool ) –

    True if any ports of this instance are tied to constant values. False otherwise, i.e. all ports are connected to wires.

has_tied_inputs 

has_tied_inputs() -> bool

Checks the input ports of this instance whether any are tied to constant values.

Instance ports can be tied to a constant value for several reasons, but if all input or all output ports are tied, the instance is rendered useless.

Returns:

  • bool ( bool ) –

    True if any input ports of this instance are tied to constant values. False otherwise, i.e. all input ports are connected to wires.

has_tied_outputs 

has_tied_outputs() -> bool

Checks the output ports of this instance whether any are tied to constant values.

Instance ports can be tied to a constant value for several reasons, but if all input or all output ports are tied, the instance is rendered useless.

Returns:

  • bool ( bool ) –

    True if any output ports of this instance are tied to constant values. False otherwise, i.e. all output ports are connected to wires.

update_signedness 

update_signedness(port_name: str) -> None

Retrieves the signedness of the given port and updates it in this gate instance's parameter dictionary.

Parameters:

  • port_name

    (str) –

    The name of the port, of which the signedness value is retrieved.

split 

split() -> Dict[NonNegativeInt, Self]

Performs a bit-wise split on this instance.

If this instance supports splitting and has a data width of n bit, this method splits this instance into n 1-bit instances. This works for instances, where each output bit depends only on the corresponding input bit(s), e.g. an AND gate or a D-Flipflop.

Returns:

  • Dict[NonNegativeInt, Self] –

    Dict[int, Instance]: An n-bit large dictionary, where each key conforms to a bit of the original instance, and each value is an 1-bit instance representing the corresponding "slice" of the original instance.

Raises:

  • SplittingUnsupportedError –

    If this instance does not support splitting. Happens for any gate or instance whose behavior depends on the whole bus, and splitting would make it lose its meaning.

change_mutability 

change_mutability(is_now_locked: bool, recursive: bool = False) -> Self

Change the mutability status of this instance and optionally its ports.

This method allows setting whether this instance can be modified or not. If recursive is set to True, it also applies the same mutability status to all ports of this instance.

Parameters:

  • is_now_locked

    (bool) –

    The new mutability status for this instance.

  • recursive

    (bool, default: False ) –

    Whether to apply the change recursively to its ports. Defaults to False.

evaluate 

evaluate() -> None

Evaluate the element depending on the incoming signals.

This is used for instances, which have some sort of transfer function. The combination of input signals and the transfer function determine the output signal. For simple gate instances, such as AND and OR gates, this is trivial, as the transfer function is just a small truth table. Complex structures, like submodules, are comprised of other instances, which are evaluated recursively, down to the leaf instances, which in return are primitive gates. Thus, to evaluate a module, first all of its submodules and gates are evaluated, to calculate the output signals of the module.

Raises: