peakrdl_halcpp package

Subpackages

• peakrdl_halcpp.include package
  • List of files:
• peakrdl_halcpp.templates package
  • List of files:

Submodules

peakrdl_halcpp.exporter module

class peakrdl_halcpp.exporter.HalExporter(**kwargs: Any)

Bases: object

HAL C++ PeakRDL plugin top class to generate the C++ HAL from SystemRDL description.

Class methods:

• copy_base_headers()

• export()

• process_template()

__init__(**kwargs: Any)

cpp_dir

HAL C++ copied header library location within the generated files output directory

base_headers

HAL C++ headers list (copied into cpp_dir)

copy_base_headers(outdir: str)

Copies the HAL C++ headers to the generated files location given by the outdir parameter.

Parameters:

outdir (str) – Output directory in which the output files are generated.

export(node: ~systemrdl.node.AddrmapNode, outdir: str, list_files: bool = False, ext_modules: ~typing.List = [<class 'str'>], skip_buses: bool = False)

Main function of the plugin extension.

Parameters:

• node (AddrmapNode) – Top AddrmapNode of the SystemRDL description.

• outdir (str) – Output directory in which the output files are generated.

• list_files (bool = False) – Don’t generate but print the files that would be generated.

• ext_modules (List[str]) – List of modules (i.e., SystemRDL addrmap objects) with extended functionalities.

• skip_buses (bool = False) – If True, AddrMapNodes containing only AddrMapNodes (transparent buses) are removed from the hierarchy and their children are promoted.

process_template(context: Dict) → str

Generates a C++ header file based on a jinja2 template.

Parameters:

context (Dict) – Dictionary containing a HalAddrmapNode and the HalUtils object (and other variables) passed to the jinja2 env

Returns:

Text of the generated C++ header for a given HalAddrmap node.

Return type:

str

peakrdl_halcpp.halnode module

class peakrdl_halcpp.halnode.HalBaseNode(inst: Component, env: RDLEnvironment, parent: Node | None)

Bases: Node

HAL node base class.

This class inherits from the systemrdl Node class. Each subclass will also inherit its systemrdl Node subclass specialization counterpart (e.g, HalFieldNode inherits from FieldNode).

digraph inheritance35bb04c66f { bgcolor=transparent; rankdir=TB; size="8.0, 12.0"; "AddressableNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Base-class for any kind of node that can have an address"]; "Node" -> "AddressableNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "AddrmapNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Represents an RDL ``addrmap``"]; "AddressableNode" -> "AddrmapNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FieldNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Represents an RDL ``field``"]; "VectorNode" -> "FieldNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalAddrmapNode" [URL="#peakrdl_halcpp.halnode.HalAddrmapNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HAL node wrapping a SystemRDL address map (:class:`~systemrdl.node.AddrmapNode`)."]; "HalBaseNode" -> "HalAddrmapNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "AddrmapNode" -> "HalAddrmapNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalBaseNode" [URL="#peakrdl_halcpp.halnode.HalBaseNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HAL node base class."]; "Node" -> "HalBaseNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalFieldNode" [URL="#peakrdl_halcpp.halnode.HalFieldNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HalFieldNode class inheriting from HalBaseNode class and systemrdl FieldNode class."]; "HalBaseNode" -> "HalFieldNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FieldNode" -> "HalFieldNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalMemNode" [URL="#peakrdl_halcpp.halnode.HalMemNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HAL node wrapping a SystemRDL memory (:class:`~systemrdl.node.MemNode`)."]; "HalBaseNode" -> "HalMemNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "MemNode" -> "HalMemNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalRegNode" [URL="#peakrdl_halcpp.halnode.HalRegNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HAL node wrapping a SystemRDL register (:class:`~systemrdl.node.RegNode`)."]; "HalBaseNode" -> "HalRegNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "RegNode" -> "HalRegNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HalRegfileNode" [URL="#peakrdl_halcpp.halnode.HalRegfileNode",color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",target="_top",tooltip="HAL node wrapping a SystemRDL register file (:class:`~systemrdl.node.RegfileNode`)."]; "HalBaseNode" -> "HalRegfileNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "RegfileNode" -> "HalRegfileNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "MemNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Represents an RDL ``mem``"]; "AddressableNode" -> "MemNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Node" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="The Node class is the base for all Node overlay classes."]; "RegNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Represents an RDL ``reg``"]; "AddressableNode" -> "RegNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "RegfileNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Represents an RDL ``regfile``"]; "AddressableNode" -> "RegfileNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; "VectorNode" [color="#6AB0DE",fillcolor="#E7F2FA",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="rounded, filled",tooltip="Base-class for any kind of node that is vector-like."]; "Node" -> "VectorNode" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Class methods:

