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