Base classes

Base classes#

Node#

class systemrdl.node.Node(inst: Component, env: RDLEnvironment, parent: Node | None)#

The Node class is the base for all Node overlay classes.

__eq__(other: object) → bool#

Node equality checks determine whether the other node represents the same position in the register model’s hierarchy.

__deepcopy__(memo: Dict[int, Any]) → Node#

Deepcopy the node overlay. Members that are not part of the overlay (component tree) are not deepcopied.

Added in version 1.8.

children(unroll: bool = False, skip_not_present: bool = True) → List[Node]#

Returns a list of all immediate children of this component.

Parameters:

  • unroll (bool) – If True, any children that are arrays are unrolled.

  • skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False

Returns:

All immediate children

Return type:

List of Node

Changed in version 1.29: Returns list instead of generator

property component_type_name: str#

Returns the component type name that this node represents. For example: “reg”, “field”, “addrmap”, etc…

Added in version 1.31.

property cpuif_reset: SignalNode | None#

Returns a reference to the nearest cpuif_reset signal in the enclosing hierarchy.

Is None if no cpuif_reset signal was found.

Added in version 1.19.

property def_src_ref: SourceRefBase | None#

Source Reference for the component definition.

Added in version 1.30.

descendants(unroll: bool = False, skip_not_present: bool = True, in_post_order: bool = False) → Iterator[Node]#

Returns an iterator that provides nodes for all descendants of this component.

Parameters:

  • unroll (bool) – If True, any children that are arrays are unrolled.

  • skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False

  • in_post_order (bool) – If True, descendants are walked using post-order traversal (children first) rather than the default pre-order traversal (parents first).

Yields:

Node – All descendant nodes of this component

property external: bool#

True if instance type is external. False if internal.

Added in version 1.9.

find_by_path(path: str) → Node | None#

Finds the descendant node that is located at the relative path Returns None if not found Raises exception if path is malformed, or array index is out of range

Parameters:

path (str) – Path to target relative to current node

Returns:

Descendant Node. None if not found.

Return type:

Node or None

Raises:

  • ValueError – If path syntax is invalid

  • IndexError – If an array index in the path is invalid

get_child_by_name(inst_name: str) → Node | None#

Returns an immediate child Node whose instance name matches inst_name

Returns None if inst_name does not match

Parameters:

inst_name (str) – Name of immediate child to get

Returns:

Child Node. None if not found.

Return type:

Node or None

get_global_type_name(separator: str = '__') → str | None#

Returns a globally scoped type name that can be used to uniquely identify this node’s type.

If scope or type name information is not available due to the node being imported from a non-RDL source, this will return None.

Added in version 1.27.0.

get_html_desc(markdown_inst: Markdown | None = None) → str | None#

Translates the node’s ‘desc’ property into HTML.

Any RDLFormatCode tags used are converted to HTML. The text is also fed through a Markdown processor.

The additional Markdown processing allows designers the choice to use a more modern lightweight markup language as an alternative to SystemRDL’s “RDLFormatCode”.

Parameters:

markdown_inst (markdown.Markdown) – Override the class instance of the Markdown processor. See the Markdown module for more details.

Returns:

HTML formatted string. If node does not have a description, returns None

Return type:

str or None

Changed in version 1.6: Added markdown_inst option.

get_html_name() → str | None#

Translates the node’s ‘name’ property into HTML.

Any RDLFormatCode tags used are converted to HTML.

Returns:

HTML formatted string. If node does not have an explicitly set name, returns None

Return type:

str or None

Added in version 1.8.

get_path(hier_separator: str = '.', array_suffix: str = '[{index:d}]', empty_array_suffix: str = '[]') → str#

Generate an absolute path string to this node