• get_docstring()

• _halfactory()

• halunrolled()

• halchildren()

• haldescendants()

property inst_name_hal: str

Return the node name with the ‘_hal’ suffix.

property orig_type_name_hal: str

Return the original type name with the ‘_hal’ suffix.

property orig_type_name: str

Returns type_name if orig_type_name is none.

Node instantiate anonymously do not have orig_type_name so use type_name.

property is_bus: bool

Returns True if the HAL node is considered a bus (i.e., an addrmap containing only addrmaps).

Always returns False for non-addrmap nodes. Overridden in HalAddrmapNode.

get_docstring() → str

Converts the node description property into a C++ multi-line comment.

Returns:

A /* ... */ formatted comment containing the node’s desc property, or an empty string if no description is set.

Return type:

str

halunrolled() → Iterator[Node]

Yields one HAL node per array element, or yields the node itself if not an array.

Adapted from the systemrdl Node unrolling logic. For array nodes, each yielded node has its current_idx set to the corresponding index tuple.

halchildren(children_type: Node = <class 'systemrdl.node.Node'>, unroll: bool = False, skip_not_present: bool = True, skip_buses: bool = False, bus_offset: int = 0, unique_orig_type: bool = False, type_dict: dict | None = None) → Iterator[Node]

Yields HAL-wrapped children of this node, with optional filtering.

Wraps systemrdl Node.children so that each child is converted to the appropriate HAL subclass via _halfactory().

Parameters:

• children_type (Node, optional) – Only yield children that are instances of this type. Defaults to Node (all types).

• unroll (bool, optional) – If True, unroll array children into individual element nodes.

• skip_not_present (bool, optional) – If True (default), skip nodes whose ispresent property is False.

• skip_buses (bool, optional) – If True, transparent bus addrmaps (containing only addrmaps) are flattened and their children are yielded instead.

• bus_offset (int, optional) – Cumulative address offset inherited from skipped bus nodes.

• unique_orig_type (bool, optional) – If True, yield at most one child per unique orig_type_name.

• type_dict (dict, optional) – Dictionary used internally to track seen orig_type_name values and detect parameterised type conflicts. Pass None to start fresh.

haldescendants(descendants_type: Node = <class 'systemrdl.node.Node'>, unroll: bool = False, skip_not_present: bool = True, in_post_order: bool = False, skip_buses: bool = False, bus_offset: int = 0, unique_orig_type: bool = False, type_dict: dict | None = None) → Iterator[Node]

Yields all HAL-wrapped descendants of this node, with optional filtering.

Adapted from systemrdl Node.descendants. Recursively calls halchildren() to traverse the full subtree.

Parameters:

• descendants_type (Node, optional) – Only yield descendants that are instances of this type. Defaults to Node (all types).

• unroll (bool, optional) – If True, unroll array nodes into individual element nodes.

• skip_not_present (bool, optional) – If True (default), skip nodes whose ispresent property is False.

• in_post_order (bool, optional) – If True, yield children before their parent (post-order traversal). Defaults to pre-order.

• skip_buses (bool, optional) – If True, transparent bus addrmaps are flattened and their children are yielded instead.

• bus_offset (int, optional) – Cumulative address offset inherited from skipped bus nodes.

• unique_orig_type (bool, optional) – If True, yield at most one descendant per unique orig_type_name.

• type_dict (dict, optional) – Dictionary used internally to track seen orig_type_name values. Pass None to start fresh.

class peakrdl_halcpp.halnode.HalFieldNode(node: FieldNode)

Bases: HalBaseNode, FieldNode

HalFieldNode class inheriting from HalBaseNode class and systemrdl FieldNode class.

Class methods:

• get_enums()

__init__(node: FieldNode)

property address_offset: int

Always returns 0. Fields have no independent address; the offset is on the parent register.

property cpp_access_type: str

C++ access right template selection.

get_enums()

Returns the enumeration(s) of a FieldNode.

Inside an addrmap node, all enumerations must have a different name. The jinja template used to create the C++ header filters enumerations with already-existing names.

Returns:

(has_enum, enum_cls_name, enum_strings, enum_values, enum_desc, const_width) where has_enum is a bool indicating whether an encoding is defined. All other elements are None when has_enum is False.

Return type:

tuple

class peakrdl_halcpp.halnode.HalRegNode(node: RegNode)

Bases: HalBaseNode, RegNode

HAL node wrapping a SystemRDL register (RegNode).

