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) –

    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) 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) –

    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.

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

define_udp(name, valid_type, valid_components=None, default=None)

Pre-define a user-defined property.

This is the equivalent to the following RDL:

property <name> {
    type = <valid_type>;
    component = <valid_components>;
    default = <default>
};
Parameters:
  • name (str) – Property name

  • valid_components (set) – Set of Component types the UDP can be bound to. If None, then UDP can be bound to all components.

  • valid_type (type) – Assignment type that this UDP will enforce

  • default – Default if a value is not specified when the UDP is bound to a component. Value must be compatible with valid_type

elaborate(top_def_name: Optional[str] = None, inst_name: Optional[str] = None, parameters: Optional[Dict[str, Union[int, bool, str, list, BuiltinEnum, UserEnum, UserStruct, Type[UserEnum], Node, PropertyReference]]] = 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) Union[int, bool, str, list, BuiltinEnum, UserEnum, UserStruct, Type[UserEnum], Node, PropertyReference]

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

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

Preprocess a single file without compiling it.

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

  • incl_search_paths (list) –

    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.

Raises:

RDLCompileError – If any fatal preprocessing error is encountered.

Returns:

File info object

Return type:

FileInfo

New in version 1.20.

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