regfile_generics

Regfile generics

Submodules

• regfile_generics.regfile
• regfile_generics.regfile_device

Classes

Regfile	A Regfile handles multiple RegfileEntry items.
RegfileMemAccess	Handling Memory through a regfile device.
RegisterEntry	Decompose access of a register into fields.
RegfileDev	Regfile Device class that handels the access of a Regfile
RegfileDevSimple	RegfileDev that operates on words only (implements read-modify-write if necessary)
RegfileDevSimpleDebug	Debug implementation of RegfileDevSimple
RegfileDevSubword	RegfileDev that operates on word sizes (implements read-modify-write if this)
RegfileDevSubwordDebug	Debug implementation of RegfileDevSimple
StringCmdRegfileDevSimple	Forwards regfile operations to a function call with string command,
StringCmdRegfileDevSubword	Forwards regfile operations to a function call with string command,

Package Contents

class regfile_generics.Regfile(rfdev, base_addr=0, name=None)

A Regfile handles multiple RegfileEntry items.

It can be only be initialized by using context managers (with-statement). if name is not given the default name will be the <CLASSNAME>@<BASEADDR>.

Example:

class SubmodRegfile(Regfile):
    def __init__(self, rfdev, base_addr):
        super().__init__(rfdev, base_addr)

        with self as regfile:
            with regfile["reg0"].represent(addr=0x0000, write_mask=0x0000001F) as reg:
                reg["cfg"].represent(bits="4:0", access="RW", reset="0x0", desc="Configure component")
                reg["status"].represent(bits="31:16", access="regfile", desc="Component status")

Parameters:

• base_addr (int)

• name (Optional[str])

get_base_addr()

Return the base address of the register file (provided upon instantiation).

Return type:

int

property name: str

“Return the name of the registerfile

Return type:

str

__setitem__(key, value)

Access a register entry of the Regfile.

Parameters:

• key (str) – name of the register

• value (Union[int, dict, RegisterEntry]) – value to execute a register write access

Return type:

None

Example:

submodregfile['reg0'] = {'cfg': 0b1_1011}

__getitem__(key)

Access a register entry of register.

Parameters:

key (str) – name of the register

Return type:

RegisterEntry

keys()

Get all register names of the Regfile.

Return type:

collections.abc.KeysView[str]

values()

Get all registers of the Regfile.

Return type:

collections.abc.ValuesView[RegfileEntry]

items()

Get all names plus the corresponding registers of the Regfile.

Return type:

collections.abc.ItemsView[str, RegisterEntry]

__iter__()

Return type:

collections.abc.Iterator[RegfileEntry]

reset_all()

Apply initial reset value to mirrored value of all registers.

Return type:

None

get_rfdev()

Get the regfile device with is used upon access.

Return type:

regfile_generics.regfile_device.RegfileDev

set_rfdev(dev)

Set the regfile device with is used upon access.

Parameters:

dev (regfile_generics.regfile_device.RegfileDev) – regfile device

Return type:

None

__setattr__(name, value)

Enforce that no new attributes are set when the instance is frozen.

__getattr__(name)

Providing additional attribute-like access of a register. To avoid collisions the name has a _r suffix.

Example:

assert submodregfile["config"] == submodregfile.config_r

__enter__()

Context manager of with statement - After __enter__ adding of new entries is allowed.

__exit__(exception_type, exception_value, exception_traceback)

Context manager of with statement - Locks the instances again.

class regfile_generics.RegfileMemAccess(rfdev, base_addr, **kwargs)

Handling Memory through a regfile device.

Note that indexing is word wise, depending on regfile_device.RegfileDev.n_word_bytes.

Parameters:

• rfdev (regfile_generics.regfile_device.RegfileDev) – regfile device

• base_addr (int) – base address of the memory

Optional kwargs: :key size: the size of the memory to check of index errors

__getitem__(index)

Read a memory element via index (word addressing)

Parameters:

index (int) – word address to be read

Return type:

int

__setitem__(index, value)

Write a memory element via index (word addressing)

Parameters:

• index (int) – word address to be read

• value (int)

Value value:

value to be written to the memory

get_rfdev()

Get the regfile device with is used upon access.

Return type:

regfile_generics.regfile_device.RegfileDev

set_rfdev(dev)

Set the regfile device with is used upon access.

Parameters:

dev – regfile device

Return type:

None

get_base_addr()

Return the base address of the register file (provided upon instantiation).

Return type:

int

read_image(addr, size)

Read Image starting on specified address.

Parameters:

• addr (int) – start address

• size (int) – size of image to be read from the memory

Returns:

memory image as list

Return type:

list[int]

write_image(addr, image)

Write Image starting on specified address.

Parameters:

