Framework

Hypervisor

Build virtualization solutions on top of a lightweight hypervisor, without the need for third-party kernel extensions.

Overview

The Hypervisor framework provides C APIs for interacting with virtualization technologies in user-space, without the need for writing kernel extensions (KEXTs). As a result, apps created using this framework are suitable for distribution on the Mac App Store.

Hardware-facilitated virtual machines (VMs) and virtual processors (vCPUs) can be created and controlled by an entitled sandboxed user space process, the hypervisor client. The Hypervisor framework abstracts virtual machines as tasks and virtual processors as threads.

Requirements

The Hypervisor framework has the following requirements:

Entitlements

A sandboxed user space process must have the com.apple.vm.hypervisor entitlement in order to use Hypervisor APIs.

Supported Hardware

Generally, machines with an Intel VT-x feature set that includes Extended Page Tables (EPT) and Unrestricted Mode are supported. You can determine the availability of Hypervisor APIs on a particular machine at runtime with the sysctl(8) command, passing kern.hv_support as an argument.

Example VM Life Cycle

The following figure illustrates a simplified life cycle of creating and running a virtual machine with one or more virtual CPUs using the Hypervisor Framework API.

Figure 1

An example life cycle of creating and running a virtual machine with one or more virtual CPUs.

A flow diagram representing the life cycle of a virtual machine.

At the start of a task, create a VM, map a region in the virtual address space of the task into the guest physical address space of the VM, and create POSIX Threads. Then, create one or more virtual CPUs, run the task on a POSIX thread, handle the VMEXIT event, and then destroy the virtual CPU. After virtual CPUs are destroyed, end the POSIX threads, unmap the memory region, and finally destroy the VM.

Topics

Creating and Destroying VM Instances

hv_vm_create

Creates a VM instance for the current task.

hv_vm_destroy

Destroys the VM instance associated with the current task.

Managing Memory Regions

hv_vm_map

Maps a region in the virtual address space of the current task into the guest physical address space of the VM.

hv_vm_unmap

Unmaps a region in the guest physical address space of the VM.

hv_vm_protect

Modifies the permissions of a region in the guest physical address space of the VM.

Creating and Managing vCPU Instances

hv_vcpu_create

Creates a vCPU instance for the current thread.

hv_vcpu_destroy

Destroys the vCPU instance associated with the current thread.

hv_vcpu_run

Executes a vCPU.

hv_vcpu_interrupt

Forces an immediate VMEXIT of a set of vCPU instances of the VM.

hv_vcpu_invalidate_tlb

Invalidates the translation look-aside buffer (TLB) of a vCPU.

hv_vcpu_flush

Flushes the cached state of a vCPU.

hv_vcpu_enable_native_msr

Enables or disables a machine specific register (MSR) to be used natively by the VM.

hv_vcpu_get_exec_time

Returns, by reference, the cumulative execution time of a vCPU, in nanoseconds.

Managing Timestamp-Counters (TSC)

hv_vm_sync_tsc

Synchronizes guest timestamp-counters (TSC) across all vCPUs.

Accessing Registers

hv_vcpu_read_register

Returns, by reference, the current value of an architectural x86 register of a vCPU.

hv_vcpu_write_register

Sets the value of an architectural x86 register of a vCPU.

Accessing Floating Point (FP) State

hv_vcpu_read_fpstate

Returns, by reference, the current architectural x86 floating point and SIMD state of a vCPU.

hv_vcpu_write_fpstate

Sets the architectural x86 floating point and SIMD state of a vCPU.

Accessing Machine Specific Registers (MSRs)

hv_vcpu_read_msr

Returns, by reference, the current value of a machine specific register (MSR) of a vCPU.

hv_vcpu_write_msr

Sets the value of a machine specific register (MSR) of a vCPU.

Data Types

hv_return_t

The return type for Hypervisor Framework functions.

hv_vm_options_t

Options for the hv_vm_create function.

hv_vcpu_options_t

Options for the hv_vcpu_create function.

hv_memory_flags_t

Guest physical memory region permissions for the hv_vm_map and hv_vm_protect functions.

hv_x86_reg_t

x86 architectural register IDs.

hv_vcpuid_t

Type of a vCPU ID.

hv_uvaddr_t

Type of a user virtual address.

hv_gpaddr_t

Type of a guest physical address (GPA).