Porting research

This entry summarizes PORTING_RESEARCH.md in the repo root — a long-form survey written before implementation started, gathering every known resource on FreeBSD support for the RK3399S (PinePhone Pro) and RK3566 (PineTab2). Read it when you want historical context: what was already working in early 2026, what was known to be blocked, and which forum threads, repositories, and schematics to consult.

The summary below mirrors the document’s structure. The full document is the source of truth and includes ~50 hyperlinks to specific resources that this summary doesn’t reproduce.

Headline finding

The PinePhone Pro research snapshot had display, touchscreen, and battery management working, while WiFi, USB, and cellular were still major open blockers. The current tree has moved beyond that: USB networking, native WiFi association/DHCP, Bluetooth A2DP, Panfrost graphics, on-device speaker audio, buttons, LEDs, and raw sensors are all represented. PineTab2 remains the harder RK3566/tablet target: its MIPI DSI display and BES2600 WiFi chip still lack FreeBSD drivers.

— PORTING_RESEARCH.md opening paragraph (the assessment as of research date; many of the identified blockers have since been knocked down — see Status).

PinePhone Pro: the existing port

Honeyguide and the pre-built image

• Primary repo: Honeyguide/freebsd-pinephonepro on Codeberg — 63 commits, C 93.7%. Toby Kurien is the developer (teekay on FreeBSD forums); Stephan Lichtenauer (@hnygd) coordinates at the Honeyguide Group.
• Pre-built image at pppfreebsd.honeyguide.net — freebsd-pinephonepro-20250523.img.xz, ~1 GB compressed, ~9 GB uncompressed. Includes minimal Xorg, on-screen keyboard, kernel source, build tools.
• Three FreeBSD quarterly status reports cover the project (Q3 2024, Q4 2024, Q1 2025); Pine64 featured it in the August 2025 community blog.

What was working at research time

Boot to multi-user, serial via headphone jack, EFI framebuffer display, backlight, Goodix touchscreen, R/G/B notification LEDs, RK818 PMIC (custom Honeyguide driver), RTC, battery charging via USB, battery status via sysctl hw.acpi.battery, minimal Xorg via scfb software rendering.

What was blocked

WiFi/Bluetooth, USB enumeration, cellular modem, audio, cameras, GPU acceleration, and sensors were the research-time gaps. In this repo, USB management, WiFi association/DHCP, Bluetooth A2DP, loudspeaker playback, Panfrost-backed Sway, volume/power buttons, LEDs, STK3311, MPU-6500, TSADC, eFuse, and several bench candidates have since landed. The remaining PinePhone Pro work is now mostly quality and policy: WiFi SDIO IRQ versus poll fallback, modem SIM/data policy, microphone/headphone routing, suspend/resume, camera infrastructure, battery/thermal UI, and upstream cleanup.

Bootloader and SPI flash

• RK3399S boot order is SPI flash → eMMC → microSD; Megi’s rk2aw modifies this to prefer SD.
• SPI NOR is GD25LQ128EWIGR (schematic) / SK25LP128 (some boards).
• Three bootloader options exist: Tow-Boot (pre-installed July 2022–November 2023), rk2aw + Megi U-Boot 2024.04 (recommended for FreeBSD because it sets up the EFI framebuffer), and levinboot (community alternative, beta).

RK3399S vs RK3399

The RK3399S is binned and voltage-locked, running ~20% slower for smartphone thermals. Linux uses a dedicated rk3399-s.dtsi for the DVFS OPP table modifications. FreeBSD has supported the RK3399 since late 2018 (Phabricator review D16732, Emmanuel Vadot); existing drivers cover RK808 PMIC, CRU clock, GPIO, I²C, SD/MMC, UART, cpufreq. The PinePhone Pro port adds an RK818 PMIC driver, RTC, and battery charger/monitor.

Driver-by-driver gaps and porting priorities

