Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
22.1 KB
Raw Blame
// DyldSharedCacheMaxSlidePatcher.swift — Clamp the dyld shared cache's recorded maxSlide so
// a large userland cache fits the PCC vphone600 26.x kernel's fixed 6 GiB
// shared region.
//
// Swift port of `scripts/patchers/cfw_patch_dsc_maxslide.py`, driven by
// `cfw.py patch-dsc-maxslide <chunks_dir> [--dry-run] [--force]` from
// `cfw_install.sh` and `cfw-kit/lib/base_stages.sh`.
//
// Why the patch exists
// --------------------
// The vphone600 26.x kernel reserves SHARED_REGION_SIZE_ARM64 = 0x180000000
// (6 GiB) at SHARED_REGION_BASE_ARM64 = 0x180000000 (verified by disassembling
// the arm64 case of the kernel's `shared_region_create`). At map time the kernel
// needs room for the cache's mapped span PLUS the cache header's `maxSlide` —
// the ASLR range it will pick a slide from. A newer userland whose cache nearly
// fills the region overflows it:
//
//     iOS 27.0 (24A5380h): span 0x17C830000 (~5.95 GiB)
//                        + maxSlide 0x20000000 (512 MiB)
//                        = 0x19C830000 (~6.46 GiB) > 0x180000000 (6 GiB)
//     iOS 27.0 (24A435):   size 0x17D504000 + maxSlide 0x20000000
//                        = 0x19D504000 > 0x180000000
//
// The 512 MiB is not a per-build accident: the cache builder gives every iOS
// arm64 cache a fixed 512 MiB slide and sizes it to fit the iOS 27 SDK's own,
// larger region. So every 27 cache read so far overflows this kernel's region,
// and the gate below patches it.
//
// `_shared_region_map_and_slide` then returns ENOMEM, dyld cannot map
// libSystem, and launchd (pid 1) panics: "initproc failed to start -- Library
// not loaded: /usr/lib/libSystem.B.dylib". Older userlands (26.x / 18.x) fit
// with their full slide and are unaffected.
//
// The fix is to zero `maxSlide`, so the cache maps at slide 0 and fits — iOS
// 27.0 leaves ~58 MiB spare. ASLR of the shared cache is lost; nothing else is.
//
// Page 0 is re-attested although the kernel boots without it: Xcode's
// `dsc_extractor` rejects a stale header slot (see row 10 of 0_binary_patch_comparison.md).
//
// On the CLAUDE.md patcher guardrails
// -----------------------------------
// There is no instruction here to decode and none to assemble: the patch writes
// a little-endian u64 metadata field, so Capstone and the Keystone-backed
// `ARM64Encoder` have nothing to contribute. What replaces them is the
// structural check in `readHeader`: the field offsets come from
// `dyld_cache_header` in dyld's `dyld_cache_format.h`, and before they are
// trusted this code applies dyld's own version gate (`mappingOffset` must reach
// past the field) and cross-checks the values it reads against the mapping
// table it parsed independently. A cache whose header does not corroborate the
// layout is refused rather than written into blind.

import Foundation
import VPhonePatchKit

/// Zeroes `dyld_cache_header.maxSlide` when the cache would otherwise overflow
/// the kernel's fixed shared region.
public enum DyldSharedCacheMaxSlidePatcher {
    // MARK: - Constants

    /// `SHARED_REGION_SIZE_ARM64` as baked into the PCC vphone600 26.x kernel.
    /// A cache's span plus its `maxSlide` must fit inside this or the shared
    /// region map ENOMEMs.
    public static let kernelSharedRegionSize: UInt64 = 0x1_8000_0000

    /// The same kernel with the `kernel-boot-shared_region_size` patch applied
    /// (`KernelCustomFirmwarePatchSharedRegionSize`): the arm64 region grows to
    /// 0x1C0000000 while the base stays 0x180000000. The region top
    /// (0x340000000) remains under the kernel's own task map ceilings, so
    /// nothing else moves with it. `cfw install` checks the cache against this
    /// size when the VM's kernelcache receipt lists the patch.
    public static let patchedKernelSharedRegionSize: UInt64 = 0x1_C000_0000

