2 Provides firmware device specific services to support updates of a firmware
3 image stored in a firmware device.
5 Copyright (c) Microsoft Corporation.<BR>
6 Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #include <Guid/SystemResourceTable.h>
14 #include <Library/FmpDeviceLib.h>
17 Provide a function to install the Firmware Management Protocol instance onto a
18 device handle when the device is managed by a driver that follows the UEFI
19 Driver Model. If the device is not managed by a driver that follows the UEFI
20 Driver Model, then EFI_UNSUPPORTED is returned.
22 @param[in] FmpInstaller Function that installs the Firmware Management
25 @retval EFI_SUCCESS The device is managed by a driver that follows the
26 UEFI Driver Model. FmpInstaller must be called on
27 each Driver Binding Start().
28 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
29 the UEFI Driver Model.
30 @retval other The Firmware Management Protocol for this firmware
31 device is not installed. The firmware device is
32 still locked using FmpDeviceLock().
37 RegisterFmpInstaller (
38 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Function
41 return EFI_UNSUPPORTED
;
45 Provide a function to uninstall the Firmware Management Protocol instance from a
46 device handle when the device is managed by a driver that follows the UEFI
47 Driver Model. If the device is not managed by a driver that follows the UEFI
48 Driver Model, then EFI_UNSUPPORTED is returned.
50 @param[in] FmpUninstaller Function that installs the Firmware Management
53 @retval EFI_SUCCESS The device is managed by a driver that follows the
54 UEFI Driver Model. FmpUninstaller must be called on
55 each Driver Binding Stop().
56 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
57 the UEFI Driver Model.
58 @retval other The Firmware Management Protocol for this firmware
59 device is not installed. The firmware device is
60 still locked using FmpDeviceLock().
65 RegisterFmpUninstaller (
66 IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER Function
69 return EFI_UNSUPPORTED
;
73 Set the device context for the FmpDeviceLib services when the device is
74 managed by a driver that follows the UEFI Driver Model. If the device is not
75 managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
76 is returned. Once a device context is set, the FmpDeviceLib services
77 operate on the currently set device context.
79 @param[in] Handle Device handle for the FmpDeviceLib services.
80 If Handle is NULL, then Context is freed.
81 @param[in, out] Context Device context for the FmpDeviceLib services.
82 If Context is NULL, then a new context is allocated
83 for Handle and the current device context is set and
84 returned in Context. If Context is not NULL, then
85 the current device context is set.
87 @retval EFI_SUCCESS The device is managed by a driver that follows the
89 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
90 the UEFI Driver Model.
91 @retval other The Firmware Management Protocol for this firmware
92 device is not installed. The firmware device is
93 still locked using FmpDeviceLock().
100 IN OUT VOID
**Context
103 return EFI_UNSUPPORTED
;
107 Returns the size, in bytes, of the firmware image currently stored in the
108 firmware device. This function is used to by the GetImage() and
109 GetImageInfo() services of the Firmware Management Protocol. If the image
110 size can not be determined from the firmware device, then 0 must be returned.
112 @param[out] Size Pointer to the size, in bytes, of the firmware image
113 currently stored in the firmware device.
115 @retval EFI_SUCCESS The size of the firmware image currently
116 stored in the firmware device was returned.
117 @retval EFI_INVALID_PARAMETER Size is NULL.
118 @retval EFI_UNSUPPORTED The firmware device does not support reporting
119 the size of the currently stored firmware image.
120 @retval EFI_DEVICE_ERROR An error occurred attempting to determine the
121 size of the firmware image currently stored in
122 in the firmware device.
132 return EFI_INVALID_PARAMETER
;
140 Returns the GUID value used to fill in the ImageTypeId field of the
141 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
142 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
143 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
144 returned, then ImageTypeId is set to the Guid returned from this function.
146 @param[out] Guid Double pointer to a GUID value that is updated to point to
147 to a GUID value. The GUID value is not allocated and must
148 not be modified or freed by the caller.
150 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
151 to the returned Guid value.
152 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
158 FmpDeviceGetImageTypeIdGuidPtr (
162 return EFI_UNSUPPORTED
;
166 Returns values used to fill in the AttributesSupported and AttributesSettings
167 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
168 GetImageInfo() service of the Firmware Management Protocol. The following
169 bit values from the Firmware Management Protocol may be combined:
170 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
171 IMAGE_ATTRIBUTE_RESET_REQUIRED
172 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
173 IMAGE_ATTRIBUTE_IN_USE
174 IMAGE_ATTRIBUTE_UEFI_IMAGE
176 @param[out] Supported Attributes supported by this firmware device.
177 @param[out] Setting Attributes settings for this firmware device.
179 @retval EFI_SUCCESS The attributes supported by the firmware
180 device were returned.
181 @retval EFI_INVALID_PARAMETER Supported is NULL.
182 @retval EFI_INVALID_PARAMETER Setting is NULL.
187 FmpDeviceGetAttributes (
188 OUT UINT64
*Supported
,
192 if ((Supported
== NULL
) || (Setting
== NULL
)) {
193 return EFI_INVALID_PARAMETER
;
202 Returns the value used to fill in the LowestSupportedVersion field of the
203 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
204 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
205 the firmware device supports a method to report the LowestSupportedVersion
206 value from the currently stored firmware image. If the value can not be
207 reported for the firmware image currently stored in the firmware device, then
208 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
209 occurs attempting to retrieve the LowestSupportedVersion value for the
210 currently stored firmware image.
212 @note It is recommended that all firmware devices support a method to report
213 the LowestSupportedVersion value from the currently stored firmware
216 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
217 from the currently stored firmware image.
219 @retval EFI_SUCCESS The lowest supported version of currently stored
220 firmware image was returned in LowestSupportedVersion.
221 @retval EFI_UNSUPPORTED The firmware device does not support a method to
222 report the lowest supported version of the currently
223 stored firmware image.
224 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
225 supported version of the currently stored firmware
231 FmpDeviceGetLowestSupportedVersion (
232 OUT UINT32
*LowestSupportedVersion
235 return EFI_UNSUPPORTED
;
239 Returns the Null-terminated Unicode string that is used to fill in the
240 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
241 returned by the GetImageInfo() service of the Firmware Management Protocol.
242 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
244 @note It is recommended that all firmware devices support a method to report
245 the VersionName string from the currently stored firmware image.
247 @param[out] VersionString The version string retrieved from the currently
248 stored firmware image.
250 @retval EFI_SUCCESS The version string of currently stored
251 firmware image was returned in Version.
252 @retval EFI_INVALID_PARAMETER VersionString is NULL.
253 @retval EFI_UNSUPPORTED The firmware device does not support a method
254 to report the version string of the currently
255 stored firmware image.
256 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
257 version string of the currently stored
259 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
260 buffer for the version string of the currently
261 stored firmware image.
266 FmpDeviceGetVersionString (
267 OUT CHAR16
**VersionString
270 if (VersionString
== NULL
) {
271 return EFI_INVALID_PARAMETER
;
274 *VersionString
= NULL
;
275 return EFI_UNSUPPORTED
;
279 Returns the value used to fill in the Version field of the
280 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
281 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
282 the firmware device supports a method to report the Version value from the
283 currently stored firmware image. If the value can not be reported for the
284 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
285 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
286 to retrieve the LowestSupportedVersion value for the currently stored firmware
289 @note It is recommended that all firmware devices support a method to report
290 the Version value from the currently stored firmware image.
292 @param[out] Version The version value retrieved from the currently stored
295 @retval EFI_SUCCESS The version of currently stored firmware image was
297 @retval EFI_UNSUPPORTED The firmware device does not support a method to
298 report the version of the currently stored firmware
300 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
301 of the currently stored firmware image.
306 FmpDeviceGetVersion (
310 return EFI_UNSUPPORTED
;
314 Returns the value used to fill in the HardwareInstance field of the
315 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
316 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
317 the firmware device supports a method to report the HardwareInstance value.
318 If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
319 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
320 to retrieve the HardwareInstance value for the firmware device.
322 @param[out] HardwareInstance The hardware instance value for the firmware
325 @retval EFI_SUCCESS The hardware instance for the current firmware
326 device is returned in HardwareInstance.
327 @retval EFI_UNSUPPORTED The firmware device does not support a method to
328 report the hardware instance value.
329 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
335 FmpDeviceGetHardwareInstance (
336 OUT UINT64
*HardwareInstance
339 return EFI_UNSUPPORTED
;
343 Returns a copy of the firmware image currently stored in the firmware device.
345 @note It is recommended that all firmware devices support a method to retrieve
346 a copy currently stored firmware image. This can be used to support
347 features such as recovery and rollback.
349 @param[out] Image Pointer to a caller allocated buffer where the
350 currently stored firmware image is copied to.
351 @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
352 On return, points to the size, in bytes, of firmware
353 image currently stored in the firmware device.
355 @retval EFI_SUCCESS Image contains a copy of the firmware image
356 currently stored in the firmware device, and
357 ImageSize contains the size, in bytes, of the
358 firmware image currently stored in the
360 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
361 to hold the firmware image currently stored in
362 the firmware device. The buffer size required
363 is returned in ImageSize.
364 @retval EFI_INVALID_PARAMETER The Image is NULL.
365 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
366 @retval EFI_UNSUPPORTED The operation is not supported.
367 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
368 firmware image currently stored in the firmware
376 IN OUT UINTN
*ImageSize
379 return EFI_UNSUPPORTED
;
383 Checks if a new firmware image is valid for the firmware device. This
384 function allows firmware update operation to validate the firmware image
385 before FmpDeviceSetImage() is called.
387 @param[in] Image Points to a new firmware image.
388 @param[in] ImageSize Size, in bytes, of a new firmware image.
389 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
390 a firmware update to the firmware device. The
391 following values from the Firmware Management
392 Protocol are supported:
393 IMAGE_UPDATABLE_VALID
394 IMAGE_UPDATABLE_INVALID
395 IMAGE_UPDATABLE_INVALID_TYPE
396 IMAGE_UPDATABLE_INVALID_OLD
397 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
399 @retval EFI_SUCCESS The image was successfully checked. Additional
400 status information is returned in
402 @retval EFI_INVALID_PARAMETER Image is NULL.
403 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
408 FmpDeviceCheckImage (
409 IN CONST VOID
*Image
,
411 OUT UINT32
*ImageUpdatable
414 UINT32 LastAttemptStatus
;
416 return FmpDeviceCheckImageWithStatus (Image
, ImageSize
, ImageUpdatable
, &LastAttemptStatus
);
420 Checks if a new firmware image is valid for the firmware device. This
421 function allows firmware update operation to validate the firmware image
422 before FmpDeviceSetImage() is called.
424 @param[in] Image Points to a new firmware image.
425 @param[in] ImageSize Size, in bytes, of a new firmware image.
426 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
427 a firmware update to the firmware device. The
428 following values from the Firmware Management
429 Protocol are supported:
430 IMAGE_UPDATABLE_VALID
431 IMAGE_UPDATABLE_INVALID
432 IMAGE_UPDATABLE_INVALID_TYPE
433 IMAGE_UPDATABLE_INVALID_OLD
434 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
435 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
436 status to report back to the ESRT table in case
439 The return status code must fall in the range of
440 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
441 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
443 If the value falls outside this range, it will be converted
444 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
446 @retval EFI_SUCCESS The image was successfully checked. Additional
447 status information is returned in
449 @retval EFI_INVALID_PARAMETER Image is NULL.
450 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
455 FmpDeviceCheckImageWithStatus (
456 IN CONST VOID
*Image
,
458 OUT UINT32
*ImageUpdatable
,
459 OUT UINT32
*LastAttemptStatus
462 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
468 Updates a firmware device with a new firmware image. This function returns
469 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
470 is updatable, the function should perform the following minimal validations
471 before proceeding to do the firmware image update.
472 - Validate that the image is a supported image for this firmware device.
473 Return EFI_ABORTED if the image is not supported. Additional details
474 on why the image is not a supported image may be returned in AbortReason.
475 - Validate the data from VendorCode if is not NULL. Firmware image
476 validation must be performed before VendorCode data validation.
477 VendorCode data is ignored or considered invalid if image validation
478 fails. Return EFI_ABORTED if the VendorCode data is invalid.
480 VendorCode enables vendor to implement vendor-specific firmware image update
481 policy. Null if the caller did not specify the policy or use the default
482 policy. As an example, vendor can implement a policy to allow an option to
483 force a firmware image update when the abort reason is due to the new firmware
484 image version is older than the current firmware image version or bad image
485 checksum. Sensitive operations such as those wiping the entire firmware image
486 and render the device to be non-functional should be encoded in the image
487 itself rather than passed with the VendorCode. AbortReason enables vendor to
488 have the option to provide a more detailed description of the abort reason to
491 @param[in] Image Points to the new firmware image.
492 @param[in] ImageSize Size, in bytes, of the new firmware image.
493 @param[in] VendorCode This enables vendor to implement vendor-specific
494 firmware image update policy. NULL indicates
495 the caller did not specify the policy or use the
497 @param[in] Progress A function used to report the progress of
498 updating the firmware device with the new
500 @param[in] CapsuleFwVersion The version of the new firmware image from the
501 update capsule that provided the new firmware
503 @param[out] AbortReason A pointer to a pointer to a Null-terminated
504 Unicode string providing more details on an
505 aborted operation. The buffer is allocated by
507 EFI_BOOT_SERVICES.AllocatePool(). It is the
508 caller's responsibility to free this buffer with
509 EFI_BOOT_SERVICES.FreePool().
511 @retval EFI_SUCCESS The firmware device was successfully updated
512 with the new firmware image.
513 @retval EFI_ABORTED The operation is aborted. Additional details
514 are provided in AbortReason.
515 @retval EFI_INVALID_PARAMETER The Image was NULL.
516 @retval EFI_UNSUPPORTED The operation is not supported.
522 IN CONST VOID
*Image
,
524 IN CONST VOID
*VendorCode OPTIONAL
,
525 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
526 IN UINT32 CapsuleFwVersion
,
527 OUT CHAR16
**AbortReason
530 UINT32 LastAttemptStatus
;
532 return FmpDeviceSetImageWithStatus (
544 Updates a firmware device with a new firmware image. This function returns
545 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
546 is updatable, the function should perform the following minimal validations
547 before proceeding to do the firmware image update.
548 - Validate that the image is a supported image for this firmware device.
549 Return EFI_ABORTED if the image is not supported. Additional details
550 on why the image is not a supported image may be returned in AbortReason.
551 - Validate the data from VendorCode if is not NULL. Firmware image
552 validation must be performed before VendorCode data validation.
553 VendorCode data is ignored or considered invalid if image validation
554 fails. Return EFI_ABORTED if the VendorCode data is invalid.
556 VendorCode enables vendor to implement vendor-specific firmware image update
557 policy. Null if the caller did not specify the policy or use the default
558 policy. As an example, vendor can implement a policy to allow an option to
559 force a firmware image update when the abort reason is due to the new firmware
560 image version is older than the current firmware image version or bad image
561 checksum. Sensitive operations such as those wiping the entire firmware image
562 and render the device to be non-functional should be encoded in the image
563 itself rather than passed with the VendorCode. AbortReason enables vendor to
564 have the option to provide a more detailed description of the abort reason to
567 @param[in] Image Points to the new firmware image.
568 @param[in] ImageSize Size, in bytes, of the new firmware image.
569 @param[in] VendorCode This enables vendor to implement vendor-specific
570 firmware image update policy. NULL indicates
571 the caller did not specify the policy or use the
573 @param[in] Progress A function used to report the progress of
574 updating the firmware device with the new
576 @param[in] CapsuleFwVersion The version of the new firmware image from the
577 update capsule that provided the new firmware
579 @param[out] AbortReason A pointer to a pointer to a Null-terminated
580 Unicode string providing more details on an
581 aborted operation. The buffer is allocated by
583 EFI_BOOT_SERVICES.AllocatePool(). It is the
584 caller's responsibility to free this buffer with
585 EFI_BOOT_SERVICES.FreePool().
586 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
587 status to report back to the ESRT table in case
588 of error. This value will only be checked when this
589 function returns an error.
591 The return status code must fall in the range of
592 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
593 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
595 If the value falls outside this range, it will be converted
596 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
598 @retval EFI_SUCCESS The firmware device was successfully updated
599 with the new firmware image.
600 @retval EFI_ABORTED The operation is aborted. Additional details
601 are provided in AbortReason.
602 @retval EFI_INVALID_PARAMETER The Image was NULL.
603 @retval EFI_UNSUPPORTED The operation is not supported.
608 FmpDeviceSetImageWithStatus (
609 IN CONST VOID
*Image
,
611 IN CONST VOID
*VendorCode OPTIONAL
,
612 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
613 IN UINT32 CapsuleFwVersion
,
614 OUT CHAR16
**AbortReason
,
615 OUT UINT32
*LastAttemptStatus
618 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
620 return EFI_UNSUPPORTED
;
624 Lock the firmware device that contains a firmware image. Once a firmware
625 device is locked, any attempts to modify the firmware image contents in the
626 firmware device must fail.
628 @note It is recommended that all firmware devices support a lock method to
629 prevent modifications to a stored firmware image.
631 @note A firmware device lock mechanism is typically only cleared by a full
632 system reset (not just sleep state/low power mode).
634 @retval EFI_SUCCESS The firmware device was locked.
635 @retval EFI_UNSUPPORTED The firmware device does not support locking
644 return EFI_UNSUPPORTED
;