rpi-hal | Blog

Introducing rpi-hal

Fri, 16 Oct 2026 00:00:00 GMT

rpi-hal is a hardware abstraction layer for running Rust directly on a Raspberry Pi: no Linux, no operating system of any kind, just your program, the hardware, and a crate that knows how to talk to it. It currently covers the Pi 1 and Pi Zero, the Pi 2, the Pi 3 and, in a preliminary way, the Pi 4, in both 32-bit and 64-bit builds where the chip has both. The Pi Zero 2 W and the Pi 5 are on the list for later; the supported devices page tracks where each board stands.

If you have written firmware for an STM32 or an RP2040 in Rust, it is meant to feel familiar. If you haven’t, it is meant to be a reasonable place to start.

What it is

The Rust embedded ecosystem has settled on a shape for a HAL. A peripheral access crate (PAC) describes the registers; the HAL wraps them in types that own the hardware they drive; and the HAL implements the embedded-hal traits, so that a driver written against OutputPin or I2c works on any chip that provides them. stm32xx-hal and rp2040-hal look this way, and so does rpi-hal, on purpose: the same naming, the same typestate pattern (a pin’s mode is part of its type, so writing to an input doesn’t compile), and the embedded-hal traits implemented beside the crate’s own methods rather than instead of them.

Here is a complete program that blinks an LED on GPIO4:

#![no_std]
#![no_main]

use embedded_hal::digital::OutputPin;
use rpi_hal::gpio::{Input, Pin};
use rpi_hal::pac;
use rpi_hal::timer::Timer;

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    rpi_hal::halt();
}

#[no_mangle]
pub extern "C" fn kmain() -> ! {
    let peripherals = unsafe { pac::Peripherals::steal() };

    let mut led = Pin::<4, Input>::new(peripherals.GPIO).into_output();
    let timer = Timer::new(peripherals.SYSTMR);

    loop {
        let _ = led.set_high();
        timer.delay_ms(500);
        let _ = led.set_low();
        timer.delay_ms(500);
    }
}

Apart from kmain where you might expect main, nothing in it is particular to a Pi. That is the goal: a basic application written against embedded-hal for another chip should port with only the setup lines changed.

What sits underneath is more than an MCU HAL usually carries, because a Pi is not a microcontroller. rpi-hal brings up the MMU and the caches, installs the exception vectors and routes interrupts, and wakes the other three cores if you ask it to. Then come the peripherals: GPIO, the UARTs, SPI, I2C, PWM, PCM/I2S, DMA, the SD card, USB host, the VideoCore mailbox and more. The README keeps the status of every one of them.

Why bare metal on a Pi at all

A Pi is usually a small Linux computer, and for most things that is exactly what you want. But it is also a very capable piece of hardware: four cores, hundreds of megabytes to a few gigabytes of RAM, HDMI, USB host, Ethernet, and on some boards Wi-Fi and Bluetooth. Running without an operating system changes what that hardware is like to use:

The machine is entirely yours. No scheduler preempts you, no kernel decides when your interrupt is serviced, no background service takes a core. Timing is whatever your code makes it.
So is the memory. No kernel reserves a slice of it, and there is no process address space to fit inside: your program can use all of the RAM the board has, apart from the share you give the GPU in config.txt.
The SD card barely matters. It doesn’t carry a Linux distribution, only the Pi’s boot firmware and your image, a few megabytes in all, so the smallest card you can find is plenty. And nothing writes to it unless your program decides to: no logs, no swap, no package cache wearing it out in the background. A card that is written only when you say so lasts far longer than one under an operating system.
It starts when the power does. There’s no distribution to boot, no filesystem to check, nothing to shut down cleanly. Pull the plug whenever you like: unless your program is in the middle of writing to the card, there is nothing on it to corrupt.
You see everything. There is no driver between you and a register, which is as much a way to learn how the hardware actually works as it is a way to control it.

The price is that there is no driver between you and a register. Linux gives you a working USB stack, a network stack and a filesystem for free; on bare metal someone has to write them. Doing that work once, in crates other people can build on, is what this project is for.

One thing bare metal does not get rid of is the Pi’s own boot firmware. On every Pi the GPU starts first, reads bootcode.bin, start.elf and config.txt from the SD card, and only then loads your image and releases the ARM cores. rpi-hal takes over from that point.

The family

rpi-hal is the foundation. Three more crates live beside it in the same repository:

rpi-hal-embassy brings Embassy to the Pi: a time driver on the System Timer, an executor that sleeps with wfe and wakes on sev, and embassy-net drivers for the onboard Ethernet. Async Rust, with tasks instead of a main loop.
rpi-kickstart is the bring-up every application ends up writing anyway: a console with logln!, a heap, a config file on the SD card, storage, networking with DHCP and SNTP, a small web server, Prometheus metrics, and over-the-air updates. Each is a cargo feature, so you take only what you use.
rpi-loader makes development bearable. Without it, every change means pulling the SD card, copying a file and putting it back. With it, you copy one loader image to the card once, and from then on rpi-loader uploads your build over a USB-serial cable and starts it, in seconds. It can also read and write the card in place, so the card can stay in the board.

All four are on crates.io, are dual-licensed MIT or Apache-2.0, and follow their own version numbers.

How to start

The quickest way is the project selector: pick your board, and it hands you a zip with a project ready to build. That project has the right target and linker settings, a config.txt for the board, the matching loader image, and a main.rs that logs a heartbeat over the UART console. If you prefer the command line, the same template is available through cargo generate:

cargo install cargo-generate
cargo generate --git https://github.com/joeferner/rpi-hal template

Either way, make sd-card fetches the firmware files and the loader image for the card, and make run builds, uploads and boots your program. The getting started guide walks through the wiring and the first boot.

