Operating System development tutorials in Rust on the Raspberry Pi

Notice

This is a work-in-progress rewrite, started on September 2019.

You can find the original version of the tutorials here. They are worth checking out for some advanced features that are not yet rewritten, like exception handling. They will be ported over soon, though.

Some info on the rewrite and in general:

• I will first add code and minimal READMEs, and later write accompanying full-fledged tutorial text.
• The code written in these tutorials supports and runs on the Raspberry Pi 3 and the Raspberry Pi 4.
  • Tutorials 1 till 5 are groundwork code which only makes sense to run on QEMU.
  • Starting with tutorial 6, you can load and run the kernel on Raspberrys and observe output over UART.
• For editing, I recommend Visual Studio Code with the Rust Language Server extension.
• Check out the make doc command to browse the code with HTML goodness.

Cheers, Andre

Introduction

The target audience is hobby OS developers who are new to ARM's 64 bit ARMv8-A architecture. The tutorials will give a guided, step-by-step tour of how to write a monolithic Operating System kernel from scratch. They cover implementation of common Operating Systems tasks, like writing to the serial console, setting up virtual memory and exception handling. All while leveraging Rust's unique features to provide for safety and speed.

While the Raspberry Pi 3 and 4 are the main target boards, the code is written in a modular fashion which allows for easy porting to other CPU architectures and/or boards.

I would really love if someone takes a shot at a RISC-V implementation.

Ease of use

This repo tries to put a focus on user friendliness. Therefore, I made some efforts to eliminate the biggest painpoint in embedded development: Toolchain hassles.

Users eager to try the code should not be bothered with complicated toolchain installation/compilation steps. This is achieved by trying to use the standard Rust toolchain as much as possible, and bridge existing gaps with Docker containers. Please install Docker for your distro.

The setup consists of the following components:

• Compiler, linker and binutils are used from Rust nightly.
• Additional OS Dev tools, like QEMU, are pre-packaged into this container.

If you want to know more about docker and peek at the the containers used in these tutorials, please refer to the repository's docker folder.

Prerequisites

Before you can start, you'll need a suitable Rust toolchain.

curl https://sh.rustup.rs -sSf  \
    |                           \
    sh -s --                    \
    --default-toolchain nightly \
    --component rust-src llvm-tools-preview clippy rustfmt rls rust-analysis

cargo install cargo-xbuild cargo-binutils

USB Serial

It is highly recommended to get a USB serial debug cable. It also powers the Raspberry once you connect it, so you don't need extra power over the dedicated power-USB. I use a bunch of these.

You connect it to the GPIO pins 14/15 as shown beyond.

Tutorial 6 is the first where you can use it. Go to the README there for instructions on how to prepare the SD card to run your self-made kernels from it.

Acknowledgements

The original version of the tutorials started out as a fork of Zoltan Baldaszti's awesome tutorials on bare metal programming on RPi3 in C. Thanks for giving me a head start!

License

Licensed under the MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT).