Files
UniXNU/docs/porting/macos.md

16 KiB

macOS profile

macos-27.3-26C5035r builds a kernel for macOS 27.3 user space. It is an arm64e profile, so the device must pass the arm64e requirements. One device repository serves the iPadOS and macOS profiles: the macOS values sit in [os_overrides."macos-27.3-26C5035r"] of board.toml, and an iPadOS build never reads them.

This page follows Port a device and names what differs for macOS. Every step not named here is the same as for iPadOS.

What the profile supplies

profiles/os/macos-27.3-26C5035r/profile.toml in UniXNU:

Table Content
[os] XNU 12377.121.6 with target = "macosx". The kernel is compiled with XNU_TARGET_OS_OSX on the machine configuration, memory layout and link address of the iPadOS kernel
[ipsw] UniversalMac_27.3_26C5035r_Restore.ipsw, product Mac17,11. fetch lists the kernelcache, the device tree and the static, system and application trust caches
[kernel.prelink] The kernelcache_sha256 pin, the roots of the macOS startup closure and early_security_init. A root with a leading ! is left out of the closure. The collection keeps its symbol tables and its linked addresses, so there is no slide
[adt] The Mac17,11 identity, the /chosen boot volume UUIDs and the asmb boot policy
[userdata] Three windows: OS, SystemOS (Cryptex1,SystemOS) and App (Cryptex1,AppOS)
[root], [payload.adt] Volume UUIDs and image digests of the three windows, and the root volume UUID

configs/macos.config and patches/xnu/series beside it hold the kernel configuration and the patch series: the Darwin 26 system calls and kernel interfaces, the macOS machine options, the Data firmlinks, the VM and Hardware volumes on Data, and the application cryptex mount.

Signed-text fixups retain their original bytes for verification. Code-signing checks use a bounded snapshot; APFS compressed-block checks use a private copy while resident executable pages keep the configured instructions.

1. Check the host and inputs

A macOS build runs on a Mac with Xcode. In addition to the common requirements:

Input Source
macOS SDK Xcode. The boot shim and the device recipes that use macOS family headers compile with xcrun --sdk macosx
IPSW [ipsw] url of the profile, or --ipsw
Kernelcache Extracted from the IPSW and checked against kernelcache_sha256
Trust caches [payload.runtime] trust_components names the IPSW members that go into the owner trust bundle
Data seed Made once as root from the system volume, see step 4
Root access sudo for the Data seed; noninteractive sudo for read-only Metal-library enumeration

2. Add the macOS values to the device repository

Add a defconfig for the profile, map it in [package.defconfig], and put every value that differs under the override. The sheng board file is a complete example.

[package.defconfig]
"macos-27.3-26C5035r" = "<device>_macos_defconfig"

[os_overrides."macos-27.3-26C5035r"]
remove = ["payload.install", "payload.skip_setup_tool", "payload.runtime.appsync"]

[os_overrides."macos-27.3-26C5035r".kernel]
defconfig = "<device>_macos_defconfig"
config_fragments = ["arch:configs/common.config", "os:configs/macos.config"]
archives = ["<every archive recipe of the macOS kernel, in order>"]

[os_overrides."macos-27.3-26C5035r".components]
include = ["<every component of the macOS kernel>"]

[os_overrides."macos-27.3-26C5035r".payload]
size_mib = 200
kernel_args = ["<every kernel argument of the macOS image>"]

[os_overrides."macos-27.3-26C5035r".payload.adt]
chip_id = "6050"

[os_overrides."macos-27.3-26C5035r".payload.runtime]
target = "macos27"
build = "26C5035r"
data_seed_tool = "scripts/make-macos-data-seed.py"
data_gib = 210
skip_setup = false
boot_shims = true
Key macOS value
[package.defconfig] The defconfig that --os and the packaging script select for the profile
kernel.config_fragments os:configs/macos.config
kernel.patch_series No override when the board list uses the os: prefix: os:patches/xnu/series resolves to the macOS series
kernel.archives, components.include, payload.kernel_args Complete lists. Arrays replace the board arrays
kernel.prelink.roots Not set. The profile list applies. A board list for another profile belongs in that profile's override, because a board value replaces the profile list
payload.size_mib Room for the kernel collection, the Data seed and the addon
payload.adt.chip_id 6050, the chip of Mac17,11
payload.runtime.target, build macos27 and 26C5035r
payload.runtime.data_seed_tool The seed script that runs as root
payload.runtime.data_gib Size of the Data volume. The persistent Data store must not overlap the root image in userdata
payload.runtime.skip_setup true adds --skip-setup to the seed command
payload.runtime.boot_shims Adds the owner apfs_boot_util to the addon, for apfs-boot-shim=1
payload.runtime.gpu_addon true builds the Metal plugin for macOS. With gpu-addon=1 the kernel writes it to /Library/GPUBundles on Data
remove Board keys that apply to iPadOS only, such as the install entry, payload.skip_setup_tool and payload.runtime.appsync

