diff --git a/FmpDevicePkg/FmpDevicePkg.dec b/FmpDevicePkg/FmpDevicePkg.dec new file mode 100644 index 0000000000..9ea0d73359 --- /dev/null +++ b/FmpDevicePkg/FmpDevicePkg.dec @@ -0,0 +1,132 @@ +## @file +# Firmware Management Protocol Device Package +# +# This package provides an implementation of a Firmware Management Protocol +# instance that supports the update of firmware storage devices using UEFI +# Capsules. The behavior of the Firmware Management Protocol instance is +# customized using libraries and PCDs. +# +# Copyright (c) 2016, Microsoft Corporation. All rights reserved.
+# Copyright (c) 2018, Intel Corporation. All rights reserved.
+# +# 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. +# +## + +[Defines] + DEC_SPECIFICATION = 0x00010005 + PACKAGE_NAME = FmpDevicePkg + PACKAGE_UNI_FILE = FmpDevicePkg.uni + PACKAGE_GUID = 080b5b4f-27c6-11e8-84d1-f8597177a00a + PACKAGE_VERSION = 0.1 + +[Includes] + Include + +[LibraryClasses] + ## @libraryclass 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. + FmpPayloadHeaderLib|Include/Library/FmpPayloadHeaderLib.h + + ## @libraryclass Provides platform policy services used during a capsule + # update. + CapsuleUpdatePolicyLib|Include/Library/CapsuleUpdatePolicyLib.h + + ## @libraryclass Provides firmware device specific services to support + # updates of a firmware image stored in a firmware device. + FmpDeviceLib|Include/Library/FmpDeviceLib.h + +[Guids] + ## Firmware Management Protocol Device Package Token Space GUID + gFmpDevicePkgTokenSpaceGuid = { 0x40b2d964, 0xfe11, 0x40dc, { 0x82, 0x83, 0x2e, 0xfb, 0xda, 0x29, 0x53, 0x56 } } + +[PcdsFixedAtBuild] + ## Indicates if a full system reset is required before a firmware update to a + # firmware devices takes effect.

+ # TRUE - System reset is required.
+ # FALSE - System reset is not required.
+ # @Prompt FMP Device System Reset Required. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceSystemResetRequired|TRUE|BOOLEAN|0x40000008 + + ## The SHA-256 hash of a PKCS7 test key that is used to detect if a test key + # is being used to authenticate capsules. Test key detection is disabled by + # setting the value to {0}. + # @Prompt SHA-256 hash of PKCS7 test key. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceTestKeySha256Digest|{0x2E, 0x97, 0x89, 0x1B, 0xDB, 0xE7, 0x08, 0xAA, 0x8C, 0xB2, 0x8F, 0xAD, 0x20, 0xA9, 0x83, 0xC7, 0x84, 0x7D, 0x4F, 0xEE, 0x48, 0x25, 0xE9, 0x4D, 0x39, 0xFA, 0x34, 0x9A, 0xB8, 0xB1, 0xC4, 0x26}|VOID*|0x40000009 + +[PcdsFixedAtBuild, PcdsPatchableInModule] + ## The color of the progress bar during a firmware update. Each firmware + # device can set its own color. The default color is white.

