intc_esp32.h File Reference

#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	shared_vector_desc_t
struct	vector_desc_t
struct	intr_handle_data_t
	Interrupt handler associated data structure. More...

Macros
#define	ESP_INTC_INTS_NUM   (32)
#define	ESP_INTR_FLAG_LEVEL1   (1<<1) /* Accept a Level 1 int vector, lowest priority */
#define	ESP_INTR_FLAG_LEVEL2   (1<<2) /* Accept a Level 2 int vector */
#define	ESP_INTR_FLAG_LEVEL3   (1<<3) /* Accept a Level 3 int vector */
#define	ESP_INTR_FLAG_LEVEL4   (1<<4) /* Accept a Level 4 int vector */
#define	ESP_INTR_FLAG_LEVEL5   (1<<5) /* Accept a Level 5 int vector */
#define	ESP_INTR_FLAG_LEVEL6   (1<<6) /* Accept a Level 6 int vector */
#define	ESP_INTR_FLAG_NMI   (1<<7) /* Accept a Level 7 int vector, highest priority */
#define	ESP_INTR_FLAG_SHARED   (1<<8) /* Interrupt can be shared between ISRs */
#define	ESP_INTR_FLAG_EDGE   (1<<9) /* Edge-triggered interrupt */
#define	ESP_INTR_FLAG_IRAM   (1<<10) /* ISR can be called if cache is disabled */
#define	ESP_INTR_FLAG_INTRDISABLED   (1<<11) /* Return with this interrupt disabled */
#define	ESP_INTR_FLAG_LOWMED   (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3)
#define	ESP_INTR_FLAG_HIGH
#define	ESP_INTR_FLAG_LEVELMASK
#define	ESP_PRIO_TO_FLAGS(priority)
#define	ESP_INT_FLAGS_CHECK(int_flags)
#define	ETS_INTERNAL_TIMER0_INTR_SOURCE   -1 /* Xtensa timer 0 interrupt source */
#define	ETS_INTERNAL_TIMER1_INTR_SOURCE   -2 /* Xtensa timer 1 interrupt source */
#define	ETS_INTERNAL_TIMER2_INTR_SOURCE   -3 /* Xtensa timer 2 interrupt source */
#define	ETS_INTERNAL_SW0_INTR_SOURCE   -4 /* Software int source 1 */
#define	ETS_INTERNAL_SW1_INTR_SOURCE   -5 /* Software int source 2 */
#define	ETS_INTERNAL_PROFILING_INTR_SOURCE   -6 /* Int source for profiling */

Typedefs
typedef void(*	intr_handler_t) (void *arg)

Functions
void	esp_intr_initialize (void)
	Initializes interrupt table to its defaults.
int	esp_intr_mark_shared (int intno, int cpu, bool is_in_iram)
	Mark an interrupt as a shared interrupt.
int	esp_intr_reserve (int intno, int cpu)
	Reserve an interrupt to be used outside of this framework.
int	esp_intr_alloc (int source, int flags, intr_handler_t handler, void *arg, struct intr_handle_data_t **ret_handle)
	Allocate an interrupt with the given parameters.
int	esp_intr_alloc_intrstatus (int source, int flags, uint32_t intrstatusreg, uint32_t intrstatusmask, intr_handler_t handler, void *arg, struct intr_handle_data_t **ret_handle)
	Allocate an interrupt with the given parameters.
int	esp_intr_free (struct intr_handle_data_t *handle)
	Disable and free an interrupt.
int	esp_intr_get_cpu (struct intr_handle_data_t *handle)
	Get CPU number an interrupt is tied to.
int	esp_intr_get_intno (struct intr_handle_data_t *handle)
	Get the allocated interrupt for a certain handle.
int	esp_intr_disable (struct intr_handle_data_t *handle)
	Disable the interrupt associated with the handle.
int	esp_intr_enable (struct intr_handle_data_t *handle)
	Enable the interrupt associated with the handle.
int	esp_intr_set_in_iram (struct intr_handle_data_t *handle, bool is_in_iram)
	Set the "in IRAM" status of the handler.
void	esp_intr_noniram_disable (void)
	Disable interrupts that aren't specifically marked as running from IRAM.
void	esp_intr_noniram_enable (void)
	Re-enable interrupts disabled by esp_intr_noniram_disable.

Macro Definition Documentation

ESP_INT_FLAGS_CHECK

#define ESP_INT_FLAGS_CHECK

(

int_flags

)

Value:

((int_flags) & ESP_INTR_FLAG_SHARED)

ESP_INTC_INTS_NUM

#define ESP_INTC_INTS_NUM   (32)

ESP_INTR_FLAG_EDGE

#define ESP_INTR_FLAG_EDGE   (1<<9) /* Edge-triggered interrupt */

ESP_INTR_FLAG_HIGH

#define ESP_INTR_FLAG_HIGH

Value:

                                 (ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
                                 ESP_INTR_FLAG_NMI)

ESP_INTR_FLAG_INTRDISABLED

#define ESP_INTR_FLAG_INTRDISABLED   (1<<11) /* Return with this interrupt disabled */

