# sypstraw/rpi4-osdev: A Bare Metal OS Tutorial for Raspberry Pi 4

> A fifteen-part C tutorial that builds a bare metal operating system for the Raspberry Pi 4, from bootstrapping to a TCP/IP web server. It is a teaching repository, not a kernel you would ship, and its value depends on whether you want the hardware path or the software path.

**sypstraw/rpi4-osdev** — Tutorial: Writing a "bare metal" operating system for Raspberry Pi 4

- Repository: https://github.com/sypstraw/rpi4-osdev
- Website: https://www.rpi4os.com
- Stars: 3,770 · Forks: 283
- Language: C
- License: CC0-1.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/sypstraw-rpi4-osdev

## What the rpi4-osdev tutorial actually solves

Most operating system courses hand you an emulator. You write a scheduler, run it, and never touch a real interrupt controller. This repository takes the opposite route. Its stated goal is to write a bare metal operating system that runs on commercial hardware, and the hardware is a Raspberry Pi 4 Model B with a 1.5 GHz 64-bit quad-core Arm Cortex-A72 processor. The README frames the motivation plainly: computers cannot do anything useful without an OS, so why should only Microsoft, Apple and Google get to tell the majority of computers what to do as they are switched on.

The audience is therefore not a team looking for a kernel to fork. It is an individual who wants to see a serial console print a character they wrote, on a board they own. The repository is organised as fifteen numbered directories, from part1-bootstrapping through part15-tcpip-webserver, with intermediate stops at part4-miniuart, part5-framebuffer, part7-bluetooth, part9-sound, part10-multicore, part13-interrupts and part14-spi-ethernet. That sequence is the syllabus. Each part is a working checkpoint rather than a library, so you read it in order and you build it in order.

## How the parts build on each other, from bootstrapping to a web server

The directory names describe the data flow better than any prose summary could. part1-bootstrapping and part2-building cover getting code onto the board and getting it compiled for a different architecture. part3-helloworld is the first payload. part4-miniuart is where output becomes observable, because a UART gives you a text channel before any display driver exists. part5-framebuffer moves from characters to pixels. part6-breakout, part11-breakout-smp and part8-breakout-ble turn the framebuffer into a game, with the SMP variant adding the other cores and the BLE variant adding a wireless input path.

Later parts widen the machine rather than the application. part13-interrupts introduces asynchronous events, part14-spi-ethernet brings up networking hardware over SPI, and part15-tcpip-webserver stacks a TCP/IP implementation on top of it. part9-sound and part7-bluetooth fill in audio and Bluetooth. The repository is written in C throughout, and the README notes that all parts are confirmed working when built on an Apple MacBook Pro M1 running MacOS Tahoe 26.6, Clang 21.0.0 or Arm's gcc 15.2.1, Node 24.13.1. That is a build-environment statement from the author, not a compatibility matrix for every toolchain you might have.

## Installing the cross-compiler and building your first part

There is no package to install and no service to start. The README's software prerequisites are a cross-compiler, because your dev machine is likely running on an Intel processor while the RPi4 runs an Arm Cortex-A72, and GNU make. On Linux or WSL, the README points at Arm's gcc compiler and says to use the AArch64 ELF bare-metal target, and it suggests installing make with apt.

```bash
sudo apt install make
```

On macOS, the README recommends XCode from the App Store, which provides make, and Homebrew for LLVM.

```bash
brew install llvm
```

Hardware comes before all of this. The README lists an RPi4 with a dedicated power supply and HDMI lead, a monitor or TV, a micro-SD card, and a dev machine that can write to that card. It also calls a USB to serial TTL cable something you simply cannot do without, because it lets you see what the OS is doing long before you can write information to the screen.

The first real use is a sanity check, not your own code. The README says to flash the SD card with Raspbian using the Imager tool, boot the RPi4 into it, and not to proceed until that works, because if you cannot get someone else's OS running you likely will not be able to write your own. It notes one concrete gotcha: on a weaker TV the author had to set the hdmi_safe parameter to 1 in config.txt on the SD card, otherwise the screen stayed black. Once Raspbian boots, you move to part1-bootstrapping and part2-building and follow the build steps in those directories with the cross-compiler you just installed.

## Where the rpi4-osdev tutorial stops being the right tool

This is a tutorial series, and the README never presents it as anything else. There are no releases in the repository, so there is no versioned artefact to pin and no changelog to read before an upgrade. If you need a kernel with a security process, a stable ABI, or a support window, this is the wrong repository, and the README is silent on all three.

The hardware scope is equally narrow. The board is the Raspberry Pi 4 Model B, and the tutorial is written around its Cortex-A72 and its attached hardware. Nothing in the README claims the code runs on a Raspberry Pi 3 or a Raspberry Pi 5, and the directory names are tied to RPi4 peripherals such as the SPI Ethernet path in part14-spi-ethernet. Porting to another board means rewriting the parts that touch hardware, which is most of them.

