📚 Learn to write an embedded OS in Rust 🦀
Go to file
Andre Richter 2c3f705051
Update dependencies
register-rs 1.0.0 now uses UnsafeCell internally, which means we lost the Copy
derive on InMemoryRegister.

Therefore, a small set of changes was needed in the MMU driver to dance around
the static array init depending on a Copy type.
2020-11-23 22:34:20 +01:00
.githooks Integrate prettier into toolflow 2020-09-25 21:24:02 +02:00
.github Workflows: Bump versions 2020-09-25 21:48:43 +02:00
.vscode Run of prettier over whole repo 2020-09-25 21:24:56 +02:00
00_before_we_start Fix 00_before_we_start/README.CN.md 2020-08-01 22:31:56 +02:00
01_wait_forever Demangle++: Pipe through rustfilt 2020-11-20 22:27:21 +01:00
02_runtime_init Demangle++: Pipe through rustfilt 2020-11-20 22:27:21 +01:00
03_hacky_hello_world Demangle++: Pipe through rustfilt 2020-11-20 22:27:21 +01:00
04_zero_overhead_abstraction Update dependencies 2020-11-23 22:34:20 +01:00
05_safe_globals Update dependencies 2020-11-23 22:34:20 +01:00
06_drivers_gpio_uart Update dependencies 2020-11-23 22:34:20 +01:00
07_uart_chainloader Update dependencies 2020-11-23 22:34:20 +01:00
08_timestamps Update dependencies 2020-11-23 22:34:20 +01:00
09_hw_debug_JTAG Update dependencies 2020-11-23 22:34:20 +01:00
10_privilege_level Update dependencies 2020-11-23 22:34:20 +01:00
11_virtual_mem_part1_identity_mapping Update dependencies 2020-11-23 22:34:20 +01:00
12_exceptions_part1_groundwork Update dependencies 2020-11-23 22:34:20 +01:00
13_integrated_testing Update dependencies 2020-11-23 22:34:20 +01:00
14_exceptions_part2_peripheral_IRQs Update dependencies 2020-11-23 22:34:20 +01:00
15_virtual_mem_part2_mmio_remap Update dependencies 2020-11-23 22:34:20 +01:00
doc Add tutorial 15: MMIO Remap 2020-10-04 22:05:35 +02:00
docker Switch to GCC objdump and nm 2020-11-01 15:58:05 +01:00
utils Bump rubocop version; Fix issues 2020-11-14 10:25:00 +01:00
X1_JTAG_boot Update dependencies 2020-11-23 22:34:20 +01:00
.editorconfig Add line length to editorconfig 2020-09-24 23:30:56 +02:00
.gitignore Add prettier for .json and .yml 2020-09-25 21:23:15 +02:00
.prettierignore Adapt ignore file 2020-09-25 21:40:50 +02:00
.prettierrc.json Add prettier for .json and .yml 2020-09-25 21:23:15 +02:00
.rubocop.yml rubocop: Enable new cops 2020-07-12 15:09:32 +02:00
.rustfmt.toml
contributor_setup.sh Add prettier for .json and .yml 2020-09-25 21:23:15 +02:00
devtool devtool: symlink + clippy for rpi4 2020-03-24 21:57:58 +01:00
devtool_completion.bash autocomplete for devtool 2020-07-29 08:33:45 +02:00
Gemfile Bump rubocop version; Fix issues 2020-11-14 10:25:00 +01:00
LICENSE-APACHE Relicense as dual MIT OR Apache-2.0 2019-11-25 19:54:05 +01:00
LICENSE-MIT Copyright bump to 2020 🎆 2020-01-02 00:41:03 +01:00
README.CN.md Demangle++: Pipe through rustfilt 2020-11-20 22:27:21 +01:00
README.md Demangle++: Pipe through rustfilt 2020-11-20 22:27:21 +01:00
SPONSORING.md Fix some old links 2020-04-11 12:38:49 +02:00

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. Install a suitable Rust toolchain:

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

      rustup toolchain add nightly-2020-11-20
      rustup default nightly-2020-11-20
      rustup component add llvm-tools-preview
      rustup target add aarch64-unknown-none-softfloat
      cargo install cargo-binutils rustfilt
      
    2. If you need a fresh install:

      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- \
          --default-toolchain nightly-2020-11-20                           \
          --component llvm-tools-preview
      
      source $HOME/.cargo/env
      rustup target add aarch64-unknown-none-softfloat
      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
    

🧰 The Long Version: 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 is to install the respective target through 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 debug cable to get the full experience. The cable also powers the Raspberry once you connect it, so you don't need extra power over the dedicated power-USB.

  • You can find USB-to-serial cables that should work right away at [1] [2].
  • You connect it to the 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.