CSR Design Fundamentals

The previous module built an APB slave's RTL — bank, decoder, read mux, write logic. This module steps back to the thing that RTL exists to implement: the register map, the set of addressable registers and fields a peripheral exposes to software. The single idea to carry: the register map is a contract between hardware and firmware, and it must be designed — addressing, field layout, and access types specified up front — not discovered from whatever the RTL happened to do. A peripheral's RTL can be flawless and the chip still unusable if the map is badly addressed, packs fields across word boundaries, or leaves access semantics ambiguous. CSR design is the discipline of specifying that contract precisely, before and independently of the logic that implements it.

1. Problem statement

The problem is defining the software-visible interface of a peripheral — every address software can touch, every field within it, and exactly what reading or writing each one does — as a precise, stable, machine-readable specification.

A control/status register (CSR) map is the only thing firmware, driver writers, validation, and the next chip's integrators see of your peripheral. They never read your RTL; they read the map. That forces three specification decisions that have nothing to do with how the logic is built:

• Where each register lives, and how it aligns. Registers sit at byte offsets in the peripheral's address window. They must be word-aligned and laid out so the address decode is clean and software can compute offsets trivially — a decision about the map, made before any decoder exists.
• What each field is, and how bits are packed. A 32-bit register is a collection of named fields — a 1-bit enable, a 3-bit mode, a 16-bit threshold. How those fields pack into the word (and crucially, whether a field straddles a word boundary or a byte-strobe lane) is a specification choice that determines whether software can update one field without disturbing another.
• What access does — as a contract, not an implementation. "This bit is read-write," "this one is read-only status," "this one clears when you read it," "writing this triggers an action" are access-type declarations. They are part of the spec a driver is written against, and they must be stated per field before the RTL chooses how to realise them.

So the job is not "make some registers" — it is to author a precise, stable contract: addressed, field-packed, and access-typed, that software is written against and hardware must honour exactly.

2. Why previous knowledge is insufficient

Module 11 built the slave's implementation — the typed flop bank, the decoder, the read/write logic. That is the hardware that realises a map. But the implementation is downstream of a decision the RTL chapters took as given: what the map should be. This module supplies that:

• Module 11 assumed the map; this module designs it. The bank chapter said "an RW control register at offset 0, a status register at offset 4" as if those choices were obvious. They are not — addressing, field layout, and per-field access types are design decisions with real consequences (software ergonomics, forward compatibility, atomicity), and getting them wrong cannot be fixed in RTL without breaking the software contract.
• Access "kind" was an RTL property; here it is a software contract. Module 11 implemented RW/RO/W1C as circuits. This module treats them as specification — what the driver is promised, documented in the map, and frozen across silicon revisions. The same circuit can satisfy or violate the contract depending on what the map said; the map is the source of truth.
• The map outlives and constrains the RTL. RTL gets rewritten, re-synthesised, ported. The map cannot change without breaking every driver and validation suite written against it. So the map is the more durable, higher-stakes artifact — and it must be designed as a first-class specification, not emitted as a side effect of coding the slave.

So the model to add is the contract view: the register map as a designed, documented, stable interface — addressing, fields, and access types — that the RTL serves and software depends on.

3. Mental model

The model: a register map is the published API of a chunk of silicon. Like a software API, it has named entry points (registers) at stable addresses, each with typed parameters (fields) and defined behaviour on call (read/write semantics). Firmware is the caller; it binds to the signature, not the implementation. You design an API deliberately — naming, types, versioning, backward compatibility — and you do the same for a register map. A peripheral with great internals and a sloppy map is an unusable library with a great implementation and a terrible interface.

Three refinements make it precise:

• Registers are addressed and aligned like API endpoints. Each register has a fixed byte offset within the peripheral's window, word-aligned, so software addresses it as base + offset. The layout is part of the contract: moving a register is a breaking API change. (Allocation strategy is its own chapter.)
• Fields are typed parameters packed into the word. A register is a struct of named bit-fields, each with a width, a position, a reset value, and an access type. Packing matters: fields that software updates together belong in one register; a field must not straddle a byte-strobe lane if software needs to write it independently, or atomicity breaks.
• Access type is the behavioural part of the signature. Per field, the map declares the read effect and the write effect: RW (read returns last write; write stores), RO (read returns hardware state; write ignored), W1C (read returns flags; write-1 clears), RC (read clears), WO/strobe (write triggers; read defined). The driver is written against these declarations; the hardware must honour them exactly. This is the API's documented behaviour, and it is the heart of CSR design.