ESP_INTR_FLAG_IRAM

#define ESP_INTR_FLAG_IRAM   (1<<10) /* ISR can be called if cache is disabled */

ESP_INTR_FLAG_LEVEL1

#define ESP_INTR_FLAG_LEVEL1   (1<<1) /* Accept a Level 1 int vector, lowest priority */

ESP_INTR_FLAG_LEVEL2

#define ESP_INTR_FLAG_LEVEL2   (1<<2) /* Accept a Level 2 int vector */

ESP_INTR_FLAG_LEVEL3

#define ESP_INTR_FLAG_LEVEL3   (1<<3) /* Accept a Level 3 int vector */

ESP_INTR_FLAG_LEVEL4

#define ESP_INTR_FLAG_LEVEL4   (1<<4) /* Accept a Level 4 int vector */

ESP_INTR_FLAG_LEVEL5

#define ESP_INTR_FLAG_LEVEL5   (1<<5) /* Accept a Level 5 int vector */

ESP_INTR_FLAG_LEVEL6

#define ESP_INTR_FLAG_LEVEL6   (1<<6) /* Accept a Level 6 int vector */

ESP_INTR_FLAG_LEVELMASK

#define ESP_INTR_FLAG_LEVELMASK

Value:

                                 (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
                                 ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
                                 ESP_INTR_FLAG_NMI)

ESP_INTR_FLAG_LOWMED

#define ESP_INTR_FLAG_LOWMED   (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3)

ESP_INTR_FLAG_NMI

#define ESP_INTR_FLAG_NMI   (1<<7) /* Accept a Level 7 int vector, highest priority */

ESP_INTR_FLAG_SHARED

#define ESP_INTR_FLAG_SHARED   (1<<8) /* Interrupt can be shared between ISRs */

ESP_PRIO_TO_FLAGS

#define ESP_PRIO_TO_FLAGS

(

priority

)

Value:

        ((priority) > 0 ? ((1 << (priority)) & ESP_INTR_FLAG_LEVELMASK) : 0)

ETS_INTERNAL_PROFILING_INTR_SOURCE

#define ETS_INTERNAL_PROFILING_INTR_SOURCE   -6 /* Int source for profiling */

ETS_INTERNAL_SW0_INTR_SOURCE

#define ETS_INTERNAL_SW0_INTR_SOURCE   -4 /* Software int source 1 */

ETS_INTERNAL_SW1_INTR_SOURCE

#define ETS_INTERNAL_SW1_INTR_SOURCE   -5 /* Software int source 2 */

ETS_INTERNAL_TIMER0_INTR_SOURCE

#define ETS_INTERNAL_TIMER0_INTR_SOURCE   -1 /* Xtensa timer 0 interrupt source */

ETS_INTERNAL_TIMER1_INTR_SOURCE

#define ETS_INTERNAL_TIMER1_INTR_SOURCE   -2 /* Xtensa timer 1 interrupt source */

ETS_INTERNAL_TIMER2_INTR_SOURCE

#define ETS_INTERNAL_TIMER2_INTR_SOURCE   -3 /* Xtensa timer 2 interrupt source */

Typedef Documentation

intr_handler_t

typedef void(* intr_handler_t) (void *arg)

Function Documentation

esp_intr_alloc()

int esp_intr_alloc	(	int	source,
		int	flags,
		intr_handler_t	handler,
		void *	arg,
		struct intr_handle_data_t **	ret_handle )

Allocate an interrupt with the given parameters.

This finds an interrupt that matches the restrictions as given in the flags parameter, maps the given interrupt source to it and hooks up the given interrupt handler (with optional argument) as well. If needed, it can return a handle for the interrupt as well.

The interrupt will always be allocated on the core that runs this function.

If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or RTC_FAST_MEM, then ESP_ERR_INVALID_ARG is returned.

Parameters

source	The interrupt source. One of the *_INTR_SOURCE interrupt mux sources, as defined in esp-xtensa-intmux.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
flags	An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of interrupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the interrupt disabled.
handler	The interrupt handler. Must be NULL when an interrupt of level >3 is requested, because these types of interrupts aren't C-callable.
arg	Optional argument for passed to the interrupt handler
ret_handle	Pointer to a struct intr_handle_data_t pointer to store a handle that can later be used to request details or free the interrupt. Can be NULL if no handle is required.

Returns

-EINVAL if the combination of arguments is invalid. -ENODEV No free interrupt found with the specified flags 0 otherwise

esp_intr_alloc_intrstatus()

int esp_intr_alloc_intrstatus	(	int	source,
		int	flags,
		uint32_t	intrstatusreg,
		uint32_t	intrstatusmask,
		intr_handler_t	handler,
		void *	arg,
		struct intr_handle_data_t **	ret_handle )

Allocate an interrupt with the given parameters.

This essentially does the same as esp_intr_alloc, but allows specifying a register and mask combo. For shared interrupts, the handler is only called if a read from the specified register, ANDed with the mask, returns non-zero. By passing an interrupt status register address and a fitting mask, this can be used to accelerate interrupt handling in the case a shared interrupt is triggered; by checking the interrupt statuses first, the code can decide which ISRs can be skipped

