HFS+ bootloader plan for FreeBSD

Companion to the HFS+ kernel module port plan and scopes issue #80 (boot-132 / modern derivative). The HFS+ kmod gets us read/write of HFS+ data partitions after the kernel is up; this plan addresses the prior question: how does the bootloader find the kernel if the boot partition is HFS+? Three options reviewed; recommendation: Option C (UFS for /boot, HFS+ for data) — zero bootloader work, and matches how every modern FreeBSD installer already lays out disks.

1. What we're solving

FreeBSD's stand/loader (the second-stage bootloader that runs after boot0/boot1) can read UFS, ZFS, ext2fs, ISO 9660, FAT/msdosfs, and NFS. It cannot read HFS+. So an installation with HFS+ on /boot can't start — the loader physically can't find kernel.bin or loader.conf on disk.

If we want HFS+ anywhere on a freebsd-launchd-mach system, three patterns satisfy that:

1. Replace FreeBSD's loader with an HFS+-capable one (boot-132 family).
2. Teach FreeBSD's loader to read HFS+ (add one file to stand/libsa).
3. Don't put HFS+ on /boot — use UFS for the boot partition, HFS+ for whatever data we want.

The HFS+ kmod port (separate plan) handles all post-kernel HFS+ access regardless of which option we pick here.

2. Apple boot-132 (BIOS) — what it is, plus the UEFI boot path

Attribute	Status
Repository	apple-oss-distributions/boot
Last release	boot-132, October 24, 2006. Final release Apple ever published. Seven tags total, nothing newer in ~20 years.
License	APSL 2.0 (Aug 6, 2003)
Architecture	i386 only. No x86_64, no PPC (PPC BootX was separate, also abandoned).
Size	~30k LOC C + assembly (90% C, 6% asm)
Boot model	3-stage BIOS chainloader. No UEFI. Pre-boot.efi.
Partition table	MBR only. GPT support added by community forks (Chameleon, Clover), not Apple.
Successor	boot.efi (10.6+), iBoot (iOS/Apple Silicon). Both closed-source; never published.

What boot-132 actually does:

1. boot0 — MBR sector-0 stub; finds the active partition.
2. boot1h — HFS+ partition boot sector; locates /boot in the HFS+ catalog B-tree.
3. boot (stage 2) — reads mach_kernel + Extensions.mkext (kext cache) from HFS+; parses com.apple.Boot.plist for kernel args; sets up the Mach boot-args page; switches to protected mode; jumps to xnu's entry.

The handoff at the end of stage 2 is completely Darwin-specific: Mach boot-args page, kext cache pointer, specific xnu entry contract. Pointing this code at FreeBSD's kernel.bin means replacing the entire handoff and the kext-cache logic with FreeBSD's elf_freebsd_exec/loader interaction — at which point you've reimplemented stand/loader, just badly.

The UEFI boot path (Apple EFI · generic UEFI · FreeBSD loader.efi)

boot-132 is a BIOS loader: the chain above (boot0 MBR sector → boot1h partition sector → the /boot file) is pure MBR/BIOS and has no UEFI equivalent. Under UEFI the firmware itself owns a filesystem driver, reads the GPT, and launches a PE/COFF .efi application off a partition — there is no boot0/boot1h sector chain at all. Three cases matter for HFS+:

• Apple Intel Macs. Apple's EFI firmware ships a built-in HFS+ driver, so it reads the HFS+ system volume directly and launches /System/Library/CoreServices/boot.efi, which loads the prelinkedkernel/kernelcache and hands off to XNU. "Boot from HFS+" worked because the firmware itself could read HFS+ — there was never a /boot file or a boot1h sector involved on EFI Macs.
• Generic PC UEFI (hackintosh). Stock firmware reads only FAT (the EFI System Partition). To boot HFS+ you must first load an EFI HFS+ driver (VBoxHfs.efi / HfsPlus.efi) — exactly what OpenCore/Clover ship, and the only reusable ~3–5k LOC buried in them (see §3).
• FreeBSD / NextBSD. Firmware → ESP (FAT) → loader.efi, which finds the kernel through the shared stand/libsa filesystem readers. It can't read HFS+ today — the same gap as the BIOS loader, and fixable in the same place: a libsa HFS+ reader compiles into both loader (BIOS) and loader.efi (UEFI), so one reader covers both firmwares.

This is why the recommendation is firmware-agnostic. Option C (UFS/ZFS for /boot + the FAT ESP that UEFI already requires, HFS+ for data) needs nothing on either BIOS or UEFI. Option B's single libsa reader serves both. Only boot-132 (Option A) is BIOS-only — UEFI support would mean bolting on a separate EFI HFS+ driver (OpenCore territory), which is the bulk of why §5 rejects it.

