esp_ipc: Update documentation and API descriptions

This commit updates the documentation and API descriptions of
the esp_ipc and esp_ipc_isr features.

components/esp_system/include/esp_ipc_isr.h

@@ -14,31 +14,38 @@ extern "C" {
 
 #ifdef CONFIG_ESP_IPC_ISR_ENABLE
 
-/** @cond */
+/**
+ * @brief IPC ISR Callback
+ *
+ * A callback of this type should be provided as an argument when calling esp_ipc_isr_asm_call() or
+ * esp_ipc_isr_asm_call_blocking().
+ */
 typedef void (*esp_ipc_isr_func_t)(void* arg);
-/** @endcond */
 
 /**
- * @brief Initialize inter-processor call module which based on #4 high-interrupt.
+ * @brief Initialize the IPC ISR feature
  *
- * This function is called on CPU start and should not be called from the application.
+ * This function initializes the IPC ISR feature and must be called before any other esp_ipc_isr...() functions.
+ * The IPC ISR feature allows for callbacks (written in assembly) to be run on a particular CPU in the context of a
+ * High Priority Interrupt.
  *
- * This function starts two tasks, one on each CPU. These tasks register
- * #4 High-interrupt and after that, the tasks are deleted.
- * The next API functions work with this functionality:
- * esp_ipc_isr_asm_call
- * esp_ipc_isr_asm_call_blocking
- * They allow to run an asm function on other CPU.
+ * - This function will register a High Priority Interrupt on each CPU. The priority of the interrupts is dependent on
+ *   the CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL option.
+ * - Callbacks written in assembly can then run in context of the registered High Priority Interrupts
+ * - Callbacks can be executed by calling esp_ipc_isr_asm_call() or esp_ipc_isr_asm_call_blocking()
  */
 void esp_ipc_isr_init(void);
 
 /**
- * @brief Execute an asm function on the other CPU (uses the #4 high-priority interrupt)
+ * @brief Execute an assembly callback on the other CPU
  *
- * @note In single-core mode, it is not available.
- * This function calls the #4 high-priority interrupt on the other CPU.
- * The given function is called in the context of the interrupt by CALLX0 command and
- * operates with registers a2, a3, a4.
+ * 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, is invoked using a CALLX0 instruction, and has a2, a3, a4 as scratch
+ *   registers. See docs for more details
+ *
+ * @note This function is not available in single-core mode.
  *
  * @param[in]   func    Pointer to a function of type void func(void* arg) to be executed
  * @param[in]   arg     Arbitrary argument of type void* to be passed into the function
@@ -46,11 +53,12 @@ void esp_ipc_isr_init(void);
 void esp_ipc_isr_asm_call(esp_ipc_isr_func_t func, void* arg);
 
 /**
- * @brief Execute an asm function on the other CPU and blocks until it completes (uses the #4 high-priority interrupt)
+ * @brief Execute an assembly callback on the other CPU and busy-wait until it completes
  *
- * @note In single-core mode, it is not available.
- * This function calls the #4 high-priority interrupt on the other CPU.
- * The given function is called in the context of the interrupt by CALLX0 command.
+ * This function is identical to esp_ipc_isr_asm_call() except that this function will busy-wait until the execution of
+ * the callback completes.
+ *
+ * @note This function is not available in single-core mode.
  *
  * @param[in]   func    Pointer to a function of type void func(void* arg) to be executed
  * @param[in]   arg     Arbitrary argument of type void* to be passed into the function
@@ -58,51 +66,60 @@ void esp_ipc_isr_asm_call(esp_ipc_isr_func_t func, void* arg);
 void esp_ipc_isr_asm_call_blocking(esp_ipc_isr_func_t func, void* arg);
 
 /**
- * @brief Stall the other CPU and the current CPU disables interrupts with level 3 and lower.
+ * @brief Stall the other CPU
  *
- * @note In single-core mode, it is not available.
- * This function calls the #4 high-priority interrupt on the other CPU.
- * The esp_ipc_isr_finish_cmd() function is called on the other CPU in the context of the #4 high-priority interrupt.
- * The esp_ipc_isr_finish_cmd is called by CALLX0 command.
- * It is waiting for the end command. The command will be sent by esp_ipc_isr_release_other_cpu().
- * This function is used for DPORT workaround.
+ * 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 blocks other CPU until the release call esp_ipc_isr_release_other_cpu().
+ * - 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 fucntion is used for the DPORT workaround: stall other cpu that this cpu is pending to access dport register start.
+ * @note This function is not available in single-core mode.
  */
 void esp_ipc_isr_stall_other_cpu(void);
 
 /**
  * @brief Release the other CPU
  *
- * @note In single-core mode, it is not available.
- * This function will send the end command to release the stall other CPU.
- * This function is used for DPORT workaround: stall other cpu that this cpu is pending to access dport register end.
+ * 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
+ *
+ * @note This function is not available in single-core mode.
  */
 void esp_ipc_isr_release_other_cpu(void);
 
 /**
- * @brief Pause stall the other CPU
+ * @brief 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_pause(void);
 
 /**
- * @brief Abort stall the other CPU
+ * @brief Abort a CPU stall
  *
- * This routine does not stop the stall routines in any way that is recoverable.
- * Please only call in case of panic().
- * Used in panic code: the enter_critical stuff may be messed up so we just stop everything without checking the mux.
+ * 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_abort(void);
 
 /**
- * @brief Resume stall the other CPU
+ * @brief 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.
  */
 void esp_ipc_isr_stall_resume(void);
 
-#else // not CONFIG_ESP_IPC_ISR_ENABLE
+#else // CONFIG_ESP_IPC_ISR_ENABLE
 
 #define esp_ipc_isr_stall_other_cpu()
 #define esp_ipc_isr_release_other_cpu()