*(.gnu.linkonce.lit4.*)
_lit4_end = ABSOLUTE(.);
. = ALIGN(4);
+ _thread_local_start = ABSOLUTE(.);
+ *(.tdata)
+ *(.tdata.*)
+ *(.tbss)
+ *(.tbss.*)
+ _thread_local_end = ABSOLUTE(.);
+ . = ALIGN(4);
} >drom0_0_seg
.flash.text :
* @return pdPASS if the task was successfully created and added to a ready
* list, otherwise an error code defined in the file projdefs.h
*
+ * @note If program uses thread local variables (ones specified with "__thread" keyword)
+ * then storage for them will be allocated on the task's stack.
+ *
* Example usage:
* @code{c}
* // Task to be created.
* are NULL then the task will not be created and
* errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
*
+ * @note If program uses thread local variables (ones specified with "__thread" keyword)
+ * then storage for them will be allocated on the task's stack.
+ *
* Example usage:
* @code{c}
*
*/
#include <stdlib.h>
+#include <string.h>
#include <xtensa/config/core.h>
#include "xtensa_rtos.h"
#if XCHAL_CP_NUM > 0
uint32_t *p;
#endif
+ uint32_t *threadptr;
+ void *task_thread_local_start;
+ extern int _thread_local_start, _thread_local_end, _rodata_start;
+ // TODO: check that TLS area fits the stack
+ uint32_t thread_local_sz = (uint8_t *)&_thread_local_end - (uint8_t *)&_thread_local_start;
- /* Create interrupt stack frame aligned to 16 byte boundary */
- sp = (StackType_t *) (((UBaseType_t)(pxTopOfStack + 1) - XT_CP_SIZE - XT_STK_FRMSZ) & ~0xf);
+ thread_local_sz = ALIGNUP(0x10, thread_local_sz);
+
+ /* Initialize task's stack so that we have the following structure at the top:
+
+ ----LOW ADDRESSES ----------------------------------------HIGH ADDRESSES----------
+ task stack | interrupt stack frame | thread local vars | co-processor save area |
+ ----------------------------------------------------------------------------------
+ | |
+ SP pxTopOfStack
+
+ All parts are aligned to 16 byte boundary. */
+ sp = (StackType_t *) (((UBaseType_t)(pxTopOfStack + 1) - XT_CP_SIZE - thread_local_sz - XT_STK_FRMSZ) & ~0xf);
/* Clear the entire frame (do not use memset() because we don't depend on C library) */
for (tp = sp; tp <= pxTopOfStack; ++tp)
frame->vpri = 0xFFFFFFFF;
#endif
+ /* Init threadptr reg and TLS vars */
+ task_thread_local_start = (void *)(((uint32_t)pxTopOfStack - XT_CP_SIZE - thread_local_sz) & ~0xf);
+ memcpy(task_thread_local_start, &_thread_local_start, thread_local_sz);
+ threadptr = (uint32_t *)(sp + XT_STK_EXTRA);
+ /* shift threadptr by the offset of _thread_local_start from DROM start;
+ need to take into account extra 16 bytes offset */
+ *threadptr = (uint32_t)task_thread_local_start - ((uint32_t)&_thread_local_start - (uint32_t)&_rodata_start) - 0x10;
+
#if XCHAL_CP_NUM > 0
/* Init the coprocessor save area (see xtensa_context.h) */
/* No access to TCB here, so derive indirectly. Stack growth is top to bottom.
--- /dev/null
+/*
+ Test for thread local storage support.
+*/
+
+#include <string.h>
+#include <esp_types.h>
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "unity.h"
+#include "sdkconfig.h"
+
+static __thread int tl_test_var1;
+static __thread uint8_t tl_test_var2 = 55;
+static __thread uint16_t tl_test_var3 = 44;
+static __thread uint8_t tl_test_arr_var[10];
+static __thread struct test_tls_var {
+ int f32;
+ uint8_t f8;
+ uint16_t f16;
+ uint8_t farr[10];
+} tl_test_struct_var;
+
+static void task_test_tls(void *arg)
+{
+ bool *running = (bool *)arg;
+ uint32_t tp = (uint32_t)-1;
+ int test_var1_old = 0;
+ uint8_t test_var2_old = 0;
+ uint16_t test_var3_old = 0;
+ int f32_old = 0;
+ uint8_t f8_old = 0;
+ uint16_t f16_old = 0;
+
+ asm volatile ("rur.threadptr %0":"=r"(tp));
+ for (int i = 0; i < 5; i++) {
+ printf("Task[%x]: var = 0x%x 0x%x\n", tp, tl_test_var1, tl_test_var2);
+ if (i == 0) {
+ TEST_ASSERT_EQUAL(0, tl_test_var1);
+ TEST_ASSERT_EQUAL(55, tl_test_var2);
+ TEST_ASSERT_EQUAL(44, tl_test_var3);
+ for (int k = 0; k < sizeof(tl_test_arr_var); k++) {
+ TEST_ASSERT_EQUAL(0, tl_test_arr_var[k]);
+ }
+ TEST_ASSERT_EQUAL(0, tl_test_struct_var.f32);
+ TEST_ASSERT_EQUAL(0, tl_test_struct_var.f8);
+ TEST_ASSERT_EQUAL(0, tl_test_struct_var.f16);
+ for (int k = 0; k < sizeof(tl_test_struct_var.farr); k++) {
+ TEST_ASSERT_EQUAL(0, tl_test_struct_var.farr[k]);
+ }
+ } else {
+ TEST_ASSERT_EQUAL(test_var1_old+1, tl_test_var1);
+ TEST_ASSERT_EQUAL(test_var2_old+1, tl_test_var2);
+ TEST_ASSERT_EQUAL(test_var3_old+1, tl_test_var3);
+ for (int k = 0; k < sizeof(tl_test_arr_var); k++) {
+ TEST_ASSERT_EQUAL(i-1, tl_test_arr_var[k]);
+ }
+ TEST_ASSERT_EQUAL(f32_old+1, tl_test_struct_var.f32);
+ TEST_ASSERT_EQUAL(f8_old+1, tl_test_struct_var.f8);
+ TEST_ASSERT_EQUAL(f16_old+1, tl_test_struct_var.f16);
+ for (int k = 0; k < sizeof(tl_test_struct_var.farr); k++) {
+ TEST_ASSERT_EQUAL(i-1, tl_test_struct_var.farr[k]);
+ }
+ }
+ test_var1_old = tl_test_var1;
+ test_var2_old = tl_test_var2;
+ test_var3_old = tl_test_var3;
+ f32_old = tl_test_struct_var.f32;
+ f8_old = tl_test_struct_var.f8;
+ f16_old = tl_test_struct_var.f16;
+ tl_test_var1++;
+ tl_test_var2++;
+ tl_test_var3++;
+ memset(tl_test_arr_var, i, sizeof(tl_test_arr_var));
+ tl_test_struct_var.f32++;
+ tl_test_struct_var.f8++;
+ tl_test_struct_var.f16++;
+ memset(tl_test_struct_var.farr, i, sizeof(tl_test_struct_var.farr));
+ vTaskDelay(10);
+ }
+
+ if (running) {
+ *running = false;
+ vTaskDelete(NULL);
+ }
+}
+
+TEST_CASE("TLS test", "[freertos]")
+{
+ static StackType_t s_stack[2048];
+ StaticTask_t s_task;
+ bool running[2] = {true, true};
+#if CONFIG_FREERTOS_UNICORE == 0
+ int other_core = 1;
+#else
+ int other_core = 0;
+#endif
+
+ xTaskCreatePinnedToCore((TaskFunction_t)&task_test_tls, "task_test_tls", 3072, &running[0], 5, NULL, 0);
+ xTaskCreateStaticPinnedToCore((TaskFunction_t)&task_test_tls, "task_test_tls", sizeof(s_stack), &running[1],
+ 5, s_stack, &s_task, other_core);
+ while (running[0] || running[1]) {
+ vTaskDelay(10);
+ }
+}
ESP32 Core Dump <core_dump>
Flash Encryption <../security/flash-encryption>
FreeRTOS SMP Changes <freertos-smp>
+ Thread Local Storage <thread-local-storage>
High Level Interrupts <hlinterrupts>
JTAG Debugging <jtag-debugging/index>
Partition Tables <partition-tables>
--- /dev/null
+Thread Local Storage
+====================
+
+Overview
+--------
+
+Thread-local storage (TLS) is a mechanism by which variables are allocated such that there
+is one instance of the variable per extant thread. ESP-IDF provides three ways to make use
+of such variables:
+
+ - :ref:`freertos-native`: ESP-IDF FreeRTOS native API.
+ - :ref:`pthread-api`: ESP-IDF's pthread API.
+ - :ref:`c11-std`: C11 standard introduces special keyword to declare variables as thread local.
+
+.. _freertos-native:
+
+FreeRTOS Native API
+--------------------
+
+The ESP-IDF FreeRTOS provides the following API to manage thread local variables:
+
+ - :cpp:func:`vTaskSetThreadLocalStoragePointer`
+ - :cpp:func:`pvTaskGetThreadLocalStoragePointer`
+ - :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`
+
+In this case maximum number of variables that can be allocated is limited by
+``configNUM_THREAD_LOCAL_STORAGE_POINTERS`` macro. Variables are kept in the task control block (TCB)
+and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
+Using that API user can allocate thread local variables of an arbitrary size and assign them to any number of tasks.
+Different tasks can have different sets of TLS variables.
+If size of the variable is more then 4 bytes then user is responsible for allocating/deallocating memory for it.
+Variable's deallocation is initiated by FreeRTOS when task is deleted, but user must provide function (callback)
+to do proper cleanup.
+
+.. _pthread-api:
+
+Pthread API
+----------------
+
+The ESP-IDF provides the following pthread API to manage thtread local variables:
+
+ - :cpp:func:`pthread_key_create`
+ - :cpp:func:`pthread_key_delete`
+ - :cpp:func:`pthread_getspecific`
+ - :cpp:func:`pthread_setspecific`
+
+This API has all benefits of the one above, but eliminates some its limits. The number of variables is
+limited only by size of available memory on the heap.
+Due to the dynamic nature this API introduces additional performance overhead compared to the native one.
+
+.. _c11-std:
+
+C11 Standard
+------------
+
+The ESP-IDF FreeRTOS supports thread local variables according to C11 standard (ones specified with ``__thread`` keyword).
+For details on this GCC feature please see https://gcc.gnu.org/onlinedocs/gcc-5.5.0/gcc/Thread-Local.html#Thread-Local.
+Storage for that kind of variables is allocated on the task's stack.
+Note that area for all such variables in the program will be allocated on the stack of
+every task in the system even if that task does not use such variables at all. For example
+ESP-IDF system tasks (like ``ipc``, ``timer`` tasks etc.) will also have that extra stack space allocated.
+So this feature should be used with care. There is a tradeoff: C11 thread local variables are quite handy
+to use in programming and can be accessed using just a few Xtensa instructions, but this benefit goes
+with the cost of additional stack usage for all tasks in the system.
+Due to static nature of variables allocation all tasks in the system have the same sets of C11 thread local variables.
projects / esp-idf / commitdiff