Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 40 ยท Projects

Project: Build Your Own Tiny CPU Emulator

Write a fetch-decode-execute emulator in JavaScript with registers, flags, a stack and memory, assemble programs for it, then add new instructions.

Every program in this tutorial ran on a toy CPU that someone had to write. In this last big project you write one yourself. An emulator is the best way to understand what a processor really does, because it has to do it in plain code: take the next instruction, work out what it means, change some registers or memory, and repeat. There is no magic left once you have typed the loop yourself.

You should know how a CPU executes instructions, what flags record, and how CALL and RET use the stack. The machine here is a fresh, even smaller design than Meet the Toy CPU: four registers, two flags, 64 words of memory and about twenty instructions. Every TryIt contains the complete emulator, so you can edit anything and run it again.

The shape of an emulator

An emulator is three things: state (what the machine remembers), a decoder (turning stored numbers into actions) and a loop that repeats the same cycle until the program halts.

flowchart LR
  F["Fetch<br/>read the words at pc,<br/>then pc = pc + 1"] --> D["Decode<br/>look the opcode up<br/>in the instruction table"]
  D --> E["Execute<br/>change registers, flags,<br/>memory or pc"]
  E --> C{"halted<br/>or error?"}
  C -->|"no"| F
  C -->|"yes"| S["Stop"]

The cycle every CPU repeats, and the loop at the heart of every emulator.

Our machine's state is a small object:

  • r: four registers a, b, c, d holding 32-bit signed integers.
  • pc: the program counter, the index of the next instruction.
  • sp: the stack pointer. It starts at 64, one past the end of memory, and the stack grows downwards.
  • z and s: the zero and sign flags, set by arithmetic and cmp.
  • mem: 64 words of data memory. The program itself is kept apart in a list of instructions, which keeps the design simple (real CPUs share one memory, see the memory lesson).

To keep the emulator small there are only two flags. That makes jl correct only when no signed overflow happens, an honest limitation that the ideas at the end ask you to fix.

One table drives everything

The cleverest simplification is an instruction table. Each entry has a name, a numeric opcode, the kinds of its operands and a small function that performs it. def("add", "rr", ...) means "an instruction called add with two register operands". The codes are handed out in order, so the table also defines the machine code.

The operand kinds are single letters: r for a register, i for an immediate number, l for a label (turned into an instruction index by the assembler) and m for a register in square brackets, a memory reference.

Because the decoder just looks an opcode up in this table, adding an instruction means adding one def line. The assembler and the CPU loop never change. You will see that in a moment.

The assembler turns each source line into three numbers, [opcode, x, y]. Unused slots are 0, so every instruction has the same width. A fixed width is unlike x86-64, where instructions are 1 to 15 bytes long, but it is how ARM64 works: every instruction is 4 bytes. Fixed-width decoding is far simpler, which is one reason modern designs like it.

The complete emulator

Run it. The program adds the numbers 5 down to 1. The trace prints one line after every instruction, with the registers and flags it left behind. Read the first two lines, then watch the loop at addresses 2 to 4 repeat while b counts down. The loop ends when sub b, 1 makes b zero, which sets z, so jnz falls through.

JS The emulator and a first program

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The three commented lines in run mark fetch, decode and execute. If you moved cpu.pc++ after the execute step, every call would save the wrong return address and every jump would be off by one.

Machine code is only numbers

The program the CPU runs is not the text you typed. After assembly it is a list of numbers, and the instruction table is the only thing that gives them meaning. The next demonstration prints the encoded form beside the source, then prints the whole table so you can decode a word by hand, like reading a datasheet.

JS Assemble, then decode by hand

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that movi a, 7 and mov a, b have different opcodes. The assembler quietly chooses movi when the second operand is a number and mov when it is a register. A real assembler does the same: the single mnemonic mov in x86-64 covers many different machine encodings, as Assemblers and Syntax explained.

flowchart LR
  T["movi a, 7<br/>source text"] --> A["assembler"]
  A --> W["1 | 0 | 7<br/>opcode, register a, value 7"]
  W --> X["CPU: BY_CODE[1].run(cpu, 0, 7)<br/>a = 7"]

