hdl_registers package
A HDL register generator fast enough to be run in real time.
Submodules
hdl_registers.about module
- hdl_registers.about.get_readme_rst(include_extra_for_gitlab=False, include_extra_for_website=False, include_extra_for_pypi=False)
Get the complete README.rst (to be used on website and in PyPI release). RST file inclusion in README.rst does not work on gitlab 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, gitlab, PyPI).
- Parameters
include_extra_for_gitlab (bool) – Include the extra text that shall be included in the gitlab 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_slogan()
One-paragraph description of the project.
hdl_registers.bit module
- class hdl_registers.bit.Bit(name, index, description, default_value)
Bases:
RegisterFieldUsed to represent a bit field in a register.
- __init__(name, index, description, default_value)
- property base_index
The index within the register for the lowest bit of this Field.
- property default_value
Getter for default_value.
- property default_value_str
Return a formatted string of the default value. The way it shall appear in documentation.
- Returns
The default value.
- Return type
- property default_value_uint
Return a the default value as an unsigned int.
- Returns
The default value.
- Return type
- property range
Return the bits that this field occupies in a readable format. The way it shall appear in documentation.
- Returns
The bit range.
- Return type
- width = 1
hdl_registers.bit_vector module
- class hdl_registers.bit_vector.BitVector(name, base_index, description, width, default_value, field_type: FieldType = Unsigned)
Bases:
RegisterFieldUsed to represent a bit vector field in a register.
- __init__(name, base_index, description, width, default_value, field_type: FieldType = Unsigned)
- Parameters
name (str) – The name of the bit vector.
base_index (int) – The zero-based index within the register for the lowest bit of this bit vector.
description (str) – Textual bit vector description.
width (int) – The width of the bit vector field.
default_value (str) – Default value as a string. Must be of length
widthand contain only “1” and “0”.field_type (FieldType) – The field type used to interpret the bits of the field.
- property base_index
The index within the register for the lowest bit of this Field.
- property default_value
Getter for default_value.
- property default_value_str
Return a formatted string of the default value. The way it shall appear in documentation.
- Returns
The default value.
- Return type
- property default_value_uint
Return a the default value as an unsigned int.
- Returns
The default value.
- Return type
- property field_type: FieldType
The field type (Unsigned, Signed, UnsignedFixedPoint, SignedFixedPoint…) used to interpret the bits of the field.
- Returns
The instanced FieldType subclass.
- Return type
- property range
Return the bits that this field occupies in a readable format. The way it shall appear in documentation.
- Returns
The bit range.
- Return type
hdl_registers.constant module
hdl_registers.html_translator module
- class hdl_registers.html_translator.HtmlTranslator
Bases:
objectTranslate a raw text with markdown/rst annotations into HTML code.
Supports:
Strong: double asterisks
Emphasis: single asterisks
Literal asterisks should be escaped: *
- translate(text)
Translate the text to have HTML tags where appropriate.
hdl_registers.parser module
- class hdl_registers.parser.RegisterParser(module_name, source_definition_file, default_registers)
Bases:
object- __init__(module_name, source_definition_file, default_registers)
- parse(register_data)
Parse the TOML data.
- Parameters
register_data (str) – TOML register data.
- Returns
The resulting register list.
- Return type
- recognized_bit_items = {'default_value', 'description'}
- recognized_bit_vector_items = {'default_value', 'description', 'width'}
- recognized_constant_items = {'description', 'value'}
- recognized_register_array_items = {'array_length', 'description', 'register'}
- recognized_register_items = {'bit', 'bit_vector', 'description', 'mode'}
- hdl_registers.parser.from_toml(module_name, toml_file, default_registers=None)
Parse a register TOML file.
- Parameters
module_name (str) – The name of the module that these registers belong to.
toml_file (pathlib.Path) – The TOML file path.
default_registers (list(Register)) – List of default registers.
- Returns
The resulting register list.
- Return type
- hdl_registers.parser.load_toml_file(toml_file)
hdl_registers.register module
- class hdl_registers.register.Register(name, index, mode, description)
Bases:
objectUsed to represent a register and its fields.
- __init__(name, index, mode, description)
- Parameters
name (str) – The name of the register.
index (int) – 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 (str) – A valid register mode.
description (str) – Textual register description.
- append_bit(name, description, default_value)
Append a bit field to this register.
- append_bit_vector(name, description, width, default_value, field_type: FieldType = Unsigned)
Append a bit vector field to this register.
- Parameters
name (str) – The name of the bit vector.
width (int) – The width of the bit vector.
description (str) – Description of the bit vector.
default_value (str) – Default value as a string. Must be of length
widthand contain only “1” and “0”.field_type (FieldType) – The field type used to interpret the bits of the field.
- Returns
The bit vector object that was created.
- Return type
- property default_value
The default value of the register. Depends on the default values of it’s fields.
- Returns
The default value.
- Return type
- get_field(name)
Get the field within this register that has the given name. Will raise exception if no field matches.
- Parameters
name (str) – The name of the field.
- Returns
The field.
- Return type
- property is_bus_readable
True if the register is readable by bus. Based on the register type.
- property is_bus_writeable
True if the register is writeable by bus. Based on the register type.
hdl_registers.register_array module
- class hdl_registers.register_array.RegisterArray(name, base_index, length, description)
Bases:
objectRepresent an array of registers. That is, a sequence of registers that shall be repeated a number of times in a register list.
- __init__(name, base_index, length, description)
- append_register(name, mode, description)
Append a register to this array.
- get_register(name)
Get a register from this array. Will raise exception if no register matches.
hdl_registers.register_c_generator module
- class hdl_registers.register_c_generator.RegisterCGenerator(module_name, generated_info)
Bases:
RegisterCodeGeneratorGenerate a C code header with register information.
There is no unit test of this class that checks the generated code. It is instead functionally tested in the file test_register_compilation.py. That test generates C code from an example register set, compiles it and performs some run-time assertions in a C program. That test is considered more meaningful and exhaustive than a unit test would be.
- __init__(module_name, generated_info)
hdl_registers.register_code_generator module
hdl_registers.register_cpp_generator module
- class hdl_registers.register_cpp_generator.CommonGenerator(module_name, generated_info)
Bases:
RegisterCodeGeneratorClass with common methods for generating C++ code. Do not use this directly, should use
RegisterCppGenerator:- __init__(module_name, generated_info)
- class hdl_registers.register_cpp_generator.HeaderGenerator(module_name, generated_info)
Bases:
CommonGeneratorClass to generate a C++ header. Do not use this directly, should use
RegisterCppGenerator:- get_header(register_objects)
Get a complete C++ class header for the implementation of all methods. See
RegisterCppGenerator.get_header()for more details.
- class hdl_registers.register_cpp_generator.ImplementationGenerator(module_name, generated_info)
Bases:
CommonGeneratorClass to generate a C++ implementation. Do not use this directly, should use
RegisterCppGenerator:- get_implementation(register_objects)
Get a complete C++ class implementation with all methods. See
RegisterCppGenerator.get_implementation()for more details.
- class hdl_registers.register_cpp_generator.InterfaceGenerator(module_name, generated_info)
Bases:
CommonGeneratorClass to generate a C++ interface header. Do not use this directly, should use
RegisterCppGenerator:- get_interface(register_objects, constants)
Get a complete C++ interface class header. See
RegisterCppGenerator.get_interface()for more details.
- class hdl_registers.register_cpp_generator.RegisterCppGenerator(module_name, generated_info)
Bases:
objectGenerate a C++ class with register definitions and methods.
There is only a very limited unit test of this class that checks the generated code. It is instead functionally tested in the file test_register_compilation.py. That test generates C++ code from an example register set, compiles it and performs some run-time assertions in a C++ program. That test is considered more meaningful and exhaustive than a unit test would be.
- __init__(module_name, generated_info)
- get_header(register_objects)
Get a complete C++ class header for the implementation of all methods.
- get_implementation(register_objects)
Get a complete C++ class implementation with all methods.
- get_interface(register_objects, constants)
Get a complete C++ interface class header with all constant values and the signatures of all methods.
hdl_registers.register_field module
- class hdl_registers.register_field.RegisterField
Bases:
ABCMeta class for all register fields (bits, bit vectors, integers, …). Lists a few methods that must be implemented.
- abstract property base_index
The index within the register for the lowest bit of this Field.
- Returns
The index.
- Return type
- abstract property default_value_str
Return a formatted string of the default value. The way it shall appear in documentation.
- Returns
The default value.
- Return type
- abstract property default_value_uint
Return a the default value as an unsigned int.
- Returns
The default value.
- Return type
- property field_type: FieldType
The field type (Unsigned, Signed, UnsignedFixedPoint, SignedFixedPoint…) used to interpret the bits of the field.
- Returns
The instanced FieldType subclass.
- Return type
- get_value(register_value: int) float
Get the value of this field, given the supplied register value. Child classes might implement sanity checks on the value.
- property max_binary_value: int
Get the maximum value, represented as a positive integer, that this field can hold given its width.
- Returns
The maximum value.
- Return type
- abstract property range
Return the bits that this field occupies in a readable format. The way it shall appear in documentation.
- Returns
The bit range.
- Return type
hdl_registers.register_field_type module
- class hdl_registers.register_field_type.FieldType
Bases:
ABC- abstract convert_from_unsigned_binary(bit_width: int, unsigned_binary: int)
Convert from the unsigned binary integer representation of a field, into the native Python value of the field.
- class hdl_registers.register_field_type.Fixed(is_signed: bool, max_bit_index: int, min_bit_index: int)
-
- __init__(is_signed: bool, max_bit_index: int, min_bit_index: int)
Abstract baseclass for Fixed field types.
The bit_index arguments indicates the position of the decimal point in relation to the number expressed by the field. The decimal point is between the “0” and “-1” bit index. If the bit_index argument is negative, then the number represented by the field will include a fractional portion.
- convert_from_unsigned_binary(bit_width: int, unsigned_binary: int) float
Convert from the unsigned binary integer representation of a field, into the native Python value of the field.
- class hdl_registers.register_field_type.Signed
Bases:
FieldTypeTwo’s complement signed integer format.
- convert_from_unsigned_binary(bit_width: int, unsigned_binary: int) int
Convert from the unsigned binary integer representation of a field, into the native Python value of the field.
- class hdl_registers.register_field_type.SignedFixedPoint(max_bit_index: int, min_bit_index: int)
Bases:
Fixed- __init__(max_bit_index: int, min_bit_index: int)
Signed fixed point format to represent fractional values. Signed integer uses two’s complement representation.
The bit_index arguments indicates the position of the decimal point in relation to the number expressed by the field. The decimal point is between the “0” and “-1” bit index. If the bit_index argument is negative, then the number represented by the field will include a fractional portion.
e.g. sfixed (4 downto -5) specifies signed fixed point, 10 bits wide, with 5 bits of decimal. Consequently y = -6.5 = “11001.10000”.
- classmethod from_bit_widths(integer_bit_width: int, fraction_bit_width: int) SignedFixedPoint
Create instance via the respective fixed point bit widths.
- class hdl_registers.register_field_type.Unsigned
Bases:
FieldTypeUnsigned integer.
- convert_from_unsigned_binary(bit_width: int, unsigned_binary: int) int
Convert from the unsigned binary integer representation of a field, into the native Python value of the field.
- class hdl_registers.register_field_type.UnsignedFixedPoint(max_bit_index: int, min_bit_index: int)
Bases:
Fixed- __init__(max_bit_index: int, min_bit_index: int)
Unsigned fixed point format to represent fractional values.
The bit_index arguments indicates the position of the decimal point in relation to the number expressed by the field. The decimal point is between the “0” and “-1” bit index. If the bit_index argument is negative, then the number represented by the field will include a fractional portion.
e.g. ufixed (4 downto -5) specifies unsigned fixed point, 10 bits wide, with 5 bits of decimal. Consequently y = 6.5 = “00110.10000”.
- classmethod from_bit_widths(integer_bit_width: int, fraction_bit_width: int) UnsignedFixedPoint
Create instance via the respective fixed point bit widths.
hdl_registers.register_html_generator module
- class hdl_registers.register_html_generator.RegisterHtmlGenerator(module_name, generated_info)
Bases:
objectGenerate a HTML page with register information.
- __init__(module_name, generated_info)
- get_constant_table(constants)
Get a HTML table with constant infomation. Can be included in other documents.
- get_page(register_objects, constants)
Get a complete HTML page with register and constant infomation.
- static get_page_style(table_style=None, font_style=None, extra_style='')
Get a CSS style for the register pages. Shall be saved to a file called
regs_style.css.- Returns
CSS code.
- Return type
hdl_registers.register_list module
- class hdl_registers.register_list.RegisterList(name, source_definition_file)
Bases:
objectUsed to handle the registers of a module. Also known as a register map.
- __init__(name, source_definition_file)
- Parameters
name (str) – The name of this register list. Typically the name of the module that uses it.
source_definition_file (pathlib.Path) – The TOML source file that defined this register list. Will be displayed in generated source code and documentation for traceability.
- add_constant(name, value, description=None)
Add a constant. Will be available in the generated packages and headers.
- append_register(name, mode, description)
Append a register to this list.
- append_register_array(name, length, description)
Append a register array to this list.
- Parameters
- Returns
The register array object that was created.
- Return type
- copy_source_definition(output_path)
Copy the source file that created this register list. If no source file is set, nothing will be copied.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_c_header(output_path, file_name=None)
Create a C header file with register and field definitions.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
file_name (str) – Optionally specify an explicit file name.
- create_cpp_header(output_path)
Create a C++ class header file.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_cpp_implementation(output_path)
Create a C++ class implementation file.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_cpp_interface(output_path)
Create a C++ class interface header file, with register and field definitions. The interface header contains only virtual methods.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_html_constant_table(output_path)
Create documentation HTML table with constant information.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_html_page(output_path)
Create a documentation HTML page with register and field information. Will include the tables created by
create_html_register_table()andcreate_html_constant_table().- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_html_register_table(output_path)
Create documentation HTML table with register and field information.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_python_class(output_path)
Save a python class with all register and constant information.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- create_vhdl_package(output_path)
Create a VHDL package file with register and field definitions.
This function assumes that the
output_pathfolder already exists. This assumption makes it slightly faster than the other functions that usecreate_file(). Necessary since this one is often used in real time (before simulations, etc..) and not in one-off scenarios like the others (when making a release).In order to save time, there is a mechanism to only generate the VHDL file when necessary. A hash of this register list object will be written to the file along with all the register definitions. This hash will be inspected and compared, and the VHDL file will only be generated again if something has changed.
- Parameters
output_path (pathlib.Path) – Result will be placed here.
- classmethod from_default_registers(name, source_definition_file, default_registers)
Factory method. Create a RegisterList object from a plain list of registers.
- Parameters
name (str) – The name of this register list.
source_definition_file (pathlib.Path) –
The source file that defined this register list. Will be displayed in generated source code and documentation for traceability.
Can be set to
Noneif this information does not make sense in the current use case.default_registers (list(Register)) – These registers will be inserted in the register list.
- static generated_info()
- generated_source_info()
- get_constant(name)
Get a constant from this list. Will raise exception if no constant matches.
- get_register(name)
Get a register from this list. Will only find single registers, not registers in a register array. Will raise exception if no register matches.
- get_register_array(name)
Get a register array from this list. Will raise exception if no register array matches.
- Parameters
name (str) – The name of the register array.
- Returns
The register array.
- Return type
- get_register_index(register_name, register_array_name=None, register_array_index=None)
Get the zero-based index within the register list for the specified register.
- Parameters
- Returns
The index.
- Return type
hdl_registers.register_python_generator module
- class hdl_registers.register_python_generator.RegisterPythonGenerator(module_name, generated_info)
Bases:
RegisterCodeGeneratorGenerate a Python class with register definitions.
- __init__(module_name, generated_info)
- create_class(register_list, output_folder)
Save register list object to binary file (pickle) and create a python class that recreates it.
- Parameters
register_list (RegisterList) – This register list object will be saved.
output_folder (pathlib.Path) – The pickle and python files will be saved here.
hdl_registers.register_vhdl_generator module
- class hdl_registers.register_vhdl_generator.RegisterVhdlGenerator(module_name, generated_info)
Bases:
RegisterCodeGeneratorGenerate a VHDL package with register information.
- __init__(module_name, generated_info)