SPTM - The Last Bits
November 19, 2025
By Jonathan Levin and the DFFenders
Welcome Back
It's been a while since we last blogged. Let's catch up quickly. Almost two years later, there is still a dearth of information about SPTM, TXM and Exclaves. Until recently, the entire Internet only contained two posts by Random Augustine and our own. As recently as October 10th, 2025, this changed with an academic thesis in ArXiv by Steffin & Classen. As befitting a Master's thesis, the work provides great detail on SPTM and Exclaves, though leaves the discussion of TXM wanting. DFF's own Jonathan Levin gave a detailed talk at OBTSv8 about XNU's restructuring as well. The interested reader is encouraged to view both the above resources, before continuing further.
One key observation by said thesis is that Apple provided surprisingly good documentation of SPTM in the headers of the Kernel.framework. Normally, these framework headers are just derived from those of XNU. In this case, however, two key headers provide not only APIs, enumerations and other constants, but also verbose commentary explaining how the components work and interact. Much of the header contents corroborate and affirm our earlier observations - while even more shed new light as to parts we have yet to explore.
This post aims to complement the abovementioned thesis, recap the key points of our previous three blog posts, and broaden the discussion so as to finally fill in the full picture of SPTM.
The Story So Far
If you haven't read our previous blog post and the one that started our exploration into the SPTM images, now's a good time to do so. Let's summarize what we've ascertained thus far:
SPTM Initialization
SPTM starts at its
LC_MAIN, which is also the only exported symbol,__start.
This entry point sets up the initial
VBAR_GL1, and other steps of initialization we have yet to look into, before returning into_sptm_init._sptm_initdoes most of the initialization. We managed to symbolicate nearly all functions, based on their arguments, or their panicky messages:
The _sptm _args
SPTM is initialized with a combination of device tree entries. Additionally, an _sptm_boot_args structure is used. This structure is shared with XNU, so xn00ping around a device revealed its rough layout. It was not until Jonathan read the Steffin & Classen article and we realized the full layout is given in Kernel.framework's sptm_xnu.h. This makes it easy to not just dump, but also decipher the values:
From the above we can see this SPTM dump is from a device without exclaves (those only appeared in the A17), since sk_bootstrapped is 0.
There is also a library - libsptm - which is linked into XNU and SPTM itself, but its sources are not available. Nonetheless, the headers show the layout of the libsptm_state_t structure, which is the sptm_args_t. Xn00ping around in iOS 19 ("26"), this is in its version 9, and looks like this:
SPTM also keeps a debug header, whose layout can be seen from sptm_common.h. This shows where SPTM, TXM and the KernelCache have been loaded:
Virtual ←→ Physical Address Translation
A key part of virtual memory management is translating the virtual address to a physical address and vice versa. Traditionally, the kernel would do that by implementing vtop(…) and ptov(…). With SPTM taking over, the implementation changes.
ptov
XNU's phystokv calls sptm_phystokv. The function is not part of the open sources (since it's part of the closed source libsptm, but lends itself to disassembly easily, especially in the symbolicated kernel.development.t8142 from the macOS KDK_26.2_25C5031i.kdk (which also contains nice MTE insights we should cover in some future blog post).
Xn00ping around the raw memory dump corroborates the code disassembly:
And further trying Xn00p's ptov dumps the table in a more readable format:
vtop
XNU's kvtophys(vaddr) similarly calls sptm_kvtophys(vaddr, &paddr), which is again closed source. Disassembly here is similar, with checks into the libsptm_state_t's first_papt and last_papt, with a call to _sptm_ml_kvtop for the "Machine Layer"'s fallback - the processor's AT (address translation) instruction:
Page Retypings
Recall that a key functionality of SPTM is physical page retyping...
Steffin & Classen detailed page typing in great depth (particularly in 5.7 and appendices A.11 through A.14), so there is little more to add here. We briefly examine another aspect of the page typing code here, namely symbolication.
Looking through the disassembly of _sptm_retype, we spot a reference to __DATA_CONST.__const, at 0xfffffff02701dbe0. This appears to be a structure of 8 8-byte entries, with two of them being function pointers. Some of the entries are symbolicated, as ...page_type.._retype_in or ...page_type.._retype_out.
We can find the list of SPTM page types in __DATA_CONST through _type_id_to_string, or simply by its first entry, "SPTM_UNTYPED":
This further shows that the very partial symbols match those of the page types, giving us effectively the entire table. Two repeating functions in the structure (_func_0xfffffff0270d79d4 and _func_0xfffffff0270d79dc) are null functions (BTI c/RET), probably for pages which don't require any special handling during retyping. There are also cases wherein there is no retype in or out function for a given page type.
Another important addition to page retyping is MTE tag storage. Apple went to great lengths to hide their plans for MTE/MIE, so only the A19 IPSWs (iPhone18,4 and higher) contain MTE-enabled images. SPTM defines a new type for tag storage.
All three domains - XNU, TXM and SK - call on SPTM provided endpoints for page retyping. For XNU, this is endpoint #1, for TXM - endpoint #3, and likewise for SK.
The _dispatch_state_machine
The dispatch_state_machine is called from multiple points in SPTM code. True to its name, it indeed implements a state machine, which Steffin & Classen's paper illustrates. The paper leaves out a few of the specifics of state transitions, however, which can be further analyzed and deduced, as follows here.
State Machine Events
State transitions are triggered by 'events'. There are presently (iOS 26) 15 event types, which can be translated to human readable text through event_type_to_string (@0xfffffff0270dbf38), which uses a table in __DATA_CONST.__const:
The 'event' is supplied in X0. Isolating calls to _dispatch_state_machine and disassembling around them we see:
As the above shows, the event code is loaded into X0, with the Link Register (a.k.a. X30) explicitly set so as to return to, in a tail-call like manner. The return address, however, is always either a breakpoint (BRK #1) or a "dead" loop (quite literally, loading 0xdead into X0 and entering an idle loop of WFE). This means that the state machine is expected to never actually return to this value.
The event table (which was likely not available in the version of SPTM reverse engineered by Steffin & Classen) makes it far easier to figure out routines. This is how, for example, we could name fffffff0270990e0 is _bootstrap TXM (With event #0. Similarly, func_0xfffffff0270991e0 was renamed by us to be bootstrap_sk, since it uses event id #1:
As another example, EVENT_CONTEXT_SAVED is called when the code from TXM is 0xff00000000, meaning that this value (specifically, 255), is used to save context. Similarly, 0xfe00000000 is for panicking.State Machine States
The second string format specifier ("%s") in the panic string indicates a state name, and so we can guess that 0xfffffff0270dbeec will translate the state number to a string. Looking through the function reveals its name is indeed _state_to_string, and further shows a state name table used for lookups:
And the state table is readily dumpable:
SPTM provides no interface for obtaining the state, which is held in TLS (through TPIDR_GL2). Events cause state transitions subject to strict verification.
State Machine Actions
Acting on an event involves performing some action. The state machine actions are in a table (at fffffff02701a2b8. This is a table spanning 11,040 bytes (in our SPTM, from 0x...2701a2b8 to 0x...2701cdd8), comprised of 23 480-byte structures - that is, one 480 byte structure for every state type. 480 divided by 15 leaving 32-bit entries for every event type. For each entry, the next state is at +0x0 and the action - a function pointer - at +0x08. In other words, this is a two-dimensional array indexed by (event, state).
Many of these table entries are all zeros, which constitute invalid transitions. For example, EVENT_BOOTSTRAP_TXM and EVENT_BOOTSTRAP_SK are only possible in state 0. Using the event codes allows us to further symbolicate their corresponding actions, as shown in the annotations above.
State actions do not return. This is made clear from their disassembly, which has a breakpoint (BRK #1 following it. For example, the two above:
Since the breakpoint cannot be reached, it means the "actual" actions cannot return, despite being called (using BL), instead of being branched to. Further inspection reveals one of two possibilities here:
The actions may end with an
ERETinstruction - an Exception Return, which drop into a lower GL (in the same manner as the instruction does a lower EL), but to the address ofELR_GL1. This pattern is used when returning from SPTM into TXM or SK (i.e. other GL-components, thus remaining in Guarded Mode), or when starting them for the first time.
Alternatively, they end with a GEXIT, which exits Guarded Mode - also returning to the value specified by ELR_GL1, which will hold the address following the GENTER. In both cases, ELR_GL1 may be explicitly overridden by SPTM. The use of many 0xdead/WFE loops suggests that these are different state specifiers for debugging.
If we assume this is responsible for bootstrapping XNU (since it is called from ffffff0270b40f8 right after a serial print out), then this loads an address from 0xfffffff027090720 - which is likely XNU's entry point - into ELR_GL1 (through X4), before setting up the saved program status register and calling GEXIT.
Domain Traversals
We already discussed that SPTM occupies GL2, with XNU in the unguarded domain, TXM in GL0, and SK in GL1. TXM uses a supervisor call (SVC) and SK uses a hypervisor call (HVC) to gate into SPTM. Those are handled by VBAR_GL2, which is analogous to ARMv8 exception handling. That is, at VBAR_GL2 + 0x400 is a synchronous error handler, which checks bits #26-31 of the Exception Syndrome Register (ESR_GLx).
XNU is in the unguarded domain, so it uses the specialized GENTER instruction. What we know now is that this is equivalent not only to entering guarded mode, but also to jumping to a pre-determined entry point in the IMPLEMENTATION DEFINED MSR of S3_6_C15_C8_2. Jonathan's disarm(j) dubs this register AAPL_GENTER_ADDR, along with its neighbor (S3_6_C15_C8_2), which is AAPL_GENTER_ERROR since it is set to a routine which halts. This usage can be seen in SPTM's disassembly:
After setting the register, GENTER is invoked to actually effectuate the guarded entry. The code in _initial_genter sets up a couple of other registers. Somewhere down the initialization we hit the "Final GENTER Setup":
Behind the scenes of GENTER (0xfffffff027098524)
As you may recall, GENTER takes a 5-bit immediate. Normally this is #0, but there are (presently) some five values defined. We had our educated guesses from the disassembly of SPTM. Disassembling from the address of AAPL_GENTER_ADDR:
GENTER #0
We can now follow the full flow of a GENTER #0. Recall (from our previous post) that X16 gets loaded with a selector value. Thanks to the Kernel.framework's sptm_common.h we see that the value is encoded thusly:
Given that GENTER jumps to AAPL_GENTER_ADDR - This lands us at 0xfffffff027098524, which then branches to our label of genter_0 - 0xfffffff027098a20. The code we find there checks the TPIDR_GL2 register, which holds the TLS.
There is a validation that a value there is 0 (else halting), after which register arguments X0-X7 are saved. The value is then checked (twice) to be not higher than 1 (else halting), eventually getting to 0xfffffff027098a6c. SPSR_GL1, SP_EL0 and ELR_GL1 are saved, X16 (the selector) is moved to X0, and control is transferred to genter_dispatch_entry, setting the return address (LR) to a dead loop.
; ; Get TLS, halting if a value was previously set at [TLS]+56 ; fffffff027098a20 d53efb28 MRS X8, TPIDR_GL2 ; X8 = TPIDR_GL2 fffffff027098a24 91114108 ADD X8, X8, #1104 ; X8 = X8 + 0x450 = 0x450 -- ! fffffff027098a28 f9401d09 LDRi X9, [X8, #56] ; ?9 = *(0x450 (55) + 0x38).. = 0x0! fffffff027098a2c f100013f CMPi X9, #0 ; fffffff027098a30 54000001 B.NE 0xfffffff027098a30 ; (no symbol for 0xfffffff027098a30) ; ; Store all arguments (X0-X7) at [TLS]+64 through [TLS]+128 ; fffffff027098a34 91010109 ADD X9, X8, #64 ; X9 = X8 + 0x40 = 0x40 -- ! fffffff027098a38 a9000520 STP X0, X1, [X9] ; *(X9) = [X0, X1] fffffff027098a3c a9010d22 STP X2, X3, [X9, #16] ; *[? +16] = [X2, X3] fffffff027098a40 a9021524 STP X4, X5, [X9, #32] ; *[? +32] = [X4, X5] fffffff027098a44 a9031d26 STP X6, X7, [X9, #48] ; *[? +48] = [X6, X7] ; ; Sanity: check (twice) that [TLS]+56 is not set ; fffffff027098a48 f9401d0a LDRi X10, [X8, #56] ; (Value of R8 unknown) fffffff027098a4c f100055f CMPi X10, #1 ; fffffff027098a50 54000008 B.HI 0xfffffff027098a50 ; (no symbol for 0xfffffff027098a50) fffffff027098a54 f100055f CMPi X10, #1 ; fffffff027098a58 54000008 B.HI 0xfffffff027098a58 ; (no symbol for 0xfffffff027098a58) fffffff027098a5c 54000060 B.EQ 0xfffffff027098a68 ; (no symbol for 0xfffffff027098a68) fffffff027098a60 91020109 ADD X9, X8, #128 ; X9 = X8 + 0x80 = 0x80 -- ! fffffff027098a64 14000002 B 0xfffffff027098a6c ; (no symbol for 0xfffffff027098a6c) fffffff027098a68 9104e109 ADD X9, X8, #312 ; X9 = X8 + 0x138 = 0x138 -- ! ; ; Save other register context at either [TLS]+128 or [TLS]+312 ; fffffff027098a6c a9005133 STP X19, X20, [X9] ; *(X9) = [X19, X20] fffffff027098a70 a9015935 STP X21, X22, [X9, #16] ; *[? +16] = [X21, X22] fffffff027098a74 a9026137 STP X23, X24, [X9, #32] ; *[? +32] = [X23, X24] fffffff027098a78 a9036939 STP X25, X26, [X9, #48] ; *[? +48] = [X25, X26] fffffff027098a7c a904713b STP X27, X28, [X9, #64] ; *[? +64] = [X27, X28] fffffff027098a80 a909793d STP X29, X30, [X9, #144] ; *[? +144] = [X29, X30] fffffff027098a84 6d052528 STP D8, D9, [X9, #80] ; *[? +80] = [X8, X9] fffffff027098a88 6d062d2a STP D10, D11, [X9, #96] ; *[? +96] = [X10, X11] fffffff027098a8c 6d07352c STP D12, D13, [X9, #112] ; *[? +112] = [X12, X13] fffffff027098a90 6d083d2e STP D14, D15, [X9, #128] ; *[? +128] = [X14, X15] ; ; Flag (set) TLS + 56 ; fffffff027098a94 9100054a ADD X10, X10, #1 ; X10 = X10 + 0x1 = 0x1 -- ! fffffff027098a98 f9001d0a STRi X10, [X8, #56] ; *0x38 = 0x1 ; ; Save SPSR_GL1, ELR_GL1... ; fffffff027098a9c d53efa6a MRS X10, SPSR_GL1 ; X10 = SPSR_GL1 fffffff027098aa0 f900592a STRi X10, [X9, #176] ; *0x1e8 = 0x0 fffffff027098aa4 d538410a MRS X10, SP_EL0 ; X10 = SP_EL0 fffffff027098aa8 f900512a STRi X10, [X9, #160] ; *0x1d8 = 0x0 fffffff027098aac d53efaca MRS X10, ELR_GL1 ; X10 = ELR_GL1 fffffff027098ab0 f900552a STRi X10, [X9, #168] ; *0x1e0 = 0x0 fffffff027098ab4 f9401109 LDRi X9, [X8, #32] ; (Value of R8 unknown) fffffff027098ab8 9100013f MOVr X31, X9 ; SP = X9 (0x138 - (null).. <<) fffffff027098abc a9bf7bfd STP X29, X30, [X31, #-16]! ; SP -= 16; *[SP] = [X29, X30] fffffff027098ac0 910003fd MOVr X29, X31 ; FP = SP fffffff027098ac4 aa1003e0 MOVr X0, X16 ; X0 = X16 (0x0 - (null).. <<) ; ; Jump to genter_dispatch_entry - Link register will point to dead_loop ; fffffff027098ac8 1000005e ADR X30, 0xfffffff027098ad0 ; LR = _dead_loop: fffffff027098acc 14010e0d B 0xfffffff0270dc300 ; _genter_dispatch_entry _dead_loop: fffffff027098ad0 d29bd5a0 MOVZ X0, #57005 ; X0 = 0xdead fffffff027098ad4 d503205f WFE ; fffffff027098ad8 17ffffff B 0xfffffff027098ad4 ; (no symbol for 0xfffffff027098ad4)
Steffin & Classen present a rough decompilation of genter_dispatch_entry using IDA or Ghidra, but the assembly is straightforward:
We'll handle _dispatch_state_machine next, but not before dealing with the other GENTER immediates.
GENTER #1, #2, and #3 (or - To There and Back Again)
A particularly interesting domain traversal happens when servicing interrupts. In XNU's sources we see:
And, in locore.s:
Neither of the sptm_... prefixed symbols nor the ..._resume suffixed symbols are in the sources, but given that SPTM_GENTER_TXM_RESUME and SPTM_GENTER_SK_RESUME are GENTER immediates #2 and #3 we can work back from the disassembly:
which matches the assembly, and reveals the #defines of TH_TXM_THREAD_STACK, TH_EXCLAVES_INTSTATE and TH_EXCLAVES_EXECUTION:
Since 0xfffffe000825bfb0 here must be xnu_return_to_gl2, we can look for where it is used as an argument. Even without analyzing XNU, the location pops up clearly:
Meaning 0xffffffe0008adc4e8 is sptm_xnu_register_exc_handler. This, too, makes perfect sense, because the function is an SPTM call:
Endpoint 18 here is indeed verified by the headers (and Steffin & Classen) to be SPTM_FUNCTIONID_REGISTER_EXC_RETURN.
To summarize, interrupts in GL get passed back to XNU, which then realizes the interrupted thread was in GL, and therefore makes a specific GENTER to resume - either #1, #2, or #3,
TXM and SK Upcalls
The plot thickens when we see several routines in SPTM which call up to TXM. That is, SPTM requiring some TXM service for its own purposes, and not merely a relay from XNU:
We called the function at 0xfffffff027098f7c _sptm_enter_txm. This is further supported by a call to _dispatch_state_machine with an event code of #3 (which the headers showed us is EVENT_CALL_TXM). The call numbers are crafted in the same way as XNU, but with a prefix (in bits 48+) of 0x2, to indicate dispatching is for the SPTM interface.
For example, _sptm_map_page calls _txm_upcall_1. As our analysis of TXM showed, this is likely related to code signature hash verification of the page being mapped.
Similar calls exist into SK:
With the _dispatch_state_machine event as #4, _EVENT_CALL_SK. Upcall 0 is apparently, SK_HIB_start, #1 is SK_HIB_encrypt, #2 is SK_HIB_finish, and #3 is SK_HIB_Patchup.
Dispatch Tables
At this point, we've fully figured out the state machine and events - but how do we know how to resolve the sptm_dispatch_target_t?
This is handled by TXM, SK and the IOMMUs registration of dispatch tables. We've discussed this in our previous posts, and this was further corroborated by the Kernel.framework headers:
In addition to those, there are the codes of 253 (SPTM_DISPATCH_TABLE_RETURN_TO_CALLER), 254 (SPTM_DISPATCH_TABLE_PANIC) and 255 (SPTM_DISPATCH_TABLE_EXCEPTION_STATE_SAVED).
Looking through the disassembly of _sptm_dispatch (whose name we know thanks to panic strings) we have:
The value loaded initially into X8 is from a global - 0xfffffff027091740 - which we find in __LATE_CONST. This, like __DATA_CONST is data which gets initialized and then CTRR-locked. We find there an array of pointers which aligns with the XNU, TXM and SK dispatch tables (0,1,2), followed by a gap until entry #10, which is the dispatch table for hibernation:
The missing entries - #3 through #8 are taken up by the IOMMUs.
IOMMUs
Another aspect of SPTM is to allow IOMMUs, providing further memory separation between the various domains. Somewhere late in _sptm_bootstrap_late are calls to _iommu_init_driver:
Previous versions of SPTM used more arguments for this routine, but the one in iOS 26 only takes one. We proceed to disassemble:
From the ADRP/ADD/ADDsr sequence we can deduce that 0xfffffff027090e68 is a table of IOMMUs, with each entry occupying 32 bits (LSL #5). Dumping from that address, we indeed find:
These align with the first parameters to the _register_iommu_driver. The XXX_subsystem symbols (ours, not Apple's) are for each IOMMU, pointing into the subsystem parameters in __DATA_CONST.__const. Taking one of these as an example:
These structures exhibit similar structure to XNU's pagers, as structures containing metadata and function pointers. Correlating between the known symbols of the Unified Address Translation (UAT) and T8110DART corroborates this. The function pointers are used in the respective stages of the IOMMU's lifecycle. The endpoints differ with each IOMMU, but align with XNU's (and possibly SK's) calls.
For example, XNU's UAT calls _sptm_enter with a dispatch_... of 0x70000000# (as UAT claims dispatch table ID #7). In this way, it can get to endpoint 0 (_sptm_uat_init_state), 0x700000003 for endpoint 3 (_sptm_uat_unmap_table), etc.
This can be used to add additional (otherwise redacted) symbols to the MOVK,MOVK,MOVK,B sequences found throughout XNU. The Violation strings at the end of each IOMMU are resolved by _sptm_violation_type_to_string (called from _env_violation). This function also refers to the IOMMU Table (0xfffffff027090e68).
XNU Endpoints
The recently released sources of xnu-12377 reveal several calls from XNU's pmap layer to SPTM, though their implementation is redacted. There are also other examples, like sptm_resume_from_exception and sptm_register_xnu_exc_return, which we discussed previously.
By attacking from the XNU side, we can figure out the endpoint identifiers in SPTM. Putting the two together, we can build a table, with entries like this:
Of course, the sptm_xnu.h header makes this far easier and corroborates the table above. Darwin 24 had some 34 endpoints for XNU (0-33), and Darwin 25 adds 37 through 42. The interested reader is encouraged to complete the table as an exercise, though we have symbolicated it in the accompanying disarm(j) matchers file, provided later.
CoreCrypto
While looking through SPTM's __TEXT_CONST, disarm(j) spotted a familiar pattern - "67 E6 09 6A 85 AE 67 BB", which was also referenced from the beginning of __DATA_CONST.__const. A little researching found this is part of Apple's CoreCrypto, Apple's commonly used CoreCrypto library - specifically, _ccsha256_initial_state. From there, detecting _ccsha384_initial_state and sha512_K was straightforward using pattern matchers.
There is also an embedding of K256 inside __TEXT.__text, which is called on by _func_0xfffffff0270a8d00 (which would make it _AccelerateCrypto_SHA256_compress, from CoreCrypto's /acceleratecrypto/Source/sha256/arm64/sha256_compress_arm64.s).
This is in line with it being wrapped by csha256_vng_arm_compress (from ccsha2/src/ccsha256_vng_arm_di.c), which would be _func_0xfffffff0270aad24 in our binary. This leads us to see that the _ccshaxxx_initial_state references we see in __DATA_CONST are _ccsha384_vng_arm_di and _ccsha256_vng_arm_di, respectively, so that:
Along with the mention of hibernation keys in the device tree, an educated guess is that SPTM also contains code to cryptographically (key) hash memory pages going in and out of hibernation, in order to tamperproof them.
Conclusion
This blog post has been long in the making, but we hope you now realize why. In addition to our more immediate workflows in establishing unique forensics into both Android and iOS, the amount of research required to get to this level of detail was massive and time consuming. This should hopefully flesh out all the pieces that make up SPTM.
Further, you can get all our symbolication logic for all versions of SPTM so far - past, present, and hopefully future - using This disarm(j) matchers file. Disarm is available here.
To apply, simply do the following:
# # Download the matchers file: # $ wget https://df-f.com/s/sptm.matchers # # Apply the matching logic using disarm's JMATCHERS environment variable: # $ JMATCHERS=sptm.matchers disarm your_sptm_binary
The matcher logic uncovers some 100 or so functions automatically (at least until Apple redacts the panic strings), with additional fixed address rules (that only apply to iOS 26's SPTM image) symbolicating some 70-80 more. Overall, this provides a third of SPTM's routines, focusing on the code flow of initialization, and of the dispatch state machine traversals.
We hope the detail presented here helps encourage further research into SPTM, with open sharing of the information, and not seek to monopolize it. Also, please remember to give acknowledgments where due. For our part, we would like to once again acknowledge the great work of Steffin & Classen, as well as the posts by Random Augustine.
As with the OBTS talk, this has gone long enough - so we will leave the last bits of TXM and a discussion of Exclaves for a future blog post!