3. Modern descendants: OpenCore, Clover, Chameleon

Project	License	Status	FS support	Boot model
OpenCorePkg	BSD-3-Clause	Active; v1.0.7 March 20, 2025; 5,005 commits	HFS+ via closed-Apple-derived HfsPlus.efi binary blob in OcBinaryData; APFS via Apple's container-embedded driver; FAT native; ext4/btrfs via plug-ins	Pure UEFI
Clover	BSD-2-Clause	Active; release-5172g, March 22, 2026; 2,489 commits	HFS+ via VBoxHfs.efi (VirtualBox-derived, LGPL-compatible); APFS via Apple's driver; FAT, ext, NTFS	BIOS + UEFI
Chameleon (meklort fork)	APSL 2.0	Dormant since ~2014	HFS+, FAT32, ext2, GPT+MBR	BIOS (closest to boot-132)

Architectural reality: all three exist to boot macOS/Darwin. Their reason for being is the Apple-specific bring-up dance (SMBIOS spoofing, ACPI patching, ApplePlatformInfo emulation, EfiBoot protocol, kext injection). For our purposes we'd be importing ~50–200k LOC of macOS-emulation work to use the ~3-5k LOC HFS+ reader buried inside. That's a maintenance trap.

What's useful from this ecosystem: the standalone HFS+ readers they each ship are extractable.

• Clover's VBoxHfs — LGPL, EDK2-style EFI driver, ~3-5k LOC, derived from VirtualBox's HFS+ reader, read-only, byte-swappable, no Apple binary dependency. Best candidate for re-use as the basis of a libsa-side reader.
• OpenCore's OpenHfsPlus — the open variant; acidanthera bug #659 calls it slow and unaudited.
• GRUB's HFS+ module — GPLv3, used by rEFInd via efi.akeo.ie's driver bundle. License-incompatible with our preferred posture.
• PureDarwin's HFSPlus_EFI — sparse, 6 commits, unclear licensing.
• boot-132's own i386/boot2/hfs.c — APSL 2.0, oldest, last touched 2006.

4. FreeBSD's stand/loader today

From freebsd-src/stand/libsa:

Filesystem	File	Approx LOC
UFS	ufs.c, ufsread.c	~1500
ext2fs	ext2fs.c	~1200
ISO 9660	cd9660.c, cd9660read.c	~600
FAT/msdosfs	dosfs.c	~1100
NFS	nfs.c	~900
ZFS	zfs/ subdir	~larger
HFS+	(none, never has been)	—

The loader's plug-in FS ABI is simple: each filesystem implements fs_open/close/read/write/seek/stat/readdir via a struct fs_ops exposed through libsa. Adding a new reader is a single C file. UFS is ~1500 LOC, ext2fs ~1200, cd9660 ~600 — an HFS+ read-only reader for libsa would fit in the same ~1.5–3 kLOC envelope, far smaller than the EDK2-style EFI drivers because libsa provides its own buffered-block I/O (no UEFI protocol marshalling).

5. Option A — Port boot-132 / OpenCore

What it is: import Apple's boot-132 source (or OpenCore) into our tree, modify the stage-2 handoff to point at FreeBSD's kernel.bin instead of mach_kernel, replace the kext-cache logic with whatever FreeBSD's loader does to find modules, and wire it as the live ISO's bootloader.

Effort: rough lower bound 3 person-months. Most of the work isn't the HFS+ reader (which is already wired) — it's gutting the Darwin handoff and replacing it with FreeBSD's loader contract. Boot-132's BIOS-only model and i386-only support also mean we'd be writing the EFI side too. OpenCore brings EFI for free but drags in vastly more macOS-emulation code we'd have to either disable or maintain.

Tradeoffs:

