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