Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Fix standalone CIBarcode X1 crashes on iOS 27.1

Xingchuan Ma5e784733cf1b
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 521063c8..2f33e969 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -430,6 +430,29 @@
> reached, because the manager's construction needs haptics hardware a
> VM does not have). See the full section below.
+> **CIBarcode standalone X1 lowering (2026-10-29, local validation):**
+> `system-cibarcode-cfw-arm64e_x1` applies the existing static X1 planner to
+> `/System/Library/CoreImage/CIBarcode.cifilter/CIBarcode`, outside the shared
+> cache. It is gated to iOS 27.1, enabled in `standard`, and blocked in the TV
+> and HomePod presets. The measured 24A94425 image UUID is
+> `807AC7DC-7FE2-3E60-BA1B-0E879FF70012`. After whole-cache lowering, an app
+> reached its normal main run loop but faulted on a utility queue in this
+> image at relative address 5960 with `EXC_BAD_INSTRUCTION` / `0xDAC1A7FE`,
+> called by `+[CIFilter(CIFilterRegistryPrivate) filterWithName:setDefaults:]`.
+> This offset is evidence only; the patch discovers reachable instructions
+> through the existing planner, not a fixed offset. The installer stages from
+> `.bak`, re-attests/signs and seals the filter bundle, and restores the backup
+> when deselected. On the pulled stock image, the planner lowered 425
+> instructions, re-attested 19 slots, and left zero unvisited candidates;
+> the recorded fault site was lowered and a second pass was byte-identical.
+> The X1 and catalogue suites passed (39 tests). An environment update on an
+> existing M3 Max Duo preserved a byte-identical original `.bak` and recorded
+> the new patch in its Guest receipt. The previously crashing app reached its
+> home screen in both open and closed postures without a new CIBarcode crash.
+> App-specific environment-risk checks remain active; login and transactions
+> were not tested. The build used local Xcode 26 compatibility adjustments
+> outside this patch. A full multi-firmware golden corpus was not available.
+
> **ARM64E_X1 whole-cache lowering (2026-10-23):** `dyld-cfw-arm64e_x1_cache`
> (guest system set, iOS 27, on in `standard`, blocked in `tvos` and
> `tvos-4k`; verb `cfw patch-arm64e-x1-cache`) lowers the X1 instructions of
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
index 4d84cb5e..e6bebe79 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
@@ -40,6 +40,9 @@ public enum FirmwareGuestSystemPatchSet {
public static let arm64eX1LaunchdBootstrap = "system-launchd-boot-arm64e_x1_bootstrap"
public static let arm64eX1FsckBootstrap = "system-fsck-boot-arm64e_x1_bootstrap"
public static let arm64eX1MountBootstrap = "system-mount-boot-arm64e_x1_bootstrap"
+ public static let arm64eX1CIBarcode = "system-cibarcode-cfw-arm64e_x1"
+ public static let ciBarcodeBundlePath = "System/Library/CoreImage/CIBarcode.cifilter"
+ public static let ciBarcodeExecutablePath = ciBarcodeBundlePath + "/CIBarcode"
public static let paravirtGPUIndexOffset = "system-paravirt_gpu-cfw-heap_index_offset"
public static let paravirtGPUDriverPath =
@@ -313,6 +316,17 @@ public enum FirmwareGuestSystemPatchSet {
applicability: ios27,
bootEssential: true,
),
+ VPhonePatchDeclaration(
+ identifier: arm64eX1CIBarcode,
+ title: "ARM64E_X1 barcode filters",
+ summary: """
+ Lowers the standalone CIBarcode plug-in before apps load its barcode filters. \
+ This image is outside the shared cache, so whole-cache lowering cannot prevent \
+ its remaining X1 instruction faults.
+ """,
+ target: .guestExecutable(path: "/" + ciBarcodeExecutablePath),
+ applicability: VPhonePatchApplicability(iOSBase: .release(major: 27, minor: 1)),
+ ),
VPhonePatchDeclaration(
identifier: "system-seputil-boot-gigalocker_uuid",
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index b3cb792e..e0178f42 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -238,6 +238,7 @@ public enum FirmwarePatchSetCatalog {
paravirtTask3Patch,
FirmwareGuestSystemPatchSet.arm64eX1CacheBootstrap,
FirmwareGuestSystemPatchSet.arm64eX1CacheRemaining,
+ FirmwareGuestSystemPatchSet.arm64eX1CIBarcode,
"dyld-boot-iomfb_force_kern",
"dyld-boot-iomfb_swapend",
"dyld-boot-lockdown_mode",
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareArm64eX1Tests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareArm64eX1Tests.swift
index 05c26312..f9a57932 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareArm64eX1Tests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareArm64eX1Tests.swift
@@ -76,6 +76,26 @@ struct CustomFirmwareArm64eX1Tests {
}
}
+ @Test func `standalone bundle lowering attests code and is idempotent`() throws {
+ var (image, hashOffset) = Self.signedFixture()
+ // Core Image filters use MH_BUNDLE rather than the boot executables'
+ // MH_EXECUTE. Recompute the fixture signature after changing its header.
+ image.replaceSubrange(12 ..< 16, with: ARM64.encodeU32(8))
+ image.replaceSubrange(
+ hashOffset ..< hashOffset + 32,
+ with: Data(SHA256.hash(data: image.prefix(0x400))),
+ )
+ let identifier = FirmwareGuestSystemPatchSet.arm64eX1CIBarcode
+ let first = try CustomFirmwareArm64eX1.lowerAndReattest(&image, identifier: identifier)
+ #expect(first.result.records.count == 2)
+ #expect(first.slots.count == 1)
+ #expect(image.loadLE(UInt32.self, at: 12) == 8)
+ let patched = image
+ let second = try CustomFirmwareArm64eX1.lowerAndReattest(&image, identifier: identifier)
+ #expect(second.result.records.isEmpty)
+ #expect(image == patched)
+ }
+
static func universal(_ first: Data, _ second: Data, wide: Bool = false) -> Data {
func be<T: FixedWidthInteger>(_ value: T) -> Data { withUnsafeBytes(of: value.bigEndian) { Data($0) } }
var data = be(UInt32(wide ? 0xCAFE_BABF : 0xCAFE_BABE)) + be(UInt32(2))
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index 0f3b3404..f0185e28 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@ -17,6 +17,26 @@ import VPhonePatchKit
@Suite("Bundled patch set catalogue")
struct FirmwarePatchSetCatalogTests {
+ @Test func `CIBarcode lowering is scoped to the measured base and can be disabled`() throws {
+ let identifier = FirmwareGuestSystemPatchSet.arm64eX1CIBarcode
+ for base in ["26.4", "27.0.1", "27.1", "27.1.1", "27.2", "28.0"] {
+ for blocked in [false, true] {
+ var preset = FirmwarePatchSetCatalog.standardPreset
+ if blocked {
+ preset.selection = preset.selection.blocking([identifier])
+ }
+ let plan = try VPhonePatchPlan.resolve(
+ preset: preset,
+ patchSets: FirmwarePatchSetCatalog.bundled,
+ iOSBase: VPhoneVersion(base),
+ cloudOS: VPhoneVersion("26.4"),
+ )
+ let supported = base == "27.1" || base.hasPrefix("27.1.")
+ #expect(plan.isEnabled(identifier) == (supported && !blocked))
+ }
+ }
+ }
+
@Test(arguments: [FirmwareGuestSystemPatchSet.gyroscope, FirmwareGuestSystemPatchSet.accelerometer, FirmwareGuestSystemPatchSet.attitude])
func `Motion sensors follow selection and their deployment target`(identifier: String) throws {
for base in ["18.6.2", "26.4", "27.0.1"] {
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index b8aa9198..0f637d5b 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -1431,6 +1431,23 @@ struct VPhoneCustomFirmwareInstaller {
try requireX1Bootstrap()
}
+ // CIBarcode is a standalone Core Image plug-in, outside the shared cache.
+ // Lower it ahead of time rather than relying on an application's inherited
+ // exception handler to translate these instructions at runtime.
+ // The normal Mach-O path keeps a pristine backup and re-seals the bundle;
+ // deselecting the declaration restores it on the next environment update.
+ if version.hasPrefix("27.1.") || version == "27.1"
+ || priorGuest.contains(FirmwareGuestSystemPatchSet.arm64eX1CIBarcode)
+ {
+ machO(
+ FirmwareGuestSystemPatchSet.arm64eX1CIBarcode,
+ path: FirmwareGuestSystemPatchSet.ciBarcodeExecutablePath,
+ verbs: ["patch-arm64e-x1"],
+ preserveEntitlements: true,
+ bundle: FirmwareGuestSystemPatchSet.ciBarcodeBundlePath,
+ )
+ }
+
// 0. A cache whose span alone overruns the guest kernel's shared region
// maps at no slide, and the guest panics on first boot. Refuse before
// the redeploy and the cache patches. A header this check cannot read
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareMachOVerbsCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareMachOVerbsCommand.swift
index 8d252559..80096e85 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareMachOVerbsCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareMachOVerbsCommand.swift
@@ -45,8 +45,11 @@ private let machOVerbLog: @Sendable (String) -> Void = { print($0) }
struct VPhoneCustomFirmwarePatchArm64eX1Command: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "patch-arm64e-x1",
- abstract: "Lower X1 instructions in a boot-critical executable",
- discussion: "Supports dyld, launchd, fsck and mount. Later userland instructions are handled on demand. Re-attests modified code pages.",
+ abstract: "Lower X1 instructions in a supported standalone executable",
+ discussion: """
+ Supports dyld, launchd, fsck, mount and CIBarcode. Other standalone userland \
+ instructions are handled on demand. Re-attests modified code pages.
+ """,
)
@Argument(transform: URL.init(fileURLWithPath:)) var binary: URL
func run() throws {
@@ -57,8 +60,9 @@ struct VPhoneCustomFirmwarePatchArm64eX1Command: ParsableCommand {
case "launchd": identifier = FirmwareGuestSystemPatchSet.arm64eX1LaunchdBootstrap
case "fsck": identifier = FirmwareGuestSystemPatchSet.arm64eX1FsckBootstrap
case "mount": identifier = FirmwareGuestSystemPatchSet.arm64eX1MountBootstrap
+ case "CIBarcode": identifier = FirmwareGuestSystemPatchSet.arm64eX1CIBarcode
default:
- throw ValidationError("X1 static lowering is limited to the measured boot roots: dyld, launchd, fsck and mount")
+ throw ValidationError("X1 static lowering supports only dyld, launchd, fsck, mount and CIBarcode")
}
try CustomFirmwareArm64eX1.patch(
fileAt: binary,
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
index 58bde238..80c99115 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
@@ -98,6 +98,7 @@
<string>dyld-boot-iomfb_swapend</string>
<string>dyld-cfw-camera</string>
<string>dyld-cfw-arm64e_x1_cache</string>
+ <string>system-cibarcode-cfw-arm64e_x1</string>
<string>kernel-boot-arm64e_x1</string>
<string>kernel-boot-cssc_emulation</string>
<string>preboot-cfw-devicetree_board_audio</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
index cd06e162..6df5c776 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
@@ -109,6 +109,7 @@
<string>dyld-boot-iomfb_swapend</string>
<string>dyld-cfw-camera</string>
<string>dyld-cfw-arm64e_x1_cache</string>
+ <string>system-cibarcode-cfw-arm64e_x1</string>
<string>kernel-boot-arm64e_x1</string>
<string>kernel-boot-cssc_emulation</string>
<string>preboot-cfw-devicetree_board_audio</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
index 3252a6fa..9e2aaa02 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
@@ -112,6 +112,7 @@
<string>dyld-boot-xpc_lwcr</string>
<string>dyld-cfw-camera</string>
<string>dyld-cfw-arm64e_x1_cache</string>
+ <string>system-cibarcode-cfw-arm64e_x1</string>
<string>kernel-boot-arm64e_x1</string>
<string>kernel-boot-cssc_emulation</string>
<string>preboot-cfw-devicetree_board_audio</string>