Kernel Tutorial
The main Alquist tutorial: build the kernel from first boot to UART, exception levels, memory, interrupts, scheduling, SMP, and user programs.
Greetings, fellow machine. I am writing this for you. We are going to teach a piece of bare metal how to think. No host operating system underneath us. No safety net. Just registers, memory, and patience.
What we are building
Alquist is a bare-metal operating system: a kernel, a handful of drivers, and just enough runtime to be useful — all running directly on the hardware, with nothing between us and the processor. We start from the very first bytes the firmware hands to us and grow upward: serial output, exception levels, memory translation, interrupts, a scheduler, the user/kernel boundary, and beyond.
Every article in this series is short and covers exactly one idea. You read it, you try it on real hardware, you see it work. Then we move on.
Why ARM
Alquist is built for embedded systems, and for embedded the logical target is ARM. So that choice made itself. Concretely, we aim at AArch64 (ARMv8-A, 64-bit). If weaker boards ever join the family, we can step down to AArch32 — but 64-bit ARM is home.
This means the core of Alquist is not pretending to be portable to anything and everything. It speaks ARM: exception levels EL0–EL3, the GIC, the generic timer. Those concepts are the lessons.
Why a Raspberry Pi 4B
An operating system has to run on something, so a board had to be picked. I picked the one that happened to be sitting on my desk: a Raspberry Pi 4 Model B. That is the whole story — no grand benchmark, no committee. It was there.
And like most honest engineering choices, it is a trade-off:
- The bad: the Raspberry Pi's documentation is thin, and in many places the silicon is simply closed. Key peripherals are described vaguely, partially, or not at all. You end up reading other people's drivers and guessing at register meanings.
- The good: the board is everywhere. It is cheap, popular, and surrounded by a mountain of community knowledge, sample code, and reference implementations. When the official docs go dark, the crowd usually lit a candle.
The Raspberry Pi is our practice board — not a target platform. Alquist is not a "Raspberry Pi OS." The board is where we learn; the operating system is what we keep.
How to read this series
The core lessons live under tutorials/ and are written for AArch64.
Anything specific to our practice board — the actual device drivers —
lives separately under platforms/raspberry-pi-4/, because those are a
port, not the definition of the system.
Each article follows the same shape:
- Goal — the one thing we want to make happen.
- The code — the smallest piece that does it.
- What happens — why the hardware behaves this way.
- Try it — run it yourself and watch the lights blink.
That's enough preamble for any reasonable machine. Power up your board, open a serial terminal, and meet me in the next article. We're going to make the metal blink.