# What Virtual Devices Are Configured for the vphone-cli VM: Complete Hardware Emulation Breakdown

> Explore the 13+ virtual devices emulated by vphone-cli VM, from graphics and audio to networking and Secure Enclave. Understand its complete hardware emulation.

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

---

**The vphone-cli VM configures 13+ virtual devices including graphics, audio, storage, network, serial, multi-touch, accelerators, entropy, keyboard, socket, battery, debug stub, and Secure Enclave coprocessor to emulate a complete iPhone hardware platform.**

The **vphone-cli** project by Lakr233 creates a macOS virtual machine using Apple's Virtualization.framework to run iOS environments. Understanding what virtual devices are configured for the vphone-cli VM requires examining the `VPhoneVirtualMachine.init` method in [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift), where the `VZVirtualMachineConfiguration` is assembled. This article breaks down every emulated device category with direct source references.

---

## Core Virtual Devices Overview

The VM construction follows a pattern: each device type is instantiated with platform-specific configurations, then assigned to the configuration object. Some use public Apple APIs, while hardware-accurate features rely on private API calls through `Dynamic` wrappers.

### Graphics Device: VZMacGraphicsDeviceConfiguration

The display subsystem uses **VZMacGraphicsDeviceConfiguration** with a single **VZMacGraphicsDisplayConfiguration** that specifies width, height, and DPI to match iPhone screen characteristics.

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L61-L69
let gfx = VZMacGraphicsDeviceConfiguration()
let display = VZMacGraphicsDisplayConfiguration(
    widthInPixels: options.screenWidth,
    heightInPixels: options.screenHeight,
    pixelsPerInch: options.screenPPI
)
gfx.displays = [display]
config.graphicsDevices = [gfx]

```

This creates a Retina-compatible virtual display that iOS renders into.

---

### Audio Device: VZVirtioSoundDeviceConfiguration

Audio emulation uses VirtIO with separate input and output stream configurations:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L71-L78
let afg = VZVirtioSoundDeviceConfiguration()
affg.streams = [
    VZVirtioSoundDeviceInputStreamConfiguration(),   // Microphone input
    VZVirtioSoundDeviceOutputStreamConfiguration()   // Speaker output
]
config.audioDevices = [afg]

```

The **VZVirtioSoundDeviceConfiguration** provides standard audio device semantics that iOS audio drivers recognize.

---

### Storage Device: VZVirtioBlockDeviceConfiguration

Persistent storage attaches a disk image through a virtIO block interface:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L80-L86
let attachment = VZDiskImageStorageDeviceAttachment(
    url: options.diskURL,
    readOnly: false
)
let block = VZVirtioBlockDeviceConfiguration(attachment: attachment)
config.storageDevices = [block]

```

The **VZVirtioBlockDeviceConfiguration** presents the VM's root filesystem to iOS as a standard block device.

---

### Network Device: VZVirtioNetworkDeviceConfiguration

Networking is optional and mode-configurable through `VPhoneNetworking.makeNetworkDevice`:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L87-L92
if let net = VPhoneNetworking.makeNetworkDevice(options: options) {
    config.networkDevices = [net]
} else {
    config.networkDevices = []
}

```

The implementation in `sources/VPhoneCore/VPhoneNetworking.swift#L92-L115` supports three modes:
- **NAT** — isolated VM with outbound connectivity
- **Bridged** — full network integration with host interface
- **None** — no network device attached

---

### Serial Port: VZSerialPortConfiguration

A PL011 UART provides console access for debugging and boot logging:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L94-L122
let serialPort = VZSerialPortConfiguration()
let inputPipe = Pipe()
let outputPipe = Pipe()
serialPort.attachment = VZSerialPortAttachment(
    fileHandleForReading: inputPipe.fileHandleForReading,
    fileHandleForWriting: outputPipe.fileHandleForWriting
)
config.serialPorts = [serialPort]

```

Host processes read VM output from `outputPipe` and send input through `inputPipe`.

---

## Private API Devices: Hardware-Accurate Emulation

Several iPhone-specific devices require private Virtualization.framework APIs, accessed through `Dynamic` runtime binding.

### GPU Accelerators

Three accelerator types provide hardware media and ML capabilities:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L24-L30
Dynamic(config)._setAcceleratorDevices([
    VZMacVideoToolboxDeviceConfiguration(),      // Video codec acceleration
    VZMacNeuralEngineDeviceConfiguration(),      // Core ML / ANE access
    VZMacScalerAcceleratorDeviceConfiguration()  // Image scaling operations
])

```

These expose host Apple Silicon media engines to the guest iOS environment.

---

### Multi-Touch Input: VZUSBTouchScreenConfiguration

Touch screen emulation uses a USB HID device:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L32-L36
let touch = VZUSBTouchScreenConfiguration()
Dynamic(config)._setMultiTouchDevices([touch])

```

The **VZUSBTouchScreenConfiguration** translates host touch events into iOS-compatible multi-touch reports.

---

### Power Source: VZMacSyntheticBatterySource

Battery state emulation enables iOS battery monitoring APIs:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L50-L57
let battery = VZMacSyntheticBatterySource()
let batteryDevice = VZMacBatteryPowerSourceDeviceConfiguration(
    battery: battery
)
Dynamic(config)._setPowerSourceDevices([batteryDevice])

```

The **VZMacSyntheticBatterySource** reports synthetic charge states that iOS Settings and apps can query.

---

## Additional Virtual Devices

### Entropy Device: VZVirtioEntropyDeviceConfiguration

Cryptographic randomness for the guest kernel:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L38-L40
let entropy = VZVirtioEntropyDeviceConfiguration()
config.entropyDevices = [entropy]

