granicus.if.org Git - esp-idf/blob - components/spi_flash/include/esp_partition.h

   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_spi_flash.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file esp_partition.h
  30  * @brief Partition APIs
  31  */
  32
  33
  34 /**
  35  * @brief Partition type
  36  * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
  37  */
  38 typedef enum {
  39     ESP_PARTITION_TYPE_APP = 0x00,       //!< Application partition type
  40     ESP_PARTITION_TYPE_DATA = 0x01,      //!< Data partition type
  41 } esp_partition_type_t;
  42
  43 /**
  44  * @brief Partition subtype
  45  * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
  46  */
  47 typedef enum {
  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 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 16,//!< Max subtype of OTA partition
  67     ESP_PARTITION_SUBTYPE_APP_TEST = 0x20,                                    //!< Test application partition
  68
  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
  73
  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
  77
  78     ESP_PARTITION_SUBTYPE_ANY = 0xff,                                         //!< Used to search for partitions with any subtype
  79 } esp_partition_subtype_t;
  80
  81 /**
  82  * @brief Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition
  83  */
  84 #define ESP_PARTITION_SUBTYPE_OTA(i) ((esp_partition_subtype_t)(ESP_PARTITION_SUBTYPE_APP_OTA_MIN + ((i) & 0xf)))
  85
  86 /**
  87  * @brief Opaque partition iterator type
  88  */
  89 typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t;
  90
  91 /**
  92  * @brief partition information structure
  93  *
  94  * This is not the format in flash, that format is esp_partition_info_t.
  95  *
  96  * However, this is the format used by this API.
  97  */
  98 typedef struct {
  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 */
 105 } esp_partition_t;
 106
 107 /**
 108  * @brief Find partition based on one or more parameters
 109  *
 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.
 116  *
 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.
 121  */
 122 esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
 123
 124 /**
 125  * @brief Find first partition based on one or more parameters
 126  *
 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.
 133  *
 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.
 136  */
 137 const esp_partition_t* esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
 138
 139 /**
 140  * @brief Get esp_partition_t structure for given partition
 141  *
 142  * @param iterator  Iterator obtained using esp_partition_find. Must be non-NULL.
 143  *
 144  * @return pointer to esp_partition_t structure. This pointer is valid for the lifetime
 145  *         of the application.
 146  */
 147 const esp_partition_t* esp_partition_get(esp_partition_iterator_t iterator);
 148
 149 /**
 150  * @brief Move partition iterator to the next partition found
 151  *
 152  * Any copies of the iterator will be invalid after this call.
 153  *
 154  * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
 155  *
 156  * @return NULL if no partition was found, valid esp_partition_iterator_t otherwise.
 157  */
 158 esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator);
 159
 160 /**
 161  * @brief Release partition iterator
 162  *
 163  * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
 164  *
 165  */
 166 void esp_partition_iterator_release(esp_partition_iterator_t iterator);
 167
 168 /**
 169  * @brief Verify partition data
 170  *
 171  * Given a pointer to partition data, verify this partition exists in the partition table (all fields match.)
 172  *
 173  * This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the
 174  * permanent partition data stored in flash.
 175  *
 176  * Pointers returned from this function can be compared directly to the address of any pointer returned from
 177  * esp_partition_get(), as a test for equality.
 178  *
 179  * @param partition Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the
 180  * partition table entry in flash for this function to return a successful match.
 181  *
 182  * @return
 183  * - If partition not found, returns NULL.
 184  * - If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application.
 185  */
 186 const esp_partition_t *esp_partition_verify(const esp_partition_t *partition);
 187
 188 /**
 189  * @brief Read data from the partition
 190  *
 191  * @param partition Pointer to partition structure obtained using
 192  *                  esp_partition_find_first or esp_partition_get.
 193  *                  Must be non-NULL.
 194  * @param dst Pointer to the buffer where data should be stored.
 195  *            Pointer must be non-NULL and buffer must be at least 'size' bytes long.
 196  * @param src_offset Address of the data to be read, relative to the
 197  *                   beginning of the partition.
 198  * @param size Size of data to be read, in bytes.
 199  *
 200  * @return ESP_OK, if data was read successfully;
 201  *         ESP_ERR_INVALID_ARG, if src_offset exceeds partition size;
 202  *         ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition;
 203  *         or one of error codes from lower-level flash driver.
 204  */
 205 esp_err_t esp_partition_read(const esp_partition_t* partition,
 206                              size_t src_offset, void* dst, size_t size);
 207
 208 /**
 209  * @brief Write data to the partition
 210  *
 211  * Before writing data to flash, corresponding region of flash needs to be erased.
 212  * This can be done using esp_partition_erase_range function.
 213  *
 214  * Partitions marked with an encryption flag will automatically be
 215  * written via the spi_flash_write_encrypted() function. If writing to
 216  * an encrypted partition, all write offsets and lengths must be
 217  * multiples of 16 bytes. See the spi_flash_write_encrypted() function
 218  * for more details. Unencrypted partitions do not have this
 219  * restriction.
 220  *
 221  * @param partition Pointer to partition structure obtained using
 222  *                  esp_partition_find_first or esp_partition_get.
 223  *                  Must be non-NULL.
 224  * @param dst_offset Address where the data should be written, relative to the
 225  *                   beginning of the partition.
 226  * @param src Pointer to the source buffer.  Pointer must be non-NULL and
 227  *            buffer must be at least 'size' bytes long.
 228  * @param size Size of data to be written, in bytes.
 229  *
 230  * @note Prior to writing to flash memory, make sure it has been erased with
 231  *       esp_partition_erase_range call.
 232  *
 233  * @return ESP_OK, if data was written successfully;
 234  *         ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size;
 235  *         ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition;
 236  *         or one of error codes from lower-level flash driver.
 237  */
 238 esp_err_t esp_partition_write(const esp_partition_t* partition,
 239                              size_t dst_offset, const void* src, size_t size);
 240
 241 /**
 242  * @brief Erase part of the partition
 243  *
 244  * @param partition Pointer to partition structure obtained using
 245  *                  esp_partition_find_first or esp_partition_get.
 246  *                  Must be non-NULL.
 247  * @param start_addr Address where erase operation should start. Must be aligned
 248  *                   to 4 kilobytes.
 249  * @param size Size of the range which should be erased, in bytes.
 250  *                   Must be divisible by 4 kilobytes.
 251  *
 252  * @return ESP_OK, if the range was erased successfully;
 253  *         ESP_ERR_INVALID_ARG, if iterator or dst are NULL;
 254  *         ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition;
 255  *         or one of error codes from lower-level flash driver.
 256  */
 257 esp_err_t esp_partition_erase_range(const esp_partition_t* partition,
 258                                     uint32_t start_addr, uint32_t size);
 259
 260 /**
 261  * @brief Configure MMU to map partition into data memory
 262  *
 263  * Unlike spi_flash_mmap function, which requires a 64kB aligned base address,
 264  * this function doesn't impose such a requirement.
 265  * If offset results in a flash address which is not aligned to 64kB boundary,
 266  * address will be rounded to the lower 64kB boundary, so that mapped region
 267  * includes requested range.
 268  * Pointer returned via out_ptr argument will be adjusted to point to the
 269  * requested offset (not necessarily to the beginning of mmap-ed region).
 270  *
 271  * To release mapped memory, pass handle returned via out_handle argument to
 272  * spi_flash_munmap function.
 273  *
 274  * @param partition Pointer to partition structure obtained using
 275  *                  esp_partition_find_first or esp_partition_get.
 276  *                  Must be non-NULL.
 277  * @param offset Offset from the beginning of partition where mapping should start.
 278  * @param size Size of the area to be mapped.
 279  * @param memory  Memory space where the region should be mapped
 280  * @param out_ptr  Output, pointer to the mapped memory region
 281  * @param out_handle  Output, handle which should be used for spi_flash_munmap call
 282  *
 283  * @return ESP_OK, if successful
 284  */
 285 esp_err_t esp_partition_mmap(const esp_partition_t* partition, uint32_t offset, uint32_t size,
 286                              spi_flash_mmap_memory_t memory,
 287                              const void** out_ptr, spi_flash_mmap_handle_t* out_handle);
 288
 289
 290 #ifdef __cplusplus
 291 }
 292 #endif
 293
 294
 295 #endif /* __ESP_PARTITION_H__ */