feat(esp_partition): Add esp_partition_flash_binary() CMake function

Add a new CMake function esp_partition_flash_binary() that provides a
unified API for registering partition data binaries to be flashed. It
replaces the direct esptool_py_flash_target calls scattered across
components (spiffs, fatfs, nvs_flash) with a single function that:

- Resolves partition offset from the partition table automatically
- Determines encryption requirements (auto-detect or ALWAYS_PLAINTEXT)
- Creates per-partition flash targets (e.g. idf.py <partition>-flash)
- Optionally includes the binary in `idf.py flash` via FLASH_IN_PROJECT

On the linux target, the function registers binaries for pre-loading
into the emulated flash. A build-time manifest (linux_flash_data.txt)
is generated via file(GENERATE), and partition_linux.c reads it at
runtime to copy each binary into the memory-mapped flash buffer at
the correct offset.

The partition_ops example is updated to use the new function and
includes a custom_partition with pre-built data to demonstrate the
full workflow, including on the linux target.

examples/storage/nvs/nvs_bootloader/main/CMakeLists.txt

@@ -5,9 +5,9 @@ if(NOT CONFIG_NVS_ENCRYPTION)
     nvs_create_partition_image(nvs ../nvs_data.csv FLASH_IN_PROJECT)
 else()
     if(CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC)
-        esptool_py_flash_to_partition(flash "nvs_key" ${PROJECT_DIR}/main/encryption_keys.bin)
-        esptool_py_flash_to_partition(flash "nvs" ${PROJECT_DIR}/main/nvs_encrypted.bin)
+        esp_partition_register_target("nvs_key" ${PROJECT_DIR}/main/encryption_keys.bin FLASH_IN_PROJECT)
+        esp_partition_register_target("nvs" ${PROJECT_DIR}/main/nvs_encrypted.bin FLASH_IN_PROJECT)
     else()  # NVS Encryption using HMAC (CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC)
-        esptool_py_flash_to_partition(flash "nvs" ${PROJECT_DIR}/main/nvs_encrypted_hmac.bin)
+        esp_partition_register_target("nvs" ${PROJECT_DIR}/main/nvs_encrypted_hmac.bin FLASH_IN_PROJECT)
     endif()
 endif()

examples/storage/partition_api/partition_ops/README.md

@@ -18,7 +18,8 @@ and read back using `esp_partition_read`, verifying the read and written data ma
 I (588) example: Written data: ESP-IDF Partition Operations Example (Read, Erase, Write)
 I (588) example: Read data: ESP-IDF Partition Operations Example (Read, Erase, Write)
 I (638) example: Erased data
-I (638) example: Example end
+I (693) example: Read data from custom partition: abcdef123456
+I (693) example: Example end
 ```
 
 # Others

examples/storage/partition_api/partition_ops/create_custom_partition.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+"""Create a 4kiB binary file with 'abcdef123456' at the start, rest filled with zeros."""
+
+import argparse
+import os
+
+FILE_NAME = 'custom_partition.bin'
+FILE_SIZE = 4 * 1024  # 4 kiB
+HEADER = b'abcdef123456'
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Generate a custom partition binary file.')
+    parser.add_argument(
+        'output_path',
+        nargs='?',
+        default=None,
+        help='Path for the output binary file. Defaults to custom_partition.bin in the script directory.',
+    )
+    args = parser.parse_args()
+
+    if args.output_path:
+        output_path = args.output_path
+    else:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        output_path = os.path.join(script_dir, FILE_NAME)
+
+    data = HEADER + b'\x00' * (FILE_SIZE - len(HEADER))
+
+    with open(output_path, 'wb') as f:
+        f.write(data)
+
+    print(f'Created {output_path} ({FILE_SIZE} bytes)')
+
+
+if __name__ == '__main__':
+    main()

examples/storage/partition_api/partition_ops/main/CMakeLists.txt

@@ -1,3 +1,21 @@
 idf_component_register(SRCS "main.c"
                     INCLUDE_DIRS "."
                     REQUIRES esp_partition)
+
+set(partition "custom_partition")
+set(image_file ${CMAKE_BINARY_DIR}/custom_partition.bin)
+set(custom_partition_script_py ${CMAKE_CURRENT_SOURCE_DIR}/../create_custom_partition.py)
+
+# Generate custom_partition.bin using the Python script (output to build directory)
+add_custom_command(
+    OUTPUT ${image_file}
+    COMMAND ${PYTHON} ${custom_partition_script_py} ${image_file}
+    DEPENDS ${custom_partition_script_py}
+    COMMENT "Generating custom_partition.bin"
+)
+add_custom_target(generate_custom_partition ALL DEPENDS ${image_file})
+
+# Flash the generated binary to the partition named "custom_partition"
+# (build target depends on generate_custom_partition to ensure the binary is created first, and FLASH_IN_PROJECT
+# makes it get flashed when calling `idf.py custom_partition-flash` or just `idf.py flash`)
+esp_partition_register_target(${partition} "${image_file}" DEPENDS generate_custom_partition FLASH_IN_PROJECT)

examples/storage/partition_api/partition_ops/main/main.c

@@ -54,5 +54,15 @@ void app_main(void)
 
     ESP_LOGI(TAG, "Erased data");
 
+    // Find the custom partition in the partition table
+    partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "custom_partition");
+    assert(partition != NULL);
+
+    memset(read_data, 0, sizeof(read_data));
+    // Read the data and check if it matches the expected content (first 12 bytes should be "abcdef123456", rest should be 0x00's)
+    ESP_ERROR_CHECK(esp_partition_read(partition, 0, read_data, sizeof(read_data)));
+    assert(memcmp("abcdef123456", read_data, 12) == 0);
+    ESP_LOGI(TAG, "Read data from custom partition: %s", read_data);
+
     ESP_LOGI(TAG, "Example end");
 }

examples/storage/partition_api/partition_ops/partitions_example.csv

@@ -3,4 +3,5 @@
 nvs,        data, nvs,      0x9000,  0x6000,
 phy_init,   data, phy,      0xf000,  0x1000,
 factory,    app,  factory,  0x10000, 1M,
-storage,    data, ,             , 0x40000,
+storage,    data, ,                , 0x3F000,
+custom_partition, data, ,          , 0x1000,