chore: import upstream snapshot with attribution

examples/custom_bootloader/bootloader_hooks/CMakeLists.txt

@@ -0,0 +1,10 @@
+# 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)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(main)

examples/custom_bootloader/bootloader_hooks/README.md

@@ -0,0 +1,60 @@
+| 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 hooks
+
+(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 hooks to the 2nd stage bootloader.
+
+## 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 output should be as followed:
+```
+I (24) HOOK: This hook is called BEFORE bootloader initialization
+I (37) boot: [...]
+[...]
+I (60) HOOK: This hook is called AFTER bootloader initialization
+```
+
+And finally the application will start and show the message:
+```
+User application is loaded and running.
+```
+
+## Organisation of this example
+
+This project contains an application, in the `main` directory that represents a user program.
+It also contains a `bootloader_components` that, as it name states, contains a component compiled and linked with the bootloader.
+
+Below is a short explanation of files in the project folder.
+
+```
+├── CMakeLists.txt
+├── main
+│   ├── CMakeLists.txt
+│   └── main.c                 User application
+├── bootloader_components
+│   └── my_boot_hooks
+│       ├── CMakeLists.txt   
+│       └── hooks.c            Implementation of the hooks to execute on boot
+└── README.md                  This is the file you are currently reading
+```
+Bootloader hooks are **not** supported in legacy `make` build system. They are only supported with `CMake` build system.
+
+## Note about including weak symbols
+
+The components in ESP-IDF are compiled as static libraries. Moreover, the bootloaders' hooks are declared as `weak`. Thus, when
+defining hooks for the bootloader, we **must** tell the compiler to always include our library (`my_boot_hooks`) in the link process.
+To achieve this, we need to define an extra symbol: `bootloader_hooks_include`. In our case, this symbol is a function defined in
+`bootloader_components/my_boot_hooks/hooks.c`. This will make the linker include all the symbols contained in that file.

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

@@ -0,0 +1,8 @@
+idf_component_register(SRCS "hooks.c")
+
+# 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_hooks/bootloader_components/my_boot_hooks/hooks.c

@@ -0,0 +1,20 @@
+#include "esp_log.h"
+
+/* Function used to tell the linker to include this file
+ * with all its symbols.
+ */
+void bootloader_hooks_include(void){
+}
+
+
+void bootloader_before_init(void) {
+    /* Keep in mind that a lot of functions cannot be called from here
+     * as system initialization has not been performed yet, including
+     * BSS, SPI flash, or memory protection.
+     */
+    ESP_LOGI("HOOK", "This hook is called BEFORE bootloader initialization");
+}
+
+void bootloader_after_init(void) {
+    ESP_LOGI("HOOK", "This hook is called AFTER bootloader initialization");
+}

examples/custom_bootloader/bootloader_hooks/main/CMakeLists.txt

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

examples/custom_bootloader/bootloader_hooks/main/bootloader_hooks_example_main.c

@@ -0,0 +1,11 @@
+#include <stdio.h>
+
+void app_main(void)
+{
+    /**
+     * Nothing special is done here, everything interesting in this example
+     * is done in the custom bootloader code, located in:
+     * `bootloader_components/my_boot_hooks/hooks.c`
+     */
+    printf("User application is loaded and running.\n");
+}

examples/custom_bootloader/bootloader_hooks/pytest_custom_bootloader_hooks.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2021-2026 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
+@pytest.mark.parametrize(
+    'config',
+    [
+        'default',
+        # log_v2 routes ESP_LOG through esp_rom_output_to_channels() -> _putc2. This config
+        # verifies that logging works correctly in bootloader hooks (before BSS is cleared),
+        # where _putc2 must be initialized to a safe noop rather than left as NULL/garbage.
+        'log_v2',
+    ],
+    indirect=True,
+)
+@idf_parametrize('target', ['esp32s3', 'esp32c3'], indirect=['target'])
+def test_custom_bootloader_hooks_example(dut: Dut) -> None:
+    # Expect to read both hooks messages
+    dut.expect_exact('This hook is called BEFORE bootloader initialization')
+    dut.expect_exact('This hook is called AFTER bootloader initialization')

examples/custom_bootloader/bootloader_hooks/sdkconfig.ci.default

@@ -0,0 +1 @@
+# This is left intentionally blank. It inherits all configurations from sdkconfig.defaults.

examples/custom_bootloader/bootloader_hooks/sdkconfig.ci.log_v2

@@ -0,0 +1,2 @@
+CONFIG_LOG_VERSION_2=y
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y