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 12 #include <linux/types.h> 13 14 struct fwu_mdata; 15 struct udevice; 16 17 struct fwu_mdata_gpt_blk_priv { 18 struct udevice *blk_dev; 19 }; 20 21 /** 22 * @mdata_check: check the validity of the FWU metadata partitions 23 * @get_mdata() - Get a FWU metadata copy 24 * @update_mdata() - Update the FWU metadata copy 25 */ 26 struct fwu_mdata_ops { 27 /** 28 * check_mdata() - Check if the FWU metadata is valid 29 * @dev: FWU device 30 * 31 * Validate both copies of the FWU metadata. If one of the copies 32 * has gone bad, restore it from the other copy. 33 * 34 * Return: 0 if OK, -ve on error 35 */ 36 int (*check_mdata)(struct udevice *dev); 37 38 /** 39 * get_mdata() - Get a FWU metadata copy 40 * @dev: FWU device 41 * @mdata: Pointer to FWU metadata 42 * 43 * Get a valid copy of the FWU metadata. 44 * 45 * Return: 0 if OK, -ve on error 46 */ 47 int (*get_mdata)(struct udevice *dev, struct fwu_mdata *mdata); 48 49 /** 50 * update_mdata() - Update the FWU metadata 51 * @dev: FWU device 52 * @mdata: Copy of the FWU metadata 53 * 54 * Update the FWU metadata structure by writing to the 55 * FWU metadata partitions. 56 * 57 * Return: 0 if OK, -ve on error 58 */ 59 int (*update_mdata)(struct udevice *dev, struct fwu_mdata *mdata); 60 61 /** 62 * get_mdata_part_num() - Get the FWU metadata partition numbers 63 * @dev: FWU metadata device 64 * @mdata_parts: array for storing the metadata partition numbers 65 * 66 * Get the partition numbers on the storage device on which the 67 * FWU metadata is stored. Two partition numbers will be returned. 68 * 69 * Return: 0 if OK, -ve on error 70 */ 71 int (*get_mdata_part_num)(struct udevice *dev, uint *mdata_parts); 72 73 /** 74 * read_mdata_partition() - Read the FWU metadata from a partition 75 * @dev: FWU metadata device 76 * @mdata: Copy of the FWU metadata 77 * @part_num: Partition number from which FWU metadata is to be read 78 * 79 * Read the FWU metadata from the specified partition number 80 * 81 * Return: 0 if OK, -ve on error 82 */ 83 int (*read_mdata_partition)(struct udevice *dev, 84 struct fwu_mdata *mdata, uint part_num); 85 86 /** 87 * write_mdata_partition() - Write the FWU metadata to a partition 88 * @dev: FWU metadata device 89 * @mdata: Copy of the FWU metadata 90 * @part_num: Partition number to which FWU metadata is to be written 91 * 92 * Write the FWU metadata to the specified partition number 93 * 94 * Return: 0 if OK, -ve on error 95 */ 96 int (*write_mdata_partition)(struct udevice *dev, 97 struct fwu_mdata *mdata, uint part_num); 98 }; 99 100 #define FWU_MDATA_VERSION 0x1 101 #define FWU_IMAGE_ACCEPTED 0x1 102 103 /* 104 * GUID value defined in the FWU specification for identification 105 * of the FWU metadata partition. 106 */ 107 #define FWU_MDATA_GUID \ 108 EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \ 109 0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23) 110 111 /* 112 * GUID value defined in the Dependable Boot specification for 113 * identification of the revert capsule, used for reverting 114 * any image in the updated bank. 115 */ 116 #define FWU_OS_REQUEST_FW_REVERT_GUID \ 117 EFI_GUID(0xacd58b4b, 0xc0e8, 0x475f, 0x99, 0xb5, \ 118 0x6b, 0x3f, 0x7e, 0x07, 0xaa, 0xf0) 119 120 /* 121 * GUID value defined in the Dependable Boot specification for 122 * identification of the accept capsule, used for accepting 123 * an image in the updated bank. 124 */ 125 #define FWU_OS_REQUEST_FW_ACCEPT_GUID \ 126 EFI_GUID(0x0c996046, 0xbcc0, 0x4d04, 0x85, 0xec, \ 127 0xe1, 0xfc, 0xed, 0xf1, 0xc6, 0xf8) 128 129 /** 130 * fwu_check_mdata_validity() - Check for validity of the FWU metadata copies 131 * 132 * Read both the metadata copies from the storage media, verify their 133 * checksum, and ascertain that both copies match. If one of the copies 134 * has gone bad, restore it from the good copy. 135 * 136 * Return: 0 if OK, -ve on error 137 * 138 */ 139 int fwu_check_mdata_validity(void); 140 141 /** 142 * fwu_get_mdata_part_num() - Get the FWU metadata partition numbers 143 * @dev: FWU metadata device 144 * @mdata_parts: array for storing the metadata partition numbers 145 * 146 * Get the partition numbers on the storage device on which the 147 * FWU metadata is stored. Two partition numbers will be returned 148 * through the array. 149 * 150 * Return: 0 if OK, -ve on error 151 * 152 */ 153 int fwu_get_mdata_part_num(struct udevice *dev, uint *mdata_parts); 154 155 /** 156 * fwu_read_mdata_partition() - Read the FWU metadata from a partition 157 * @dev: FWU metadata device 158 * @mdata: Copy of the FWU metadata 159 * @part_num: Partition number from which FWU metadata is to be read 160 * 161 * Read the FWU metadata from the specified partition number 162 * 163 * Return: 0 if OK, -ve on error 164 * 165 */ 166 int fwu_read_mdata_partition(struct udevice *dev, struct fwu_mdata *mdata, 167 uint part_num); 168 169 /** 170 * fwu_write_mdata_partition() - Write the FWU metadata to a partition 171 * @dev: FWU metadata device 172 * @mdata: Copy of the FWU metadata 173 * @part_num: Partition number to which FWU metadata is to be written 174 * 175 * Write the FWU metadata to the specified partition number 176 * 177 * Return: 0 if OK, -ve on error 178 * 179 */ 180 int fwu_write_mdata_partition(struct udevice *dev, struct fwu_mdata *mdata, 181 uint part_num); 182 183 /** 184 * fwu_get_mdata() - Get a FWU metadata copy 185 * @dev: FWU metadata device 186 * @mdata: Copy of the FWU metadata 187 * 188 * Get a valid copy of the FWU metadata. 189 * 190 * Note: This function is to be called first when modifying any fields 191 * in the metadata. The sequence of calls to modify any field in the 192 * metadata would be 1) fwu_get_mdata 2) Modify metadata, followed by 193 * 3) fwu_update_mdata 194 * 195 * Return: 0 if OK, -ve on error 196 * 197 */ 198 int fwu_get_mdata(struct udevice *dev, struct fwu_mdata *mdata); 199 200 /** 201 * fwu_update_mdata() - Update the FWU metadata 202 * @dev: FWU metadata device 203 * @mdata: Copy of the FWU metadata 204 * 205 * Update the FWU metadata structure by writing to the 206 * FWU metadata partitions. 207 * 208 * Note: This function is not to be called directly to update the 209 * metadata fields. The sequence of function calls should be 210 * 1) fwu_get_mdata() 2) Modify the medata fields 3) fwu_update_mdata() 211 * 212 * The sequence of updating the partitions should be, update the 213 * primary metadata partition (first partition encountered), followed 214 * by updating the secondary partition. With this update sequence, in 215 * the rare scenario that the two metadata partitions are valid but do 216 * not match, maybe due to power outage at the time of updating the 217 * metadata copies, the secondary partition can be updated from the 218 * primary. 219 * 220 * Return: 0 if OK, -ve on error 221 * 222 */ 223 int fwu_update_mdata(struct udevice *dev, struct fwu_mdata *mdata); 224 225 /** 226 * fwu_get_active_index() - Get active_index from the FWU metadata 227 * @active_idxp: active_index value to be read 228 * 229 * Read the active_index field from the FWU metadata and place it in 230 * the variable pointed to be the function argument. 231 * 232 * Return: 0 if OK, -ve on error 233 * 234 */ 235 int fwu_get_active_index(uint *active_idxp); 236 237 /** 238 * fwu_set_active_index() - Set active_index in the FWU metadata 239 * @active_idx: active_index value to be set 240 * 241 * Update the active_index field in the FWU metadata 242 * 243 * Return: 0 if OK, -ve on error 244 * 245 */ 246 int fwu_set_active_index(uint active_idx); 247 248 /** 249 * fwu_get_image_index() - Get the Image Index to be used for capsule update 250 * @image_index: The Image Index for the image 251 * 252 * The FWU multi bank update feature computes the value of image_index at 253 * runtime, based on the bank to which the image needs to be written to. 254 * Derive the image_index value for the image. 255 * 256 * Currently, the capsule update driver uses the DFU framework for 257 * the updates. This function gets the DFU alt number which is to 258 * be used as the Image Index 259 * 260 * Return: 0 if OK, -ve on error 261 * 262 */ 263 int fwu_get_image_index(u8 *image_index); 264 265 /** 266 * fwu_mdata_check() - Check if the FWU metadata is valid 267 * @dev: FWU metadata device 268 * 269 * Validate both copies of the FWU metadata. If one of the copies 270 * has gone bad, restore it from the other copy. 271 * 272 * Return: 0 if OK, -ve on error 273 * 274 */ 275 int fwu_mdata_check(struct udevice *dev); 276 277 /** 278 * fwu_revert_boot_index() - Revert the active index in the FWU metadata 279 * 280 * Revert the active_index value in the FWU metadata, by swapping the values 281 * of active_index and previous_active_index in both copies of the 282 * FWU metadata. 283 * 284 * Return: 0 if OK, -ve on error 285 * 286 */ 287 int fwu_revert_boot_index(void); 288 289 /** 290 * fwu_verify_mdata() - Verify the FWU metadata 291 * @mdata: FWU metadata structure 292 * @pri_part: FWU metadata partition is primary or secondary 293 * 294 * Verify the FWU metadata by computing the CRC32 for the metadata 295 * structure and comparing it against the CRC32 value stored as part 296 * of the structure. 297 * 298 * Return: 0 if OK, -ve on error 299 * 300 */ 301 int fwu_verify_mdata(struct fwu_mdata *mdata, bool pri_part); 302 303 /** 304 * fwu_accept_image() - Set the Acceptance bit for the image 305 * @img_type_id: GUID of the image type for which the accepted bit is to be 306 * cleared 307 * @bank: Bank of which the image's Accept bit is to be set 308 * 309 * Set the accepted bit for the image specified by the img_guid parameter. This 310 * indicates acceptance of image for subsequent boots by some governing component 311 * like OS(or firmware). 312 * 313 * Return: 0 if OK, -ve on error 314 * 315 */ 316 int fwu_accept_image(efi_guid_t *img_type_id, u32 bank); 317 318 /** 319 * fwu_clear_accept_image() - Clear the Acceptance bit for the image 320 * @img_type_id: GUID of the image type for which the accepted bit is to be 321 * cleared 322 * @bank: Bank of which the image's Accept bit is to be cleared 323 * 324 * Clear the accepted bit for the image type specified by the img_type_id parameter. 325 * This function is called after the image has been updated. The accepted bit is 326 * cleared to be set subsequently after passing the image acceptance criteria, by 327 * either the OS(or firmware) 328 * 329 * Return: 0 if OK, -ve on error 330 * 331 */ 332 int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank); 333 334 /** 335 * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform 336 * @dev: FWU device 337 * @image_guid: Image GUID for which DFU alt number needs to be retrieved 338 * @alt_num: Pointer to the alt_num 339 * 340 * Get the DFU alt number from the platform for the image specified by the 341 * image GUID. 342 * 343 * Return: 0 if OK, -ve on error 344 * 345 */ 346 int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid, 347 u8 *alt_num); 348 349 /** 350 * fwu_plat_get_update_index() - Get the value of the update bank 351 * @update_idx: Bank number to which images are to be updated 352 * 353 * Get the value of the bank(partition) to which the update needs to be 354 * made. 355 * 356 * Note: This is a weak function and platforms can override this with 357 * their own implementation for selection of the update bank. 358 * 359 * Return: 0 if OK, -ve on error 360 * 361 */ 362 int fwu_plat_get_update_index(uint *update_idx); 363 364 /** 365 * fwu_plat_get_bootidx() - Get the value of the boot index 366 * @boot_idx: Boot index value 367 * 368 * Get the value of the bank(partition) from which the platform 369 * has booted. This value is passed to U-Boot from the earlier 370 * stage bootloader which loads and boots all the relevant 371 * firmware images 372 * 373 */ 374 void fwu_plat_get_bootidx(uint *boot_idx); 375 376 /** 377 * fwu_update_checks_pass() - Check if FWU update can be done 378 * 379 * Check if the FWU update can be executed. The updates are 380 * allowed only when the platform is not in Trial State and 381 * the boot time checks have passed 382 * 383 * Return: 1 if OK, 0 if checks do not pass 384 * 385 */ 386 u8 fwu_update_checks_pass(void); 387 388 /** 389 * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed 390 * 391 * Check if the empty capsule can be processed to either accept or revert 392 * an earlier executed update. The empty capsules need to be processed 393 * only when the platform is in Trial State and the boot time checks have 394 * passed 395 * 396 * Return: 1 if OK, 0 if not to be allowed 397 * 398 */ 399 u8 fwu_empty_capsule_checks_pass(void); 400 401 /** 402 * fwu_trial_state_ctr_start() - Start the Trial State counter 403 * 404 * Start the counter to identify the platform booting in the 405 * Trial State. The counter is implemented as an EFI variable. 406 * 407 * Return: 0 if OK, -ve on error 408 * 409 */ 410 int fwu_trial_state_ctr_start(void); 411 412 #endif /* _FWU_H_ */ 413