hdl_registers.field package

Submodules

hdl_registers.field.bit module

class hdl_registers.field.bit.Bit(name: str, index: int, description: str, default_value: str)

Bases: RegisterField

Used to represent a bit field in a register.

__init__(name: str, index: int, description: str, default_value: str)
Parameters:

  • name – The name of the bit.

  • index – The zero-based index of this bit within the register.

  • description – Textual bit description.

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

property base_index: int

The index within the register for the lowest bit of this field.

property default_value: str

Getter for private member.

property default_value_str: str

Return a formatted string of the default value. The way it shall appear in documentation.

property default_value_uint: int

Return a the default value as an unsigned int.

width = 1

hdl_registers.field.bit_vector module

class hdl_registers.field.bit_vector.BitVector(name: str, base_index: int, description: str, width: int, default_value: str, field_type: FieldType = Unsigned)

Bases: RegisterField

Used to represent a bit vector field in a register.

__init__(name: str, base_index: int, description: str, width: int, default_value: str, field_type: FieldType = Unsigned)
Parameters:

  • name – The name of the bit vector.

  • base_index – The zero-based index within the register for the lowest bit of this bit vector.

  • description – Textual bit vector description.

  • width – The width of the bit vector field.

  • default_value – Default value as a string. Must be of length width and contain only “1” and “0”.

  • field_type – The field type used to interpret the bits of the field.

property base_index: int

The index within the register for the lowest bit of this field.

property default_value: str

Getter for private member.

property default_value_str: str

Return a formatted string of the default value. The way it shall appear in documentation.

property default_value_uint: int

Return a the default value as an unsigned int.

property field_type: FieldType

The field type (Unsigned, Signed, UnsignedFixedPoint, SignedFixedPoint, …) used to interpret the bits of the field.

property width: int

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

hdl_registers.field.enumeration module

class hdl_registers.field.enumeration.Enumeration(name: str, base_index: int, description: str, elements: dict[str, str], default_value: str)

Bases: RegisterField

Used to represent an enumeration field in a register.

__init__(name: str, base_index: int, description: str, elements: dict[str, str], default_value: str)
Parameters:

  • name – The name of the register field.

  • base_index – The zero-based index within the register for the lowest bit of this field.

  • description – Textual field description.

  • elements – Dictionary mapping element names to their description.

  • default_value – The name of the element that shall be set as default.

property base_index: int

The index within the register for the lowest bit of this field.

property default_value: EnumerationElement

Getter for default_value.

property default_value_str: str

Return a formatted string of the default value. The way it shall appear in documentation.

property default_value_uint: int

Return a the default value as an unsigned int.

property elements: list[EnumerationElement]

Getter for elements.

get_element_by_name(name: str) → EnumerationElement

Get an enumeration element by name.

Parameters:

name – The name of the element.

Returns:

The enumeration element with the provided name.

get_element_by_value(value: int) → EnumerationElement

Get an enumeration element by value.

Parameters:

value – The value of the element.

Returns:

The enumeration element with the provided value.

get_value(register_value: int) → EnumerationElement

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

Parameters:

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

Returns:

The value of the field. If the field has a non-zero number of fractional bits, the type of the result will be a float. Otherwise it will be an int.

Note that a subclass might have a different type for the resulting value. Subclasses should call this super method and convert the numeric value to whatever type is applicable for that field.

set_default_value(value: str) → None

Set the default value for this enumeration field.

Parameters:

value – The name of the enumeration element that shall be set as default.

set_value(field_value: EnumerationElement) → int

Convert the supplied value into the bit-shifted unsigned integer ready to be written to the register. The bits of the other fields in the register are masked out and will be set to zero.

Parameters:

field_value –

Desired value to set the field to. If the field has a non-zero number of fractional bits, the type of the value is expected to be a float. Otherwise it should be an int.

Note that a subclass might have a different type for this argument. Subclasses should convert their argument value to an integer/float and call this super method.

Returns:

The register value as an unsigned integer.

property width: int

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

class hdl_registers.field.enumeration.EnumerationElement(name: str, value: int, description: str)

Bases: object

Represent a single element, also known as a “member”/”enumerator”/”option”/”choice”, within an enumeration type.

Optionally we could use a python dataclass: https://docs.python.org/3/library/dataclasses.html Would get the __repr__ method for free, but also a lot of other stuff that we do not need. Requires Python 3.7+ which should not be a problem though since 3.6 is end of life.

We could also use Python enum class: https://docs.python.org/3/library/enum.html Which would be a whole other concept.

It is deemed more flexible to use a simple class for now.

__init__(name: str, value: int, description: str)
property name: str

Getter for name. This member is read-only, since changing the name of an element poses some risks for the functionality of the enumeration field:

  • Could cause name collisions with other elements.

  • Could invalidate the currently selected default value of the field.

property value: int

Getter for value. This member is read-only, since changing the value of an element poses the risk of value collisions with other elements in the enumeration field.

hdl_registers.field.integer module

class hdl_registers.field.integer.Integer(name: str, base_index: int, description: str, min_value: int, max_value: int, default_value: int)

Bases: RegisterField

Used to represent an integer field in a register.

__init__(name: str, base_index: int, description: str, min_value: int, max_value: int, default_value: int)
Parameters:

  • name – The name of the field.

  • base_index – The zero-based index within the register for the lowest bit of this field.

  • description – Textual field description.

  • min_value – The minimum value that this field shall be able to represent.

  • min_value – The maximum value that this field shall be able to represent.

  • default_value – Default value. Must be within the specified range.

property base_index: int

The index within the register for the lowest bit of this field.

property default_value: int

Getter for private member.

property default_value_str: str

Return a formatted string of the default value. The way it shall appear in documentation.

property default_value_uint: int

