FmpDeviceLib.h File Reference

Typedefs
typedef EFI_STATUS(EFIAPI *	FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER )(IN EFI_HANDLE Handle)
typedef EFI_STATUS(EFIAPI *	FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER )(IN EFI_HANDLE Handle)

Functions
EFI_STATUS EFIAPI	RegisterFmpInstaller (IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller)
EFI_STATUS EFIAPI	RegisterFmpUninstaller (IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER FmpUninstaller)
EFI_STATUS EFIAPI	FmpDeviceSetContext (IN EFI_HANDLE Handle, IN OUT VOID **Context)
EFI_STATUS EFIAPI	FmpDeviceGetSize (OUT UINTN *Size)
EFI_STATUS EFIAPI	FmpDeviceGetImageTypeIdGuidPtr (OUT EFI_GUID **Guid)
EFI_STATUS EFIAPI	FmpDeviceGetAttributes (OUT UINT64 *Supported, OUT UINT64 *Setting)
EFI_STATUS EFIAPI	FmpDeviceGetLowestSupportedVersion (OUT UINT32 *LowestSupportedVersion)
EFI_STATUS EFIAPI	FmpDeviceGetVersionString (OUT CHAR16 **VersionString)
EFI_STATUS EFIAPI	FmpDeviceGetVersion (OUT UINT32 *Version)
EFI_STATUS EFIAPI	FmpDeviceGetHardwareInstance (OUT UINT64 *HardwareInstance)
EFI_STATUS EFIAPI	FmpDeviceGetImage (OUT VOID *Image, IN OUT UINTN *ImageSize)
EFI_STATUS EFIAPI	FmpDeviceCheckImage (IN CONST VOID *Image, IN UINTN ImageSize, OUT UINT32 *ImageUpdatable)
EFI_STATUS EFIAPI	FmpDeviceCheckImageWithStatus (IN CONST VOID *Image, IN UINTN ImageSize, OUT UINT32 *ImageUpdatable, OUT UINT32 *LastAttemptStatus)
EFI_STATUS EFIAPI	FmpDeviceSetImage (IN CONST VOID *Image, IN UINTN ImageSize, IN CONST VOID *VendorCode, IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, IN UINT32 CapsuleFwVersion, OUT CHAR16 **AbortReason)
EFI_STATUS EFIAPI	FmpDeviceSetImageWithStatus (IN CONST VOID *Image, IN UINTN ImageSize, IN CONST VOID *VendorCode, IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, IN UINT32 CapsuleFwVersion, OUT CHAR16 **AbortReason, OUT UINT32 *LastAttemptStatus)
EFI_STATUS EFIAPI	FmpDeviceLock (VOID)

Detailed Description

Provides firmware device specific services to support updates of a firmware image stored in a firmware device.

Copyright (c) Microsoft Corporation.
Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.

SPDX-License-Identifier: BSD-2-Clause-Patent

Typedef Documentation

typedef EFI_STATUS(EFIAPI * FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER)(IN EFI_HANDLE Handle)

Callback function that installs a Firmware Management Protocol instance onto a handle.

Parameters

[in]

Handle

The device handle to install a Firmware Management Protocol instance.

Return values

EFI_SUCCESS	A Firmware Management Protocol instance was installed onto Handle.
EFI_INVALID_PARAMETER	Handle is invalid
other	A Firmware Management Protocol instance could not be installed onto Handle.

typedef EFI_STATUS(EFIAPI * FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER)(IN EFI_HANDLE Handle)

Callback function that uninstalls a Firmware Management Protocol instance from a handle.

Parameters

[in]

Handle

The device handle to uninstall a Firmware Management Protocol instance.

Return values

EFI_SUCCESS	A Firmware Management Protocol instance was uninstalled from Handle.
EFI_INVALID_PARAMETER	Handle is invalid
other	A Firmware Management Protocol instance could not be uninstalled from Handle.

Function Documentation

EFI_STATUS EFIAPI FmpDeviceCheckImage	(	IN CONST VOID *	Image,
		IN UINTN	ImageSize,
		OUT UINT32 *	ImageUpdatable
	)

Checks if a new firmware image is valid for the firmware device. This function allows firmware update operation to validate the firmware image before FmpDeviceSetImage() is called.

