From af1a266670d040d2f4083ff309d732d648afba2a Mon Sep 17 00:00:00 2001 From: Angelos Mouzakitis Date: Tue, 10 Oct 2023 14:33:42 +0000 Subject: Add submodule dependency files Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec --- .../Include/Library/CapsuleUpdatePolicyLib.h | 103 +++++ .../Include/Library/FmpDependencyCheckLib.h | 38 ++ .../Include/Library/FmpDependencyDeviceLib.h | 51 +++ .../Include/Library/FmpDependencyLib.h | 90 ++++ .../FmpDevicePkg/Include/Library/FmpDeviceLib.h | 490 +++++++++++++++++++++ 5 files changed, 772 insertions(+) create mode 100644 roms/edk2/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h create mode 100644 roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyCheckLib.h create mode 100644 roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyDeviceLib.h create mode 100644 roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyLib.h create mode 100644 roms/edk2/FmpDevicePkg/Include/Library/FmpDeviceLib.h (limited to 'roms/edk2/FmpDevicePkg/Include') diff --git a/roms/edk2/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h b/roms/edk2/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h new file mode 100644 index 000000000..5ec4d487e --- /dev/null +++ b/roms/edk2/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h @@ -0,0 +1,103 @@ +/** @file + Provides platform policy services used during a capsule update. + + Copyright (c) 2016, Microsoft Corporation. All rights reserved.
+ Copyright (c) 2018, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __CAPSULE_UPDATE_POLICY_LIB__ +#define __CAPSULE_UPDATE_POLICY_LIB__ + +/** + Determine if the system power state supports a capsule update. + + @param[out] Good Returns TRUE if system power state supports a capsule + update. Returns FALSE if system power state does not + support a capsule update. Return value is only valid if + return status is EFI_SUCCESS. + + @retval EFI_SUCCESS Good parameter has been updated with result. + @retval EFI_INVALID_PARAMETER Good is NULL. + @retval EFI_DEVICE_ERROR System power state can not be determined. + +**/ +EFI_STATUS +EFIAPI +CheckSystemPower ( + OUT BOOLEAN *Good + ); + +/** + Determines if the system thermal state supports a capsule update. + + @param[out] Good Returns TRUE if system thermal state supports a capsule + update. Returns FALSE if system thermal state does not + support a capsule update. Return value is only valid if + return status is EFI_SUCCESS. + + @retval EFI_SUCCESS Good parameter has been updated with result. + @retval EFI_INVALID_PARAMETER Good is NULL. + @retval EFI_DEVICE_ERROR System thermal state can not be determined. + +**/ +EFI_STATUS +EFIAPI +CheckSystemThermal ( + OUT BOOLEAN *Good + ); + +/** + Determines if the system environment state supports a capsule update. + + @param[out] Good Returns TRUE if system environment state supports a capsule + update. Returns FALSE if system environment state does not + support a capsule update. Return value is only valid if + return status is EFI_SUCCESS. + + @retval EFI_SUCCESS Good parameter has been updated with result. + @retval EFI_INVALID_PARAMETER Good is NULL. + @retval EFI_DEVICE_ERROR System environment state can not be determined. + +**/ +EFI_STATUS +EFIAPI +CheckSystemEnvironment ( + OUT BOOLEAN *Good + ); + +/** + Determines if the Lowest Supported Version checks should be performed. The + expected result from this function is TRUE. A platform can choose to return + FALSE (e.g. during manufacturing or servicing) to allow a capsule update to a + version below the current Lowest Supported Version. + + @retval TRUE The lowest supported version check is required. + @retval FALSE Do not perform lowest support version check. + +**/ +BOOLEAN +EFIAPI +IsLowestSupportedVersionCheckRequired ( + VOID + ); + +/** + Determines if the FMP device should be locked when the event specified by + PcdFmpDeviceLockEventGuid is signaled. The expected result from this function + is TRUE so the FMP device is always locked. A platform can choose to return + FALSE (e.g. during manufacturing) to allow FMP devices to remain unlocked. + + @retval TRUE The FMP device lock action is required at lock event guid. + @retval FALSE Do not perform FMP device lock at lock event guid. + +**/ +BOOLEAN +EFIAPI +IsLockFmpDeviceAtLockEventGuidRequired ( + VOID + ); + +#endif diff --git a/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyCheckLib.h b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyCheckLib.h new file mode 100644 index 000000000..ec380c494 --- /dev/null +++ b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyCheckLib.h @@ -0,0 +1,38 @@ +/** @file + Fmp Capsule Dependency check functions for Firmware Management Protocol based + firmware updates. + + Copyright (c) 2020, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __FMP_DEPENDENCY_CHECK_LIB__ +#define __FMP_DEPENDENCY_CHECK_LIB__ + +#include +#include + +/** + Check dependency for firmware update. + + @param[in] ImageTypeId Image Type Id. + @param[in] Version New version. + @param[in] Dependencies Fmp dependency. + @param[in] DependenciesSize Size, in bytes, of the Fmp dependency. + + @retval TRUE Dependencies are satisfied. + @retval FALSE Dependencies are unsatisfied or dependency check fails. + +**/ +BOOLEAN +EFIAPI +CheckFmpDependency ( + IN EFI_GUID ImageTypeId, + IN UINT32 Version, + IN EFI_FIRMWARE_IMAGE_DEP *Dependencies, OPTIONAL + IN UINT32 DependenciesSize + ); + +#endif diff --git a/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyDeviceLib.h b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyDeviceLib.h new file mode 100644 index 000000000..4351173b7 --- /dev/null +++ b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyDeviceLib.h @@ -0,0 +1,51 @@ +/** @file + Provides firmware device specific services to support saving dependency to + firmware device and getting dependency from firmware device. + + Copyright (c) 2020, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __FMP_DEPENDENCY_DEVICE_LIB__ +#define __FMP_DEPENDENCY_DEVICE_LIB__ + +#include +#include + +/** + Save dependency to Fmp device. + + @param[in] Depex Fmp dependency. + @param[in] DepexSize Size, in bytes, of the Fmp dependency. + + @retval EFI_SUCCESS Save Fmp dependency succeeds. + @retval EFI_UNSUPPORTED Save Fmp dependency is not supported. + @retval Others Save Fmp dependency fails. + +**/ +EFI_STATUS +EFIAPI +SaveFmpDependency ( + IN EFI_FIRMWARE_IMAGE_DEP *Depex, + IN UINT32 DepexSize + ); + +/** + Get dependency from the Fmp device. + This caller is responsible for freeing the dependency buffer. + + @param[out] DepexSize Size, in bytes, of the dependency. + + @retval The pointer to dependency. + @retval NULL + +**/ +EFI_FIRMWARE_IMAGE_DEP* +EFIAPI +GetFmpDependency ( + OUT UINT32 *DepexSize + ); + +#endif diff --git a/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyLib.h b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyLib.h new file mode 100644 index 000000000..c73290342 --- /dev/null +++ b/roms/edk2/FmpDevicePkg/Include/Library/FmpDependencyLib.h @@ -0,0 +1,90 @@ +/** @file + Fmp Capsule Dependency support functions for Firmware Management Protocol based + firmware updates. + + Copyright (c) Microsoft Corporation.
+ Copyright (c) 2020, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __FMP_DEPENDENCY_LIB__ +#define __FMP_DEPENDENCY_LIB__ + +#include +#include + +// +// Data struct to store FMP ImageType and version for dependency check. +// +typedef struct { + EFI_GUID ImageTypeId; + UINT32 Version; +} FMP_DEPEX_CHECK_VERSION_DATA; + +/** + Validate the dependency expression and output its size. + + @param[in] Dependencies Pointer to the EFI_FIRMWARE_IMAGE_DEP. + @param[in] MaxDepexSize Max size of the dependency. + @param[out] DepexSize Size of dependency. + + @retval TRUE The dependency expression is valid. + @retval FALSE The dependency expression is invalid. + +**/ +BOOLEAN +EFIAPI +ValidateDependency ( + IN EFI_FIRMWARE_IMAGE_DEP *Dependencies, + IN UINTN MaxDepexSize, + OUT UINT32 *DepexSize + ); + +/** + Get dependency from firmware image. + + @param[in] Image Points to the firmware image. + @param[in] ImageSize Size, in bytes, of the firmware image. + @param[out] DepexSize Size, in bytes, of the dependency. + + @retval The pointer to dependency. + @retval Null + +**/ +EFI_FIRMWARE_IMAGE_DEP* +EFIAPI +GetImageDependency ( + IN EFI_FIRMWARE_IMAGE_AUTHENTICATION *Image, + IN UINTN ImageSize, + OUT UINT32 *DepexSize + ); + +/** + Evaluate the dependencies. The caller must search all the Fmp instances and + gather their versions into FmpVersions parameter. If there is PUSH_GUID opcode + in dependency expression with no FmpVersions provided, the dependency will + evaluate to FALSE. + + @param[in] Dependencies Dependency expressions. + @param[in] DependenciesSize Size of Dependency expressions. + @param[in] FmpVersions Array of Fmp ImageTypeId and version. This + parameter is optional and can be set to NULL. + @param[in] FmpVersionsCount Element count of the array. When FmpVersions + is NULL, FmpVersionsCount must be 0. + + @retval TRUE Dependency expressions evaluate to TRUE. + @retval FALSE Dependency expressions evaluate to FALSE. + +**/ +BOOLEAN +EFIAPI +EvaluateDependency ( + IN EFI_FIRMWARE_IMAGE_DEP *Dependencies, + IN UINTN DependenciesSize, + IN FMP_DEPEX_CHECK_VERSION_DATA *FmpVersions OPTIONAL, + IN UINTN FmpVersionsCount + ); + +#endif diff --git a/roms/edk2/FmpDevicePkg/Include/Library/FmpDeviceLib.h b/roms/edk2/FmpDevicePkg/Include/Library/FmpDeviceLib.h new file mode 100644 index 000000000..9a89f5c2e --- /dev/null +++ b/roms/edk2/FmpDevicePkg/Include/Library/FmpDeviceLib.h @@ -0,0 +1,490 @@ +/** @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.
+ Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __FMP_DEVICE_LIB__ +#define __FMP_DEVICE_LIB__ + +#include + +/** + 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. FmpUninstaller 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 + device 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 -- cgit 1.2.3-korg