From c40f7cc7fd75e5fff9915ceedb1c10584c98e581 Mon Sep 17 00:00:00 2001 From: Eric Jin Date: Sun, 11 Aug 2019 13:36:46 +0800 Subject: FmpDevicePkg: Add Capsule Update Policy Protocol REF: https://bugzilla.tianocore.org/show_bug.cgi?id=1525 * Add Capsule Update Policy Protocol to FmpDevicePkg * Add CapsuleUpdatePolicyLib instance that uses the services of the Capsule Update Policy Protocol * Add module that produces the Capsule Update Policy Protocol using the services of the CapsuleUpdatePolicyLib class. * Update FmpDevicePkg DSC to build the new library instance and the new module and update builds of FmpDxe modules to demonstrate the use of the different CapsuleUpdatePolicyLib instances. Cc: Sean Brogan Cc: Bret Barkelew Cc: Liming Gao Signed-off-by: Michael D Kinney Signed-off-by: Wang Fan Reviewed-by: Eric Jin Reviewed-by: Liming Gao --- .../PrivateInclude/Library/FmpPayloadHeaderLib.h | 83 +++++++++++++ .../PrivateInclude/Protocol/CapsuleUpdatePolicy.h | 132 +++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 FmpDevicePkg/PrivateInclude/Library/FmpPayloadHeaderLib.h create mode 100644 FmpDevicePkg/PrivateInclude/Protocol/CapsuleUpdatePolicy.h (limited to 'FmpDevicePkg/PrivateInclude') diff --git a/FmpDevicePkg/PrivateInclude/Library/FmpPayloadHeaderLib.h b/FmpDevicePkg/PrivateInclude/Library/FmpPayloadHeaderLib.h new file mode 100644 index 0000000000..24afd5e299 --- /dev/null +++ b/FmpDevicePkg/PrivateInclude/Library/FmpPayloadHeaderLib.h @@ -0,0 +1,83 @@ +/** @file + Provides services to retrieve values from a capsule's FMP Payload Header. + The structure is not included in the library class. Instead, services are + provided to retrieve information from the FMP Payload Header. If information + is added to the FMP Payload Header, then new services may be added to this + library class to retrieve the new information. + + Copyright (c) 2016, Microsoft Corporation. All rights reserved.
+ Copyright (c) 2018, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _FMP_PAYLOAD_HEADER_LIB_H__ +#define _FMP_PAYLOAD_HEADER_LIB_H__ + +/** + Returns the FMP Payload Header size in bytes. + + @param[in] Header FMP Payload Header to evaluate + @param[in] FmpPayloadSize Size of FMP payload + @param[out] Size The size, in bytes, of the FMP Payload Header. + + @retval EFI_SUCCESS The firmware version was returned. + @retval EFI_INVALID_PARAMETER Header is NULL. + @retval EFI_INVALID_PARAMETER Size is NULL. + @retval EFI_INVALID_PARAMETER Header is not a valid FMP Payload Header. + +**/ +EFI_STATUS +EFIAPI +GetFmpPayloadHeaderSize ( + IN CONST VOID *Header, + IN CONST UINTN FmpPayloadSize, + OUT UINT32 *Size + ); + +/** + Returns the version described in the FMP Payload Header. + + @param[in] Header FMP Payload Header to evaluate + @param[in] FmpPayloadSize Size of FMP payload + @param[out] Version The firmware version described in the FMP Payload + Header. + + @retval EFI_SUCCESS The firmware version was returned. + @retval EFI_INVALID_PARAMETER Header is NULL. + @retval EFI_INVALID_PARAMETER Version is NULL. + @retval EFI_INVALID_PARAMETER Header is not a valid FMP Payload Header. + +**/ +EFI_STATUS +EFIAPI +GetFmpPayloadHeaderVersion ( + IN CONST VOID *Header, + IN CONST UINTN FmpPayloadSize, + OUT UINT32 *Version + ); + +/** + Returns the lowest supported version described in the FMP Payload Header. + + @param[in] Header FMP Payload Header to evaluate + @param[in] FmpPayloadSize Size of FMP payload + @param[out] LowestSupportedVersion The lowest supported version described in + the FMP Payload Header. + + @retval EFI_SUCCESS The lowest support version was returned. + @retval EFI_INVALID_PARAMETER Header is NULL. + @retval EFI_INVALID_PARAMETER LowestSupportedVersion is NULL. + @retval EFI_INVALID_PARAMETER Header is not a valid FMP Payload Header. + +**/ +EFI_STATUS +EFIAPI +GetFmpPayloadHeaderLowestSupportedVersion ( + IN CONST VOID *Header, + IN CONST UINTN FmpPayloadSize, + OUT UINT32 *LowestSupportedVersion + ); + +#endif diff --git a/FmpDevicePkg/PrivateInclude/Protocol/CapsuleUpdatePolicy.h b/FmpDevicePkg/PrivateInclude/Protocol/CapsuleUpdatePolicy.h new file mode 100644 index 0000000000..871f0a1854 --- /dev/null +++ b/FmpDevicePkg/PrivateInclude/Protocol/CapsuleUpdatePolicy.h @@ -0,0 +1,132 @@ +/** @file + Provides platform policy services used during a capsule update. + + Copyright (c) 2019, Intel Corporation. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __CAPSULE_UPDATE_POLICY_H__ +#define __CAPSULE_UPDATE_POLICY_H__ + +#define EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL_GUID \ + { \ + 0x487784c5, 0x6299, 0x4ba6, { 0xb0, 0x96, 0x5c, 0xc5, 0x27, 0x7c, 0xf7, 0x57 } \ + } + +typedef struct _EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL; + +/** + Determine if the system power state supports a capsule update. + + @param[in] This A pointer to the EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL instance. + @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. + +**/ +typedef +EFI_STATUS +(EFIAPI * EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_POWER) ( + IN EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL *This, + OUT BOOLEAN *Good + ); + +/** + Determines if the system thermal state supports a capsule update. + + @param[in] This A pointer to the EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL instance. + @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. + +**/ +typedef +EFI_STATUS +(EFIAPI * EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_THERMAL) ( + IN EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL *This, + OUT BOOLEAN *Good + ); + +/** + Determines if the system environment state supports a capsule update. + + @param[in] This A pointer to the EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL instance. + @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. + +**/ +typedef +EFI_STATUS +(EFIAPI * EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_ENVIRONMENT) ( + IN EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL *This, + 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. + + @param[in] This A pointer to the EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL instance. + + @retval TRUE The lowest supported version check is required. + @retval FALSE Do not perform lowest support version check. + +**/ +typedef +BOOLEAN +(EFIAPI * EDKII_CAPSULE_UPDATE_POLICY_IS_LOWEST_SUPPORTED_VERSION_CHECK_REQUIRED) ( + IN EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL *This + ); + +/** + 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. + + @param[in] This A pointer to the EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL instance. + + @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. + +**/ +typedef +BOOLEAN +(EFIAPI * EDKII_CAPSULE_UPDATE_POLICY_IS_FMP_DEVICE_AT_LOCK_EVENT_REQUIRED) ( + IN EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL *This + ); + +/// +/// This protocol provides platform policy services used during a capsule update. +/// +struct _EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL { + EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_POWER CheckSystemPower; + EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_THERMAL CheckSystemThermal; + EDKII_CAPSULE_UPDATE_POLICY_CHECK_SYSTEM_ENVIRONMENT CheckSystemEnvironment; + EDKII_CAPSULE_UPDATE_POLICY_IS_LOWEST_SUPPORTED_VERSION_CHECK_REQUIRED IsLowestSupportedVersionCheckRequired; + EDKII_CAPSULE_UPDATE_POLICY_IS_FMP_DEVICE_AT_LOCK_EVENT_REQUIRED IsLockFmpDeviceAtLockEventGuidRequired; +}; + +extern EFI_GUID gEdkiiCapuleUpdatePolicyProtocolGuid; + +#endif -- cgit v1.2.3