]> git.proxmox.com Git - mirror_edk2.git/blame - FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c
projects / mirror_edk2.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
FmpDevicePkg/FmpDeviceLib: Add Last Attempt Status to Check/Set API
[mirror_edk2.git] / FmpDevicePkg / Library / FmpDeviceLibNull / FmpDeviceLib.c
CommitLineData
a6d73269 1/** @file\r
403d4bcd
KM		 2 Provides firmware device specific services to support updates of a firmware\r
3 image stored in a firmware device.\r
4\r
6ad819c1 5 Copyright (c) Microsoft Corporation.<BR>\r
1f06aa24 6 Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
403d4bcd 7\r
bcef758c 8 SPDX-License-Identifier: BSD-2-Clause-Patent\r
403d4bcd
KM		 9\r
10**/\r
11\r
12#include <PiDxe.h>\r
6ad819c1 13#include <Guid/SystemResourceTable.h>\r
403d4bcd
KM		 14#include <Library/FmpDeviceLib.h>\r
15\r
16/**\r
17 Provide a function to install the Firmware Management Protocol instance onto a\r
18 device handle when the device is managed by a driver that follows the UEFI\r
19 Driver Model. If the device is not managed by a driver that follows the UEFI\r
20 Driver Model, then EFI_UNSUPPORTED is returned.\r
21\r
22 @param[in] FmpInstaller Function that installs the Firmware Management\r
23 Protocol.\r
24\r
25 @retval EFI_SUCCESS The device is managed by a driver that follows the\r
26 UEFI Driver Model. FmpInstaller must be called on\r
27 each Driver Binding Start().\r
28 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
29 the UEFI Driver Model.\r
30 @retval other The Firmware Management Protocol for this firmware\r
31 device is not installed. The firmware device is\r
32 still locked using FmpDeviceLock().\r
33\r
34**/\r
35EFI_STATUS\r
36EFIAPI\r
37RegisterFmpInstaller (\r
38 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Function\r
39 )\r
40{\r
41 return EFI_UNSUPPORTED;\r
42}\r
43\r
1f06aa24
EJ		 44/**\r
45 Provide a function to uninstall the Firmware Management Protocol instance from a\r
46 device handle when the device is managed by a driver that follows the UEFI\r
47 Driver Model. If the device is not managed by a driver that follows the UEFI\r
48 Driver Model, then EFI_UNSUPPORTED is returned.\r
49\r
50 @param[in] FmpUninstaller Function that installs the Firmware Management\r
51 Protocol.\r
52\r
53 @retval EFI_SUCCESS The device is managed by a driver that follows the\r
95d28836 54 UEFI Driver Model. FmpUninstaller must be called on\r
1f06aa24
EJ		 55 each Driver Binding Stop().\r
56 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
57 the UEFI Driver Model.\r
58 @retval other The Firmware Management Protocol for this firmware\r
59 device is not installed. The firmware device is\r
60 still locked using FmpDeviceLock().\r
61\r
62**/\r
63EFI_STATUS\r
64EFIAPI\r
65RegisterFmpUninstaller (\r
66 IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER Function\r
67 )\r
68{\r
69 return EFI_UNSUPPORTED;\r
70}\r
71\r
72/**\r
73 Set the device context for the FmpDeviceLib services when the device is\r
74 managed by a driver that follows the UEFI Driver Model. If the device is not\r
75 managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED\r
76 is returned. Once a device context is set, the FmpDeviceLib services\r
77 operate on the currently set device context.\r
78\r
79 @param[in] Handle Device handle for the FmpDeviceLib services.\r
80 If Handle is NULL, then Context is freed.\r
81 @param[in, out] Context Device context for the FmpDeviceLib services.\r
82 If Context is NULL, then a new context is allocated\r
83 for Handle and the current device context is set and\r
84 returned in Context. If Context is not NULL, then\r
85 the current device context is set.\r
86\r
87 @retval EFI_SUCCESS The device is managed by a driver that follows the\r
88 UEFI Driver Model.\r
89 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
90 the UEFI Driver Model.\r
91 @retval other The Firmware Management Protocol for this firmware\r
92 device is not installed. The firmware device is\r
93 still locked using FmpDeviceLock().\r
94\r
95**/\r
96EFI_STATUS\r
97EFIAPI\r
98FmpDeviceSetContext (\r
99 IN EFI_HANDLE Handle,\r
100 IN OUT VOID **Context\r
101 )\r
102{\r
103 return EFI_UNSUPPORTED;\r
104}\r
105\r
403d4bcd
KM		 106/**\r
107 Returns the size, in bytes, of the firmware image currently stored in the\r
108 firmware device. This function is used to by the GetImage() and\r
109 GetImageInfo() services of the Firmware Management Protocol. If the image\r
110 size can not be determined from the firmware device, then 0 must be returned.\r
111\r
112 @param[out] Size Pointer to the size, in bytes, of the firmware image\r
113 currently stored in the firmware device.\r
114\r
115 @retval EFI_SUCCESS The size of the firmware image currently\r
116 stored in the firmware device was returned.\r
117 @retval EFI_INVALID_PARAMETER Size is NULL.\r
118 @retval EFI_UNSUPPORTED The firmware device does not support reporting\r
119 the size of the currently stored firmware image.\r
120 @retval EFI_DEVICE_ERROR An error occurred attempting to determine the\r
121 size of the firmware image currently stored in\r
122 in the firmware device.\r
123\r
124**/\r
125EFI_STATUS\r
126EFIAPI\r
127FmpDeviceGetSize (\r
a6d73269 128 OUT UINTN *Size\r
403d4bcd
KM		 129 )\r
130{\r
131 if (Size == NULL) {\r
132 return EFI_INVALID_PARAMETER;\r
133 }\r
134 *Size = 0;\r
135 return EFI_SUCCESS;\r
136}\r
137\r
138/**\r
139 Returns the GUID value used to fill in the ImageTypeId field of the\r
140 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
141 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,\r
142 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is\r
143 returned, then ImageTypeId is set to the Guid returned from this function.\r
144\r
145 @param[out] Guid Double pointer to a GUID value that is updated to point to\r
146 to a GUID value. The GUID value is not allocated and must\r
147 not be modified or freed by the caller.\r
148\r
149 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
150 to the returned Guid value.\r
151 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
152 to gEfiCallerIdGuid.\r
153\r
154**/\r
155EFI_STATUS\r
156EFIAPI\r
157FmpDeviceGetImageTypeIdGuidPtr (\r
158 OUT EFI_GUID **Guid\r
159 )\r
160{\r
161 return EFI_UNSUPPORTED;\r
162}\r
163\r
164/**\r
165 Returns values used to fill in the AttributesSupported and AttributesSettings\r
166 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the\r
167 GetImageInfo() service of the Firmware Management Protocol. The following\r
168 bit values from the Firmware Management Protocol may be combined:\r
169 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE\r
170 IMAGE_ATTRIBUTE_RESET_REQUIRED\r
171 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED\r
172 IMAGE_ATTRIBUTE_IN_USE\r
173 IMAGE_ATTRIBUTE_UEFI_IMAGE\r
174\r
175 @param[out] Supported Attributes supported by this firmware device.\r
176 @param[out] Setting Attributes settings for this firmware device.\r
177\r
178 @retval EFI_SUCCESS The attributes supported by the firmware\r
179 device were returned.\r
180 @retval EFI_INVALID_PARAMETER Supported is NULL.\r
181 @retval EFI_INVALID_PARAMETER Setting is NULL.\r
182\r
183**/\r
184EFI_STATUS\r
185EFIAPI\r
186FmpDeviceGetAttributes (\r
a6d73269
SZ		 187 OUT UINT64 *Supported,\r
188 OUT UINT64 *Setting\r
403d4bcd
KM		 189 )\r
190{\r
191 if (Supported == NULL || Setting == NULL) {\r
192 return EFI_INVALID_PARAMETER;\r
193 }\r
194 *Supported = 0;\r
195 *Setting = 0;\r
196 return EFI_SUCCESS;\r
197}\r
198\r
199/**\r
200 Returns the value used to fill in the LowestSupportedVersion field of the\r
201 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
202 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
203 the firmware device supports a method to report the LowestSupportedVersion\r
204 value from the currently stored firmware image. If the value can not be\r
205 reported for the firmware image currently stored in the firmware device, then\r
206 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error\r
207 occurs attempting to retrieve the LowestSupportedVersion value for the\r
208 currently stored firmware image.\r
209\r
210 @note It is recommended that all firmware devices support a method to report\r
211 the LowestSupportedVersion value from the currently stored firmware\r
212 image.\r
213\r
214 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved\r
215 from the currently stored firmware image.\r
216\r
217 @retval EFI_SUCCESS The lowest supported version of currently stored\r
218 firmware image was returned in LowestSupportedVersion.\r
219 @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
220 report the lowest supported version of the currently\r
221 stored firmware image.\r
222 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest\r
223 supported version of the currently stored firmware\r
224 image.\r
225\r
226**/\r
227EFI_STATUS\r
228EFIAPI\r
229FmpDeviceGetLowestSupportedVersion (\r
230 OUT UINT32 *LowestSupportedVersion\r
231 )\r
232{\r
233 return EFI_UNSUPPORTED;\r
234}\r
235\r
236/**\r
237 Returns the Null-terminated Unicode string that is used to fill in the\r
238 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is\r
239 returned by the GetImageInfo() service of the Firmware Management Protocol.\r
240 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().\r
241\r
242 @note It is recommended that all firmware devices support a method to report\r
243 the VersionName string from the currently stored firmware image.\r
244\r
245 @param[out] VersionString The version string retrieved from the currently\r
246 stored firmware image.\r
247\r
248 @retval EFI_SUCCESS The version string of currently stored\r
249 firmware image was returned in Version.\r
250 @retval EFI_INVALID_PARAMETER VersionString is NULL.\r
251 @retval EFI_UNSUPPORTED The firmware device does not support a method\r
252 to report the version string of the currently\r
253 stored firmware image.\r
254 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
255 version string of the currently stored\r
256 firmware image.\r
257 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the\r
258 buffer for the version string of the currently\r
259 stored firmware image.\r
260\r
261**/\r
262EFI_STATUS\r
263EFIAPI\r
264FmpDeviceGetVersionString (\r
265 OUT CHAR16 **VersionString\r
266 )\r
267{\r
268 if (VersionString == NULL) {\r
269 return EFI_INVALID_PARAMETER;\r
270 }\r
271 *VersionString = NULL;\r
272 return EFI_UNSUPPORTED;\r
273}\r
274\r
275/**\r
276 Returns the value used to fill in the Version field of the\r
277 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
278 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
279 the firmware device supports a method to report the Version value from the\r
280 currently stored firmware image. If the value can not be reported for the\r
281 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED\r
282 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting\r
283 to retrieve the LowestSupportedVersion value for the currently stored firmware\r
284 image.\r
285\r
286 @note It is recommended that all firmware devices support a method to report\r
287 the Version value from the currently stored firmware image.\r
288\r
289 @param[out] Version The version value retrieved from the currently stored\r
290 firmware image.\r
291\r
292 @retval EFI_SUCCESS The version of currently stored firmware image was\r
293 returned in Version.\r
294 @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
295 report the version of the currently stored firmware\r
296 image.\r
297 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version\r
298 of the currently stored firmware image.\r
299\r
300**/\r
301EFI_STATUS\r
302EFIAPI\r
303FmpDeviceGetVersion (\r
304 OUT UINT32 *Version\r
305 )\r
306{\r
307 return EFI_UNSUPPORTED;\r
308}\r
309\r
1f06aa24
EJ		 310/**\r
311 Returns the value used to fill in the HardwareInstance field of the\r
312 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
313 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
314 the firmware device supports a method to report the HardwareInstance value.\r
315 If the value can not be reported for the firmware device, then EFI_UNSUPPORTED\r
316 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting\r
317 to retrieve the HardwareInstance value for the firmware device.\r
318\r
319 @param[out] HardwareInstance The hardware instance value for the firmware\r
320 device.\r
321\r
322 @retval EFI_SUCCESS The hardware instance for the current firmware\r
95d28836 323 device is returned in HardwareInstance.\r
1f06aa24
EJ		 324 @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
325 report the hardware instance value.\r
326 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware\r
327 instance value.\r
328\r
329**/\r
330EFI_STATUS\r
331EFIAPI\r
332FmpDeviceGetHardwareInstance (\r
333 OUT UINT64 *HardwareInstance\r
334 )\r
335{\r
336 return EFI_UNSUPPORTED;\r
337}\r
338\r
403d4bcd
KM		 339/**\r
340 Returns a copy of the firmware image currently stored in the firmware device.\r
341\r
342 @note It is recommended that all firmware devices support a method to retrieve\r
343 a copy currently stored firmware image. This can be used to support\r
344 features such as recovery and rollback.\r
345\r
a6d73269 346 @param[out] Image Pointer to a caller allocated buffer where the\r
403d4bcd 347 currently stored firmware image is copied to.\r
a6d73269 348 @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.\r
403d4bcd
KM		 349 On return, points to the size, in bytes, of firmware\r
350 image currently stored in the firmware device.\r
351\r
352 @retval EFI_SUCCESS Image contains a copy of the firmware image\r
353 currently stored in the firmware device, and\r
354 ImageSize contains the size, in bytes, of the\r
355 firmware image currently stored in the\r
356 firmware device.\r
357 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small\r
358 to hold the firmware image currently stored in\r
359 the firmware device. The buffer size required\r
360 is returned in ImageSize.\r
361 @retval EFI_INVALID_PARAMETER The Image is NULL.\r
362 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.\r
363 @retval EFI_UNSUPPORTED The operation is not supported.\r
364 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
365 firmware image currently stored in the firmware\r
366 device.\r
367\r
368**/\r
369EFI_STATUS\r
370EFIAPI\r
371FmpDeviceGetImage (\r
a6d73269
SZ		 372 OUT VOID *Image,\r
373 IN OUT UINTN *ImageSize\r
403d4bcd
KM		 374 )\r
375{\r
376 return EFI_UNSUPPORTED;\r
377}\r
378\r
379/**\r
380 Checks if a new firmware image is valid for the firmware device. This\r
381 function allows firmware update operation to validate the firmware image\r
382 before FmpDeviceSetImage() is called.\r
383\r
384 @param[in] Image Points to a new firmware image.\r
385 @param[in] ImageSize Size, in bytes, of a new firmware image.\r
386 @param[out] ImageUpdatable Indicates if a new firmware image is valid for\r
387 a firmware update to the firmware device. The\r
388 following values from the Firmware Management\r
389 Protocol are supported:\r
390 IMAGE_UPDATABLE_VALID\r
391 IMAGE_UPDATABLE_INVALID\r
392 IMAGE_UPDATABLE_INVALID_TYPE\r
393 IMAGE_UPDATABLE_INVALID_OLD\r
394 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
395\r
396 @retval EFI_SUCCESS The image was successfully checked. Additional\r
397 status information is returned in\r
a6d73269 398 ImageUpdatable.\r
403d4bcd 399 @retval EFI_INVALID_PARAMETER Image is NULL.\r
a6d73269 400 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.\r
403d4bcd
KM		 401\r
402**/\r
403EFI_STATUS\r
404EFIAPI\r
405FmpDeviceCheckImage (\r
406 IN CONST VOID *Image,\r
407 IN UINTN ImageSize,\r
a6d73269 408 OUT UINT32 *ImageUpdatable\r
403d4bcd
KM		 409 )\r
410{\r
6ad819c1
MK		 411 UINT32 LastAttemptStatus;\r
412\r
413 return FmpDeviceCheckImageWithStatus (Image, ImageSize, ImageUpdatable, &LastAttemptStatus);\r
414}\r
415\r
416/**\r
417 Checks if a new firmware image is valid for the firmware device. This\r
418 function allows firmware update operation to validate the firmware image\r
419 before FmpDeviceSetImage() is called.\r
420\r
421 @param[in] Image Points to a new firmware image.\r
422 @param[in] ImageSize Size, in bytes, of a new firmware image.\r
423 @param[out] ImageUpdatable Indicates if a new firmware image is valid for\r
424 a firmware update to the firmware device. The\r
425 following values from the Firmware Management\r
426 Protocol are supported:\r
427 IMAGE_UPDATABLE_VALID\r
428 IMAGE_UPDATABLE_INVALID\r
429 IMAGE_UPDATABLE_INVALID_TYPE\r
430 IMAGE_UPDATABLE_INVALID_OLD\r
431 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
432 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
433 status to report back to the ESRT table in case\r
434 of error. This value will only be checked when this\r
435 function returns an error.\r
436\r
437 The return status code must fall in the range of\r
438 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
439 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
440\r
441 If the value falls outside this range, it will be converted\r
442 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
443\r
444 @retval EFI_SUCCESS The image was successfully checked. Additional\r
445 status information is returned in\r
446 ImageUpdatable.\r
447 @retval EFI_INVALID_PARAMETER Image is NULL.\r
448 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.\r
449\r
450**/\r
451EFI_STATUS\r
452EFIAPI\r
453FmpDeviceCheckImageWithStatus (\r
454 IN CONST VOID *Image,\r
455 IN UINTN ImageSize,\r
456 OUT UINT32 *ImageUpdatable,\r
457 OUT UINT32 *LastAttemptStatus\r
458 )\r
459{\r
460 *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;\r
461\r
403d4bcd
KM		 462 return EFI_SUCCESS;\r
463}\r
464\r
465/**\r
466 Updates a firmware device with a new firmware image. This function returns\r
467 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
468 is updatable, the function should perform the following minimal validations\r
469 before proceeding to do the firmware image update.\r
470 - Validate that the image is a supported image for this firmware device.\r
471 Return EFI_ABORTED if the image is not supported. Additional details\r
472 on why the image is not a supported image may be returned in AbortReason.\r
473 - Validate the data from VendorCode if is not NULL. Firmware image\r
474 validation must be performed before VendorCode data validation.\r
475 VendorCode data is ignored or considered invalid if image validation\r
476 fails. Return EFI_ABORTED if the VendorCode data is invalid.\r
477\r
478 VendorCode enables vendor to implement vendor-specific firmware image update\r
479 policy. Null if the caller did not specify the policy or use the default\r
480 policy. As an example, vendor can implement a policy to allow an option to\r
481 force a firmware image update when the abort reason is due to the new firmware\r
482 image version is older than the current firmware image version or bad image\r
483 checksum. Sensitive operations such as those wiping the entire firmware image\r
484 and render the device to be non-functional should be encoded in the image\r
485 itself rather than passed with the VendorCode. AbortReason enables vendor to\r
486 have the option to provide a more detailed description of the abort reason to\r
487 the caller.\r
488\r
489 @param[in] Image Points to the new firmware image.\r
490 @param[in] ImageSize Size, in bytes, of the new firmware image.\r
491 @param[in] VendorCode This enables vendor to implement vendor-specific\r
492 firmware image update policy. NULL indicates\r
493 the caller did not specify the policy or use the\r
494 default policy.\r
495 @param[in] Progress A function used to report the progress of\r
496 updating the firmware device with the new\r
497 firmware image.\r
498 @param[in] CapsuleFwVersion The version of the new firmware image from the\r
499 update capsule that provided the new firmware\r
500 image.\r
501 @param[out] AbortReason A pointer to a pointer to a Null-terminated\r
502 Unicode string providing more details on an\r
503 aborted operation. The buffer is allocated by\r
504 this function with\r
505 EFI_BOOT_SERVICES.AllocatePool(). It is the\r
506 caller's responsibility to free this buffer with\r
507 EFI_BOOT_SERVICES.FreePool().\r
508\r
509 @retval EFI_SUCCESS The firmware device was successfully updated\r
510 with the new firmware image.\r
511 @retval EFI_ABORTED The operation is aborted. Additional details\r
512 are provided in AbortReason.\r
513 @retval EFI_INVALID_PARAMETER The Image was NULL.\r
514 @retval EFI_UNSUPPORTED The operation is not supported.\r
515\r
516**/\r
517EFI_STATUS\r
518EFIAPI\r
519FmpDeviceSetImage (\r
520 IN CONST VOID *Image,\r
521 IN UINTN ImageSize,\r
522 IN CONST VOID *VendorCode, OPTIONAL\r
523 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL\r
524 IN UINT32 CapsuleFwVersion,\r
525 OUT CHAR16 **AbortReason\r
526 )\r
527{\r
6ad819c1
MK		 528 UINT32 LastAttemptStatus;\r
529\r
530 return FmpDeviceSetImageWithStatus (\r
531 Image,\r
532 ImageSize,\r
533 VendorCode,\r
534 Progress,\r
535 CapsuleFwVersion,\r
536 AbortReason,\r
537 &LastAttemptStatus\r
538 );\r
539}\r
540\r
541/**\r
542 Updates a firmware device with a new firmware image. This function returns\r
543 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
544 is updatable, the function should perform the following minimal validations\r
545 before proceeding to do the firmware image update.\r
546 - Validate that the image is a supported image for this firmware device.\r
547 Return EFI_ABORTED if the image is not supported. Additional details\r
548 on why the image is not a supported image may be returned in AbortReason.\r
549 - Validate the data from VendorCode if is not NULL. Firmware image\r
550 validation must be performed before VendorCode data validation.\r
551 VendorCode data is ignored or considered invalid if image validation\r
552 fails. Return EFI_ABORTED if the VendorCode data is invalid.\r
553\r
554 VendorCode enables vendor to implement vendor-specific firmware image update\r
555 policy. Null if the caller did not specify the policy or use the default\r
556 policy. As an example, vendor can implement a policy to allow an option to\r
557 force a firmware image update when the abort reason is due to the new firmware\r
558 image version is older than the current firmware image version or bad image\r
559 checksum. Sensitive operations such as those wiping the entire firmware image\r
560 and render the device to be non-functional should be encoded in the image\r
561 itself rather than passed with the VendorCode. AbortReason enables vendor to\r
562 have the option to provide a more detailed description of the abort reason to\r
563 the caller.\r
564\r
565 @param[in] Image Points to the new firmware image.\r
566 @param[in] ImageSize Size, in bytes, of the new firmware image.\r
567 @param[in] VendorCode This enables vendor to implement vendor-specific\r
568 firmware image update policy. NULL indicates\r
569 the caller did not specify the policy or use the\r
570 default policy.\r
571 @param[in] Progress A function used to report the progress of\r
572 updating the firmware device with the new\r
573 firmware image.\r
574 @param[in] CapsuleFwVersion The version of the new firmware image from the\r
575 update capsule that provided the new firmware\r
576 image.\r
577 @param[out] AbortReason A pointer to a pointer to a Null-terminated\r
578 Unicode string providing more details on an\r
579 aborted operation. The buffer is allocated by\r
580 this function with\r
581 EFI_BOOT_SERVICES.AllocatePool(). It is the\r
582 caller's responsibility to free this buffer with\r
583 EFI_BOOT_SERVICES.FreePool().\r
584 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
585 status to report back to the ESRT table in case\r
586 of error. This value will only be checked when this\r
587 function returns an error.\r
588\r
589 The return status code must fall in the range of\r
590 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
591 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
592\r
593 If the value falls outside this range, it will be converted\r
594 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
595\r
596 @retval EFI_SUCCESS The firmware device was successfully updated\r
597 with the new firmware image.\r
598 @retval EFI_ABORTED The operation is aborted. Additional details\r
599 are provided in AbortReason.\r
600 @retval EFI_INVALID_PARAMETER The Image was NULL.\r
601 @retval EFI_UNSUPPORTED The operation is not supported.\r
602\r
603**/\r
604EFI_STATUS\r
605EFIAPI\r
606FmpDeviceSetImageWithStatus (\r
607 IN CONST VOID *Image,\r
608 IN UINTN ImageSize,\r
609 IN CONST VOID *VendorCode, OPTIONAL\r
610 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL\r
611 IN UINT32 CapsuleFwVersion,\r
612 OUT CHAR16 **AbortReason,\r
613 OUT UINT32 *LastAttemptStatus\r
614 )\r
615{\r
616 *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;\r
617\r
403d4bcd
KM		 618 return EFI_UNSUPPORTED;\r
619}\r
620\r
621/**\r
622 Lock the firmware device that contains a firmware image. Once a firmware\r
623 device is locked, any attempts to modify the firmware image contents in the\r
624 firmware device must fail.\r
625\r
626 @note It is recommended that all firmware devices support a lock method to\r
627 prevent modifications to a stored firmware image.\r
628\r
629 @note A firmware device lock mechanism is typically only cleared by a full\r
630 system reset (not just sleep state/low power mode).\r
631\r
632 @retval EFI_SUCCESS The firmware device was locked.\r
633 @retval EFI_UNSUPPORTED The firmware device does not support locking\r
634\r
635**/\r
636EFI_STATUS\r
637EFIAPI\r
638FmpDeviceLock (\r
639 VOID\r
640 )\r
641{\r
642 return EFI_UNSUPPORTED;\r
643}\r
EFI Development Kit II mirror for PVE