Convert Figma logo to code with AI

rust-embedded logorust-raspberrypi-OS-tutorials

:books: Learn to write an embedded OS in Rust :crab:

13,476
783
13,476
13
View on GitHub

Top Related Projects

phil-opp's avatar

blog_os

14,568

Writing an OS in Rust

s-matyukevich's avatar

raspberry-pi-os

13,132

Learning operating system development using Linux kernel and Raspberry Pi

bztsrc's avatar

raspi3-tutorial

2,716

Bare metal Raspberry Pi 3 tutorials

rcore-os's avatar

rCore-Tutorial-v3

1,579

Let's write an OS which can run on RISC-V in Rust from scratch!

Quick Overview

The rust-embedded/rust-raspberrypi-OS-tutorials repository is a comprehensive series of tutorials for learning embedded systems development using Rust on the Raspberry Pi. It guides users through building a bare-metal operating system from scratch, covering topics from basic boot code to more advanced concepts like virtual memory and multitasking.

Pros

  • Provides hands-on experience with low-level programming and OS development
  • Teaches Rust in the context of embedded systems, promoting safe and efficient code
  • Offers a structured learning path with incremental complexity
  • Includes detailed explanations and comments throughout the code

Cons

  • Requires specific hardware (Raspberry Pi) for practical implementation
  • May be challenging for beginners with no prior experience in systems programming
  • Limited to Raspberry Pi architecture, not directly applicable to other platforms
  • Requires a significant time investment to work through all tutorials

Getting Started

  1. Clone the repository:

    git clone https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials.git
cd rust-raspberrypi-OS-tutorials

  2. Install dependencies:

    • Rust (nightly toolchain)
    • QEMU (for emulation)
    • Raspberry Pi 3 or 4 (for hardware testing)

  3. Choose a tutorial (e.g., 05_drivers_gpio_uart):

    cd 05_drivers_gpio_uart

  4. Build and run in QEMU:

    make qemu

  5. To run on actual hardware, build and copy to an SD card:

    make
sudo dd if=kernel8.img of=/dev/sdX bs=4M conv=fsync

    (Replace /dev/sdX with your SD card device)

For detailed instructions and explanations, refer to the README.md file in each tutorial directory.

Competitor Comparisons

phil-opp logo

blog_os

14,568

Writing an OS in Rust

Pros of blog_os

  • Focuses on x86_64 architecture, which is more common for desktop and server environments
  • Provides a comprehensive, step-by-step guide for building an OS from scratch
  • Includes detailed explanations of OS concepts and Rust implementation

Cons of blog_os

  • Limited to x86_64 architecture, not covering embedded systems like Raspberry Pi
  • May not cover some specific hardware interactions relevant to embedded development
  • Less emphasis on bare-metal programming concepts

Code Comparison

blog_os:

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");
    loop {}
}

rust-raspberrypi-OS-tutorials:

#[no_mangle]
pub extern "C" fn kernel_main() -> ! {
    uart::init();
    uart::puts("Hello from Rust!\n");
    loop {}
}

Both projects use similar bare-metal entry points, but rust-raspberrypi-OS-tutorials initializes UART for communication, while blog_os uses a higher-level println! macro.

The rust-raspberrypi-OS-tutorials repository focuses on embedded systems, specifically Raspberry Pi, providing hands-on experience with ARM architecture and low-level hardware interactions. It offers a series of tutorials progressing from basic bare-metal programming to more advanced OS concepts.

blog_os, on the other hand, provides a comprehensive guide for building a 64-bit operating system using Rust, covering topics like memory management, interrupts, and multitasking. It's an excellent resource for understanding OS development on modern PC hardware.

s-matyukevich logo

raspberry-pi-os

13,132

Learning operating system development using Linux kernel and Raspberry Pi

Pros of raspberry-pi-os

  • Uses C language, which is more familiar to many developers and has a lower learning curve
  • Provides a step-by-step tutorial with detailed explanations for each concept
  • Focuses on bare-metal programming, offering a deeper understanding of low-level operations

