Merge branch 'refactor/freertos_component_structure' into 'master'

FreeRTOS: Refactor copmonent structure

See merge request espressif/esp-idf!23367

components/freertos/CMakeLists.txt

@@ -1,114 +1,189 @@
+# FreeRTOS Component Architecture
+#
+# The FreeRTOS component mainly contains
+# - Different FreeRTOS kernel implementations (namely IDF FreeRTOS and Amazon SMP FreeRTOS).
+# - Different ports of each architecture for each kernel implementaiton.
+# - IDF additions to FreeRTOS (e.g., features and API) to augment FreeRTOS
+#
+# The FreeRTOS component organizes its files as follows
+#
+# - `./config`
+#       - Contains all "FreeRTOSConfig.h" files required by FreeRTOS
+# - `./esp_additions`
+#       - Additional features added by ESP-IDF to augment FreeRTOS, and not part of the original kernel
+# - `./FreeRTOS-Kernel-...`
+#       - Different FreeRTOS kernel implementations. Each implementaiton is kept in its own directory.
+#       - Ports for the implementation are kept in `FreeRTOS-Kernel-.../portable/xxx/`\
+# - `./test_apps`
+#       - Contains all unit tests/test apps for the FreeRTOS component.
+# - `./`
+#       - Files common across all kernel implementations and all ports
+
+# Bootloader builds only needs FreeRTOS for config, not for anything else
 if(BOOTLOADER_BUILD)
-    # bootloader only needs FreeRTOS for config, not for anything else
     idf_component_register()
     return()
 endif()
 
+# Set some convenience variables
 idf_build_get_property(target IDF_TARGET)
 
 if(CONFIG_FREERTOS_SMP)
-    set(kernel_dir "FreeRTOS-Kernel-SMP")
+    set(kernel_impl "FreeRTOS-Kernel-SMP")
 else()
-    set(kernel_dir "FreeRTOS-Kernel")
+    set(kernel_impl "FreeRTOS-Kernel")
 endif()
 
 if(CONFIG_IDF_TARGET_ARCH_XTENSA)
-set(arch "xtensa")
+    set(arch "xtensa")
 elseif(CONFIG_IDF_TARGET_ARCH_RISCV)
-set(arch "riscv")
+    set(arch "riscv")
 elseif(${target} STREQUAL "linux")
-set(arch "linux")
+    set(arch "linux")
 endif()
 
-set(srcs
-    "heap_idf.c"
-    "esp_additions/idf_additions.c"
-    "${kernel_dir}/list.c"
-    "${kernel_dir}/queue.c"
-    "${kernel_dir}/tasks.c"
-    "${kernel_dir}/timers.c"
-    "${kernel_dir}/croutine.c"
-    "${kernel_dir}/event_groups.c"
-    "${kernel_dir}/stream_buffer.c"
-    "${kernel_dir}/portable/${arch}/port.c")
-
-set(include_dirs
-    "${kernel_dir}/include" # FreeRTOS headers via #include "freertos/xxx.h"
-    "${kernel_dir}/portable/${arch}/include" # For arch-specific #include "freertos/portmacro.h"
-    "esp_additions/include/freertos"         # For files with #include "FreeRTOSConfig.h"
-    "esp_additions/include"                  # For files with #include "freertos/FreeRTOSConfig.h"
-                                             #      or #include "freertos/task_snapshot.h"
-                                             #      or #include "freertos/idf_additions.h"
-                                             #      or #include "esp_private/freertos_idf_additions_priv.h"
-    "esp_additions/arch/${arch}/include")    # For #include "freertos/FreeRTOSConfig_arch.h"
+set(srcs "")
+set(include_dirs "")
+set(private_include_dirs "")
+set(private_requirements "")
+set(ldfragments "")
 
-if(CONFIG_FREERTOS_SMP)
-    list(APPEND include_dirs "${kernel_dir}/portable/${arch}/include/freertos") # Xtensa headers via #include "xx.h"
-endif()
+# ---------------------------------------------------- Set Sources -----------------------------------------------------
 
-set(private_include_dirs
-    "${kernel_dir}/portable/${arch}/include/freertos"
-    "${kernel_dir}/portable/${arch}"
-    "${kernel_dir}/include/freertos"   # FreeRTOS headers via #include "xxx.h"
-    "esp_additions"                    # For include "freertos_tasks_c_additions.h"
-    .)
+# Add common source files
+list(APPEND srcs
+    "heap_idf.c")
 
