netlist_carpentry.core.netlist_elements.wire

Module for handling of wires inside a circuit module.

Classes:

• Wire –

  Represents a wire in a netlist.

Wire

Bases: NetlistElement, BaseModel

Represents a wire in a netlist.

The wire is composed of multiple wire segments, which are connected together to form a single wire. The wire segments are stored in a dictionary, where the keys are the indices of the wire segments and the values are the wire segments themselves.

Methods:

• __getitem__ –

  Allows subscripting of a Wire object to access its wire segments directly.

• create_wire_segment –

  Creates a new wire segment and adds it to the wire.

• create_wire_segments –

  Creates a wire segment and adds it to this wire.

• remove_wire_segment –

  Removes a wire segment at the specified index from the wire.

• get_wire_segment –

  Retrieves a wire segment at the specified index from the wire.

• get_wire_segments –

  Retrieves a dictionary of wire segments with the specified name.

• set_signal –

  Sets the signal of the wire segment at the given index to the given new signal.

• driver –

  Returns a dictionary of wire segment indices to lists of driving ports.

• loads –

  Returns a dictionary of wire segment indices to lists of load ports.

• has_no_driver –

  Retrieves a boolean indicating whether a wire segment has no driver connection at all wire indices.

• has_multiple_drivers –

  Determines if any wire segment has multiple driver connections.

• has_no_loads –

  Retrieves a boolean indicating whether any wire segment has no load connections.

• is_dangling –

  Retrieves a boolean indicating whether any wire segment is dangling (has no driver or load connections at all wire indices).

• has_problems –

  Retrieves a boolean indicating whether any wire segment has problems (has no driver or load connections, or has multiple drivers).

Attributes:

• msb_first (bool) –

  Whether this port is MSB (most significant bit) first or not

• path (WirePath) –

  Returns the WirePath of the netlist element.

• type (EType) –

  The type of the element, which is a wire.

• segments (CustomDict[int, WireSegment]) –

  Retrieves the dictionary of wire segments.

• signal (Signal) –

  Returns the signal associated with this wire.

• signal_array (Dict[int, Signal]) –

  A dictionary of wire segment indices to the signals of the corresponding wire segments.

• signal_str (str) –

  The signal currently applied to this wire as a string (MSB first).

• signal_int (Optional[int]) –

  The signal currently applied to this wire as an integer, if possible.

• width (int) –

  The width of the wire, which is the number of wire segments that compose it.

• lsb_first (bool) –

  Whether the LSB (least significant bit) comes first.

• ports (Dict[int, List[PortSegment]]) –

  Dictionary mapping port names to dictionaries of wire segment indices and corresponding element paths.

• connected_port_segments (Dict[PositiveInt, List[PortSegment]]) –

  Retrieves a dictionary of all wire segments and their corresponding port segments.

• name (str) –

  The name of the element.

• metadata (MetadataMixin) –

  Metadata of a netlist element.

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

msb_first class-attribute instance-attribute

msb_first: bool = True

Whether this port is MSB (most significant bit) first or not

path property

path: WirePath

Returns the WirePath of the netlist element.

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

Returns:

• WirePath ( WirePath ) –

  The hierarchical path of the netlist element.

type property

type: EType

The type of the element, which is a wire.

segments property

segments: CustomDict[int, WireSegment]

Retrieves the dictionary of wire segments.

Returns:

• CustomDict[int, WireSegment] –

  A dictionary with integer keys representing wire segment indices and values being WireSegment objects.

signal property

signal: Signal

Returns the signal associated with this wire.

Does only work for 1-bit wide wires, as a convenient alternative for wire.signal_array.

If there's only one segment in the wire (i.e. the wire is exactly 1 bit wide), returns the signal of that segment. Otherwise, returns Signal.UNDEFINED to indicate ambiguity. This is meant as a shortcut of signal_array[0], since many wires commonly are only 1 bit wide. Thus, this property should only be used for 1-bit wide wires!

Returns:

