hdl_registers package

An open-source HDL register interface code generator fast enough to run in real time

Subpackages

Submodules

hdl_registers.about module

hdl_registers.about.get_readme_rst(include_extra_for_github: bool = False, include_extra_for_website: bool = False, include_extra_for_pypi: bool = False) str

Get the complete README.rst (to be used on website and in PyPI release). RST file inclusion in README.rst does not work on GitHub unfortunately, hence this cumbersome handling where the README is duplicated in two places.

The arguments control some extra text that is included. This is mainly links to the other places where you can find information on the project (website, GitHub, PyPI).

Parameters:
  • include_extra_for_github (bool) – Include the extra text that shall be included in the GitHub README.

  • include_extra_for_website (bool) – Include the extra text that shall be included in the website main page.

  • include_extra_for_pypi (bool) – Include the extra text that shall be included in the PyPI release README.

hdl_registers.about.get_short_slogan() str

Short slogan used e.g. on pypi.org. Note that there seems to be an upper limit of 98 characters when rendering the slogan on pypi.org.

Note that this slogan should be the same as the one used in the readme and on the website below. The difference is capitalization and whether the project name is included.

hdl_registers.conftest module

hdl_registers.register module

class hdl_registers.register.Register(name: str, index: int, mode: str, description: str)

Bases: object

Used to represent a register and its fields.

__init__(name: str, index: int, mode: str, description: str)
Parameters:
  • name – The name of the register.

  • index – The zero-based index of this register. If this register is part of a register array, the index shall be relative to the start of the array. I.e. the index is zero for the first register in the array. If the register is a plain register, the index shall be relative to the start of the register list.

  • mode – A valid register mode. Should be a key in the REGISTER_MODES dictionary. I.e. the shorthand name for the mode, e.g. "r_w". See https://hdl-registers.com/rst/basic_feature/basic_feature_register_modes.html for more information.

  • description – Textual register description.

property address: int

Byte address, within the register list, of this register.

append_bit(name: str, description: str, default_value: str) Bit

Append a bit field to this register.

See Bit for documentation of the arguments.

Returns:

The bit field object that was created.

append_bit_vector(name: str, description: str, width: int, default_value: str, field_type: FieldType = Unsigned) BitVector

Append a bit vector field to this register.

See BitVector for documentation of the arguments.

Returns:

The bit vector field object that was created.

append_enumeration(name: str, description: str, elements: dict[str, str], default_value: str) Enumeration

Append an enumeration field to this register.

See Enumeration for documentation of the arguments.

Returns:

The enumeration field object that was created.

append_integer(name: str, description: str, min_value: int, max_value: int, default_value: int) Integer

Append an integer field to this register.

See Integer for documentation of the arguments.

Returns:

The integer field object that was created.

property default_value: int

The default value of this register as an unsigned integer. Depends on the default values of the fields in this register.

get_field(name: str) RegisterField

Get the field within this register that has the given name. Will raise exception if no field matches.

Parameters:

name – The name of the field.

Returns:

The field.

property is_bus_readable: bool

True if the register is readable by bus. Based on the register mode. Analogous the reg_file.reg_file_pkg.is_read_type VHDL function.

property is_bus_writeable: bool

True if the register is writeable by bus. Based on the register mode. Analogous the reg_file.reg_file_pkg.is_write_type VHDL function.

class hdl_registers.register.RegisterMode(mode_readable: str, description: str)

Bases: object

__init__(mode_readable: str, description: str)
Parameters:
  • mode_readable – The readable representation of this mode. E.g. “r” -> “Read”.

  • description – Textual description of mode.

hdl_registers.register_array module

class hdl_registers.register_array.RegisterArray(name: str, base_index: int, length: int, description: str)

Bases: object

Represent an array of registers. That is, a sequence of registers that shall be repeated a number of times in a RegisterList.

__init__(name: str, base_index: int, length: int, description: str)
Parameters:
  • name – The name of this register array.

  • base_index – The zero-based index of the first register of this array in the register list.

  • length – The number of times the register sequence shall be repeated.

  • description – Textual register array description.

append_register(name: str, mode: str, description: str) Register

Append a register to this array.

Parameters:
  • name – The name of the register.

  • mode – A valid register mode.

  • description – Textual register description.

Returns:

The register object that was created.

get_register(name: str) Register

Get a register from this array. Will raise exception if no register matches.

Parameters:

name – The name of the register.

Returns:

The register.

get_start_index(array_index: int) int

The index within the register list where array iteration number array_index starts.

Parameters:

array_index – The array iteration index. Must be less than the array length.

property index: int

Property exists to be used analogously with Register.index.

Returns:

The highest index occupied by this array.

hdl_registers.register_list module

class hdl_registers.register_list.RegisterList(name: str, source_definition_file: Path | None = None)

Bases: object

Used to handle the registers of a module. Also known as a register map.

__init__(name: str, source_definition_file: Path | None = None)
Parameters:
  • name – The name of this register list. Typically the name of the module that uses it.

  • source_definition_file

    The source file that defined this register list. Will be displayed in generated source code and documentation for traceability.

    Can be set to None if this information does not make sense in the current use case.

add_constant(name: str, value: bool | float | int | str | UnsignedVector, description: str) Constant

Add a constant. Will be available in the generated packages and headers. Will automatically determine the type of the constant based on the type of the value argument.

Parameters:
  • name – The name of the constant.

  • value – The constant value.

  • description – Textual description for the constant.

Returns:

The constant object that was created.

append_register(name: str, mode: str, description: str) Register

Append a register to this register list.

Parameters:
Returns:

The register object that was created.

append_register_array(name: str, length: int, description: str) RegisterArray

Append a register array to this list.

Parameters:
  • name – The name of the register array.

  • length – The number of times the register sequence shall be repeated.

  • description – Textual description of the register array.

Returns:

The register array object that was created.

classmethod from_default_registers(name: str, source_definition_file: Path, default_registers: list[Register]) RegisterList

Factory method. Create a RegisterList object from a plain list of registers.

Parameters:
  • name – The name of this register list.

  • source_definition_file

    The source file that defined this register list. Will be displayed in generated source code and documentation for traceability.

    Can be set to None if this information does not make sense in the current use case.

  • default_registers – These registers will be inserted at the beginning of the register list.

get_constant(name: str) Constant

Get a constant from this list. Will raise exception if no constant matches.

Parameters:

name – The name of the constant.

Returns:

The constant.

get_register(name: str, register_array_name: str | None = None) Register

Get a register from this list. Will raise exception if no register matches.

If register_array_name is specified, this method will search for registers within that array. If it is not specified, the method will only search for plain registers (not registers in any arrays).

Parameters:
  • name – The name of the register.

  • register_array_name – If the register is within a register array, this is the name of the array.

Returns:

The register.

get_register_array(name: str) RegisterArray

Get a register array from this list. Will raise exception if no register array matches.

Parameters:

name – The name of the register array.

Returns:

The register array.

get_register_index(register_name: str, register_array_name: str | None = None, register_array_index: int | None = None) int

Get the zero-based index within the register list for the specified register.

Parameters:
  • register_name – The name of the register.

  • register_array_name – If the register is within a register array, the name of the array must be specified.

  • register_array_index – If the register is within a register array, the array iteration index must be specified.

Returns:

The index.

property object_hash: str

Get a hash of this object representation. SHA1 is the fastest method according to e.g. http://atodorov.org/blog/2013/02/05/performance-test-md5-sha1-sha256-sha512/ Result is a lowercase hexadecimal string.