core.netlist_elements.wire_segment
¶
Module for handling of wire segments (i.e. wire slices) inside a circuit module.
Classes:
-
WireSegment–Represents a wire segment within a netlist.
-
WireSegmentConst0–A wire segment that represents a constant 0 signal.
-
WireSegmentConst1–A wire segment that represents a constant 1 signal.
-
WireSegmentConstZ–A wire segment that represents a floating signal.
-
WireSegmentConstX–A wire segment that represents an unconnected signal (which has the value
X/UNDEFINED).
Attributes:
-
WIRE_SEGMENT_0–A locked (unchangeable) placeholder representing the constant 0. Its signal is always 0.
-
WIRE_SEGMENT_1–A locked (unchangeable) placeholder representing the constant 1. Its signal is always 1.
-
WIRE_SEGMENT_Z–A locked (unchangeable) placeholder representing a floating state. Its signal is always z (floating).
-
WIRE_SEGMENT_X–A locked (unchangeable) placeholder representing an unconnected state. Its signal is always x (unknown, don't-care).
-
CONST_MAP_VAL2OBJ(Dict[str, _WireSegmentConst]) –A mapping from constant values to their corresponding wire segment objects.
-
CONST_MAP_VAL2VERILOG(Dict[str, str]) –A mapping from constant values to Verilog signal representations.
-
CONST_MAP_YOSYS2OBJ(Dict[str, _WireSegmentConst]) –A mapping from Yosys wire segment strings to their corresponding wire segment objects.
module-attribute
¶
A locked (unchangeable) placeholder representing the constant 0. Its signal is always 0.
module-attribute
¶
A locked (unchangeable) placeholder representing the constant 1. Its signal is always 1.
module-attribute
¶
A locked (unchangeable) placeholder representing a floating state. Its signal is always z (floating).
module-attribute
¶
A locked (unchangeable) placeholder representing an unconnected state. Its signal is always x (unknown, don't-care).
module-attribute
¶
CONST_MAP_VAL2OBJ: Dict[str, _WireSegmentConst] = {
"0": WIRE_SEGMENT_0,
"1": WIRE_SEGMENT_1,
"Z": WIRE_SEGMENT_Z,
"X": WIRE_SEGMENT_X,
"": WIRE_SEGMENT_X,
}
A mapping from constant values to their corresponding wire segment objects.
module-attribute
¶
CONST_MAP_VAL2VERILOG: Dict[str, str] = {
"0": "1'b0",
"1": "1'b1",
"Z": "1'bz",
"X": "1'bx",
"": "1'bx",
}
A mapping from constant values to Verilog signal representations.
module-attribute
¶
CONST_MAP_YOSYS2OBJ: Dict[str, _WireSegmentConst] = {
"0": WIRE_SEGMENT_0,
"1": WIRE_SEGMENT_1,
"x": WIRE_SEGMENT_X,
"z": WIRE_SEGMENT_Z,
}
A mapping from Yosys wire segment strings to their corresponding wire segment objects.
Bases: _Segment, BaseModel
Represents a wire segment within a netlist.
A wire segment is a part of a wire that carries a signal between ports. A wire may consist of multiple wire segments, but should at least contain one. The number of wire segments in a wire indicates the width of the wire. If a wire has only one wire segment, it is a single-bit wire. If a wire has e.g. 4 wire segments, it is a 4-bit wire. A wire segment can have multiple ports connected to it, but should have exactly one driver and at least one load.
Methods:
-
add_port_segment–Adds a port segment to the set of ports connected to this wire segment.
-
add_port_segments–Adds multiple ports to the set of ports connected to this wire segment.
-
remove_port_segment–Removes a port segment from the set of ports connected to this wire segment.
-
set_signal–Sets the signal of this wire segment to the given new signal.
-
has_defined_signal–Checks if the signal on this wire segment is defined.
-
driver–Returns a list of port segments driving this wire segment.
-
loads–Returns a list of port segments being driven by this wire segment.
-
has_no_driver–Checks if this wire segment has no ports driving it.
-
has_multiple_drivers–Checks if this wire segment has multiple ports driving it.
-
has_no_loads–Checks if this wire segment has no ports being driven by it.
-
is_dangling–Checks if this wire segment is dangling.
-
has_problems–Checks if this wire segment has any problems.
-
change_mutability–Change the mutability of this NetlistElement instance.
-
copy_object–Creates a new object of this type and copies the contents of this object into the new one.
-
normalize_metadata–Performs normalization of this element's metadata.
Attributes:
-
path(WireSegmentPath) –Returns the WireSegmentPath of the netlist element.
-
type(EType) –The type of the element, which is a wire segment.
-
grandparent('Module') –Retrieves the module that contains this WireSegment.
-
signal(Signal) –The signal on this wire segment.
-
port_segments(CustomList[PortSegment]) –The port segments connected to this wire segment.
-
nr_connected_ports(int) –The number of port segments connected to this wire segment.
-
is_constant(bool) –Checks if the wire segment represents a constant value.
-
is_defined_constant(bool) –Checks if the wire segment represents a defined constant value.
-
name(str) –The name of the element.
-
parameters(TypedParams) –Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as
WIDTHfor some instances). -
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.
-
index(int) –The index of the PortSegment in the Port, which is retrieved from the name.
property
¶
path: WireSegmentPath
Returns the WireSegmentPath of the netlist element.
The WireSegmentPath object is constructed using the element's type and its raw hierarchical path.
Returns:
-
WireSegmentPath(WireSegmentPath) –The hierarchical path of the netlist element.
property
¶
Retrieves the module that contains this WireSegment.
If a parent is available (i.e. the hierarchy level is 2 or more), it is returned.
Returns:
-
Module('Module') –The module if it exists.
Raises:
-
ParentNotFoundError–If no parent or grandparent was found.
property
¶
port_segments: CustomList[PortSegment]
The port segments connected to this wire segment.
property
¶
nr_connected_ports: int
The number of port segments connected to this wire segment.
property
¶
is_constant: bool
Checks if the wire segment represents a constant value.
A wire segment is considered a constant if its raw path is 'Z' or an empty string (both mean floating/high impedance), or if it's defined as a constant ('0' or '1').
Returns:
-
bool(bool) –True if the wire segment is a constant, False otherwise.
property
¶
is_defined_constant: bool
Checks if the wire segment represents a defined constant value.
A wire segment is considered defined and a constant if its raw path is '0' or '1'.
Returns:
-
bool(bool) –True if the wire segment is a defined constant, False otherwise.
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
¶
Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).
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
¶
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
writable
¶
index: int
The index of the PortSegment in the Port, which is retrieved from the name.
If this PortSegment instance is a placeholder instance (i.e. the path is empty and thus no name is available), then this value is -1 instead.
add_port_segment(port_segment: PortSegment) -> PortSegment
Adds a port segment to the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to add.
Returns:
-
PortSegment(PortSegment) –The PortSegment object that was added to this wire segment.
add_port_segments(port_segments: Iterable[PortSegment]) -> List[PortSegment]
Adds multiple ports to the set of ports connected to this wire segment.
Parameters:
-
(port_segments¶Iterable[PortSegment]) –An iterable of PortSegment objects to add.
Returns:
-
List[PortSegment]–List[PortSegment] A list with all port segments that were added.
remove_port_segment(port_segment: PortSegment) -> None
Removes a port segment from the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to remove.
set_signal(signal: SignalOrLogicLevel) -> None
Sets the signal of this wire segment to the given new signal.
This method is intended to be used in the signal evaluation process, where the signal of this wire segment is driven onto it by the driving port (e.g. a module input port or an instance output port driving this wire segment). This method is called during the signal evaluation process whenever the driving port of this wire segment updates its signal value.
Parameters:
-
(signal¶SignalOrLogicLevel) –The new signal to set on the wire segment.
has_defined_signal() -> bool
Checks if the signal on this wire segment is defined.
A defined signal is a signal with a value that is not "x" (undefined) or "z" (unconnected/floating). A signal with value 0 or 1 is considered defined.
driver(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments driving this wire segment.
A driver is a port segment that is connected to this wire segment and is driving the signal on it. A wire segment should have only one driver, so this function should return a list with only one element. If the list has more or less than one element, a warning is logged.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are more or less than 1 drivers. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments driving this wire segment.
loads(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments being driven by this wire segment.
A load is a port segment that is connected to this wire segment and is being driven by the signal on it. A wire segment can have multiple loads. If the list is empty (i.e., if there are no loads), a warning is logged if warn_if_issue is set to True.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are no loads. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments being driven by this wire segment.
has_no_driver() -> bool
Checks if this wire segment has no ports driving it.
Returns:
-
bool(bool) –True if the wire segment has no drivers, False otherwise.
has_multiple_drivers() -> bool
Checks if this wire segment has multiple ports driving it.
A wire segment should have only one driver, so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has multiple drivers, False otherwise.
has_no_loads() -> bool
Checks if this wire segment has no ports being driven by it.
A wire segment should have at least one load (otherwise it is dangling), so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has no loads, False otherwise.
is_dangling() -> bool
Checks if this wire segment is dangling.
A wire segment is dangling if it has no ports driving it or no ports being driven by it. A wire segment should have exactly one driver and at least one load, so this function should normally return False. If the function returns True (i.e. if the wire segment has no drivers or no loads), a warning is logged.
Returns:
-
bool(bool) –True if the wire segment is dangling, False otherwise.
has_problems() -> bool
Checks if this wire segment has any problems.
A wire segment has problems if it is dangling (i.e. it has no drivers or no loads) or if it has multiple drivers.
Returns:
-
bool(bool) –True if the wire segment has problems, False otherwise.
change_mutability(is_now_locked: bool) -> Self
copy_object(new_name: str) -> NetlistElement
Creates a new object of this type and copies the contents of this object into the new one.
Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.
When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.
Parameters:
Returns:
-
NetlistElement(NetlistElement) –A new object of this class.
normalize_metadata(
include_empty: bool = False,
sort_by: Literal["path", "category"] = "path",
filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT
Performs normalization of this element's metadata.
This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.
Parameters:
-
(include_empty¶bool, default:False) –Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.
-
(sort_by¶Literal['path', 'category'], default:'path') –Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.
-
(filter¶Callable[[str, NESTED_DICT], bool], default:lambda cat, md: True) –A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to
lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.
Returns:
-
METADATA_DICT(METADATA_DICT) –A normalized metadata dictionary containing the metadata of this element and all nested objects.
Bases: _WireSegmentConst
A wire segment that represents a constant 0 signal.
Methods:
-
change_mutability–Change the mutability of this NetlistElement instance.
-
copy_object–Creates a new object of this type and copies the contents of this object into the new one.
-
normalize_metadata–Performs normalization of this element's metadata.
-
add_port_segment–Adds a port segment to the set of ports connected to this wire segment.
-
add_port_segments–Adds multiple ports to the set of ports connected to this wire segment.
-
remove_port_segment–Removes a port segment from the set of ports connected to this wire segment.
-
has_defined_signal–Checks if the signal on this wire segment is defined.
-
driver–Returns a list of port segments driving this wire segment.
-
loads–Returns a list of port segments being driven by this wire segment.
-
has_no_driver–Checks if this wire segment has no ports driving it.
-
has_multiple_drivers–Checks if this wire segment has multiple ports driving it.
-
has_no_loads–Checks if this wire segment has no ports being driven by it.
-
is_dangling–Checks if this wire segment is dangling.
-
has_problems–Checks if this wire segment has any problems.
Attributes:
-
signal(Signal) –Returns the constant signal value for this wire segment, which is always Signal.LOW.
-
name(str) –The name of the element.
-
parameters(TypedParams) –Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as
WIDTHfor some instances). -
metadata(MetadataMixin) –Metadata of a netlist element.
-
type(EType) –The type of the element, which is a wire segment.
-
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.
-
index(int) –The index of the PortSegment in the Port, which is retrieved from the name.
-
grandparent('Module') –Retrieves the module that contains this WireSegment.
-
port_segments(CustomList[PortSegment]) –The port segments connected to this wire segment.
-
nr_connected_ports(int) –The number of port segments connected to this wire segment.
property
¶
signal: Signal
Returns the constant signal value for this wire segment, which is always Signal.LOW.
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
¶
Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).
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
¶
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.
This property is always True for constant wire segments.
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
writable
¶
index: int
The index of the PortSegment in the Port, which is retrieved from the name.
If this PortSegment instance is a placeholder instance (i.e. the path is empty and thus no name is available), then this value is -1 instead.
property
¶
Retrieves the module that contains this WireSegment.
If a parent is available (i.e. the hierarchy level is 2 or more), it is returned.
Returns:
-
Module('Module') –The module if it exists.
Raises:
-
ParentNotFoundError–If no parent or grandparent was found.
property
¶
port_segments: CustomList[PortSegment]
The port segments connected to this wire segment.
property
¶
nr_connected_ports: int
The number of port segments connected to this wire segment.
change_mutability(is_now_locked: bool) -> Self
copy_object(new_name: str) -> NetlistElement
Creates a new object of this type and copies the contents of this object into the new one.
Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.
When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.
Parameters:
Returns:
-
NetlistElement(NetlistElement) –A new object of this class.
normalize_metadata(
include_empty: bool = False,
sort_by: Literal["path", "category"] = "path",
filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT
Performs normalization of this element's metadata.
This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.
Parameters:
-
(include_empty¶bool, default:False) –Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.
-
(sort_by¶Literal['path', 'category'], default:'path') –Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.
-
(filter¶Callable[[str, NESTED_DICT], bool], default:lambda cat, md: True) –A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to
lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.
Returns:
-
METADATA_DICT(METADATA_DICT) –A normalized metadata dictionary containing the metadata of this element and all nested objects.
add_port_segment(port_segment: PortSegment) -> PortSegment
Adds a port segment to the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to add.
Returns:
-
PortSegment(PortSegment) –The PortSegment object that was added to this wire segment.
add_port_segments(port_segments: Iterable[PortSegment]) -> List[PortSegment]
Adds multiple ports to the set of ports connected to this wire segment.
Parameters:
-
(port_segments¶Iterable[PortSegment]) –An iterable of PortSegment objects to add.
Returns:
-
List[PortSegment]–List[PortSegment] A list with all port segments that were added.
remove_port_segment(port_segment: PortSegment) -> None
Removes a port segment from the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to remove.
has_defined_signal() -> bool
Checks if the signal on this wire segment is defined.
A defined signal is a signal with a value that is not "x" (undefined) or "z" (unconnected/floating). A signal with value 0 or 1 is considered defined.
driver(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments driving this wire segment.
A driver is a port segment that is connected to this wire segment and is driving the signal on it. A wire segment should have only one driver, so this function should return a list with only one element. If the list has more or less than one element, a warning is logged.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are more or less than 1 drivers. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments driving this wire segment.
loads(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments being driven by this wire segment.
A load is a port segment that is connected to this wire segment and is being driven by the signal on it. A wire segment can have multiple loads. If the list is empty (i.e., if there are no loads), a warning is logged if warn_if_issue is set to True.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are no loads. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments being driven by this wire segment.
has_no_driver() -> bool
Checks if this wire segment has no ports driving it.
Returns:
-
bool(bool) –True if the wire segment has no drivers, False otherwise.
has_multiple_drivers() -> bool
Checks if this wire segment has multiple ports driving it.
A wire segment should have only one driver, so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has multiple drivers, False otherwise.
has_no_loads() -> bool
Checks if this wire segment has no ports being driven by it.
A wire segment should have at least one load (otherwise it is dangling), so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has no loads, False otherwise.
is_dangling() -> bool
Checks if this wire segment is dangling.
A wire segment is dangling if it has no ports driving it or no ports being driven by it. A wire segment should have exactly one driver and at least one load, so this function should normally return False. If the function returns True (i.e. if the wire segment has no drivers or no loads), a warning is logged.
Returns:
-
bool(bool) –True if the wire segment is dangling, False otherwise.
Bases: _WireSegmentConst
A wire segment that represents a constant 1 signal.
Methods:
-
change_mutability–Change the mutability of this NetlistElement instance.
-
copy_object–Creates a new object of this type and copies the contents of this object into the new one.
-
normalize_metadata–Performs normalization of this element's metadata.
-
add_port_segment–Adds a port segment to the set of ports connected to this wire segment.
-
add_port_segments–Adds multiple ports to the set of ports connected to this wire segment.
-
remove_port_segment–Removes a port segment from the set of ports connected to this wire segment.
-
has_defined_signal–Checks if the signal on this wire segment is defined.
-
driver–Returns a list of port segments driving this wire segment.
-
loads–Returns a list of port segments being driven by this wire segment.
-
has_no_driver–Checks if this wire segment has no ports driving it.
-
has_multiple_drivers–Checks if this wire segment has multiple ports driving it.
-
has_no_loads–Checks if this wire segment has no ports being driven by it.
-
is_dangling–Checks if this wire segment is dangling.
-
has_problems–Checks if this wire segment has any problems.
Attributes:
-
signal(Signal) –Returns the constant signal value for this wire segment, which is always Signal.HIGH.
-
name(str) –The name of the element.
-
parameters(TypedParams) –Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as
WIDTHfor some instances). -
metadata(MetadataMixin) –Metadata of a netlist element.
-
type(EType) –The type of the element, which is a wire segment.
-
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.
-
index(int) –The index of the PortSegment in the Port, which is retrieved from the name.
-
grandparent('Module') –Retrieves the module that contains this WireSegment.
-
port_segments(CustomList[PortSegment]) –The port segments connected to this wire segment.
-
nr_connected_ports(int) –The number of port segments connected to this wire segment.
property
¶
signal: Signal
Returns the constant signal value for this wire segment, which is always Signal.HIGH.
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
¶
Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).
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
¶
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.
This property is always True for constant wire segments.
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
writable
¶
index: int
The index of the PortSegment in the Port, which is retrieved from the name.
If this PortSegment instance is a placeholder instance (i.e. the path is empty and thus no name is available), then this value is -1 instead.
property
¶
Retrieves the module that contains this WireSegment.
If a parent is available (i.e. the hierarchy level is 2 or more), it is returned.
Returns:
-
Module('Module') –The module if it exists.
Raises:
-
ParentNotFoundError–If no parent or grandparent was found.
property
¶
port_segments: CustomList[PortSegment]
The port segments connected to this wire segment.
property
¶
nr_connected_ports: int
The number of port segments connected to this wire segment.
change_mutability(is_now_locked: bool) -> Self
copy_object(new_name: str) -> NetlistElement
Creates a new object of this type and copies the contents of this object into the new one.
Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.
When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.
Parameters:
Returns:
-
NetlistElement(NetlistElement) –A new object of this class.
normalize_metadata(
include_empty: bool = False,
sort_by: Literal["path", "category"] = "path",
filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT
Performs normalization of this element's metadata.
This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.
Parameters:
-
(include_empty¶bool, default:False) –Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.
-
(sort_by¶Literal['path', 'category'], default:'path') –Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.
-
(filter¶Callable[[str, NESTED_DICT], bool], default:lambda cat, md: True) –A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to
lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.
Returns:
-
METADATA_DICT(METADATA_DICT) –A normalized metadata dictionary containing the metadata of this element and all nested objects.
add_port_segment(port_segment: PortSegment) -> PortSegment
Adds a port segment to the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to add.
Returns:
-
PortSegment(PortSegment) –The PortSegment object that was added to this wire segment.
add_port_segments(port_segments: Iterable[PortSegment]) -> List[PortSegment]
Adds multiple ports to the set of ports connected to this wire segment.
Parameters:
-
(port_segments¶Iterable[PortSegment]) –An iterable of PortSegment objects to add.
Returns:
-
List[PortSegment]–List[PortSegment] A list with all port segments that were added.
remove_port_segment(port_segment: PortSegment) -> None
Removes a port segment from the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to remove.
has_defined_signal() -> bool
Checks if the signal on this wire segment is defined.
A defined signal is a signal with a value that is not "x" (undefined) or "z" (unconnected/floating). A signal with value 0 or 1 is considered defined.
driver(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments driving this wire segment.
A driver is a port segment that is connected to this wire segment and is driving the signal on it. A wire segment should have only one driver, so this function should return a list with only one element. If the list has more or less than one element, a warning is logged.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are more or less than 1 drivers. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments driving this wire segment.
loads(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments being driven by this wire segment.
A load is a port segment that is connected to this wire segment and is being driven by the signal on it. A wire segment can have multiple loads. If the list is empty (i.e., if there are no loads), a warning is logged if warn_if_issue is set to True.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are no loads. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments being driven by this wire segment.
has_no_driver() -> bool
Checks if this wire segment has no ports driving it.
Returns:
-
bool(bool) –True if the wire segment has no drivers, False otherwise.
has_multiple_drivers() -> bool
Checks if this wire segment has multiple ports driving it.
A wire segment should have only one driver, so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has multiple drivers, False otherwise.
has_no_loads() -> bool
Checks if this wire segment has no ports being driven by it.
A wire segment should have at least one load (otherwise it is dangling), so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has no loads, False otherwise.
is_dangling() -> bool
Checks if this wire segment is dangling.
A wire segment is dangling if it has no ports driving it or no ports being driven by it. A wire segment should have exactly one driver and at least one load, so this function should normally return False. If the function returns True (i.e. if the wire segment has no drivers or no loads), a warning is logged.
Returns:
-
bool(bool) –True if the wire segment is dangling, False otherwise.
Bases: _WireSegmentConst
A wire segment that represents a floating signal.
Methods:
-
change_mutability–Change the mutability of this NetlistElement instance.
-
copy_object–Creates a new object of this type and copies the contents of this object into the new one.
-
normalize_metadata–Performs normalization of this element's metadata.
-
add_port_segment–Adds a port segment to the set of ports connected to this wire segment.
-
add_port_segments–Adds multiple ports to the set of ports connected to this wire segment.
-
remove_port_segment–Removes a port segment from the set of ports connected to this wire segment.
-
has_defined_signal–Checks if the signal on this wire segment is defined.
-
driver–Returns a list of port segments driving this wire segment.
-
loads–Returns a list of port segments being driven by this wire segment.
-
has_no_driver–Checks if this wire segment has no ports driving it.
-
has_multiple_drivers–Checks if this wire segment has multiple ports driving it.
-
has_no_loads–Checks if this wire segment has no ports being driven by it.
-
is_dangling–Checks if this wire segment is dangling.
-
has_problems–Checks if this wire segment has any problems.
Attributes:
-
signal(Signal) –Returns the constant signal value for this wire segment, which is always Signal.FLOATING.
-
name(str) –The name of the element.
-
parameters(TypedParams) –Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as
WIDTHfor some instances). -
metadata(MetadataMixin) –Metadata of a netlist element.
-
type(EType) –The type of the element, which is a wire segment.
-
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.
-
index(int) –The index of the PortSegment in the Port, which is retrieved from the name.
-
grandparent('Module') –Retrieves the module that contains this WireSegment.
-
port_segments(CustomList[PortSegment]) –The port segments connected to this wire segment.
-
nr_connected_ports(int) –The number of port segments connected to this wire segment.
property
¶
signal: Signal
Returns the constant signal value for this wire segment, which is always Signal.FLOATING.
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
¶
Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).
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
¶
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.
This property is always True for constant wire segments.
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
writable
¶
index: int
The index of the PortSegment in the Port, which is retrieved from the name.
If this PortSegment instance is a placeholder instance (i.e. the path is empty and thus no name is available), then this value is -1 instead.
property
¶
Retrieves the module that contains this WireSegment.
If a parent is available (i.e. the hierarchy level is 2 or more), it is returned.
Returns:
-
Module('Module') –The module if it exists.
Raises:
-
ParentNotFoundError–If no parent or grandparent was found.
property
¶
port_segments: CustomList[PortSegment]
The port segments connected to this wire segment.
property
¶
nr_connected_ports: int
The number of port segments connected to this wire segment.
change_mutability(is_now_locked: bool) -> Self
copy_object(new_name: str) -> NetlistElement
Creates a new object of this type and copies the contents of this object into the new one.
Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.
When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.
Parameters:
Returns:
-
NetlistElement(NetlistElement) –A new object of this class.
normalize_metadata(
include_empty: bool = False,
sort_by: Literal["path", "category"] = "path",
filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT
Performs normalization of this element's metadata.
This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.
Parameters:
-
(include_empty¶bool, default:False) –Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.
-
(sort_by¶Literal['path', 'category'], default:'path') –Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.
-
(filter¶Callable[[str, NESTED_DICT], bool], default:lambda cat, md: True) –A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to
lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.
Returns:
-
METADATA_DICT(METADATA_DICT) –A normalized metadata dictionary containing the metadata of this element and all nested objects.
add_port_segment(port_segment: PortSegment) -> PortSegment
Adds a port segment to the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to add.
Returns:
-
PortSegment(PortSegment) –The PortSegment object that was added to this wire segment.
add_port_segments(port_segments: Iterable[PortSegment]) -> List[PortSegment]
Adds multiple ports to the set of ports connected to this wire segment.
Parameters:
-
(port_segments¶Iterable[PortSegment]) –An iterable of PortSegment objects to add.
Returns:
-
List[PortSegment]–List[PortSegment] A list with all port segments that were added.
remove_port_segment(port_segment: PortSegment) -> None
Removes a port segment from the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to remove.
has_defined_signal() -> bool
Checks if the signal on this wire segment is defined.
A defined signal is a signal with a value that is not "x" (undefined) or "z" (unconnected/floating). A signal with value 0 or 1 is considered defined.
driver(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments driving this wire segment.
A driver is a port segment that is connected to this wire segment and is driving the signal on it. A wire segment should have only one driver, so this function should return a list with only one element. If the list has more or less than one element, a warning is logged.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are more or less than 1 drivers. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments driving this wire segment.
loads(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments being driven by this wire segment.
A load is a port segment that is connected to this wire segment and is being driven by the signal on it. A wire segment can have multiple loads. If the list is empty (i.e., if there are no loads), a warning is logged if warn_if_issue is set to True.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are no loads. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments being driven by this wire segment.
has_no_driver() -> bool
Checks if this wire segment has no ports driving it.
Returns:
-
bool(bool) –True if the wire segment has no drivers, False otherwise.
has_multiple_drivers() -> bool
Checks if this wire segment has multiple ports driving it.
A wire segment should have only one driver, so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has multiple drivers, False otherwise.
has_no_loads() -> bool
Checks if this wire segment has no ports being driven by it.
A wire segment should have at least one load (otherwise it is dangling), so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has no loads, False otherwise.
is_dangling() -> bool
Checks if this wire segment is dangling.
A wire segment is dangling if it has no ports driving it or no ports being driven by it. A wire segment should have exactly one driver and at least one load, so this function should normally return False. If the function returns True (i.e. if the wire segment has no drivers or no loads), a warning is logged.
Returns:
-
bool(bool) –True if the wire segment is dangling, False otherwise.
Bases: _WireSegmentConst
A wire segment that represents an unconnected signal (which has the value X/UNDEFINED).
Methods:
-
change_mutability–Change the mutability of this NetlistElement instance.
-
copy_object–Creates a new object of this type and copies the contents of this object into the new one.
-
normalize_metadata–Performs normalization of this element's metadata.
-
add_port_segment–Adds a port segment to the set of ports connected to this wire segment.
-
add_port_segments–Adds multiple ports to the set of ports connected to this wire segment.
-
remove_port_segment–Removes a port segment from the set of ports connected to this wire segment.
-
has_defined_signal–Checks if the signal on this wire segment is defined.
-
driver–Returns a list of port segments driving this wire segment.
-
loads–Returns a list of port segments being driven by this wire segment.
-
has_no_driver–Checks if this wire segment has no ports driving it.
-
has_multiple_drivers–Checks if this wire segment has multiple ports driving it.
-
has_no_loads–Checks if this wire segment has no ports being driven by it.
-
is_dangling–Checks if this wire segment is dangling.
-
has_problems–Checks if this wire segment has any problems.
Attributes:
-
signal(Signal) –Returns the constant signal value for this wire segment, which is always Signal.UNDEFINED.
-
name(str) –The name of the element.
-
parameters(TypedParams) –Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as
WIDTHfor some instances). -
metadata(MetadataMixin) –Metadata of a netlist element.
-
type(EType) –The type of the element, which is a wire segment.
-
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.
-
index(int) –The index of the PortSegment in the Port, which is retrieved from the name.
-
grandparent('Module') –Retrieves the module that contains this WireSegment.
-
port_segments(CustomList[PortSegment]) –The port segments connected to this wire segment.
-
nr_connected_ports(int) –The number of port segments connected to this wire segment.
property
¶
signal: Signal
Returns the constant signal value for this wire segment, which is always Signal.UNDEFINED.
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
¶
Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).
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
¶
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.
This property is always True for constant wire segments.
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
writable
¶
index: int
The index of the PortSegment in the Port, which is retrieved from the name.
If this PortSegment instance is a placeholder instance (i.e. the path is empty and thus no name is available), then this value is -1 instead.
property
¶
Retrieves the module that contains this WireSegment.
If a parent is available (i.e. the hierarchy level is 2 or more), it is returned.
Returns:
-
Module('Module') –The module if it exists.
Raises:
-
ParentNotFoundError–If no parent or grandparent was found.
property
¶
port_segments: CustomList[PortSegment]
The port segments connected to this wire segment.
property
¶
nr_connected_ports: int
The number of port segments connected to this wire segment.
change_mutability(is_now_locked: bool) -> Self
copy_object(new_name: str) -> NetlistElement
Creates a new object of this type and copies the contents of this object into the new one.
Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.
When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.
Parameters:
Returns:
-
NetlistElement(NetlistElement) –A new object of this class.
normalize_metadata(
include_empty: bool = False,
sort_by: Literal["path", "category"] = "path",
filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT
Performs normalization of this element's metadata.
This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.
Parameters:
-
(include_empty¶bool, default:False) –Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.
-
(sort_by¶Literal['path', 'category'], default:'path') –Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.
-
(filter¶Callable[[str, NESTED_DICT], bool], default:lambda cat, md: True) –A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to
lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.
Returns:
-
METADATA_DICT(METADATA_DICT) –A normalized metadata dictionary containing the metadata of this element and all nested objects.
add_port_segment(port_segment: PortSegment) -> PortSegment
Adds a port segment to the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to add.
Returns:
-
PortSegment(PortSegment) –The PortSegment object that was added to this wire segment.
add_port_segments(port_segments: Iterable[PortSegment]) -> List[PortSegment]
Adds multiple ports to the set of ports connected to this wire segment.
Parameters:
-
(port_segments¶Iterable[PortSegment]) –An iterable of PortSegment objects to add.
Returns:
-
List[PortSegment]–List[PortSegment] A list with all port segments that were added.
remove_port_segment(port_segment: PortSegment) -> None
Removes a port segment from the set of ports connected to this wire segment.
Parameters:
-
(port_segment¶PortSegment) –The port segment to remove.
has_defined_signal() -> bool
Checks if the signal on this wire segment is defined.
A defined signal is a signal with a value that is not "x" (undefined) or "z" (unconnected/floating). A signal with value 0 or 1 is considered defined.
driver(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments driving this wire segment.
A driver is a port segment that is connected to this wire segment and is driving the signal on it. A wire segment should have only one driver, so this function should return a list with only one element. If the list has more or less than one element, a warning is logged.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are more or less than 1 drivers. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments driving this wire segment.
loads(warn_if_issue: bool = False) -> List[PortSegment]
Returns a list of port segments being driven by this wire segment.
A load is a port segment that is connected to this wire segment and is being driven by the signal on it. A wire segment can have multiple loads. If the list is empty (i.e., if there are no loads), a warning is logged if warn_if_issue is set to True.
Parameters:
-
(warn_if_issue¶bool, default:False) –Whether or not to log a warning if there are no loads. Defaults to False.
Returns:
-
List[PortSegment]–List[PortSegment]: A list of port segments being driven by this wire segment.
has_no_driver() -> bool
Checks if this wire segment has no ports driving it.
Returns:
-
bool(bool) –True if the wire segment has no drivers, False otherwise.
has_multiple_drivers() -> bool
Checks if this wire segment has multiple ports driving it.
A wire segment should have only one driver, so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has multiple drivers, False otherwise.
has_no_loads() -> bool
Checks if this wire segment has no ports being driven by it.
A wire segment should have at least one load (otherwise it is dangling), so this function should return False. If the function returns True, a warning is logged.
Returns:
-
bool(bool) –True if the wire segment has no loads, False otherwise.
is_dangling() -> bool
Checks if this wire segment is dangling.
A wire segment is dangling if it has no ports driving it or no ports being driven by it. A wire segment should have exactly one driver and at least one load, so this function should normally return False. If the function returns True (i.e. if the wire segment has no drivers or no loads), a warning is logged.
Returns:
-
bool(bool) –True if the wire segment is dangling, False otherwise.