Return a the default value as an unsigned int.

property field_type: FieldType

Getter for private member.

get_value(register_value: int) → int

See super method for details. Adds sanity checks of the value.

property is_signed: bool

Returns True if the field can hold negative numbers.

property max_value: int

Getter for private member.

property min_value: int

Getter for private member.

set_value(field_value: int) → int

See super method for details. Adds sanity checks of the value.

property width: int

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

hdl_registers.field.register_field module

class hdl_registers.field.register_field.RegisterField

Bases: ABC

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

abstract property base_index: int

The index within the register for the lowest bit of this field.

default_value: str | int
abstract property default_value_str: str

Return a formatted string of the default value. The way it shall appear in documentation.

abstract property default_value_uint: int

Return a the default value as an unsigned int.

description: str
property field_type: FieldType

The field type (Unsigned, Signed, UnsignedFixedPoint, SignedFixedPoint, …) used to interpret the bits of the field.

get_value(register_value: int) → int | float

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

Parameters:

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

Returns:

The value of the field. If the field has a non-zero number of fractional bits, the type of the result will be a float. Otherwise it will be an int.

Note that a subclass might have a different type for the resulting value. Subclasses should call this super method and convert the numeric value to whatever type is applicable for that field.

property max_binary_value: int

Get the maximum value, represented as a positive integer, that this field can hold given its width.

name: str
property range_str: str

Return the bits that this field occupies in a readable format. The way it shall appear in documentation.

set_value(field_value: int | float) → int

Convert the supplied value into the bit-shifted unsigned integer ready to be written to the register. The bits of the other fields in the register are masked out and will be set to zero.

Parameters:

field_value –

Desired value to set the field to. If the field has a non-zero number of fractional bits, the type of the value is expected to be a float. Otherwise it should be an int.

Note that a subclass might have a different type for this argument. Subclasses should convert their argument value to an integer/float and call this super method.

Returns:

The register value as an unsigned integer.

abstract property width: int

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

hdl_registers.field.register_field_type module

class hdl_registers.field.register_field_type.FieldType

Bases: ABC

abstract convert_from_unsigned_binary(bit_width: int, unsigned_binary: int) → int | float

Convert from the unsigned binary integer representation of a field, into the native Python value of the field.

Parameters:

  • bit_width – Width of the field.

  • unsigned_binary – Unsigned binary integer representation of the field.

abstract convert_to_unsigned_binary(bit_width: int, value: int | float) → int

Convert from the native Python value of the field, into the unsigned binary integer representation which can be written to a register.

Parameters:

  • bit_width – Width of the field.

  • value – Native Python representation of the field value.

Returns:

Unsigned binary integer representation of the field.

abstract max_value(bit_width: int) → int | float

Maximum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

abstract min_value(bit_width: int) → int | float

Minimum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

class hdl_registers.field.register_field_type.Fixed(is_signed: bool, max_bit_index: int, min_bit_index: int)

Bases: FieldType, ABC

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

Parameters:

  • is_signed – Is the field signed (two’s complement)?

  • max_bit_index – Position of the upper bit relative to the decimal point.

  • min_bit_index – Position of the lower bit relative to the decimal point.

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.

Parameters:

  • bit_width – Width of the field.

  • unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(bit_width: int, value: float) → int

Convert from the native Python value of the field, into the unsigned binary integer representation which can be written to a register.

Parameters:

  • bit_width – Width of the field.

  • value – Native Python representation of the field value.

Returns:

Unsigned binary integer representation of the field.

max_value(bit_width: int) → float

Maximum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

min_value(bit_width: int) → float

Minimum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

class hdl_registers.field.register_field_type.Signed

Bases: FieldType

Two’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.

Parameters:

  • bit_width – Width of the field.

  • unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(bit_width: int, value: float) → int

Convert from the native Python value of the field, into the unsigned binary integer representation which can be written to a register.

Parameters:

  • bit_width – Width of the field.

  • value – Native Python representation of the field value.

Returns:

Unsigned binary integer representation of the field.

max_value(bit_width: int) → int

Maximum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

min_value(bit_width: int) → int

Minimum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

class hdl_registers.field.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”.

Parameters:

  • max_bit_index – Position of the upper bit relative to the decimal point.

  • min_bit_index – Position of the lower bit relative to the decimal point.

classmethod from_bit_widths(integer_bit_width: int, fraction_bit_width: int) → SignedFixedPoint

Create instance via the respective fixed point bit widths.

Parameters:

  • integer_bit_width – The number of bits assigned to the integer part of the field value.

  • fraction_bit_width – The number of bits assigned to the fractional part of the field value.

class hdl_registers.field.register_field_type.Unsigned

Bases: FieldType

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

Parameters:

  • bit_width – Width of the field.

  • unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(bit_width: int, value: float) → int

Convert from the native Python value of the field, into the unsigned binary integer representation which can be written to a register.

Parameters:

  • bit_width – Width of the field.

  • value – Native Python representation of the field value.

Returns:

Unsigned binary integer representation of the field.

max_value(bit_width: int) → int

Maximum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

min_value(bit_width: int) → int

Minimum representable value for this field type.

Return type is the native Python representation of the value, which depends on the subclass. If the subclass has a non-zero number of fractional bits, the value will be a float. If not, it will be an int.

class hdl_registers.field.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”.

Parameters:

  • max_bit_index – Position of the upper bit relative to the decimal point.

  • min_bit_index – Position of the lower bit relative to the decimal point.

classmethod from_bit_widths(integer_bit_width: int, fraction_bit_width: int) → UnsignedFixedPoint

Create instance via the respective fixed point bit widths.

Parameters:

  • integer_bit_width – The number of bits assigned to the integer part of the field value.

  • fraction_bit_width – The number of bits assigned to the fractional part of the field value.