xtensa: Move Xtensa RTOS porting layer files to xtensa component

When porting an RTOS to the Xtensa architecture, there are a few files that
are common to all Xtensa RTOS ports. These files form the Xtensa RTOS porting
layer (e.g., "xtensa_vectors.S", "xtensa_context.S"). An Xtensa RTOS port is
expected to provide an RTOS specific "xtensa_rtos.h" header to interface with
the Xtensa RTOS porting layer.

Previously, the Xtensa RTOS porting layer files were placed in the FreeRTOS
component. This commit does the following:

1. Moves the Xtensa RTOS porting layer files from the `freertos` component to
the `xtensa` component. The following files were moved:

    - xtensa_asm_utils.h
    - xtensa_context.S
    - xtensa_loadstore_handler.S
    - xtensa_vectors.S

2. Refactored xtensa component include paths to separate Xtensa RTOS porting
layer headers.

- Xtensa HAL headers included via `#include <xtensa/...h>`
- Xtensa RTOS porting layer headers included via `#include <...h>`

Note: The xtensa files in the Amazon SMP FreeRTOS port are not moved/deleted in
this commit to ensure the moved files retain a clean diff history.

components/freertos/CMakeLists.txt

@@ -82,17 +82,14 @@ endif()
 
 if(CONFIG_IDF_TARGET_ARCH_XTENSA)
     list(APPEND srcs
-        "${kernel_dir}/portable/${arch}/xtensa_context.S"
         "${kernel_dir}/portable/${arch}/xtensa_init.c"
-        "${kernel_dir}/portable/${arch}/xtensa_overlay_os_hook.c"
-        "${kernel_dir}/portable/${arch}/xtensa_vectors.S")
+        "${kernel_dir}/portable/${arch}/xtensa_overlay_os_hook.c")
+
+    list(APPEND include_dirs
+         "${kernel_dir}/portable/xtensa/include/freertos")  # For #include "xtensa_...h"
 endif()
 
 