• addr (int) – start address

• image (tuple[int, Ellipsis]) – image to be written to the memory

Return type:

None

class regfile_generics.RegisterEntry(**kwargs)

Decompose access of a register into fields.

If kwargs are specified, they are passed to the represent() function.

addr = 0

write_mask = -1

regfile = None

name = 'UNNAMED'

mirrored_value = 0

desired_value = 0

represent(addr=None, write_mask=None, fields=None, regfile=None, name=None, reset=None, mirrored_value=None, **kwargs)

Used upon initialization.

Parameters:

• addr (Optional[int])

• write_mask (Optional[int])

• fields (Optional[dict[str, RegisterField]])

• regfile (Optional[Regfile])

• name (Optional[str])

• reset (Optional[int])

• mirrored_value (Optional[int])

Return type:

RegisterEntry

__getitem__(key)

Dict-like access tor read a value from a field of the register-entry

Parameters:

key (str) – Name of the register-field.

Return type:

int

__setitem__(key, value)

Dict-like access to write a value to a field.

Parameters:

• key (str) – name of the register field

• value (int) – value to be written to the field

Return type:

None

write_update(*args, **kwargs)

Update the register.

This function takes a dict as argument containing key/value of the fields to be written or kwargs with fieldnames/values

Example:

submodregfile["reg0"].write_update(cfg=0b0_0100)

get_reg(value=None)

Return a new RegisterEntry (shallow copy).

Parameters:

value (Optional[int]) – Value to be hold by the new RegisterEntry, if value is not the value will be taken from the original instance

Return type:

RegisterEntry

read_entry()

Reads the value and returns a new RegisterEntry (alias of get_reg()).

Return type:

RegisterEntry

get_dict(value=None)

Get dictionary field view of the register.

If value is not specified a read will be executed, otherwise the value is decomposed to the fields

Parameters:

value (Optional[int]) – Integer value that should be decomposed

Return type:

dict[str, int]

get_name()

Get the name of the register, if set otherwise return UNNAMED

Return type:

str

get_field_names()

Returns a copy of the field’s dictionary’s list of keys (fieldnames).

Return type:

collections.abc.KeysView[str]

get_writable_fieldnames()

Return a copied list containing all writable fieldnames

Return type:

tuple[str]

writable_field_items()

Return a iterator over all writable_fields (tuple name, RegisterEntry)

Return type:

collections.abc.Iterator[tuple[str, RegisterEntry]]

get_reset_values()

Get iterator object of the tuple (fieldname, resetvalue) for writable fields only.

Return type:

dict[str, int]

field(name)

Get the field by name and add callback for UVM-like set() method of fields

Parameters:

name (str)

Return type:

RegisterField

items()

Providing all (fieldname, field) tuples for for self-inspection.

Return type:

collections.abc.ItemsView[str, RegisterField]

__iter__()

Iterator over the (name, int) mainly for dict() conversion.

Return type:

collections.abc.Iterator[tuple[str, int]]

__setattr__(name, value)

Enforce that no new attributes are set when the instance is frozen.

__str__()

Read the register and format it decomposed as fields as well as integer value.

Return type:

str

get_value(field_dict=None)

Return the integer view of the register. If field_dict is not specified a read will be executed, otherwise the dict is composed to get the integer value

Parameters:

field_dict (Optional[dict])

Return type:

int

set_value(value, mask=None)

Set the value of register. The value can be an integer a dict or a register object (e.g. obtained by get_reg()).

Parameters:

• value (Union[int, dict, RegfileEntry]) – new value for the register

• mask (Optional[int]) – write mask for the register

Return type:

None

__enter__()

The with statement allows to add fields to the register -

with reg as add_fields_register:

add_fields_register.represent(name=”FIELDNAME”, bits=(msb,lsb), reset=0x0, …)

Return type:

_RepresentDict

__exit__(exception_type, exception_value, exception_traceback)

Lock the register fields - sort-out the writable_fieldnames with the help of the write_mask

__getattr__(name)

Allow member access of fields - must have ‘_f’ as suffix (<FIELDNAME>_f).

Parameters:

name (str)

read()

UVM-like - Read the current value from this register.

Return type:

int

get()

UVM-like - Return the desired value of the fields in the register.

Return type:

int

get_mirrored_value()

UVM-like - Return the mirrored value of the fields in the register.

Return type:

int

get_mirrored_dict()

UVM-like - Variation of get_mirrored_value() return a dict instead of an int

Return type:

dict

get_mirrored_reg()

UVM-like - Variation of get_mirrored_value() return a reg instead of an int

Return type:

RegisterEntry

set(value)

UVM-like - Set the desired value for this register.

Parameters:

value (int)

Return type:

None

