# VM 8-Segment Translation Cheat Sheet

*VCA-CSA-101 cross-chapter quick-reference handout. Anchor: §7.6 + Ch 8 §8.5-§8.7. *

**Purpose:** complete reference for the eight memory segments the Virtus VM exposes and the RV32I-Lite assembly each `push X i` / `pop X i` translates to. Print and pin during Lab 7.1 (stack arithmetic), Lab 7.2 (segment translator), Lab 7.3 (capstone end-to-end), Lab 8.1-8.4 (function-call protocol). Every memory access in any `.vm` source file the student writes lands on one of these eight segments; every emission pattern is one of the three translation strategies catalogued below.

---

## At a glance

| Property | Value |
|---|---|
| Total segments | **8** (`constant`, `argument`, `local`, `static`, `this`, `that`, `pointer`, `temp`) |
| Translation strategies | **3** (runtime base register / direct-address mapping / translation-time symbol) |
| Stack growth | **Upward** (Nand2Tetris convention; CSA-201 reconciles to real-RISC-V's downward) |
| `sp` register | `x2` per RV32I ABI; points at next-free slot |
| Primitive cost | Every `push`/`pop` ≈ 2 RV32I-Lite instructions |
| Typical bloat | ~5-7 RV32I-Lite instructions per memory-touching VM command |

---

## The 8 segments. Overview table

| Segment | Translation strategy | Lifetime | Per-instance? | Lab introduced |
|---|---|---|---|---|
| `constant` | No memory; immediate value | Compile-time | - | 7.1 |
| `argument` | Runtime base register (`ARG`) | Per-call | yes | 7.2, 8.5 |
| `local` | Runtime base register (`LCL`) | Per-call | yes | 7.2, 8.5 |
| `this` | Runtime base register (`THIS`) | Per-call object follow-through | yes | 7.2 |
| `that` | Runtime base register (`THAT`) | Per-call object follow-through | yes | 7.2 |
| `pointer` | Direct-address mapping → `THIS`/`THAT` registers | Per-program-shared | no | 7.2 |
| `temp` | Direct-address mapping → 8 fixed slots | Per-program-shared scratch | no | 7.2 |
| `static` | Translation-time symbol → linker-resolved `.data` slot | Per-source-file globals | no | 7.2 |

**The three lifetime classes drive the three translation strategies:**
- **Per-call** (`argument`, `local`, `this`, `that`) → runtime base register held at fixed memory location; the *callee's* call-protocol prologue writes the per-call value into the base-register slot.
- **Per-program-shared** (`pointer`, `temp`) → fixed memory addresses; same for every call.
- **Per-source-file globals** (`static`) → translation-time symbol; the linker resolves to a `.data` slot the assembler reserved.

---

## Memory map: where each segment lives at runtime

```
Virtus Console runtime memory layout (Ch 12 §12.2):

0x00000000 ─── OS .text (16 KiB)               ── (immutable; FPGA-init)
0x00004000 ─── OS .data + .bss (16 KiB)
       ├─ 0x00004400  Memory._free_head
       ├─ 0x00004??? Screen state / Keyboard state / Sound state
       └─ ...
0x00008000 ─── Application .text (32 KiB)      ── (immutable; FPGA-init)
0x00010000 ─── Application heap (16 KiB)       ── managed by Memory.alloc/dealloc
0x00010000 ─── ALSO the VM segment-base region:
       ├─ 0x00010000  LCL_addr     ← `local` segment base pointer
       ├─ 0x00010004  ARG_addr     ← `argument` segment base pointer
       ├─ 0x00010008  THIS_addr    ← `this` segment base pointer
       ├─ 0x0001000C  THAT_addr    ← `that` segment base pointer
       ├─ 0x00010010  temp[0]      ← fixed `temp` slot 0
       ├─ 0x00010014  temp[1]
       ├─ 0x00010018  temp[2]
       ├─ ...
       └─ 0x0001002C  temp[7]      ← fixed `temp` slot 7
0x00010030 ─── stack (grows upward)            ── sp initialised here
0x00014000 ─── application data heap continues
0x80000000 ─── HDMI framebuffer (peripheral)
0x80010000 ─── VCP shared memory (peripheral)
0x80020000 ─── GPIO/GamePad decoder (peripheral; DS2 protocol)
0x80030000 ─── system control (peripheral)
```

`static` storage lives in `.data` at addresses the linker resolves at link time; per-file naming convention `static.<basename>.<i>` keeps each file's statics distinct (see §static naming below).

---

## Stack discipline

Every memory-touching VM command bottoms out on the stack, accessed via `sp` (= `x2`).

```
sp always points at the NEXT FREE SLOT (one past the topmost occupied word).

push:  M[sp] = value;  sp += 4
pop:   sp -= 4;        value = M[sp]
```

**Push / pop primitives in RV32I-Lite (the building block for every emission pattern):**

```asm
# push (value in t0 → top of stack)
sw   t0, 0(sp)
addi sp, sp, 4

# pop (top of stack → t0)
addi sp, sp, -4
lw   t0, 0(sp)
```

**2 instructions per primitive.** Every translation pattern below is `<address arithmetic> + <push or pop primitive>`.

---

## Strategy 1: Runtime base register

Used by `argument`, `local`, `this`, `that`. **The base address is itself stored at a fixed memory location** (per the memory map above); the translator emits a load-then-add-offset-then-load/store pattern.

### `push <segment> i`. Read from segment

```asm
# push <segment> i  (segment ∈ {local, argument, this, that})
lw   t1, 0(<SEGMENT>_addr)    # t1 = base address of segment
addi t1, t1, 4*i              # t1 = address of segment[i]
lw   t0, 0(t1)                # t0 = M[base + 4*i] = segment[i]
sw   t0, 0(sp)                # push t0
addi sp, sp, 4
```

**5 instructions** plus whatever the assembler needs to materialise `<SEGMENT>_addr` (typically one extra `lw` via `.data`-resident pointer indirection because RV32I-Lite has no `lui`).

### `pop <segment> i`. Write to segment

```asm
# pop <segment> i  (segment ∈ {local, argument, this, that})
addi sp, sp, -4               # decrement sp first
lw   t0, 0(sp)                # t0 = top-of-stack value
lw   t1, 0(<SEGMENT>_addr)    # t1 = base address
addi t1, t1, 4*i              # t1 = address of segment[i]
sw   t0, 0(t1)                # M[base + 4*i] = t0
```

**5 instructions.** The ordering (pop first, then compute address) matters: it uses 2 temp registers (`t0` for value, `t1` for address) instead of 3, which fits the chapter's two-temp convention.

### Mapping table

| VM segment | Base register location | Set by |
|---|---|---|
| `local` | `LCL_addr` at `0x00010000` | Caller's `call` protocol (Ch 8 §8.6) |
| `argument` | `ARG_addr` at `0x00010004` | Caller's `call` protocol |
| `this` | `THIS_addr` at `0x00010008` | Method prologue (Ch 8 §8.5) or `pop pointer 0` |
| `that` | `THAT_addr` at `0x0001000C` | `pop pointer 1` from VM source |

---

## Strategy 2: Direct-address mapping

Used by `pointer` and `temp`. **The segment's address range is fixed at translation time**; the translator emits a direct-address load.

### `pointer` segment. Exposes THIS/THAT registers themselves

The `pointer` segment is a **two-slot segment** that aliases the THIS and THAT registers:
- `pointer 0` ↔ `THIS`
- `pointer 1` ↔ `THAT`

```asm
# push pointer 0
lw   t0, 0(THIS_addr)         # t0 = current THIS
sw   t0, 0(sp)
addi sp, sp, 4

# pop pointer 0  (sets THIS register)
addi sp, sp, -4
lw   t0, 0(sp)
sw   t0, 0(THIS_addr)
```

**3 instructions per `pop pointer 0`**, the simplest of all segments because no base+offset arithmetic.

`pop pointer 0` is the canonical idiom for *establishing `this`* in a method body:

```vm
push argument 0           # push the receiver (caller's `this`)
pop  pointer 0            # set THIS to the receiver
```

Indices outside `0..1` are illegal and must be diagnosed by the translator.

### `temp` segment, 8 fixed scratch slots

The `temp` segment is an **eight-slot scratch region** at fixed addresses:
- `temp 0` → `0x00010010`
- `temp 1` → `0x00010014`
- ...
- `temp 7` → `0x0001002C`

```asm
# push temp i
lw   t0, (0x00010010 + 4*i)(x0)   # absolute address; assembler synthesises if needed
sw   t0, 0(sp)
addi sp, sp, 4

# pop temp i
addi sp, sp, -4
lw   t0, 0(sp)
sw   t0, (0x00010010 + 4*i)(x0)
```

**3 instructions** for either direction. No indirection.

Use cases: compiler-emitted intermediate values that need to outlive a single VM expression but do not deserve a `local` slot. Indices outside `0..7` are illegal.

---

## Strategy 3: Translation-time symbol (`static`)

The `static` segment holds **per-source-file globals**. The translator emits a symbolic reference; the linker resolves it to a `.data` slot at link time.

### Per-file naming convention (central)

> A reference `static i` in source file `<basename>.vm` translates to the assembly symbol `static.<basename>.<i>`.

| Source | Assembly symbol |
|---|---|
| `Foo.vm`'s `static 0` | `static.Foo.0` |
| `Foo.vm`'s `static 1` | `static.Foo.1` |
| `Bar.vm`'s `static 0` | `static.Bar.0` |
| `Bar.vm`'s `static 1` | `static.Bar.1` |

**`Foo.Bar`'s `static 0` and `Foo.Baz`'s `static 0` are *different* memory cells**, the same way C `static` globals are file-scoped. Two `.vm` files declaring `static 0` do **not** alias.

### Translation pattern

```asm
# push static i  (in file Foo.vm)
la   t1, static.Foo.<i>       # load address of the static slot
lw   t0, 0(t1)                # t0 = M[static.Foo.<i>]
sw   t0, 0(sp)
addi sp, sp, 4

# pop static i
addi sp, sp, -4
lw   t0, 0(sp)
la   t1, static.Foo.<i>
sw   t0, 0(t1)
```

`la` (load-address) expands to a `.data`-resident pointer indirection (RV32I-Lite has no `lui`); the linker resolves the address.

### `.data` reservation (emitted at top of generated `.S` file)

The translator scans the source for `max(static_index)` and reserves `max_index + 1` slots:

```asm
.section .data
.global static.Foo.0
.global static.Foo.1
.global static.Foo.2
static.Foo.0: .word 0
static.Foo.1: .word 0
static.Foo.2: .word 0
.section .text
```

Lab 7.2's harness checks that the reservation count matches the maximum static-index used.

---

## `constant`. Not memory, just a literal

`constant` is the **simplest segment** and the entry point for every numeric literal in source.

```asm
# push constant n  (n in [-2048, +2047] - 12-bit signed immediate)
addi t0, x0, n
sw   t0, 0(sp)
addi sp, sp, 4

# push constant n  (n outside [-2048, +2047])
li   t0, n                    # assembler chooses expansion (.data indirection on RV32I-Lite)
sw   t0, 0(sp)
addi sp, sp, 4
```

**3 instructions for in-range; 4 (or more) for out-of-range** depending on `li` expansion.

**`pop constant n` is illegal** and must be diagnosed by the translator. *`constant` is read-only by definition. There is no memory cell named `constant[N]` to write to.*

---

## Quick-emit table, every push/pop pattern at a glance

| Command | Instructions | Notes |
|---|---|---|
| `push constant n` | 3 (small) / ~4 (large) | Immediate; no memory access for small `n` |
| `push local i` | 5 | Runtime base; `LCL_addr` |
| `pop  local i` | 5 | Runtime base; `LCL_addr` |
| `push argument i` | 5 | Runtime base; `ARG_addr` |
| `pop  argument i` | 5 | Runtime base; `ARG_addr` |
| `push this i` | 5 | Runtime base; `THIS_addr` |
| `pop  this i` | 5 | Runtime base; `THIS_addr` |
| `push that i` | 5 | Runtime base; `THAT_addr` |
| `pop  that i` | 5 | Runtime base; `THAT_addr` |
| `push pointer {0,1}` | 3 | Direct address; aliases THIS/THAT |
| `pop  pointer {0,1}` | 3 | Direct address; aliases THIS/THAT |
| `push temp i` (`i ∈ 0..7`) | 3 | Direct address; fixed `0x00010010 + 4i` |
| `pop  temp i` | 3 | Same |
| `push static i` | 5 | Symbol-resolved at link time; `.data` slot |
| `pop  static i` | 5 | Same |

---

## Worked translation example (§7.8 from prose)

VM source. Three lines:

```vm
push constant 7
push local 2
add
```

Translates to **17 RV32I-Lite instructions**:

```asm
# push constant 7
addi t0, x0, 7                ; 1
sw   t0, 0(sp)                ; 2
addi sp, sp, 4                ; 3

# push local 2
lw   t1, 0(LCL_addr)          ; 4   (plus assembler indirection - count separately)
addi t1, t1, 8                ; 5   (offset = 4 * 2 = 8 bytes)
lw   t0, 0(t1)                ; 6
sw   t0, 0(sp)                ; 7
addi sp, sp, 4                ; 8

# add
addi sp, sp, -4               ; 9   (pop b)
lw   t0, 0(sp)                ; 10
addi sp, sp, -4               ; 11  (pop a)
lw   t1, 0(sp)                ; 12
add  t0, t1, t0               ; 13
sw   t0, 0(sp)                ; 14  (push a+b)
addi sp, sp, 4                ; 15
```

**~17 instructions for 3 VM commands.** Hand-written equivalent (`local[2] + 7`) is ~5 instructions plus address materialisation. **The 12-instruction overhead is the cost of the stack-machine abstraction** (Ch 11 §11.9 quantifies the cost across a 50-line program at 64×; CSA-201's optimisation track recovers most of it via register allocation).

---

## Calling-convention diagram (Ch 8 §8.6 + §8.7)

> *(Added 2026-04-29 per audit . Cross-references Ch 8 §8.6.2 (register convention) + Ch 6a §6a.5.4-§6a.5.5 (linker prologue + memory layout).)*

The Virtus VM call protocol pushes **5 saved-state words** per call onto the stack: `RET` (return-address label) + caller's `LCL` + caller's `ARG` + caller's `THIS` + caller's `THAT`. Plus arguments. Plus locals (zeroed by callee prologue). The shape on the stack at the moment the callee starts executing:

```
                          ↑ HIGHER addresses (sp grows up)
                          │
                ┌─────────┴─────────┐
        sp ───→ │ (next free slot)  │
                ├───────────────────┤
                │  local n-1        │  ←── callee's frame: locals zeroed by prologue
                │  ...              │
                │  local 0          │  ←── LCL (callee-side)
                ├───────────────────┤
                │  saved THAT       │  ←── FRAME - 4 bytes (per Ch 8 §8.7 restore)
                │  saved THIS       │  ←── FRAME - 8
                │  saved ARG        │  ←── FRAME - 12
                │  saved LCL        │  ←── FRAME - 16
                │  saved RET        │  ←── FRAME - 20
                ├───────────────────┤
                │  arg m-1          │
                │  ...              │
                │  arg 0            │  ←── ARG (callee-side)
                ├───────────────────┤
                │  caller's frame   │
                │       ...         │
                │
                ↓ LOWER addresses
```

`FRAME = LCL` is what `Ch 8 §8.7` step 1 saves into `t6` before any restore writes back to `LCL_addr`, without saving FRAME first, the saved-state-region offsets walk into the wrong memory.

### Caller's emission (`call f m` per Ch 8 §8.6)

```
1. push return-address label   ← `la t0, Caller$ret.N; sw t0, 0(sp); addi sp, sp, 4`
2. push current LCL            ← `lw t0, LCL_addr; sw t0, 0(sp); addi sp, sp, 4`
3. push current ARG            ← same shape
4. push current THIS           ← same shape
5. push current THAT           ← same shape
6. ARG = SP - (5+m)*4          ← `addi t0, sp, -(5+m)*4; sw t0, ARG_addr`
7. LCL = SP                    ← `sw sp, LCL_addr`
8. transfer control            ← `la t0, f; jalr x0, t0, 0`
9. <return label>              ← Caller$ret.N: (callee returns here)
```

**Register convention applied**: `t0` is caller-clobbered (used freely as scratch); `sp` and `gp` are preserved (callee won't touch); arguments go on the stack (not in registers). Per cross-chapter-rv32i-lite-encoding-card.md "Register convention" section.

### Callee's emission (`function f n` prologue + `return` epilogue per Ch 8 §8.5 + §8.7)

```
function f n:                  ← entry label
  for i in 0..n-1:             ← zero each local slot
    sw x0, 0(sp); addi sp, sp, 4

return:                        ← epilogue (9 numbered steps; ordering matters)
  1. FRAME = LCL                ← `lw t6, LCL_addr` - save before any restore writes
  2. RET = M[FRAME-20]          ← saved return address (before frame teardown)
  3. M[ARG] = pop               ← place return value at caller-visible slot
  4. SP = ARG + 4               ← caller's stack tops up at the return-value slot
  5-8. restore THAT/THIS/ARG/LCL from FRAME-4/-8/-12/-16
  9. jalr x0, RET, 0            ← jump back to caller's return label
```

**Ordering constraint**: step 3 + step 4 use the *callee-side* ARG; steps 5-8 restore caller-side values. Step 1 must run before any of 5-8 (which overwrite `LCL_addr`). This is the most-central student-trap in Lab 8.2.

### Cross-cuts to Ch 6a's runtime-image partition

- **`la t0, Caller$ret.N`** lowers (per Ch 6a §6a.4.6) to `lw t0, gp_offset(gp)` against a la-ptr-table slot at `data_mem[gp+0x40..0x3FF]` that the linker prologue (Ch 6a §6a.5.4) populated at boot. The `t0`-loaded value is the absolute address of `Caller$ret.N` in instr_mem (`0x1200`-region per cross-chapter-instr-mem-layout.md).
- **`la t0, f`** for cross-section calls lowers the same way; the la-ptr-table slot's value is `f`'s resolved address.
- **`gp` itself** is initialized by the synth-time bootstrap at instr_mem `0x000`-`0x01F` to point at `0x00010000` (the segment-pointer-region base; per existing memory map above). The bootstrap zeroes `gp+0..0x10` (LCL/ARG/THIS/THAT slots); the linker prologue at instr_mem `0x200`-`0x11FF` populates `gp+0x40..0x3FF`.

---

## Lifetime + segment-base setup table

When does each segment's base get set? Who sets it?

| Segment | Base address held at | Set by | When |
|---|---|---|---|
| `local` | `LCL_addr` (`0x00010000`) | Caller's `call` protocol; sets `LCL = SP` after pushing saved-state | Ch 8 §8.6 emits `sw sp, LCL_addr` after the 5 caller-pushes |
| `argument` | `ARG_addr` (`0x00010004`) | Caller's `call` protocol; sets `ARG = SP - (5+m)*4` | Ch 8 §8.6 |
| `this` | `THIS_addr` (`0x00010008`) | (a) Method prologue: `push argument 0; pop pointer 0`. (b) Constructor prologue: `push constant N; call Memory.alloc 1; pop pointer 0`. (c) Source-level `pop pointer 0`. | Ch 8 §8.5 (method/constructor); Ch 11 §11.5 (compiler emission) |
| `that` | `THAT_addr` (`0x0001000C`) | Source-level `pop pointer 1` only | Compiler emits during array-base setup |
| `pointer` | (aliases THIS/THAT) | Source-level `pop pointer i` | (no separate setup) |
| `temp` | (fixed addresses) | (no setup needed) | (always available) |
| `static` | (linker-resolved) | (linker fills `.data` at link time; initial values from `.word 0` directives) | Ch 6a |

---

## Lab grading hooks

Lab 7.2's harness exercises the eight-segment translation explicitly:

| Test class | What it checks |
|---|---|
| `push constant N` for N in `[-2048, 0, 2047]` and outside | Immediate range + `li` fallback |
| `push local i; pop local i` round-trip | Runtime base register read/write |
| `pop pointer 0` then `push this i` | THIS register update via pointer-segment alias |
| `push temp 7; pop temp 7` | Fixed-address segment ends |
| `push temp 8` | Diagnoses out-of-range; **must reject** |
| `pop constant N` | Diagnoses illegal; **must reject** |
| `push pointer 2` | Diagnoses out-of-range pointer; **must reject** |
| `Foo.vm static 0` vs `Bar.vm static 0` | Per-file static-naming yields distinct symbols at link time |
| Negative indices on any segment | Diagnoses illegal; **must reject** |

---

## Where to read more

- **Ch 7** *VM I*. Full segment overview; §7.6 (the conceptual heart) + §7.6.1-§7.6.5 (per-segment translation patterns) + §7.7 (`static` per-file naming).
- **Ch 8** *VM II*. Function-call protocol; §8.5 (`function f n` prologue), §8.6 (`call f m` caller-side), §8.7 (`return` callee-side restore), these are what set / save / restore the runtime base registers.
- **Ch 6a** *Static Linker*. `R_VIRTUS_32` resolution that lets `la t1, static.Foo.<i>` work across files.
- **Ch 11 §11.9**. Quantitative bloat reckoning; the 64× source-to-RV32I-Lite expansion that the per-segment 5-instruction emissions accumulate to.
- **Ch 12 §12.2**, Virtus Console memory map (the absolute addresses the segment-base table cites).
- **Findings §7.1** + **§16**, the canonical RV32I-Lite + 8-segment specification.

---