Node

Base classes

Node

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

The Node object is a higher-level overlay that provides a more user-friendly interface to query the compiled RDL object model.

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

New in version 1.8.

children(unroll: bool = False, skip_not_present: bool = True) → Iterator[Node]

Returns an iterator that provides nodes for 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

Yields:

Node – All immediate children

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.

New in version 1.19.

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.

New in version 1.9.

fields(skip_not_present: bool = True) → Iterator[FieldNode]

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

Parameters:: skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False
Yields:: FieldNode – All fields in this component

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.

New 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

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

New in version 1.8.

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

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

New in version 1.8.

inst: Reference to Component that instantiates this node

property inst_name: str: Name of instantiated element

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.

New 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

New in version 1.12.

parent: Reference to parent Node

registers(unroll: bool = False, skip_not_present: bool = True) → Iterator[RegNode]

Returns an iterator that provides nodes for 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

Yields:

RegNode – All registers in this component

signals(skip_not_present: bool = True) → Iterator[SignalNode]

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

Parameters:: skip_not_present (bool) – If True, skips children whose ‘ispresent’ property is set to False
Yields:: SignalNode – All signals in this component

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

New 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)

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.

New 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

property is_array: bool: Indicates that this node represents an array of instances

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

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

New in version 1.7.

VectorNode

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

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

property high: int: High index of bit range

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

property width: int: Width of vector in bits

Component Nodes

SignalNode

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

FieldNode

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

property alias_primary: FieldNode

Returns the FieldNode that is associated with this alias’s primary register.

Raises ValueError if this field is not an alias

New in version 1.23.

aliases(skip_not_present: bool = True) → Iterator[FieldNode]

Returns an iterator of all the fields that are aliases of this primary field

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

New in version 1.23.

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.

New in version 1.27.0.

property has_aliases: bool: Returns True if this field has aliases

New in version 1.23.

property implements_storage: bool: True if combination of field access properties imply that the field implements a storage element.

Changed in version 1.22: Counter, interrupt, stickybit, and sticky fields always implement storage, regardless of sw/hw access.

Changed in version 1.23: Alias fields never implement storage. A primary field may inherit a storage element depending on the access modes of aliases that augment access to it.

property is_alias: bool: Indicates whether this field is an alias (is contained inside an alias register)

New in version 1.23.

property is_down_counter: bool: Denotes whether this field is a counter and the property assignments imply it has down-counting functionality.

New in version 1.21.

property is_hw_readable: bool: Field is readable by hardware

property is_hw_writable: bool: Field is writable by hardware

property is_sw_readable: bool: Field is readable by software

property is_sw_writable: bool: Field is writable by software

property is_up_counter: bool: Denotes whether this field is a counter and the property assignments imply it has up-counting functionality.

New in version 1.21.

property is_virtual: bool: Determines if this node represents a virtual field (child of a virtual register)

property is_volatile: bool: True if combination of field access properties result in a field that should be interpreted as volatile. (Any hardware-writable field is inherently volatile)

RegNode

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

property alias_primary: RegNode

Returns the RegNode of this alias’s primary register.

Raises ValueError if this register is not an alias

New in version 1.23.

aliases(skip_not_present: bool = True) → Iterator[RegNode]

Returns an iterator of all the registers that are aliases of this primary register

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

New in version 1.23.

property has_aliases: bool: Returns True if this register has aliases

New in version 1.23.

property has_hw_readable: bool: Register contains one or more present fields readable by hardware

property has_hw_writable: bool: Register contains one or more present fields writable by hardware

property has_sw_readable: bool: Register contains one or more present fields readable by software

property has_sw_writable: bool: Register contains one or more present fields writable by software

property is_alias: bool: Indicates whether this register is an alias.

New in version 1.23.

property is_halt_reg: bool: Register contains one or more interrupt fields that use haltenable or haltmask and therefore produces a halt output signal.

New in version 1.22.

property is_interrupt_reg: bool: Register contains one or more interrupt fields and therefore produces an interrupt output signal.

New in version 1.22.

property is_virtual: bool: True if this node represents a virtual register. (child of a mem component)

property size: int

Determine the size (in bytes) of this node.

If an array, returns the size of a single element

RegfileNode

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

property size: int

Determine the size (in bytes) of this node.

If an array, returns the size of a single element

AddrmapNode

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

property size: int

Determine the size (in bytes) of this node.

If an array, returns the size of a single element

MemNode

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

property is_sw_readable: bool: Memory is readable by software

New in version 1.21.

property is_sw_writable: bool: Memory is writable by software

New in version 1.21.

property size: int

Determine the size (in bytes) of this node.

If an array, returns the size of a single element

Other

RootNode

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

property top: AddrmapNode: Returns the top-level addrmap node