    /// Byte offsets of the `dyld_cache_header` fields this patcher reads, from
    /// dyld's `dyld_cache_format.h`. Stable across every iOS this project
    /// targets, and corroborated at run time — see ``readHeader(from:)``.
    enum HeaderField {
        /// `char magic[16]` — "dyld_v1" followed by the architecture.
        static let magic = 0x00
        /// `uint32_t mappingOffset` — also dyld's own "is this field present"
        /// gate: a field is present when `mappingOffset` reaches past it.
        static let mappingOffset = 0x10
        /// `uint64_t sharedRegionStart`.
        static let sharedRegionStart = 0xE0
        /// `uint64_t sharedRegionSize`.
        static let sharedRegionSize = 0xE8
        /// `uint64_t maxSlide` — the one field this patcher writes.
        static let maxSlide = 0xF0
    }

    /// The `dyld_v1` prefix, checked exactly as the Python checks it: the first
    /// seven bytes, so any architecture suffix passes.
    static let magicPrefix = Data("dyld_v1".utf8)

    /// The patch identifier the reference capture records under.
    public static let patchID = "dyld-boot-maxslide"

    // MARK: - Result

    /// What the gate decided.
    public enum Outcome: Sendable, Equatable {
        /// Span + maxSlide already fits the region, and `force` was not set.
        case fits(combined: UInt64, region: UInt64)
        /// `maxSlide` was already 0, so there is nothing left to clamp.
        case alreadyZero
        /// The cache overflows the region: the patch applies.
        case overflow(combined: UInt64, region: UInt64)
        /// The cache fits but `force` was set, so the patch applies anyway.
        case forced(combined: UInt64, region: UInt64)

        /// True when this outcome means bytes are (or would be) written.
        public var patches: Bool {
            switch self {
            case .fits, .alreadyZero: false
            case .overflow, .forced: true
            }
        }

        /// The sentence the Python prints as its reason, reproduced verbatim so
        /// the two implementations' logs diff cleanly.
        var reason: String? {
            switch self {
            case .fits, .alreadyZero:
                nil
            case let .overflow(combined, region):
                "overflow: span+maxSlide \(DyldSharedCacheMaxSlidePatcher.hex(combined)) > "
                    + "region \(DyldSharedCacheMaxSlidePatcher.hex(region))"
            case let .forced(combined, region):
                "forced: span+maxSlide \(DyldSharedCacheMaxSlidePatcher.hex(combined)) fits "
                    + "region \(DyldSharedCacheMaxSlidePatcher.hex(region)) but --force set"
            }
        }
    }

    /// Everything one run learned and did.
    public struct Result: Sendable {
        /// What the gate decided.
        public let outcome: Outcome
        /// `dyld_cache_header.sharedRegionStart`, as found.
        public let sharedRegionStart: UInt64
        /// `dyld_cache_header.sharedRegionSize`, as found.
        public let sharedRegionSize: UInt64
        /// `dyld_cache_header.maxSlide`, as found — before any write.
        public let maxSlide: UInt64
        /// The patch, when one applies. Present on a dry run too: the Python
        /// returns 1 in that case, meaning "this cache needs the patch".
        public let record: PatchRecord?
        /// The span that landed on disk, or `nil` on a dry run or a no-op.
        public let writtenSpan: DyldSharedCacheWriteSpan?
        /// Page 0's re-attestation, or `nil` when the gate left the header alone.
        public let reattestation: DyldSharedCacheReattestation?

        /// Sites patched — the Python function's return value, which is 0 or 1.
        public var siteCount: Int {
            record == nil ? 0 : 1
        }

        /// Whether the `maxSlide` field was written; slot rewrites are in `reattestation`.
        public var didWrite: Bool {
            writtenSpan != nil
        }
    }

    // MARK: - Region Check

    /// A cache that does not fit the kernel's shared region even at slide 0.
    ///
    /// Zeroing `maxSlide` only gives the slide back. When `sharedRegionSize`
    /// alone is larger than the region, `_shared_region_map_and_slide` still
    /// returns ENOMEM and launchd panics on first boot with "Library not
    /// loaded: /usr/lib/libSystem.B.dylib". The iOS 27 caches for iPhone18,1
    /// and iPhone18,2 are such caches: 0x185804000 on 27.0.1 (24A446), where
    /// iPhone17,3's 0x17D508000 still fits.
    public struct RegionOverflow: Error, CustomStringConvertible, Sendable, Equatable {
        /// `dyld_cache_header.sharedRegionSize`, as found.
        public let sharedRegionSize: UInt64
        /// The guest kernel's shared region size it was checked against.
        public let region: UInt64

