How the PV=3 Hardware Model Is Created and Applied During the vPhone-CLI Boot Process

vPhone-CLI constructs a PV=3 hardware model using private Virtualization.framework APIs and applies it to both the platform configuration and auxiliary storage during VM initialization to enable security-research features.

The Lakr233/vphone-cli repository provides a command-line tool for booting iOS virtual machines on macOS. To present a PV=3 hardware profile to the guest OS, the tool dynamically constructs a VZMacHardwareModel with specific platform parameters and injects it into the Virtualization.framework stack before the boot sequence begins.

Understanding the PV=3 Hardware Model Requirement

The PV=3 (Platform Version 3) hardware model represents a specialized configuration used for security research virtualization. According to the source code in sources/vphone-cli/VPhoneHardwareModel.swift, creating this model requires private entitlements—specifically com.apple.private.virtualization.security-research and com.apple.private.virtualization—which must be declared in the project's sources/vphone-cli/vphone.entitlements file.

This hardware profile is only supported on macOS 15 Sequoia or newer. If the host operating system lacks support for the model parameters, the initialization throws an error before the VM can start.

Step 1: Constructing the Hardware Model Descriptor

The creation process begins in VPhoneHardware.createModel(), defined in sources/vphone-cli/VPhoneHardwareModel.swift (lines 19-34). This method allocates a private _VZMacHardwareModelDescriptor through the Objective-C runtime dynamic bridging mechanism.

Dynamic Runtime Bridging

The function sets three critical fields on the descriptor:

• Platform version: Set to 3 to indicate PV=3
• Board ID: Set to 0x90
• ISA: Set to 2

After configuring these fields, the descriptor is converted into a concrete VZMacHardwareModel instance. The method validates that the resulting model isSupported on the current host; otherwise, it raises a fatal error.

// Simplified representation from VPhoneHardwareModel.swift
let descriptor = /* dynamically allocate _VZMacHardwareModelDescriptor */
descriptor.platformVersion = 3
descriptor.boardId = 0x90
descriptor.isa = 2
let hwModel = VZMacHardwareModel(descriptor: descriptor)
guard hwModel.isSupported else { fatalError("PV=3 not supported") }

Step 2: Applying the Model to the Virtual Machine

Once constructed, the hardware model must be applied to two distinct components within sources/vphone-cli/VPhoneVirtualMachine.swift. The initializer—triggered by VPhoneAppDelegate.swift—obtains the model via let hwModel = try VPhoneHardware.createModel() and then propagates it through the VM configuration stack.

Platform Configuration and Auxiliary Storage

The same hwModel instance is assigned to:

• VZMacPlatformConfiguration.hardwareModel: This property tells the Virtualization.framework which hardware signature to present to the guest iOS kernel.
• VZMacAuxiliaryStorage: The auxiliary storage (NVRAM) is instantiated with the identical hardwareModel, ensuring that NVRAM data—including boot arguments—matches the PV=3 profile.

// From sources/vphone-cli/VPhoneVirtualMachine.swift
// ── 1️⃣ Build the PV=3 hardware model ──
let hwModel = try VPhoneHardware.createModel()
print("[vphone] PV=3 hardware model: isSupported = true")

// ── 2️⃣ Apply the model to platform & NVRAM ──
let auxStorage = try VZMacAuxiliaryStorage(
    creatingStorageAt: options.nvramURL,
    hardwareModel: hwModel,
    options: .allowOverwrite
)
platform.hardwareModel = hwModel
platform.auxiliaryStorage = auxStorage

Entitlement Validation in the Boot Sequence

During the actual boot process, the Virtualization.framework performs a bitwise entitlement check against the binary's code signature. The framework verifies that the calling process holds the required private entitlements using the mask (entitlements & 0x12) != 0.

Because vphone-cli is built with the necessary entitlements—as specified in sources/vphone-cli/vphone.entitlements—the framework accepts the PV=3 descriptor. This validation allows the VM to present the research hardware profile to the iOS kernel, enabling the specialized virtualization features required by the tool.

Summary

• PV=3 construction relies on VPhoneHardware.createModel() in VPhoneHardwareModel.swift to dynamically build a VZMacHardwareModel with platform version 3, board ID 0x90, and ISA 2.
• Model application occurs in VPhoneVirtualMachine.swift, where the hardware model is injected into both VZMacPlatformConfiguration and VZMacAuxiliaryStorage to ensure consistency.
• Entitlement verification happens at boot time when Virtualization.framework checks for com.apple.private.virtualization.security-research before accepting the private hardware descriptor.
• macOS 15 Sequoia is the minimum host version required for PV=3 support, with runtime validation occurring during model creation.

Frequently Asked Questions

What is the PV=3 hardware model in Apple Virtualization?

The PV=3 hardware model is a specialized platform configuration used by Apple’s Virtualization.framework for security research scenarios. It requires private entitlements and presents a distinct hardware signature (platform version 3, board ID 0x90, ISA 2) to the guest operating system, enabling research-grade virtualization features not available in standard configurations.

Why does vPhone-CLI require private entitlements to use PV=3?

The PV=3 model accesses private APIs within the _VZMacHardwareModelDescriptor class and requires the com.apple.private.virtualization.security-research entitlement. According to the source code in VPhoneHardwareModel.swift, these private interfaces are necessary to construct the specific hardware descriptor that Virtualization.framework validates using the bitmask 0x12 during the boot sequence.

What happens if the host macOS version does not support PV=3?

If the host system is running a version older than macOS 15 Sequoia, VPhoneHardware.createModel() throws an error during initialization. The function explicitly checks hwModel.isSupported after construction and terminates with a fatal error if the platform cannot support the PV=3 configuration, preventing the VM from entering an undefined state.

How does the PV=3 model affect NVRAM and boot arguments?

The PV=3 hardware model directly influences the VZMacAuxiliaryStorage (NVRAM) creation. Because the auxiliary storage is instantiated with the same VZMacHardwareModel instance used for the platform configuration, the NVRAM data structure aligns with the PV=3 profile. This ensures that boot arguments and firmware variables stored in NVRAM are interpreted correctly by the guest iOS kernel running under the research hardware model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}