Parameters

[in]	Image	Points to a new firmware image.
[in]	ImageSize	Size, in bytes, of a new firmware image.
[out]	ImageUpdatable	Indicates if a new firmware image is valid for a firmware update to the firmware device. The following values from the Firmware Management Protocol are supported: IMAGE_UPDATABLE_VALID IMAGE_UPDATABLE_INVALID IMAGE_UPDATABLE_INVALID_TYPE IMAGE_UPDATABLE_INVALID_OLD IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE

Return values

EFI_SUCCESS	The image was successfully checked. Additional status information is returned in ImageUpdatable.
EFI_INVALID_PARAMETER	Image is NULL.
EFI_INVALID_PARAMETER	ImageUpdatable is NULL.

EFI_STATUS EFIAPI FmpDeviceCheckImageWithStatus	(	IN CONST VOID *	Image,
		IN UINTN	ImageSize,
		OUT UINT32 *	ImageUpdatable,
		OUT UINT32 *	LastAttemptStatus
	)

Checks if a new firmware image is valid for the firmware device. This function allows firmware update operation to validate the firmware image before FmpDeviceSetImage() is called.

Parameters

[in]	Image	Points to a new firmware image.
[in]	ImageSize	Size, in bytes, of a new firmware image.
[out]	ImageUpdatable	Indicates if a new firmware image is valid for a firmware update to the firmware device. The following values from the Firmware Management Protocol are supported: IMAGE_UPDATABLE_VALID IMAGE_UPDATABLE_INVALID IMAGE_UPDATABLE_INVALID_TYPE IMAGE_UPDATABLE_INVALID_OLD IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
[out]	LastAttemptStatus	A pointer to a UINT32 that holds the last attempt status to report back to the ESRT table in case of error. This value will only be checked when this function returns an error.

The return status code must fall in the range of LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.

If the value falls outside this range, it will be converted to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.

Return values

EFI_SUCCESS	The image was successfully checked. Additional status information is returned in ImageUpdatable.
EFI_INVALID_PARAMETER	Image is NULL.
EFI_INVALID_PARAMETER	ImageUpdatable is NULL.

EFI_STATUS EFIAPI FmpDeviceGetAttributes	(	OUT UINT64 *	Supported,
		OUT UINT64 *	Setting
	)

Returns values used to fill in the AttributesSupported and AttributesSettings fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. The following bit values from the Firmware Management Protocol may be combined: IMAGE_ATTRIBUTE_IMAGE_UPDATABLE IMAGE_ATTRIBUTE_RESET_REQUIRED IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED IMAGE_ATTRIBUTE_IN_USE IMAGE_ATTRIBUTE_UEFI_IMAGE

Parameters

[out]	Supported	Attributes supported by this firmware device.
[out]	Setting	Attributes settings for this firmware device.

Return values

EFI_SUCCESS	The attributes supported by the firmware device were returned.
EFI_INVALID_PARAMETER	Supported is NULL.
EFI_INVALID_PARAMETER	Setting is NULL.

EFI_STATUS EFIAPI FmpDeviceGetHardwareInstance

(

OUT UINT64 *

HardwareInstance

)

Returns the value used to fill in the HardwareInstance field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then the firmware device supports a method to report the HardwareInstance value. If the value can not be reported for the firmware device, then EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting to retrieve the HardwareInstance value for the firmware device.

Parameters

[out]

HardwareInstance

The hardware instance value for the firmware device.

Return values

EFI_SUCCESS	The hardware instance for the current firmware device is returned in HardwareInstance.
EFI_UNSUPPORTED	The firmware device does not support a method to report the hardware instance value.
EFI_DEVICE_ERROR	An error occurred attempting to retrieve the hardware instance value.

EFI_STATUS EFIAPI FmpDeviceGetImage	(	OUT VOID *	Image,
		IN OUT UINTN *	ImageSize
	)

Returns a copy of the firmware image currently stored in the firmware device.

Note

It is recommended that all firmware devices support a method to retrieve a copy currently stored firmware image. This can be used to support features such as recovery and rollback.

Parameters

[out]	Image	Pointer to a caller allocated buffer where the currently stored firmware image is copied to.
[in,out]	ImageSize	Pointer the size, in bytes, of the Image buffer. On return, points to the size, in bytes, of firmware image currently stored in the firmware device.

