mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-25 09:42:35 +00:00
Merge branch 'docs/add_cn_trans_for_ipc.rst_in_api-reference_system' into 'master'
docs: Provide Chinese translation for api-reference/system/ipc.rst See merge request espressif/esp-idf!26122
This commit is contained in:
Ren Pei Ying
@@ -1,51 +1,57 @@
|
||||
Inter-Processor Call
|
||||
====================
|
||||
Inter-Processor Call (IPC)
|
||||
==========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
|
||||
The IPC is an **Inter-Processor Call** and **NOT Inter-Process Communication** as found on other operating systems.
|
||||
IPC stands for an **"Inter-Processor Call"** and **NOT** "Inter-Process Communication" as found on other operating systems.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Due to the dual core nature of the {IDF_TARGET_NAME}, there are instances where a certain callback must be run in the context of a particular CPU such as:
|
||||
Due to the dual core nature of the {IDF_TARGET_NAME}, there are some scenarios where a certain callback must be executed from a particular core such as:
|
||||
|
||||
- When allocating an ISR to an interrupt source of a particular CPU (applies to freeing a particular CPU's interrupt source as well).
|
||||
- On particular chips (such as the ESP32), accessing memory that is exclusive to a particular CPU (such as RTC Fast Memory).
|
||||
- Reading the registers/state of another CPU.
|
||||
- When allocating an ISR to an interrupt source of a particular core (applies to freeing a particular core's interrupt source as well)
|
||||
- On particular chips (such as the ESP32), accessing memory that is exclusive to a particular core (such as RTC Fast Memory)
|
||||
- Reading the registers/state of another core
|
||||
|
||||
The IPC (Inter-Processor Call) feature allows a particular CPU (the calling CPU) to trigger the execution of a callback function on another CPU (the target CPU). The IPC feature allows execution of a callback function on the target CPU in either ``a task context``, or ``an interrupt context``. Depending on the context that the callback function is executed in, different restrictions apply to the implementation of the callback function.
|
||||
The IPC (Inter-Processor Call) feature allows a particular core (the calling core) to trigger the execution of a callback function on another core (the target core). The IPC feature allows execution of a callback function on the target core in either a task context, or an interrupt context. Depending on the context that the callback function is executed in, different restrictions apply to the implementation of the callback function.
|
||||
|
||||
IPC in Task Context
|
||||
-------------------
|
||||
|
||||
The IPC feature implements callback execution in a task context by creating an IPC task for each CPU during application startup. When the calling CPU needs to execute a callback on the target CPU, the callback will execute in the context of the target CPU's IPC task.
|
||||
The IPC feature implements callback execution in a task context by creating an IPC task for each core during application startup. When the calling core needs to execute a callback on the target core, the callback will execute in the context of the target core's IPC task.
|
||||
|
||||
When using IPCs in a task context, users need to consider the following:
|
||||
|
||||
- IPC callbacks should ideally be simple and short. **An IPC callback should avoid attempting to block or yield**.
|
||||
- The IPC tasks are created at the highest possible priority (i.e., ``configMAX_PRIORITIES - 1``) thus the callback should also run at that priority as a result. However, :ref:`CONFIG_ESP_IPC_USES_CALLERS_PRIORITY` is enabled by default which temporarily lowers the priority of the target CPU's IPC task to the calling CPU before executing the callback.
|
||||
- IPC callbacks should ideally be simple and short. An IPC callback **must never block or yield**.
|
||||
- The IPC tasks are created at the highest possible priority (i.e., ``configMAX_PRIORITIES - 1``).
|
||||
|
||||
- If :ref:`CONFIG_ESP_IPC_USES_CALLERS_PRIORITY` is enabled, the target core's IPC task will be lowered to the current priority of the target core before executing the callback.
|
||||
- If :ref:`CONFIG_ESP_IPC_USES_CALLERS_PRIORITY` is disabled, the target core will always execute the callback at the highest possible priority.
|
||||
|
||||
- Depending on the complexity of the callback, users may need to configure the stack size of the IPC task via :ref:`CONFIG_ESP_IPC_TASK_STACK_SIZE`.
|
||||
- The IPC feature is internally protected by a mutex. Therefore, simultaneous IPC calls from two or more calling CPUs are handled on a first come first serve basis.
|
||||
- The IPC feature is internally protected by a mutex. Therefore, simultaneous IPC calls from two or more calling core's are serialized on a first come first serve basis.
|
||||
|
||||
API Usage
|
||||
^^^^^^^^^
|
||||
|
||||
Task Context IPC callbacks have the following restrictions:
|
||||
|
||||
- The callback must be of type ``void func(void *arg)``
|
||||
- The callback should avoid attempting to block or yield as this will result in the target CPU's IPC task blocking or yielding.
|
||||
- The callback must avoid changing any aspect of the IPC task (e.g., by calling ``vTaskPrioritySet(NULL, x)``).
|
||||
- The callback must be of the :cpp:type:`esp_ipc_func_t` type.
|
||||
- The callback **must never block or yield** as this will result in the target core's IPC task blocking or yielding.
|
||||
- The callback must avoid changing any aspect of the IPC task's state, e.g., by calling ``vTaskPrioritySet(NULL, x)``.
|
||||
|
||||
The IPC feature offers the API listed below to execute a callback in a task context on a target CPU. The API allows the calling CPU to block until the callback's execution has completed, or return immediately once the callback's execution has started.
|
||||
The IPC feature offers the API listed below to execute a callback in a task context on a target core. The API allows the calling core to block until the callback's execution has completed, or return immediately once the callback's execution has started.
|
||||
|
||||
- :cpp:func:`esp_ipc_call` triggers an IPC call on the target CPU. This function will block until the target CPU's IPC task **begins** execution of the callback.
|
||||
- :cpp:func:`esp_ipc_call_blocking` triggers an IPC on the target CPU. This function will block until the target CPU's IPC task **completes** execution of the callback.
|
||||
- :cpp:func:`esp_ipc_call` triggers an IPC call on the target core. This function will block until the target core's IPC task **begins** execution of the callback.
|
||||
- :cpp:func:`esp_ipc_call_blocking` triggers an IPC on the target core. This function will block until the target core's IPC task **completes** execution of the callback.
|
||||
|
||||
IPC in Interrupt Context
|
||||
------------------------
|
||||
|
||||
In some cases, we need to quickly obtain the state of another CPU such as in a core dump, GDB stub, various unit tests, and DPORT workaround. The IPC ISR feature implements the High Priority Interrupt context by reserving a High Priority Interrupt on each CPU for IPC usage. When a calling CPU needs to execute a callback on the target CPU, the callback will execute in the context of the High Priority Interrupt of the target CPU.
|
||||
In some cases, we need to quickly obtain the state of another core such as in a core dump, GDB stub, various unit tests, and hardware errata workarounds. The IPC ISR feature implements callback execution from a High Priority Interrupt context by reserving a High Priority Interrupt on each core for IPC usage. When a calling core needs to execute a callback on the target core, the callback will execute in the context of the High Priority Interrupt of the target core.
|
||||
|
||||
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
|
||||
|
||||
@@ -61,10 +67,10 @@ When using IPCs in High Priority Interrupt context, users need to consider the f
|
||||
When the callback executes, users need to consider the following:
|
||||
|
||||
.. list::
|
||||
|
||||
- The calling CPU will disable interrupts of level 3 and lower.
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: - Although the priority of the reserved interrupt depends on :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`, during the execution IPC ISR callback, the target CPU will disable interrupts of level 5 and lower regardless of what :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL` is set to.
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - Although the priority of the reserved interrupt depends on :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`, during the execution IPC ISR callback, the target CPU will disable all interrupts.
|
||||
|
||||
- The calling core will disable interrupts of priority level 3 and lower.
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: - Although the priority of the reserved interrupt depends on :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`, during the execution of IPC ISR callback, the target core will disable interrupts of priority level 5 and lower regardless of what :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL` is set to.
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - Although the priority of the reserved interrupt depends on :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`, during the execution of IPC ISR callback, the target core will disable all interrupts.
|
||||
|
||||
API Usage
|
||||
^^^^^^^^^
|
||||
@@ -73,32 +79,32 @@ API Usage
|
||||
|
||||
High Priority Interrupt IPC callbacks have the following restrictions:
|
||||
|
||||
- The callback must be of type ``void func(void *arg)`` but implemented entirely in assembly
|
||||
- The callback must be of type :cpp:type:`esp_ipc_isr_func_t` but implemented entirely in assembly.
|
||||
- The callback is invoked via the ``CALLX0`` instruction with register windowing disabled, thus the callback:
|
||||
- Must not call any register window related instructions (e.g., ``entry`` and ``retw``).
|
||||
- Must not call other C functions as register windowing is disabled
|
||||
- The callback should be placed in IRAM at a 4-byte aligned address
|
||||
- (On invocation of/after returning from) the callback, the registers ``a2, a3, a4`` are (saved/restored) automatically thus can be used in the callback. The callback should **ONLY** use those registers.
|
||||
- ``a2`` contains the ``void *arg`` of the callback
|
||||
- ``a3/a4`` are free to use as scratch registers
|
||||
- must not call any register window related instructions, e.g., ``entry`` and ``retw``.
|
||||
- must not call other C functions as register windowing is disabled.
|
||||
- The callback should be placed in IRAM at a 4-byte aligned address.
|
||||
- On invocation of, or after returning from the callback, the registers ``a2, a3, a4`` are saved/restored automatically, thus can be used in the callback. The callback should **ONLY** use those registers.
|
||||
- ``a2`` contains the ``void *arg`` of the callback.
|
||||
- ``a3/a4`` are free to use as scratch registers.
|
||||
|
||||
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
|
||||
|
||||
High Priority Interrupt IPC callbacks have the same restrictions as for regular interrupt handlers. The callback function can be written in C.
|
||||
High Priority Interrupt IPC callbacks must be of type :cpp:type:`esp_ipc_isr_func_t` and have the same restrictions as for regular interrupt handlers. The callback function can be written in C.
|
||||
|
||||
The IPC feature offers the API listed below to execute a callback in a High Priority Interrupt context.
|
||||
The IPC feature offers the API listed below to execute a callback in a High Priority Interrupt context:
|
||||
|
||||
- :cpp:func:`esp_ipc_isr_call` triggers an IPC call on the target CPU. This function will busy-wait until the target CPU begins execution of the callback.
|
||||
- :cpp:func:`esp_ipc_isr_call_blocking` triggers an IPC call on the target CPU. This function will busy-wait until the target CPU completes execution of the callback.
|
||||
- :cpp:func:`esp_ipc_isr_call` triggers an IPC call on the target core. This function will busy-wait until the target core **begins** execution of the callback.
|
||||
- :cpp:func:`esp_ipc_isr_call_blocking` triggers an IPC call on the target core. This function will busy-wait until the target core **completes** execution of the callback.
|
||||
|
||||
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
|
||||
|
||||
The following code-blocks demonstrates a High Priority Interrupt IPC callback written in assembly that simply reads the target CPU's cycle count.
|
||||
The following code-blocks demonstrates a High Priority Interrupt IPC callback written in assembly that simply reads the target core's cycle count:
|
||||
|
||||
.. code-block:: asm
|
||||
|
||||
/* esp_test_ipc_isr_get_cycle_count_other_cpu(void *arg) */
|
||||
// this function reads CCOUNT of the target CPU and stores it in arg.
|
||||
// this function reads CCOUNT of the target core and stores it in arg.
|
||||
// use only a2, a3 and a4 regs here.
|
||||
.section .iram1, "ax"
|
||||
.align 4
|
||||
@@ -122,7 +128,7 @@ The IPC feature offers the API listed below to execute a callback in a High Prio
|
||||
|
||||
.. note::
|
||||
|
||||
For more examples of High Priority Interrupt IPC callbacks, see :idf_file:`components/esp_system/port/arch/xtensa/esp_ipc_isr_routines.S` and :idf_file:`components/esp_system/test_apps/esp_system_unity_tests/main/port/arch/xtensa/test_ipc_isr.S`.
|
||||
For more examples of High Priority Interrupt IPC callbacks, you can refer to :idf_file:`components/esp_system/port/arch/xtensa/esp_ipc_isr_routines.S` and :idf_file:`components/esp_system/test_apps/esp_system_unity_tests/main/port/arch/xtensa/test_ipc_isr.S`.
|
||||
|
||||
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
|
||||
|
||||
@@ -132,13 +138,13 @@ The IPC feature offers the API listed below to execute a callback in a High Prio
|
||||
|
||||
See :idf_file:`examples/system/ipc/ipc_isr/xtensa/main/main.c` for an example of its use.
|
||||
|
||||
The High Priority Interrupt IPC API also provides the following convenience functions that can stall/resume the target CPU. These API utilize the High Priority Interrupt IPC, but supply their own internal callbacks:
|
||||
The High Priority Interrupt IPC API also provides the following convenience functions that can stall/resume the target core. These APIs utilize the High Priority Interrupt IPC, but supply their own internal callbacks:
|
||||
|
||||
.. list::
|
||||
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - :cpp:func:`esp_ipc_isr_stall_other_cpu` stalls the target CPU. The calling CPU disables interrupts of level 3 and lower while the target CPU will busy-wait with all interrupts disabled. The target CPU will busy-wait until :cpp:func:`esp_ipc_isr_release_other_cpu` is called.
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: - :cpp:func:`esp_ipc_isr_stall_other_cpu` stalls the target CPU. The calling CPU disables interrupts of level 3 and lower while the target CPU will busy-wait with interrupts of level 5 and lower disabled. The target CPU will busy-wait until :cpp:func:`esp_ipc_isr_release_other_cpu` is called.
|
||||
- :cpp:func:`esp_ipc_isr_release_other_cpu` resumes the target CPU.
|
||||
:CONFIG_IDF_TARGET_ARCH_RISCV: - :cpp:func:`esp_ipc_isr_stall_other_cpu` stalls the target core. The calling core disables interrupts of level 3 and lower, while the target core will busy-wait with all interrupts disabled. The target core will busy-wait until :cpp:func:`esp_ipc_isr_release_other_cpu` is called.
|
||||
:CONFIG_IDF_TARGET_ARCH_XTENSA: - :cpp:func:`esp_ipc_isr_stall_other_cpu` stalls the target core. The calling core disables interrupts of level 3 and lower while the target core will busy-wait with interrupts of level 5 and lower disabled. The target core will busy-wait until :cpp:func:`esp_ipc_isr_release_other_cpu` is called.
|
||||
- :cpp:func:`esp_ipc_isr_release_other_cpu` resumes the target core.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Reference in New Issue
Block a user