4. Real SoC implementation

The map is authored as a specification first — ideally in a machine-readable source (IP-XACT / SystemRDL) that generates the RTL, the C header, and the documentation from one source of truth. Conceptually, a register is a packed struct of typed fields with offsets and reset values; the RTL then realises each field's access type.

// The map as a specification, expressed close to how tooling captures it.
// Each field has: position, width, reset value, and an ACCESS TYPE (the contract).
//
//  Offset  Register  Field        Bits     Reset   Access
//  0x00    CTRL      EN           [0]      0       RW    (enable)
//  0x00    CTRL      MODE         [3:1]    0       RW    (mode select)
//  0x00    CTRL      THRESH       [31:16]  0       RW    (threshold)
//  0x04    STATUS    BUSY         [0]      0       RO    (hardware-driven)
//  0x04    STATUS    CODE         [7:4]    0       RO
//  0x08    IFLAG     DONE         [0]      0       W1C   (write-1 clears)
//  0x0C    CMD       START        [0]      0       WO    (write triggers, read 0)
 
localparam CTRL = 4'h0, STATUS = 4'h4, IFLAG = 4'h8, CMD = 4'hC;
 
// CTRL: an all-RW register — fields packed so software updates them together.
always_ff @(posedge pclk or negedge presetn)
  if (!presetn)        ctrl <= 32'h0;             // reset value IS part of the map
  else if (wr_en_ctrl) ctrl <= wr_data;          // RW contract: write stores
 
// STATUS: RO — the access type says software writes do nothing; only hardware drives it.
assign status = {24'h0, hw_code, 3'h0, hw_busy}; // field positions match the map exactly
 
// Reading honours the map's per-register semantics (e.g. CMD reads as 0).
always_comb unique case (paddr[3:0])
  CTRL:    prdata = ctrl;
  STATUS:  prdata = status;
  IFLAG:   prdata = iflag;
  CMD:     prdata = 32'h0;                        // WO: read returns a defined 0
  default: prdata = 32'h0;
endcase

Two facts make this CSR design and not just coding. First, the field layout, reset values, and access types are decided in the map, then implemented — the RTL's job is to be a faithful realisation of a spec, which is why generating it from a machine-readable map (best practices) eliminates an entire class of map-vs-RTL mismatches. Second, field packing is a software-atomicity decision: EN, MODE, and THRESH share CTRL because firmware sets them together in one write; a field software must change independently belongs in its own register (or at least its own byte-strobe lane), or every update becomes a read-modify-write with a race. The map's structure encodes how software will actually use the peripheral.

5. Engineering tradeoffs

CSR design is a sequence of contract decisions, each trading software ergonomics, area, and future-proofing.

The throughline: every CSR choice is made for the software that will use it. Pack for atomicity, align for clean addressing, type per field for honest semantics, define reset for a known boot state, and generate from one source so the map, the hardware, and the documentation never disagree. The map is a product, and its users are driver writers.

6. Common RTL mistakes

7. Debugging scenario

The signature CSR-design bug is a field-packing atomicity failure: two unrelated fields share a register, and updating one corrupts the other because software has no way to write just one — a defect in the map, not the RTL.