Return values

EFI_SUCCESS	Image contains a copy of the firmware image currently stored in the firmware device, and ImageSize contains the size, in bytes, of the firmware image currently stored in the firmware device.
EFI_BUFFER_TOO_SMALL	The buffer specified by ImageSize is too small to hold the firmware image currently stored in the firmware device. The buffer size required is returned in ImageSize.
EFI_INVALID_PARAMETER	The Image is NULL.
EFI_INVALID_PARAMETER	The ImageSize is NULL.
EFI_UNSUPPORTED	The operation is not supported.
EFI_DEVICE_ERROR	An error occurred attempting to retrieve the firmware image currently stored in the firmware device.

EFI_STATUS EFIAPI FmpDeviceGetImageTypeIdGuidPtr

(

OUT EFI_GUID **

Guid

)

Returns the GUID value used to fill in the ImageTypeId field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned, then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is returned, then ImageTypeId is set to the Guid returned from this function.

Parameters

[out]

Guid

Double pointer to a GUID value that is updated to point to to a GUID value. The GUID value is not allocated and must not be modified or freed by the caller.

Return values

EFI_SUCCESS	EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set to the returned Guid value.
EFI_UNSUPPORTED	EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set to gEfiCallerIdGuid.

EFI_STATUS EFIAPI FmpDeviceGetLowestSupportedVersion

(

OUT UINT32 *

LowestSupportedVersion

)

Returns the value used to fill in the LowestSupportedVersion field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then the firmware device supports a method to report the LowestSupportedVersion value from the currently stored firmware image. If the value can not be reported for the firmware image currently stored in the firmware device, then EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting to retrieve the LowestSupportedVersion value for the currently stored firmware image.

Note

It is recommended that all firmware devices support a method to report the LowestSupportedVersion value from the currently stored firmware image.

Parameters

[out]

LowestSupportedVersion

LowestSupportedVersion value retrieved from the currently stored firmware image.

Return values

EFI_SUCCESS	The lowest supported version of currently stored firmware image was returned in LowestSupportedVersion.
EFI_UNSUPPORTED	The firmware device does not support a method to report the lowest supported version of the currently stored firmware image.
EFI_DEVICE_ERROR	An error occurred attempting to retrieve the lowest supported version of the currently stored firmware image.

EFI_STATUS EFIAPI FmpDeviceGetSize

(

OUT UINTN *

Size

)

Returns the size, in bytes, of the firmware image currently stored in the firmware device. This function is used to by the GetImage() and GetImageInfo() services of the Firmware Management Protocol. If the image size can not be determined from the firmware device, then 0 must be returned.

Parameters

[out]

Size

Pointer to the size, in bytes, of the firmware image currently stored in the firmware device.

Return values

EFI_SUCCESS	The size of the firmware image currently stored in the firmware device was returned.
EFI_INVALID_PARAMETER	Size is NULL.
EFI_UNSUPPORTED	The firmware device does not support reporting the size of the currently stored firmware image.
EFI_DEVICE_ERROR	An error occurred attempting to determine the size of the firmware image currently stored in in the firmware device.

EFI_STATUS EFIAPI FmpDeviceGetVersion

(

OUT UINT32 *

Version

)

Returns the value used to fill in the Version field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then the firmware device supports a method to report the Version value from the currently stored firmware image. If the value can not be reported for the firmware image currently stored in the firmware device, then EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting to retrieve the LowestSupportedVersion value for the currently stored firmware image.

Note

It is recommended that all firmware devices support a method to report the Version value from the currently stored firmware image.

Parameters

[out]

Version

The version value retrieved from the currently stored firmware image.

Return values

EFI_SUCCESS	The version of currently stored firmware image was returned in Version.
EFI_UNSUPPORTED	The firmware device does not support a method to report the version of the currently stored firmware image.
EFI_DEVICE_ERROR	An error occurred attempting to retrieve the version of the currently stored firmware image.

EFI_STATUS EFIAPI FmpDeviceGetVersionString

(

OUT CHAR16 **

VersionString

)

Returns the Null-terminated Unicode string that is used to fill in the VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo() service of the Firmware Management Protocol. The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().

Note

It is recommended that all firmware devices support a method to report the VersionName string from the currently stored firmware image.