Parameters:

  • hier_separator (str) – Override the hierarchy separator

  • array_suffix (str) –

    Override how array suffixes are represented when the index is known.

    The suffix is processed using string.format() with the following available kwargs:

    • index: The current array index

    • dim: The number of elements in the array dimension

  • empty_array_suffix (str) –

    Override how array suffixes are represented when the index is not known.

    The suffix is processed using string.format() with the following available kwargs:

    • dim: The number of elements in the array dimension

Changed in version 1.17: Added dim kwarg to suffix formatting.

get_path_segment(array_suffix: str = '[{index:d}]', empty_array_suffix: str = '[]') → str#

Gets the hierarchical path segment for just this node. This includes the instance name and any array suffixes.

Parameters:

  • array_suffix (str) – Override how array suffixes are represented when the index is known

  • empty_array_suffix (str) – Override how array suffixes are represented when the index is not known

get_path_segments(array_suffix: str = '[{index:d}]', empty_array_suffix: str = '[]') → List[str]#

Gets a list of path segments that represent the hierarchical path.

Added in version 1.8.

get_property(prop_name: Literal['name'], *, default: T) → str | T#
get_property(prop_name: Literal['name'], **kwargs: Any) → str
get_property(prop_name: Literal['desc'], *, default: T) → str | None | T
get_property(prop_name: Literal['desc'], **kwargs: Any) → str | None
get_property(prop_name: Literal['ispresent'], *, default: T) → bool | T
get_property(prop_name: Literal['ispresent'], **kwargs: Any) → bool
get_property(prop_name: str, *, default: T) → Any | T
get_property(prop_name: str) → Any

Gets the SystemRDL component property

If a property was not explicitly set in the RDL source, its default value is derived. In some cases, a default value is implied according to other property values.

Properties values that are a reference to a component instance are converted to a Node overlay object.

Parameters:

  • prop_name (str) – SystemRDL property name

  • default – Override built-in default value of property. If the property was not explicitly set, return this value rather than the property’s intrinsic default value.

Raises:

LookupError – If prop_name is invalid

get_rel_path(ref: Node, uplevel: str = '^', hier_separator: str = '.', array_suffix: str = '[{index:d}]', empty_array_suffix: str = '[]') → str#

Generate a relative path string to this node with respect to a reference node.

A reference to a descendant node:

foo.bar->foo.bar.baz.abcd = "baz.abcd"

Relative path that traverses upwards:

foo.bar.baz->foo.abc.def = "^.^.abc.def"

Relative path to self results in an empty string:

foo.bar.baz->foo.bar.baz = ""

Paths between array nodes with/without indexes will result in upwards paths:

foo.array[].baz->foo.array[0].baz = "^.^.array[0].baz"
foo.array[0].baz->foo.array[].baz = "^.^.array[].baz"
Parameters:

  • ref (Node) – Reference starting point node

  • uplevel (str) – Override the string that denotes traversing up by one parent

  • hier_separator (str) – Override the hierarchy separator

  • array_suffix (str) – Override how array suffixes are represented when the index is known

  • empty_array_suffix (str) – Override how array suffixes are represented when the index is not known

Added in version 1.8.

get_scope_path(scope_separator: str = '::') → str | None#

Generate a string that represents this component’s declaration namespace scope.

Returns None if scope is not known or not applicable.

For example, the following SystemRDL snippet:

reg my_reg_t {
    field {} x;
};

addrmap top {
    my_reg_t foo;
    reg my_other_reg_t {
        field {} y;
    } bar;
    reg {
        field {} z;
    } baz, xyz;
};

… results in:

  • Field x of hierarchical path top.foo.x was declared in the lexical scope my_reg_t

  • Field y of hierarchical path top.bar.y was declared in the lexical scope top::my_other_reg_t

  • Both fields z of hierarchical paths top.baz.z and top.xyz.z were declared in the same lexical scope top::baz

  • Register foo was declared in the root scope which is represented by an empty string.

Parameters:

  • scope_separator (str) – Override the separator between namespace scopes

  • versionadded: (..) – 1.30:

inst#

Reference to Component data object.