On sheng the macOS defconfig differs from the iPadOS 27 one only in the Data volume UUID, which the build writes from the seed. The Mac17,11 identity comes from the profile.

Kernel arguments that the macOS patch series adds:

Argument Effect
vc-text=1 Draws the kernel console as text on the boot framebuffer and mirrors it to the serial console
exec-log=1 Prints every image activation and every exit with its wait status and reason. Diagnostic, off by default
apfs-boot-shim=1 Shows the addon's apfs_boot_util over the system's for launchd's mount boot tasks. Needs boot_shims = true
timebase-hz=24000000 Gives user space a 24 MHz timebase when the hardware counter runs at another rate
gpu-addon=1 Writes the Metal plugin to /Library/GPUBundles

3. Select the profile

--os applies to one command. Pass it to every command of a macOS build, or set board.os_profile on a board that builds macOS only. macos-27 resolves to macos-27.3-26C5035r, and the output directory is out/<device>/macos-27.3-26C5035r/<config>/.

./unixnu defconfig <device>_macos_defconfig -D ../UniXNU-<device> --os macos-27
./unixnu fetch --os macos-27
./unixnu ipsw info --os macos-27
./unixnu status --json --os macos-27

ipsw info shows 27.3 (26C5035r). status shows the macOS profile root, the merged override and the patch order.

4. Make the Data seed

Build the kernel and the payload in one command, so the kernel build binds the seed's volume UUID:

./unixnu build kernel payload --os macos-27

Without a seed the command stops before compiling and prints the seed creation command, including the OS image, output path and data_gib.

Create an account and skip Setup

Run from the UniXNU checkout with the paths and size printed by the build. Prompt for a short login name, display name and hidden password:

sudo python3 scripts/make-macos-data-seed.py \
  "<OS image>" "<output>/runtime/data.dbr" --gib "<data_gib>" \
  --skip-setup --interactive-user --auto-login

The script creates a local administrator and its home, preserves template owners, and skips both initial and first-login Setup. The output seed must be new.

The prompts use admin and Admin as defaults. sudo authenticates the build host account; the interactive password is assigned to the new macOS administrator.

For automation, replace --interactive-user with --user NAME:PASSWORD and --real-name NAME, or read credentials from a private JSON file:

sudo -v
sudo -n python3 scripts/make-macos-data-seed.py \
  "<OS image>" "<output>/runtime/data.dbr" --gib "<data_gib>" \
  --skip-setup --user-stdin --auto-login < account.json

account.json contains name, password and an optional real_name string. --real-name overrides the JSON display name. Supplied credentials do not open an account input prompt.

Build and pack using that seed:

./unixnu build kernel payload --os macos-27 \
  --data-ramdisk "<output>/runtime/data.dbr"
./unixnu bootimg --os macos-27 \
  --data-ramdisk "<output>/runtime/data.dbr"

After flashing fresh userdata on sheng, select Initialize macOS Data and boot and confirm Initialize Data and boot. This erases macOS Data and initializes its persistent store from the seed. Use Boot on subsequent starts to retain Data. The account and Setup settings come from the seed; --skip-setup is a seed creation option.

The sheng macOS desktop profile builds its BootShim, board firmware and DarwinBoot from the selected sources. Its 256 MiB logical payload uses chunk compression and fits the 193 MiB boot-image limit. The menu selects Boot after one second. autoreset=7200 and uefi-watchdog=1 provide the firmware return timer; diag-export=7140 retains the boot log before the deadline. Shader Cache is installed in Applications and shows compilation progress.

Seed creation options:

Argument Effect
--skip-setup Marks Setup Assistant done
--user NAME:PASSWORD Adds a local administrator and its home
--real-name NAME Sets the displayed administrator name; the short account name and /Users/NAME remain unchanged
--user-stdin Reads name, password and optional real_name from a JSON object on standard input
--interactive-user Prompts for the account name, display name and password
--auto-login Logs the selected account in at boot. For unattended tests
--keyboard-type PRODUCT-VENDOR-COUNTRY=TYPE Records a keyboard layout type, so Keyboard Setup Assistant does not ask
--volume-uuid UUID Gives the Data volume a fixed UUID, so a new seed replaces an older one without a kernel build

Keep runtime/data.dbr for every later build of the installation. A payload build with a seed whose UUID differs from the compiled configuration stops and asks for a kernel build. The kernel mounts the seed at /System/Volumes/Data and sets the firmlinks of /usr/share/firmlinks.

5. Build the images

./unixnu build kernel payload --os macos-27
./unixnu build package --os macos-27
./unixnu build firmware --os macos-27
./unixnu build userdata --os macos-27 --dry-run
./unixnu build userdata --os macos-27
./unixnu bootimg --os macos-27

The packaging script runs the same steps except userdata:

