← Back · part of NextBSD Research · companion to the arm64 KMS options and the driver-delivery plan

NextBSD on the Raspberry Pi 500+: native boot, and the driver map

The target is a Raspberry Pi 500+ — BCM2712 D0 silicon, 16 GB, built-in 256 GB NVMe, and a keyboard that sits behind PCIe. worproject/rpi5-uefi cannot boot it, and that is not bad luck: the repo has been archived since Feb 2025, its only releases target pre-D0 BCM2712C1, and board type 0x19 was never added. This page lays out every option for booting it natively — one of which, unexpectedly, needs zero new boot code — and maps every device on the board to a driver we can port today, port from Linux, or must write new.

2026-08-17. Written after a 4-agent research sweep (FreeBSD arm64 status; OpenBSD/NetBSD/DragonFly driver survey; the BCM2712 boot chain; Linux 6.12 port viability), plus a live hardware inventory taken over ssh from the board itself. Citations to freebsd/freebsd-src main, openbsd/src master, raspberrypi/linux rpi-6.12.y, u-boot/u-boot master, and the Raspberry Pi documentation and EEPROM release notes. Every load-bearing source claim below was re-verified directly against the tree rather than taken from an agent summary.

1. The hardware, as measured

Taken from the running board (Debian 13, kernel 6.12.47+rpt-rpi-2712) rather than from a spec sheet, because the board and its firmware disagree about what it is.

The topology that decides everything

Both of the things you need to use this machine — the keyboard and the disk — are behind PCIe:

BCM2712
 ├─ pcie1  0001:00:00.0 [brcm,bcm2712-pcie]  MSI: mip1
 │   └─ 0001:01:00.0  NVMe 1d97:5216  FORESEE XP1000F256G, 238.5 G   ← built-in 500+ SSD
 └─ pcie2  0002:00:00.0 [brcm,bcm2712-pcie]  MSI: mip0, Gen2 x4
     └─ 0002:01:00.0  RP1 southbridge 1de4:0001
         ├─ 1f00100000  ethernet [raspberrypi,rp1-gem, cdns,macb]   ← Cadence GEM
         ├─ 1f00200000  usb [snps,dwc3] → xhci-hcd.0
         └─ 1f00300000  usb [snps,dwc3] → xhci-hcd.1
             └─ 3-2  2e8a:0011  "Raspberry Pi Ltd Pi 500+ Keyboard (ANSI)"  usbhid

That product string is read from the device's own USB descriptor, so it is the real 500+ keyboard. Nothing types on this machine until PCIe, RP1, dwc3, xHCI and USB-HID all work — five layers. A serial cable is not a convenience here, it is the only input channel for the entire bring-up.

2. Why the UEFI route is closed

Three independent reasons, all verified, in order of severity.

16 GB is not the problem, contrary to the obvious guess. 256MB << 6 is decoded correctly and mapped above 4 GB. (The 3 GB cap people remember is pftf/RPi4, a real BCM2711 DMA erratum. BCM2712 has no such limit.) The failures are D0 display and DTB failures.

And there will never be a pftf/RPi5. Pete Batard, pftf/RPi4#243: “we have moved on to other endeavours and have currently no scope (or interest) to invest our time to do the same for the Pi 5.” Mario Bălănică, rpi5-uefi's own author, in the same thread: “most of us have simply moved on… I upstreamed my TF-A port for the RPi 5 over a year ago… they still haven't contributed any of those changes back.”

Note which half survived: the TF-A port was upstreamed (PLAT=rpi5 is in mainline TF-A) and lives on inside the EEPROM. The EDK2 platform half was never upstreamed, and died. That is the argument for putting our effort where upstream will carry it.

3. The boot chain, and the four routes

What the Pi 5 firmware actually does

The Pi 5 family firmware is entirely self-contained in the SPI EEPROM. There is no bootcode.bin, no start*.elf, no fixup*.dat — the docs are explicit: “The Raspberry Pi 5 does not use elf files… the bootloader has an embedded version of start.elf.”

