Appendix A. CSR Reference

Control and Status Register Quick Reference

💡 Usage Guide: This appendix is your “dashboard” during development. When you need to look up a CSR’s bit positions or operation methods, flip right here.

🛠️ Common CSR Quick Reference

mstatus (Machine Status) Bit Map

This is the most frequently used CSR, controlling interrupts, privilege modes, and other core functions.

63    62    38 37 36   34 33 32   22 21 20 19 18 17   13 12 11 10  9  8  7  6  5  4  3  2  1  0
┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐
│ SD │WPRI│ MBE│ SBE│ SXL│ UXL│WPRI│ TSR│ TW │ TVM│ MXR│ SUM│MPRV│ XS │ FS │ MPP│WPRI│ SPP│MPIE│
└────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘
                                                                   │     │     │
                                                                   │     │     └─ Bit 7: MPIE
                                                                   │     └─ Bit 11-12: MPP
                                                                   └─ Bit 3: MIE

Key Bit Descriptions:

Common Operation Snippets

// 1. Enable Global Interrupt
csrs mstatus, (1 << 3);   // Set MIE bit

// 2. Disable Global Interrupt
csrc mstatus, (1 << 3);   // Clear MIE bit

// 3. Set next mode to S-mode (preparing for mret)
csrc mstatus, (3 << 11);  // Clear MPP
csrs mstatus, (1 << 11);  // Set MPP = 01 (S-mode)

// 4. Read current MPP value
csrr t0, mstatus
srli t0, t0, 11
andi t0, t0, 3            // t0 = MPP (0=U, 1=S, 3=M)

mie / mip (Interrupt Enable/Pending) Reference

These two CSRs control interrupt enable and pending status.

Bit Position Reference:
┌─────────────────────────────────────────────────────────────┐
│  11  │  9   │  7   │  5   │  3   │  1   │                   │
│ MEIE │ SEIE │ MTIE │ STIE │ MSIE │ SSIE │                   │
│  M   │  S   │  M   │  S   │  M   │  S   │                   │
│ Ext  │ Ext  │Timer │Timer │ Soft │ Soft │                   │
└─────────────────────────────────────────────────────────────┘

Common Operations:

// Enable Machine Timer Interrupt
csrs mie, (1 << 7);       // Set MTIE

// Enable Machine External Interrupt
csrs mie, (1 << 11);      // Set MEIE

// Check if Timer Interrupt is Pending
csrr t0, mip
andi t0, t0, (1 << 7)     // t0 != 0 means Timer interrupt pending

mcause (Machine Cause) Decode Table

When a trap occurs, mcause tells you the reason.

Interrupt (mcause[63] = 1):

Exception (mcause[63] = 0):

Trap Handler Example:

void trap_handler() {
    uint64_t cause;
    asm volatile ("csrr %0, mcause" : "=r" (cause));

    if (cause & (1UL << 63)) {
        // Interrupt
        uint64_t code = cause & 0x7FF;
        switch (code) {
            case 7:  handle_timer_interrupt(); break;
            case 11: handle_external_interrupt(); break;
        }
    } else {
        // Exception
        switch (cause) {
            case 2:  handle_illegal_instruction(); break;
            case 7:  handle_store_access_fault(); break;
            case 8:  handle_ecall_from_umode(); break;
        }
    }
}

This appendix provides a comprehensive reference for RISC-V Control and Status Registers (CSRs). CSRs control processor behavior, report status, and provide access to privileged functionality. Each CSR has a 12-bit address and is accessed using dedicated CSR instructions (CSRRW, CSRRS, CSRRC, and their immediate variants).

A.1 CSR Address Space Organization

CSR addresses are 12 bits, organized as follows:

Bits [11:10]: Privilege Level
  00 = User/Unprivileged
  01 = Supervisor
  10 = Hypervisor (reserved in base spec)
  11 = Machine

Bits [9:8]: Read/Write Access
  00 = Read/Write
  01 = Read/Write
  10 = Read/Write
  11 = Read-Only

Bits [7:0]: Register Number

Access Rules:

• Accessing a CSR from insufficient privilege level causes an illegal instruction exception
• Writing to a read-only CSR (bits [11:10] = 11) causes an illegal instruction exception
• Unimplemented CSRs may read as zero or cause an exception (implementation-defined)