• WiFi (BCM43455 SDIO) — the single biggest blocker. Nascent brcmfmac port at narqo/freebsd-brcmfmac supports BCM4350 (PCIe) and BCM43455 (RPi4); SDIO support in FreeBSD remains limited. Landon Fuller’s Broadcom WiFi Improvements writeup is the canonical reference.
• USB — controllers detected but no devices visible. Blocks the internal cellular modem and external peripherals. Toby explicitly asked for FreeBSD USB-subsystem expertise.
• GPU (Mali T860 MP4) — has a path forward via the FreeBSD panfrost port reviewed for other RK3399 boards; needs proper DRM/KMS for the Rockchip display engine.

PineTab2: building on the Quartz64 foundation

RK3566 status in FreeBSD today

Preliminary support via the Quartz64 platform. Definitive forum thread: “How to run FreeBSD on new boards built on Rockchip 35XX”. Soren (sos@FreeBSD.org) hosts installable images at people.freebsd.org/~sos/ARM64/RockChip/. Community contributor covacat added eMMC HS200 (198 MHz, ~150 MB/s), EQOS Ethernet (940 Mbit/s FDX), and clock-tree fixes.

Recommended boot path: Tianocore EDK2 UEFI via jaredmcneill’s quartz64_uefi. Supports both ACPI and FDT modes. PineTab2 not yet in the supported list but should slot in.

