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 16struct fwu_mdata; 17struct udevice; 18 19struct fwu_mdata_gpt_blk_priv { 20 struct udevice *blk_dev; 21}; 22 23struct fwu_mtd_image_info { 24 u32 start, size; 25 int bank_num, image_num; 26 char uuidbuf[UUID_STR_LEN + 1]; 27}; 28 29struct 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 */ 83int 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 */ 88int 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 */ 99int 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 */ 111int 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 */ 122int fwu_set_active_index(uint active_idx); 123 124/** 125 * fwu_get_dfu_alt_num() - Get the dfu_alt_num to be used for capsule update 126 * @image_index: The Image Index for the image 127 * @alt_num: pointer to store dfu_alt_num 128 * 129 * Currently, the capsule update driver uses the DFU framework for 130 * the updates. This function gets the DFU alt number which is to 131 * be used for capsule update. 132 * 133 * Return: 0 if OK, -ve on error 134 * 135 */ 136int fwu_get_dfu_alt_num(u8 image_index, u8 *alt_num); 137 138/** 139 * fwu_revert_boot_index() - Revert the active index in the FWU metadata 140 * 141 * Revert the active_index value in the FWU metadata, by swapping the values 142 * of active_index and previous_active_index in both copies of the 143 * FWU metadata. 144 * 145 * Return: 0 if OK, -ve on error 146 * 147 */ 148int fwu_revert_boot_index(void); 149 150/** 151 * fwu_accept_image() - Set the Acceptance bit for the image 152 * @img_type_id: GUID of the image type for which the accepted bit is to be 153 * cleared 154 * @bank: Bank of which the image's Accept bit is to be set 155 * 156 * Set the accepted bit for the image specified by the img_guid parameter. This 157 * indicates acceptance of image for subsequent boots by some governing component 158 * like OS(or firmware). 159 * 160 * Return: 0 if OK, -ve on error 161 * 162 */ 163int fwu_accept_image(efi_guid_t *img_type_id, u32 bank); 164 165/** 166 * fwu_clear_accept_image() - Clear the Acceptance bit for the image 167 * @img_type_id: GUID of the image type for which the accepted bit is to be 168 * cleared 169 * @bank: Bank of which the image's Accept bit is to be cleared 170 * 171 * Clear the accepted bit for the image type specified by the img_type_id parameter. 172 * This function is called after the image has been updated. The accepted bit is 173 * cleared to be set subsequently after passing the image acceptance criteria, by 174 * either the OS(or firmware) 175 * 176 * Return: 0 if OK, -ve on error 177 * 178 */ 179int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank); 180 181/** 182 * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform 183 * @dev: FWU device 184 * @image_guid: Image GUID for which DFU alt number needs to be retrieved 185 * @alt_num: Pointer to the alt_num 186 * 187 * Get the DFU alt number from the platform for the image specified by the 188 * image GUID. 189 * 190 * Return: 0 if OK, -ve on error 191 * 192 */ 193int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid, 194 u8 *alt_num); 195 196/** 197 * fwu_plat_get_update_index() - Get the value of the update bank 198 * @update_idx: Bank number to which images are to be updated 199 * 200 * Get the value of the bank(partition) to which the update needs to be 201 * made. 202 * 203 * Note: This is a weak function and platforms can override this with 204 * their own implementation for selection of the update bank. 205 * 206 * Return: 0 if OK, -ve on error 207 * 208 */ 209int fwu_plat_get_update_index(uint *update_idx); 210 211/** 212 * fwu_plat_get_bootidx() - Get the value of the boot index 213 * @boot_idx: Boot index value 214 * 215 * Get the value of the bank(partition) from which the platform 216 * has booted. This value is passed to U-Boot from the earlier 217 * stage bootloader which loads and boots all the relevant 218 * firmware images 219 * 220 */ 221void fwu_plat_get_bootidx(uint *boot_idx); 222 223/** 224 * fwu_update_checks_pass() - Check if FWU update can be done 225 * 226 * Check if the FWU update can be executed. The updates are 227 * allowed only when the platform is not in Trial State and 228 * the boot time checks have passed 229 * 230 * Return: 1 if OK, 0 if checks do not pass 231 * 232 */ 233u8 fwu_update_checks_pass(void); 234 235/** 236 * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed 237 * 238 * Check if the empty capsule can be processed to either accept or revert 239 * an earlier executed update. The empty capsules need to be processed 240 * only when the platform is in Trial State and the boot time checks have 241 * passed 242 * 243 * Return: 1 if OK, 0 if not to be allowed 244 * 245 */ 246u8 fwu_empty_capsule_checks_pass(void); 247 248/** 249 * fwu_trial_state_ctr_start() - Start the Trial State counter 250 * 251 * Start the counter to identify the platform booting in the 252 * Trial State. The counter is implemented as an EFI variable. 253 * 254 * Return: 0 if OK, -ve on error 255 * 256 */ 257int fwu_trial_state_ctr_start(void); 258 259/** 260 * fwu_gen_alt_info_from_mtd() - Parse dfu_alt_info from metadata in mtd 261 * @buf: Buffer into which the dfu_alt_info is filled 262 * @len: Maximum characters that can be written in buf 263 * @mtd: Pointer to underlying MTD device 264 * 265 * Parse dfu_alt_info from metadata in mtd. Used for setting the env. 266 * 267 * Return: 0 if OK, -ve on error 268 */ 269int fwu_gen_alt_info_from_mtd(char *buf, size_t len, struct mtd_info *mtd); 270 271/** 272 * fwu_mtd_get_alt_num() - Mapping of fwu_plat_get_alt_num for MTD device 273 * @image_guid: Image GUID for which DFU alt number needs to be retrieved 274 * @alt_num: Pointer to the alt_num 275 * @mtd_dev: Name of mtd device instance 276 * 277 * To map fwu_plat_get_alt_num onto mtd based metadata implementation. 278 * 279 * Return: 0 if OK, -ve on error 280 */ 281int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev); 282 283#endif /* _FWU_H_ */ 284