1 // Copyright 2015-2017 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 _wear_levelling_H_ 16 #define _wear_levelling_H_ 17 18 #include "esp_log.h" 19 #include "esp_partition.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief wear levelling handle 27 */ 28 typedef int32_t wl_handle_t; 29 30 #define WL_INVALID_HANDLE -1 31 32 /** 33 * @brief Mount WL for defined partition 34 * 35 * @param partition that will be used for access 36 * @param out_handle handle of the WL instance 37 * 38 * @return 39 * - ESP_OK, if the allocation was successfully; 40 * - ESP_ERR_INVALID_ARG, if WL allocation was unsuccessful; 41 * - ESP_ERR_NO_MEM, if there was no memory to allocate WL components; 42 */ 43 esp_err_t wl_mount(const esp_partition_t *partition, wl_handle_t *out_handle); 44 45 /** 46 * @brief Unmount WL for defined partition 47 * 48 * @param handle WL partition handle 49 * 50 * @return 51 * - ESP_OK, if the operation completed successfully; 52 * - or one of error codes from lower-level flash driver. 53 */ 54 esp_err_t wl_unmount(wl_handle_t handle); 55 56 /** 57 * @brief Erase part of the WL storage 58 * 59 * @param handle WL handle that are related to the partition 60 * @param start_addr Address where erase operation should start. Must be aligned 61 * to the result of function wl_sector_size(...). 62 * @param size Size of the range which should be erased, in bytes. 63 * Must be divisible by result of function wl_sector_size(...).. 64 * 65 * @return 66 * - ESP_OK, if the range was erased successfully; 67 * - ESP_ERR_INVALID_ARG, if iterator or dst are NULL; 68 * - ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; 69 * - or one of error codes from lower-level flash driver. 70 */ 71 esp_err_t wl_erase_range(wl_handle_t handle, size_t start_addr, size_t size); 72 73 /** 74 * @brief Write data to the WL storage 75 * 76 * Before writing data to flash, corresponding region of flash needs to be erased. 77 * This can be done using wl_erase_range function. 78 * 79 * @param handle WL handle that are related to the partition 80 * @param dest_addr Address where the data should be written, relative to the 81 * beginning of the partition. 82 * @param src Pointer to the source buffer. Pointer must be non-NULL and 83 * buffer must be at least 'size' bytes long. 84 * @param size Size of data to be written, in bytes. 85 * 86 * @note Prior to writing to WL storage, make sure it has been erased with 87 * wl_erase_range call. 88 * 89 * @return 90 * - ESP_OK, if data was written successfully; 91 * - ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; 92 * - ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; 93 * - or one of error codes from lower-level flash driver. 94 */ 95 esp_err_t wl_write(wl_handle_t handle, size_t dest_addr, const void *src, size_t size); 96 97 /** 98 * @brief Read data from the WL storage 99 * 100 * @param handle WL module instance that was initialized before 101 * @param dest Pointer to the buffer where data should be stored. 102 * Pointer must be non-NULL and buffer must be at least 'size' bytes long. 103 * @param src_addr Address of the data to be read, relative to the 104 * beginning of the partition. 105 * @param size Size of data to be read, in bytes. 106 * 107 * @return 108 * - ESP_OK, if data was read successfully; 109 * - ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; 110 * - ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; 111 * - or one of error codes from lower-level flash driver. 112 */ 113 esp_err_t wl_read(wl_handle_t handle, size_t src_addr, void *dest, size_t size); 114 115 /** 116 * @brief Get size of the WL storage 117 * 118 * @param handle WL module handle that was initialized before 119 * @return usable size, in bytes 120 */ 121 size_t wl_size(wl_handle_t handle); 122 123 /** 124 * @brief Get sector size of the WL instance 125 * 126 * @param handle WL module handle that was initialized before 127 * @return sector size, in bytes 128 */ 129 size_t wl_sector_size(wl_handle_t handle); 130 131 132 #ifdef __cplusplus 133 } // extern "C" 134 #endif 135 136 #endif // _wear_levelling_H_ 137