What works on RK3566 today: eMMC and microSD (with covacat’s patches), USB 2.0, HDMI (DW-HDMI driver, covacat fixed a deadlock), GPIO/I²C/ SPI/PWM/UART via DT overlays, Gigabit Ethernet at 1 Gbps, partial PCIe (resource allocation bugs — see bugs.freebsd.org #281722).

Critical gotcha: tsadc@fe710000 causes reboots during boot on some RK3566 boards — work around with fdt rm /tsadc@fe710000 in loader.conf.

What makes the PineTab2 harder than the Quartz64

• MIPI DSI display. BOE TH101MB31IG002-28A 10.1” IPS panel (1280×800). FreeBSD has no MIPI DSI driver framework at all. Linux has panel-boe-th101mb31ig002-28a.c. Workaround: use the micro-HDMI port via DW-HDMI for development; ship MIPI DSI later.
• BES2600 WiFi. Bestechnic SDIO chip used only in PineTab2 and PineTab-V. Even on Linux the driver is out-of-tree, crash-prone, and lacks Bluetooth. Hardware bug prevents reset without a full power cycle. Porting to FreeBSD is impractical — use a USB WiFi dongle (RTL8xxxU or MT76xx, both supported in FreeBSD).
• Additional gaps: Goodix touchscreen (PinePhone Pro driver should adapt), RK817 PMIC (partial FreeBSD support), cameras (no drivers), GPU acceleration (Mali-G52 MP2 — Bifrost/Valhall, not panfrost-able).

PineTab2 device tree

In mainline Linux via Heiko Stuebner’s rockchip tree: rk3566-pinetab2-v0.1.dts, rk3566-pinetab2-v2.0.dts, shared rk3566-pinetab2.dtsi. Submitted by Manuel Traut and Alexander Warnecke. Not in the FreeBSD source tree. U-Boot has a pinetab2-rk3566_defconfig. Compile the DTB from Linux sources manually — many nodes reference drivers that don’t exist on FreeBSD, but the DTB still compiles and the unbound nodes simply don’t attach.

OpenBSD as a reference point

OpenBSD added RK3566/RK3568 support in OpenBSD 7.3 (April 2023). Supported boards: Quartz64 A/B, Firefly ROC-RK3566-PC, NanoPi R5S, Radxa ROCK 3A. PineTab2 not listed. OpenBSD developer bluerise contributed to quartz64_uefi.

Cross-compiling and image layout

Cross-compile from amd64

cd /usr/src
make -j$(sysctl -n hw.ncpu) TARGET=arm64 TARGET_ARCH=aarch64 buildworld
make -j$(sysctl -n hw.ncpu) TARGET=arm64 TARGET_ARCH=aarch64 \
  buildkernel KERNCONF=GENERIC

Object files end up in /usr/obj/usr/src/arm64.aarch64/. On an AMD FX-8350, full cross-build is approximately 2 hours. We cross-build on honor (FreeBSD 15 amd64) — see Build environment.

Disk image layout for Rockchip boards

Rockchip U-Boot is written to raw sectors, not as a partition:

Flash with dd if=idbloader.bin of=/dev/sdX bs=512 seek=64 conv=notrunc. For EDK2 UEFI, same offsets with idblock.bin and BOARD_EFI.itb. Kwiboo’s u-boot-rockchip fork with CONFIG_EFI_LOADER=y is confirmed working for RK3566.

Device tree handling in FreeBSD

Two source locations: Linux-imported DTS at sys/contrib/device-tree/src/arm64/rockchip/, FreeBSD-specific overlays at sys/dts/arm64/overlays/. DTBs install to /boot/dtb/. Overlays declared in loader.conf as fdt_overlays="overlay1.dtbo,overlay2.dtbo". To swap base DTB, fdt_file="myboard.dtb". FreeBSD can also boot ACPI mode via EDK2 UEFI, bypassing FDT entirely. Useful debugging tip from gonzo: sysctl -b hw.fdt.dtb | dtc -I dtb dumps the runtime device tree.

See Writing a device-tree overlay for our overlay workflow.

Pine64 hardware documentation

Both boards have full schematics, PCB component placement, and datasheets at files.pine64.org/doc/. The PinePhone Pro UART console uses the 3.5 mm headphone jack at 1,500,000 baud (8N1) with hardware privacy switch #6 enabled. Must be 3.3 V TTL — 5 V will damage the SoC. The PinePhone Pro was officially discontinued in August 2025 due to low sales; refurbished units and spare parts remain available for two years.

The PineTab2 UART uses a dedicated USB-C UART dongle (ships in the box) at 1,500,000 baud, plugged into the USB-C port furthest from the power button.

Recommended porting strategy (research-time)

For PinePhone Pro, the highest-impact contributions identified were USB host controller debugging, WiFi driver porting, and upstreaming. Those are no longer all first-light tasks in this tree: USB management and native WiFi are alive. The current high-value work is deciding BCM43455 SDIO IRQ versus explicit poll fallback, cleaning up Bluetooth userland orchestration, turning modem enumeration into SIM/data policy, and preparing upstreamable slices for the device tree plus narrow drivers.

For PineTab2: start with a headless boot via the Quartz64 DTB, compile the PineTab2 DTB from Linux mainline, use micro-HDMI with DW-HDMI for graphical output, bypass BES2600 entirely with a USB WiFi dongle. MIPI DSI framework and BOE panel driver are a longer-term collaboration with the FreeBSD DRM/graphics community.

Essential developer resources

• Emmanuel Vadot, “FreeBSD ARM32/ARM64: Porting to a new board” (BSDCan 2018) — canonical guide.
• “FreeBSD on the Pinebook Pro” (FreeBSD Journal) — DRM, panfrost, audio for RK3399.
• “The Panfrost Driver” (FreeBSD Foundation paper).
• wiki.freebsd.org/arm/RockChip.
• Mailing list: freebsd-arm@FreeBSD.org.
• Pine64 community: Discord, Matrix #pinephone:matrix.org, forums.

Conclusion (verbatim)

The PinePhone Pro FreeBSD port is real, active, and usable for development. The original research called USB and WiFi the critical barriers; this repo has since brought both past first light. The PineTab2 port is still feasible because the RK3566 SoC already has working FreeBSD drivers via the Quartz64 platform, and the device tree is in mainline Linux. The two hardest PineTab2-specific problems are the MIPI DSI display and the BES2600 WiFi. The pragmatic path remains: use the PinePhone Pro for FreeBSD mobile development now, finish and upstream the phone’s drivers, then bring up the PineTab2 headless via HDMI using the Quartz64 foundation.

— PORTING_RESEARCH.md, conclusion. This was the plan, and it is broadly the path the project has followed.