diff --git a/06_drivers_gpio_uart/README.md b/06_drivers_gpio_uart/README.md
index c5063102..dcc46661 100644
--- a/06_drivers_gpio_uart/README.md
+++ b/06_drivers_gpio_uart/README.md
@@ -3,8 +3,8 @@
## tl;dr
Now that we enabled safe globals in the previous tutorial, the infrastructure is laid for adding the
-first real device drivers. We throw out the magic QEMU console and use a real UART now. Like serious
-embedded hackers do!
+first real device drivers. We throw out the magic QEMU console and use a real `UART` now. Like
+serious embedded hackers do!
## Notable additions
@@ -71,6 +71,9 @@ on the SD card._
$ sudo screen /dev/ttyUSB0 230400
```
+> â **NOTE**: Depending on your host operating system, the serial device name might differ.
+> For example, on `macOS`, it might be something like `/dev/tty.usbserial-0001`.
+
7. Hit Enter to kick off the kernel boot process. Observe the output:
```console
diff --git a/07_uart_chainloader/README.md b/07_uart_chainloader/README.md
index 6b69befd..57f92a96 100644
--- a/07_uart_chainloader/README.md
+++ b/07_uart_chainloader/README.md
@@ -21,6 +21,12 @@ You can try it with this tutorial already:
4. Now plug in the USB Serial.
5. Observe the loader fetching a kernel over `UART`:
+> â **NOTE**: By default, `make chainboot` tries to connect to `/dev/ttyUSB0`.
+> Should the USB serial on your system have a different name, you have to provide it explicitly. For
+> exmaple:
+>
+> `DEV_SERIAL=/dev/tty.usbserial-0001 make chainboot`
+
[raspbootin]: https://github.com/mrvn/raspbootin
```console
diff --git a/README.md b/README.md
index 6e6b80ee..73035b75 100644
--- a/README.md
+++ b/README.md
@@ -8,17 +8,18 @@
## âšī¸ 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.
+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.
-_Cheers, Andre ([@andre-richter])_
+Have fun!
-P.S.: In the future, Chinese :cn: versions of the tutorials will be maintained as [`README.CN.md`](README.CN.md) by [@colachg] and [@readlnh].
+_Best regards,
Andre ([@andre-richter])_
+
+P.S.: In the future, Chinese :cn: versions of the tutorials will be maintained as
+[`README.CN.md`](README.CN.md) by [@colachg] and [@readlnh].
[ARMv8-A architecture]: https://developer.arm.com/products/architecture/cpu-architecture/a-profile/docs
[monolithic]: https://en.wikipedia.org/wiki/Monolithic_kernel
@@ -30,25 +31,23 @@ P.S.: In the future, Chinese :cn: versions of the tutorials will be maintained a
- 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.
+- 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 6](06_drivers_gpio_uart), you can load and run the
- 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.
+- 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 6](06_drivers_gpio_uart), 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 to browse
- the code, which is extensively documented.
+- 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`
@@ -57,36 +56,18 @@ P.S.: In the future, Chinese :cn: versions of the tutorials will be maintained a
[Visual Studio Code]: https://code.visualstudio.com
[Rust Analyzer]: https://rust-analyzer.github.io
-## đ Ease of use
-
-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 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 development setup consists of the following components:
+## đ System Requirements
-- Compiler, linker and binutils are used from Rust nightly.
-- Additional OS Dev tools, like `QEMU` or `GDB`, are provided by [this
- container](docker/rustembedded-osdev-utils).
+The tutorials are primarily targeted at **Linux**-based distributions. Most stuff will also work on
+other Unix flavors such as **macOS**, but this is only _experimental_.
-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.
+### đ The tl;dr Version
-## đ Prerequisites
-
-Before you can start, you must install a suitable Rust toolchain:
+1. [Install Docker][install_docker].
+2. Install a suitable `Rust` toolchain:
```bash
-curl https://sh.rustup.rs -sSf \
- | \
- sh -s -- \
+curl https://sh.rustup.rs -sSf | sh -s -- \
--default-toolchain nightly-2020-04-07 \
--component llvm-tools-preview rustfmt
@@ -95,49 +76,77 @@ rustup target add aarch64-unknown-none-softfloat
cargo install cargo-binutils
```
-In case you use `Visual Studio Code`, I strongly recommend installing the
-[Rust Analyzer extension] as well.
+3. In case you use `Visual Studio Code`, I strongly recommend installing the [Rust Analyzer extension].
+4. If you are **NOT** running Linux, some `Ruby` gems are needed as well:
+
+```bash
+sudo gem install bundler
+bundle install --path .vendor/bundle
+```
[Rust Analyzer extension]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer
+### 𧰠The Long Version: 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 is to install the respective target through `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][install_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](docker) folder.
+
+[install_docker]: https://docs.docker.com/install
+
## đ USB Serial Output
-Since the kernel developed in the tutorials runs on the real hardware, it is
-highly recommended to get a USB serial debug cable to make the experience.
-The cable also powers the Raspberry once you connect it, so you don't need extra
-power over the dedicated power-USB.
+Since the kernel developed in the tutorials runs on the real hardware, it is highly recommended to
+get a USB serial debug cable to get the full experience. The cable 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 serial cables](https://www.amazon.de/dp/B0757FQ5CX/ref=cm_sw_r_tw_dp_U_x_ozGRDbVTJAG4Q).
+- I use a bunch of [these serial cables].
- You connect it to the GPIO pins `14/15` as shown below.
-- [Tutorial 6](06_drivers_gpio_uart) 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 7](07_uart_chainloader), 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`.
+- [Tutorial 6](06_drivers_gpio_uart) 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 7](07_uart_chainloader), 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](doc/wiring.png)
+[these serial cables]: https://www.amazon.de/dp/B0757FQ5CX/ref=cm_sw_r_tw_dp_U_x_ozGRDbVTJAG4Q
+
## đ 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!
+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 either of
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
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.
+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.