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
12 #ifndef __FMP_DEVICE_LIB__
13 #define __FMP_DEVICE_LIB__
15 #include <Protocol/FirmwareManagement.h>
18 Callback function that installs a Firmware Management Protocol instance onto
21 @param[in] Handle The device handle to install a Firmware Management
24 @retval EFI_SUCCESS A Firmware Management Protocol instance was
25 installed onto Handle.
26 @retval EFI_INVALID_PARAMETER Handle is invalid
27 @retval other A Firmware Management Protocol instance could
28 not be installed onto Handle.
33 (EFIAPI
*FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER
)(
38 Callback function that uninstalls a Firmware Management Protocol instance from
41 @param[in] Handle The device handle to uninstall a Firmware Management
44 @retval EFI_SUCCESS A Firmware Management Protocol instance was
45 uninstalled from Handle.
46 @retval EFI_INVALID_PARAMETER Handle is invalid
47 @retval other A Firmware Management Protocol instance could
48 not be uninstalled from Handle.
53 (EFIAPI
*FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER
)(
58 Provide a function to install the Firmware Management Protocol instance onto a
59 device handle when the device is managed by a driver that follows the UEFI
60 Driver Model. If the device is not managed by a driver that follows the UEFI
61 Driver Model, then EFI_UNSUPPORTED is returned.
63 @param[in] FmpInstaller Function that installs the Firmware Management
66 @retval EFI_SUCCESS The device is managed by a driver that follows the
67 UEFI Driver Model. FmpInstaller must be called on
68 each Driver Binding Start().
69 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
70 the UEFI Driver Model.
71 @retval other The Firmware Management Protocol for this firmware
72 device is not installed. The firmware device is
73 still locked using FmpDeviceLock().
78 RegisterFmpInstaller (
79 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller
83 Provide a function to uninstall the Firmware Management Protocol instance from a
84 device handle when the device is managed by a driver that follows the UEFI
85 Driver Model. If the device is not managed by a driver that follows the UEFI
86 Driver Model, then EFI_UNSUPPORTED is returned.
88 @param[in] FmpUninstaller Function that installs the Firmware Management
91 @retval EFI_SUCCESS The device is managed by a driver that follows the
92 UEFI Driver Model. FmpUninstaller must be called on
93 each Driver Binding Stop().
94 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
95 the UEFI Driver Model.
96 @retval other The Firmware Management Protocol for this firmware
97 device is not installed. The firmware device is
98 still locked using FmpDeviceLock().
103 RegisterFmpUninstaller (
104 IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER FmpUninstaller
108 Set the device context for the FmpDeviceLib services when the device is
109 managed by a driver that follows the UEFI Driver Model. If the device is not
110 managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
111 is returned. Once a device context is set, the FmpDeviceLib services
112 operate on the currently set device context.
114 @param[in] Handle Device handle for the FmpDeviceLib services.
115 If Handle is NULL, then Context is freed.
116 @param[in, out] Context Device context for the FmpDeviceLib services.
117 If Context is NULL, then a new context is allocated
118 for Handle and the current device context is set and
119 returned in Context. If Context is not NULL, then
120 the current device context is set.
122 @retval EFI_SUCCESS The device is managed by a driver that follows the
124 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
125 the UEFI Driver Model.
126 @retval other The Firmware Management Protocol for this firmware
127 device is not installed. The firmware device is
128 still locked using FmpDeviceLock().
133 FmpDeviceSetContext (
134 IN EFI_HANDLE Handle
,
135 IN OUT VOID
**Context
139 Returns the size, in bytes, of the firmware image currently stored in the
140 firmware device. This function is used to by the GetImage() and
141 GetImageInfo() services of the Firmware Management Protocol. If the image
142 size can not be determined from the firmware device, then 0 must be returned.
144 @param[out] Size Pointer to the size, in bytes, of the firmware image
145 currently stored in the firmware device.
147 @retval EFI_SUCCESS The size of the firmware image currently
148 stored in the firmware device was returned.
149 @retval EFI_INVALID_PARAMETER Size is NULL.
150 @retval EFI_UNSUPPORTED The firmware device does not support reporting
151 the size of the currently stored firmware image.
152 @retval EFI_DEVICE_ERROR An error occurred attempting to determine the
153 size of the firmware image currently stored in
154 in the firmware device.
164 Returns the GUID value used to fill in the ImageTypeId field of the
165 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
166 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
167 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
168 returned, then ImageTypeId is set to the Guid returned from this function.
170 @param[out] Guid Double pointer to a GUID value that is updated to point to
171 to a GUID value. The GUID value is not allocated and must
172 not be modified or freed by the caller.
174 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
175 to the returned Guid value.
176 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
182 FmpDeviceGetImageTypeIdGuidPtr (
187 Returns values used to fill in the AttributesSupported and AttributesSettings
188 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
189 GetImageInfo() service of the Firmware Management Protocol. The following
190 bit values from the Firmware Management Protocol may be combined:
191 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
192 IMAGE_ATTRIBUTE_RESET_REQUIRED
193 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
194 IMAGE_ATTRIBUTE_IN_USE
195 IMAGE_ATTRIBUTE_UEFI_IMAGE
197 @param[out] Supported Attributes supported by this firmware device.
198 @param[out] Setting Attributes settings for this firmware device.
200 @retval EFI_SUCCESS The attributes supported by the firmware
201 device were returned.
202 @retval EFI_INVALID_PARAMETER Supported is NULL.
203 @retval EFI_INVALID_PARAMETER Setting is NULL.
208 FmpDeviceGetAttributes (
209 OUT UINT64
*Supported
,
214 Returns the value used to fill in the LowestSupportedVersion field of the
215 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
216 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
217 the firmware device supports a method to report the LowestSupportedVersion
218 value from the currently stored firmware image. If the value can not be
219 reported for the firmware image currently stored in the firmware device, then
220 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
221 occurs attempting to retrieve the LowestSupportedVersion value for the
222 currently stored firmware image.
224 @note It is recommended that all firmware devices support a method to report
225 the LowestSupportedVersion value from the currently stored firmware
228 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
229 from the currently stored firmware image.
231 @retval EFI_SUCCESS The lowest supported version of currently stored
232 firmware image was returned in LowestSupportedVersion.
233 @retval EFI_UNSUPPORTED The firmware device does not support a method to
234 report the lowest supported version of the currently
235 stored firmware image.
236 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
237 supported version of the currently stored firmware
243 FmpDeviceGetLowestSupportedVersion (
244 OUT UINT32
*LowestSupportedVersion
248 Returns the Null-terminated Unicode string that is used to fill in the
249 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
250 returned by the GetImageInfo() service of the Firmware Management Protocol.
251 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
253 @note It is recommended that all firmware devices support a method to report
254 the VersionName string from the currently stored firmware image.
256 @param[out] VersionString The version string retrieved from the currently
257 stored firmware image.
259 @retval EFI_SUCCESS The version string of currently stored
260 firmware image was returned in Version.
261 @retval EFI_INVALID_PARAMETER VersionString is NULL.
262 @retval EFI_UNSUPPORTED The firmware device does not support a method
263 to report the version string of the currently
264 stored firmware image.
265 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
266 version string of the currently stored
268 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
269 buffer for the version string of the currently
270 stored firmware image.
275 FmpDeviceGetVersionString (
276 OUT CHAR16
**VersionString
280 Returns the value used to fill in the Version field of the
281 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
282 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
283 the firmware device supports a method to report the Version value from the
284 currently stored firmware image. If the value can not be reported for the
285 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
286 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
287 to retrieve the LowestSupportedVersion value for the currently stored firmware
290 @note It is recommended that all firmware devices support a method to report
291 the Version value from the currently stored firmware image.
293 @param[out] Version The version value retrieved from the currently stored
296 @retval EFI_SUCCESS The version of currently stored firmware image was
298 @retval EFI_UNSUPPORTED The firmware device does not support a method to
299 report the version of the currently stored firmware
301 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
302 of the currently stored firmware image.
307 FmpDeviceGetVersion (
312 Returns the value used to fill in the HardwareInstance field of the
313 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
314 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
315 the firmware device supports a method to report the HardwareInstance value.
316 If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
317 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
318 to retrieve the HardwareInstance value for the firmware device.
320 @param[out] HardwareInstance The hardware instance value for the firmware
323 @retval EFI_SUCCESS The hardware instance for the current firmware
324 device is returned in HardwareInstance.
325 @retval EFI_UNSUPPORTED The firmware device does not support a method to
326 report the hardware instance value.
327 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
333 FmpDeviceGetHardwareInstance (
334 OUT UINT64
*HardwareInstance
338 Returns a copy of the firmware image currently stored in the firmware device.
340 @note It is recommended that all firmware devices support a method to retrieve
341 a copy currently stored firmware image. This can be used to support
342 features such as recovery and rollback.
344 @param[out] Image Pointer to a caller allocated buffer where the
345 currently stored firmware image is copied to.
346 @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
347 On return, points to the size, in bytes, of firmware
348 image currently stored in the firmware device.
350 @retval EFI_SUCCESS Image contains a copy of the firmware image
351 currently stored in the firmware device, and
352 ImageSize contains the size, in bytes, of the
353 firmware image currently stored in the
355 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
356 to hold the firmware image currently stored in
357 the firmware device. The buffer size required
358 is returned in ImageSize.
359 @retval EFI_INVALID_PARAMETER The Image is NULL.
360 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
361 @retval EFI_UNSUPPORTED The operation is not supported.
362 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
363 firmware image currently stored in the firmware
371 IN OUT UINTN
*ImageSize
375 Checks if a new firmware image is valid for the firmware device. This
376 function allows firmware update operation to validate the firmware image
377 before FmpDeviceSetImage() is called.
379 @param[in] Image Points to a new firmware image.
380 @param[in] ImageSize Size, in bytes, of a new firmware image.
381 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
382 a firmware update to the firmware device. The
383 following values from the Firmware Management
384 Protocol are supported:
385 IMAGE_UPDATABLE_VALID
386 IMAGE_UPDATABLE_INVALID
387 IMAGE_UPDATABLE_INVALID_TYPE
388 IMAGE_UPDATABLE_INVALID_OLD
389 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
391 @retval EFI_SUCCESS The image was successfully checked. Additional
392 status information is returned in
394 @retval EFI_INVALID_PARAMETER Image is NULL.
395 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
400 FmpDeviceCheckImage (
401 IN CONST VOID
*Image
,
403 OUT UINT32
*ImageUpdatable
407 Checks if a new firmware image is valid for the firmware device. This
408 function allows firmware update operation to validate the firmware image
409 before FmpDeviceSetImage() is called.
411 @param[in] Image Points to a new firmware image.
412 @param[in] ImageSize Size, in bytes, of a new firmware image.
413 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
414 a firmware update to the firmware device. The
415 following values from the Firmware Management
416 Protocol are supported:
417 IMAGE_UPDATABLE_VALID
418 IMAGE_UPDATABLE_INVALID
419 IMAGE_UPDATABLE_INVALID_TYPE
420 IMAGE_UPDATABLE_INVALID_OLD
421 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
422 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
423 status to report back to the ESRT table in case
426 The return status code must fall in the range of
427 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
428 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
430 If the value falls outside this range, it will be converted
431 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
433 @retval EFI_SUCCESS The image was successfully checked. Additional
434 status information is returned in
436 @retval EFI_INVALID_PARAMETER Image is NULL.
437 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
442 FmpDeviceCheckImageWithStatus (
443 IN CONST VOID
*Image
,
445 OUT UINT32
*ImageUpdatable
,
446 OUT UINT32
*LastAttemptStatus
450 Updates a firmware device with a new firmware image. This function returns
451 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
452 is updatable, the function should perform the following minimal validations
453 before proceeding to do the firmware image update.
454 - Validate that the image is a supported image for this firmware device.
455 Return EFI_ABORTED if the image is not supported. Additional details
456 on why the image is not a supported image may be returned in AbortReason.
457 - Validate the data from VendorCode if is not NULL. Firmware image
458 validation must be performed before VendorCode data validation.
459 VendorCode data is ignored or considered invalid if image validation
460 fails. Return EFI_ABORTED if the VendorCode data is invalid.
462 VendorCode enables vendor to implement vendor-specific firmware image update
463 policy. Null if the caller did not specify the policy or use the default
464 policy. As an example, vendor can implement a policy to allow an option to
465 force a firmware image update when the abort reason is due to the new firmware
466 image version is older than the current firmware image version or bad image
467 checksum. Sensitive operations such as those wiping the entire firmware image
468 and render the device to be non-functional should be encoded in the image
469 itself rather than passed with the VendorCode. AbortReason enables vendor to
470 have the option to provide a more detailed description of the abort reason to
473 @param[in] Image Points to the new firmware image.
474 @param[in] ImageSize Size, in bytes, of the new firmware image.
475 @param[in] VendorCode This enables vendor to implement vendor-specific
476 firmware image update policy. NULL indicates
477 the caller did not specify the policy or use the
479 @param[in] Progress A function used to report the progress of
480 updating the firmware device with the new
482 @param[in] CapsuleFwVersion The version of the new firmware image from the
483 update capsule that provided the new firmware
485 @param[out] AbortReason A pointer to a pointer to a Null-terminated
486 Unicode string providing more details on an
487 aborted operation. The buffer is allocated by
489 EFI_BOOT_SERVICES.AllocatePool(). It is the
490 caller's responsibility to free this buffer with
491 EFI_BOOT_SERVICES.FreePool().
493 @retval EFI_SUCCESS The firmware device was successfully updated
494 with the new firmware image.
495 @retval EFI_ABORTED The operation is aborted. Additional details
496 are provided in AbortReason.
497 @retval EFI_INVALID_PARAMETER The Image was NULL.
498 @retval EFI_UNSUPPORTED The operation is not supported.
504 IN CONST VOID
*Image
,
506 IN CONST VOID
*VendorCode OPTIONAL
,
507 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
508 IN UINT32 CapsuleFwVersion
,
509 OUT CHAR16
**AbortReason
513 Updates a firmware device with a new firmware image. This function returns
514 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
515 is updatable, the function should perform the following minimal validations
516 before proceeding to do the firmware image update.
517 - Validate that the image is a supported image for this firmware device.
518 Return EFI_ABORTED if the image is not supported. Additional details
519 on why the image is not a supported image may be returned in AbortReason.
520 - Validate the data from VendorCode if is not NULL. Firmware image
521 validation must be performed before VendorCode data validation.
522 VendorCode data is ignored or considered invalid if image validation
523 fails. Return EFI_ABORTED if the VendorCode data is invalid.
525 VendorCode enables vendor to implement vendor-specific firmware image update
526 policy. Null if the caller did not specify the policy or use the default
527 policy. As an example, vendor can implement a policy to allow an option to
528 force a firmware image update when the abort reason is due to the new firmware
529 image version is older than the current firmware image version or bad image
530 checksum. Sensitive operations such as those wiping the entire firmware image
531 and render the device to be non-functional should be encoded in the image
532 itself rather than passed with the VendorCode. AbortReason enables vendor to
533 have the option to provide a more detailed description of the abort reason to
536 @param[in] Image Points to the new firmware image.
537 @param[in] ImageSize Size, in bytes, of the new firmware image.
538 @param[in] VendorCode This enables vendor to implement vendor-specific
539 firmware image update policy. NULL indicates
540 the caller did not specify the policy or use the
542 @param[in] Progress A function used to report the progress of
543 updating the firmware device with the new
545 @param[in] CapsuleFwVersion The version of the new firmware image from the
546 update capsule that provided the new firmware
548 @param[out] AbortReason A pointer to a pointer to a Null-terminated
549 Unicode string providing more details on an
550 aborted operation. The buffer is allocated by
552 EFI_BOOT_SERVICES.AllocatePool(). It is the
553 caller's responsibility to free this buffer with
554 EFI_BOOT_SERVICES.FreePool().
555 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
556 status to report back to the ESRT table in case
557 of error. This value will only be checked when this
558 function returns an error.
560 The return status code must fall in the range of
561 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
562 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
564 If the value falls outside this range, it will be converted
565 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
567 @retval EFI_SUCCESS The firmware device was successfully updated
568 with the new firmware image.
569 @retval EFI_ABORTED The operation is aborted. Additional details
570 are provided in AbortReason.
571 @retval EFI_INVALID_PARAMETER The Image was NULL.
572 @retval EFI_UNSUPPORTED The operation is not supported.
577 FmpDeviceSetImageWithStatus (
578 IN CONST VOID
*Image
,
580 IN CONST VOID
*VendorCode OPTIONAL
,
581 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL
,
582 IN UINT32 CapsuleFwVersion
,
583 OUT CHAR16
**AbortReason
,
584 OUT UINT32
*LastAttemptStatus
588 Lock the firmware device that contains a firmware image. Once a firmware
589 device is locked, any attempts to modify the firmware image contents in the
590 firmware device must fail.
592 @note It is recommended that all firmware devices support a lock method to
593 prevent modifications to a stored firmware image.
595 @note A firmware device lock mechanism is typically only cleared by a full
596 system reset (not just sleep state/low power mode).
598 @retval EFI_SUCCESS The firmware device was locked.
599 @retval EFI_UNSUPPORTED The firmware device does not support locking