Repository files navigation

This is a tutorial series for hobby OS developers who are new to ARM's 64 bitARMv8-Aarchitecture. The tutorials will give a guided, step-by-step tour of how to write amonolithicOperating Systemkernel for anembedded system from scratch. They cover implementation of commonOperating Systems tasks, like writing to the serial console, setting up virtual memory and handlingHW exceptions. All while leveragingRust's unique features to provide for safety and speed.

Have fun!

Best regards,
Andre (@andre-richter)

P.S.: For other languages, please look out for alternative README files. For example,README.CN.md orREADME.ES.md. Many thanks to ourtranslators 🙌.

• Each tutorial contains a stand-alone, bootablekernel binary.
• Each new tutorial extends the previous one.
• Each tutorialREADME 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 thechanges/additions.
  • Some tutorials have a full-fledged, detailed text in addition to thetl;dr section. Thelong-term plan is that all tutorials get a full text, but for now this is exclusive totutorials where I think thattl;dr anddiff are not enough to get the idea.
• The code written in these tutorials supports and runs on theRaspberry Pi 3 and theRaspberry Pi 4.
  • Tutorials 1 till 5 are groundwork code which only makes sense to run inQEMU.
  • Starting withtutorial 5, you can load and run the kernel on the realRaspberrys and observe output overUART.
• Although the Raspberry Pi 3 and 4 are the main target boards, the code is written in a modularfashion which allows for easy porting to other CPU architectures and/or boards.
  • I would really love if someone takes a shot at aRISC-V implementation!
• For editing, I recommendVisual Studio Code withRust Analyzer.
• In addition to the tutorial text, also check out themake doc command in each tutorial. It letsyou browse the extensively documented code in a convenient way.

The tutorials are primarily targeted atLinux-based distributions. Most stuff will also work onmacOS, but this is onlyexperimental.

1. Install Docker Engine.

2. (Linux only) Ensure your user account is in thedocker group.

3. Prepare theRust toolchain. Most of it will be handled on first use through therust-toolchain.toml 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| shsource$HOME/.cargo/envcargo install cargo-binutils rustfilt

4. In case you useVisual Studio Code, I strongly recommend installing theRust Analyzer extension.

5. (macOS only) Install a fewRuby gems.

This was last tested by the author with Ruby version3.0.2 onmacOS Monterey. If you are usingrbenv, the respective.ruby-version file is already in place. If you never heard ofrbenv,try usingthis little guide.

Run this in the repository root folder:

bundle configset --local path'.vendor/bundle'bundle configset --local without'development'bundle install

This series tries to put a strong focus on user friendliness. Therefore, efforts were made toeliminate 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 forcross-compilation. All that we need for cross-compiling from anx86 host to the Raspberry Pi'sAArch64 architecture will be automatically installed byrustup. However, besides the Rustcompiler, we will use some more tools. Among others:

• QEMU to emulate our kernel on the host system.
• A self-made tool calledMinipush 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 toolon your host machine. For example, your distribution might not provide the latest version that isneeded. Or you are missing some hard-to-get dependencies for the compilation of one of these tools.

This is why we will make use ofDocker whenever possible. We are providing anaccompanying container that has all the needed tools or dependencies pre-installed, and it getspulled in automagically once it is needed. If you want to know more about Docker and peek at theprovided container, please refer to the repository'sdocker folder.

Since the kernel developed in the tutorials runs on the real hardware, it is highly recommended toget 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 otherswill work too. Ideally, your cable is based on theCP2102 chip.
• You connect it toGND and GPIO pins14/15 as shown below.
• Tutorial 5 is the first where you can use it. Check it out forinstructions on how to prepare the SD card to boot your self-made kernel from it.
• Starting withtutorial 6, booting kernels on your Raspberry is gettingreally comfortable. In this tutorial, a so-calledchainloader is developed, which will be thelast file you need to manually copy on the SD card for a while. It will enable you to load thetutorial kernels during boot on demand overUART.

The original version of the tutorials started out as a fork ofZoltanBaldaszti's awesometutorials on bare metal programming onRPi3 inC. Thanks for giving me a head start!

• Chinese
  • @colachg and@readlnh.
  • Need updating.
• Spanish
  • @zanezhub.
  • In the future there'll be tutorials translated to spanish.

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttps://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttps://opensource.org/licenses/MIT)

at your option.

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