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.
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
- Run the requirement checks on every enabled CPU and record them.
- Set
board.os_profile = "ipados-27.0.1-24A446"in the device configuration, or pass--os 27to./unixnufor one run. For macOS, pass--os macos-27and follow macOS profile. - Run
./unixnu fetchand./unixnu status --json. Confirm the arm64e profile, XNU revision and patch order. - Build with Building: kernel, package, firmware, payload, userdata, boot image.
- Follow the bring-up order and record each checkpoint.
Facts
- The public
xnu-12377.121.6tree keeps the non-SPTM pmap inosfmk/arm/pmap. - The arm64e kernel builds with the
BCM2837machine config, the non-SPTM pmap and Apple CPU counters disabled. - The iPadOS 27 kernelcache is an
MH_FILESETwith 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.