Contents

Hypervisor

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

Overview

Hypervisor provides C APIs so you can interact with virtualization technologies in user space, without writing kernel extensions (KEXTs). As a result, the apps you create using this framework are suitable for distribution on the Mac App Store.

Use this framework to create and control hardware-facilitated virtual machines and virtual processors (VMs and vCPUs) from your entitled, sandboxed, user-space process. Hypervisor abstracts virtual machines as processes, and virtual processors as threads.

Requirements

The Hypervisor framework has the following requirements:

Supported hardware

The Hypervisor framework requires hardware support to virtualize hardware resources. On Apple silicon, that includes the Virtualization Extensions. On Intel-based Mac computers, the framework supports machines with an Intel VT-x feature set that includes Extended Page Tables (EPT) and Unrestricted Mode.

At runtime, determine whether the Hypervisor APIs are available on a particular machine with the sysctl command, passing kern.hv_support as an argument.

Entitlements

All process must have the com.apple.security.hypervisor entitlement to use Hypervisor API.

Virtual Resource Mapping

A guest is an operating system that runs on top of the virtual hardware. The operating system and processes that run the virtualized hardware are together called the host. Virtual hardware in the guest maps to specific resources on the host.

Each virtual machine corresponds to a process on the host. There can only be one virtual machine at a time per process; the virtual machine creates it with hv_vm_create(_:).

Virtual CPUs (vCPUs) in a virtual machine map to POSIX threads. Create a new vCPU for the current thread with hv_vcpu_create(_:_:_:). The vCPU runs when the thread calls hv_vcpu_run(_:).

Hypervisor maps the physical memory in the guest to virtual memory of the host process. Create a new memory mapping with hv_vm_map(_:_:_:_:). Access to memory outside the mapped range causes hv_vcpu_run(_:) to exit. Emulate memory-mapped hardware by emulating the memory access on exit and re-enter the guest with hv_vcpu_run(_:).

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 API.

[Image]

At the start of a task:

  • Create a VM with hv_vm_create(_:).

  • Map a region in the virtual address space of the current task into the guest physical address space of the VM with hv_vm_map(_:_:_:_:).

  • Create one or more POSIX threads with pthread_create(_:_:_:_:).

In each thread:

When a thread receives an exit event:

After all threads finish:

Topics

Platforms

Entitlements

Reference

Structures

Variables

Functions