Parameters

source	The interrupt source. One of the *_INTR_SOURCE interrupt mux sources, as defined in esp-xtensa-intmux.h, or one of the internal ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
flags	An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the choice of interrupts that this routine can choose from. If this value is 0, it will default to allocating a non-shared interrupt of level 1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return from this function with the interrupt disabled.
intrstatusreg	The address of an interrupt status register
intrstatusmask	A mask. If a read of address intrstatusreg has any of the bits that are 1 in the mask set, the ISR will be called. If not, it will be skipped.
handler	The interrupt handler. Must be NULL when an interrupt of level >3 is requested, because these types of interrupts aren't C-callable.
arg	Optional argument for passed to the interrupt handler
ret_handle	Pointer to a struct intr_handle_data_t pointer to store a handle that can later be used to request details or free the interrupt. Can be NULL if no handle is required.

Returns

-EINVAL if the combination of arguments is invalid. -ENODEV No free interrupt found with the specified flags 0 otherwise

esp_intr_disable()

int esp_intr_disable

(

struct intr_handle_data_t *

handle

)

Disable the interrupt associated with the handle.

Note

1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the interrupt is allocated on. Other interrupts have no such restriction.
2. When several handlers sharing a same interrupt source, interrupt status bits, which are handled in the handler to be disabled, should be masked before the disabling, or handled in other enabled interrupts properly. Miss of interrupt status handling will cause infinite interrupt calls and finally system crash.

Parameters

handle

The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus

Returns

-EINVAL if the combination of arguments is invalid. 0 otherwise

esp_intr_enable()

int esp_intr_enable

(

struct intr_handle_data_t *

handle

)

Enable the interrupt associated with the handle.

Note

For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the CPU the interrupt is allocated on. Other interrupts have no such restriction.

Parameters

handle

The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus

Returns

-EINVAL if the combination of arguments is invalid. 0 otherwise

esp_intr_free()

int esp_intr_free

(

struct intr_handle_data_t *

handle

)

Disable and free an interrupt.

Use an interrupt handle to disable the interrupt and release the resources associated with it. If the current core is not the core that registered this interrupt, this routine will be assigned to the core that allocated this interrupt, blocking and waiting until the resource is successfully released.

Note

When the handler shares its source with other handlers, the interrupt status bits it's responsible for should be managed properly before freeing it. See esp_intr_disable for more details. Please do not call this function in esp_ipc_call_blocking.

Parameters

handle

The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus

Returns

-EINVAL the handle is NULL 0 otherwise

esp_intr_get_cpu()

int esp_intr_get_cpu

(

struct intr_handle_data_t *

handle

)

Get CPU number an interrupt is tied to.

Parameters

handle

The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus

Returns

The core number where the interrupt is allocated

esp_intr_get_intno()

int esp_intr_get_intno

(

struct intr_handle_data_t *

handle

)

Get the allocated interrupt for a certain handle.

Parameters

handle

The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus

Returns

The interrupt number

esp_intr_initialize()

void esp_intr_initialize

(

void

)

Initializes interrupt table to its defaults.

esp_intr_mark_shared()

int esp_intr_mark_shared	(	int	intno,
		int	cpu,
		bool	is_in_iram )

Mark an interrupt as a shared interrupt.

This will mark a certain interrupt on the specified CPU as an interrupt that can be used to hook shared interrupt handlers to.

Parameters

intno	The number of the interrupt (0-31)
cpu	CPU on which the interrupt should be marked as shared (0 or 1)
is_in_iram	Shared interrupt is for handlers that reside in IRAM and the int can be left enabled while the flash cache is disabled.

Returns

-EINVAL if cpu or intno is invalid 0 otherwise

esp_intr_noniram_disable()

void esp_intr_noniram_disable

(

void

)

Disable interrupts that aren't specifically marked as running from IRAM.

esp_intr_noniram_enable()

void esp_intr_noniram_enable

(

void

)

Re-enable interrupts disabled by esp_intr_noniram_disable.

esp_intr_reserve()

int esp_intr_reserve	(	int	intno,
		int	cpu )

Reserve an interrupt to be used outside of this framework.

This will mark a certain interrupt on the specified CPU as reserved, not to be allocated for any reason.

Parameters

intno	The number of the interrupt (0-31)
cpu	CPU on which the interrupt should be marked as shared (0 or 1)

Returns

-EINVAL if cpu or intno is invalid 0 otherwise

esp_intr_set_in_iram()

int esp_intr_set_in_iram	(	struct intr_handle_data_t *	handle,
		bool	is_in_iram )

Set the "in IRAM" status of the handler.

Note

Does not work on shared interrupts.

Parameters

handle	The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
is_in_iram	Whether the handler associated with this handle resides in IRAM. Handlers residing in IRAM can be called when cache is disabled.

Returns

-EINVAL if the combination of arguments is invalid. 0 otherwise