Build Your Own Toy Computer
A toy computer project goes one level below an emulator. Instead of only emulating an existing instruction set, you design the tiny machine: binary representation, logic blocks, registers, memory, instruction format, control flow, I/O, and a small monitor program.
1. Overview & motivation
Build a small computer model with fixed-width words, registers, flags, RAM, an instruction set, fetch/decode/execute control, an assembler or loader, example programs, and optional display, keyboard, timer, or storage.
Unlike Emulator, the goal is not compatibility with a real platform. The goal is to make every hardware concept explicit enough that you could emulate it, test it, and explain it.
2. Where this fits in the degree
- Phase: Systems
- Semester: 4 (Systems Programming)
- Modules deepened: Module 2 (machine representation), Module 3 (computer organization), Module 5 (interpretation)
Cross-phase relevance:
- Prepares directly for Emulator.
- Makes Compiler code generation concrete because the target machine is yours.
- Helps before Operating System, where CPU privilege, interrupts, and memory maps matter.
3. Local source backbone
Primary local source:
- Programming a Toy Computer from Scratch (
build-your-own/toy-computer)
| Local chunks | Use them for | Project milestone |
|---|---|---|
002-004 | Binary numbers, arithmetic, logical operations, hex | Bit and word representation |
005-010 | Transistors, logic gates, arithmetic circuits, memory cells, buses | Datapath and memory model |
011-017 | Instructions, toy instruction set, control circuits, implementation, example programs | CPU core and sample programs |
018-032 | Embedded board overview, registers, instruction set, vector table, first program | Real-hardware comparison and optional embedded path |
033-040 | Bytecode instructions and interpreter | Fetch/decode/execute loop |
041-063 | Clocks, display, keyboard, UART, interrupts, basic I/O | Timers, input, output, and interrupt-style extensions |
064-172 | Flash, UI, algorithms, implementation, compilation and tests | Monitor, debugger, storage, and larger capstone extensions |
4. Implementation milestones
Milestone 1: Word, memory, and register model
Choose word size, address size, register count, and memory layout.
Evidence: unit tests for overflow, sign/zero handling, and memory bounds.
Milestone 2: Instruction set
Define opcodes for load/store, arithmetic, compare, jump, and halt.
Evidence: instruction reference table with binary encoding and examples.
Milestone 3: Fetch/decode/execute loop
Implement the CPU state and run one instruction at a time.
Evidence: trace shows PC, opcode, operands, registers, flags, and changed memory after each instruction.
Milestone 4: Assembler or loader
Write a minimal assembler or structured loader so examples are not hand-coded byte arrays.
Evidence: assemble and run sum 1..10, max, and a loop with conditional jump.
Milestone 5: I/O device
Add memory-mapped output, keyboard input, or a timer.
Evidence: a program writes text or pixels through the device interface.
Milestone 6: Monitor/debugger
Add single-step, breakpoints, memory inspection, and register inspection.
Evidence: debugging transcript of a broken program being diagnosed.
5. Tests & evidence
| Test | Evidence |
|---|---|
| ALU correctness | arithmetic and flag tests |
| Instruction decode | every opcode decodes from bytes correctly |
| Control flow | loops, branches, halt behavior |
| Memory safety | invalid addresses fail predictably |
| Program examples | at least three non-trivial programs |
| Debugger | trace or transcript proving step mode works |
6. Architecture specification
Before coding, write a machine specification. Keep it small enough to fit on one page.
| Decision | Example | Why it matters |
|---|---|---|
| Word size | 8-bit, 16-bit, or 32-bit | Determines overflow, instruction width, and memory addressing |
| Address size | 8-bit address = 256 cells | Sets program/data limits |
| Register file | R0-R7, PC, SP, FLAGS | Defines what instructions can touch directly |
| Flags | zero, carry, negative, overflow | Defines branch behavior |
| Memory map | code, data, stack, I/O page | Prevents accidental overlap |
| Instruction format | fixed 16-bit or variable length | Controls decoder complexity |
| Halt/error model | HALT, invalid opcode trap | Makes failures inspectable |
Suggested minimal ISA
| Category | Instructions |
|---|---|
| Data movement | LOAD, STORE, MOV, PUSH, POP |
| Arithmetic | ADD, SUB, INC, DEC |
| Logic | AND, OR, XOR, NOT, SHL, SHR |
| Compare/branch | CMP, JMP, JZ, JNZ, JC, JNC |
| I/O | IN, OUT or memory-mapped load/store |
| Control | CALL, RET, HALT, TRAP |
Do not add every instruction at once. Add a category only when you have a program that needs it.
Execution trace contract
Every instruction should be traceable:
cycle=0042 pc=0x0010 instr=ADD R1,R2 before={R1=3,R2=4,Z=0,C=0} after={R1=7,Z=0,C=0}
If a learner cannot explain a bug from the trace, the machine is still too implicit.
7. Programs to require
| Program | Concepts proven |
|---|---|
| Add two numbers | load, arithmetic, halt |
Sum 1..N | loop, compare, conditional branch |
| Max of an array | memory addressing, branch decision |
| Copy memory range | pointer-like iteration |
| Subroutine call | stack, call frame, return address |
| Echo input to output | I/O register or memory-mapped device |
Each program must include source assembly, assembled bytes, final output, and one execution trace.
8. Common failure modes
- No written instruction encoding. If encoding lives only in code, the assembler and CPU drift.
- Ambiguous flags. Define whether
SUBsets carry on borrow and how signed overflow is represented. - PC update bugs. Branches, calls, and variable-length instructions are frequent off-by-one sources.
- Stack collision. If stack grows into program/data memory, the machine needs a trap.
- I/O side effects hidden in helpers. Memory-mapped I/O should be visible in the trace.
- Too-real too soon. A tiny correct ISA teaches more than an unfinished ARM clone.
9. Portfolio framing
Publish this as a computer-architecture artifact: instruction set reference, architecture diagram, sample programs, execution traces, debugger transcript, and explicit limitations.
The strongest demo is a tiny program that a reviewer can read in assembly, run, and watch at the register/memory level.
10. Deep project spec
Project contract
Build a toy machine, not only an interpreter loop. The project must define word size, address width, register file, flags, memory map, instruction encoding, assembler syntax, trap behavior, and at least one I/O mechanism. The implementation may be an emulator, but the deliverable is the machine specification plus runnable programs.
Source-backed reading map
| Source ID | Use for | Required output |
|---|---|---|
build-your-own/toy-computer | binary arithmetic, gates, buses, instruction set, bytecode interpreter, I/O, monitor | ISA reference, trace format, debugger transcript |
Milestone map
| Milestone | Deliverable | Tests | Failure case |
|---|---|---|---|
| Machine spec | one-page architecture | spec review checklist | undefined flag/overflow behavior |
| ALU/registers | arithmetic and flags | overflow/carry tests | signed/unsigned confusion |
| Instruction set | binary encoding and disassembler | encode/decode round trip | invalid opcode trap |
| CPU loop | fetch/decode/execute | instruction trace fixtures | PC off-by-one regression |
| Assembler | source to bytes | assembly golden fixtures | label resolution error |
| Programs | required sample suite | output and trace fixtures | stack/data collision |
| Monitor | step/break/inspect | debugger transcript | invalid breakpoint |
Test matrix
| Test type | Required examples |
|---|---|
| Unit | ALU, flags, memory bounds, encode/decode |
| Golden | assembly to bytes, bytes to disassembly |
| Integration | sum, max, memory copy, call/return, echo I/O |
| Property | assembler/disassembler round trip for valid instructions |
| Trace | every sample program has at least one inspectable run |
Design notes required
isa.md: instruction table, binary encoding, examples.memory-map.md: code, data, stack, I/O regions.debugger.md: trace format and debugger command contract.
Portfolio evidence
Publish the ISA reference, architecture diagram, sample programs, assembled bytes, execution traces, and one bug story where the debugger exposed a machine-state issue.
Source
This project is based on the local toypc-contents chunks and complements the Emulator and Compiler projects.