中断分配

概述

ESP32-H2 有一个核，28 个外部异步中断。每个中断的优先级别都可独立地通过编程设置。此外，还有 4 个核心本地中断源 (CLINT)。详细信息请参见 ESP32-H2 技术参考手册 [PDF]。

由于中断源数量多于中断，有时多个驱动程序可以共用一个中断。esp_intr_alloc() 抽象隐藏了这些实现细节。

驱动程序可以通过调用 esp_intr_alloc()，或 esp_intr_alloc_intrstatus() 为某个外设分配中断。通过向此函数传递 flag，可以指定中断类型、优先级和触发方式。然后，中断分配代码会找到适用的中断，使用中断矩阵将其连接到外设，并为其安装给定的中断处理程序和 ISR。

中断分配器提供两种不同的中断类型：共享中断和非共享中断，这两种中断需要不同处理方式。非共享中断在每次调用 esp_intr_alloc() 时，都会分配一个单独的中断，该中断仅用于与其相连的外设，只调用一个 ISR。共享中断则可以由多个外设触发，当其中一个外设发出中断信号时，会调用多个 ISR。因此，针对共享中断的 ISR 应检查对应外设的中断状态，以确定是否需要采取任何操作。

非共享中断可由电平或边缘触发。共享中断只能由电平触发，因为使用边缘触发可能会错过中断。

要解释为什么共享中断只能由电平触发，以外设 A 和外设 B 共用一个边缘触发中断为例进行说明：当外设 B 触发中断时，会将其中断信号设置为高电平，产生一个从低到高的边缘，进而锁存 CPU 中断位，并触发 ISR。接着，ISR 开始执行，检查到此时外设 A 没有触发中断，于是继续处理外设 B 的中断信号，最后将外设 B 的中断状态清除。最后，CPU 会在 ISR 返回之前清除中断位锁存器。因此在整个中断处理过程中，如果外设 A 触发了中断，该中断会因 CPU 清除中断位锁存器而丢失。

IRAM 安全中断处理程序

在执行 SPI flash 的写入和擦除操作时，ESP32-H2 会禁用 cache，中断处理程序将无法访问 SPI flash 和 SPIRAM。因此，ESP-IDF 中存在两种中断处理程序，它们各有优缺点：

IRAM 安全中断处理程序 - 只能访问内部内存中的代码和数据（代码存储在 IRAM 中，数据存储在 DRAM 中）。

+ 延迟：flash 写入和擦除操作相对缓慢，例如擦除可能需要几十或几百毫秒才能完成，但这些中断处理程序不受影响，执行速度较快且延迟较低，能够保证最小执行延迟。
- 占用内部内存：中断处理程序占用了宝贵的内部内存，这些内存本可以用于其他目的。
+ cache 未命中：中断处理程序不依赖 cache, 因此就不会出现 cache 未命中带来的不确定性，因为代码和数据已存储在内部存储器中了。
使用场景：请使用 ESP_INTR_FLAG_IRAM 标志，通过中断分配器 API 注册此类中断。

非 IRAM 安全中断处理程序 - 可能会访问 flash 中的代码和（只读）数据。

- 延迟：在进行 flash 操作时，中断处理程序会被推迟，因此平均延迟较高且难以预测。
+ 占用内部内存：该中断处理程序不使用内部 RAM，或者使用的内存比 IRAM 安全中断要少。
使用场景：通过中断分配器 API 注册此类中断时，请不要使用 ESP_INTR_FLAG_IRAM 标志。

请注意，没有任何显式标记将中断处理程序标识为 IRAM 安全。 当且仅当要访问的代码和数据存储在内部内存中时，中断处理程序才被隐式标记为 IRAM 安全。“IRAM 安全”这个术语实际上有点误导性，因为除了将处理程序的代码放在 IRAM 中之外，还有更多其他要求。以下是 不属于 IRAM 安全的中断处理程序示例：

部分代码放置在 flash 中。
放置在 IRAM 中但调用了存储在 flash 里的函数。
代码放置在 IRAM 中但访问了位于 flash 中的只读变量。

关于如何将代码和数据放置在 IRAM 或 DRAM 中，请参见如何将代码放入 IRAM。

有关 SPI flash 操作及其与中断处理程序交互的更多详细信息，请参见 SPI flash API 文档。

备注

如果不能 100% 确定中断处理程序访问的所有代码和数据都位于 IRAM（代码）或 DRAM（数据）中，切勿使用 ESP_INTR_FLAG_IRAM 标志注册中断处理程序。忽略这一点将导致（有时是偶发性的）:ref:cache 错误 <cache_error>。通过调用函数间接访问代码和数据时也需要注意这点。