        public var description: String {
            "The dyld shared cache spans \(DyldSharedCacheMaxSlidePatcher.hex(sharedRegionSize)), "
                + "more than the guest kernel's \(DyldSharedCacheMaxSlidePatcher.hex(region)) shared region "
                + "even with no slide, so this guest would panic on first boot (launchd cannot load "
                + "libSystem). Choose a device and iOS version whose cache fits, such as iPhone17,3, "
                + "or iOS 26 for this device."
        }
    }

    /// Throws ``RegionOverflow`` when the cache under `chunksDirectory` cannot
    /// map at any slide, and returns its `sharedRegionSize` otherwise. Reads
    /// only; nothing is written.
    @discardableResult
    public static func requireFitsAtSlideZero(
        chunksDirectory: URL,
        architecture: String? = nil,
        kernelRegionSize: UInt64 = kernelSharedRegionSize,
    ) throws -> UInt64 {
        let chunks = try DyldSharedCacheChunkSet(directory: chunksDirectory, architecture: architecture)
        let header = try readHeader(
            from: chunks,
            at: headerVMA(of: chunks),
            chunkName: chunks.mainCacheURL.lastPathComponent,
        )
        guard header.sharedRegionSize <= kernelRegionSize else {
            throw RegionOverflow(sharedRegionSize: header.sharedRegionSize, region: kernelRegionSize)
        }
        return header.sharedRegionSize
    }

    // MARK: - Patching