A.2 Machine-Level CSRs (M-mode)

Machine Information Registers

Usage: These read-only CSRs identify the processor implementation. Software can use them to detect features, apply workarounds, or report system information.

Example:

csrr t0, mhartid        # Read hart ID
csrr t1, mvendorid      # Read vendor ID

Machine Trap Setup

Machine Trap Handling

Machine Memory Protection

Note: RV32 uses pmpcfg0, pmpcfg2, pmpcfg4, etc. (even-numbered only). RV64 uses pmpcfg0, pmpcfg2, pmpcfg4, etc., with each holding 8 configuration bytes.

Machine Counters and Timers

Machine Counter Setup

Usage: mcountinhibit controls which counters are active. Setting bit N stops counter N from incrementing, saving power.

A.3 Supervisor-Level CSRs (S-mode)

Supervisor Trap Setup

Supervisor Trap Handling

Supervisor Address Translation and Protection

satp Format (RV64):

Bits [63:60]: Mode (0=Bare, 8=Sv39, 9=Sv48, 10=Sv57)
Bits [59:44]: ASID (Address Space Identifier)
Bits [43:0]:  PPN (Physical Page Number of root page table)

A.4 User-Level CSRs (U-mode)

Floating-Point Control and Status

fflags Bits:

• Bit 0: NV (Invalid Operation)
• Bit 1: DZ (Divide by Zero)
• Bit 2: OF (Overflow)
• Bit 3: UF (Underflow)
• Bit 4: NX (Inexact)

frm Values:

• 0: RNE (Round to Nearest, ties to Even)
• 1: RTZ (Round towards Zero)
• 2: RDN (Round Down, towards -∞)
• 3: RUP (Round Up, towards +∞)
• 4: RMM (Round to Nearest, ties to Max Magnitude)

User Counters and Timers

Note: These are read-only shadows of the machine-level counters. Access can be disabled by mcounteren (for S-mode) or scounteren (for U-mode).

A.5 Debug CSRs

Debug CSRs are accessible only in Debug Mode (entered via debugger or trigger).

dcsr Bit Fields:

• Bits [31:28]: xdebugver (Debug specification version)
• Bits [8:6]: cause (Reason for entering debug mode)
  • 1: ebreak instruction
  • 2: Trigger module
  • 3: Debugger halt request
  • 4: Single step
  • 5: Reset halt
• Bit [2]: step (Single-step mode enable)
• Bits [1:0]: prv (Privilege level before entering debug mode)

A.6 Trigger/Debug Module CSRs

Usage: Triggers enable hardware breakpoints and watchpoints. tselect chooses which trigger to configure, tdata1-3 configure the selected trigger.

A.7 Key CSR Bit Fields

mstatus (Machine Status Register)

RV64 Format:

Bit  63: SD (State Dirty - summary of FS/XS)
Bits 36-37: SXL (S-mode XLEN)
Bits 34-35: UXL (U-mode XLEN)
Bit  22: TSR (Trap SRET)
Bit  21: TW (Timeout Wait - trap WFI)
Bit  20: TVM (Trap Virtual Memory - trap SATP writes)
Bit  19: MXR (Make eXecutable Readable)
Bit  18: SUM (permit Supervisor User Memory access)
Bit  17: MPRV (Modify PRiVilege)
Bits 15-16: XS (user eXtension State)
Bits 13-14: FS (Floating-point State)
Bits 11-12: MPP (Machine Previous Privilege)
Bit  8: SPP (Supervisor Previous Privilege)
Bit  7: MPIE (Machine Previous Interrupt Enable)
Bit  5: SPIE (Supervisor Previous Interrupt Enable)
Bit  3: MIE (Machine Interrupt Enable)
Bit  1: SIE (Supervisor Interrupt Enable)

FS/XS Values:

• 0: Off (all off)
• 1: Initial (none dirty, some on)
• 2: Clean (none dirty, some on)
• 3: Dirty (some dirty)

MPP/SPP Values:

• 0: User mode
• 1: Supervisor mode
• 3: Machine mode

mtvec (Machine Trap Vector)

