Tasks - Espressif ESP32-S2 Programming Manual

Chapter 4. API Guides
Although an SMP system allows threads to switch cores, there are scenarios where a thread must/should only run on
a particular core. Therefore, threads in an SMP systems will also have a core affinity that specifies which particular
core the thread is allowed to run on.
• A thread that is pinned to a particular core will only be able to run on that core
• A thread that is unpinned will be allowed to switch between cores during execution instead of being pinned to
a particular core.
SMP on an ESP Target
ESP targets (such as the ESP32, ESP32-S3) are dual core SMP SoCs. These targets have the following hardware
features that make them SMP capable:
• Two identical cores known as CPU0 (i.e., Protocol CPU or PRO_CPU) and CPU1 (i.e., Application CPU or
APP_CPU). This means that the execution of a piece of code is identical regardless of which core it runs on.
• Symmetric memory (with some small exceptions).
– If multiple cores access the same memory address, their access will be serialized at the memory bus level.
– True atomic access to the same memory address is achieved via an atomic compare-and-swap instruction
provided by the ISA.
• Cross-core interrupts that allow one CPU to trigger and interrupt on another CPU. This allows cores to signal
each other.
Note: The"PRO_CPU" and"APP_CPU" aliases for CPU0 and CPU1 exist in ESP-IDF as they reflect how typical
IDF applications will utilize the two CPUs. Typically, the tasks responsible for handling wireless networking (e.g.,
WiFi or Bluetooth) will be pinned to CPU0 (thus the name PRO_CPU), whereas the tasks handling the remainder
of the application will be pinned to CPU1 (thus the name APP_CPU).

4.14.3 Tasks

Creation
Vanilla FreeRTOS provides the following functions to create a task:
• xTaskCreate()
• xTaskCreateStatic()
user)
However, in an SMP system, tasks need to be assigned a particular affinity. Therefore, ESP-IDF provides a Pinned-
ToCore version of Vanilla FreeRTOS's task creation functions:
• xTaskCreatePinnedToCore()
dynamically allocated.
• xTaskCreateStaticPinnedToCore()
ory is statically allocated (i.e., provided by the user)
The PinnedToCore versions of the task creation functions API differ from their vanilla counter parts by having an
extra xCoreID parameter that is used to specify the created task's core affinity. The valid values for core affinity
are:
• 0 which pins the created task to CPU0
• 1 which pins the created task to CPU1
• tskNO_AFFINITY which allows the task to be run on both CPUs
Note that ESP-IDF FreeRTOS still supports the vanilla versions of the task creation functions. However, they have
been modified to simply call their PinnedToCore counterparts with tskNO_AFFINITY.
Note: ESP-IDF FreeRTOS also changes the units of ulStackDepth in the task creation functions. Task stack
sizes in Vanilla FreeRTOS are specified in number of words, whereas in ESP-IDF FreeRTOS, the task stack sizes
Espressif Systems
creates a task. The task's memory is dynamically allocated
creates a task. The task's memory is statically allocated (i.e., provided by the
creates a task with a particular core affinity. The task's memory is
Submit Document Feedback
creates a task with a particular core affinity. The task' s mem-
1359 Release v4.4