• Observed symptom: a driver that sets the operating MODE field intermittently also disturbs an unrelated THRESH value in the same register, or clears a status bit it never meant to touch. The peripheral misbehaves only when two pieces of firmware (or an ISR and a thread) touch the same register around the same time.
• Waveform clue: on the bus, the MODE update is a full-word write to the shared register — the driver did read CTRL; modify MODE bits; write CTRL — and between its read and its write, another context changed THRESH (or hardware updated a status field packed into the same word). The full-word write-back stamps the stale THRESH over the new one. There is no partial-write protecting the other field because the map packed independently-updated fields together.
• Root cause: the register map packed fields that software updates independently into one register without byte-strobe separation, forcing every single-field update to be a read-modify-write of the whole word — which is not atomic, so concurrent updates race and clobber each other. The bug is in the map's field layout, decided before any RTL.
• Correct RTL: fix the map: place independently-updated fields in separate registers (or in separate byte lanes so PSTRB can write one without the other), so a single-field update is a direct write with no read-modify-write. If the layout cannot change (frozen contract), document that updates to the shared register must hold a lock, and where possible add a SET/CLR alias register so software can change one field atomically without RMW.
• Verification assertion: assert that a write intended for one field never changes another — at the spec level, that each field is independently writable: assert property (@(posedge pclk) disable iff(!presetn) (wr_en_ctrl && pstrb == 4'b0010) |=> $stable(ctrl[31:16]) && $stable(ctrl[0])); (a byte-1-only write leaves the other fields untouched) — and a coverage point that two contexts updated the same register concurrently.
• Debug habit: when "writing field A corrupts field B," do not start in the RTL — open the register map and check whether A and B are independently-updated fields packed into the same word. A huge fraction of CSR bugs are field-packing decisions that forced a non-atomic read-modify-write. The fix is in the map's layout, not the logic.

8. Verification perspective

A register map is verified against its specification — every field's access type, reset value, and independence — and the highest-value automation comes from driving the verification from the same machine-readable map the RTL was generated from.

• Generate the checks from the map. A register abstraction layer (UVM RAL or equivalent) built from the IP-XACT/SystemRDL source gives you, for free, a model that knows every field's offset, reset, and access type. Automated tests then prove the RTL matches the spec: reset values read back correctly, RW fields store, RO fields ignore writes, W1C/RC fields clear as specified. If the map is the source of both RTL and checks, map-vs-RTL drift is structurally impossible.
• Prove field independence and atomicity. Beyond per-field access, assert that writing one field never disturbs another in the same register (the packing contract), and exercise byte-strobed single-field writes to confirm independent fields are independently writable. This is where field-packing bugs surface — a per-register read/write test will pass while the atomicity contract is broken.
• Cover reset, access type, and the corners — not just addresses. Functional coverage must include every field observed at its reset value, every access type exercised (including a write to an RO field and a read of a WO field), and concurrent hardware/software updates to mixed-kind words. An address-only model ("every offset accessed") misses the field-level semantics that are the map's contract.

The point: verify the map as a specification — per-field access type, reset value, and independence — ideally with checks generated from the same source as the RTL, so the contract software relies on is provably what the silicon implements.

9. Interview discussion

"How do you design a register map?" is a strong system-thinking question because a weak answer lists register types while a strong one frames the map as a contract designed for software.

Lead with the framing: a register map is the published API of the peripheral — a stable hardware/software contract — and it is designed before, and independently of, the RTL. Name the three specification axes: addressing (word-aligned offsets, clean base + offset layout), field packing (named bit-fields with widths, positions, and reset values, packed for software atomicity — fields updated together share a register, fields updated independently must not), and access types (RW/RO/W1C/RC/WO as documented per-field behaviour the driver binds to). Then deliver the depth that signals real experience: field packing is an atomicity decision — packing independently-updated fields into one word forces a non-atomic read-modify-write and the classic "writing A corrupts B" bug; reset values are part of the contract because software reads registers at boot; and the map should be machine-readable (IP-XACT/SystemRDL) so the RTL, the C header, the documentation, and the verification all come from one source and cannot drift. Closing with "the RTL implements the map, the map is never reverse-engineered from the RTL" shows you understand which artifact is authoritative.

10. Practice

1. Type a register. Given a peripheral with an enable, a 3-bit mode, a 16-bit threshold, a busy flag, and a done-interrupt flag, lay them out into registers and assign each field a width, offset, reset value, and access type.
2. Pack for atomicity. From the fields above, decide which share a register and which get their own, justifying each by how software updates them.
3. Spell the contract. For each access type (RW/RO/W1C/RC/WO), state the read effect and the write effect a driver can rely on.
4. Align the map. Lay your registers at word-aligned offsets and show how software computes each address as base + offset.
5. Find the atomicity bug. Given a register where setting one field corrupts another, identify the field-packing decision that caused it and the map-level fix.

11. Q&A

12. Key takeaways

• The register map is a hardware/software contract — the peripheral's published API — and it is designed before, and independently of, the RTL that implements it.
• Three specification axes: addressing (word-aligned offsets, clean base + offset), field packing (named typed bit-fields with reset values), and per-field access types (RW/RO/W1C/RC/WO as documented behaviour).
• Field packing is an atomicity decision: pack fields software updates together, separate fields it updates independently (different registers or byte lanes), or every single-field update becomes a racy read-modify-write.
• Reset values are part of the contract — software reads registers at boot, so every visible field needs a defined, documented reset.
• The map should be machine-readable (IP-XACT/SystemRDL) and generate the RTL, the C header, the docs, and the verification from one source, so the contract, the hardware, and the documentation cannot drift.
• Verify the map as a specification — per-field access type, reset value, and independence — ideally with checks generated from the same source as the RTL.