Lab 14: Capstone — Tier 1 Gate Verification and Submission

Week: 14
Points: 100 (replaces standard lab weight; this is the capstone)
Time: ~7 days
Deliverable: Complete submission package per the capstone specification in week-14-capstone.md

What you ship

{your-name}-csa-110-capstone/
├── program/
│   ├── Main.vl
│   └── *.vl (any additional classes)
├── virtus-os/      (all 9 services from Lab 13)
├── toolchain/      (compiler/ vm-translator/ assembler/ linker/)
├── program-built/
│   ├── program.bin
│   └── program.bin.sha256
├── demo/
│   └── demo.mp4
├── diary/
│   └── week-14.md
└── writeup.md

Lab 14.1: Tier 1 gate dry run

Run the Tier 1 gate from a clean temporary directory before assembling your final submission:

# Create a clean temp directory and unzip your submission there
mkdir /tmp/csa110-gate-test
cp -r {your-name}-csa-110-capstone/ /tmp/csa110-gate-test/

cd /tmp/csa110-gate-test/{your-name}-csa-110-capstone/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
# Compare to:
cat program-built/program.bin.sha256

If the hashes match: Dimension 2 is verified. Proceed to Lab 14.2.

If the hashes do not match: do not submit until you find the root cause. Common causes:

• Compiler uses a hardcoded path (fix: use argument-relative paths)
• VM translator produces non-deterministic output (fix: sort all output deterministically)
• Assembler has a platform-dependent byte-order issue (fix: always use little-endian struct.pack('<I', ...))
• Linker processes files in a different order depending on glob behavior (fix: sort input files explicitly)

Lab 14.2: Compliance suite final check

Run the full Virtus OS compliance suite from the submission directory:

cd /tmp/csa110-gate-test/{your-name}-csa-110-capstone/
python3 tests/os/run_compliance.py --os-dir virtus-os/ --cpu-sim vvp

Expected: 38/38. Do not submit with any failing tests. Each failing test costs 2 points from Dimension 2.

Lab 14.3: Demo video checklist

Your 60-90 second demo video must show:

• The program booting (first frame of output)
• At least one OS call producing visible output (a printed number, a drawn pixel, or a character on screen)
• At least one interaction (a key press, button press, or computed result)
• The UART terminal or HDMI display (not just a terminal showing a build command)

Record multiple takes. Use the take where the output is cleanest.

Minimum acceptable: 480p at 30fps, audio optional, duration 60-90 seconds. No post-editing required.

Lab 14.4: Write-up sections

Write writeup.md with exactly five numbered sections:

Section 1: What my program does. Describe your capstone program in 2-3 sentences. What does it do? Why did you choose it? What OS services does it use?

Section 2: Three architecture decisions. Describe three decisions you made during Weeks 8-13 that you would make differently with hindsight. Each decision: one sentence describing what you chose, one sentence describing what you would choose now, one sentence explaining the difference.

Section 3: What broke and how I fixed it. Describe the most difficult bug you encountered during Weeks 8-14. Include: the symptom, your hypothesis, the debugging step that revealed the root cause, and the fix.

Section 4: CSA-101 comparison. Identify three concrete differences between your 6502 toolchain (CSA-101) and your RV32I-Lite toolchain (CSA-110). Each must be specific and evidence-grounded — cite a program, a line count, a cycle count, or a failure mode you actually observed. Generic comparisons earn no credit.

Section 5: Forward promise to CSA-201. Three sentences. What will the CSA-201 hardware multiplier change about the performance of your Virtus OS? What will a pipeline stage change about the debugging experience? What would you want to measure first in CSA-201 to understand the impact?

Lab 14.5: Toolchain Diary final entry

In diary/week-14.md:

• The binary size of program.bin in bytes. The percentage of the binary that is Virtus OS vs your program (estimate from VM line counts).
• The instruction count for your capstone program (from simulation trace or link map).
• One change you would make to your assembler and why.
• One change you would make to your compiler and why.
• The Math.mul(5, 7) cycle count from Lab 9.5.

This entry is graded on specificity. Numbers must match observable evidence.

Lab 14.6: Final zip and SHA-256

# In the parent directory of your submission folder:
sha256sum {your-name}-csa-110-capstone/program-built/program.bin \
    > {your-name}-csa-110-capstone/program-built/program.bin.sha256

zip -r {your-name}-csa-110-capstone.zip {your-name}-csa-110-capstone/

# Verify the zip contents
unzip -l {your-name}-csa-110-capstone.zip | grep -E 'Main\.vl|program\.bin|writeup|demo'

Submit the .zip file. Submissions without a program-built/program.bin.sha256 file cannot be graded for Dimension 2.

Grading rubric

Dimension 2 breakdown:

Dimension 3 breakdown:

What comes after submission

The grader returns Dimension 2 feedback within 48 hours (automated). Dimensions 1 and 3 within 5 business days. If Dimension 2 fails for a reason unrelated to your toolchain (grading environment issue), you will be notified and given 24 hours to resubmit.

CSA-201 enrollment opens the week after final submissions close. Bring your Toolchain Diary — the Lab 9.5 cycle count baseline is the first thing CSA-201 Module 1 asks for.