+ # Bits 7..0 - Red
+ # Bits 15..8 - Green
+ # Bits 23..16 - Blue
+ # @Prompt Firmware Device Progress Bar Color. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceProgressColor|0x00FFFFFF|UINT32|0x40000004 + + ## The Null-terminated Unicode string used to fill in the ImageIdName field of + # the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the + # GetImageInfo() service of the Firmware Management Protocol for the firmware + # device. An ImageIdName string must be provided for each firmware device. + # The default value is an empty string. + # @Prompt Firmware Device ImageIdName string. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceImageIdName|L""|VOID*|0x40000007 + + ## The build time 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. This value is + # only used if the firmware device does not provide a method to report the + # lowest supported version value from the current firmware image and the + # UEFI variable used to provide the lowest supported version value does not + # exist. The default value is 0. + # @Prompt Build Time Firmware Device Lowest Support Version. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceBuildTimeLowestSupportedVersion|0x0|UINT32|0x4000000C + + ## The time in seconds to arm a watchdog timer during the update of a firmware + # device. The watchdog is re-armed each time the FmpDeviceLib calls the + # Progress() function passed into FmpDeviceSetImage() function. The + # FmpDeviceLib calls Progress() to update the percent completion of a + # firmware update. If the watchdog timer expires, the system reboots. A + # value of 0 disables the watchdog timer. The default value is 0 (watchdog + # disabled). + # @Prompt Firmware Device Watchdog Time in Seconds. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceProgressWatchdogTimeInSeconds|0x0|UINT8|0x4000000D + +[PcdsFixedAtBuild, PcdsPatchableInModule, PcdsDynamic, PcdsDynamicEx] + ## One or more PKCS7 certificates used to verify a firmware device capsule + # update image. Encoded using the Variable-Length Opaque Data format of RFC + # 4506 External Data Representation Standard (XDR). The default value is + # empty with 0 certificates. + # @Prompt One or more XDR encoded PKCS7 certificates used to verify firmware device capsule update images. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDevicePkcs7CertBufferXdr|{0x0}|VOID*|0x4000000E + + ## An event GUID that locks the firmware device when the event is signaled. + # If this PCD is not a valid GUID value, then the firmware device is locked + # when gEfiEndOfDxeEventGroupGuid (End of DXE Phase) is signaled. The + # default value is empty, so by default the firmware device is locked at the + # end of the DXE phase. + # @Prompt Firmware Device Lock Event GUID. + gFmpDevicePkgTokenSpaceGuid.PcdFmpDeviceLockEventGuid|{0}|VOID*|0x4000000F + +[UserExtensions.TianoCore."ExtraFiles"] + FmpDevicePkgExtra.uni diff --git a/FmpDevicePkg/FmpDevicePkg.uni b/FmpDevicePkg/FmpDevicePkg.uni new file mode 100644 index 0000000000..da31d0ac81 --- /dev/null +++ b/FmpDevicePkg/FmpDevicePkg.uni @@ -0,0 +1,80 @@ +// /** @file +// Firmware Management Protocol Device Package +// +// This package provides an implementation of a Firmware Management Protocol +// instance that supports the update of firmware storage devices using UEFI +// Capsules. The behavior of the Firmware Management Protocol instance is +// customized using libraries and PCDs. +// +// Copyright (c) 2018, Intel Corporation. All rights reserved.
+// +// This program and the accompanying materials are licensed and made available under +// the terms and conditions of the BSD License which accompanies this distribution. +// The full text of the license may be found at +// http://opensource.org/licenses/bsd-license.php +// +// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +// +// **/ + +#string STR_PACKAGE_ABSTRACT #language en-US "Firmware Management Protocol Software Development Kit" + +#string STR_PACKAGE_DESCRIPTION #language en-US "This package provides libraries that support the implementation of a module that produces the Firmware Management Protocol to support the update of a system firmware component." + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceSystemResetRequired_PROMPT #language en-US "FMP Device System Reset Required." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceSystemResetRequired_HELP #language en-US "Indicates if a full system reset is required before a firmware update to a firmware device takes effect.

\n" + "TRUE - System reset is required.
\n" + "FALSE - System reset is not required.
" + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceTestKeySha256Digest_PROMPT #language en-US "SHA-256 hash of PKCS7 test key." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceTestKeySha256Digest_HELP #language en-US "The SHA-256 hash of a PKCS7 test key that is used to detect if a test key" + "is being used to authenticate capsules. Test key detection can be disabled" + "by setting the value to {0}" + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceProgressColor_PROMPT #language en-US "Firmware Device Progress Bar Color." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceProgressColor_HELP #language en-US "The color of the progress bar during a firmware update. Each firmware" + "device can set its own color. The default color is white.

