1 /****************************************************************************
2 * boot/nuttx/include/flash_map_backend/flash_map_backend.h
3 *
4 * Copyright (c) 2021 Espressif Systems (Shanghai) Co., Ltd.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 ****************************************************************************/
19
20 #ifndef __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H
21 #define __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H
22
23 /****************************************************************************
24 * Included Files
25 ****************************************************************************/
26
27 #include <inttypes.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /****************************************************************************
34 * Public Types
35 ****************************************************************************/
36
37 /* Structure describing a flash area. */
38
39 struct flash_area
40 {
41 /* MCUboot-API fields */
42
43 uint8_t fa_id; /* The slot/scratch ID */
44 uint8_t fa_device_id; /* The device ID (usually there's only one) */
45 uint16_t pad16; /* Padding */
46 uint32_t fa_off; /* The flash offset from the beginning */
47 uint32_t fa_size; /* The size of this sector */
48
49 /* NuttX implementation-specific fields */
50
51 const char *fa_mtd_path; /* Path for the MTD partition */
52 };
53
54 /* Structure describing a sector within a flash area. */
55
56 struct flash_sector
57 {
58 /* Offset of this sector, from the start of its flash area (not device). */
59
60 uint32_t fs_off;
61
62 /* Size of this sector, in bytes. */
63
64 uint32_t fs_size;
65 };
66
67 /****************************************************************************
68 * Inline Functions
69 ****************************************************************************/
70
71 /****************************************************************************
72 * Name: flash_area_get_id
73 *
74 * Description:
75 * Obtain the ID of a given flash area.
76 *
77 * Input Parameters:
78 * fa - Flash area.
79 *
80 * Returned Value:
81 * The ID of the requested flash area.
82 *
83 ****************************************************************************/
84
flash_area_get_id(const struct flash_area * fa)85 static inline uint8_t flash_area_get_id(const struct flash_area *fa)
86 {
87 return fa->fa_id;
88 }
89
90 /****************************************************************************
91 * Name: flash_area_get_device_id
92 *
93 * Description:
94 * Obtain the ID of the device in which a given flash area resides on.
95 *
96 * Input Parameters:
97 * fa - Flash area.
98 *
99 * Returned Value:
100 * The device ID of the requested flash area.
101 *
102 ****************************************************************************/
103
flash_area_get_device_id(const struct flash_area * fa)104 static inline uint8_t flash_area_get_device_id(const struct flash_area *fa)
105 {
106 return fa->fa_device_id;
107 }
108
109 /****************************************************************************
110 * Name: flash_area_get_sector
111 *
112 * Description:
113 * Retrieve the flash sector a given offset belongs to.
114 *
115 * Input Parameters:
116 * fap - flash area structure
117 * off - address offset.
118 * sector - flash sector
119 *
120 * Returned Value:
121 * Returns 0 on success, or an error code on failure.
122 *
123 ****************************************************************************/
124
125 int flash_area_get_sector(const struct flash_area *fap, off_t off,
126 struct flash_sector *fs);
127
128 /****************************************************************************
129 * Name: flash_area_get_off
130 *
131 * Description:
132 * Obtain the offset, from the beginning of a device, where a given flash
133 * area starts at.
134 *
135 * Input Parameters:
136 * fa - Flash area.
137 *
138 * Returned Value:
139 * The offset value of the requested flash area.
140 *
141 ****************************************************************************/
142
flash_area_get_off(const struct flash_area * fa)143 static inline uint32_t flash_area_get_off(const struct flash_area *fa)
144 {
145 return fa->fa_off;
146 }
147
148 /****************************************************************************
149 * Name: flash_area_get_size
150 *
151 * Description:
152 * Obtain the size, from the offset, of a given flash area.
153 *
154 * Input Parameters:
155 * fa - Flash area.
156 *
157 * Returned Value:
158 * The size value of the requested flash area.
159 *
160 ****************************************************************************/
161
flash_area_get_size(const struct flash_area * fa)162 static inline uint32_t flash_area_get_size(const struct flash_area *fa)
163 {
164 return fa->fa_size;
165 }
166
167 /****************************************************************************
168 * Name: flash_sector_get_off
169 *
170 * Description:
171 * Obtain the offset, from the beginning of its flash area, where a given
172 * flash sector starts at.
173 *
174 * Input Parameters:
175 * fs - Flash sector.
176 *
177 * Returned Value:
178 * The offset value of the requested flash sector.
179 *
180 ****************************************************************************/
181
flash_sector_get_off(const struct flash_sector * fs)182 static inline uint32_t flash_sector_get_off(const struct flash_sector *fs)
183 {
184 return fs->fs_off;
185 }
186
187 /****************************************************************************
188 * Name: flash_sector_get_size
189 *
190 * Description:
191 * Obtain the size, from the offset, of a given flash sector.
192 *
193 * Input Parameters:
194 * fs - Flash sector.
195 *
196 * Returned Value:
197 * The size in bytes of the requested flash sector.
198 *
199 ****************************************************************************/
200
flash_sector_get_size(const struct flash_sector * fs)201 static inline uint32_t flash_sector_get_size(const struct flash_sector *fs)
202 {
203 return fs->fs_size;
204 }
205
206 /****************************************************************************
207 * Public Function Prototypes
208 ****************************************************************************/
209
210 /****************************************************************************
211 * Name: flash_area_open
212 *
213 * Description:
214 * Retrieve flash area from the flash map for a given partition.
215 *
216 * Input Parameters:
217 * id - ID of the flash partition.
218 *
219 * Output Parameters:
220 * fa - Pointer which will contain the reference to flash_area.
221 * If ID is unknown, it will be NULL on output.
222 *
223 * Returned Value:
224 * Zero on success, or negative value in case of error.
225 *
226 ****************************************************************************/
227
228 int flash_area_open(uint8_t id, const struct flash_area **fa);
229
230 /****************************************************************************
231 * Name: flash_area_close
232 *
233 * Description:
234 * Close a given flash area.
235 *
236 * Input Parameters:
237 * fa - Flash area to be closed.
238 *
239 * Returned Value:
240 * None.
241 *
242 ****************************************************************************/
243
244 void flash_area_close(const struct flash_area *fa);
245
246 /****************************************************************************
247 * Name: flash_area_read
248 *
249 * Description:
250 * Read data from flash area.
251 * Area readout boundaries are asserted before read request. API has the
252 * same limitation regarding read-block alignment and size as the
253 * underlying flash driver.
254 *
255 * Input Parameters:
256 * fa - Flash area to be read.
257 * off - Offset relative from beginning of flash area to be read.
258 * len - Number of bytes to read.
259 *
260 * Output Parameters:
261 * dst - Buffer to store read data.
262 *
263 * Returned Value:
264 * Zero on success, or negative value in case of error.
265 *
266 ****************************************************************************/
267
268 int flash_area_read(const struct flash_area *fa, uint32_t off,
269 void *dst, uint32_t len);
270
271 /****************************************************************************
272 * Name: flash_area_write
273 *
274 * Description:
275 * Write data to flash area.
276 * Area write boundaries are asserted before write request. API has the
277 * same limitation regarding write-block alignment and size as the
278 * underlying flash driver.
279 *
280 * Input Parameters:
281 * fa - Flash area to be written.
282 * off - Offset relative from beginning of flash area to be written.
283 * src - Buffer with data to be written.
284 * len - Number of bytes to write.
285 *
286 * Returned Value:
287 * Zero on success, or negative value in case of error.
288 *
289 ****************************************************************************/
290
291 int flash_area_write(const struct flash_area *fa, uint32_t off,
292 const void *src, uint32_t len);
293
294 /****************************************************************************
295 * Name: flash_area_erase
296 *
297 * Description:
298 * Erase a given flash area range.
299 * Area boundaries are asserted before erase request. API has the same
300 * limitation regarding erase-block alignment and size as the underlying
301 * flash driver.
302 *
303 * Input Parameters:
304 * fa - Flash area to be erased.
305 * off - Offset relative from beginning of flash area to be erased.
306 * len - Number of bytes to be erase.
307 *
308 * Returned Value:
309 * Zero on success, or negative value in case of error.
310 *
311 ****************************************************************************/
312
313 int flash_area_erase(const struct flash_area *fa, uint32_t off,
314 uint32_t len);
315
316 /****************************************************************************
317 * Name: flash_area_align
318 *
319 * Description:
320 * Get write block size of the flash area.
321 * Write block size might be treated as read block size, although most
322 * drivers support unaligned readout.
323 *
324 * Input Parameters:
325 * fa - Flash area.
326 *
327 * Returned Value:
328 * Alignment restriction for flash writes in the given flash area.
329 *
330 ****************************************************************************/
331
332 uint32_t flash_area_align(const struct flash_area *fa);
333
334 /****************************************************************************
335 * Name: flash_area_erased_val
336 *
337 * Description:
338 * Get the value expected to be read when accessing any erased flash byte.
339 * This API is compatible with the MCUboot's porting layer.
340 *
341 * Input Parameters:
342 * fa - Flash area.
343 *
344 * Returned Value:
345 * Byte value of erased memory.
346 *
347 ****************************************************************************/
348
349 uint8_t flash_area_erased_val(const struct flash_area *fa);
350
351 /****************************************************************************
352 * Name: flash_area_get_sectors
353 *
354 * Description:
355 * Retrieve info about sectors within the area.
356 *
357 * Input Parameters:
358 * fa_id - ID of the flash area whose info will be retrieved.
359 * count - On input, represents the capacity of the sectors buffer.
360 *
361 * Output Parameters:
362 * count - On output, it shall contain the number of retrieved sectors.
363 * sectors - Buffer for sectors data.
364 *
365 * Returned Value:
366 * Zero on success, or negative value in case of error.
367 *
368 ****************************************************************************/
369
370 int flash_area_get_sectors(int fa_id, uint32_t *count,
371 struct flash_sector *sectors);
372
373 /****************************************************************************
374 * Name: flash_area_id_from_multi_image_slot
375 *
376 * Description:
377 * Return the flash area ID for a given slot and a given image index
378 * (in case of a multi-image setup).
379 *
380 * Input Parameters:
381 * image_index - Index of the image.
382 * slot - Image slot, which may be 0 (primary) or 1 (secondary).
383 *
384 * Returned Value:
385 * Flash area ID (0 or 1), or negative value in case the requested slot
386 * is invalid.
387 *
388 ****************************************************************************/
389
390 int flash_area_id_from_multi_image_slot(int image_index, int slot);
391
392 /****************************************************************************
393 * Name: flash_area_id_from_image_slot
394 *
395 * Description:
396 * Return the flash area ID for a given slot.
397 *
398 * Input Parameters:
399 * slot - Image slot, which may be 0 (primary) or 1 (secondary).
400 *
401 * Returned Value:
402 * Flash area ID (0 or 1), or negative value in case the requested slot
403 * is invalid.
404 *
405 ****************************************************************************/
406
407 int flash_area_id_from_image_slot(int slot);
408
409 /****************************************************************************
410 * Name: flash_area_id_to_multi_image_slot
411 *
412 * Description:
413 * Convert the specified flash area ID and image index (in case of a
414 * multi-image setup) to an image slot index.
415 *
416 * Input Parameters:
417 * image_index - Index of the image.
418 * area_id - Unique identifier that is represented by fa_id in the
419 * flash_area struct.
420 * Returned Value:
421 * Image slot index (0 or 1), or negative value in case ID doesn't
422 * correspond to an image slot.
423 *
424 ****************************************************************************/
425
426 int flash_area_id_to_multi_image_slot(int image_index, int area_id);
427
428 /****************************************************************************
429 * Name: flash_area_id_from_image_offset
430 *
431 * Description:
432 * Return the flash area ID for a given image offset.
433 *
434 * Input Parameters:
435 * offset - Image offset.
436 *
437 * Returned Value:
438 * Flash area ID (0 or 1), or negative value in case the requested offset
439 * is invalid.
440 *
441 ****************************************************************************/
442
443 int flash_area_id_from_image_offset(uint32_t offset);
444
445 #ifdef __cplusplus
446 }
447 #endif
448
449 #endif /* __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H */
450
