1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
15 #ifndef __ESP_PARTITION_H__
16 #define __ESP_PARTITION_H__
22 #include "esp_spi_flash.h"
29 * @file esp_partition.h
30 * @brief Partition APIs
35 * @brief Partition type
36 * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
39 ESP_PARTITION_TYPE_APP = 0x00, //!< Application partition type
40 ESP_PARTITION_TYPE_DATA = 0x01, //!< Data partition type
41 } esp_partition_type_t;
44 * @brief Partition subtype
45 * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
48 ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00, //!< Factory application partition
49 ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10, //!< Base for OTA partition subtypes
50 ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0, //!< OTA partition 0
51 ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1, //!< OTA partition 1
52 ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2, //!< OTA partition 2
53 ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3, //!< OTA partition 3
54 ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4, //!< OTA partition 4
55 ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5, //!< OTA partition 5
56 ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6, //!< OTA partition 6
57 ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7, //!< OTA partition 7
58 ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8, //!< OTA partition 8
59 ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9, //!< OTA partition 9
60 ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10,//!< OTA partition 10
61 ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11,//!< OTA partition 11
62 ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12,//!< OTA partition 12
63 ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13,//!< OTA partition 13
64 ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14,//!< OTA partition 14
65 ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15,//!< OTA partition 15
66 ESP_PARTITION_SUBTYPE_APP_OTA_MAX = 15, //!< Max subtype of OTA partition
67 ESP_PARTITION_SUBTYPE_APP_TEST = 0x20, //!< Test application partition
69 ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00, //!< OTA selection partition
70 ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01, //!< PHY init data partition
71 ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02, //!< NVS partition
72 ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03, //!< COREDUMP partition
74 ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80, //!< ESPHTTPD partition
75 ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81, //!< FAT partition
76 ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82, //!< SPIFFS partition
78 ESP_PARTITION_SUBTYPE_ANY = 0xff, //!< Used to search for partitions with any subtype
79 } esp_partition_subtype_t;
82 * @brief Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition
84 #define ESP_PARTITION_SUBTYPE_OTA(i) ((esp_partition_subtype_t)(ESP_PARTITION_SUBTYPE_APP_OTA_MIN + ((i) & 0xf)))
87 * @brief Opaque partition iterator type
89 typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t;
92 * @brief partition information structure
94 * This is not the format in flash, that format is esp_partition_info_t.
96 * However, this is the format used by this API.
99 esp_partition_type_t type; /*!< partition type (app/data) */
100 esp_partition_subtype_t subtype; /*!< partition subtype */
101 uint32_t address; /*!< starting address of the partition in flash */
102 uint32_t size; /*!< size of the partition, in bytes */
103 char label[17]; /*!< partition label, zero-terminated ASCII string */
104 bool encrypted; /*!< flag is set to true if partition is encrypted */
108 * @brief Find partition based on one or more parameters
110 * @param type Partition type, one of esp_partition_type_t values
111 * @param subtype Partition subtype, one of esp_partition_subtype_t values.
112 * To find all partitions of given type, use
113 * ESP_PARTITION_SUBTYPE_ANY.
114 * @param label (optional) Partition label. Set this value if looking
115 * for partition with a specific name. Pass NULL otherwise.
117 * @return iterator which can be used to enumerate all the partitions found,
118 * or NULL if no partitions were found.
119 * Iterator obtained through this function has to be released
120 * using esp_partition_iterator_release when not used any more.
122 esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
125 * @brief Find first partition based on one or more parameters
127 * @param type Partition type, one of esp_partition_type_t values
128 * @param subtype Partition subtype, one of esp_partition_subtype_t values.
129 * To find all partitions of given type, use
130 * ESP_PARTITION_SUBTYPE_ANY.
131 * @param label (optional) Partition label. Set this value if looking
132 * for partition with a specific name. Pass NULL otherwise.
134 * @return pointer to esp_partition_t structure, or NULL if no partition is found.
135 * This pointer is valid for the lifetime of the application.
137 const esp_partition_t* esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
140 * @brief Get esp_partition_t structure for given partition
142 * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
144 * @return pointer to esp_partition_t structure. This pointer is valid for the lifetime
145 * of the application.
147 const esp_partition_t* esp_partition_get(esp_partition_iterator_t iterator);
150 * @brief Move partition iterator to the next partition found
152 * Any copies of the iterator will be invalid after this call.
154 * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
156 * @return NULL if no partition was found, valid esp_partition_iterator_t otherwise.
158 esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator);
161 * @brief Release partition iterator
163 * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
166 void esp_partition_iterator_release(esp_partition_iterator_t iterator);
169 * @brief Read data from the partition
171 * @param partition Pointer to partition structure obtained using
172 * esp_partition_find_first or esp_partition_get.
174 * @param dst Pointer to the buffer where data should be stored.
175 * Pointer must be non-NULL and buffer must be at least 'size' bytes long.
176 * @param src_offset Address of the data to be read, relative to the
177 * beginning of the partition.
178 * @param size Size of data to be read, in bytes.
180 * @return ESP_OK, if data was read successfully;
181 * ESP_ERR_INVALID_ARG, if src_offset exceeds partition size;
182 * ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition;
183 * or one of error codes from lower-level flash driver.
185 esp_err_t esp_partition_read(const esp_partition_t* partition,
186 size_t src_offset, void* dst, size_t size);
189 * @brief Write data to the partition
191 * Before writing data to flash, corresponding region of flash needs to be erased.
192 * This can be done using esp_partition_erase_range function.
194 * @param partition Pointer to partition structure obtained using
195 * esp_partition_find_first or esp_partition_get.
197 * @param dst_offset Address where the data should be written, relative to the
198 * beginning of the partition.
199 * @param src Pointer to the source buffer. Pointer must be non-NULL and
200 * buffer must be at least 'size' bytes long.
201 * @param size Size of data to be written, in bytes.
203 * @note Prior to writing to flash memory, make sure it has been erased with
204 * esp_partition_erase_range call.
206 * @return ESP_OK, if data was written successfully;
207 * ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size;
208 * ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition;
209 * or one of error codes from lower-level flash driver.
211 esp_err_t esp_partition_write(const esp_partition_t* partition,
212 size_t dst_offset, const void* src, size_t size);
215 * @brief Erase part of the partition
217 * @param partition Pointer to partition structure obtained using
218 * esp_partition_find_first or esp_partition_get.
220 * @param start_addr Address where erase operation should start. Must be aligned
222 * @param size Size of the range which should be erased, in bytes.
223 * Must be divisible by 4 kilobytes.
225 * @return ESP_OK, if the range was erased successfully;
226 * ESP_ERR_INVALID_ARG, if iterator or dst are NULL;
227 * ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition;
228 * or one of error codes from lower-level flash driver.
230 esp_err_t esp_partition_erase_range(const esp_partition_t* partition,
231 uint32_t start_addr, uint32_t size);
234 * @brief Configure MMU to map partition into data memory
236 * Unlike spi_flash_mmap function, which requires a 64kB aligned base address,
237 * this function doesn't impose such a requirement.
238 * If offset results in a flash address which is not aligned to 64kB boundary,
239 * address will be rounded to the lower 64kB boundary, so that mapped region
240 * includes requested range.
241 * Pointer returned via out_ptr argument will be adjusted to point to the
242 * requested offset (not necessarily to the beginning of mmap-ed region).
244 * To release mapped memory, pass handle returned via out_handle argument to
245 * spi_flash_munmap function.
247 * @param partition Pointer to partition structure obtained using
248 * esp_partition_find_first or esp_partition_get.
250 * @param offset Offset from the beginning of partition where mapping should start.
251 * @param size Size of the area to be mapped.
252 * @param memory Memory space where the region should be mapped
253 * @param out_ptr Output, pointer to the mapped memory region
254 * @param out_handle Output, handle which should be used for spi_flash_munmap call
256 * @return ESP_OK, if successful
258 esp_err_t esp_partition_mmap(const esp_partition_t* partition, uint32_t offset, uint32_t size,
259 spi_flash_mmap_memory_t memory,
260 const void** out_ptr, spi_flash_mmap_handle_t* out_handle);
268 #endif /* __ESP_PARTITION_H__ */