Format:

Bits [XLEN-1:2]: BASE (trap handler base address, 4-byte aligned)
Bits [1:0]: MODE
  0 = Direct (all traps to BASE)
  1 = Vectored (interrupts to BASE + 4*cause, exceptions to BASE)

Example:

la t0, trap_handler
csrw mtvec, t0          # Direct mode (MODE=0)

la t0, trap_handler
ori t0, t0, 1           # Set MODE=1
csrw mtvec, t0          # Vectored mode

mcause (Machine Cause Register)

Format:

• Bit [XLEN-1]: Interrupt (1=interrupt, 0=exception)
• Bits [XLEN-2:0]: Exception Code

Exception Codes (Interrupt=0):

Interrupt Codes (Interrupt=1):

satp (Supervisor Address Translation and Protection)

RV64 Format:

Bits [63:60]: MODE
  0 = Bare (no translation)
  8 = Sv39 (39-bit virtual address)
  9 = Sv48 (48-bit virtual address)
  10 = Sv57 (57-bit virtual address)
Bits [59:44]: ASID (Address Space Identifier, 16 bits)
Bits [43:0]: PPN (Physical Page Number of root page table, 44 bits)

RV32 Format:

Bit [31]: MODE (0=Bare, 1=Sv32)
Bits [30:22]: ASID (9 bits)
Bits [21:0]: PPN (22 bits)

Example:

# Switch to Sv39 mode with ASID=1, root page table at 0x80200000
li t0, 0x8000000000080200  # MODE=8, ASID=0, PPN=0x80200
csrw satp, t0
sfence.vma                 # Flush TLB

A.8 CSR Instructions Quick Reference

Pseudo-instructions:

csrr rd, csr        # Read CSR (csrrs rd, csr, x0)
csrw csr, rs1       # Write CSR (csrrw x0, csr, rs1)
csrs csr, rs1       # Set bits (csrrs x0, csr, rs1)
csrc csr, rs1       # Clear bits (csrrc x0, csr, rs1)
csrwi csr, imm      # Write immediate (csrrwi x0, csr, imm)
csrsi csr, imm      # Set bits immediate (csrrsi x0, csr, imm)
csrci csr, imm      # Clear bits immediate (csrrci x0, csr, imm)

A.9 Common CSR Usage Patterns

Enable Machine-Mode Interrupts

# Enable machine timer and external interrupts
li t0, 0x88             # MTIE (bit 7) + MEIE (bit 11)
csrs mie, t0            # Set bits in mie

# Enable global interrupts
li t0, 0x8              # MIE (bit 3)
csrs mstatus, t0        # Set MIE in mstatus

Trap Handler Entry

trap_handler:
    # Save context
    csrrw sp, mscratch, sp  # Swap sp with mscratch

    # Save registers on stack
    addi sp, sp, -32*8
    sd x1, 0(sp)
    sd x2, 8(sp)
    # ... save all registers ...

    # Read trap cause
    csrr t0, mcause
    csrr t1, mepc
    csrr t2, mtval

    # Handle trap...

Context Switch (Change satp)

# Switch to new process page table
# a0 = new satp value
csrw satp, a0
sfence.vma              # Flush TLB

Disable Interrupts for Critical Section

# Save and disable interrupts
csrrci t0, mstatus, 0x8  # Clear MIE, save old mstatus

# Critical section...

# Restore interrupts
csrw mstatus, t0         # Restore original mstatus

A.10 CSR Access Permissions

Privilege Level Check:

• CSR address bits [11:10] encode minimum privilege level
• Accessing CSR from lower privilege → illegal instruction exception

Read-Only Check:

• CSR address bits [11:10] = 11 → read-only
• Writing to read-only CSR → illegal instruction exception

Implementation-Defined Behavior:

• Unimplemented CSRs may:
  • Read as zero, writes ignored (WARL - Write Any, Read Legal)
  • Cause illegal instruction exception
  • Implementation must document behavior

A.11 References

• RISC-V Privileged Specification: Complete CSR definitions and bit fields
• RISC-V Debug Specification: Debug CSRs (dcsr, dpc, tselect, tdata)
• RISC-V ISA Manual: CSR instructions and access rules