I’ve been working through an excellent series of tutorials from Andre Richter on writing an operating system for the Raspberry Pi – https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials. I’m excited to now have my own Rust project kernel to mess around with, especially one that I can flash onto a single-board computer like the Raspberry Pi 3B. For those of you who also want to be able to brag that you got your Pi to boot into an operating system you wrote in Rust, I do highly recommend starting the series at Tutorial 0 and working your way through each in turn. However, if you just want to follow along with this blog post, we will be flashing the code from Tutorial 5.
In this post, we will examine the process of flashing a compiled kernel binary, kernel8.img, onto a microSD card, and then using a FT232H to communicate with a Raspberry Pi 3B. Both the specific RPi model and the USB-TTL serial converter were chosen because they what was available, but the process outlined in this post should be adaptable for any RPi 3/4 and UART-capable programmer.
Specifically, this tutorial requires the following equipment:
- Raspberry Pi 3 B. This is the device that executes the operating system. The Github tutorial today includes board-specific code for the RPi models 3 and 4, but the project uses a modular design that makes it easy to support new hardware models.
- FT232H. This is a USB-to-TTL serial convertor used to help my workstation speak UART to the RPi.
- 3x female-female Dupont connector cable.
- 2x Micro-B USB to Standard-A USB cables. Micro-USB cables, as Skeet might say.
- MicroSD card and any necessary programmer. I used a 16 GB card and the microSD-SD converter that came with it. The latter is actually only necessary for Tutorial 5, as Tutorial 6 implements a UART chainloader that allows updating the firmware without needing to remove the microSD card from the RPi.
As is always the case with these infernal machines, this post reflects one successful method I found after hours of failures. In the end, I got my kernel working by first flashing it onto the microSD card with gparted on Kali Linux, then later, while on the W11 side of the dual boot, installing the necessary drivers to use PuTTY to talk to a FT232H talking to the Pi. However, because most people don’t have readily available access to more than one operating system, what follows are separate tutorials for completing the entire process in Windows and Linux. I don’t have access to a Mac because I have to pay for my own machines.
Windows
- Open a WSL terminal on your programming workstation (desktop/laptop) and navigate to the directory containing the image to be flashed.
- Using Tutorial 5:
- git clone https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials
- cd 05_drivers_gpio_uart
- make
- The compiled firmware binary is now available at ‘kernel8.img’.
- Using Tutorial 5:
- Insert your microSD card into the workstation.
- Using a tool like Rufus, format the drive as FAT32. ENSURE THAT THE CORRECT DRIVE IS SELECTED BEFORE CLICKING START, and that the Volume Label is set to “boot”.
- Copy the following files from the Raspberry Pi firmware repo onto the SD card:
- Copy the file “kernel8.img” generated during step 1, to the SD card.
- Eject the microSD card safely from your workstation and insert into the RPi. No need to power it up right now, we’d just have to reboot it in a minute.
- Follow this FT232H tutorial from Adafruit in order to install the proper Windows drivers for the FT232H and connect to the device over PuTTY.
- Note: when I shorted TX to RX on my chip and connected via serial, sending a message just had the effect of moving my cursor to the front of the message on the screen. It seems that PuTTY is using \r line endings with no associated \n. Or this is just a weird quirk of my system that may or may not have something to do with why the text later won’t be properly aligned on the screen. Either way, don’t get discouraged if your test at this step doesn’t print your input back to you on a new line.
- Boot/reboot your RPi.
- If all goes well, PuTTY should now be serving you an actual system console over UART, and you should experiencing a nice fat dopamine hit :).
Linux
- Open a bash terminal and navigate to the directory containing the image to be flashed.
- Using Tutorial 5:
- git clone https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials
- cd 05_drivers_gpio_uart
- make
- The compiled firmware binary is now available at ‘kernel8.img’.
- Using Tutorial 5:
- Insert your microSD card into your workstation.
- Using gparted, format your drive as FAT32. TODO add more details when my microSD slot stops acting up in Linux
- Copy the following files from the Raspberry Pi firmware repo onto the SD card:
- Copy the file “kernel8.img” generated during step 1, to the SD card.
- Eject the microSD card safely from your workstation and insert into the RPi. No need to power it up right now, we’d just have to reboot it in a minute.
- Follow this Linux FT232H tutorial from Adafruit through the creation of the file /etc/udev/rules.d/11-ftdi.rules. Otherwise, your FT232H will randomly drop traffic.
- Run the following:
- ls /dev/tty*
- Plug your FT232H into your workstation and repeat step 8. Compare the output of the two commands to determine the name of your device. On my machine, the device is /dev/ttyUSB0.
- Open a serial connection to the device with baud rate 921600:
- sudo screen ${DEVICE_NAME_FROM_STEP_8} 921600
- Boot/reboot the RPi.
- If all goes well, screen should now be serving you an actual system console over UART, and you should experiencing a nice fat dopamine hit :).
- Use CTRL-A, CTRL-D to leave screen
This is obviously just the beginning. There’s an entire kernel to write in Rust – virtualization, concurrency, and persistence to implement – not to mention all those SBC hardware peripherals to write device drivers for. And that’s just the stuff CS undergrads have to do in Operating Systems their junior year – what about network protocols? What about modern security mechanisms (slash where does Rust make these redundant)? This can be a project for your entire life if you want it to be – it can be a lot more than that.
The _start label in src/_arch/aarch64/cpu/boot.s serves as entry point for the compiled binary. This file consists of ARM assembly whose purpose is to initialize the runtime and then pass off execution to an unsafe Rust context at _start_rust in src/_arch/aarch64/cpu/boot.rs. This aarch64-specific code then passes off execution to unsafe crate::kernel_init(), which then in turn enters a safe Rust context through crate::kernel_main(). This is how the kernel manages to bootstrap itself from a raw ARM execution context to one with the full safety and security guarantees provided by the Rust ownership system.
But that’s all I have to say about that. Go do the tutorials, they’re excellent! And if anyone sees Andre Richter, please pass along my thanks and offer him a beer – I’ll be sure to pay you back.
Leave a Reply