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 "region_defs.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 #if (defined(BOOT_TFM_SHARED_DATA_BASE) && defined(BOOT_TFM_SHARED_DATA_SIZE))
68 #define MCUBOOT_SHARED_DATA_BASE    BOOT_TFM_SHARED_DATA_BASE
69 #define MCUBOOT_SHARED_DATA_SIZE    BOOT_TFM_SHARED_DATA_SIZE
70 #else
71 #error "BOOT_TFM_SHARED_DATA_* must be defined by target."
72 #endif
73 
74 /**
75  * @brief Structure describing an area on a flash device.
76  *
77  * Multiple flash devices may be available in the system, each of
78  * which may have its own areas. For this reason, flash areas track
79  * which flash device they are part of.
80  */
81 struct flash_area {
82     /**
83      * This flash area's ID; unique in the system.
84      */
85     uint8_t fa_id;
86 
87     /**
88      * ID of the flash device this area is a part of.
89      */
90     uint8_t fa_device_id;
91 
92     uint16_t pad16;
93 
94     /**
95      * Pointer to driver
96      */
97     ARM_DRIVER_FLASH *fa_driver;
98 
99     /**
100      * This area's offset, relative to the beginning of its flash
101      * device's storage.
102      */
103     uint32_t fa_off;
104 
105     /**
106      * This area's size, in bytes.
107      */
108     uint32_t fa_size;
109 };
110 
111 /**
112  * @brief Structure describing a sector within a flash area.
113  *
114  * Each sector has an offset relative to the start of its flash area
115  * (NOT relative to the start of its flash device), and a size. A
116  * flash area may contain sectors with different sizes.
117  */
118 struct flash_sector {
119     /**
120      * Offset of this sector, from the start of its flash area (not device).
121      */
122     uint32_t fs_off;
123 
124     /**
125      * Size of this sector, in bytes.
126      */
127     uint32_t fs_size;
128 };
129 
130 /**
131  * @brief Macro retrieving driver from struct flash area
132  *
133  */
134 #define DRV_FLASH_AREA(area) ((area)->fa_driver)
135 
136 /* Initialiaze all flash driver */
137 int flash_area_driver_init(void);
138 
139 /*
140  * Start using flash area.
141  */
142 int flash_area_open(uint8_t id, const struct flash_area **area);
143 
144 void flash_area_close(const struct flash_area *area);
145 
146 /*
147  * Read/write/erase. Offset is relative from beginning of flash area.
148  */
149 int flash_area_read(const struct flash_area *area, uint32_t off, void *dst,
150                     uint32_t len);
151 
152 int flash_area_write(const struct flash_area *area, uint32_t off,
153                      const void *src, uint32_t len);
154 
155 int flash_area_erase(const struct flash_area *area, uint32_t off, uint32_t len);
156 
157 /*
158  * Alignment restriction for flash writes.
159  */
160 uint32_t flash_area_align(const struct flash_area *area);
161 
162 /*
163  * Given flash area ID, return info about sectors within the area.
164  */
165 int flash_area_get_sectors(int fa_id, uint32_t *count,
166   struct flash_sector *sectors);
167 
168 /*
169  * Similar to flash_area_get_sectors(), but return the values in an
170  * array of struct flash_area instead.
171  */
172 __attribute__((deprecated))
173 int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
174 
175 #ifdef __cplusplus
176 }
177 #endif
178 
179 #endif /* H_UTIL_FLASH_MAP_ */
180