Files
UniXNU/docs/reference/configuration.md

295 lines
12 KiB
Markdown

# 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-<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`.
```sh
./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](/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:<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](/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_<NAME>` becomes `XNU_<NAME>`. `{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-<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
- [Boot configuration](/reference/boot-configuration)
- [Device repository](/porting/device-repository)
- [Command line](/reference/cli)