blob: 6affb73c4fb910dda84fdc0e505b3e738615e4ba [file] [log] [blame]
Sughosh Ganu0f9399a2022-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>
11
12#include <linux/types.h>
13
14struct fwu_mdata;
15struct udevice;
16
Sughosh Ganuee062b52022-10-21 18:15:56 +053017struct fwu_mdata_gpt_blk_priv {
18 struct udevice *blk_dev;
19};
20
Sughosh Ganu0f9399a2022-10-21 18:15:55 +053021struct fwu_mdata_ops {
22 /**
Jassi Brar821e4622023-03-06 17:18:28 -060023 * 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 Ganu0f9399a2022-10-21 18:15:55 +053041};
42
43#define FWU_MDATA_VERSION 0x1
Sughosh Ganu1cadae22022-10-21 18:16:03 +053044#define FWU_IMAGE_ACCEPTED 0x1
Sughosh Ganu0f9399a2022-10-21 18:15:55 +053045
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 Ganu1cadae22022-10-21 18:16:03 +053054/*
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 Ganu0f9399a2022-10-21 18:15:55 +053072/**
Jassi Brar821e4622023-03-06 17:18:28 -060073 * fwu_read_mdata() - Wrapper around fwu_mdata_ops.read_mdata()
74 */
75int 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 */
80int fwu_write_mdata(struct udevice *dev, struct fwu_mdata *mdata, bool primary);
81
82/**
Jassi Brarf7522552023-03-06 17:18:48 -060083 * fwu_get_mdata() - Read, verify and return the FWU metadata
Jassi Brar821e4622023-03-06 17:18:28 -060084 *
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 Brarf7522552023-03-06 17:18:48 -060091int fwu_get_mdata(struct fwu_mdata *mdata);
Jassi Brar821e4622023-03-06 17:18:28 -060092
93/**
Sughosh Ganu0f9399a2022-10-21 18:15:55 +053094 * 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 */
103int 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 */
114int 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 */
131int fwu_get_image_index(u8 *image_index);
132
133/**
Sughosh Ganu0f9399a2022-10-21 18:15:55 +0530134 * 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 */
143int fwu_revert_boot_index(void);
144
145/**
Sughosh Ganu0f9399a2022-10-21 18:15:55 +0530146 * 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 */
158int 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 */
174int fwu_clear_accept_image(efi_guid_t *img_type_id, u32 bank);
175
Sughosh Ganu60475ca2022-10-21 18:15:59 +0530176/**
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 */
188int 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 */
204int fwu_plat_get_update_index(uint *update_idx);
Sughosh Ganu73abe8e2022-10-21 18:16:00 +0530205
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 */
216void fwu_plat_get_bootidx(uint *boot_idx);
Sughosh Ganu2a0592a2022-10-21 18:16:02 +0530217
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 */
228u8 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 */
241u8 fwu_empty_capsule_checks_pass(void);
242
Sughosh Ganu1cadae22022-10-21 18:16:03 +0530243/**
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 */
252int fwu_trial_state_ctr_start(void);
253
Sughosh Ganu0f9399a2022-10-21 18:15:55 +0530254#endif /* _FWU_H_ */