6.3 KiB
Boot the image
Follow Building through boot-image assembly first. The procedure below starts the image from RAM and checks the menu, loader and kernel in order.
Build the firmware with ./unixnu build firmware --uefi ../uefi-<device> and include UniXNURamDiskDxe plus DiskIoDxe and FAT support for a Mu-Silicium initrd payload. Build the payload before ./unixnu bootimg. The firmware integration guide lists the required DSC/FDF entries and menu checks.
For repeated builds, save paths in unixnu.local.toml. After changing boot arguments, rebuild the payload and boot image using the argument workflow. Follow the green-bar diagnosis for a stall at loader handoff.
1. Check inputs
- An unlocked bootloader with
fastboot. - A device with a UEFI port that matches the board configuration.
- A built boot image with a payload, or an empty ramdisk for the boot manager smoke test.
- A serial console when the board exposes a UART.
2. Prepare root storage
Ports using the userdata root layout need that image installed before their first root boot. The image supplies the OS and SystemOS volumes and the root volume UUID that the kernel matches.
Run the flash command when installing or replacing the root image. With the matching root image already installed, continue at step 3.
Flashing userdata overwrites that partition. Confirm the target device, its partition geometry and the report's image path, and save any data needed from that partition before running the command.
fastboot devices
fastboot flash userdata out/<device>/<os_profile>/<config>/userdata/userdata-root.img
fastboot reboot bootloader
The userdata image is large. Build it with unixnu build userdata and flash it from the device repository report.
The Data seed supplies the writable Data volume. The --skip-setup option marks Setup as done in a copy of the seed, so the Hello pages do not run. The procedure and the preference changes are in Skip Setup.
3. Start the image
fastboot devices
fastboot boot out/<device>/<os_profile>/<config>/boot/boot.img
fastboot boot transfers the image and starts it once. The running payload follows its configured storage and installation policy.
The boot image contains:
| Part | Contents |
|---|---|
| Kernel | gzip of BootShim plus the UEFI firmware volume |
| Ramdisk | UniXNU payload FAT volume |
| Appended data | Device tree |
The stock Android bootloader loads the image, verifies the ARM64 header in BootShim, and jumps to the shim. BootShim starts the firmware volume.
4. Check the boot menu
UniXNU prints its version and configuration summary to the serial port and draws the menu. The default configuration uses a timeout, a default entry and a countdown.
| Action | Key |
|---|---|
| Move the highlight | Up and Down |
| Boot the selected entry | Enter |
| Stop the countdown | Any key |
| Confirm an entry | Enter |
| Cancel a confirmation | Any key without choices, or Enter on Cancel |
| Choose a confirmation option | Up and Down, then Enter |
An entry with confirm shows a question before it boots. The countdown skips entries that require confirmation. With confirm_titles, Cancel is selected first and the chosen confirm_args entry is appended to the entry's arguments. See Boot configuration.
The menu entries come from \EFI\UniXNU\unixnu.toml. An entry can start an EFI image, a Linux image with an EFI stub, an action, or a Darwin kernel through the loader protocol.
If UniXNU finds no configuration, it scans every volume for \EFI\BOOT\BOOTAA64.EFI and adds those entries in front of the built-in actions.
5. Check loader handoff
For an entry of type xnu, DarwinBoot reads these files from the entry directory:
| File | Required | Contents |
|---|---|---|
kernel.macho |
yes | Prelinked XNU kernel |
kernel.macho.adt |
yes | Apple-format device tree sidecar |
kernel.macho.trustcache |
no | Trust cache bundle |
the entry initrd |
no | Data ramdisk seed |
DarwinBoot copies the kernel segments into a contiguous physical window, builds boot_args, installs the ADT and the trust cache addresses in the /chosen/memory-map placeholders, and exits boot services.
The default window is 256 MiB. The ADT property /chosen/darwinboot-memory-size can request a larger window.
6. Save logs
The UEFI firmware logs to EFI_SERIAL_IO_PROTOCOL when the board exposes a UART. UniXNU prefixes its lines with UNIXNU:.
The kernel logs to the serial port when the command line selects one, for example serial=3. The boot progress layer writes checkpoints to the framebuffer and the serial port.
Useful logs:
| Source | Location |
|---|---|
| Build driver | out/<device>/<os_profile>/<config>/logs/*.log |
| Boot manager | Serial console, lines with UNIXNU: |
| DarwinBoot | Serial console, lines with DARWINBOOT: |
| XNU | Serial console, kernel output |
Recovery
Use the device's hardware reset sequence to return to its bootloader. Once fastboot responds, the following command restarts that bootloader:
fastboot reboot bootloader
If firmware stalls before the menu, capture the last output, reset into the bootloader and confirm fastboot devices. Check the firmware inputs using bring-up before another attempt.
macOS
A macOS port needs an OS profile matching its XNU version, kernelcache, prelink
roots, private driver ABIs, trust caches and root layout. Qualify those inputs
with kernel preparation and prelink.
The supplied ipados-17.7.11-21H461 profile describes its named iPadOS build.
Select the completed OS profile in board.os_profile, inspect status --json,
then repeat the build and bring-up sequence. Record macOS results against that
profile and the target device.
Next steps
- Userdata image describes the partition image.
- Boot arguments lists the kernel arguments.
- Troubleshooting lists failure conditions and checks.
- Devices lists device specific commands.