tsfpga.registers package

Submodules

tsfpga.registers.bit module

class tsfpga.registers.bit.Bit(name, index, description, default_value)

Bases: tsfpga.registers.register_field.RegisterField

Used to represent a bit field in a register.

__init__(name, index, description, default_value)
Parameters
  • name (str) – The name of the bit array.

  • index (int) – The zero-based index of this bit array within the register.

  • description (str) – Textual bit array description.

  • default_value (str) – Default value. Either “1” or “0”.

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

str

property default_value_uint

Return a the default value as an unsigned int.

Returns

The default value.

Return type

int

get_value(register_value)

Get the value of this field, given the supplied register value. Child classes might implement sanity checks on the value.

Parameters

register_value (int) – Value of the register that this field belongs to.

Returns

The value.

Return type

int

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

str

width = 1

tsfpga.registers.bit_vector module

class tsfpga.registers.bit_vector.BitVector(name, base_index, description, width, default_value)

Bases: tsfpga.registers.register_field.RegisterField

Used to represent a bit vector field in a register.

__init__(name, base_index, description, width, default_value)
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 width and contain only “1” and “0”.

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

str

property default_value_uint

Return a the default value as an unsigned int.

Returns

The default value.

Return type

int

get_value(register_value)

Get the value of this field, given the supplied register value. Child classes might implement sanity checks on the value.

Parameters

register_value (int) – Value of the register that this field belongs to.

Returns

The value.

Return type

int

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

str

property width

Return the width, in number of bits, that this field occupies.

Returns

The width.

Return type

int

tsfpga.registers.constant module

class tsfpga.registers.constant.Constant(name, value, description=None)

Bases: object

__init__(name, value, description=None)
Parameters
  • name (str) – The name of the constant.

  • length (int) – The constant value (signed).

  • description (str) – Textual description for the constant.

tsfpga.registers.html_translator module

class tsfpga.registers.html_translator.HtmlTranslator

Bases: object

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

tsfpga.registers.parser module

class tsfpga.registers.parser.RegisterParser(module_name, source_definition_file, default_registers)

Bases: object

__init__(module_name, source_definition_file, default_registers)

Initialize self. See help(type(self)) for accurate signature.

parse(register_data)

Parse the TOML data.

Parameters

register_data (str) – TOML register data.

Returns

The resulting register list.

Return type

RegisterList

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'}
tsfpga.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

RegisterList

tsfpga.registers.parser.load_toml_file(toml_file)

tsfpga.registers.register module

class tsfpga.registers.register.Register(name, index, mode, description)

Bases: object

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

property address

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

Type

int

append_bit(name, description, default_value)

Append a bit field to this register.

Parameters
  • name (str) – The name of the bit.

  • description (str) – Description of the bit.

  • default_value (str) – Default value. Either “1” or “0”.

Returns

The bit object that was created.

Return type

Bit

append_bit_vector(name, description, width, default_value)

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 width and contain only “1” and “0”.

Returns

The bit vector object that was created.

Return type

BitVector

property default_value

The default value of the register. Depends on the default values of it’s fields.

Returns

The default value.

Return type

int

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

RegisterField

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.

class tsfpga.registers.register.RegisterMode(mode_readable, description)

Bases: object

__init__(mode_readable, description)

Initialize self. See help(type(self)) for accurate signature.

tsfpga.registers.register_array module

class tsfpga.registers.register_array.RegisterArray(name, base_index, length, description)

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, base_index, length, description)
Parameters
  • name (str) – The name of this register array.

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

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

  • description (str) – Textual register array description.

append_register(name, mode, description)

Append a register to this array.

Parameters
  • name (str) – The name of the register.

  • mode (str) – A valid register mode.

  • description (str) – Textual register description.

Returns

The register object that was created.

Return type

Register

get_register(name)

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

Parameters

name (str) – The name of the register.

Returns

The register.

Return type

Register

get_start_index(array_index)

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

Parameters

array_index (int) – The array iteration index. Shall be less than or equal to the array length.

property index

Property exists to be used analogously with Register.index.

Returns

The highest index occupied by this array.

Return type

int

tsfpga.registers.register_c_generator module

class tsfpga.registers.register_c_generator.RegisterCGenerator(module_name, generated_info)

Bases: tsfpga.registers.register_code_generator.RegisterCodeGenerator

