12 KiB
Device configuration
Format 2 uses schema_version = 2 at the top of board.toml. Files without
this field use format 1. See the device repository specification
for profile ownership and examples.
Local build inputs
Copy unixnu.example.toml to unixnu.local.toml in the UniXNU checkout and fill in your device paths. The file is ignored by Git. Use --config /path/to/build.toml to select another file.
[build]
device = "../UniXNU-<device>"
uefi = "../uefi-<device>"
dtb = "/path/to/firmware.dtb"
kernelcache = "/path/to/kernelcache"
trust_cache = "/path/to/trustcache.bundle"
data_ramdisk = "/path/to/data-seed.dbr"
unique_chip_id = "<hex>"
jobs = 8
target = "DEBUG"
kernel_args = ["-v", "serial=3", "debug=0x14e"]
Replace the placeholders with your port's inputs. Relative paths start at the configuration file's directory. Command-line flags take priority, followed by environment variables, then this file, then device defaults. kernel_args overrides board arguments by name; --kernel-arg overrides local arguments by name.
Supported path keys are device, out, uefi, edk2, clang_bin, kernel_sdk, kernel_tools, kernelcache, kernel, trust_cache, owner_trust_cache, data_ramdisk, gpu_addon, dtb, fd, ramdisk, and output. Other keys are ipsw (path or URL), unique_chip_id (hex string), jobs (positive integer), target (DEBUG or RELEASE), and kernel_args (string array). ramdisk = "none" selects an empty boot-image ramdisk.
clang_bin selects the EDK II tool directory containing clang, lld-link, llvm-lib and llvm-rc (--clang-bin or CLANG_BIN). kernel_sdk and kernel_tools select an exported iPhoneOS SDK and toolchain bin directory for kernel compilation and prelink. Their command-line options are --kernel-sdk and --kernel-tools; their environment variables are UNIXNU_KERNEL_SDK and UNIXNU_KERNEL_TOOLS.
./unixnu defconfig <device>_defconfig
./unixnu kernel
./unixnu firmware
./unixnu payload
./unixnu bootimg
./unixnu status --json
status reports the selected file as build_config. Build inputs use unixnu.local.toml; module source overrides use the device repository's local.toml.
The device enables the AppSync adapter
with [payload.runtime] appsync = true and the matching kernel patches. It
applies to all user application bundles without per-app build inputs.
Profile fields
| Table | Key | Meaning |
|---|---|---|
board |
soc_source |
Name of a pinned kind = "soc" source |
board |
os_profile |
Directory under profiles/os/ |
components |
include |
Canonical component IDs; dependencies are resolved in build order |
kernel |
config_fragments |
Ordered profile-relative configuration files |
kernel |
patch_series |
Ordered profile-relative series files |
device_tree |
source |
DTS entry point, such as device:dts/myboard.dts |
device_tree |
include_dirs |
DTS include paths, such as soc:dts |
Layers apply as ARM64, SoC, OS, device. Tables merge by key; arrays replace.
The selected defconfig applies after config_fragments. File prefixes are
arch:, soc:, os:, and device:. Series entries also accept
component:<ID>/path. unixnu status --json reports the effective configuration.
board.toml [os_overrides."<profile>"] holds the board values that differ for one OS profile. The
table of the selected profile merges over the board, and the others are dropped. Its remove array
lists dotted keys, such as payload.runtime.appsync, that are deleted after the merge. A removed key
is gone from the merged profile and board values together, so a board list that would replace a
profile list belongs in the override of the profile that uses it.
board.toml
[board]
| Key | Type | Meaning |
|---|---|---|
name |
string | Output directory name |
soc |
string | SoC identifier |
description |
string | Human readable description |
kit |
string | Device package folder under kits/ |
example |
boolean | Marks a sample. Build and bootimg refuse it |
[ipsw]
| Key | Type | Meaning |
|---|---|---|
url |
string | Default remote IPSW |
product |
string | Product type, for example iPad7,1 |
version |
string | Product version |
build |
string | Product build |
device_class |
string | Device class from the manifest |
chip_id |
integer | ApChipID |
board_id |
integer | ApBoardID |
fetch |
array | Components extracted by ipsw fetch |
[ipsw.sha256]
| Key | Type | Meaning |
|---|---|---|
| member file | string | Expected SHA-256 of the extracted member |
[userdata]
| Key | Type | Meaning |
|---|---|---|
first_lba |
integer | First LBA of the userdata GPT entry |
last_lba |
integer | Last LBA of the userdata GPT entry |
lba_bytes |
integer | Logical block size |
windows |
array | { name, component } entries |
[kernel]
| Key | Type | Meaning |
|---|---|---|
defconfig |
string | File name under configs/ |
archives |
array | Archive builder scripts of the build tree, run in order before the kernel link |
[kernel.prelink]
| Key | Type | Meaning |
|---|---|---|
tool |
string | Prelink tool path in the build tree |
kernel |
string | Native kernel path in the build tree |
slide |
string | Address slide |
roots |
array | Bundle identifiers kept from the kernelcache |
early_security_init |
string | identifier=address |
kernelcache |
string | Optional path to a local kernelcache |
kernelcache_sha256 |
string | Expected kernelcache hash |
extra_args |
array | Extra prelink arguments |
[firmware]
| Key | Type | Meaning |
|---|---|---|
config |
string | Mu-Silicium Resources/Configs/<name>.toml |
dsc |
string | DSC path in the checkout |
fd |
string | Firmware volume path, {target} replaced |
packages |
array | PACKAGES_PATH entries |
preflight |
array | Preflight scripts in the build tree |
patches |
array | Patches applied to edk2 for the build |
submodules |
array | Mu-Silicium submodules to initialize |
[firmware.defines]
| Key | Type | Meaning |
|---|---|---|
| any | string | -D NAME=VALUE for the EDK II build |
[bootimg.image]
| Key | Type | Meaning |
|---|---|---|
base |
integer | Image base address |
kernel_offset |
integer | Kernel offset |
tags_offset |
integer | Tags offset |
pagesize |
integer | Image page size |
header_version |
integer | Android boot image header version |
kernel_compression |
string | gzip (default) or none; selects how the kernel is stored in the boot image |
bootimg.dtb_node
| Key | Type | Meaning |
|---|---|---|
path |
string | Device tree node path |
props |
array | { name, type, value } |
Types are s for string, x for hex cells, i for decimal cells, u for unsigned cells and empty.
[payload]
| Key | Type | Meaning |
|---|---|---|
volume |
string | FAT label, at most 11 characters |
size_mib |
integer | Volume size |
loader |
string | firmware or a driver path mode |
title |
string | Menu title |
dram_size |
string | DRAM size for the ADT |
panic_screen |
boolean | Patch the panic screen into the payload kernel |
trust_cache_sha256 |
array | Accepted trust cache hashes. An owner bundle passed with --owner-trust-cache skips this list |
kernel_args |
array | Default kernel arguments |
tools |
boolean | Add Tools to the generated menu; configure plugins with log capture |
timeout |
integer | Menu timeout |
skip_setup_tool |
string | Script used by --skip-setup |
[payload.adt]
| Key | Type | Meaning |
|---|---|---|
tool |
string | ADT generator path |
chip_id |
string | Chip ID for the ADT |
owned_memory_size |
string | Contiguous window request |
owned_memory_excluded_ranges |
integer | Size of the excluded-range table; the window may then span more than one run of free memory. Only for an OS profile whose XNU reads the table |
loader_inputs |
boolean | Reserve the records in which DarwinBoot reports where the payload RAM disk and the initrd buffer lie |
owned_memory_outside_ranges |
integer | Size of the table in which DarwinBoot lists the free memory outside the window. A kernel with window-outside-memory-adoption.patch adopts it as VM memory, one probed page at a time; memory-outside=0 leaves it alone |
owned_memory_outside_reserved |
array of strings | "BASE:SIZE" parts of that memory the kernel must not adopt: memory a board driver uses at a fixed address |
root_match_volume_uuid |
string | Root volume UUID |
cpu_regs |
string | CPU MPIDR values, comma separated |
psci_method |
string | smc or hvc |
packed_data_ramdisk |
boolean | Use the packed Data format |
ipad_identity |
boolean | Write the Apple device identity properties |
unique_chip_id |
string | required when the seed is mandatory |
[payload.runtime]
Runtime inputs prepared before the kernel build. The Data seed's volume UUID is written to
CONFIG_XNU_OWNER_DATA_VOLUME_UUID.
| Key | Type | Meaning |
|---|---|---|
tool |
string | Runtime builder in the build tree |
target |
string | Userspace target, such as ios27 or macos27 |
build |
string | OS build the inputs were inspected against |
data_gib |
integer | Size of a new Data seed |
skip_setup |
boolean | Mark Setup as done in a new Data seed |
data_seed_tool |
string | Seed script that runs as root. A missing seed stops the build with the command to run |
gpu_addon |
boolean | Build the GPU addon (default true). With false, the trust bundle holds the original caches only |
boot_shims |
boolean | Add the owner apfs_boot_util to the addon, for macOS with apfs-boot-shim=1 |
trust_components |
array | IPSW trust cache components bundled for the owner trust cache |
wallpapers, audio_tool, wifi_tool, bluetooth_tool, appsync |
Optional userspace layers added to the addon |
defconfig
CONFIG_NAME=y
CONFIG_NAME=n
CONFIG_NAME="text"
CONFIG_NAME=123
# CONFIG_NAME is not set
Each CONFIG_XNU_<NAME> becomes XNU_<NAME>. {tree} in a string becomes the build tree path.
feeds.toml
[[source]]
name = "Name"
kind = "driver" # driver, kit, patch, script, package, refer, soc
git = "https://github.com/ORG/REPO"
ref = "main"
path = "drivers/Name"
commit = "..."
local = "/path/to/local"
submodules = []
| Key | Meaning |
|---|---|
name |
Module name |
kind |
Module kind |
git |
Source repository |
ref |
Branch, tag or commit to fetch |
path |
Optional subdirectory, fetched sparse |
commit |
Optional pin |
local |
Local directory instead of git |
submodules |
Upstream submodules to initialize |
local.toml
An ignored file in the device repository:
[local]
drivers = "/path/to/drivers"
kits = "/path/to/kits"
patches = "/path/to/patches"
scripts = "/path/to/scripts"
package = "/path/to/package"
unixnu.lock
[source."Name"]
commit = "0123456789abcdef"
Written by unixnu fetch for Git sources. Format 2 gives an explicit source commit priority over the lock, including the selected OS XNU revision. Format 1 uses lock-first precedence. Official aliases can reuse lock entries recorded under their accepted source names.
Module resolution
--local-module [KIND:]NAME=PATH--local-<kind> DIR--local DIR- a
localkey infeeds.tomlorlocal.toml - the device repository
- the base repository
- a git source in
feeds.toml
The first match wins.