scripts/package.sh --os macos-27 --uefi ../uefi-<device>

For sheng, prepare the LLVM 22 tools, then save the installation inputs in the UniXNU checkout's unixnu.local.toml:

[build]
device = "../UniXNU-sheng"
uefi = "../uefi-sheng"
clang_bin = ".cache/edk2-llvm22"
data_ramdisk = "/path/to/installed-data.dbr"
unique_chip_id = "<device platform seed>"

Then run ../UniXNU-sheng/scripts/package.sh --os macos-27 from UniXNU. Add the exported kernel tool paths on a host using exported build inputs. package.manifest.json records the source revisions, complete boot arguments and runtime input identities.

The sheng macOS workflow uses Xcode 26.6, Python 3.14 and LLVM/LLD 22. Configure repository secrets UNIXNU_UNIQUE_CHIP_ID and UNIXNU_LAB_PASSWORD for the device identity and the initial administrator account. root_storage=true builds the three verified root windows and userdata; false retains the profile's signed policies for a boot-image update.

A saved Android sparse userdata image can supply the three root images locally:

python3 ../UniXNU-sheng/scripts/restore-macos-images.py /path/to/userdata.sparse

The script checks each recovered image against the selected OS profile and stores it as out/ipsw/<build>/<window>.raw.dmg. The build uses these verified images. Reserve their combined size plus build space before extraction.

Step macOS difference
Kernel XNU_TARGET_OS_OSX, the macOS series and the prelink against the macOS kernel collection
Payload The Mac17,11 ADT, the owner trust bundle and the addon built for macos27
Userdata Three windows. Check the dry-run capacity against data_gib
Package, firmware, boot image None

A board that links owner root policies (CONFIG_XNU_SOURCE_STORAGE=y) needs a signed policy for each window. scripts/make-root-policies.py --tree TREE --output POLICIES --window NAME=IMAGE:VOLUME_UUID writes POLICIES/NAME/manifest.header.bin, trusted-key.bin and verification.json, and the hash table TREE/build/verified-root-NAME/hashes.bin. IMAGE holds the window's bytes; its SHA-256 equals [root] <window>_image_sha256 of the profile. The storage archive recipe reads the policy directory named by its --policy-dir argument. With CONFIG_XNU_SOURCE_STORAGE_TABLES="userdata", add each hash table to the userdata image as --object NAME.vroot=FILE.

6. Adapt the drivers

Follow driver adaptation in the same order. The macOS kernel collection has its own class layouts, and macOS user space expects some services that iPadOS does not. The sheng port shows each case:

Area macOS adaptation
Private class bindings A fixture per build for each bound class family, scripts/<family>-26C5035r.json. scripts/gen-board-abi.py writes them from the symbols of the collection, and the display recipe selects them by build
Crypto SoftwareAES joins components.include and kernel.archives, compiled against the 26C5035r class layout. A board probe registers it, because AppleImage4 waits for an IOAESAccelerator service
Network en0 is an IOEthernetController of the original IONetworkingFamily, started with ethernet=1. It carries the Wi-Fi module's frames. The TimeSync clock takes its identifier from the address of an Ethernet or 802.11 interface, and WindowServer waits for that clock. The supplicant is built for macOS and its job is a plist in /Library/LaunchDaemons
Input The HID device starts with offline-hid-home=1. WindowServer pairs the touch screen with the display through the service's displayUUID, the UUID the framebuffer publishes as IOMFBUUID
Keyboard cover A keyboard and a pointer: relative motion, scroll steps and two buttons, without the Keyboard Power usage
GPU The plugin is built as a macOS bundle with its executable in Contents/MacOS
Audio The audio server plug-in is a macOS driver bundle in /Library/Audio/Plug-Ins/HAL
Bluetooth The daemon opens the serial device /dev/cu.BLTH. The board's daemon, BlueTool and capability library sit in the addon's sbin and lib, shown over /usr/sbin and /usr/lib
Firmware images in the kernel Placed in __DATA,__firmware

7. Boot and check

Flash the userdata image and boot as in Boot the image. The bring-up order applies with these macOS checkpoints:

Stage Check
Storage and root The partition scheme publishes OS, SystemOS and App. The root is the read-only system volume with SystemOS mounted over it
Data Data mounts at /System/Volumes/Data. /System/Volumes/VM and /System/Volumes/Hardware resolve into it
Cryptexes The OS cryptex view and the App cryptex appear below /System/Volumes/Preboot/Cryptexes
Userland launchd finishes its boot tasks and WindowServer presents the login window or Setup Assistant

vc-text=1 keeps the kernel log on the panel. exec-log=1 names a boot task that fails.

8. Record the results

device.os_profile in porting.toml equals board.os_profile, the default profile of the board. A board that serves several profiles keeps one record: write the macOS configuration, findings and evidence into the same areas and name the profile and build in each entry. See porting records.