coreblocks.priv.csr package

Submodules

coreblocks.priv.csr.aliased module

class coreblocks.priv.csr.aliased.AliasedCSR

Bases: CSRRegisterBase

__init__(csr_number: int | None, gen_params: GenParams, width: int | None = None, src_loc: int | tuple[str, int] = 0)

Parameters:

gen_params: GenParams: Core generation parameters.
csr_number: Optional[int]: Address of this CSR Register. If None is given, CSR is virtual - not registerable to CSRUnit. Otherwise it’s registered under provided address to CSRUnit using CSRListKey.
width: int: Bit width of CSR register.
src_loc: SrcLoc: CSR location in source code for error reporting.

add_field(bit_position: int, csr: CSRRegister)

add_read_only_field(bit_position: int, bit_width: int, value: int | Enum)

coreblocks.priv.csr.csr_instances module

class coreblocks.priv.csr.csr_instances.CSRInstances

Bases: Elaboratable

__init__(gen_params: GenParams)

class coreblocks.priv.csr.csr_instances.MachineModeCSRRegisters

Bases: Elaboratable

__init__(gen_params: GenParams)

class coreblocks.priv.csr.csr_instances.SupervisorModeCSRRegisters

Bases: Elaboratable

Supervisor-mode CSR block with status, envcfg, trap, and SATP support.

__init__(gen_params: GenParams, m_mode: MachineModeCSRRegisters)

coreblocks.priv.csr.csr_instances.counteren_access_filter(gen_params: GenParams, counteren_bit: int)

coreblocks.priv.csr.csr_instances.counteren_writable_mask(hpm_counters_count: int) → int

coreblocks.priv.csr.csr_register module

class coreblocks.priv.csr.csr_register.CSRRegister

Bases: CSRRegisterBase

CSR Register Flexible implementation of a general purpose CSR register.

Used to define a basic CSR register and specify its behaviour. CSRRegisters with csr_number defined are automatically assigned to CSRListKey dependency key, to be accessed from CSRUnits.

See CSRRegisterBase for class attributes.

Examples

# Timer register that increments on each cycle and resets if read by CSR instruction
csr = CSRRegister(1, gen_params)
with Transaction.body(m):
    csr_val = csr.read()
    with m.If(csr_val.read):
        csr.write(0)
    with m.Else():
        csr.write(csr_val.data + 1)

Parameters:

csr_number: Optional[int]: Address of this CSR Register. If None is given, CSR is virtual - not automatically connected to CSRUnit.
gen_params: GenParams: Core generation parameters.
width: Optional[int]: Width of CSR register. Defaults to xlen.
ro_bits: int: Bit mask of read-only bits in register. Writes from _fu_write (instructions) to those bits are ignored. Note that this parameter is only required if there are some read-only bits in read-write register. Writes to read-only registers specified by upper 2 bits of CSR address set to 0b11 are discarded by CSRUnit.
init: int | Enum: Reset value of CSR.
fu_write_priority: bool: Priority of CSR instruction write over write method, if both are called at the same cycle. If ro_bits are set, both operations will be performed, respecting priority on writeable bits. Defaults to True.
fu_write_filtermap: function (TModule, Value) -> (ValueLike, ValueLike): Filter + map on CSR writes from instruction. First Value in returned tuple signals if write should be performed, second is modified input data.
fu_read_map: function (TModule, Value) -> (ValueLike): Map on CSR reads from instructions. Maps value returned from CSR.
fu_access_filter: function (TModule, Value) -> ValueLike: Filter on CSR accesses from instructions. Returned value indicates if access should be considered legal.
fu_write_combine: function (TModule, Value, Value, Value) -> ValueLike: Combine function for CSR instruction writes. Takes the input from CSR* instruction, the mode (CSRRegisterLayouts.WriteOpType) and the value returned the CSR* instruction (_fu_read).
src_loc: int | SrcLoc: How many stack frames deep the source location is taken from. Alternatively, the source location to use instead of the default.

class coreblocks.priv.csr.csr_register.CSRRegisterBase

Bases: ABC, Elaboratable

RISC-V Control and Status Register base class Abstract class defining basic internal CSR register interface, that all CSR variations should implement. Provides constructor defining required methods and signals.

Attributes:

