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