change(freertos/idf): Deprecate some FreeRTOS IDF addition functions

This commit deprecates xTaskGetAffinity(), xTaskGetCurrentTaskHandleForCPU() and xTaskGetIdleTaskHandleForCPU() APIs for IDF-FreeRTOS kernel. Instead, users are directed to use alternatives. All other components in IDF using these functions have been updated accordingly.
2023-11-02 11:19:42 +01:00 · 2023-11-02 11:19:42 +01:00 · d38f100223
commit d38f100223
--- a/components/esp_gdbstub/src/gdbstub.c
+++ b/components/esp_gdbstub/src/gdbstub.c
@ -925,14 +925,14 @@ static int get_task_cpu_id(size_t index)
    if (!get_task_handle(index, &handle)) {
        return -1;
    }
-    BaseType_t core_id = xTaskGetAffinity(handle);
+    BaseType_t core_id = xTaskGetCoreID(handle);
    return (int)core_id;
 }

 /** Get the index of the task running on the current CPU, and save the result */
 static void find_paniced_task_index(void)
 {
-    TaskHandle_t cur_handle = (TaskHandle_t)xTaskGetCurrentTaskHandleForCPU(xPortGetCoreID());
+    TaskHandle_t cur_handle = (TaskHandle_t)xTaskGetCurrentTaskHandleForCore(xPortGetCoreID());
    TaskHandle_t handle;
    for (int i = 0; i < s_scratch.task_count; i++) {
        if (get_task_handle(i, &handle) && cur_handle == handle) {
--- a/components/esp_system/port/arch/riscv/debug_helpers.c
+++ b/components/esp_system/port/arch/riscv/debug_helpers.c
@ -39,7 +39,7 @@ esp_err_t IRAM_ATTR esp_backtrace_print(int depth)
    const int current_core = xPortGetCoreID();

    TaskSnapshot_t snapshot = { 0 };
-    BaseType_t ret = vTaskGetSnapshot(xTaskGetCurrentTaskHandleForCPU(current_core), &snapshot);
+    BaseType_t ret = vTaskGetSnapshot(xTaskGetCurrentTaskHandleForCore(current_core), &snapshot);

    if (ret != pdTRUE) {
        return ESP_ERR_NOT_FOUND;
--- a/components/esp_system/port/arch/riscv/panic_arch.c
+++ b/components/esp_system/port/arch/riscv/panic_arch.c
@ -167,7 +167,7 @@ static inline void print_assist_debug_details(const void *frame)
 {
    uint32_t core_id = esp_cpu_get_core_id();
    uint32_t sp_min, sp_max;
-    const char *task_name = pcTaskGetName(xTaskGetCurrentTaskHandleForCPU(core_id));
+    const char *task_name = pcTaskGetName(xTaskGetCurrentTaskHandleForCore(core_id));
    esp_hw_stack_guard_get_bounds(&sp_min, &sp_max);

    panic_print_str("\r\n");
--- a/components/esp_system/port/arch/xtensa/panic_arch.c
+++ b/components/esp_system/port/arch/xtensa/panic_arch.c
@ -146,7 +146,7 @@ static void print_debug_exception_details(const void *f)
            }
 #endif

-            const char *name = pcTaskGetName(xTaskGetCurrentTaskHandleForCPU(core));
+            const char *name = pcTaskGetName(xTaskGetCurrentTaskHandleForCore(core));
            panic_print_str("Stack canary watchpoint triggered (");
            panic_print_str(name);
            panic_print_str(") ");
--- a/components/esp_system/task_wdt/task_wdt.c
+++ b/components/esp_system/task_wdt/task_wdt.c
@ -279,7 +279,7 @@ static void unsubscribe_idle(uint32_t core_mask)
            ESP_ERROR_CHECK(esp_task_wdt_delete_user(core_user_handles[core_num]));
            core_user_handles[core_num] = NULL;
 #else // CONFIG_FREERTOS_SMP
-            TaskHandle_t idle_task_handle = xTaskGetIdleTaskHandleForCPU(core_num);
+            TaskHandle_t idle_task_handle = xTaskGetIdleTaskHandleForCore(core_num);
            assert(idle_task_handle);
            esp_deregister_freertos_idle_hook_for_cpu(idle_hook_cb, core_num);
            ESP_ERROR_CHECK(esp_task_wdt_delete(idle_task_handle));
@ -306,7 +306,7 @@ static void subscribe_idle(uint32_t core_mask)
            ESP_ERROR_CHECK(esp_task_wdt_add_user((const char *)core_user_names[core_num], &core_user_handles[core_num]));
            ESP_ERROR_CHECK(esp_register_freertos_idle_hook_for_cpu(idle_hook_cb, core_num));
 #else // CONFIG_FREERTOS_SMP
-            TaskHandle_t idle_task_handle = xTaskGetIdleTaskHandleForCPU(core_num);
+            TaskHandle_t idle_task_handle = xTaskGetIdleTaskHandleForCore(core_num);
            assert(idle_task_handle);
            ESP_ERROR_CHECK(esp_task_wdt_add(idle_task_handle));
            ESP_ERROR_CHECK(esp_register_freertos_idle_hook_for_cpu(idle_hook_cb, core_num));
@ -489,7 +489,7 @@ static void task_wdt_isr(void *arg)
                cpus_fail |= BIT(0);
 #endif // configNUM_CORES > 1
 #else // CONFIG_FREERTOS_SMP
-                BaseType_t task_affinity = xTaskGetAffinity(entry->task_handle);
+                BaseType_t task_affinity = xTaskGetCoreID(entry->task_handle);
                const char *cpu;
                if (task_affinity == 0) {
                    cpu = DRAM_STR("CPU 0");
@ -517,7 +517,7 @@ static void task_wdt_isr(void *arg)
    }
    ESP_EARLY_LOGE(TAG, "%s", DRAM_STR("Tasks currently running:"));
    for (int x = 0; x < portNUM_PROCESSORS; x++) {
-        ESP_EARLY_LOGE(TAG, "CPU %d: %s", x, pcTaskGetName(xTaskGetCurrentTaskHandleForCPU(x)));
+        ESP_EARLY_LOGE(TAG, "CPU %d: %s", x, pcTaskGetName(xTaskGetCurrentTaskHandleForCore(x)));
    }
    portEXIT_CRITICAL_ISR(&spinlock);

--- a/components/espcoredump/src/core_dump_common.c
+++ b/components/espcoredump/src/core_dump_common.c
@ -319,7 +319,7 @@ inline bool esp_core_dump_in_isr_context(void)

 inline core_dump_task_handle_t esp_core_dump_get_current_task_handle()
 {
-    return (core_dump_task_handle_t) xTaskGetCurrentTaskHandleForCPU(xPortGetCoreID());
+    return (core_dump_task_handle_t) xTaskGetCurrentTaskHandleForCore(xPortGetCoreID());
 }

 #endif
--- a/components/freertos/esp_additions/include/freertos/idf_additions.h
+++ b/components/freertos/esp_additions/include/freertos/idf_additions.h
@ -129,15 +129,6 @@
 */
 BaseType_t xTaskGetCoreID( TaskHandle_t xTask );

-/** @cond */
-/* Todo: Deprecate this API in favor of xTaskGetIdleTaskHandleForCore (IDF-8163) */
-static inline __attribute__( ( always_inline ) )
-BaseType_t xTaskGetAffinity( TaskHandle_t xTask )
-{
-    return xTaskGetCoreID( xTask );
-}
-/** @endcond */
-
 /**
 * @brief Get the handle of idle task for the given core.
 *
@ -150,15 +141,6 @@ BaseType_t xTaskGetAffinity( TaskHandle_t xTask )
 */
 TaskHandle_t xTaskGetIdleTaskHandleForCore( BaseType_t xCoreID );

-/** @cond */
-/* Todo: Deprecate this API in favor of xTaskGetIdleTaskHandleForCore (IDF-8163) */
-static inline __attribute__( ( always_inline ) )
-TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID )
-{
-    return xTaskGetIdleTaskHandleForCore( xCoreID );
-}
-/** @endcond */
-
 /**
 * @brief Get the handle of the task currently running on a certain core
 *
@ -175,14 +157,6 @@ TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID )
 */
 TaskHandle_t xTaskGetCurrentTaskHandleForCore( BaseType_t xCoreID );

-/** @cond */
-/* Todo: Deprecate this API in favor of xTaskGetCurrentTaskHandleForCore (IDF-8163) */
-static inline __attribute__( ( always_inline ) )
-TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t xCoreID )
-{
-    return xTaskGetCurrentTaskHandleForCore( xCoreID );
-}
-/** @endcond */

 #if ( !CONFIG_FREERTOS_SMP && ( configGENERATE_RUN_TIME_STATS == 1 ) && ( INCLUDE_xTaskGetIdleTaskHandle == 1 ) )

@ -644,6 +618,32 @@ void vStreamBufferGenericDeleteWithCaps( StreamBufferHandle_t xStreamBuffer,

 #endif /* configSUPPORT_STATIC_ALLOCATION == 1 */

+
+/* --------------------------------------------------- Deprecated ------------------------------------------------------
+ * Deprecated IDF FreeRTOS API additions.
+ * Todo: Remove in v6.0 (IDF-8499)
+ * ------------------------------------------------------------------------------------------------------------------ */
+
+/** @cond */
+static inline __attribute__( ( always_inline, deprecated( "This function is deprecated and will be removed in ESP-IDF 6.0. Please use xTaskGetCoreID() instead." ) ) )
+BaseType_t xTaskGetAffinity( TaskHandle_t xTask )
+{
+    return xTaskGetCoreID( xTask );
+}
+
+static inline __attribute__( ( always_inline, deprecated( "This function is deprecated and will be removed in ESP-IDF 6.0. Please use xTaskGetIdleTaskHandleForCore() instead." ) ) )
+TaskHandle_t xTaskGetIdleTaskHandleForCPU( BaseType_t xCoreID )
+{
+    return xTaskGetIdleTaskHandleForCore( xCoreID );
+}
+
+static inline __attribute__( ( always_inline, deprecated( "This function is deprecated and will be removed in ESP-IDF 6.0. Please use xTaskGetCurrentTaskHandleForCore() instead." ) ) )
+TaskHandle_t xTaskGetCurrentTaskHandleForCPU( BaseType_t xCoreID )
+{
+    return xTaskGetCurrentTaskHandleForCore( xCoreID );
+}
+/** @endcond */
+
 /* *INDENT-OFF* */
 #ifdef __cplusplus
    }
--- a/components/freertos/test_apps/freertos/kernel/tasks/test_freertos_psram.c
+++ b/components/freertos/test_apps/freertos/kernel/tasks/test_freertos_psram.c
@ -107,7 +107,7 @@ typedef struct {
 static void task_report_corenum(void *arg)
 {
    report_corenum_info_t *info = (report_corenum_info_t*) arg;
-    info->recorded_core_num = xTaskGetAffinity(NULL);
+    info->recorded_core_num = xTaskGetCoreID(NULL);
    xTaskNotifyGive(info->parent_handle);
    vTaskSuspend(NULL);
 }
--- a/components/freertos/test_apps/freertos/kernel/tasks/test_vTaskSuspendAll_xTaskResumeAll.c
+++ b/components/freertos/test_apps/freertos/kernel/tasks/test_vTaskSuspendAll_xTaskResumeAll.c
@ -595,7 +595,7 @@ static void test_pended_running_task(void *arg)
    // While tasks which do not have affinity to the current core are unblocked.
    for (int i = 0; i < TEST_PENDED_NUM_BLOCKED_TASKS; i++) {
        // Note: We use eBlocked instead of eReady due to a bug in eTaskGetState(). See (IDF-5543)
-        if (xTaskGetAffinity(blkd_tsks[i]) == xPortGetCoreID()) {
+        if (xTaskGetCoreID(blkd_tsks[i]) == xPortGetCoreID()) {
            TEST_ASSERT_EQUAL(eBlocked, eTaskGetState(blkd_tsks[i]));
            TEST_ASSERT_EQUAL(false, has_run[i]);
        } else {
--- a/components/freertos/test_apps/freertos/port/test_fpu_in_isr.c
+++ b/components/freertos/test_apps/freertos/port/test_fpu_in_isr.c
@ -119,7 +119,7 @@ static void unpinned_task(void *arg)
 #if CONFIG_FREERTOS_SMP
    TEST_ASSERT_EQUAL(tskNO_AFFINITY, vTaskCoreAffinityGet(NULL));
 #else
-    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetAffinity(NULL));
+    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetCoreID(NULL));
 #endif
 #endif // !CONFIG_FREERTOS_UNICORE

@ -136,7 +136,7 @@ static void unpinned_task(void *arg)
 #if CONFIG_FREERTOS_SMP
    TEST_ASSERT_EQUAL(tskNO_AFFINITY, vTaskCoreAffinityGet(NULL));
 #else
-    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetAffinity(NULL));
+    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetCoreID(NULL));
 #endif
 #endif // !CONFIG_FREERTOS_UNICORE
    // Reenable scheduling/preemption
--- a/components/freertos/test_apps/freertos/port/test_fpu_in_task.c
+++ b/components/freertos/test_apps/freertos/port/test_fpu_in_task.c
@ -141,7 +141,7 @@ static void unpinned_task(void *arg)
 #if CONFIG_FREERTOS_SMP
    TEST_ASSERT_EQUAL(tskNO_AFFINITY, vTaskCoreAffinityGet(NULL));
 #else
-    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetAffinity(NULL));
+    TEST_ASSERT_EQUAL(tskNO_AFFINITY, xTaskGetCoreID(NULL));
 #endif
 #endif // !CONFIG_FREERTOS_UNICORE

@ -162,7 +162,7 @@ static void unpinned_task(void *arg)
 #if CONFIG_FREERTOS_SMP
    TEST_ASSERT_EQUAL(1 << cur_core_num, vTaskCoreAffinityGet(NULL));
 #else
-    TEST_ASSERT_EQUAL(cur_core_num, xTaskGetAffinity(NULL));
+    TEST_ASSERT_EQUAL(cur_core_num, xTaskGetCoreID(NULL));
 #endif
 #endif // !CONFIG_FREERTOS_UNICORE
    // Reenable scheduling/preemption
--- a/components/unity/unity_utils_freertos.c
+++ b/components/unity/unity_utils_freertos.c
@ -49,7 +49,7 @@ void unity_utils_task_delete(TaskHandle_t thandle)
 #if CONFIG_FREERTOS_UNICORE
    vTaskDelete(thandle);
 #else // CONFIG_FREERTOS_UNICORE
-    const BaseType_t tsk_affinity = xTaskGetAffinity(thandle);
+    const BaseType_t tsk_affinity = xTaskGetCoreID(thandle);
    const BaseType_t core_id = xPortGetCoreID();

    printf("Task_affinity: 0x%x, current_core: %d\n", tsk_affinity, core_id);