RAL API

RAL API#

RALGroup#

class peakrdl_pyral_runtime.model.RALGroup#

Represents an intermediate RAL hierarchy that may contain RALGroup or RALRegister members.

address#: Absolute address of this RAL node

attach_hwio(hwio: HWIO) → None#

Attach a HWIO interface to this node. All read/write operations to this node and its descendants will use the provided HWIO interface.

If this is the root node of the RAL, transactions will include any additional address offset provided during RAL construction.

If this is an internal node of the RAL, transactions will use an address relative to this node.

children() → tuple[RALArray | RALRegister | RALGroup | RALField, ...]#: Returns a tuple of child RAL elements

detach_hwio() → None#: Detach the HWIO interface from this node, if any.

name#: Node name. If the node is an array, the name will include any array suffixes.

parent: 'RALGroup' | None#: Parent RAL node

path#: Hierarchical path of this node

read(offset: int, size: int = 4) → int#

Perform a read operation from an address offset relative to this node’s address.

Parameters:

offset (int) – Offset relative to this node’s address to read. Resulting absolute address shall be aligned to the access size.
size (int) – Size of the access in bytes. Shall be 1, 2, 4, or 8.

Returns:

Read value

Return type:

int

read_bytes(offset: int, size: int) → bytearray#

Read a buffer of bytes relative to this node’s address. User shall make no assumptions on what underlying access size will be used.

Parameters:

offset (int) – Offset from this node’s address.
size (int) – Number of bytes to read

Returns:

Read data

Return type:

bytearray

read_list(offset: int, n_words: int, size: int = 4) → list[int]#

Read a contiguous list of words relative to this node’s address.

Parameters:

offset (int) – Offset from this node’s address.
n_words (int) – Number of words to read.
size (int) – Size of the read access in bytes to use for each entry. Shall be 1, 2, 4, or 8.

size#: Node’s size in bytes

write(offset: int, value: int, size: int = 4) → None#

Perform a write operation to an address offset relative to this node’s address.

Parameters:

offset (int) – Offset relative to this node’s address to write. Resulting absolute address shall be aligned to the access size.
value (int) – Value to write
size (int) – Size of the access in bytes. Shall be 1, 2, 4, or 8.

write_bytes(offset: int, data: bytes | bytearray) → None#

Write a buffer of bytes relative to this node’s address. User shall make no assumptions on what underlying access size will be used.

Parameters:

offset (int) – Offset from this node’s address.
data (bytes) – Buffer of data to write

write_list(offset: int, data: list[int], size: int = 4) → None#

Write a contiguous list of words relative to this node’s address.

Parameters:

offset (int) – Offset from this node’s address.
data (list[int]) – List of words to write.
size (int) – Size of the write access in bytes to use for each entry. Shall be 1, 2, 4, or 8.

RALRegister#

class peakrdl_pyral_runtime.model.RALRegister#

Represents a register.

access_size#: Register’s access size in bytes

address#: Absolute address of this RAL node

attach_hwio(hwio: HWIO) → None#

Attach a HWIO interface to this node. All read/write operations to this node and its descendants will use the provided HWIO interface.

If this is the root node of the RAL, transactions will include any additional address offset provided during RAL construction.

If this is an internal node of the RAL, transactions will use an address relative to this node.

change_fields() → Iterator[RegValue]#

Provides a context manager to modify the value of a register’s fields. This operations triggers a read operation prior to entering the with context body, and a write operation once exiting.

Any fields that are not explicitly set will remain unchanged.

with my_reg.change_fields() as r:
    r.field_1 = 1
    r.field_2 += 5 # increment by 5
    # r.field_3 (remains unchanged)

children() → tuple[RALArray | RALRegister | RALGroup | RALField, ...]#: Returns a tuple of child RAL elements

detach_hwio() → None#: Detach the HWIO interface from this node, if any.

name#: Node name. If the node is an array, the name will include any array suffixes.

parent: RALGroup#: Parent RAL node

path#: Hierarchical path of this node

read() → int#: Read the register’s value

read_fields() → RegValue#

Read the register’s value and return it as a structured RegValue object.

This allows you to access individual fields by-name:

r = my_reg.read_fields()
print(r.field_1)
print(r.field_2)
print(r.field_3)

size#: Node’s size in bytes

write(value: int) → None#

Write a value to the register

Parameters:: value (int) – Value to write

write_fields() → Iterator[RegValue]#

Provides a context manager to write a register’s value by-field. This operation triggers a write operation to the register after exiting the with context body.

Any fields that are not explicitly set will be written with a value of 0.

with my_reg.write_fields() as r:
    r.field_1 = 123
    # r.field_2 = 0 (implied)
    r.field_3 = 456

RALField#

class peakrdl_pyral_runtime.model.RALField#

Represents a single field in a register.

change(value: int) → None#

Change the value of this field.

This will implicitly perform a read and a write of the parent register.

If you are changing multiple fields from the same register, it may be more efficient to use RALRegister.change_fields()

Parameters:: value (int) – Value to change the field to

name#: Node name. If the node is an array, the name will include any array suffixes.

offset#: Bit-offset of this field

parent: RALRegister#: Parent RAL node

path#: Hierarchical path of this node

read() → int#

Read the value of this field.

This will implicitly perform a read of the parent register before returning the field’s value.

If you are reading multiple fields from the same register, it may be more efficient to use RALRegister.read_fields()

width#: Bit-width of this field

RALArray#

class peakrdl_pyral_runtime.model.RALArray#: Represents an array of a RAL node. A RALArray may be indexed and iterated over just like regular Python lists.

RegValue#

class peakrdl_pyral_runtime.model.RegValue#

Structured representation of a register’s value that allows field-level access.

Fields can be accessed by name:

rv.field_1 = 123
print(rv.field_1)

RegValue objects are iterable as name/value pairs:

for name, value in rv:
    print(f"Field {name} has value {value}")

RegValue objects can be converted to an integer:

rv_value = int(rv)

RAL API

Contents

RAL API#

RALGroup#

RALRegister#

RALField#

RALArray#

RegValue#