1 /* 2 * Copyright (c) 2017 Nordic Semiconductor ASA 3 * Copyright (c) 2015 Runtime Inc 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** 9 * @file 10 * @brief Public API for flash map 11 */ 12 13 #ifndef ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_ 14 #define ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_ 15 16 /** 17 * @brief Abstraction over flash partitions/areas and their drivers 18 * 19 * @defgroup flash_area_api flash area Interface 20 * @{ 21 */ 22 23 /* 24 * This API makes it possible to operate on flash areas easily and 25 * effectively. 26 * 27 * The system contains global data about flash areas. Every area 28 * contains an ID number, offset, and length. 29 */ 30 31 /** 32 * 33 */ 34 #include <zephyr/types.h> 35 #include <stddef.h> 36 #include <sys/types.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** Provided for compatibility with MCUboot */ 43 #define SOC_FLASH_0_ID 0 44 /** Provided for compatibility with MCUboot */ 45 #define SPI_FLASH_0_ID 1 46 47 /** 48 * @brief Flash partition 49 * 50 * This structure represents a fixed-size partition on a flash device. 51 * Each partition contains one or more flash sectors. 52 */ 53 struct flash_area { 54 /** ID number */ 55 uint8_t fa_id; 56 /** Provided for compatibility with MCUboot */ 57 uint8_t fa_device_id; 58 uint16_t pad16; 59 /** Start offset from the beginning of the flash device */ 60 off_t fa_off; 61 /** Total size */ 62 size_t fa_size; 63 /** 64 * Name of the flash device, suitable for passing to 65 * device_get_binding(). 66 */ 67 const char *fa_dev_name; 68 }; 69 70 /** 71 * @brief Structure for transfer flash sector boundaries 72 * 73 * This template is used for presentation of flash memory structure. It 74 * consumes much less RAM than @ref flash_area 75 */ 76 struct flash_sector { 77 /** Sector offset from the beginning of the flash device */ 78 off_t fs_off; 79 /** Sector size in bytes */ 80 size_t fs_size; 81 }; 82 83 #if defined(CONFIG_FLASH_AREA_CHECK_INTEGRITY) 84 /** 85 * @brief Structure for verify flash region integrity 86 * 87 * This is used to pass data to be used to check flash integrity using SHA-256 88 * algorithm. 89 */ 90 struct flash_area_check { 91 const uint8_t *match; /** 256 bits match vector */ 92 size_t clen; /** Content len to be compared */ 93 size_t off; /** Start Offset */ 94 uint8_t *rbuf; /** Temporary read buffer */ 95 size_t rblen; /** Size of read buffer */ 96 }; 97 98 /** 99 * Verify flash memory length bytes integrity from a flash area. The start 100 * point is indicated by an offset value. 101 * 102 * @param[in] fa Flash area 103 * @param[in] fic Flash area check integrity data 104 * 105 * @return 0 on success, negative errno code on fail 106 */ 107 int flash_area_check_int_sha256(const struct flash_area *fa, 108 const struct flash_area_check *fac); 109 #endif 110 111 /** 112 * @brief Retrieve partitions flash area from the flash_map. 113 * 114 * Function Retrieves flash_area from flash_map for given partition. 115 * 116 * @param[in] id ID of the flash partition. 117 * @param[out] fa Pointer which has to reference flash_area. If 118 * @p ID is unknown, it will be NULL on output. 119 * 120 * @return 0 on success, -EACCES if the flash_map is not available , 121 * -ENOENT if @p ID is unknown. 122 */ 123 int flash_area_open(uint8_t id, const struct flash_area **fa); 124 125 /** 126 * @brief Close flash_area 127 * 128 * Reserved for future usage and external projects compatibility reason. 129 * Currently is NOP. 130 * 131 * @param[in] fa Flash area to be closed. 132 */ 133 void flash_area_close(const struct flash_area *fa); 134 135 /** 136 * @brief Read flash area data 137 * 138 * Read data from flash area. Area readout boundaries are asserted before read 139 * request. API has the same limitation regard read-block alignment and size 140 * as wrapped flash driver. 141 * 142 * @param[in] fa Flash area 143 * @param[in] off Offset relative from beginning of flash area to read 144 * @param[out] dst Buffer to store read data 145 * @param[in] len Number of bytes to read 146 * 147 * @return 0 on success, negative errno code on fail. 148 */ 149 int flash_area_read(const struct flash_area *fa, off_t off, void *dst, 150 size_t len); 151 152 /** 153 * @brief Write data to flash area 154 * 155 * Write data to flash area. Area write boundaries are asserted before write 156 * request. API has the same limitation regard write-block alignment and size 157 * as wrapped flash driver. 158 * 159 * @param[in] fa Flash area 160 * @param[in] off Offset relative from beginning of flash area to read 161 * @param[out] src Buffer with data to be written 162 * @param[in] len Number of bytes to write 163 * 164 * @return 0 on success, negative errno code on fail. 165 */ 166 int flash_area_write(const struct flash_area *fa, off_t off, const void *src, 167 size_t len); 168 169 /** 170 * @brief Erase flash area 171 * 172 * Erase given flash area range. Area boundaries are asserted before erase 173 * request. API has the same limitation regard erase-block alignment and size 174 * as wrapped flash driver. 175 * 176 * @param[in] fa Flash area 177 * @param[in] off Offset relative from beginning of flash area. 178 * @param[in] len Number of bytes to be erase 179 * 180 * @return 0 on success, negative errno code on fail. 181 */ 182 int flash_area_erase(const struct flash_area *fa, off_t off, size_t len); 183 184 /** 185 * @brief Get write block size of the flash area 186 * 187 * Currently write block size might be treated as read block size, although 188 * most of drivers supports unaligned readout. 189 * 190 * @param[in] fa Flash area 191 * 192 * @return Alignment restriction for flash writes in [B]. 193 */ 194 uint8_t flash_area_align(const struct flash_area *fa); 195 196 /** 197 * Retrieve info about sectors within the area. 198 * 199 * @param[in] fa_id Given flash area ID 200 * @param[out] sectors buffer for sectors data 201 * @param[in,out] count On input Capacity of @p sectors, on output number of 202 * sectors Retrieved. 203 * 204 * @return 0 on success, negative errno code on fail. Especially returns 205 * -ENOMEM if There are too many flash pages on the flash_area to fit in the 206 * array. 207 */ 208 int flash_area_get_sectors(int fa_id, uint32_t *count, 209 struct flash_sector *sectors); 210 211 /** 212 * Flash map iteration callback 213 * 214 * @param fa flash area 215 * @param user_data User supplied data 216 * 217 */ 218 typedef void (*flash_area_cb_t)(const struct flash_area *fa, 219 void *user_data); 220 221 /** 222 * Iterate over flash map 223 * 224 * @param user_cb User callback 225 * @param user_data User supplied data 226 */ 227 void flash_area_foreach(flash_area_cb_t user_cb, void *user_data); 228 229 /** 230 * Check whether given flash area has supporting flash driver 231 * in the system. 232 * 233 * @param[in] fa Flash area. 234 * 235 * @return 1 On success. -ENODEV if no driver match. 236 */ 237 int flash_area_has_driver(const struct flash_area *fa); 238 239 /** 240 * Get driver for given flash area. 241 * 242 * @param fa Flash area. 243 * 244 * @return device driver. 245 */ 246 const struct device *flash_area_get_device(const struct flash_area *fa); 247 248 /** 249 * Get the value expected to be read when accessing any erased 250 * flash byte. 251 * This API is compatible with the MCUBoot's porting layer. 252 * 253 * @param fa Flash area. 254 * 255 * @return Byte value of erase memory. 256 */ 257 uint8_t flash_area_erased_val(const struct flash_area *fa); 258 259 #define FLASH_AREA_LABEL_EXISTS(label) \ 260 DT_HAS_FIXED_PARTITION_LABEL(label) 261 262 #define FLASH_AREA_LABEL_STR(lbl) \ 263 DT_PROP(DT_NODE_BY_FIXED_PARTITION_LABEL(lbl), label) 264 265 #define FLASH_AREA_ID(label) \ 266 DT_FIXED_PARTITION_ID(DT_NODE_BY_FIXED_PARTITION_LABEL(label)) 267 268 #define FLASH_AREA_OFFSET(label) \ 269 DT_REG_ADDR(DT_NODE_BY_FIXED_PARTITION_LABEL(label)) 270 271 #define FLASH_AREA_SIZE(label) \ 272 DT_REG_SIZE(DT_NODE_BY_FIXED_PARTITION_LABEL(label)) 273 274 #ifdef __cplusplus 275 } 276 #endif 277 278 /** 279 * @} 280 */ 281 282 #endif /* ZEPHYR_INCLUDE_STORAGE_FLASH_MAP_H_ */ 283
