RISC-V Emulation

# RISC-V Emulation

## CS 631 Systems Foundations — Mar 26, 2026

---

## Today's Agenda

1. What is an emulator?
2. Emulator state in Rust
3. The fetch-decode-execute loop
4. Unsafe Rust for emulation
5. R-type instructions
6. I-type instructions
7. Loads and stores (detailed)
8. Branches and jumps
9. Incremental development strategy

---

## What is an Emulator?

Software that **mimics hardware behavior**:

- Maintains registers, PC, stack in software
- Reads real RISC-V machine code from memory
- Decodes each instruction and performs the operation
- Updates state (registers, memory, PC)

<div class="info-box">
Our emulator executes the <strong>same machine code</strong> that a physical RISC-V processor would run.
</div>

---

## Emulator State: RvState

```rust
const RV_NUM_REGS: usize = 32;
const STACK_SIZE: usize = 8192;

pub struct RvState {
    pub regs: [u64; RV_NUM_REGS],  // 32 general-purpose registers
    pub pc: *const u8,              // Program counter (raw pointer)
    pub stack: [u8; STACK_SIZE],    // Emulated stack memory
}
```

- **`regs`**: 32 registers, each 64 bits wide
- **`pc`**: Raw pointer to current instruction in memory
- **`stack`**: 8KB array for the emulated stack

---

## Why a Raw Pointer for PC?

`pc: *const u8` — not a reference, not an integer

1. **Points to real memory** — compiled assembly lives at actual addresses
2. **Pointer arithmetic** — advance by 4 bytes, jump by signed offsets
3. **Dereference to fetch** — cast to `*const u32` to read instruction word

```rust
// Fetch instruction word at PC
let iw = unsafe { *(state.pc as *const u32) };

// Advance PC to next instruction
state.pc = unsafe { state.pc.add(4) };
```

---

## ABI Register Constants

```rust
const RV_ZERO: usize = 0;   // x0 — hardwired zero
const RV_RA: usize = 1;     // x1 — return address
const RV_SP: usize = 2;     // x2 — stack pointer
const RV_A0: usize = 10;    // x10 — arg 0 / return value
const RV_A1: usize = 11;    // x11 — arg 1
const RV_A2: usize = 12;    // x12 — arg 2
const RV_A3: usize = 13;    // x13 — arg 3
```

Type is `usize` so they work directly as array indices: `state.regs[RV_A0]`

---

## Initialization

```rust
pub fn rv_init(state: &mut RvState, target: *const u32,
               a0: u64, a1: u64, a2: u64, a3: u64) {
    state.pc = target as *const u8;
    state.regs[RV_A0] = a0;
    state.regs[RV_A1] = a1;
    state.regs[RV_A2] = a2;
    state.regs[RV_A3] = a3;
    state.regs[RV_ZERO] = 0;
    state.regs[RV_RA] = 0; // Halt sentinel
    state.regs[RV_SP] = unsafe {
        state.stack.as_ptr().add(STACK_SIZE) as u64
    };
}
```

- **`target`**: function pointer → address of first instruction
- **`ra = 0`**: null = halt sentinel
- **`sp`**: points to top of stack (stack grows down)

---

## The Fetch-Decode-Execute Loop

```rust
pub fn rv_emulate(state: &mut RvState) -> u64 {
    while !state.pc.is_null() {
        rv_one(state);
        state.regs[RV_ZERO] = 0;  // x0 must always be 0
    }
    state.regs[RV_A0]  // Return value
}
```

Loop until PC is null. After each instruction, force `x0 = 0`.

<div class="highlight-box">
<strong>Why reset x0?</strong> If an instruction writes to x0, the hardware discards it. We simulate this by resetting it after every instruction.
</div>

---

## Executing One Instruction

