Snapintosh/docs/KERNEL-PATCHES.md

# Kernel patches

This document lists every change Snapintosh can make to the guest kernel's
code: what each patch changes, why it exists, how its sites are found and
checked, and what it was measured to do. It also lists monitor features that
are easy to mistake for kernel patches, and patches that were studied and
rejected.

The kernel is Apple's stock J700 kernelcache for macOS 27 build 26A428
(`com.apple.kernel` UUID `F9F468D7-1F50-354A-BECD-6BD6C1C834AD`). See
[../README.md](../README.md) for the project overview.

## Policy

The goal is to run stock kernels unmodified wherever possible. A trap cost is
fixed in the monitor first, and a kernel patch is considered only when:

- the trap is hot enough to matter in the trap census, and the monitor cannot
  make it cheap on its own;
- the patch sites are found by decoding instructions (an instruction pattern
  anchored on symbols, strings or operands), never by fixed address;
- the patch is opt-in: without its flag, the loaded image, page tables and
  parameters are byte-identical to a build without the patch code;
- the patch is admitted only for the reviewed kernel: the image digest must
  match a pinned value, every site must still hold its stock instruction, and
  the decoded site list must hash to a reviewed closure value;
- its effect is measured against the stock kernel under the same monitor.

The kernelcache file on disk is never rewritten. Each patch rewrites words in
the loader's in-memory copy (`probes/xnuboot.py`, `build()`), and the build
record lists the sites it changed and the closure hash. Every patch flag must be
given to every mode of one `tools/cycle.py` attempt (prepare, check and boot),
so the checked image is the booted image.

Boot-policy and signing questions are outside the scope of this document.

## Summary

| Patch | Define / flag | What it changes | Why | Measured effect |
| --- | --- | --- | --- | --- |
| SPTM call entry | `SNAP_SPTM_HVC_CALLS=1` (needs `SNAP_NATIVE_CALLS=1`), monitor `-DSNAP_SPTM_HVC_CALLS=1` | 348 SPTM call instructions in XNU become `HVC #0x5350` | Removes the undefined-instruction and vector detour of the stock call encodings; one monitor exit remains | About 32 ns less per SPTM call (about 239 to 207 ns, 13%) |
| System-register zeroing | `SNAP_KERNEL_SYSREG_ZERO=1`, `cycle.py installed-fresh --kernel-sysreg-zero` | 240 accesses to 18 registers the monitor answers with 0: reads become `MOVZ Xt,#0`, writes become `NOP` | The monitor already returns 0 and drops the writes; the patch removes the trap | About 44M fewer traps per 600 s, about 29% of all traps in the census |
| Reference-clear skip | `SNAP_KERNEL_REFMOD_SKIP=1`, `cycle.py installed-fresh --kernel-refmod-skip` | 2 page-aging reference clears become `NOP` | Each clear costs an SPTM page-table update and often a later Access-flag fault | Estimated 1.4 to 1.9M fewer SPTM updates per run and 0.25 to 0.9M fewer guest Access-flag faults |
| 4 KiB user pmaps | `SNAP_KERNEL_USER_4K=1`, `cycle.py installed-fresh --kernel-user-4k` | 4 branches: every process gets a 4 KiB user pmap, as with Apple's own 4K spawn switch | Lets the monitor's hardware-walk mode run XNU's own user tables instead of shadow copies | Estimated user-table lock hold about 967 s down to about 150 s per 30 min run (with `--user-hw-walk`) |
| Application AMX hide | `SNAP_HIDE_AMX=1`, `cycle.py installed-fresh --hide-amx` | 1 instruction: the AMX version bits are cleared from the published application capabilities | The A16 has no AMX unit; applications must not select AMX code paths | Compatibility, not speed: only capability bits 27 to 30 change |

The sections below give the details.

## SPTM call entry

**Define:** `SNAP_SPTM_HVC_CALLS=1` in the loader environment, which requires
`SNAP_NATIVE_CALLS=1`, plus the monitor define `-DSNAP_SPTM_HVC_CALLS=1`.

