mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
18d545708a
The interrupt allocator now allows allocating an interrupt with a handler in ROM and flags set to ESP_INTR_FLAG_IRAM
338 lines
14 KiB
C
338 lines
14 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include <stdio.h>
|
|
#include "esp_err.h"
|
|
#include "esp_intr_types.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
/** @addtogroup Intr_Alloc
|
|
* @{
|
|
*/
|
|
|
|
|
|
/** @brief Interrupt allocation flags
|
|
*
|
|
* These flags can be used to specify which interrupt qualities the
|
|
* code calling esp_intr_alloc* needs.
|
|
*
|
|
*/
|
|
|
|
//Keep the LEVELx values as they are here; they match up with (1<<level)
|
|
#define ESP_INTR_FLAG_LEVEL1 (1<<1) ///< Accept a Level 1 interrupt vector (lowest priority)
|
|
#define ESP_INTR_FLAG_LEVEL2 (1<<2) ///< Accept a Level 2 interrupt vector
|
|
#define ESP_INTR_FLAG_LEVEL3 (1<<3) ///< Accept a Level 3 interrupt vector
|
|
#define ESP_INTR_FLAG_LEVEL4 (1<<4) ///< Accept a Level 4 interrupt vector
|
|
#define ESP_INTR_FLAG_LEVEL5 (1<<5) ///< Accept a Level 5 interrupt vector
|
|
#define ESP_INTR_FLAG_LEVEL6 (1<<6) ///< Accept a Level 6 interrupt vector
|
|
#define ESP_INTR_FLAG_NMI (1<<7) ///< Accept a Level 7 interrupt 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) ///< Low and medium prio interrupts. These can be handled in C.
|
|
#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.
|
|
|
|
/** Mask for all level flags */
|
|
#define ESP_INTR_FLAG_LEVELMASK (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)
|
|
|
|
|
|
/** @addtogroup Intr_Alloc_Pseudo_Src
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* The esp_intr_alloc* functions can allocate an int for all ETS_*_INTR_SOURCE interrupt sources that
|
|
* are routed through the interrupt mux. Apart from these sources, each core also has some internal
|
|
* sources that do not pass through the interrupt mux. To allocate an interrupt for these sources,
|
|
* pass these pseudo-sources to the functions.
|
|
*/
|
|
#define ETS_INTERNAL_TIMER0_INTR_SOURCE -1 ///< Platform timer 0 interrupt source
|
|
#define ETS_INTERNAL_TIMER1_INTR_SOURCE -2 ///< Platform timer 1 interrupt source
|
|
#define ETS_INTERNAL_TIMER2_INTR_SOURCE -3 ///< Platform 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
|
|
#define ETS_INTERNAL_UNUSED_INTR_SOURCE -99 ///< Interrupt is not assigned to any source
|
|
|
|
/**@}*/
|
|
|
|
/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
|
|
*/
|
|
#define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE)
|
|
|
|
/** Enable interrupt by interrupt number */
|
|
#define ESP_INTR_ENABLE(inum) esp_intr_enable_source(inum)
|
|
|
|
/** Disable interrupt by interrupt number */
|
|
#define ESP_INTR_DISABLE(inum) esp_intr_disable_source(inum)
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param intno The number of the interrupt (0-31)
|
|
* @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
|
|
* @param 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.
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param intno The number of the interrupt (0-31)
|
|
* @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if cpu or intno is invalid
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_reserve(int intno, int cpu);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
|
|
* sources, as defined in soc/soc.h, or one of the internal
|
|
* ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
|
|
* @param 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.
|
|
* @param handler The interrupt handler. Must be NULL when an interrupt of level >3
|
|
* is requested, because these types of interrupts aren't C-callable.
|
|
* @param arg Optional argument for passed to the interrupt handler
|
|
* @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
|
|
* used to request details or free the interrupt. Can be NULL if no handle
|
|
* is required.
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
|
|
* ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_t *ret_handle);
|
|
|
|
|
|
/**
|
|
* @brief 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
|
|
*
|
|
* @param source The interrupt source. One of the ETS_*_INTR_SOURCE interrupt mux
|
|
* sources, as defined in soc/soc.h, or one of the internal
|
|
* ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
|
|
* @param 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.
|
|
* @param intrstatusreg The address of an interrupt status register
|
|
* @param 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.
|
|
* @param handler The interrupt handler. Must be NULL when an interrupt of level >3
|
|
* is requested, because these types of interrupts aren't C-callable.
|
|
* @param arg Optional argument for passed to the interrupt handler
|
|
* @param ret_handle Pointer to an intr_handle_t to store a handle that can later be
|
|
* used to request details or free the interrupt. Can be NULL if no handle
|
|
* is required.
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
|
|
* ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
|
|
* ESP_OK otherwise
|
|
*/
|
|
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);
|
|
|
|
|
|
/**
|
|
* @brief 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``.
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG the handle is NULL
|
|
* ESP_FAIL failed to release this handle
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_free(intr_handle_t handle);
|
|
|
|
|
|
/**
|
|
* @brief Get CPU number an interrupt is tied to
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
*
|
|
* @return The core number where the interrupt is allocated
|
|
*/
|
|
int esp_intr_get_cpu(intr_handle_t handle);
|
|
|
|
/**
|
|
* @brief Get the allocated interrupt for a certain handle
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
*
|
|
* @return The interrupt number
|
|
*/
|
|
int esp_intr_get_intno(intr_handle_t handle);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_disable(intr_handle_t handle);
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_enable(intr_handle_t handle);
|
|
|
|
/**
|
|
* @brief Set the "in IRAM" status of the handler.
|
|
*
|
|
* @note Does not work on shared interrupts.
|
|
*
|
|
* @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
|
|
* @param is_in_iram Whether the handler associated with this handle resides in IRAM.
|
|
* Handlers residing in IRAM can be called when cache is disabled.
|
|
*
|
|
* @return ESP_ERR_INVALID_ARG if the combination of arguments is invalid.
|
|
* ESP_OK otherwise
|
|
*/
|
|
esp_err_t esp_intr_set_in_iram(intr_handle_t handle, bool is_in_iram);
|
|
|
|
/**
|
|
* @brief Disable interrupts that aren't specifically marked as running from IRAM
|
|
*/
|
|
void esp_intr_noniram_disable(void);
|
|
|
|
/**
|
|
* @brief Re-enable interrupts disabled by esp_intr_noniram_disable
|
|
*/
|
|
void esp_intr_noniram_enable(void);
|
|
|
|
/**
|
|
* @brief enable the interrupt source based on its number
|
|
* @param inum interrupt number from 0 to 31
|
|
*/
|
|
void esp_intr_enable_source(int inum);
|
|
|
|
/**
|
|
* @brief disable the interrupt source based on its number
|
|
* @param inum interrupt number from 0 to 31
|
|
*/
|
|
void esp_intr_disable_source(int inum);
|
|
|
|
/**
|
|
* @brief Get the lowest interrupt level from the flags
|
|
* @param flags The same flags that pass to `esp_intr_alloc_intrstatus` API
|
|
*/
|
|
static inline int esp_intr_flags_to_level(int flags)
|
|
{
|
|
return __builtin_ffs((flags & ESP_INTR_FLAG_LEVELMASK) >> 1);
|
|
}
|
|
|
|
/**
|
|
* @brief Get the interrupt flags from the supplied level (priority)
|
|
* @param level The interrupt priority level
|
|
*/
|
|
static inline int esp_intr_level_to_flags(int level)
|
|
{
|
|
return (level > 0) ? (1 << level) & ESP_INTR_FLAG_LEVELMASK : 0;
|
|
}
|
|
|
|
/**
|
|
* @brief Dump the status of allocated interrupts
|
|
* @param stream The stream to dump to, if NULL then stdout is used
|
|
* @return ESP_OK on success
|
|
*/
|
|
esp_err_t esp_intr_dump(FILE *stream);
|
|
|
|
|
|
/**
|
|
* @brief Check if the given pointer is in the safe ISR area.
|
|
* In other words, make sure that the pointer's content is accessible at
|
|
* any time, regardless of the cache status
|
|
*
|
|
* @param ptr Pointer to check
|
|
*
|
|
* @return true if `ptr` points to ISR area, false else
|
|
*/
|
|
bool esp_intr_ptr_in_isr_region(void* ptr);
|
|
|
|
/**@}*/
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|