```rust
fn rv_one(state: &mut RvState) {
    // FETCH
    let iw = unsafe { *(state.pc as *const u32) };

// DECODE
    let opcode = get_bits(iw as u64, 0, 7);

// EXECUTE
    match opcode {
        FMT_R       => run_r_format(state, iw),
        FMT_I_ARITH => run_i_arith(state, iw),
        FMT_I_JALR  => run_i_jalr(state, iw),
        _           => unsupported("format", opcode),
    }
}
```

---

## Opcode Constants

```rust
const FMT_R: u32       = 0b0110011;  // add, sub, mul, ...
const FMT_RW: u32      = 0b0111011;  // sllw, srlw, sraw
const FMT_I_JALR: u32  = 0b1100111;  // jalr
const FMT_I_ARITH: u32 = 0b0010011;  // addi, slli, ...
```

The opcode (bits [6:0]) determines which format handler to call.

---

## Bit Manipulation Recap

```rust
pub fn get_bits(num: u64, start: u32, count: u32) -> u32 {
    let mask: u64 = (1u64 << count) - 1;
    ((num >> start) & mask) as u32
}

pub fn get_bit(num: u64, which: u32) -> bool {
    ((num >> which) & 1) != 0
}

pub fn sign_extend(num: u64, start: u32) -> i64 {
    let dist = 64 - start;
    let shifted = (num << dist) as i64;
    shifted >> dist
}
```

Same functions from the Machine Code lecture.

---

## Unsafe Rust: Why We Need It

The emulator requires operations Rust cannot verify at compile time:

| Operation | Why Unsafe |
|-----------|-----------|
| `*(pc as *const u32)` | Dereference raw pointer |
| `pc.add(4)` | Pointer arithmetic |
| `pc.offset(n)` | Signed pointer arithmetic |
| `read_unaligned(addr as *const T)` | Read arbitrary address |
| `write_unaligned(addr as *mut T, v)` | Write arbitrary address |

All wrapped in `unsafe { ... }` blocks.

---

## Pointer Operations

| Operation | Code | Use |
|-----------|------|-----|
| Advance PC | `pc.add(4)` | Next instruction (+4 bytes) |
| Branch/Jump | `pc.offset(n as isize)` | Signed byte offset |
| Read memory | `std::ptr::read_unaligned(addr as *const T)` | Load instructions |
| Write memory | `std::ptr::write_unaligned(addr as *mut T, v)` | Store instructions |
| Int → Pointer | `sum as *const u8` | JALR target |
| Pointer → Int | `pc as u64` | Save return address |

<div class="info-box">
<code>add(n)</code> = unsigned offset, <code>offset(n)</code> = signed offset
</div>

---

## R-Type Format

```
┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ funct7   │ rs2      │ rs1      │ funct3   │ rd       │ opcode   │
│ [31:25]  │ [24:20]  │ [19:15]  │ [14:12]  │ [11:7]   │ [6:0]    │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
```

Operation determined by **(funct3, funct7)** tuple:

| funct3 | funct7 = 0b0000000 | funct7 = 0b0100000 | funct7 = 0b0000001 |
|--------|-------------------|-------------------|-------------------|
| 000 | ADD | SUB | MUL |
| 001 | SLL | — | — |
| 100 | XOR | — | DIV |
| 101 | SRL | SRA | — |
| 111 | AND | — | — |

---

## R-Type Implementation

```rust
fn run_r_format(s: &mut RvState, iw: u32) {
    let rd = get_rd(iw);
    let funct3 = get_funct3(iw);
    let funct7 = get_funct7(iw);
    let rs1 = get_rs1(iw);
    let rs2 = get_rs2(iw);

match (funct3, funct7) {
        (0b000, 0b0000000) => { // ADD
            s.regs[rd] = s.regs[rs1].wrapping_add(s.regs[rs2]);
        }
        // ... other (funct3, funct7) values
        _ => unsupported("R-type funct3", funct3),
    }
    s.pc = unsafe { s.pc.add(4) };
}
```

---

## Wrapping Arithmetic

Rust panics on unsigned overflow in debug mode!

