ESP32-IDF 分区表

---

一、基本介绍

使用时要添加头文件 #include "esp_partition.h"。

1、配置结构体

1.1 esp_partition_t

typedef struct {
   
   
    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 */
} esp_partition_t;

该结构体存储的是分区信息，使用的是 API 的格式，而不是 Flash 中的格式，该格式是 esp_partition_info_t。

• flash_chip：分区所在的 SPI 闪存芯片
• type：分区类型 （app/data）
• subtype：partition subtype partition 子类型
• address：Flash 中分区的起始地址
• size：分区的大小（以字节为单位）
• erase_size：擦除操作所应对齐的大小
• label：分区标签，以零结尾的 ASCII 字符串
• encrypted：如果分区已加密，则 flag 设置为 true
• readonly：如果 partition 是只读的，则 flag 设置为 true

1.2 esp_partition_iterator_t

用于遍历分区表的迭代器：

typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t;

...

typedef struct esp_partition_iterator_opaque_ {
   
   
    esp_partition_type_t type;                      // requested type
    esp_partition_subtype_t subtype;                // requested subtype
    const char *label;                              // requested label (can be NULL)
    partition_list_item_t *next_item;               // next item to iterate to
    esp_partition_t *info;                          // pointer to info (it is redundant, but makes code more readable)
} esp_partition_iterator_opaque_t;

2、常用 API

2.1 esp_partition_find

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

• 参数
  • type：分区类型，参考 esp_partition_type_t
  • subtype：分区子类型，参考 esp_partition_subtype_t
  • label：可选）分区标签。如果查找具有特定名称的分区，请设置此值。否则传递 NULL。
• 作用
  • 根据一个或多个参数查找分区。
• 返回值
  • esp_partition_iterator_t ：可用于枚举找到的所有分区的迭代器；如果未找到分区，则为 NULL。通过此函数获取的 Iterator 在不再使用时必须使用 esp_partition_iterator_release 释放。

2.2 esp_partition_find_first

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

• 参数
  • type：分区类型，参考 esp_partition_type_t
  • subtype：分区子类型，参考 esp_partition_subtype_t
  • label：可选）分区标签。如果查找具有特定名称的分区，请设置此值。否则传递 NULL。
• 作用
  • 根据一个或多个参数查找第一个分区。
• 返回值
  • esp_partition_iterator_t ：指向 esp_partition_t 结构的指针，如果未找到分区，则为 NULL。此指针在应用程序的生存期内有效。

2.3 esp_partition_get

const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator)

• 参数
  • iterator：通过 esp_partition_find 获取的迭代器。必须为非 NULL。
• 作用
  • 获取给定分区 esp_partition_t 结构。
• 返回值
  • esp_partition_t ：指向 esp_partition_t 结构的指针。此指针在应用程序的生存期内有效。

2.4 esp_partition_next

esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator)

• 参数
  • iterator：通过 esp_partition_find 获取的迭代器。必须为非 NULL。
• 作用
  • 将 partition iterator 移动到找到的下一个分区。
• 返回值
  • esp_partition_t ：如果未找到分区，则为 NULL，否则为有效的 esp_partition_iterator_t。

2.5 esp_partition_iterator_release

void esp_partition_iterator_release(esp_partition_iterator_t iterator)

• 参数
  • iterator：使用 esp_partition_find 获取的迭代器。迭代器允许为 NULL，因此在调用此函数之前无需检查其值。
• 作用
  • 释放 partition 迭代器。

2.6 esp_partition_verify

const esp_partition_t *esp_partition_verify(const esp_partition_t *partition)

• 参数
  • partition：指向要验证的分区数据的指针。必须为非 NULL。此结构的所有字段必须与 flash 中的分区表条目匹配，此函数才能返回成功匹配。
• 作用
  • 验证分区数据。
• 返回值
  • 如果未找到分区，则返回 NULL。
  • 如果找到，则返回指向 flash 中 esp_partition_t 结构的指针。此指针在应用程序的生存期内始终有效。

2.7 esp_partition_read

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

• 参数
  • partition：指向使用 esp_partition_find_first 或 esp_partition_get 获取的分区结构的指针。必须为非 NULL。
  • src_offset：要读取的数据的地址，相对于分区的开头。
  • dst：向应存储数据的缓冲区的指针。指针必须为非 NULL，并且缓冲区必须至少为 ‘size’ 字节长。
  • size：要读取的数据的大小，以字节为单位。
• 作用
  • 从分区中读取数据。
• 返回值
  • ESP_OK，如果数据读取成功
  • ESP_ERR_INVALID_ARG：参数错误，比如 src_offset 超过分区大小
  • ESP_ERR_INVALID_SIZE：如果读取将超出分区的边界

2.8 esp_partition_write

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

• 参数
  • partition：指向使用 esp_partition_find_first 或 esp_partition_get 获取的分区结构的指针。必须为非 NULL。
  • dst_offset：相对于分区开头应写入数据的地址。
  • src：指向源缓冲区的指针。指针必须为非 NULL，并且缓冲区必须至少为 ‘size’ 字节长。
  • size：要写入的数据的大小，以字节为单位。
• 作用
  • 从将数据写入分区。
• 返回值
  • ESP_OK，如果数据读取成功
  • ESP_ERR_INVALID_ARG：参数错误，比如 dst_offset 超过分区大小
  • ESP_ERR_INVALID_SIZE：如果 write 会超出分区的边界
  • ESP_ERR_NOT_ALLOWED：如果分区是只读的

在将数据写入 flash 之前，需要擦除 flash 的相应区域。这可以使用 esp_partition_erase_range 函数来完成。

2.9 esp_partition_erase_range

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

• 参数
  • partition：指向使用 esp_partition_find_first 或 esp_partition_get 获取的分区结构的指针。必须为非 NULL。
  • offset：从擦除操作应开始的分区开头开始