\n" + "Bits 7..0 - Red
\n" + "Bits 15..8 - Green
\n" + "Bits 23..16 - Blue
\n" + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceImageIdName_PROMPT #language en-US "Firmware Device ImageIdName string." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceImageIdName_HELP #language en-US "The Null-terminated Unicode string used to fill in the ImageIdName field of" + "the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the" + "GetImageInfo() service of the Firmware Management Protocol for the firmware" + "device. An ImageIdName string must be provided for each firmware device." + "The default value is an empty string." + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceBuildTimeLowestSupportedVersion_PROMPT #language en-US "Build Time Firmware Device Lowest Support Version." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceBuildTimeLowestSupportedVersion_HELP #language en-US "The build time 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. This value is" + "only used if the firmware device does not provide a method to report the" + "lowest supported version value from the current firmware image and the" + "UEFI variable used to provide the lowest supported version value does not" + "exist. The default value is 0." + +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceProgressWatchdogTimeInSeconds_PROMPT #language en-US "Firmware Device Watchdog Time in Seconds." +#string STR_gFmpDevicePkgTokenSpaceGuid_PcdFmpDeviceProgressWatchdogTimeInSeconds_HELP #language en-US "Indicates the time in seconds to arm a watchdog timer during the update of" + "a firmware device. The watchdog is re-armed each time the FmpDeviceLib" + "calls the Progress() function passed into FmpDeviceSetImage() function." + "The FmpDeviceLib calls Progress() to update the percent completion of a" + "firmware update. If the watchdog timer expires, the system reboots. A" + "value of 0 disables the watchdog timer. The default value is 0 (watchdog" + "disabled)." + +#string STR_gEfiSecurityPkgTokenSpaceGuid_PcdFmpDevicePkcs7CertBufferXdr_PROMPT #language en-US "One or more XDR encoded PKCS7 certificates used to verify firmware device capsule update images" +#string STR_gEfiSecurityPkgTokenSpaceGuid_PcdFmpDevicePkcs7CertBufferXdr_HELP #language en-US "Provides one or more PKCS7 certificates used to verify a firmware device" + "capsule update image. This PCD is encoded using the Variable-Length Opaque" + "Data format of RFC 4506 External Data Representation Standard (XDR)." + "The default value is empty with 0 certificates." + +#string STR_gEfiSecurityPkgTokenSpaceGuid_PcdFmpDeviceLockEventGuid_PROMPT #language en-US "Firmware Device Lock Event GUID." +#string STR_gEfiSecurityPkgTokenSpaceGuid_PcdFmpDeviceLockEventGuid_HELP #language en-US "An event GUID that locks the firmware device when the event is signaled." + "If this PCD is not a valid GUID value, then the firmware device is locked" + "when gEfiEndOfDxeEventGroupGuid (End of DXE Phase) is signaled. The" + "default value is empty, so by default the firmware device is locked at the" + "end of the DXE phase." + + diff --git a/FmpDevicePkg/FmpDevicePkgExtra.uni b/FmpDevicePkg/FmpDevicePkgExtra.uni new file mode 100644 index 0000000000..fe49e8cd6c --- /dev/null +++ b/FmpDevicePkg/FmpDevicePkgExtra.uni @@ -0,0 +1,18 @@ +// /** @file +// Firmware Management Protocol Device Package Localized Strings and Content. +// +// Copyright (c) 2018, Intel Corporation. All rights reserved.
+// +// This program and the accompanying materials are licensed and made available under +// the terms and conditions of the BSD License which accompanies this distribution. +// The full text of the license may be found at +// http://opensource.org/licenses/bsd-license.php +// +// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +// +// **/ + +#string STR_PROPERTIES_PACKAGE_NAME +#language en-US +"Firmware Management Protocol Device package" diff --git a/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h b/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h new file mode 100644 index 0000000000..acd3ce5bf5 --- /dev/null +++ b/FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h @@ -0,0 +1,120 @@ +/** @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.
+ + 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 __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 ( + IN 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 ( + IN 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/FmpDevicePkg/Include/Library/FmpDeviceLib.h b/FmpDevicePkg/Include/Library/FmpDeviceLib.h new file mode 100644 index 0000000000..08125f0096 --- /dev/null +++ b/FmpDevicePkg/Include/Library/FmpDeviceLib.h @@ -0,0 +1,405 @@ +/** @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, Intel Corporation. All rights reserved.
+ + 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 + +/** + 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 ( + IN OUT UINT64 *Supported, + IN 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 ( + IN OUT VOID *Image, + IN 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 + ImageUpdateable. + @retval EFI_INVALID_PARAMETER Image is NULL. + @retval EFI_INVALID_PARAMETER ImageUpdateable is NULL. + +**/ +EFI_STATUS +EFIAPI +FmpDeviceCheckImage ( + IN CONST VOID *Image, + IN UINTN ImageSize, + OUT UINT32 *ImageUpdateable + ); + +/** + 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 diff --git a/FmpDevicePkg/Include/Library/FmpPayloadHeaderLib.h b/FmpDevicePkg/Include/Library/FmpPayloadHeaderLib.h new file mode 100644 index 0000000000..cb5622e9ce --- /dev/null +++ b/FmpDevicePkg/Include/Library/FmpPayloadHeaderLib.h @@ -0,0 +1,100 @@ +/** @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.
+ + 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_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, + IN OUT UINT32 *LowestSupportedVersion + ); + +#endif