1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Copyright (c) 2022, Linaro Limited 4 */ 5 6 #if !defined _FWU_H_ 7 #define _FWU_H_ 8 9 #include <blk.h> 10 #include <efi.h> 11 #include <fwu_mdata.h> 12 #include <u-boot/uuid.h> 13 14 #include <linux/types.h> 15 16 struct fwu_mdata; 17 struct udevice; 18 19 struct fwu_mdata_gpt_blk_priv { 20 struct udevice *blk_dev; 21 }; 22 23 struct fwu_mtd_image_info { 24 u32 start, size; 25 int bank_num, image_num; 26 char uuidbuf[UUID_STR_LEN + 1]; 27 }; 28 29 struct fwu_mdata_mtd_priv { 30 struct mtd_info *mtd; 31 char pri_label[50]; 32 char sec_label[50]; 33 u32 pri_offset; 34 u32 sec_offset; 35 struct fwu_mtd_image_info *fwu_mtd_images; 36 }; 37 38 struct fwu_data { 39 uint32_t crc32; 40 uint32_t version; 41 uint32_t active_index; 42 uint32_t previous_active_index; 43 uint32_t metadata_size; 44 uint32_t boot_index; 45 uint32_t num_banks; 46 uint32_t num_images; 47 uint8_t bank_state[4]; 48 bool trial_state; 49 50 struct fwu_mdata *fwu_mdata; 51 52 struct fwu_image_entry fwu_images[CONFIG_FWU_NUM_IMAGES_PER_BANK]; 53 }; 54 55 struct fwu_mdata_ops { 56 /** 57 * read_mdata() - Populate the asked FWU metadata copy 58 * @dev: FWU metadata device 59 * @mdata: Output FWU mdata read 60 * @primary: If primary or secondary copy of metadata is to be read 61 * @size: Size in bytes of the metadata to be read 62 * 63 * Return: 0 if OK, -ve on error 64 */ 65 int (*read_mdata)(struct udevice *dev, struct fwu_mdata *mdata, 66 bool primary, uint32_t size); 67 68 /** 69 * write_mdata() - Write the given FWU metadata copy 70 * @dev: FWU metadata device 71 * @mdata: Copy of the FWU metadata to write 72 * @primary: If primary or secondary copy of metadata is to be written 73 * @size: Size in bytes of the metadata to be written 74 * 75 * Return: 0 if OK, -ve on error 76 */ 77 int (*write_mdata)(struct udevice *dev, struct fwu_mdata *mdata, 78 bool primary, uint32_t size); 79 }; 80 81 #define FWU_IMAGE_ACCEPTED 0x1 82 83 #define FWU_BANK_INVALID (uint8_t)0xFF 84 #define FWU_BANK_VALID (uint8_t)0xFE 85 #define FWU_BANK_ACCEPTED (uint8_t)0xFC 86 87 enum { 88 PRIMARY_PART = 1, 89 SECONDARY_PART, 90 BOTH_PARTS, 91 }; 92 93 /* 94 * GUID value defined in the FWU specification for identification 95 * of the FWU metadata partition. 96 */ 97 #define FWU_MDATA_GUID \ 98 EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \ 99 0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23) 100 101 /* 102 * GUID value defined in the Dependable Boot specification for 103 * identification of the revert capsule, used for reverting 104 * any image in the updated bank. 105 */ 106 #define FWU_OS_REQUEST_FW_REVERT_GUID \ 107 EFI_GUID(0xacd58b4b, 0xc0e8, 0x475f, 0x99, 0xb5, \ 108 0x6b, 0x3f, 0x7e, 0x07, 0xaa, 0xf0) 109 110 /* 111 * GUID value defined in the Dependable Boot specification for 112 * identification of the accept capsule, used for accepting 113 * an image in the updated bank. 114 */ 115 #define FWU_OS_REQUEST_FW_ACCEPT_GUID \ 116 EFI_GUID(0x0c996046, 0xbcc0, 0x4d04, 0x85, 0xec, \ 117 0xe1, 0xfc, 0xed, 0xf1, 0xc6, 0xf8) 118 119 /** 120 * fwu_read_mdata() - Wrapper around fwu_mdata_ops.read_mdata() 121 */ 122 int fwu_read_mdata(struct udevice *dev, struct fwu_mdata *mdata, 123 bool primary, uint32_t size); 124 125 /** 126 * fwu_write_mdata() - Wrapper around fwu_mdata_ops.write_mdata() 127 */ 128 int fwu_write_mdata(struct udevice *dev, struct fwu_mdata *mdata, 129 bool primary, uint32_t size); 130 131 /** 132 * fwu_get_mdata() - Read, verify and return the FWU metadata 133 * 134 * Read both the metadata copies from the storage media, verify their checksum, 135 * and ascertain that both copies match. If one of the copies has gone bad, 136 * restore it from the good copy. 137 * 138 * Return: 0 if OK, -ve on error 139 */ 140 int fwu_get_mdata(struct fwu_mdata *mdata); 141 142 /** 143 * fwu_get_active_index() - Get active_index from the FWU metadata 144 * @active_idxp: active_index value to be read 145 * 146 * Read the active_index field from the FWU metadata and place it in 147 * the variable pointed to be the function argument. 148 * 149 * Return: 0 if OK, -ve on error 150 * 151 */ 152 int fwu_get_active_index(uint *active_idxp); 153 154 /** 155 * fwu_set_active_index() - Set active_index in the FWU metadata 156 * @active_idx: active_index value to be set 157 * 158 * Update the active_index field in the FWU metadata 159 * 160 * Return: 0 if OK, -ve on error 161 * 162 */ 163 int fwu_set_active_index(uint active_idx); 164 165 /** 166 * fwu_get_dfu_alt_num() - Get the dfu_alt_num to be used for capsule update 167 * @image_index: The Image Index for the image 168 * @alt_num: pointer to store dfu_alt_num 169 * 170 * Currently, the capsule update driver uses the DFU framework for 171 * the updates. This function gets the DFU alt number which is to 172 * be used for capsule update. 173 * 174 * Return: 0 if OK, -ve on error 175 * 176 */ 177 int fwu_get_dfu_alt_num(u8 image_index, u8 *alt_num); 178 179 /** 180 * fwu_revert_boot_index() - Revert the active index in the FWU metadata 181 * 182 * Revert the active_index value in the FWU metadata, by swapping the values 183 * of active_index and previous_active_index in both copies of the 184 * FWU metadata. 185 * 186 * Return: 0 if OK, -ve on error 187 * 188 */ 189 int fwu_revert_boot_index(void); 190 191 /** 192 * fwu_accept_image() - Set the Acceptance bit for the image 193 * @img_type_id: GUID of the image type for which the accepted bit is to be 194 * cleared 195 * @bank: Bank of which the image's Accept bit is to be set 196 * 197 * Set the accepted bit for the image specified by the img_guid parameter. This 198 * indicates acceptance of image for subsequent boots by some governing component 199 * like OS(or firmware). 200 * 201 * Return: 0 if OK, -ve on error 202 * 203 */ 204 int fwu_accept_image(efi_guid_t *img_type_id, u32 bank); 205 206 /** 207 * fwu_clear_accept_image() - Clear the Acceptance bit for the image 208 * @img_type_id: GUID of the image type for which the accepted bit is to be 209 * cleared 210 * @bank: Bank of which the image's Accept bit is to be cleared 211 * 212 * Clear the accepted bit for the image type specified by the img_type_id parameter. 213 * This function is called after the image has been updated. The accepted bit is 214 * cleared to be set subsequently after passing the image acceptance criteria, by 215 * either the OS(or firmware) 216 * 217 * Return: 0 if OK, -ve on error 218 * 219 */ 220 int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank); 221 222 /** 223 * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform 224 * @dev: FWU device 225 * @image_guid: Image GUID for which DFU alt number needs to be retrieved 226 * @alt_num: Pointer to the alt_num 227 * 228 * Get the DFU alt number from the platform for the image specified by the 229 * image GUID. 230 * 231 * Return: 0 if OK, -ve on error 232 * 233 */ 234 int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid, 235 u8 *alt_num); 236 237 /** 238 * fwu_plat_get_update_index() - Get the value of the update bank 239 * @update_idx: Bank number to which images are to be updated 240 * 241 * Get the value of the bank(partition) to which the update needs to be 242 * made. 243 * 244 * Note: This is a weak function and platforms can override this with 245 * their own implementation for selection of the update bank. 246 * 247 * Return: 0 if OK, -ve on error 248 * 249 */ 250 int fwu_plat_get_update_index(uint *update_idx); 251 252 /** 253 * fwu_plat_get_bootidx() - Get the value of the boot index 254 * @boot_idx: Boot index value 255 * 256 * Get the value of the bank(partition) from which the platform 257 * has booted. This value is passed to U-Boot from the earlier 258 * stage bootloader which loads and boots all the relevant 259 * firmware images 260 * 261 */ 262 void fwu_plat_get_bootidx(uint *boot_idx); 263 264 /** 265 * fwu_update_checks_pass() - Check if FWU update can be done 266 * 267 * Check if the FWU update can be executed. The updates are 268 * allowed only when the platform is not in Trial State and 269 * the boot time checks have passed 270 * 271 * Return: 1 if OK, 0 if checks do not pass 272 * 273 */ 274 u8 fwu_update_checks_pass(void); 275 276 /** 277 * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed 278 * 279 * Check if the empty capsule can be processed to either accept or revert 280 * an earlier executed update. The empty capsules need to be processed 281 * only when the platform is in Trial State and the boot time checks have 282 * passed 283 * 284 * Return: 1 if OK, 0 if not to be allowed 285 * 286 */ 287 u8 fwu_empty_capsule_checks_pass(void); 288 289 /** 290 * fwu_trial_state_ctr_start() - Start the Trial State counter 291 * 292 * Start the counter to identify the platform booting in the 293 * Trial State. The counter is implemented as an EFI variable. 294 * 295 * Return: 0 if OK, -ve on error 296 * 297 */ 298 int fwu_trial_state_ctr_start(void); 299 300 /** 301 * fwu_gen_alt_info_from_mtd() - Parse dfu_alt_info from metadata in mtd 302 * @buf: Buffer into which the dfu_alt_info is filled 303 * @len: Maximum characters that can be written in buf 304 * @mtd: Pointer to underlying MTD device 305 * 306 * Parse dfu_alt_info from metadata in mtd. Used for setting the env. 307 * 308 * Return: 0 if OK, -ve on error 309 */ 310 int fwu_gen_alt_info_from_mtd(char *buf, size_t len, struct mtd_info *mtd); 311 312 /** 313 * fwu_mtd_get_alt_num() - Mapping of fwu_plat_get_alt_num for MTD device 314 * @image_guid: Image GUID for which DFU alt number needs to be retrieved 315 * @alt_num: Pointer to the alt_num 316 * @mtd_dev: Name of mtd device instance 317 * 318 * To map fwu_plat_get_alt_num onto mtd based metadata implementation. 319 * 320 * Return: 0 if OK, -ve on error 321 */ 322 int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev); 323 324 /** 325 * fwu_mdata_copies_allocate() - Allocate memory for metadata 326 * @mdata_size: Size of the metadata structure 327 * 328 * Allocate memory for storing both the copies of the FWU metadata. The 329 * copies are then used as a cache for storing FWU metadata contents. 330 * 331 * Return: 0 if OK, -ve on error 332 */ 333 int fwu_mdata_copies_allocate(u32 mdata_size); 334 335 /** 336 * fwu_get_dev() - Return the FWU metadata device 337 * 338 * Return the pointer to the FWU metadata device. 339 * 340 * Return: Pointer to the FWU metadata dev 341 */ 342 struct udevice *fwu_get_dev(void); 343 344 /** 345 * fwu_get_data() - Return the version agnostic FWU structure 346 * 347 * Return the pointer to the version agnostic FWU structure. 348 * 349 * Return: Pointer to the FWU data structure 350 */ 351 struct fwu_data *fwu_get_data(void); 352 353 /** 354 * fwu_sync_mdata() - Update given meta-data partition(s) with the copy provided 355 * @data: FWU Data structure 356 * @part: Bitmask of FWU metadata partitions to be written to 357 * 358 * Return: 0 if OK, -ve on error 359 */ 360 int fwu_sync_mdata(struct fwu_mdata *mdata, int part); 361 362 /** 363 * fwu_populate_mdata_image_info() - Populate the image information 364 * of the metadata 365 * @data: Version agnostic FWU metadata information 366 * 367 * Populate the image information in the FWU metadata by copying it 368 * from the version agnostic structure. This is done before the 369 * metadata gets written to the storage media. 370 * 371 * Return: None 372 */ 373 void fwu_populate_mdata_image_info(struct fwu_data *data); 374 375 /** 376 * fwu_get_mdata_size() - Get the FWU metadata size 377 * @mdata_size: Size of the metadata structure 378 * 379 * Get the size of the FWU metadata from the structure. This is later used 380 * to allocate memory for the structure. 381 * 382 * Return: 0 if OK, -ve on error 383 */ 384 int fwu_get_mdata_size(uint32_t *mdata_size); 385 386 /** 387 * fwu_state_machine_updates() - Update FWU state of the platform 388 * @trial_state: Is platform transitioning into Trial State 389 * @update_index: Bank number to which images have been updated 390 * 391 * On successful completion of updates, transition the platform to 392 * either Trial State or Regular State. 393 * 394 * To transition the platform to Trial State, start the 395 * TrialStateCtr counter, followed by setting the value of bank_state 396 * field of the metadata to Valid state(applicable only in version 2 397 * of metadata). 398 * 399 * In case, the platform is to transition directly to Regular State, 400 * update the bank_state field of the metadata to Accepted 401 * state(applicable only in version 2 of metadata). 402 * 403 * Return: 0 if OK, -ve on error 404 */ 405 int fwu_state_machine_updates(bool trial_state, uint32_t update_index); 406 407 /** 408 * fwu_init() - FWU specific initialisations 409 * 410 * Carry out some FWU specific initialisations including allocation 411 * of memory for the metadata copies, and reading the FWU metadata 412 * copies into the allocated memory. The metadata fields are then 413 * copied into a version agnostic structure. 414 * 415 * Return: 0 if OK, -ve on error 416 */ 417 int fwu_init(void); 418 419 /** 420 * fwu_bank_accepted() - Has the bank been accepted 421 * @data: Version agnostic FWU metadata information 422 * @bank: Update bank to check 423 * 424 * Check in the given bank if all the images have been accepted. 425 * 426 * Return: true if all images accepted, false otherwise 427 */ 428 bool fwu_bank_accepted(struct fwu_data *data, uint32_t bank); 429 430 #endif /* _FWU_H_ */ 431