Provides firmware device specific services to support updates of a firmware\r
image stored in a firmware device.\r
\r
- Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
- Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>\r
-\r
- Redistribution and use in source and binary forms, with or without\r
- modification, are permitted provided that the following conditions are met:\r
- 1. Redistributions of source code must retain the above copyright notice,\r
- this list of conditions and the following disclaimer.\r
- 2. Redistributions in binary form must reproduce the above copyright notice,\r
- this list of conditions and the following disclaimer in the documentation\r
- and/or other materials provided with the distribution.\r
-\r
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND\r
- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\r
- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\r
- IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,\r
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,\r
- BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE\r
- OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF\r
- ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
+ Copyright (c) Microsoft Corporation.<BR>\r
+ Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
+\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
IN EFI_HANDLE Handle\r
);\r
\r
+/**\r
+ Callback function that uninstalls a Firmware Management Protocol instance from\r
+ a handle.\r
+\r
+ @param[in] Handle The device handle to uninstall a Firmware Management\r
+ Protocol instance.\r
+\r
+ @retval EFI_SUCCESS A Firmware Management Protocol instance was\r
+ uninstalled from Handle.\r
+ @retval EFI_INVALID_PARAMETER Handle is invalid\r
+ @retval other A Firmware Management Protocol instance could\r
+ not be uninstalled from Handle.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER)(\r
+ IN EFI_HANDLE Handle\r
+ );\r
+\r
/**\r
Provide a function to install the Firmware Management Protocol instance onto a\r
device handle when the device is managed by a driver that follows the UEFI\r
IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller\r
);\r
\r
+/**\r
+ Provide a function to uninstall the Firmware Management Protocol instance from a\r
+ device handle when the device is managed by a driver that follows the UEFI\r
+ Driver Model. If the device is not managed by a driver that follows the UEFI\r
+ Driver Model, then EFI_UNSUPPORTED is returned.\r
+\r
+ @param[in] FmpUninstaller Function that installs the Firmware Management\r
+ Protocol.\r
+\r
+ @retval EFI_SUCCESS The device is managed by a driver that follows the\r
+ UEFI Driver Model. FmpUninstaller must be called on\r
+ each Driver Binding Stop().\r
+ @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
+ the UEFI Driver Model.\r
+ @retval other The Firmware Management Protocol for this firmware\r
+ device is not installed. The firmware device is\r
+ still locked using FmpDeviceLock().\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+RegisterFmpUninstaller (\r
+ IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER FmpUninstaller\r
+ );\r
+\r
+/**\r
+ Set the device context for the FmpDeviceLib services when the device is\r
+ managed by a driver that follows the UEFI Driver Model. If the device is not\r
+ managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED\r
+ is returned. Once a device context is set, the FmpDeviceLib services\r
+ operate on the currently set device context.\r
+\r
+ @param[in] Handle Device handle for the FmpDeviceLib services.\r
+ If Handle is NULL, then Context is freed.\r
+ @param[in, out] Context Device context for the FmpDeviceLib services.\r
+ If Context is NULL, then a new context is allocated\r
+ for Handle and the current device context is set and\r
+ returned in Context. If Context is not NULL, then\r
+ the current device context is set.\r
+\r
+ @retval EFI_SUCCESS The device is managed by a driver that follows the\r
+ UEFI Driver Model.\r
+ @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
+ the UEFI Driver Model.\r
+ @retval other The Firmware Management Protocol for this firmware\r
+ device is not installed. The firmware device is\r
+ still locked using FmpDeviceLock().\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceSetContext (\r
+ IN EFI_HANDLE Handle,\r
+ IN OUT VOID **Context\r
+ );\r
+\r
/**\r
Returns the size, in bytes, of the firmware image currently stored in the\r
firmware device. This function is used to by the GetImage() and\r
@retval EFI_INVALID_PARAMETER Size is NULL.\r
@retval EFI_UNSUPPORTED The firmware device does not support reporting\r
the size of the currently stored firmware image.\r
- @retval EFI_DEVICE_ERROR An error occured attempting to determine the\r
+ @retval EFI_DEVICE_ERROR An error occurred attempting to determine the\r
size of the firmware image currently stored in\r
in the firmware device.\r
\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetAttributes (\r
- OUT UINT64 *Supported,\r
- OUT UINT64 *Setting\r
+ OUT UINT64 *Supported,\r
+ OUT UINT64 *Setting\r
);\r
\r
/**\r
OUT UINT32 *Version\r
);\r
\r
+/**\r
+ Returns the value used to fill in the HardwareInstance field of the\r
+ EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
+ service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
+ the firmware device supports a method to report the HardwareInstance value.\r
+ If the value can not be reported for the firmware device, then EFI_UNSUPPORTED\r
+ must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting\r
+ to retrieve the HardwareInstance value for the firmware device.\r
+\r
+ @param[out] HardwareInstance The hardware instance value for the firmware\r
+ device.\r
+\r
+ @retval EFI_SUCCESS The hardware instance for the current firmware\r
+ device is returned in HardwareInstance.\r
+ @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
+ report the hardware instance value.\r
+ @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware\r
+ instance value.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceGetHardwareInstance (\r
+ OUT UINT64 *HardwareInstance\r
+ );\r
+\r
/**\r
Returns a copy of the firmware image currently stored in the firmware device.\r
\r
OUT UINT32 *ImageUpdatable\r
);\r
\r
+/**\r
+ Checks if a new firmware image is valid for the firmware device. This\r
+ function allows firmware update operation to validate the firmware image\r
+ before FmpDeviceSetImage() is called.\r
+\r
+ @param[in] Image Points to a new firmware image.\r
+ @param[in] ImageSize Size, in bytes, of a new firmware image.\r
+ @param[out] ImageUpdatable Indicates if a new firmware image is valid for\r
+ a firmware update to the firmware device. The\r
+ following values from the Firmware Management\r
+ Protocol are supported:\r
+ IMAGE_UPDATABLE_VALID\r
+ IMAGE_UPDATABLE_INVALID\r
+ IMAGE_UPDATABLE_INVALID_TYPE\r
+ IMAGE_UPDATABLE_INVALID_OLD\r
+ IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
+ @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
+ status to report back to the ESRT table in case\r
+ of error.\r
+\r
+ The return status code must fall in the range of\r
+ LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+ LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+ If the value falls outside this range, it will be converted\r
+ to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+ @retval EFI_SUCCESS The image was successfully checked. Additional\r
+ status information is returned in\r
+ ImageUpdatable.\r
+ @retval EFI_INVALID_PARAMETER Image is NULL.\r
+ @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceCheckImageWithStatus (\r
+ IN CONST VOID *Image,\r
+ IN UINTN ImageSize,\r
+ OUT UINT32 *ImageUpdatable,\r
+ OUT UINT32 *LastAttemptStatus\r
+ );\r
+\r
/**\r
Updates a firmware device with a new firmware image. This function returns\r
EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
FmpDeviceSetImage (\r
IN CONST VOID *Image,\r
IN UINTN ImageSize,\r
- IN CONST VOID *VendorCode, OPTIONAL\r
- IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL\r
+ IN CONST VOID *VendorCode OPTIONAL,\r
+ IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL,\r
IN UINT32 CapsuleFwVersion,\r
OUT CHAR16 **AbortReason\r
);\r
\r
+/**\r
+ Updates a firmware device with a new firmware image. This function returns\r
+ EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
+ is updatable, the function should perform the following minimal validations\r
+ before proceeding to do the firmware image update.\r
+ - Validate that the image is a supported image for this firmware device.\r
+ Return EFI_ABORTED if the image is not supported. Additional details\r
+ on why the image is not a supported image may be returned in AbortReason.\r
+ - Validate the data from VendorCode if is not NULL. Firmware image\r
+ validation must be performed before VendorCode data validation.\r
+ VendorCode data is ignored or considered invalid if image validation\r
+ fails. Return EFI_ABORTED if the VendorCode data is invalid.\r
+\r
+ VendorCode enables vendor to implement vendor-specific firmware image update\r
+ policy. Null if the caller did not specify the policy or use the default\r
+ policy. As an example, vendor can implement a policy to allow an option to\r
+ force a firmware image update when the abort reason is due to the new firmware\r
+ image version is older than the current firmware image version or bad image\r
+ checksum. Sensitive operations such as those wiping the entire firmware image\r
+ and render the device to be non-functional should be encoded in the image\r
+ itself rather than passed with the VendorCode. AbortReason enables vendor to\r
+ have the option to provide a more detailed description of the abort reason to\r
+ the caller.\r
+\r
+ @param[in] Image Points to the new firmware image.\r
+ @param[in] ImageSize Size, in bytes, of the new firmware image.\r
+ @param[in] VendorCode This enables vendor to implement vendor-specific\r
+ firmware image update policy. NULL indicates\r
+ the caller did not specify the policy or use the\r
+ default policy.\r
+ @param[in] Progress A function used to report the progress of\r
+ updating the firmware device with the new\r
+ firmware image.\r
+ @param[in] CapsuleFwVersion The version of the new firmware image from the\r
+ update capsule that provided the new firmware\r
+ image.\r
+ @param[out] AbortReason A pointer to a pointer to a Null-terminated\r
+ Unicode string providing more details on an\r
+ aborted operation. The buffer is allocated by\r
+ this function with\r
+ EFI_BOOT_SERVICES.AllocatePool(). It is the\r
+ caller's responsibility to free this buffer with\r
+ EFI_BOOT_SERVICES.FreePool().\r
+ @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
+ status to report back to the ESRT table in case\r
+ of error. This value will only be checked when this\r
+ function returns an error.\r
+\r
+ The return status code must fall in the range of\r
+ LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+ LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+ If the value falls outside this range, it will be converted\r
+ to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+ @retval EFI_SUCCESS The firmware device was successfully updated\r
+ with the new firmware image.\r
+ @retval EFI_ABORTED The operation is aborted. Additional details\r
+ are provided in AbortReason.\r
+ @retval EFI_INVALID_PARAMETER The Image was NULL.\r
+ @retval EFI_UNSUPPORTED The operation is not supported.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceSetImageWithStatus (\r
+ IN CONST VOID *Image,\r
+ IN UINTN ImageSize,\r
+ IN CONST VOID *VendorCode OPTIONAL,\r
+ IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress OPTIONAL,\r
+ IN UINT32 CapsuleFwVersion,\r
+ OUT CHAR16 **AbortReason,\r
+ OUT UINT32 *LastAttemptStatus\r
+ );\r
+\r
/**\r
Lock the firmware device that contains a firmware image. Once a firmware\r
device is locked, any attempts to modify the firmware image contents in the\r
projects / mirror_edk2.git / blobdiff