rust-raspberrypi-OS-tutorials is a series of tutorials aimed at enthusiasts/self-learners, teaching you how to write a monolithic operating system kernel in Rust, targeting the Raspberry Pi (mainly Pi 3 and Pi 4). Each lesson provides a bootable and runnable kernel image, with subsequent lessons building on the previous ones, ultimately allowing you to run it in QEMU and flash it to real hardware to see the results via UART output.
What Pain Points Does It Address?
- • Toolchain Hell: Embedded/bare-metal development often involves wrestling with cross-compilation tools, different versions of binutils, QEMU, OpenOCD, etc., which can lead to errors. This project significantly reduces the “environment setup failure rate” through Rust’s rustup and by providing Docker containers.
- • Fragmented or Overly Theoretical Tutorials: This is a hands-on tutorial with runnable code at every step, and each tutorial includes a tl;dr and source code diff, making it clear where the changes are.
- • The Gap from Simulation to Real Hardware: The first few lessons lay the foundation in QEMU; starting from lesson 5, you can see output on a real Pi via serial (UART), and later lessons include chainloading functionality for easier kernel flashing.
- • Low-Level Development with Modern Language: Rust’s ownership/borrowing system helps you avoid a large class of memory/concurrency bugs, making it a comfortable addition to bare-metal experiments.
Who Is It Suitable For?
- • Engineers or students with a certain programming background who want to deepen their understanding of CPU architecture/OS principles.
- • Developers looking to do low-level system development with Rust.
- • Hands-on enthusiasts who want to run code on real hardware.
Installation and Usage (Practical Steps, Concise Version)
Prerequisite: Linux preferred; some features may work on macOS but are considered experimental by the author. For Windows, it is recommended to use WSL2.
- 1. Install Docker (strongly recommended)
- • Install Docker Engine and add your user to the docker group (on Linux) to avoid using sudo every time. Docker will pull the toolchain images provided by the author as needed, saving a lot of hassle.
- • If you already have Rust installed:cargo install cargo-binutils rustfilt
- • If not installed:curl –proto ‘=https’ –tlsv1.2 -sSf https://sh.rustup.rs | shsource $HOME/.cargo/envcargo install cargo-binutils rustfilt
- • It is recommended to use VS Code with the Rust Analyzer plugin for a better editing experience.
- • Each chapter in the repository has a README, tl;dr, diff, and demo code. Running make doc will generate the documentation automatically.
- • The repository includes scripts/Makefile to facilitate simulation startup in QEMU and view output.
- • Prepare an SD card and write the chainloader or kernel files (instructions are provided in the tutorial).
- • It is recommended to buy a USB-to-serial cable (common and reliable with CP2102 chip), connect GND and GPIO 14/15 properly, and use serial tools to view output. The project also provides a small tool called “minipush” that can send the kernel to the device via UART as needed.
Quick Comparison Table of Installation Points
| Step | Purpose | Key Commands/Tools |
| Docker | Unified toolchain to avoid dependency issues | Docker Engine + repository-provided container |
| Rust Environment | Required for compiling the kernel | rustup, cargo-binutils, rustfilt |
| QEMU | Simulate running on the host | qemu-system-aarch64 |
| USB-Serial | View output on real hardware | CP2102 model cable + miniterm / picocom |
| Write to SD | Boot on real hardware | dd / official tutorial script |
| Debugging | GDB step-by-step / OpenOCD | openocd + aarch64 gdb |
Advantages (Why It’s Worth a Look)
- • The tutorial system is complete and progressive, suitable for learning from the basics.
- • Memory safety provided by Rust can reduce many painful bugs.
- • Seamless transition between real hardware and simulator, providing a complete experience.
- • The repository is well-maintained: each lesson is independent, diffs are clear, and documentation and make doc are very convenient.
- • The author maintains and provides Docker containers, saving a lot of version conflicts and dependency hassles.
Disadvantages and Limitations (Don’t Just Look at the Highlights)
- • The learning curve is still steep: understanding ARMv8 architecture, bare-metal boot processes, linker scripts, and other low-level concepts is necessary.
- • Support for Windows is not friendly; it is recommended to use Linux or WSL.
- • Some long documents in certain tutorials are still incomplete (the author is gradually supplementing them). Although there are translations of Chinese materials, they may need to be verified against the latest code.
ConclusionIf you want to deeply master ARM bare-metal/operating system principles while using a modern language to avoid the pitfalls of traditional C pointers, this tutorial series is very suitable. For beginners, it is recommended to run a few lessons in QEMU, understand the diffs of each change, and then buy a USB-to-serial cable to flash the later versions to the Pi to see real output.
If you enjoy learning by doing and relish the sense of accomplishment from building a system step by step, this will keep you hooked. Get ready to connect your serial port and boot your first Rust kernel!
Project Address: https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials