← back
minimal-instruction-set
C · Virtual Machine · Interpreter · Low-Level Systems
Overview
minimal-instruction-set is a stack-based virtual machine and interpreter written in C,
designed to explore low-level execution models and instruction set design.
The project implements a complete execution pipeline including parsing, symbol resolution,
and runtime interpretation of a custom assembly-like language.
Instruction Set
- Stack operations:
PUSH, POP, DUP, SWAP,
PICK
- Arithmetic:
ADD, SUB, MUL, DIV, MOD
- Unary operations:
INC, DEC, NEG
- Control flow:
JMP, JZ, JNZ, JL, JG
- Subroutines:
CALL, RET
- I/O:
PRINT, DUPRINT
Core Design
- Stack-based execution model with explicit operand manipulation
- Custom parser for tokenising and interpreting assembly-like source files
- Symbol table implementation for label resolution and jump targets
- Program representation decoupled from execution engine
- Simple VM loop handling instruction dispatch and execution
Control Flow & Execution
- Label-based jump system for structured and unstructured control flow
- Conditional branching based on stack values
- Call stack support for subroutine execution and recursion
- Explicit program entry via
START label
Example Programs
- Fibonacci sequence using recursive calls and stack manipulation
- Loop-based programs with conditional branching and modulo logic
- Subroutine-based transformations (e.g. square, triple)
- Instruction coverage scripts exercising full VM capability
Key Engineering Decisions
- Minimal instruction set to emphasise composability over complexity
- Separation of parsing, program representation, and execution layers
- Explicit stack manipulation rather than register-based design
- Incremental development of features (arithmetic → jumps → calls)
Limitations
- No optimisation layer (pure interpreted execution)
- No memory model beyond stack and call stack
- Limited error handling for malformed programs
- Designed for learning and experimentation rather than performance
What I Learned
- Designing and implementing a custom instruction set architecture
- Building interpreters and execution pipelines in C
- Managing control flow via jumps and stack-based evaluation
- Trade-offs between simplicity, expressiveness, and usability