1. boot ROM → SPI EEPROM 2nd stage
2. VPU bootloader:
     • loads RP1 firmware (~46 KB) into RP1 SRAM over I2C   ← concurrent with DDR init
       (RP1 missing = FATAL: 4 long / 3 short blinks)
     • releases RP1_RUN → RP1's Cortex-M3 boots → its PCIe endpoint comes alive
     • init clocks + LPDDR4X, walk BOOT_ORDER, train the x4 link, enumerate 1de4:0001
3. loads armstub (TF-A BL31) at 0x0, kernel at 0x200000, DTB, initramfs
4. unless pciex4_reset=0: resets the x4 controller before handoff
5. EL3 TF-A BL31 → eret → EL2 non-secure: kernel entry, x0 = physical DTB pointer

Two things follow that are worth stating plainly, because they invert the usual assumption that the Pi is a hostile boot target:

• RP1 is brought up by the firmware, not by us. Its firmware is embedded in the EEPROM — there is nothing to ship or load. An OS driver's whole job is: enumerate PCIe, map BAR1, allocate 61 MSI-X vectors, program MSIX_CFG_n, populate the DT subtree. Linux's rp1_pci.c probe is a few dozen lines, and it detects a firmware-less RP1 by checking whether BAR1 has grown from 64 KB to 4 MB.
• The BCM2712 is a more conventional arm64 target than the BCM2711. The Pi 4 chain needed FreeBSD's own hand-rolled EL3 armstub to fake up a GIC and PSCI. That is gone, replaced by real TF-A BL31, a real GICv2, competent DTB fixups, and a documented kernel= contract. FreeBSD's problem on this board was never the boot protocol.

The four routes, costed

Presented so they can be compared, not ranked. (a) and (c) are not mutually exclusive — they share every driver below the boot layer, and (a) doubles as the debugging harness for (c).

# config.txt
kernel=kernel8.img
device_tree=bcm2712-rpi-500.dtb
enable_rp1_uart=1      # firmware inits RP1 UART0 @115200 and does not reset RP1
pciex4_reset=0         # required companion to the above
enable_uart=1
dtparam=uart0_console  # 2712-only: console to UART0 on 40-pin pins 6, 8, 10
dtparam=nvme

# cmdline.txt
FreeBSD: vfs.root.mountfrom=ufs:/dev/... -v

Serial console — the part to get right first

There are two entirely different UARTs, and only one of them works before PCIe:

On a 500+ the 3-pin debug connector may not be physically exposed — the signals exist (bcm2712-rpi-500.dts still names AON_GPIO_13 = "UART_TX_FS") but it is inside a keyboard enclosure and no teardown confirms a populated header. The 40-pin header is the path that definitely works: pin 6 GND, pin 8 TXD, pin 10 RXD, 3.3 V, 115200 8N1, with enable_rp1_uart=1 + pciex4_reset=0 so the firmware initialises it and declines to reset RP1. For EARLY_PRINTF, hard-code the PL011 at 0x1F_0003_0000 — the firmware has already set the baud rate, so only the FIFO needs poking.

Physically connecting a console from a Mac

A USB-to-TTL serial adapter is required: a USB device to the Mac on one side, 3.3 V UART pins on the other.

What to buy

The Raspberry Pi Debug Probe ($12, in production until at least Jan 2030) is the right tool here for a reason specific to this board: it ships with cables for both UART paths — a 3-pin JST-SH → JST-SH lead that mates directly with the Pi 5-family debug connector, and JST-SH → 0.1″ female and male header leads for the 40-pin GPIO header. One purchase covers whichever connector turns out to be reachable.

It is also CDC-ACM class-compliant, so macOS needs no driver at all — it enumerates as /dev/cu.usbmodem*. That matters more than it sounds: generic CP2102 / CH340 dongles may want a vendor kext depending on the macOS version, which is friction you do not want in the middle of a bring-up. FTDI FT232R parts are the next-best option (macOS has carried an in-box FTDI driver for years).

