1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2014 Intel Corporation
5 #ifndef _RTE_INTERRUPTS_H_
6 #error "don't include this file directly, please include generic <rte_interrupts.h>"
10 * @file rte_eal_interrupts.h
13 * Contains function prototypes exposed by the EAL for interrupt handling by
14 * drivers and other DPDK internal consumers.
17 #ifndef _RTE_EAL_INTERRUPTS_H_
18 #define _RTE_EAL_INTERRUPTS_H_
20 #define RTE_MAX_RXTX_INTR_VEC_ID 512
21 #define RTE_INTR_VEC_ZERO_OFFSET 0
22 #define RTE_INTR_VEC_RXTX_OFFSET 1
25 * The interrupt source type, e.g. UIO, VFIO, ALARM etc.
27 enum rte_intr_handle_type {
28 RTE_INTR_HANDLE_UNKNOWN = 0, /**< generic unknown handle */
29 RTE_INTR_HANDLE_UIO, /**< uio device handle */
30 RTE_INTR_HANDLE_UIO_INTX, /**< uio generic handle */
31 RTE_INTR_HANDLE_VFIO_LEGACY, /**< vfio device handle (legacy) */
32 RTE_INTR_HANDLE_VFIO_MSI, /**< vfio device handle (MSI) */
33 RTE_INTR_HANDLE_VFIO_MSIX, /**< vfio device handle (MSIX) */
34 RTE_INTR_HANDLE_ALARM, /**< alarm handle */
35 RTE_INTR_HANDLE_EXT, /**< external handler */
36 RTE_INTR_HANDLE_VDEV, /**< virtual device */
37 RTE_INTR_HANDLE_DEV_EVENT, /**< device event handle */
38 RTE_INTR_HANDLE_VFIO_REQ, /**< VFIO request handle */
39 RTE_INTR_HANDLE_MAX /**< count of elements */
42 #define RTE_INTR_EVENT_ADD 1UL
43 #define RTE_INTR_EVENT_DEL 2UL
45 typedef void (*rte_intr_event_cb_t)(int fd, void *arg);
47 struct rte_epoll_data {
48 uint32_t event; /**< event type */
49 void *data; /**< User data */
50 rte_intr_event_cb_t cb_fun; /**< IN: callback fun */
51 void *cb_arg; /**< IN: callback arg */
55 RTE_EPOLL_INVALID = 0,
60 /** interrupt epoll event obj, taken by epoll_event.ptr */
61 struct rte_epoll_event {
62 uint32_t status; /**< OUT: event status */
63 int fd; /**< OUT: event fd */
64 int epfd; /**< OUT: epoll instance the ev associated with */
65 struct rte_epoll_data epdata;
68 /** Handle for interrupts. */
69 struct rte_intr_handle {
75 /** VFIO device file descriptor */
77 /** UIO cfg file desc for uio_pci_generic */
80 int fd; /**< interrupt event file descriptor */
82 void *handle; /**< device driver handle (Windows) */
84 enum rte_intr_handle_type type; /**< handle type */
85 uint32_t max_intr; /**< max interrupt requested */
86 uint32_t nb_efd; /**< number of available efd(event fd) */
87 uint8_t efd_counter_size; /**< size of efd counter, used for vdev */
88 int efds[RTE_MAX_RXTX_INTR_VEC_ID]; /**< intr vectors/efds mapping */
89 struct rte_epoll_event elist[RTE_MAX_RXTX_INTR_VEC_ID];
90 /**< intr vector epoll event */
91 int *intr_vec; /**< intr vector number array */
94 #define RTE_EPOLL_PER_THREAD -1 /**< to hint using per thread epfd */
97 * It waits for events on the epoll instance.
98 * Retries if signal received.
101 * Epoll instance fd on which the caller wait for events.
103 * Memory area contains the events that will be available for the caller.
105 * Up to maxevents are returned, must greater than zero.
107 * Specifying a timeout of -1 causes a block indefinitely.
108 * Specifying a timeout equal to zero cause to return immediately.
110 * - On success, returns the number of available event.
111 * - On failure, a negative value.
114 rte_epoll_wait(int epfd, struct rte_epoll_event *events,
115 int maxevents, int timeout);
118 * It waits for events on the epoll instance.
119 * Does not retry if signal received.
122 * Epoll instance fd on which the caller wait for events.
124 * Memory area contains the events that will be available for the caller.
126 * Up to maxevents are returned, must greater than zero.
128 * Specifying a timeout of -1 causes a block indefinitely.
129 * Specifying a timeout equal to zero cause to return immediately.
131 * - On success, returns the number of available event.
132 * - On failure, a negative value.
136 rte_epoll_wait_interruptible(int epfd, struct rte_epoll_event *events,
137 int maxevents, int timeout);
140 * It performs control operations on epoll instance referred by the epfd.
141 * It requests that the operation op be performed for the target fd.
144 * Epoll instance fd on which the caller perform control operations.
146 * The operation be performed for the target fd.
148 * The target fd on which the control ops perform.
150 * Describes the object linked to the fd.
151 * Note: The caller must take care the object deletion after CTL_DEL.
153 * - On success, zero.
154 * - On failure, a negative value.
157 rte_epoll_ctl(int epfd, int op, int fd,
158 struct rte_epoll_event *event);
161 * The function returns the per thread epoll instance.
164 * epfd the epoll instance referred to.
167 rte_intr_tls_epfd(void);
171 * Pointer to the interrupt handle.
173 * Epoll instance fd which the intr vector associated to.
175 * The operation be performed for the vector.
176 * Operation type of {ADD, DEL}.
178 * RX intr vector number added to the epoll instance wait list.
182 * - On success, zero.
183 * - On failure, a negative value.
186 rte_intr_rx_ctl(struct rte_intr_handle *intr_handle,
187 int epfd, int op, unsigned int vec, void *data);
190 * It deletes registered eventfds.
193 * Pointer to the interrupt handle.
196 rte_intr_free_epoll_fd(struct rte_intr_handle *intr_handle);
199 * It enables the packet I/O interrupt event if it's necessary.
200 * It creates event fd for each interrupt vector when MSIX is used,
201 * otherwise it multiplexes a single event fd.
204 * Pointer to the interrupt handle.
206 * Number of interrupt vector trying to enable.
207 * The value 0 is not allowed.
209 * - On success, zero.
210 * - On failure, a negative value.
213 rte_intr_efd_enable(struct rte_intr_handle *intr_handle, uint32_t nb_efd);
216 * It disables the packet I/O interrupt event.
217 * It deletes registered eventfds and closes the open fds.
220 * Pointer to the interrupt handle.
223 rte_intr_efd_disable(struct rte_intr_handle *intr_handle);
226 * The packet I/O interrupt on datapath is enabled or not.
229 * Pointer to the interrupt handle.
232 rte_intr_dp_is_en(struct rte_intr_handle *intr_handle);
235 * The interrupt handle instance allows other causes or not.
236 * Other causes stand for any none packet I/O interrupts.
239 * Pointer to the interrupt handle.
242 rte_intr_allow_others(struct rte_intr_handle *intr_handle);
245 * The multiple interrupt vector capability of interrupt handle instance.
246 * It returns zero if no multiple interrupt vector support.
249 * Pointer to the interrupt handle.
252 rte_intr_cap_multiple(struct rte_intr_handle *intr_handle);
256 * @b EXPERIMENTAL: this API may change without prior notice
259 * Check if currently executing in interrupt context
262 * - non zero in case of interrupt context
263 * - zero in case of process context
267 rte_thread_is_intr(void);
269 #endif /* _RTE_EAL_INTERRUPTS_H_ */