1 /*
2 * Copyright (c) 2018 Nordic Semiconductor ASA
3 * Copyright (c) 2015 Runtime Inc
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8 #ifndef __FLASH_MAP_BACKEND_H__
9 #define __FLASH_MAP_BACKEND_H__
10
11 #include <zephyr/storage/flash_map.h> // the zephyr flash_map
12
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17 /**
18 *
19 * Provides abstraction of flash regions for type of use.
20 * I.e. dude where's my image?
21 *
22 * System will contain a map which contains flash areas. Every
23 * region will contain flash identifier, offset within flash and length.
24 *
25 * 1. This system map could be in a file within filesystem (Initializer
26 * must know/figure out where the filesystem is at).
27 * 2. Map could be at fixed location for project (compiled to code)
28 * 3. Map could be at specific place in flash (put in place at mfg time).
29 *
30 * Note that the map you use must be valid for BSP it's for,
31 * match the linker scripts when platform executes from flash,
32 * and match the target offset specified in download script.
33 */
34 #include <inttypes.h>
35 #include <sys/types.h>
36
37 /*
38 * Retrieve a memory-mapped flash device's base address.
39 *
40 * On success, the address will be stored in the value pointed to by
41 * ret.
42 *
43 * Returns 0 on success, or an error code on failure.
44 */
45 int flash_device_base(uint8_t fd_id, uintptr_t *ret);
46
47 int flash_area_id_from_image_slot(int slot);
48 int flash_area_id_from_multi_image_slot(int image_index, int slot);
49
50 /**
51 * Converts the specified flash area ID and image index (in multi-image setup)
52 * to an image slot index.
53 *
54 * Returns image slot index (0 or 1), or -1 if ID doesn't correspond to an image
55 * slot.
56 */
57 int flash_area_id_to_multi_image_slot(int image_index, int area_id);
58
59 /* Retrieve the flash sector a given offset belongs to.
60 *
61 * Returns 0 on success, or an error code on failure.
62 */
63 int flash_area_sector_from_off(off_t off, struct flash_sector *sector);
64
flash_area_get_off(const struct flash_area * fa)65 static inline uint32_t flash_area_get_off(const struct flash_area *fa)
66 {
67 return (uint32_t)fa->fa_off;
68 }
69
flash_area_get_size(const struct flash_area * fa)70 static inline uint32_t flash_area_get_size(const struct flash_area *fa)
71 {
72 return (uint32_t)fa->fa_size;
73 }
74
flash_area_get_id(const struct flash_area * fa)75 static inline uint8_t flash_area_get_id(const struct flash_area *fa)
76 {
77 return fa->fa_id;
78 }
79
80 uint8_t flash_area_get_device_id(const struct flash_area *fa);
81
82 /*
83 * Returns the value expected to be read when accessing any erased
84 * flash byte.
85 */
86 uint8_t flash_area_erased_val(const struct flash_area *fap);
87
flash_sector_get_off(const struct flash_sector * fs)88 static inline uint32_t flash_sector_get_off(const struct flash_sector *fs)
89 {
90 return fs->fs_off;
91 }
92
flash_sector_get_size(const struct flash_sector * fs)93 static inline uint32_t flash_sector_get_size(const struct flash_sector *fs)
94 {
95 return fs->fs_size;
96 }
97
98 /* Retrieve the flash sector withing given flash area, at a given offset.
99 *
100 * @param fa flash area where the sector is taken from.
101 * @param off offset within flash area.
102 * @param sector structure of sector information.
103 * Returns 0 on success, -ERANGE if @p off is beyond flash area size,
104 * other negative errno code on failure.
105 */
106 int flash_area_get_sector(const struct flash_area *fa, off_t off,
107 struct flash_sector *fs);
108
109 #ifdef __cplusplus
110 }
111 #endif
112
113 #endif /* __FLASH_MAP_BACKEND_H__ */
114
