处理器间调用 (IPC)

[English]

备注

IPC 指 处理器间调用 (Inter-Processor Call)，而不是其他操作系统中所指的 进程间通信 (Inter-Process Communication)。

概述

由于 ESP32-S3 的双核特性，在某些情况下，某个回调必须在特定的内核上下文中运行。例如：

为特定内核的中断源分配 ISR，或释放特定内核的中断源时
在特定芯片（如 ESP32）上访问某个内核独有的内存，如 RTC Fast Memory 时
读取另一个内核的寄存器或状态时

IPC 功能允许一个特定的内核（下文称“调用内核”）触发另一个内核（下文称“目标内核”）的回调函数执行，并允许目标内核在任务上下文或中断上下文中执行回调函数。在不同的上下文中，回调函数的实现限制有所不同。

任务上下文中的 IPC

在应用程序启动时，IPC 功能为每个内核创建一个 IPC 任务，从而在任务上下文中执行回调。当调用内核需要在目标内核中执行回调时，回调将在目标内核的 IPC 任务的上下文中执行。

在任务上下文中使用 IPC 功能时，需考虑以下几点：

IPC 回调应该尽可能简短。 IPC 回调决不能阻塞或让出。
IPC 任务是以尽可能高的优先级创建的（即 configMAX_PRIORITIES - 1）。
- 如果启用了 CONFIG_ESP_IPC_USES_CALLERS_PRIORITY，执行回调前会降低目标内核的 IPC 任务优先级，使其等于调用内核的优先级。
- 如果禁用了 CONFIG_ESP_IPC_USES_CALLERS_PRIORITY，目标内核将始终以尽可能高的优先级执行回调。
如果回调较为复杂，用户可能需要通过 CONFIG_ESP_IPC_TASK_STACK_SIZE 来配置 IPC 任务的堆栈大小。
IPC 功能受内部互斥锁保护。因此，如果同时收到来自两个或多个调用内核的 IPC 请求，将按照“先到先得”的原则按顺序处理。

API 用法

任务上下文中的 IPC 回调具有以下限制：

回调类型必须是 esp_ipc_func_t。
回调 决不能阻塞或让出，以免导致目标内核的 IPC 任务阻塞或让出。
回调必须避免改变 IPC 任务的任何状态，例如，不能调用 vTaskPrioritySet(NULL, x)。

IPC 功能提供了以下 API，用于在目标内核的任务上下文中执行回调。这两个 API 允许调用内核在回调执行完成前处于阻塞，或者在回调开始执行后立即返回。

esp_ipc_call() 会在目标内核上触发一个 IPC 调用。在目标内核的 IPC 任务开始执行回调前，此函数会一直处于阻塞状态。
esp_ipc_call_blocking() 会在目标内核上触发一个 IPC。在目标内核的 IPC 任务完成回调执行前，此函数会一直处于阻塞状态。

中断上下文中的 IPC

在某些情况下，我们需要快速获取另一个内核的状态，如在核心转储、GDB Stub、各种单元测试和绕过硬件错误的过程中。IPC ISR 功能会在每个内核上保留一个高优先级中断供 IPC 使用，从而在高优先级中断上下文中执行回调。当调用内核需要在目标内核上执行回调时，该回调将在目标内核的高优先级中断的上下文中执行。

在这种情况下，IPC ISR 功能支持在高优先级中断上下文中执行回调。

在高优先级中断上下文中使用 IPC 时，需要考虑以下几点：

由于回调是在高优先级中断上下文中执行的，因此，回调必须完全用汇编语言编写。如需了解更多关于用汇编语言编写回调的内容，请参阅下文的 API 使用介绍。
保留的高优先级中断的优先级取决于 CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL 选项。

当回调执行时，需考虑以下几点：

调用内核会禁用 3 级及以下优先级的中断。
虽然保留中断的优先级取决于 CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL，但是在执行 IPC ISR 回调期间，无论 CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL 如何设置，目标内核都会禁用 5 级及以下优先级的中断。

API 用法

高优先级中断的 IPC 回调具有以下限制：

