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