    /// Clamp `maxSlide` in the cache under `chunksDirectory`.
    ///
    /// Self-gating, exactly as the Python is: a cache whose span plus slide
    /// already fits `kernelRegionSize` is left alone unless `force` is set, and
    /// a cache already at `maxSlide == 0` is left alone either way. That keeps
    /// an 18.x / 26.x base untouched even when the install-side `27.*` gate is
    /// removed, and makes a re-run over an already-patched cache a no-op rather
    /// than an error.
    ///
    /// - Parameters:
    ///   - chunksDirectory: the directory of `dyld_shared_cache_<arch>*` chunks.
    ///   - architecture: explicit cache suffix, or nil to discover the cache.
    ///   - kernelRegionSize: the guest kernel's `SHARED_REGION_SIZE_ARM64`.
    ///   - dryRun: decide and report, but write nothing.
    ///   - force: clamp even when the cache already fits — the verb's `--force`,
    ///     for use by hand. `cfw install` never sets it.
    ///   - verbose: print the Python's log lines.
    @discardableResult
    public static func patch(
        chunksDirectory: URL,
        architecture: String? = nil,
        kernelRegionSize: UInt64 = kernelSharedRegionSize,
        dryRun: Bool = false,
        force: Bool = false,
        captureUndo: Bool = false,
        onUndo: ((DyldSharedCacheUndoLog) -> Void)? = nil,
        verbose: Bool = true,
    ) throws -> Result {
        let mainChunk = DyldSharedCacheChunkSet.mainCacheURL(in: chunksDirectory, architecture: architecture)
        let mainChunkName = mainChunk.lastPathComponent
        // Checked before the chunk set is built so the error names the file the
        // Python's FileNotFoundError names, rather than the directory.
        guard FileManager.default.fileExists(atPath: mainChunk.path) else {
            throw PatcherError.fileNotFound("main DSC chunk not found: \(mainChunk.path)")
        }

        let chunks = try DyldSharedCacheChunkSet(
            directory: chunksDirectory, architecture: architecture, captureUndo: captureUndo,
        )
        defer {
            if captureUndo, let undo = chunks.takeUndoLog() {
                onUndo?(undo)
            }
        }
        let headerVMA = try headerVMA(of: chunks)
        let header = try readHeader(from: chunks, at: headerVMA, chunkName: mainChunkName)

        if verbose {
            print(
                "  [.] \(mainChunkName): start=\(hex(header.sharedRegionStart)) "
                    + "size=\(hex(header.sharedRegionSize)) maxSlide=\(hex(header.maxSlide))",
            )
        }

        // Python does this in arbitrary-precision arithmetic. A u64 header where
        // the two fields sum past 2^64 is not a cache, and clamping a field we
        // evidently cannot parse is worse than saying so.
        let (combined, overflowed) = header.sharedRegionSize
            .addingReportingOverflow(header.maxSlide)
        guard !overflowed else {
            throw PatcherError.invalidFormat(
                "\(mainChunk.path): sharedRegionSize \(hex(header.sharedRegionSize)) + maxSlide "
                    + "\(hex(header.maxSlide)) overflows 64 bits; header is not a dyld_cache_header",
            )
        }

        let fieldVMA = headerVMA &+ UInt64(HeaderField.maxSlide)
        let log: ((String) -> Void)? = if verbose { DyldSharedCacheCodeSignature.stderrLog } else { nil }
        func attestClampedHeader() throws -> DyldSharedCacheReattestation? {
            guard header.maxSlide == 0 else { return nil }
            return try DyldSharedCacheCodeSignature.reattest(
                in: chunks,
                modifiedSpans: [DyldSharedCacheWriteSpan(vma: fieldVMA, length: 8)],
                dryRun: dryRun,
                log: log,
            )
        }

        let fits = combined <= kernelRegionSize
        if fits, !force {
            if verbose {
                print(
                    "      [=] fits: span+maxSlide \(hex(combined)) <= "
                        + "region \(hex(kernelRegionSize)); no change",
                )
            }
            return try Result(
                outcome: .fits(combined: combined, region: kernelRegionSize),
                sharedRegionStart: header.sharedRegionStart,
                sharedRegionSize: header.sharedRegionSize,
                maxSlide: header.maxSlide,
                record: nil,
                writtenSpan: nil,
                reattestation: attestClampedHeader(),
            )
        }
        guard header.maxSlide != 0 else {
            if verbose {
                print("      [=] maxSlide already 0; no change")
            }
            return try Result(
                outcome: .alreadyZero,
                sharedRegionStart: header.sharedRegionStart,
                sharedRegionSize: header.sharedRegionSize,
                maxSlide: header.maxSlide,
                record: nil,
                writtenSpan: nil,
                reattestation: attestClampedHeader(),
            )
        }

        let outcome: Outcome = fits
            ? .forced(combined: combined, region: kernelRegionSize)
            : .overflow(combined: combined, region: kernelRegionSize)
        let reason = outcome.reason ?? ""
        if verbose {
            print(
                "      [+] \(reason); \(dryRun ? "would set" : "set") "
                    + "maxSlide \(hex(header.maxSlide)) -> 0x0",
            )
        }

        let originalBytes = littleEndianBytes(header.maxSlide)
        let patchedBytes = littleEndianBytes(0)
        let record = PatchRecord(
            patchID: patchID,
            component: mainChunkName,
            fileOffset: HeaderField.maxSlide,
            virtualAddress: fieldVMA,
            originalBytes: originalBytes,
            patchedBytes: patchedBytes,
            description: "dyld_cache_header maxSlide \(hex(header.maxSlide)) -> 0 (\(reason))",
        )

        guard !dryRun else {
            // The Python prints its completion line on a dry run too — the run
            // did complete, it just wrote nothing. Every log line in this
            // function is kept identical to the Python's, so a `--dry-run` of
            // one can be diffed against a `--dry-run` of the other.
            if verbose {
                print("  [+] DSC maxSlide patch complete")
            }
            return Result(
                outcome: outcome,
                sharedRegionStart: header.sharedRegionStart,
                sharedRegionSize: header.sharedRegionSize,
                maxSlide: header.maxSlide,
                record: record,
                writtenSpan: nil,
                reattestation: nil,
            )
        }

        let span = try chunks.write(at: fieldVMA, patchedBytes)

        // Read the field back through the same addressing the write used, the
        // way the Python re-reads and unpacks it. A write that reported success
        // and left the old value is the one failure mode that would boot into
        // the panic this patch exists to prevent.
        let readBack = try chunks.bytesAtVMA(fieldVMA, length: 8).loadLE(UInt64.self, at: 0)
        guard readBack == 0 else {
            throw PatcherError.patchVerificationFailed(
                "maxSlide write verify failed: \(hex(readBack))",
            )
        }

        let reattestation = try DyldSharedCacheCodeSignature.reattestRecordedWrites(in: chunks, log: log)

        if verbose {
            print("  [+] DSC maxSlide patch complete")
        }
        return Result(
            outcome: outcome,
            sharedRegionStart: header.sharedRegionStart,
            sharedRegionSize: header.sharedRegionSize,
            maxSlide: header.maxSlide,
            record: record,
            writtenSpan: span,
            reattestation: reattestation,
        )
    }

    // MARK: - Header

    /// The three header fields the gate runs on.
    struct Header: Sendable, Equatable {
        let sharedRegionStart: UInt64
        let sharedRegionSize: UInt64
        let maxSlide: UInt64
    }