Inherits from HalBaseNode and RegNode.

Class methods:

• get_template_line()

• get_cls_tmpl_params()

__init__(node: RegNode)

property cpp_access_type

C++ access right template selection.

property address_offset: int

Returns the address offset adjusted by the accumulated bus offset.

For array registers with no current index set, the offset of the first element is used.

property width: int

Returns the register width in bits, derived from the highest bit position of its fields.

get_template_line() → str

Returns the class template string.

get_cls_tmpl_params() → str

Returns the class template parameter string.

These parameters must match the the template returned by get_template_line().

class peakrdl_halcpp.halnode.HalRegfileNode(node: RegfileNode)

Bases: HalBaseNode, RegfileNode

HAL node wrapping a SystemRDL register file (RegfileNode).

Inherits from HalBaseNode and RegfileNode.

Class methods:

• get_template_line()

• get_cls_tmpl_params()

__init__(node: RegfileNode)

property cpp_access_type

C++ access right template selection.

For RegfileNodes, the access rights are selected at lower levels (e.g., registers).

property address_offset: int

Returns the address offset adjusted by the accumulated bus offset.

For array register files with no current index set, the offset of the first element is used.

get_template_line() → str

Returns the class template string.

get_cls_tmpl_params() → str

Returns the class template parameter string.

These parameters must match the the template returned by get_template_line().

class peakrdl_halcpp.halnode.HalMemNode(node: MemNode)

Bases: HalBaseNode, MemNode

HAL node wrapping a SystemRDL memory (MemNode).

Inherits from HalBaseNode and MemNode.

Class methods:

• get_template_line()

• get_cls_tmpl_params()

__init__(node: MemNode)

property address_offset: int

Returns the address offset adjusted by the accumulated bus offset.

get_template_line() → str

Returns the class template string.

get_cls_tmpl_params() → str

Returns the class template parameter string.

These parameters must match the the template returned by get_template_line().

class peakrdl_halcpp.halnode.HalAddrmapNode(node: AddrmapNode)

Bases: HalBaseNode, AddrmapNode

HAL node wrapping a SystemRDL address map (AddrmapNode).

Inherits from HalBaseNode and AddrmapNode.

Class methods:

• get_template_line()

• get_cls_tmpl_params()

__init__(node: AddrmapNode)

bus_offset

The bus offset is used for address offset correction when the –skip-buses option is used

property is_top_node: bool

Checks if this is the top node.

property address_offset: int

Returns the address offset adjusted by the accumulated bus offset.

property is_bus: bool

Returns True if this addrmap contains only other addrmaps (i.e., is a transparent bus).

property is_mem_addrmap: bool

Returns True if this addrmap contains only HalMemNode children.

get_template_line() → str

Returns the class template string.

get_cls_tmpl_params() → str

Returns the class template parameter string.

These parameters must match the the template returned by get_template_line().

peakrdl_halcpp.halutils module

class peakrdl_halcpp.halutils.HalUtils(ext_modules: List[str])

Bases: object

Utility helpers used by the jinja2 template during C++ header generation.

Class methods:

• get_include_file()

• has_extern()

• get_extern()

• generate_file_header()

__init__(ext_modules: List[str]) → None

Parameters:

ext_modules (List[str]) – List of addrmap instance names that have user-supplied *_hal_ext.h extension headers.

ext_modules

List of modules (i.e., SystemRDL addrmap objects) with extended functionalities.

get_include_file(halnode: HalAddrmapNode) → str

Returns the header filename to #include for a given HAL node.

If the node has an extension header, returns <name>_hal_ext.h; otherwise returns <name>_hal.h.

Parameters:

halnode (HalAddrmapNode) – The HAL addrmap node whose include filename is needed.

Returns:

Header filename (without path).

Return type:

str

has_extern(halnode: HalAddrmapNode) → bool

Returns True if the HAL node has a user-supplied extension header.

Parameters:

halnode (HalAddrmapNode) – The HAL addrmap node to check.

Returns:

True if halnode.inst_name appears in ext_modules.

Return type:

bool

get_extern(halnode: HalAddrmapNode) → str

Returns the C++ type name for the node, using the _ext variant when applicable.

If the node has an extension header, the _hal suffix of the original type name is replaced by _ext; otherwise the standard _hal name is returned.

Parameters:

halnode (HalAddrmapNode) – The HAL addrmap node.

Returns:

C++ type name string (<name>_ext or <name>_hal).

Return type:

str

generate_file_header() → str

Returns a one-line C++ comment used as the header of every generated file.

Returns:

A // Generated with ... comment string.

Return type:

str