mirror of https://github.com/acidanthera/audk.git
491 lines
22 KiB
C
491 lines
22 KiB
C
/** @file
|
|
Provides firmware device specific services to support updates of a firmware
|
|
image stored in a firmware device.
|
|
|
|
Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>
|
|
Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#ifndef __FMP_DEVICE_LIB__
|
|
#define __FMP_DEVICE_LIB__
|
|
|
|
#include <Protocol/FirmwareManagement.h>
|
|
|
|
/**
|
|
Callback function that installs a Firmware Management Protocol instance onto
|
|
a handle.
|
|
|
|
@param[in] Handle The device handle to install a Firmware Management
|
|
Protocol instance.
|
|
|
|
@retval EFI_SUCCESS A Firmware Management Protocol instance was
|
|
installed onto Handle.
|
|
@retval EFI_INVALID_PARAMETER Handle is invalid
|
|
@retval other A Firmware Management Protocol instance could
|
|
not be installed onto Handle.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER)(
|
|
IN EFI_HANDLE Handle
|
|
);
|
|
|
|
/**
|
|
Callback function that uninstalls a Firmware Management Protocol instance from
|
|
a handle.
|
|
|
|
@param[in] Handle The device handle to uninstall a Firmware Management
|
|
Protocol instance.
|
|
|
|
@retval EFI_SUCCESS A Firmware Management Protocol instance was
|
|
uninstalled from Handle.
|
|
@retval EFI_INVALID_PARAMETER Handle is invalid
|
|
@retval other A Firmware Management Protocol instance could
|
|
not be uninstalled from Handle.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER)(
|
|
IN EFI_HANDLE Handle
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] FmpInstaller Function that installs the Firmware Management
|
|
Protocol.
|
|
|
|
@retval EFI_SUCCESS The device is managed by a driver that follows the
|
|
UEFI Driver Model. FmpInstaller must be called on
|
|
each Driver Binding Start().
|
|
@retval EFI_UNSUPPORTED The device is not managed by a driver that follows
|
|
the UEFI Driver Model.
|
|
@retval other The Firmware Management Protocol for this firmware
|
|
device is not installed. The firmware device is
|
|
still locked using FmpDeviceLock().
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
RegisterFmpInstaller (
|
|
IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] FmpUninstaller Function that installs the Firmware Management
|
|
Protocol.
|
|
|
|
@retval EFI_SUCCESS The device is managed by a driver that follows the
|
|
UEFI Driver Model. FmpUinstaller must be called on
|
|
each Driver Binding Stop().
|
|
@retval EFI_UNSUPPORTED The device is not managed by a driver that follows
|
|
the UEFI Driver Model.
|
|
@retval 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
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] Handle Device handle for the FmpDeviceLib services.
|
|
If Handle is NULL, then Context is freed.
|
|
@param[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.
|
|
|
|
@retval EFI_SUCCESS The device is managed by a driver that follows the
|
|
UEFI Driver Model.
|
|
@retval EFI_UNSUPPORTED The device is not managed by a driver that follows
|
|
the UEFI Driver Model.
|
|
@retval other The Firmware Management Protocol for this firmware
|
|
device is not installed. The firmware device is
|
|
still locked using FmpDeviceLock().
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceSetContext (
|
|
IN EFI_HANDLE Handle,
|
|
IN OUT VOID **Context
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] Size Pointer to the size, in bytes, of the firmware image
|
|
currently stored in the firmware device.
|
|
|
|
@retval EFI_SUCCESS The size of the firmware image currently
|
|
stored in the firmware device was returned.
|
|
@retval EFI_INVALID_PARAMETER Size is NULL.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support reporting
|
|
the size of the currently stored firmware image.
|
|
@retval 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
|
|
FmpDeviceGetSize (
|
|
OUT UINTN *Size
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[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.
|
|
|
|
@retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
|
|
to the returned Guid value.
|
|
@retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
|
|
to gEfiCallerIdGuid.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetImageTypeIdGuidPtr (
|
|
OUT EFI_GUID **Guid
|
|
);
|
|
|
|
/**
|
|
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
|
|
|
|
@param[out] Supported Attributes supported by this firmware device.
|
|
@param[out] Setting Attributes settings for this firmware device.
|
|
|
|
@retval EFI_SUCCESS The attributes supported by the firmware
|
|
device were returned.
|
|
@retval EFI_INVALID_PARAMETER Supported is NULL.
|
|
@retval EFI_INVALID_PARAMETER Setting is NULL.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetAttributes (
|
|
OUT UINT64 *Supported,
|
|
OUT UINT64 *Setting
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
|
|
from the currently stored firmware image.
|
|
|
|
@retval EFI_SUCCESS The lowest supported version of currently stored
|
|
firmware image was returned in LowestSupportedVersion.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support a method to
|
|
report the lowest supported version of the currently
|
|
stored firmware image.
|
|
@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
|
|
supported version of the currently stored firmware
|
|
image.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetLowestSupportedVersion (
|
|
OUT UINT32 *LowestSupportedVersion
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] VersionString The version string retrieved from the currently
|
|
stored firmware image.
|
|
|
|
@retval EFI_SUCCESS The version string of currently stored
|
|
firmware image was returned in Version.
|
|
@retval EFI_INVALID_PARAMETER VersionString is NULL.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support a method
|
|
to report the version string of the currently
|
|
stored firmware image.
|
|
@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
|
|
version string of the currently stored
|
|
firmware image.
|
|
@retval 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
|
|
FmpDeviceGetVersionString (
|
|
OUT CHAR16 **VersionString
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] Version The version value retrieved from the currently stored
|
|
firmware image.
|
|
|
|
@retval EFI_SUCCESS The version of currently stored firmware image was
|
|
returned in Version.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support a method to
|
|
report the version of the currently stored firmware
|
|
image.
|
|
@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
|
|
of the currently stored firmware image.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetVersion (
|
|
OUT UINT32 *Version
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] HardwareInstance The hardware instance value for the firmware
|
|
device.
|
|
|
|
@retval EFI_SUCCESS The hardware instance for the current firmware
|
|
devide is returned in HardwareInstance.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support a method to
|
|
report the hardware instance value.
|
|
@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
|
|
instance value.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetHardwareInstance (
|
|
OUT UINT64 *HardwareInstance
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[out] Image Pointer to a caller allocated buffer where the
|
|
currently stored firmware image is copied to.
|
|
@param[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.
|
|
|
|
@retval 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.
|
|
@retval 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.
|
|
@retval EFI_INVALID_PARAMETER The Image is NULL.
|
|
@retval EFI_INVALID_PARAMETER The ImageSize is NULL.
|
|
@retval EFI_UNSUPPORTED The operation is not supported.
|
|
@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
|
|
firmware image currently stored in the firmware
|
|
device.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceGetImage (
|
|
OUT VOID *Image,
|
|
IN OUT UINTN *ImageSize
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] Image Points to a new firmware image.
|
|
@param[in] ImageSize Size, in bytes, of a new firmware image.
|
|
@param[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
|
|
|
|
@retval EFI_SUCCESS The image was successfully checked. Additional
|
|
status information is returned in
|
|
ImageUpdatable.
|
|
@retval EFI_INVALID_PARAMETER Image is NULL.
|
|
@retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceCheckImage (
|
|
IN CONST VOID *Image,
|
|
IN UINTN ImageSize,
|
|
OUT UINT32 *ImageUpdatable
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param[in] Image Points to the new firmware image.
|
|
@param[in] ImageSize Size, in bytes, of the new firmware image.
|
|
@param[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.
|
|
@param[in] Progress A function used to report the progress of
|
|
updating the firmware device with the new
|
|
firmware image.
|
|
@param[in] CapsuleFwVersion The version of the new firmware image from the
|
|
update capsule that provided the new firmware
|
|
image.
|
|
@param[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().
|
|
|
|
@retval EFI_SUCCESS The firmware device was successfully updated
|
|
with the new firmware image.
|
|
@retval EFI_ABORTED The operation is aborted. Additional details
|
|
are provided in AbortReason.
|
|
@retval EFI_INVALID_PARAMETER The Image was NULL.
|
|
@retval EFI_UNSUPPORTED The operation is not supported.
|
|
|
|
**/
|
|
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
|
|
);
|
|
|
|
/**
|
|
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.
|
|
|
|
@note A firmware device lock mechanism is typically only cleared by a full
|
|
system reset (not just sleep state/low power mode).
|
|
|
|
@retval EFI_SUCCESS The firmware device was locked.
|
|
@retval EFI_UNSUPPORTED The firmware device does not support locking
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
FmpDeviceLock (
|
|
VOID
|
|
);
|
|
|
|
#endif
|