chore: import upstream snapshot with attribution

examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt

@@ -0,0 +1,39 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+# The bootloader always uses the "bootloader_components" folder name
+# as the project-local search path for bootloader components added to the bootloader build.
+#
+# Use BOOTLOADER_EXTRA_COMPONENT_DIRS when bootloader components already lives somewhere else,
+# for example in a shared components directory or in a component reused by several projects.
+# The path may point to a directory containing multiple components.
+idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_bootloader_components" APPEND)
+
+# The path may also point directly to a single component when adding a wrapper directory
+# just for the bootloader build would be unnecessary.
+idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_component4" APPEND)
+idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_component5" APPEND)
+
+# A shared extra directory may contain components that are not needed in this bootloader build.
+# Ignore them by component name, including direct single-component paths.
+set(BOOTLOADER_IGNORE_EXTRA_COMPONENT extra_component3 extra_component5)
+
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+
+project(main)
+
+# Check which extra bootloader components are included and which ones are ignored.
+add_custom_target(check_bootloader_extra_components ALL
+    COMMAND ${CMAKE_COMMAND}
+        -DPROJECT_DESCRIPTION=${CMAKE_BINARY_DIR}/bootloader/project_description.json
+        -DEXPECTED_COMPONENTS=extra_component1,extra_component2,extra_component4
+        -DIGNORED_COMPONENTS=extra_component3,extra_component5
+        -P ${CMAKE_CURRENT_LIST_DIR}/check_bootloader_component.cmake
+    DEPENDS bootloader
+    VERBATIM)

examples/custom_bootloader/bootloader_extra_dir/README.md

@@ -0,0 +1,72 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
+
+# Bootloader extra component
+
+(See the README.md file in the upper level for more information about bootloader examples.)
+
+The purpose of this example is to show how to add bootloader components that are not placed in the conventional `bootloader_components` directory.
+
+The bootloader always uses the `bootloader_components` folder name as the project-local search path for bootloader components. Use this folder for bootloader-specific code that belongs to the project, such as hooks or overrides.
+
+Use the `BOOTLOADER_EXTRA_COMPONENT_DIRS` property when bootloader components already live somewhere else, for example in a shared components directory or in a component reused by several projects. Each path can point either to a directory containing multiple components or directly to a single component. If the extra location contains components that are not needed in a particular bootloader build, list them by component name in `BOOTLOADER_IGNORE_EXTRA_COMPONENT`.
+
+## Usage of this example:
+
+Simply compile it:
+```
+idf.py build
+```
+
+Then flash it and open the monitor with the following command:
+```
+idf.py flash monitor
+```
+
+If everything went well, the bootloader should output the following message:
+```
+I (60) EXTRA: This function is called from an extra component
+```
+
+And finally the application will start and show the message:
+```
+User application is loaded and running.
+```
+
+## Organization of this example
+
+This project contains a `main` directory that represents an application. It also has a `bootloader_components` directory with `my_boot_hooks`, a bootloader-specific hook component that belongs to this project.
+
+The `extra_bootloader_components/` directory demonstrates an extra path that contains several components. `extra_component1` is required by `my_boot_hooks`, while `extra_component2` is included directly from `BOOTLOADER_EXTRA_COMPONENT_DIRS` without being required by another component. `extra_component3` is present in the same directory but is excluded from this bootloader build with `BOOTLOADER_IGNORE_EXTRA_COMPONENT`.
+
+The `extra_component4/` and `extra_component5/` directories demonstrate extra paths that point directly to individual components. `extra_component4` is included directly, while `extra_component5` is excluded with `BOOTLOADER_IGNORE_EXTRA_COMPONENT`.
+
+Below is a short explanation of files in the project folder.
+
+```
+├── CMakeLists.txt             Defines the `BOOTLOADER_EXTRA_COMPONENT_DIRS` property
+├── main
+│   ├── CMakeLists.txt
+│   └── main.c                 User application
+├── bootloader_components
+│   └── my_boot_hooks
+│       ├── CMakeLists.txt
+│       └── hooks.c            Implementation of the hooks to execute on boot
+├── extra_bootloader_components
+│   ├── extra_component1
+│   │   ├── CMakeLists.txt
+│   │   └── extra_component1.c                 Implementation of the extra component
+│   ├── extra_component2
+│   │   ├── CMakeLists.txt
+│   │   └── extra_component2.c                 Implementation of the 2nd extra component
+│   └── extra_component3
+│       ├── CMakeLists.txt
+│       └── extra_component3.c                 Extra component excluded from this bootloader build
+├── extra_component4
+│   ├── CMakeLists.txt
+│   └── extra_component4.c                     Extra component included directly
+├── extra_component5
+│   ├── CMakeLists.txt
+│   └── extra_component5.c                     Extra component excluded directly
+└── README.md                  This is the file you are currently reading
+```

examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/CMakeLists.txt

@@ -0,0 +1,9 @@
+idf_component_register(SRCS "hooks.c"
+                       REQUIRES extra_component1)
+
+# We need to force GCC to integrate this static library into the
+# bootloader link. Indeed, by default, as the hooks in the bootloader are weak,
+# the linker would just ignore the symbols in the extra. (i.e. not strictly
+# required)
+# To do so, we need to define the symbol (function) `bootloader_hooks_include`
+# within hooks.c source file.

examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/hooks.c

@@ -0,0 +1,17 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+extern void bootloader_extra_dir_function(void);
+
+/* Function used to tell the linker to include this file
+ * with all its symbols.
+ */
+void bootloader_hooks_include(void){
+}
+
+void bootloader_after_init(void) {
+    bootloader_extra_dir_function();
+}

examples/custom_bootloader/bootloader_extra_dir/check_bootloader_component.cmake

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+
+file(READ "${PROJECT_DESCRIPTION}" project_description)
+string(JSON component_count LENGTH "${project_description}" build_components)
+
+set(build_components)
+if(component_count GREATER 0)
+    math(EXPR last_component_index "${component_count} - 1")
+    foreach(component_index RANGE 0 ${last_component_index})
+        string(JSON component_name GET "${project_description}" build_components ${component_index})
+        if(NOT component_name STREQUAL "")
+            list(APPEND build_components "${component_name}")
+        endif()
+    endforeach()
+endif()
+
+string(REPLACE "," ";" expected_components "${EXPECTED_COMPONENTS}")
+foreach(expected_component ${expected_components})
+    list(FIND build_components "${expected_component}" component_index)
+    if(component_index EQUAL -1)
+        message(FATAL_ERROR "${expected_component} was not included in the bootloader build")
+    endif()
+endforeach()
+
+string(REPLACE "," ";" ignored_components "${IGNORED_COMPONENTS}")
+foreach(ignored_component ${ignored_components})
+    list(FIND build_components "${ignored_component}" component_index)
+    if(NOT component_index EQUAL -1)
+        message(FATAL_ERROR "${ignored_component} was included in the bootloader build")
+    endif()
+endforeach()

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component1/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "extra_component1.c")

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component1/extra_component1.c

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include "esp_log.h"
+
+void bootloader_extra_dir_function(void)
+{
+    ESP_LOGI("EXTRA", "This function is called from an extra component");
+}

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component2/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "extra_component2.c")

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component2/extra_component2.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+void bootloader_extra_component2_marker(void)
+{
+}

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component3/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "extra_component3.c")

examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component3/extra_component3.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+void bootloader_extra_component3_marker(void)
+{
+}

examples/custom_bootloader/bootloader_extra_dir/extra_component4/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "extra_component4.c")

examples/custom_bootloader/bootloader_extra_dir/extra_component4/extra_component4.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+void bootloader_extra_component4_marker(void)
+{
+}

examples/custom_bootloader/bootloader_extra_dir/extra_component5/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "extra_component5.c")

examples/custom_bootloader/bootloader_extra_dir/extra_component5/extra_component5.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+void bootloader_extra_component5_marker(void)
+{
+}

examples/custom_bootloader/bootloader_extra_dir/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "bootloader_hooks_example_main.c"
+                    INCLUDE_DIRS ".")

examples/custom_bootloader/bootloader_extra_dir/main/bootloader_hooks_example_main.c

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include <stdio.h>
+
+void app_main(void)
+{
+    printf("User application is loaded and running.\n");
+}

examples/custom_bootloader/bootloader_extra_dir/pytest_bootloader_extra_dir.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import pytest
+from pytest_embedded import Dut
+from pytest_embedded_idf.utils import idf_parametrize
+
+
+@pytest.mark.generic
+@idf_parametrize('target', ['esp32s3', 'esp32c3'], indirect=['target'])
+def test_custom_bootloader_extra_component(dut: Dut) -> None:
+    dut.expect_exact('This function is called from an extra component')