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