Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
6.9 KB
Raw Blame
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

struct KDKImageExportTests {
    @Test func pointerLayouts() throws {
        #expect(try KDKImageExport.pointer(target: 0xFE00_0000_0123_4567, ordinal: nil, auth: nil, next: 3) == 0x001F_F000_0123_4567)
        #expect(try KDKImageExport.pointer(target: 0, ordinal: 7, addend: -4, auth: nil, next: 2) == 0x4017_FFFC_0000_0007)
        #expect(try KDKImageExport.pointer(target: 0x4000, ordinal: nil, auth: 0x0005_1234_0000_0000, next: 5) == 0x802D_1234_0000_4000)
        #expect(try KDKImageExport.pointer(target: 0, ordinal: 9, auth: 0x0002_BEEF_0000_0000, next: 1) == 0xC00A_BEEF_0000_0009)
        #expect(throws: PatcherError.self) { try KDKImageExport.pointer(target: 0, ordinal: 0, addend: 1 << 18, auth: nil, next: 0) }
        #expect(throws: PatcherError.self) { try KDKImageExport.pointer(target: 0, ordinal: nil, auth: nil, next: 0x800) }
    }

    @Test func braaAndKernelADRP() throws {
        // xcrun clang -arch arm64e (2026-10-23), verified independently of
        // this encoder. Keystone 0.9.2 rejects BRAA; it cannot be the oracle.
        let cases: [(UInt32, UInt32, UInt32)] = [(16, 17, 0xD71F_0A11), (0, 1, 0xD71F_0801), (30, 31, 0xD71F_0BDF)]
        for (rn, rm, expected) in cases {
            let encoded = try #require(ARM64Encoder.encodeBRAA(rn: rn, rm: rm))
            #expect([UInt8](encoded).le(UInt32.self, 0) == expected)
            let decoded = try #require(ARM64Disassembler().disassembleOne(encoded, at: 0))
            #expect(decoded.mnemonic == "braa")
        }
        #expect(ARM64Encoder.encodeBRAA(rn: 31, rm: 0) == nil)
        #expect(ARM64Encoder.encodeBRAA(rn: 0, rm: 32) == nil)
        let low = ARM64Encoder.encodeADRP(rd: 17, pc: 0x4000, target: 0xA123)
        let high = ARM64Encoder.encodeADRP(rd: 17, pc: 0xFFFF_FE00_0000_4000, target: 0xFFFF_FE00_0000_A123)
        #expect(low == high)
        #expect(high != nil)
    }

    @Test func off12RetainsInstructionAndScale() throws {
        // Independent clang encodings of ldr/str/ldrsw/ldr q/add (see guide).
        let cases: [(UInt32, UInt32, UInt32)] = [
            (0x3940_0020, 0x123, 0x3944_8C20), // ldrb w0, [x1, #0x123]
            (0x7940_0020, 0x246, 0x7944_8C20), // ldrh
            (0xB940_0020, 0x48C, 0xB944_8C20), // ldr w0
            (0xF940_0020, 0x918, 0xF944_8C20), // ldr x0
            (0x3DC0_0020, 0x230, 0x3DC0_8C20), // ldr q0
            (0x9100_0020, 0x123, 0x9104_8C20), // add x0, x1
        ]
        for (word, offset, expected) in cases {
            let encoded = try #require(ARM64Encoder.retargetPageOffset(word, offset: offset))
            let actual = [UInt8](encoded).le(UInt32.self, 0)
            #expect(actual == expected)
            #expect(ARM64Encoder.decodePageOffset(actual) == offset)
            #expect(ARM64Disassembler().disassembleOne(encoded, at: 0) != nil)
        }
        #expect(ARM64Encoder.retargetPageOffset(0xD503_201F, offset: 4) == nil)
    }

    /// Opt-in external corpus: no Apple firmware or extracted binaries checked
    /// in. Xcode passes TEST_RUNNER_KDK_PARITY_ROOT to the test process as
    /// KDK_PARITY_ROOT. Each JSON is the reference Export call's complete input.
    @Test(.enabled(if: ProcessInfo.processInfo.environment["KDK_PARITY_ROOT"] != nil))
    func referenceCorpusByteParity() throws {
        let root = try URL(fileURLWithPath: #require(ProcessInfo.processInfo.environment["KDK_PARITY_ROOT"]))
        let selected = ProcessInfo.processInfo.environment["KDK_PARITY_ENTRY"]
        let fm = FileManager.default
        struct Symbol: Decodable {
            var name: String
            var indirectName: String?
            var type: UInt8
            var sect: UInt8
            var desc: UInt16
            var value: UInt64
            var valueModel: KDKSymbol {
                .init(name: name, indirectName: indirectName ?? "", type: type, sect: sect, desc: desc, value: value)
            }
        }
        struct Input: Decodable {
            var entryID: String
            var output: String
            var baseAddress: UInt64
            var addressOnlyBinds: Bool
            var symbols: [Symbol]
            var references: [KDKReference]
        }
        var verified = 0
        for (label, kernel) in [("donor", "vphone600"), ("research", "vresearch101")] {
            let collectionURL = root.appending(path: "data/264beta/kernelcache.release.\(kernel).decompressed")
            let collection = try KDKKernelCollection(Data(contentsOf: collectionURL, options: .mappedIfSafe))
            let corpus = root.appending(path: "parity/\(label)")
            let files = try fm.contentsOfDirectory(at: corpus.appending(path: "inputs"), includingPropertiesForKeys: nil)
                .filter { $0.pathExtension == "json" }.sorted { $0.lastPathComponent < $1.lastPathComponent }
            #expect(files.count == collection.entries.count)
            for file in files {
                let input = try JSONDecoder().decode(Input.self, from: Data(contentsOf: file))
                if let selected, selected != input.entryID {
                    continue
                }
                var image = try collection.image(input.entryID)
                // extract.go performs this before calling Export; the dump hook
                // intentionally captures Export arguments, not this preparation.
                if input.entryID == "com.apple.kernel", let thread = collection.unixThread,
                   let i = image.commands.firstIndex(where: { $0.command == KDKMachO.lcUnixThread })
                {
                    image.commands[i] = thread
                }
                var writer = try KDKImageExport(collection: collection, image: image, baseAddress: input.baseAddress,
                                                symbols: input.symbols.map(\.valueModel), references: input.references,
                                                addressOnlyBinds: input.addressOnlyBinds)
                let actual = try writer.export()
                let expected = try Data(contentsOf: corpus.appending(path: "out").appending(path: input.output))
                if actual != expected {
                    let difference = zip(actual, expected).enumerated().first { $0.element.0 != $0.element.1 }?.offset ?? min(actual.count, expected.count)
                    let destination = root.appending(path: "swift-\(label)-\(input.entryID)")
                    try actual.write(to: destination)
                    Issue.record("\(label)/\(input.entryID): first difference 0x\(String(difference, radix: 16)), Swift \(actual.count) vs Go \(expected.count) bytes; wrote \(destination.path)")
                    return
                }
                verified += 1
                if verified % 20 == 0 {
                    print("KDK parity: \(verified) images verified")
                }
            }
        }
        #expect(verified == (selected == nil ? 264 : 2))
        print("KDK parity: all \(verified) exports are byte-identical")
    }
}