From: Ivan Grokhotkov Date: Thu, 8 Sep 2016 11:18:03 +0000 (+0800) Subject: components/spi_flash: add high level partition api header X-Git-Tag: v1.0~98^2~12 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f6f23141b35dd3fbcf7fe4522766e732ea92df61;p=esp-idf components/spi_flash: add high level partition api header TW6701 --- diff --git a/components/spi_flash/include/esp_partition.h b/components/spi_flash/include/esp_partition.h new file mode 100644 index 0000000000..fd1223da51 --- /dev/null +++ b/components/spi_flash/include/esp_partition.h @@ -0,0 +1,211 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#ifndef __ESP_PARTITION_H__ +#define __ESP_PARTITION_H__ + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +enum esp_partition_type_t { + PT_APP_MASK = 0x0000, + PT_APP_FACTORY = PT_APP_MASK | 0x00, + PT_APP_OTA_MIN = PT_APP_MASK | 0x10, + PT_APP_OTA_0 = PT_APP_OTA_MIN + 0, + PT_APP_OTA_1 = PT_APP_OTA_MIN + 1, + PT_APP_OTA_2 = PT_APP_OTA_MIN + 2, + PT_APP_OTA_3 = PT_APP_OTA_MIN + 3, + PT_APP_OTA_4 = PT_APP_OTA_MIN + 4, + PT_APP_OTA_5 = PT_APP_OTA_MIN + 5, + PT_APP_OTA_6 = PT_APP_OTA_MIN + 6, + PT_APP_OTA_7 = PT_APP_OTA_MIN + 7, + PT_APP_OTA_8 = PT_APP_OTA_MIN + 8, + PT_APP_OTA_9 = PT_APP_OTA_MIN + 9, + PT_APP_OTA_10 = PT_APP_OTA_MIN + 10, + PT_APP_OTA_11 = PT_APP_OTA_MIN + 11, + PT_APP_OTA_12 = PT_APP_OTA_MIN + 12, + PT_APP_OTA_13 = PT_APP_OTA_MIN + 13, + PT_APP_OTA_14 = PT_APP_OTA_MIN + 14, + PT_APP_OTA_15 = PT_APP_OTA_MIN + 15, + PT_APP_OTA_MAX = PT_APP_MASK | 0x1f, + PT_APP_TEST = PT_APP_MASK | 0x20, + PT_APP_ANY = PT_APP_MASK | 0xff, + + PT_DATA_MASK = 0x0100, + PT_DATA_OTA = PT_DATA_MASK | 0x00, + PT_DATA_RF = PT_DATA_MASK | 0x01, + PT_DATA_WIFI = PT_DATA_MASK | 0x02, + PT_DATA_ANY = PT_DATA_MASK | 0xff, + + PT_FILESYSTEM_MASK = 0x0200, + PT_FILESYSTEM_ESPHTTPD = 0x0200, + PT_FILESYSTEM_FAT = 0x0201, + PT_FILESYSTEM_SPIFFS = 0x0202, + PT_FILESYSTEM_ANY = 0x20ff, + + PT_END = 0xffff +}; + +#define PT_APP_OTA(i) ((esp_partition_type_t)(PT_APP_OTA_MIN + ((i) & 0xf))) + + +typedef struct esp_partition_iterator_opaque_t* esp_partition_iterator_t; + +/** + * @brief Find partition based on one or more parameters + * + * @param type Partition type, one of esp_partition_type_t values + * To find all app partitions or all filesystem partitions, + * use PT_APP_ANY or PT_FILESYSTEM_ANY, respectively. + * @param label (optional) Partition label. Set this value if looking + * for partition with a specific name. Pass NULL otherwise. + * + * @return iterator which can be used to enumerate all the partitions found, + * or NULL if no partitions were found. + * Iterator obtained through this function has to be released + * using esp_partition_iterator_release when not used any more. + */ +esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, const char* label); + + +/** + * @brief Move partition iterator to the next partition found + * + * Any pointers obtained using esp_partition_label function for this iterator + * will be invalid after this call. + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + * @return iterator pointing to the next partition found, or NULL if no more + * partitions were found. + * + */ +esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator); + +/** + * @brief Get partition type + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + * @return esp_partition_type_t value for partition pointed to by the iterator. + */ +esp_partition_type_t esp_partition_type(esp_partition_iterator_t iterator); + +/** + * @brief Get partition size + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + * @return partition size, in bytes + */ +uint32_t esp_partition_size(esp_partition_iterator_t iterator); + +/** + * @brief Get partition address + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + * @return flash address of partition start + */ +uint32_t esp_partition_address(esp_partition_iterator_t iterator); + +/** + * @brief Get partition label + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + * @return pointer to a zero-terminated string with partition label. + * The pointer is valid until the call to esp_partition_next or + * esp_partition_iterator_release for the given iterator. + */ +const char* esp_partition_label(esp_partition_iterator_t iterator); + +/** + * @brief Read data from the partition + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * @param src_offset Address of the data to be read, relative to the + * beginning of the partition. + * @param dst Pointer to the buffer where data should be stored. + * Must be non-NULL and at least 'size' bytes long. + * @param size Size of data to be read, in bytes. + * + * @return ESP_OK, if data was read successfully; + * ESP_INVALID_ARG, if iterator or src are NULL; + * ESP_INVALID_SIZE, if read would go out of bounds of the partition; + * or one of error codes from lower-level flash driver. + */ +esp_err_t esp_partition_read(esp_partition_iterator_t iterator, + uint32_t src_offset, uint8_t* dst, uint32_t size); + +/** + * @brief Write data to the partition + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * @param src Pointer to the source buffer. Must be non-NULL and + * at least 'size' bytes long. + * @param dst_offset Address where the data should be written, relative to the + * beginning of the partition. + * @param size Size of data to be written, in bytes. + * + * @note Prior to writing to flash memory, make sure it has been erased with + * esp_partition_erase_range call. + * + * @return ESP_OK, if data was written successfully; + * ESP_INVALID_ARG, if iterator or dst are NULL; + * ESP_INVALID_SIZE, if write would go out of bounds of the partition; + * or one of error codes from lower-level flash driver. + */ +esp_err_t esp_partition_write(esp_partition_iterator_t iterator, + const uint8_t* src, uint32_t dst_offset, uint32_t size); + +/** + * @brief Erase part of the partition + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * @param start_addr Address where erase operation should start. Must be aligned + * to 4 kilobytes. + * @param size Size of the range which should be erased, in bytes. + * Must be divisible by 4 kilobytes. + * + * @return ESP_OK, if the range was erased successfully; + * ESP_INVALID_ARG, if iterator or dst are NULL; + * ESP_INVALID_SIZE, if erase would go out of bounds of the partition; + * or one of error codes from lower-level flash driver. + */ +esp_err_t esp_partition_erase_range(esp_partition_iterator_t iterator, + uint32_t start_addr, uint32_t size); + + +/** + * @brief Release partition iterator + * + * Any pointers obtained using esp_partition_label function will be invalid + * after this call. + * + * @param iterator Iterator obtained using esp_partition_find. Must be non-NULL. + * + */ +void esp_partition_iterator_release(esp_partition_iterator_t iterator); + + +#ifdef __cplusplus +} +#endif + + +#endif /* __ESP_PARTITION_H__ */