hdl_registers package

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

Subpackages

• hdl_registers.constant package
  • Submodules
  • hdl_registers.constant.bit_vector_constant module
    • BitVectorConstant
      • BitVectorConstant.__init__()
      • BitVectorConstant.allowed_binary_characters
      • BitVectorConstant.allowed_hexadecimal_characters
      • BitVectorConstant.is_hexadecimal_not_binary
      • BitVectorConstant.prefix
      • BitVectorConstant.separator_character
      • BitVectorConstant.value
      • BitVectorConstant.value_without_separator
      • BitVectorConstant.width
    • UnsignedVector
    • UnsignedVectorConstant
  • hdl_registers.constant.boolean_constant module
    • BooleanConstant
      • BooleanConstant.__init__()
      • BooleanConstant.value
  • hdl_registers.constant.constant module
    • Constant
      • Constant.description
      • Constant.name
      • Constant.value
  • hdl_registers.constant.float_constant module
    • FloatConstant
      • FloatConstant.__init__()
      • FloatConstant.value
  • hdl_registers.constant.integer_constant module
    • IntegerConstant
      • IntegerConstant.__init__()
      • IntegerConstant.value
  • hdl_registers.constant.string_constant module
    • StringConstant
      • StringConstant.__init__()
      • StringConstant.value
• hdl_registers.field package
  • Submodules
  • hdl_registers.field.bit module
    • Bit
      • Bit.__init__()
      • Bit.base_index
      • Bit.default_value
      • Bit.default_value_str
      • Bit.default_value_uint
      • Bit.width
  • hdl_registers.field.bit_vector module
    • BitVector
      • BitVector.__init__()
      • BitVector.base_index
      • BitVector.default_value
      • BitVector.default_value_str
      • BitVector.default_value_uint
      • BitVector.field_type
      • BitVector.width
  • hdl_registers.field.enumeration module
    • Enumeration
      • Enumeration.__init__()
      • Enumeration.base_index
      • Enumeration.default_value
      • Enumeration.default_value_str
      • Enumeration.default_value_uint
      • Enumeration.elements
      • Enumeration.get_element_by_name()
      • Enumeration.get_element_by_value()
      • Enumeration.get_value()
      • Enumeration.set_default_value()
      • Enumeration.set_value()
      • Enumeration.width
    • EnumerationElement
      • EnumerationElement.__init__()
      • EnumerationElement.name
      • EnumerationElement.value
  • hdl_registers.field.integer module
    • Integer
      • Integer.__init__()
      • Integer.base_index
      • Integer.default_value
      • Integer.default_value_str
      • Integer.default_value_uint
      • Integer.field_type
      • Integer.get_value()
      • Integer.is_signed
      • Integer.max_value
      • Integer.min_value
      • Integer.set_value()
      • Integer.width
  • hdl_registers.field.register_field module
    • RegisterField
      • RegisterField.base_index
      • RegisterField.default_value
      • RegisterField.default_value_str
      • RegisterField.default_value_uint
      • RegisterField.description
      • RegisterField.field_type
      • RegisterField.get_value()
      • RegisterField.max_binary_value
      • RegisterField.name
      • RegisterField.range_str
      • RegisterField.set_value()
      • RegisterField.width
  • hdl_registers.field.register_field_type module
    • FieldType
      • FieldType.convert_from_unsigned_binary()
      • FieldType.convert_to_unsigned_binary()
      • FieldType.max_value()
      • FieldType.min_value()
    • Fixed
      • Fixed.__init__()
      • Fixed.convert_from_unsigned_binary()
      • Fixed.convert_to_unsigned_binary()
      • Fixed.max_value()
      • Fixed.min_value()
    • Signed
      • Signed.convert_from_unsigned_binary()
      • Signed.convert_to_unsigned_binary()
      • Signed.max_value()
      • Signed.min_value()
    • SignedFixedPoint
      • SignedFixedPoint.__init__()
      • SignedFixedPoint.from_bit_widths()
    • Unsigned
      • Unsigned.convert_from_unsigned_binary()
      • Unsigned.convert_to_unsigned_binary()
      • Unsigned.max_value()
      • Unsigned.min_value()
    • UnsignedFixedPoint
      • UnsignedFixedPoint.__init__()
      • UnsignedFixedPoint.from_bit_widths()
