mirror of
https://github.com/UniXNU/UniXNU.git
synced 2026-11-18 10:01:39 +03:00
304 lines
8.9 KiB
Markdown
304 lines
8.9 KiB
Markdown
# Boot configuration
|
|
|
|
The UniXNU boot manager reads `\EFI\UniXNU\unixnu.toml` from the volume it was started from, then from every other volume. A kit directory contains `Kit.toml` with the same match and injection sections.
|
|
|
|
Boot arguments are stored in the payload's `EFI/UniXNU/unixnu.toml`. After changing them, run `./unixnu payload` and `./unixnu bootimg`, then boot the new image. See [apply boot arguments](/xnu/boot-arguments#apply-arguments) for precedence and inspection commands.
|
|
|
|
## Procedure {#procedure}
|
|
|
|
1. Locate the configuration on the payload volume: `EFI/UniXNU/unixnu.toml`. For generated device payloads, edit the source `[payload]` settings in `board.toml` or local build inputs before rebuilding.
|
|
2. Use the [unixnu.toml fields](#unixnu-toml) to define the entry and its paths. Check that each referenced kernel, sidecar, driver and initrd is present in the volume.
|
|
3. For a kit, fill [Kit.toml](#kit-toml) and verify every match rule against the target. Keep paths relative to the configuration or kit as specified below.
|
|
4. Rebuild the payload and boot image. Inspect the packaged configuration with `mtype -i <payload.img> ::/EFI/UniXNU/unixnu.toml`, then check [menu behavior](#menu-behavior) on boot.
|
|
|
|
## unixnu.toml
|
|
|
|
```toml
|
|
version = 1
|
|
|
|
[boot]
|
|
timeout = 5
|
|
rotate = 0
|
|
fallback_timeout = 10
|
|
connect_all = true
|
|
default = "xnu"
|
|
|
|
[ui]
|
|
title = "UniXNU"
|
|
scale = 0
|
|
logo = true
|
|
layout = "auto"
|
|
portrait_below = 800
|
|
console = "auto"
|
|
```
|
|
|
|
### [boot]
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `timeout` | 5 | Seconds. Negative waits for input |
|
|
| `rotate` | 0 | Idle highlight rotation in seconds. 0 disables it |
|
|
| `fallback_timeout` | 10 | Timeout when no input device exists |
|
|
| `connect_all` | true | Calls `ConnectController` on every handle |
|
|
| `default` | first entry | Entry id or index |
|
|
|
|
### [ui]
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `title` | `UniXNU` | Menu title |
|
|
| `scale` | 0 | Glyph scale. 0 selects automatically |
|
|
| `logo` | true | Draws the logo |
|
|
| `layout` | `auto` | `auto`, `landscape` or `portrait` |
|
|
| `portrait_below` | 800 | With `auto`, portrait when width / height times 1000 is below this value |
|
|
| `console` | `auto` | `auto`, `graphics`, `text` or `none` |
|
|
|
|
The portrait layout is a column for a tall panel such as a phone. The logo floats at the top, the entries are numbered cards at the bottom, and the status lines wrap under a rule. The logo carries the UniXNU wordmark, so the title text appears only when `logo` is false or `title` is not `UniXNU`. With `auto`, a 1080x2400 panel (ratio 450) is portrait, a 3:4 tablet (750) is portrait, and a 4:5 panel (800) or any wider one keeps the landscape layout. Without a `scale` value, the portrait layout picks a glyph scale of width / 270, so a 1080 pixel wide panel shows about 33 characters per line.
|
|
|
|
### [[driver]]
|
|
|
|
```toml
|
|
[[driver]]
|
|
path = "Drivers/MyDriver.efi"
|
|
args = "board=1"
|
|
connect = true
|
|
enabled = true
|
|
```
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `path` | required | File path or `fv:<GUID>` |
|
|
| `args` | | Load options |
|
|
| `connect` | true | Connects controllers after the driver starts |
|
|
| `enabled` | true | `false` skips the entry |
|
|
|
|
A kit driver uses `file` instead of `path`.
|
|
|
|
### [[dt_patch]]
|
|
|
|
```toml
|
|
[[dt_patch]]
|
|
op = "set"
|
|
node = "/chosen"
|
|
prop = "bootargs"
|
|
value = "console=ttyAMA0"
|
|
type = "string"
|
|
```
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `op` | `set`, `delete-prop`, `add-node`, `delete-node` or `overlay` |
|
|
| `node` | Absolute node path |
|
|
| `prop` | Property name for `set` and `delete-prop` |
|
|
| `value` | Value for `set` |
|
|
| `type` | `string`, `stringlist`, `u32`, `u64`, `bytes` or `empty` |
|
|
| `file` | Overlay file for `overlay` |
|
|
|
|
Patches apply to EFI and Linux entries. The Darwin path uses the `.adt` sidecar.
|
|
|
|
### [[block_slice]]
|
|
|
|
```toml
|
|
[[block_slice]]
|
|
partition = "<GPT name>"
|
|
name = "<slice name>"
|
|
offset = 0
|
|
length = 0
|
|
writable = false
|
|
enabled = true
|
|
```
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `partition` | GPT partition name |
|
|
| `name` | Label in the device path |
|
|
| `offset` | Byte offset from the partition start |
|
|
| `length` | Byte length. 0 means to the end |
|
|
| `writable` | Publishes a writable block device |
|
|
| `enabled` | `false` skips the slice |
|
|
|
|
The slice appears as a whole disk with its own device path. A child partition scheme or file system driver can bind to it.
|
|
|
|
### ACPI
|
|
|
|
```toml
|
|
[acpi]
|
|
add = ["Tables/DSDT.aml", "Tables/SSDT.aml"]
|
|
```
|
|
|
|
Each table is installed through `EFI_ACPI_TABLE_PROTOCOL`. The header length must match the file size.
|
|
|
|
### Kits
|
|
|
|
```toml
|
|
[[kit]]
|
|
path = "Kits/MyKit.kit"
|
|
enabled = true
|
|
|
|
[kits]
|
|
autoload = true
|
|
directory = "Kits"
|
|
```
|
|
|
|
Explicit kits load first. With `autoload`, every `*.kit` directory under `directory` loads in name order.
|
|
|
|
### [[entry]]
|
|
|
|
```toml
|
|
[[entry]]
|
|
id = "xnu"
|
|
title = "UniXNU"
|
|
type = "xnu"
|
|
path = "Payloads/kernel.macho"
|
|
args = "-v serial=3"
|
|
initrd = "Payloads/scratch-data.img"
|
|
confirm = "Boot the kernel?"
|
|
confirm_titles = ["Normal", "Verbose"]
|
|
confirm_args = ["", "debug=0x14e"]
|
|
enabled = true
|
|
```
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `id` | Entry identifier |
|
|
| `title` | Menu title |
|
|
| `type` | `efi`, `linux`, `action` or `xnu` |
|
|
| `path` | EFI image, Linux image or kernel path |
|
|
| `args` | Load options or kernel command line |
|
|
| `dtb` | `firmware`, a file path, or absent |
|
|
| `initrd` | Initrd path |
|
|
| `confirm` | Question shown before the entry boots. The entry never boots by countdown |
|
|
| `confirm_titles` | Optional choice titles. Requires `confirm` and `confirm_args` |
|
|
| `confirm_args` | One argument string per choice. The chosen string is appended to `args` |
|
|
| `action` | `reset`, `shutdown`, `exit` or `tools` for `action` entries |
|
|
| `enabled` | `false` skips the entry |
|
|
|
|
An entry with `confirm` boots only when Enter is pressed. Without choices, any other key cancels, and a machine without an input device cancels. With `confirm_titles`, Up and Down step through the choices and Cancel is selected first. The chosen `confirm_args` entry is appended to a copy of the entry's `args`.
|
|
|
|
When the default entry requires confirmation, the countdown falls back to the first entry that does not.
|
|
|
|
The built-in configuration has `exit`, `reset`, `shutdown` and `tools` entries. `tools` opens a second-level menu listing the installed menu plugins. When no file is found, removable loaders are added in front of them.
|
|
|
|
### [entry.chosen]
|
|
|
|
```toml
|
|
[entry.chosen]
|
|
bootargs = "console=ttyAMA0"
|
|
```
|
|
|
|
Every key becomes a `/chosen` property. These patches apply after the entry patches.
|
|
|
|
### [[entry.kext]]
|
|
|
|
```toml
|
|
[[entry.kext]]
|
|
bundle = "Kexts/MyDriver.kext"
|
|
plist = "Contents/Info.plist"
|
|
executable = "Contents/MacOS/MyDriver"
|
|
enabled = true
|
|
```
|
|
|
|
Entry kexts apply only to the entry that declares them.
|
|
|
|
### [[entry.variable]]
|
|
|
|
```toml
|
|
[[entry.variable]]
|
|
guid = "00000000-0000-0000-0000-000000000000"
|
|
name = "MyVariable"
|
|
value = "hello"
|
|
type = "ascii"
|
|
volatile = true
|
|
```
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `guid` | Variable GUID |
|
|
| `name` | Variable name |
|
|
| `value` | Value |
|
|
| `type` | `ascii`, `ucs2`, `u8`, `u16`, `u32`, `u64` or `bytes` |
|
|
| `volatile` | `false` adds `EFI_VARIABLE_NON_VOLATILE` |
|
|
|
|
The variables are set before the entry starts.
|
|
|
|
### [[entry.dt_patch]]
|
|
|
|
The entry accepts its own `[[dt_patch]]` array. Entry patches apply after global patches.
|
|
|
|
## Kit.toml
|
|
|
|
```toml
|
|
schema = 1
|
|
|
|
[kit]
|
|
name = "MyKit"
|
|
version = "1.0.0"
|
|
description = "Board support"
|
|
|
|
[match]
|
|
arch = "AARCH64"
|
|
fdt_compatible = ["vendor,board"]
|
|
firmware_vendor = ["Vendor"]
|
|
requires_protocol = ["00000000-0000-0000-0000-000000000000"]
|
|
|
|
[[driver]]
|
|
file = "MyDriver.efi"
|
|
args = "from-kit"
|
|
|
|
[[overlay]]
|
|
file = "board.dtbo"
|
|
|
|
[[dt_patch]]
|
|
op = "set"
|
|
node = "/chosen"
|
|
prop = "from-kit"
|
|
value = "1"
|
|
type = "u32"
|
|
|
|
[[acpi]]
|
|
file = "DSDT.aml"
|
|
|
|
[[kext]]
|
|
bundle = "MyDriver.kext"
|
|
entry = "xnu"
|
|
```
|
|
|
|
| Section | Meaning |
|
|
| --- | --- |
|
|
| `[kit]` | Name, version and description |
|
|
| `[match]` | All present keys must match |
|
|
| `[[driver]]` | Driver file relative to the kit |
|
|
| `[[overlay]]` | Device tree overlay relative to the kit |
|
|
| `[[dt_patch]]` | Device tree patch |
|
|
| `[[acpi]]` | ACPI table relative to the kit |
|
|
| `[[kext]]` | Kext bundle scoped to an entry id |
|
|
|
|
Match keys:
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `arch` | `AARCH64` |
|
|
| `fdt_compatible` | Strings in the firmware root `compatible` list |
|
|
| `firmware_vendor` | Substring of `gST->FirmwareVendor` |
|
|
| `requires_protocol` | GUIDs that must be installed |
|
|
|
|
Within a key, any listed value matches. Across keys, every key must match.
|
|
|
|
## Menu behavior
|
|
|
|
| Condition | Result |
|
|
| --- | --- |
|
|
| Input device present | Countdown runs to the timeout |
|
|
| No input device | `fallback_timeout` applies |
|
|
| Negative timeout with input | Waits for a key |
|
|
| Negative timeout without input | `fallback_timeout` applies |
|
|
| Failed boot | Returns to the menu without a countdown |
|
|
|
|
The menu shows the configuration source, the entry list, the injection summary and the first error.
|
|
|
|
## Next steps
|
|
|
|
- [Payload](/concepts/payload)
|
|
- [Kext bundles](/drivers/kexts)
|
|
- [Device configuration](/reference/configuration)
|