1# zx_guest_set_trap 2 3## NAME 4 5guest_set_trap - sets a trap within a guest 6 7## SYNOPSIS 8 9``` 10#include <zircon/syscalls.h> 11#include <zircon/syscalls/port.h> 12 13zx_status_t zx_guest_set_trap(zx_handle_t guest, uint32_t kind, zx_vaddr_t addr, 14 size_t len, zx_handle_t port, uint64_t key); 15``` 16 17## DESCRIPTION 18 19**guest_set_trap**() sets a trap within a guest, which generates a packet when 20there is an access by a VCPU within the address range defined by *addr* and 21*len*, within the address space defined by *kind*. 22 23If *port* is specified, a packet for the trap will be delivered through *port* 24each time the trap is triggered, otherwise if *ZX_HANDLE_INVALID* is given, a 25packet will be delivered through **vcpu_resume**(). This provides control over 26whether the packet is delivered asynchronously or synchronously. 27 28When *port* is specified, a fixed number of packets are pre-allocated per trap. 29If all the packets are exhausted, execution of the VCPU that caused the trap 30will be paused. When at least one packet is dequeued, execution of the VCPU will 31resume. To dequeue a packet from *port*, use **port_wait**(). Multiple threads 32may use **port_wait**() to dequeue packets, enabling the use of a thread pool to 33handle traps. 34 35*key* is used to set the key field within *zx_port_packet_t*, and can be used to 36distinguish between packets for different traps. 37 38*kind* may be either *ZX_GUEST_TRAP_BELL*, *ZX_GUEST_TRAP_MEM*, or 39*ZX_GUEST_TRAP_IO*. If *ZX_GUEST_TRAP_BELL* or *ZX_GUEST_TRAP_MEM* is specified, 40then *addr* and *len* must both be page-aligned. If *ZX_GUEST_TRAP_BELL* is set, 41then *port* must be specified. If *ZX_GUEST_TRAP_MEM* or *ZX_GUEST_TRAP_IO* is 42set, then *port* must be *ZX_HANDLE_INVALID*. 43 44*ZX_GUEST_TRAP_BELL* is a type of trap that defines a door-bell. If there is an 45access to the memory region specified by the trap, then a packet is generated 46that does not fetch the instruction associated with the access. The packet will 47then be delivered via *port*. 48 49To identify what *kind* of trap generated a packet, use *ZX_PKT_TYPE_GUEST_MEM*, 50*ZX_PKT_TYPE_GUEST_IO*, *ZX_PKT_TYPE_GUEST_BELL*, and *ZX_PKT_TYPE_GUEST_VCPU*. 51*ZX_PKT_TYPE_GUEST_VCPU* is a special packet, not caused by a trap, that 52indicates that the guest requested to start an additional VCPU. 53 54## RIGHTS 55 56TODO(ZX-2399) 57 58## RETURN VALUE 59 60**guest_set_trap**() returns ZX_OK on success. On failure, an error value is 61returned. 62 63## ERRORS 64 65**ZX_ERR_ACCESS_DENIED** *guest* or *port* do not have the *ZX_RIGHT_WRITE* 66right. 67 68**ZX_ERR_ALREADY_EXISTS** A trap with the same *kind* and *addr* already exists. 69 70**ZX_ERR_BAD_HANDLE** *guest* or *port* are invalid handles. 71 72**ZX_ERR_INVALID_ARGS** *kind* is not a valid address space, *addr* or *len* 73do not meet the requirements of *kind*, *len* is 0, or *ZX_GUEST_TRAP_MEM* was 74specified with a *port*. 75 76**ZX_ERR_NO_MEMORY** Failure due to lack of memory. 77There is no good way for userspace to handle this (unlikely) error. 78In a future build this error will no longer occur. 79 80**ZX_ERR_OUT_OF_RANGE** The region specified by *addr* and *len* is outside of 81of the valid bounds of the address space *kind*. 82 83**ZX_ERR_WRONG_TYPE** *guest* is not a handle to a guest, or *port* is not a 84handle to a port. 85 86## NOTES 87 88*ZX_GUEST_TRAP_BELL* shares the same address space as *ZX_GUEST_TRAP_MEM*. 89 90On x86-64, if *kind* is *ZX_GUEST_TRAP_BELL* or *ZX_GUEST_TRAP_MEM* and *addr* 91is the address of the local APIC, then *len* must be equivalent to the size of a 92page. This is due to a special page being mapped when a trap is requested at the 93address of the local APIC. This allows us to take advantage of hardware 94acceleration when available. 95 96## SEE ALSO 97 98[guest_create](guest_create.md), 99[port_create](port_create.md), 100[port_wait](port_wait.md), 101[vcpu_create](vcpu_create.md), 102[vcpu_resume](vcpu_resume.md), 103[vcpu_interrupt](vcpu_interrupt.md), 104[vcpu_read_state](vcpu_read_state.md), 105[vcpu_write_state](vcpu_write_state.md). 106