blob: c5e516bd3bc980c8a26f9581988b1b17c185b3ee [file] [log] [blame] [view]
# zx_guest_create
## NAME
<!-- Updated by update-docs-from-abigen, do not edit. -->
Create a guest.
## SYNOPSIS
<!-- Updated by update-docs-from-abigen, do not edit. -->
```c
#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);
```
## DESCRIPTION
`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_HYPERVISOR** must be supplied.
In order to begin execution within the guest, a VMO should be mapped into
*vmar_handle* using [`zx_vmar_map()`], and a VCPU must be created using
[`zx_vcpu_create()`], and then run using [`zx_vcpu_resume()`].
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** &mdash; *guest_handle* may be transferred over a channel.
**ZX_RIGHT_DUPLICATE** &mdash; *guest_handle* may be duplicated.
**ZX_RIGHT_WRITE** &mdash; A trap to be may be set using [`zx_guest_set_trap()`].
**ZX_RIGHT_MANAGE_PROCESS** &mdash; A VCPU may be created using [`zx_vcpu_create()`].
See [`zx_vmo_create()`] for the set of rights applied to *vmar_handle*.
## RIGHTS
<!-- Updated by update-docs-from-abigen, do not edit. -->
*resource* must have resource kind **ZX_RSRC_KIND_HYPERVISOR**.
## RETURN VALUE
`zx_guest_create()` returns **ZX_OK** on success. On failure, an error value is
returned.
## ERRORS
**ZX_ERR_ACCESS_DENIED** *resource* is not of **ZX_RSRC_KIND_HYPERVISOR**.
**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.
## SEE ALSO
- [`zx_guest_set_trap()`]
- [`zx_vcpu_create()`]
- [`zx_vcpu_interrupt()`]
- [`zx_vcpu_read_state()`]
- [`zx_vcpu_resume()`]
- [`zx_vcpu_write_state()`]
- [`zx_vmar_map()`]
- [`zx_vmo_create()`]
<!-- References updated by update-docs-from-abigen, do not edit. -->
[`zx_guest_set_trap()`]: guest_set_trap.md
[`zx_vcpu_create()`]: vcpu_create.md
[`zx_vcpu_interrupt()`]: vcpu_interrupt.md
[`zx_vcpu_read_state()`]: vcpu_read_state.md
[`zx_vcpu_resume()`]: vcpu_resume.md
[`zx_vcpu_write_state()`]: vcpu_write_state.md
[`zx_vmar_map()`]: vmar_map.md
[`zx_vmo_create()`]: vmo_create.md