-set(private_requirements "")
+if((arch STREQUAL "xtensa") OR (arch STREQUAL "riscv"))
+    list(APPEND srcs
+        "app_startup.c"
+        "port_common.c"
+        "port_systick.c")
+endif()
 
-if(${target} STREQUAL "linux")
-    list(APPEND srcs "${kernel_dir}/portable/${arch}/utils/wait_for_event.c")
-    if(NOT CONFIG_FREERTOS_SMP)
-        list(APPEND srcs "${kernel_dir}/portable/${arch}/port_idf.c")
+# Add FreeRTOS Kernel source files
+list(APPEND srcs
+    "${kernel_impl}/list.c"
+    "${kernel_impl}/queue.c"
+    "${kernel_impl}/tasks.c"
+    "${kernel_impl}/timers.c"
+    "${kernel_impl}/croutine.c"
+    "${kernel_impl}/event_groups.c"
+    "${kernel_impl}/stream_buffer.c")
+
+# Add port source files
+list(APPEND srcs
+    "${kernel_impl}/portable/${arch}/port.c")
+
+if(arch STREQUAL "linux")
+    list(APPEND srcs
+        "${kernel_impl}/portable/${arch}/utils/wait_for_event.c")
+    if(kernel_impl STREQUAL "FreeRTOS-Kernel")
+        list(APPEND srcs
+            "${kernel_impl}/portable/${arch}/port_idf.c")
     endif()
+else()
+    list(APPEND srcs
+        "${kernel_impl}/portable/${arch}/portasm.S")
+endif()
+
+if(arch STREQUAL "xtensa")
+    list(APPEND srcs
+        "${kernel_impl}/portable/${arch}/xtensa_init.c"
+        "${kernel_impl}/portable/${arch}/xtensa_overlay_os_hook.c")
+endif()
 
-    # Check if we need to address the FreeRTOS EINTR coexistence with linux system calls
-    # if we're building without lwIP, we need to use linux system select which will receive
-    # EINTR event on every FreeRTOS interrupt, we workaround this problem by wrapping select()
-    # to bypass and silence the EINTR events
+# Add ESP-additions source files
+list(APPEND srcs
+    "esp_additions/idf_additions.c")
+
+if(kernel_impl STREQUAL "FreeRTOS-Kernel")
+    list(APPEND srcs
+        "esp_additions/freertos_v8_compat.c")
+endif()
+
+if(arch STREQUAL "linux")
+    # Check if we need to address the FreeRTOS EINTR coexistence with linux system calls if we're building without
+    # lwIP, we need to use linux system select which will receive EINTR event on every FreeRTOS interrupt, we
+    # workaround this problem by wrapping select() to bypass and silence the EINTR events
     set(BYPASS_EINTR_ISSUE 0)
     idf_build_get_property(build_components BUILD_COMPONENTS)
     if(NOT "lwip" IN_LIST build_components)
         set(BYPASS_EINTR_ISSUE 1)
-        list(APPEND srcs esp_additions/arch/linux/FreeRTOSSimulator_wrappers.c)
+        list(APPEND srcs "esp_additions/FreeRTOSSimulator_wrappers.c")
     endif()
+endif()
 
-else()
-    list(APPEND srcs
-        "app_startup.c"
-        "FreeRTOS-openocd.c"
-        "port_common.c"
-        "port_systick.c"
-        "${kernel_dir}/portable/${arch}/portasm.S")
+# ------------------------------------------------ Set Public Includes -------------------------------------------------
 
-    if(CONFIG_FREERTOS_SMP)
-        set(ldfragments linker_smp.lf linker_common.lf)
-    else()
-        list(APPEND srcs
-            "esp_additions/freertos_v8_compat.c")
+# Add common public include directories
+list(APPEND include_dirs
+    "config/include"                # For `#include "freertos/FreeRTOSConfig.h"`
+    "config/include/freertos"       # For `#include "FreeRTOSConfig.h"`
+    "config/${arch}/include")       # For `#include "freertos/FreeRTOSConfig_arch.h"`
 
-        set(ldfragments linker.lf linker_common.lf)
-    endif()
+# Add FreeRTOS Kernel public include directories
+list(APPEND include_dirs
+    "${kernel_impl}/include")       # FreeRTOS headers via `#include "freertos/xxx.h"`
+
+# Add port public include directories
+list(APPEND include_dirs
+    "${kernel_impl}/portable/${arch}/include"               # For port headers via `#include "freertos/...h"`
+    "${kernel_impl}/portable/${arch}/include/freertos")     # For port headers via `#include "...h"`
+
+# Add ESP-additions public include directories
+list(APPEND include_dirs
+    "esp_additions/include")        # For ESP-addition headers via
+                                    #   - `#include "freertos/...h"`
+                                    #   - `#include "esp_private/...h"`
 
