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

> Learn how vPhone-CLI builds and applies the PV=3 hardware model using private Virtualization.framework APIs during VM boot. Enable security-research features now.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: internals
- Published: 2026-09-08

---

**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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```swift
// 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`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift). The initializer—triggered by [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```swift
// 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`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) to dynamically build a `VZMacHardwareModel` with platform version 3, board ID `0x90`, and ISA `2`.
- **Model application** occurs in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.