回调必须是 esp_ipc_isr_func_t 类型，但必须完全用汇编语言实现。
回调通过 CALLX0 指令调用，同时禁用寄存器窗口，因此，该回调：
- 不得调用任何与寄存器窗口相关的指令，例如 entry 和 retw。
- 由于禁用了寄存器窗口，不得调用其他 C 函数。
回调应放在 4 字节对齐的 IRAM 地址上。
在调用或返回回调后，寄存器 a2，a3，和 a4 会被自动保存或恢复，从而在回调中使用。回调 只能使用这些寄存器。
- a2 包含回调的 void *arg。
- a3/a4 可以作为临时寄存器使用。

IPC 功能提供了下列 API，以在高优先级中断的上下文中执行回调：

esp_ipc_isr_call() 能够在目标内核上触发一个 IPC 调用。在目标内核开始执行回调前，此函数将一直处于忙等待。
esp_ipc_isr_call_blocking() 能够在目标内核上触发一个 IPC 调用。在目标内核完成回调执行前，此函数将一直处于忙等待。

以下示例代码用汇编语言编写了一个高优先级中断 IPC 回调，该回调的作用为读取目标内核的周期计数：

/* esp_test_ipc_isr_get_cycle_count_other_cpu(void *arg) */
// 此函数读取目标内核的 CCOUNT，并将其存储到 arg 中。
// 此处仅使用 a2、a3 和 a4 寄存器。
.section    .iram1, "ax"
.align      4
.global     esp_test_ipc_isr_get_cycle_count_other_cpu
.type       esp_test_ipc_isr_get_cycle_count_other_cpu, @function
// Args:
// a2 - void* arg
esp_test_ipc_isr_get_cycle_count_other_cpu:
rsr.ccount a3
s32i    a3, a2, 0
ret

unit32_t cycle_count;
esp_ipc_isr_call_blocking(esp_test_ipc_isr_get_cycle_count_other_cpu, (void *)cycle_count);

备注

对于大多数简单用例，可用的临时寄存器数量是足够的。如果需要在回调函数中使用更多的临时寄存器，可以用 void *arg 指向一个用作寄存器保存区域的 buffer，使回调函数保存或恢复更多的寄存器。前往 system/ipc/ipc_isr 查看示例。

备注

如需查看更多高优先级中断 IPC 回调的示例，请前往 components/esp_system/port/arch/xtensa/esp_ipc_isr_routines.S 和 components/esp_system/test_apps/esp_system_unity_tests/main/port/arch/xtensa/test_ipc_isr.S。

请前往 examples/system/ipc/ipc_isr/xtensa/main/main.c 查看使用示例。

高优先级中断 IPC API 还提供了以下便利函数，这些函数可以暂停或恢复目标内核的执行。这些 API 利用高优先级中断 IPC，但同时提供了自己的内部回调函数：

esp_ipc_isr_stall_other_cpu()：暂停目标内核。调用内核禁用 3 级及以下级别的中断，而目标内核将在 5 级及以下的中断被禁用的情况下进入忙等待。在调用 esp_ipc_isr_release_other_cpu() 前，目标内核会保持忙等待。
esp_ipc_isr_release_other_cpu()：恢复目标内核。

API 参考

Header File

components/esp_system/include/esp_ipc.h
This header file can be included with:
#include "esp_ipc.h"

Functions

esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void *arg)

Execute a callback on a given CPU.

Execute a given callback on a particular CPU. The callback must be of type "esp_ipc_func_t" and will be invoked in the context of the target CPU's IPC task.

This function will block the target CPU's IPC task has begun execution of the callback
If another IPC call is ongoing, this function will block until the ongoing IPC call completes
The stack size of the IPC task can be configured via the CONFIG_ESP_IPC_TASK_STACK_SIZE option

备注

In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.

参数

cpu_id -- [in] CPU where the given function should be executed (0 or 1)
func -- [in] Pointer to a function of type void func(void* arg) to be executed
arg -- [in] Arbitrary argument of type void* to be passed into the function

返回

ESP_ERR_INVALID_ARG if cpu_id is invalid
ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
ESP_OK otherwise

esp_err_t esp_ipc_call_blocking(uint32_t cpu_id, esp_ipc_func_t func, void *arg)

Execute a callback on a given CPU until and block until it completes.

This function is identical to esp_ipc_call() except that this function will block until the execution of the callback completes.

备注

In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.

参数

