CSRs

Bus

class torii.lib.soc.csr.bus.Element(width: int, access: Access, *, name: str | None = None, src_loc_at: int = 0)
class torii.lib.soc.csr.bus.Interface(*, addr_width: int, data_width: int, name: str | None = None)

CPU-side CSR interface.

A low-level interface to a set of atomically readable and writable peripheral CSR registers.

Operation

CSR registers mapped to the CSR bus are split into chunks according to the bus data width. Each chunk is assigned a consecutive address on the bus. This allows accessing CSRs of any size using any datapath width.

When the first chunk of a register is read, the value of a register is captured, and reads from subsequent chunks of the same register return the captured values. When any chunk except the last chunk of a register is written, the written value is captured; a write to the last chunk writes the captured value to the register. This allows atomically accessing CSRs larger than datapath width.

param addr_width:

Address width. At most (2 ** addr_width) * data_width register bits will be available.

type addr_width:

int

param data_width:

Data width. Registers are accessed in data_width sized chunks.

type data_width:

int

param name:

Name of the underlying record.

type name:

str

Attributes:

  • memory_map (MemoryMap) – Map of the bus.

  • addr (Signal(addr_width)) – Address for reads and writes.

  • r_data (Signal(data_width)) – Read data. Valid on the next cycle after r_stb is asserted. Otherwise, zero. (Keeping read data of an unused interface at zero simplifies multiplexers.)

  • r_stb (Signal()) – Read strobe. If addr points to the first chunk of a register, captures register value and causes read side effects to be performed (if any). If addr points to any chunk of a register, latches the captured value to r_data. Otherwise, latches zero to r_data.

  • w_data (Signal(data_width)) – Write data. Must be valid when w_stb is asserted.

  • w_stb (Signal()) – Write strobe. If addr points to the last chunk of a register, writes captured value to the register and causes write side effects to be performed (if any). If addr points to any chunk of a register, latches w_data to the captured value. Otherwise, does nothing.

class torii.lib.soc.csr.bus.Decoder(*args: Any, src_loc_at: int = 0, **kwargs: Any)

CSR bus decoder.

An address decoder for subordinate CSR buses.

Usage

Although there is no functional difference between adding a set of registers directly to a Multiplexer and adding a set of registers to multiple Multiplexer`s that are aggregated with a :class:`Decoder, hierarchical CSR buses are useful for organizing a hierarchical design. If many peripherals are directly served by a single Multiplexer, a very large amount of ports will connect the peripheral registers with the decoder, and the cost of decoding logic would not be attributed to specific peripherals. With a decoder, only five signals per peripheral will be used, and the logic could be kept together with the peripheral.

param addr_width:

Address width. See Interface.

type addr_width:

int

param data_width:

Data width. See Interface.

type data_width:

int

param alignment:

Window alignment. See memory.MemoryMap.

type alignment:

log2 of int

param name:

Window name. Optional.

type name:

str

Attributes:

bus (Interface) – CSR bus providing access to subordinate buses.

class torii.lib.soc.csr.bus.Multiplexer(*args: Any, src_loc_at: int = 0, **kwargs: Any)

Events

class torii.lib.soc.csr.event.EventMonitor(*args: Any, src_loc_at: int = 0, **kwargs: Any)

Event monitor.

A monitor for subordinate event sources, with a CSR bus interface.

CSR registers

enableself.src.event_map.size, read/write

Enabled events. See event.EventMap.sources() for layout.

pendingself.src.event_map.size, read/clear

Pending events. See event.EventMap.sources() for layout.

param data_width:

CSR bus data width. See csr.Interface.

type data_width:

int

param alignment:

CSR address alignment. See mem.map.MemoryMap.

type alignment:

int

param trigger:

Trigger mode. See event.Source.

type trigger:

event.Source.Trigger

Wishbone

class torii.lib.soc.csr.wishbone.WishboneCSRBridge(*args: Any, src_loc_at: int = 0, **kwargs: Any)

Wishbone to CSR bridge.

A bus bridge for accessing CSR registers from Wishbone. This bridge supports any Wishbone data width greater or equal to CSR data width and performs appropriate address translation.

Latency

Reads and writes always take self.data_width // csr_bus.data_width + 1 cycles to complete, regardless of the select inputs. Write side effects occur simultaneously with acknowledgement.

param csr_bus:

CSR bus driven by the bridge.

type csr_bus:

csr.Interface

param data_width:

Wishbone bus data width. If not specified, defaults to csr_bus.data_width.

type data_width:

int or None

param name:

Window name. Optional.

type name:

str

Attributes:

wb_bus (bus.wishbone.Interface) – Wishbone bus provided by the bridge.