read: Method: Reads register value and side effect status. Side effect fields read and written are set if register was accessed by _fu_read or _fu_write methods (by CSR instruction) in a current cycle; they can be used to trigger other actions. Always ready.
read_comb: Method: Reads register value or value submitted by _fu_write`(instruction write) combinationally. Note that returned value ignores priority setting. It allows for `_fu_write -> read_comb -> write operation in single cycle. Note that if _fu_write is called, it returns call value ignoring ro_bits. Always ready.
write: Method: Updates register value. Always ready.
_fu_read: Method: Method connected automatically by CSRUnit. Reads register value.
_fu_write: Method: Method connected automatically by CSRUnit. Updates register value. Always ready.
_fu_access_valid: Method: Method connected automatically by CSRUnit. Returns whether CSR access is legal for a provided privilege level, or should an instruction access cause an exception.
value: Signal: Represents current value of a CSR register. Useful for debugging and traces.

__init__(gen_params: GenParams, csr_number: int | None, width: int, src_loc: tuple[str, int])

Parameters:

gen_params: GenParams: Core generation parameters.
csr_number: Optional[int]: Address of this CSR Register. If None is given, CSR is virtual - not registerable to CSRUnit. Otherwise it’s registered under provided address to CSRUnit using CSRListKey.
width: int: Bit width of CSR register.
src_loc: SrcLoc: CSR location in source code for error reporting.

coreblocks.priv.csr.double_counter module

class coreblocks.priv.csr.double_counter.DoubleCounterCSR

Bases: Elaboratable

Double counter CSR.

A 64-bit CSR counter, visible on two CSR addresses on RV32.

Parameters:

gen_params: GenParams: Core generation parameters.
low_addr: CSRAddress: Address of the CSR register representing lower part of the counter on RV32, or the entire counter on RV64.
high_addr: CSRAddress: Address of the CSR register representing higher part of the counter on RV32. Unused on RV64.
shadow_low_addr: CSRAddress, optional: Address of the shadow CSR register for the lower part of the counter. If provided, shadow CSR is synthetised with read-only access to the counter value.
shadow_high_addr: CSRAddress, optional: Address of the shadow CSR register for the higher part of the counter. If provided, shadow CSR is synthetised with read-only access to the counter value. If shadow_low_addr is provided, shadow_high_addr also should be provided.
shadow_access_filter: Callable, optional: Provides access_filter for additional shadow CSRs.
read_only_zero: bool: If True, the increment is no-op and the counter always reads as zero.

increment: Method: Increments the counter by 1. At overflow, counter value is set to 0.

coreblocks.priv.csr.double_shadow module

class coreblocks.priv.csr.double_shadow.DoubleShadowCSR

Bases: Elaboratable

Double shadow CSR.

Creates two 32-bit shadows of an 64-bit CSR on RV32, or a single 64-bit shadow on RV64. Can also create an additional shadow pair, e.g. for S-mode registers.

Parameters:

gen_params: GenParams: Core generation parameters.
low_addr: CSRAddress, optional: Address of the CSR register representing lower part of the CSR on RV32, or the entire CSR on RV64.
high_addr: CSRAddress, optional: Address of the CSR register representing higher part of the CSR on RV32. Unused on RV64.
shadow_low_addr: CSRAddress, optional: Address of the shadow CSR register for the lower part of the CSR. If provided, shadow CSR is synthetised with read-only access to the CSR value.
shadow_high_addr: CSRAddress, optional: Address of the shadow CSR register for the higher part of the CSR. If provided, shadow CSR is synthetised with read-only access to the CSR value. If shadow_low_addr is provided, shadow_high_addr also should be provided.
shadow_access_filter: Callable, optional: Provides access_filter for additional shadow CSRs.

coreblocks.priv.csr.shadow module

class coreblocks.priv.csr.shadow.ShadowCSR

Bases: CSRRegisterBase

CSR shadow register.

Creates a CSR which is backed by another CSR - reads and writes are forwarded to it. Optional bit masks can restrict visible read bits and writable bits for both instruction-visible access and internal CSR logic.

Parameters:

gen_params: GenParams: Core generation parameters.
csr_number: Optional[int]: Address of this CSR Register. If None is given, CSR is virtual - not registerable to CSRUnit. Otherwise it’s registered under provided address to CSRUnit using CSRListKey.
width: int: Bit width of CSR register.
src_loc: SrcLoc: CSR location in source code for error reporting.

coreblocks.priv.csr package

Submodules

coreblocks.priv.csr.aliased module

coreblocks.priv.csr.csr_instances module

coreblocks.priv.csr.csr_register module

coreblocks.priv.csr.double_counter module

coreblocks.priv.csr.double_shadow module

coreblocks.priv.csr.shadow module

Module contents