1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  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,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied.  See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  */
19 
20 #ifndef H_UTIL_FLASH_MAP_
21 #define H_UTIL_FLASH_MAP_
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 /**
28  *
29  * Provides abstraction of flash regions for type of use.
30  * I.e. dude where's my image?
31  *
32  * System will contain a map which contains flash areas. Every
33  * region will contain flash identifier, offset within flash and length.
34  *
35  * 1. This system map could be in a file within filesystem (Initializer
36  * must know/figure out where the filesystem is at).
37  * 2. Map could be at fixed location for project (compiled to code)
38  * 3. Map could be at specific place in flash (put in place at mfg time).
39  *
40  * Note that the map you use must be valid for BSP it's for,
41  * match the linker scripts when platform executes from flash,
42  * and match the target offset specified in download script.
43  */
44 #include <inttypes.h>
45 
46 /**
47  * @brief Structure describing an area on a flash device.
48  *
49  * Multiple flash devices may be available in the system, each of
50  * which may have its own areas. For this reason, flash areas track
51  * which flash device they are part of.
52  */
53 struct flash_area {
54     /**
55      * This flash area's ID; unique in the system.
56      */
57     uint8_t fa_id;
58 
59     /**
60      * ID of the flash device this area is a part of.
61      */
62     uint8_t fa_device_id;
63 
64     uint16_t pad16;
65 
66     /**
67      * This area's offset, relative to the beginning of its flash
68      * device's storage.
69      */
70     uint32_t fa_off;
71 
72     /**
73      * This area's size, in bytes.
74      */
75     uint32_t fa_size;
76 };
77 
78 /**
79  * @brief Structure describing a sector within a flash area.
80  *
81  * Each sector has an offset relative to the start of its flash area
82  * (NOT relative to the start of its flash device), and a size. A
83  * flash area may contain sectors with different sizes.
84  */
85 struct flash_sector {
86     /**
87      * Offset of this sector, from the start of its flash area (not device).
88      */
89     uint32_t fs_off;
90 
91     /**
92      * Size of this sector, in bytes.
93      */
94     uint32_t fs_size;
95 };
96 
97 /*
98  * Retrieve a memory-mapped flash device's base address.
99  *
100  * On success, the address will be stored in the value pointed to by
101  * ret.
102  *
103  * Returns 0 on success, or an error code on failure.
104  */
105 int flash_device_base(uint8_t fd_id, uintptr_t *ret);
106 
107 /*
108  * Start using flash area.
109  */
110 int flash_area_open(uint8_t id, const struct flash_area **);
111 
112 void flash_area_close(const struct flash_area *);
113 
114 /*
115  * Read/write/erase. Offset is relative from beginning of flash area.
116  */
117 int flash_area_read(const struct flash_area *, uint32_t off, void *dst,
118   uint32_t len);
119 int flash_area_write(const struct flash_area *, uint32_t off, const void *src,
120   uint32_t len);
121 int flash_area_erase(const struct flash_area *, uint32_t off, uint32_t len);
122 
123 /*
124  * Alignment restriction for flash writes.
125  */
126 uint32_t flash_area_align(const struct flash_area *);
127 
128 /*
129  * What is value is read from erased flash bytes.
130  */
131 uint8_t flash_area_erased_val(const struct flash_area *);
132 
133 /*
134  * Given flash area ID, return info about sectors within the area.
135  */
136 int flash_area_get_sectors(int fa_id, uint32_t *count,
137   struct flash_sector *sectors);
138 
139 
140 /* Retrieve the flash sector a given offset belongs to.
141  *
142  * Returns 0 on success, or an error code on failure.
143  */
144 int flash_area_sector_from_off(uint32_t off, struct flash_sector *sector);
145 
146 /* Retrieve the flash sector a given offset, within flash area.
147  *
148  * @param fa        flash area.
149  * @param off       offset of sector.
150  * @param sector    pointer to structure for obtained information.
151  * Returns 0 on success, or an error code on failure.
152  */
153 int flash_area_get_sector(const struct flash_area *fa, uint32_t off,
154   struct flash_sector *sector);
155 
156 /*
157  * Similar to flash_area_get_sectors(), but return the values in an
158  * array of struct flash_area instead.
159  */
160 __attribute__((deprecated))
161 int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
162 
163 int flash_area_id_from_image_slot(int slot);
164 int flash_area_id_from_multi_image_slot(int image_index, int slot);
165 int flash_area_id_to_multi_image_slot(int image_index, int area_id);
166 
167 #ifdef __cplusplus
168 }
169 #endif
170 
171 #endif /* H_UTIL_FLASH_MAP_ */
172