blob: eb5638f4f3a05dfd2af4f375e9ada0651e56a790 [file] [log] [blame]
Sughosh Ganu2eaedc92022-10-21 18:15:55 +05301/* 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>
Masami Hiramatsu48986792023-05-31 00:29:14 -050011#include <mtd.h>
12#include <uuid.h>
Sughosh Ganu2eaedc92022-10-21 18:15:55 +053013
14#include <linux/types.h>
15
16struct fwu_mdata;
17struct udevice;
18
Sughosh Ganu554b38f2022-10-21 18:15:56 +053019struct fwu_mdata_gpt_blk_priv {
20 struct udevice *blk_dev;
21};
22
Masami Hiramatsu48986792023-05-31 00:29:14 -050023struct fwu_mtd_image_info {
24 u32 start, size;
25 int bank_num, image_num;
26 char uuidbuf[UUID_STR_LEN + 1];
27};
28
Sughosh Ganu2eaedc92022-10-21 18:15:55 +053029struct fwu_mdata_ops {
30 /**
Jassi Brar167994f2023-03-06 17:18:28 -060031 * 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);
Sughosh Ganu2eaedc92022-10-21 18:15:55 +053049};
50
51#define FWU_MDATA_VERSION 0x1
Sughosh Ganu86794052022-10-21 18:16:03 +053052#define FWU_IMAGE_ACCEPTED 0x1
Sughosh Ganu2eaedc92022-10-21 18:15:55 +053053
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
Sughosh Ganu86794052022-10-21 18:16:03 +053062/*
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
Sughosh Ganu2eaedc92022-10-21 18:15:55 +053080/**
Jassi Brar167994f2023-03-06 17:18:28 -060081 * 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/**
Jassi Brar1e917a62023-03-06 17:18:48 -060091 * fwu_get_mdata() - Read, verify and return the FWU metadata
Jassi Brar167994f2023-03-06 17:18:28 -060092 *
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 */
Jassi Brar1e917a62023-03-06 17:18:48 -060099int fwu_get_mdata(struct fwu_mdata *mdata);
Jassi Brar167994f2023-03-06 17:18:28 -0600100
101/**
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530102 * 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/**
Masahisa Kojimaaf7a34a2024-01-11 14:35:39 +0900125 * 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
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530128 *
129 * Currently, the capsule update driver uses the DFU framework for
130 * the updates. This function gets the DFU alt number which is to
Masahisa Kojimaaf7a34a2024-01-11 14:35:39 +0900131 * be used for capsule update.
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530132 *
133 * Return: 0 if OK, -ve on error
134 *
135 */
Masahisa Kojimaaf7a34a2024-01-11 14:35:39 +0900136int fwu_get_dfu_alt_num(u8 image_index, u8 *alt_num);
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530137
138/**
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530139 * 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/**
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530151 * 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
Sughosh Ganu7d6e2c52022-10-21 18:15:59 +0530181/**
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);
Sughosh Ganu95b5a7d2022-10-21 18:16:00 +0530210
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);
Sughosh Ganu7e9814c2022-10-21 18:16:02 +0530222
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
Sughosh Ganu86794052022-10-21 18:16:03 +0530248/**
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
Masami Hiramatsu48986792023-05-31 00:29:14 -0500259/**
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
Sughosh Ganu2eaedc92022-10-21 18:15:55 +0530283#endif /* _FWU_H_ */