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 #include <mtd.h>
  12 #include <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_ops {
  30         /**
  31          * read_mdata() - Populate the asked FWU metadata copy
  32          * @dev: FWU metadata device
  33          * @mdata: Output FWU mdata read
  34          * @primary: If primary or secondary copy of metadata is to be read
  35          *
  36          * Return: 0 if OK, -ve on error
  37          */
  38         int (*read_mdata)(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  39
  40         /**
  41          * write_mdata() - Write the given FWU metadata copy
  42          * @dev: FWU metadata device
  43          * @mdata: Copy of the FWU metadata to write
  44          * @primary: If primary or secondary copy of metadata is to be written
  45          *
  46          * Return: 0 if OK, -ve on error
  47          */
  48         int (*write_mdata)(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  49 };
  50
  51 #define FWU_MDATA_VERSION       0x1
  52 #define FWU_IMAGE_ACCEPTED      0x1
  53
  54 /*
  55 * GUID value defined in the FWU specification for identification
  56 * of the FWU metadata partition.
  57 */
  58 #define FWU_MDATA_GUID \
  59         EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \
  60                  0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23)
  61
  62 /*
  63 * GUID value defined in the Dependable Boot specification for
  64 * identification of the revert capsule, used for reverting
  65 * any image in the updated bank.
  66 */
  67 #define FWU_OS_REQUEST_FW_REVERT_GUID \
  68         EFI_GUID(0xacd58b4b, 0xc0e8, 0x475f, 0x99, 0xb5, \
  69                  0x6b, 0x3f, 0x7e, 0x07, 0xaa, 0xf0)
  70
  71 /*
  72 * GUID value defined in the Dependable Boot specification for
  73 * identification of the accept capsule, used for accepting
  74 * an image in the updated bank.
  75 */
  76 #define FWU_OS_REQUEST_FW_ACCEPT_GUID \
  77         EFI_GUID(0x0c996046, 0xbcc0, 0x4d04, 0x85, 0xec, \
  78                  0xe1, 0xfc, 0xed, 0xf1, 0xc6, 0xf8)
  79
  80 /**
  81  * fwu_read_mdata() - Wrapper around fwu_mdata_ops.read_mdata()
  82  */
  83 int fwu_read_mdata(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  84
  85 /**
  86  * fwu_write_mdata() - Wrapper around fwu_mdata_ops.write_mdata()
  87  */
  88 int fwu_write_mdata(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
  89
  90 /**
  91  * fwu_get_mdata() - Read, verify and return the FWU metadata
  92  *
  93  * Read both the metadata copies from the storage media, verify their checksum,
  94  * and ascertain that both copies match. If one of the copies has gone bad,
  95  * restore it from the good copy.
  96  *
  97  * Return: 0 if OK, -ve on error
  98  */
  99 int fwu_get_mdata(struct fwu_mdata *mdata);
 100
 101 /**
 102  * fwu_get_active_index() - Get active_index from the FWU metadata
 103  * @active_idxp: active_index value to be read
 104  *
 105  * Read the active_index field from the FWU metadata and place it in
 106  * the variable pointed to be the function argument.
 107  *
 108  * Return: 0 if OK, -ve on error
 109  *
 110  */
 111 int fwu_get_active_index(uint *active_idxp);
 112
 113 /**
 114  * fwu_set_active_index() - Set active_index in the FWU metadata
 115  * @active_idx: active_index value to be set
 116  *
 117  * Update the active_index field in the FWU metadata
 118  *
 119  * Return: 0 if OK, -ve on error
 120  *
 121  */
 122 int fwu_set_active_index(uint active_idx);
 123
 124 /**
 125  * fwu_get_image_index() - Get the Image Index to be used for capsule update
 126  * @image_index: The Image Index for the image
 127  *
 128  * The FWU multi bank update feature computes the value of image_index at
 129  * runtime, based on the bank to which the image needs to be written to.
 130  * Derive the image_index value for the image.
 131  *
 132  * Currently, the capsule update driver uses the DFU framework for
 133  * the updates. This function gets the DFU alt number which is to
 134  * be used as the Image Index
 135  *
 136  * Return: 0 if OK, -ve on error
 137  *
 138  */
 139 int fwu_get_image_index(u8 *image_index);
 140
 141 /**
 142  * fwu_revert_boot_index() - Revert the active index in the FWU metadata
 143  *
 144  * Revert the active_index value in the FWU metadata, by swapping the values
 145  * of active_index and previous_active_index in both copies of the
 146  * FWU metadata.
 147  *
 148  * Return: 0 if OK, -ve on error
 149  *
 150  */
 151 int fwu_revert_boot_index(void);
 152
 153 /**
 154  * fwu_accept_image() - Set the Acceptance bit for the image
 155  * @img_type_id: GUID of the image type for which the accepted bit is to be
 156  *               cleared
 157  * @bank: Bank of which the image's Accept bit is to be set
 158  *
 159  * Set the accepted bit for the image specified by the img_guid parameter. This
 160  * indicates acceptance of image for subsequent boots by some governing component
 161  * like OS(or firmware).
 162  *
 163  * Return: 0 if OK, -ve on error
 164  *
 165  */
 166 int fwu_accept_image(efi_guid_t *img_type_id, u32 bank);
 167
 168 /**
 169  * fwu_clear_accept_image() - Clear the Acceptance bit for the image
 170  * @img_type_id: GUID of the image type for which the accepted bit is to be
 171  *               cleared
 172  * @bank: Bank of which the image's Accept bit is to be cleared
 173  *
 174  * Clear the accepted bit for the image type specified by the img_type_id parameter.
 175  * This function is called after the image has been updated. The accepted bit is
 176  * cleared to be set subsequently after passing the image acceptance criteria, by
 177  * either the OS(or firmware)
 178  *
 179  * Return: 0 if OK, -ve on error
 180  *
 181  */
 182 int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank);
 183
 184 /**
 185  * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform
 186  * @dev: FWU device
 187  * @image_guid: Image GUID for which DFU alt number needs to be retrieved
 188  * @alt_num: Pointer to the alt_num
 189  *
 190  * Get the DFU alt number from the platform for the image specified by the
 191  * image GUID.
 192  *
 193  * Return: 0 if OK, -ve on error
 194  *
 195  */
 196 int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid,
 197                          u8 *alt_num);
 198
 199 /**
 200  * fwu_plat_get_update_index() - Get the value of the update bank
 201  * @update_idx: Bank number to which images are to be updated
 202  *
 203  * Get the value of the bank(partition) to which the update needs to be
 204  * made.
 205  *
 206  * Note: This is a weak function and platforms can override this with
 207  * their own implementation for selection of the update bank.
 208  *
 209  * Return: 0 if OK, -ve on error
 210  *
 211  */
 212 int fwu_plat_get_update_index(uint *update_idx);
 213
 214 /**
 215  * fwu_plat_get_bootidx() - Get the value of the boot index
 216  * @boot_idx: Boot index value
 217  *
 218  * Get the value of the bank(partition) from which the platform
 219  * has booted. This value is passed to U-Boot from the earlier
 220  * stage bootloader which loads and boots all the relevant
 221  * firmware images
 222  *
 223  */
 224 void fwu_plat_get_bootidx(uint *boot_idx);
 225
 226 /**
 227  * fwu_update_checks_pass() - Check if FWU update can be done
 228  *
 229  * Check if the FWU update can be executed. The updates are
 230  * allowed only when the platform is not in Trial State and
 231  * the boot time checks have passed
 232  *
 233  * Return: 1 if OK, 0 if checks do not pass
 234  *
 235  */
 236 u8 fwu_update_checks_pass(void);
 237
 238 /**
 239  * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed
 240  *
 241  * Check if the empty capsule can be processed to either accept or revert
 242  * an earlier executed update. The empty capsules need to be processed
 243  * only when the platform is in Trial State and the boot time checks have
 244  * passed
 245  *
 246  * Return: 1 if OK, 0 if not to be allowed
 247  *
 248  */
 249 u8 fwu_empty_capsule_checks_pass(void);
 250
 251 /**
 252  * fwu_trial_state_ctr_start() - Start the Trial State counter
 253  *
 254  * Start the counter to identify the platform booting in the
 255  * Trial State. The counter is implemented as an EFI variable.
 256  *
 257  * Return: 0 if OK, -ve on error
 258  *
 259  */
 260 int fwu_trial_state_ctr_start(void);
 261
 262 /**
 263  * fwu_gen_alt_info_from_mtd() - Parse dfu_alt_info from metadata in mtd
 264  * @buf: Buffer into which the dfu_alt_info is filled
 265  * @len: Maximum characters that can be written in buf
 266  * @mtd: Pointer to underlying MTD device
 267  *
 268  * Parse dfu_alt_info from metadata in mtd. Used for setting the env.
 269  *
 270  * Return: 0 if OK, -ve on error
 271  */
 272 int fwu_gen_alt_info_from_mtd(char *buf, size_t len, struct mtd_info *mtd);
 273
 274 /**
 275  * fwu_mtd_get_alt_num() - Mapping of fwu_plat_get_alt_num for MTD device
 276  * @image_guid: Image GUID for which DFU alt number needs to be retrieved
 277  * @alt_num: Pointer to the alt_num
 278  * @mtd_dev: Name of mtd device instance
 279  *
 280  * To map fwu_plat_get_alt_num onto mtd based metadata implementation.
 281  *
 282  * Return: 0 if OK, -ve on error
 283  */
 284 int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev);
 285
 286 #endif /* _FWU_H_ */