Run a virtual iPhone on an Apple Silicon Mac.
Swift
// DyldSharedCacheLSDEmbeddedRegTests.swift — parity for the lsd embedded-registration gate.
//
// The patch is one instruction in a 6.7 GB cache, and a wrong one is a boot
// panic rather than a failing assertion, so the reference these tests grade
// against is the Python that shipped before this port: `cfw.py
// patch-lsd-embedded-reg`. That Python has since been deleted, so its result
// is frozen here instead of re-run: `FrozenReference` below records the site
// it found, the bytes it wrote and the SHA-256 of every chunk it changed, and
// the Swift patcher is graded against those numbers. Each constant names the
// command that produced it.
//
// The cache is required. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
// `ipsws/ref_extract/dsc_pristine` in place. Without it these tests FAIL — the
// suite never opens with a bare `return`, which Swift Testing reports as a
// pass, so a green run cannot mean the cache was absent. A machine that
// genuinely cannot carry the fixture sets `VPHONE_DSC_FIXTURE_OPTIONAL=1`,
// which turns the failure into a visible skip.
//
// Nothing here writes to the pristine tree. Clones are made with `clonefile`
// (instant and near-free on APFS) under the system temporary directory, or
// under `VPHONE_DSC_SCRATCH` when the caller names one.
import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit
// MARK: - The frozen reference
/// What the reference Python wrote on the real 24A435 arm64e shared cache.
///
/// Every value below was read off one live run, recorded at commit 78cbeea:
///
/// .venv/bin/python3 scripts/patchers/cfw.py \
/// patch-lsd-embedded-reg <clone of ipsws/ref_extract/dsc_pristine>
///
/// The Swift patcher has to land on the same site, write the same bytes and
/// leave the same chunk files with the same digests.
private enum FrozenReference {
/// Python: `[.] -[_LSDModifyClient clientIsEntitled…] @ 0x186EE9FAC`.
static let methodVMA: UInt64 = 0x1_86EE_9FAC
/// Python: `[.] gate: cbz w0, #0x186eea048 @ 0x186EEA024`.
static let gateVMA: UInt64 = 0x1_86EE_A024
/// Python: the gate it decoded at `0x186EEA024` was a `cbz`.
static let gateMnemonic = "cbz"
/// Python: `(fall-through sets w20=1)` — the register carrying the YES.
static let gateResultRegister = "w20"
/// Python: `NOP'd gate cbz -> nop … (bytes 20010034 -> 1f2003d5)`.
static let originalBytes = Data([0x20, 0x01, 0x00, 0x34])
/// Python: the same line's replacement half, `1f2003d5`, i.e. `ARM64.nop`.
static let patchedBytes = Data([0x1F, 0x20, 0x03, 0xD5])
/// Python: one `NOP'd gate` line, so one site written.
static let sitesWritten = 1
/// `cmp -s` of the Python's output against the pristine tree, chunk by
/// chunk: exactly one file moved, with this SHA-256 afterwards, from
/// `shasum -a 256 <python output>/dyld_shared_cache_arm64e.01`.
///
/// The digest covers the re-attestation as well as the NOP — the Python
/// logged `re-attest: wrote slot 6842 of dyld_shared_cache_arm64e.01`
/// (`ee91dcbd.. -> 4ba06a66..`), `updated 1 slot hash(es) across 1
/// chunk(s)`, and a Swift run that skipped or mis-computed that slot hash
/// would land on a different digest here.
///
/// Two further runs of the same Python pinned the edges: re-run over its
/// own output printed `already NOP at 0x186EEA024`, no `NOP'd gate` line,
/// `updated 0 slot hash(es)`, and left this digest standing; `--dry-run`
/// on a fresh clone printed `would NOP gate cbz -> nop at 0x186EEA024` and
/// changed no byte of any chunk.
static let changedChunks: [String: String] = [
"dyld_shared_cache_arm64e.01":
"e0c33aa967c0de2d2f46ee6becf40eab5acf20c12a8e1d99bf5b14da6da12a7c",
]
}
// MARK: - Fixture discovery
private enum LSDRegFixture {
static let repoRoot = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
/// The read-only reference cache.
static var pristine: URL? {
let url = ProcessInfo.processInfo.environment["VPHONE_DSC_PRISTINE"]
.map { URL(fileURLWithPath: $0) }
?? repoRoot.appendingPathComponent("ipsws/ref_extract/dsc_pristine")
let main = url.appendingPathComponent("dyld_shared_cache_arm64e")
return FileManager.default.fileExists(atPath: main.path) ? url : nil
}
/// Opt-out for a machine that cannot carry the 6.7 GB fixture.
static var isOptional: Bool {
ProcessInfo.processInfo.environment["VPHONE_DSC_FIXTURE_OPTIONAL"] == "1"
}
/// The suite runs unless the cache is absent *and* the caller opted out.
static var runs: Bool {
pristine != nil || !isOptional
}
static let missing: Comment = """
the real 24A435 arm64e shared cache is required — put it at \
ipsws/ref_extract/dsc_pristine, point VPHONE_DSC_PRISTINE at it, or set \
VPHONE_DSC_FIXTURE_OPTIONAL=1 to skip these tests instead of failing
"""
/// Where clones go. Deliberately *not* inside `ipsws/ref_extract`: that
/// tree is the pristine reference every DSC test compares against, and a
/// scratch directory next to it is one `rm -rf` typo away from destroying
/// a 6.7 GB extraction nobody can regenerate quickly.
static var scratchRoot: URL {
// Per-suite leaf on BOTH branches: the override is a base shared with
// the other DSC suites, and they reuse the same clone names.
let base = ProcessInfo.processInfo.environment["VPHONE_DSC_SCRATCH"]
.map { URL(fileURLWithPath: $0) }
?? URL(fileURLWithPath: NSTemporaryDirectory())
return base.appendingPathComponent("vphone-dsc-lsd-embedded-reg")
}
/// Clone the pristine cache into a fresh directory the caller may write to.
///
/// `cp -c` asks for a `clonefile`, which costs no space and no time when
/// the scratch root is on the same APFS volume as the fixture. When it is
/// not — a caller who pointed `VPHONE_DSC_SCRATCH` at another disk — the
/// clone is refused, and the fallback is an ordinary copy rather than a
/// failed test.
static func cloneCache(named name: String) throws -> URL {
let pristine = try #require(self.pristine, missing)
let destination = scratchRoot.appendingPathComponent(name)
try? FileManager.default.removeItem(at: destination)
try FileManager.default.createDirectory(
at: destination,
withIntermediateDirectories: true,
)
let entries = try FileManager.default
.contentsOfDirectory(atPath: pristine.path)
.sorted()
.map { pristine.appendingPathComponent($0).path }
for flags in [["-c", "-R"], ["-R"]] {
let result = try Shell.run(
executable: URL(fileURLWithPath: "/bin/cp"),
arguments: flags + entries + [destination.path],
)
if result.status == 0 {
return destination
}
}
Issue.record("could not clone the pristine cache into \(destination.path)")
throw CocoaError(.fileWriteUnknown)
}
/// Discard clones, and the scratch root with them once the last one is
/// gone, so a test run leaves the filesystem as it found it.
static func discard(_ clones: URL...) {
for clone in clones {
try? FileManager.default.removeItem(at: clone)
}
let remaining = (try? FileManager.default
.contentsOfDirectory(atPath: scratchRoot.path)) ?? []
if remaining.isEmpty {
try? FileManager.default.removeItem(at: scratchRoot)
}
}
}
// MARK: - Subprocess helper
private enum Shell {
struct Result {
let status: Int32
let stdout: String
let stderr: String
}
@discardableResult
static func run(
executable: URL,
arguments: [String],
currentDirectory: URL? = nil,
) throws -> Result {
let process = Process()
process.executableURL = executable
process.arguments = arguments
if let currentDirectory {
process.currentDirectoryURL = currentDirectory
}
let out = Pipe()
let err = Pipe()
process.standardOutput = out
process.standardError = err
try process.run()
let outData = out.fileHandleForReading.readDataToEndOfFile()
let errData = err.fileHandleForReading.readDataToEndOfFile()
process.waitUntilExit()
return Result(
status: process.terminationStatus,
stdout: String(decoding: outData, as: UTF8.self),
stderr: String(decoding: errData, as: UTF8.self),
)
}
}
// MARK: - Digests
/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
/// whole. The hex spelling matches `shasum -a 256`, which is what produced the
/// frozen digests.
private enum Digest {
static func sha256(of url: URL) throws -> String {
let handle = try FileHandle(forReadingFrom: url)
defer { try? handle.close() }
var hasher = SHA256()
while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
hasher.update(data: block)
}
return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
}
// MARK: - Byte-for-byte cache comparison
private enum CacheComparison {
/// Every file name that differs between two cache directories.
///
/// `cmp -s` rather than loading 6.7 GB into memory twice; file names are
/// compared first so a missing or extra chunk is reported as such.
static func differences(between lhs: URL, and rhs: URL) throws -> [String] {
let manager = FileManager.default
let left = try Set(manager.contentsOfDirectory(atPath: lhs.path))
let right = try Set(manager.contentsOfDirectory(atPath: rhs.path))
var differing = Array(left.symmetricDifference(right)).sorted()
for name in left.intersection(right).sorted() {
let result = try Shell.run(
executable: URL(fileURLWithPath: "/usr/bin/cmp"),
arguments: [
"-s",
lhs.appendingPathComponent(name).path,
rhs.appendingPathComponent(name).path,
],
)
if result.status != 0 {
differing.append(name)
}
}
return differing.sorted()
}
/// How many chunk files differ from the pristine tree.
static func changedFiles(in directory: URL) throws -> [String] {
let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
return try differences(between: pristine, and: directory)
}
}
// MARK: - Gate discovery
@Suite(
"DSC lsd embedded-registration gate",
.enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
.serialized,
)
struct DyldSharedCacheLSDEmbeddedRegGateTests {
@Test
func `the gate is a cbz/cbnz on w0 whose fall-through sets a w register to 1`() throws {
let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
let chunks = try DyldSharedCacheChunkSet(directory: pristine)
let located = try #require(
try DyldSharedCacheLSDEmbeddedRegPatcher.locateGate(in: chunks),
"the iOS 27 fixture must carry \(DyldSharedCacheLSDEmbeddedRegPatcher.method)",
)
#expect(["cbz", "cbnz"].contains(located.gate.mnemonic))
#expect(!located.gate.wasAlreadyNOP)
#expect(located.gate.resultRegister.hasPrefix("w"))
#expect(located.gate.vma > located.functionVMA)
// The gate is inside the disassembly window, by construction.
#expect(
located.gate.vma
< located.functionVMA + UInt64(DyldSharedCacheLSDEmbeddedRegPatcher.maxInstructions * 4),
)
// …and it is the exact site the reference Python reported.
#expect(located.functionVMA == FrozenReference.methodVMA)
#expect(located.gate.vma == FrozenReference.gateVMA)
#expect(located.gate.mnemonic == FrozenReference.gateMnemonic)
#expect(located.gate.resultRegister == FrozenReference.gateResultRegister)
}
@Test
func `the symbol resolves through the cache's own local symbol table`() throws {
let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
let chunks = try DyldSharedCacheChunkSet(directory: pristine)
let address = try #require(
try chunks.resolveLocalSymbol(DyldSharedCacheLSDEmbeddedRegPatcher.method),
"\(DyldSharedCacheLSDEmbeddedRegPatcher.method) must be in the .symbols table",
)
#expect(address == FrozenReference.methodVMA)
// It has to live in an executable mapping, or it is not the method.
let mapping = try #require(chunks.mapping(forVMA: address))
#expect(mapping.isExecutable)
}
}
// MARK: - Parity against the frozen reference
@Suite(
"DSC lsd embedded-registration parity",
.enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
.serialized,
)
struct DyldSharedCacheLSDEmbeddedRegParityTests {
@Test
func `Swift reproduces the reference cache byte for byte, one site`() throws {
let swiftClone = try LSDRegFixture.cloneCache(named: "swift")
defer { LSDRegFixture.discard(swiftClone) }
let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(
chunksDirectory: swiftClone,
log: nil,
)
#expect(report.outcome == .patched)
#expect(report.sitesWritten == FrozenReference.sitesWritten)
#expect(report.methodIsPresent)
#expect(report.gate?.vma == FrozenReference.gateVMA)
// Exactly the chunk the Python moved, and to exactly the same bytes.
let changed = try CacheComparison.changedFiles(in: swiftClone)
#expect(changed == FrozenReference.changedChunks.keys.sorted())
for name in changed {
let digest = try Digest.sha256(of: swiftClone.appendingPathComponent(name))
let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
#expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
}
}
@Test
func `the recorded write names the chunk, its offset and the gate address`() throws {
let clone = try LSDRegFixture.cloneCache(named: "record")
defer { LSDRegFixture.discard(clone) }
let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
let record = try #require(report.record)
let gate = try #require(report.gate)
#expect(record.patchID == DyldSharedCacheLSDEmbeddedRegPatcher.patchID)
#expect(record.component.hasPrefix("dyld_shared_cache_arm64e"))
#expect(record.virtualAddress == gate.vma)
#expect(record.patchedBytes == ARM64.nop)
#expect(record.originalBytes != ARM64.nop)
#expect(record.originalBytes.count == 4)
#expect(record.afterDisasm == "nop")
#expect(record.beforeDisasm.hasPrefix(gate.mnemonic))
// The bytes on both sides are the pair the Python printed.
#expect(record.originalBytes == FrozenReference.originalBytes)
#expect(record.patchedBytes == FrozenReference.patchedBytes)
#expect(record.virtualAddress == FrozenReference.gateVMA)
// The offset has to name the byte that changed, in the file it names.
let handle = try FileHandle(
forReadingFrom: clone.appendingPathComponent(record.component),
)
defer { try? handle.close() }
try handle.seek(toOffset: UInt64(record.fileOffset))
#expect(try handle.read(upToCount: 4) == ARM64.nop)
}
}
// MARK: - Re-runs and dry runs
@Suite(
"DSC lsd embedded-registration re-runs",
.enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
.serialized,
)
struct DyldSharedCacheLSDEmbeddedRegRerunTests {
@Test
func `a second Swift run is idempotent and leaves the bytes alone`() throws {
let clone = try LSDRegFixture.cloneCache(named: "idempotent")
defer { LSDRegFixture.discard(clone) }
let first = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
#expect(first.outcome == .patched)
let afterFirst = try CacheComparison.changedFiles(in: clone)
let second = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
#expect(second.outcome == .alreadyPatched)
#expect(second.sitesWritten == 0)
#expect(second.gate?.wasAlreadyNOP == true)
#expect(second.gate?.vma == first.gate?.vma)
#expect(try CacheComparison.changedFiles(in: clone) == afterFirst)
// The reference was idempotent across runs too, so a second Swift pass
// has to leave the frozen digests standing.
for name in afterFirst {
#expect(
try Digest.sha256(of: clone.appendingPathComponent(name))
== FrozenReference.changedChunks[name],
)
}
}
@Test
func `a dry run locates the gate and writes nothing`() throws {
let clone = try LSDRegFixture.cloneCache(named: "dryrun")
defer { LSDRegFixture.discard(clone) }
let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(
chunksDirectory: clone,
dryRun: true,
log: nil,
)
#expect(report.outcome == .wouldPatch)
#expect(report.sitesWritten == 0)
#expect(report.gate?.vma == FrozenReference.gateVMA)
// The reference dry run wrote nothing either.
#expect(try CacheComparison.changedFiles(in: clone).isEmpty)
}
}