doc: Add clarifications Xtensa Core ID and "Core ID" used in FreeRTOS are different

Closes https://github.com/espressif/esp-idf/issues/2567

diff --git a/components/freertos/include/freertos/portmacro.h b/components/freertos/include/freertos/portmacro.h
index d5df0b274e416a8b2cade460b0130048f759af17..6b09a2ce8bfa07b357a616d282759e45ddeca2da 100644 (file)
--- a/components/freertos/include/freertos/portmacro.h
+++ b/components/freertos/include/freertos/portmacro.h
@@ -136,10 +136,14 @@ typedef unsigned portBASE_TYPE    UBaseType_t;
 /* "mux" data structure (spinlock) */
 typedef struct {
        /* owner field values:
-        * 0                - Uninitialized (invalid)
+        * 0                            - Uninitialized (invalid)
         * portMUX_FREE_VAL - Mux is free, can be locked by either CPU
         * CORE_ID_PRO / CORE_ID_APP - Mux is locked to the particular core
         *
+        * Note that for performance reasons we use the full Xtensa CORE ID values
+        * (CORE_ID_PRO, CORE_ID_APP) and not the 0,1 values which are used in most
+        * other FreeRTOS code.
+        *
         * Any value other than portMUX_FREE_VAL, CORE_ID_PRO, CORE_ID_APP indicates corruption
         */
        uint32_t owner;

diff --git a/components/freertos/include/freertos/task.h b/components/freertos/include/freertos/task.h
index 3fc06d9e38a0f45ab99458d016e20258ce928fb9..8fb6ee22fb32dec1d777a14c25bc80ab411fc977 100644 (file)
--- a/components/freertos/include/freertos/task.h
+++ b/components/freertos/include/freertos/task.h
@@ -185,7 +185,7 @@ typedef struct xTASK_STATUS
        StackType_t *pxStackBase;               /*!< Points to the lowest address of the task's stack area. */
        uint32_t usStackHighWaterMark;  /*!< The minimum amount of stack space that has remained for the task since the task was created.  The closer this value is to zero the closer the task has come to overflowing its stack. */
 #if configTASKLIST_INCLUDE_COREID
-       BaseType_t xCoreID;                             /*!< Core this task is pinned to. This field is present if CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID is set. */
+       BaseType_t xCoreID;                             /*!< Core this task is pinned to (0, 1, or -1 for tskNO_AFFINITY). This field is present if CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID is set. */
 #endif
 } TaskStatus_t;
 
@@ -324,7 +324,7 @@ is used in assert() statements. */
  *
  * @param xCoreID If the value is tskNO_AFFINITY, the created task is not
  * pinned to any CPU, and the scheduler can run it on any core available.
- * Other values indicate the index number of the CPU which the task should
+ * Values 0 or 1 indicate the index number of the CPU which the task should
  * be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will
  * cause the function to fail.
  *
@@ -476,7 +476,7 @@ is used in assert() statements. */
  *
  * @param xCoreID If the value is tskNO_AFFINITY, the created task is not
  * pinned to any CPU, and the scheduler can run it on any core available.
- * Other values indicate the index number of the CPU which the task should
+ * Values 0 or 1 indicate the index number of the CPU which the task should
  * be pinned to. Specifying values larger than (portNUM_PROCESSORS - 1) will
  * cause the function to fail.
  *

diff --git a/components/freertos/include/freertos/xtensa_context.h b/components/freertos/include/freertos/xtensa_context.h
index 9e6fe558f541e24b19885784fa3d5e575ddd97c3..073a137bced97a4c0b76a46aecc5a355c5b29c38 100644 (file)
--- a/components/freertos/include/freertos/xtensa_context.h
+++ b/components/freertos/include/freertos/xtensa_context.h
@@ -325,6 +325,9 @@ STRUCT_END(XtSolFrame)
        .endm
 #endif
 
+/* Note: These are different to xCoreID used in ESP-IDF FreeRTOS, we just use
+   0 and 1 which are determined by checking bit 13 (see previous comment)
+*/
 #define CORE_ID_PRO 0xCDCD
 #define CORE_ID_APP 0xABAB