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

docs/en/api-reference/system/ipc.rst

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