• Signal ( Signal ) –

  The signal associated with this wire, if this wire is 1 bit wide, otherwise returns Signal.UNDEFINED.

signal_array property

signal_array: Dict[int, Signal]

A dictionary of wire segment indices to the signals of the corresponding wire segments.

Returns:

• Dict[int, Signal] –

  A dictionary with integer keys representing wire segment indices and values being Signal objects

• Dict[int, Signal] –

  representing the signal of each wire segment.

signal_str property

signal_str: str

The signal currently applied to this wire as a string (MSB first).

The length of the string corresponds to the width of this wire. Offset is ignored by this property. If a 4 bit wire has an offset of 3, the returned string only consists of the actually present segments (i.e. the string consists of the signals at the 4 present segments). Analogously, if segments are missing in between, they are also ignored and treated as if there was no gap. If a wire has a segment with index 0 and with index 2, but a segment for index 1 is missing, the returned string will have the values of the segments 2 and 0 (in descending order), without including or mentioning the gap at index 1.

If the signal string for a 4 bit wire is '1010', then the segments with indices 3 and 1 (plus offset) are currently 1 and the other two segments are 0. If the string contains 'x', the corresponding segment has an undefined value, and if the string contains 'z', the corresponding segment is floating.

signal_int property

signal_int: Optional[int]

The signal currently applied to this wire as an integer, if possible.

If Wire.signed is False, the value is treated as an unsigned signal. If Wire.signed is True, the value is treated as a signed signal, using the two's complement, if the sign bit is 1.

Offset is ignored when calculating this property. If a 4 bit wire has an offset of 3, the returned integer is built form the actually present segments (i.e. the integer value is between 0 and 15). Analogously, if segments are missing in between, they are also ignored and treated as if there was no gap. If a wire has a segment with index 0 and with index 2, but a segment for index 1 is missing, the returned integer will be the decimal representation of the values of the segments 2 and 0, without including or mentioning the gap at index 1. The calculated number ranges thus between 0 and 3, and not between 0 and 7.

If the signal string for a 4 bit wire is '1001', then this property will return 9. If the string contains 'x' or 'z', the signal does not form an integer and this property returns None.

width property

width: int

The width of the wire, which is the number of wire segments that compose it.

Returns:

• int –

  The number of wire segments in the wire (int).

lsb_first property

lsb_first: bool

Whether the LSB (least significant bit) comes first.

This property is coupled with Port.msb_first. To change this value, change Port.msb_first, and this property is updated accordingly.

ports property

ports: Dict[int, List[PortSegment]]

Dictionary mapping port names to dictionaries of wire segment indices and corresponding element paths.

Returns:

• Dict[int, List[PortSegment]] –

  A dictionary where each key is a port name (str), and the value is another dictionary.

• Dict[int, List[PortSegment]] –

  The inner dictionary has wire segment indices (int) as keys, and the values are ElementPaths

• Dict[int, List[PortSegment]] –

  representing the instance path of the port connected at this wire index.

connected_port_segments property

connected_port_segments: Dict[PositiveInt, List[PortSegment]]

Retrieves a dictionary of all wire segments and their corresponding port segments.

name instance-attribute

name: str

The name of the element.

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

metadata class-attribute instance-attribute

metadata: MetadataMixin = MetadataMixin()

Metadata of a netlist element.

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

hierarchy_level property

hierarchy_level: int

The level of hierarchy of the element in the design.

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

Returns:

• int ( int ) –

  The hierarchy level of the element.

has_parent property

has_parent: bool

Whether this object has a parent.

circuit property

circuit: 'Circuit'

The circuit object to which this netlist element belongs to.

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

Raises:

• ParentNotFoundError –

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

• ObjectNotFoundError –

  If for a module no circuit is set.

has_circuit property

has_circuit: bool

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

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

locked property

locked: bool

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

Can be changed via NetlistElement.change_mutability(bool).

Immutability is used to prevent accidental changes to the design.

is_placeholder_instance property

is_placeholder_instance: bool

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

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

can_carry_signal property