needs_update()

UVM-like - Returns True if any of the fields need updating

Return type:

bool

update()

UVM-like - Updates the content of the register in the design to match the desired value.

Return type:

None

write(*args, **kwargs)

UVM-like - Write the specified value in this register.

Return type:

None

reset()

UVM-like - Reset the desired/mirrored value for this register.

Return type:

None

get_reset()

UVM-like - Get the specified reset value for this register.

Return type:

int

get_field_by_name(name)

UVM-like - Return the fields in this register.

Parameters:

name (str)

Return type:

RegisterField

get_offset()

UVM-like - Returns the offset of this register.

get_address()

UVM-like - Returns the base external physical address of this register

__int__()

Integer conversion of register value

Return type:

int

__bool__()

Boolean conversion of register value

Return type:

bool

__eq__(other)

Equal comparison with integer

__ne__(other)

Not equal comparison with integer

__lt__(other)

Less-than comparison with integer

__le__(other)

Less-than/equal comparison with integer

__gt__(other)

Greater-than comparison with integer

__ge__(other)

Greater-than/equal comparison with integer

get_register_entry(value)

Deprecated since version 0.2.0.

Use get_reg() instead.

Parameters:

value (int) – Value to be hold by the new RegisterEntry

Return type:

RegisterEntry

class regfile_generics.RegfileDev(callback=None, bytes_per_word=4, logger=None, prefix='', **kwargs)

Regfile Device class that handels the access of a Regfile

Parameters:

• callback (Optional[dict[str, Callable]]) – dict with rfdev_read/rfdev_write/blockread/blockwrite pointing to a register read/write function

• bytes_per_word (int) – bytes per word a single register access can handle (default 4)

• logger (Optional[logging.Logger]) – logger instance

• prefix (str) – prefix for (debug) logging with the logger instance

Deprecated since version 0.2.0:

key blockread:

reference to a blockread function, use callback dict instead

key blockwrite:

reference to a blockwrite function, use callback dict instead

logger = None

callback

property n_word_bytes: int

Returs the number of bytes per word the device handles on one operation.

Return type:

int

blockread(start_addr, size)

Initiate a blockread used for

Parameters:

• start_addr (int) – start address of read data

• size (int) – number of words to be read

Return type:

list[int]

blockwrite(start_addr, values)

Initiate a blockwrite used for memory access :param start_addr: start address of write data :param value: word list to be written

Parameters:

• start_addr (int)

• values (tuple[int, Ellipsis])

Return type:

None

rfdev_read(addr)

Read method calling rfdev_read of callback dict passed upon init - could be overridden, when deriving a new RegfileDev

Parameters:

addr (int)

Return type:

int

read(baseaddr, entry)

Read a register entry relative to a base address

Parameters:

• baseaddr (int) – Base address of the Register File

• entry (regfile_generics.regfile.RegfileEntry) – A register entry

Return type:

int

rfdev_write(addr, value, mask, write_mask)

Read method could be overridden when deriving a new RegfileDev default implementation is to call the function passed while initialization, through the value of the “rfdev_write”-key of the callback dictionary.

Parameters:

• addr (int) – Absolute Address to be accessed for write

• value (int) – Value to be written

• mask (int) – Mask for the write operation to the register

• write_mask (int) – Mask of writeable bits inside the register (e.g. to determine if read-modify-write is necessary)

Return type:

None

write(baseaddr, entry, value, mask)

Read a register entry relative to a base address

Parameters:

• baseaddr (int) – Base address of the Register File

• entry (regfile_generics.regfile.RegfileEntry) – A register entry

• value (int) – register value

• mask (int) – mask for the operation

Return type:

None

readwrite_block(start_addr, values, write)

Deprecated since version 0.2.0.

Use blockread() or blockwrite() instead.

class regfile_generics.RegfileDevSimple(callback=None, bytes_per_word=4, logger=None, prefix='', **kwargs)

Bases: RegfileDev

RegfileDev that operates on words only (implements read-modify-write if necessary)

Derived from RegfileDev

Allowed callback entries:

key rfdev_read:

read function (signature RegfileDev.rfdev_read())

key rfdev_write_simple:

write function which has the same signature like rfdev_write_simple()

Parameters:

• callback (Optional[dict[str, Callable]])

• bytes_per_word (int)

• logger (Optional[logging.Logger])

• prefix (str)

rfdev_write_simple(addr, value)

Simple write operation - calls back rfdev_write_simple if passed to constructor.

Parameters:

• addr (int) – absolute address for write operation

• value (int) – value to write

Return type:

None

rfdev_write(addr, value, mask, write_mask)

RegfileDev rfdev_write implementations - executes the read-modify-write if necessary

Parameters:

