Compiler

class systemrdl.RDLCompiler(**kwargs: Any)

RDLCompiler constructor.

Parameters

  • message_printer (MessagePrinter) – Override the default message printer

  • warning_flags (int) – Flags to enable warnings. See Warnings for more details.

  • error_flags (int) – Same as warning_flags but promote them to errors instead.

  • dedent_desc (bool) –

    Automatically remove any common indentation from multi-line desc properties.

    Set to True by default.

  • extended_dpa_type_names (bool) –

    Enable extended type name generation that accounts for dynamic property assignments augmenting the type.

    Set to True by default.

    See Extended Type Name Generation for more details.

  • perl_safe_opcodes (List[str]) –

    Perl preprocessor commands are executed within a Perl Safe compartment to prevent malicious code execution.

    The default set of Perl opcodes allowed should be sufficient for most applications, however this option is exposed in the rare case it is necessary to override the opcode list in order to make an exception.

    Default value:

    [
    ':base_core', ':base_mem', ':base_loop', ':base_orig', ':base_math',
    ':base_thread', ':filesys_read', ':sys_db', ':load',
    'sort', 'tied', 'pack', 'unpack', 'reset'
]

Changed in version 1.8: Added dedent_desc option.

Changed in version 1.9: Added extended_dpa_type_names option.

Changed in version 1.10: Added perl_safe_opcodes option.

compile_file(path: str, incl_search_paths: Optional[List[str]] = None, defines: Optional[Dict[str, str]] = None) → FileInfo

Parse & compile a single file and append it to RDLCompiler’s root namespace.

If any exceptions (RDLCompileError or other) occur during compilation, then the RDLCompiler object should be discarded.

Parameters

  • path (str) – Path to an RDL source file

  • incl_search_paths (List[str]) –

    List of additional paths to search to resolve includes. If unset, defaults to an empty list.

    Relative include paths are resolved in the following order:

    1. Search each path specified in incl_search_paths.

    2. Path relative to the source file performing the include.

  • defines (Dict[str, str]) – Dictionary of pre-defined verilog macros where the key is the macro name, and the value is the macro text.

Raises

RDLCompileError – If any fatal compile error is encountered.

Returns

File info object

Return type

FileInfo

Changed in version 1.20: Returns a FileInfo object instead of None

elaborate(top_def_name: Optional[str] = None, inst_name: Optional[str] = None, parameters: Optional[Dict[str, RDLValue]] = None) → RootNode

Elaborates the design for the given top-level addrmap component.

During elaboration, the following occurs:

  • An instance of the $root meta-component is created.

  • The addrmap component specified by top_def_name is instantiated as a child of $root.

  • Expressions, parameters, and inferred address/field placements are elaborated.

  • Validation checks are performed.

If a design contains multiple root-level addrmaps, elaborate() can be called multiple times in order to elaborate each individually.

If any exceptions (RDLCompileError or other) occur during elaboration, then the RDLCompiler object should be discarded.

Parameters

  • top_def_name (str) –

    Explicitly choose which addrmap in the root namespace will be the top-level component.

    If unset, The last addrmap defined will be chosen.

  • inst_name (str) – Overrides the top-component’s instantiated name. By default, instantiated name is the same as top_def_name

  • parameters (dict) – Dictionary of parameter overrides for the top component instance.

Raises

RDLCompileError – If any fatal elaboration error is encountered

Returns

Elaborated root meta-component’s Node object.

Return type

RootNode

eval(expression: str) → RDLValue

Evaluate an RDL expression string and return its compiled value. This function is provided as a helper to simplify overriding top-level parameters during elaboration.

Parameters

expression (str) – This string is parsed and evaluated as a SystemRDL expression. Any references used in the expression are resolved using the current contents of the root namespace.

Raises

ValueError – If any parse or evaluation error occurs.

New in version 1.8.

list_udps() → List[str]

List all user-defined properties encountered by the compiler.

New in version 1.12.

msg

Reference to the compiler’s MessageHandler object

Warning

This will be deprecated in a future release. See this page for more details: https://github.com/SystemRDL/systemrdl-compiler/issues/168

preprocess_file(path: str, incl_search_paths: Optional[List[str]] = None, defines: Optional[Dict[str, str]] = None) → FileInfo

Preprocess a single file without compiling it.

Parameters

  • path (str) – Path to an RDL source file

  • incl_search_paths (List[str]) –

    List of additional paths to search to resolve includes. If unset, defaults to an empty list.

    Relative include paths are resolved in the following order:

    1. Search each path specified in incl_search_paths.

    2. Path relative to the source file performing the include.

  • defines (Dict[str, str]) – Dictionary of pre-defined verilog macros where the key is the macro name, and the value is the macro text.

Raises

RDLCompileError – If any fatal preprocessing error is encountered.

Returns

File info object

Return type

FileInfo

New in version 1.20.

register_udp(definition_cls: Type[UDPDefinition], soft: bool = True) → None

Pre-register a User Defined Property into the compiler.

Parameters

  • definition_cls (systemrdl.udp.UDPDefinition) – Reference to the container class that defines your new UDP.

  • soft (bool) – Override to False to register the UDP as a hard definition.

New in version 1.25.

class systemrdl.compiler.FileInfo(preprocessed_text: str, included_files: Iterable[str])
property included_files: Iterable[str]

Iterable of paths that were included while preprocessing this file.

property preprocessed_text: str

Resolved text after Perl and Verilog preprocessing