main/syscalls/interrupt_create.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_interrupt_create

## Summary

Create an interrupt object.

## Declaration

```c
#include <zircon/syscalls.h>

zx_status_t zx_interrupt_create(zx_handle_t src_obj,
                                uint32_t src_num,
                                uint32_t options,
                                zx_handle_t* out_handle);
```

## Description

`zx_interrupt_create()` creates an interrupt object that represents a
(physical)[Interrupts#physical-interrupts] or (virtual)[Interrupts#virtual-interrupts]
interrupt.  Users of Zircon interrupt objects are *strongly* encouraged to read the
(Interrupt Object)[Interrupts] overview documentation to become familiar with the
operational model for interrupt objects before making use of them in code.

To create a physical interrupt, users must:
+ Pass a handle to a suitable resource for creating platform interrupts, or a handle to a
  PCI object, via the *src_obj* parameter.
+ Pass the associated interrupt number via the *src_num* parameter.

Requiring a platform resource or PCI object handle largely restricts the creation of
interrupts to the internals of the [Driver Framework]. Physical interrupts are typically
obtained by drivers through various [Driver Framework] APIs.

Physical interrupts honor the options `ZX_INTERRUPT_MODE_EDGE_LOW`,
`ZX_INTERRUPT_MODE_EDGE_HIGH`, `ZX_INTERRUPT_MODE_LEVEL_LOW`,
`ZX_INTERRUPT_MODE_LEVEL_HIGH`, and `ZX_INTERRUPT_REMAP_IRQ`.

To create a virtual interrupt, users may pass the `ZX_INTERRUPT_VIRTUAL` flag via the
*options* parameter.  Virtual interrupts always behave as edge triggered interrupts, whose
polarity does not need to be specified as they are triggered by software via a call to
[`zx_interrupt_trigger()`] instead of a hardware signal.

Both physical and virtual interrupts honor the option `ZX_INTERRUPT_TIMESTAMP_MONO`.
An interrupt created with this option will return a monotonic timestamp from
[`zx_interrupt_wait()`], and will assume timestamps passed to [`zx_interrupt_trigger()`]
are on the monotonic timeline. By default, these timestamps operate on the boot timeline.

The handles will have `ZX_RIGHT_INSPECT`, `ZX_RIGHT_DUPLICATE`, `ZX_RIGHT_TRANSFER`
(allowing them to be sent to another process via [`zx_channel_write()`]), `ZX_RIGHT_READ`,
`ZX_RIGHT_WRITE` (required for [`zx_interrupt_ack()`]), `ZX_RIGHT_WAIT` (required for
[`zx_interrupt_wait()`], and `ZX_RIGHT_SIGNAL` (required for [`zx_interrupt_trigger()`]).

Interrupts are said to be "triggered" when the underlying physical interrupt occurs or when
[`zx_interrupt_trigger()`] is called on a virtual interrupt.  A triggered interrupt, when
bound to a port with [`zx_interrupt_bind()`], causes a packet to be delivered to the port.
Alternatively, if the interrupt is not bound to a port, users may block a thread on an
interrupt until it is triggered, using a call to [`zx_interrupt_wait()`].

Receiving a notification that an interrupt has occurred, either from port packets or from
calls to [`zx_interrupt_wait()`], and subsequently acknowledging the interrupt when
processing is complete is a moderately complicated process which depends on a number of
factors.  Please see (here)[Interrupts#waiting-for-and-acknowledging-interrupts] for
details.

## Rights

*src_obj* must have resource kind `ZX_RSRC_KIND_IRQ`.

## Return value

`zx_interrupt_create()` returns `ZX_OK` on success. In the event
of failure, a negative error value is returned.

## Errors

`ZX_ERR_BAD_HANDLE` the *src_obj* handle is invalid (if this is not a virtual interrupt)

`ZX_ERR_WRONG_TYPE` the *src_obj* handle is not of an appropriate type to create an interrupt.

`ZX_ERR_ACCESS_DENIED` the *src_obj* handle does not allow this operation.

`ZX_ERR_INVALID_ARGS` *options* contains invalid flags or the *out_handle*
parameter is an invalid pointer.

`ZX_ERR_NO_MEMORY`  Failure due to lack of memory.
There is no good way for userspace to handle this (unlikely) error.
In a future build this error will no longer occur.

## See also

 - [Interrupts]
 - [Driver Framework]
 - [`zx_handle_close()`]
 - [`zx_interrupt_ack()`]
 - [`zx_interrupt_bind()`]
 - [`zx_interrupt_destroy()`]
 - [`zx_interrupt_wait()`]
 - [`zx_port_wait()`]

[Interrupts]: /docs/reference/kernel_objects/interrupts.md
[Interrupts#physical-interrupts]: /docs/reference/kernel_objects/interrupts.md#physical-interrupts
[Interrupts#virtual-interrupts]: /docs/reference/kernel_objects/interrupts.md#virtual-interrupts
[Interrupts#waiting-for-and-acknowledging-interrupts]: /docs/reference/kernel_objects/interrupts.md#waiting-for-and-acknowledging-interrupts
[Driver Framework]: /docs/concepts/drivers/driver_framework.md
[`zx_channel_write()`]: channel_write.md
[`zx_handle_close()`]: handle_close.md
[`zx_interrupt_ack()`]: interrupt_ack.md
[`zx_interrupt_bind()`]: interrupt_bind.md
[`zx_interrupt_destroy()`]: interrupt_destroy.md
[`zx_interrupt_trigger()`]: interrupt_trigger.md
[`zx_interrupt_wait()`]: interrupt_wait.md
[`zx_port_wait()`]: port_wait.md