1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_PARTITION_H__ 16 #define __ESP_PARTITION_H__ 17 18 #include <stdint.h> 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include "esp_err.h" 22 #include "esp_flash.h" 23 #include "esp_spi_flash.h" 24 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @file esp_partition.h 32 * @brief Partition APIs 33 */ 34 35 36 /** 37 * @brief Partition type 38 * 39 * @note Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. 40 * Any other integer value 0x40-0xFE can be used by individual applications, without restriction. 41 * 42 * @internal Keep this enum in sync with PartitionDefinition class gen_esp32part.py @endinternal 43 * 44 */ 45 typedef enum { 46 ESP_PARTITION_TYPE_APP = 0x00, //!< Application partition type 47 ESP_PARTITION_TYPE_DATA = 0x01, //!< Data partition type 48 49 ESP_PARTITION_TYPE_ANY = 0xff, //!< Used to search for partitions with any type 50 } esp_partition_type_t; 51 52 /** 53 * @brief Partition subtype 54 * 55 * @note These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP 56 * and ESP_PARTITION_TYPE_DATA. 57 * 58 * Application-defined partition types (0x40-0xFE) can set any numeric subtype value. 59 * 60 * @internal Keep this enum in sync with PartitionDefinition class gen_esp32part.py @endinternal 61 */ 62 typedef enum { 63 ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00, //!< Factory application partition 64 ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10, //!< Base for OTA partition subtypes 65 ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0, //!< OTA partition 0 66 ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1, //!< OTA partition 1 67 ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2, //!< OTA partition 2 68 ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3, //!< OTA partition 3 69 ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4, //!< OTA partition 4 70 ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5, //!< OTA partition 5 71 ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6, //!< OTA partition 6 72 ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7, //!< OTA partition 7 73 ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8, //!< OTA partition 8 74 ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9, //!< OTA partition 9 75 ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10,//!< OTA partition 10 76 ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11,//!< OTA partition 11 77 ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12,//!< OTA partition 12 78 ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13,//!< OTA partition 13 79 ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14,//!< OTA partition 14 80 ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15,//!< OTA partition 15 81 ESP_PARTITION_SUBTYPE_APP_OTA_MAX = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 16,//!< Max subtype of OTA partition 82 ESP_PARTITION_SUBTYPE_APP_TEST = 0x20, //!< Test application partition 83 84 ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00, //!< OTA selection partition 85 ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01, //!< PHY init data partition 86 ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02, //!< NVS partition 87 ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03, //!< COREDUMP partition 88 ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS = 0x04, //!< Partition for NVS keys 89 ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM = 0x05, //!< Partition for emulate eFuse bits 90 ESP_PARTITION_SUBTYPE_DATA_UNDEFINED = 0x06, //!< Undefined (or unspecified) data partition 91 92 ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80, //!< ESPHTTPD partition 93 ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81, //!< FAT partition 94 ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82, //!< SPIFFS partition 95 96 ESP_PARTITION_SUBTYPE_ANY = 0xff, //!< Used to search for partitions with any subtype 97 } esp_partition_subtype_t; 98 99 /** 100 * @brief Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition 101 */ 102 #define ESP_PARTITION_SUBTYPE_OTA(i) ((esp_partition_subtype_t)(ESP_PARTITION_SUBTYPE_APP_OTA_MIN + ((i) & 0xf))) 103 104 /** 105 * @brief Opaque partition iterator type 106 */ 107 typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t; 108 109 /** 110 * @brief partition information structure 111 * 112 * This is not the format in flash, that format is esp_partition_info_t. 113 * 114 * However, this is the format used by this API. 115 */ 116 typedef struct { 117 esp_flash_t* flash_chip; /*!< SPI flash chip on which the partition resides */ 118 esp_partition_type_t type; /*!< partition type (app/data) */ 119 esp_partition_subtype_t subtype; /*!< partition subtype */ 120 uint32_t address; /*!< starting address of the partition in flash */ 121 uint32_t size; /*!< size of the partition, in bytes */ 122 char label[17]; /*!< partition label, zero-terminated ASCII string */ 123 bool encrypted; /*!< flag is set to true if partition is encrypted */ 124 } esp_partition_t; 125 126 /** 127 * @brief Find partition based on one or more parameters 128 * 129 * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. 130 * To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set 131 * subtype argument to ESP_PARTITION_SUBTYPE_ANY. 132 * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer. 133 * To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY. 134 * @param label (optional) Partition label. Set this value if looking 135 * for partition with a specific name. Pass NULL otherwise. 136 * 137 * @return iterator which can be used to enumerate all the partitions found, 138 * or NULL if no partitions were found. 139 * Iterator obtained through this function has to be released 140 * using esp_partition_iterator_release when not used any more. 141 */ 142 esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label); 143 144 /** 145 * @brief Find first partition based on one or more parameters 146 * 147 * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. 148 * To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set 149 * subtype argument to ESP_PARTITION_SUBTYPE_ANY. 150 * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer 151 * To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY. 152 * @param label (optional) Partition label. Set this value if looking 153 * for partition with a specific name. Pass NULL otherwise. 154 * 155 * @return pointer to esp_partition_t structure, or NULL if no partition is found. 156 * This pointer is valid for the lifetime of the application. 157 */ 158 const esp_partition_t* esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label); 159 160 /** 161 * @brief Get esp_partition_t structure for given partition 162 * 163 * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. 164 * 165 * @return pointer to esp_partition_t structure. This pointer is valid for the lifetime 166 * of the application. 167 */ 168 const esp_partition_t* esp_partition_get(esp_partition_iterator_t iterator); 169 170 /** 171 * @brief Move partition iterator to the next partition found 172 * 173 * Any copies of the iterator will be invalid after this call. 174 * 175 * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. 176 * 177 * @return NULL if no partition was found, valid esp_partition_iterator_t otherwise. 178 */ 179 esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator); 180 181 /** 182 * @brief Release partition iterator 183 * 184 * @param iterator Iterator obtained using esp_partition_find. 185 * The iterator is allowed to be NULL, so it is not necessary to check its value 186 * before calling this function. 187 * 188 */ 189 void esp_partition_iterator_release(esp_partition_iterator_t iterator); 190 191 /** 192 * @brief Verify partition data 193 * 194 * Given a pointer to partition data, verify this partition exists in the partition table (all fields match.) 195 * 196 * This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the 197 * permanent partition data stored in flash. 198 * 199 * Pointers returned from this function can be compared directly to the address of any pointer returned from 200 * esp_partition_get(), as a test for equality. 201 * 202 * @param partition Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the 203 * partition table entry in flash for this function to return a successful match. 204 * 205 * @return 206 * - If partition not found, returns NULL. 207 * - If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application. 208 */ 209 const esp_partition_t *esp_partition_verify(const esp_partition_t *partition); 210 211 /** 212 * @brief Read data from the partition 213 * 214 * Partitions marked with an encryption flag will automatically be 215 * be read and decrypted via a cache mapping. 216 * 217 * @param partition Pointer to partition structure obtained using 218 * esp_partition_find_first or esp_partition_get. 219 * Must be non-NULL. 220 * @param dst Pointer to the buffer where data should be stored. 221 * Pointer must be non-NULL and buffer must be at least 'size' bytes long. 222 * @param src_offset Address of the data to be read, relative to the 223 * beginning of the partition. 224 * @param size Size of data to be read, in bytes. 225 * 226 * @return ESP_OK, if data was read successfully; 227 * ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; 228 * ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; 229 * or one of error codes from lower-level flash driver. 230 */ 231 esp_err_t esp_partition_read(const esp_partition_t* partition, 232 size_t src_offset, void* dst, size_t size); 233 234 /** 235 * @brief Write data to the partition 236 * 237 * Before writing data to flash, corresponding region of flash needs to be erased. 238 * This can be done using esp_partition_erase_range function. 239 * 240 * Partitions marked with an encryption flag will automatically be 241 * written via the spi_flash_write_encrypted() function. If writing to 242 * an encrypted partition, all write offsets and lengths must be 243 * multiples of 16 bytes. See the spi_flash_write_encrypted() function 244 * for more details. Unencrypted partitions do not have this 245 * restriction. 246 * 247 * @param partition Pointer to partition structure obtained using 248 * esp_partition_find_first or esp_partition_get. 249 * Must be non-NULL. 250 * @param dst_offset Address where the data should be written, relative to the 251 * beginning of the partition. 252 * @param src Pointer to the source buffer. Pointer must be non-NULL and 253 * buffer must be at least 'size' bytes long. 254 * @param size Size of data to be written, in bytes. 255 * 256 * @note Prior to writing to flash memory, make sure it has been erased with 257 * esp_partition_erase_range call. 258 * 259 * @return ESP_OK, if data was written successfully; 260 * ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; 261 * ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; 262 * or one of error codes from lower-level flash driver. 263 */ 264 esp_err_t esp_partition_write(const esp_partition_t* partition, 265 size_t dst_offset, const void* src, size_t size); 266 267 /** 268 * @brief Read data from the partition without any transformation/decryption. 269 * 270 * @note This function is essentially the same as \c esp_partition_read() above. 271 * It just never decrypts data but returns it as is. 272 * 273 * @param partition Pointer to partition structure obtained using 274 * esp_partition_find_first or esp_partition_get. 275 * Must be non-NULL. 276 * @param dst Pointer to the buffer where data should be stored. 277 * Pointer must be non-NULL and buffer must be at least 'size' bytes long. 278 * @param src_offset Address of the data to be read, relative to the 279 * beginning of the partition. 280 * @param size Size of data to be read, in bytes. 281 * 282 * @return ESP_OK, if data was read successfully; 283 * ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; 284 * ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; 285 * or one of error codes from lower-level flash driver. 286 */ 287 esp_err_t esp_partition_read_raw(const esp_partition_t* partition, 288 size_t src_offset, void* dst, size_t size); 289 290 /** 291 * @brief Write data to the partition without any transformation/encryption. 292 * 293 * @note This function is essentially the same as \c esp_partition_write() above. 294 * It just never encrypts data but writes it as is. 295 * 296 * Before writing data to flash, corresponding region of flash needs to be erased. 297 * This can be done using esp_partition_erase_range function. 298 * 299 * @param partition Pointer to partition structure obtained using 300 * esp_partition_find_first or esp_partition_get. 301 * Must be non-NULL. 302 * @param dst_offset Address where the data should be written, relative to the 303 * beginning of the partition. 304 * @param src Pointer to the source buffer. Pointer must be non-NULL and 305 * buffer must be at least 'size' bytes long. 306 * @param size Size of data to be written, in bytes. 307 * 308 * @note Prior to writing to flash memory, make sure it has been erased with 309 * esp_partition_erase_range call. 310 * 311 * @return ESP_OK, if data was written successfully; 312 * ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; 313 * ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; 314 * or one of the error codes from lower-level flash driver. 315 */ 316 esp_err_t esp_partition_write_raw(const esp_partition_t* partition, 317 size_t dst_offset, const void* src, size_t size); 318 319 /** 320 * @brief Erase part of the partition 321 * 322 * @param partition Pointer to partition structure obtained using 323 * esp_partition_find_first or esp_partition_get. 324 * Must be non-NULL. 325 * @param offset Offset from the beginning of partition where erase operation 326 * should start. Must be aligned to 4 kilobytes. 327 * @param size Size of the range which should be erased, in bytes. 328 * Must be divisible by 4 kilobytes. 329 * 330 * @return ESP_OK, if the range was erased successfully; 331 * ESP_ERR_INVALID_ARG, if iterator or dst are NULL; 332 * ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; 333 * or one of error codes from lower-level flash driver. 334 */ 335 esp_err_t esp_partition_erase_range(const esp_partition_t* partition, 336 size_t offset, size_t size); 337 338 /** 339 * @brief Configure MMU to map partition into data memory 340 * 341 * Unlike spi_flash_mmap function, which requires a 64kB aligned base address, 342 * this function doesn't impose such a requirement. 343 * If offset results in a flash address which is not aligned to 64kB boundary, 344 * address will be rounded to the lower 64kB boundary, so that mapped region 345 * includes requested range. 346 * Pointer returned via out_ptr argument will be adjusted to point to the 347 * requested offset (not necessarily to the beginning of mmap-ed region). 348 * 349 * To release mapped memory, pass handle returned via out_handle argument to 350 * spi_flash_munmap function. 351 * 352 * @param partition Pointer to partition structure obtained using 353 * esp_partition_find_first or esp_partition_get. 354 * Must be non-NULL. 355 * @param offset Offset from the beginning of partition where mapping should start. 356 * @param size Size of the area to be mapped. 357 * @param memory Memory space where the region should be mapped 358 * @param out_ptr Output, pointer to the mapped memory region 359 * @param out_handle Output, handle which should be used for spi_flash_munmap call 360 * 361 * @return ESP_OK, if successful 362 */ 363 esp_err_t esp_partition_mmap(const esp_partition_t* partition, size_t offset, size_t size, 364 spi_flash_mmap_memory_t memory, 365 const void** out_ptr, spi_flash_mmap_handle_t* out_handle); 366 367 /** 368 * @brief Get SHA-256 digest for required partition. 369 * 370 * For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app image content. 371 * The hash is verified before returning, if app content is invalid then the function returns ESP_ERR_IMAGE_INVALID. 372 * For apps without SHA-256 appended to the image, the result is the SHA-256 of all bytes in the app image. 373 * For other partition types, the result is the SHA-256 of the entire partition. 374 * 375 * @param[in] partition Pointer to info for partition containing app or data. (fields: address, size and type, are required to be filled). 376 * @param[out] sha_256 Returned SHA-256 digest for a given partition. 377 * 378 * @return 379 * - ESP_OK: In case of successful operation. 380 * - ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL. 381 * - ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation. 382 * - ESP_ERR_IMAGE_INVALID: App partition doesn't contain a valid app image. 383 * - ESP_FAIL: An allocation error occurred. 384 */ 385 esp_err_t esp_partition_get_sha256(const esp_partition_t *partition, uint8_t *sha_256); 386 387 /** 388 * @brief Check for the identity of two partitions by SHA-256 digest. 389 * 390 * @param[in] partition_1 Pointer to info for partition 1 containing app or data. (fields: address, size and type, are required to be filled). 391 * @param[in] partition_2 Pointer to info for partition 2 containing app or data. (fields: address, size and type, are required to be filled). 392 * 393 * @return 394 * - True: In case of the two firmware is equal. 395 * - False: Otherwise 396 */ 397 bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t *partition_2); 398 399 /** 400 * @brief Register a partition on an external flash chip 401 * 402 * This API allows designating certain areas of external flash chips (identified by the esp_flash_t structure) 403 * as partitions. This allows using them with components which access SPI flash through the esp_partition API. 404 * 405 * @param flash_chip Pointer to the structure identifying the flash chip 406 * @param offset Address in bytes, where the partition starts 407 * @param size Size of the partition in bytes 408 * @param label Partition name 409 * @param type One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applications can not be booted from external flash 410 * chips, so using ESP_PARTITION_TYPE_APP is not supported. 411 * @param subtype One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer. 412 * @param[out] out_partition Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure 413 * @return 414 * - ESP_OK on success 415 * - ESP_ERR_NOT_SUPPORTED if CONFIG_CONFIG_SPI_FLASH_USE_LEGACY_IMPL is enabled 416 * - ESP_ERR_NO_MEM if memory allocation has failed 417 * - ESP_ERR_INVALID_ARG if the new partition overlaps another partition on the same flash chip 418 * - ESP_ERR_INVALID_SIZE if the partition doesn't fit into the flash chip size 419 */ 420 esp_err_t esp_partition_register_external(esp_flash_t* flash_chip, size_t offset, size_t size, 421 const char* label, esp_partition_type_t type, esp_partition_subtype_t subtype, 422 const esp_partition_t** out_partition); 423 424 /** 425 * @brief Deregister the partition previously registered using esp_partition_register_external 426 * @param partition pointer to the partition structure obtained from esp_partition_register_external, 427 * @return 428 * - ESP_OK on success 429 * - ESP_ERR_NOT_FOUND if the partition pointer is not found 430 * - ESP_ERR_INVALID_ARG if the partition comes from the partition table 431 * - ESP_ERR_INVALID_ARG if the partition was not registered using 432 * esp_partition_register_external function. 433 */ 434 esp_err_t esp_partition_deregister_external(const esp_partition_t* partition); 435 436 #ifdef __cplusplus 437 } 438 #endif 439 440 441 #endif /* __ESP_PARTITION_H__ */ 442