多个处理程序共用一个中断源

如果用 ESP_INTR_FLAG_SHARED flag 分配所有处理程序，可能将多个处理程序分配给同一个源。这些程序会被分配给与源关联的中断，并在源可用时按顺序调用。处理程序可以单独禁用和释放。如果启用了一个或多个处理程序，则会将源关联到中断（启用），否则会取消关联。禁用的处理程序永远不会被调用，但是只要启用了源的任何一个处理程序，这个源仍然能被触发。

关联到非共享中断的源不支持此功能。

尽管支持此功能，使用时也必须 非常小心。通常存在两种办法可以阻止中断触发： 禁用源 或 屏蔽外设中断状态。ESP-IDF 仅处理源本身的启用和禁用，中断源的状态位和屏蔽位须由用户操作。

状态位须在负责该位的处理程序禁用前屏蔽，也可以在另一个启用的中断中屏蔽和处理该状态位。

备注

如果不屏蔽状态位而让其处于未处理状态，同时禁用这些状态位的处理程序，就会导致无限次触发中断，引起系统崩溃。

排除中断分配故障

CPU 中断在大多数 Espressif SoC 上都是有限的资源。因此，一个运行的程序有可能耗尽 CPU 中断，例如初始化多个外设驱动程序的情况。这通常导致驱动程序的初始化函数返回 ESP_ERR_NOT_FOUND 错误。

这种情况下，可使用 esp_intr_dump() 函数打印中断列表及其状态。此函数输出通常如下：

CPU 0 interrupt status:
Int  Level  Type   Status
0     1    Level  Reserved
1     1    Level  Reserved
2     1    Level  Used: RTC_CORE
3     1    Level  Used: TG0_LACT_LEVEL
...

输出列含义如下：

Int：CPU 中断输入编号。通常不直接在软件中使用，仅作为参考。
Level：已分配中断的优先级级别。空闲的中断具有标记 *。
Type：已分配中断的类型（电平或边缘中断）。空闲的中断具有标记 *。
Status：中断的可能状态：
- Reserved：中断在硬件层面保留，或由 ESP-IDF 的某些部分保留。不能使用 esp_intr_alloc() 分配。
- Used: <source>：中断已分配并连接到单个外设。
- Shared: <source1> <source2> ...：中断已分配并连接到多个外设。参见本文档多个处理程序共用一个中断源章节。
- Free：中断未分配，可以由 esp_intr_alloc() 使用。

如果已确认应用程序的确用完了中断，可组合采用下列建议解决问题：

找到可接受更高延迟的中断，并用 ESP_INTR_FLAG_SHARED flag （或与 ESP_INTR_FLAG_LOWMED 进行 OR 运算）分配这些中断。对两个或更多外设使用此 flag 能让它们使用单个中断输入，从而为其他外设节约中断输入。参见多个处理程序共用一个中断源。
检查是否有些外设驱动程序不需要一直启用，并按需将其初始化或取消初始化。这样可以减少同时分配的中断数量。

API 参考

Header File

components/esp_hw_support/include/esp_intr_types.h
This header file can be included with:
#include "esp_intr_types.h"

Macros

ESP_INTR_CPU_AFFINITY_TO_CORE_ID(cpu_affinity): Convert esp_intr_cpu_affinity_t to CPU core ID.

Type Definitions

typedef void (*intr_handler_t)(void *arg): Function prototype for interrupt handler function

typedef struct intr_handle_data_t *intr_handle_t: Handle to an interrupt handler

Enumerations

enum esp_intr_cpu_affinity_t

Interrupt CPU core affinity.

This type specify the CPU core that the peripheral interrupt is connected to.

Values:

enumerator ESP_INTR_CPU_AFFINITY_AUTO: Install the peripheral interrupt to ANY CPU core, decided by on which CPU the interrupt allocator is running.

enumerator ESP_INTR_CPU_AFFINITY_0: Install the peripheral interrupt to CPU core 0.

enumerator ESP_INTR_CPU_AFFINITY_1: Install the peripheral interrupt to CPU core 1.

Header File

components/esp_hw_support/include/esp_intr_alloc.h
This header file can be included with:
#include "esp_intr_alloc.h"

Functions

esp_err_t 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.

参数

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.

返回

ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise

esp_err_t 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.

参数

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

返回

ESP_ERR_INVALID_ARG if cpu or intno is invalid ESP_OK otherwise