**What it changes.** XNU's private SPTM call instructions become
`HVC #0x5350`, one instruction for one instruction, at 348 sites. The stock
encodings reach the monitor through an undefined-instruction exception and a
vector detour; the `HVC` enters it directly. One monitor exit, the same
serialization and the same endpoint code remain, and the calling sequence
around each site is untouched.

**How sites are found.** `probes/nativecalls.py` (`patch_hvc_calls`) takes the
call sites from the native-call contract derived from the stock image, with a
complete-closure check. `tools/qualify-sptm-call-entry.py` checks all 348
sites, and a call-entry microbenchmark measured the saving on the A16.

**Where it runs.** `cycle.py bootstrap-smoke` and `cycle.py speed-test` build
with it (`tools/cycle_lib/bootstrap_smoke.py`, `tools/cycle_lib/speed_test.py`).
It is not used on the installed desktop route.

**Effect.** About 32 ns saved per SPTM call (239 ns to 207 ns, 13.4%).

## System-register zeroing

**Flag:** `cycle.py installed-fresh --kernel-sysreg-zero`
(`SNAP_KERNEL_SYSREG_ZERO=1`).

**What it changes.** Every `MRS Xt,<reg>` of the listed registers becomes
`MOVZ Xt,#0`; every `MSR <reg>,Xt`, and every `MRS` into `XZR`, becomes `NOP`.
The registers are the 18 that the monitor answers with 0 and whose writes it
drops: PMC0 to PMC9, PMCR0, UPMSR, GXF_STATUS_EL1, AMX_STATE_T_EL1 and four
Apple implementation-defined encodings (`S3_4_C15_C15_6`, `S3_4_C15_C10_4`,
`S3_1_C15_C1_5`, `S3_4_C15_C1_4`). The result is exactly what the monitor
already does, without the trap.

**Sites.** 240: 222 in `com.apple.kernel` and 18 in `AppleT8140CLPC`
(146 `MOVZ`, 94 `NOP`).

**How sites are found.** `probes/sysregzero.py` decodes every executable
`__text` word. Each site must still hold its stock word, the kernel digest must
be pinned, and the decoded set must equal the reviewed closure.

**Checks.** `tools/test-kernel-sysreg-zero.py`: only the site words change,
default builds are identical, and both monitor variants return 0 for every
listed register.

**Effect.** About 43.7M traps removed per 600 s, 29% of all traps in the census
run. Most come from the per-idle-iteration `cpc_hw_update` and from performance
counter reads on every context switch. In one control comparison, WindowServer's
share of time in `__ulock_wake` fell from about 18% to 0.3%. It has been part of
every installed desktop run since it was introduced.

## Reference-clear skip

**Flag:** `cycle.py installed-fresh --kernel-refmod-skip`
(`SNAP_KERNEL_REFMOD_SKIP=1`).

**What it changes.** XNU's page-aging reference clears,
`pmap_clear_refmod_options(pn, VM_MEM_REFERENCED, PMAP_OPTIONS_NOFLUSH, NULL)`,
are skipped: the `BL` to `phys_attribute_clear_with_flush_range` that follows
the four argument set-ups (`MOVZ W1,#0x40`, `MOVZ W2,#0x20`, `MOVZ X3,#0`,
`MOVZ X4,#0`) becomes `NOP`. Each such call cost one SPTM `UPDATE_DISJOINT`
(clear the Access flag). If the page was touched again, it also cost an
Access-flag fault and a second `UPDATE_DISJOINT`.

**Sites.** 2, both in `com.apple.kernel`: `vm_page_balance_inactive` (runs on
every active-queue insertion and inactive removal) and
`vm_fault_deactivate_behind`. The other 14 calls to the function are left alone.
Modify-bit clears (write protection), madvise, UPL, pageout and copy-on-write
paths are untouched.