Stocked by Raspberry Pi's own reseller list, and directly by Pimoroni, SparkFun, Micro Center, CanaKit and Vilros. Prices and stock as of 2026-08-17 — check before ordering.

Wiring to the 40-pin header

Probe lead colours are orange = TX (out of probe), yellow = RX (into probe), black = GND. Serial is crossed, so:

Probe orange (TX) ──▶ Pi pin 10   GPIO15 / RXD
Probe yellow (RX) ◀── Pi pin 8    GPIO14 / TXD
Probe black (GND) ─── Pi pin 6    GND

On the Mac

ls /dev/cu.usb*                          # find it
brew install tio
tio /dev/cu.usbmodem1101 -b 115200

Use /dev/cu.*, not /dev/tty.*. On macOS the tty. node blocks on carrier-detect and will simply hang; cu. (call-up) does not. And prefer tio over screen for one reason that matters enormously here: it reconnects automatically when the device disappears. Driver bring-up means power-cycling the board constantly, and screen dies on every reboot.

Which connector to aim for

The 40-pin header is the path that certainly works, and is the right choice for phases 0–2. But note what it costs from phase 3 onward: the console would live on the very hardware being brought up. The first time a half-written bcm2712-pcie or rpone driver resets the link, output stops — and a lost console is indistinguishable from a hang. That is a concrete reason to open the case early and look for the 3-pin JST-SH connector, before the PCIe work starts rather than during it.

4. The driver map

Why not LinuxKPI for this tier

Worth settling explicitly, because the drm-kmod success makes it the natural assumption. LinuxKPI cannot host a devicetree/platform driver at all:

/* sys/compat/linuxkpi/common/include/linux/platform_device.h */
platform_driver_register(...)  →  pr_debug("TODO"); return (-ENXIO);
to_platform_device(dev)        →  (NULL)
dev_is_platform(dev)           →  (false)

linux/of.h is a 1,486-byte stub whose entire body is #include <linux/kobject.h>. linux/clk.h, linux/reset.h, linux/pinctrl/, linux/gpio/ and linux/dmaengine.h do not exist. regmap.h, component.h, of_address.h and property.h exist only as 0-byte files in linuxkpi/dummy/include/. There is no linux_of.c, linux_platform.c or linux_clk.c, and no evidence anyone has attempted one. Building that layer is a multi-year subsystem project, not a shim.

FreeBSD's own equivalent is healthy and is where this belongs: sys/dev/clk/, sys/dev/regulator/, sys/dev/hwreset/, sys/dev/phy/, sys/dev/syscon/, sys/dev/ofw/, sys/dev/fdt/fdt_pinctrl.c.

The RP1 shape, and why FreeBSD can express it

RP1 is a PCIe endpoint that exposes an entire simple-bus of peripherals behind a BAR. OpenBSD solves it in four layers, and the trick is worth copying verbatim:

1. bcmpcie matches brcm,bcm2712-pcie and simultaneously inherits simplebus_softc, so the PCIe node doubles as an FDT bus for RP1's subnodes.
2. bcmmip remaps MSI to GIC SPIs.
3. rpone attaches at pci? on 1de4:0001, maps the MSI-X and peripheral BARs, builds a synthetic bus_space that rebases RP1 MMIO, and registers an FDT interrupt controller demuxing 61 MSI-X vectors — in 219 lines.
4. RP1's children then attach as ordinary FDT devices.

FreeBSD has every primitive, already exported as public API in sys/dev/fdt/simplebus.h: simplebus_init(), simplebus_add_device(), simplebus_attach_impl(), and DECLARE_CLASS(simplebus_driver) for inheritance. simple_mfd.c is the in-tree precedent. This was the blocker that stalled earlier FreeBSD attempts — mkarels reported “the rp1 node doesn't get probed and attached” — and it is not actually a missing primitive, just a missing driver.

Tier A — boot, console, storage, input