Cons of raspberry-pi-os

  • Less memory-safe compared to Rust-based alternatives
  • May require more manual memory management and error handling
  • Limited to C language features, missing out on Rust's modern language capabilities

Code Comparison

raspberry-pi-os (C):

void kernel_main(uint32_t r0, uint32_t r1, uint32_t atags)
{
    uart_init();
    uart_send_string("Hello, world!\r\n");

    while (1) {
        uart_send(uart_recv());
    }
}

rust-raspberrypi-OS-tutorials (Rust):

#[no_mangle]
pub extern "C" fn kernel_main() -> ! {
    let uart = unsafe { Uart::new(UART_BASE) };
    uart.send_string("Hello, world!\n");

    loop {
        uart.send(uart.receive());
    }
}

Both examples initialize UART and implement a simple echo program. The Rust version benefits from stronger type safety and memory safety guarantees, while the C version is more straightforward but requires careful handling of memory and types.

bztsrc logo

raspi3-tutorial

2,716

Bare metal Raspberry Pi 3 tutorials

Pros of raspi3-tutorial

  • Written in C, which may be more familiar to some developers
  • Covers a wider range of topics, including graphics and USB support
  • Provides more detailed explanations of low-level concepts

Cons of raspi3-tutorial

  • Less structured learning path compared to rust-raspberrypi-OS-tutorials
  • May not be as up-to-date with the latest Raspberry Pi hardware
  • Lacks the memory safety benefits inherent to Rust

Code Comparison

raspi3-tutorial (C):

void main()
{
    uart_init();
    uart_puts("Hello World!\n");
    while(1);
}

rust-raspberrypi-OS-tutorials (Rust):

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World!");
    loop {}
}

Both examples demonstrate a simple "Hello World" program, but the Rust version showcases its built-in safety features and more modern syntax. The C version requires explicit UART initialization, while Rust abstracts this complexity away.

The raspi3-tutorial provides a more traditional bare-metal programming experience, suitable for those wanting to understand low-level details. In contrast, rust-raspberrypi-OS-tutorials offers a more modern approach with Rust's safety guarantees and abstractions, making it potentially easier for beginners to avoid common pitfalls in OS development.

rcore-os logo

rCore-Tutorial-v3

1,579

Let's write an OS which can run on RISC-V in Rust from scratch!

Pros of rCore-Tutorial-v3

  • Focuses on building a complete operating system from scratch, providing a deeper understanding of OS concepts
  • Implements a RISC-V based OS, offering exposure to a modern and open instruction set architecture
  • Includes comprehensive documentation in both English and Chinese, making it accessible to a wider audience

Cons of rCore-Tutorial-v3

  • Requires more advanced knowledge of operating systems and computer architecture
  • Less beginner-friendly compared to rust-raspberrypi-OS-tutorials
  • May have a steeper learning curve for those not familiar with RISC-V architecture

Code Comparison

rCore-Tutorial-v3:

#[no_mangle]
pub fn rust_main() -> ! {
    clear_bss();
    println!("Hello, world!");
    panic!("Shutdown machine!");
}

rust-raspberrypi-OS-tutorials:

#[no_mangle]
pub extern "C" fn kernel_main() -> ! {
    println!("Hello from Rust!");
    cpu::wait_forever();
}

Both examples show the main entry point of the kernel, but rCore-Tutorial-v3 includes additional setup steps like clearing the BSS section. The rust-raspberrypi-OS-tutorials example is simpler and more focused on the Raspberry Pi hardware.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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.: 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 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 5, 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 macOS, but this is only experimental.

🚀 The tl;dr Version

  1. Install Docker Engine.

  2. (Linux only) 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.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 | 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. (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 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 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 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!

Translations of this repository

  • Chinese
  • Spanish
    • @zanezhub.
    • In the future there'll be tutorials translated to spanish.

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.