Files
UniXNU/docs/porting/arm64e.md
UniXNU Docs 1446f449b6 docs(porting): cover the macOS path
The porting flow covers the macos-27.3-26C5035r profile from profile
selection to the porting record: the macOS profile page lists the profile
contents, host inputs, board.toml override, Data seed, build commands,
driver adaptations and boot checkpoints, and the steps, arm64e, packaging,
records, bring-up, building, requirements and reference pages point to it.
The iPadOS instructions are unchanged.

Porting pages link porting pages for driver topics: Develop a driver and
Brightness interface are porting pages, and component names in porting
pages are plain text. English and Chinese pages.
2026-11-10 19:26:10 +08:00

5.4 KiB

arm64e OS profiles

Applies to supported devices only. Use this method only on a device that meets every requirement and appears in supported devices. Other devices use an arm64 profile (iOS 16 or iPadOS 17, for example ipados-17.7.11-21H461) and the regular porting steps. The two arm64 targets share the arm64 patch series in profiles/arch/arm64.

arm64e needs native PAC hardware: a CPU that implements pointer authentication and a hypervisor that leaves it usable, as the requirements check. A device without it stays on arm64: iOS and iPadOS 18 are the last releases that support arm64, and iOS and iPadOS 27 are arm64e only. An arm64e profile builds XNU with pointer authentication (PAC) and links the original arm64e kexts of the target kernelcache.

For a new port, choose a device whose CPUs have PAC and prefer the iOS or iPadOS 27 profile. Its drivers, patches and build recipes are the ones under active maintenance. Every driver and optimization in this repository must work for 17 and 27, arm64 and arm64e, with the build target as the only difference: the --os parameter of the packaging script. A change that works for one target only is not merged.

Requirements

Requirement Check
Every enabled CPU implements FEAT_PAuth with address and generic keys ID_AA64ISAR1_EL1 APA or API, and GPA or GPI, are nonzero; or ID_AA64ISAR2_EL1 APA3 and GPA3 are nonzero
XNU runs at EL1 and can write the five key registers Writing APIAKey, APIBKey, APDAKey, APDBKey and APGAKey at EL1 does not trap
PAC instructions do not trap at EL1 and EL0 PACIA changes a pointer and AUTIA restores it on every core
SoC support exists The SoC repository is listed in SoC support
Native 4 KiB stage 1 translation Same as the arm64 profile, see four-kilobyte pages

A hypervisor that clears HCR_EL2.APK or HCR_EL2.API traps these accesses. Record the result of each check in the device porting.toml.

Supported devices

Device SoC OS profile State
sheng SM8550 ipados-27.0.1-24A446 In development
sheng SM8550 macos-27.3-26C5035r In development

Profile layout

Location Contents
profiles/arch/arm64e arm64e build configuration, PAC key management and XNU patch series
profiles/os/ipados-27.0.1-24A446 XNU 12377.121.6 with the Darwin 26 calls, iPadOS 27.0.1 IPSW pins, prelink roots and OS patches
profiles/os/macos-27.3-26C5035r The same XNU built for macOS user space, macOS 27.3 IPSW pins, prelink roots and OS patches. See macOS profile

The OS profile selects its architecture with [os] arch = "arm64e". Profiles without the key use profiles/arch/arm64. Both architectures use the same components; the arm64e build compiles them for arm64e.

Pointer authentication

An arm64e image stores authenticated pointers as chained fixups that name a key and a diversifier. dyld signs user pointers when it loads an image, and XNU signs kernel collection pointers during early boot. No signature is computed off the device, so the CPU's PAC algorithm does not need to match Apple's.

Public XNU source programs keys only for the paravirtualized VMAPPLE platform, in osfmk/arm64/pac_asm.h. The arm64e profile supplies native key programming for ARMv8.3 key registers.

On ARMv8.3, EL0 and EL1 use the same key registers. The current profile loads one random key set per boot on every CPU and enables SCTLR_EL1 EnIA, EnIB, EnDA and EnDB. The kernel and all arm64e processes share this key set, so PAC does not isolate processes from each other.

An arm64 process runs at EL0 with the four keys off. Its code signs nothing, and the arm64e system libraries it loads authenticate its return addresses with IB. The kernel clears the enable bits on the return to EL0 and sets them again at the EL0 vectors, so EL1 keeps every key. ml_default_jop_pid is nonzero, so the shared region and dyld pagers sign pointers only for arm64e processes.

CPU features

XNU publishes only the features the CPU implements, through hw.optional sysctls and the commpage capability words. SM8550 has no SME.

Procedure

  1. Run the requirement checks on every enabled CPU and record them.
  2. Set board.os_profile = "ipados-27.0.1-24A446" in the device configuration, or pass --os 27 to ./unixnu for one run. For macOS, pass --os macos-27 and follow macOS profile.
  3. Run ./unixnu fetch and ./unixnu status --json. Confirm the arm64e profile, XNU revision and patch order.
  4. Build with Building: kernel, package, firmware, payload, userdata, boot image.
  5. Follow the bring-up order and record each checkpoint.

Facts

  • The public xnu-12377.121.6 tree keeps the non-SPTM pmap in osfmk/arm/pmap.
  • The arm64e kernel builds with the BCM2837 machine config, the non-SPTM pmap and Apple CPU counters disabled.
  • The iPadOS 27 kernelcache is an MH_FILESET with stripped symbol tables. Its kext code branches directly into the kernel, so the arm64 prelink step does not apply.
  • The macOS 27.3 kernelcache keeps its symbol tables. Its prelink map is built from names, and the fileset stays at its linked addresses.