Deprecated since version 1.30: Querying the internal Component objects is no longer recommended.

Equivalents for most concepts have been made available as direct methods or properties of Node objects. It is strongly recommended to use these instead to prevent compatibility issues.

property inst_name: str#

Name of instantiated element

property inst_src_ref: SourceRefBase | None#

Source Reference for the component instantiation.

Added in version 1.30.

list_properties(list_all: bool = False, include_native: bool = True, include_udp: bool = True) → List[str]#

Lists properties associated with this node. By default, only lists properties that were explicitly set. If list_all is set to True then lists all valid properties of this component type

Parameters:

  • list_all (bool) – If true, lists all valid properties of this component type.

  • include_native (bool) – If set to false, does not list native SystemRDL properties in the output.

  • include_udp (bool) – If set to false, does not list user-defined properties in the output.

Changed in version 1.12: Added include_native and include_udp options.

property orig_type_name: str | None#

Named definition identifier prior to type name normalization. If the declaration was anonymous, this reads as None.

Added in version 1.9.

property owning_addrmap: AddrmapNode | None#

Returns the enclosing addrmap that owns this node.

If this node is already an addrmap, returns itself

If not enclosed in an addrmap, returns None

Added in version 1.12.

property parameters: OrderedDict[str, Any]#

Returns a dictionary of the parameters of this component, and their final elaborated values.

These are stored in the order that they were defined

Added in version 1.30.

parent#

Reference to parent Node

property property_src_ref: Dict[str, SourceRefBase]#

Source Reference for each explicit property assignment (if available)

Added in version 1.30.

registers(unroll: bool = False, skip_not_present: bool = True) → List[RegNode]#

Returns a list of all immediate registers of this component.

Parameters:

  • unroll (bool) – If True, any children that are arrays are unrolled.

  • skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False

Returns:

All registers in this component

Return type:

RegNode

Changed in version 1.29: Returns list instead of generator

signals(skip_not_present: bool = True) → List[SignalNode]#

Returns a list of all immediate signals of this component.

Parameters:

skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False

Returns:

All signals in this component

Return type:

SignalNode

Changed in version 1.29: Returns list instead of generator

property type_name: str | None#

Named definition identifier. If declaration was anonymous, inherits the first instance’s name. The type name of parameterized components is normalized based on the instance’s parameter values.

Importers may leave this as None

Added in version 1.9.

unrolled() → Iterator[Node]#

Returns an iterator that provides unrolled nodes for this instance

Yields:

  • Node – Unrolled array dimensions

  • .. versionadded:: 1.20.0

AddressableNode#

class systemrdl.node.AddressableNode(inst: AddressableComponent, env: RDLEnvironment, parent: Node | None)#

Bases: Node

Base-class for any kind of node that can have an address

property absolute_address: int#

Get the absolute byte address of this node.

Indexes of all arrays in the node’s lineage must be known

Raises:

ValueError – If this property is referenced on a node whose array lineage is not fully defined

property address_offset: int#

Byte address offset of this node relative to its parent

If this node is an array, its index must be known

Raises:

ValueError – If this property is referenced on a node whose array index is not fully defined

property array_dimensions: List[int] | None#

List of sizes for each array dimension. Last item in the list iterates the most frequently.

If node is not an array (is_array == False), then this is None

property array_stride: int | None#

Address offset between array elements.

If node is not an array (is_array == False), then this is None

clear_lineage_index() → None#

Resets this node’s, as well as all parent node array indexes to the ‘unknown index’ state.

Added in version 1.7.

current_idx: List[int] | None#

List of current array indexes this node is referencing where the last item in this list iterates the most frequently

If None, then the current index is unknown

get_path_segment(array_suffix: str = '[{index:d}]', empty_array_suffix: str = '[]') → str#

Gets the hierarchical path segment for just this node. This includes the instance name and any array suffixes.

Parameters:

  • array_suffix (str) – Override how array suffixes are represented when the index is known

  • empty_array_suffix (str) – Override how array suffixes are represented when the index is not known