```rust
// WRONG — panics if overflow occurs in debug:
s.regs[rd] = s.regs[rs1] + s.regs[rs2];

// CORRECT — wraps like RISC-V hardware:
s.regs[rd] = s.regs[rs1].wrapping_add(s.regs[rs2]);
```

<div class="highlight-box">
Use <code>wrapping_add</code>, <code>wrapping_sub</code>, <code>wrapping_mul</code>, <code>wrapping_div</code> for all arithmetic operations.
</div>

---

## I-Type Format (Three Variants)

```
┌──────────────┬──────────┬──────────┬──────────┬──────────┐
│ imm[11:0]    │ rs1      │ funct3   │ rd       │ opcode   │
│ [31:20]      │ [19:15]  │ [14:12]  │ [11:7]   │ [6:0]    │
└──────────────┴──────────┴──────────┴──────────┴──────────┘
```

| Variant | Opcode | Instructions |
|---------|--------|-------------|
| I_ARITH | `0010011` | addi, slli, srli, srai |
| I_LOAD | `0000011` | lb, lw, ld |
| I_JALR | `1100111` | jalr |

Same format, different opcodes — each handled by its own function.

---

## I-Type: Arithmetic (run_i_arith)

```rust
fn run_i_arith(s: &mut RvState, iw: u32) {
    let rd = get_rd(iw);
    let funct3 = get_funct3(iw);
    let v1 = s.regs[get_rs1(iw)];
    let imm = sign_extend(get_bits(iw as u64, 20, 12) as u64, 12);
    let shamt = get_bits(iw as u64, 20, 6);

match funct3 {
        0b000 => { s.regs[rd] = v1.wrapping_add(imm as u64); } // ADDI
        0b001 => { s.regs[rd] = v1 << shamt; }                 // SLLI
        0b101 => { /* SRLI / SRAI depending on bit 30 */ }
        _ => unsupported("I-arith funct3", funct3),
    }
    s.pc = unsafe { s.pc.add(4) };
}
```

---

## I-Type: JALR (run_i_jalr)

```rust
fn run_i_jalr(s: &mut RvState, iw: u32) {
    let rd = get_rd(iw);
    let v1 = s.regs[get_rs1(iw)];
    let imm = sign_extend(get_bits(iw as u64, 20, 12) as u64, 12);
    let target = v1.wrapping_add(imm as u64);

if rd != 0 {
        s.regs[rd] = (s.pc as u64).wrapping_add(4);
    }
    s.pc = target as *const u8;  // Don't advance PC!
}
```

<div class="highlight-box">
<strong>JALR</strong> sets PC directly — no <code>pc.add(4)</code> needed.
</div>

---

## Load Instructions

Loads read data from memory into a register.

**Computing the target address:**
```rust
let base: u64 = s.regs[get_rs1(iw)];    // e.g., sp value
let imm = sign_extend(get_bits(iw as u64, 20, 12) as u64, 12);
let addr: u64 = base.wrapping_add(imm as u64);
```

**Reading from memory:**
```rust
fn run_load(width: u32, addr: u64) -> u64 {
    unsafe {
        match width {
            0 => std::ptr::read_unaligned(addr as *const u8) as u64,
            3 => std::ptr::read_unaligned(addr as *const u64),
            _ => panic!("unsupported load width"),
        }
    }
}
```

---

## Why `read_unaligned`?

Normal dereference requires **aligned** pointers:
- `*const u32` must be 4-byte aligned
- `*const u64` must be 8-byte aligned

RISC-V code may compute arbitrary addresses.

```rust
// May cause undefined behavior if addr is not aligned:
let value = unsafe { *(addr as *const u32) };

// Works regardless of alignment:
let value = unsafe {
    std::ptr::read_unaligned(addr as *const u32)
};
```

<div class="info-box">
Always use <code>read_unaligned</code> / <code>write_unaligned</code> for emulator memory access.
</div>

---

## The Integer-to-Pointer Cast

