hdl_registers.generator package

Subpackages

Submodules

hdl_registers.generator.register_code_generator module

class hdl_registers.generator.register_code_generator.RegisterCodeGenerator(register_list: RegisterList, output_folder: Path)

Bases: ABC

Abstract interface and common functions for generating register code.

COMMENT_END = ''

abstract property COMMENT_START: str

The character(s) that start a comment line in the programming language that we are generating code for.

Overload in subclass by setting e.g.

COMMENT_START = "#"

as a static class member at the top of the class.

DEFAULT_INDENTATION_LEVEL = 0

abstract property SHORT_DESCRIPTION: str

A short description of what this generator produces. Will be used when printing status messages.

Overload in subclass by setting e.g.

SHORT_DESCRIPTION = "C++ header"

as a static class member at the top of the class.

__init__(register_list: RegisterList, output_folder: Path)

Parameters:

register_list – Registers and constants from this register list will be included in the generated artifacts.
output_folder – Result file will be placed in this folder.

create(**kwargs: Any) → None

Generate the result artifact. I.e. create the output_file() containing the result from get_code() method.

Parameters:: kwargs – Further optional parameters that will be sent on to the get_code() method. See get_code() for details.

create_if_needed(**kwargs: Any) → bool

Generate the result file if needed. I.e. call create() if should_create() is True.

This method is recommended rather than create() in time-critical scenarios, such as before a user simulation run. The should_create() check is very fast (0.5 ms on a decent computer with a typical register list), while a typical register generator is quite slow by comparison. Hence it makes sense to run this method in order to save execution time. This increased speed gives a much nicer user experience.

Parameters:: kwargs – Further optional parameters that will be sent on to the get_code() method. See get_code() for details.
Returns:: True if artifacts where created, False otherwise.

property generated_source_info: list[str]: Return lines informing the user that the file is automatically generated, Containing info about the source of the generated register information.

abstract get_code(**kwargs: Any) → str

Get the generated code as a string.

Overload in a subclass where the code generation is implemented.

Parameters:: kwargs – Further optional parameters that can be used. Can send any number of named arguments, per the requirements of get_code() of any custom generators that inherit this class.

property header: str: Get file header informing the user that the file is automatically generated, The information from generated_source_info() formatted as a comment block.

abstract property output_file: Path

Result will be placed in this file.

Overload in a subclass to give the proper name to the code artifact. Probably using a combination of self.output_folder and self.name. For example:

@property
def output_file(self) -> Path:
    return self.output_folder / f"{self.name}_regs.html"

property should_create: bool

Indicates if a (re-)create of artifacts is needed. Will be True if any of these conditions are true:

File does not exist.
Generator version of artifact does not match current code version.
Artifact hash does not match RegisterList.object_hash() of the current register list. I.e. something has changed since the previous file was generated.

The version and hash checks above are dependent on the artifact file having a header as given by header().

hdl_registers.generator.register_code_generator_helpers module

class hdl_registers.generator.register_code_generator_helpers.RegisterCodeGeneratorHelpers

Bases: object

Various helper methods that make register code generation easier.

COMMENT_END: str

COMMENT_START: str

DEFAULT_INDENTATION_LEVEL: int

comment(comment: str, indent: int | None = None) → str: Create a one-line comment.

comment_block(text: str, indent: int | None = None) → str: Create a comment block from a string with newlines.

field_description(register: Register, field: RegisterField, register_array: RegisterArray | None = None) → str: Get a comment describing the field.

get_indentation(indent: int | None = None) → str: Get the requested indentation in spaces. Will use the default indentation for this generator if not specified.

get_separator_line(indent: int | None = None) → str: Get a separator line, e.g. # ---------------------------------.

iterate_constants() → Iterator[Constant]: Iterate of all constants in the register list.

iterate_plain_registers() → Iterator[Register]: Iterate over all plain registers (i.e. registers not in array) in the register list.

iterate_register_arrays() → Iterator[RegisterArray]: Iterate over all register arrays in the register list.

iterate_register_objects() → Iterator[Register | RegisterArray]: Iterate over all register objects in the register list. I.e. all plain registers and all register arrays.

iterate_registers() → Iterator[tuple[Register, RegisterArray | None]]

Iterate over all registers, plain or in array, in the register list.

Returns:: If the register is plain, the array return value in the tuple will be None. If the register is in an array, the array return value will conversely be non-None.

static register_description(register: Register, register_array: RegisterArray | None = None) → str: Get a comment describing the register.

register_list: RegisterList

static to_pascal_case(snake_string: str) → str

Converts e.g., “my_funny_string” to “MyFunnyString”.

Pascal case is like camel case but with the initial character being capitalized. I.e. how classes are named in Python, C and C++.