Generate 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)

Initialize self. See help(type(self)) for accurate signature.

get_header(register_objects, constants)

tsfpga.registers.register_code_generator module

class tsfpga.registers.register_code_generator.RegisterCodeGenerator

Bases: object

Common functions for generating register code.

tsfpga.registers.register_cpp_generator module

class tsfpga.registers.register_cpp_generator.RegisterCppGenerator(module_name, generated_info)

Bases: tsfpga.registers.register_code_generator.RegisterCodeGenerator

Generate a C++ class with register definitions and methods.

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)

Initialize self. See help(type(self)) for accurate signature.

get_header(register_objects)
get_implementation(register_objects)
get_interface(register_objects, constants)

tsfpga.registers.register_field module

class tsfpga.registers.register_field.RegisterField

Bases: abc.ABC

Meta class for all register fields (bits, bit vectors, integers, …). Lists a few methods that must be implemented.

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

str

abstract property default_value_uint

Return a the default value as an unsigned int.

Returns

The default value.

Return type

int

abstract get_value(register_value)

Get the value of this field, given the supplied register value. Child classes might implement sanity checks on the value.

Parameters

register_value (int) – Value of the register that this field belongs to.

Returns

The value.

Return type

int

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

str

abstract property width

Return the width, in number of bits, that this field occupies.

Returns

The width.

Return type

int

tsfpga.registers.register_html_generator module

class tsfpga.registers.register_html_generator.RegisterHtmlGenerator(module_name, generated_info)

Bases: object

Generate a HTML page with register information.

__init__(module_name, generated_info)

Initialize self. See help(type(self)) for accurate signature.

get_constant_table(constants)

Get a HTML table with constant infomation. Can be included in other documents.

Returns

HTML code.

Return type

str

get_page(register_objects, constants)

Get a complete HTML page with register and constant infomation.

Returns

HTML code.

Return type

str

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

str

get_register_table(register_objects)

Get a HTML table with register infomation. Can be included in other documents.

Returns

HTML code.

Return type

str

tsfpga.registers.register_list module

class tsfpga.registers.register_list.RegisterList(name, source_definition_file)

Bases: object

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

Parameters
  • name (str) – The name of the constant.

  • length (int) – The constant value (signed).

  • description (str) – Textual description for the constant.

Returns

The constant object that was created.

Return type

Constant

append_register(name, mode, description)

Append a register to this list.

Parameters
  • name (str) – The name of the register.

  • mode (str) – A valid register mode.

  • description (str) – Textual register description.

Returns

The register object that was created.

Return type

Register

append_register_array(name, length, description)

Append a register array to this list.

Parameters
  • name (str) – The name of the register array.

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

Returns

The register array object that was created.

Return type

RegisterArray

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)

Create a C header file with register and field definitions.

Parameters

output_path (pathlib.Path) – Result will be placed here.

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() and create_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_path folder already exists. This assumption makes it slightly faster than the other functions that use create_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 None if 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()
Returns

Line(s) informing the user that a file is automatically generated.

Return type

list(str)

generated_source_info()
Returns

Line(s) informing the user that a file is automatically generated, containing info about the source of the generated register information.

Return type

list(str)

get_constant(name)

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

Parameters

name (str) – The name of the constant.

Returns

The constant.

Return type

Constant

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.

Parameters

name (str) – The name of the register.

Returns

The register.

Return type

Register

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

RegisterArray

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
  • register_name (str) – The name of the register.

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

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

Returns

The index.

Return type

int

tsfpga.registers.register_python_generator module

class tsfpga.registers.register_python_generator.RegisterPythonGenerator(module_name, generated_info)

Bases: tsfpga.registers.register_code_generator.RegisterCodeGenerator

Generate a Python class with register definitions.

__init__(module_name, generated_info)
Parameters
  • module_name (str) – The name of the register map.

  • generated_info (list(str)) – Will be placed in the file headers.

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.

tsfpga.registers.register_vhdl_generator module

class tsfpga.registers.register_vhdl_generator.RegisterVhdlGenerator(module_name, generated_info)

Bases: tsfpga.registers.register_code_generator.RegisterCodeGenerator

Generate a VHDL package with register information.

__init__(module_name, generated_info)

Initialize self. See help(type(self)) for accurate signature.

get_package(register_objects, constants)

Module contents