```

This feeds hardware-derived random data into iOS's entropy pool.

---

### Keyboard: VZUSBKeyboardConfiguration

Standard USB HID keyboard for text input:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L42-L44
config.keyboards = [VZUSBKeyboardConfiguration()]

```

---

### Socket Device: VZVirtioSocketDeviceConfiguration

Host-guest communication channel (vsock), conditionally enabled:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L44-L48
if !options.noVphoned {
    let socket = VZVirtioSocketDeviceConfiguration()
    config.socketDevices = [socket]
}

```

When enabled, the host-side client in [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift) connects to this for VM management.

---

### Debug Infrastructure

Two debugging facilities support development workflows:

**GDB Debug Stub** — remote debugging protocol implementation:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L61-L78
let debugStub = VZGDBDebugStubConfiguration(
    port: options.debugPort ?? 0  // 0 = system-assigned
)
Dynamic(config)._setDebugStub(debugStub)

```

**Secure Enclave Coprocessor** — SEP emulation with optional ROM and dedicated debug stub:

```swift
// From sources/vphone-cli/VPhoneVirtualMachine.swift#L80-L88
let sep = VZSEPCoprocessorConfiguration()
if let romURL = options.romURL {
    sep.rom = VZSEPCoprocessorROMConfiguration(url: romURL)
}
sep.debugStub = VZGDBDebugStubConfiguration(port: sepDebugPort)
Dynamic(config)._setCoprocessors([sep])

```

The **VZSEPCoprocessorConfiguration** is essential for iOS features requiring Secure Enclave services.

---

## Inspecting Configured Devices at Runtime

After VM initialization, you can verify device configuration through the public `VZVirtualMachineConfiguration` API:

```swift
// Inspecting what virtual devices are configured for the vphone-cli VM
if let graphics = vm.configuration?.graphicsDevices?.first 
    as? VZMacGraphicsDeviceConfiguration {
    let display = graphics.displays.first
    print("Display: \(display?.widthInPixels ?? 0)×\(display?.heightInPixels ?? 0) @ \(display?.pixelsPerInch ?? 0) PPI")
}

print("Audio devices: \(vm.configuration?.audioDevices?.count ?? 0)")
print("Storage devices: \(vm.configuration?.storageDevices?.count ?? 0)")
print("Network devices: \(vm.configuration?.networkDevices?.count ?? 0)")
print("Serial ports: \(vm.configuration?.serialPorts?.count ?? 0)")
print("Socket devices: \(vm.configuration?.socketDevices?.count ?? 0)")
print("Keyboards: \(vm.configuration?.keyboards?.count ?? 0)")

```

---

## Source File Reference

| File | Purpose |
|------|---------|
| [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) | Central VM construction and all device configuration |
| [`sources/VPhoneCore/VPhoneNetworking.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/VPhoneCore/VPhoneNetworking.swift) | Network device factory with NAT/bridged/none modes |
| [`sources/vphone-cli/VPhoneControl.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneControl.swift) | Host-side vsock client implementation |
| [`research/VPhoneVirtualMachineRefactored.swift`](https://github.com/Lakr233/vphone-cli/blob/main/research/VPhoneVirtualMachineRefactored.swift) | Extended reference implementation with detailed comments |

The primary configuration logic spans approximately 100 lines in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), assembling what virtual devices are configured for the vphone-cli VM through sequential property assignments on `VZVirtualMachineConfiguration`.

---

## Summary

- **Graphics, audio, storage, and network** use public Virtualization.framework APIs with VirtIO and Mac-specific device configurations
- **Serial ports, entropy, keyboard, and socket** provide standard PC-compatible interfaces that iOS drivers recognize
- **Accelerators, multi-touch, battery, debug stub, and SEP** require private API access via `Dynamic` runtime calls to achieve iPhone hardware fidelity
- **Conditional devices** (network, socket) depend on runtime options; debug infrastructure is development-only
- All device creation is centralized in `VPhoneVirtualMachine.init` with clear separation between public API usage and private hardware emulation

---

## Frequently Asked Questions

### How does vphone-cli achieve iPhone-specific hardware emulation?

The project combines public Virtualization.framework APIs for standard devices with private API calls through Swift runtime dynamic dispatch. Standard devices (storage, audio, network) use documented **VZVirtio***Configuration classes. iPhone-specific features like the Secure Enclave, Neural Engine, and synthetic battery require `_set` methods on `VZVirtualMachineConfiguration` that Apple does not expose publicly—these are accessed via `Dynamic(config)._setAcceleratorDevices()` and similar patterns.

### Can I disable specific virtual devices when creating a vphone-cli VM?

Some devices are conditionally configured based on `VPhoneVirtualMachine.Options`. Set `noVphoned: true` to disable the **VZVirtioSocketDeviceConfiguration**. Network can be disabled by omitting network configuration parameters. However, core devices (graphics, audio, storage, keyboard, entropy) are mandatory and always attached—modifying these requires editing [`sources/vphone-cli/VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneVirtualMachine.swift) directly.

### What resolution and DPI does the vphone-cli VM display use?

The display configuration uses parameters from `Options.screenWidth`, `Options.screenHeight`, and `Options.screenPPI`. Typical iPhone values are 1125×2436 at 458 PPI for iPhone X-class devices, or 1170×2532 at 460 PPI for iPhone 12/13. These map to **VZMacGraphicsDisplayConfiguration** properties that iOS renders into at native Retina density.

### Where is the VM disk image attached in the storage configuration?

The **VZVirtioBlockDeviceConfiguration** receives a **VZDiskImageStorageDeviceAttachment** initialized with `options.diskURL`, typically pointing to an APFS or HFS+ formatted raw disk image containing the iOS root filesystem. This attachment is marked read-write by default (`readOnly: false`), allowing persistent state across VM restarts.