Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Attach file disks with cachingMode .cached instead of the default

Jackye45f7c9576ea
diff --git a/Research/Host/disk_caching_mode.md b/Research/Host/disk_caching_mode.md
new file mode 100644
index 00000000..1bc8ca8a
--- /dev/null
+++ b/Research/Host/disk_caching_mode.md
@@ -0,0 +1,51 @@
+# Disk caching mode
+
+`vphone-vm` attaches `Disk.img` through `VPhoneDiskAttachment.make`, which
+spells out caching `.cached` and synchronization `.full`. Before, it used
+`VZDiskImageStorageDeviceAttachment(url:readOnly:)`, whose defaults are caching
+`automatic` and synchronization `full` (read back on macOS 27.0.1 with a
+probe; the header does not state them).
+
+## Why `.cached`
+
+Measured on 2026-10-21 (Mac fleet investigation W7) on two idle Mac mini M4
+hosts (16 GB, macOS 27.0.1, SIP as shipped, no other VMs), with Linux guests
+rather than vphone guests, since SIP as shipped cannot run a vphone. 2 GiB
+guests checked known patterns in 1.3 GiB of RAM, through a virtio-blk disk
+with `O_DIRECT` and through the page cache, and in `O_DIRECT` read buffers
+left idle, while a host program pushed memory pressure to warning and then
+critical. Each round ran 900 seconds.
+
+| Disk | Guest-runs | Lost data |
+|---|---|---|
+| Sparse image, `automatic` or `uncached`, host compressing | 26 | 26 |
+| Sparse image, `automatic` or `uncached`, host idle | 2 | 0 |
+| Fully written (not sparse) image, `automatic` or `uncached` | 8 | 0 |
+| `cached` (sparse or written, all three synchronization modes) | 39 | 0 |
+| NBD | 9 | 0 |
+| virtiofs | 6 | 0 |
+
+- The loss is always zeros, never stale data, in runs that are whole
+ multiples of 2 MiB of guest RAM. It hits anonymous memory the guest never
+ did I/O into, the guest kernel itself (one guest oopsed on a NULL pointer),
+ page-cache pages and idle `O_DIRECT` buffers. A zeroed dirty page written
+ back leaves a zero block in the image.
+- What gates it is the host compressor working on guest memory, not the
+ pressure level: one round lost data at level normal, and every round where
+ the compressor stayed idle was clean. A memory gate or a 1.0 overcommit
+ ratio does not protect a non-cached guest.
+- 36 of the 39 `cached` guest-runs saw the host at critical, some for five
+ minutes.
+
+So the loss needs a non-cached attachment on a sparse image while the host
+compresses guest memory, and `.cached` removed it on these hosts. A vphone
+guest itself was not tested; it uses the same attachment.
+
+## Effect on existing machines
+
+Nothing on disk or in `config.plist` changes, and no manifest key is added.
+The mode is chosen by `vphone-vm` at each launch, so a machine takes it at its
+first launch with a bundle carrying this change; a running machine keeps the
+old mode until it restarts. Going back to an older bundle goes back to
+`automatic` with nothing to undo. `.cached` lets the host page cache hold more
+of the image; the memory and speed effect on a running vphone is not measured.
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
index 6f13a16e..9fe6dfc7 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
@@ -178,7 +178,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
guard try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: options.diskURL) else {
throw VPhoneVirtualMachineError.diskNotFound(options.diskURL.path)
}
- let attachment = try VZDiskImageStorageDeviceAttachment(url: options.diskURL, readOnly: false)
+ let attachment = try VPhoneDiskAttachment.make(url: options.diskURL, readOnly: false)
config.storageDevices = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]
// Network (mode, MAC, address and forwards from the bundle manifest)
diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneDiskAttachment.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneDiskAttachment.swift
new file mode 100644
index 00000000..e7a9446e
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneDiskAttachment.swift
@@ -0,0 +1,28 @@
+import Foundation
+import Virtualization
+
+/// How `vphone-vm` attaches a disk image file to the guest.
+public enum VPhoneDiskAttachment {
+ /// Spelled out rather than left to `init(url:readOnly:)`, whose defaults
+ /// are caching `.automatic` and synchronization `.full` (read back on
+ /// macOS 27.0.1). With `.automatic` or `.uncached` on a sparse image, guest
+ /// RAM came back zeroed in 2 MiB runs whenever the host compressor was
+ /// compressing guest memory, at pressure level normal as well as warning
+ /// and critical; a zeroed dirty page written back leaves a zero block in
+ /// the image. `.cached` lost nothing under the same load. See
+ /// Research/Host/disk_caching_mode.md.
+ public static let cachingMode: VZDiskImageCachingMode = .cached
+
+ /// `.full` keeps the guest's flushes reaching permanent storage, as the
+ /// default did.
+ public static let synchronizationMode: VZDiskImageSynchronizationMode = .full
+
+ public static func make(url: URL, readOnly: Bool) throws -> VZDiskImageStorageDeviceAttachment {
+ try VZDiskImageStorageDeviceAttachment(
+ url: url,
+ readOnly: readOnly,
+ cachingMode: cachingMode,
+ synchronizationMode: synchronizationMode,
+ )
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/DiskAttachmentTests.swift b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/DiskAttachmentTests.swift
new file mode 100644
index 00000000..c9935c89
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/DiskAttachmentTests.swift
@@ -0,0 +1,67 @@
+import Foundation
+import Testing
+import Virtualization
+@testable import VPhoneCoreKit
+
+struct DiskAttachmentTests {
+ private func withImage(_ body: (URL) throws -> Void) throws {
+ let dir = FileManager.default.temporaryDirectory
+ .appendingPathComponent("vphone-disk-attachment-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: dir) }
+ let url = dir.appendingPathComponent("Disk.img")
+ // Sparse, as Disk.img is.
+ #expect(FileManager.default.createFile(atPath: url.path, contents: nil))
+ let handle = try FileHandle(forWritingTo: url)
+ try handle.truncate(atOffset: 64 << 20)
+ try handle.close()
+ try body(url)
+ }
+
+ @Test func `file disks are attached cached with full synchronization`() throws {
+ try withImage { url in
+ let attachment = try VPhoneDiskAttachment.make(url: url, readOnly: false)
+ #expect(attachment.cachingMode == .cached)
+ #expect(attachment.synchronizationMode == .full)
+ #expect(!attachment.isReadOnly)
+ }
+ }
+
+ @Test func `read-only file disks are attached cached too`() throws {
+ try withImage { url in
+ let attachment = try VPhoneDiskAttachment.make(url: url, readOnly: true)
+ #expect(attachment.cachingMode == .cached)
+ #expect(attachment.isReadOnly)
+ }
+ }
+
+ /// `vphone-vm` must not build a file disk any other way: every
+ /// `VZDiskImageStorageDeviceAttachment(` in the shipped sources has to be
+ /// the one inside `VPhoneDiskAttachment`.
+ @Test func `no other code attaches a disk image`() throws {
+ let repo = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent() // VirtualMachine
+ .deletingLastPathComponent() // VPhoneCoreKitTests
+ .deletingLastPathComponent() // VPhoneKit
+ .deletingLastPathComponent() // repository root
+ let roots = ["VPhoneKit", "VPhoneExecutable", "VPhoneLaunchpad", "VPhoneDaemon"]
+ .map { repo.appendingPathComponent($0) }
+ var offenders: [String] = []
+ for root in roots {
+ guard let walker = FileManager.default.enumerator(at: root, includingPropertiesForKeys: nil) else {
+ continue
+ }
+ for case let file as URL in walker where file.pathExtension == "swift" {
+ if file.path.contains("/.build/") || file.lastPathComponent == "VPhoneDiskAttachment.swift" {
+ continue
+ }
+ if file.path.contains("Tests/") { continue }
+ let text = try String(contentsOf: file, encoding: .utf8)
+ if text.contains("VZDiskImageStorageDeviceAttachment(") {
+ offenders.append(file.path)
+ }
+ }
+ }
+ #expect(offenders.isEmpty, "attach file disks through VPhoneDiskAttachment.make: \(offenders)")
+ }
+}