One instruction's journey from text to numbers to a changed register.

Faults: when the program is wrong

A real CPU cannot trust its program, and neither can an emulator. The emulator turns each kind of mistake into a fault, an error message plus a stop, instead of a crash or an endless loop:

  • Step limit: maxSteps stops runaway loops. A real operating system does something similar when a timer interrupt takes the CPU away from a process.
  • Memory fault: address() rejects any address outside memory, like the segmentation faults in Debugging Assembly.
  • Stack overflow and underflow: push, call, pop and ret check the stack pointer against both ends.
  • pc out of range: running off the end of the program is a fault, because there is no instruction to fetch.

The run loop wraps everything in try and catch, so a fault becomes cpu.error and the machine simply stops with its state intact for you to inspect, much as a debugger shows a crashed process.

Extending the machine

Now the payoff. The next example adds six instructions, inc, dec, shl, xor, jle and div, each with a single def line. It then runs a factorial subroutine that uses call, ret, mul, cmp and the new jle, and runs several broken programs on purpose so you can see each fault.

Watch two details. div checks for a zero divisor and throws, which is how x86-64 treats its div instruction: it raises a divide error instead of returning something. And shl is registered as shli because it takes a number, so the assembler adds the i for you, using the same rule as before.

JS Add instructions and trigger faults

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The factorial of 5 takes 29 steps: 4 before the loop, 5 per pass for 4 passes, then the final compare, jump, ret, out and halt. Change the 5 to a 6 and predict the step count before you run it (each extra pass adds 5 steps).

Ideas to extend it

  • Add a carry flag and an overflow flag, and make jl and jg depend on s and o as real CPUs do, so signed comparisons work at the extremes (Flags has the rules).
  • Add and, or, shr, neg and not, and rewrite the bit tricks from Logic and Shifts.
  • Add byte-addressed memory with ldb and stb, and store strings the way the string toolkit would on real hardware.
  • Add outc to print characters, and a .data section to the assembler so programs start with chosen memory contents.
  • Add a cycle counter where each opcode has a cost (say mul costs 3 and a memory access costs 5) and report the total, to feel the ideas from Performance: Pipelines, Caches and Branches.
  • Add interrupts: after every N instructions, push pc and jump to a handler, which is how multitasking begins.
  • Write a disassembler that turns the numbers back into text.

What real emulators add

Our loop executes one instruction at a time by looking it up in a table. That is called an interpreter. Fast emulators and virtual machines, such as QEMU or a JIT compiler, translate blocks of guest instructions into native machine code and run them directly. Everything you built carries over: the registers become a struct, the table becomes a decoder, the faults become emulated exceptions. Real hardware adds privilege levels, virtual memory and caches, but the heart is the same three-step cycle.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What are the three steps of the loop in the emulator?

    Every CPU, real or emulated, fetches the next instruction, decodes what it means and executes it. Fetching also advances pc, which is why a jump only needs to overwrite pc.
  2. 2. Why is it easy to add a new instruction to this emulator?

    The table maps an opcode to a function. The assembler reads names and operand kinds from it, and the run loop calls the function, so neither needs changes.
  3. 3. What does the emulator do when a program divides by zero or loops forever?

    Faults are thrown as errors and caught in the run loop, so the program stops cleanly. The step limit also protects against endless loops, as a timer does for an operating system.
  4. 4. Why does the assembler pick movi for mov a, 7 but mov for mov a, b?

    One mnemonic can stand for several encodings. The assembler chooses by the operand types, as real assemblers do for mov on x86-64.

Summary

  • An emulator is state plus a fetch, decode, execute loop; the program counter advances during the fetch.
  • An instruction table of name, opcode, operand kinds and function drives both the assembler and the CPU.
  • Machine code is just numbers; the table gives them meaning.
  • Faults (bad memory address, stack limits, divide by zero, runaway loops) are checked and reported, never ignored.
  • A new instruction is one table entry; the missing overflow flag is an honest limitation you can fix.
  • Real fast emulators translate whole blocks of code, but still do the same three steps.

Next: finish with the real thing in Project: Hello World the Real Way.