Skip to content

feat: add SPTM virtualization, trace macOS guest under hypervisor - #70

Merged
RyanTheTide merged 147 commits into
mainfrom
feat/sptm-hv
Nov 14, 2026
Merged

RyanTheTide merged 147 commits into
mainfrom
feat/sptm-hv

Conversation

@DjDeveloperr

@DjDeveloperr DjDeveloperr commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

aura can run macOS's own stock SPTM, TXM, the cL4 secure kernel with its exclaves, and XNU as a FEAT_NV2 guest at virtual EL2, with their guarded world (GXF/SPRR) running natively one level below aura's own GL2. It runs on four SoCs:

  • T8140 (J700): macOS 26.6.2 (25G83) boots to the desktop on all six cores, and it suspends to RAM and wakes as it does natively, while aura sees every power-management access it makes. That trace is where the sleep sequence for the Linux port came from.
  • T8132 (J713), from sptm_virt: boot the 25G83 guest on T8132 (J713) #109: 25G83 boots to a working desktop on all ten cores, and the sleep trace and go-mode sleep and wake work there too.
  • T8142 (J813), from sptm_virt: boot the macOS 27.0 guest on T8142 (J813) and trace its GPU bring-up #118: macOS 27.0 (26A428) boots through SPTM's checks to XNU userspace (its own NVMe, its APFS root mounted with the root hash validated, launchd started), and aura records macOS's GPU bring-up.
  • T6050 (J714s, M5 Pro): macOS 27.0 (26A428) boots to loginwindow on all 18 cores, with the guest on its own Wi-Fi and ssh into it (55230faa, 11-09). See the "M5 Pro" section.

It is a development tool: everything is built only with SPTM_VIRT=1 (which needs CHAINLOADING=1), and other builds carry none of it. That now includes aura's NV2 support. The series drops NV2's Linux host mode (aura-nv2), and NV2 no longer uses the resident monitor. docs/sptm-nv2-virt.md describes the design.

M5 Pro (T6050, J714s): macOS 27.0 (26A428)

6749cbb7..55230faa add what the hypervisor needed to boot macOS 27.0 on the M5 Pro, and 0ea1ebfb its sleep and wake (18 cores, MTE). Each one turned an M5 failure into progress. Each is keyed on the trap, the ADT, the boot core or the image, never on the chip. The work came from feat/m5-sptm-hv-20261108 and feat/m5-s2r-coproc-trace (aura-internal), where macOS reached loginwindow on 11-08 and ssh on 11-09.

Commit M5 symptom it fixed Keyed on Reaches other chips?
6749cbb7 smp: guest resets take the boot core's Aff2 for its core class XNU's start of cpu1 timed out: the M cores of clusters 0 and 1 have MPIDR Aff2 4, which the ADT's reg omits the boot core's own MPIDR and the ADT's cluster-type No. Only a boot core with Aff2 != 0 changes anything; T8140, T8132 and T8142 boot on Aff2 0 and keep the old rule. Only the SPTM path calls it.
701c90da run_guest_sptm: hide a port's SPMI controller, not its bus hiding the debug port hid nub-spmi-a0 and nub-spmi-a1, and every other port's controller with them the ADT path (a device on an SPMI bus) J700 25G83: hidden list unchanged
7f22dd7b run_guest_sptm: give TXM the guest's OS long version TXM refused 26A428's type13 cryptex cache, and launchd stopped in early boot. A tree that aura's Stage 1 booted has no love --os-long-version / AURA_OS_LONG_VERSION (Ap,OSLongVersion from the BuildIdentity); a live tree with another one is refused only with the option
5e960f94 sptm_virt: issue SPTM's trapped context instruction at GL2 SPTM 26A428 runs 0x00201340 | Rt on context switches; from the guest's GL1 it traps (EC 0x3f, ISS 0x20000 | Rt), and aura parked the CPU right after launchd's early boot the trap plus the exact word at ELR an SPTM that never issues it never takes the path
52f9b6c8 chainload: --reclaim-stage1-heap Stage 1's heap left 160 MiB under the 480 MiB cap; the low (MTE) carve-out was refused against its 192 MiB minimum. With the option it is 224 MiB the option only with the option
1f63c8f8 run_guest_sptm: XNU workarounds keyed on the kernelcache one release ships a kernelcache per SoC: the J813's 26A428 entry (PCIe/Wi-Fi hidden, RO-zone patch) matched the J714s's kernelcache by release string, which would have taken the M5's Wi-Fi away XNU_QUIRKS entries carry an instruction in the kernelcache's text (the RO-zone branch) as well as the release J813's kernelcache: the same entry as before (its branch is the fingerprint; not re-checked on a J813 image here). J714s: no entry.
f29a4eec run_guest_sptm: enter without waiting for a reply entering as a "reboot" waited for a boot banner, ate the guest's first console output and reopened the tty, which can drop KIS none every chip enters this way now
55230faa run_guest_sptm: AURA_KEEP_BOOT_VIDEO the M5 boots ran with iBoot's framebuffer handed to XNU the option; the framebuffer must lie in DRAM with a sane geometry only with the option

Left out on purpose:

  • ANS behind an ESP Stage 2. XNU's ANS2 starts only from the state Stage 1 leaves when it falls back to its own proxy ("controller off, RTKit quiesced"). Behind an ESP Stage 2's proxy window, ANS still runs Stage 1's live RTKit session, and XNU panics ("message 50000000000001 for unknown endpoint 2") or times out. That is a Stage 1/Stage 2 hand-off fix, not the hypervisor's. The M5 boots here go through Stage 1's proxy with the ESP's Stage 2 renamed for the session.
  • The window end behind a Stage 2. Stage 2 keeps the top 32 KiB, so cur_boot_args ends inside a 2 MiB block and SPTM panics "Frame has been left untyped during bootstrap". The trace lane aligned the end down to 2 MiB, which gets past that. But on Stage 1's path, the same alignment (iBoot's own end is only 1 MiB aligned there) gave "Kernel tag check fault": SPTM puts the MTE tag storage at the window's top. The generic fix is to end the window where iBoot's does, which the ADT records in region-id-24 and SPTM itself cross-checks. That is untested (it needs the ANS fix first), so it isn't here, nor is the 128 MiB low-heap minimum that path also needed.
  • The coprocessor trace hooks (COPROC/DCP_PKT) stay on the trace lane's branch: their node lists are by name, and MEM breaks SPTM on the M5.
  • CDC on T6050 (usb: explicit T6050 Stage 2 CDC handoff) and the M5 kboot handoffs (DCP, ATC, GPU, 16 I2C controllers): boot code, not the hypervisor; they are on the integration branch. The M5 HV runs use KIS.
  • The diagnostics on the M5 branch (a pre-guest probe of the context instruction, a per-CPU guarded-fault record, an NV2 control observer) are dropped. The probe was how the fix above was found.

Host results at 55230faa (clang 23.1.1, make clean per configuration):

  • CHAINLOADING=1 SPTM_VIRT=1: links, _file_vital_end 0x11b2b0 (limit 0x120000), no new warnings. CHAINLOADING=1: links, no sptm_virt/nv2 symbols, _file_vital_end 0x11ad58.
  • pytest tests/python: 614 passed, 12 skipped, 9 failed. The same 9 fail at bb85da6c on this host: test_m3_defaults_optout.py reads the host's installed updater, and test_loadobjs.py diffs this host's nm output.
  • Real images (test_sptm_virt_generic.py, test_sptm_virt_plan.py): J700 25G83 plans byte-identical with the old table, 11 patch sites, 8 port nodes hidden, sleep path on. J714s 26A428: 11 patch sites, MTE rewrite, CTRR stash 0x5f0, 4 debug ports, 54 port nodes hidden (56 at bb85da6c: the two SPMI buses), sleep path off (no soc_misc, as before). No J713 or J813 image set was on this host, so those rows were not re-run.

