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.

docs/en/api-reference/storage/partition.rst

@@ -35,6 +35,39 @@ Application Examples
 
 - :example:`storage/partition_api/partition_mmap` demonstrates how to configure the MMU, map a partition into memory address space for read operations, and verify the data written and read.
 
+Flashing Binaries to Partitions
+-------------------------------
+
+The ``esp_partition_register_target`` function allows registering binary files to be flashed to specific partitions. It creates a per-partition flash target (e.g., ``idf.py mypart-flash``, where ``mypart`` is the name of the partition in ``partitions.csv``) and optionally includes the binary in ``idf.py flash``.
+
+This function is defined in :component_file:`esp_partition/project_include.cmake`.
+
+**Basic usage in a project's CMakeLists.txt:**
+
+.. code-block:: cmake
+
+   esp_partition_register_target(my_partition "${CMAKE_BINARY_DIR}/my_data.bin" FLASH_IN_PROJECT)
+
+This creates a ``my_partition-flash`` target and includes the binary when running ``idf.py flash``.
+
+**Arguments:**
+
+- ``partition_name`` — Name of the partition as defined in the partition table.
+- ``binary_path`` — Path to the binary file to flash.
+- ``FLASH_IN_PROJECT`` (optional) — Also flash this binary when running ``idf.py flash``.
+- ``ALWAYS_PLAINTEXT`` (optional) — Flash without encryption even when flash encryption is enabled. Use for filesystems that don't support encryption (e.g., SPIFFS). Must not be used with partitions marked as ``encrypted`` in the partition table.
+- ``DEPENDS <targets>`` (optional) — CMake targets that must be built before flashing (e.g., a custom target that generates the binary).
+- ``FLASH_IN_PROJECT_DEPENDENCY_TARGETS <targets>`` (optional) — Additional flash targets (e.g., ``encrypted-flash``) that should also depend on the targets specified in ``DEPENDS``. Requires ``FLASH_IN_PROJECT``.
+
+**Component integration examples:**
+
+Several IDF components use ``esp_partition_register_target`` internally:
+
+- :example:`storage/partition_api/partition_ops` uses it to flash a custom partition with predefined content.
+- :component_file:`fatfs/project_include.cmake` — ``fatfs_create_spiflash_image`` creates a FATFS image and registers a ``<partition>-flash`` target.
+- :component_file:`nvs_flash/project_include.cmake` — ``nvs_create_partition_image`` creates an NVS image and registers a ``<partition>-flash`` target.
+- :component_file:`spiffs/project_include.cmake` — ``spiffs_create_partition_image`` creates a SPIFFS image and registers a ``<partition>-flash`` target.
+
 See Also
 --------