**How sites are found.** `probes/refmodskip.py` identifies the callee as the
function that holds the only reference to each of its two
`phys_attribute_clear(...)` panic strings. A site is a `BL` to it after exactly
those four `MOVZ` instructions; no branch may land inside that window, and the
region may contain no indirect jump. Admission uses the digest pin and the
reviewed closure.

**Checks.** `tools/test-kernel-refmod-skip.py`: symbol and DWARF signature
checks against the Kernel Debug Kit, inline chains, an emulation of the skipped
call's entry (Access-flag clear only, no write protection), a caller-register
walk after the `NOP`, refusals, identical default builds, and composition with
the other patches.

**Effect.** Estimated from a 30 minute installed run: 1.4 to 1.9M fewer of
2.69M `UPDATE_DISJOINT` calls, about 30 to 43 s less of their 60.6 s token hold
and 190 to 250 s less of their 361 s lock wait, and 0.25 to 0.9M fewer guest
Access-flag faults. It has been part of every installed desktop run since it was
introduced.

**Cost.** Under memory pressure, `vm_pageout_scan` treats these pages as
referenced, so reclaim of them becomes first-in first-out instead of
second-chance.

## 4 KiB user pmaps

**Flag:** `cycle.py installed-fresh --kernel-user-4k`
(`SNAP_KERNEL_USER_4K=1`). It is used together with the monitor's
`--user-hw-walk` (`SNAP_USER_HW_WALK`).

**What it changes.** Every process is created as if it had been spawned with
Apple's own 4K testing switch (`psa_4k`, `_POSIX_SPAWN_FORCE_4K_PAGES`), so
every user pmap is SPTM format 1 (4 KiB tables, L0 root). Four branches change,
all in `com.apple.kernel`:

| Site | Source location (XNU) | Change |
| --- | --- | --- |
| Force flag in `load_machfile` | `mach_loader.c:781` | The spawn-attribute NULL test before the `psa_4k` test becomes an unconditional branch to the code that sets `PMAP_CREATE_FORCE_4K_PAGES` |
| Eligibility check in `load_machfile` | `mach_loader.c:1006` | The check that would refuse a forced-4K exec is branched past |
| Apple string in `exec_add_apple_strings` | `kern_exec.c:8165` | Same forced branch, so the process receives `vm_force_4k_pages=1` |
| Guard-object bucket in `vm_guard_object_find_space_anywhere` | `vm_map_store.c:1958` | A `B` becomes a `TBZ` on the page shift, so 4 KiB maps take the function's own fall-back exit |

`cambria_pagesize=4` is not needed; it only selects 4K for x86_64 processes.

The fourth site exists because of a real XNU limit. The guard-object allocator
buckets its slab by the bit length of the page-rounded size minus 14. In a
4 KiB map, a request of 4 KiB or less gives index -2, so the new chunk pointer
was written 16 bytes before the map's slab pair, inside the previous
`kalloc.1024` element ("element modified after free" panics). With the patch, a
4 KiB page shift returns the function's existing fall-back value (46), which its
only caller answers with the ordinary allocator; 16 KiB maps keep the stock
path.

**How sites are found.** `probes/user4k.py` matches the load / compare / test
sequence around the spawn-attribute fields and classifies each match by the
instruction at its branch target. The eligibility check is matched by
its position relative to the string it tests. The
guard-object site is matched by its own short sequence, and its fall-back must
be one of the function's own exits that returns the value in `X8`. Admission
uses the digest pin and the reviewed closure.

**Checks.** `tools/test-kernel-user-4k.py`: source file and line of each site
from the Kernel Debug Kit, before/after disassembly, forced paths never read the
absent spawn attributes, every exit of the eligibility check equals the new
target, the guard-object fall-back is one of the function's own exits, its
caller treats 46 as a fall-back, refusals, identical default builds, and
composition with the other patches.

