utils.gate_lib
¶
The gate_lib module provides a library of digital gates and other netlist elements.
These gates are the basic building blocks of digital circuits, and they can be combined to create more complex circuits. The module includes classes for various types of gates, including unary gates (such as buffers and inverters), binary gates (such as AND, OR, and XOR gates), and more complex gates like multiplexers and demultiplexers.
Every primitive gate from this library has an instance_type string, which starts with an {CFG.nc_identifier_internal} (section symbol),
which is not a valid Verilog symbol for use in identifiers (except if escaped).
This is intended to distinguish primitive gates from user-defined module instances.
Classes:
-
Buffer–A buffer gate.
-
NotGate–An inverter gate.
-
PosGate–An arithmetic plus gate.
-
NegGate–An arithmetic negator gate.
-
ReduceAnd–A reduction AND gate.
-
ReduceOr–A reduction OR gate.
-
ReduceBool–A reduction Boolean gate.
-
ReduceXor–A reduction XOR gate.
-
ReduceXnor–A reduction XNOR gate.
-
LogicNot–A logic not gate.
-
AndGate–An AND gate.
-
OrGate–An OR gate.
-
XorGate–An XOR gate.
-
XnorGate–An XNOR gate.
-
NorGate–A NOR gate.
-
NandGate–A NAND gate.
-
ShiftSigned–A signed SHIFT gate.
-
ShiftLeft–A SHIFT-LEFT gate.
-
ShiftRight–A SHIFT-RIGHT gate.
-
ShiftX–A SHIFT-X gate.
-
LogicAnd–A LOGIC-AND gate.
-
LogicOr–A LOGIC-OR gate.
-
LessThan–A LESS-THAN gate.
-
LessEqual–A LESS-OR-EQUAL gate.
-
Equal–An EQUAL gate.
-
NotEqual–A NOT-EQUAL gate.
-
GreaterThan–A GREATER-THAN gate.
-
GreaterEqual–A GREATER-OR-EQUAL gate.
-
Multiplexer–A multiplexer.
-
Demultiplexer–A demultiplexer.
-
Adder– -
Subtractor– -
Multiplier– -
Divider– -
Modulo– -
DFF–A D flip-flop (DFF) is a clocked gate that stores a value on its input port and outputs it on its output port.
-
DLatch–
Functions:
-
get–Retrieves the class of a primitive gate based on its instance type.
Bases: UnaryGate, BaseModel
A buffer gate.
A buffer gate is a gate that simply passes its input signal to its output. It is used to isolate a signal or to drive a long wire.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: UnaryGate, BaseModel
An inverter gate.
An inverter gate is a gate that inverts its input signal. It produces a HIGH output signal if its input signal is LOW, and vice versa.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: UnaryGate, BaseModel
An arithmetic plus gate.
An arithmetic plus gate is a gate that just returns its input signal, sign extended.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: UnaryGate, BaseModel
An arithmetic negator gate.
An arithmetic negator gate is a gate that returns the two's complement of its input signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A reduction AND gate.
A reduction AND gate performs a logical AND operation on all input signals. It produces a HIGH output signal if and only if all input signals are HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A reduction OR gate.
A reduction OR gate performs a logical OR operation on all input signals. It produces a HIGH output signal if at least one input signal is HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A reduction Boolean gate.
A reduction Boolean gate performs a logical OR operation on all input signals, but with the effect of a double negation (i.e., '!(!wire_vector)' in Verilog). It produces a HIGH output signal if at least one input signal is HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A reduction XOR gate.
A reduction XOR gate performs a logical XOR operation on all input signals. It produces a HIGH output signal if an odd number of input signals are HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A reduction XNOR gate.
A reduction XNOR gate performs a logical XNOR operation on all input signals. It produces a HIGH output signal if an even number of input signals are HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ReduceGate, BaseModel
A logic not gate.
A logic not gate performs a logical not operation on all input signals. It produces a HIGH output signal if all input signals are LOW. The output is LOW, if any input signal is HIGH.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signal_in–The input signal of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
An AND gate.
An AND gate is a gate that produces a HIGH output signal only if both its input signals are HIGH. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
An OR gate.
An OR gate is a gate that produces a HIGH output signal if either of its input signals is HIGH. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
An XOR gate.
An XOR gate is a gate that produces a HIGH output signal if its input signals are different. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
An XNOR gate.
An XNOR gate is a gate that produces a HIGH output signal if its input signals are the same. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
A NOR gate.
A NOR gate is a gate that produces a LOW output signal if either of its input signals is HIGH. Otherwise, it produces a HIGH output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryGate, BaseModel
A NAND gate.
A NAND gate is a gate that produces a LOW output signal only if both its input signals are HIGH. Otherwise, it produces a HIGH output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ShiftGate, BaseModel
A signed SHIFT gate.
A signed SHIFT gate is a gate that returns its left input shifted right by the number on the right side if it is positive or unsigned, and shifted left by the number on the right side if it is negative.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ShiftGate, BaseModel
A SHIFT-LEFT gate.
A SHIFT-LEFT gate is a gate that returns its left input shifted left by the number on the right side.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ShiftGate, BaseModel
A SHIFT-RIGHT gate.
A SHIFT-RIGHT gate is a gate that returns its left input shifted right by the number on the right side.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ShiftGate, BaseModel
A SHIFT-X gate.
A SHIFT-X gate is a gate that returns its first input shifted right or left by the number on the second input, based on whether the second input is signed and negative or not.
Attributes:
Methods:
-
model_post_init–Initializes the gate's ports and connections.
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Bases: BinaryNto1Gate, BaseModel
A LOGIC-AND gate.
A LOGIC-AND gate is a gate that produces a HIGH output signal if both input signals are non-zero. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A LOGIC-OR gate.
A LOGIC-OR gate is a gate that produces a HIGH output signal if at least one of both input signals is non-zero. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A LESS-THAN gate.
A LESS-THAN gate is a gate that produces a HIGH output signal only if its "left" input signal value is less than its "right" input signal. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A LESS-OR-EQUAL gate.
A LESS-OR-EQUAL gate is a gate that produces a HIGH output signal if its "left" input signal value is less or equal to its "right" input signal. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
An EQUAL gate.
An EQUAL gate is a gate that produces a HIGH output signal only if both input signals have the same value. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A NOT-EQUAL gate.
A NOT-EQUAL gate is a gate that produces a HIGH output signal only if both input signals have different values. Otherwise (if both are equal), it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A GREATER-THAN gate.
A GREATER-THAN gate is a gate that produces a HIGH output signal only if its "left" input signal value is greater than its "right" input signal. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: BinaryNto1Gate, BaseModel
A GREATER-OR-EQUAL gate.
A GREATER-OR-EQUAL gate is a gate that produces a HIGH output signal if its "left" input signal value is greater or equal to its "right" input signal. Otherwise, it produces a LOW output signal.
Attributes:
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
The input ports of the gate as a 2-tuple.
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: PrimitiveGate, BaseModel
A multiplexer.
A multiplexer is a gate that selects one of its input signals to be its output signal, based on a control signal.
Attributes:
-
name(str) –The name of the gate instance.
-
instance_type(str) –The type of the gate.
-
bit_width(PositiveInt) –The width of the control signal.
Methods:
-
model_post_init–Initializes the gate's ports and connections.
-
is_d_port–Whether a port is a data port.
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
property
writable
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
writable
¶
bit_width: int
The width of the multiplexer's control signal.
Not to be confused with the data width of the multiplexer! The bit width indicates the width of the control signal, which is used to switch between all input paths. The total number of input paths is "2 to the power of bit_width".
If bit_width is set to 1, there are 2^bitwidth = 2¹ = 2 input paths. If bit_width is set to 2, there are 2² = 4 input paths. ...
property
¶
property
¶
property
¶
property
¶
s_defined: bool
Whether the select signals are defined.
Returns:
-
bool(bool) –True if the select signals are defined, False otherwise.
property
¶
s_val: int
The value of the select signals.
Returns:
-
int(int) –The value of the select signals, or -1 if the select signals are not defined.
property
¶
property
¶
verilog: str
Creates a Verilog multiplexer from the Python object.
This method generates the Verilog code for the multiplexer gate.
It uses the verilog_template property as a base and fills in the
select signal and cases.
The cases are generated by iterating over all possible values of the select signal (i.e., from 0 to 2^bit_width - 1) and creating a case for each value. In each case, the output signals are assigned the value of the input signal if the current case matches the select signal.
Returns:
-
str(str) –The Verilog code for the multiplexer gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
Bases: PrimitiveGate, BaseModel
A demultiplexer.
A demultiplexer is a gate that selects one of its output ports to be connected to its input signal, based on a control signal.
Attributes:
-
name(str) –The name of the gate instance.
-
instance_type(str) –The type of the gate.
-
bit_width(PositiveInt) –The width of the control signal.
Methods:
-
model_post_init–Initializes the gate's ports and connections.
-
is_y_port–Whether a port is an output port.
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
property
writable
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
writable
¶
The width of the demultiplexer's control signal.
Not to be confused with the data width of the demultiplexer! The bit width indicates the width of the control signal, which is used to switch between all input paths. The total number of input paths is "2 to the power of bit_width".
If bit_width is set to 1, there are 2^bitwidth = 2¹ = 2 input paths. If bit_width is set to 2, there are 2² = 4 input paths. ...
property
¶
property
¶
property
¶
property
¶
s_defined: bool
Whether the select signals are defined.
Returns:
-
bool(bool) –True if the select signals are defined, False otherwise.
property
¶
s_val: int
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
property
¶
property
¶
verilog: str
Creates a Verilog demultiplexer from the Python object.
This method generates the Verilog code for the demultiplexer gate.
It uses the verilog_template property as a base and fills in the
select signal and cases.
The cases are generated by iterating over all possible values of the select signal (i.e., from 0 to 2^bit_width - 1) and creating a case for each value. In each case, the output signals are assigned the value of the input signal if the current case matches the select signal.
Returns:
-
str(str) –The Verilog code for the demultiplexer gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
Bases: ArithmeticGate, BaseModel
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], Port[Instance]]) –The input ports of the gate.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
y_width(PositiveInt) –Width of the gate, based on a certain port's width, depending on the actual gate.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_combinational(bool) –Whether instances of this gate are considered combinational gates.
-
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
a_signed(bool) –The signedness of input port A.
-
b_signed(bool) –The signedness of input port B.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ArithmeticGate, BaseModel
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], Port[Instance]]) –The input ports of the gate.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
y_width(PositiveInt) –Width of the gate, based on a certain port's width, depending on the actual gate.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_combinational(bool) –Whether instances of this gate are considered combinational gates.
-
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
a_signed(bool) –The signedness of input port A.
-
b_signed(bool) –The signedness of input port B.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ArithmeticGate, BaseModel
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], Port[Instance]]) –The input ports of the gate.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
y_width(PositiveInt) –Width of the gate, based on a certain port's width, depending on the actual gate.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_combinational(bool) –Whether instances of this gate are considered combinational gates.
-
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
a_signed(bool) –The signedness of input port A.
-
b_signed(bool) –The signedness of input port B.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ArithmeticGate, BaseModel
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], Port[Instance]]) –The input ports of the gate.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
y_width(PositiveInt) –Width of the gate, based on a certain port's width, depending on the actual gate.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_combinational(bool) –Whether instances of this gate are considered combinational gates.
-
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
a_signed(bool) –The signedness of input port A.
-
b_signed(bool) –The signedness of input port B.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ArithmeticGate, BaseModel
Methods:
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
evaluate–Evaluates the gate's output signal based on its input signals.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
signals_in–The input signals of the gate.
-
signal_out–The output signal of the gate.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], Port[Instance]]) –The input ports of the gate.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
y_width(PositiveInt) –Width of the gate, based on a certain port's width, depending on the actual gate.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_combinational(bool) –Whether instances of this gate are considered combinational gates.
-
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
a_signed(bool) –The signedness of input port A.
-
b_signed(bool) –The signedness of input port B.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
Width of the gate, based on a certain port's width, depending on the actual gate.
property
¶
is_combinational: bool
Whether instances of this gate are considered combinational gates.
True for combinational gates, such as AND gates or arithmetic gates.
False for flip-flops and latches.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
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:
Evaluates the gate's output signal based on its input signals.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
Bases: ClkMixin, BaseModel
A D flip-flop (DFF) is a clocked gate that stores a value on its input port and outputs it on its output port. The value is stored when the clock signal has a rising edge. The most basic version only has 3 ports: D, Q and CLK.
Attributes:
-
name(str) –The name of the gate instance.
-
instance_type(str) –The type of the gate.
-
en_polarity(Signal) –The polarity of the enable signal.
Methods:
-
get_scanff–Creates and returns a scan-DFF version of this DFF, copying all parameters of this DFF.
-
evaluate–Evaluates the gate's output signal.
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
model_post_init–Initializes the gate's ports and connections.
-
set_clk–Sets the clock signal.
class-attribute
instance-attribute
¶
instance_type: str = f'{id_internal}dff'
Instance type descriptor for D-Flip-Flops. Defaults to §dff, but may be overwritten upon creation by Yosys.
Yosys introduces a variety of flip-flop descriptor types. See the Yosys documentation for more information.
property
¶
scan_ff_equivalent: Type[ScanDFF]
Returns the Scan-FF type equivalent for normal FF and the FF type equivalent for Scan-FF.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
property
writable
¶
clk_polarity: Signal
Which clock edge activates the flip-flop. Default is Signal.HIGH, i.e. rising edge.
Creates and returns a scan-DFF version of this DFF, copying all parameters of this DFF.
No connections are copied however, and the instance initially does not belong to any module.
Evaluates the gate's output signal.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
Initializes the gate's ports and connections.
This method is called after the gate's attributes have been initialized, and it sets up the gate's ports and connections.
set_clk(new_signal: SignalOrLogicLevel) -> None
Bases: EnMixin, StorageGate, BaseModel
Methods:
-
evaluate–Evaluates the gate's output signal.
-
change_mutability–Change the mutability status of this instance and optionally its ports.
-
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.
-
p2v–Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
-
set–Sets the signal on a port.
-
set_en–Sets the enable signal.
Attributes:
-
name(str) –The name of the element.
-
metadata(MetadataMixin) –Metadata of a netlist element.
-
path(InstancePath) –Returns the InstancePath of the netlist element.
-
type(EType) –The type of the element, which is an instance.
-
hierarchy_level(int) –The level of hierarchy of the element in the design.
-
has_parent(bool) –Whether this object has a parent.
-
circuit('Circuit') –The circuit object to which this netlist element belongs to.
-
has_circuit(bool) –Whether this netlist element has a defined circuit it belongs to.
-
locked(bool) –True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.
-
is_placeholder_instance(bool) –A placeholder represents an element that does not have a specific path.
-
can_carry_signal(bool) –Whether this exact object is able to receive, pass or hold signal values.
-
connections(Dict[str, Dict[int, WireSegmentPath]]) –A dictionary mapping port names to their corresponding connection paths.
-
connection_str_paths(Dict[str, Dict[int, str]]) –Returns a dictionary mapping port names to their corresponding connection paths as strings.
-
ports(CustomDict[str, Port[Instance]]) –A dictionary mapping port names to their corresponding Port objects.
-
input_ports(Tuple[Port[Instance], ...]) –Returns a tuple of input ports associated with this instance.
-
output_ports(Tuple[Port[Instance], ...]) –Returns a tuple of output ports associated with this instance.
-
has_unconnected_port_segments(bool) –Returns True if the instance has at least one unconnected port segment.
-
signals(Dict[str, Dict[int, Signal]]) –A dictionary with all signals currently present on all ports of this instance.
-
is_blackbox(bool) –Flag indicating whether the instance represents neither a primitive element nor a module instance.
-
a_width(PositiveInt) –Width of the gate's
Aport. -
b_width(PositiveInt) –Width of the gate's
Bport. -
is_sequential(bool) –Whether instances of this gate are considered sequential gates.
-
output_port(Port[Instance]) –The output port of the gate.
-
data_width(int) –The data width of this instance.
-
input_port(Port[Instance]) –The input port of the gate.
-
en_polarity(Signal) –Which EN-signal level enables writing on the data storage. Default is Signal.HIGH.
-
en_port(Port[Instance]) –The enable port of the gate.
-
en_signal(Signal) –The enable signal of the gate.
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.
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.
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.
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.
property
¶
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.
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.
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.
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.
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.
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')} }
property
¶
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'} }
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:
-
CustomDict[str, Port[Instance]]–A dictionary mapping port names to their corresponding Port objects.
property
¶
property
¶
property
¶
has_unconnected_port_segments: bool
Returns True if the instance has at least one unconnected port segment.
property
¶
A dictionary with all signals currently present on all ports of this instance.
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.
property
¶
is_sequential: bool
Whether instances of this gate are considered sequential gates.
False for combinational gates, such as AND gates or arithmetic gates.
True for flip-flops and latches.
property
¶
data_width: int
The data width of this instance.
Defaults to the data width of the output port. Can be overwritten in extended classes.
In contrast to self.width, which is used for the creation and initialization,
this property is linked to the data width of the output port.
This property is useful when the data width of the output port can be changed.
property
writable
¶
en_polarity: Signal
Which EN-signal level enables writing on the data storage. Default is Signal.HIGH.
Evaluates the gate's output signal.
This method is called when the gate's input signals change, and it updates the gate's output signal accordingly.
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:
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:
Returns:
-
Dict[str, Dict[int, WireSegmentPath]]–A dictionary mapping port names to their corresponding connection paths.
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.
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:
-
ObjectLockedError–If this instance is locked.
-
ObjectNotFoundError–If no port exists with the given name.
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:
-
Union[WireSegmentPath, Dict[int, WireSegmentPath], None]–Union[WireSegmentPath, Dict[int, WireSegmentPath]]: Either a single WireSegmentPath or a dictionary mapping indices to WireSegmentPaths.
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(
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.
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() -> 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() -> 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() -> 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.
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.
Converts a Port object to its corresponding Verilog structure by using the connected wire segments.
This method takes the connected wire segments of a Port object and converts them to their corresponding Verilog signal structure (p2ws2v -> Port to WireSegment to Verilog signal syntax). The method requires that the currently selected module matches the module of the Port object, which is derived from the design path of the Port object. For each segment of the port, it checks whether a corresponding connected wire segment exists in the current module. If the port is set to a constant, the corresponding constant wire segment placeholder is used instead. Port segments can be excluded from the conversion by providing a list of indices, indicating which segments should be excluded from the conversion (e.g. segments that are known to be unconnected).
Parameters:
-
(port¶Port) –The Port object to convert.
-
(exclude_indices¶List[int], default:None) –A list of indices to exclude from the conversion. Defaults to an empty list.
Returns:
-
str(str) –The Verilog signal structure as a string.
Raises:
-
AttributeError–If the currently selected module does not match the module of the port.
set(port_name: str, new_signal: SignalOrLogicLevel) -> None
set_en(new_signal: SignalOrLogicLevel) -> None
get(instance_type: str) -> Union[type[PrimitiveGate], None]
Retrieves the class of a primitive gate based on its instance type.
This function is needed to find the correct class for a primitive gate
given its instance type. It searches for a class in the gate_lib module,
whose instance type matches the given instance_type string.
Parameters:
Returns:
-
Union[type[PrimitiveGate], None]–Union[type[_PrimitiveGate], None]: The class of the primitive gate or None if not found.