hdl_registers package
An open-source HDL register 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
- hdl_registers.constant.constant module
- hdl_registers.constant.float_constant module
- hdl_registers.constant.integer_constant module
- hdl_registers.constant.string_constant module
- hdl_registers.field package
- Submodules
- hdl_registers.field.bit module
- hdl_registers.field.bit_vector module
- 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
- hdl_registers.field.integer module
- 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
- hdl_registers.generator package
- Subpackages
- 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.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.register_description()
RegisterCodeGeneratorHelpers.register_list
RegisterCodeGeneratorHelpers.to_pascal_case()
- hdl_registers.parser package
- Submodules
- hdl_registers.parser.json module
- 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
- hdl_registers.parser.toml module
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.
- 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.
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 register list.
- __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.
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 TOML source file that defined this register list. Will be displayed in generated source code and documentation for traceability. Can be left out when working directly with the Python API.
- 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 list.
- Parameters:
name – The name of the register.
mode – A valid register mode.
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 in 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 single 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.