Crate rpi_hal 

Hardware abstraction layer for bare-metal Raspberry Pi.

Built around the BCM2836/BCM2837 (Pi 2, Pi 3), with preliminary support for the BCM2711 (Pi 4), the BCM2835 (Pi 1, Pi Zero) and the BCM2712 (Pi 5) — see the crate’s README for what is verified on each. Exactly one of the bcm2837/bcm2711/bcm2835/bcm2712 features selects the chip; none is a default, since there is no sensible default target chip.

Re-exports

pub use bcm2837_lpa as pac;bcm2837 and non-bcm2711 and non-bcm2712

Modules

aux_spiNon-bcm2712

Blocking driver for the auxiliary SPI controllers SPI1 and SPI2. Blocking driver for the auxiliary SPI controllers SPI1 and SPI2 — two of the three sub-peripherals behind the AUX block (alongside the mini UART, crate::mini_uart).

bluetoothNon-bcm2712

HCI bring-up for the on-board BCM43438 Bluetooth controller (Pi 3): H4 transport, .hcd patchram firmware load, and local version/address readback. HCI bring-up for the on-board BCM43438 Bluetooth controller (Pi 3).

cpu

Identity of the core executing this code — see the module’s own doc comment for why this is not part of multicore. Identity of the core executing this code.

dmaNon-bcm2712

Blocking driver for the DMA controller. Blocking driver for the BCM2835/2836/2837 DMA controller.

fpu

Enabling the hardware floating-point / SIMD unit (VFP + NEON). Enables the CPU’s hardware floating-point / SIMD unit (VFP + NEON).

generic_timerNeither armv6 nor bcm2712

Per-core ARM generic (architected) timer: monotonic counter, blocking delays, and interrupt-driven deadlines.

gpioNon-bcm2712

Typestated GPIO pin wrapper with embedded-hal digital trait implementations. GPIO pin wrapper with compile-time input/output mode enforcement (typestate) and embedded-hal digital trait implementations.

hid_reportNon-bcm2712

Transport-independent HID report descriptor parser, shared by the USB and Bluetooth HID hosts — see hid_report::ReportDescriptor. A HID Report Descriptor parser — turns the self-describing descriptor bytes (from sdp on Classic, a Report Map characteristic on LE, or a USB GET_DESCRIPTOR(REPORT)) into a flat Field map, so reports can be decoded without a hand-written per-device layout.

i2cNon-bcm2712

Blocking driver for I2C1 (BSC1). Blocking driver for the BCM2835 BSC I2C controllers.

irqrt

CPU-level IRQ enable/disable and the exception vector table.

licNeither bcm2711 nor bcm2712

Safe wrapper around the BCM2836/2837 legacy interrupt controller.

mailbox

Blocking driver for the VideoCore mailbox property interface. Blocking driver for the VideoCore mailbox property interface — the RPC channel to the GPU firmware for anything the ARM core can’t learn or do on its own: real clock rates, board identification, the ARM/VideoCore memory split, and (see allocate_framebuffer) a display framebuffer. Display output itself (HDMI or the MIPI DSI touchscreen) is entirely mediated by the VideoCore the same way: there’s no ARM-side HDMI or DSI PHY to program directly, only this mailbox request for a buffer to write pixels into. Which physical output that buffer appears on is chosen with set_display_num, out of the displays the firmware enumerated. How many there are to choose between is still firmware/config.txt configuration — a board whose max_framebuffers leaves room for one display offers a choice of one, whatever is plugged into it — but which of them the framebuffer lands on is this driver’s to decide.

memrt and non-bcm2712

Where the loaded image ends and free RAM begins — see mem::heap_region, which is how a program sizes a heap without hardcoding a board’s memory split.

mini_uartNon-bcm2712

Blocking driver for the mini UART (UART1). Blocking driver for the mini UART (UART1), one of the three sub-peripherals behind the AUX block (alongside SPI1/SPI2 — see crate::aux_spi).

mmummu

Identity-mapped MMU bring-up, plus the one thing a driver may need to change about the map afterwards: taking a region of RAM out of the caches (mmu::set_uncached), for memory a bus master writes concurrently with this core. MMU bring-up: enables address translation so RAM can be marked Normal memory, needed for core::sync::atomic’s exclusive-access instructions (ldrex/strex on AArch32, ldxr/stxr on AArch64) to behave correctly – those are architecturally UNPREDICTABLE on the Strongly-Ordered/Device memory every address is with the MMU off. Every peripheral MMIO region keeps behaving exactly as it does today (Device memory, same ordering guarantees raw register access already relies on everywhere else in this crate).

multicoremulticore and rt and non-armv6

Bringing up secondary cores (1-3) — see the module’s own doc comment for the wake-up handoff this builds on.

ov5647Non-bcm2712

Reference I2C driver for the OV5647 (Raspberry Pi Camera v1) image sensor — a third-party device (paired with unicam), not a SoC peripheral. Reference driver for the OmniVision OV5647 (Raspberry Pi Camera v1) image sensor, over I2C.

pcmNon-bcm2712

Blocking bring-up for the PCM / I2S peripheral (digital audio out to an external I2S DAC). Blocking bring-up for the BCM PCM / I2S peripheral, driving digital audio out to an external I2S DAC (e.g. a PCM5102 / UDA1334) in standard Philips-I2S master mode, DMA-fed.

pmuNon-armv6

The PMU cycle counter — a cheap per-core CPU-cycle clock for profiling work too short for the System Timer to measure without disturbing it.