    /// The address the main chunk's byte 0 is mapped at.
    ///
    /// Derived from the mapping table rather than written down: the header lives
    /// at file offset 0 of the unsuffixed chunk, so the mapping that carries
    /// file offset 0 of that chunk is the one that carries the header.
    static func headerVMA(of chunks: DyldSharedCacheChunkSet) throws -> UInt64 {
        let main = chunks.mainCacheURL
        guard let mapping = chunks.mappings.first(where: {
            $0.chunkURL == main && $0.fileOffset == 0
        }) else {
            throw PatcherError.invalidFormat(
                "\(main.path): no mapping covers the cache header at file offset 0",
            )
        }
        return mapping.address
    }

    /// Read and corroborate the header fields.
    ///
    /// Three checks stand in for the Capstone decode a code patcher would do:
    ///
    /// * the `dyld_v1` magic, checked over seven bytes as the Python checks it;
    /// * dyld's own field-presence gate — `mappingOffset` is where the mapping
    ///   table starts, so the header struct runs out at that offset, and a field
    ///   only exists in this cache version if `mappingOffset` reaches past it;
    /// * agreement with the mapping table this code parsed on its own:
    ///   `sharedRegionStart` has to be the lowest address the cache maps, and
    ///   `sharedRegionSize` has to cover everything it maps. Both hold on the
    ///   24A435 arm64e cache (start 0x180000000, size 0x17D504000 against a
    ///   0x17D500000 span). If they did not, the offsets would be describing
    ///   some other struct and the write would land in an unknown field.
    static func readHeader(
        from chunks: DyldSharedCacheChunkSet,
        at headerVMA: UInt64,
        chunkName: String,
    ) throws -> Header {
        let header = try chunks.bytesAtVMA(headerVMA, length: 0x100)

        guard header.prefix(magicPrefix.count) == magicPrefix else {
            let magic = header.subdata(in: HeaderField.magic ..< (HeaderField.magic + 16))
            throw PatcherError.invalidFormat(
                "\(chunkName): not a dyld shared cache (magic=\(magic.hex))",
            )
        }

        let mappingOffset = Int(header.loadLE(UInt32.self, at: HeaderField.mappingOffset))
        let fieldEnd = HeaderField.maxSlide + MemoryLayout<UInt64>.size
        guard mappingOffset >= fieldEnd else {
            throw PatcherError.invalidFormat(
                "\(chunkName): dyld_cache_header ends at \(hex(UInt64(mappingOffset))), before "
                    + "maxSlide at \(hex(UInt64(HeaderField.maxSlide))); this cache version has no "
                    + "maxSlide field",
            )
        }

        let parsed = Header(
            sharedRegionStart: header.loadLE(UInt64.self, at: HeaderField.sharedRegionStart),
            sharedRegionSize: header.loadLE(UInt64.self, at: HeaderField.sharedRegionSize),
            maxSlide: header.loadLE(UInt64.self, at: HeaderField.maxSlide),
        )

        let mapped = chunks.addressRange
        guard parsed.sharedRegionStart == mapped.lowerBound else {
            throw PatcherError.invalidFormat(
                "\(chunkName): sharedRegionStart \(hex(parsed.sharedRegionStart)) is not the "
                    + "cache's lowest mapped address \(hex(mapped.lowerBound)); the header layout "
                    + "is not the one these offsets describe",
            )
        }
        let span = mapped.upperBound &- mapped.lowerBound
        guard parsed.sharedRegionSize >= span else {
            throw PatcherError.invalidFormat(
                "\(chunkName): sharedRegionSize \(hex(parsed.sharedRegionSize)) is smaller than "
                    + "the \(hex(span)) the cache actually maps; the header layout is not the one "
                    + "these offsets describe",
            )
        }
        return parsed
    }

    // MARK: - Formatting

    /// The 8 bytes a little-endian `uint64_t` field holds for `value`.
    ///
    /// Spelled as a value conversion rather than a byte literal: nothing here is
    /// an instruction, and nothing here should read like one.
    static func littleEndianBytes(_ value: UInt64) -> Data {
        withUnsafeBytes(of: value.littleEndian) { Data($0) }
    }

    /// `0x%X`, matching the Python's f-strings so the two logs diff cleanly.
    static func hex(_ value: UInt64) -> String {
        "0x" + String(value, radix: 16, uppercase: true)
    }
}