1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
|
/** @file
Copyright (c) 2024, Arm Limited. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent
@par Reference(s):
- Platform Security Firmware Update for the A-profile Specification 1.0
(https://developer.arm.com/documentation/den0118/latest)
//
@par Glossary:
- FW - Firmware
- FWU - Firmware Update
- FWS - Firmware Storage
- PSA - Platform Security update for the A-profile specification
- IF - Image File
**/
#ifndef FWS_PLATFORM_LIB_H_
#define FWS_PLATFORM_LIB_H_
#include <IndustryStandard/PsaMmFwUpdate.h>
#include <Protocol/BlockIo.h>
/** Ignore modification of image file.
*/
#define FWS_IF_F_IGNORE_DIRTY (1 << 0)
#pragma pack (1)
/**
* Firmware Storage Device Instance.
*/
typedef struct {
/// Firmware storage Instance.
EFI_BLOCK_IO_PROTOCOL *Instance;
// Opened Image File Count.
UINT64 ImageFileCount;
// Private Data.
VOID *Private;
} FWS_DEVICE_INSTANCE;
/** Image file instance describing image in firmware storage.
*/
typedef struct {
/// Image Type Guid.
EFI_GUID ImageTypeGuid;
/// Image File Name Guid saved in firmware storage.
EFI_GUID FileNameGuid;
/// Image File Size.
UINTN FileSize;
/// Maximum Image File Size.
UINTN MaxSize;
/// Image File Flags. See FWS_IF_F_*
UINTN Flags;
/// Related Device Instance
FWS_DEVICE_INSTANCE *FwsDevice;
/// File Private Data.
VOID *Private;
} FWS_IMAGE_FILE;
#pragma pack ()
/**
Open the firmware storage device instance.
@param [in] Instance Firmware storage instance.
@param [out] FwsDevice Opened firmware storage device.
@retval EFI_SUCCESS
@retval EFI_INVALID_PARAMETER
@retval EFI_OUT_OF_RESOURCES Out of Memory.
@retval Others Fail to open device internally.
**/
EFI_STATUS
EFIAPI
FwsOpenDevice (
IN EFI_BLOCK_IO_PROTOCOL *Instance,
OUT FWS_DEVICE_INSTANCE **FwsDevice
);
/**
Release the firmware storage device instance.
@param [out] FwsDevice Opened firmware storage device.
@retval EFI_SUCCESS
@retval EFI_INVALID_PARAMETER
@retval EFI_NOT_READY Some image files opened using this device.
**/
EFI_STATUS
EFIAPI
FwsReleaseDevice (
IN FWS_DEVICE_INSTANCE *FwsDevice
);
/**
Get Image Directory.
@param [in] FwsDevice Opened firmware storage device instance.
@param [out] ImageDirectory Pointer to Image directory.
@retval EFI_SUCCESS
**/
EFI_STATUS
EFIAPI
FwsGetImageDirectory (
IN FWS_DEVICE_INSTANCE *FwsDevice,
OUT PSA_MM_FWU_IMAGE_DIRECTORY **ImageDirectory
);
/**
Open the @ImageTypeGuid Image from storage.
@param [in] FwsDevice Opened firmware storage device instance.
@param [in] ImageTypeGuid
@param [in] OpType FwuOpStreamRead / FwuOpStreamWrite
@param [out] ImageFile Opened Image File Handle.
@retval EFI_SUCCESS
@retval EFI_INVALID_PARAMETER
@retval EFI_OUT_OF_RESOURCES Out of Memory.
@retval Others Fail to open internally.
**/
EFI_STATUS
EFIAPI
FwsOpen (
IN FWS_DEVICE_INSTANCE *FwsDevice,
IN CONST EFI_GUID *ImageTypeGuid,
IN FWU_OP_TYPE OpType,
OUT FWS_IMAGE_FILE **ImageFile
);
/**
Close the opened image via FwsOpen.
This function performs:
- If requires, apply changes on the image file to storage.
- If image file is changed, set the image as unaccepted.
@param [in] ImageFile Image File Handle.
@param [in] MaxAtomicTimeNs Max Time to execute without yielding to client.
0 means unbounded time.
@param [out] Progress Unit of work completed.
@param [out] TotalWork Unit of work must be completed.
@retval EFI_SUCCESS
@retval EFI_INVALID_PARAMETER
@retval Others
**/
EFI_STATUS
EFIAPI
FwsRelease (
IN FWS_IMAGE_FILE *ImageFile,
IN UINT32 MaxAtomicTimeNs,
OUT UINT32 *Progress,
OUT UINT32 *TotalWork
);
/**
Write data to a partition stored in the Instance.
@param[in] ImageFile Image File Handle.
@param[in] Buffer Data to be written to the partition.
@param[in/out] WriteSize Size to write / real write to the partition in bytes.
@param[in] Offset The offset, within the partition, to write to.
@retval EFI_SUCCESS The write operation was successful.
@retval EFI_INVALID_PARAMETER
@retval EFI_NOT_READY Storage is not ready.
@retval Other Fail to write the data to partition.
**/
EFI_STATUS
EFIAPI
FwsWrite (
IN FWS_IMAGE_FILE *ImageFile,
IN VOID *Buffer,
IN OUT UINTN *WriteSize,
IN UINTN Offset
);
/**
Erase whole data in a partition stored related to Image.
@param[in] ImageFile Image File Handle.
@retval EFI_SUCCESS Erase data success.
@retval EFI_INVALID_PARAMETER
@retval EFI_NOT_READY Storage is not ready.
@retval Others Fail to erase the data on partition.
**/
EFI_STATUS
EFIAPI
FwsErase (
IN FWS_IMAGE_FILE *ImageFile
);
/**
Read data from a partition stored in ImageFile.
@param[in] ImageFile A pointer to the read destination buffer.
@param[out] Buffer Read destination buffer.
@param[in,out] ReadSize Size to read / Real read size from partition in bytes.
@param[in] Offset The offset, within the partition to read from.
@retval EFI_SUCCESS The read operation was successful.
@retval EFI_INVALID_PARAMETER
@retval EFI_NOT_READY Storage is not ready.
@retval Others Fail to read from partition.
**/
EFI_STATUS
EFIAPI
FwsRead (
IN FWS_IMAGE_FILE *ImageFile,
IN OUT VOID *Buffer,
IN UINTN *ReadSize,
IN UINTN Offset
);
/**
Signal that an image has been accepted.
@param[in] FwsDevice Opened firmware storage device instance.
@param[in] ImgTypeGuid The image type to be accepted
@param[in] AcceptUpdateImage If true, Accept the image on the update banks.
other accept the image on the active banks.
@retval EFI_SUCCESS The image was accepted successfully.
@retval EFI_INVALID_PARAMETER
@retval EFI_NOT_READY Currently, incorrect boot state.
(boot index != active index).
@retval EFI_NOT_FOUND Couldn't find Image related to @ImgTypeGuid.
@retval Others Fail to write Metadata.
**/
EFI_STATUS
EFIAPI
FwsAcceptImage (
IN FWS_DEVICE_INSTANCE *FwsDevice,
IN CONST EFI_GUID *ImgTypeGuid,
IN BOOLEAN AcceptUpdateImage
);
/**
Start firmware image update process.
@param [in] FwsDevice Opened firmware storage device instance.
@param [in] VendorFlags Vendor related flags to control firmware update.
@retval EFI_SUCCESS firmware update process is started.
@retval EFI_NOT_READY Current is incorrect boot state.
Couldn't start firmware update.
@retval Other Errors
**/
EFI_STATUS
EFIAPI
FwsUpdateStart (
IN FWS_DEVICE_INSTANCE *FwsDevice,
IN UINT32 VendorFlags
);
/**
Finish firmware image update process.
@param [in] FwsDevice Opened firmware storage device instance.
@param [in] Abort If true, cancel the firmware update process for error
or client request to cancel update.
@retval EFI_SUCCESS Success to finish firmware update process.
@retval EFI_NOT_READY firmware update process isn't started.
@retval EFI_ABORTED Error on firmware update metadata.
**/
EFI_STATUS
EFIAPI
FwsUpdateEnd (
IN FWS_DEVICE_INSTANCE *FwsDevice,
IN BOOLEAN Abort
);
/**
Check if current is on Trial state.
This function only check the if current in Trial state based on active index.
In other word, for checking other state (normal state && incorrect boot),
caller need to get that information by calling other function or
checking image directory information.
@param [in] FwsDevice Opened firmware storage device instance.
@param [out] IsTrialState If true, It is in Trial State.
@retval EFI_SUCCESS Success to get Trial State.
@retval EFI_INVALID_PARAMETER Invalid Parameter.
**/
EFI_STATUS
EFIAPI
FwsCheckTrialState (
IN FWS_DEVICE_INSTANCE *FwsDevice,
OUT BOOLEAN *IsTrialState
);
/**
Check if booted with active index or not.
@param [in] FwsDevice Opened firmware storage device instance.
@param [out] IsCorrectBoot If true, It is in Correct Boot.
@retval EFI_SUCCESS Success to get Correct Boot.
@retval EFI_INVALID_PARAMETER Invalid Parameter.
**/
EFI_STATUS
EFIAPI
FwsCheckCorrectBoot (
IN FWS_DEVICE_INSTANCE *FwsDevice,
OUT BOOLEAN *IsCorrectBoot
);
/**
Roll back the image.
Based on the firmware update started or not,
This function choice proper backup image.
@param [in] FwsDevice Opened firmware storage device instance.
@retval EFI_SUCCESS
@retval EFI_INVALID_PARAMETER Invalid Parameter.
@retval EFI_DEVICE_ERROR Error on metadata.
@retval Others Fail to rollback the image.
**/
EFI_STATUS
EFIAPI
FwsRollBack (
IN FWS_DEVICE_INSTANCE *FwsDevice
);
#endif /* __FWS_PLATFORM_LIB_H */
|