powerNon-bcm2712

Board reboot and shutdown via the Power Management (PM) block. Board reboot and shutdown via the BCM Power Management (PM) block.

pwmNon-bcm2712

Blocking driver for the PWM controller. Blocking driver for the BCM System PWM controller — two independent duty-cycle channels sharing one clock. Named RNG1/DAT1/CTL’s *1 bits and RNG2/DAT2/CTL’s *2 bits in the PAC (matching this module’s Channel1/ Channel2); the BCM2835 ARM Peripherals datasheet calls the same two channels “PWM0”/“PWM1” (0-indexed) instead — same hardware, different numbering.

rngNon-bcm2712

Blocking driver for the hardware random number generator. Blocking driver for the hardware random number generator.

sd

Blocking driver for the on-board SD card slot (Arasan EMMC host controller, or the SDHCI that replaced it on the Pi 4 and Pi 5). Blocking driver for the on-board SD card slot, via the Arasan “EMMC” SD host controller (the BCM2835 ARM Peripherals datasheet’s “External Mass Media Controller” — an SDHCI-compatible host).

sdhostNeither bcm2711 nor bcm2712

Blocking driver for the SD card slot over the other host controller, SDHOST — the one that leaves the Arasan controller free for sdio, so a board can drive its card and its wireless chip at the same time.

sdioNon-bcm2712

Blocking SDIO driver for the on-board BCM43438 wireless chip (Wi-Fi side), via the same Arasan EMMC host controller. Blocking driver for the on-board wireless chip’s SDIO interface — the bus the Wi-Fi side of the chip is reached over.

spiNon-bcm2712

Blocking driver for SPI0. Blocking driver for SPI0.

stackrt

Extent of the main stack and how much of it is left — see stack::headroom.

timer

BCM System Timer driver: free-running microsecond counter and delays.

touchNon-bcm2712

Driver for the DSI touchscreen’s touch input (the firmware-mediated shared touch buffer, not I2C). Driver for the DSI touchscreen’s touch input, read from a shared touch buffer the VideoCore firmware keeps updated, rather than over I2C.

uart

Blocking driver for UART0 (PL011) — on the Pi 5, RP1’s UART0, on the same GPIO14/15 header pins.

unicamNon-bcm2712

Blocking driver for the Unicam CSI-2 camera receiver. Blocking driver for the Unicam CSI-2 receiver (camera capture).

usbNon-bcm2712

USB host support for the built-in DWC2 OTG controller. USB host support for the BCM2836/2837’s built-in DWC2 OTG controller, built up in stages rather than attempted as one unit: host controller bring-up first, enumeration and a HID class driver next (the smallest real thing that validates the controller actually works end to end), Ethernet only once those are solid (its own class driver plus a full TCP/IP stack on top, far more surface area than HID). So far there’s controller/root-port bring-up (dwc2::Dwc2Host); the standard control transfers that enumerate a device (reading its device and configuration descriptors, SET_ADDRESS, SET_CONFIGURATION); and the hub-class requests that drive the on-board hub’s downstream ports (hub descriptor, set_port_power, get_port_status, set_port_reset). A device behind the hub can be reset and its descriptor read through it — at high speed directly, or at full/low speed via split transactions through the hub’s transaction translator (see dwc2::SplitTarget) — and interrupt-IN endpoints can be polled (dwc2::Channel::interrupt_in), directly (the hub’s own status-change endpoint) or through the hub at full/low speed via periodic split scheduling (the report endpoint of a HID keyboard on a physical port). enumerate ties the whole bring-up together — root-port reset, root-hub configuration, and per-port reset/probe/address, applied again to any port that turns out to have a hub on it, so a device several hubs deep is found and pointed at the right transaction translator for where it sits — and hands each device to a callback (see the usb_enum/usb_hid_keyboard examples). The bus type is the same walk with its state kept afterwards, so a later sweep can bring up a device that attaches after the walk and report one that goes away — which a single pass cannot, and which matters on boards where a soldered-on device takes longer to announce itself than the walk takes to run. On top of that sit the class drivers — HID (hid), turning a device’s report endpoint into input events: a boot-protocol keyboard and mouse, and a gamepad decoded through its own HID report descriptor (hid::gamepad) — and the beginnings of the on-board LAN9514 USB-Ethernet controller (lan9514), so far reaching its registers over vendor control transfers. Still missing: bulk transfers (which Ethernet frame RX/TX needs), and the rest of the LAN9514 driver and a network stack on top. Each is real, separate work still to come, layered on top of dwc2/control.

v3dv3d

Bring-up for the V3D 3D pipeline (VideoCore IV’s QPU shader cores). Pi 3 (BCM2836/BCM2837) only. Bring-up for the V3D 3D pipeline: VideoCore IV’s QPU shader cores and the tile-based binning/render hardware around them.

watchdogNon-bcm2712

Blocking driver for the PM block’s watchdog timer. Blocking driver for the BCM Power Management (PM) block’s watchdog timer: arms a hardware countdown that triggers a full board reset (equivalent to a power cycle) if it’s not re-armed before it expires, for automatic recovery from a hang that leaves nothing running to notice or act on it.

wifiNon-bcm2712

Host control protocol (SDPCM/CDC) for the on-board BCM43430 Wi-Fi chip, on top of sdio. Host-side control protocol for the on-board wireless chip, on top of the crate::sdio link once its firmware is running.

Functions

halt

Halts the calling core forever, parking it in a low-power wait-for-event loop.