mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 11:03:11 +00:00
Merge branch 'feat/cmake_add_partition_flash_binary_function' into 'master'
feat(esp_partition): Add esp_partition_register_target Cmake function Closes IDF-11870 and DOC-14244 See merge request espressif/esp-idf!37176
This commit is contained in:
Adam Múdry
@@ -6,7 +6,7 @@ Partitions API
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ``esp_partition`` component has higher-level API functions which work with partitions defined in the :doc:`/api-guides/partition-tables`. These APIs are based on lower level API provided by :doc:`/api-reference/peripherals/spi_flash/index`.
|
||||
The ``esp_partition`` component has higher-level API functions which work with partitions defined in the :doc:`/api-guides/partition-tables`. These APIs are based on lower-level API provided by :doc:`/api-reference/peripherals/spi_flash/index`.
|
||||
|
||||
.. _flash-partition-apis:
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
|
||||
@@ -35,12 +35,45 @@ ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导加载
|
||||
|
||||
- :example:`storage/partition_api/partition_mmap` 演示了如何配置 MMU，将分区映射到内存地址空间以进行读操作，并验证写入和读取的数据。
|
||||
|
||||
将二进制文件烧录到分区
|
||||
-------------------------------
|
||||
|
||||
``esp_partition_register_target`` 函数允许将二进制文件注册到特定分区进行烧录。它会创建一个按分区划分的烧录目标（例如，``idf.py mypart-flash``，其中 ``mypart`` 是 ``partitions.csv`` 中分区的名称），并可选择将该二进制文件包含在 ``idf.py flash`` 中。
|
||||
|
||||
该函数在 :component_file:`esp_partition/project_include.cmake` 中定义。
|
||||
|
||||
**在项目的 CMakeLists.txt 中的基本用法：**
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
esp_partition_register_target(my_partition "${CMAKE_BINARY_DIR}/my_data.bin" FLASH_IN_PROJECT)
|
||||
|
||||
这会创建一个 ``my_partition-flash`` 目标，并在运行 ``idf.py flash`` 时包含该二进制文件。
|
||||
|
||||
**参数：**
|
||||
|
||||
- ``partition_name`` — 在分区表中定义的分区名称。
|
||||
- ``binary_path`` — 要烧录的二进制文件路径。
|
||||
- ``FLASH_IN_PROJECT`` （可选） — 在运行 ``idf.py flash`` 时也会烧录此二进制文件。
|
||||
- ``ALWAYS_PLAINTEXT`` （可选） — 即使启用了 flash 加密，仍以非加密方式烧录。用于不支持加密的文件系统（例如 SPIFFS）。不得与分区表中标记为 ``encrypted`` 的分区一起使用。
|
||||
- ``DEPENDS <targets>`` （可选） — 在烧录之前必须构建的 CMake 目标（例如，生成二进制文件的自定义目标）。
|
||||
- ``FLASH_IN_PROJECT_DEPENDENCY_TARGETS <targets>`` （可选） — 额外的烧录目标（例如 ``encrypted-flash``），这些目标也应依赖于 ``DEPENDS`` 中指定的目标。需要 ``FLASH_IN_PROJECT``。
|
||||
|
||||
**组件集成示例：**
|
||||
|
||||
某些 IDF 组件在内部使用了 ``esp_partition_register_target``：
|
||||
|
||||
- 使用 :example:`storage/partition_api/partition_ops` 烧录带有预定义内容的自定义分区。
|
||||
- :component_file:`fatfs/project_include.cmake` — ``fatfs_create_spiflash_image`` 会创建一个 FATFS 镜像并注册 ``<partition>-flash`` 目标。
|
||||
- :component_file:`nvs_flash/project_include.cmake` — ``nvs_create_partition_image`` 会创建 NVS 镜像，并注册 ``<partition>-flash`` 目标。
|
||||
- :component_file:`spiffs/project_include.cmake` — ``spiffs_create_partition_image`` 会创建 SPIFFS 镜像并注册 ``<partition>-flash`` 目标。
|
||||
|
||||
其他资源
|
||||
-------------
|
||||
|
||||
- :doc:`../../api-guides/partition-tables`
|
||||
- :doc:`../system/ota` 提供了高层 API 用于更新存储在 flash 中的 app 固件。
|
||||
- :doc:`nvs_flash` 提供了结构化 API 用于存储 SPI flash 中的碎片数据。
|
||||
- :doc:`../system/ota` 提供了高层 API，用于更新存储在 flash 中的应用程序。
|
||||
- :doc:`nvs_flash` 提供了结构化 API，用于在 SPI flash 中存储小块数据。
|
||||
|
||||
|
||||
.. _api-reference-partition-table:
|
||||
|
||||
Reference in New Issue
Block a user