Operating System development tutorials in Rust on the Raspberry Pi

Last update: May 22, 2022

Operating System development tutorials in Rust on the Raspberry Pi


ℹ️ Introduction

This is a tutorial series for 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 for an embedded system from scratch. They cover implementation of common Operating Systems tasks, like writing to the serial console, setting up virtual memory and handling HW exceptions. All while leveraging Rust's unique features to provide for safety and speed.

Have fun!

Best regards,
Andre (@andre-richter)

P.S.: In the future, Chinese 🇨🇳 versions of the tutorials will be maintained as README.CN.md by @colachg and @readlnh.

📑 Organization

  • Each tutorial contains a stand-alone, bootable kernel binary.
  • Each new tutorial extends the previous one.
  • Each tutorial README will have a short tl;dr section giving a brief overview of the additions, and show the source code diff to the previous tutorial, so that you can conveniently inspect the changes/additions.
    • Some tutorials have a full-fledged, detailed text in addition to the tl;dr section. The long-term plan is that all tutorials get a full text, but for now this is exclusive to tutorials where I think that tl;dr and diff are not enough to get the idea.
  • 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 in QEMU.
    • Starting with tutorial 6, you can load and run the kernel on the real Raspberrys and observe output over UART.
  • Although 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!
  • For editing, I recommend Visual Studio Code with Rust Analyzer.
  • In addition to the tutorial text, also check out the make doc command in each tutorial. It lets you browse the extensively documented code in a convenient way.

Output of make doc

make doc

🛠 System Requirements

The tutorials are primarily targeted at Linux-based distributions. Most stuff will also work on other Unix flavors such as macOS, but this is only experimental.

🚀 The tl;dr Version

  1. Install Docker.

  2. Ensure your user account is in the docker group.

  3. Prepare the Rust toolchain. Most of it will be handled on first use through the rust-toolchain file. What's left for us to do is:

    1. If you already have a version of Rust installed:

      cargo install cargo-binutils rustfilt
    2. If you need to install Rust from scratch:

      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
      
      source $HOME/.cargo/env
      cargo install cargo-binutils rustfilt
  4. In case you use Visual Studio Code, I strongly recommend installing the Rust Analyzer extension.

  5. If you are NOT running Linux, some Ruby gems are needed as well:

    sudo gem install bundler
    bundle config set path '.vendor/bundle'
    bundle install

🧰 More Details: Eliminating Toolchain Hassle

This series tries to put a strong focus on user friendliness. Therefore, efforts were made to eliminate the biggest painpoint in embedded development as much as possible: Toolchain hassle.

Rust itself is already helping a lot in that regard, because it has built-in support for cross-compilation. All that we need for cross-compiling from an x86 host to the Raspberry Pi's AArch64 architecture will be automatically installed by rustup. However, besides the Rust compiler, we will use some more tools. Among others:

  • QEMU to emulate our kernel on the host system.
  • A self-made tool called Minipush to load a kernel onto the Raspberry Pi on-demand over UART.
  • OpenOCD and GDB for debugging on the target.

There is a lot that can go wrong while installing and/or compiling the correct version of each tool on your host machine. For example, your distribution might not provide the latest version that is needed. Or you are missing some hard-to-get dependencies for the compilation of one of these tools.

This is why we will make use of Docker whenever possible. We are providing an accompanying container that has all the needed tools or dependencies pre-installed, and it gets pulled in automagically once it is needed. If you want to know more about Docker and peek at the provided container, please refer to the repository's docker folder.

📟 USB Serial Output

Since the kernel developed in the tutorials runs on the real hardware, it is highly recommended to get a USB serial cable to get the full experience.

  • You can find USB-to-serial cables that should work right away at [1] [2], but many others will work too. Ideally, your cable is based on the CP2102 chip.
  • You connect it to GND and GPIO pins 14/15 as shown below.
  • Tutorial 6 is the first where you can use it. Check it out for instructions on how to prepare the SD card to boot your self-made kernel from it.
  • Starting with tutorial 7, booting kernels on your Raspberry is getting really comfortable. In this tutorial, a so-called chainloader is developed, which will be the last file you need to manually copy on the SD card for a while. It will enable you to load the tutorial kernels during boot on demand over UART.

UART wiring diagram

🙌 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 either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

GitHub

https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials
You might also like...

Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and "i2clib" integrated

Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and

raslib Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and "i2clib" integrated All tests are made on Raspberry PI 4B+ on Raspbia

Apr 12, 2022

A port of OxidGB to the Raspberry Pi Pico

OxidGB Pico Port This is a simple, display-only (for now) port of OxidGB to the Raspberry Pi Pico. Note that this by default overclocks your device -

May 15, 2022

Tested on Raspberry pi 3 on QEMU

Tested on Raspberry pi 3 on QEMU

Mar 10, 2022

A Raspberry Pi Pico-based sequencer for Eurorack

A Raspberry Pi Pico-based sequencer for Eurorack.

May 3, 2022

A hobby operating system, in Rust

intermezzOS: kernel intermezzOS is a hobby operating system. This repository is for its kernel. See the website for more. License This project is dual

May 24, 2022

A new operating system kernel with Linux binary compatibility written in Rust.

A new operating system kernel with Linux binary compatibility written in Rust.

Kerla Kerla is a monolithic operating system kernel from scratch in Rust which aims to be compatible with the Linux ABI, that is, runs Linux binaries

