docs/ipc documentation
This commit updates doxygen comments in the IPC header files and adds an rst docs page.
This commit is contained in:
Darian Leung
parent
02304ad83e
commit
4c13b2f391
|
|
@ -20,11 +20,11 @@
|
|||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** @cond */
|
||||
typedef void (*esp_ipc_func_t)(void* arg);
|
||||
|
||||
/**
|
||||
* @brief Inter-processor call APIs
|
||||
/** @endcond */
|
||||
/*
|
||||
* Inter-processor call APIs
|
||||
*
|
||||
* FreeRTOS provides several APIs which can be used to communicate between
|
||||
* different tasks, including tasks running on different CPUs.
|
||||
|
|
@ -34,8 +34,9 @@ typedef void (*esp_ipc_func_t)(void* arg);
|
|||
*/
|
||||
|
||||
|
||||
/**
|
||||
* @brief Initialize inter-processor call module.
|
||||
/*
|
||||
* Initialize inter-processor call module. This function is called automatically
|
||||
* on CPU start and should not be called from the application.
|
||||
*
|
||||
* This function start two tasks, one on each CPU. These tasks are started
|
||||
* with high priority. These tasks are normally inactive, waiting until one of
|
||||
|
|
@ -43,51 +44,59 @@ typedef void (*esp_ipc_func_t)(void* arg);
|
|||
* woken up to execute the callback provided to esp_ipc_call_nonblocking or
|
||||
* esp_ipc_call_blocking.
|
||||
*/
|
||||
/** @cond */
|
||||
void esp_ipc_init();
|
||||
|
||||
/** @endcond */
|
||||
|
||||
/**
|
||||
* @brief Execute function on the given CPU
|
||||
* @brief Execute a function on the given CPU
|
||||
*
|
||||
* This will wake a high-priority task on CPU indicated by cpu_id argument,
|
||||
* and run func(arg) in the context of that task.
|
||||
* This function returns as soon as the high-priority task is woken up.
|
||||
* If another IPC call is already being executed, this function will also wait
|
||||
* for it to complete.
|
||||
* Run a given function on a particular CPU. The given function must accept a
|
||||
* void* argument and return void. The given function is run in the context of
|
||||
* the IPC task of the CPU specified by the cpu_id parameter. The calling task
|
||||
* will be blocked until the IPC task begins executing the given function. If
|
||||
* another IPC call is ongoing, the calling task will block until the other IPC
|
||||
* call completes. The stack size allocated for the IPC task can be configured
|
||||
* in the "Inter-Processor Call (IPC) task stack size" setting in menuconfig.
|
||||
* Increase this setting if the given function requires more stack than default.
|
||||
*
|
||||
* In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
|
||||
* @note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
|
||||
*
|
||||
* For complex functions, you may need to increase the stack size of the "IPC task"
|
||||
* which runs the function must be sufficient. See the "Inter-Processor Call (IPC)
|
||||
* task stack size" setting in menuconfig.
|
||||
* @param[in] cpu_id CPU where the given function should be executed (0 or 1)
|
||||
* @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
|
||||
*
|
||||
* @param cpu_id CPU where function should be executed (0 or 1)
|
||||
* @param func pointer to a function which should be executed
|
||||
* @param arg arbitrary argument to be passed into function
|
||||
*
|
||||
* @return ESP_ERR_INVALID_ARG if cpu_id is invalid
|
||||
* ESP_ERR_INVALID_STATE if FreeRTOS scheduler is not running
|
||||
* ESP_OK otherwise
|
||||
* @return
|
||||
* - 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(uint32_t cpu_id, esp_ipc_func_t func, void* arg);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Execute function on the given CPU and wait for it to finish
|
||||
* @brief Execute a function on the given CPU and blocks until it completes
|
||||
*
|
||||
* This will wake a high-priority task on CPU indicated by cpu_id argument,
|
||||
* and run func(arg) in the context of that task.
|
||||
* This function waits for func to return.
|
||||
* Run a given function on a particular CPU. The given function must accept a
|
||||
* void* argument and return void. The given function is run in the context of
|
||||
* the IPC task of the CPU specified by the cpu_id parameter. The calling task
|
||||
* will be blocked until the IPC task completes execution of the given function.
|
||||
* If another IPC call is ongoing, the calling task will block until the other
|
||||
* IPC call completes. The stack size allocated for the IPC task can be
|
||||
* configured in the "Inter-Processor Call (IPC) task stack size" setting in
|
||||
* menuconfig. Increase this setting if the given function requires more stack
|
||||
* than default.
|
||||
*
|
||||
* In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
|
||||
* @note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
|
||||
*
|
||||
* @param cpu_id CPU where function should be executed (0 or 1)
|
||||
* @param func pointer to a function which should be executed
|
||||
* @param arg arbitrary argument to be passed into function
|
||||
* @param[in] cpu_id CPU where the given function should be executed (0 or 1)
|
||||
* @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
|
||||
*
|
||||
* @return ESP_ERR_INVALID_ARG if cpu_id is invalid
|
||||
* ESP_ERR_INVALID_STATE if FreeRTOS scheduler is not running
|
||||
* ESP_OK otherwise
|
||||
* @return
|
||||
* - 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);
|
||||
|
||||
|
|
|
|||
|
|
@ -128,6 +128,8 @@ INPUT = \
|
|||
../components/esp32/include/esp_task_wdt.h \
|
||||
## Hooks
|
||||
../components/esp32/include/esp_freertos_hooks.h \
|
||||
## Inter-Processor Call
|
||||
../components/esp32/include/esp_ipc.h \
|
||||
## Over The Air Updates (OTA)
|
||||
../components/app_update/include/esp_ota_ops.h \
|
||||
## Sleep
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ System API
|
|||
Interrupt Allocation <intr_alloc>
|
||||
Watchdogs <wdts>
|
||||
Hooks <hooks>
|
||||
Inter-Processor Call <ipc>
|
||||
Over The Air Updates (OTA) <ota>
|
||||
Sleep Modes <sleep_modes>
|
||||
Power Management <power_management>
|
||||
|
|
|
|||
43
docs/api-reference/system/ipc.rst
Normal file
43
docs/api-reference/system/ipc.rst
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
Inter-Processor Call
|
||||
====================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Due to the dual core nature of the ESP32, there are instances where a certain
|
||||
function must be run in the context of a particular core (e.g. allocating
|
||||
ISR to an interrupt source of a particular core). The IPC (Inter-Processor
|
||||
Call) feature allows for the execution of functions on a particular CPU.
|
||||
|
||||
A given function can be executed on a particular core by calling
|
||||
:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking`. IPC is
|
||||
implemented via two high priority FreeRTOS tasks pinned to each CPU known as
|
||||
the IPC Tasks. The two IPC Tasks remain inactive (blocked) until
|
||||
:cpp:func:`esp_ipc_call` or :cpp:func:`esp_ipc_call_blocking` is called. When
|
||||
an IPC Task of a particular core is unblocked, it will preempt the current
|
||||
running task on that core and execute a given function.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
:cpp:func:`esp_ipc_call` unblocks the IPC task on a particular core to execute
|
||||
a given function. The task that calls :cpp:func:`esp_ipc_call` will be blocked
|
||||
until the IPC Task begins execution of the given function.
|
||||
:cpp:func:`esp_ipc_call_blocking` is similar but will block the calling task
|
||||
until the IPC Task has completed execution of the given function.
|
||||
|
||||
Functions executed by IPCs must be functions of type
|
||||
`void func(void *arg)`. To run more complex functions which require a larger
|
||||
stack, the IPC tasks' stack size can be configured by modifying
|
||||
:ref:`CONFIG_IPC_TASK_STACK_SIZE` in `menuconfig`. The IPC API is protected by a
|
||||
mutex hence simultaneous IPC calls are not possible.
|
||||
|
||||
Care should taken to avoid deadlock when writing functions to be executed by
|
||||
IPC, especially when attempting to take a mutex within the function.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_ipc.inc
|
||||
|
||||
|
||||
Loading…
Reference in a new issue