Registers hold **integers** that represent **memory addresses**:

```rust
let addr: u64 = base + offset;  // This is a number

// Cast to pointer to read memory at that address
let ptr: *const u32 = addr as *const u32;
let value: u32 = unsafe {
    std::ptr::read_unaligned(ptr)
};

// Widen to 64 bits for the register
s.regs[rd] = value as u64;
```

---

## Load Width (funct3)

| funct3 | Instruction | Bytes | Pointer Type |
|--------|-------------|-------|-------------|
| `000` | `lb` | 1 | `*const u8` |
| `010` | `lw` | 4 | `*const u32` |
| `011` | `ld` | 8 | `*const u64` |

All values widened to `u64` with `as u64` before storing in the register.

---

## S-Type Format (Stores)

```
┌──────────────┬──────────┬──────────┬──────────┬──────────────┬──────────┐
│ imm[11:5]    │ rs2      │ rs1      │ funct3   │ imm[4:0]     │ opcode   │
│ [31:25]      │ [24:20]  │ [19:15]  │ [14:12]  │ [11:7]       │ [6:0]    │
└──────────────┴──────────┴──────────┴──────────┴──────────────┴──────────┘
```

The immediate is **split** across two fields!

**Reassemble:**
```rust
let off_4_0 = get_bits(iw as u64, 7, 5);    // bits [11:7]
let off_11_5 = get_bits(iw as u64, 25, 7);  // bits [31:25]
let offset = (off_11_5 << 5) | off_4_0;     // 12-bit offset
```

---

## Store Implementation

```rust
fn run_s_format(s: &mut RvState, iw: u32) {
    let off_4_0 = get_bits(iw as u64, 7, 5);
    let off_11_5 = get_bits(iw as u64, 25, 7);
    let offset = (off_11_5 << 5) | off_4_0;
    let width = get_funct3(iw);
    let rs1 = get_rs1(iw);
    let rs2 = get_rs2(iw);

let target = s.regs[rs1].wrapping_add(offset as u64);

unsafe {
        match width {
            0 => std::ptr::write_unaligned(
                     target as *mut u8, s.regs[rs2] as u8),
            3 => std::ptr::write_unaligned(
                     target as *mut u64, s.regs[rs2]),
            _ => panic!("unsupported store width"),
        }
    }
    s.pc = unsafe { s.pc.add(4) };
}
```

---

## Loads vs Stores

| | Load | Store |
|---|------|-------|
| Direction | Memory → Register | Register → Memory |
| Pointer type | `*const T` | `*mut T` |
| Function | `read_unaligned` | `write_unaligned` |
| Width cast | Widen: `as u64` | Truncate: `as u8/u32` |

```rust
// Load: read from memory into register
s.regs[rd] = read_unaligned(addr as *const u32) as u64;

// Store: write register value to memory
write_unaligned(addr as *mut u32, s.regs[rs2] as u32);
```

---

## B-Type Format (Branches)

```
┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ imm[12]  │ imm[10:5]│ rs2      │ rs1      │ funct3   │ imm[4:1] │ imm[11]  │ opcode   │
│ [31]     │ [30:25]  │ [24:20]  │ [19:15]  │ [14:12]  │ [11:8]   │ [7]      │ [6:0]    │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
```

Immediate bits are **scattered** for hardware efficiency.

| funct3 | Instruction | Condition |
|--------|-------------|-----------|
| 000 | BEQ | `v1 == v2` |
| 001 | BNE | `v1 != v2` |
| 100 | BLT | `(v1 as i64) < (v2 as i64)` |
| 101 | BGE | `(v1 as i64) >= (v2 as i64)` |

---

## Branch Offset Reconstruction

