Create a guest.
#include <zircon/syscalls.h> zx_status_t zx_guest_create(zx_handle_t resource, uint32_t options, zx_handle_t* guest_handle, zx_handle_t* vmar_handle);
zx_guest_create() creates a guest, which is a virtual machine that can be run within the hypervisor, with vmar_handle used to represent the physical address space of the guest.
To create a guest, a resource of ZX_RSRC_KIND_SYSTEM with ZX_RSRC_SYSTEM_HYPERVISOR_BASE must be supplied.
Additionally, a VMO should be mapped into vmar_handle to provide a guest with physical memory.
The following rights will be set on the handle guest_handle by default:
ZX_RIGHT_TRANSFER — guest_handle may be transferred over a channel.
ZX_RIGHT_DUPLICATE — guest_handle may be duplicated.
ZX_RIGHT_WRITE — A trap to be may be set using
ZX_RIGHT_MANAGE_THREAD — A VCPU may be created using
zx_vmo_create() for the set of rights applied to vmar_handle.
resource must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_HYPERVISOR_BASE.
zx_guest_create() returns ZX_OK on success. On failure, an error value is returned.
ZX_ERR_NOT_SUPPORTED The hypervisor is not supported by the device.
ZX_ERR_ACCESS_DENIED resource is not of kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_HYPERVISOR_BASE.
ZX_ERR_INVALID_ARGS guest_handle or vmar_handle is an invalid pointer, or options is nonzero.
ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.
ZX_ERR_WRONG_TYPE resource is not a handle to a resource.