The build story has the same shape. The README confirms the parts work with Clang 21.0.0 or Arm's gcc 15.2.1, and it names the AArch64 ELF bare-metal target specifically. A toolchain outside that description is untested ground. The README also does not document rollback, so if a later part leaves your board in a state you cannot explain, the recovery path is reflashing the card, which the README only describes in the Raspbian sanity-check step.

## Why not just use an emulator or an existing hobby kernel

The obvious alternative is QEMU, which lets you boot Arm code on your laptop with no SD card, no serial cable and no board. The difference is what you learn. An emulator will happily run a kernel that would fail on real silicon, because timing, firmware behaviour and peripheral quirks are smoothed over. This repository deliberately chooses the opposite trade: you buy hardware, you fight the HDMI and serial setup, and in return the failures you debug are the failures a real RPi4 produces. The README's insistence on booting Raspbian first is exactly that philosophy applied to troubleshooting.

A second alternative is to start from an existing hobby kernel and modify it. That is faster, but the repository's structure argues against it. Because each part is a checkpoint, part4-miniuart and part5-framebuffer are small enough to read end to end, which is the point of a tutorial. A mature hobby kernel gives you more features and less explanation of how each feature was reached. If your goal is a working system, take the mature kernel. If your goal is to have written the UART driver yourself, take this one.

## Licence and maintenance cost of the tutorial

The repository is licensed CC0-1.0. That is a public domain dedication rather than a permissive software licence, which means the usual conditions you look for in an open source licence, such as attribution or a patent grant, are not part of the text. For a tutorial you are reading and adapting, that is permissive in the extreme, but it also means there is no warranty language and no contributor patent grant to rely on. If you intend to lift code from these parts into a product, have someone who understands the difference between CC0 and an MIT or Apache-2.0 licence look at it before you do. Nothing here is legal advice.

Maintenance is a different question. The last push to the repository was on 2026-09-03, and the README's own note is dated Tuesday 4th August 2026, stating that all parts are now updated to reflect the latest RPi4 firmware changes. That is a recent, deliberate refresh rather than a steady release cadence. Because there are no releases, an upgrade is a git pull and a rebuild, and the cost of keeping up is the cost of re-reading whichever part changed. The README does not describe a deprecation policy or a minimum supported firmware version, so you should check the firmware note against the board you actually have before assuming a part still builds.

## Conclusion

Adopt this repository if you have an RPi4, a USB to serial TTL cable and a micro-SD card, and you want to understand Arm boot, UART output and framebuffer drawing by writing them yourself. Do not adopt it if you need a maintained kernel, a stable API, or anything that runs on a Raspberry Pi 5; the repository is a tutorial series and the README does not document a supported release, a rollback path or a security process. Before you start, verify that your dev machine can build the AArch64 ELF bare-metal target and that you can flash and boot Raspbian on the same board, because the README states you should not proceed until Raspbian runs.

## FAQ

### What hardware do I need to follow the sypstraw/rpi4-osdev tutorial?

The README lists an RPi4 with a dedicated power supply and HDMI lead, a monitor or TV, a micro-SD card, and a dev machine that can write to that card. It also calls a USB to serial TTL cable something you cannot do without, because it shows what the OS is doing before you can write to the screen.

### Which compiler does sypstraw/rpi4-osdev require?

The README says to use Arm's gcc compiler with the AArch64 ELF bare-metal target on Linux or WSL, or LLVM installed through Homebrew on macOS. It states the parts are confirmed working with Clang 21.0.0 or Arm's gcc 15.2.1.

### Does sypstraw/rpi4-osdev run on a Raspberry Pi 5?

The tutorial is written for the Raspberry Pi 4 Model B and its Cortex-A72 processor, and nothing in the README claims support for other boards. Parts such as part14-spi-ethernet are tied to RPi4 peripherals, so another board would require rewriting the hardware-facing code.

### What licence is sypstraw/rpi4-osdev released under?

The repository is licensed CC0-1.0, a public domain dedication rather than a permissive software licence. It carries no warranty language and no contributor patent grant, so check what that means for your use before copying code out of it.

## Sources

- [Issues](https://github.com/sypstraw/rpi4-osdev/issues)
- [License: CC0-1.0](https://github.com/sypstraw/rpi4-osdev/blob/master/LICENSE)
- [Project website](https://www.rpi4os.com)
- [README](https://github.com/sypstraw/rpi4-osdev/blob/master/README.md)
- [sypstraw/rpi4-osdev on GitHub](https://github.com/sypstraw/rpi4-osdev)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sypstraw-rpi4-osdev