can_carry_signal: bool

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

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

__getitem__

__getitem__(index: int) -> WireSegment

Allows subscripting of a Wire object to access its wire segments directly.

This is mainly for convenience, to use Wire[i] instead of Wire.segments[i].

Parameters:

• index

  (int) –

  The index of the desired wire segment.

Returns:

• WireSegment ( WireSegment ) –

  The wire segment at the specified index.

create_wire_segment

create_wire_segment(index: NonNegativeInt) -> WireSegment

Creates a new wire segment and adds it to the wire.

Parameters:

• index

  (NonNegativeInt) –

  The index where a new wire segment should be added.

Returns:

• WireSegment ( WireSegment ) –

  The WireSegment that was added to this wire.

create_wire_segments

create_wire_segments(
    count: PositiveInt, offset: NonNegativeInt = 0
) -> Dict[int, WireSegment]

Creates a wire segment and adds it to this wire.

The number of wire segments can be specified via count, which will create and add exactly this much wire segments (in ascending order) to this wire. With offset, the start index can be set

Parameters:

• count

  (PositiveInt) –

  The amount of WireSegments to be created and added to this wire.

• offset

  (NonNegativeInt, default: 0 ) –

  The index from which the generated wire segments start.

Returns:

• Dict[int, WireSegment] –

  List[WireSegment]: A list of WireSegment objects created and added to this wire.

remove_wire_segment

remove_wire_segment(index: NonNegativeInt) -> None

Removes a wire segment at the specified index from the wire.

This method attempts to remove a wire segment from the internal segments dictionary using the specified index. The operation checks for immutability and performs the removal if allowed.

Parameters:

• index

  (NonNegativeInt) –

  The index of the wire segment to be removed.

get_wire_segment

get_wire_segment(index: NonNegativeInt) -> Optional[WireSegment]

Retrieves a wire segment at the specified index from the wire.

This method attempts to retrieve a wire segment from the internal segments dictionary using the specified index.

Parameters:

• index

  (NonNegativeInt) –

  The index of the wire segment to be retrieved.

Returns:

• Optional[WireSegment] –

  Optional[WireSegment]: The wire segment at the specified index, or None if not found.

get_wire_segments

get_wire_segments(
    name: str = "", fuzzy: bool = False
) -> Dict[int, WireSegment]

Retrieves a dictionary of wire segments with the specified name.

This method retrieves a dictionary of wire segments that match the specified name. If fuzzy is True, the method will also return segments whose name contains the specified name.

Parameters:

• name

  (str, default: '' ) –

  The name of the wire segment to retrieve. Defaults to ''.

• fuzzy

  (bool, default: False ) –

  Whether to allow fuzzy matching. Defaults to False.

Returns:

• Dict[int, WireSegment] –

  Dict[int, WireSegment]: A dictionary of wire segments with the specified name or containing the specified name if fuzzy is True.

set_signal

set_signal(signal: LogicLevel, index: NonNegativeInt = 0) -> None

set_signal(signal: Signal, index: NonNegativeInt = 0) -> None

set_signal(signal: SignalOrLogicLevel, index: NonNegativeInt = 0) -> None

Sets the signal of the wire segment at the given index to the given new signal.

This method is intended to be used in the signal evaluation process, where the signal of this wire is driven onto it by the driving port (e.g. a module input port or an instance output port). This method is called during the signal evaluation process whenever the driving port of this wire updates its signal value.

Parameters:

• signal

  (SignalOrLogicLevel) –

  The new signal to set on the wire.

• index

  (NonNegativeInt, default: 0 ) –

  The index of the wire to set the signal on. Defaults to 0, which is the LSB of the wire.

Raises:

• ValueError –

  If the index is out of range of the wire's segments.

driver

driver() -> Dict[int, Optional[PortSegment]]

Returns a dictionary of wire segment indices to lists of driving ports.

The method retrieves the connections that are considered as drivers (which ideally is only one driver) for each wire segment in the wire.

Returns:

