diff --git a/README.md b/README.md index 688f6eb6..2497432b 100644 --- a/README.md +++ b/README.md @@ -2,26 +2,74 @@ ## Notice -**This is a work-in-progress rewrite, started on September 2019. I will first add -code and minimal READMEs, and later write accompanying full-fledged tutorial -text.** +**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). +They are worth checking out for some advanced features that are not yet +rewritten, like _virtual memory_ or _exception handling_. They will be ported +over soon, though (if time permits). -- 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. - - Starting with [tutorial 6](06_drivers_gpio_uart), you can load and run the kernel on Raspberrys and observe output over UART. -- For practical purposes, the kernel will be a classic [monolith]. -- For editing, I recommend [Visual Studio Code] with the [Rust Language Server] extension. +Some info on the rewrite and in general: +- I will first add +code and minimal READMEs, and later write accompanying full-fledged tutorial +text. +- 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. + - Starting with [tutorial 6](06_drivers_gpio_uart), you can load and run the + kernel on Raspberrys and observe output over UART. +- 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. -- Note that the branch is subject to frequent force pushing. If updates happened - since you last visited, make sure to clone a clean copy to be safe. _Cheers, [Andre](https://github.com/andre-richter)_ - [monolith]: https://en.wikipedia.org/wiki/Monolithic_kernel + [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` 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 +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/). + +The 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 + 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. + ## Prerequisites Before you can start, you'll need a suitable Rust toolchain. @@ -38,17 +86,26 @@ cargo install cargo-xbuild cargo-binutils ## USB Serial -It is highly recommended to get a USB serial debug cable. It also powers the Raspberry once you -connect it, so you don't need extra power over the dedicated power-USB. I use a bunch of +It is highly recommended to get a USB serial debug cable. It also powers the +Raspberry once you connect it, so you don't need extra power over the dedicated +power-USB. I use a bunch of [these](https://www.amazon.de/dp/B0757FQ5CX/ref=cm_sw_r_tw_dp_U_x_ozGRDbVTJAG4Q). You connect it to the GPIO pins 14/15 as shown beyond. -[Tutorial 6](06_drivers_gpio_uart) is the first where you can use it. Go to the README there -for instructions on how to prepare the SD card to run your self-made kernels from it. +[Tutorial 6](06_drivers_gpio_uart) is the first where you can use it. Go to the +README there for instructions on how to prepare the SD card to run your +self-made kernels from it. ![UART wiring diagram](doc/wiring.png) +## Acknowledgements + +The original version of the tutorials started out as a fork of [Zoltan +Baldaszti](https://github.com/bztsrc)'s awesome [tutorials on bare metal +programming on RPi3](https://github.com/bztsrc/raspi3-tutorial) in `C`. Thanks +for giving me a head start! + ## License Licensed under the MIT license ([LICENSE-MIT](LICENSE) or http://opensource.org/licenses/MIT).