-    list(APPEND private_requirements soc esp_pm)
+# ----------------------------------------------- Set Private Includes -------------------------------------------------
+
+# Add common private include directories
+if((arch STREQUAL "xtensa") OR (arch STREQUAL "riscv"))
+    list(APPEND private_include_dirs
+        ".")                        # For `#include "port_systick.h"
 endif()
 
-if(CONFIG_IDF_TARGET_ARCH_XTENSA)
-    list(APPEND srcs
-        "${kernel_dir}/portable/${arch}/xtensa_init.c"
-        "${kernel_dir}/portable/${arch}/xtensa_overlay_os_hook.c")
+# Add FreeRTOS Kernel private include directories
+list(APPEND private_include_dirs
+    "${kernel_impl}/include/freertos")      # FreeRTOS headers via `#include "xxx.h"`
+
+# Add port private include directories
+if(arch STREQUAL "linux")
+    list(APPEND private_include_dirs
+        "${kernel_impl}/portable/${arch}/") # Linux port `#include "utils/wait_for_event.h"`
+endif()
+
+# Add ESP-additions private include directories
+list(APPEND private_include_dirs
+    "esp_additions")                # For `include "freertos_tasks_c_additions.h"`
+
+# ------------------------------------------------------- Misc ---------------------------------------------------------
 
-    list(APPEND include_dirs
-         "${kernel_dir}/portable/xtensa/include/freertos")  # For #include "xtensa_...h"
+# Add linker fragments
+list(APPEND ldfragments
+    "linker_common.lf")
+
+if((arch STREQUAL "xtensa") OR (arch STREQUAL "riscv"))
+    if(kernel_impl STREQUAL "FreeRTOS-Kernel-SMP")
+        list(APPEND ldfragments
+            "linker_smp.lf")
+    else()
+        list(APPEND ldfragments
+            "linker.lf")
+    endif()
 endif()
 
+# ------------------------------------------------ Register Component --------------------------------------------------
 
-idf_component_register(SRCS "${srcs}"
+idf_component_register(SRCS ${srcs}
                     INCLUDE_DIRS ${include_dirs}
-                    PRIV_INCLUDE_DIRS  ${private_include_dirs}
-                    LDFRAGMENTS "${ldfragments}"
-                    PRIV_REQUIRES "${private_requirements}")
+                    PRIV_INCLUDE_DIRS ${private_include_dirs}
+                    LDFRAGMENTS ${ldfragments}
+                    PRIV_REQUIRES ${private_requirements})
 
-if(${target} STREQUAL "linux")
+if(arch STREQUAL "linux")
     target_compile_definitions(${COMPONENT_LIB} PUBLIC "projCOVERAGE_TEST=0")
     target_link_libraries(${COMPONENT_LIB} PUBLIC pthread)
     if(BYPASS_EINTR_ISSUE)
@@ -117,12 +192,10 @@ if(${target} STREQUAL "linux")
 else()
     idf_component_get_property(COMPONENT_DIR freertos COMPONENT_DIR)
 
-    idf_component_set_property(freertos ORIG_INCLUDE_PATH "${COMPONENT_DIR}/${kernel_dir}/include/freertos/")
+    idf_component_set_property(freertos ORIG_INCLUDE_PATH "${COMPONENT_DIR}/${kernel_impl}/include/freertos/")
 
     if(CONFIG_FREERTOS_DEBUG_OCDAWARE)
-        target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--undefined=uxTopUsedPriority") #will be removed
         target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--undefined=FreeRTOS_openocd_params")
