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 : /** @cond INTERNAL_HIDDEN */
58 : uint8_t *buf; /* Write buffer */
59 : size_t buf_len; /* Length of write buffer */
60 : size_t buf_bytes; /* Number of bytes currently stored in write buf */
61 : const struct device *fdev; /* Flash device */
62 : size_t bytes_written; /* Number of bytes written to flash */
63 : size_t offset; /* Offset from base of flash device to write area */
64 : size_t available; /* Available bytes in write area */
65 : #ifdef CONFIG_STREAM_FLASH_POST_WRITE_CALLBACK
66 : stream_flash_callback_t callback; /* Callback invoked after write op */
67 : #endif
68 : #ifdef CONFIG_STREAM_FLASH_ERASE
69 : size_t erased_up_to; /* First offset in continuous range,
70 : * relative to the stream_flash_ctx.offset,
71 : * that has not yet been erased while
72 : * preparing Stream Flash designated area
73 : * for write.
74 : */
75 : #endif
76 : size_t write_block_size; /* Offset/size device write alignment */
77 : uint8_t erase_value;
78 : /** @endcond */
79 : };
80 :
81 : /**
82 : * @brief Initialize context needed for stream writes to flash.
83 : *
84 : * @param ctx context to be initialized
85 : * @param fdev Flash device to operate on
86 : * @param buf Write buffer
87 : * @param buf_len Length of write buffer. Can not be larger than the page size.
88 : * Must be multiple of the flash device write-block-size.
89 : * @param offset Offset within flash device to start writing to
90 : * @param size Number of bytes available for performing buffered write.
91 : * @param cb Callback to be invoked on completed flash write operations.
92 : * Callback is supported when CONFIG_STREAM_FLASH_POST_WRITE_CALLBACK
93 : * is enabled.
94 : *
95 : * @return non-negative on success, negative errno code on fail
96 : */
97 1 : int stream_flash_init(struct stream_flash_ctx *ctx, const struct device *fdev,
98 : uint8_t *buf, size_t buf_len, size_t offset, size_t size,
99 : stream_flash_callback_t cb);
100 : /**
101 : * @brief Read number of bytes written to the flash.
102 : *
103 : * @note api-tags: pre-kernel-ok isr-ok
104 : *
105 : * @param ctx context
106 : *
107 : * @return Number of payload bytes written to flash.
108 : */
109 1 : size_t stream_flash_bytes_written(const struct stream_flash_ctx *ctx);
110 :
111 : /**
112 : * @brief Read number of bytes buffered for the next flash write.
113 : *
114 : * @param ctx context
115 : *
116 : * @return Number of payload bytes buffered for the next flash write.
117 : */
118 1 : size_t stream_flash_bytes_buffered(const struct stream_flash_ctx *ctx);
119 :
120 : /**
121 : * @brief Process input buffers to be written to flash device in single blocks.
122 : * Will store remainder between calls.
123 : *
124 : * A write with the @p flush set to true has to be issued as the last
125 : * write request for a given context, as it concludes write of a stream,
126 : * and flushes buffers to storage device.
127 : *
128 : * @warning There must not be any additional write requests issued for a flushed context,
129 : * unless it is re-initialized, as such write attempts may result in the function
130 : * failing and returning error.
131 : * Once context has been flushed, it can be re-initialized and re-used for new
132 : * stream flash session.
133 : *
134 : * @param ctx context
135 : * @param data data to write
136 : * @param len Number of bytes to write
137 : * @param flush when true this forces any buffered data to be written to flash
138 : *
139 : * @return non-negative on success, negative errno code on fail
140 : */
141 1 : int stream_flash_buffered_write(struct stream_flash_ctx *ctx, const uint8_t *data,
142 : size_t len, bool flush);
143 :
144 : /**
145 : * @brief Erase the flash page to which a given offset belongs.
146 : *
147 : * @deprecated Use @a flash_area_erase() or flash_erase(). Note that there
148 : * is no Stream Flash API equivalent for that.
149 : *
150 : * This function erases a flash page to which an offset belongs if this page
151 : * is not the page previously erased by the provided ctx
152 : * (ctx->last_erased_page_start_offset).
153 : *
154 : * @param ctx context
155 : * @param off offset from the base address of the flash device
156 : *
157 : * @return non-negative on success, negative errno code on fail
158 : */
159 1 : __deprecated int stream_flash_erase_page(struct stream_flash_ctx *ctx, off_t off);
160 :
161 : /**
162 : * @brief Load persistent stream write progress stored with key
163 : * @p settings_key .
164 : *
165 : * This function should be called directly after @ref stream_flash_init to
166 : * load previous stream write progress before writing any data. If the loaded
167 : * progress has fewer bytes written than @p ctx then it will be ignored.
168 : *
169 : * @param ctx context
170 : * @param settings_key key to use with the settings module for loading
171 : * the stream write progress
172 : *
173 : * @return non-negative on success, -ERANGE in case when @p off is out
174 : * of area designated for stream or negative errno code on fail
175 : */
176 1 : int stream_flash_progress_load(struct stream_flash_ctx *ctx,
177 : const char *settings_key);
178 :
179 : /**
180 : * @brief Save persistent stream write progress using key @p settings_key .
181 : *
182 : * @param ctx context
183 : * @param settings_key key to use with the settings module for storing
184 : * the stream write progress
185 : *
186 : * @return non-negative on success, negative errno code on fail
187 : */
188 1 : int stream_flash_progress_save(const struct stream_flash_ctx *ctx,
189 : const char *settings_key);
190 :
191 : /**
192 : * @brief Clear persistent stream write progress stored with key
193 : * @p settings_key .
194 : *
195 : * @param ctx context
196 : * @param settings_key key previously used for storing the stream write progress
197 : *
198 : * @return non-negative on success, negative errno code on fail
199 : */
200 1 : int stream_flash_progress_clear(const struct stream_flash_ctx *ctx,
201 : const char *settings_key);
202 :
203 : #ifdef __cplusplus
204 : }
205 : #endif
206 :
207 : /**
208 : * @}
209 : */
210 :
211 : #endif /* ZEPHYR_INCLUDE_STORAGE_STREAM_FLASH_H_ */
|
