]>
Commit | Line | Data |
---|---|---|
2eaedc95 SG |
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> | |
4898679e MH |
11 | #include <mtd.h> |
12 | #include <uuid.h> | |
2eaedc95 SG |
13 | |
14 | #include <linux/types.h> | |
15 | ||
16 | struct fwu_mdata; | |
17 | struct udevice; | |
18 | ||
554b38f7 SG |
19 | struct fwu_mdata_gpt_blk_priv { |
20 | struct udevice *blk_dev; | |
21 | }; | |
22 | ||
4898679e MH |
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 | ||
2eaedc95 | 29 | struct fwu_mdata_ops { |
167994f2 JB |
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); | |
2eaedc95 SG |
49 | }; |
50 | ||
51 | #define FWU_MDATA_VERSION 0x1 | |
86794052 | 52 | #define FWU_IMAGE_ACCEPTED 0x1 |
2eaedc95 SG |
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 | ||
86794052 SG |
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 | ||
167994f2 JB |
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 | /** | |
1e917a69 | 91 | * fwu_get_mdata() - Read, verify and return the FWU metadata |
167994f2 JB |
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 | */ | |
1e917a69 | 99 | int fwu_get_mdata(struct fwu_mdata *mdata); |
167994f2 | 100 | |
2eaedc95 SG |
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 | /** | |
af7a34ac MK |
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 | |
2eaedc95 SG |
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 | |
af7a34ac | 131 | * be used for capsule update. |
2eaedc95 SG |
132 | * |
133 | * Return: 0 if OK, -ve on error | |
134 | * | |
135 | */ | |
af7a34ac | 136 | int fwu_get_dfu_alt_num(u8 image_index, u8 *alt_num); |
2eaedc95 | 137 | |
2eaedc95 SG |
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 | */ | |
148 | int fwu_revert_boot_index(void); | |
149 | ||
2eaedc95 SG |
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 | */ | |
163 | int 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 | */ | |
179 | int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank); | |
180 | ||
7d6e2c54 SG |
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 | */ | |
193 | int 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 | */ | |
209 | int fwu_plat_get_update_index(uint *update_idx); | |
95b5a7de SG |
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 | */ | |
221 | void fwu_plat_get_bootidx(uint *boot_idx); | |
7e9814cc SG |
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 | */ | |
233 | u8 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 | */ | |
246 | u8 fwu_empty_capsule_checks_pass(void); | |
247 | ||
86794052 SG |
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 | */ | |
257 | int fwu_trial_state_ctr_start(void); | |
258 | ||
4898679e MH |
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 | */ | |
269 | int 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 | */ | |
281 | int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev); | |
282 | ||
2eaedc95 | 283 | #endif /* _FWU_H_ */ |