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 /*
21  * Original code taken from mcuboot project at:
22  * https://github.com/mcu-tools/mcuboot
23  * Git SHA of the original version: ac55554059147fff718015be9f4bd3108123f50a
24  * Modifications are Copyright (c) 2018-2020 Arm Limited.
25  */
26 
27 #ifndef H_UTIL_FLASH_MAP_
28 #define H_UTIL_FLASH_MAP_
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  *
36  * Provides abstraction of flash regions for type of use.
37  * I.e. dude where's my image?
38  *
39  * System will contain a map which contains flash areas. Every
40  * region will contain flash identifier, offset within flash and length.
41  *
42  * 1. This system map could be in a file within filesystem (Initializer
43  * must know/figure out where the filesystem is at).
44  * 2. Map could be at fixed location for project (compiled to code)
45  * 3. Map could be at specific place in flash (put in place at mfg time).
46  *
47  * Note that the map you use must be valid for BSP it's for,
48  * match the linker scripts when platform executes from flash,
49  * and match the target offset specified in download script.
50  */
51 #include <inttypes.h>
52 #include "tfm_plat_shared_measurement_data.h"
53 #include "Driver_Flash.h"
54 
55 /*
56  * For now, we only support one flash device.
57  *
58  * Pick a random device ID for it that's unlikely to collide with
59  * anything "real".
60  */
61 #define FLASH_DEVICE_ID                 100
62 #define FLASH_DEVICE_BASE               FLASH_BASE_ADDRESS
63 
64 /*
65  * Shared data area between bootloader and runtime firmware.
66  */
67 #define MCUBOOT_SHARED_DATA_BASE (tfm_plat_get_shared_measurement_data_base())
68 #define MCUBOOT_SHARED_DATA_SIZE (tfm_plat_get_shared_measurement_data_size())
69 
70 /**
71  * @brief Structure describing an area on a flash device.
72  *
73  * Multiple flash devices may be available in the system, each of
74  * which may have its own areas. For this reason, flash areas track
75  * which flash device they are part of.
76  */
77 struct flash_area {
78     /**
79      * This flash area's ID; unique in the system.
80      */
81     uint8_t fa_id;
82 
83     /**
84      * ID of the flash device this area is a part of.
85      */
86     uint8_t fa_device_id;
87 
88     uint16_t pad16;
89 
90     /**
91      * Pointer to driver
92      */
93     ARM_DRIVER_FLASH *fa_driver;
94 
95     /**
96      * This area's offset, relative to the beginning of its flash
97      * device's storage.
98      */
99     uint32_t fa_off;
100 
101     /**
102      * This area's size, in bytes.
103      */
104     uint32_t fa_size;
105 };
106 
107 /**
108  * @brief Structure describing a sector within a flash area.
109  *
110  * Each sector has an offset relative to the start of its flash area
111  * (NOT relative to the start of its flash device), and a size. A
112  * flash area may contain sectors with different sizes.
113  */
114 struct flash_sector {
115     /**
116      * Offset of this sector, from the start of its flash area (not device).
117      */
118     uint32_t fs_off;
119 
120     /**
121      * Size of this sector, in bytes.
122      */
123     uint32_t fs_size;
124 };
125 
126 /**
127  * @brief Macro retrieving driver from struct flash area
128  *
129  */
130 #define DRV_FLASH_AREA(area) ((area)->fa_driver)
131 
132 /* Initialiaze all flash driver */
133 int flash_area_driver_init(void);
134 
135 /*
136  * Start using flash area.
137  */
138 int flash_area_open(uint8_t id, const struct flash_area **area);
139 
140 void flash_area_close(const struct flash_area *area);
141 
142 /*
143  * Read/write/erase. Offset is relative from beginning of flash area.
144  */
145 int flash_area_read(const struct flash_area *area, uint32_t off, void *dst,
146                     uint32_t len);
147 
148 int flash_area_write(const struct flash_area *area, uint32_t off,
149                      const void *src, uint32_t len);
150 
151 int flash_area_erase(const struct flash_area *area, uint32_t off, uint32_t len);
152 
153 /*
154  * Alignment restriction for flash writes.
155  */
156 uint32_t flash_area_align(const struct flash_area *area);
157 
158 /*
159  * Given flash area ID, return info about sectors within the area.
160  */
161 int flash_area_get_sectors(int fa_id, uint32_t *count,
162   struct flash_sector *sectors);
163 
164 /* Retrieve the flash sector a given offset belongs to.
165  *
166  * Returns 0 on success, or an error code on failure.
167  */
168 int flash_area_sector_from_off(uint32_t off, struct flash_sector *sector);
169 
170 /* Retrieve the flash sector a given offset, within flash area.
171  *
172  * @param fa        flash area.
173  * @param off       offset of sector.
174  * @param sector    pointer to structure for obtained information.
175  * Returns 0 on success, or an error code on failure.
176  */
177 int flash_area_get_sector(const struct flash_area *fa, uint32_t off,
178   struct flash_sector *sector);
179 
180 /*
181  * Similar to flash_area_get_sectors(), but return the values in an
182  * array of struct flash_area instead.
183  */
184 __attribute__((deprecated))
185 int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
186 
187 #ifdef __cplusplus
188 }
189 #endif
190 
191 #endif /* H_UTIL_FLASH_MAP_ */
192