Files

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
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

  1. --local-module [KIND:]NAME=PATH
  2. --local-<kind> DIR
  3. --local DIR
  4. a local key in feeds.toml or local.toml
  5. the device repository
  6. the base repository
  7. a git source in feeds.toml

The first match wins.

Next steps