Parameters

[out]

VersionString

The version string retrieved from the currently stored firmware image.

Return values

EFI_SUCCESS	The version string of currently stored firmware image was returned in Version.
EFI_INVALID_PARAMETER	VersionString is NULL.
EFI_UNSUPPORTED	The firmware device does not support a method to report the version string of the currently stored firmware image.
EFI_DEVICE_ERROR	An error occurred attempting to retrieve the version string of the currently stored firmware image.
EFI_OUT_OF_RESOURCES	There are not enough resources to allocate the buffer for the version string of the currently stored firmware image.

EFI_STATUS EFIAPI FmpDeviceLock

(

VOID

)

Lock the firmware device that contains a firmware image. Once a firmware device is locked, any attempts to modify the firmware image contents in the firmware device must fail.

Note

It is recommended that all firmware devices support a lock method to prevent modifications to a stored firmware image.

A firmware device lock mechanism is typically only cleared by a full system reset (not just sleep state/low power mode).

Return values

EFI_SUCCESS	The firmware device was locked.
EFI_UNSUPPORTED	The firmware device does not support locking

EFI_STATUS EFIAPI FmpDeviceSetContext	(	IN EFI_HANDLE	Handle,
		IN OUT VOID **	Context
	)

Set the device context for the FmpDeviceLib services when the device is managed by a driver that follows the UEFI Driver Model. If the device is not managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED is returned. Once a device context is set, the FmpDeviceLib services operate on the currently set device context.

Parameters

[in]	Handle	Device handle for the FmpDeviceLib services. If Handle is NULL, then Context is freed.
[in,out]	Context	Device context for the FmpDeviceLib services. If Context is NULL, then a new context is allocated for Handle and the current device context is set and returned in Context. If Context is not NULL, then the current device context is set.

Return values

EFI_SUCCESS	The device is managed by a driver that follows the UEFI Driver Model.
EFI_UNSUPPORTED	The device is not managed by a driver that follows the UEFI Driver Model.
other	The Firmware Management Protocol for this firmware device is not installed. The firmware device is still locked using FmpDeviceLock().

EFI_STATUS EFIAPI FmpDeviceSetImage	(	IN CONST VOID *	Image,
		IN UINTN	ImageSize,
		IN CONST VOID *	VendorCode,
		IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS	Progress,
		IN UINT32	CapsuleFwVersion,
		OUT CHAR16 **	AbortReason
	)

Updates a firmware device with a new firmware image. This function returns EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image is updatable, the function should perform the following minimal validations before proceeding to do the firmware image update.

• Validate that the image is a supported image for this firmware device. Return EFI_ABORTED if the image is not supported. Additional details on why the image is not a supported image may be returned in AbortReason.
• Validate the data from VendorCode if is not NULL. Firmware image validation must be performed before VendorCode data validation. VendorCode data is ignored or considered invalid if image validation fails. Return EFI_ABORTED if the VendorCode data is invalid.

VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if the caller did not specify the policy or use the default policy. As an example, vendor can implement a policy to allow an option to force a firmware image update when the abort reason is due to the new firmware image version is older than the current firmware image version or bad image checksum. Sensitive operations such as those wiping the entire firmware image and render the device to be non-functional should be encoded in the image itself rather than passed with the VendorCode. AbortReason enables vendor to have the option to provide a more detailed description of the abort reason to the caller.

Parameters

[in]	Image	Points to the new firmware image.
[in]	ImageSize	Size, in bytes, of the new firmware image.
[in]	VendorCode	This enables vendor to implement vendor-specific firmware image update policy. NULL indicates the caller did not specify the policy or use the default policy.
[in]	Progress	A function used to report the progress of updating the firmware device with the new firmware image.
[in]	CapsuleFwVersion	The version of the new firmware image from the update capsule that provided the new firmware image.
[out]	AbortReason	A pointer to a pointer to a Null-terminated Unicode string providing more details on an aborted operation. The buffer is allocated by this function with EFI_BOOT_SERVICES.AllocatePool(). It is the caller's responsibility to free this buffer with EFI_BOOT_SERVICES.FreePool().

Return values

