5.8 KiB
Boot arguments
Apply boot arguments
The effective command line combines [payload] kernel_args in the board profile, [build] kernel_args in unixnu.local.toml, and --kernel-arg overrides. Later sources replace arguments with the same name. The payload builder writes it to EFI/UniXNU/unixnu.toml as the XNU entry's args. UniXNU passes the selected entry to DarwinBoot, which copies the line into XNU's boot_args.CommandLine at boot. Kernel configuration switches are compiled by ./unixnu kernel.
With local build inputs saved:
./unixnu payload --kernel-arg serial=3 --kernel-arg debug=0x14e
./unixnu bootimg
jq -r .kernel_args out/<device>/<os_profile>/<config>/payload/payload.json
mtype -i out/<device>/<os_profile>/<config>/payload/payload.img ::/EFI/UniXNU/unixnu.toml
Boot the newly generated boot/boot.img. bootimg copies the current payload into that file. Editing a payload after packaging requires running bootimg again. A custom --ramdisk FILE selects that file's configuration. Check the XNU entry you select and any appended confirm_args. When several volumes contain unixnu.toml, check the configuration on the boot manager's own volume first.
The payload command prints kernel args: and DarwinBoot prints DARWINBOOT: command line: before handoff. If they differ, inspect the selected volume and entry. If they match and behavior is unchanged, check that the kernel or selected driver implements the argument. A green handoff bar is covered in early boot diagnosis.
Format
An argument matches:
[A-Za-z0-9_.-]+(=[A-Za-z0-9_.,-]+)?
The joined line is at most 1000 bytes. DarwinBoot copies it into a 1024-byte buffer.
./unixnu build payload --kernel-arg serial=3 --kernel-arg debug=0x14e
Common arguments
| Argument | Purpose |
|---|---|
-v |
Verbose kernel output |
serial=3 |
Selects the serial console |
debug=0x14e |
Enables the debug output mask |
kextlog=0xfff |
Verbose kext logging |
-apfs_shared_datavolume |
Uses the shared APFS data volume |
-no_slto_panic |
Suppresses the SLTO panic |
kt_fixed_zones=<n> |
Fixes the kernel trace zone count |
boot-progress=<n> |
Selects the boot progress display level |
cs_debug=<mask> |
Code signing debug output |
amfi_get_out_of_my_way=1 |
Runs without AMFI enforcement |
pmap_debug=<mask> |
Pmap debug output |
zlog=<name> |
Selects the zone log |
Use amfi_get_out_of_my_way=1 only in a diagnostic boot. It changes the security policy.
Platform arguments
| Argument | Purpose |
|---|---|
platform-stage=<n> |
Stops the platform expert at a fixed stage |
pmgr=<n> |
Selects the board PMGR integration |
native-ufs-root=1 |
Uses the native UFS root path |
native-ufs-stats-delay=<n> |
Delays the UFS statistics read |
armcpu-diagnostics=1 |
Prints the CPU and interrupt state |
armcpu-spi-ipi=1 |
Uses the SPI path for inter-processor interrupts |
smp=1 |
Starts the secondary CPUs |
cpufreq=<n> |
Selects the CPU frequency path |
touch=<n> |
Runs the touch probe stage |
touch-hz=<n> |
Selects the touch SPI clock |
touch-mode=<n> |
Forces the touch SPI mode |
touch-hid=1 |
Publishes touch contacts to HID |
aks=1 |
Enables the AKS path |
aks-sls=<n> |
Selects the reported lock state; 3 means no passcode |
usb=<n> |
Runs QcomDwc3; 2 adds register sampling, 3 also cycles the bus once |
usb-host=<s> |
Forces USB host mode after a delay |
usb-back=<s> |
Returns to the cable's role after this time in forced host mode |
gpu-power=<n> |
Selects the GPU power sequence |
gpu-metal=1 |
Enables the Metal path |
gpu-addon=1 |
Mounts the GPU addon content |
data-persist=<n> |
1 proves the Data store window read-only, 2 opens it for writes |
data-reset=<n> |
1 discards the Data overlay, 2 also asks for Setup |
log-reserve=<mib> |
End-of-userdata reserve for the diagnostic log and export region, default 1024 |
data-fua=1 |
Runs the Data store write through (every write with FUA) instead of write back |
ufs-bench=1 |
Runs the UFS read benchmark before the boot goes on, logs it and restarts into fastboot |
disable-watchdogd=1 |
Stops the watchdog daemon |
disable-jobs=<list> |
Skips the named launch jobs |
offline-legacy-*=1 |
Enables the legacy display and input probes |
offline-owner-root-check=1 |
Starts the verified root check |
offline-owner-root-audit=1 |
Enables the root binding audit |
offline-apfs-load=1 |
Loads APFS at the offline checkpoint |
offline-mobile-graphics-*=1 |
Enables the mobile graphics probes |
boot-ui-focus=<name> |
Selects the process for the boot UI trace |
The list above includes board specific arguments. Check the device page and the board file for the set a device uses.
Adding an argument
- Add the default to
[payload] kernel_args. - Add a one-off value with
--kernel-arg. - Read the value in the kernel with
PE_parse_boot_argn:
unsigned stage = 0;
if (PE_parse_boot_argn("my-driver-stage", &stage, sizeof(stage))) {
...
}
- Document the argument in the device page.
Debugging
| Need | Arguments |
|---|---|
| Early kernel output | -v serial=3 debug=0x14e |
| Kext load detail | kextlog=0xfff |
| Boot progress | boot-progress=2 |
| Platform stop | platform-stage=<n> |
| Storage detail | native-ufs-root=1 native-ufs-stats-delay=30 |
| Display detail | offline-legacy-gop=1 offline-legacy-phase=<n> |
| Code signing detail | cs_debug=<mask> |
A panic log records the last kernel output. The embedded panic region is read from the device tree when XNU_DT_PANIC_REGION is set.