esp_err_t esp_intr_alloc(int source, int flags, intr_handler_t handler, void *arg, intr_handle_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.

参数

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.
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 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.

返回

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)

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

参数

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.
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 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.

返回

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_free(intr_handle_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.

备注

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.

参数: handle -- The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
返回: ESP_ERR_INVALID_ARG the handle is NULL ESP_FAIL failed to release this handle ESP_OK otherwise

int esp_intr_get_cpu(intr_handle_t handle)

Get CPU number an interrupt is tied to.

参数: handle -- The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
返回: The core number where the interrupt is allocated

int esp_intr_get_intno(intr_handle_t handle)

Get the allocated interrupt for a certain handle.

参数: handle -- The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
返回: The interrupt number

esp_err_t esp_intr_disable(intr_handle_t handle)

Disable the interrupt associated with the handle.

备注

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.
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.

参数: handle -- The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
返回: ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise

esp_err_t esp_intr_enable(intr_handle_t handle)

Enable the interrupt associated with the handle.

备注

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.

参数: handle -- The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
返回: 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)

Set the "in IRAM" status of the handler.

备注

Does not work on shared interrupts.

参数

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.

返回

ESP_ERR_INVALID_ARG if the combination of arguments is invalid. ESP_OK otherwise

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.

void esp_intr_enable_source(int inum)

enable the interrupt source based on its number

参数: inum -- interrupt number from 0 to 31

void esp_intr_disable_source(int inum)

disable the interrupt source based on its number

参数: inum -- interrupt number from 0 to 31

static inline int esp_intr_flags_to_level(int flags)

Get the lowest interrupt level from the flags.

参数: flags -- The same flags that pass to esp_intr_alloc_intrstatus API

static inline int esp_intr_level_to_flags(int level)

Get the interrupt flags from the supplied level (priority)

参数: level -- The interrupt priority level

esp_err_t esp_intr_dump(FILE *stream)

Dump the status of allocated interrupts.

参数: stream -- The stream to dump to, if NULL then stdout is used
返回: ESP_OK on success

bool esp_intr_ptr_in_isr_region(void *ptr)

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.

参数: ptr -- Pointer to check
返回: true if ptr points to ISR area, false else

Macros

ESP_INTR_FLAG_LEVEL1

Interrupt allocation flags.

These flags can be used to specify which interrupt qualities the code calling esp_intr_alloc* needs. Accept a Level 1 interrupt vector (lowest priority)

ESP_INTR_FLAG_LEVEL2: Accept a Level 2 interrupt vector.

ESP_INTR_FLAG_LEVEL3: Accept a Level 3 interrupt vector.

ESP_INTR_FLAG_LEVEL4: Accept a Level 4 interrupt vector.

ESP_INTR_FLAG_LEVEL5: Accept a Level 5 interrupt vector.

ESP_INTR_FLAG_LEVEL6: Accept a Level 6 interrupt vector.

ESP_INTR_FLAG_NMI: Accept a Level 7 interrupt vector (highest priority)

ESP_INTR_FLAG_SHARED: Interrupt can be shared between ISRs.

ESP_INTR_FLAG_EDGE: Edge-triggered interrupt.

ESP_INTR_FLAG_IRAM: ISR can be called if cache is disabled.

ESP_INTR_FLAG_INTRDISABLED: Return with this interrupt disabled.

ESP_INTR_FLAG_LOWMED: Low and medium prio interrupts. These can be handled in C.

ESP_INTR_FLAG_HIGH: High level interrupts. Need to be handled in assembly.

ESP_INTR_FLAG_LEVELMASK: Mask for all level flags

ETS_INTERNAL_TIMER0_INTR_SOURCE

Platform timer 0 interrupt source.

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.

ETS_INTERNAL_TIMER1_INTR_SOURCE: Platform timer 1 interrupt source.

ETS_INTERNAL_TIMER2_INTR_SOURCE: Platform timer 2 interrupt source.

ETS_INTERNAL_SW0_INTR_SOURCE: Software int source 1.

ETS_INTERNAL_SW1_INTR_SOURCE: Software int source 2.

ETS_INTERNAL_PROFILING_INTR_SOURCE: Int source for profiling.

ETS_INTERNAL_UNUSED_INTR_SOURCE: Interrupt is not assigned to any source.

ETS_INTERNAL_INTR_SOURCE_OFF: Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly

ESP_INTR_ENABLE(inum): Enable interrupt by interrupt number

ESP_INTR_DISABLE(inum): Disable interrupt by interrupt number

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。