1 /*
2 * Copyright (c) 2018 Nordic Semiconductor ASA
3 * Copyright (c) 2015 Runtime Inc
4 * Copyright (c) 2020 Cypress Semiconductor Corporation
5 *
6 * SPDX-License-Identifier: Apache-2.0
7 */
8 /*
9 * Licensed to the Apache Software Foundation (ASF) under one
10 * or more contributor license agreements. See the NOTICE file
11 * distributed with this work for additional information
12 * regarding copyright ownership. The ASF licenses this file
13 * to you under the Apache License, Version 2.0 (the
14 * "License"); you may not use this file except in compliance
15 * with the License. You may obtain a copy of the License at
16 *
17 * http://www.apache.org/licenses/LICENSE-2.0
18 *
19 * Unless required by applicable law or agreed to in writing,
20 * software distributed under the License is distributed on an
21 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
22 * KIND, either express or implied. See the License for the
23 * specific language governing permissions and limitations
24 * under the License.
25 */
26 /*******************************************************************************/
27
28 #ifndef __FLASH_MAP_BACKEND_H__
29 #define __FLASH_MAP_BACKEND_H__
30
31 #include <mcuboot_config/mcuboot_config.h>
32 #include "cy_flash.h"
33 #define FLASH_DEVICE_INDEX_MASK (0x7F)
34 #define FLASH_DEVICE_GET_EXT_INDEX(n) ((n) & FLASH_DEVICE_INDEX_MASK)
35 #define FLASH_DEVICE_EXTERNAL_FLAG (0x80)
36 #define FLASH_DEVICE_INTERNAL_FLASH (0x7F)
37 #define FLASH_DEVICE_EXTERNAL_FLASH(index) (FLASH_DEVICE_EXTERNAL_FLAG | index)
38
39 #ifndef CY_BOOT_EXTERNAL_DEVICE_INDEX
40 /* assume first(one) SMIF device is used */
41 #define CY_BOOT_EXTERNAL_DEVICE_INDEX (0)
42 #endif
43
44 /**
45 *
46 * Provides abstraction of flash regions for type of use.
47 * I.e. dude where's my image?
48 *
49 * System will contain a map which contains flash areas. Every
50 * region will contain flash identifier, offset within flash and length.
51 *
52 * 1. This system map could be in a file within filesystem (Initializer
53 * must know/figure out where the filesystem is at).
54 * 2. Map could be at fixed location for project (compiled to code)
55 * 3. Map could be at specific place in flash (put in place at mfg time).
56 *
57 * Note that the map you use must be valid for BSP it's for,
58 * match the linker scripts when platform executes from flash,
59 * and match the target offset specified in download script.
60 */
61 #include <inttypes.h>
62
63 /**
64 * @brief Structure describing an area on a flash device.
65 *
66 * Multiple flash devices may be available in the system, each of
67 * which may have its own areas. For this reason, flash areas track
68 * which flash device they are part of.
69 */
70 struct flash_area {
71 /**
72 * This flash area's ID; unique in the system.
73 */
74 uint8_t fa_id;
75
76 /**
77 * ID of the flash device this area is a part of.
78 */
79 uint8_t fa_device_id;
80
81 uint16_t pad16;
82
83 /**
84 * This area's offset, relative to the beginning of its flash
85 * device's storage.
86 */
87 uint32_t fa_off;
88
89 /**
90 * This area's size, in bytes.
91 */
92 uint32_t fa_size;
93 };
94
flash_area_get_id(const struct flash_area * fa)95 static inline uint8_t flash_area_get_id(const struct flash_area *fa)
96 {
97 return fa->fa_id;
98 }
99
flash_area_get_device_id(const struct flash_area * fa)100 static inline uint8_t flash_area_get_device_id(const struct flash_area *fa)
101 {
102 return fa->fa_device_id;
103 }
104
flash_area_get_off(const struct flash_area * fa)105 static inline uint32_t flash_area_get_off(const struct flash_area *fa)
106 {
107 return fa->fa_off;
108 }
109
flash_area_get_size(const struct flash_area * fa)110 static inline uint32_t flash_area_get_size(const struct flash_area *fa)
111 {
112 return fa->fa_size;
113 }
114
115 /**
116 * @brief Structure describing a sector within a flash area.
117 *
118 * Each sector has an offset relative to the start of its flash area
119 * (NOT relative to the start of its flash device), and a size. A
120 * flash area may contain sectors with different sizes.
121 */
122 struct flash_sector {
123 /**
124 * Offset of this sector, from the start of its flash area (not device).
125 */
126 uint32_t fs_off;
127
128 /**
129 * Size of this sector, in bytes.
130 */
131 uint32_t fs_size;
132 };
133
flash_sector_get_off(const struct flash_sector * fs)134 static inline uint32_t flash_sector_get_off(const struct flash_sector *fs)
135 {
136 return fs->fs_off;
137 }
138
flash_sector_get_size(const struct flash_sector * fs)139 static inline uint32_t flash_sector_get_size(const struct flash_sector *fs)
140 {
141 return fs->fs_size;
142 }
143
144 struct flash_map_entry {
145 uint32_t magic;
146 struct flash_area area;
147 unsigned int ref_count;
148 };
149
150 /*
151 * Retrieve a memory-mapped flash device's base address.
152 * On success, the address will be stored in the value pointed to by
153 * ret.
154 * Returns 0 on success, or an error code on failure.
155 */
156 int flash_device_base(uint8_t fd_id, uintptr_t *ret);
157
158 /*< Opens the area for use. id is one of the `fa_id`s */
159 int flash_area_open(uint8_t id, const struct flash_area **);
160 void flash_area_close(const struct flash_area *);
161 /*< Reads `len` bytes of flash memory at `off` to the buffer at `dst` */
162 int flash_area_read(const struct flash_area *, uint32_t off, void *dst,
163 uint32_t len);
164 /*< Writes `len` bytes of flash memory at `off` from the buffer at `src` */
165 int flash_area_write(const struct flash_area *, uint32_t off,
166 const void *src, uint32_t len);
167 /*< Erases `len` bytes of flash memory at `off` */
168 int flash_area_erase(const struct flash_area *, uint32_t off, uint32_t len);
169 /*< Returns this `flash_area`s alignment */
170 uint32_t flash_area_align(const struct flash_area *);
171 /*< Initializes an array of flash_area elements for the slot's sectors */
172 int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
173 /*< Returns the `fa_id` for slot, where slot is 0 (primary) or 1 (secondary) */
174 int flash_area_id_from_image_slot(int slot);
175
176 int flash_area_id_from_multi_image_slot(int image_index, int slot);
177 int flash_area_id_to_multi_image_slot(int image_index, int area_id);
178 #ifdef MCUBOOT_USE_FLASH_AREA_GET_SECTORS
179 int flash_area_get_sectors(int idx, uint32_t *cnt, struct flash_sector *ret);
180 #endif
181 /*
182 * Returns the value expected to be read when accesing any erased
183 * flash byte.
184 */
185 uint8_t flash_area_erased_val(const struct flash_area *fap);
186
187 /*
188 * Reads len bytes from off, and checks if the read data is erased.
189 *
190 * Returns 1 if erased, 0 if non-erased, and -1 on failure.
191 */
192 int flash_area_read_is_empty(const struct flash_area *fa, uint32_t off,
193 void *dst, uint32_t len);
194
195 #endif /* __FLASH_MAP_BACKEND_H__ */
196
