mirror of
https://github.com/UniXNU/UniXNU.git
synced 2026-11-18 10:01:39 +03:00
295 lines
12 KiB
Markdown
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)
|