Run a virtual iPhone on an Apple Silicon Mac.
Swift
// CustomFirmwareJetsamTests.swift — `CustomFirmwareJetsamPatcher` against the reference it replaces.
//
// The bar for this port is not "the test passes". It is that the Swift patcher
// and `scripts/patchers/cfw_patch_jetsam.py` produce the same bytes from the
// same input, on the real `/sbin/launchd` out of iOS 27.0 / 24A435. That Python
// is gone: what it wrote, and the two anchors it printed on its way there, are
// frozen in ``JetsamGolden`` below, and the comparison tests grade the Swift
// against those.
//
// `codesign -v` is the second, fully independent reference: the patcher's
// `reattest: true` mode has to leave a binary that verifies, and the slot hash
// it writes has to equal the one the Python's own `cfw_macho_codesign.py`
// computed over the same patched bytes — also frozen.
//
// `ipsws/` is not in the repo, so every test that needs the pristine `launchd`
// is gated on it being there and skips rather than fails when it is not. The
// pure decode/encode tests below have no such dependency and always run.
//
// Set `VPHONE_JETSAM_ARTIFACTS=<dir>` to keep each run's inputs and outputs for
// inspection from a shell; without it they land in a temporary directory.
import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit
// MARK: - Fixtures
enum JetsamFixture {
/// The package root, derived from this file rather than the working
/// directory, which `swift test` does not promise.
static let repositoryRoot = URL(filePath: #filePath)
.deletingLastPathComponent() // CustomFirmware
.deletingLastPathComponent() // FirmwarePatcherTests
.deletingLastPathComponent() // VPhoneCommand
.deletingLastPathComponent() // VPhoneExecutable
.deletingLastPathComponent() // <root>
/// The real, ad-hoc signed, thin arm64e `/sbin/launchd`.
static let pristineLaunchd = repositoryRoot
.appending(path: "ipsws/ref_extract/macho_pristine/launchd")
static let codesign = URL(filePath: "/usr/bin/codesign")
static func exists(_ url: URL) -> Bool {
FileManager.default.fileExists(atPath: url.path)
}
static var hasLaunchd: Bool {
exists(pristineLaunchd)
}
static var hasLaunchdAndCodesign: Bool {
hasLaunchd && exists(codesign)
}
/// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
/// taken again from a shell over the same file.
static func digest(of url: URL) throws -> String {
try Data(SHA256.hash(data: Data(contentsOf: url))).hex
}
/// A directory for one test's artifacts. `VPHONE_JETSAM_ARTIFACTS` pins it
/// so a shell can look at what a run produced.
static func workDirectory(_ name: String) throws -> URL {
let base = ProcessInfo.processInfo.environment["VPHONE_JETSAM_ARTIFACTS"]
.map { URL(filePath: $0) } ?? URL(filePath: NSTemporaryDirectory())
let directory = base.appending(path: "CustomFirmwareJetsamTests-\(name)")
try? FileManager.default.removeItem(at: directory)
try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
return directory
}
/// A private, writable clone of the pristine `launchd`.
static func launchdCopy(named name: String, in directory: URL) throws -> URL {
let destination = directory.appending(path: name)
try FileManager.default.copyItem(at: pristineLaunchd, to: destination)
return destination
}
@discardableResult
static func run(
_ tool: URL,
_ arguments: [String],
workingDirectory: URL? = nil,
) throws -> (status: Int32, output: String) {
let process = Process()
process.executableURL = tool
process.arguments = arguments
process.currentDirectoryURL = workingDirectory
let pipe = Pipe()
process.standardOutput = pipe
process.standardError = pipe
try process.run()
let output = pipe.fileHandleForReading.readDataToEndOfFile()
process.waitUntilExit()
return (process.terminationStatus, String(decoding: output, as: UTF8.self))
}
/// The first byte offset at which two files differ, or nil when equal.
static func firstDifference(_ lhs: Data, _ rhs: Data) -> Int? {
if lhs.count != rhs.count {
return min(lhs.count, rhs.count)
}
for index in 0 ..< lhs.count where lhs[index] != rhs[index] {
return index
}
return nil
}
}
// MARK: - The frozen reference
/// What `scripts/patchers/` produced on this fixture, recorded before it was
/// deleted.
///
/// Every value below was taken at repo commit `78cbeea`, with
/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
/// 24A435 / iPhone17,3 `/sbin/launchd` whose own digest is ``pristine``.
enum JetsamGolden {
/// `shasum -a 256 ipsws/ref_extract/macho_pristine/launchd`
static let pristine = "c640246d38aaeb2d2372aff1e5aa0de59dec267f53c0dfc155f7837e717af68b"
/// `.venv/bin/python3 scripts/patchers/cfw.py patch-launchd-jetsam <clone>`
/// — `cbz w0, #0xfaec` at 0xFA98 rewritten to `b #0xfaec`, signature left
/// stale.
static let patched = "cae806f55aadc0109c6b8e737b0ee4e648ce7ec1fbcce0ac9215f45b736d0fcb"
/// The two anchors that run printed on its way to the gate, not just its
/// answer — so a port that agreed on the gate by luck is still caught:
/// " xref at foff:0xFB0C"
/// " [+] Patched at 0xFA98: jetsam panic guard bypass"
static let xrefOffset = 0xFB0C
static let gateOffset = 0xFA98
/// ``patched``, then
/// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts/patchers");
/// import cfw_macho_codesign as r;
/// r.reattest_modified_offsets(sys.argv[1], [64152], verbose=True)'`
/// — which reported `wrote cd_index=0 slot 15 (ff0c126a.. -> 361aa09d..)`.
static let patchedAndReattested =
"689236aad3bb8fe360412195ff626269ee7403be322628a5bb66517a65ad2ea2"
/// The one code slot that re-attestation rewrote.
static let reattestedSlot = 15
/// `cfw.py patch-launchd-jetsam` run a SECOND time over ``patched``.
///
/// Not what the reference should have done — what it did. It landed a
/// second site the pristine image never had patched, printing
/// `[+] Patched at 0xFAB0`, so the file moved again. This port recognises
/// its own work and stops; the digest keeps that divergence visible.
static let patchedTwice = "2c979d9dbeb0de9cd4877c843f1910ccff43a5ebfdf50c1e0f6bdc5d53370979"
/// The second gate the reference took, from that stdout line.
static let secondRunGateOffset = 0xFAB0
}
// MARK: - Against the frozen reference
@Suite("launchd jetsam guard — against the frozen reference")
struct CustomFirmwareJetsamReferenceTests {
/// The fixture the frozen digests were taken over. Without this a digest
/// mismatch below would read as a patcher bug when the real cause is a
/// different firmware's `launchd`.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `fixture matches the goldens`() throws {
#expect(
try JetsamFixture.digest(of: JetsamFixture.pristineLaunchd) == JetsamGolden.pristine,
"""
this is not the 24A435 launchd JetsamGolden was recorded from — \
re-derive the goldens before reading a failure below as a patcher bug
""",
)
}
/// The whole point of the port: same input, same bytes out.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `matches the frozen reference byte for byte`() throws {
let work = try JetsamFixture.workDirectory("byte-equivalence")
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
let outcome = try CustomFirmwareJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
#expect(outcome.verdict == .patched)
#expect(
try JetsamFixture.digest(of: swiftTarget) == JetsamGolden.patched,
"Swift and the frozen reference diverge",
)
// And the only thing that moved is inside the instruction the record
// names. Not every one of the four bytes has to differ: on this image
// `cbz w0, #0xfaec` is A0 02 00 34 and `b #0xfaec` is 15 00 00 14, so
// byte 2 is 0x00 either way. Containment is the real claim — the whole
// instruction was rewritten and nothing outside it was.
let swiftBytes = try Data(contentsOf: swiftTarget)
let pristine = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let site = outcome.gateOffset ..< outcome.gateOffset + 4
let changed = (0 ..< pristine.count).filter { pristine[$0] != swiftBytes[$0] }
#expect(!changed.isEmpty)
#expect(changed.allSatisfy(site.contains), "bytes changed outside the gate: \(changed)")
#expect(Data(swiftBytes[site]) == outcome.record?.patchedBytes)
#expect(Data(pristine[site]) == outcome.record?.originalBytes)
}
/// The gate the reference reported is the gate this finds — and the xref it
/// reached it through too, so a port that agreed on the gate by luck is
/// still caught.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `agrees with the frozen reference on the site`() throws {
let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let image = try CustomFirmwareJetsamPatcher.Image(data: data)
let site = try #require(try CustomFirmwareJetsamPatcher.locate(in: image))
#expect(site.xrefOffset == JetsamGolden.xrefOffset)
#expect(site.gateOffset == JetsamGolden.gateOffset)
var patchable = data
let outcome = try CustomFirmwareJetsamPatcher.patch(&patchable, dryRun: true, log: nil)
#expect(outcome.gateOffset == JetsamGolden.gateOffset)
#expect(outcome.verdict == .wouldPatch)
}
}
// MARK: - Idempotence
@Suite("launchd jetsam guard — idempotence")
struct CustomFirmwareJetsamIdempotenceTests {
/// The bug this patcher must not have. The reference re-patches a second,
/// different branch on an already-patched binary; this one recognises its
/// own work and stops.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `second run changes nothing`() throws {
let work = try JetsamFixture.workDirectory("idempotence")
let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
let first = try CustomFirmwareJetsamPatcher.patch(fileAt: target, log: nil)
#expect(first.verdict == .patched)
let afterFirst = try Data(contentsOf: target)
let second = try CustomFirmwareJetsamPatcher.patch(fileAt: target, log: nil)
#expect(second.verdict == .alreadyPatched)
#expect(second.gateOffset == first.gateOffset)
#expect(second.returnBlockOffset == first.returnBlockOffset)
#expect(second.record == nil)
let afterSecond = try Data(contentsOf: target)
#expect(JetsamFixture.firstDifference(afterFirst, afterSecond) == nil)
// A third pass must not drift either.
let third = try CustomFirmwareJetsamPatcher.patch(fileAt: target, log: nil)
#expect(third.verdict == .alreadyPatched)
let afterThird = try Data(contentsOf: target)
#expect(JetsamFixture.firstDifference(afterFirst, afterThird) == nil)
}
/// Where the reference went wrong, and the measurement that showed it: run
/// twice, and it landed a *second* site the pristine image never had
/// patched. Frozen, so the divergence stays a measurement, not a claim.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `reference was not idempotent and this is`() throws {
let work = try JetsamFixture.workDirectory("reference-double-apply")
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
// The frozen half: the reference's second run moved the file, and to a
// different instruction than the gate it had already rewritten.
#expect(
JetsamGolden.patchedTwice != JetsamGolden.patched,
"the reference was recorded as non-idempotent — re-check what this port has to preserve",
)
#expect(JetsamGolden.secondRunGateOffset != JetsamGolden.gateOffset)
// The Swift half, measured: run once, land on the reference's one-run
// bytes; run again, and nothing moves.
try CustomFirmwareJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
let swiftOnce = try Data(contentsOf: swiftTarget)
#expect(Data(SHA256.hash(data: swiftOnce)).hex == JetsamGolden.patched)
try CustomFirmwareJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
let swiftTwice = try Data(contentsOf: swiftTarget)
#expect(JetsamFixture.firstDifference(swiftOnce, swiftTwice) == nil)
#expect(Data(SHA256.hash(data: swiftTwice)).hex != JetsamGolden.patchedTwice)
// And the instruction the reference's second run would have taken is
// still the one the pristine image carries there.
let pristine = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let second = JetsamGolden.secondRunGateOffset ..< JetsamGolden.secondRunGateOffset + 4
#expect(Data(swiftTwice[second]) == Data(pristine[second]))
}
}
// MARK: - Re-attestation
@Suite("launchd jetsam guard — signature re-attestation")
struct CustomFirmwareJetsamSignatureTests {
/// Default is the reference's behaviour: the four bytes and nothing else,
/// because every call site re-signs with `ldid` straight afterwards.
@Test(.enabled(if: JetsamFixture.hasLaunchdAndCodesign))
func `default leaves the signature stale`() throws {
let work = try JetsamFixture.workDirectory("stale-signature")
let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
let outcome = try CustomFirmwareJetsamPatcher.patch(fileAt: target, log: nil)
#expect(outcome.rehashes.isEmpty)
let verify = try JetsamFixture.run(JetsamFixture.codesign, ["-v", target.path])
#expect(verify.status != 0, "a patch with no re-attestation must not still verify")
}
/// `reattest: true` has to leave a binary `codesign` accepts — one page's
/// slot hash, recomputed, tail slot included.
@Test(.enabled(if: JetsamFixture.hasLaunchdAndCodesign))
func `reattested binary verifies`() throws {
let work = try JetsamFixture.workDirectory("reattested")
let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
let outcome = try CustomFirmwareJetsamPatcher.patch(fileAt: target, reattest: true, log: nil)
#expect(outcome.verdict == .patched)
#expect(outcome.rehashes.count == 1)
let rehash = try #require(outcome.rehashes.first)
let patched = try Data(contentsOf: target)
let directory = try #require(
CustomFirmwareMachOCodeSignature.codeDirectories(in: patched)?
.first { $0.hashType == CustomFirmwareMachOCodeSignature.hashTypeSHA256 },
)
#expect(rehash.pageIndex == outcome.gateOffset / directory.pageSize)
let verify = try JetsamFixture.run(JetsamFixture.codesign, ["-v", target.path])
#expect(verify.status == 0, "codesign -v rejected the re-attested binary:\n\(verify.output)")
}
/// The slot hash itself, against the frozen output of the Python's
/// independent re-signer run over the Python's own patched bytes. Two
/// implementations, one number.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `slot hash matches the frozen resigner`() throws {
let work = try JetsamFixture.workDirectory("slot-hash")
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
let outcome = try CustomFirmwareJetsamPatcher.patch(fileAt: swiftTarget, reattest: true, log: nil)
#expect(outcome.verdict == .patched)
#expect(outcome.gateOffset == JetsamGolden.gateOffset)
#expect(outcome.rehashes.first?.pageIndex == JetsamGolden.reattestedSlot)
#expect(
try JetsamFixture.digest(of: swiftTarget) == JetsamGolden.patchedAndReattested,
"the re-attested slot hash must be the one the reference computed",
)
}
}
// MARK: - Anchoring, without a reference
@Suite("launchd jetsam guard — anchoring")
struct CustomFirmwareJetsamAnchoringTests {
/// Every step of the reveal lands where the disassembly says it should:
/// the xref is inside the function, the gate is inside the function and
/// before the xref, and the gate's target really does return.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `reveal steps are self consistent`() throws {
let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let image = try CustomFirmwareJetsamPatcher.Image(data: data)
let site = try #require(try CustomFirmwareJetsamPatcher.locate(in: image))
#expect(CustomFirmwareJetsamPatcher.panicStringAnchors.contains(site.anchor))
#expect(!site.isAlreadyPatched)
#expect(site.functionOffset <= site.gateOffset)
#expect(site.gateOffset < site.xrefOffset)
#expect(image.isInText(site.xrefOffset))
#expect(image.isInText(site.returnBlockOffset))
#expect(CustomFirmwareJetsamPatcher.isReturnBlock(site.returnBlockOffset, in: image))
// The function bound is a real prologue, not the blind fallback.
#expect(data.loadLE(UInt32.self, at: site.functionOffset) == ARM64.pacibspU32)
// The anchor string starts where the xref computes it to start.
let page = CustomFirmwareJetsamPatcher.adrpPage(
data.loadLE(UInt32.self, at: site.xrefOffset),
at: image.virtualAddress(ofTextOffset: site.xrefOffset),
)
#expect(site.stringVMA & ~0xFFF == page)
// The gate is a conditional branch, and it branches to the return block.
let disassembler = ARM64Disassembler()
let gate = try #require(disassembler.disassembleOne(in: data, at: site.gateOffset))
#expect(CustomFirmwareJetsamPatcher.conditionalBranchMnemonics.contains(gate.mnemonic))
#expect(CustomFirmwareJetsamPatcher.branchTarget(gate) == site.returnBlockOffset)
}
/// The gate is the *earliest* qualifying branch in the function — any later
/// one leaves more of the jetsam path running.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `gate is the earliest qualifying branch`() throws {
let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let image = try CustomFirmwareJetsamPatcher.Image(data: data)
let site = try #require(try CustomFirmwareJetsamPatcher.locate(in: image))
let disassembler = ARM64Disassembler()
for offset in stride(from: site.functionOffset, to: site.gateOffset, by: 4) {
guard let insn = disassembler.disassembleOne(in: data, at: offset),
CustomFirmwareJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic)
|| insn.mnemonic == "b",
let target = CustomFirmwareJetsamPatcher.branchTarget(insn),
image.isInText(target)
else { continue }
#expect(
!CustomFirmwareJetsamPatcher.isReturnBlock(target, in: image),
"0x\(String(offset, radix: 16)) qualifies and is earlier than the chosen gate",
)
}
}
/// Rewriting the gate is what makes the second pass a no-op, and the scan
/// has to see that on its own — the site it would pick on a re-run is a
/// different, later branch, so checking the picked site afterwards would
/// not catch it.
@Test(.enabled(if: JetsamFixture.hasLaunchd))
func `patched shape is recognised in place`() throws {
var data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let outcome = try CustomFirmwareJetsamPatcher.patch(&data, log: nil)
#expect(outcome.verdict == .patched)
let image = try CustomFirmwareJetsamPatcher.Image(data: data)
let site = try #require(try CustomFirmwareJetsamPatcher.locate(in: image))
#expect(site.isAlreadyPatched)
#expect(site.gateOffset == outcome.gateOffset)
#expect(site.returnBlockOffset == outcome.returnBlockOffset)
// And the later branch the reference would fall back to really is
// there, live, into the same return block — which is why the check has
// to live inside the scan.
let gate = try #require(CustomFirmwareJetsamPatcher.findReturnGate(
from: site.gateOffset + 4,
to: site.xrefOffset,
in: image,
))
#expect(!gate.isUnconditional)
#expect(gate.offset > outcome.gateOffset)
#expect(gate.target == outcome.returnBlockOffset)
}
}
// MARK: - Decoders and encoders
@Suite("launchd jetsam guard — instruction decoding")
struct CustomFirmwareJetsamDecodeTests {
/// `ADD Xd, Xn, #imm12, LSL #0` only — an `LSL #12` form or a
/// shifted-register add would make the xref land on the wrong string.
@Test
func `add immediate predicate rejects the neighbours`() throws {
let disassembler = ARM64Disassembler()
// The real thing: the ADD half of the string xref, straight out of the
// project encoder rather than typed in.
let addImm = try #require(ARM64Encoder.encodeAddImm12(rd: 0, rn: 0, imm12: 0xA09))
let decoded = try #require(disassembler.disassembleOne(addImm, at: 0))
#expect(decoded.mnemonic == "add")
#expect(CustomFirmwareJetsamPatcher.isAddImm64(addImm.loadLE(UInt32.self, at: 0)))
// And the neighbours it must not accept.
#expect(!CustomFirmwareJetsamPatcher.isAddImm64(0x9140_0000)) // add x0, x0, #0, lsl #12
#expect(!CustomFirmwareJetsamPatcher.isAddImm64(0x1100_0000)) // add w0, w0, #0 (32-bit)
#expect(!CustomFirmwareJetsamPatcher.isAddImm64(0x8B08_1534)) // add x20, x9, x8, lsl #5
#expect(!CustomFirmwareJetsamPatcher.isAddImm64(0xD100_0000)) // sub x0, x0, #0
}
/// `adrpPage` against Capstone, which resolves the page for us. The inputs
/// come from `ARM64Encoder.encodeADRP`, so nothing here is a typed-in word.
@Test
func `adrp page agrees with capstone`() throws {
let disassembler = ARM64Disassembler()
for (pc, target) in [
(UInt64(0x1_0000_FB0C), UInt64(0x1_0006_5A09)), // forward
(UInt64(0x1_0000_0000), UInt64(0x1_0000_0FFF)), // same page
(UInt64(0x1_0005_0000), UInt64(0x1_0000_1234)), // backward
] {
let encoded = try #require(ARM64Encoder.encodeADRP(rd: 0, pc: pc, target: target))
let insn = try #require(disassembler.disassembleOne(encoded, at: pc))
let operands = try #require(insn.detail?.operands)
#expect(insn.mnemonic == "adrp")
#expect(operands.count >= 2 && operands[1].type == .immediate)
let word = encoded.loadLE(UInt32.self, at: 0)
#expect(CustomFirmwareJetsamPatcher.adrpPage(word, at: pc) == UInt64(operands[1].imm))
#expect(CustomFirmwareJetsamPatcher.adrpPage(word, at: pc) == target & ~0xFFF)
}
}
/// The replacement is `ARM64Encoder`'s, and it decodes back to a `b` at the
/// intended target — never a hand-written instruction word.
@Test
func `replacement branch round trips`() throws {
let disassembler = ARM64Disassembler()
for (site, target) in [(0xFA98, 0xFAEC), (0x1000, 0x800), (0x40, 0x40)] {
let encoded = try #require(ARM64Encoder.encodeB(from: site, to: target))
let insn = try #require(disassembler.disassembleOne(encoded, at: UInt64(site)))
#expect(insn.mnemonic == "b")
#expect(CustomFirmwareJetsamPatcher.branchTarget(insn) == target)
}
}
/// The return-block probe rests entirely on two questions — "does this
/// return?" and "does control leave here?" — and both are answered from
/// Capstone's instruction groups. Pinned against real decodes, because a
/// mnemonic prefix gets each of the last three rows below wrong: `brk` is
/// not a branch, and a conditional branch falls through.
@Test
func `block boundaries come from capstone groups`() throws {
let disassembler = ARM64Disassembler()
func decode(_ bytes: Data) throws -> ARM64Instruction {
try #require(disassembler.disassembleOne(bytes, at: 0))
}
// Returns, from the project's own pre-encoded constants.
for bytes in [ARM64.ret, ARM64.retaa, ARM64.retab] {
let insn = try decode(bytes)
#expect(CustomFirmwareJetsamPatcher.isReturn(insn))
}
// Control leaves: an unconditional relative jump and a relative call,
// both straight out of `ARM64Encoder`.
for bytes in try [
#require(ARM64Encoder.encodeB(from: 0, to: 8)),
#require(ARM64Encoder.encodeBL(from: 0, to: 8)),
] {
let insn = try decode(bytes)
#expect(CustomFirmwareJetsamPatcher.leavesBlock(insn))
#expect(!CustomFirmwareJetsamPatcher.isReturn(insn))
}
// The register-indirect forms, and the breakpoint that a `hasPrefix("br")`
// test would have mistaken for one. No encoder writes these — no patch
// emits them — so the words come from the ISA field layout and every
// claim about them is checked against Capstone's decode.
let indirect: [(UInt32, String, Bool)] = [
(0xD61F_0000, "br", true), // br x0
(0xD63F_0000, "blr", true), // blr x0
(0xD420_0000, "brk", false), // brk #0 — an exception, not a branch
]
for (word, mnemonic, ends) in indirect {
let insn = try decode(ARM64.encodeU32(word))
#expect(insn.mnemonic == mnemonic)
#expect(CustomFirmwareJetsamPatcher.leavesBlock(insn) == ends)
#expect(!CustomFirmwareJetsamPatcher.isReturn(insn))
}
// Conditional branches fall through, so they end nothing — this is what
// lets a `b.cond` sit inside the return block being probed.
let conditional: [UInt32] = [
0x5400_0000 | (2 << 5), // b.eq #8
0x3400_0000 | (2 << 5), // cbz w0, #8
0x3600_0000 | (2 << 5), // tbz w0, #0, #8
]
for word in conditional {
let insn = try decode(ARM64.encodeU32(word))
#expect(CustomFirmwareJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic))
#expect(!CustomFirmwareJetsamPatcher.leavesBlock(insn))
#expect(!CustomFirmwareJetsamPatcher.isReturn(insn))
}
}
/// `cbz`/`tbz` put the target last; reading the last immediate is what
/// keeps one code path covering all of them.
@Test
func `branch target reads the last immediate`() throws {
let disassembler = ARM64Disassembler()
// tbz w8, #1, #8 — three operands, target last, from the encoder.
let tbz = try #require(ARM64Encoder.encodeTestBitBranch(
nonzero: false,
register: 8,
bit: 1,
from: 0,
to: 8,
))
let tbzInsn = try #require(disassembler.disassembleOne(tbz, at: 0))
#expect(tbzInsn.mnemonic == "tbz")
#expect(CustomFirmwareJetsamPatcher.branchTarget(tbzInsn) == 8)
// cbz w0, #8 and b.eq #8 — two and one operand. Neither has an encoder
// in `ARM64Encoder` (no patch writes one), so the words are built here
// from the ISA field layout and checked against Capstone's decode.
let cbz: UInt32 = 0x3400_0000 | (2 << 5) // imm19 = 8 / 4
let beq: UInt32 = 0x5400_0000 | (2 << 5) // imm19 = 8 / 4, cond = EQ
for word in [cbz, beq] {
let insn = try #require(disassembler.disassembleOne(ARM64.encodeU32(word), at: 0))
#expect(CustomFirmwareJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic))
#expect(CustomFirmwareJetsamPatcher.branchTarget(insn) == 8)
}
}
/// A substring anchor has to widen to the whole C string, because that is
/// what an ADRP+ADD points at.
@Test
func `c string start widens to the whole string`() throws {
var bytes = Data("first\u{0}jetsam property category (%s) is not initialized\u{0}".utf8)
var hit = try #require(bytes.range(of: Data("property".utf8))?.lowerBound)
#expect(CustomFirmwareJetsamPatcher.cStringStart(in: bytes, containing: hit, sectionStart: 0) == 6)
// A string that starts at the section's first byte has no NUL in front.
bytes = Data("jetsam property category\u{0}".utf8)
hit = try #require(bytes.range(of: Data("property".utf8))?.lowerBound)
#expect(CustomFirmwareJetsamPatcher.cStringStart(in: bytes, containing: hit, sectionStart: 0) == 0)
}
}