Line data Source code
1 1 : /* 2 : * Copyright (c) 2017, 2020 Nordic Semiconductor ASA 3 : * Copyright (c) 2017 Linaro Limited 4 : * 5 : * SPDX-License-Identifier: Apache-2.0 6 : */ 7 : 8 : /** 9 : * @file 10 : * @brief Public API for stream writes to flash 11 : */ 12 : 13 : #ifndef ZEPHYR_INCLUDE_STORAGE_STREAM_FLASH_H_ 14 : #define ZEPHYR_INCLUDE_STORAGE_STREAM_FLASH_H_ 15 : 16 : /** 17 : * @brief Abstraction over stream writes to flash 18 : * 19 : * @defgroup stream_flash Stream to flash interface 20 : * @since 2.3 21 : * @version 0.1.0 22 : * @ingroup storage_apis 23 : * @{ 24 : */ 25 : 26 : #include <stdbool.h> 27 : #include <zephyr/drivers/flash.h> 28 : 29 : #ifdef __cplusplus 30 : extern "C" { 31 : #endif 32 : 33 : /** 34 : * @typedef stream_flash_callback_t 35 : * 36 : * @brief Signature for callback invoked after flash write completes. 37 : * 38 : * @details Functions of this type are invoked with a buffer containing 39 : * data read back from the flash after a flash write has completed. 40 : * This enables verifying that the data has been correctly stored (for 41 : * instance by using a SHA function). The write buffer 'buf' provided in 42 : * stream_flash_init is used as a read buffer for this purpose. 43 : * 44 : * @param buf Pointer to the data read. 45 : * @param len The length of the data read. 46 : * @param offset The offset the data was read from. 47 : */ 48 1 : typedef int (*stream_flash_callback_t)(uint8_t *buf, size_t len, size_t offset); 49 : 50 : /** 51 : * @brief Structure for stream flash context 52 : * 53 : * Users should treat these structures as opaque values and only interact 54 : * with them through the below API. 55 : */ 56 1 : struct stream_flash_ctx { 57 0 : uint8_t *buf; /* Write buffer */ 58 0 : size_t buf_len; /* Length of write buffer */ 59 0 : size_t buf_bytes; /* Number of bytes currently stored in write buf */ 60 0 : const struct device *fdev; /* Flash device */ 61 0 : size_t bytes_written; /* Number of bytes written to flash */ 62 0 : size_t offset; /* Offset from base of flash device to write area */ 63 0 : size_t available; /* Available bytes in write area */ 64 : #ifdef CONFIG_STREAM_FLASH_POST_WRITE_CALLBACK 65 : stream_flash_callback_t callback; /* Callback invoked after write op */ 66 : #endif 67 : #ifdef CONFIG_STREAM_FLASH_ERASE 68 : off_t last_erased_page_start_offset; /* Last erased offset */ 69 : #endif 70 0 : size_t write_block_size; /* Offset/size device write alignment */ 71 0 : uint8_t erase_value; 72 : }; 73 : 74 : /** 75 : * @brief Initialize context needed for stream writes to flash. 76 : * 77 : * @param ctx context to be initialized 78 : * @param fdev Flash device to operate on 79 : * @param buf Write buffer 80 : * @param buf_len Length of write buffer. Can not be larger than the page size. 81 : * Must be multiple of the flash device write-block-size. 82 : * @param offset Offset within flash device to start writing to 83 : * @param size Number of bytes available for performing buffered write. 84 : * If this is '0', the size will be set to the total size 85 : * of the flash device minus the offset. 86 : * @param cb Callback to be invoked on completed flash write operations. 87 : * Callback is supported when CONFIG_STREAM_FLASH_POST_WRITE_CALLBACK 88 : * is enabled. 89 : * 90 : * @return non-negative on success, negative errno code on fail 91 : */ 92 1 : int stream_flash_init(struct stream_flash_ctx *ctx, const struct device *fdev, 93 : uint8_t *buf, size_t buf_len, size_t offset, size_t size, 94 : stream_flash_callback_t cb); 95 : /** 96 : * @brief Read number of bytes written to the flash. 97 : * 98 : * @note api-tags: pre-kernel-ok isr-ok 99 : * 100 : * @param ctx context 101 : * 102 : * @return Number of payload bytes written to flash. 103 : */ 104 1 : size_t stream_flash_bytes_written(const struct stream_flash_ctx *ctx); 105 : 106 : /** 107 : * @brief Process input buffers to be written to flash device in single blocks. 108 : * Will store remainder between calls. 109 : * 110 : * A write with the @p flush set to true has to be issued as the last 111 : * write request for a given context, as it concludes write of a stream, 112 : * and flushes buffers to storage device. 113 : * 114 : * @warning There must not be any additional write requests issued for a flushed context, 115 : * unless it is re-initialized, as such write attempts may result in the function 116 : * failing and returning error. 117 : * Once context has been flushed, it can be re-initialized and re-used for new 118 : * stream flash session. 119 : * 120 : * @param ctx context 121 : * @param data data to write 122 : * @param len Number of bytes to write 123 : * @param flush when true this forces any buffered data to be written to flash 124 : * 125 : * @return non-negative on success, negative errno code on fail 126 : */ 127 1 : int stream_flash_buffered_write(struct stream_flash_ctx *ctx, const uint8_t *data, 128 : size_t len, bool flush); 129 : 130 : /** 131 : * @brief Erase the flash page to which a given offset belongs. 132 : * 133 : * This function erases a flash page to which an offset belongs if this page 134 : * is not the page previously erased by the provided ctx 135 : * (ctx->last_erased_page_start_offset). 136 : * 137 : * @param ctx context 138 : * @param off offset from the base address of the flash device 139 : * 140 : * @return non-negative on success, negative errno code on fail 141 : */ 142 1 : int stream_flash_erase_page(struct stream_flash_ctx *ctx, off_t off); 143 : 144 : /** 145 : * @brief Load persistent stream write progress stored with key 146 : * @p settings_key . 147 : * 148 : * This function should be called directly after @ref stream_flash_init to 149 : * load previous stream write progress before writing any data. If the loaded 150 : * progress has fewer bytes written than @p ctx then it will be ignored. 151 : * 152 : * @param ctx context 153 : * @param settings_key key to use with the settings module for loading 154 : * the stream write progress 155 : * 156 : * @return non-negative on success, -ERANGE in case when @p off is out 157 : * of area designated for stream or negative errno code on fail 158 : */ 159 1 : int stream_flash_progress_load(struct stream_flash_ctx *ctx, 160 : const char *settings_key); 161 : 162 : /** 163 : * @brief Save persistent stream write progress using key @p settings_key . 164 : * 165 : * @param ctx context 166 : * @param settings_key key to use with the settings module for storing 167 : * the stream write progress 168 : * 169 : * @return non-negative on success, negative errno code on fail 170 : */ 171 1 : int stream_flash_progress_save(const struct stream_flash_ctx *ctx, 172 : const char *settings_key); 173 : 174 : /** 175 : * @brief Clear persistent stream write progress stored with key 176 : * @p settings_key . 177 : * 178 : * @param ctx context 179 : * @param settings_key key previously used for storing the stream write progress 180 : * 181 : * @return non-negative on success, negative errno code on fail 182 : */ 183 1 : int stream_flash_progress_clear(const struct stream_flash_ctx *ctx, 184 : const char *settings_key); 185 : 186 : #ifdef __cplusplus 187 : } 188 : #endif 189 : 190 : /** 191 : * @} 192 : */ 193 : 194 : #endif /* ZEPHYR_INCLUDE_STORAGE_STREAM_FLASH_H_ */
