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