Tier B — useful, deferrable

Tier C — graphics and media

The licence argument, stated once

NextBSD has so far vendored only GPL-2.0-or-later. That rule alone excludes a large share of the Linux candidates: irq-bcm2712-mip, sdhci-brcmstb, macb_main, irq-brcmstb-l2, gpio-brcmstb, i2c-brcmstb, iproc-rng200 and most of vc4 are all GPL-2.0-only. The OpenBSD route sidesteps the question entirely — all 4,113 LOC are ISC, which is strictly more permissive than anything in the Linux tree and imposes nothing on kext packaging. RTEMS learned this the expensive way: they got PCIe link training working by studying Circle (GPLv3) and Linux, then had to discard it — “we cannot accept GPL code into rtems.”

5. Delivering it as kexts

The driver-delivery plan settled a three-tier split for amd64. Mapping it onto this board gives the shape below — if arm64 follows the same model, which is decision 3:

6. Graphics: VideoCore, vc4, and v3d

The naming is confusing: BCM2712 has VideoCore VII, the DT compatible says vc6, and the Linux driver is still called vc4 (from VideoCore IV, where it began). All three name the same lineage. On this board it resolves to two independent drivers:

vc4 gives a picture; v3d gives acceleration. Since this board has no simple-framebuffer node and no UEFI GOP, there is no display path at all without vc4 — which is why serial is mandatory and why graphics cannot be an early shortcut.

No BSD anywhere has either driver; tree-wide searches of all four found zero. The only prior art is NetBSD's GSoC 2022 vc4 attempt (loaded on a real RPi 3B+, then crashed startx in drm_gem_object_put_unlocked, never merged) and a FreeBSD compile-only skeleton whose last commit reads “now comes the hard part of actually getting it to work on hardware.”

What already exists on our side

nextbsd-kernel-modules#33 has already measured the foundation: drm.ko, ttm.ko, dmabuf.ko, radeonkms.ko and drm_extra_helpers.ko build and fully symbol-resolve on aarch64 against the NextBSD kernel. That settles the question the ports tree appears to answer negatively — graphics/drm-612-kmod is ONLY_FOR_ARCHS = amd64, but we build from source, and the upstream tree's SUPPORTED_ARCH does list aarch64. The port's gate is conservative, not load-bearing.

That PR also found a real upstream bug: kconfig.mk gates DRM_AMD_DC_FP to amd64 while the references stay compiled unconditionally, so amdgpu.ko builds clean on aarch64 and dies at kldload with five unresolved dal_hw_* / dscl*_spl_calc_lb_num_partitions symbols. Worth reporting upstream.

What is still missing

1. Six DRM helpers, ~2,930 LOC, absent from drm-kmod 6.12-lts: drm_gem_shmem_helper.c (782, v3d's GEM backend), drm_gem_dma_helper.c (604, vc4's), drm_of.c (546), drm_simple_kms_helper.c (457), drm_fbdev_dma.c (346), drm_fb_dma_helper.c (195). graphics/drm_extra_helpers/ is already the designated home for exactly this.
2. The non-PCI guard. vc4 and v3d are FDT platform devices; every driver drm.ko has hosted so far is PCI. bsd-sbc-drm's drm-kmod branch sbc-nopci is a one-commit guard on to_pci_dev() in drm_sysctl_freebsd.c. Its sibling drm-subtree (Jesper Schmitz Mouridsen, jsm@, pushed 2026-08-10) runs native FreeBSD arm64 KMS for Rockchip/Allwinner/komeda plus Panfrost on stock drm.ko — a working existence proof of the exact shape needed.
3. Mesa. graphics/mesa-dri ships no vc4, no v3d, no broadcom. A loading v3d.kext renders nothing without a separate ports task. panfrost is enabled on aarch64, so arm64 SoC Gallium is shippable — just not Broadcom's yet.

The two orders, and the vc4 walls