**Effect.** On its own the patch is slower (see the rejected study below). With
`--user-hw-walk`, the hardware walks XNU's own user tables, and the monitor no
longer builds, caches or rebuilds shadow roots on `SWITCH_ROOT`. The estimate
from a 30 minute run is a user-table lock hold of about 967 s falling to about
150 s.

**History (October 2026).** The first hardware runs found, in order: a monitor
check that refused the first 4 KiB root switch; a copy-table compaction bug in
the monitor; the guard-object slab underflow above (fixed by the fourth site);
and a stage-2 fault caused by the SPTM model writing descriptors byte by byte.
After those fixes a full 30 minute desktop run completed with no faults, and
the patch has been on every installed desktop run since.

## Application AMX hide

**Flag:** `cycle.py installed-fresh --hide-amx` (`SNAP_HIDE_AMX=1`;
`tools/kc-load.py --hide-amx` for an offline image).

**Why.** The kernel panics at startup if `AMXIDR_EL1` reads as 0, so the
monitor gives it the compatibility value it needs. The kernel then publishes
an AMX version to applications in `_get_cpu_capabilities()` bits 27 to 30, and
libraries such as Accelerate may select AMX code paths. The Snapdragon X2 Elite
has no AMX unit, so those paths cannot run.

**What it changes.** One instruction in `commpage_populate`: the `ORR` that
merges the AMX version into the capability accumulator becomes an `AND` that
clears bits 27 to 30. The global capability value and its comm-page copies
(32-bit, 64-bit and the optional x86 alias) all receive the result. `AMXIDR`,
XNU's internal AMX version and every SME bit are unchanged; the patch does not
enable or advertise SME.

**How the site is found.** `tools/kc-load.py` (`hide_amx`) matches the
18-instruction publication sequence, resolves its three data addresses and
checks that they are distinct mapped data, that the shared load and store
offsets agree, and that the loaded words are still stock. All sites are checked
before any is written, and a second application is refused.

**Checks.** `tools/test-hide-amx.py` replays the patched and unpatched
publication sequence with all six AMX versions, several capability accumulators
(with and without SME and SME2 and unrelated bits) and with and without the x86
alias: only bits 27 to 30 change. It also checks identical default builds,
refusals, environment validation and the `installed-fresh` argument routing.

**Effect.** Applications see no AMX and take their non-AMX (NEON) paths. It is
used on installed desktop runs. A run without AMX crashes does not prove that
every application consults the capability bits before using AMX.

## Not kernel patches

These change no kernel instructions, even when their names say "kernel":

- **Monitor defines named `SNAP_KERNEL_*`**: `SNAP_KERNEL_PPERM_VARIANTS`,
  `SNAP_KERNEL_PPERM_FAST` (`--kernel-pperm-fast`), `SNAP_KERNEL_PPERM_REUSE`,
  `SNAP_KERNEL_VIEW_REUSE`, `SNAP_KERNEL_DIRTY_PUBLISH` and
  `SNAP_KERNEL_CLASS_PROOF` are monitor code. For example,
  `SNAP_KERNEL_PPERM_VARIANTS` keeps a second private copy of each CPU's kernel
  page tables and swaps to it on a permission flip; it touches page tables, not
  kernel code.
- **Monitor speed defines** such as `SNAP_ROOT_MISS_FAST`,
  `SNAP_UPDATE_DISJOINT_FAST`, `SNAP_ROOT_CACHE_WIDE`,
  `SNAP_UPDATE_CHECK_SPARSE`, `SNAP_FAST_TIMER_IRQ_CPU0` and the
  `ADRENO_IB_POLL_DIVISOR` override: monitor code only.
- **`--lean-traps [1|2]`** (`SNAP_LEAN_TRAPS`): at level 1, after a lock-free
  read of ESR, FAR or a performance counter, the monitor also emulates the
  adjacent read (XNU reads these in pairs), using the sealed kernel image; level
  2 uses fine-grained traps (FEAT_FGT) instead of `HCR_EL2.TVM`/`TRVM`, so
  `ESR_EL1`/`FAR_EL1` reads and `CONTEXTIDR_EL1` writes stop trapping.