0ea1ebfb sptm_virt: s2r: a sleep that is the S2R timer's start, with a timed wake. The sleep path needed the PMGR's per-core self-disable block, which T6050's PMGR doesn't have, so the M5 got no sleep path at all.

  • One data entry, keyed on the PMGR's compatible, gives the register whose 32-bit write of 1 starts the S2R timer (T6050: reg 11 + 0x4000; the only chip fact). That write is the sleep commit.
  • Everything else comes from the ADT: the PS groups and the cores' and clusters' windows are traced, and the PMU RTC wake (AURA_S2R_WAKE_S) takes its PMU, registers and bits from the first SPMI child with info-rtc* properties. spmi_cmd_reg() is new in spmi.c.
  • AURA_S2R_GO_COUNT stops in the proxy at the commit after n wakes.
  • A PMGR without an entry keeps today's path unchanged (8 MiB ring, same rules; record bits 57:56 are set only for core numbers above 15).
  • Host check: on the live J714s ADT the timer is 0x288f04000; the J700's 25G83 tree finds its old blocks.
  • Hardware, J714s, 11-09 15:49-15:56 (runs/hv70-s2b). The same sleep code, applied on the ANS lane's ESP macOS image b4e3dcbc (aura-internal test/hv70-timer-sleep-esp-20261109, e840030f), kicked from Stage 2's window with no ESP writes, manifest: GO, FULL, COPROC, go_count 1, wake_s 30.
    • The PMU was found as nub-spmi0/spmi-abbeyL1 (SPMI 0xe, cmd 0x28a014210, RTC ctrl 0x2000 / compare 0x2008 / mask 0x200e), the same registers the M5 branch had hard-coded.
    • Timer-only GO hooked 406 pages with the commit at [0x288f04000].
    • macOS 26A428 reached loginwindow and ssh macOS-guest. After pmset sleepnow, cpu0 started the S2R timer, aura armed the RTC for +30 s, and the SoC went down.
    • WAKE #1 came 29 s later on the alarm, with XNU running again 2 ms after cpu0's reset. At macOS's next sleep commit aura stopped in the proxy, and the 23.5 MB ring was read.
    • No panic; the default boot came back.
    • This path does not use run_guest_sptm.py (the image plans in C), so the host's two new env switches were not exercised.

cdb21b6f nv2: forward the guest's writes to S3_1_C15_C7_4 to the hardware.

  • The register: XNU writes this unnamed Apple register from virtual EL2, and aura dropped the write as an unknown register.
  • The symptom: about half the M5 macOS-HV boots panicked ("ApplePMGR ... XNU ACC cluster rail-gating callback failed to respond in 30 seconds"). In a panic caught in aura's proxy, the core that never answered XNU's halt had such a dropped write as its last trap, 7 ms after its cluster's power-up.
  • The result: with the write forwarded, 5 of 5 loaded ESP-route boots passed on J714s, against about one in two before. Reads stay read-as-zero.
  • Other chips: not run on T8140, T8132 or T8142. The change only adds a case for one register encoding.

