Port a device

UniXNU runs iOS or macOS on ARM64 devices through UEFI. The welcome page explains the architecture. Follow the eight steps below to collect inputs, select shared support, adapt drivers and build images. Each step states its expected result. New and migrated repositories use the same completion and publication requirements.

• Add a device: start at step 1.
• Build an existing device: check its inputs and current support in Devices, then follow Building.
• Migrate an existing repository: update its configuration with the migration guide, then continue with the required driver adaptation and build steps.

1. Collect the device inputs

Prepare the host tools. Record the board's SoC, CPU layout, RAM reservations, interrupt controllers, storage, panel, touch sensor, wireless chip and firmware versions. Use the stock DTS, firmware source and hardware observations as sources. Read the target repositories' root AGENTS.md.

Create a porting record as you collect these facts. For each subsystem, record its input source, implementation, current result and next measurement. The driver adaptation checklist links subsystem interfaces, source references and build integration, including services in the device package.

Result: a hardware inventory and a list of missing inputs. Hardware addresses and partition geometry must come from the target board.

2. Choose shared support

Read the component catalog and candidate implementations before selecting drivers. Match hardware revision, firmware protocol and OS ABI.

Location	Contents to select or implement
UniXNU/profiles/arch/arm64	Common ARM64 build configuration and patches
UniXNU-<soc>-common	SoC resources, DTSI, platform operations and patches
UniXNU/profiles/os/<profile>	XNU/IPSW revisions, ABI, prelink and OS patches
UniXNU-<device>	Board wiring, component selection, firmware and partition policy
Component repository	Reusable driver, library, loader or tool
uefi-<device>	Firmware platform and peripheral initialization

Follow SoC support to select an existing implementation or create a shared repository. Check resources, platform operations and component dependencies, then pin the source in the device configuration. A new OS profile needs the XNU and patch inputs and prelink ABI work before hardware drivers can be qualified.

Result: selected repositories and exact source revisions, with unresolved hardware or ABI work recorded.

3. Create the device repository

The template selects SM8550 and the iPadOS 17.7.11 profile. Set DEVICE to the new board's codename. Run from the UniXNU repository:

DEVICE=myboard
DEVICE_DIR="../UniXNU-$DEVICE"
cp -R examples/device "$DEVICE_DIR"
mv "$DEVICE_DIR/configs/example_defconfig" "$DEVICE_DIR/configs/${DEVICE}_defconfig"
mv "$DEVICE_DIR/dts/board.dts" "$DEVICE_DIR/dts/${DEVICE}.dts"

Complete these files using the device repository reference:

1. board.toml: set the board name, kit, SoC source, OS profile, DTS entry point and firmware paths. Review the complete component and archive selections.
2. feeds.toml: set the SoC repository URL and commit. For another SoC, also change board.soc, board.soc_source and the DTS include.
3. Set kernel.defconfig to <device>_defconfig and device_tree.source to device:dts/<device>.dts to match the renamed files. Review all configuration fragments and patch series for the selected SoC and OS.
4. Fill the RAM range, enabled CPUs, peripherals and reservations in the DTS.
5. List required firmware files and their sources in proprietary-files.txt.
6. Complete porting.toml, the root README and AGENTS.md for the board. Match the record identity to board.toml, cover every selected component and dependency, and set ownership paths to the actual board files. Keep the copied .github/workflows/porting-record.yml, .gitignore and local.toml.example; review them with the completion checklist.
7. Remove board.example = true after the required placeholders are filled. The build commands reject repositories marked as examples.

Arrays replace inherited arrays. Keep the complete required component, archive, configuration-fragment and patch-series lists in each override.

Result: a device repository whose source pins and hardware values are explicit.

4. Resolve and inspect the build

./unixnu defconfig "${DEVICE}_defconfig" -D "../UniXNU-$DEVICE"
./unixnu fetch
./unixnu status --json
./unixnu tree

Inspect the selected profiles, component sources, overrides and patch order in status. The assembled sources appear under out/<device>/<os_profile>/<config>/tree/; the device's package/ appears there as kits/<board.kit>. Run component scripts from this assembled tree when their instructions use scripts/, drivers/ and kits/ together.

Result: resolved dependencies and a build tree with the selected revisions. Use configuration for field definitions and CLI reference for options.

5. Prepare hardware description and firmware

Follow device-tree conversion to compile the board DTS and inspect the ADT resources consumed by drivers. The payload command generates kernel.macho.adt from this hardware description and the selected OS profile. The boot image separately needs the DTB required by the device's firmware.

Follow UEFI integration to include UniXNU, DarwinBoot and payload filesystem support. For a Mu-Silicium initrd, include UniXNURamDiskDxe, DiskIoDxe and FAT support in the DSC and FDF.

Include the firmware log exporter so you can scan logs from the menu during initial bring-up.

Result: a buildable firmware configuration and two identified tree inputs: the board DTS for XNU's ADT, and the firmware DTB for boot-image assembly.

6. Adapt drivers in dependency order

Work through driver adaptation: platform and memory, storage, display and brightness, input, GPU, Wi-Fi, then DSP, audio and power. Each guide identifies source files, board inputs, build integration and expected observations. Select only implementations whose required inputs are satisfied.

Result: each selected capability has its own configuration and verification entry. A component selected in TOML still needs its archive recipe and board hooks.

7. Build and start the image

Save the paths from requirements in local build configuration. Follow Building in order: kernel, package, firmware, payload, userdata when required, then boot image. Check each output before proceeding. For a separate UniXNU partition, follow the partition procedure before installing the image.

Follow bring-up for firmware, menu, loader, kernel and root checkpoints. Use boot and recovery for device commands. After changing boot arguments, rebuild both the payload and boot image as described in apply arguments.

Result: build outputs and separately recorded device observations. For a failure, record the last completed checkpoint and use debugging and troubleshooting.

Set up QR log export during firmware integration and save the firmware log before kernel handoff. After storage verification, follow the same guide through persistent capture, a manual cycle and automated tests.

8. Complete and publish the repository

Follow repository completion in order: check the tracked files, resolve sources, validate the record, and publish the reviewed commit. This is also the final procedure for migrated repositories.

Add the unixnu GitHub topic using the publication commands. Enable the record workflow and publish the device revision and bilingual pages through porting records and documentation contribution.

Result: the repository meets the common format 2 requirements and is discoverable through the unixnu topic. Its record identifies completed and pending work with source, host and device evidence.

Related documentation

Use these references for the step you are working on:

Topic	Documentation
Boot process and image inputs	Boot chain, prelink, payload, userdata layout, integrity and boot policy
Component implementation and development	Driver layers, driver repositories and component pages
Kernel changes	Source and patches, patch reference, 4 KiB page tables
Build and boot configuration	Command line, device configuration, boot configuration, output layout
Host verification	QEMU workflow
Project maintenance	Repository layout, documentation workflow, glossary

Use Technical reference for fields, driver interfaces, kernel patches and project maintenance.