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