Hardware (J714s, macOS 26A428, image and proxyclient of 55230faa, clang build above), 11-09 11:12-11:18:

  • Path: Stage 1's own proxy with the ESP's Stage 2 renamed for the session (it syncs, remounts read-only, and re-checks the size and sha under the new name), chainload.py -r --reclaim-stage1-heap, then run_guest_sptm.py over KIS with AURA_KEEP_EXCLAVES=1 AURA_XNU_SERIAL=uart0 AURA_HIDE_DOCKCHANNEL=1 AURA_DEBUG_PORT=1 AURA_KEEP_BOOT_VIDEO=1 AURA_OS_LONG_VERSION=26.1.428.0.0,0 and the IPSW's T6050 exclave bundle, integrity catalog and trust cache.
  • Host side: heap reclaimed (top 0x1000f100000, Stage 1's high-water was 0x10011a1c000), aura's heap at 0x10010000000, the managed window [0x1001e000000, 0x10fca500000) ending where iBoot's does, 11 SPTM patch sites and the MTE rewrite, manifest love = 26.1.428.0.0,0, no XNU workaround matched, and 20 port nodes hidden for port 1 (nub-spmi-a0/hpm0 without its bus).
  • Guest: all 18 cores published with the MPIDRs they report (0x40000-0x40105, 0x10200-0x10205). The stage-2 tree was intact at XNU entry. All 18 CPUs issued SPTM's context instruction at GL2 (values 0x101-0x16f). loginwindow came up about 3 minutes into the session, with no park, panic or Debugger called.
  • ssh macOS-guest answered 6 s after loginwindow: macOS 27.0 26A428, xnu-13432.1.9~1/RELEASE_ARM64_T6050, Mac17,9, 18 CPUs, Apple M5 Pro, loginwindow and WindowServer running, Wi-Fi , sudo -n works.
  • Afterwards the default boot was restored: the SSD Linux was chain-booted over Stage 1's proxy, Stage 2 recomposed (3998253 B, sha 361be3c4…), and a plain reset reached the SSD Linux.
  • Not run on this code: T8140, T8132, T8142. The shared paths they take are unchanged (table above); the J700's host plan is byte-identical.

On top of aura#77

This branch now merges #77 (feat/ctxr-exec-window), which takes the monitor, PSCI, NV2 and PV-KVM out of the Linux boot. NV2 stays, built only with SPTM_VIRT=1. It already had its own EL2 setup and entry (commit 9), so the only monitor-era code it still needed was the ERET gate in _v_lower_sync. That gate moves to nv2_asm.S, and only SPTM_VIRT builds point the lower-EL vector at it. The SPTM path never used PV-KVM or the monitor's UNDEF reflection, so both are gone. On M4 an SPTM_VIRT build now sets only mmu_sprr, which is all aura's GL2 needs. It used to set apple_sysregs_unlocked too, which would have let deep_wfi(), cpu_sleep() and the hypervisor write the locked CYC_OVRD. A default build takes #77's boot path and has no NV2 or SPTM symbols. The J700 results below predate these changes.

T8132 and T8142: #109 and #118

Both are merged into this branch as real merges (b59f5b2f for #109 by @niteria, 9c7871d4 for #118 by @sithglan), with their commits as they were. Their descriptions have the details; in short:

  • sptm_virt: boot the 25G83 guest on T8132 (J713) #109: sptm_virt_requested() takes T8132; an SPTM patch table for sptm.t8132 (25G83, the T8140 build with its four AMCC patches 0xc4 later); the J713's debug port hidden from XNU. sptm_virt_s2r.c takes its SoC parts (PMGR reg indices, PMS, the AON wake status, the AMCC, the debug link's nodes) from a per-SoC table with T8140 and T8132 entries, and the wake and sleep records are paced over the DockChannel.
  • sptm_virt: boot the macOS 27.0 guest on T8142 (J813) and trace its GPU bring-up #118: the carve-out comes off the bottom of DRAM when SPTM's window ends in MTE tag storage; HCR_EL2.ATA for a guarded guest with MTE; SPTM's tag-storage base from its window (an 18-instruction reorder, refused unless all 18 match); exceptions the guest takes at virtual EL2 delivered at its own VBAR; per-SPTM-build constants (SPTM_BUILDS: patches, the XNU-entry GEXIT page offset, the CTRR stash offset), with the build picked by matching every patch site in the image; the SPTM diagnostic record; a GPU and PMP register trace (AURA_GPU_TRACE), a pre-XNU PC sampler (AURA_SAMPLE) and an opt-in XNU RO-zone patch (AURA_XNU_RO_RELAX), all off by default; exclaves from the IPSW's own members.

Conflicts: sptm_virt_requested() (now T8140, T8132 and T8142), sptm_virt_priv.h, and run_guest_sptm.py, where #109's T8132 patch table became a SPTM_BUILDS entry, so every chip's SPTM is recognised by its image. #109 carried a bot commit that deletes the agent policy copies; the merge keeps them, identical to main's.

Gating

Three follow-ups make the new behaviour depend on a SoC feature or the firmware rather than on the chip ID:

  • 656e35cc: the low carve-out and HCR_EL2.ATA follow FEAT_MTE2 (ID_AA64PFR1_EL1.MTE >= 2), through one helper. T8140 and T8132 have no MTE (their SPTM builds have no tag-storage code either), so they keep the top carve-out and no ATA.
  • 03212f5c (replaces a7c05c81's table rule): the sleep path takes its SoC blocks from the ADT, with no per-chip table. The PMGR reg list names none of them: ps-regs/ps-groups give the PS and always-on areas, and each block is the reg entry at its place in one of them. The PMS is the PMGR's 16 MiB entry, and the AMCC is the mcc entry amcc-reg-idx names, with amcc-count × dcs-count-per-amcc planes. The debug link is the USB port(s) whose PHY phandles the host records when it hides them, and the link domains the ADT flags 0x2 are reported off at sleep (T8132's ATC0_COMMON). A SoC whose ADT lacks a piece gets one line naming it and no sleep path. tests/python/test_sptm_virt_s2r_soc.py runs this C, with aura's ADT reader built for the host, on real ADTs: the J700 and J713 give exactly the old table. The J813 lacks only the clock pages (its clkgen entry is 0x3c000 long), and the J616c (T6041) has only the PS block, PMS and AMCC, so neither gets a sleep path, as before.
  • 754d5fef: the diagnostic record (boot_args revision 3 plus an SPTMDebug region) and the PCIe and Wi-Fi nodes hidden for 26A428's zalloc_ro_mut panic come from the SPTM_BUILDS entry, and are on for 26A428 on T8142 only. 25G83's __start uses a non-zero +0x480 pointer whatever the revision, so with the record on, the J700 would have booted a different handoff.

The rest of the per-chip and per-build code is gone too; see the next section.

What the merge changes on T8140:

  • The forwarded-exception delivery in nv2.c is shared code. On T8140 that path was never reached: it re-entered aura's forwarder forever, and the J700 boots. 25G83's SPTM and TXM contain no HVC instruction, so none of the guest's own HVCs can be taken for the forwarder's.
  • The sampler hook in exc_fiq returns at once unless AURA_SAMPLE is on, and the GPU hooks are off unless AURA_GPU_TRACE is.
  • New console lines: SPTM build 25G83, its GEXIT and CTRR stash offsets (the same values as before), and the CTRR stash base.
  • Otherwise nothing: with the real 25G83 images, the J700's plan (boot_args, edited ADT, regions, loads) is byte-identical to 8010bc70's.

Every M4 and later Mac, with no per-chip or per-board code

9a59a62c..f33fcd14 take the remaining per-chip, per-board and per-SPTM-build values from the hardware and the images:

  • Who can host it: FEAT_NV2 and GXF, not a chip list. The host refuses an SPTM it can't patch.
  • SPTM patches (proxyclient/aura/sptm_patch.py): each site is found by a short run of SPTM's own instructions, with PC-relative immediates and load offsets masked, and must match exactly once or the image is refused. The CTRR branch targets, the CTRR stash offset and the MTE tag-storage rewrite come from the code found. SPTM_BUILDS is gone. For the three builds it covered, the result is its own patches, stash offset and MTE rewrite.
  • XNU's entry: SPTM's first exit to its normal world at EL2h, not a per-build page offset.
  • Debug port: aura reports the port its CDC proxy uses; on KIS every USB-C port with an ATC PHY is hidden (AURA_DEBUG_PORT=<n> hides one). A port's nodes follow from its PHY through the ADT's phandles. For the J700 that is its old list exactly.
  • Reset guard: the exclave watchdog's ALARM is read at the guest's first access, not at setup, so a page the exclaves own is never read. Watchdog-node writes are passed through on the ADT's wdt-version >= 3 (J813) instead of the chip ID.
  • Sleep path: only the blocks that mark the sleep (soc_misc, aon_pst) are required; trace-only blocks the ADT lacks are skipped with a line.
  • Firmware workarounds: 26A428's hidden PCIe/Wi-Fi nodes and the opt-in RO-zone patch are keyed on the kernelcache's XNU release (XNU_QUIRKS). The SPTM diagnostic record is opt-in (AURA_SPTM_DIAG). The AMCC status words come from the ADT.

Host results (tests/python/test_sptm_virt_generic.py, public IPSW parts, proxy on KIS):

Image set Plan SPTM patch sites MTE rewrite Debug ports / nodes hidden Sleep path
J700 (T8140) 25G83 plans, byte-identical to before 11, the old table's none 1 / 8, the old list on
J700 26A428 plans 11 none 1 / 8 on
J713 (T8132) 25G83 plans 11, the old table's none 2 / 31 on, the old table with port 1
J713 26A428 plans 11 none 2 / 31 on
J813 (T8142) 25G83 plans 11 yes (25G83 shape) 2 / 31 on, clock pages not traced
J813 26A428 plans 11, the old table's yes, the old rewrite 2 / 31 on, clock pages not traced
J614s (T6040) 25G83, 26A428 plans 11 none 4 / 50 off: no soc_misc block
J616c (T6041) 25G83, 26A428 plans 11 none 4 / 50 off: no soc_misc block

"Plans" means the host finds and patches everything and lays out the boot. Only the J700, J713 and J813 have booted on hardware, and none of them on this code yet.

What's left, and why:

  • The sleep path on T6040/T6041: their ADT names neither the cores' self-disable block nor the S2R timer, and their PMGR layout differs, so finding them needs T6041's own layout.
  • The places of the PMGR blocks in the PS and always-on areas: data in one place (s2r_places), the M4 generation's layout.
  • Retimers have no phandle to their port, so they are paired with the PHY by index.
  • The CTXR CTL values aura answers with are constants, but the patch signature contains them, so a build with others is refused.
  • XNU_QUIRKS: a firmware bug's workaround, keyed on the release in one place.
  • On KIS aura can't tell which port carries the link, so every ATC port is hidden: the J713 loses its second port unless AURA_DEBUG_PORT=1 is set.
  • aura's shared boot code (usb.c, smp.c, startup.c) still has chip checks. That code isn't the hypervisor's, and every Linux boot runs it.

Main

8e218618 merges main (3bb35193, 1.0.0b9 and the M4 firmware gates). Only aura.ld and aura-raw.ld conflicted: main moved hv_vm/hv_sprr into .init as this branch did, which also puts sptm_virt*.o there.

The series

Rebased onto current main and reorganized; the bring-up instrumentation and one-off experiments are gone.

Preparation, independent of SPTM:

  1. aura.ld, aura-raw.ld: the hypervisor's stage-2 and SPRR code in the mostly empty .init slot. With clang, main's CHAINLOADING image no longer fits its 0x120000 file limit (.text crosses its next 64 KiB step; CI's gcc build is smaller); this makes it fit again, with or without SPTM_VIRT.
  2. usb_dwc3: CONTROL_STATUS3 for three-stage control transfers on high-speed ports (a real bug for any HS CDC gadget)
  3. usb: the T8140 CDC handoff may use ATC0 despite usb-device-disable
  4. dockchannel_uart: one timeout per stall, not per byte; a TX timeout setter
  5. rust: one codegen unit, for reproducible images
  6. hv: stage-2 block split and tree checksum; a persistent abort reports instead of looping
  7. hv_vuart: guest TX to a non-USB iodev
  8. hv_sprr: the emulated SPRR tables allocated on first use (110 KiB out of .bss)
  9. nv2: drop the Linux host mode (kboot's NV2 path, aura-nv2, NV2_BOOT, chosen.aura,nv2). NV2 gets its own EL2 setup and entry instead of the monitor's; its EL2 setup does not trap SMC, which was only there for the monitor's PSCI. monitor_reflect_undef becomes nv2_reflect_undef. PV-KVM and the monitor are otherwise unchanged.
  10. nv2: a mode for a guarded guest hypervisor

The virtualized SPTM, in the order it came up:

  1. build option, carve-out layout and the host's loader (planner plus host tests). NV2 (nv2.c, nv2_asm.S, exception.c's NV2 hooks and the lower-EL ERET gate) is built only with it. One of those hooks is the UNDEF reflection on the resident monitor's path, so other images report an OS trap the monitor does not service as an unhandled exception instead of reflecting it into the OS (aura#77 removes that path with the monitor).
  2. entering SPTM guarded at virtual EL2: the GL2 shadow, CTRR/CTXR, guarded ERET and GEXIT
  3. every core through SPTM's reset vector
  4. XNU's stage 2: vuart, reset guard, aura's memory unmapped
  5. the cL4 secure kernel as SPTM's guarded child (world switch, ExclaveCore bundle)
  6. run_guest_sptm.py, the host side, with a test that its imports resolve and it starts
  7. host configuration, and XNU backtraces

Suspend to RAM:

  1. keep the CDC debug link powered under macOS

  2. trace the sleep path, stopping before the commit

  3. let macOS sleep and wake (go mode), with the rules each failed attempt taught

  4. take the debug USB link again after a wake

  5. docs

Every commit builds, with CHAINLOADING=1 and (from 11) with CHAINLOADING=1 SPTM_VIRT=1, passes make format-check, and passes the host tests that exist at that point. A default image has no nv2 or sptm_virt symbols, and the NV2 and SPTM code references nothing of the monitor, PSCI or PV-KVM.

Testing

make CHAINLOADING=1 SPTM_VIRT=1
python3 proxyclient/tools/chainload.py -r build/aura.bin
PYTHONPATH=proxyclient python3 proxyclient/tools/run_guest_sptm.py \
    --sptm sptm.bin --txm txm.bin --xnu kernelcache.decompressed --trustcache iboot.tc

The desktop needs AURA_KEEP_EXCLAVES=1 AURA_EXCLAVE_FW=<extracted exclave firmware> AURA_XNU_SERIAL=uart0 AURA_HIDE_DOCKCHANNEL=1. A sleep test adds AURA_S2R_TRACE=1 AURA_S2R_GO=1 AURA_S2R_DROP_USB=1 AURA_KEEP_ERRH=1 AURA_AMCC_CLEAR=1, and AURA_S2R_USB_RETAKE=1 for the debug link after the wake; then pmset schedule wake and pmset sleepnow over ssh. Pass: the Mac wakes on the RTC alarm in the same boot, and once the link is back aura logs USB-RETAKE: controller up and WAKE #1: cpuN reset after the sleep commit, link back N ms after the reset.

Host tests: pytest tests/python/test_sptm_virt_carveout.py tests/python/test_sptm_virt_plan.py tests/python/test_exclave_bundle.py tests/python/test_run_guest_sptm.py. The last one imports everything the two host tools take from aura and runs each with --help. SPTM_VIRT_IMAGES=<dir> (sptm.bin, txm.bin, kernelcache*, dtree) adds a plan of real images, with and without the diagnostic record.

On J713 and J813 the commands are the same. #109 used AURA_XNU_SERIAL=uart0 AURA_HIDE_DOCKCHANNEL=1 and no exclaves; #118 can take the exclaves straight from the IPSW (AURA_EXCLAVE_BUNDLE, AURA_EXCLAVE_INTEGRITY, AURA_EXCLAVE_TRUSTCACHE).

The reorganized series was checked against the previous code on the host: the planner's output and the host's sequence of device operations are unchanged, apart from log-only reads and the renamed config call.

Tested at 8e218618 (and 776fd4c4, host Python only), on the host

clang 23.1.1, GNU make 4, rustc 1.98.1, after make clean for each configuration.

Configuration .text left before its next 64 KiB step .init left
RELEASE=1 CHAINLOADING=1 BUILTIN_LOGO=aurora 19804 B (main: 15828 B) 46304 B
RELEASE=1 CHAINLOADING=1 ESP_STAGE2=1 BUILTIN_LOGO=aurora 22124 B (main: 18148 B) 46308 B
RELEASE=1 CHAINLOADING=1 ESP_STAGE2=1 USE_CLANG=1 (cold kit) 22124 B (main: 18148 B) 46308 B
CHAINLOADING=1 18668 B (main: 14692 B) 46304 B
CHAINLOADING=1 SPTM_VIRT=1 6044 B (8010bc70: 6472 B) 10424 B (8010bc70: 14680 B)

Hardware results

  • J700, merged head (11-08): desktop and sleep-and-wake pass, after one host-tool fix the run found (below). That run predates 03212f5c..f33fcd14 (the ADT-driven sleep path and the generic host), which have not run on hardware. On the J700's images the host plan and patches are byte-identical to that run's, and on the J700's and J713's ADTs the sleep path finds exactly the table those runs used. The proxy ran over KIS: the CDC switch did not come up on the rig that day (cdc_schedule returned 0, no CDC device), so the USB drop and re-take, which need CDC, were not run.
    • Desktop, image of 8e218618 (the C is unchanged since) with host 776fd4c4: SPTM build 25G83 matched with all 11 patch sites, top carve-out, boot_args revision 2, six cores into SPTM with stage 2 intact on each, Finder 77 s after XNU entry, still up at 5 minutes. No reset trap, park, guard trip, forwarded-exception line or XNU panic.
    • Sleep and wake, two cycles in one boot (error handler hidden, AURA_S2R_QUIESCE=24): both woke on the RTC alarm to the desktop. WAKE #1 and #2 on cpu4, XNU running again 2 ms after each reset, and the other five cores re-entered SPTM each time.
    • The first desktop run on the merged head reset the Neo as SPTM entered cL4. sptm_virt: boot the macOS 27.0 guest on T8142 (J813) and trace its GPU bring-up #118's exclave_firmware() took the first ExclaveCore bundle in the extracted install, and the J700's 25G83 install has three (t6050, t8140, t8142), so cL4 started from T6050's image. 8010bc70 passed the same point on the same rig. 776fd4c4 picks the bundle by the ADT's chip ID; with exclaves, the J700's plan is byte-identical to 8010bc70's again.
  • J713: sptm_virt: boot the 25G83 guest on T8132 (J713) #109's results, on its own head: desktop after login, the sleep trace in stop mode, and a 27 s go-mode sleep woken by the keyboard, back to the desktop and network.
  • J813: sptm_virt: boot the macOS 27.0 guest on T8142 (J813) and trace its GPU bring-up #118's results, on its own head: SPTM's checks passed, XNU to userspace, and the GPU trace read back from the ring.
  • The gating follow-ups change only where the J813's decisions come from (the MTE field and the build entry instead of the chip ID). The host plan for the J813 is byte-identical. The one thing the host cannot check is that the J813 reads ID_AA64PFR1_EL1.MTE >= 2 at EL2, which sptm_virt: boot the macOS 27.0 guest on T8142 (J813) and trace its GPU bring-up #118's HCR_EL2.ATA gate already relied on. The next J813 run confirms it: run_guest_sptm.py's managed window from aura line starts 480 MiB into DRAM, with the carve-out below it.

J700, a2cfc9e9: desktop, SPTM entered with all five patches, XNU on all six cores (stage 2 intact on each), Finder after 82 s, still up at 5 minutes, no reset trap, park or XNU panic.

Sleep and wake ran on af7a7036. It had the UNDEF reflection in monitor.c as monitor_reflect_undef; a2cfc9e9 moves it into nv2.c as nv2_reflect_undef, which the sleep path does not use, and in the SPTM image that name is the only difference in the symbol table. On af7a7036:

  • Desktop: SPTM entered with all five patches, XNU on all six cores (stage 2 intact on each), Finder after 74 s, still up at 5 minutes, no reset trap, park or XNU panic.
  • Sleep and wake, two cycles in one boot (network wakes off): both woke on the RTC alarm to the desktop. After each wake the other five cores re-entered SPTM, the debug link came back (USB-RETAKE: controller up in 327 and 325 ms) and aura logged WAKE #1 and WAKE #2, 630 and 627 ms after the reset. XNU logged no panic.

09b82f70, before the NV2 changes in commits 9 and 11, passed the same two tests: Finder after 81 s, and two RTC wakes with the link back in 325 and 326 ms.

🤖 Generated with Claude Code

M5 Pro ESP split and dependency

The M5 Pro macOS additions are fast-forward commits on this branch. They add the ESP manifest loader, iBoot-window/MTE staging, ANS-to-XNU quiesce, optional capture hooks and the three observed NV2 register accesses. The newly qualified reads/additional registers are scoped to T6050. The old M5 fixes already reworked into this PR are preserved by content rather than replayed.

This requires the separate T6050 Linux/shared-storage series for the shared ANS power-cycle, RTKit/ASC, SART, PMGR/PCIe and boot-window helpers. These helpers are not duplicated as new macOS commits. The combined build's source heads/tree, configuration and artifact hashes are retained in the validation receipt. A plain image uses TRACE/WAKE/GO_COUNT=0; it does not exercise every optional hook set.

The combined ESP build retains the DCP buffer boundary assertion and places guest code in the existing executable read-only region. The target ESP partition must be provided explicitly; the bundle tools contain no development machine UUID or home path. The enrolled M5 Stage 1 did not consume the trial marker, so the validated entry route is a chainload from Stage 2's DebugUSB window, with no ESP writes.

Exact final-artifact ESP-to-macOS SSH validation: PASS on J714s, macOS 27.0 build 26A428. The guest reached SSH 21 seconds after chainload, with WindowServer/loginwindow running; SSH survived the second read 20 seconds later. The slot-start Linux current/prev set identities were restored unchanged. No ESP writes or sleep experiment ran. Tested combined source tree: 699dbbf7a99fba1cdf813deab046d17ab4122b16; bare ESP image SHA-256: 01d1fa29979e6669be2c7a773bdbee4150ac9ebb5eb64d410bb5c8eafa50dc90. The sleep lane separately observed two full native wakes on the equivalent plain T6050 register-forwarding path. Those results do not establish a universal wake fix: GPU-traced runs previously still failed, and Linux suspend remains under investigation.

This PR remains unmerged. The owner's Neo validation and explicit green light are still required.

Pending dependency: the separate T6050 Linux/shared-storage public main PR is not published yet. This head must remain unmerged until that dependency and the owner gates are resolved.

…init

With clang, a CHAINLOADING image no longer fits: .text ends at 0xb2e94, past its 64 KiB
step at 0xb0000, which moves .rodata and .data up by 64 KiB and puts .data past
_file_limit ("Code and data reach the DCP log buffer after stage 1!"). gcc's smaller
code still fits, so CI does not see it.

.init's 64 KiB slot holds 3 KiB of startup code. Put the two largest pieces of code that
only run when aura hosts a guest there, hv_vm (stage 2) and hv_sprr (SPRR emulation),
about 16 KiB: .text ends at 0xae310 again and .data at 0x100000.

Signed-off-by: Diljit Singh <hey@djdev.me>
…gh-speed ports

The status stage of a control transfer with a data stage (wLength != 0, such as every
GET_DESCRIPTOR) must be CONTROL_STATUS3; CONTROL_STATUS2 is only for a two-stage
transfer. The high-speed path armed STATUS2 unconditionally, so a CDC gadget on a
high-speed port stalled its first three-stage status stage and the host never sent
SET_CONFIGURATION. Track the transfer kind on both speeds.

Signed-off-by: Diljit Singh <hey@djdev.me>
J700's ATC0 usb-drd carries usb-device-disable, yet that port is the debug port. The
CDC handoff has already cold-reset its HPM and taken the carrier over, and asks for
device mode explicitly, so it bypasses the property for that one bring-up. Every
other bring-up still honours it.

Signed-off-by: Diljit Singh <hey@djdev.me>
A stalled FIFO cost the 1 s timeout for every byte of every line. After one byte has
timed out, drop the following ones at once while the FIFO stays full.

Add dockchannel_uart_set_tx_timeout() for a caller that prints from a running OS's
traps, where even a single 1 s wait freezes the OS.

Signed-off-by: Diljit Singh <hey@djdev.me>
The default release codegen-units=16 reorders functions from build to build, so two
builds of the same tree produce different images. One codegen unit makes the build
reproducible, which a layout-sensitive guest needs to compare one run with the next.

Signed-off-by: Diljit Singh <hey@djdev.me>
… abort

hv_pt_split_block() replaces an L2 block with L3 pages, for ranges the hardware refuses
to translate with a block. hv_pt_checksum() hashes the whole stage-2 tree, for a caller
that hands the tree to a guest and wants to know nothing changed it.

hv_handle_dabort() retried an abort on a mapped page forever; a fault that persists on
the same access now reports after a few retries. The retry state is per CPU.

Signed-off-by: Diljit Singh <hey@djdev.me>
Over KIS the proxy rides the DockChannel, not a DWC3 CDC pair. Mirror the guest's TX to
that iodev and keep RX off, as reading the shared channel would steal the proxy's framed
replies. With the proxy on CDC, also copy TX to DockChannel, so the guest's console can
be read there if the CDC link goes away.

Signed-off-by: Diljit Singh <hey@djdev.me>
The shadow cache and the write-protect hash (110 KiB) were in .bss in every build. On
T8140 aura runs at stage 1's base and .bss must end below the DCP __OS_LOG buffers iBoot
places after it. Allocate them when emulation is first enabled.

Signed-off-by: Diljit Singh <hey@djdev.me>
NV2 let Linux run at virtual EL2 under the resident monitor, for nested KVM (aura-nv2,
NV2_BOOT, chosen.aura,nv2). That mode goes: kboot's NV page and trace-ring setup, the
monitor's entry into it, the boot option and its ESP override, and PV-KVM's exclusion
of it. PV-KVM and the monitor itself are unchanged.

nv2.c keeps the virtual-EL2 machinery for its remaining user, the virtualized SPTM, and
no longer uses the monitor: it has its own EL2 setup and entry (nv2_el2_setup,
nv2_enter_el1h) instead of monitor_el2_setup and monitor_eret. Its EL2 setup does not
trap SMC, which existed for the monitor's PSCI: with no EL3 a guest's SMC is UNDEFINED,
as on the bare machine. monitor_reflect_undef becomes nv2_reflect_undef and keeps only its
plain-EL1 path; its virtual-EL2 path was for the Linux mode.

Signed-off-by: Diljit Singh <hey@djdev.me>
nv2_guarded is set for a guest hypervisor that runs its own GXF/SPRR world below EL2
(the stock SPTM). It reads its real ID registers, so HCR_EL2.TID3 stays clear.

For any NV2 guest: emulate the FEAT_XS nXS TLBI forms (CRn 9) as the CRn 8 ones, keep
AGTCNTHP_CTL from EL2 as a per-CPU shadow, and read APSTS_EL1 from the hardware, where
PAC is up; a guest hypervisor polls its bit 0 before it configures APCTL.

Signed-off-by: Diljit Singh <hey@djdev.me>
The first part of running macOS's stock SPTM, TXM, secure kernel and XNU as a FEAT_NV2
guest on T8140 (docs/sptm-nv2-virt.md). SPTM_VIRT=1 builds it in; it needs
CHAINLOADING=1, as the image must stay at stage 1's base, and other builds carry none of
it.

SPTM owns the managed-RAM window iBoot would hand it. aura's heap moves to a 512 MiB
carve-out at the window's top, below the fixed high-firmware regions, and SPTM's window
starts above everything aura and iBoot left low. The layout math is pure and tested on
the host.

The host lays out the images and the device tree (proxyclient/aura/sptm_virt_plan.py) and
calls sptm_virt_place, sptm_virt_load and sptm_virt_flush over the proxy; aura refuses a
boot_args that is not one or that would let SPTM manage aura's memory.

NV2 is built only with SPTM_VIRT too: nv2.c, nv2_asm.S, exception.c's NV2 hooks and
the lower-EL ERET gate in exception_asm.S, so other images carry none of it. One of those
hooks is nv2_reflect_undef on the resident monitor's path, so an OS trap the monitor does
not service is no longer reflected into the OS as an UNDEF in other images; aura reports
it as an unhandled exception.

The SPTM_VIRT objects' code goes in .init with the hypervisor's, so .text stays below its
next 64 KiB step.

Signed-off-by: Diljit Singh <hey@djdev.me>
SPTM's __start writes GL-only SPRR registers, which UNDEF at non-guarded EL1 and cannot
be trapped there. So aura brings up its own GL2 (SPRR, then GXF) before entry, and SPTM's
GENTER from virtual EL2 lands in GL1. What SPTM does there that needs GL2 traps to aura's
GL2 (sptm_virt_gl.c):

- GL2 register accesses, kept per CPU in a shadow; AMX_CTL_EL2 is applied.
- CTRR/CTXR: the real value is read and writes are dropped, except the bounds SPTM checks
  against its stash, which answer with SPTM's own values (stage 1 locked them for aura).
- Its guarded ERET, whose target is in the guest's GL1 bank (_GL12 from GL2).
- Its GEXIT to its own normal world, which physical GL1 cannot reach.

Until a core's first GEXIT into XNU its WFEs trap: SPTM's panic halt is `wfe; b .`,
which nothing would end under aura. aura reports it once and steps over.

On M4-class cores SPTM_VIRT builds set up SPRR/GXF (mmu_sprr) and read the error
registers; CYC_OVRD, which UNDEFs on parts without a sleep mode, is left alone.

Signed-off-by: Diljit Singh <hey@djdev.me>
Under the virtualized SPTM every core enters the guest through a hardware reset, as
natively: XNU starts a core with PMGR CPUSTART, and a core that power-gates in idle or
sleep comes back the same way. Its locked RVBAR lands in aura with the MMU off, on a
stack published per MPIDR; aura rebuilds the core's GL2 and EL2 state and enters SPTM's
reset vector at virtual EL2, and SPTM decides cold start or resume itself.

So before entry every ADT core gets its NV2 pages and GL stacks (gxf_prealloc), its
reset stack and an RVBAR that reaches aura (smp_prepare_guest_resets). While the guest
is live a core's reset goes to sptm_virt_cpu_reset, a would-be reboot parks the CPU
instead, the CPU part line is not printed, the guest's interrupts stay masked at EL2,
and DockChannel waits at most 20 ms for a full FIFO.

Signed-off-by: Diljit Singh <hey@djdev.me>
Each core arms it at its first GEXIT into XNU, after checking that nothing changed the
tree since setup; SPTM's own bring-up runs without it. It is an identity map of the low
2 TiB with a few pages trapped:

- uart0 is aura's vuart, mirrored to the proxy's iodev; XNU's console is moved there in
  the device tree, so its serial stack never binds the DockChannel that carries the proxy.
- The SoC watchdogs are guarded: a write that would let one reset the SoC is neutered,
  and a restart parks the core in aura's proxy instead of resetting the Mac.
- aura's image and carve-out are unmapped, so a stray guest access stops in aura with the
  guest's frame chain.
- Blocks over the CTRR-class ranges are mapped with pages, as those ranges refuse a block
  translation that overlaps them.

XNU touches iBoot's reserved low RAM below physBase; a fault there maps the page.

Signed-off-by: Diljit Singh <hey@djdev.me>
SPTM enters cL4 with a guarded ERET to EL1, and cL4 leaves by any exception it takes to
the level above, which aura delivers to SPTM's GL vector as the hardware would. An FIQ
while cL4 runs preempts it the same way, so aura's GL2 now takes FIQs.

cL4, and XNU's own VMs, share the one physical EL1 register file with the host. On real
hardware SPTM programs its child's copy of Apple's per-level registers through the
_EL12/_GL12 aliases while its own writes go to EL2's; here its own writes, lock bits
included, land on the copy the child runs on. So aura switches those registers with the
world (APCTL, the GXF and SPRR configuration, the PAC keys, VMSA_LOCK, AGTCNTRDIR,
AMX_CONFIG), from GL2 through the aliases, which can rewrite the locks. The child's EL1
regime comes from SPTM's VNCR page (nv2_guarded_child_enter). The child's view, and its
CNTKCTL, survive a core's warm reset.

The host lays cL4 out from the ExclaveCore bundle (proxyclient/aura/exclave_bundle.py).

Signed-off-by: Diljit Singh <hey@djdev.me>
run_guest_sptm.py plays iBoot's SPTM loader: it takes the window aura computed, lays out
the images and the device tree with sptm_virt_plan in the native layout (physBase at the
window's base, iBoot's data regions copied to the blob's tail), refuses to enter if
aura's .bss reaches a DCP __OS_LOG buffer, writes everything, patches the five checks in
SPTM's text that compare the hardware stage 1 locked with SPTM's own placement, and asks
aura to enter. Each patch checks the instruction it expects, so a different SPTM build is
refused instead of booting unpatched.

console_tail.py keeps reading a console, for example XNU's on the CDC vuart port. A host
test checks that both tools' aura imports resolve and that they start (--help).

Signed-off-by: Diljit Singh <hey@djdev.me>
sptm_virt_config() takes one flags word from the host before entry. The first flag,
SPTM_VIRT_XNU_BT, samples XNU's frame chain at a GEXIT into it, at most every 5 s per
core. Nothing XNU sees changes: SPTM preserves x29 and XNU's EL1 regime is loaded, so the
frames are read with AT S1E1R. It shows where a boot that stops making progress spins.

Signed-off-by: Diljit Singh <hey@djdev.me>
aura's debug link is hidden from XNU, but XNU's PMGR driver still lowers its power
domains (the ATC0 USB controller, its DART and PHY, and their ancestors) about a second
into its boot, and with the proxy on CDC the link drops. Hook those PS words in the
stage 2: a lowering write is not performed, and reads then report the state XNU asked
for, so its polls complete.

This adds the hooked-page table the sleep path uses (sptm_virt_s2r.c) and
pmgr_adt_collect_psregs(), which lists a node's PS words and all its ancestors'.

Signed-off-by: Diljit Singh <hey@djdev.me>
With SPTM_VIRT_S2R, pass-through stage-2 hooks on the power-management blocks record
every access macOS makes into an 8 MiB ring in aura's carve-out, with markers, and two of
them time the sleep: each core's self-disable in pmgr-soc-misc, and the boot core
starting the S2R timer in pmgr-aon-pst, the commit.

This mode stops in the proxy before the commit, which hands the SoC to the hardware,
with the whole entry sequence in the ring; each other core's last WFI is trapped and the
core parks there. SPTM_VIRT_S2R_COPROC also hooks the RTKit and exclave mailboxes. The
reset guard records into the same ring.

Signed-off-by: Diljit Singh <hey@djdev.me>
With SPTM_VIRT_S2R_GO the sleep goes through, as natively. What it takes, each rule
learned from a failed attempt:

- The reset guard lets macOS program its sleep-time reconfig watchdog (about 5 s, reset
  enabled), still catching a real restart.
- aura prints nothing from the first core's self-disable to the wake: output there delays
  the boot core's last steps past that watchdog.
- The console, the proxy and XNU's vuart move to the always-on DockChannel first: uart0
  and the CDC link are SoC-domain devices that are off at the wake.
- At the commit the debug link's domains get the states XNU asked for and the ATC0 port is
  powered off, as XNU would if it owned it, or its USB wake source wakes the SoC halfway.
  SPTM_VIRT_S2R_DROP_USB tears the gadget down first.
- With macOS's error handler hidden (Linux's position), an enabled and pending AMCC error
  at the commit wakes the SoC within 20 ms; sptm_virt_s2r_quiesce clears DSID_AGE_OUT
  (word 0 bit 25) and UNEXP_RT_HIT_DIR (word 1 bit 8) on all four planes before it.

The first core reset after the commit is the wake. aura marks it, logs the first guest
traps and hooked accesses, and with SPTM_VIRT_S2R_FULL (the high-volume blocks, which a
go-mode sleep otherwise leaves unhooked) prints the wake's MMIO record once XNU stops the
watchdog. The commit time is recorded before the write that starts the S2R timer.

Signed-off-by: Diljit Singh <hey@djdev.me>
s2r_release_kept took the CDC link down at the commit, and usb_cdc_link_start brings it
up again on the running macOS: the same code stage 1 runs, except it waits 300 ms in
fixed delays, and XNU must not lose a core for that long. So it runs as a coroutine on
its own stack: each GEXIT into XNU and each trapped console access may resume it for one
slice, and its waits (usb_cdc_wait_us, usb_cdc_poll32, plain delays in other builds)
switch back to the trap. Meanwhile XNU's console goes to a ring, drained once the host
has the port open. Once the link is up the coroutine polls the controller and prints the
wake record and, with the mailboxes hooked, their traffic around the sleep.

A value above 1 also drops and takes the link n seconds in with no sleep, which tests all
of this under a running macOS. The port controller is not touched: CC stays up across a
sleep, and hpm0 shares its SPMI controller with XNU's hpm1. A domain the running OS has
on keeps its word (pmgr_keep_configured).

Signed-off-by: Diljit Singh <hey@djdev.me>
One design document for the series: what runs where, the memory layout, the iBoot-to-SPTM
handoff, the guarded world, cores, cL4, XNU's stage 2, suspend to RAM with what it found
for a Linux port, and how to run it.

Signed-off-by: Diljit Singh <hey@djdev.me>
Take aura#77, which removes the resident EL2 monitor, PSCI, NV2 and
PV-KVM from the Linux boot and runs Linux at EL2 in the CTXR window.

Resolutions:
- monitor.c, pv_kvm.c: deleted, as in #77. This branch's NV2 already
  has its own EL2 setup and entry (nv2_el2_setup, nv2_enter_el1h) and
  used neither the monitor nor PV-KVM.
- nv2.c, nv2.h, nv2_asm.S: kept from this branch. They are built only
  with SPTM_VIRT=1.
- exception.c: #77, plus this branch's SPTM_VIRT hooks. The UNDEF
  reflection on the monitor's path goes, with monitor_active. The
  proxy's hvc #1 case is SPTM_VIRT-only as a whole.
- exception_asm.S: #77's, with no lower-EL ERET gate. Until a later
  commit puts the gate back for SPTM_VIRT, the guest's ERETs take
  nv2_eret's C path, which handles all of them.
- Makefile: #77's object list plus SPTM_VIRT. NV2_TRACE and
  NV2_TRACE_PRINT only mean something inside SPTM_VIRT.
- boot_options, payload.c, main.c, kboot.c, docs/boot-options.md and
  their tests: #77's. This branch only removed NV2 host mode from them,
  and #77 removes it along with PV-KVM.

Signed-off-by: Diljit Singh <hey@djdev.me>
RyanTheTide and others added 12 commits November 14, 2026 18:48
The AuractlDevice kext linked with no LC_BUILD_VERSION, and kmutil refuses
to load a kext that carries none. ld's -kext mode drops the platform load
command, so -mmacosx-version-min alone does not leave one in the bundle;
stamp it back in with vtool after the link. Also link with -nostdlib so the
kext does not pull in the host C++ runtime. KEXT_MIN (default 14.0) is the
lowest macOS the kext loads on, not the build SDK: keep it at or below the
target's version.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Nothing stopped a local process from IOServiceOpen()ing AuractlDevice
directly, which skips the auractl tool's own root check. From an open
connection it could arm stage-2 hooks, drain the trace ring, read aura's
console, and on a non-AURACTL aura panic the guest.

Require the opening task to hold administrator privilege in
AuractlUserClient::initWithTask (clientHasPrivilege with
kIOClientPrivilegeAdministrator), so the kext is no weaker than the tool.
This also makes the "needs root" note in entry_iokit.c accurate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
src/auractl_abi.h and tools/auractl/entry.h still said this tree carries
no guest-side code and that the only entry is `none`. The tree now ships
the IOKit entry (ENTRY=iokit) and the AuractlDevice kext, so reword both
to point at it. No code change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ctl_never() has no branch for the T6040/T6041 (J616s): they fall through
to the default and get the same EACCES as any unlisted chip. The old
comment called PEEK "wired" there, which overstated it. Reword to say
PEEK is not enabled yet on any chip without a confirmed never-read list,
and that enabling it means adding that list and a branch. Behaviour is
unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`make kext` produced no kmod_info symbol (Xcode generates it from the
"Generate kmod info" setting, which the hand-rolled build does not run).
kextload/kmutil refuse a kext without it: the bundle id, version and
start/stop entry points live there.

Add AuractlDevice/kmod_info.c in the standard IOKit-C++ form (real entry
points in libkmodc++, _realmain/_antimain NULL), wire it into KEXT_SRCS,
and bump Info.plist CFBundleVersion to match its version string. It is
written to have C linkage whether the C++ driver compiles it as C or C++.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Drop the "AURACTL HV object for the J616s" runbook from the tool README:
  it pointed at build paths and object names not in this repo, so nobody
  could follow it from here. Replace it with a short generic note that
  booting macOS under an AURACTL aura is the normal HV enrol flow, and
  make the surviving end-to-end example chip-agnostic.
- Refresh the "no guest-side code" / "only entry is none" wording in the
  intro and Build sections for the IOKit entry and the kext.
- Word the T6040/T6041 PEEK path as "not enabled yet" in both the doc and
  the README, matching the handler.
- Note that `kmutil load` cannot build an AuxKC under SPTM-virt (the
  BootKC is host-fed, measured on the J616s) and point at `kextload`,
  and record that `make kext` now stamps kmod_info.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
auractl: IOKit guest entry, decode.py, J616s runbook (draft)
The IOKit entry needs a kext, and under SPTM-virt a kext may not load: the
BootKC is fed by the host loader, so kmutil/kextload have no writable boot
kext collection to extend, and SIP may be on regardless. On the J616s both
hold, so `auractl status` could never see the ring.

Add a second transport into the same ABI and the same handler, needing no
guest kernel code at all. An unprivileged process writes its request's own
EL0 address, tagged in the top 16 bits (a macOS user VA is 47-bit), to the
debug-communications-channel register DBGDTR_EL0. aura traps every EL0/EL1
DCC access to EL2 with MDCR_EL2.TDCC (FEAT_FGT, present on the M-series),
sees the tag, and reads and runs the request through that process's own EL0
translation exactly as the hvc path does; the errno is read back from
DBGDTR_EL0 (tagged, so with no aura trap the tool reports ENODEV instead of
acting on stray debug-channel state).

For an EL0 access the EL1 control MDSCR_EL1.TDCC has priority over the EL2
controls, so aura forces the hardware MDSCR_EL1.TDCC clear at guest bring-up;
the guest's MDSCR_EL1 is VNCR-banked, so what it reads back is unchanged.
Other EL0/EL1 DCC registers are emulated RAZ/WI (MDCCSR_EL0 reads TXfull) so
a stray access never wedges.

aura side: refactor the hvc handler's request marshalling into a transport-
agnostic sptm_virt_ctl_call(req_va), add sptm_virt_ctl_dcc() for the trapped
DCC access (src/sptm_virt_ctl.c), set MDCR_EL2.TDCC in the L1 EL2 state and
decode the trap ahead of the EL0 reflection (src/nv2.c).

tool side: entry_dcc.c (`make ENTRY=dcc`), which needs no root; scope the
tool's root check to the kext entry. Docs and README updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…-siq-skip

chickens: keep iBoot's SIQ_CFG_EL1 on an M4 Pro/Max guest boot
readmem's KIS resync-and-retry -- for a chunk whose reply is cut short by a
dropped USB packet or the bridge dropping the device -- referenced
SerialException without importing it and called self._kis_reopen() /
self._kis_resync(), neither of which existed: the first SerialException raised
NameError and any other retry hit AttributeError, so the recovery never ran.

- Import SerialException from serial.serialutil.
- Define _kis_resync(): flush the serial buffers and re-establish the proxy
  sync point with a NOP (which drops a stale late reply); a vanished device
  raises SerialException for the caller to reopen, a NOP that merely times out
  is left for the next retry.
- Define _kis_reopen(): wait for the device node to reappear and reopen it at
  the same path and baud as __init__, so an in-flight transfer survives a USB
  re-enumeration; return False if it does not come back.
- Give writemem the same recovery: split the single write into _writemem_one()
  and wrap the per-1024-byte KIS chunks in the resync-retry loop. A memory write
  is idempotent, so without this one dropped packet anywhere in a multi-MiB
  image write (e.g. the BootKC) was fatal.

Non-KIS transfers are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
s2r_soc_from_adt() returns -1 when the ADT has no debug-link USB port, as
on a KIS/DockChannel proxy: there is no hidden USB port to keep alive across
a sleep. sptm_virt_s2r_setup() took that as "no trace at all", cleared
SPTM_VIRT_S2R and returned before allocating the ring, so auractl reported
NO RING and arm/read/mark returned ENODEV even though the catalogue resolved
and the guest could reach the handler over hvc.

The sleep path -- keeping the debug-link domains on, the capture hooks and
the commit rules -- genuinely needs that link. The record ring and the live
in-guest catalogue tracing do not: auractl arms named MMIO pages and records
their accesses into the ring with no sleep involved. Decouple them: when the
debug-link port is absent, still allocate the ring for live tracing while
leaving every sleep flag clear, so no wake or sleep code runs with a NULL
s2r_soc.

Factor the ring allocation (with its big->small fallback) into
s2r_ring_alloc() and reuse it on both paths. Guard s2r_hook()'s one s2r_soc
dereference so an armed-page access on the ring-only path takes the plain
record branch; every other s2r_soc user is a sleep/wake helper gated by
SPTM_VIRT_S2R, which stays clear here. The sleep machinery is unchanged when
a debug-link port is present.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
(cherry picked from commit 9ef9468)
@RyanTheTide

Copy link
Copy Markdown
Contributor

Public-text review of this branch:

  • No in-guest trace-control client or guest entry is present in this branch; that interface lands in the follow-on auractl work, not here.
  • No absolute host paths, addresses, or credentials in shipped source. The /Volumes/... paths in docs/macho-boot-object.md, docs/recovery-enroll.md, and tools/recovery/enroll-stage1.sh are standard macOS mount points used as examples/placeholders.
  • A few comments describe an internal capture configuration by name rather than describing the code — proxyclient/aura/esp_macos.py:38,44, src/sptm_virt_esp.c:6, tests/python/test_esp_macos.py:5 ("the trace lane's launch.sh / cp.env"). Suggest rewording to generic terms, e.g. "the capture run's configuration".
  • tests/python/test_t8140_ave_enable.py:16 names a contributor in a comment ("…Dj's unit type"); suggest a generic phrasing.

All comment-only; no functional change implied.

RyanTheTide and others added 13 commits November 14, 2026 22:53
The DCC transport reaches aura from any EL0 process with no kernel help, so
on its own it lets anyone in the guest arm hooks, record and read the trace.
Put it behind two independent controls, with no guest kernel code and no data
derived from Apple's binaries.

Off unless enabled at boot: aura arms MDCR_EL2.TDCC (and clears the guest's
MDSCR_EL1.TDCC) only when the boot flags carry SPTM_VIRT_CTL_DCC
(AURA_AURACTL_DCC for run_guest_sptm.py, --flag AURA_AURACTL_DCC for an ESP
bundle). With it clear the guest's DCC behaves as on bare metal and the
transport is absent. nv2.c reads the flag at guest bring-up (nv2_l1_mdcr).

A per-boot cookie for anything past the read-only status: the host passes a
random value to sptm_virt_ctl_set_cookie over the proxy, a self-booting ESP
bundle bakes it into the boot-args and aura reads it back from there
(sptm_virt_ctl_cookie_from_cmdline). Either way it lands in the guest's
boot-args, which only root can read (sysctl kern.bootargs). The tool reads it
and presents it through DBGDTRTX_EL0 just before each doorbell; aura latches
it per core, consumes it on the next doorbell, and refuses a gated command
with EPERM without it. INFO (status) stays open, so status works for any user
while arming and reading records need root. The hvc transports are unchanged:
their caller is already vetted by the guest kernel, so they always pass authed
and struct auractl_req keeps its layout and x0 semantics.

ctl_host gains a cookie-gate test (a call without the cookie refuses every
command past the status).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The macOS ESP stage 2 (SPTM_VIRT_ESP) boots via the macos= line and never
builds a Linux devicetree or hands off to a kernel. It is still chainloaded to
the base of stage 1, where the panel DCP's __OS_LOG buffer sits _file_limit
(0x120000) bytes in and the running DCP overwrites anything mapped there. With
the full kboot/devicetree/display/GPU-initdata/PCIe tree linked in, the vital
region ran ~48 KiB past that buffer, so the image only linked with the limit
raised onto the DCP buffer.

Gate the Linux boot entries (kboot_prepare_dt, kboot_boot) out under
SPTM_VIRT_ESP in the two places that reference them: payload.c's kernel handoff
and the proxy's P_KBOOT_BOOT / P_KBOOT_PREPARE_DT commands. The build already
compiles with -ffunction-sections/-fdata-sections and links with --gc-sections,
so dropping those references lets the linker discard the whole unreferenced
tree. The ESP vital region drops to 744016 B against the stock 0x120000 limit
(~425 KiB free) and the image links without raising _file_limit. The gated
entries become panics, so an ESP build that still reaches a Linux boot path
fails loudly rather than running code that is no longer linked in.

The change is entirely under #ifdef SPTM_VIRT_ESP, so every other build is
unchanged: with the macro unset the shipped aura.bin / aura.macho are byte-for-
byte identical (only the per-object DWARF line tables shift by the added lines).

Add an esp-stage2-size workflow that builds both configurations and prints the
ESP vital region against _file_limit, so a change that grows it back over the
DCP buffer is caught in review.

Assisted-by: LLM
Signed-off-by: Ryan Murray <ryan@aurorasilicon.org>
Adds a guest-side entry that reaches aura's control hvc with no kext, for
guests where loading one is not wanted: the host patches the guest
kernelcache's acct(2) syscall so that, past acct's own root check, the
kernel loads the caller's request address into x1, issues
`hvc #AURACTL_HVC_IMM` with the magic in w0, and returns through acct's
own errno epilogue. The tool (make ENTRY=xnu) then reaches aura by calling
acct() as root with its request block in place of the path.

acct(2) is a good host: root-only, otherwise unused on these guests, one
user pointer, and its epilogue already returns the errno in w0. A non-root
caller never reaches the patch (acct still sends it to EPERM); a root
caller that is not auractl passes a real path whose first word is not
AURACTL_REQ_MAGIC and gets EINVAL -- either way acct() behaves as before.

proxyclient/aura/auractl_xnu.py plans the patch from the kernelcache file
alone: it locates acct() through the syscall table's build-independent
fingerprint, reads which callee-saved register acct holds uap in and the
address of its errno epilogue, and builds every word it writes from named
AArch64 instruction fields -- it carries no kernelcache bytes. It fails
closed: any ambiguity (sysent not unique, root check not matched, a branch
into the patch window) raises rather than guess. It runs standalone to
dump the plan for a cache.

proxyclient/tools/run_guest_sptm.py applies the patch to the BootKC it
chainloads when AURA_XNU_ENTRY=1, verifying the five words it overwrites
against the file's before it writes.

tests/python/test_auractl_xnu.py pins the emitted ABI to src/auractl_abi.h,
decodes each patch word independently of the encoder that built it, and
checks the finder fails closed on non-Mach-O and truncated input. The full
plan against a real kernelcache runs when AURACTL_XNU_KC points at one, so
no kernelcache data lives in the tree.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
tools/auractl: XNU (acct) guest entry, no kext
…esync

proxyclient: fix and extend the KIS memory-transfer resync-retry
…virt-esp

sptm_virt_esp: compile the Linux kboot path out of the ESP stage 2
This reverts commit 25c5dfc, reversing
changes made to 276340b.

Signed-off-by: Diljit Singh <hey@djdev.me>
auractl: a kext-free DCC transport (same ABI, no kext/root/SIP)
sptm-virt: auractl, a paravirtual trace-control interface (draft)
Signed-off-by: Ryan Murray <81541646+RyanTheTide@users.noreply.github.com>
@RyanTheTide
RyanTheTide merged commit f6aad3a into main Nov 14, 2026
17 checks passed
m0d16l14n1 pushed a commit to m0d16l14n1/aura that referenced this pull request Nov 14, 2026
Since aurora-silicon#70, an ESP Stage 2 built with SPTM_VIRT=1 but without
SPTM_VIRT_ESP (USE_CLANG=1 BUILDSTD=1 CHAINLOADING=1 SPTM_VIRT=1
ESP_STAGE2=1 DEBUGUSB_PROXY=1) no longer links: _file_vital_end is at
0x13bcc8, 113864 B past _file_limit. .text crossed one 64 KiB step and
the read-only segment, which now also holds the virtualized SPTM's
code, crossed another. Moving code into .init no longer helps, as .init
and .text share their steps.

- Link the compressed boot logos past _file_vital_end again, with the
  fonts. c5c5b35 put them there; 21a2a83, from a tree whose limit
  still covered the whole file part, linked them as .rodata, so the
  *_48.o(.data) lines in aura-raw.ld stopped matching and 42 KiB of
  logos went back into the vital region. A logo the DCP overwrites
  fails its gzip CRC in fb.c and is left blank, as c5c5b35 intended.
  aura.ld (the Mach-O) keeps them in .rodata.
- Build the kboot_*.o handoff objects and the sptm_virt objects at -Oz,
  as kboot.o and sptm_virt_cl4.o already are, and aura's own Rust crate
  at opt-level "z", as ed25519-compact already is. All of it is setup
  or development code; sha2, which hashes each measured kernel, nv2.c
  and the dependencies keep their levels.
- Put sptm_virt_s2r.o's code in .text with the room that frees, so
  .text and the read-only segment each stay below their step. Both are
  in the one executable mapping, [_base, _rodata_end).

_file_limit is unchanged. With the flags above (clang 23, rustc 1.99,
cold build) _file_vital_end is now 0x11bcc0: 23608 B left in .text,
16120 B in .rodata and 17216 B of data room. The image is 64 KiB
smaller. A Stage 1 (RELEASE=1 CHAINLOADING=1 BUILTIN_LOGO=aurora) has
18424 B of headroom.

Signed-off-by: Diljit Singh <hey@djdev.me>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants