U-Boot bootflow: boot a USB or kernel on an Apple Silicon Mac

The boot chain is iBoot → m1n1 s1 → m1n1 s2 → U-Boot → bootflow → GRUB → Linux. bootflow (U-Boot's bootstd subsystem) is where you manually choose what to boot — e.g. the Fedora Asahi live USB you need in order to run luks-deploy.sh, or a specific kernel when GRUB/BLS is misbehaving.

Get to the U-Boot prompt

Interrupt the autoboot countdown: spam a key (any key / Esc / Ctrl-C) at the "Hit any key to stop autoboot" line. You land at the => prompt.

Core sequence

bootflow scan -l        # scan every bootdev; list entries as they're found
bootflow list           # re-show the table afterwards (add -e to include errors)
bootflow select 3       # pick by NUMBER — or by NAME: bootflow select usb0.bootdev
bootflow info           # confirm what's selected  (add -d to dump full details)
bootflow boot           # boot the selected entry

`bootflow scan` flags

flag	meaning
`-l`	list bootflows as they are scanned
`-e`	show errors for entries that failed to load
`-a`	collect all bootflows, including ones that error
`-b`	boot each valid bootflow as it is found
`-G`	skip Global bootmeths

Handy combos:

bootflow scan -lb       # scan, list, and boot the FIRST valid entry (just-boot-something)
bootflow scan -ale      # DIAGNOSTIC: list everything incl. failures + why they failed
bootflow scan usb0      # scope the scan to a single bootdev (see 'bootdev list')

When the entry you want isn't listed

bootdev list            # which boot devices U-Boot sees (nvme0, usb0, mmc…)
bootmeth list           # active boot methods (extlinux, efi, script, …)
bootflow scan -ale      # show why a device's bootflow failed (missing bootmeth, no ESP, …)

Persist the boot order

env print boot_targets              # current order
env set boot_targets "usb nvme"     # try USB before internal NVMe
env save                            # persist to U-Boot env

Where the EFI boot entries live (and why `efibootmgr` lies to you)

boot_targets above is U-Boot's own environment. The EFI boot entries — Boot####, BootOrder, what efibootmgr shows under Linux — are a different store: U-Boot keeps them in one file on the EFI System Partition, /boot/efi/ubootefi.var (lib/efi_loader/efi_var_file.c), and picks that ESP by the PARTUUID the stub names in the device tree (/chosen/asahi,efi-system-partition; arch/arm/mach-apple/board.c). U-Boot reads the file at boot and writes it only from its own boot-time code: an entry shim's fallback registers at boot persists; an entry efibootmgr creates or deletes from Linux is a change to U-Boot's in-memory runtime copy and is gone at the next boot (efi_set_variable_runtime; Kconfig EFI_RT_VOLATILE_STORE: "The OS will be responsible for syncing the RAM contents to the file, otherwise any changes made during runtime won't persist reboots").

So: to remove a stale entry for good, edit the file — boot-guards/bin/uboot-efivar.py does (list, stale, prune-stale, remove NNNN), and the clean-stale-efi-entries guard runs it at every boot. With no Boot#### entry that works, U-Boot's boot manager tries the default loader on the stub's own ESP before any other partition (lib/efi_loader/efi_bootmgr.c, try EFI system partition), so a deleted or unreadable ubootefi.var still boots — the ESP's EFI/BOOT/BOOTAA64.EFI (shim) runs, and shim's fallback writes the entry back.

The flow for this repo (boot the live USB to encrypt)

=> bootflow scan -l
   # find the entry on the usb0 bootdev (NOT nvme0 = the internal disk)
=> bootflow select <N>       # the usb0 entry
=> bootflow info             # sanity check: it's the USB, not the NVMe
=> bootflow boot
   # → boots Fedora Asahi live → sudo /root/AsahiLocker/bin/luks-deploy.sh

Notes / gotchas

usb start first if USB devices don't appear: some builds need usb start (or usb reset) before bootflow scan sees usb0.
Selecting by name is more stable than by number across reboots — the numeric index can shift if a device appears/disappears.
This is separate from GRUB. U-Boot is the UEFI firmware layer; once bootflow hands off to shim/GRUB, use GRUB's own menu and editor. Fedora Asahi normally drives GRUB from BLS entries in /boot/loader/entries/ — which is why luks-deploy.sh updates those with grubby rather than relying on grub2-mkconfig alone.
bootflow boot on a failed/partial entry returns to the => prompt with an error rather than hanging — re-scan with -ale to see the reason.

If the USB never shows up

Some U-Boot builds do not enumerate USB until told to, and some ports are simply not usable for boot. In order:

usb start (or usb reset), then bootflow scan -l again.
bootdev list — if usb0 is absent entirely, U-Boot cannot see the drive.
Try a different physical port, and a different USB stick. Some controllers (notably certain Phison-based drives) enumerate under Linux but stay invisible to U-Boot's bootdev list. That is a firmware/controller issue, not a problem with your install.
bootflow scan -ale shows why a device's bootflow failed.

Kept alongside the LUKS scripts so it is available on the live USB when you need it.

← Back to the full guide: encrypt Fedora Asahi Remix with LUKS2, in place