Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Kernelcache recipes per guest family, with ordered kext sources

Maximilian Paß71b41fe5db2f
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheKDK.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheKDK.swift
index a64acfa0..79161fc5 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheKDK.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheKDK.swift
@@ -58,6 +58,16 @@ enum KernelCacheKDK {
/// listed bundles that only `donor` has (at their bundle paths). Nested bundles
/// keep their parents' directories.
static func mix(base: URL, donor: URL, wanted: [String], output: URL) throws -> (removed: [String], added: [String]) {
+ let (removed, added) = try mix(base: base, sources: [base, donor], wanted: wanted, output: output)
+ return (removed, added[donor] ?? [])
+ }
+
+ /// Copy `base` to `output` and keep the bundles listed in `wanted`, each from
+ /// the first of `sources` (which includes `base`) that has it; the kernel's
+ /// KPI bundles (System.kext) always stay the base's. Nested bundles keep
+ /// their parents' directories. Returns the base bundles dropped and the
+ /// bundles added from each other source.
+ static func mix(base: URL, sources: [URL], wanted: [String], output: URL) throws -> (removed: [String], added: [URL: [String]]) {
let fm = FileManager.default
let wantedSet = Set(wanted)
if fm.fileExists(atPath: output.path) { try fm.removeItem(at: output) }
@@ -66,13 +76,33 @@ enum KernelCacheKDK {
let outExtensions = output.appending(path: "System/Library/Extensions")
let have = try bundles(in: output)
+ let available = try sources.map { $0 == base ? have : try bundles(in: $0) }
+ func isKPI(_ relative: String) -> Bool {
+ relative == "System.kext" || relative.hasPrefix("System.kext/")
+ }
+ var owner: [String: Int] = [:]
+ for id in wantedSet {
+ if let relative = have[id], isKPI(relative) {
+ owner[id] = sources.firstIndex(of: base)
+ } else {
+ owner[id] = available.indices.first { index in
+ available[index][id].map { sources[index] == base || !isKPI($0) } ?? false
+ }
+ }
+ }
+ let missing = wantedSet.filter { owner[$0] == nil }
+ guard missing.isEmpty else {
+ throw PatcherError.fileNotFound("kexts in none of the mix's KDKs: \(missing.sorted().joined(separator: ", "))")
+ }
+ let keptFromBase = Set(wantedSet.filter { sources[owner[$0]!] == base })
+
var removed: [String] = []
// Deepest bundles first, so plug-ins go before their parents.
for (id, relative) in have.sorted(by: { $0.value.split(separator: "/").count > $1.value.split(separator: "/").count }) {
let path = outExtensions.appending(path: relative)
- guard !wantedSet.contains(id), fm.fileExists(atPath: path.path) else { continue }
+ guard !keptFromBase.contains(id), fm.fileExists(atPath: path.path) else { continue }
let keepsWantedPlugin = have.contains { other in
- wantedSet.contains(other.key) && other.value != relative && other.value.hasPrefix(relative + "/")
+ keptFromBase.contains(other.key) && other.value != relative && other.value.hasPrefix(relative + "/")
}
if keepsWantedPlugin {
// Keep the directory for its plug-ins, but not the bundle itself.
@@ -84,22 +114,20 @@ enum KernelCacheKDK {
continue
}
try fm.removeItem(at: path)
- removed.append(id)
- }
-
- let donated = try bundles(in: donor)
- let donorExtensions = donor.appending(path: "System/Library/Extensions")
- var added: [String] = []
- for id in wantedSet.subtracting(have.keys).sorted() {
- guard let relative = donated[id] else { continue }
- // Nested plug-ins are copied for their own identifiers.
- try copyTree(from: donorExtensions.appending(path: relative), to: outExtensions.appending(path: relative), skipping: "PlugIns")
- added.append(id)
+ if !wantedSet.contains(id) {
+ removed.append(id)
+ }
}
- let missing = wantedSet.subtracting(have.keys).subtracting(added)
- guard missing.isEmpty else {
- throw PatcherError.fileNotFound("kexts in neither the base nor the donor KDK: \(missing.sorted().joined(separator: ", "))")
+ var added: [URL: [String]] = [:]
+ for (index, source) in sources.enumerated() where source != base {
+ let extensions = source.appending(path: "System/Library/Extensions")
+ for id in wantedSet.filter({ owner[$0] == index }).sorted() {
+ let relative = available[index][id]!
+ // Nested plug-ins are copied for their own identifiers.
+ try copyTree(from: extensions.appending(path: relative), to: outExtensions.appending(path: relative), skipping: "PlugIns")
+ added[source, default: []].append(id)
+ }
}
return (removed.sorted(), added)
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheMixer.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheMixer.swift
index fa4e02b0..3421e532 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheMixer.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheMixer.swift
@@ -64,15 +64,31 @@ public final class KernelCacheMixer {
// MARK: - Identification
- public func base(for kernelcache: Data) throws -> KernelCacheBase {
- if let base = try recipes.base(forKernelcache: kernelcache) {
+ /// A research board kernelcache to rebuild, and the guest it boots.
+ public struct Input {
+ /// The kernelcache as shipped (IM4P or decompressed).
+ public let kernelcache: Data
+ /// `VPhoneGuestDevice.Family` raw value of the guest.
+ public let guest: String
+ /// The VM's restore tree, which holds a donor the guest's IPSW ships.
+ public let restoreTree: URL
+
+ public init(kernelcache: Data, guest: String, restoreTree: URL) {
+ self.kernelcache = kernelcache
+ self.guest = guest
+ self.restoreTree = restoreTree
+ }
+ }
+
+ public func base(for input: Input) throws -> KernelCacheBase {
+ if let base = try recipes.base(forKernelcache: input.kernelcache, guest: input.guest) {
return base
}
- let supported = (try? recipes.bases().map(\.id).joined(separator: ", ")) ?? "none"
+ let supported = (try? recipes.bases().map { ($0.guest.map { "\($0) " } ?? "iOS ") + $0.id }.joined(separator: ", ")) ?? "none"
throw PatcherError.invalidFormat(
"this cloudOS has no vphone600 components, and no kernelcache recipe covers its research board kernelcache "
- + "(SHA-256 \(KernelCacheRecipes.sha256(kernelcache))) to rebuild with the virtualisation kexts; "
- + "recipes exist for iOS \(supported)",
+ + "(SHA-256 \(KernelCacheRecipes.sha256(input.kernelcache))) for this \(input.guest) guest "
+ + "to rebuild with the virtualisation kexts; recipes exist for \(supported)",
)
}
@@ -80,18 +96,18 @@ public final class KernelCacheMixer {
/// with. `fw prepare` asks, so a cloudOS no recipe covers is refused before
/// anything is patched.
public static func recipe(forRestoreTree restoreDir: URL) throws -> KernelCacheBase {
- try KernelCacheMixer(recipes: .locate(), verbose: false).base(for: kernelcache(inRestoreTree: restoreDir))
+ try KernelCacheMixer(recipes: .locate(), verbose: false).base(for: input(forRestoreTree: restoreDir))
}
/// Throws what `mix` would for `restoreDir`, without building anything.
/// `vm create` asks as soon as `fw prepare` finds the recipe, not at
/// `fw patch` after the restores.
public static func checkMixable(restoreTree restoreDir: URL) throws {
- let kernelcache = try kernelcache(inRestoreTree: restoreDir)
+ let input = try Self.input(forRestoreTree: restoreDir)
let mixer = try KernelCacheMixer(recipes: .locate(), verbose: false)
- let state = try mixer.state(for: kernelcache)
+ let state = try mixer.state(for: input)
guard state != .mixed else { return }
- try KernelCollectionBuilder.checkLayout(for: mixer.locations(for: kernelcache).base)
+ try KernelCollectionBuilder.checkLayout(for: mixer.locations(for: input).base)
guard geteuid() == 0 else {
throw PatcherError.invalidFormat(linkInstructions(staged: state == .staged))
}
@@ -100,9 +116,10 @@ public final class KernelCacheMixer {
}
}
- static func kernelcache(inRestoreTree restoreDir: URL) throws -> Data {
+ static func input(forRestoreTree restoreDir: URL) throws -> Input {
let path = try FirmwarePipeline.manifestComponentPath("RestoreKernelCache", in: restoreDir)
- return try Data(contentsOf: restoreDir.appending(path: path), options: .mappedIfSafe)
+ let data = try Data(contentsOf: restoreDir.appending(path: path), options: .mappedIfSafe)
+ return Input(kernelcache: data, guest: FirmwarePipeline.guestFamily(restoreDir: restoreDir), restoreTree: restoreDir)
}
// MARK: - Mix
@@ -117,8 +134,8 @@ public final class KernelCacheMixer {
case missing
}
- public func state(for kernelcache: Data) throws -> State {
- let (_, paths) = try locations(for: kernelcache)
+ public func state(for input: Input) throws -> State {
+ let (_, paths) = try locations(for: input)
if FileManager.default.fileExists(atPath: paths.mixed.path) {
return .mixed
}
@@ -128,9 +145,9 @@ public final class KernelCacheMixer {
/// The mixed kernelcache (an IMG4 `krnl` container) for a research board
/// one: from the cache, linked from a staged volume (root), or staged and
/// linked in one go (root with `VPHONE_IPSW`).
- public func mix(kernelcache: Data) throws -> Data {
- let (base, paths) = try locations(for: kernelcache)
- log(" [kc] base \(base.id) (iOS \(base.productVersion)), donor \(base.donor)")
+ public func mix(_ input: Input) throws -> Data {
+ let (base, paths) = try locations(for: input)
+ log(" [kc] base \(base.id) (\(base.productVersion)), donors \(base.donors.joined(separator: ", "))")
if let data = try? Data(contentsOf: paths.mixed), !data.isEmpty {
log(" [kc] using the cached mix \(paths.mixed.path)")
return data
@@ -139,19 +156,19 @@ public final class KernelCacheMixer {
throw PatcherError.invalidFormat(Self.linkInstructions(staged: Self.isStaged(paths.staged)))
}
if !Self.isStaged(paths.staged) {
- try stage(kernelcache: kernelcache)
+ try stage(input)
}
- return try link(kernelcache: kernelcache)
+ return try link(input)
}
/// Extracts both kernelcaches and stages the volume kmutil links, as the
/// invoking user: the one step that runs `ipsw`. Does nothing when the mix
/// or its volume is already in the cache.
- public func stage(kernelcache: Data, ipsw ipswPath: String? = nil) throws {
- let (base, paths) = try locations(for: kernelcache)
+ public func stage(_ input: Input, ipsw ipswPath: String? = nil) throws {
+ let (base, paths) = try locations(for: input)
guard !FileManager.default.fileExists(atPath: paths.mixed.path), !Self.isStaged(paths.staged) else { return }
try KernelCollectionBuilder.checkLayout(for: base)
- let donor = try recipes.donor(id: base.donor)
+ let donors = try base.donors.map { try recipes.donor(id: $0) }
let ipsw = try Self.ipsw(ipswPath)
let fm = FileManager.default
@@ -160,8 +177,8 @@ public final class KernelCacheMixer {
try fm.createDirectory(at: work, withIntermediateDirectories: true)
log(" [kc] staging in \(paths.staged.path)")
- let donorKDK = try donorKDK(donor, ipsw: ipsw)
- let payload = try Self.payload(of: kernelcache)
+ let donorKDKs = try donors.map { try donorKDK($0, restoreTree: input.restoreTree, ipsw: ipsw) }
+ let payload = try Self.payload(of: input.kernelcache)
try Self.check(payload, base.kernel.decompressedSHA256, "decompressed \(base.kernel.file)")
let decompressed = work.appending(path: "\(base.kernel.file).decompressed")
try payload.write(to: decompressed)
@@ -173,8 +190,12 @@ public final class KernelCacheMixer {
let identifiers = try base.kextIdentifiers()
let mixKDK = work.appending(path: "mix/\(base.kernel.kdk)")
- let (removed, added) = try KernelCacheKDK.mix(base: baseKDK, donor: donorKDK, wanted: identifiers, output: mixKDK)
- log(" [kc] mix: \(identifiers.count) kexts, \(removed.count) research board kexts removed, \(added.count) added from the donor")
+ let sources = base.kextSources.map { source in
+ base.donors.firstIndex(of: source).map { donorKDKs[$0] } ?? baseKDK
+ }
+ let (removed, added) = try KernelCacheKDK.mix(base: baseKDK, sources: sources, wanted: identifiers, output: mixKDK)
+ let addedText = zip(donors, donorKDKs).map { "\(added[$1]?.count ?? 0) from \($0.id)" }.joined(separator: ", ")
+ log(" [kc] mix: \(identifiers.count) kexts, \(removed.count) research board kexts removed, \(addedText)")
try KernelCacheKDK.makeVolume(kdk: mixKDK, identifiers: identifiers, output: paths.staged.appending(path: "volume"))
try fm.removeItem(at: work)
try Data(ipsw.hash.utf8).write(to: paths.staged.appending(path: "ipsw.sha256"))
@@ -190,8 +211,8 @@ public final class KernelCacheMixer {
/// the volume is copied into a directory only root can reach, with nothing
/// in it that points outside, and kmutil links that copy.
@discardableResult
- public func link(kernelcache: Data) throws -> Data {
- let (base, paths) = try locations(for: kernelcache)
+ public func link(_ input: Input) throws -> Data {
+ let (base, paths) = try locations(for: input)
if let data = try? Data(contentsOf: paths.mixed), !data.isEmpty {
return data
}
@@ -203,7 +224,7 @@ public final class KernelCacheMixer {
throw PatcherError.fileNotFound("the staged \(base.id) kernelcache volume in \(paths.staged.path); run `vphone-cli fw kernelcache` with \(Self.ipswEnvironmentVariable) first")
}
- let payload = try Self.payload(of: kernelcache)
+ let payload = try Self.payload(of: input.kernelcache)
let copy = try KernelCacheVolumeCopy(
staged: paths.staged.appending(path: "volume"), kdk: base.kernel.kdk, pathLength: Self.buildRootLength(of: payload),
)
@@ -236,9 +257,9 @@ public final class KernelCacheMixer {
}
/// The recipe and where its mix and staged volume are kept.
- func locations(for kernelcache: Data) throws -> (base: KernelCacheBase, paths: (mixed: URL, staged: URL)) {
- let base = try base(for: kernelcache)
- let key = try cacheKey(base: base, donor: recipes.donor(id: base.donor))
+ func locations(for input: Input) throws -> (base: KernelCacheBase, paths: (mixed: URL, staged: URL)) {
+ let base = try base(for: input)
+ let key = try cacheKey(base: base, donors: base.donors.map { try recipes.donor(id: $0) })
return (base, (
cacheDirectory.appending(path: "mix/\(base.id)/\(key).im4p"),
cacheDirectory.appending(path: "staged/\(base.id)/\(key)"),
@@ -331,7 +352,7 @@ public final class KernelCacheMixer {
}
/// The donor's KDK, extracted once into `donors/<id>`.
- func donorKDK(_ donor: KernelCacheDonor, ipsw: (url: URL, hash: String)) throws -> URL {
+ func donorKDK(_ donor: KernelCacheDonor, restoreTree: URL, ipsw: (url: URL, hash: String)) throws -> URL {
let fm = FileManager.default
let directory = cacheDirectory.appending(path: "donors/\(donor.id)")
let kdk = directory.appending(path: "extract/\(donor.kernel.kdk)")
@@ -347,7 +368,7 @@ public final class KernelCacheMixer {
return kdk
}
try fm.createDirectory(at: directory, withIntermediateDirectories: true)
- let payload = try Self.payload(of: donorKernelcache(donor, in: directory))
+ let payload = try Self.payload(of: donorKernelcache(donor, in: directory, restoreTree: restoreTree))
try Self.check(payload, donor.kernel.decompressedSHA256, "decompressed donor \(donor.kernel.file)")
let decompressed = directory.appending(path: "\(donor.kernel.file).decompressed")
try payload.write(to: decompressed)
@@ -361,14 +382,22 @@ public final class KernelCacheMixer {
return extracted
}
- /// The donor kernelcache, kept in `directory` once read from its cloudOS
- /// IPSW. Only that one entry is downloaded.
- func donorKernelcache(_ donor: KernelCacheDonor, in directory: URL) throws -> Data {
+ /// The donor kernelcache: from the guest's restore tree for one its IPSW
+ /// ships, else kept in `directory` once read from its cloudOS IPSW, of
+ /// which only that one entry is downloaded.
+ func donorKernelcache(_ donor: KernelCacheDonor, in directory: URL, restoreTree: URL) throws -> Data {
+ guard let cloudOSSource = donor.cloudOSSource else {
+ let data = try Data(contentsOf: restoreTree.appending(path: donor.kernel.file), options: .mappedIfSafe)
+ guard donor.kernel.matches(sha: KernelCacheRecipes.sha256(data)) else {
+ throw PatcherError.invalidFormat("the guest's \(donor.kernel.file) does not match the \(donor.id) recipe")
+ }
+ return data
+ }
let local = directory.appending(path: donor.kernel.file)
if let data = try? Data(contentsOf: local), donor.kernel.matches(sha: KernelCacheRecipes.sha256(data)) {
return data
}
- guard let source = URL(string: donor.cloudOSSource) else {
+ guard let source = URL(string: cloudOSSource) else {
throw PatcherError.invalidFormat("the \(donor.id) recipe has no valid cloudOS URL")
}
log(" [kc] reading \(donor.kernel.file) from \(source.absoluteString)")
@@ -390,12 +419,19 @@ public final class KernelCacheMixer {
/// layout and this file's steps. Not the ipsw, which the root link does not
/// run: a stage records which one made it (`ipsw.sha256`), and removing
/// `~/.vphone/kernelcache` rebuilds everything.
- func cacheKey(base: KernelCacheBase, donor: KernelCacheDonor) throws -> String {
- var material = Data("\(Self.identity(base.kernel))|\(Self.identity(donor.kernel))|".utf8)
- for url in [base.symbolsURL, base.kextsURL] + (donor.symbolsURL.map { [$0] } ?? []) {
+ func cacheKey(base: KernelCacheBase, donors: [KernelCacheDonor]) throws -> String {
+ var material = Data("\(Self.identity(base.kernel))|".utf8)
+ for donor in donors {
+ material += Data("\(Self.identity(donor.kernel))|".utf8)
+ }
+ for url in [base.symbolsURL, base.kextsURL] + donors.compactMap(\.symbolsURL) {
material += try Data(contentsOf: url)
}
material += Data("\(Self.revision)|\(base.builderLayout.rawValue)".utf8)
+ // A recipe with its own source order is keyed on it too.
+ if base.sources != nil {
+ material += Data("|\(base.kextSources.joined(separator: ","))".utf8)
+ }
return String(KernelCacheRecipes.sha256(material).prefix(16))
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheRecipes.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheRecipes.swift
index 2cdd7a95..0ce40af8 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheRecipes.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/KernelCache/KernelCacheRecipes.swift
@@ -43,13 +43,33 @@ public struct KernelCacheBase: Decodable, Sendable {
public let symbols: String
/// Bundle identifiers of the mix, one per line.
public let kexts: String
- public let donor: String
+ /// The guest family the recipe is for (`VPhoneGuestDevice.Family`), when
+ /// not an iPhone or iPad: a watch links another kext set against the same
+ /// kernel.
+ public let guest: String?
+ /// Where the kexts come from, in order: `base` and donor ids. Each kext is
+ /// taken from the first that has it; the kernel and its KPI bundles
+ /// (System.kext) always from the base. Default: the base, then `donor`.
+ let sources: [String]?
+ let donor: String?
public let builderLayout: BuilderLayout
public internal(set) var directory = URL(fileURLWithPath: "/")
enum CodingKeys: String, CodingKey {
- case id, productVersion, kernel, symbols, kexts, donor, builderLayout
+ case id, productVersion, kernel, symbols, kexts, guest, sources, donor, builderLayout
+ }
+
+ static let baseSource = "base"
+
+ /// `sources`, or the base and its one donor.
+ public var kextSources: [String] {
+ sources ?? [Self.baseSource] + (donor.map { [$0] } ?? [])
+ }
+
+ /// The donor ids among `kextSources`.
+ public var donors: [String] {
+ kextSources.filter { $0 != Self.baseSource }
}
public var symbolsURL: URL {
@@ -65,13 +85,14 @@ public struct KernelCacheBase: Decodable, Sendable {
}
}
-/// A donor of the virtualisation kexts (`donors/<id>/manifest.json`).
+/// A donor of kexts (`donors/<id>/manifest.json`).
public struct KernelCacheDonor: Decodable, Sendable {
public let id: String
public let description: String?
public let kernel: KernelCacheFile
- /// The cloudOS IPSW the donor kernelcache is read from.
- public let cloudOSSource: String
+ /// The cloudOS IPSW the donor kernelcache is read from; nil for one the
+ /// guest's own IPSW ships, read from the VM's restore tree.
+ public let cloudOSSource: String?
/// Symbol map, for a stripped donor.
public let symbols: String?
@@ -129,12 +150,18 @@ public struct KernelCacheRecipes: Sendable {
return donor
}
- /// The recipe for a kernelcache, given as its IM4P or decompressed bytes.
- public func base(forKernelcache data: Data) throws -> KernelCacheBase? {
+ /// The recipe for a kernelcache, given as its IM4P or decompressed bytes,
+ /// and the guest family (`VPhoneGuestDevice.Family` raw value) it boots.
+ public func base(forKernelcache data: Data, guest: String) throws -> KernelCacheBase? {
let sha = Self.sha256(data)
- return try bases().first { $0.kernel.matches(sha: sha) }
+ let own = Self.ownRecipeGuests.contains(guest) ? guest : nil
+ return try bases().first { $0.kernel.matches(sha: sha) && $0.guest == own }
}
+ /// Guest families that need a recipe of their own; the others share the
+ /// iPhone's.
+ static let ownRecipeGuests: Set<String> = ["watch"]
+
private func manifests(in subdirectory: String) throws -> [URL] {
let directory = root.appending(path: subdirectory)
let entries = try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
index 0a5dbc59..64cdf87e 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
@@ -286,7 +286,8 @@ extension FirmwarePipeline {
// As shipped: the stash once a run has put it aside.
let shipped = try Data(contentsOf: pristineInput(for: restoreDir.appending(path: restoreKernelPath)).url)
let mixer = try KernelCacheMixer(recipes: .locate(), verbose: verbose)
- let base = try mixer.base(for: shipped)
+ let input = KernelCacheMixer.Input(kernelcache: shipped, guest: guestDevice.family.rawValue, restoreTree: restoreDir)
+ let base = try mixer.base(for: input)
let record = PatchRecord(
patchID: kernelMixPatch,
component: "kernelcache",
@@ -294,9 +295,9 @@ extension FirmwarePipeline {
virtualAddress: nil,
originalBytes: Data(),
patchedBytes: Data(),
- description: "the \(base.id) research board kernelcache, rebuilt with the \(base.donor) virtualisation kexts",
+ description: "the \(base.id) research board kernelcache, rebuilt with the kexts of \(base.donors.joined(separator: " and "))",
)
- return try (mixer.mix(kernelcache: shipped), record)
+ return try (mixer.mix(input), record)
} : nil
components.append(ComponentDescriptor(
name: "kernelcache",
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift
index db2c9c3d..a135e4df 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift
@@ -38,12 +38,22 @@ extension FirmwarePipeline {
/// The research board kernelcache the VM's mix is built from, as shipped:
/// its `RestoreKernelCache`, from the originals once `fw patch` has put it
/// aside. Nil when the restore tree has vphone600 components.
- public func researchBoardKernelcache() throws -> Data? {
+ public func researchBoardKernelcache() throws -> KernelCacheMixer.Input? {
let restoreDir = try findRestoreDirectory()
guard Self.researchBoardStandsIn(restoreDir: restoreDir) else { return nil }
let file = try restoreDir.appending(path: Self.manifestComponentPath("RestoreKernelCache", in: restoreDir))
let stashed = originalURL(for: file).flatMap { FileManager.default.fileExists(atPath: $0.path) ? $0 : nil }
- return try Data(contentsOf: stashed ?? file)
+ return try KernelCacheMixer.Input(
+ kernelcache: Data(contentsOf: stashed ?? file),
+ guest: readGuestDevice(restoreDir).family.rawValue,
+ restoreTree: restoreDir,
+ )
+ }
+
+ /// The guest family the preserved iPhone manifest names (iPhone when none).
+ static func guestFamily(restoreDir: URL) -> String {
+ let manifest = restoreDir.appendingPathComponent("iPhone-BuildManifest.plist")
+ return (VPhoneGuestDevice.detect(buildManifestAt: manifest) ?? .default).family.rawValue
}
/// `ProductVersion` from a manifest in `restoreDir`, or nil if absent/unreadable.
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/KernelCacheMixerTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/KernelCacheMixerTests.swift
index 6cc52f8d..75d11ebb 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/KernelCacheMixerTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/KernelCacheMixerTests.swift
@@ -23,24 +23,37 @@ struct KernelCacheMixerTests {
@Test("Every recipe has its map, its bundle list and its donor")
func recipesAreComplete() throws {
let bases = try Self.recipes.bases()
- #expect(bases.map(\.productVersion) == ["26.4", "26.5", "26.6", "26.7"])
+ #expect(bases.map(\.id) == ["26.4_23E246", "26.5_23F77", "26.6_23G71", "26.7_23H20", "watch_26.4_23T240"])
for base in bases {
#expect(FileManager.default.fileExists(atPath: base.symbolsURL.path), "\(base.id)")
let identifiers = try base.kextIdentifiers()
#expect(identifiers.count > 100, "\(base.id)")
#expect(Set(identifiers).count == identifiers.count, "\(base.id)")
#expect(base.builderLayout == .kernelLast, "\(base.id)")
- let donor = try Self.recipes.donor(id: base.donor)
- #expect(donor.symbolsURL.map { FileManager.default.fileExists(atPath: $0.path) } == true)
- #expect(URL(string: donor.cloudOSSource)?.scheme == "https")
+ #expect(base.kextSources.contains("base"), "\(base.id)")
+ for id in base.donors {
+ let donor = try Self.recipes.donor(id: id)
+ #expect(donor.symbolsURL.map { FileManager.default.fileExists(atPath: $0.path) } == true)
+ #expect(donor.cloudOSSource.map { URL(string: $0)?.scheme == "https" } ?? true)
+ }
}
}
+ @Test("A watch links its own kext set against the kernel the iPhone recipe uses")
+ func recipeFollowsGuest() throws {
+ let watch = try #require(try Self.recipes.bases().first { $0.guest == "watch" })
+ let shared = try Self.recipes.bases().filter { $0.kernel.matches(sha: watch.kernel.sha256) }
+ #expect(Set(shared.map(\.id)) == ["26.4_23E246", "watch_26.4_23T240"])
+ #expect(watch.kextSources == ["watch7c_26.4_23T240", "base", "vphone600_26.4_23E5207q"])
+ #expect(try Self.recipes.donor(id: "watch7c_26.4_23T240").cloudOSSource == nil)
+ }
+
@Test("A kernelcache is matched by the SHA-256 of its container or of its payload, and nothing else")
func matchesByHash() throws {
let base = try #require(try Self.recipes.bases().first)
let mixer = KernelCacheMixer(recipes: Self.recipes, verbose: false)
- #expect(throws: PatcherError.self) { try mixer.base(for: Data("not a kernelcache".utf8)) }
+ let input = KernelCacheMixer.Input(kernelcache: Data("not a kernelcache".utf8), guest: "iPhone", restoreTree: URL(fileURLWithPath: "/"))
+ #expect(throws: PatcherError.self) { try mixer.base(for: input) }
#expect(base.kernel.matches(sha: base.kernel.sha256))
#expect(base.kernel.matches(sha: base.kernel.decompressedSHA256))
#expect(!base.kernel.matches(sha: String(repeating: "0", count: 64)))
@@ -50,10 +63,10 @@ struct KernelCacheMixerTests {
func cacheKeyFollowsRecipe() throws {
let bases = try Self.recipes.bases()
let mixer = KernelCacheMixer(recipes: Self.recipes, verbose: false)
- let keys = try bases.map { try mixer.cacheKey(base: $0, donor: Self.recipes.donor(id: $0.donor)) }
+ let keys = try bases.map { try mixer.cacheKey(base: $0, donors: $0.donors.map { try Self.recipes.donor(id: $0) }) }
#expect(Set(keys).count == bases.count)
let first = try #require(bases.first)
- #expect(try mixer.cacheKey(base: first, donor: Self.recipes.donor(id: first.donor)) == keys.first)
+ #expect(try mixer.cacheKey(base: first, donors: first.donors.map { try Self.recipes.donor(id: $0) }) == keys.first)
}
@Test("The volume path takes the length of the build root the base records")
@@ -130,6 +143,26 @@ struct KernelCacheMixerTests {
try KernelCacheKDK.mix(base: base, donor: donor, wanted: wanted + ["com.apple.nowhere"], output: output)
}
+ // A donor listed before the base supplies the kexts both have; the
+ // kernel's KPI bundles stay the base's.
+ let first = root.appending(path: "first/KDK_26.4_23T235.kdk")
+ try Self.kdk(at: first, kexts: [
+ "com.apple.kept": "Kept.kext",
+ "com.apple.kpi.bsd": "System.kext/PlugIns/BSDKernel.kext",
+ ])
+ try Data("first".utf8).write(to: first.appending(path: "System/Library/Extensions/Kept.kext/Kept"))
+ let ordered = root.appending(path: "ordered/KDK_26.6_23G71.kdk")
+ let (_, addedBy) = try KernelCacheKDK.mix(
+ base: base, sources: [first, base, donor], wanted: ["com.apple.kept", "com.apple.driver.AppleParavirtGPU"], output: ordered,
+ )
+ #expect(addedBy[first] == ["com.apple.kept"])
+ #expect(addedBy[donor] == ["com.apple.driver.AppleParavirtGPU"])
+ let kept = ordered.appending(path: "System/Library/Extensions/Kept.kext/Kept")
+ #expect(try String(contentsOf: kept, encoding: .utf8) == "first")
+ #expect(throws: PatcherError.self) {
+ try KernelCacheKDK.mix(base: base, sources: [first, base], wanted: ["com.apple.kpi.bsd"], output: ordered)
+ }
+
// The staged volume root links holds no link but the KDK's own.
try KernelCacheVolumeCopy.checkLinks(in: volume, kdk: "KDK_26.6_23G71.kdk")
try FileManager.default.createSymbolicLink(
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
index c667c8c3..a2da94b1 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift
@@ -396,9 +396,9 @@ struct VPhoneFirmwarePatchCommand: ParsableCommand {
// A research board kernelcache is mixed beforehand (`fw kernelcache`),
// since linking it needs root; root builds it here if need be.
if geteuid() != 0, !selection.blockedPatches.contains(FirmwareResearchBoardPatchSet.kernelMix),
- let kernelcache = try FirmwarePipeline(vmDirectory: bundle.url, variant: .jb).researchBoardKernelcache()
+ let input = try FirmwarePipeline(vmDirectory: bundle.url, variant: .jb).researchBoardKernelcache()
{
- let state = try KernelCacheMixer(recipes: .locate()).state(for: kernelcache)
+ let state = try KernelCacheMixer(recipes: .locate()).state(for: input)
if state != .mixed {
throw ValidationError(KernelCacheMixer.linkInstructions(staged: state == .staged).replacingOccurrences(of: "<vm>", with: name))
}
@@ -690,12 +690,12 @@ struct VPhoneFirmwareKernelcacheCommand: ParsableCommand {
func run() throws {
let name = try VPhoneVirtualMachineSelection.resolveExisting(name, in: lib.library)
let bundle = try lib.library.bundle(named: name)
- guard let kernelcache = try FirmwarePipeline(vmDirectory: bundle.url, variant: .jb).researchBoardKernelcache() else {
+ guard let input = try FirmwarePipeline(vmDirectory: bundle.url, variant: .jb).researchBoardKernelcache() else {
print("[=] \(name)'s cloudOS has vphone600 components; its kernelcache needs no mix.")
return
}
let mixer = try KernelCacheMixer(recipes: .locate())
- let state = try mixer.state(for: kernelcache)
+ let state = try mixer.state(for: input)
if state == .mixed {
print("[+] The kernelcache mix is ready; `fw patch` takes it from the cache.")
return
@@ -705,16 +705,16 @@ struct VPhoneFirmwareKernelcacheCommand: ParsableCommand {
guard !linkOnly else {
throw ValidationError("\(name)'s kernelcache mix is not staged. Stage it first, as yourself: \(KernelCacheMixer.ipswEnvironmentVariable)=<ipsw> vphone-cli fw kernelcache \(name)")
}
- try mixer.stage(kernelcache: kernelcache, ipsw: ipsw)
+ try mixer.stage(input, ipsw: ipsw)
}
- try mixer.link(kernelcache: kernelcache)
+ try mixer.link(input)
print("[+] The kernelcache mix is ready; `fw patch` takes it from the cache.")
return
}
guard !linkOnly else {
throw ValidationError("Linking the kernelcache mix needs root. Run this command with sudo.")
}
- try mixer.stage(kernelcache: kernelcache, ipsw: ipsw)
+ try mixer.stage(input, ipsw: ipsw)
print("[+] Staged. Link it with: sudo vphone-cli fw kernelcache \(name)")
}
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
index 70014892..9a1bdd47 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
@@ -99,11 +99,22 @@ for manifest in "$resources/kernelcache_recipes/bases/"*/manifest.json; do
file=$(/usr/bin/plutil -extract $key raw -o - "$manifest") || { print -u2 "Malformed kernelcache recipe: ${recipe:t}"; exit 1; }
[[ -s "$recipe/$file" ]] || { print -u2 "Kernelcache recipe ${recipe:t} lacks $file"; exit 1; }
done
- donor=$(/usr/bin/plutil -extract donor raw -o - "$manifest")
- [[ -s "$resources/kernelcache_recipes/donors/$donor/manifest.json" ]] || {
- print -u2 "Kernelcache recipe ${recipe:t} names a missing donor: $donor"
- exit 1
- }
+ # The donor, or the kext sources in order (the base and donors).
+ donors=()
+ if count=$(/usr/bin/plutil -extract sources raw -o - "$manifest" 2>/dev/null); then
+ for (( i = 0; i < count; i++ )); do
+ source=$(/usr/bin/plutil -extract sources.$i raw -o - "$manifest")
+ [[ $source == base ]] || donors+=($source)
+ done
+ else
+ donors=($(/usr/bin/plutil -extract donor raw -o - "$manifest"))
+ fi
+ for donor in $donors; do
+ [[ -s "$resources/kernelcache_recipes/donors/$donor/manifest.json" ]] || {
+ print -u2 "Kernelcache recipe ${recipe:t} names a missing donor: $donor"
+ exit 1
+ }
+ done
done
# New machines copy this ROM. Without it vm new would fail, and OpenAVB is
# distributed only with its licences. The ROM window is 512 KiB.
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/kexts.txt b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/kexts.txt
new file mode 100644
index 00000000..b65245e6
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/kexts.txt
@@ -0,0 +1,129 @@
+com.apple.AppleFSCompression.AppleFSCompressionTypeZlib
+com.apple.IOTextEncryptionFamily
+com.apple.driver.AppleA7IOP
+com.apple.driver.AppleARMGIC
+com.apple.driver.AppleARMPMU
+com.apple.driver.AppleARMPlatform
+com.apple.driver.AppleARMWatchdogTimer
+com.apple.driver.AppleAudioClockLibs
+com.apple.driver.AppleBSDKextStarter
+com.apple.driver.AppleBSDKextStarterTMPFS
+com.apple.driver.AppleBluetooth
+com.apple.driver.AppleCallbackPowerSource
+com.apple.driver.AppleDiagnosticDataAccessReadOnly
+com.apple.driver.AppleDiskImages2
+com.apple.driver.AppleEffaceableStorage
+com.apple.driver.AppleEmbeddedAudioLibs
+com.apple.driver.AppleEmbeddedLightSensor
+com.apple.driver.AppleEmbeddedTempSensor
+com.apple.driver.AppleEmbeddedUSB
+com.apple.driver.AppleFirmwareUpdateKext
+com.apple.driver.AppleHIDKeyboard
+com.apple.driver.AppleIDV
+com.apple.driver.AppleIISController
+com.apple.driver.AppleInputDeviceSupport
+com.apple.driver.AppleLockdownMode
+com.apple.driver.AppleM2ScalerCSCDriver
+com.apple.driver.AppleM68Buttons
+com.apple.driver.AppleMobileApNonce
+com.apple.driver.AppleMobileFileIntegrity
+com.apple.driver.AppleMultitouchDriver
+com.apple.driver.AppleNANDConfigAccess
+com.apple.driver.AppleOnboardSerial
+com.apple.driver.ApplePMGR
+com.apple.driver.ApplePVPanic
+com.apple.driver.AppleParavirtGPUIOGPUFamily
+com.apple.driver.AppleS8000AES
+com.apple.driver.AppleSEPCredentialManager
+com.apple.driver.AppleSEPKeyStore
+com.apple.driver.AppleSEPManager
+com.apple.driver.AppleSMC
+com.apple.driver.AppleSPU
+com.apple.driver.AppleSamsungSerial
+com.apple.driver.AppleSerialShim
+com.apple.driver.AppleTopCaseDriverV2
+com.apple.driver.AppleTopCaseHIDEventDriver
+com.apple.driver.AppleUSBDeviceMux
+com.apple.driver.AppleUSBDeviceNCM
+com.apple.driver.AppleUSBHostMergeProperties
+com.apple.driver.AppleVPIOP
+com.apple.driver.AppleVideoToolboxParavirtualization
+com.apple.driver.AppleVirtIO
+com.apple.driver.AppleVirtualPlatform
+com.apple.driver.AvpFairPlayDriver
+com.apple.driver.DiskImages
+com.apple.driver.DiskImages.FileBackingStore
+com.apple.driver.DiskImages.KernelBacked
+com.apple.driver.DiskImages.RAMBackingStore
+com.apple.driver.DiskImages.ReadWriteDiskImage
+com.apple.driver.DiskImages.UDIFDiskImage
+com.apple.driver.ExclavesAudioKext
+com.apple.driver.FairPlayIOKit
+com.apple.driver.IISAudioIsolatedStreamECProxy
+com.apple.driver.IODARTFamily
+com.apple.driver.IOSlaveProcessor
+com.apple.driver.OpticalMultisensor
+com.apple.driver.RTBuddy
+com.apple.driver.corecapture
+com.apple.driver.driverkit.serial
+com.apple.driver.usb.AppleUSBCommon
+com.apple.driver.usb.AppleUSBHostCompositeDevice
+com.apple.driver.usb.AppleUSBHostDeviceSupport
+com.apple.driver.usb.AppleUSBHostPacketFilter
+com.apple.driver.usb.AppleUSBHostPlatformProperties
+com.apple.driver.usb.AppleUSBHostiOSDevice
+com.apple.driver.usb.AppleUSBXHCI
+com.apple.driver.usb.AppleUSBXHCIPCI
+com.apple.driver.usb.cdc
+com.apple.driver.usb.cdc.acm
+com.apple.driver.usb.networking
+com.apple.driver.usb.serial
+com.apple.filesystems.apfs
+com.apple.filesystems.hfs.kext
+com.apple.filesystems.tmpfs
+com.apple.iokit.AppleARMIISAudio
+com.apple.iokit.AppleParavirtIOSurface
+com.apple.iokit.AppleVirtIONeuralEngineDevice
+com.apple.iokit.AppleVirtIOStorage
+com.apple.iokit.CoreAnalyticsFamily
+com.apple.iokit.IO80211Family
+com.apple.iokit.IOAVFamily
+com.apple.iokit.IOAccessoryManager
+com.apple.iokit.IOAudio2Family
+com.apple.iokit.IOCECFamily
+com.apple.iokit.IOCryptoAcceleratorFamily
+com.apple.iokit.IOGPUFamily
+com.apple.iokit.IOHDCPFamily
+com.apple.iokit.IOHIDEventDriver
+com.apple.iokit.IOHIDEventDriverSafeBoot
+com.apple.iokit.IOHIDFamily
+com.apple.iokit.IOMobileGraphicsFamily
+com.apple.iokit.IONetworkFamily
+com.apple.iokit.IONetworkingFamily
+com.apple.iokit.IOPCIFamily
+com.apple.iokit.IOPortFamily
+com.apple.iokit.IOReportFamily
+com.apple.iokit.IOSerialFamily
+com.apple.iokit.IOSkywalkFamily
+com.apple.iokit.IOSlowAdaptiveClockingFamily
+com.apple.iokit.IOStorageFamily
+com.apple.iokit.IOStreamFamily
+com.apple.iokit.IOSurface
+com.apple.iokit.IOUSBDeviceFamily
+com.apple.iokit.IOUSBHostFamily
+com.apple.kec.Compression
+com.apple.kec.Libm
+com.apple.kec.corecrypto
+com.apple.kec.pthread
+com.apple.kext.AppleMatch
+com.apple.kext.CoreTrust
+com.apple.kpi.bsd
+com.apple.kpi.dsep
+com.apple.kpi.iokit
+com.apple.kpi.libkern
+com.apple.kpi.mach
+com.apple.kpi.private
+com.apple.kpi.unsupported
+com.apple.security.AKSAnalytics
+com.apple.security.AppleImage4
+com.apple.security.sandbox
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/manifest.json b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/manifest.json
new file mode 100644
index 00000000..5002b8e0
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/manifest.json
@@ -0,0 +1,19 @@
+{
+ "builderLayout" : "kernel-last",
+ "guest" : "watch",
+ "id" : "watch_26.4_23T240",
+ "kernel" : {
+ "decompressedSHA256" : "e4de60cdf330adefedcc6d6eae1874cff83f955e9ca25191e31e918def8306d0",
+ "file" : "kernelcache.release.vresearch101",
+ "kdk" : "KDK_26.4_23E235.kdk",
+ "sha256" : "79a43249ea047f23c2046c266ee3419d3223038dae9efe367dbb4fb1b1486cd1"
+ },
+ "kexts" : "kexts.txt",
+ "productVersion" : "26.4",
+ "sources" : [
+ "watch7c_26.4_23T240",
+ "base",
+ "vphone600_26.4_23E5207q"
+ ],
+ "symbols" : "symbols.json.gz"
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/symbols.json.gz b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/symbols.json.gz
new file mode 100644
index 00000000..ced88cb6
Binary files /dev/null and b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/bases/watch_26.4_23T240/symbols.json.gz differ
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/manifest.json b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/manifest.json
new file mode 100644
index 00000000..5bdfa38d
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/manifest.json
@@ -0,0 +1,11 @@
+{
+ "description" : "Apple Watch kernelcache of the Watch7,18 26.4 (23T240) IPSW: the watchOS kexts, read from the guest restore tree",
+ "id" : "watch7c_26.4_23T240",
+ "kernel" : {
+ "decompressedSHA256" : "399333b1f4a9e2a9f9ad34740b741a6c000c1d8bf92294d5c5a7b6671ad927f4",
+ "file" : "kernelcache.release.watch7c",
+ "kdk" : "KDK_26.4_23T235.kdk",
+ "sha256" : "cd0f707f6741b147b457df8dead2eb00bb1ebf8d72d28a0db47c09b0dce917be"
+ },
+ "symbols" : "symbols.json.gz"
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/symbols.json.gz b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/symbols.json.gz
new file mode 100644
index 00000000..d0077a45
Binary files /dev/null and b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/donors/watch7c_26.4_23T240/symbols.json.gz differ