# 分区 API

[English]

## 概述

`esp_partition` 组件提供了高层次的 API 函数，用于访问定义在 分区表 中的分区。这些 API 基于 SPI flash API 提供的低层次 API。

## 分区表 API

ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导加载程序、各种应用程序二进制文件、数据及文件系统等。请参阅 分区表，查看详细信息。

该组件在 `esp_partition.h` 中声明了一些 API 函数，用以枚举在分区表中找到的分区，并对这些分区执行操作：

- `esp_partition_find()`：在分区表中查找特定类型的条目，返回一个不透明迭代器；

- `esp_partition_get()`：返回一个结构体，描述给定迭代器的分区；

- `esp_partition_next()`：将迭代器移至下一个找到的分区；

- `esp_partition_iterator_release()`：释放 `esp_partition_find()` 中返回的迭代器；

- `esp_partition_find_first()`：返回描述 `esp_partition_find()` 中找到的第一个分区的结构；

- `esp_partition_read()`、`esp_partition_write()` 和 `esp_partition_erase_range()` 等同于 `esp_flash_read()`、`esp_flash_write()` 和 `esp_flash_erase_region()`，但在分区边界内执行。

## 应用示例

- storage/partition_api/partition_ops 演示了如何对分区表执行读、写和擦除操作。

- storage/parttool 演示了如何使用分区工具执行读、写、擦除分区、检索分区信息和转储整个分区表等操作。

- storage/partition_api/partition_find 演示了如何搜索分区表，并根据分区类型、子类型和标签/名称等约束条件返回匹配的分区。

- storage/partition_api/partition_mmap 演示了如何配置 MMU，将分区映射到内存地址空间以进行读操作，并验证写入和读取的数据。

## 将二进制文件烧录到分区

`esp_partition_register_target` 函数允许将二进制文件注册到特定分区进行烧录。它会创建一个按分区划分的烧录目标（例如，`idf.py mypart-flash`，其中 `mypart` 是 `partitions.csv` 中分区的名称），并可选择将该二进制文件包含在 `idf.py flash` 中。

该函数在 esp_partition/project_include.cmake 中定义。

