From 6f90393f2218560ff3fbd4bb4980ea03b4173193 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 4 Dec 2017 20:09:12 +0800 Subject: [PATCH] docs: link to FreeRTOS APIs from SMP changes documentation --- docs/api-guides/freertos-smp.rst | 122 +++++++++++++++---------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/docs/api-guides/freertos-smp.rst b/docs/api-guides/freertos-smp.rst index 16d4c139b..e1763bf59 100644 --- a/docs/api-guides/freertos-smp.rst +++ b/docs/api-guides/freertos-smp.rst @@ -20,8 +20,8 @@ found via http://www.freertos.org/a00106.html port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported to ESP-IDF. -:ref:`tasks-and-task-creation`: Use ``xTaskCreatePinnedToCore()`` or -``xTaskCreateStaticPinnedToCore()`` to create tasks in ESP-IDF FreeRTOS. The +:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or +:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The last parameter of the two functions is ``xCoreID``. This parameter specifies which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, ``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on @@ -34,13 +34,13 @@ enter a blocked state, or are distributed across a wider range of priorities. :ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only affect the scheduler on the the calling core. In other words, calling -``vTaskSuspendAll()`` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and +:cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and vice versa. Use critical sections or semaphores instead for simultaneous access protection. :ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** -are not synchronized. Do not expect to use ``vTaskDelay`` or -``vTaskDelayUntil`` as an accurate method of synchronizing task execution +are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or +:cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution between the two cores. Use a counting semaphore instead as their context switches are not tied to tick interrupts due to preemption. @@ -51,15 +51,15 @@ unaffected. If the other core attemps to take same mutex, it will spin until the calling core has released the mutex by exiting the critical section. :ref:`floating-points`: The ESP32 supports hardware acceleration of single -precision floating point arithmetic (`float`). However the use of hardware +precision floating point arithmetic (``float``). However the use of hardware acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. -Therefore, tasks that utilize `float` will automatically be pinned to a core if -not done so already. Furthermore, `float` cannot be used in interrupt service +Therefore, tasks that utilize ``float`` will automatically be pinned to a core if +not done so already. Furthermore, ``float`` cannot be used in interrupt service routines. :ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately -when `vTaskDelete()` is called to delete a task that is not currently running +when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running and not pinned to the other core. Otherwise, freeing of task memory will still be delegated to the Idle Task. @@ -67,7 +67,7 @@ be delegated to the Idle Task. Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been added. Deletion callbacks are called automatically during task deletion and are used to free memory pointed to by TLSP. Call -``vTaskSetThreadLocalStoragePointerAndDelCallback()`` to set TLSP and Deletion +:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion Callbacks. :ref:`FreeRTOS Hooks`: Vanilla FreeRTOS Hooks were not designed for SMP. @@ -94,34 +94,34 @@ This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The in order for static allocation functions to be available. Once enabled, the following functions can be called... - - ``xTaskCreateStatic()`` See :ref:`backporting-notes` below - - ``xQueueCreateStatic()`` - - ``xSemaphoreCreateBinaryStatic()`` - - ``xSemaphoreCreateCountingStatic()`` - - ``xSemaphoreCreateMutexStatic()`` - - ``xSemaphoreCreateRecursiveMutexStatic()`` - - ``xTimerCreateStatic()`` See :ref:`backporting-notes` below - - ``xEventGroupCreateStatic()`` + - :cpp:func:`xTaskCreateStatic` (see :ref:`backporting-notes` below) + - :c:macro:`xQueueCreateStatic` + - :c:macro:`xSemaphoreCreateBinaryStatic` + - :c:macro:`xSemaphoreCreateCountingStatic` + - :c:macro:`xSemaphoreCreateMutexStatic` + - :c:macro:`xSemaphoreCreateRecursiveMutexStatic` + - :cpp:func:`xTimerCreateStatic` (see :ref:`backporting-notes` below) + - :cpp:func:`xEventGroupCreateStatic` Other Features ^^^^^^^^^^^^^^ - - ``vTaskSetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below - - ``pvTaskGetThreadLocalStoragePointer()`` See :ref:`backporting-notes` below - - ``vTimerSetTimerID()`` - - ``xTimerGetPeriod()`` - - ``xTimerGetExpiryTime()`` - - ``pcQueueGetName()`` - - ``uxSemaphoreGetCount()`` + - :cpp:func:`vTaskSetThreadLocalStoragePointer` (see :ref:`backporting-notes` below) + - :cpp:func:`pvTaskGetThreadLocalStoragePointer` (see :ref:`backporting-notes` below) + - :cpp:func:`vTimerSetTimerID` + - :cpp:func:`xTimerGetPeriod` + - :cpp:func:`xTimerGetExpiryTime` + - :cpp:func:`pcQueueGetName` + - :c:macro:`uxSemaphoreGetCount` .. _backporting-notes: Backporting Notes ^^^^^^^^^^^^^^^^^ -**1)** ``xTaskCreateStatic`` has been made SMP compatible in a similar -fashion to ``xTaskCreate`` (see :ref:`tasks-and-task-creation`). Therefore -``xTaskCreateStaticPinnedToCore()`` can also be called. +**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar +fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore +:cpp:func:`xTaskCreateStaticPinnedToCore` can also be called. **2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to be statically allocated, the daemon task is always dynamically allocated in @@ -130,7 +130,7 @@ defined when using statically allocated timers in ESP-IDF FreeRTOS. **3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore -the function ``vTaskSetThreadLocalStoragePointerAndDelCallback()`` can also be +the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be called. @@ -142,9 +142,9 @@ Tasks and Task Creation Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore two new task creation functions have been added to ESP-IDF FreeRTOS by appending ``PinnedToCore`` to the names of the task creation functions in -vanilla FreeRTOS. The vanilla FreeRTOS functions of ``xTaskCreate()`` -and ``xTaskCreateStatic()`` have led to the addition of -``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()`` in +vanilla FreeRTOS. The vanilla FreeRTOS functions of :cpp:func:`xTaskCreate` +and :cpp:func:`xTaskCreateStatic` have led to the addition of +:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS (see :ref:`backported-features`). For more details see :component_file:`freertos/task.c` @@ -164,9 +164,9 @@ of 1000 bytes. It should be noted that the ``uxStackDepth`` parameter in vanilla FreeRTOS specifies a task’s stack depth in terms of the number of words, whereas ESP-IDF FreeRTOS specifies the stack depth in terms of bytes. -Note that the vanilla FreeRTOS functions ``xTaskCreate`` and -``xTaskCreateStatic`` have been macro defined in ESP-IDF FreeRTOS to call -``xTaskCreatePinnedToCore()`` and ``xTaskCreateStaticPinnedToCore()`` +Note that the vanilla FreeRTOS functions :cpp:func:`xTaskCreate` and +:cpp:func:`xTaskCreateStatic` have been defined in ESP-IDF FreeRTOS as inline functions which call +:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` respectively with ``tskNO_AFFINITY`` as the ``xCoreID`` value. Each Task Control Block (TCB) in ESP-IDF stores the ``xCoreID`` as a member. @@ -283,18 +283,18 @@ different cores. Scheduler Suspension ^^^^^^^^^^^^^^^^^^^^ -In vanilla FreeRTOS, suspending the scheduler via ``vTaskSuspendAll()`` will -prevent calls of ``vTaskSwitchContext()`` from context switching until the -scheduler has been resumed with ``vTaskResumeAll()``. However servicing ISRs +In vanilla FreeRTOS, suspending the scheduler via :cpp:func:`vTaskSuspendAll` will +prevent calls of ``vTaskSwitchContext`` from context switching until the +scheduler has been resumed with :cpp:func:`xTaskResumeAll`. However servicing ISRs are still permitted. Therefore any changes in task states as a result from the current running task or ISRSs will not be executed until the scheduler is resumed. Scheduler suspension in vanilla FreeRTOS is a common protection method against simultaneous access of data shared between tasks, whilst still allowing ISRs to be serviced. -In ESP-IDF FreeRTOS, ``vTaskSuspendAll()`` will only prevent calls of +In ESP-IDF FreeRTOS, :cpp:func:`xTaskResumeAll` will only prevent calls of ``vTaskSwitchContext()`` from switching contexts on the core that called for the -suspension. Hence if **PRO_CPU** calls ``vTaskSuspendAll()``, **APP_CPU** will +suspension. Hence if **PRO_CPU** calls :cpp:func:`vTaskSuspendAll`, **APP_CPU** will still be able to switch contexts. If data is shared between tasks that are pinned to different cores, scheduler suspension is **NOT** a valid method of protection against simultaneous access. Consider using critical sections @@ -302,7 +302,7 @@ protection against simultaneous access. Consider using critical sections protecting shared resources in ESP-IDF FreeRTOS. In general, it's better to use other RTOS primitives like mutex semaphores to protect -against data shared between tasks, rather than ``vTaskSuspendAll()``. +against data shared between tasks, rather than :cpp:func:`vTaskSuspendAll`. .. _tick-interrupt-synchronicity: @@ -316,8 +316,8 @@ each core being independent, and the tick interrupts to each core being unsynchronized. In vanilla FreeRTOS the tick interrupt triggers a call to -``xTaskIncrementTick()`` which is responsible for incrementing the tick -counter, checking if tasks which have called ``vTaskDelay()`` have fulfilled +:cpp:func:`xTaskIncrementTick` which is responsible for incrementing the tick +counter, checking if tasks which have called :cpp:func:`vTaskDelay` have fulfilled their delay period, and moving those tasks from the Delayed Task List to the Ready Task List. The tick interrupt will then call the scheduler if a context switch is necessary. @@ -372,11 +372,11 @@ The ESP-IDF FreeRTOS critical section functions have been modified as follows… - ``taskENTER_CRITICAL(mux)``, ``taskENTER_CRITICAL_ISR(mux)``, ``portENTER_CRITICAL(mux)``, ``portENTER_CRITICAL_ISR(mux)`` are all macro - defined to call ``vTaskEnterCritical()`` + defined to call :cpp:func:`vTaskEnterCritical` - ``taskEXIT_CRITICAL(mux)``, ``taskEXIT_CRITICAL_ISR(mux)``, ``portEXIT_CRITICAL(mux)``, ``portEXIT_CRITICAL_ISR(mux)`` are all macro - defined to call ``vTaskExitCritical()`` + defined to call :cpp:func:`vTaskExitCritical` For more details see :component_file:`freertos/include/freertos/portmacro.h` and :component_file:`freertos/task.c` @@ -394,23 +394,23 @@ Floating Point Aritmetic ------------------------ The ESP32 supports hardware acceleration of single precision floating point -arithmetic (`float`) via Floating Point Units (FPU, also known as coprocessors) +arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors) attached to each core. The use of the FPUs imposes some behavioral restrictions on ESP-IDF FreeRTOS. ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, the state of a core's FPU registers are not immediately saved when a context -switch occurs. Therefore, tasks that utilize `float` must be pinned to a +switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin the task in question to whichever core the task was running on upon the task's -first use of `float`. Likewise due to Lazy Context Switching, interrupt service -routines must also not use `float`. +first use of ``float``. Likewise due to Lazy Context Switching, interrupt service +routines must also not use ``float``. ESP32 does not support hardware acceleration for double precision floating point -arithmetic (`double`). Instead `double` is implemented via software hence the -behavioral restrictions with regards to `float` do not apply to `double`. Note -that due to the lack of hardware acceleration, `double` operations may consume -significantly larger amount of CPU time in comparison to `float`. +arithmetic (``double``). Instead ``double`` is implemented via software hence the +behavioral restrictions with regards to ``float`` do not apply to ``double``. Note +that due to the lack of hardware acceleration, ``double`` operations may consume +significantly larger amount of CPU time in comparison to ``float``. .. _task-deletion: @@ -420,12 +420,12 @@ Task Deletion FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory entirely to the Idle Task. Currently, the freeing of task memory will occur -immediately (within `vTaskDelete()`) if the task being deleted is not currently +immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently running or is not pinned to the other core (with respect to the core -`vTaskDelete()` is called on). TLSP deletion callbacks will also run immediately +:cpp:func:`vTaskDelete` is called on). TLSP deletion callbacks will also run immediately if the same conditions are met. -However, calling `vTaskDelete()` to delete a task that is either currently +However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently running or pinned to the other core will still result in the freeing of memory being delegated to the Idle Task. @@ -456,8 +456,8 @@ is the index number of the associated TLSP, and the second parameter is the TLSP itself. Deletion callbacks are set alongside TLSP by calling -``vTaskSetThreadLocalStoragePointerAndDelCallback()``. Calling the vanilla -FreeRTOS function ``vTaskSetThreadLocalStoragePointer()`` will simply set the +:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla +FreeRTOS function :cpp:func:`vTaskSetThreadLocalStoragePointer` will simply set the TLSP's associated Deletion Callback to `NULL` meaning that no callback will be called for that TLSP during task deletion. If a deletion callback is `NULL`, users should manually free the memory pointed to by the associated TLSP before @@ -466,7 +466,7 @@ task deletion in order to avoid memory leak. :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used to configure the number TLSP and Deletion Callbacks a TCB will have. -For more details see :component_file:`freertos/include/freertos/task.h` +For more details see :doc:`FreeRTOS API reference<../api-reference/system/freertos>`. .. _esp-idf-freertos-configuration: @@ -491,9 +491,9 @@ number of Thread Local Storage Pointers each task will have in ESP-IDF FreeRTOS. :ref:`CONFIG_SUPPORT_STATIC_ALLOCATION` will enable the backported -functionality of ``xTaskCreateStaticPinnedToCore()`` in ESP-IDF FreeRTOS +functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in particular functions in ESP-IDF FreeRTOS which have not been fully tested in an SMP context. - +