riscv-privileged

RISC-V Privileged Architecture

Purpose

Guide agents through the RISC-V privileged specification: M/S/U privilege modes, CSR registers, trap handling, PLIC and CLINT interrupt controllers, OpenSBI firmware integration, Sv39/Sv48 page tables, and QEMU virt machine testing.

When to Use

• Writing an OS kernel or hypervisor for RISC-V
• Implementing trap handlers and context switch
• Integrating OpenSBI for S-mode firmware services
• Configuring interrupt controllers on QEMU virt or hardware
• Setting up virtual memory with Sv39 or Sv48
• Porting xv6-RISC-V or bare-metal firmware

Workflow

1. Privilege levels

RISC-V privilege stack
├── M-mode (Machine) — firmware, OpenSBI, most privileged
├── S-mode (Supervisor) — OS kernel
└── U-mode (User) — applications

Embedded (no S-mode): M + U only

2. Key CSRs

CSR	Mode	Purpose
mstatus / sstatus	M/S	Interrupt enable, privilege state
mtvec / stvec	M/S	Trap vector base address
mepc / sepc	M/S	Exception PC
mcause / scause	M/S	Trap cause code
mtval / stval	M/S	Faulting address/instruction
satp	S	Page table root (mode + PPN)
mie / sie	M/S	Interrupt enable bits
mip / sip	M/S	Interrupt pending bits

// Read CSR (GCC extended asm)
static inline uint64_t read_csr_satp(void) {
    uint64_t val;
    asm volatile("csrr %0, satp" : "=r"(val));
    return val;
}

// Write CSR
static inline void write_csr_stvec(void *handler) {
    asm volatile("csrw stvec, %0" :: "r"(handler));
}

3. Trap handling

Trap types
├── Synchronous exceptions — ecall, page fault, illegal insn
└── Asynchronous interrupts — timer, external, software

// scause encoding (top bit: 1=interrupt, 0=exception)
void handle_trap(uint64_t scause, uint64_t sepc, uint64_t stval) {
    if (scause & (1UL << 63)) {
        // Interrupt
        switch (scause & 0xff) {
        case 5:  // Supervisor timer interrupt
            timer_interrupt();
            break;
        case 9:  // Supervisor external interrupt
            external_interrupt();
            break;
        }
    } else {
        // Exception
        switch (scause) {
        case 8:   // ecall from U-mode
            handle_syscall();
            break;
        case 12:  // Instruction page fault
        case 13:  // Load page fault
        case 15:  // Store page fault
            handle_page_fault(stval, scause);
            break;
        }
    }
}