1# zx_guest_create 2 3## NAME 4 5guest_create - create a guest 6 7## SYNOPSIS 8 9``` 10#include <zircon/syscalls.h> 11 12zx_status_t zx_guest_create(zx_handle_t resource, uint32_t options, 13 zx_handle_t* guest_handle, 14 zx_handle_t* vmar_handle); 15``` 16 17## DESCRIPTION 18 19**guest_create**() creates a guest, which is a virtual machine that can be run 20within the hypervisor, with *vmar_handle* used to represent the physical address 21space of the guest. 22 23To create a guest, a *resource* of *ZX_RSRC_KIND_HYPERVISOR* must be supplied. 24 25In order to begin execution within the guest, a VMO should be mapped into 26*vmar_handle* using **vmar_map**(), and a VCPU must be created using 27**vcpu_create**(), and then run using **vcpu_resume**(). 28 29Additionally, a VMO should be mapped into *vmar_handle* to provide a guest with 30physical memory. 31 32The following rights will be set on the handle *guest_handle* by default: 33 34**ZX_RIGHT_TRANSFER** ��� *guest_handle* may be transferred over a channel. 35 36**ZX_RIGHT_DUPLICATE** ��� *guest_handle* may be duplicated. 37 38**ZX_RIGHT_WRITE** ��� A trap to be may be set using **guest_set_trap**(). 39 40**ZX_RIGHT_MANAGE_PROCESS** ��� A VCPU may be created using **vcpu_create**(). 41 42See [vmar_create](vmar_create.md) for the set of rights applied to 43*vmar_handle*. 44 45## RIGHTS 46 47TODO(ZX-2399) 48 49## RETURN VALUE 50 51**guest_create**() returns ZX_OK on success. On failure, an error value is 52returned. 53 54## ERRORS 55 56**ZX_ERR_ACCESS_DENIED** *resource* is not of *ZX_RSRC_KIND_HYPERVISOR*. 57 58**ZX_ERR_INVALID_ARGS** *guest_handle* or *vmar_handle* is an invalid pointer, 59or *options* is nonzero. 60 61**ZX_ERR_NO_MEMORY** Failure due to lack of memory. 62There is no good way for userspace to handle this (unlikely) error. 63In a future build this error will no longer occur. 64 65**ZX_ERR_WRONG_TYPE** *resource* is not a handle to a resource. 66 67## SEE ALSO 68 69[guest_set_trap](guest_set_trap.md), 70[vcpu_create](vcpu_create.md), 71[vcpu_resume](vcpu_resume.md), 72[vcpu_interrupt](vcpu_interrupt.md), 73[vcpu_read_state](vcpu_read_state.md), 74[vcpu_write_state](vcpu_write_state.md), 75[vmar_map](vmar_map.md), 76[vmo_create](vmo_create.md). 77