• addr (int) – absolute Address to be accessed for write

• value (int) – value to be written

• mask (int) – mask for the write operation to the register

• write_mask (int) – mask of writeable bits inside the register

Return type:

None

class regfile_generics.RegfileDevSimpleDebug(interactive=False, **kwargs)

Bases: RegfileDevSimple

Debug implementation of RegfileDevSimple

Parameters:

interactive (bool) – if set to True the regfile device will request a user input upon read.

mem: dict[int, int]

write_count = 0

read_count = 0

rfdev_read(addr)

Debug read function interactive if necessary

Param:

addr address

Parameters:

addr (int)

Return type:

int

rfdev_write_simple(addr, value)

Debug write function to mem attribute.

Parameters:

• addr (int) – absolute address for write operation

• value (int) – value to write

Return type:

None

getvalue(addr)

Get value out of the memory, randomize if necessary.

Parameters:

addr (int) – address to be read

Return type:

int

class regfile_generics.RegfileDevSubword(callback=None, bytes_per_word=4, logger=None, prefix='', **kwargs)

Bases: RegfileDev

RegfileDev that operates on word sizes (implements read-modify-write if this)

Derived from RegfileDev

Allowed callback entries:

key rfdev_read:

read function (signature RegfileDev.rfdev_read())

key rfdev_write_simple:

write function which has the same signature like rfdev_write_simple()

Parameters:

• callback (Optional[dict[str, Callable]])

• bytes_per_word (int)

• logger (Optional[logging.Logger])

• prefix (str)

rfdev_write(addr, value, mask, write_mask)

Read method could be overridden when deriving a new RegfileDev default implementation is to call the function passed while initialization, through the value of the “rfdev_write”-key of the callback dictionary.

Parameters:

• addr (int) – Absolute Address to be accessed for write

• value (int) – Value to be written

• mask (int) – Mask for the write operation to the register

• write_mask (int) – Mask of writeable bits inside the register (e.g. to determine if read-modify-write is necessary)

Return type:

None

rfdev_write_subword(addr, value, size)

Word size write operation - calls back rfdev_write_subword if passed to constructor.

Parameters:

• addr (int) – absolute address for write operation (lower address bit indicate word position)

• value (int) – value to write

• size (int) – number of bytes to write

Return type:

None

class regfile_generics.RegfileDevSubwordDebug(interactive=False, **kwargs)

Bases: RegfileDevSubword

Debug implementation of RegfileDevSimple

Parameters:

interactive (bool) – if set to True the regfile device will request a user input upon read.

mem: dict[int, int]

write_count = 0

read_count = 0

getvalue(addr)

Return memory value

Parameters:

addr (int) – address were the data will be read

Return type:

int

rfdev_read(addr)

Debug read function interactive if necessary

Param:

addr address

Parameters:

addr (int)

Return type:

int

rfdev_write_subword(addr, value, size)

Word size write operation - calls back rfdev_write_subword if passed to constructor.

Parameters:

• addr (int) – absolute address for write operation (lower address bit indicate word position)

• value (int) – value to write

• size (int) – number of bytes to write

Return type:

None

class regfile_generics.StringCmdRegfileDevSimple(execute=None, **kwargs)

Bases: RegfileDevSimple

Forwards regfile operations to a function call with string command, to do the regfile operations.

Read:

r<NUMBITS> <address>

e.g. r32 0x1C

Write:

w<NUMBITS> <address> <value>

e.g. w32 0x80 0xF9852A

Parameters:

execute (Optional[Callable[[str], Optional[str]]])

execute = None

rfdev_read(addr)

Debug read function implementation translates to execute()

Parameters:

addr (int) – absolute address for read operation

Return type:

int

rfdev_write_simple(addr, value)

Debug write function implementation translates to execute()

Parameters:

• addr (int) – absolute address for write operation

• value (int) – value to write

class regfile_generics.StringCmdRegfileDevSubword(**kwargs)

Bases: RegfileDevSubword

Forwards regfile operations to a function call with string command, to do the regfile operations.

Read:

r<NUMBITS> <address>

e.g. r32 0x1C

Write:

w<NUMBITS> <address> <value> [bsel]

e.g. w32 0x80 0xF9852A

w32 0x80 0xF9852A 0x1

execute

rfdev_read(addr)

Read method calling rfdev_read of callback dict passed upon init - could be overridden, when deriving a new RegfileDev

Parameters:

addr (int)

Return type:

int

rfdev_write_subword(addr, value, size)

Word size write operation - calls back rfdev_write_subword if passed to constructor.

Parameters:

• addr (int) – absolute address for write operation (lower address bit indicate word position)

• value (int) – value to write

• size (int) – number of bytes to write

Return type:

None