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: RegisterMode, description: str)

Bases: object

Used to represent a register and its fields.

__init__(name: str, index: int, mode: RegisterMode, 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 mode that decides the behavior of this register. See https://hdl-registers.com/rst/basic_feature/basic_feature_register_modes.html for more information about the different modes.

  • 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, numerical_interpretation: NumericalInterpretation | None = None) → 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.

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.

Note that every register array must have at least one register added to it via the append_register() method. Empty register arrays will result in errors.

__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: RegisterMode, description: str) → Register

Append a register to this array.

Parameters:
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: RegisterMode, 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(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:

  • register_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.

hdl_registers.register_mode module

class hdl_registers.register_mode.HardwareAccessDirection(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The possible directions hardware can provide/read register values.

DOWN = 2
UP = 1
class hdl_registers.register_mode.RegisterMode(shorthand: str, name: str, description: str, software_can_read: bool, software_can_write: bool, hardware_has_up: bool)

Bases: object

Represents a mode of a register, which defines how the register can be accessed. The terms “software”/”hardware”, along with “register bus”, “register file”, “read”, “write, “up” and “down” are used in this class. These terms are explained by the following diagram:

 ________________________________
|           "Software"           |
| E.g. CPU, PCIe interface, etc. |
|________________________________|
                ||
                ||         "Register bus"
                ||         E.g. AXI-Lite.
                || "read" or "write" transactions.
                ||
      _______________________      "down"      ______________________________
     |    "Register file"    |--------------->|          "Hardware"          |
     | E.g. generic AXI-Lite |                |  Meaning, your application.  |
     |     register file.    |      "up"      | In e.g. FPGA fabric or ASIC. |
     |_______________________|<---------------|______________________________|
__init__(shorthand: str, name: str, description: str, software_can_read: bool, software_can_write: bool, hardware_has_up: bool)
Parameters:

  • shorthand – A short string that can be used to refer to this mode. E.g. “r”.

  • name – A short but human-readable readable representation of this mode. E.g. “Read”.

  • description – Textual description and explanation of this mode.

  • software_can_read –

    True if register is readable by software on the register bus. I.e. if software accessors shall have a ‘read’ method for registers of this mode. False otherwise.

    Analogous the reg_file.reg_file_pkg.is_read_type VHDL function.

  • software_can_write –

    True if register is writeable by software on the register bus. I.e. if software accessors shall have a ‘write’ method for registers of this mode. False otherwise.

    Analogous the reg_file.reg_file_pkg.is_write_type VHDL function.

  • hardware_has_up –

    True if register gets its software-read value from hardware. I.e. if register file shall have an ‘up’ input port for registers of this mode.

    False otherwise, which can be due to either

    • mode is not software-readable, or

    • mode loopbacks a software-written value to the software read value.

property hardware_has_down: bool

True if register provides a value from software to hardware. I.e. if register file shall have a ‘down’ output port for registers of this mode.

False otherwise, which is most likely due to the register being read-only.

is_hardware_accessible(direction: HardwareAccessDirection) → bool

Test if this mode is hardware-accessible in the given direction.

is_software_accessible(direction: SoftwareAccessDirection) → bool

Test if this mode is software-accessible in the given direction.

class hdl_registers.register_mode.SoftwareAccessDirection(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The possible directions software can access registers.

READ = _SoftwareAccessDirection(name_past='read', name_adjective='readable')
WRITE = _SoftwareAccessDirection(name_past='written', name_adjective='writeable')

hdl_registers.register_modes module