May 23, 2022

Operating system written in Rust for NumWorks calculator (model n0110)

RustWorks An OS (eventually) for the Numworks calculator (model n0110). Setup First install Rust by following these instuctions then: rustup target ad

May 13, 2022

SteinsOS is an operating system written in Rust

SteinsOS is an operating system featuring non-preemptive kernel targeting on single-core armv8 architecture.

May 8, 2022

MimiRust - Hacking the Windows operating system to hand us the keys to the kingdom with Rust.

MimiRust - Hacking the Windows operating system to hand us the keys to the kingdom with Rust.

MimiRust - Hacking the Windows operating system to hand us the keys to the kingdom with Rust. MimiRust is a program based on the wdigest attack vector

May 24, 2022

Xrs is a POSIX-subset operating system kernel written in Rust.

XRS-OS ( 🚧 WIP) Xrs is a POSIX-subset operating system kernel written in Rust. Current project team members 0x5459 core developer (he/him) 0x5457 cor

Feb 22, 2022

A simples rust operating system that prints hello world.

rust-os-helloworld A simples rust operating system that prints hello world. Just run: cargo install bootimage and: cargo bootimage Install QEMU and: q

Nov 24, 2021

An attempt at an operating system written in Rust

Rust Operating System An attempt at a simple operating system in Rust and a semester project for the Operating Systems course at [email protected] Documentation

Jan 15, 2022

Rux - An x86_64 toy operating system kernel written in Rust

Rux - An x86_64 toy operating system kernel written in Rust

Rux - An x86_64 toy operating system kernel written in Rust. Rux is a port of the Hux kernel, my x86 32-bit single-CPU toy kernel written in C, following the OSTEP book structure and terminology.

Feb 26, 2022

A Rust Operating System, written from the ground up

ThornOS A Rust Operating System, written from the ground up Build Dependencies Bootimage TODO: Document build process in more detail Acknowledgements

Mar 31, 2022

A Real Time Operating System in Rust for Cortex M3 embedded systems

A Real Time Operating System in Rust for Cortex M3 embedded systems

Apr 23, 2022

An experimental real-time operating system (RTOS) written in Rust

An experimental real-time operating system (RTOS) written in Rust

May 16, 2022

Mini operating system with a graphical interface, for x64 platforms, in Rust and Assembly

osmini Mini operating system with a graphical interface, for x64 platforms, in Rust and Assembly Build Don't forget to install the dependencies. This

Apr 20, 2022

A secure embedded operating system for microcontrollers

Tock is an embedded operating system designed for running multiple concurrent, mutually distrustful applications on Cortex-M and RISC-V based embedded

May 23, 2022

A secure embedded operating system for microcontrollers

Tock is an embedded operating system designed for running multiple concurrent, mutually distrustful applications on Cortex-M and RISC-V based embedded

May 26, 2022
Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and "i2clib" integrated
Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and

raslib Raspberry PI library for Rust. GPIO controller, L298N motors, sockets and "i2clib" integrated All tests are made on Raspberry PI 4B+ on Raspbia

Apr 12, 2022
Everything you need to know about cross compiling Rust programs!

rust-cross Everything you need to know about cross compiling Rust programs! If you want to set up your Rust toolchain as a cross compiler, you have co

May 21, 2022
Vue's template compiler reimplemented in Rust!

vue template compiler in Rust https://github.com/vuejs/rfcs/discussions/369#discussioncomment-1192421 Maybe in the long run we want the whole transfor

May 13, 2022
A Brainheck compiler written in Rust.

Brainhecc A compiler for Brain[hecc] programs, written in Rust with Cranelift. It compiles any valid Brainhecc program into an executable binary. Inst

Oct 28, 2021
A LED Christmas Tree controlled by Rust. Contribute your own renderers!
A LED Christmas Tree controlled by Rust. Contribute your own renderers!

Rusty Christmas Tree This is code that draws on the LED Christmas Tree made by @aidancrowther. You can see his 3D design files and Pi Pico setup code

May 15, 2022
A lightweight microkernel/IPC based operating system built with Rust which is not a clone of any existing operating system
A lightweight microkernel/IPC based operating system built with Rust which is not a clone of any existing operating system

Noble Operating System Noble is a lightweight microkernel and IPC based operating system built with Rust which is not a clone of any existing operatin

Jan 10, 2022
This is the repository with the tutorials of Learning Rust series in @Leticia-maria Youtube channel
This is the repository with the tutorials of Learning Rust series in @Leticia-maria Youtube channel

Rust Tutorials This repository contains the information of Learning Rust playlist in my youtube channel. Learning Rust(part. 1)! Installation on Ubunt

May 24, 2022
Tutorials for Piston

Piston-Tutorials This is a repository for examples of Piston projects that have are accompanied by written tutorials explaining core concepts for that

May 10, 2022
[OUTDATED] Instructions for how to cross compile Rust projects for the Raspberry Pi

Cross Compiling for Raspberry Pi This guide will show how Rust programs can be cross compiled for the Raspberry Pi using Cargo. These instructions may

Apr 4, 2022
Program a Raspberry Pi Pico with pure Rust

pi-pico-rs Program a Raspberry Pi Pico with pure Rust. Get Started Install the latest version of Rust and the thumbv6m-none-eabi target. This is the p

Mar 15, 2022