|
|
|
|
@ -2,75 +2,75 @@
|
|
|
|
|
|
|
|
|
|
 
|
|
|
|
|
|
|
|
|
|
## ⚠️ Info
|
|
|
|
|
## ℹ️ Introduction
|
|
|
|
|
|
|
|
|
|
**This is a work-in-progress rewrite, started on September 2019.** You can find the original version of the tutorials
|
|
|
|
|
[here](https://github.com/rust-embedded/rust-raspi3-OS-tutorials/tree/original_version).
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Some general info:
|
|
|
|
|
- Tutorials that existed before the rewrite have a full-fledged tutorial
|
|
|
|
|
text, while most new tutorials will only contain a short`tl;dr` section for now.
|
|
|
|
|
I plan to provide full-fledged text for all tutorials once the kernel has reached
|
|
|
|
|
a certain milestone.
|
|
|
|
|
_Cheers,
|
|
|
|
|
[Andre](https://github.com/andre-richter)_
|
|
|
|
|
|
|
|
|
|
[ARMv8-A architecture]: https://developer.arm.com/products/architecture/cpu-architecture/a-profile/docs
|
|
|
|
|
[monolithic]: https://en.wikipedia.org/wiki/Monolithic_kernel
|
|
|
|
|
|
|
|
|
|
## Organization
|
|
|
|
|
|
|
|
|
|
- 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 on
|
|
|
|
|
QEMU.
|
|
|
|
|
- Tutorials 1 till 5 are groundwork code which only makes sense to run in
|
|
|
|
|
`QEMU`.
|
|
|
|
|
- Starting with [tutorial 6](06_drivers_gpio_uart), you can load and run the
|
|
|
|
|
kernel on Raspberrys and observe output over UART.
|
|
|
|
|
kernel on 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 the [Rust Language Server]
|
|
|
|
|
extension.
|
|
|
|
|
- Check out the `make doc` command to browse the code with HTML goodness.
|
|
|
|
|
|
|
|
|
|
_Cheers,
|
|
|
|
|
[Andre](https://github.com/andre-richter)_
|
|
|
|
|
|
|
|
|
|
- In addition to the tutorial text, also check out the `make doc` command to
|
|
|
|
|
browse the code with HTML goodness.
|
|
|
|
|
|
|
|
|
|
[Visual Studio Code]: https://code.visualstudio.com
|
|
|
|
|
[Rust Language Server]: https://github.com/rust-lang/rls
|
|
|
|
|
|
|
|
|
|
## ℹ️ Introduction
|
|
|
|
|
|
|
|
|
|
The target audience is hobby OS developers who are new to ARM's 64 bit [ARMv8-A
|
|
|
|
|
architecture](https://developer.arm.com/products/architecture/cpu-architecture/a-profile/docs).
|
|
|
|
|
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 exception handling. All while
|
|
|
|
|
leveraging Rust's unique features to provide for safety and speed.
|
|
|
|
|
|
|
|
|
|
[monolithic]: https://en.wikipedia.org/wiki/Monolithic_kernel
|
|
|
|
|
|
|
|
|
|
While 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.
|
|
|
|
|
|
|
|
|
|
## ✔️ Ease of use
|
|
|
|
|
|
|
|
|
|
This repo tries to put a focus on user friendliness. Therefore, I made some
|
|
|
|
|
This series tries to put a strong focus on user friendliness. Therefore, I made
|
|
|
|
|
efforts to eliminate the biggest painpoint in embedded development: Toolchain
|
|
|
|
|
hassles.
|
|
|
|
|
|
|
|
|
|
Users eager to try the code should not be bothered with complicated toolchain
|
|
|
|
|
installation/compilation steps. This is achieved by trying to use the standard
|
|
|
|
|
Rust toolchain as much as possible, and bridge existing gaps with Docker
|
|
|
|
|
containers. [Please install Docker for your
|
|
|
|
|
distro](https://docs.docker.com/install/).
|
|
|
|
|
Users eager to try the code will not be bothered with complicated toolchain
|
|
|
|
|
installation/compilation steps. This is achieved by using the standard Rust
|
|
|
|
|
toolchain as much as possible, and provide all additional tooling through an
|
|
|
|
|
accompanying Docker container. The container will be pulled in automagically
|
|
|
|
|
once it is needed. The only requirement is that you have [installed Docker for
|
|
|
|
|
your distro](https://docs.docker.com/install/).
|
|
|
|
|
|
|
|
|
|
The setup consists of the following components:
|
|
|
|
|
The development setup consists of the following components:
|
|
|
|
|
|
|
|
|
|
- Compiler, linker and binutils are used from Rust nightly.
|
|
|
|
|
- Additional OS Dev tools, like QEMU, are pre-packaged into [this
|
|
|
|
|
- Additional OS Dev tools, like `QEMU` or `GDB`, are provided by [this
|
|
|
|
|
container](docker/rustembedded-osdev-utils).
|
|
|
|
|
|
|
|
|
|
If you want to know more about docker and peek at the the containers used in
|
|
|
|
|
these tutorials, please refer to the repository's docker folder.
|
|
|
|
|
If you want to know more about docker and peek at the the container used for the
|
|
|
|
|
tutorials, please refer to the repository's [docker](docker) folder.
|
|
|
|
|
|
|
|
|
|
## 🛠 Prerequisites
|
|
|
|
|
|
|
|
|
|
Before you can start, you'll need a suitable Rust toolchain.
|
|
|
|
|
Before you can start, you must install a suitable Rust toolchain:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl https://sh.rustup.rs -sSf \
|
|
|
|
|
|
Andre Richter
4 years ago