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 #define ETS_INTERNAL_UNUSED_INTR_SOURCE -99 ///< Interrupt is not assigned to any source
68
69 /**@}*/
70
71 /** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
72 */
73 #define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
74
75 /** Enable interrupt by interrupt number */
76 #define ESP_INTR_ENABLE(inum) esp_intr_enable_source(inum)
77
78 /** Disable interrupt by interrupt number */
79 #define ESP_INTR_DISABLE(inum) esp_intr_disable_source(inum)
80
81 /** Function prototype for interrupt handler function */
82 typedef void (*intr_handler_t)(void *arg);
83
84 /** Interrupt handler associated data structure */
85 typedef struct intr_handle_data_t intr_handle_data_t;
86
87 /** Handle to an interrupt handler */
88 typedef intr_handle_data_t *intr_handle_t ;
89
90 /**
91 * @brief Mark an interrupt as a shared interrupt
92 *
93 * This will mark a certain interrupt on the specified CPU as
94 * an interrupt that can be used to hook shared interrupt handlers
95 * to.
96 *
97 * @param intno The number of the interrupt (0-31)
98 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
99 * @param is_in_iram Shared interrupt is for handlers that reside in IRAM and
100 * the int can be left enabled while the flash cache is disabled.
101 *
102 * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
103 * ESP_OK otherwise
104 */
105 esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);
106
107 /**
108 * @brief Reserve an interrupt to be used outside of this framework
109 *
110 * This will mark a certain interrupt on the specified CPU as
111 * reserved, not to be allocated for any reason.
112 *
113 * @param intno The number of the interrupt (0-31)
114 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
115 *
116 * @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
117 * ESP_OK otherwise
118 */
119 esp_err_t esp_intr_reserve(int intno, int cpu);
120
121 /**
122 * @brief Allocate an interrupt with the given parameters.
123 *
124 * This finds an interrupt that matches the restrictions as given in the flags
125 * parameter, maps the given interrupt source to it and hooks up the given
126 * interrupt handler (with optional argument) as well. If needed, it can return
127 * a handle for the interrupt as well.
128 *
129 * The interrupt will always be allocated on the core that runs this function.
130 *
131 * If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or
132 * RTC_FAST_MEM, then ESP_ERR_INVALID_ARG is returned.
133 *
134 * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
135 * sources, as defined in soc/soc.h, or one of the internal
136 * ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
137 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
138 * choice of interrupts that this routine can choose from. If this value
139 * is 0, it will default to allocating a non-shared interrupt of level
140 * 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
141 * interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
142 * from this function with the interrupt disabled.
143 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
144 * is requested, because these types of interrupts aren't C-callable.
145 * @param arg Optional argument for passed to the interrupt handler
146 * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
147 * used to request details or free the interrupt. Can be NULL if no handle
148 * is required.
149 *
150 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
151 * ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
152 * ESP_OK otherwise
153 */
154 esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
155
156
157 /**
158 * @brief Allocate an interrupt with the given parameters.
159 *
160 *
161 * This essentially does the same as esp_intr_alloc, but allows specifying a register and mask
162 * combo. For shared interrupts, the handler is only called if a read from the specified
163 * register, ANDed with the mask, returns non-zero. By passing an interrupt status register
164 * address and a fitting mask, this can be used to accelerate interrupt handling in the case
165 * a shared interrupt is triggered; by checking the interrupt statuses first, the code can
166 * decide which ISRs can be skipped
167 *
168 * @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
169 * sources, as defined in soc/soc.h, or one of the internal
170 * ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
171 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
172 * choice of interrupts that this routine can choose from. If this value
173 * is 0, it will default to allocating a non-shared interrupt of level
174 * 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
175 * interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
176 * from this function with the interrupt disabled.
177 * @param intrstatusreg The address of an interrupt status register
178 * @param intrstatusmask A mask. If a read of address intrstatusreg has any of the bits
179 * that are 1 in the mask set, the ISR will be called. If not, it will be
180 * skipped.
181 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
182 * is requested, because these types of interrupts aren't C-callable.
183 * @param arg Optional argument for passed to the interrupt handler
184 * @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
185 * used to request details or free the interrupt. Can be NULL if no handle
186 * is required.
187 *
188 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
189 * ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
190 * ESP_OK otherwise
191 */
192 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);
193
194
195 /**
196 * @brief Disable and free an interrupt.
197 *
198 * Use an interrupt handle to disable the interrupt and release the resources associated with it.
199 * If the current core is not the core that registered this interrupt, this routine will be assigned to
200 * the core that allocated this interrupt, blocking and waiting until the resource is successfully released.
201 *
202 * @note
203 * When the handler shares its source with other handlers, the interrupt status
204 * bits it's responsible for should be managed properly before freeing it. see
205 * ``esp_intr_disable`` for more details. Please do not call this function in ``esp_ipc_call_blocking``.
206 *
207 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
208 *
209 * @return ESP_ERR_INVALID_ARG the handle is NULL
210 * ESP_FAIL failed to release this handle
211 * ESP_OK otherwise
212 */
213 esp_err_t esp_intr_free(intr_handle_t handle);
214
215
216 /**
217 * @brief Get CPU number an interrupt is tied to
218 *
219 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
220 *
221 * @return The core number where the interrupt is allocated
222 */
223 int esp_intr_get_cpu(intr_handle_t handle);
224
225 /**
226 * @brief Get the allocated interrupt for a certain handle
227 *
228 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
229 *
230 * @return The interrupt number
231 */
232 int esp_intr_get_intno(intr_handle_t handle);
233
234 /**
235 * @brief Disable the interrupt associated with the handle
236 *
237 * @note
238 * 1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
239 * CPU the interrupt is allocated on. Other interrupts have no such restriction.
240 * 2. When several handlers sharing a same interrupt source, interrupt status bits, which are
241 * handled in the handler to be disabled, should be masked before the disabling, or handled
242 * in other enabled interrupts properly. Miss of interrupt status handling will cause infinite
243 * interrupt calls and finally system crash.
244 *
245 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
246 *
247 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
248 * ESP_OK otherwise
249 */
250 esp_err_t esp_intr_disable(intr_handle_t handle);
251
252 /**
253 * @brief Enable the interrupt associated with the handle
254 *
255 * @note For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
256 * CPU the interrupt is allocated on. Other interrupts have no such restriction.
257 *
258 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
259 *
260 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
261 * ESP_OK otherwise
262 */
263 esp_err_t esp_intr_enable(intr_handle_t handle);
264
265 /**
266 * @brief Set the "in IRAM" status of the handler.
267 *
268 * @note Does not work on shared interrupts.
269 *
270 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
271 * @param is_in_iram Whether the handler associated with this handle resides in IRAM.
272 * Handlers residing in IRAM can be called when cache is disabled.
273 *
274 * @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
275 * ESP_OK otherwise
276 */
277 esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram);
278
279 /**
280 * @brief Disable interrupts that aren't specifically marked as running from IRAM
281 */
282 void esp_intr_noniram_disable(void);
283
284 /**
285 * @brief Re-enable interrupts disabled by esp_intr_noniram_disable
286 */
287 void esp_intr_noniram_enable(void);
288
289 /**
290 * @brief enable the interrupt source based on its number
291 * @param inum interrupt number from 0 to 31
292 */
293 void esp_intr_enable_source(int inum);
294
295 /**
296 * @brief disable the interrupt source based on its number
297 * @param inum interrupt number from 0 to 31
298 */
299 void esp_intr_disable_source(int inum);
300
301 /**
302 * @brief Get the lowest interrupt level from the flags
303 * @param flags The same flags that pass to `esp_intr_alloc_intrstatus` API
304 */
esp_intr_flags_to_level(int flags)305 static inline int esp_intr_flags_to_level(int flags)
306 {
307 return __builtin_ffs((flags & ESP_INTR_FLAG_LEVELMASK) >> 1) + 1;
308 }
309
310 /**@}*/
311
312
313 #ifdef __cplusplus
314 }
315 #endif
316
