Python API

Python API#

PeakRDL Python can be used from a python API to generate the python package. This approach may be useful if multiple operations need to be sequenced for example:

  • A build process that has multiple files dependencies

  • A build process that needs other IP-XACT inputs

  • A build process that will use other tools form the PeakRDL Suite, for example:

    • building HTML documentation with PeakRDL HTML

    • building UVM using PeakRDL UVM

Example#

The following example shows the compiling an SystemRDL file and then generating the python register access layer using PeakRDL Python.

from peakrdl_python import compiler_with_udp_registers
from peakrdl_python.exporter import PythonExporter

# compile the systemRDL
rdlc = compiler_with_udp_registers()
rdlc.compile_file('basic.rdl')
spec = rdlc.elaborate(top_def_name='basic').top

# generate the python package register access layer
exporter = PythonExporter()
exporter.export(node=spec, path='generated_code')

PythonExporter#

The main exported class used to build the python register access layer:

class peakrdl_python.exporter.PythonExporter(**kwargs)#

PeakRDL Python Exporter class

Parameters:

  • user_template_dir (str) – Path to a directory where user-defined template overrides are stored.

  • user_template_context (dict) – Additional context variables to load into the template namespace.

__init__(**kwargs)#
export(node: RootNode | AddrmapNode, path: str, *, asyncoutput: bool = False, skip_test_case_generation: bool = False, delete_existing_package_content: bool = True, skip_library_copy: bool = False, legacy_block_access: bool = False, show_hidden: bool = False, user_defined_properties_to_include: list[str] | None = None, user_defined_properties_to_include_regex: str | None = None, hidden_inst_name_regex: str | None = None, legacy_enum_type: bool = False, skip_systemrdl_name_and_desc_properties: bool = False, skip_systemrdl_name_and_desc_in_docstring: bool = False, register_class_per_generated_file: int = 25, field_class_per_generated_file: int = 25, enum_field_class_per_generated_file: int = 50, memory_class_per_generated_file: int = 50, hashing_method: NodeHashingMethod = NodeHashingMethod.PYTHONHASH) → str#

Generated Python Code and Testbench

Parameters:

  • node – Top-level node to export. Can be the top-level RootNode or any internal AddrmapNode.

  • path – Output package path.

  • asyncoutput – If set this builds a register model with async callbacks

  • skip_test_case_generation – skip generation the generation of the test cases

  • delete_existing_package_content – delete any python files in the package location, normally left over from previous operations

  • skip_library_copy – skip copy the libraries to the generated package, this is useful to turn off when developing peakrdl python to avoid editing the wrong copy of the library. It also avoids the potential licensing implications of package distribution, However, this means the end-user is responsible for installing the libraries.

  • legacy_block_access – version 0.8 changed the block access methods from using arrays to lists. This allows memory widths of other than 8, 16, 32, 64 to be supported which are legal in systemRDL. The legacy mode with Arrays is still in the tool and will be turned on by default for a few releases.

  • show_hidden – By default any item (Address Map, Regfile, Register, Memory or Field) with the systemRDL User Defined Property (UDP) python_hide set to true will not be included in the generated python code. This behaviour can be overridden by setting this property to true.

  • user_defined_properties_to_include – A list of strings of the names of user-defined properties to include. Set to None for nothing to appear.

  • user_defined_properties_to_include_regex – A regex expression that defines whether user-defined properties will be included if they match. Set to None for it not to be used.

  • hidden_inst_name_regex – A regular expression which will hide any fully qualified instance name that matches, set to None to for this to have no effect

  • legacy_enum_type – version 1.2 introduced a new Enum type that allows system rdl name and desc properties on field encoding to be included. The legacy mode uses python IntEnum. .. version-deprecated:: 3.0

  • skip_systemrdl_name_and_desc_properties (bool) – version 1.2 introduced new properties that include the systemRDL name and desc as properties of the built python. Setting this option to True will exclude them.

  • skip_systemrdl_name_and_desc_in_docstring (bool) – version 2.0 introduced the option skip the systemRDL name and desc as properties of the built python. Including them help developers use the package and allows autogenerated document generation for the python module. However it also increases file sizes. Setting this option to True will exclude them.

  • register_class_per_generated_file – Number of register class definitions to put in each python module of the generated code. Make sure this is set to ensure the file does not get too big otherwise the generation and loading is slow.

  • field_class_per_generated_file – Number of register class definitions to put in each python module of the generated code. Make sure this is set to ensure the file does not get too big otherwise the generation and loading is slow.

  • enum_field_class_per_generated_file – Number of register class definitions to put in each python module of the generated code. Make sure this is set to ensure the file does not get too big otherwise the generation and loading is slow.

  • memory_class_per_generated_file – Number of memory class definitions to put in each python module of the generated code. Make sure this is set to ensure the file does not get too big otherwise the generation and loading is slow.

  • hashing_method – The algorithm used to generate the hash of nodes during the building process. The is intended for advanced users, please look at the documentation to understand this impact of this.

Return type:

modules that have been exported

Compiler Extensions#

PeakRDL Python uses two User Defined Properties to help the generation, there are definitions of these available to register with a the Compiler

class peakrdl_python.PythonHideUDP(env: RDLEnvironment)#

Definition of the class for the python_hide systemRDL property used by peakrdl-python

name: str = 'python_hide'#

User-defined property name

valid_components: Set[Type[Component]] = {<class 'systemrdl.component.Addrmap'>, <class 'systemrdl.component.Field'>, <class 'systemrdl.component.Mem'>, <class 'systemrdl.component.Reg'>, <class 'systemrdl.component.Regfile'>}#

Set of Component types the UDP can be bound to. By default, the UDP can be bound to all components.

valid_type#

alias of bool

class peakrdl_python.PythonInstNameUDP(env: RDLEnvironment)#

Definition of the class for the python_inst_name systemRDL property used by peakrdl-python

name: str = 'python_inst_name'#

User-defined property name

valid_components: Set[Type[Component]] = {<class 'systemrdl.component.Addrmap'>, <class 'systemrdl.component.Field'>, <class 'systemrdl.component.Mem'>, <class 'systemrdl.component.Reg'>, <class 'systemrdl.component.Regfile'>}#

Set of Component types the UDP can be bound to. By default, the UDP can be bound to all components.

valid_type#

alias of str

validate(node: Node, value: str) → None#

Optional user-defined validation function.

This function is called after design elaboration on every assignment of the user defined property. This provides a mechanism to further validate the value assigned to your user-defined property.

If the user-assigned value fails your validation test, be sure to flag it as an error as follows:

self.msg.error("My error message", self.get_src_ref(node))

The compiler factory function will generate an instance of the compiler with these registered

peakrdl_python.compiler_with_udp_registers(**kwargs: Any) → RDLCompiler#

Factory function to create an instance of the systemRDL compiler with the UDP registrations