v3d first minimises engineering risk — a quarter the size, inside the licence rule, already 2712-capable at 6.12, no component framework, no ASoC, no CEC, and its own MMU so no dependency on the BCM2712 IOMMU. It proves the FDT-driver-on-drm.ko plumbing cheaply. It also delivers nothing visible, and needs Mesa before it delivers anything at all.

vc4 first is the only path to a screen on this board, and pays the full cost up front. Three walls:

• ASoC. vc4_hdmi.c includes sound/soc.h, sound/hdmi-codec.h, sound/jack.h, sound/dmaengine_pcm.h. FreeBSD has no ALSA/ASoC at all and it is a hard Kconfig depends on. ~450 lines must be surgically removed; no HDMI audio in v1.
• The component framework. vc4 is a component_master_add_with_match() over eight OF sub-devices with a binding-order constraint. linux/component.h is 0 bytes. Implement over newbus, or flatten as the NetBSD port did.
• Our 6.12 base is the worst available vc4 baseline. Measured deltas against rpi-6.12.y: v6.12 → 5,866 changed lines; v6.18 → 2,619. Take vc4 from v6.18, which also brings GEN_6_C/GEN_6_D — and this board is D0.

Two easy scope cuts: dropping the eight MIT-licensed VC4-2.x 3D-submission files removes ~4,700 LOC and the licence wrinkle (2712's 3D is V3D 7.1, so they are dead code), and skipping downstream-only vc4_firmware_kms.c (2,079). Realistic KMS-only target: ~14.5k LOC vendored + 3–5k of new shim, HDMI only.

7. Dependency order

What unblocks what. This is a dependency graph, not a schedule — phases 0–2 are common to every route, and where the paths diverge is called out in §9.

Phase 3 has an upstream dependency worth engaging rather than forking around: D58105, Michal Meloun's bus-view DMA implementation, created 2026-07-08 and still being revised. BCM2712's pcie2 has a non-identity dma-ranges — a 64 GiB aperture mapping PCIe 0x10_0000_0000 → CPU 0x0 — and FreeBSD has zero dma-ranges parsing anywhere. The Pi 4 driver dodges it by hardcoding its window, which does not generalise. mmel's own comment: “this minimal implementation targets RPi5 support for now.” Every PCIe driver is gated on it.

8. Open questions and risks

Ruled out by hard constraints, not preference

These are the only items the evidence closes off by itself. Each is reversible if the constraint changes.

• A LinuxKPI clk/pinctrl/regulator/OF shim. Multi-year, and FreeBSD's native extres subsystems already do the job. Constraint: platform_driver_register() returns -ENXIO.
• pispbe and rpi-hevc-dec. 4,745 + 2,335 LOC sitting on 30–40k LOC of absent V4L2/videobuf2/Media-Controller infrastructure with no other consumer. Constraint: FreeBSD has no V4L2 in kernel. Software HEVC on four A76 cores is the fallback.
• Replacing TF-A BL31. Constraint: it is what provides PSCI and secondary-core startup; replacing it costs both for no gain.
• Circle and raspberrypi/linux as copied sources. GPLv3 and GPLv2 respectively. Circle is the most complete bare-metal BCM2712 source in existence and we cannot take code from it. Constraint: licence. Both remain usable as behavioural references for clean-room work — which is how the register maps get confirmed.

9. The decisions to make

Everything above is evidence. These are the calls it does not make for us, each with what would settle it.

Two of these — #1 and #9 — are worth settling before any code is written, because they change what a phase-1 result means. The rest can wait for the first boot.

Hardware inventory captured 2026-08-17 over ssh from the board itself. Source claims re-verified against freebsd/freebsd-src main (std.arm64, Makefile.arm64, arm_kernel_boothdr.awk, machdep_boot.c, platform_device.h, of.h, simplebus.h), openbsd/src master, raspberrypi/linux rpi-6.12.y, u-boot/u-boot master, and nextbsd-redux/nextbsd-kernel-modules PR #33. Planning only — no code has been written against this board.

← Back · NextBSD Research