1# zx_interrupt_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7interrupt_create - create an interrupt object
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_interrupt_create(zx_handle_t src_obj,
17                                uint32_t src_num,
18                                uint32_t options,
19                                zx_handle_t* out_handle);
20```
21
22## DESCRIPTION
23
24`zx_interrupt_create()` creates an interrupt object which represents a physical
25or virtual interrupt.
26
27If *options* is **ZX_INTERRUPT_VIRTUAL**, *src_obj* and *src_num* are ignored and
28a virtual interrupt is returned.
29
30Otherwise *src_obj* must be a suitable resource for creating platform interrupts
31or a PCI object, and *src_num* is the associated interrupt number.  This restricts
32the creation of interrupts to the internals of the DDK (driver development kit).
33Physical interrupts are obtained by drivers through various DDK APIs.
34
35Physical interrupts honor the options **ZX_INTERRUPT_EDGE_LOW**, **ZX_INTERRUPT_EDGE_HIGH**,
36**ZX_INTERRUPT_LEVEL_LOW**, **ZX_INTERRUPT_LEVEL_HIGH**, and **ZX_INTERRUPT_REMAP_IRQ**.
37
38The handles will have **ZX_RIGHT_INSPECT**, **ZX_RIGHT_DUPLICATE**, **ZX_RIGHT_TRANSFER**
39(allowing them to be sent to another process via channel write), **ZX_RIGHT_READ**,
40**ZX_RIGHT_WRITE** (required for [`zx_interrupt_ack()`]), **ZX_RIGHT_WAIT** (required for
41[`zx_interrupt_wait()`], and **ZX_RIGHT_SIGNAL** (required for [`zx_interrupt_trigger()`]).
42
43Interrupts are said to be "triggered" when the underlying physical interrupt occurs
44or when [`zx_interrupt_trigger()`] is called on a virtual interrupt.  A triggered interrupt,
45when bound to a port with [`zx_interrupt_bind()`], causes a packet to be delivered to the port.
46
47If not bound to a port, an interrupt object may be waited on with [`zx_interrupt_wait()`].
48
49Interrupts cannot be waited on with the `zx_object_wait_` family of calls.
50
51## RIGHTS
52
53<!-- Updated by update-docs-from-abigen, do not edit. -->
54
55*src_obj* must have resource kind **ZX_RSRC_KIND_IRQ**.
56
57## RETURN VALUE
58
59`zx_interrupt_create()` returns **ZX_OK** on success. In the event
60of failure, a negative error value is returned.
61
62## ERRORS
63
64**ZX_ERR_BAD_HANDLE** the *src_obj* handle is invalid (if this is not a virtual interrupt)
65
66**ZX_ERR_WRONG_TYPE** the *src_obj* handle is not of an appropriate type to create an interrupt.
67
68**ZX_ERR_ACCESS_DENIED** the *src_obj* handle does not allow this operation.
69
70**ZX_ERR_INVALID_ARGS** *options* contains invalid flags or the *out_handle*
71parameter is an invalid pointer.
72
73**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
74There is no good way for userspace to handle this (unlikely) error.
75In a future build this error will no longer occur.
76
77## SEE ALSO
78
79 - [`zx_handle_close()`]
80 - [`zx_interrupt_ack()`]
81 - [`zx_interrupt_bind()`]
82 - [`zx_interrupt_destroy()`]
83 - [`zx_interrupt_wait()`]
84 - [`zx_port_wait()`]
85
86<!-- References updated by update-docs-from-abigen, do not edit. -->
87
88[`zx_handle_close()`]: handle_close.md
89[`zx_interrupt_ack()`]: interrupt_ack.md
90[`zx_interrupt_bind()`]: interrupt_bind.md
91[`zx_interrupt_destroy()`]: interrupt_destroy.md
92[`zx_interrupt_trigger()`]: interrupt_trigger.md
93[`zx_interrupt_wait()`]: interrupt_wait.md
94[`zx_port_wait()`]: port_wait.md
95