rust-raspberrypi-OS-tutorials README

The project's README from github.com/rust-embedded/rust-raspberrypi-OS-tutorials. As one markdown file: README.md.

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

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:

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.

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

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.

rust-raspberrypi-OS-tutorials (rust-embedded/rust-raspberrypi-OS-tutorials)

Searching Database…

14.7K ·GitHub
Rust-raspberrypi-OS-tutorials
Что это?Пошаговый учебный курс, который показывает, как с нуля написать собственное ядро встраиваемой операционной системы на Rust для Raspberry Pi 3 и 4.
Это готовая ОС или учебный курс?Это учебный курс из последовательных уроков. Каждый урок содержит самостоятельный загрузочный бинарный файл ядра, который опирается на предыдущий, а также diff с предыдущим уроком, чтобы можно было точно увидеть, что изменилось.
Как мне запустить ядро из урока?Установите Docker Engine, подготовьте набор инструментов Rust (в основном он настраивается автоматически через rust-toolchain.toml), затем соберите и запустите ядро в QEMU. Начиная с урока 5, его также можно загрузить на настоящую Raspberry Pi через UART.
Какие инструменты мне нужны, помимо самого Rust?Нужен Docker (проект загружает контейнер с предустановленными QEMU, OpenOCD и GDB), rustup для кросс-компиляции, а на macOS — пара гемов Ruby. Для работы с реальным оборудованием рекомендуется USB-to-serial кабель (желательно на базе CP2102).
Одинаково ли это работает на macOS и Linux?Уроки в первую очередь рассчитаны на Linux. Поддержка macOS пока экспериментальная, а уроки 1-5 — подготовительная часть, предназначенная для запуска только в QEMU, а не на реальном оборудовании.
Для кого этот курс?Для энтузиастов, которые пишут операционные системы в свободное время, которые незнакомы с 64-битной архитектурой ARMv8-A и хотят получить пошаговое введение в написание кода уровня ядра на Rust.
Какие темы на самом деле охватывает серия?Типичные задачи ОС, например вывод в последовательную консоль, настройка виртуальной памяти и обработка аппаратных исключений, которые реализуются пошагово с использованием механизмов безопасности Rust.
Нужно ли мне специальное оборудование, чтобы следовать курсу?Нет. Первые пять уроков — подготовительная часть, которая полностью работает в QEMU. Начиная с урока 5, ядро можно прошить на настоящую Raspberry Pi 3 или 4 и смотреть вывод через USB-кабель для последовательного порта.
Можно ли портировать это на другую плату или архитектуру?Да. Автор специально построил код модульно, чтобы упростить портирование на другие архитектуры процессоров и платы, и даже приглашает участников попробовать портировать его на RISC-V.
What are similar projects?raspberry-pi-os, linux, lytlnyblOS, redox, mu300-linux, flash-linux0.11-talk, sherpa-onnx, zxdesk
Which topics is it in?aarch64, bare-metal, os, embedded-systems, operating-system, arm64, kernel, raspberry-pi, embedded, hardware, guide, command-line
Creator
rust-embedded
Size
20.7 MB
Stars
14.7K
Updated
CommitDec 14
Age
8y
Commits · 90 Days