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
: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.
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.
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<hooks_api_reference>`: Vanilla FreeRTOS Hooks were not designed for SMP.
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
**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.
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`
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.
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
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:
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.
- ``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`
------------------------
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:
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.
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
: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:
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.
-
+
projects / esp-idf / commitdiff