// 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")
closed 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
    strict 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
    strict SetTrap(resource struct {
        handle Handle:GUEST;
        kind uint32;
        addr Vaddr;
        size usize64;
        port_handle Handle:PORT;
        key uint64;
    }) -> () error Status;
};