在项目的 CMakeLists.txt 中的基本用法：

    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`：

- 使用 storage/partition_api/partition_ops 烧录带有预定义内容的自定义分区。

- fatfs/project_include.cmake — `fatfs_create_spiflash_image` 会创建一个 FATFS 镜像并注册 `<partition>-flash` 目标。

- nvs_flash/project_include.cmake — `nvs_create_partition_image` 会创建 NVS 镜像，并注册 `<partition>-flash` 目标。

- spiffs/project_include.cmake — `spiffs_create_partition_image` 会创建 SPIFFS 镜像并注册 `<partition>-flash` 目标。

## 其他资源

- 分区表

- 空中升级 (OTA) 提供了高层 API，用于更新存储在 flash 中的应用程序。

- 非易失性存储库 提供了结构化 API，用于在 SPI flash 中存储小块数据。

## 分区表 API 参考

### Header File

- components/esp_partition/include/esp_partition.h

- This header file can be included with:

  >     #include "esp_partition.h"

- This header file is a part of the API provided by the `esp_partition` component. To declare that your component depends on `esp_partition`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_partition

  > or

  >     PRIV_REQUIRES esp_partition

### Functions

esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)

  Find partition based on one or more parameters.

  参数:

    - type -- Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

    - subtype -- Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer. To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

    - label -- (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

  返回:

    iterator which can be used to enumerate all the partitions found, or NULL if no partitions were found. Iterator obtained through this function has to be released using esp_partition_iterator_release when not used any more.

esp_err_t esp_partition_find_err(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label, esp_partition_iterator_t *it)

  Find partition based on one or more parameters with error reporting.

  This function provides the same functionality as esp_partition_find() but returns error information instead of just NULL on failure. This allows applications to distinguish between "no partitions found" and actual error conditions.

  参数:

    - type -- Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

    - subtype -- Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer. To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

    - label -- (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

    - it -- [out] Output iterator which can be used to enumerate all the partitions found. Must not be NULL. Set to NULL if no partitions were found or on error. If not NULL after successful call, iterator must be released using esp_partition_iterator_release when not used any more.

  返回:

    - ESP_OK: Operation completed successfully

    - ESP_ERR_INVALID_ARG: if param[out] it is NULL, or if type is ESP_PARTITION_TYPE_ANY but subtype is not ESP_PARTITION_SUBTYPE_ANY

    - ESP_ERR_NO_MEM: if memory allocation failed

    - ESP_ERR_NOT_FOUND: if no partition were found

    - Other error codes from partition loading functions

const esp_partition_t *esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)

  Find first partition based on one or more parameters.

  参数:

    - type -- Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

    - subtype -- Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

    - label -- (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

  返回:

    pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application.

esp_err_t esp_partition_find_first_err(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label, const esp_partition_t **partition)

  Find first partition based on one or more parameters with error reporting.

  This function provides the same functionality as esp_partition_find_first() but returns error information instead of just NULL on failure. This allows applications to distinguish between "no partition found" and actual error conditions.

  参数:

    - type -- Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

    - subtype -- Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

    - label -- (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

    - partition -- [out] Output pointer to esp_partition_t structure. Must not be NULL. Set to NULL if no partition is found or on error. If not NULL after successful call, this pointer is valid for the lifetime of the application.

  返回:

    - ESP_OK: Operation completed successfully (regardless of whether partition was found)

    - ESP_ERR_INVALID_ARG: if param[out] partition is NULL, or if type is ESP_PARTITION_TYPE_ANY but subtype is not ESP_PARTITION_SUBTYPE_ANY

    - ESP_ERR_NO_MEM: if memory allocation failed

    - ESP_ERR_NOT_FOUND: if no partition were found

    - Other error codes from partition loading functions

const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator)

  Get esp_partition_t structure for given partition.

  参数:

    iterator -- Iterator obtained using esp_partition_find. Must be non-NULL.

  返回:

    pointer to esp_partition_t structure. This pointer is valid for the lifetime of the application.

esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator)

  Move partition iterator to the next partition found.

  Any copies of the iterator will be invalid after this call.

  参数:

    iterator -- Iterator obtained using esp_partition_find. Must be non-NULL.

  返回:

    NULL if no partition was found, valid esp_partition_iterator_t otherwise.

void esp_partition_iterator_release(esp_partition_iterator_t iterator)

  Release partition iterator.

  参数:

    iterator -- Iterator obtained using esp_partition_find. The iterator is allowed to be NULL, so it is not necessary to check its value before calling this function.

const esp_partition_t *esp_partition_verify(const esp_partition_t *partition)

  Verify partition data.

  Given a pointer to partition data, verify this partition exists in the partition table (all fields match.)

  This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the permanent partition data stored in flash.

  Pointers returned from this function can be compared directly to the address of any pointer returned from esp_partition_get(), as a test for equality.

  参数:

    partition -- Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the partition table entry in flash for this function to return a successful match.

  返回:

    - If partition not found, returns NULL.

    - If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application.

esp_err_t esp_partition_verify_err(const esp_partition_t *partition, const esp_partition_t **out_partition)

  Verify partition data with error reporting.

  This function provides the same functionality as esp_partition_verify() but returns error information instead of just NULL on failure. This allows applications to distinguish between "partition not found" and actual error conditions

  Given a pointer to partition data, verify this partition exists in the partition table by comparing all key fields (flash_chip, address, size, encrypted status). The function searches through all registered partitions with matching type, subtype, and label.

  This function is useful to:

  - Take partition data from RAM buffer and convert to permanent flash-based pointer

  - Validate partition structures obtained from external sources

  - Ensure partition data integrity before performing operations

  参数:

    - partition -- Pointer to partition data to verify. Must be non-NULL. The following fields are used for verification:

      - type: Partition type

      - subtype: Partition subtype

      - label: Partition label (if non-empty)

      - flash_chip: Flash chip pointer

      - address: Starting address

      - size: Partition size

      - encrypted: Encryption status

    - out_partition -- [out] Output pointer to verified esp_partition_t structure. Must not be NULL. Set to NULL if partition is not found or on error. If not NULL after successful call, this pointer is valid for the lifetime of the application and points to the permanent partition structure in flash.

  返回:

    - ESP_OK: Partition verified successfully and found in partition table

    - ESP_ERR_INVALID_ARG: if partition or out_partition is NULL

    - ESP_ERR_NO_MEM: if memory allocation failed during partition search

    - ESP_ERR_NOT_FOUND: if no matching partition found in partition table

esp_err_t esp_partition_read(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)

  Read data from the partition.

  Partitions marked with an encryption flag will automatically be be read and decrypted via a cache mapping.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - dst -- Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least 'size' bytes long.

    - src_offset -- Address of the data to be read, relative to the beginning of the partition.

    - size -- Size of data to be read, in bytes.

  返回:

    ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.

esp_err_t esp_partition_write(const esp_partition_t *partition, size_t dst_offset, const void *src, size_t size)

  Write data to the partition.

  Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

  Partitions marked with an encryption flag will automatically be written via the esp_flash_write_encrypted() function. If writing to an encrypted partition, all write offsets and lengths must be multiples of 16 bytes. See the esp_flash_write_encrypted() function for more details. Unencrypted partitions do not have this restriction.

  备注

  Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - dst_offset -- Address where the data should be written, relative to the beginning of the partition.

    - src -- Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least 'size' bytes long.

    - size -- Size of data to be written, in bytes.

  返回:

    ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; ESP_ERR_NOT_ALLOWED, if partition is read-only; or one of error codes from lower-level flash driver.

esp_err_t esp_partition_read_raw(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)

  Read data from the partition without any transformation/decryption.

  备注

  This function is essentially the same as `esp_partition_read()` above. It just never decrypts data but returns it as is.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - dst -- Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least 'size' bytes long.

    - src_offset -- Address of the data to be read, relative to the beginning of the partition.

    - size -- Size of data to be read, in bytes.

  返回:

    ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.

esp_err_t esp_partition_write_raw(const esp_partition_t *partition, size_t dst_offset, const void *src, size_t size)

  Write data to the partition without any transformation/encryption.

  Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

  备注

  This function is essentially the same as `esp_partition_write()` above. It just never encrypts data but writes it as is.

  备注

  Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - dst_offset -- Address where the data should be written, relative to the beginning of the partition.

    - src -- Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least 'size' bytes long.

    - size -- Size of data to be written, in bytes.

  返回:

    ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; ESP_ERR_NOT_ALLOWED, if partition is read-only; or one of the error codes from lower-level flash driver.

esp_err_t esp_partition_erase_range(const esp_partition_t *partition, size_t offset, size_t size)

  Erase part of the partition.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - offset -- Offset from the beginning of partition where erase operation should start. Must be aligned to partition->erase_size.

    - size -- Size of the range which should be erased, in bytes. Must be divisible by partition->erase_size.

  返回:

    ESP_OK, if the range was erased successfully; ESP_ERR_INVALID_ARG, if iterator or dst are NULL; ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; ESP_ERR_NOT_ALLOWED, if partition is read-only; or one of error codes from lower-level flash driver.

esp_err_t esp_partition_mmap(const esp_partition_t *partition, size_t offset, size_t size, esp_partition_mmap_flag_t flags, const void **out_ptr, esp_partition_mmap_handle_t *out_handle)

  Configure MMU to map partition into data memory.

  Unlike spi_flash_mmap function, which requires a 64kB aligned base address, this function doesn't impose such a requirement. If offset results in a flash address which is not aligned to 64kB boundary, address will be rounded to the lower 64kB boundary, so that mapped region includes requested range. Pointer returned via out_ptr argument will be adjusted to point to the requested offset (not necessarily to the beginning of mmap-ed region).

  To release mapped memory, pass handle returned via out_handle argument to esp_partition_munmap function.

  If there is any mapped region while SPI Flash is being erased or programmed, the cache will be disabled and the system will be suspended by default. (for more info see SPI flash docs about cache disabling. It will decrease the performance of the system when it's possible for the cache to be kept enabled (for example, when XIP on PSRAM). Please specify ESP_PARTITION_MMAP_BLOCKS_WRITE flag to block flash erasing/writing APIs until this region is unmapped. See SPI_FLASH_MMAP_FLAG_BLOCKS_WRITE for more details.

  参数:

    - partition -- Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.

    - offset -- Offset from the beginning of partition where mapping should start.

    - size -- Size of the area to be mapped.

    - flags -- Flags of the mapping, including address space where the region should be mapped (data or instruction)

    - out_ptr -- Output, pointer to the mapped memory region

    - out_handle -- Output, handle which should be used for esp_partition_munmap call

  返回:

    ESP_OK, if successful

void esp_partition_munmap(esp_partition_mmap_handle_t handle)

  Release region previously obtained using esp_partition_mmap.

  备注

  Calling this function will not necessarily unmap memory region. Region will only be unmapped when there are no other handles which reference this region. In case of partially overlapping regions it is possible that memory will be unmapped partially.

  参数:

    handle -- Handle obtained from spi_flash_mmap

esp_err_t esp_partition_get_sha256(const esp_partition_t *partition, uint8_t *sha_256)

  Get SHA-256 digest for required partition.

  For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app image content. The hash is verified before returning, if app content is invalid then the function returns ESP_ERR_IMAGE_INVALID. For apps without SHA-256 appended to the image, the result is the SHA-256 of all bytes in the app image. For other partition types, the result is the SHA-256 of the entire partition.

  参数:

    - partition -- [in] Pointer to info for partition containing app or data. (fields: address, size and type, are required to be filled).

    - sha_256 -- [out] Returned SHA-256 digest for a given partition.

  返回:

    - ESP_OK: In case of successful operation.

    - ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL.

    - ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation.

    - ESP_ERR_IMAGE_INVALID: App partition doesn't contain a valid app image.

    - ESP_FAIL: An allocation error occurred.

bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t *partition_2)

  Check for the identity of two partitions by SHA-256 digest.

  参数:

    - partition_1 -- [in] Pointer to info for partition 1 containing app or data. (fields: address, size and type, are required to be filled).

    - partition_2 -- [in] Pointer to info for partition 2 containing app or data. (fields: address, size and type, are required to be filled).

  返回:

    - True: In case of the two firmware is equal.

    - False: Otherwise

esp_err_t esp_partition_register_external(esp_flash_t *flash_chip, size_t offset, size_t size, const char *label, esp_partition_type_t type, esp_partition_subtype_t subtype, const esp_partition_t **out_partition)

  Register a partition on an external flash chip.

  This API allows designating certain areas of external flash chips (identified by the esp_flash_t structure) as partitions. This allows using them with components which access SPI flash through the esp_partition API.

  参数:

    - flash_chip -- Pointer to the structure identifying the flash chip. If NULL then the internal flash chip is used (esp_flash_default_chip).

    - offset -- Address in bytes, where the partition starts

    - size -- Size of the partition in bytes

    - label -- Partition name

    - type -- One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applications can not be booted from external flash chips, so using ESP_PARTITION_TYPE_APP is not supported.

    - subtype -- One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer.

    - out_partition -- [out] Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure

  返回:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if memory allocation has failed

    - ESP_ERR_INVALID_ARG if the new partition overlaps another partition on the same flash chip

    - ESP_ERR_INVALID_SIZE if the partition doesn't fit into the flash chip size

esp_err_t esp_partition_deregister_external(const esp_partition_t *partition)

  Deregister the partition previously registered using esp_partition_register_external.

  参数:

    partition -- pointer to the partition structure obtained from esp_partition_register_external,

  返回:

    - ESP_OK on success

    - ESP_ERR_NOT_FOUND if the partition pointer is not found

    - ESP_ERR_INVALID_ARG if the partition comes from the partition table

    - ESP_ERR_INVALID_ARG if the partition was not registered using esp_partition_register_external function.

void esp_partition_unload_all(void)

  Unload partitions and free space allocated by them.

uint32_t esp_partition_get_main_flash_sector_size(void)

  Get the main flash sector size.

  返回:

    - SPI_FLASH_SEC_SIZE - For esp32xx target

    - ESP_PARTITION_EMULATED_SECTOR_SIZE - For linux target

esp_err_t esp_partition_copy(const esp_partition_t *dest_part, uint32_t dest_offset, const esp_partition_t *src_part, uint32_t src_offset, size_t size)

  Copy data from a source partition at a specific offset to a destination partition at a specific offset.

  The destination offset must be aligned to the flash sector size (SPI_FLASH_SEC_SIZE = 0x1000). If "size" is SIZE_MAX, the entire destination partition (from dest_offset onward) will be erased, and the function will copy all of the source partition starting from src_offset into the destination. The function ensures that the destination partition is erased on sector boundaries (erase size is aligned up SPI_FLASH_SEC_SIZE).

  This function does the following:

  - erases the destination partition from dest_offset to the specified size (or the whole partition if "size" == SIZE_MAX),

  - maps data from the source partition in chunks,

  - writes the source data into the destination partition in corresponding chunks.

  参数:

    - dest_part -- Pointer to a destination partition.

    - dest_offset -- Offset in the destination partition where the data should be written (must be aligned to SPI_FLASH_SEC_SIZE = 0x1000).

    - src_part -- Pointer to a source partition (must be located on internal flash).

    - src_offset -- Offset in the source partition where the data should be read from.

    - size -- Number of bytes to copy from the source partition to the destination partition. If "size" is SIZE_MAX, the function copies from src_offset to the end of the source partition and erases the entire destination partition (from dest_offset onward).

  返回:

    ESP_OK, if the source partition was copied successfully to the destination partition; ESP_ERR_INVALID_ARG, if src_part or dest_part are incorrect, or if dest_offset is not sector aligned; ESP_ERR_INVALID_SIZE, if the copy would go out of bounds of the source or destination partition; ESP_ERR_NOT_ALLOWED, if the destination partition is read-only; or one of the error codes from the lower-level flash driver.

esp_err_t esp_partition_get_blockdev(const esp_partition_type_t type, const esp_partition_subtype_t subtype, const char *label, esp_blockdev_handle_t *out_bdl_handle)

  Creates block device instance associated with the desired partition and returns the corresponding handle. Convenient version.

  The Block Device Layer (BDL) interface allows generic access to each partition, represented by its unique parameters or by existing 'esp_partition_t' object. Each BDL structure instance is employed as an extension to existing partition object, ie the partition object is not created if not found. The BDL instance is to be created and destroyed only via the corresponding create/release APIs. Ignoring this requirement may lead to memory leaks and similar troubles.

  New BDL structure instance is created on the application's heap, it is initialized with the partition's holder details (esp_partition_t) and the caller obtains corresponding BDL handle in 'out_bdl_handle' output parameter. The life-cycle of such BDL object is fully managed by the owner (caller) and is not checked during possible esp_partition_t changes or instance destruction.

  参数:

    - type -- [in] Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.

    - subtype -- [in] Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.

    - label -- [in] (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

    - out_bdl_handle -- [out] Block device instance handle for "native" BDL control

  返回:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if memory allocation has failed

    - ESP_ERR_NOT_FOUND if the partition defined by the parameters cannot be found

esp_err_t esp_partition_ptr_get_blockdev(const esp_partition_t *partition, esp_blockdev_handle_t *out_bdl_handle)

  The same as esp_partition_get_blockdev(), it just accepts existing partition holder as an parameter and doesn't provide the partition search by itself.

  参数:

    - partition -- [in] Pointer to existing esp_partition_t instance

    - out_bdl_handle -- [out] Block device instance handle for "native" BDL control

  返回:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if memory allocation has failed

    - ESP_ERR_NOT_FOUND if the partition defined by the parameters cannot be found

### Structures

struct esp_partition_t

  partition information structure

  This is not the format in flash, that format is esp_partition_info_t.

  However, this is the format used by this API.

  Public Members

  esp_flash_t *flash_chip

    SPI flash chip on which the partition resides

  esp_partition_type_t type

    partition type (app/data)

  esp_partition_subtype_t subtype

    partition subtype

  uint32_t address

    starting address of the partition in flash

  uint32_t size

    size of the partition, in bytes

  uint32_t erase_size

    size the erase operation should be aligned to

  char label[17]

    partition label, zero-terminated ASCII string

  bool encrypted

    flag is set to true if partition is encrypted

  bool readonly

    flag is set to true if partition is read-only

### Macros

esp_partition_mmap_memory_t

  Deprecated type.

ESP_PARTITION_SUBTYPE_OTA(i)

  Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition.

### Type Definitions

typedef uint32_t esp_partition_mmap_handle_t

  Opaque handle for memory region obtained from esp_partition_mmap.

typedef struct esp_partition_iterator_opaque_ *esp_partition_iterator_t

  Opaque partition iterator type.

### Enumerations

enum esp_partition_mmap_flag_t

  Flags for esp_partition_mmap() calls.

  Values:

  enumerator ESP_PARTITION_MMAP_DATA

    map to data memory (Vaddr0), allows byte-aligned access, (4 MB total - only for esp32)

  enumerator ESP_PARTITION_MMAP_INST

    map to instruction memory (Vaddr1-3), allows only 4-byte-aligned access, (11 MB total - only for esp32)

  enumerator ESP_PARTITION_MMAP_BLOCKS_WRITE

    Blocks flash erasing/writing until unmap to avoid the cache disabling. See SPI_FLASH_MMAP_FLAG_BLOCKS_WRITE.

enum esp_partition_type_t

  Partition type.

  备注

  Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. Any other integer value 0x40-0xFE can be used by individual applications, without restriction.

  Values:

  enumerator ESP_PARTITION_TYPE_APP

    Application partition type.

  enumerator ESP_PARTITION_TYPE_DATA

    Data partition type.

  enumerator ESP_PARTITION_TYPE_BOOTLOADER

    Bootloader partition type.

  enumerator ESP_PARTITION_TYPE_PARTITION_TABLE

    Partition table type.

  enumerator ESP_PARTITION_TYPE_ANY

    Used to search for partitions with any type.

enum esp_partition_subtype_t

  Partition subtype.

  Application-defined partition types (0x40-0xFE) can set any numeric subtype value.

  备注

  These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP and ESP_PARTITION_TYPE_DATA.

  Values:

  enumerator ESP_PARTITION_SUBTYPE_BOOTLOADER_PRIMARY

    Primary Bootloader.

  enumerator ESP_PARTITION_SUBTYPE_BOOTLOADER_OTA

    Temporary OTA storage for Bootloader, where the OTA uploads a new Bootloader image.

  enumerator ESP_PARTITION_SUBTYPE_BOOTLOADER_RECOVERY

    Recovery Bootloader.

  enumerator ESP_PARTITION_SUBTYPE_PARTITION_TABLE_PRIMARY

    Primary Partition table.

  enumerator ESP_PARTITION_SUBTYPE_PARTITION_TABLE_OTA

    Temporary OTA storage for Partition table, where the OTA uploads a new Partition table image.

  enumerator ESP_PARTITION_SUBTYPE_APP_FACTORY

    Factory application partition.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_MIN

    Base for OTA partition subtypes.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_0

    OTA partition 0.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_1

    OTA partition 1.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_2

    OTA partition 2.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_3

    OTA partition 3.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_4

    OTA partition 4.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_5

    OTA partition 5.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_6

    OTA partition 6.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_7

    OTA partition 7.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_8

    OTA partition 8.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_9

    OTA partition 9.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_10

    OTA partition 10.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_11

    OTA partition 11.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_12

    OTA partition 12.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_13

    OTA partition 13.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_14

    OTA partition 14.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_15

    OTA partition 15.

  enumerator ESP_PARTITION_SUBTYPE_APP_OTA_MAX

    Max subtype of OTA partition.

  enumerator ESP_PARTITION_SUBTYPE_APP_TEST

    Test application partition.

  enumerator ESP_PARTITION_SUBTYPE_APP_TEE_MIN

    Base for TEE partition subtypes.

  enumerator ESP_PARTITION_SUBTYPE_APP_TEE_0

    TEE partition 0.

  enumerator ESP_PARTITION_SUBTYPE_APP_TEE_1

    TEE partition 1.

  enumerator ESP_PARTITION_SUBTYPE_APP_TEE_MAX

    Max subtype of TEE partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_OTA

    OTA selection partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_PHY

    PHY init data partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_NVS

    NVS partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_COREDUMP

    COREDUMP partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS

    Partition for NVS keys.

  enumerator ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM

    Partition for emulate eFuse bits.

  enumerator ESP_PARTITION_SUBTYPE_DATA_UNDEFINED

    Undefined (or unspecified) data partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD

    ESPHTTPD partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_FAT

    FAT partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_SPIFFS

    SPIFFS partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_LITTLEFS

    LITTLEFS partition.

  enumerator ESP_PARTITION_SUBTYPE_DATA_TEE_OTA

    TEE OTA selection partition.

  enumerator ESP_PARTITION_SUBTYPE_ANY

    Used to search for partitions with any subtype.

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。