include/fwu.h

   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_ */