```rust
fn b_offset(iw: u32) -> i64 {
    let bit12 = if get_bit(iw as u64, 31) { 1u32 } else { 0 };
    let bit11 = if get_bit(iw as u64, 7) { 1u32 } else { 0 };
    let bits10_5 = get_bits(iw as u64, 25, 6);
    let bits4_1 = get_bits(iw as u64, 8, 4);

let offset = (bit12 << 12) | (bit11 << 11)
               | (bits10_5 << 5) | (bits4_1 << 1);
    sign_extend(offset as u64, 13)
}
```

Bit 0 is always 0 (2-byte alignment).

---

## Branch Implementation

```rust
fn run_b_format(s: &mut RvState, iw: u32) {
    let v1 = s.regs[get_rs1(iw)];
    let v2 = s.regs[get_rs2(iw)];

let taken = match get_funct3(iw) {
        0b000 => v1 == v2,                    // BEQ
        0b100 => (v1 as i64) < (v2 as i64),   // BLT
        _ => unsupported("B-type funct3", get_funct3(iw)),
    };

if taken {
        s.pc = unsafe { s.pc.offset(b_offset(iw) as isize) };
    } else {
        s.pc = unsafe { s.pc.add(4) };
    }
}
```

---

## Signed vs Unsigned Comparison

Registers store `u64`. For signed branches, cast to `i64`:

```rust
// Unsigned: 0xFFFFFFFFFFFFFFFF = 18446744073709551615
// Signed:   0xFFFFFFFFFFFFFFFF = -1

let v1: u64 = 0xFFFFFFFFFFFFFFFF;

v1 > 0           // true (unsigned)
(v1 as i64) > 0  // false (signed, -1 < 0)
```

<div class="highlight-box">
<code>as i64</code> reinterprets the bits as two's complement — no data changes, just interpretation.
</div>

---

## J-Type (JAL)

```rust
fn run_j_format(s: &mut RvState, iw: u32) {
    let rd = get_rd(iw);
    if rd != 0 {
        s.regs[rd] = (s.pc as u64).wrapping_add(4);
    }

// Reconstruct scattered immediate...
    let signed_offset = sign_extend(offset as u64, 20)
                            .wrapping_mul(2);

s.pc = unsafe { s.pc.offset(signed_offset as isize) };
}
```

- **`jal ra, label`** — saves return address in ra, jumps
- **`j label`** — pseudo for `jal x0, label` (rd=0, link discarded)

---

## Stopping the Emulator

```rust
// Init: ra = 0 (null)
state.regs[RV_RA] = 0;

// When function executes 'ret' (= jalr x0, 0(ra)):
//   PC = ra + 0 = null

// Loop exits:
while !state.pc.is_null() { ... }
```

<div class="mermaid">
flowchart LR
    A["rv_init:<br>ra = null"] --> B["Execute<br>instructions"]
    B --> C{"pc.is_null()?"}
    C -->|No| B
    C -->|Yes| D["Return<br>regs[a0]"]
</div>

---

## Incremental Development

Start simple, add instructions as needed:

1. **quadratic** — addi, add, sub, mul, jalr
2. **midpoint** — adds srai
3. **max3** — adds branches (bge, blt), jal
4. **get_bitseq** — adds sll, srl, and
5. **to_upper** — adds lb, sb (byte memory)
6. **swap** — adds lw, sw (word memory)
7. **sort** — adds sd, ld (doubleword, function calls)
8. **fib_rec** — recursive calls (heavy stack usage)

<div class="info-box">
Run the emulator — see which instruction is unsupported — implement it — repeat.
</div>

---

## Key Takeaways

- **Emulator** = software CPU: fetch, decode, execute loop in Rust
- **Raw pointers** (`*const u8`) for PC — `unsafe` for all pointer ops
- **`read_unaligned` / `write_unaligned`** for loads and stores
- **`wrapping_add/sub/mul`** to match RISC-V overflow behavior
- **`as i64`** for signed comparisons in branches
- **Null PC** = halt sentinel (ra initialized to 0)
- **Build incrementally** — one instruction at a time

---

## Next Lecture

- Dynamic analysis (instruction counting)
- Cache simulation (direct-mapped, set-associative)