Merged PR 3041: FmpDevicePkg: Improve library documentation

Adds a ReadMe.md to each library instance and updates
FmpDevicePkg_ReadMe.md to reference available library
documentation.

FmpDevicePkg/CapsuleUpdatePolicyDxe/ReadMe.md

@@ -0,0 +1,11 @@
+# Capsule Update Policy DXE
+
+## About
+
+This DXE driver produces the Capsule Update Policy Protocol (`EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL`). The policy
+functions wrap around the corresponding functions provided in the `CapsuleUpdatePolicyLib` linked against the driver.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Docs/FmpDevicePkg_ReadMe.md

@@ -0,0 +1,85 @@
+# Firmware Management Protocol (FMP) Device Package
+
+FmpDevicePkg provides the common resources necessary to manage the firmware on a given device. The
+[UEFI Specification](https://uefi.org/specifications) defines several elements used in the firmware management process
+that are implemented or depended upon in FmpDevicePkg such as:
+
+1. `EFI_FIRMWARE_MANAGEMENT_PROTOCOL`
+2. Firmware Management Protocol dependency expression support
+3. FMP capsule format
+4. EFI System Resource Table (ESRT)
+
+## Package Organization
+
+This section briefly describes the package modules and libraries.
+
+### Modules
+
+1. **CapsuleUpdatePolicyDxe** [readme](../CapsuleUpdatePolicyDxe/ReadMe.md)
+   * **Purpose:** \
+   Produces the Capsule Update Policy Protocol using the services of the Capsule Update Policy Library.
+2. **FmpDxe** [readme](../FmpDxe/ReadMe.md)
+   * **Purpose:** \
+   Produces an instance of the Firmware Management Protocol (`EFI_FIRMWARE_MANAGEMENT_PROTOCOL`) that is used
+   to support updates to a firmware image stored on a firmware device
+
+### Libraries
+
+1. **CapsuleUpdatePolicyLib**
+   * **Purpose:** \
+   Provides platform policy services used during a capsule update.
+
+    1. **CapsuleUpdatePolicyLibNull** [readme](../Library/CapsuleUpdatePolicyLibNull/ReadMe.md)
+    2. **CapsuleUpdatePolicyLibOnProtocol** [readme](../Library/CapsuleUpdatePolicyLibOnProtocol/ReadMe.md)
+2. **FmpDependencyCheckLib**
+   * **Purpose:** \
+   Provides services to check that capsule dependencies are met during firmware update.
+
+    1. **FmpDependencyCheckLib** [readme](../Library/FmpDependencyCheckLib/ReadMe.md)
+    2. **FmpDependencyCheckLibNull** [readme](../Library/FmpDependencyCheckLibNull/ReadMe.md)
+3. **FmpDependencyDeviceLib**
+   * **Purpose:** \
+   Provides firmware device specific services to support saving dependency expressions to a firmware device and
+   getting dependency expressions from a firmware device.
+
+    1. **FmpDependencyDeviceLibNull** [readme](../Library/FmpDependencyDeviceLibNull/ReadMe.md)
+4. **FmpDependencyLib**
+   * **Purpose:** \
+   Provides functions used to manage dependencies between firmware components during the update of device firmware
+   images.
+
+    1. **FmpDependencyLib** [readme](../Library/FmpDependencyLib/ReadMe.md)
+5. **FmpDeviceLib**
+   * **Purpose:** \
+   Provides firmware device specific services to support firmware updates on a given device.
+
+    1. **FmpDeviceLibNull** [readme](../Library/FmpDeviceLibNull/ReadMe.md)
+6. **FmpPayloadHeaderLib**
+   * **Purpose:** \
+   Provides services to retrieve values from a capsule FMP Payload Header.
+
+    1. **FmpPayloadHeaderLibV1** [readme](../Library/FmpPayloadHeaderLibV1/ReadMe.md)
+
+## Further Reading
+
+Several documents describe important elements involved in understanding `FmpDevicePkg`. Consult the following
+resource for more information on a particular topic.
+
+1. `FmpDevicePkg` Overview
+    1. The ReadMe documents referenced above that reside in the package.
+    2. [Tianocore wiki: FmpDevicePkg](https://github.com/tianocore/tianocore.github.io/wiki/FmpDevicePkg)
+
+2. UEFI Specification Definitions for Firmware Updating and Reporting
+    1. [Section 23 of the UEFI Specification 2.8B](https://uefi.org/specifications)
+
+3. Technical Overview of the EDK II Capsule Update and Recovery Flow
+    1. [A Tour Beyond BIOS - Capsule Update and Recovery in EDK II](https://github.com/tianocore-docs/Docs/blob/master/White_Papers/A_Tour_Beyond_BIOS_Capsule_Update_and_Recovery_in_EDK_II.pdf)
+
+4. Windows UEFI Firmware Update Resources
+    1. [Windows UEFI Firmware Update Platform](https://docs.microsoft.com/en-us/windows-hardware/drivers/bringup/windows-uefi-firmware-update-platform)
+    2. [Validating Windows UEFI Firmware Update Platform Functionality](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/validating-windows-uefi-firmware-update-platform-functionality)
+
+5. NIST Guidelines for Authenticated Firmware Update
+    1. [SP800-147](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-147.pdf)
+    2. [SP800-147B](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-147B.pdf)
+    3. [SP800-193](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf)

FmpDevicePkg/FmpDxe/ReadMe.md

@@ -0,0 +1,111 @@
+# Firmware Management Protocol (FMP) DXE
+
+## About
+
+This driver produces an instance of the Firmware Management Protocol (`EFI_FIRMWARE_MANAGEMENT_PROTOCOL`) that is used
+to support updates to a firmware image stored on a firmware device. Platform-specific information and customization
+is configured through libraries and PCDs.
+
+---
+
+## Getting Started
+
+This driver integrates several customization points that need to be considered during firmware update. This section
+provides brief background on key elements to consider when adapting this driver for a platform firmware.
+
+### Capsule Authentication
+
+The firmware update capsule must be signed and this driver will verify the integrity of the capsule contents. The
+actual capsule data is preceded by an `EFI_FIRMWARE_IMAGE_AUTHENTICATION` structure. This structure contains a
+monotonic count and a `WIN_CERTIFICATE_UEFI_GUID` member that contains a signature that covers both the monotonic
+count and the capsule payload data. These two elements ensure replay protection across update operations and
+authentication. The certificate type used must be `EFI_CERT_TYPE_PKCS7_GUID`.
+
+An EDK II implementation of signature verification is available in the following `FmpAuthenticationLib` instance:
+[SecurityPkg/Library/FmpAuthenticationLibPkcs7](https://github.com/tianocore/edk2/tree/master/SecurityPkg/Library/FmpAuthenticationLibPkcs7).
+
+### Capsule Versioning
+
+The capsule version should only be allowed to increment in value across updates to prevent rollback attacks. The
+`EFI_FIRMWARE_IMAGE_DESCRIPTOR` structure contains `Version` and `LowestSupportedImageVersion` fields that are used
+to check for compliance during firmware update. `Version` must be greater than or equal to
+`LowestSupportedImageVersion` in the current firmware and the greater than `Version` of the current firmware.
+
+An EDK II library implementation (`EdkiiSystemCapsuleLib`) that performs version checking is available at:
+[SignedCapsulePkg/Library/EdkiiSystemCapsuleLib](https://github.com/tianocore/edk2/tree/master/SignedCapsulePkg/Library/EdkiiSystemCapsuleLib).
+
+### Device-Specific Functionality During Update
+
+A capsule can target firmware update to a diverse set of devices on a system. Each device might bring unique logic
+and requirements to the firmware update process. Therefore, a library class called `FmpDeviceLib` exists that allows
+for instances written specific to a particular device.
+
+For more information about `FmpDeviceLib`, review:
+[FmpDevicePkg/Library/FmpDeviceLibNull/ReadMe.md](../Library/FmpDeviceLibNull/ReadMe.md)
+
+### Dependency Considerations
+
+The UEFI Specification 2.8 version introduced support for expressing dependencies between components involved in a
+capsule update. For instance, FWx requires FWy to be at least version 2.0 to install. This information is primarily
+conveyed to `FmpDxe` through the `FmpDependencyCheckLib` and `FmpDependencyLib` library classes.
+
+More information about the overall infrastructure is available in:
+[Section 23.2 of the UEFI Specification 2.8B](https://uefi.org/specifications)
+[Tianocore wiki: Fmp Capsule Dependency Introduction](https://github.com/tianocore/tianocore.github.io/wiki/Fmp-Capsule-Dependency-Introduction)
+
+More details regarding the libraries in `FmpDevicePkg` are available in the respective ReadMe files:
+[FmpDevicePkg/Library/FmpDependencyCheckLib][FmpDevicePkg/Library/FmpDependencyCheckLib/ReadMe.md](../Library/FmpDependencyCheckLib/ReadMe.md)
+[FmpDevicePkg/Library/FmpDependencyLib][FmpDevicePkg/Library/FmpDependencyLib/ReadMe.md](../Library/FmpDependencyLib/ReadMe.md)
+
+### Update Policy
+
+A library class (`CapsuleUpdatePolicyLib`) is used to make platform-specific policy decisions available to the
+firmware update process. This includes information such as whether the system power/thermal state permits firmware
+to be updated. A few functions also exist to modify expected behavior such as ignoring the
+`LowestSupportedImageVersion` check or not locking the firmware device for update when the FMP lock event is signaled.
+It is important to note that the latter functions should only be used in very rare special cases such as during
+manufacturing flows.
+
+---
+
+## Design Changes
+
+- **Date:** 06/15/2020
+- **Description/Rationale:** Extending on the more granular LastAttemptStatus support added in FmpDeviceSetImage (),
+FmpDeviceCheckImage () also has a LastAttemptStatus parameter added. An image check is always performed by a set
+image operation. A more granular status code from the check image path greatly improves overall error isolation when
+applying an image.
+- **Changes:** This change allows the FmpDeviceLib implementation to return a last attempt status code in the range
+LAST_ATTEMPT_STATUS_LIBRARY_ERROR_MIN_ERROR_CODE to LAST_ATTEMPT_STATUS_LIBRARY_ERROR_MAX_ERROR_CODE. Furthermore,
+an internal wrapper for CheckTheImage () in FmpDxe was added called CheckTheImageInternal (). This function can return
+a last attempt status code for an error in the driver prior to invoking FmpDeviceCheckImage (). These driver error
+codes will be in the range of LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL_VENDOR_RANGE_MIN to
+LAST_ATTEMPT_STATUS_DRIVER_ERROR_MAX_ERROR_CODE.
+- **Impact/Mitigation:**
+The change break the build for all FmpDeviceLib instances due to the API change. Each FmpDeviceLib should change to
+the new API definition and implement support to return unique values for LastAttemptStatus when appropriate.
+
+---
+
+- **Date:** 10/07/2019
+- **Description/Rationale:** Capsule update is the process where each OEM has a lot of interest. Especially when there
+is capsule update failure, it is helpful to gather more information of the failure. With existing implementations, the
+SetImage routine from FmpDxe driver, which performs most heavy lifting during capsule update, will only
+populate LastAttemptStatus with limited pre-defined error codes which could be consumed/inspected by the OS when it
+recovers and boots. Thus our proposal is to update the SetImage routine and leverage the
+LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL_VENDOR_RANGE range newly defined in UEFI Spec 2.8 Section 23.4, so that the
+error code will provide better granularity when viewing capsule update failure from OS device manager.
+- **Changes:** A few error codes (128 total) are reserved from LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL_VENDOR_RANGE
+range for FmpDxe driver usage, which ranges from thermal and power API failure to capsule payload header check failure.
+Furthermore, *an output pointer of the LastAttemptStatus is added as an input argument for FmpDeviceSetImage function
+in FmpDeviceLib to allow platform to provide their own platform specific error codes*.
+(SPI write failure, SVN checking failure, and more).
+- **Impact/Mitigation:**
+The italic text above will cause a breaking change for all the FmpDeviceLib instances due to API being modified. This
+is to provide better visibility to OEMs to decode capsule update failures more efficiently. Each FmpDeviceLib should
+change to the new API definition and populate proper LastAttemptStatus values when applicable.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/CapsuleUpdatePolicyLibNull/ReadMe.md

@@ -0,0 +1,34 @@
+# Capsule Update Policy NULL Library Instance
+
+## About
+
+This is a NULL instance of the `CapsuleUpdatePolicy` library class. This instance is provided for building when an
+actual library instance is not needed or the values returned by this instance are sufficient for a platform.
+
+## API Overview
+
+* `CheckSystemEnvironment ()` - Determines if the system environment state supports a capsule update.
+
+  The NULL implementation will always return `EFI_SUCCESS`.
+
+* `CheckSystemPower ()` - Determine if the system power state supports a capsule update.
+
+  The NULL implementation will always return `EFI_SUCCESS`.
+
+* `CheckSystemThermal ()` - Determines if the system thermal state supports a capsule update.
+
+  The NULL implementation will always return `EFI_SUCCESS`.
+
+* `IsLockFmpDeviceAtLockEventGuidRequired ()` - Determines if the Lowest Supported Version checks should be performed.
+
+  The NULL implementation will always return `TRUE`.
+
+* `IsLowestSupportedVersionCheckRequired ()` - Determines if the FMP device should be locked when the event specified
+  by `PcdFmpDeviceLockEventGuid` is signaled.
+
+  The NULL implementation will always return `TRUE`.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/CapsuleUpdatePolicyLibOnProtocol/ReadMe.md

@@ -0,0 +1,21 @@
+# Capsule Update Policy On Protocol Library Instance
+
+## About
+
+This library class instance of `CapsuleUpdatePolicyLib` implements the library API using the values returned from
+an installed instance of `EDKII_CAPSULE_UPDATE_POLICY_PROTOCOL`. If the protocol is not found, the library will
+default to conservative responses.
+
+## API Overview
+
+* `CheckSystemEnvironment ()` - Determines if the system environment state supports a capsule update.
+* `CheckSystemPower ()` - Determine if the system power state supports a capsule update.
+* `CheckSystemThermal ()` - Determines if the system thermal state supports a capsule update.
+* `IsLockFmpDeviceAtLockEventGuidRequired ()` - Determines if the Lowest Supported Version checks should be performed.
+* `IsLowestSupportedVersionCheckRequired ()` - Determines if the FMP device should be locked when the event specified
+  by `PcdFmpDeviceLockEventGuid` is signaled.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/FmpDependencyCheckLib/ReadMe.md

@@ -0,0 +1,15 @@
+# FMP Dependency Check Library Instance
+
+## About
+
+This library provides services to check that capsule dependencies are met during firmware update.
+
+## API Overview
+
+* `CheckFmpDependency ()` - Checks a given set of firmware image information such as the image type ID and version
+  against a given dependency expression and returns whether the dependency expression is satisfied.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/FmpDependencyCheckLibNull/ReadMe.md

@@ -0,0 +1,19 @@
+# FMP Dependency Check NULL Library Instance
+
+## About
+
+This is a NULL instance of the `FmpDependencyCheckLib` library class. This instance is provided for building when an
+actual library instance is not needed. A version of the library that contains actual dependency checking
+implementation is also available in this package, see `FmpDependencyCheckLib`.
+
+## API Overview
+
+* `CheckFmpDependency ()` - Checks a given set of firmware image information such as the image type ID and version
+  against a given dependency expression and returns whether the dependency expression is satisfied.
+
+  The NULL implementation will always return `TRUE` indicating the all dependencies are satisfied.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/FmpDependencyDeviceLibNull/ReadMe.md

@@ -0,0 +1,21 @@
+# FMP Dependency Device NULL Library Instance
+
+## About
+
+This is a NULL instance of the `FmpDependencyDeviceLib` library class. This instance is provided for building when
+an actual library instance is not needed.
+
+## API Overview
+
+* `GetFmpDependency ()` - Gets the dependency expression for the device represented by the library class instance.
+
+  The NULL implementation always returns `NULL` a dependency expression was not retrieved.
+
+* `SaveFmpDependency ()` - Saves the dependency expression to the device represented by the library class instance.
+
+  The NULL implementation always returns `EFI_UNSUPPORTED` indicating a dependency expression cannot be saved.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent

FmpDevicePkg/Library/FmpDependencyLib/ReadMe.md

@@ -0,0 +1,17 @@
+# FMP Dependency Library Instance
+
+## About
+
+This library provides functions used to manage dependencies between firmware components during the update of device
+firmware images.
+
+## API Overview
+
+* `EvaluateDependency ()` - Evaluates a given dependency expression against a given set of FMP versions.
+* `GetImageDependency ()` - Gets the dependency expression from a given firmware image.
+* `ValidateDependency ()` - Validates a given dependency expression.
+
+## Copyright
+
+Copyright (c) Microsoft Corporation.  
+SPDX-License-Identifier: BSD-2-Clause-Patent