• + HFS+ reader already wired (the only real "pro")
• − Massive code drag for Darwin-specific bring-up logic we don't want
• − No Apple upstream — we'd be maintaining ~30k LOC of bootloader by ourselves
• − Option A's effort is greater than writing the HFS+ reader from scratch into our existing loader (Option B)
• − Two parallel bootloader lineages (FreeBSD's existing loader stays for non-HFS+ setups) is a maintenance liability

Verdict: not recommended.

6. Option B — Add HFS+ reader to stand/libsa

What it is: write a new stand/libsa/hfs.c that implements fs_ops for HFS+ read-only. Wire it into stand/loader.mk behind a LOADER_HFSPLUS_SUPPORT switch. Source material: port Clover's VBoxFsDxe/VBoxHfs* (LGPL, clean BSD/LGPL-compatible) into libsa's idiom, dropping the EDK2 protocol wrapping in favor of libsa's fs_ops ABI.

Effort: 2–3 weeks for someone experienced with libsa; ~1–1.5 person-months for a junior dev. Add a week if we also want an EFI-driver standalone version of the same reader for the ESP (EFI_SIMPLE_FILE_SYSTEM_PROTOCOL wrapping around the same core).

What it delivers:

• /boot/loader can read kernel + modules + loader.conf from HFS+
• Works for BIOS and EFI loaders identically (loader is FS-agnostic above libsa)
• Tested by the same CI that tests every other libsa filesystem
• Reuses VBoxHfs's well-tested read path

Tradeoffs:

• + Tiny surface area (one C file)
• + Lives in the existing loader; no parallel bootloader to maintain
• + License-clean (LGPL via VBoxHfs, or APSL 2.0 if we instead clean-room from boot-132's hfs.c)
• + Read-only is fine for /boot — loader never writes
• ~ Requires touching FreeBSD stand/ code — if we want it upstream eventually, FreeBSD-src patch flow
• − ~2-3 weeks of work for a feature only needed if we want HFS+ root, which Option C avoids without the work

Verdict: the right answer if a real use case emerges. Don't write it preemptively.

7. Option C — UFS for /boot, HFS+ for data recommended

What it is: partition the disk so /boot is UFS (or ZFS, or msdosfs ESP). HFS+ lives on data partitions where the kmod can mount it post-kernel-load. Modern FreeBSD installers already do this — EFI System Partition (FAT) + freebsd-boot + freebsd-ufs (root) + freebsd-swap; HFS+ becomes another freebsd-data-style partition.

Effort: zero. Nothing to build, nothing to change in the loader.

What it delivers: the HFS+ kmod handles all post-boot HFS+ workflows (mount Apple DMG images, read/write external Apple drives, Time Machine sparsebundle inspection, etc.). The cost is one extra small partition for /boot — which is standard hygiene anyway.

Tradeoffs:

• + Zero bootloader work
• + Matches FreeBSD's default install layout
• + Matches how Linux handled it for years (ext-on-/boot, anything-else on root)
• + Doesn't preclude Option B later if needed
• ~ Means we can't say "freebsd-launchd-mach boots from an HFS+ root" — we'd have UFS-or-ZFS root with HFS+ as data
• − If we ever ship onto Mac hardware that came formatted as pure-HFS+, the user has to repartition

8. Decision matrix

Dimension	A: Port boot-132/OpenCore	B: Add HFS+ to libsa	C: UFS for /boot
Effort	3+ person-months	2-3 weeks	0
Boots from HFS+ root	Yes	Yes	No (UFS root)
HFS+ data works (with kmod)	Yes	Yes	Yes
Mount Apple DMGs (with kmod + dmg2img)	Yes	Yes	Yes
Maintenance burden	High (~30k LOC bootloader)	Low (~1.5-3k LOC libsa file)	None
License posture	APSL 2.0 (Apple-aligned)	LGPL via VBoxHfs OR APSL 2.0 via boot-132	n/a
Upstream-able to FreeBSD	No	Maybe (one-file libsa addition)	n/a

9. Out of scope

• Apple Silicon boot. iBoot, LocalPolicy, SEP are closed and architecturally incompatible. Asahi's m1n1 is a separate universe.
• FileVault 2 unlock. Needs CoreStorage / APFS encryption stack. Not in HFS+ scope at all.
• APFS booting. Separate filesystem; OpenCore needs Apple's own embedded apfs.efi blob, not portable. Different effort.
• UEFI Secure Boot signature chain for Apple platforms. Apple boot policy is closed.
• boot.efi compatibility / Apple boot picker. We're not emulating a Mac; FreeBSD's loader UI is fine.
• HFS+ write from the loader. /boot is read-only from loader's perspective.
• Journal replay in the loader. Only matters for writes; read-only reader ignores the journal.

Drafted 2026-05-26 from an agent research pass against Apple boot-132, OpenCore/Clover/Chameleon source repos, FreeBSD stand/libsa tree, and rEFInd/EDK2 HFS+ EFI driver ecosystem. Companion to HFS+ kernel module port plan and hdiutil port plan. Scopes issue #80. Sources: apple-oss-distributions/boot, OpenCorePkg, CloverBootloader, FreeBSD stand/libsa.