TianoCore EDK2 master
|
Go to the source code of this file.
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
Definition in file FmpDeviceLib.c.
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.
[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 |
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. |
Definition at line 408 of file FmpDeviceLib.c.
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.
[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. |
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.
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. |
Definition at line 455 of file FmpDeviceLib.c.
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
[out] | Supported | Attributes supported by this firmware device. |
[out] | Setting | Attributes settings for this firmware device. |
EFI_SUCCESS | The attributes supported by the firmware device were returned. |
EFI_INVALID_PARAMETER | Supported is NULL. |
EFI_INVALID_PARAMETER | Setting is NULL. |
Definition at line 187 of file FmpDeviceLib.c.
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.
[out] | HardwareInstance | The hardware instance value for the firmware device. |
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. |
Definition at line 335 of file FmpDeviceLib.c.
EFI_STATUS EFIAPI FmpDeviceGetImage | ( | OUT VOID * | Image, |
IN OUT UINTN * | ImageSize | ||
) |
Returns a copy of the firmware image currently stored in the firmware device.
[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. |
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. |
Definition at line 374 of file FmpDeviceLib.c.
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.
[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. |
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. |
Definition at line 158 of file FmpDeviceLib.c.
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.
[out] | LowestSupportedVersion | LowestSupportedVersion value retrieved from the currently stored firmware image. |
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. |
Definition at line 231 of file FmpDeviceLib.c.
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.
[out] | Size | Pointer to the size, in bytes, of the firmware image currently stored in the firmware device. |
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. |
Definition at line 127 of file FmpDeviceLib.c.
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.
[out] | Version | The version value retrieved from the currently stored firmware image. |
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. |
Definition at line 306 of file FmpDeviceLib.c.
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().
[out] | VersionString | The version string retrieved from the currently stored firmware image. |
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. |
Definition at line 266 of file FmpDeviceLib.c.
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.
EFI_SUCCESS | The firmware device was locked. |
EFI_UNSUPPORTED | The firmware device does not support locking |
Definition at line 640 of file FmpDeviceLib.c.
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.
[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. |
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(). |
Definition at line 98 of file FmpDeviceLib.c.
EFI_STATUS EFIAPI FmpDeviceSetImage | ( | IN CONST VOID * | Image, |
IN UINTN | ImageSize, | ||
IN CONST VOID *VendorCode | OPTIONAL, | ||
IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress | OPTIONAL, | ||
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.
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.
[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(). |
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. |
Definition at line 521 of file FmpDeviceLib.c.
EFI_STATUS EFIAPI FmpDeviceSetImageWithStatus | ( | IN CONST VOID * | Image, |
IN UINTN | ImageSize, | ||
IN CONST VOID *VendorCode | OPTIONAL, | ||
IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress | OPTIONAL, | ||
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.
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.
[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.
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. |
Definition at line 608 of file FmpDeviceLib.c.
EFI_STATUS EFIAPI RegisterFmpInstaller | ( | IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER | Function | ) |
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.
[in] | FmpInstaller | Function that installs the Firmware Management Protocol. |
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(). |
Definition at line 37 of file FmpDeviceLib.c.
EFI_STATUS EFIAPI RegisterFmpUninstaller | ( | IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER | Function | ) |
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.
[in] | FmpUninstaller | Function that installs the Firmware Management Protocol. |
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(). |
Definition at line 65 of file FmpDeviceLib.c.