Week 14: Capstone — Assemble and Ship

You have built every layer. The NAND gates are yours, the register file is yours, the ALU is yours, the instruction decoder is yours, the assembler is yours, the linker is yours, the VM translator is yours, the compiler is yours, and the operating system is yours. Week 14 is not a week of building — it is a week of knowing what you have built, verifying it runs end-to-end, recording what worked and what you would do differently, and shipping it.

Reading

No new reading. This is the week Petzold's ladder is complete. If you want a companion for the reflection work, re-read the first and last three pages of Code — the relay-to-processor arc you traced in CSA-101 is now also visible as an assembler-to-OS arc.

Lecture

1 hour. The lecture this week is a retrospective, not a tutorial.

The Tier 1 gate. The grader runs one command sequence to verify that your toolchain reproduces your submitted binary from your submitted source. This is the capstone's only automated gate:

cd {student-submission}/toolchain

python3 compiler/compiler.py ../program/Main.vl -o /tmp/main.vm
python3 vm-translator/translator.py /tmp/main.vm -o /tmp/main.s
python3 assembler/asm.py /tmp/main.s -o /tmp/main.vof
python3 linker/linker.py /tmp/main.vof virtus-os/*.vof -o /tmp/program-reproduced.bin

sha256sum /tmp/program-reproduced.bin
# Must match: program-built/program.bin.sha256

If the SHA-256 matches, your toolchain is reproducible and Dimension 2 is fully credited. If it does not match, Dimension 2 scores zero but Dimensions 1 and 3 are still graded.

What the grader does not check automatically:

• Whether your program does anything interesting (Dimension 1 — graded by human review)
• Whether your write-up demonstrates understanding (Dimension 3 — graded by human review)
• Whether your CSA-101 comparison is honest and specific (Section 4 of Dimension 3)

These are the deliverables that distinguish a memorable submission from a minimal one.

Dimension definitions:

The CSA-101 comparison (Section 4 of the write-up). This is the most distinctive deliverable available to CSA-110 students. You have built two complete stacks — a 6502 and an RV32I-Lite. Name at least three concrete differences you observed, not three textbook differences. "RV32I-Lite has more registers" earns no credit. "My 6502 assembler passed in one pass because I never used forward-reference labels; my RV32I-Lite assembler required two passes on my first real program because I used B-type branches to forward labels for the if codegen" earns full credit.

Day-by-day timeline

Submission package

{your-name}-csa-110-capstone/
├── program/
│   ├── Main.vl           -- required; your capstone program entry point
│   └── *.vl              -- any additional classes your program uses
├── virtus-os/
│   ├── Math.vl
│   ├── Memory.vl
│   ├── String.vl
│   ├── Array.vl
│   ├── Output.vl
│   ├── Screen.vl
│   ├── Keyboard.vl
│   ├── GamePad.vl
│   └── Sys.vl
├── toolchain/
│   ├── compiler/
│   │   ├── compiler.py
│   │   ├── tokenizer.py
│   │   ├── parser.py
│   │   └── codegen.py
│   ├── vm-translator/
│   │   └── translator.py
│   ├── assembler/
│   │   └── asm.py
│   └── linker/
│       └── linker.py
├── program-built/
│   ├── program.bin           -- the binary you produced
│   └── program.bin.sha256    -- its SHA-256 hash
├── demo/
│   └── demo.mp4              -- 60-90 second demo video
├── diary/
│   └── week-14.md            -- Toolchain Diary final entry
└── writeup.md                -- five-section write-up

Run this before zipping:

sha256sum program-built/program.bin > program-built/program.bin.sha256

Common capstone stumbles

Stumble 1: SHA-256 mismatch due to path assumptions in compiler.py. The Tier 1 gate runs from inside the toolchain/ directory. If your compiler.py uses ../virtus-os/ as a hardcoded path to the OS sources, it will fail when the grader runs it from a different working directory. Use path arguments, not hardcoded relative paths.

Stumble 2: The demo video shows a static terminal with no program output. The grader watches the video before reading the write-up. A blank screen for 40 seconds followed by "it worked" in narration is not a demo. Capture at minimum: the program booting, one line of output appearing, one deliberate OS call (a print, a pixel draw, a keyboard read) with a visible result.

Stumble 3: The write-up Section 4 is generic. "RV32I-Lite is a RISC architecture and the 6502 is CISC" is not a comparison — it is a definition. The comparison section is the only place in the rubric where your lived experience building both stacks is graded. Be specific about programs, output, line counts, and failure modes you encountered personally.

Stumble 4: Virtus OS compliance suite not run before final zip. A submission with 37/38 compliance tests passing loses 5 points from Dimension 2. Run the full suite the day you zip. Do not assume it still passes after you edited an OS file.

Stumble 5: Forward promise to CSA-201 is missing from Section 5. Section 5 is the easiest section to skip because it is not about what you built — it is about what comes next. The grader reads it looking for signs that the student understands what a hardware multiplier, a cache, and a pipelined CPU would change. Three sentences about Math.multiply and cycle counts is enough.

Toolchain Diary — Week 14

Your final entry in diary/week-14.md covers:

1. The binary size and instruction count of your compiled capstone program. What percentage of the binary is Virtus OS vs your program?
2. One thing you would change in your assembler, and why, if you were starting over today.
3. One thing you would change in your compiler, and why.
4. One concrete prediction about what CSA-201's hardware multiplier will change in your Math.multiply cycle count. You measured the software multiply baseline in Lab 9.5. How many cycles does it take for Math.multiply(5, 7) with your shift-and-add implementation? What would a 1-cycle hardware multiply change about the timing of your capstone program?

Reflection prompts

1. The Tier 1 gate verifies that your toolchain reproduces your binary. It does not verify that your binary is correct. What would a stronger gate look like? Design a second automated check that tests program behavior, not just binary identity.
2. Your Memory.deAlloc prepends the freed block to the free list without coalescing adjacent free blocks. Describe a specific program execution sequence that would exhaust heap memory even though enough total free bytes exist to satisfy the allocation.
3. The complete toolchain you built is roughly 1,500-2,000 lines of Python. The GCC toolchain is roughly 15 million lines of C. Name the three largest categories of work your toolchain does not do — not as a critique, but as a precise accounting of the engineering you deferred to CSA-201 and beyond.

What's next

CSA-201 picks up exactly where CSA-110 leaves off. The first module adds a hardware multiply/divide unit to your RV32I-Lite core, removing the shift-and-add loop from Math.multiply. The second module adds an instruction cache. The third module pipelines the datapath. Every change is measurable against the baseline you recorded in your Toolchain Diary.