- **`--class-proof-wide`** (`SNAP_CLASS_PROOF_WIDE`): the monitor's kernel
  page-class proof walks up to 61,440 tables instead of 8,192.
- **`--dart-wiredcnt`** (`SNAP_DART_WIREDCNT`): on each GPU unmap the monitor
  writes one XNU data word, lowering the 16-bit IOMMU-table count by the leaves
  it cleared, as `t8110dart_unmap` would. It locates `pmap_ref_iommu_table` by
  instruction pattern, decodes the globals it uses and checks every pointer; on
  any mismatch it writes nothing. Checked by `tools/test-dart-wiredcnt.py`.
- **`--panic-serve`** (`SNAP_PANIC_SERVE`): after XNU's panic entry the monitor
  keeps serving ordinary calls so the panic string is printed.
- **Pointer authentication** (`--native-pacga` and related monitor options) is
  handled entirely in the monitor and changes no kernel words.
- **Boot argument `-vm_compressor_wk_sw`** (installed route): XNU's own switch,
  not a patch. It makes the memory compressor use software WKdm instead of an
  Apple compression instruction the Snapdragon lacks, which otherwise stops the
  boot with an undefined-instruction exception in the compressor.
- **AuxKC colorimetry** (`tools/patch-auxkc-colorimetry.py`): one instruction in
  the project's own Adreno kext collection (the colour-element constant for
  sRGB). It changes the project's driver, not XNU, and the kext source now
  carries the same value.

## Proposed, not implemented

| Patch | What it would change | Expected effect | Status |
| --- | --- | --- | --- |
| `SNAP_KERNEL_USER_TIMEBASE` | One constant in `commpage_populate` so user `mach_absolute_time` reads `CNTVCTSS_EL0`, an architectural counter the monitor can serve quickly, instead of Apple's counter alias | About 2.3M user counter reads per run leave the slow path | Designed |
| `SNAP_KERNEL_NATIVE_COUNTER` | Apple counter aliases (about 1,060 sites) become the architectural counters, with a 19.2 MHz guest timebase (watchdog and microsecond constants, device-tree frequencies) | About 21% of traps in the census run; hundreds of millions of counter traps on a long installed run | Deferred: needs the timebase change; medium to high risk |

The A16 cannot scale the counter in hardware (`ID_AA64MMFR0_EL1.ECV` reports
offsets only), so there is no monitor-only route to untrapped 24 MHz counter
reads.

## Studied and rejected

- **4 KiB user pmaps under the shadow monitor.** Without the hardware walk, the
  4K patch is slower: the monitor shadows 4 KiB roots just like 16 KiB ones, two
  of its optimisations (roots cached at creation, shared-region linking) work
  only for 16 KiB, user page-map calls grow up to 4 times, and each root rebuild
  walks about 3,533 shared tables instead of 221. The estimate was 60 to 150%
  more lock hold at equal work. The patch exists only for the hardware-walk
  mode. The same study found the better lever of that time: a full 64-slot root
  cache was evicting and rebuilding tens of thousands of roots per run.
- **Skipping modify-bit write protection.** Most user `UPDATE_DISJOINT` records
  are an Access-flag clear plus write protection followed by a write fault. They
  come from `MADV_FREE`/`MADV_FREE_REUSABLE`, UPL commits and the pageout
  cleaning paths. Skipping them would lose dirty tracking (a written page could
  be discarded, or a file page could stay clean after a write); skipping the
  whole call would stop the "reusable" footprint ledger that jetsam limits rely
  on. Left as is.
- **The other reference-only clears** (`pmap_clear_reference` in
  `vm_page_deactivate_internal`, `vm_pageout_scan` and
  `vm_object_cache_evict`). They are the same kind of aging hint but did not
  appear in the recorded update traces, so they are left alone until there is
  evidence that they matter.