diff options
Diffstat (limited to 'FmpDevicePkg')
| -rw-r--r-- | FmpDevicePkg/FmpDevicePkg.dec | 132 | ||||
| -rw-r--r-- | FmpDevicePkg/FmpDevicePkg.uni | 80 | ||||
| -rw-r--r-- | FmpDevicePkg/FmpDevicePkgExtra.uni | 18 | ||||
| -rw-r--r-- | FmpDevicePkg/Include/Library/CapsuleUpdatePolicyLib.h | 120 | ||||
| -rw-r--r-- | FmpDevicePkg/Include/Library/FmpDeviceLib.h | 405 | ||||
| -rw-r--r-- | FmpDevicePkg/Include/Library/FmpPayloadHeaderLib.h | 100 |
6 files changed, 855 insertions, 0 deletions
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.<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.
+#
+##
+
+[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.<BR><BR>
+ # TRUE - System reset is required.<BR>
+ # FALSE - System reset is not required.<BR>
+ # @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.<BR><BR>
+ # Bits 7..0 - Red<BR>
+ # Bits 15..8 - Green<BR>
+ # Bits 23..16 - Blue<BR>
+ # @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.<BR>
+//
+// 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.<BR><BR>\n"
+ "TRUE - System reset is required.<BR>\n"
+ "FALSE - System reset is not required.<BR>"
+
+#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.<BR><BR>\n"
+ "Bits 7..0 - Red<BR>\n"
+ "Bits 15..8 - Green<BR>\n"
+ "Bits 23..16 - Blue<BR>\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.<BR>
+//
+// 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.<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 __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.<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 (
+ 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.<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_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
|