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 typedef enum {
  29     ESP_PARTITION_APP_MASK = 0x0000,
  30     ESP_PARTITION_APP_FACTORY = ESP_PARTITION_APP_MASK | 0x00,
  31     ESP_PARTITION_APP_OTA_MIN = ESP_PARTITION_APP_MASK | 0x10,
  32     ESP_PARTITION_APP_OTA_0 = ESP_PARTITION_APP_OTA_MIN + 0,
  33     ESP_PARTITION_APP_OTA_1 = ESP_PARTITION_APP_OTA_MIN + 1,
  34     ESP_PARTITION_APP_OTA_2 = ESP_PARTITION_APP_OTA_MIN + 2,
  35     ESP_PARTITION_APP_OTA_3 = ESP_PARTITION_APP_OTA_MIN + 3,
  36     ESP_PARTITION_APP_OTA_4 = ESP_PARTITION_APP_OTA_MIN + 4,
  37     ESP_PARTITION_APP_OTA_5 = ESP_PARTITION_APP_OTA_MIN + 5,
  38     ESP_PARTITION_APP_OTA_6 = ESP_PARTITION_APP_OTA_MIN + 6,
  39     ESP_PARTITION_APP_OTA_7 = ESP_PARTITION_APP_OTA_MIN + 7,
  40     ESP_PARTITION_APP_OTA_8 = ESP_PARTITION_APP_OTA_MIN + 8,
  41     ESP_PARTITION_APP_OTA_9 = ESP_PARTITION_APP_OTA_MIN + 9,
  42     ESP_PARTITION_APP_OTA_10 = ESP_PARTITION_APP_OTA_MIN + 10,
  43     ESP_PARTITION_APP_OTA_11 = ESP_PARTITION_APP_OTA_MIN + 11,
  44     ESP_PARTITION_APP_OTA_12 = ESP_PARTITION_APP_OTA_MIN + 12,
  45     ESP_PARTITION_APP_OTA_13 = ESP_PARTITION_APP_OTA_MIN + 13,
  46     ESP_PARTITION_APP_OTA_14 = ESP_PARTITION_APP_OTA_MIN + 14,
  47     ESP_PARTITION_APP_OTA_15 = ESP_PARTITION_APP_OTA_MIN + 15,
  48     ESP_PARTITION_APP_OTA_MAX = ESP_PARTITION_APP_MASK | 0x1f,
  49     ESP_PARTITION_APP_TEST = ESP_PARTITION_APP_MASK | 0x20,
  50     ESP_PARTITION_APP_ANY = ESP_PARTITION_APP_MASK | 0xff,
  51
  52     ESP_PARTITION_DATA_MASK = 0x0100,
  53     ESP_PARTITION_DATA_OTA = ESP_PARTITION_DATA_MASK | 0x00,
  54     ESP_PARTITION_DATA_RF = ESP_PARTITION_DATA_MASK | 0x01,
  55     ESP_PARTITION_DATA_WIFI = ESP_PARTITION_DATA_MASK | 0x02,
  56     ESP_PARTITION_DATA_ANY = ESP_PARTITION_DATA_MASK | 0xff,
  57
  58     ESP_PARTITION_FILESYSTEM_MASK = 0x0200,
  59     ESP_PARTITION_FILESYSTEM_ESPHTTPD = 0x0200,
  60     ESP_PARTITION_FILESYSTEM_FAT = 0x0201,
  61     ESP_PARTITION_FILESYSTEM_SPIFFS = 0x0202,
  62     ESP_PARTITION_FILESYSTEM_ANY = 0x20ff,
  63
  64     ESP_PARTITION_END = 0xffff
  65 } esp_partition_type_t;
  66
  67 #define ESP_PARTITION_APP_OTA(i) ((esp_partition_type_t)(ESP_PARTITION_APP_OTA_MIN + ((i) & 0xf)))
  68
  69
  70 typedef struct esp_partition_iterator_opaque_* esp_partition_iterator_t;
  71
  72 typedef struct {
  73     esp_partition_type_t type;
  74     uint32_t address;
  75     uint32_t size;
  76     char label[17];
  77     bool encrypted;
  78 } esp_partition_t;
  79
  80 /**
  81  * @brief Find partition based on one or more parameters
  82  *
  83  * @param type Partition type, one of esp_partition_type_t values
  84  *             To find all app partitions or all filesystem partitions,
  85  *             use ESP_PARTITION_APP_ANY or ESP_PARTITION_FILESYSTEM_ANY,
  86  *             respectively.
  87  * @param label (optional) Partition label. Set this value if looking
  88  *             for partition with a specific name. Pass NULL otherwise.
  89  *
  90  * @return iterator which can be used to enumerate all the partitions found,
  91  *         or NULL if no partitions were found.
  92  *         Iterator obtained through this function has to be released
  93  *         using esp_partition_iterator_release when not used any more.
  94  */
  95 esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, const char* label);
  96
  97 /**
  98  * @brief Find first partition based on one or more parameters
  99  *
 100  * @param type Partition type, one of esp_partition_type_t values
 101  *             To find all app partitions or all filesystem partitions,
 102  *             use ESP_PARTITION_APP_ANY or ESP_PARTITION_FILESYSTEM_ANY,
 103  *             respectively.
 104  * @param label (optional) Partition label. Set this value if looking
 105  *             for partition with a specific name. Pass NULL otherwise.
 106  *
 107  * @return pointer to esp_partition_t structure, or NULL if no parition is found.
 108  *         This pointer is valid for the lifetime of the application.
 109  */
 110 const esp_partition_t* esp_partition_find_first(esp_partition_type_t type, const char* label);
 111
 112 /**
 113  * @brief Get esp_partition_t structure for given partition
 114  *
 115  * @param iterator  Iterator obtained using esp_partition_find. Must be non-NULL.
 116  *
 117  * @return pointer to esp_partition_t structure. This pointer is valid for the lifetime
 118  *         of the application.
 119  */
 120 const esp_partition_t* esp_partition_get(esp_partition_iterator_t iterator);
 121
 122 /**
 123  * @brief Move partition iterator to the next partition found
 124  *
 125  * Any copies of the iterator will be invalid after this call.
 126  *
 127  * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
 128  *
 129  * @return NULL if no partition was found, valid esp_partition_iterator_t otherwise.
 130  */
 131 esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator);
 132
 133 /**
 134  * @brief Release partition iterator
 135  *
 136  * Any pointers obtained using esp_partition_label function will be invalid
 137  * after this call.
 138  *
 139  * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL.
 140  *
 141  */
 142 void esp_partition_iterator_release(esp_partition_iterator_t iterator);
 143
 144 /**
 145  * @brief Read data from the partition
 146  *
 147  * @param partition Pointer to partition structure obtained using
 148  *                  esp_partition_find_first or esp_partition_get.
 149  *                  Must be non-NULL.
 150  * @param dst Pointer to the buffer where data should be stored.
 151  *            Pointer must be non-NULL and buffer must be at least 'size' bytes long.
 152  * @param src_offset Address of the data to be read, relative to the
 153  *                   beginning of the partition.
 154  * @param size Size of data to be read, in bytes.
 155  *
 156  * @return ESP_OK, if data was read successfully;
 157  *         ESP_ERR_INVALID_ARG, if iterator or src are NULL;
 158  *         ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition;
 159  *         or one of error codes from lower-level flash driver.
 160  */
 161 esp_err_t esp_partition_read(const esp_partition_t* partition,
 162                              size_t src_offset, void* dst, size_t size);
 163
 164 /**
 165  * @brief Write data to the partition
 166  *
 167  * Before writing data to flash, corresponding region of flash needs to be erased.
 168  * This can be done using esp_partition_erase_range function.
 169  *
 170  * @param partition Pointer to partition structure obtained using
 171  *                  esp_partition_find_first or esp_partition_get.
 172  *                  Must be non-NULL.
 173  * @param dst_offset Address where the data should be written, relative to the
 174  *                   beginning of the partition.
 175  * @param src Pointer to the source buffer.  Pointer must be non-NULL and
 176  *            buffer must be at least 'size' bytes long.
 177  * @param size Size of data to be written, in bytes.
 178  *
 179  * @note Prior to writing to flash memory, make sure it has been erased with
 180  *       esp_partition_erase_range call.
 181  *
 182  * @return ESP_OK, if data was written successfully;
 183  *         ESP_ERR_INVALID_ARG, if iterator or dst are NULL;
 184  *         ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition;
 185  *         or one of error codes from lower-level flash driver.
 186  */
 187 esp_err_t esp_partition_write(const esp_partition_t* partition,
 188                              size_t dst_offset, const void* src, size_t size);
 189
 190 /**
 191  * @brief Erase part of the partition
 192  *
 193  * @param partition Pointer to partition structure obtained using
 194  *                  esp_partition_find_first or esp_partition_get.
 195  *                  Must be non-NULL.
 196  * @param start_addr Address where erase operation should start. Must be aligned
 197  *                   to 4 kilobytes.
 198  * @param size Size of the range which should be erased, in bytes.
 199  *                   Must be divisible by 4 kilobytes.
 200  *
 201  * @return ESP_OK, if the range was erased successfully;
 202  *         ESP_ERR_INVALID_ARG, if iterator or dst are NULL;
 203  *         ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition;
 204  *         or one of error codes from lower-level flash driver.
 205  */
 206 esp_err_t esp_partition_erase_range(const esp_partition_t* partition,
 207                                     uint32_t start_addr, uint32_t size);
 208
 209 /**
 210  * @brief Configure MMU to map partition into data memory
 211  *
 212  * Unlike spi_flash_mmap function, which requires a 64kB aligned base address,
 213  * this function doesn't impose such a requirement.
 214  * If offset results in a flash address which is not aligned to 64kB boundary,
 215  * address will be rounded to the lower 64kB boundary, so that mapped region
 216  * includes requested range.
 217  * Pointer returned via out_ptr argument will be adjusted to point to the
 218  * requested offset (not necessarily to the beginning of mmap-ed region).
 219  *
 220  * To release mapped memory, pass handle returned via out_handle argument to
 221  * spi_flash_munmap function.
 222  *
 223  * @param partition Pointer to partition structure obtained using
 224  *                  esp_partition_find_first or esp_partition_get.
 225  *                  Must be non-NULL.
 226  * @param offset Offset from the beginning of partition where mapping should start.
 227  * @param size Size of the area to be mapped.
 228  * @param memory  Memory space where the region should be mapped
 229  * @param out_ptr  Output, pointer to the mapped memory region
 230  * @param out_handle  Output, handle which should be used for spi_flash_munmap call
 231  *
 232  * @return ESP_OK, if successful
 233  */
 234 esp_err_t esp_partition_mmap(const esp_partition_t* partition, uint32_t offset, uint32_t size,
 235                              spi_flash_mmap_memory_t memory,
 236                              const void** out_ptr, spi_flash_mmap_handle_t* out_handle);
 237
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243
 244 #endif /* __ESP_PARTITION_H__ */