jcs.org
"Das U-Boot" Source Tree
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 <fwu_mdata.h>
12#include <mtd.h>
13#include <u-boot/uuid.h>
14
15#include <linux/types.h>
16
17struct fwu_mdata;
18struct udevice;
19
20struct fwu_mdata_gpt_blk_priv {
21 struct udevice *blk_dev;
22};
23
24struct fwu_mtd_image_info {
25 u32 start, size;
26 int bank_num, image_num;
27 char uuidbuf[UUID_STR_LEN + 1];
28};
29
30struct fwu_mdata_mtd_priv {
31 struct mtd_info *mtd;
32 char pri_label[50];
33 char sec_label[50];
34 u32 pri_offset;
35 u32 sec_offset;
36 struct fwu_mtd_image_info *fwu_mtd_images;
37};
38
39struct fwu_data {
40 uint32_t crc32;
41 uint32_t version;
42 uint32_t active_index;
43 uint32_t previous_active_index;
44 uint32_t metadata_size;
45 uint32_t boot_index;
46 uint32_t num_banks;
47 uint32_t num_images;
48 uint8_t bank_state[4];
49 bool trial_state;
50
51 struct fwu_mdata *fwu_mdata;
52
53 struct fwu_image_entry fwu_images[CONFIG_FWU_NUM_IMAGES_PER_BANK];
54};
55
56struct fwu_mdata_ops {
57 /**
58 * read_mdata() - Populate the asked FWU metadata copy
59 * @dev: FWU metadata device
60 * @mdata: Output FWU mdata read
61 * @primary: If primary or secondary copy of metadata is to be read
62 * @size: Size in bytes of the metadata to be read
63 *
64 * Return: 0 if OK, -ve on error
65 */
66 int (*read_mdata)(struct udevice *dev, struct fwu_mdata *mdata,
67 bool primary, uint32_t size);
68
69 /**
70 * write_mdata() - Write the given FWU metadata copy
71 * @dev: FWU metadata device
72 * @mdata: Copy of the FWU metadata to write
73 * @primary: If primary or secondary copy of metadata is to be written
74 * @size: Size in bytes of the metadata to be written
75 *
76 * Return: 0 if OK, -ve on error
77 */
78 int (*write_mdata)(struct udevice *dev, struct fwu_mdata *mdata,
79 bool primary, uint32_t size);
80};
81
82#define FWU_IMAGE_ACCEPTED 0x1
83
84#define FWU_BANK_INVALID (uint8_t)0xFF
85#define FWU_BANK_VALID (uint8_t)0xFE
86#define FWU_BANK_ACCEPTED (uint8_t)0xFC
87
88enum {
89 PRIMARY_PART = 1,
90 SECONDARY_PART,
91 BOTH_PARTS,
92};
93
94/*
95* GUID value defined in the FWU specification for identification
96* of the FWU metadata partition.
97*/
98#define FWU_MDATA_GUID \
99 EFI_GUID(0x8a7a84a0, 0x8387, 0x40f6, 0xab, 0x41, \
100 0xa8, 0xb9, 0xa5, 0xa6, 0x0d, 0x23)
101
102/*
103* GUID value defined in the Dependable Boot specification for
104* identification of the revert capsule, used for reverting
105* any image in the updated bank.
106*/
107#define FWU_OS_REQUEST_FW_REVERT_GUID \
108 EFI_GUID(0xacd58b4b, 0xc0e8, 0x475f, 0x99, 0xb5, \
109 0x6b, 0x3f, 0x7e, 0x07, 0xaa, 0xf0)
110
111/*
112* GUID value defined in the Dependable Boot specification for
113* identification of the accept capsule, used for accepting
114* an image in the updated bank.
115*/
116#define FWU_OS_REQUEST_FW_ACCEPT_GUID \
117 EFI_GUID(0x0c996046, 0xbcc0, 0x4d04, 0x85, 0xec, \
118 0xe1, 0xfc, 0xed, 0xf1, 0xc6, 0xf8)
119
120/**
121 * fwu_read_mdata() - Wrapper around fwu_mdata_ops.read_mdata()
122 */
123int fwu_read_mdata(struct udevice *dev, struct fwu_mdata *mdata,
124 bool primary, uint32_t size);
125
126/**
127 * fwu_write_mdata() - Wrapper around fwu_mdata_ops.write_mdata()
128 */
129int fwu_write_mdata(struct udevice *dev, struct fwu_mdata *mdata,
130 bool primary, uint32_t size);
131
132/**
133 * fwu_get_mdata() - Read, verify and return the FWU metadata
134 *
135 * Read both the metadata copies from the storage media, verify their checksum,
136 * and ascertain that both copies match. If one of the copies has gone bad,
137 * restore it from the good copy.
138 *
139 * Return: 0 if OK, -ve on error
140 */
141int fwu_get_mdata(struct fwu_mdata *mdata);
142
143/**
144 * fwu_get_active_index() - Get active_index from the FWU metadata
145 * @active_idxp: active_index value to be read
146 *
147 * Read the active_index field from the FWU metadata and place it in
148 * the variable pointed to be the function argument.
149 *
150 * Return: 0 if OK, -ve on error
151 *
152 */
153int fwu_get_active_index(uint *active_idxp);
154
155/**
156 * fwu_set_active_index() - Set active_index in the FWU metadata
157 * @active_idx: active_index value to be set
158 *
159 * Update the active_index field in the FWU metadata
160 *
161 * Return: 0 if OK, -ve on error
162 *
163 */
164int fwu_set_active_index(uint active_idx);
165
166/**
167 * fwu_get_dfu_alt_num() - Get the dfu_alt_num to be used for capsule update
168 * @image_index: The Image Index for the image
169 * @alt_num: pointer to store dfu_alt_num
170 *
171 * Currently, the capsule update driver uses the DFU framework for
172 * the updates. This function gets the DFU alt number which is to
173 * be used for capsule update.
174 *
175 * Return: 0 if OK, -ve on error
176 *
177 */
178int fwu_get_dfu_alt_num(u8 image_index, u8 *alt_num);
179
180/**
181 * fwu_revert_boot_index() - Revert the active index in the FWU metadata
182 *
183 * Revert the active_index value in the FWU metadata, by swapping the values
184 * of active_index and previous_active_index in both copies of the
185 * FWU metadata.
186 *
187 * Return: 0 if OK, -ve on error
188 *
189 */
190int fwu_revert_boot_index(void);
191
192/**
193 * fwu_accept_image() - Set the Acceptance bit for the image
194 * @img_type_id: GUID of the image type for which the accepted bit is to be
195 * cleared
196 * @bank: Bank of which the image's Accept bit is to be set
197 *
198 * Set the accepted bit for the image specified by the img_guid parameter. This
199 * indicates acceptance of image for subsequent boots by some governing component
200 * like OS(or firmware).
201 *
202 * Return: 0 if OK, -ve on error
203 *
204 */
205int fwu_accept_image(efi_guid_t *img_type_id, u32 bank);
206
207/**
208 * fwu_clear_accept_image() - Clear the Acceptance bit for the image
209 * @img_type_id: GUID of the image type for which the accepted bit is to be
210 * cleared
211 * @bank: Bank of which the image's Accept bit is to be cleared
212 *
213 * Clear the accepted bit for the image type specified by the img_type_id parameter.
214 * This function is called after the image has been updated. The accepted bit is
215 * cleared to be set subsequently after passing the image acceptance criteria, by
216 * either the OS(or firmware)
217 *
218 * Return: 0 if OK, -ve on error
219 *
220 */
221int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank);
222
223/**
224 * fwu_plat_get_alt_num() - Get the DFU Alt Num for the image from the platform
225 * @dev: FWU device
226 * @image_guid: Image GUID for which DFU alt number needs to be retrieved
227 * @alt_num: Pointer to the alt_num
228 *
229 * Get the DFU alt number from the platform for the image specified by the
230 * image GUID.
231 *
232 * Return: 0 if OK, -ve on error
233 *
234 */
235int fwu_plat_get_alt_num(struct udevice *dev, efi_guid_t *image_guid,
236 u8 *alt_num);
237
238/**
239 * fwu_plat_get_update_index() - Get the value of the update bank
240 * @update_idx: Bank number to which images are to be updated
241 *
242 * Get the value of the bank(partition) to which the update needs to be
243 * made.
244 *
245 * Note: This is a weak function and platforms can override this with
246 * their own implementation for selection of the update bank.
247 *
248 * Return: 0 if OK, -ve on error
249 *
250 */
251int fwu_plat_get_update_index(uint *update_idx);
252
253/**
254 * fwu_plat_get_bootidx() - Get the value of the boot index
255 * @boot_idx: Boot index value
256 *
257 * Get the value of the bank(partition) from which the platform
258 * has booted. This value is passed to U-Boot from the earlier
259 * stage bootloader which loads and boots all the relevant
260 * firmware images
261 *
262 */
263void fwu_plat_get_bootidx(uint *boot_idx);
264
265/**
266 * fwu_update_checks_pass() - Check if FWU update can be done
267 *
268 * Check if the FWU update can be executed. The updates are
269 * allowed only when the platform is not in Trial State and
270 * the boot time checks have passed
271 *
272 * Return: 1 if OK, 0 if checks do not pass
273 *
274 */
275u8 fwu_update_checks_pass(void);
276
277/**
278 * fwu_empty_capsule_checks_pass() - Check if empty capsule can be processed
279 *
280 * Check if the empty capsule can be processed to either accept or revert
281 * an earlier executed update. The empty capsules need to be processed
282 * only when the platform is in Trial State and the boot time checks have
283 * passed
284 *
285 * Return: 1 if OK, 0 if not to be allowed
286 *
287 */
288u8 fwu_empty_capsule_checks_pass(void);
289
290/**
291 * fwu_trial_state_ctr_start() - Start the Trial State counter
292 *
293 * Start the counter to identify the platform booting in the
294 * Trial State. The counter is implemented as an EFI variable.
295 *
296 * Return: 0 if OK, -ve on error
297 *
298 */
299int fwu_trial_state_ctr_start(void);
300
301/**
302 * fwu_gen_alt_info_from_mtd() - Parse dfu_alt_info from metadata in mtd
303 * @buf: Buffer into which the dfu_alt_info is filled
304 * @len: Maximum characters that can be written in buf
305 * @mtd: Pointer to underlying MTD device
306 *
307 * Parse dfu_alt_info from metadata in mtd. Used for setting the env.
308 *
309 * Return: 0 if OK, -ve on error
310 */
311int fwu_gen_alt_info_from_mtd(char *buf, size_t len, struct mtd_info *mtd);
312
313/**
314 * fwu_mtd_get_alt_num() - Mapping of fwu_plat_get_alt_num for MTD device
315 * @image_guid: Image GUID for which DFU alt number needs to be retrieved
316 * @alt_num: Pointer to the alt_num
317 * @mtd_dev: Name of mtd device instance
318 *
319 * To map fwu_plat_get_alt_num onto mtd based metadata implementation.
320 *
321 * Return: 0 if OK, -ve on error
322 */
323int fwu_mtd_get_alt_num(efi_guid_t *image_guid, u8 *alt_num, const char *mtd_dev);
324
325/**
326 * fwu_mdata_copies_allocate() - Allocate memory for metadata
327 * @mdata_size: Size of the metadata structure
328 *
329 * Allocate memory for storing both the copies of the FWU metadata. The
330 * copies are then used as a cache for storing FWU metadata contents.
331 *
332 * Return: 0 if OK, -ve on error
333 */
334int fwu_mdata_copies_allocate(u32 mdata_size);
335
336/**
337 * fwu_get_dev() - Return the FWU metadata device
338 *
339 * Return the pointer to the FWU metadata device.
340 *
341 * Return: Pointer to the FWU metadata dev
342 */
343struct udevice *fwu_get_dev(void);
344
345/**
346 * fwu_get_data() - Return the version agnostic FWU structure
347 *
348 * Return the pointer to the version agnostic FWU structure.
349 *
350 * Return: Pointer to the FWU data structure
351 */
352struct fwu_data *fwu_get_data(void);
353
354/**
355 * fwu_sync_mdata() - Update given meta-data partition(s) with the copy provided
356 * @data: FWU Data structure
357 * @part: Bitmask of FWU metadata partitions to be written to
358 *
359 * Return: 0 if OK, -ve on error
360 */
361int fwu_sync_mdata(struct fwu_mdata *mdata, int part);
362
363/**
364 * fwu_populate_mdata_image_info() - Populate the image information
365 * of the metadata
366 * @data: Version agnostic FWU metadata information
367 *
368 * Populate the image information in the FWU metadata by copying it
369 * from the version agnostic structure. This is done before the
370 * metadata gets written to the storage media.
371 *
372 * Return: None
373 */
374void fwu_populate_mdata_image_info(struct fwu_data *data);
375
376/**
377 * fwu_get_mdata_size() - Get the FWU metadata size
378 * @mdata_size: Size of the metadata structure
379 *
380 * Get the size of the FWU metadata from the structure. This is later used
381 * to allocate memory for the structure.
382 *
383 * Return: 0 if OK, -ve on error
384 */
385int fwu_get_mdata_size(uint32_t *mdata_size);
386
387/**
388 * fwu_state_machine_updates() - Update FWU state of the platform
389 * @trial_state: Is platform transitioning into Trial State
390 * @update_index: Bank number to which images have been updated
391 *
392 * On successful completion of updates, transition the platform to
393 * either Trial State or Regular State.
394 *
395 * To transition the platform to Trial State, start the
396 * TrialStateCtr counter, followed by setting the value of bank_state
397 * field of the metadata to Valid state(applicable only in version 2
398 * of metadata).
399 *
400 * In case, the platform is to transition directly to Regular State,
401 * update the bank_state field of the metadata to Accepted
402 * state(applicable only in version 2 of metadata).
403 *
404 * Return: 0 if OK, -ve on error
405 */
406int fwu_state_machine_updates(bool trial_state, uint32_t update_index);
407
408/**
409 * fwu_init() - FWU specific initialisations
410 *
411 * Carry out some FWU specific initialisations including allocation
412 * of memory for the metadata copies, and reading the FWU metadata
413 * copies into the allocated memory. The metadata fields are then
414 * copied into a version agnostic structure.
415 *
416 * Return: 0 if OK, -ve on error
417 */
418int fwu_init(void);
419
420/**
421 * fwu_bank_accepted() - Has the bank been accepted
422 * @data: Version agnostic FWU metadata information
423 * @bank: Update bank to check
424 *
425 * Check in the given bank if all the images have been accepted.
426 *
427 * Return: true if all images accepted, false otherwise
428 */
429bool fwu_bank_accepted(struct fwu_data *data, uint32_t bank);
430
431#endif /* _FWU_H_ */