Awesome
Operating System development tutorials in Rust on the Raspberry Pi
<img src="doc/header.jpg" height="372"> <img src="doc/minipush_demo_frontpage.gif" height="372">
âšī¸ 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,<br>Andre (@andre-richter)
P.S.: For other languages, please look out for alternative README files. For example,
README.CN.md
or README.ES.md
. Many thanks to our
translators đ.
đ Organization
- Each tutorial contains a stand-alone, bootable
kernel
binary. - Each new tutorial extends the previous one.
- Each tutorial
README
will have a shorttl;dr
section giving a brief overview of the additions, and show the source codediff
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 thattl;dr
anddiff
are not enough to get the idea.
- Some tutorials have a full-fledged, detailed text in addition to the
- 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 5, you can load and run the kernel on the real
Raspberrys and observe output over
UART
.
- Tutorials 1 till 5 are groundwork code which only makes sense to run in
- 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
đ System Requirements
The tutorials are primarily targeted at Linux-based distributions. Most stuff will also work on macOS, but this is only experimental.
đ The tl;dr Version
-
(Linux only) Ensure your user account is in the docker group.
-
Prepare the
Rust
toolchain. Most of it will be handled on first use through the rust-toolchain.toml file. What's left for us to do is:-
If you already have a version of Rust installed:
cargo install cargo-binutils rustfilt
-
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
-
-
In case you use
Visual Studio Code
, I strongly recommend installing the Rust Analyzer extension. -
(macOS only) Install a few
Ruby
gems.
This was last tested by the author with Ruby version 3.0.2
on macOS Monterey
. If you are using
rbenv
, the respective .ruby-version
file is already in place. If you never heard of rbenv
,
try using this little guide.
Run this in the repository root folder:
bundle config set --local path '.vendor/bundle'
bundle config set --local without 'development'
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 overUART
. OpenOCD
andGDB
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 pins14/15
as shown below. - Tutorial 5 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 6, 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 overUART
.
đ 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!
Translations of this repository
- Chinese
- Spanish
- @zanezhub.
- In the future there'll be tutorials translated to spanish.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
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.