Vole Machine Simulator

A simulator for the Vole machine — the teaching architecture from Brookshear's Computer Science: An Overview — written in C++ with no dependencies beyond the standard library.

It models the hardware as separate objects rather than one loop: Memory owns 256 addressable cells, Register owns 16 general-purpose registers, Instructions decodes and executes, and Machine wires them together and exposes an interactive debugger.

  Memory        256 one-byte cells, hex-addressed 00–FF
  Register      16 general-purpose registers, R0–RF
  Instructions  decode + execute, holds the program counter
  Machine       loads programs, drives execution, inspects state

Instruction set

Every instruction is two bytes, written as four hex digits: an opcode, a register, and a two-digit operand.

Opcode	Form	Meaning
1	1RXY	Load register R from memory address XY
2	2RXY	Load register R with the immediate value XY
3	3RXY	Store register R at address XY — R00 prints to the screen
4	40XY	Copy register X into register Y
5	5RXY	Add registers X and Y into R, two's-complement
B	BRXY	Jump to address XY if register R equals register 0
C	C000	Halt

Floating-point addition (opcode 6 in the original spec) is not implemented.

Build

main.cpp includes the other translation units directly, so compile only main.cpp — passing Implementation/*.cpp fails with duplicate symbols.

g++ -std=c++17 -I Headers Implementation/main.cpp -o vole

Run

./vole

The menu drives everything:

 1- load a file.                              5- Show the value of a register in the CPU.
 2- Get the value of a specific cell.         6- Show a specific part of the Registers.
 3- Show the program counter.                 7- Execute the loaded file.
 4- Show a specific part of the memory.       8- Clear the memory.
                                              9- Shut down.

Choose 1 and enter test (the .txt extension is added for you), then 7 to execute. Memory and register addresses are entered in hex.

Program files

One instruction per line, bytes space-separated, each prefixed 0x:

0x2 0x0 0x00     load R0 with 0x00
0x2 0x1 0x01     load R1 with 0x01
0x3 0x1 0x00     print R1 to the screen
0xC 0x0 0x00     halt

test.txt is a working example that loads six registers, prints five of them and halts.

Layout

Headers/          Memory.h  Register.h  Instructions.h  Machine.h
Implementation/   the matching .cpp files, plus main.cpp
test.txt          example program

Built for the Computer Systems course at FCAI, Cairo University.