Node

Base classes

Node

class systemrdl.node.Node(inst: Component, env: RDLEnvironment, parent: Optional[Node])

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: Optional[SignalNode]

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) → Optional[Node]

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) → Optional[Node]

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_html_desc(markdown_inst: Optional[Markdown] = None) → Optional[str]

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() → Optional[str]

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: Optional[str]

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: Optional[AddrmapNode]

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: Optional[str]

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: Optional[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: Optional[List[int]]

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: Optional[int]

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 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: Optional[Node])

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: Optional[Node])

FieldNode

class systemrdl.node.FieldNode(inst: Component, env: RDLEnvironment, parent: Optional[Node])

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.

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: Optional[Node])

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: Optional[Node])

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: Optional[Node])

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: Optional[Node])

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: Optional[Node])

property top: AddrmapNode

Returns the top-level addrmap node