1 /*
2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #pragma once
8
9 #include <stdint.h>
10 #include <stdbool.h>
11 #include "esp_err.h"
12
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17
18 /** @addtogroup Intr_Alloc
19 * @{
20 */
21
22
23 /** @brief Interrupt allocation flags
24 *
25 * These flags can be used to specify which interrupt qualities the
26 * code calling esp_intr_alloc* needs.
27 *
28 */
29
30 //Keep the LEVELx values as they are here; they match up with (1<<level)
31 #define ESP_INTR_FLAG_LEVEL1 (1<<1) ///< Accept a Level 1 interrupt vector (lowest priority)
32 #define ESP_INTR_FLAG_LEVEL2 (1<<2) ///< Accept a Level 2 interrupt vector
33 #define ESP_INTR_FLAG_LEVEL3 (1<<3) ///< Accept a Level 3 interrupt vector
34 #define ESP_INTR_FLAG_LEVEL4 (1<<4) ///< Accept a Level 4 interrupt vector
35 #define ESP_INTR_FLAG_LEVEL5 (1<<5) ///< Accept a Level 5 interrupt vector
36 #define ESP_INTR_FLAG_LEVEL6 (1<<6) ///< Accept a Level 6 interrupt vector
37 #define ESP_INTR_FLAG_NMI (1<<7) ///< Accept a Level 7 interrupt vector (highest priority)
38 #define ESP_INTR_FLAG_SHARED (1<<8) ///< Interrupt can be shared between ISRs
39 #define ESP_INTR_FLAG_EDGE (1<<9) ///< Edge-triggered interrupt
40 #define ESP_INTR_FLAG_IRAM (1<<10) ///< ISR can be called if cache is disabled
41 #define ESP_INTR_FLAG_INTRDISABLED (1<<11) ///< Return with this interrupt disabled
42
43 #define ESP_INTR_FLAG_LOWMED (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3) ///< Low and medium prio interrupts. These can be handled in C.
44 #define ESP_INTR_FLAG_HIGH (ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6|ESP_INTR_FLAG_NMI) ///< High level interrupts. Need to be handled in assembly.
45
46 #define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
47 ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
48 ESP_INTR_FLAG_NMI) ///< Mask for all level flags
49
50
51 /** @addtogroup Intr_Alloc_Pseudo_Src
52 * @{
53 */
54
55 /**
56 * The esp_intr_alloc* functions can allocate an int for all ETS_*_INTR_SOURCE interrupt sources that
57 * are routed through the interrupt mux. Apart from these sources, each core also has some internal
58 * sources that do not pass through the interrupt mux. To allocate an interrupt for these sources,
59 * pass these pseudo-sources to the functions.
60 */
61 #define ETS_INTERNAL_TIMER0_INTR_SOURCE -1 ///< Platform timer 0 interrupt source
62 #define ETS_INTERNAL_TIMER1_INTR_SOURCE -2 ///< Platform timer 1 interrupt source
63 #define ETS_INTERNAL_TIMER2_INTR_SOURCE -3 ///< Platform timer 2 interrupt source
64 #define ETS_INTERNAL_SW0_INTR_SOURCE -4 ///< Software int source 1
65 #define ETS_INTERNAL_SW1_INTR_SOURCE -5 ///< Software int source 2
66 #define ETS_INTERNAL_PROFILING_INTR_SOURCE -6 ///< Int source for profiling
67
68 /**@}*/
69
70 /** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
71 */
72 #define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
73
74 /** Enable interrupt by interrupt number */
75 #define ESP_INTR_ENABLE(inum) esp_intr_enable_source(inum)
76
77 /** Disable interrupt by interrupt number */
78 #define ESP_INTR_DISABLE(inum) esp_intr_disable_source(inum)
79
80 /** Function prototype for interrupt handler function */
81 typedef void (*intr_handler_t)(void *arg);
82
83 /** Interrupt handler associated data structure */
84 typedef struct intr_handle_data_t intr_handle_data_t;
85
86 /** Handle to an interrupt handler */
87 typedef intr_handle_data_t *intr_handle_t ;
88
89 /**
90 * @brief Mark an interrupt as a shared interrupt
91 *
92 * This will mark a certain interrupt on the specified CPU as
93 * an interrupt that can be used to hook shared interrupt handlers
94 * to.
95 *
96 * @param intno The number of the interrupt (0-31)
97 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
98 * @param is_in_iram Shared interrupt is for handlers that reside in IRAM and
99 * the int can be left enabled while the flash cache is disabled.
100 *
101 * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
102 * ESP_OK otherwise
103 */
104 esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);
105
106 /**
107 * @brief Reserve an interrupt to be used outside of this framework
108 *
109 * This will mark a certain interrupt on the specified CPU as
110 * reserved, not to be allocated for any reason.
111 *
112 * @param intno The number of the interrupt (0-31)
113 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
114 *
115 * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
116 * ESP_OK otherwise
117 */
118 esp_err_t esp_intr_reserve(int intno, int cpu);
119
120 /**
121 * @brief Allocate an interrupt with the given parameters.
122 *
123 * This finds an interrupt that matches the restrictions as given in the flags
124 * parameter, maps the given interrupt source to it and hooks up the given
125 * interrupt handler (with optional argument) as well. If needed, it can return
126 * a handle for the interrupt as well.
127 *
128 * The interrupt will always be allocated on the core that runs this function.
129 *
130 * If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or
131 * RTC_FAST_MEM, then ESP_ERR_INVALID_ARG is returned.
132 *
133 * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
134 * sources, as defined in soc/soc.h, or one of the internal
135 * ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
136 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
137 * choice of interrupts that this routine can choose from. If this value
138 * is 0, it will default to allocating a non-shared interrupt of level
139 * 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
140 * interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
141 * from this function with the interrupt disabled.
142 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
143 * is requested, because these types of interrupts aren't C-callable.
144 * @param arg Optional argument for passed to the interrupt handler
145 * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
146 * used to request details or free the interrupt. Can be NULL if no handle
147 * is required.
148 *
149 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
150 * ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
151 * ESP_OK otherwise
152 */
153 esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
154
155
156 /**
157 * @brief Allocate an interrupt with the given parameters.
158 *
159 *
160 * This essentially does the same as esp_intr_alloc, but allows specifying a register and mask
161 * combo. For shared interrupts, the handler is only called if a read from the specified
162 * register, ANDed with the mask, returns non-zero. By passing an interrupt status register
163 * address and a fitting mask, this can be used to accelerate interrupt handling in the case
164 * a shared interrupt is triggered; by checking the interrupt statuses first, the code can
165 * decide which ISRs can be skipped
166 *
167 * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
168 * sources, as defined in soc/soc.h, or one of the internal
169 * ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
170 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
171 * choice of interrupts that this routine can choose from. If this value
172 * is 0, it will default to allocating a non-shared interrupt of level
173 * 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
174 * interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
175 * from this function with the interrupt disabled.
176 * @param intrstatusreg The address of an interrupt status register
177 * @param intrstatusmask A mask. If a read of address intrstatusreg has any of the bits
178 * that are 1 in the mask set, the ISR will be called. If not, it will be
179 * skipped.
180 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
181 * is requested, because these types of interrupts aren't C-callable.
182 * @param arg Optional argument for passed to the interrupt handler
183 * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
184 * used to request details or free the interrupt. Can be NULL if no handle
185 * is required.
186 *
187 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
188 * ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
189 * ESP_OK otherwise
190 */
191 esp_err_t esp_intr_alloc_intrstatus(int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
192
193
194 /**
195 * @brief Disable and free an interrupt.
196 *
197 * Use an interrupt handle to disable the interrupt and release the resources associated with it.
198 * If the current core is not the core that registered this interrupt, this routine will be assigned to
199 * the core that allocated this interrupt, blocking and waiting until the resource is successfully released.
200 *
201 * @note
202 * When the handler shares its source with other handlers, the interrupt status
203 * bits it's responsible for should be managed properly before freeing it. see
204 * ``esp_intr_disable`` for more details. Please do not call this function in ``esp_ipc_call_blocking``.
205 *
206 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
207 *
208 * @return ESP_ERR_INVALID_ARG the handle is NULL
209 * ESP_FAIL failed to release this handle
210 * ESP_OK otherwise
211 */
212 esp_err_t esp_intr_free(intr_handle_t handle);
213
214
215 /**
216 * @brief Get CPU number an interrupt is tied to
217 *
218 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
219 *
220 * @return The core number where the interrupt is allocated
221 */
222 int esp_intr_get_cpu(intr_handle_t handle);
223
224 /**
225 * @brief Get the allocated interrupt for a certain handle
226 *
227 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
228 *
229 * @return The interrupt number
230 */
231 int esp_intr_get_intno(intr_handle_t handle);
232
233 /**
234 * @brief Disable the interrupt associated with the handle
235 *
236 * @note
237 * 1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
238 * CPU the interrupt is allocated on. Other interrupts have no such restriction.
239 * 2. When several handlers sharing a same interrupt source, interrupt status bits, which are
240 * handled in the handler to be disabled, should be masked before the disabling, or handled
241 * in other enabled interrupts properly. Miss of interrupt status handling will cause infinite
242 * interrupt calls and finally system crash.
243 *
244 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
245 *
246 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
247 * ESP_OK otherwise
248 */
249 esp_err_t esp_intr_disable(intr_handle_t handle);
250
251 /**
252 * @brief Enable the interrupt associated with the handle
253 *
254 * @note For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
255 * CPU the interrupt is allocated on. Other interrupts have no such restriction.
256 *
257 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
258 *
259 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
260 * ESP_OK otherwise
261 */
262 esp_err_t esp_intr_enable(intr_handle_t handle);
263
264 /**
265 * @brief Set the "in IRAM" status of the handler.
266 *
267 * @note Does not work on shared interrupts.
268 *
269 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
270 * @param is_in_iram Whether the handler associated with this handle resides in IRAM.
271 * Handlers residing in IRAM can be called when cache is disabled.
272 *
273 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
274 * ESP_OK otherwise
275 */
276 esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram);
277
278 /**
279 * @brief Disable interrupts that aren't specifically marked as running from IRAM
280 */
281 void esp_intr_noniram_disable(void);
282
283 /**
284 * @brief Re-enable interrupts disabled by esp_intr_noniram_disable
285 */
286 void esp_intr_noniram_enable(void);
287
288 /**
289 * @brief enable the interrupt source based on its number
290 * @param inum interrupt number from 0 to 31
291 */
292 void esp_intr_enable_source(int inum);
293
294 /**
295 * @brief disable the interrupt source based on its number
296 * @param inum interrupt number from 0 to 31
297 */
298 void esp_intr_disable_source(int inum);
299
300 /**
301 * @brief Get the lowest interrupt level from the flags
302 * @param flags The same flags that pass to `esp_intr_alloc_intrstatus` API
303 */
esp_intr_flags_to_level(int flags)304 static inline int esp_intr_flags_to_level(int flags)
305 {
306 return __builtin_ffs((flags & ESP_INTR_FLAG_LEVELMASK) >> 1) + 1;
307 }
308
309 /**@}*/
310
311
312 #ifdef __cplusplus
313 }
314 #endif
315
