# 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](/porting/device-repository) for profile ownership and examples. ## Local build inputs {#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. ```toml [build] device = "../UniXNU-" uefi = "../uefi-" 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 = "" 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`. ```sh ./unixnu defconfig _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](/concepts/security#user-application-installation) 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:/path`. `unixnu status --json` reports the effective configuration. `board.toml` `[os_overrides.""]` 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/.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](/porting/log-capture#firmware-setup) | | `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_` becomes `XNU_`. `{tree}` in a string becomes the build tree path. ## feeds.toml ```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: ```toml [local] drivers = "/path/to/drivers" kits = "/path/to/kits" patches = "/path/to/patches" scripts = "/path/to/scripts" package = "/path/to/package" ``` ## unixnu.lock ```toml [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- 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 - [Boot configuration](/reference/boot-configuration) - [Device repository](/porting/device-repository) - [Command line](/reference/cli)