-        idf_build_set_property(COMPILE_OPTIONS "-DconfigENABLE_FREERTOS_DEBUG_OCDAWARE=1" APPEND)
     endif()
 
     set_source_files_properties(
@@ -168,6 +241,11 @@ else()
         idf_component_optional_requires(PRIVATE esp_psram)
     endif()
 
+    if(CONFIG_PM_TRACE)
+        # esp_pm is required by port_systick.c for tracing
+        idf_component_optional_requires(PRIVATE esp_pm)
+    endif()
+
     if(CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP AND CONFIG_FREERTOS_SMP)
         target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=vPortCleanUpTCB")
     endif()

components/freertos/FreeRTOS-Kernel-SMP/include/freertos/task.h

@@ -3321,7 +3321,7 @@ core 0 during startup.
 void vTaskStartSchedulerOtherCores( void );
 #endif // configNUM_CORES > 1
 
-#include "idf_additions.h"
+#include "freertos/idf_additions.h"
 
 #endif //ESP_PLATFORM
 

components/freertos/FreeRTOS-openocd.c

@@ -1,29 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/*
- * Since at least FreeRTOS V7.5.3 uxTopUsedPriority is no longer
- * present in the kernel, so it has to be supplied by other means for
- * OpenOCD's threads awareness.
- *
- * Add this file to your project, and, if you're using --gc-sections,
- * ``--undefined=uxTopUsedPriority'' (or
- * ``-Wl,--undefined=uxTopUsedPriority'' when using gcc for final
- * linking) to your LDFLAGS; same with all the other symbols you need.
- */
-
-#include "FreeRTOS.h"
-#include "sdkconfig.h"
-
-#ifdef __GNUC__
-#define USED __attribute__((used))
-#else
-#define USED
-#endif
-
-#ifdef CONFIG_FREERTOS_DEBUG_OCDAWARE
-const int USED uxTopUsedPriority = configMAX_PRIORITIES - 1;  //will be removed
-#endif

components/freertos/esp_additions/freertos_tasks_c_additions.h

@@ -7,7 +7,7 @@
 #pragma once
 
 #include "sdkconfig.h"
-#include "idf_additions.h"
+#include "freertos/idf_additions.h"
 #include "esp_private/freertos_idf_additions_priv.h"
 
 /**
@@ -54,7 +54,7 @@ struct _reent *__getreent(void)
 
 #if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
 
-#include "task_snapshot.h"
+#include "freertos/task_snapshot.h"
 
 /**
  * @brief List of all task lists in FreeRTOS
@@ -240,7 +240,7 @@ UBaseType_t uxTaskGetSnapshotAll( TaskSnapshot_t * const pxTaskSnapshotArray, co
  *
  * ------------------------------------------------------------------------------------------------------------------ */
 
-#if ( configENABLE_FREERTOS_DEBUG_OCDAWARE == 1 )
+#if CONFIG_FREERTOS_DEBUG_OCDAWARE
 
 /**
  * Debug param indexes. DO NOT change the order. OpenOCD uses the same indexes
@@ -270,7 +270,7 @@ const DRAM_ATTR uint8_t FreeRTOS_openocd_params[ESP_FREERTOS_DEBUG_TABLE_END]  =
     offsetof(TCB_t, pcTaskName),        /* thread_name_offset; */
 };
 
-#endif // configENABLE_FREERTOS_DEBUG_OCDAWARE == 1
+#endif // CONFIG_FREERTOS_DEBUG_OCDAWARE
 
 /* -------------------------------------------- FreeRTOS IDF API Additions ---------------------------------------------
  * FreeRTOS related API that were added by IDF

components/freertos/linker_common.lf

@@ -46,12 +46,6 @@ entries:
     # ------------------------------------------------------------------------------------------------------------------
     app_startup (default)           # Place functions (but not Data and BSS) to flash
 
-    # ------------------------------------------------------------------------------------------------------------------
-    # FreeRTOS-openocd.c
-    # Placement Rules: All functions/data in internal RAM as they are called/used by OpenOCD
-    # ------------------------------------------------------------------------------------------------------------------
-    FreeRTOS-openocd (noflash)
-
     # ------------------------------------------------------------------------------------------------------------------
     # heap_idf.c
     # Placement Rules:

tools/mocks/freertos/CMakeLists.txt

@@ -8,9 +8,10 @@ set(kernel_dir "${original_freertos_dir}/FreeRTOS-Kernel")
 
 set(include_dirs
     "${kernel_dir}/include"
+    "${original_freertos_dir}/config/include" # For "freertos/FreeRTOSConfig.h"
+    "${original_freertos_dir}/config/include/freertos" # For "FreeRTOSConfig.h"
+    "${original_freertos_dir}/config/linux/include" # For "freertos/FreeRTOSConfig_arch.h"
     "${original_freertos_dir}/esp_additions/include"
-    "${original_freertos_dir}/esp_additions/include/freertos"
-    "${original_freertos_dir}/esp_additions/arch/linux/include" # For "freertos/FreeRTOSConfig_arch.h"
     "${kernel_dir}/portable/linux/include" # For "freertos/portmacro.h"
     "${kernel_dir}/include/freertos" # this is due to the way includes are generated in CMock (without freertos prefix)
 )