get_property(prop_name: Literal['name'], *, default: T) → str | T#
get_property(prop_name: Literal['name'], **kwargs: Any) → str
get_property(prop_name: Literal['desc'], *, default: T) → str | None | T
get_property(prop_name: Literal['desc'], **kwargs: Any) → str | None
get_property(prop_name: Literal['ispresent'], *, default: T) → bool | T
get_property(prop_name: Literal['ispresent'], **kwargs: Any) → bool
get_property(prop_name: str, *, default: T) → Any | T
get_property(prop_name: str, **kwargs: Any) → Any

Gets the SystemRDL component property

If a property was not explicitly set in the RDL source, its default value is derived. In some cases, a default value is implied according to other property values.

Properties values that are a reference to a component instance are converted to a Node overlay object.

Parameters:

  • prop_name (str) – SystemRDL property name

  • default – Override built-in default value of property. If the property was not explicitly set, return this value rather than the property’s intrinsic default value.

Raises:

LookupError – If prop_name is invalid

inst: AddressableComponent#

Reference to Component data object.

Deprecated since version 1.30: Querying the internal Component objects is no longer recommended.

Equivalents for most concepts have been made available as direct methods or properties of Node objects. It is strongly recommended to use these instead to prevent compatibility issues.

property is_array: bool#

Indicates that this node represents an array of instances

property n_elements: int#

Total number of array elements. If array is multidimensional, array is flattened. Returns 1 if not an array.

Added in version 1.30.

parent: AddressableNode | RootNode#

Reference to parent Node

property raw_absolute_address: int#

Get the absolute byte address of this node excluding array stride of all parent.

If this node, and all parents are not an array, then this is equivalent to absolute_address

Added in version 1.7.

property raw_address_offset: int#

Raw byte address offset of the first array element node relative to its parent.

If this node is not an array, then this is equivalent to address_offset

property size: int#

Determine the size (in bytes) of this node.

If an array, returns the size of a single element

property total_size: int#

Determine the size (in bytes) of this node. If an array, returns size of the entire array

zero_lineage_index() → None#

Resets this node’s, as well as all parent node array indexes to zero.

Added in version 1.7.

VectorNode#

class systemrdl.node.VectorNode(inst: Component, env: RDLEnvironment, parent: Node | None)#

Bases: Node

Base-class for any kind of node that is vector-like.

get_property(prop_name: Literal['name'], *, default: T) → str | T#
get_property(prop_name: Literal['name'], **kwargs: Any) → str
get_property(prop_name: Literal['desc'], *, default: T) → str | None | T
get_property(prop_name: Literal['desc'], **kwargs: Any) → str | None
get_property(prop_name: Literal['ispresent'], *, default: T) → bool | T
get_property(prop_name: Literal['ispresent'], **kwargs: Any) → bool
get_property(prop_name: str, *, default: T) → Any | T
get_property(prop_name: str, **kwargs: Any) → Any

Gets the SystemRDL component property

If a property was not explicitly set in the RDL source, its default value is derived. In some cases, a default value is implied according to other property values.

Properties values that are a reference to a component instance are converted to a Node overlay object.

Parameters:

  • prop_name (str) – SystemRDL property name

  • default – Override built-in default value of property. If the property was not explicitly set, return this value rather than the property’s intrinsic default value.

Raises:

LookupError – If prop_name is invalid

property high: int#

High index of bit range

inst: VectorComponent#

Reference to Component data object.

Deprecated since version 1.30: Querying the internal Component objects is no longer recommended.

Equivalents for most concepts have been made available as direct methods or properties of Node objects. It is strongly recommended to use these instead to prevent compatibility issues.

property low: int#

Low index of bit range

property lsb: int#

Bit position of least significant bit

property msb: int#

Bit position of most significant bit

parent: Node#

Reference to parent Node

property width: int#

Width of vector in bits