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
;
139 Returns the GUID value used to fill in the ImageTypeId field of the
140 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
141 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
142 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
143 returned, then ImageTypeId is set to the Guid returned from this function.
145 @param[out] Guid Double pointer to a GUID value that is updated to point to
146 to a GUID value. The GUID value is not allocated and must
147 not be modified or freed by the caller.
149 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
150 to the returned Guid value.
151 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
157 FmpDeviceGetImageTypeIdGuidPtr (
161 return EFI_UNSUPPORTED
;
165 Returns values used to fill in the AttributesSupported and AttributesSettings
166 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
167 GetImageInfo() service of the Firmware Management Protocol. The following
168 bit values from the Firmware Management Protocol may be combined:
169 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
170 IMAGE_ATTRIBUTE_RESET_REQUIRED
171 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
172 IMAGE_ATTRIBUTE_IN_USE
173 IMAGE_ATTRIBUTE_UEFI_IMAGE
175 @param[out] Supported Attributes supported by this firmware device.
176 @param[out] Setting Attributes settings for this firmware device.
178 @retval EFI_SUCCESS The attributes supported by the firmware
179 device were returned.
180 @retval EFI_INVALID_PARAMETER Supported is NULL.
181 @retval EFI_INVALID_PARAMETER Setting is NULL.
186 FmpDeviceGetAttributes (
187 OUT UINT64
*Supported
,
191 if (Supported
== NULL
|| Setting
== NULL
) {
192 return EFI_INVALID_PARAMETER
;
200 Returns the value used to fill in the LowestSupportedVersion field of the
201 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
202 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
203 the firmware device supports a method to report the LowestSupportedVersion
204 value from the currently stored firmware image. If the value can not be
205 reported for the firmware image currently stored in the firmware device, then
206 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
207 occurs attempting to retrieve the LowestSupportedVersion value for the
208 currently stored firmware image.
210 @note It is recommended that all firmware devices support a method to report
211 the LowestSupportedVersion value from the currently stored firmware
214 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
215 from the currently stored firmware image.
217 @retval EFI_SUCCESS The lowest supported version of currently stored
218 firmware image was returned in LowestSupportedVersion.
219 @retval EFI_UNSUPPORTED The firmware device does not support a method to
220 report the lowest supported version of the currently
221 stored firmware image.
222 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
223 supported version of the currently stored firmware
229 FmpDeviceGetLowestSupportedVersion (
230 OUT UINT32
*LowestSupportedVersion
233 return EFI_UNSUPPORTED
;
237 Returns the Null-terminated Unicode string that is used to fill in the
238 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
239 returned by the GetImageInfo() service of the Firmware Management Protocol.
240 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
242 @note It is recommended that all firmware devices support a method to report
243 the VersionName string from the currently stored firmware image.
245 @param[out] VersionString The version string retrieved from the currently
246 stored firmware image.
248 @retval EFI_SUCCESS The version string of currently stored
249 firmware image was returned in Version.
250 @retval EFI_INVALID_PARAMETER VersionString is NULL.
251 @retval EFI_UNSUPPORTED The firmware device does not support a method
252 to report the version string of the currently
253 stored firmware image.
254 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
255 version string of the currently stored
257 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
258 buffer for the version string of the currently
259 stored firmware image.
264 FmpDeviceGetVersionString (
265 OUT CHAR16
**VersionString
268 if (VersionString
== NULL
) {
269 return EFI_INVALID_PARAMETER
;
271 *VersionString
= NULL
;
272 return EFI_UNSUPPORTED
;
276 Returns the value used to fill in the Version field of the
277 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
278 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
279 the firmware device supports a method to report the Version value from the
280 currently stored firmware image. If the value can not be reported for the
281 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
282 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
283 to retrieve the LowestSupportedVersion value for the currently stored firmware
286 @note It is recommended that all firmware devices support a method to report
287 the Version value from the currently stored firmware image.
289 @param[out] Version The version value retrieved from the currently stored
292 @retval EFI_SUCCESS The version of currently stored firmware image was
294 @retval EFI_UNSUPPORTED The firmware device does not support a method to
295 report the version of the currently stored firmware
297 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
298 of the currently stored firmware image.
303 FmpDeviceGetVersion (
307 return EFI_UNSUPPORTED
;
311 Returns the value used to fill in the HardwareInstance field of the
312 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
313 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
314 the firmware device supports a method to report the HardwareInstance value.
315 If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
316 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
317 to retrieve the HardwareInstance value for the firmware device.
319 @param[out] HardwareInstance The hardware instance value for the firmware
322 @retval EFI_SUCCESS The hardware instance for the current firmware
323 device is returned in HardwareInstance.
324 @retval EFI_UNSUPPORTED The firmware device does not support a method to
325 report the hardware instance value.
326 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
332 FmpDeviceGetHardwareInstance (
333 OUT UINT64
*HardwareInstance
336 return EFI_UNSUPPORTED
;
340 Returns a copy of the firmware image currently stored in the firmware device.
342 @note It is recommended that all firmware devices support a method to retrieve
343 a copy currently stored firmware image. This can be used to support
344 features such as recovery and rollback.
346 @param[out] Image Pointer to a caller allocated buffer where the
347 currently stored firmware image is copied to.
348 @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
349 On return, points to the size, in bytes, of firmware
350 image currently stored in the firmware device.
352 @retval EFI_SUCCESS Image contains a copy of the firmware image
353 currently stored in the firmware device, and
354 ImageSize contains the size, in bytes, of the
355 firmware image currently stored in the
357 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
358 to hold the firmware image currently stored in
359 the firmware device. The buffer size required
360 is returned in ImageSize.
361 @retval EFI_INVALID_PARAMETER The Image is NULL.
362 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
363 @retval EFI_UNSUPPORTED The operation is not supported.
364 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
365 firmware image currently stored in the firmware
373 IN OUT UINTN
*ImageSize
376 return EFI_UNSUPPORTED
;
380 Checks if a new firmware image is valid for the firmware device. This
381 function allows firmware update operation to validate the firmware image
382 before FmpDeviceSetImage() is called.
384 @param[in] Image Points to a new firmware image.
385 @param[in] ImageSize Size, in bytes, of a new firmware image.
386 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
387 a firmware update to the firmware device. The
388 following values from the Firmware Management
389 Protocol are supported:
390 IMAGE_UPDATABLE_VALID
391 IMAGE_UPDATABLE_INVALID
392 IMAGE_UPDATABLE_INVALID_TYPE
393 IMAGE_UPDATABLE_INVALID_OLD
394 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
396 @retval EFI_SUCCESS The image was successfully checked. Additional
397 status information is returned in
399 @retval EFI_INVALID_PARAMETER Image is NULL.
400 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
405 FmpDeviceCheckImage (
406 IN CONST VOID
*Image
,
408 OUT UINT32
*ImageUpdatable
411 UINT32 LastAttemptStatus
;
413 return FmpDeviceCheckImageWithStatus (Image
, ImageSize
, ImageUpdatable
, &LastAttemptStatus
);
417 Checks if a new firmware image is valid for the firmware device. This
418 function allows firmware update operation to validate the firmware image
419 before FmpDeviceSetImage() is called.
421 @param[in] Image Points to a new firmware image.
422 @param[in] ImageSize Size, in bytes, of a new firmware image.
423 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
424 a firmware update to the firmware device. The
425 following values from the Firmware Management
426 Protocol are supported:
427 IMAGE_UPDATABLE_VALID
428 IMAGE_UPDATABLE_INVALID
429 IMAGE_UPDATABLE_INVALID_TYPE
430 IMAGE_UPDATABLE_INVALID_OLD
431 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
432 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
433 status to report back to the ESRT table in case
434 of error. This value will only be checked when this
435 function returns an error.
437 The return status code must fall in the range of
438 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
439 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
441 If the value falls outside this range, it will be converted
442 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
444 @retval EFI_SUCCESS The image was successfully checked. Additional
445 status information is returned in
447 @retval EFI_INVALID_PARAMETER Image is NULL.
448 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
453 FmpDeviceCheckImageWithStatus (
454 IN CONST VOID
*Image
,
456 OUT UINT32
*ImageUpdatable
,
457 OUT UINT32
*LastAttemptStatus
460 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
466 Updates a firmware device with a new firmware image. This function returns
467 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
468 is updatable, the function should perform the following minimal validations
469 before proceeding to do the firmware image update.
470 - Validate that the image is a supported image for this firmware device.
471 Return EFI_ABORTED if the image is not supported. Additional details
472 on why the image is not a supported image may be returned in AbortReason.
473 - Validate the data from VendorCode if is not NULL. Firmware image
474 validation must be performed before VendorCode data validation.
475 VendorCode data is ignored or considered invalid if image validation
476 fails. Return EFI_ABORTED if the VendorCode data is invalid.
478 VendorCode enables vendor to implement vendor-specific firmware image update
479 policy. Null if the caller did not specify the policy or use the default
480 policy. As an example, vendor can implement a policy to allow an option to
481 force a firmware image update when the abort reason is due to the new firmware
482 image version is older than the current firmware image version or bad image
483 checksum. Sensitive operations such as those wiping the entire firmware image
484 and render the device to be non-functional should be encoded in the image
485 itself rather than passed with the VendorCode. AbortReason enables vendor to
486 have the option to provide a more detailed description of the abort reason to
489 @param[in] Image Points to the new firmware image.
490 @param[in] ImageSize Size, in bytes, of the new firmware image.
491 @param[in] VendorCode This enables vendor to implement vendor-specific
492 firmware image update policy. NULL indicates
493 the caller did not specify the policy or use the
495 @param[in] Progress A function used to report the progress of
496 updating the firmware device with the new
498 @param[in] CapsuleFwVersion The version of the new firmware image from the
499 update capsule that provided the new firmware
501 @param[out] AbortReason A pointer to a pointer to a Null-terminated
502 Unicode string providing more details on an
503 aborted operation. The buffer is allocated by
505 EFI_BOOT_SERVICES.AllocatePool(). It is the
506 caller's responsibility to free this buffer with
507 EFI_BOOT_SERVICES.FreePool().
509 @retval EFI_SUCCESS The firmware device was successfully updated
510 with the new firmware image.
511 @retval EFI_ABORTED The operation is aborted. Additional details
512 are provided in AbortReason.
513 @retval EFI_INVALID_PARAMETER The Image was NULL.
514 @retval EFI_UNSUPPORTED The operation is not supported.
520 IN CONST VOID
*Image
,
522 IN CONST VOID
*VendorCode OPTIONAL
,
523 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
524 IN UINT32 CapsuleFwVersion
,
525 OUT CHAR16
**AbortReason
528 UINT32 LastAttemptStatus
;
530 return FmpDeviceSetImageWithStatus (
542 Updates a firmware device with a new firmware image. This function returns
543 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
544 is updatable, the function should perform the following minimal validations
545 before proceeding to do the firmware image update.
546 - Validate that the image is a supported image for this firmware device.
547 Return EFI_ABORTED if the image is not supported. Additional details
548 on why the image is not a supported image may be returned in AbortReason.
549 - Validate the data from VendorCode if is not NULL. Firmware image
550 validation must be performed before VendorCode data validation.
551 VendorCode data is ignored or considered invalid if image validation
552 fails. Return EFI_ABORTED if the VendorCode data is invalid.
554 VendorCode enables vendor to implement vendor-specific firmware image update
555 policy. Null if the caller did not specify the policy or use the default
556 policy. As an example, vendor can implement a policy to allow an option to
557 force a firmware image update when the abort reason is due to the new firmware
558 image version is older than the current firmware image version or bad image
559 checksum. Sensitive operations such as those wiping the entire firmware image
560 and render the device to be non-functional should be encoded in the image
561 itself rather than passed with the VendorCode. AbortReason enables vendor to
562 have the option to provide a more detailed description of the abort reason to
565 @param[in] Image Points to the new firmware image.
566 @param[in] ImageSize Size, in bytes, of the new firmware image.
567 @param[in] VendorCode This enables vendor to implement vendor-specific
568 firmware image update policy. NULL indicates
569 the caller did not specify the policy or use the
571 @param[in] Progress A function used to report the progress of
572 updating the firmware device with the new
574 @param[in] CapsuleFwVersion The version of the new firmware image from the
575 update capsule that provided the new firmware
577 @param[out] AbortReason A pointer to a pointer to a Null-terminated
578 Unicode string providing more details on an
579 aborted operation. The buffer is allocated by
581 EFI_BOOT_SERVICES.AllocatePool(). It is the
582 caller's responsibility to free this buffer with
583 EFI_BOOT_SERVICES.FreePool().
584 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
585 status to report back to the ESRT table in case
586 of error. This value will only be checked when this
587 function returns an error.
589 The return status code must fall in the range of
590 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
591 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
593 If the value falls outside this range, it will be converted
594 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
596 @retval EFI_SUCCESS The firmware device was successfully updated
597 with the new firmware image.
598 @retval EFI_ABORTED The operation is aborted. Additional details
599 are provided in AbortReason.
600 @retval EFI_INVALID_PARAMETER The Image was NULL.
601 @retval EFI_UNSUPPORTED The operation is not supported.
606 FmpDeviceSetImageWithStatus (
607 IN CONST VOID
*Image
,
609 IN CONST VOID
*VendorCode OPTIONAL
,
610 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
611 IN UINT32 CapsuleFwVersion
,
612 OUT CHAR16
**AbortReason
,
613 OUT UINT32
*LastAttemptStatus
616 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
618 return EFI_UNSUPPORTED
;
622 Lock the firmware device that contains a firmware image. Once a firmware
623 device is locked, any attempts to modify the firmware image contents in the
624 firmware device must fail.
626 @note It is recommended that all firmware devices support a lock method to
627 prevent modifications to a stored firmware image.
629 @note A firmware device lock mechanism is typically only cleared by a full
630 system reset (not just sleep state/low power mode).
632 @retval EFI_SUCCESS The firmware device was locked.
633 @retval EFI_UNSUPPORTED The firmware device does not support locking
642 return EFI_UNSUPPORTED
;