cpu_id -- [in] CPU where the given function should be executed (0 or 1)
func -- [in] Pointer to a function of type void func(void* arg) to be executed
arg -- [in] Arbitrary argument of type void* to be passed into the function

返回

ESP_ERR_INVALID_ARG if cpu_id is invalid
ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
ESP_OK otherwise

Type Definitions

typedef void (*esp_ipc_func_t)(void *arg)

IPC Callback.

A callback of this type should be provided as an argument when calling esp_ipc_call() or esp_ipc_call_blocking().

Header File

components/esp_system/include/esp_ipc_isr.h
This header file can be included with:
#include "esp_ipc_isr.h"

Functions

void esp_ipc_isr_call(esp_ipc_isr_func_t func, void *arg)

Execute an ISR callback on the other CPU.

Execute a given callback on the other CPU in the context of a High Priority Interrupt.

This function will busy-wait in a critical section until the other CPU has started execution of the callback
The callback must be written:
- in assembly for XTENSA chips (such as ESP32, ESP32S3). The function is invoked using a CALLX0 instruction and can use only a2, a3, a4 registers. See :doc:IPC in Interrupt Context </api-reference/system/ipc> doc for more details.
- in C or assembly for RISCV chips (such as ESP32P4).

备注

This function is not available in single-core mode.

参数

func -- [in] Pointer to a function of type void func(void* arg) to be executed
arg -- [in] Arbitrary argument of type void* to be passed into the function

void esp_ipc_isr_call_blocking(esp_ipc_isr_func_t func, void *arg)

Execute an ISR callback on the other CPU and busy-wait until it completes.

This function is identical to esp_ipc_isr_call() except that this function will busy-wait until the execution of the callback completes.

备注

This function is not available in single-core mode.

参数

func -- [in] Pointer to a function of type void func(void* arg) to be executed
arg -- [in] Arbitrary argument of type void* to be passed into the function

void esp_ipc_isr_stall_other_cpu(void)

Stall the other CPU.

This function will stall the other CPU. The other CPU is stalled by busy-waiting in the context of a High Priority Interrupt. The other CPU will not be resumed until esp_ipc_isr_release_other_cpu() is called.

This function is internally implemented using IPC ISR
This function is used for DPORT workaround.
If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect

备注

This function is not available in single-core mode.

备注

It is the caller's responsibility to avoid deadlocking on spinlocks

void esp_ipc_isr_release_other_cpu(void)

Release the other CPU.

This function will release the other CPU that was previously stalled from calling esp_ipc_isr_stall_other_cpu()

This function is used for DPORT workaround.
If the stall feature is paused using esp_ipc_isr_stall_pause(), this function will have no effect

备注

This function is not available in single-core mode.

void esp_ipc_isr_stall_pause(void)

Puase the CPU stall feature.

This function will pause the CPU stall feature. Once paused, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have no effect. If a IPC ISR call is already in progress, this function will busy-wait until the call completes before pausing the CPU stall feature.

void esp_ipc_isr_stall_abort(void)

Abort a CPU stall.

This function will abort any stalling routine of the other CPU due to a pervious call to esp_ipc_isr_stall_other_cpu(). This function aborts the stall in a non-recoverable manner, thus should only be called in case of a panic().

This function is used in panic handling code

void esp_ipc_isr_stall_resume(void)

Resume the CPU stall feature.

This function will resume the CPU stall feature that was previously paused by calling esp_ipc_isr_stall_pause(). Once resumed, calls to esp_ipc_isr_stall_other_cpu() and esp_ipc_isr_release_other_cpu() will have effect again.

Macros

esp_ipc_isr_asm_call(func, arg): Execute an ISR callback on the other CPU See esp_ipc_isr_call().

esp_ipc_isr_asm_call_blocking(func, arg): Execute an ISR callback on the other CPU and busy-wait until it completes See esp_ipc_isr_call_blocking().

Type Definitions

typedef void (*esp_ipc_isr_func_t)(void *arg)

IPC ISR Callback.

The callback must be written:

in assembly for XTENSA chips (such as ESP32, ESP32S3).
in C or assembly for RISCV chips (such as ESP32P4).

A callback of this type should be provided as an argument when calling esp_ipc_isr_call() or esp_ipc_isr_call_blocking().

提供有关此文档的反馈