• Dict[int, Optional[PortSegment]] –

  A dictionary mapping wire segment indices (int) to a list of Port objects

• Dict[int, Optional[PortSegment]] –

  representing the driver connections (should be only one) at each index.

loads

loads() -> Dict[int, List[PortSegment]]

Returns a dictionary of wire segment indices to lists of load ports.

The method retrieves the connections that are considered as loads for each wire segment in the wire.

Returns:

• Dict[int, List[PortSegment]] –

  A dictionary with integer keys representing wire segment indices and values being lists of Port objects,

• Dict[int, List[PortSegment]] –

  which represent the load ports connected at those indices.

has_no_driver

has_no_driver(get_mapping: bool = False) -> Union[bool, Dict[int, bool]]

Retrieves a boolean indicating whether a wire segment has no driver connection at all wire indices.

Parameters:

• get_mapping

  (bool, default: False ) –

  Whether to retrieve a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index has no driver connection. Defaults to False.

Returns:

• Union[bool, Dict[int, bool]] –

  If get_mapping is False, a boolean indicating whether all wire segments have no driver connection.

• Union[bool, Dict[int, bool]] –

  If get_mapping is True, a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index

• Union[bool, Dict[int, bool]] –

  has no driver connection.

has_multiple_drivers

has_multiple_drivers(get_mapping: bool = False) -> Union[bool, Dict[int, bool]]

Determines if any wire segment has multiple driver connections.

This method checks each wire segment in the wire to see if it has more than one driver connection.

Parameters:

• get_mapping

  (bool, default: False ) –

  If True, return a dictionary mapping wire segment indices to booleans indicating whether each segment has multiple drivers. If False, return a single boolean indicating if any segment has multiple drivers. Defaults to False.

Returns:

• Union[bool, Dict[int, bool]] –

  If get_mapping is True, a dictionary mapping wire segment indices to boolean values indicating whether the segment

• Union[bool, Dict[int, bool]] –

  at that index has multiple driver connections. If get_mapping is False, a boolean indicating whether any wire

• Union[bool, Dict[int, bool]] –

  segment has multiple driver connections.

has_no_loads

has_no_loads(get_mapping: bool = False) -> Union[bool, Dict[int, bool]]

Retrieves a boolean indicating whether any wire segment has no load connections.

Parameters:

• get_mapping

  (bool, default: False ) –

  Whether to retrieve a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index has no load connection. Defaults to False.

Returns:

• Union[bool, Dict[int, bool]] –

  If get_mapping is False, a boolean indicating whether all wire segments have no load connection.

• Union[bool, Dict[int, bool]] –

  If get_mapping is True, a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index

• Union[bool, Dict[int, bool]] –

  has no load connection.

is_dangling

is_dangling(get_mapping: bool = False) -> Union[bool, Dict[int, bool]]

Retrieves a boolean indicating whether any wire segment is dangling (has no driver or load connections at all wire indices).

Parameters:

• get_mapping

  (bool, default: False ) –

  Whether to retrieve a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index is dangling. Defaults to False.

Returns:

• Union[bool, Dict[int, bool]] –

  If get_mapping is True, a dictionary mapping wire segment indices to boolean values indicating whether the segment

• Union[bool, Dict[int, bool]] –

  at that index is dangling. If get_mapping is False, a boolean indicating whether any wire segment is dangling.

has_problems

has_problems(get_mapping: bool = False) -> Union[bool, Dict[int, bool]]

Retrieves a boolean indicating whether any wire segment has problems (has no driver or load connections, or has multiple drivers).

Parameters:

• get_mapping

  (bool, default: False ) –

  Whether to retrieve a dictionary mapping wire segment indices to boolean values indicating whether the segment at that index has problems. Defaults to False.

Returns:

• Union[bool, Dict[int, bool]] –

  If get_mapping is True, a dictionary mapping wire segment indices to boolean values indicating whether the segment

• Union[bool, Dict[int, bool]] –

  at that index has problems. If get_mapping is False, a boolean indicating whether any wire segment has problems.