What this is for, and what here is real

This handbook accompanies a set of labs in which you work with an operating system from 1986, running on a processor described in Verilog. In a browser, with nothing to install.

Before going further it is worth agreeing on what exactly is real here and what is imitation. In retrocomputing projects this is usually left vague, and it should not be.

What is real

The processor. Under the page runs RISC5.v — Niklaus Wirth's synthesisable Verilog, stepped cycle by cycle by the Verilator simulator. This is not a model of a processor and not an emulator: it is the very code that gets programmed into an FPGA. When you see the cursor blinking on screen, real logic drew it, simulated to the cycle.

The system. Project Oberon is the operating system Wirth and Jürg Gutknecht wrote in 1986 and rewrote for their own processor in 2013. All of it, together with the compiler, the window environment and the text editor, comes to about ten thousand lines.

The compiler. The Oberon compiler is written in Oberon and sits on the same disk as everything else. In lab 7 you will run it and it will build itself.

What is not real

The peripherals. Disk, keyboard and mouse are modelled in C++ and JavaScript. A real board talks to an SD card over SPI and to a keyboard over PS/2; here those protocols are reproduced in software. The processor does not know the difference — it sees the same registers at the same addresses.

The speed. Simulation gives roughly four megahertz equivalent, about four times slower than a real board. Booting takes a couple of seconds.

Why this can be believed

Claiming "we have a real processor" is easy. Checking it is hard. So everything you will see is verified by machine, and the checks live in the same repository:

• The boot is verified by a checksum of the screen. After twelve million instructions the framebuffer gives B5DFC933 — identically in the native build, in the build with the disk in memory, and in the browser.
• Step for step against an independent emulator. Fourteen and a half million instructions are compared against Peter De Wachter's emulator across all registers, flags and memory contents. Not one divergence.
• The compiler reaches a fixed point. A compiler built by itself produces the same code sizes and the same keys, bit for bit.
• The whole system rebuilds itself. Thirty-seven object files match the originals byte for byte after a rebuild.

The last point is worth dwelling on. It means this is not a museum piece but a closed system: a description of a processor produces the processor, the processor runs the system, the system contains the compiler, the compiler produces the system itself. The circle closes, and one command checks it.

How to read on

The chapters are as independent as they can be, but the order is not accidental:

• The machine — what RISC5 is: registers, instructions, memory.
• The language — Oberon entire, in one chapter. It really does fit.
• The system — the least familiar part: there are no buttons, the whole interface is text, and commands are run with the middle mouse button.
• Modules — separate compilation and symbol files.
• The compiler — four modules and the path from a[i] to instructions.
• Self-hosting — what a fixed point proves.
• What we measured — figures and findings that are not in the books.

If you would rather touch it straight away, start with lab 1: it needs nothing but a browser.