-if(CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY)
-    list(APPEND srcs "${kernel_dir}/portable/xtensa/xtensa_loadstore_handler.S")
-endif()
-
 idf_component_register(SRCS "${srcs}"
                     INCLUDE_DIRS ${include_dirs}
                     PRIV_INCLUDE_DIRS  ${private_include_dirs}

components/freertos/FreeRTOS-Kernel/portable/xtensa/include/freertos/xtensa_api.h

@@ -1,2 +0,0 @@
-/* This header file has been moved, please include <xtensa/xtensa_api.h> in future */
-#include <xtensa/xtensa_api.h>

components/freertos/FreeRTOS-Kernel/portable/xtensa/include/freertos/xtensa_context.h

@@ -1,2 +0,0 @@
-/* This header file has been moved, please include <xtensa/xtensa_context.h> in future */
-#include <xtensa/xtensa_context.h>

components/freertos/esp_additions/arch/xtensa/include/freertos/FreeRTOSConfig_arch.h

@@ -11,7 +11,7 @@
 #include "sdkconfig.h"
 
 /* Required for configuration-dependent settings. */
-#include "freertos/xtensa_config.h"
+#include "xtensa_config.h"
 
 /* -------------------------------------------- Xtensa Additional Config  ----------------------------------------------
  * - Provide Xtensa definitions usually given by -D option when building with xt-make (see readme_xtensa.txt)

components/xtensa/CMakeLists.txt

@@ -1,3 +1,20 @@
+# Xtensa Component Architecture
+#
+# The ESP-IDF Xtesna component contains two major features:
+# - The Xtensa HAL
+# - The Xtensa RTOS porting layer
+#
+# The Xtensa HAL provides various macros/functions regarding the Xtensa processor's configuration and extensions (see
+# "sys_sw_rm.pdf 3.1"). The Xtensa HAL...
+#   - is packaged as a library ("libxt_hal.a") in the ESP-IDF Xtensa component
+#   - expects `#include <xtensa/...h>` as the include path to the Xtensa HAL's headers
+#
+# The Xtensa RTOS Porting Layer is a set of helper functions and interrupt vectors that act as a basis of an RTOS port.
+# The porting layer sources files are OS agnostic, thus are common across multiple Xtensa RTOS ports (e.g., FreeRTOS,
+# ThreadX). The Xtensa RTOS Porting Layer...
+#   - interfaces with an RTOS port via the "xtensa_rtos.h" header provided by the RTOS port
+#   - expected `#include <...h>` as the incldue path to the porting layer's headers
+
 idf_build_get_property(target IDF_TARGET)
 idf_build_get_property(arch IDF_TARGET_ARCH)
 
@@ -5,14 +22,37 @@ if(NOT "${arch}" STREQUAL "xtensa")
     return()
 endif()
 
-set(srcs "eri.c" "xt_trax.c")
+set(include_dirs
+    "${target}/include"         # - Add include path for target specific Xtensa HAL headers (`#include <xtensa/...h>`)
+    "include"                   # - Add include path for...
+                                #       - common Xtensa HAL headers (`#include <xtensa/...h>`)
+                                #       - Xtensa RTOS porting layer headers (`#include <...h>`)
+    "deprecated_include")       # - For deprecated include paths (see IDF-7230)
 
+set(srcs
+    "eri.c"
+    "xt_trax.c")
+
+# Minor optimization. The following sources are excluded from the bootloader as they are not required by the bootloader.
+#
+# - ROM provides a copy of basic exception vectors (e.g., _UserExceptionVector and _WindowOverflow8)
+# - The bootloader doesn't register any interrupts, thus...
+#   - the "xtensa_api.h" isn't used
+#   - the "xtensa_context.h" functions aren't used as there are no interrupts to trigger a context switch
 if(NOT BOOTLOADER_BUILD)
-    list(APPEND srcs "xtensa_intr.c" "xtensa_intr_asm.S")
+    list(APPEND srcs
+        "xtensa_context.S"
+        "xtensa_intr_asm.S"
+        "xtensa_intr.c"
+        "xtensa_vectors.S")
+
+    if(CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY)
+        list(APPEND srcs "xtensa_loadstore_handler.S")
+    endif()
 endif()
 
 idf_component_register(SRCS ${srcs}
-                    INCLUDE_DIRS include ${target}/include
+                    INCLUDE_DIRS ${include_dirs}
                     LDFRAGMENTS linker.lf)
 
 target_link_libraries(${COMPONENT_LIB} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/${target}/libxt_hal.a")

components/xtensa/deprecated_include/freertos/xtensa_api.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <freertos/xtensa_api.h>` is deprecated. Please use `#include <xtensa_api.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa/xtensa_api.h>

components/xtensa/deprecated_include/freertos/xtensa_context.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <freertos/xtensa_context.h>` is deprecated. Please use `#include <xtensa_context.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa/xtensa_context.h>

components/xtensa/deprecated_include/freertos/xtensa_timer.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <freertos/xtensa_timer.h>` is deprecated. Please use `#include <xtensa_timer.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa_timer.h>

components/xtensa/deprecated_include/xtensa/xtensa_api.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <xtensa/xtensa_api.h>` is deprecated. Please use `#include <xtensa_api.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa_api.h>

components/xtensa/deprecated_include/xtensa/xtensa_context.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <xtensa/xtensa_context.h>` is deprecated. Please use `#include <xtensa_context.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa_context.h>

components/xtensa/deprecated_include/xtensa/xtensa_timer.h

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/* This header file has been moved, thus `#include <xtensa/xtensa_timer.h>` is deprecated. Please use `#include <xtensa_timer.h>` instead */
+/* Todo: IDF-7230 */
+#include <xtensa_timer.h>

components/xtensa/include/xtensa_api.h

@@ -1,3 +1,10 @@
+/*
+ * SPDX-FileCopyrightText: 2015-2019 Cadence Design Systems, Inc.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * SPDX-FileContributor: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ */
 /*******************************************************************************
 Copyright (c) 2006-2015 Cadence Design Systems Inc.
 

components/xtensa/include/xtensa_context.h

@@ -1,4 +1,10 @@
-
+/*
+ * SPDX-FileCopyrightText: 2015-2019 Cadence Design Systems, Inc.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * SPDX-FileContributor: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ */
 /*
  * Copyright (c) 2015-2019 Cadence Design Systems, Inc.
  *

components/xtensa/include/xtensa_timer.h

@@ -56,7 +56,6 @@
 
 #include    "xtensa_rtos.h"     /* in case this wasn't included directly */
 
-#include    "freertos/FreeRTOSConfig.h"
 
 /*
 Select timer to use for periodic tick, and determine its interrupt number

components/xtensa/linker.lf

@@ -1,8 +1,9 @@
 [mapping:xtensa]
 archive: libxtensa.a
 entries:
-    eri (noflash_text)
-    xtensa_intr_asm (noflash_text)
+    * (noflash_text)            # Default all functions to IRAM
+    xt_trax (default)
+    xtensa_intr (default)
 
 [mapping:xt_hal]
 archive: libxt_hal.a