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 field description.
default_value – Default value. Either “1” or “0”.

property default_value: str: Getter for private member.

property default_value_uint: int: Return a the default value as an unsigned int.

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, numerical_interpretation: NumericalInterpretation | None = None)

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, numerical_interpretation: NumericalInterpretation | None = None)

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 field 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”.
numerical_interpretation – The mode used when interpreting the bits of this field as a numeric value. Default is unsigned with no fractional bits.

property default_value: str: Getter for private member.

property default_value_uint: int: Return a the default value as an unsigned int.

get_value(register_value: int) → int | float: See super method for details. This subclass method uses the native numeric representation of the field value (not the raw value of the bits). 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.

property numerical_interpretation: NumericalInterpretation

The mode used when interpreting the bits of this field as a numeric value (E.g. signed, unsigned fixed-point, etc.). Is used by get_value() and set_value().

Getter for private member.

set_value(field_value: int | float) → int: See super method for details. This subclass method uses the native numeric representation of the field value (not the raw value of the bits). If the field has a non-zero number of fractional bits, the type of the argument should be a float. Otherwise it should be an int.

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 default_value: EnumerationElement: Getter for default_value.

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: See super method for details. This subclass method uses a different type to represent the field value, and also adds some sanity checks.

set_default_value(name: 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: See super method for details. This subclass method uses a different type to represent the field value.

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.

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 default_value: int: Getter for private member.

property default_value_uint: int: Return a the default value as an unsigned int.

get_value(register_value: int) → int: See super method for details. Adds signed/unsigned logic, and sanity checks of the value.

property is_signed: bool: Is the field signed (two’s complement)? Getter for private member.

property max_value: int: Maximum numeric value this field can assume. Getter for private member.

property min_value: int: Minimum numeric value this field can assume. Getter for private member.

set_value(field_value: int) → int: See super method for details. Adds signed/unsigned logic, and sanity checks of the value.

hdl_registers.field.numerical_interpretation module

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

Bases: NumericalInterpretation, ABC

__init__(is_signed: bool, max_bit_index: int, min_bit_index: int)

Abstract baseclass for fixed-point fields.

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(unsigned_binary: int) → float

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

Parameters:: unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(value: float) → int

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

Parameters:: value – Native Python representation of the field value.
Returns:: Unsigned binary integer representation of the field.

property is_signed: bool: Is the field signed (two’s complement)?

property max_value: float

Maximum representable value for this field, in its native numeric representation.

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.

property min_value: float

Minimum representable value for this field, in its native numeric representation.

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.numerical_interpretation.NumericalInterpretation

Bases: ABC

This class represents different modes used when interpreting a field of bits as a numeric value. Contains metadata, helper methods, etc.

bit_width: int

abstract convert_from_unsigned_binary(unsigned_binary: int) → int | float

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

Parameters:: unsigned_binary – Unsigned binary integer representation of the field.

abstract convert_to_unsigned_binary(value: int | float) → int

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

Parameters:: value – Native Python representation of the field value.
Returns:: Unsigned binary integer representation of the field.

abstract property is_signed: bool: Is the field signed (two’s complement)?

abstract property max_value: int | float

Maximum representable value for this field, in its native numeric representation.

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 property min_value: int | float

Minimum representable value for this field, in its native numeric representation.

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.numerical_interpretation.Signed(bit_width: int)

Bases: NumericalInterpretation

Two’s complement signed integer format.

__init__(bit_width: int)

convert_from_unsigned_binary(unsigned_binary: int) → int

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

Parameters:: unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(value: float) → int

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

Parameters:: value – Native Python representation of the field value.
Returns:: Unsigned binary integer representation of the field.

is_signed: bool = True

property max_value: int

Maximum representable value for this field, in its native numeric representation.

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.

property min_value: int

Minimum representable value for this field, in its native numeric representation.

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.numerical_interpretation.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.numerical_interpretation.Unsigned(bit_width: int)

Bases: NumericalInterpretation

Unsigned integer.

__init__(bit_width: int)

convert_from_unsigned_binary(unsigned_binary: int) → int

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

Parameters:: unsigned_binary – Unsigned binary integer representation of the field.

convert_to_unsigned_binary(value: float) → int

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

Parameters:: value – Native Python representation of the field value.
Returns:: Unsigned binary integer representation of the field.

is_signed: bool = False

property max_value: int

Maximum representable value for this field, in its native numeric representation.

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.

property min_value: int

Minimum representable value for this field, in its native numeric representation.

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

hdl_registers.field.numerical_interpretation.from_unsigned_binary(num_bits: int, value: int, num_integer_bits: int | None = None, num_fractional_bits: int = 0, is_signed: bool = False) → int | float

Convert from a fixed-point unsigned binary value to one of

unsigned integer (Python int)
signed integer (Python int)
unsigned floating-point (Python float)
signed floating-point (Python float)

Signed types use two’s complement representation for the binary value. Sources:

Parameters:

num_bits – Width of the field.
value – Unsigned binary integer representation of the value.
num_integer_bits – The number of integer bits in the fixed-point value. Might be negative if this is a fixed-point word with only fractional bits.
num_fractional_bits – The number of fractional bits in the fixed-point value. Might be negative if this is a fixed-point word with only integer bits.
is_signed – If True, the MSB of the value will be treated as a sign bit. Enables the handling of negative result values.

Returns:

Native Python representation of the value. Will be a float if num_fractional_bits is non-zero, otherwise it will be an int.

hdl_registers.field.numerical_interpretation.to_unsigned_binary(num_bits: int, value: int | float, num_integer_bits: int | None = None, num_fractional_bits: int = 0, is_signed: bool = False) → int

Convert from one of

unsigned integer (Python int)
signed integer (Python int)
unsigned floating-point (Python float)
signed floating-point (Python float)

into an unsigned binary. Signed types use two’s complement representation for the binary value. Sources:

Parameters:

num_bits – Width of the field.
value – Native numeric Python representation of the value. If num_fractional_bits is non-zero the value is expected to be a float, otherwise an int is expected.
num_integer_bits – The number of integer bits in the target fixed-point word. Might be negative if this is a fixed-point word with only fractional bits.
num_fractional_bits – The number of fractional bits in the target fixed-point word. Might be negative if this is a fixed-point word with only integer bits.
is_signed – Enables the handling of negative input value. If True, the MSB of the result word will be treated as a sign bit.

Returns:

Unsigned binary integer representation of the value. Potentially rounded, if the input value is a floating-point number.

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.

property base_index: int: The index within the register for the lowest bit of this field. Note that this (along with width) decides the base index of upcoming fields, and thus it may not be changed. Hence this read-only property which is a getter for a private member.

default_value: str | int

abstract property default_value_uint: int: Return a the default value as an unsigned int.

description: str

get_value(register_value: int) → int

Get the value of this field, given the supplied register value.

Parameters:

register_value – Value of the register that this field belongs to, as an unsigned integer.

Returns:

The value of the field as an unsigned integer.

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. Subclasses might also implement sanity checks of the value given the constraints of that field.

name: str

set_value(field_value: int) → 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 unsigned integer value to set the field to.

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

Returns:

The register value as an unsigned integer.

property width: int: The width, in number of bits, that this field occupies. The index within the register for the lowest bit of this field. Note that this (along with width) decides the base index of upcoming fields, and thus it may not be changed. Hence this read-only property which is a getter for a private member.