| /** @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, Intel Corporation. All rights reserved.<BR> | |
| Redistribution and use in source and binary forms, with or without | |
| modification, are permitted provided that the following conditions are met: | |
| 1. Redistributions of source code must retain the above copyright notice, | |
| this list of conditions and the following disclaimer. | |
| 2. Redistributions in binary form must reproduce the above copyright notice, | |
| this list of conditions and the following disclaimer in the documentation | |
| and/or other materials provided with the distribution. | |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | |
| ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | |
| WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |
| IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
| INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, | |
| BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | |
| LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE | |
| OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF | |
| ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
| **/ | |
| #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 | |
| ); | |
| /** | |
| 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 | |
| ); | |
| /** | |
| 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 occured 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 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 |