blob: 758621570f9937ba46bda31e4fd019445fb0afde [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library zx;
@transport("Syscall")
protocol Guest {
/// ## Summary
///
/// Create a guest.
///
/// ## Declaration
///
/// ```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_SYSTEM** with
/// **ZX_RSRC_SYSTEM_HYPERVISOR_BASE** 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_enter()`].
///
/// 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_THREAD** &mdash; A VCPU may be created using [`zx_vcpu_create()`].
///
/// See [`zx_vmo_create()`] for the set of rights applied to *vmar_handle*.
///
/// ## Rights
///
/// *resource* must have resource kind **ZX_RSRC_KIND_SYSTEM** with base
/// **ZX_RSRC_SYSTEM_HYPERVISOR_BASE**.
///
/// ## Return value
///
/// `zx_guest_create()` returns **ZX_OK** on success. On failure, an error value is
/// returned.
///
/// ## Errors
///
/// **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.
///
/// ## See also
///
/// - [`zx_guest_set_trap()`]
/// - [`zx_vcpu_create()`]
/// - [`zx_vcpu_enter()`]
/// - [`zx_vcpu_interrupt()`]
/// - [`zx_vcpu_kick()`]
/// - [`zx_vcpu_read_state()`]
/// - [`zx_vcpu_write_state()`]
/// - [`zx_vmar_map()`]
/// - [`zx_vmo_create()`]
///
/// [`zx_guest_set_trap()`]: guest_set_trap.md
/// [`zx_vcpu_create()`]: vcpu_create.md
/// [`zx_vcpu_enter()`]: vcpu_enter.md
/// [`zx_vcpu_interrupt()`]: vcpu_interrupt.md
/// [`zx_vcpu_kick()`]: vcpu_kick.md
/// [`zx_vcpu_read_state()`]: vcpu_read_state.md
/// [`zx_vcpu_write_state()`]: vcpu_write_state.md
/// [`zx_vmar_map()`]: vmar_map.md
/// [`zx_vmo_create()`]: vmo_create.md
Create(resource struct {
resource handle:RESOURCE;
options uint32;
}) -> (resource struct {
guest_handle handle:GUEST;
vmar_handle handle:VMAR;
}) error status;
/// ## Summary
///
/// Sets a trap within a guest.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_guest_set_trap(zx_handle_t handle,
/// uint32_t kind,
/// zx_vaddr_t addr,
/// size_t size,
/// zx_handle_t port_handle,
/// uint64_t key);
/// ```
///
/// ## Description
///
/// `zx_guest_set_trap()` sets a trap within a guest, which generates a packet when
/// there is an access by a VCPU within the address range defined by *addr* and
/// *size*, within the address space defined by *kind*.
///
/// *kind* may be either **ZX_GUEST_TRAP_BELL**, **ZX_GUEST_TRAP_MEM**, or
/// **ZX_GUEST_TRAP_IO**. If **ZX_GUEST_TRAP_BELL** or **ZX_GUEST_TRAP_MEM** is
/// specified, then *addr* and *size* must both be page-aligned.
/// **ZX_GUEST_TRAP_BELL** is an asynchronous trap, and both **ZX_GUEST_TRAP_MEM**
/// and **ZX_GUEST_TRAP_IO** are synchronous traps.
///
/// Packets for synchronous traps will be delivered through [`zx_vcpu_enter()`] and
/// packets for asynchronous traps will be delivered through *port_handle*.
///
/// *port_handle* must be **ZX_HANDLE_INVALID** for synchronous traps. For
/// asynchronous traps *port_handle* must be valid and a packet for the trap will be
/// delivered through *port_handle* each time the trap is triggered. A fixed number
/// of packets are pre-allocated per trap. If all the packets are exhausted,
/// execution of the VCPU that caused the trap will be paused. When at least one
/// packet is dequeued, execution of the VCPU will resume. To dequeue a packet from
/// *port_handle*, use [`zx_port_wait()`]. Multiple threads may use
/// [`zx_port_wait()`] to dequeue packets, enabling the use of a thread pool to
/// handle traps.
///
/// *key* is used to set the key field within `zx_port_packet_t`, and can be used to
/// distinguish between packets for different traps.
///
/// **ZX_GUEST_TRAP_BELL** is a type of trap that defines a door-bell. If there is
/// an access to the memory region specified by the trap, then a packet is generated
/// that does not fetch the instruction associated with the access. The packet will
/// then be delivered asynchronously via *port_handle*.
///
/// To identify what *kind* of trap generated a packet, use
/// **ZX_PKT_TYPE_GUEST_MEM**, **ZX_PKT_TYPE_GUEST_IO**, **ZX_PKT_TYPE_GUEST_BELL**,
/// and **ZX_PKT_TYPE_GUEST_VCPU**. **ZX_PKT_TYPE_GUEST_VCPU** is a special packet,
/// not caused by a trap, that indicates that the guest requested to start an
/// additional VCPU.
///
/// ## Rights
///
/// *handle* must be of type **ZX_OBJ_TYPE_GUEST** and have **ZX_RIGHT_WRITE**.
///
/// *port_handle* must be of type **ZX_OBJ_TYPE_PORT** and have **ZX_RIGHT_WRITE**.
///
/// ## Return value
///
/// `zx_guest_set_trap()` returns **ZX_OK** on success. On failure, an error value is
/// returned.
///
/// ## Errors
///
/// **ZX_ERR_ACCESS_DENIED** *handle* or *port_handle* do not have the
/// **ZX_RIGHT_WRITE** right.
///
/// **ZX_ERR_ALREADY_EXISTS** A trap for *kind* already exists that intersects with
/// *addr* and *size*.
///
/// **ZX_ERR_BAD_HANDLE** *handle* or *port_handle* are invalid handles.
///
/// **ZX_ERR_INVALID_ARGS** *kind* is not a valid address space, or
/// **ZX_GUEST_TRAP_MEM** was specified with a *port_handle*.
///
/// **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_OUT_OF_RANGE** The region specified by *addr* and *size* is outside of
/// of the valid bounds of the address space *kind*.
///
/// **ZX_ERR_WRONG_TYPE** *handle* is not a handle to a guest, or *port_handle* is
/// not a handle to a port.
///
/// ## Notes
///
/// **ZX_GUEST_TRAP_BELL** shares the same address space as **ZX_GUEST_TRAP_MEM**.
///
/// On x86-64, if *kind* is **ZX_GUEST_TRAP_BELL** or **ZX_GUEST_TRAP_MEM** and *addr*
/// is the address of the local APIC, then *size* must be equivalent to the size of
/// a page. This is due to a special page being mapped when a trap is requested at the
/// address of the local APIC. This allows us to take advantage of hardware
/// acceleration when available.
///
/// ## See also
///
/// - [`zx_guest_create()`]
/// - [`zx_port_create()`]
/// - [`zx_port_wait()`]
/// - [`zx_vcpu_create()`]
/// - [`zx_vcpu_enter()`]
/// - [`zx_vcpu_interrupt()`]
/// - [`zx_vcpu_kick()`]
/// - [`zx_vcpu_read_state()`]
/// - [`zx_vcpu_write_state()`]
///
/// [`zx_guest_create()`]: guest_create.md
/// [`zx_port_create()`]: port_create.md
/// [`zx_port_wait()`]: port_wait.md
/// [`zx_vcpu_create()`]: vcpu_create.md
/// [`zx_vcpu_enter()`]: vcpu_enter.md
/// [`zx_vcpu_interrupt()`]: vcpu_interrupt.md
/// [`zx_vcpu_kick()`]: vcpu_kick.md
/// [`zx_vcpu_read_state()`]: vcpu_read_state.md
/// [`zx_vcpu_write_state()`]: vcpu_write_state.md
SetTrap(resource struct {
handle handle:GUEST;
kind uint32;
addr vaddr;
size usize;
port_handle handle:PORT;
key uint64;
}) -> () error status;
};