• hdl_registers.generator package
  • Subpackages
    • hdl_registers.generator.c package
      • Submodules
      • hdl_registers.generator.c.header module
      • hdl_registers.generator.c.reserved_keywords module
    • hdl_registers.generator.cpp package
      • Submodules
      • hdl_registers.generator.cpp.cpp_generator_common module
      • hdl_registers.generator.cpp.header module
      • hdl_registers.generator.cpp.implementation module
      • hdl_registers.generator.cpp.interface module
      • hdl_registers.generator.cpp.reserved_keywords module
    • hdl_registers.generator.html package
      • Submodules
      • hdl_registers.generator.html.constant_table module
      • hdl_registers.generator.html.html_generator_common module
      • hdl_registers.generator.html.html_translator module
      • hdl_registers.generator.html.page module
      • hdl_registers.generator.html.register_table module
      • hdl_registers.generator.html.reserved_keywords module
    • hdl_registers.generator.python package
      • Submodules
      • hdl_registers.generator.python.pickle module
      • hdl_registers.generator.python.reserved_keywords module
    • hdl_registers.generator.vhdl package
      • Subpackages
      • Submodules
      • hdl_registers.generator.vhdl.record_package module
      • hdl_registers.generator.vhdl.register_package module
      • hdl_registers.generator.vhdl.reserved_keywords module
      • hdl_registers.generator.vhdl.vhdl_generator_common module
  • Submodules
  • hdl_registers.generator.register_code_generator module
    • RegisterCodeGenerator
      • RegisterCodeGenerator.COMMENT_END
      • RegisterCodeGenerator.COMMENT_START
      • RegisterCodeGenerator.DEFAULT_INDENTATION_LEVEL
      • RegisterCodeGenerator.SHORT_DESCRIPTION
      • RegisterCodeGenerator.__init__()
      • RegisterCodeGenerator.create()
      • RegisterCodeGenerator.create_if_needed()
      • RegisterCodeGenerator.generated_source_info
      • RegisterCodeGenerator.get_code()
      • RegisterCodeGenerator.header
      • RegisterCodeGenerator.output_file
      • RegisterCodeGenerator.should_create
  • hdl_registers.generator.register_code_generator_helpers module
    • RegisterCodeGeneratorHelpers
      • RegisterCodeGeneratorHelpers.COMMENT_END
      • RegisterCodeGeneratorHelpers.COMMENT_START
      • RegisterCodeGeneratorHelpers.DEFAULT_INDENTATION_LEVEL
      • RegisterCodeGeneratorHelpers.comment()
      • RegisterCodeGeneratorHelpers.comment_block()
      • RegisterCodeGeneratorHelpers.field_description()
      • RegisterCodeGeneratorHelpers.field_setter_should_read_modify_write()
      • RegisterCodeGeneratorHelpers.get_indentation()
      • RegisterCodeGeneratorHelpers.get_separator_line()
      • RegisterCodeGeneratorHelpers.iterate_constants()
      • RegisterCodeGeneratorHelpers.iterate_plain_registers()
      • RegisterCodeGeneratorHelpers.iterate_register_arrays()
      • RegisterCodeGeneratorHelpers.iterate_register_objects()
      • RegisterCodeGeneratorHelpers.iterate_registers()
      • RegisterCodeGeneratorHelpers.name
      • RegisterCodeGeneratorHelpers.qualified_field_name()
      • RegisterCodeGeneratorHelpers.qualified_register_array_name()
      • RegisterCodeGeneratorHelpers.qualified_register_name()
      • RegisterCodeGeneratorHelpers.register_description()
      • RegisterCodeGeneratorHelpers.register_list
      • RegisterCodeGeneratorHelpers.to_pascal_case()
  • hdl_registers.generator.reserved_keywords module
• hdl_registers.parser package
  • Submodules
  • hdl_registers.parser.json module
    • from_json()
  • hdl_registers.parser.parser module
    • RegisterParser
      • RegisterParser.__init__()
      • RegisterParser.parse()
      • RegisterParser.recognized_bit_items
      • RegisterParser.recognized_bit_vector_items
      • RegisterParser.recognized_constant_items
      • RegisterParser.recognized_enumeration_items
      • RegisterParser.recognized_integer_items
      • RegisterParser.recognized_register_array_items
      • RegisterParser.recognized_register_items
      • RegisterParser.required_bit_items
      • RegisterParser.required_bit_vector_items
      • RegisterParser.required_constant_items
      • RegisterParser.required_enumeration_items
      • RegisterParser.required_integer_items
      • RegisterParser.required_register_array_items
  • hdl_registers.parser.toml module
    • from_toml()
  • hdl_registers.parser.yaml module
    • from_yaml()

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:

• name – The name of the register.

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

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

Get a register from this list. Will only find plain registers, not registers in a register array. Will raise exception if no register matches.

Parameters:

name – The name of the register.

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.