处理器间调用 (IPC)

[English]

备注

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

概述

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

  • 为特定内核的中断源分配 ISR,或释放特定内核的中断源时

  • 在特定芯片(如 ESP32)上访问某个内核独有的内存,如 RTC Fast Memory 时

  • 读取另一个内核的寄存器或状态时

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

任务上下文中的 IPC

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

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

  • IPC 回调应该尽可能简短。 IPC 回调决不能阻塞或让出

  • IPC 任务是以尽可能高的优先级创建的(即 configMAX_PRIORITIES - 1)。

  • 如果回调较为复杂,用户可能需要通过 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 选项。

当回调执行时,需考虑以下几点:

API 用法

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

  • 回调必须是 esp_ipc_isr_func_t 类型,但必须完全用汇编语言实现。

  • 回调通过 CALLX0 指令调用,同时禁用寄存器窗口,因此,该回调:
    • 不得调用任何与寄存器窗口相关的指令,例如 entryretw

    • 由于禁用了寄存器窗口,不得调用其他 C 函数。

  • 回调应放在 4 字节对齐的 IRAM 地址上。

  • 在调用或返回回调后,寄存器 a2a3,和 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 查看示例。

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

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

API 参考

Header File

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

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