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.