Skip to content

netlist_carpentry.core.netlist_elements.netlist_element

Base class for all netlist (or circuit) elements.

Classes:

  • NetlistElement –

    Represents a netlist element, such as an instance or a wire.

NetlistElement

Bases: HooksMixin, BaseModel

Represents a netlist element, such as an instance or a wire.

Attributes:

  • name (str) –

    The name of the element.

Methods:

  • set_name –

    Sets the name of this object to the given value by updating its hierarchical path.

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

  • evaluate –

    Evaluate the element depending on the incoming signals.

  • normalize_metadata –

    Performs normalization of this element's metadata.

name instance-attribute 

name: str

The name of the element.

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

parameters class-attribute instance-attribute 

parameters: TypedParams = {}

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

metadata class-attribute instance-attribute 

metadata: MetadataMixin = MetadataMixin()

Metadata of a netlist element.

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

path property 

path: ElementPath

Returns the ElementPath of the netlist element.

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

Returns:

  • ElementPath ( ElementPath ) –

    The hierarchical path of the netlist element.

type property 

type: EType

The type of the element, such as an instance, wire or port.

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.

parent property 

parent: NetlistElement

The parent object of this object.

  • For a port or wire segment, the parent is a port or a wire.
  • For a port, the parent is either an instance (if it is an instance port) or a module.
  • For a wire, the parent is a module.
  • For an instance, the parent is either an instance again or a module.
  • Modules do not have parents.

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.

set_name 

set_name(new_name: str) -> None

Sets the name of this object to the given value by updating its hierarchical path.

To also update the path names of objects that are part of this object (e.g. segments), overwrite NetlistElement._set_name_recursively, which is called by this method. By doing so, the paths of all contained objects can be updated accordingly.

Parameters:

  • new_name

    (str) –

    The new name to set to the object.

change_mutability 

change_mutability(is_now_locked: bool) -> Self

Change the mutability of this NetlistElement instance.

Parameters:

  • is_now_locked

    (bool) –

    The new value for the element's mutability. True means, the element is now locked; False means, the element is mow mutable.

Returns:

  • NetlistElement ( Self ) –

    This instance with its mutability changed.

copy_object 

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:

  • new_name

    (str) –

    The name for the newly created copy.

Returns:

evaluate 

evaluate() -> None

Evaluate the element depending on the incoming signals.

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

Raises:

normalize_metadata 

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.