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