The code is at github.com/joeferner/rpi-hal. Issues and pull requests are welcome, and so are reports of which boards you’ve run it on.

rpi-loader: stop moving the SD card

Fri, 16 Oct 2026 00:00:00 GMT

Every bare-metal Raspberry Pi project starts with the same loop. Build. Power the board off. Pull the SD card, put it in the computer, copy kernel7.img over, eject it, put it back, power on, and watch the serial console to see whether it worked. Then do it all again for a one-line change.

It is slow, it wears out the card and the slot, and it is miserable once the board lives in an enclosure. A microcontroller has SWD or a USB bootloader for exactly this; a Pi has nothing of the kind. rpi-loader is that missing piece.

The idea

Put one small image on the card, once. From then on the Pi boots into a loader that sits on the UART waiting to be told what to do, and the card never has to move again.

It is a resident command agent rather than a one-shot bootloader: it answers one command, then waits for the next, for as long as the board is powered. Each run of the host tool is its own process and reconnects with a fresh handshake, so the order you start things in doesn’t matter. Power the Pi first or start the tool first; either way they find each other.

What it looks like

Find the cable:

rpi-loader list
# /dev/ttyUSB0  FTDI TTL232R-3V3  0403:6001  ...

Upload a build to RAM, jump to it, and stay attached as a terminal, so the program’s output appears where you typed the command:

rpi-loader --device /dev/ttyUSB0 boot --load-addr 0x8000 target/kernel7.img

That is the everyday loop, and it is what a project from the project selector runs as make run.

To leave the terminal, press Ctrl-], not Ctrl-C. Every other key, Ctrl-C included, goes to the board, which is what lets you interrupt something running there rather than the tool on your machine.

The loader can also reach the SD card in place, so editing config.txt doesn’t mean touching the card either:

rpi-loader --device /dev/ttyUSB0 sd-read /config.txt ./config.txt
# edit it, then put it back
rpi-loader --device /dev/ttyUSB0 sd-write ./config.txt /config.txt

There are a few more commands: listing, deleting and making directories on the card, a plain terminal for watching a kernel that is already running, and programming the ID EEPROM a HAT or a custom board carries. The README has the full list.

Getting it

The host tool is on crates.io:

cargo install rpi-loader

The loader images are on the release page, or already inside a project zip from the project selector, with the boot firmware and a config.txt beside them. Copy those to the card, connect a 3.3 V USB-serial cable to GPIO14 and GPIO15 (pins 8 and 10, ground on pin 6), and power on. The getting started guide walks through it.

After that the card stays in the board.

What goes on the card

The card needs one FAT32 partition and only a handful of files:

File	What it is
`bootcode.bin`	The first stage of the Pi’s boot firmware, which brings up SDRAM and loads `start.elf`. Not on a Pi 4, whose boot EEPROM does this job.
`start.elf` (`start4.elf` on a Pi 4)	The GPU firmware proper. It reads `config.txt`, sets up the hardware, loads the kernel image and releases the ARM cores.
`fixup.dat` (`fixup4.dat` on a Pi 4)	Tells `start.elf` how memory is split between the GPU and the ARM. Released as a pair with `start.elf`; mismatched, the board won’t boot.
`LICENCE.broadcom`	The licence the firmware files are distributed under.
`config.txt`	The firmware’s settings for your board: 32- or 64-bit, which kernel file to load, and anything else the board needs.
`kernel7.img`, `kernel8.img` or `kernel.img`	The loader, renamed to the one filename your board’s firmware loads. Which name depends on the CPU, and, on a Pi 3 or Pi 4, on `arm_64bit` in `config.txt`.

The first four come from Raspberry Pi’s firmware repository, and a project zip has all six with the right names already.

How it works

Getting out of the way

The Pi’s firmware loads every kernel at the same address: 0x8000 for a 32-bit image, 0x80000 for a 64-bit one. That includes the loader, which is a problem, because the kernel it is about to receive expects that address too, and nothing can overwrite the code it is running from.

So the loader’s first act, before anything else, is to copy itself to 0x00200000 and jump into the copy. It is linked to run from there, and its stack sits above it, which leaves the whole region from the load address up to the copy free for the incoming image.

The wire

The handshake runs at 115200 baud, which every USB-serial cable manages. For bulk transfers the two ends then agree on something faster (1.5 Mbaud by default) and drop back to 115200 afterwards, so the next command, or the program just booted, finds the link where it expects.

Data moves in chunks, each with its own CRC and each acknowledged before the next is sent. That is flow control, not caution: the Pi’s UART holds only 16 bytes in its receive FIFO, and a host that streamed freely would overrun it. A bad chunk is sent again, and the whole image is checked once more at the end.

Refusing to do damage

The loader checks every upload’s address against its own memory map, so a wrong --load-addr fails with an error instead of overwriting the loader in the middle of the transfer.

On the card, sd-write receives the whole file into RAM before writing any of it, so an interrupted upload leaves the old file as it was. And the loader keeps no state between commands: it mounts the card afresh for each one, so resetting the board between two commands loses nothing.

One image per execution state

A loader hands off in the execution state it is running in, so a 32-bit loader boots 32-bit kernels and a 64-bit loader boots 64-bit ones. With three chips, two of which can run either way, that makes five images:

Image	Boards
`bcm2837` `kernel7.img`	Pi 2, Pi 3, 32-bit
`bcm2837` `kernel8.img`	Pi 2 v1.2, Pi 3, 64-bit
`bcm2711` `kernel7.img`	Pi 4, 32-bit
`bcm2711` `kernel8.img`	Pi 4, 64-bit
`bcm2835` `kernel.img`	Pi 1, Pi Zero

The project selector picks the right one for the board you choose, and names it the way your board’s firmware expects.