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
 102 /*
 103 * GUID value defined in the FWU specification for identification
 104 * of the FWU metadata partition.
 105 */
 106 #define FWU_MDATA_GUID \
 107         EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \
 108                  0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23)
 109
 110 /**
 111  * fwu_check_mdata_validity() - Check for validity of the FWU metadata copies
 112  *
 113  * Read both the metadata copies from the storage media, verify their
 114  * checksum, and ascertain that both copies match. If one of the copies
 115  * has gone bad, restore it from the good copy.
 116  *
 117  * Return: 0 if OK, -ve on error
 118  *
 119  */
 120 int fwu_check_mdata_validity(void);
 121
 122 /**
 123  * fwu_get_mdata_part_num() - Get the FWU metadata partition numbers
 124  * @dev: FWU metadata device
 125  * @mdata_parts: array for storing the metadata partition numbers
 126  *
 127  * Get the partition numbers on the storage device on which the
 128  * FWU metadata is stored. Two partition numbers will be returned
 129  * through the array.
 130  *
 131  * Return: 0 if OK, -ve on error
 132  *
 133  */
 134 int fwu_get_mdata_part_num(struct udevice *dev, uint *mdata_parts);
 135
 136 /**
 137  * fwu_read_mdata_partition() - Read the FWU metadata from a partition
 138  * @dev: FWU metadata device
 139  * @mdata: Copy of the FWU metadata
 140  * @part_num: Partition number from which FWU metadata is to be read
 141  *
 142  * Read the FWU metadata from the specified partition number
 143  *
 144  * Return: 0 if OK, -ve on error
 145  *
 146  */
 147 int fwu_read_mdata_partition(struct udevice *dev, struct fwu_mdata *mdata,
 148                              uint part_num);
 149
 150 /**
 151  * fwu_write_mdata_partition() - Write the FWU metadata to a partition
 152  * @dev: FWU metadata device
 153  * @mdata: Copy of the FWU metadata
 154  * @part_num: Partition number to which FWU metadata is to be written
 155  *
 156  * Write the FWU metadata to the specified partition number
 157  *
 158  * Return: 0 if OK, -ve on error
 159  *
 160  */
 161 int fwu_write_mdata_partition(struct udevice *dev, struct fwu_mdata *mdata,
 162                               uint part_num);
 163
 164 /**
 165  * fwu_get_mdata() - Get a FWU metadata copy
 166  * @dev: FWU metadata device
 167  * @mdata: Copy of the FWU metadata
 168  *
 169  * Get a valid copy of the FWU metadata.
 170  *
 171  * Note: This function is to be called first when modifying any fields
 172  * in the metadata. The sequence of calls to modify any field in the
 173  * metadata would  be 1) fwu_get_mdata 2) Modify metadata, followed by
 174  * 3) fwu_update_mdata
 175  *
 176  * Return: 0 if OK, -ve on error
 177  *
 178  */
 179 int fwu_get_mdata(struct udevice *dev, struct fwu_mdata *mdata);
 180
 181 /**
 182  * fwu_update_mdata() - Update the FWU metadata
 183  * @dev: FWU metadata device
 184  * @mdata: Copy of the FWU metadata
 185  *
 186  * Update the FWU metadata structure by writing to the
 187  * FWU metadata partitions.
 188  *
 189  * Note: This function is not to be called directly to update the
 190  * metadata fields. The sequence of function calls should be
 191  * 1) fwu_get_mdata() 2) Modify the medata fields 3) fwu_update_mdata()
 192  *
 193  * The sequence of updating the partitions should be, update the
 194  * primary metadata partition (first partition encountered), followed
 195  * by updating the secondary partition. With this update sequence, in
 196  * the rare scenario that the two metadata partitions are valid but do
 197  * not match, maybe due to power outage at the time of updating the
 198  * metadata copies, the secondary partition can be updated from the
 199  * primary.
 200  *
 201  * Return: 0 if OK, -ve on error
 202  *
 203  */
 204 int fwu_update_mdata(struct udevice *dev, struct fwu_mdata *mdata);
 205
 206 /**
 207  * fwu_get_active_index() - Get active_index from the FWU metadata
 208  * @active_idxp: active_index value to be read
 209  *
 210  * Read the active_index field from the FWU metadata and place it in
 211  * the variable pointed to be the function argument.
 212  *
 213  * Return: 0 if OK, -ve on error
 214  *
 215  */
 216 int fwu_get_active_index(uint *active_idxp);
 217
 218 /**
 219  * fwu_set_active_index() - Set active_index in the FWU metadata
 220  * @active_idx: active_index value to be set
 221  *
 222  * Update the active_index field in the FWU metadata
 223  *
 224  * Return: 0 if OK, -ve on error
 225  *
 226  */
 227 int fwu_set_active_index(uint active_idx);
 228
 229 /**
 230  * fwu_get_image_index() - Get the Image Index to be used for capsule update
 231  * @image_index: The Image Index for the image
 232  *
 233  * The FWU multi bank update feature computes the value of image_index at
 234  * runtime, based on the bank to which the image needs to be written to.
 235  * Derive the image_index value for the image.
 236  *
 237  * Currently, the capsule update driver uses the DFU framework for
 238  * the updates. This function gets the DFU alt number which is to
 239  * be used as the Image Index
 240  *
 241  * Return: 0 if OK, -ve on error
 242  *
 243  */
 244 int fwu_get_image_index(u8 *image_index);
 245
 246 /**
 247  * fwu_mdata_check() - Check if the FWU metadata is valid
 248  * @dev: FWU metadata device
 249  *
 250  * Validate both copies of the FWU metadata. If one of the copies
 251  * has gone bad, restore it from the other copy.
 252  *
 253  * Return: 0 if OK, -ve on error
 254  *
 255  */
 256 int fwu_mdata_check(struct udevice *dev);
 257
 258 /**
 259  * fwu_revert_boot_index() - Revert the active index in the FWU metadata
 260  *
 261  * Revert the active_index value in the FWU metadata, by swapping the values
 262  * of active_index and previous_active_index in both copies of the
 263  * FWU metadata.
 264  *
 265  * Return: 0 if OK, -ve on error
 266  *
 267  */
 268 int fwu_revert_boot_index(void);
 269
 270 /**
 271  * fwu_verify_mdata() - Verify the FWU metadata
 272  * @mdata: FWU metadata structure
 273  * @pri_part: FWU metadata partition is primary or secondary
 274  *
 275  * Verify the FWU metadata by computing the CRC32 for the metadata
 276  * structure and comparing it against the CRC32 value stored as part
 277  * of the structure.
 278  *
 279  * Return: 0 if OK, -ve on error
 280  *
 281  */
 282 int fwu_verify_mdata(struct fwu_mdata *mdata, bool pri_part);
 283
 284 /**
 285  * fwu_accept_image() - Set the Acceptance bit for the image
 286  * @img_type_id: GUID of the image type for which the accepted bit is to be
 287  *               cleared
 288  * @bank: Bank of which the image's Accept bit is to be set
 289  *
 290  * Set the accepted bit for the image specified by the img_guid parameter. This
 291  * indicates acceptance of image for subsequent boots by some governing component
 292  * like OS(or firmware).
 293  *
 294  * Return: 0 if OK, -ve on error
 295  *
 296  */
 297 int fwu_accept_image(efi_guid_t *img_type_id, u32 bank);
 298
 299 /**
 300  * fwu_clear_accept_image() - Clear the Acceptance bit for the image
 301  * @img_type_id: GUID of the image type for which the accepted bit is to be
 302  *               cleared
 303  * @bank: Bank of which the image's Accept bit is to be cleared
 304  *
 305  * Clear the accepted bit for the image type specified by the img_type_id parameter.
 306  * This function is called after the image has been updated. The accepted bit is
 307  * cleared to be set subsequently after passing the image acceptance criteria, by
 308  * either the OS(or firmware)
 309  *
 310  * Return: 0 if OK, -ve on error
 311  *
 312  */
 313 int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank);
 314
 315 /**
 316  * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform
 317  * @dev: FWU device
 318  * @image_guid: Image GUID for which DFU alt number needs to be retrieved
 319  * @alt_num: Pointer to the alt_num
 320  *
 321  * Get the DFU alt number from the platform for the image specified by the
 322  * image GUID.
 323  *
 324  * Return: 0 if OK, -ve on error
 325  *
 326  */
 327 int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid,
 328                          u8 *alt_num);
 329
 330 /**
 331  * fwu_plat_get_update_index() - Get the value of the update bank
 332  * @update_idx: Bank number to which images are to be updated
 333  *
 334  * Get the value of the bank(partition) to which the update needs to be
 335  * made.
 336  *
 337  * Note: This is a weak function and platforms can override this with
 338  * their own implementation for selection of the update bank.
 339  *
 340  * Return: 0 if OK, -ve on error
 341  *
 342  */
 343 int fwu_plat_get_update_index(uint *update_idx);
 344
 345 /**
 346  * fwu_plat_get_bootidx() - Get the value of the boot index
 347  * @boot_idx: Boot index value
 348  *
 349  * Get the value of the bank(partition) from which the platform
 350  * has booted. This value is passed to U-Boot from the earlier
 351  * stage bootloader which loads and boots all the relevant
 352  * firmware images
 353  *
 354  */
 355 void fwu_plat_get_bootidx(uint *boot_idx);
 356
 357 /**
 358  * fwu_update_checks_pass() - Check if FWU update can be done
 359  *
 360  * Check if the FWU update can be executed. The updates are
 361  * allowed only when the platform is not in Trial State and
 362  * the boot time checks have passed
 363  *
 364  * Return: 1 if OK, 0 if checks do not pass
 365  *
 366  */
 367 u8 fwu_update_checks_pass(void);
 368
 369 /**
 370  * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed
 371  *
 372  * Check if the empty capsule can be processed to either accept or revert
 373  * an earlier executed update. The empty capsules need to be processed
 374  * only when the platform is in Trial State and the boot time checks have
 375  * passed
 376  *
 377  * Return: 1 if OK, 0 if not to be allowed
 378  *
 379  */
 380 u8 fwu_empty_capsule_checks_pass(void);
 381
 382 #endif /* _FWU_H_ */