EFI_SUCCESS	The firmware device was successfully updated with the new firmware image.
EFI_ABORTED	The operation is aborted. Additional details are provided in AbortReason.
EFI_INVALID_PARAMETER	The Image was NULL.
EFI_UNSUPPORTED	The operation is not supported.

EFI_STATUS EFIAPI FmpDeviceSetImageWithStatus	(	IN CONST VOID *	Image,
		IN UINTN	ImageSize,
		IN CONST VOID *	VendorCode,
		IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS	Progress,
		IN UINT32	CapsuleFwVersion,
		OUT CHAR16 **	AbortReason,
		OUT UINT32 *	LastAttemptStatus
	)

Updates a firmware device with a new firmware image. This function returns EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image is updatable, the function should perform the following minimal validations before proceeding to do the firmware image update.

• Validate that the image is a supported image for this firmware device. Return EFI_ABORTED if the image is not supported. Additional details on why the image is not a supported image may be returned in AbortReason.
• Validate the data from VendorCode if is not NULL. Firmware image validation must be performed before VendorCode data validation. VendorCode data is ignored or considered invalid if image validation fails. Return EFI_ABORTED if the VendorCode data is invalid.

VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if the caller did not specify the policy or use the default policy. As an example, vendor can implement a policy to allow an option to force a firmware image update when the abort reason is due to the new firmware image version is older than the current firmware image version or bad image checksum. Sensitive operations such as those wiping the entire firmware image and render the device to be non-functional should be encoded in the image itself rather than passed with the VendorCode. AbortReason enables vendor to have the option to provide a more detailed description of the abort reason to the caller.

Parameters

[in]	Image	Points to the new firmware image.
[in]	ImageSize	Size, in bytes, of the new firmware image.
[in]	VendorCode	This enables vendor to implement vendor-specific firmware image update policy. NULL indicates the caller did not specify the policy or use the default policy.
[in]	Progress	A function used to report the progress of updating the firmware device with the new firmware image.
[in]	CapsuleFwVersion	The version of the new firmware image from the update capsule that provided the new firmware image.
[out]	AbortReason	A pointer to a pointer to a Null-terminated Unicode string providing more details on an aborted operation. The buffer is allocated by this function with EFI_BOOT_SERVICES.AllocatePool(). It is the caller's responsibility to free this buffer with EFI_BOOT_SERVICES.FreePool().
[out]	LastAttemptStatus	A pointer to a UINT32 that holds the last attempt status to report back to the ESRT table in case of error. This value will only be checked when this function returns an error.

The return status code must fall in the range of LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.

If the value falls outside this range, it will be converted to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.

Return values

EFI_SUCCESS	The firmware device was successfully updated with the new firmware image.
EFI_ABORTED	The operation is aborted. Additional details are provided in AbortReason.
EFI_INVALID_PARAMETER	The Image was NULL.
EFI_UNSUPPORTED	The operation is not supported.

EFI_STATUS EFIAPI RegisterFmpInstaller

(

IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER

FmpInstaller

)

Provide a function to install the Firmware Management Protocol instance onto a device handle when the device is managed by a driver that follows the UEFI Driver Model. If the device is not managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED is returned.

Parameters

[in]

FmpInstaller

Function that installs the Firmware Management Protocol.

Return values

EFI_SUCCESS	The device is managed by a driver that follows the UEFI Driver Model. FmpInstaller must be called on each Driver Binding Start().
EFI_UNSUPPORTED	The device is not managed by a driver that follows the UEFI Driver Model.
other	The Firmware Management Protocol for this firmware device is not installed. The firmware device is still locked using FmpDeviceLock().

EFI_STATUS EFIAPI RegisterFmpUninstaller

(

IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER

FmpUninstaller

)

Provide a function to uninstall the Firmware Management Protocol instance from a device handle when the device is managed by a driver that follows the UEFI Driver Model. If the device is not managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED is returned.

Parameters

[in]

FmpUninstaller

Function that installs the Firmware Management Protocol.

Return values

EFI_SUCCESS	The device is managed by a driver that follows the UEFI Driver Model. FmpUninstaller must be called on each Driver Binding Stop().
EFI_UNSUPPORTED	The device is not managed by a driver that follows the UEFI Driver Model.
other	The Firmware Management Protocol for this firmware device is not installed. The firmware device is still locked using FmpDeviceLock().