/** @file\r
\r
- Capsule Library. This library class defines a set of interfaces on \r
- how to process capusle image update.\r
+ This library class defines a set of interfaces for how to process capsule image updates.\r
\r
- Copyright (c) 2007, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
- are licensed and made available under the terms and conditions of the BSD License\r
- which accompanies this distribution. The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php\r
- \r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+Copyright (c) 2007 - 2019, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __CAPSULE_LIB_H__\r
#define __CAPSULE_LIB_H__\r
\r
+//\r
+// BOOLEAN Variable to indicate whether system is in the capsule on disk state.\r
+//\r
+#define COD_RELOCATION_INFO_VAR_NAME L"CodRelocationInfo"\r
+\r
/**\r
- Those capsules supported by the firmwares.\r
- \r
- @param CapsuleHeader Point to the UEFI capsule image to be checked.\r
- \r
+ The firmware checks whether the capsule image is supported\r
+ by the CapsuleGuid in CapsuleHeader or if there is other specific information in\r
+ the capsule image.\r
+\r
+ Caution: This function may receive untrusted input.\r
+\r
+ @param CapsuleHeader Pointer to the UEFI capsule image to be checked.\r
+\r
@retval EFI_SUCESS Input capsule is supported by firmware.\r
@retval EFI_UNSUPPORTED Input capsule is not supported by the firmware.\r
**/\r
);\r
\r
/**\r
- The firmware implements to process the capsule image.\r
- \r
- @param CapsuleHeader Point to the UEFI capsule image to be processed. \r
- \r
- @retval EFI_SUCESS Process Capsule Image successfully. \r
+ The firmware-specific implementation processes the capsule image\r
+ if it recognized the format of this capsule image.\r
+\r
+ Caution: This function may receive untrusted input.\r
+\r
+ @param CapsuleHeader Pointer to the UEFI capsule image to be processed.\r
+\r
+ @retval EFI_SUCESS Capsule Image processed successfully.\r
@retval EFI_UNSUPPORTED Capsule image is not supported by the firmware.\r
**/\r
EFI_STATUS\r
IN EFI_CAPSULE_HEADER *CapsuleHeader\r
);\r
\r
-#endif\r
+/**\r
+\r
+ This routine is called to process capsules.\r
+\r
+ Caution: This function may receive untrusted input.\r
+\r
+ The capsules reported in EFI_HOB_UEFI_CAPSULE are processed.\r
+ If there is no EFI_HOB_UEFI_CAPSULE, this routine does nothing.\r
+\r
+ This routine should be called twice in BDS.\r
+ 1) The first call must be before EndOfDxe. The system capsules is processed.\r
+ If device capsule FMP protocols are exposted at this time and device FMP\r
+ capsule has zero EmbeddedDriverCount, the device capsules are processed.\r
+ Each individual capsule result is recorded in capsule record variable.\r
+ System may reset in this function, if reset is required by capsule and\r
+ all capsules are processed.\r
+ If not all capsules are processed, reset will be defered to second call.\r
+\r
+ 2) The second call must be after EndOfDxe and after ConnectAll, so that all\r
+ device capsule FMP protocols are exposed.\r
+ The system capsules are skipped. If the device capsules are NOT processed\r
+ in first call, they are processed here.\r
+ Each individual capsule result is recorded in capsule record variable.\r
+ System may reset in this function, if reset is required by capsule\r
+ processed in first call and second call.\r
+\r
+ @retval EFI_SUCCESS There is no error when processing capsules.\r
+ @retval EFI_OUT_OF_RESOURCES No enough resource to process capsules.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+ProcessCapsules (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ This routine is called to check if CapsuleOnDisk flag in OsIndications Variable\r
+ is enabled.\r
+\r
+ @retval TRUE Flag is enabled\r
+ @retval FALSE Flag is not enabled\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+CoDCheckCapsuleOnDiskFlag(\r
+ VOID\r
+ );\r
+\r
+/**\r
+ This routine is called to clear CapsuleOnDisk flags including OsIndications and BootNext variable\r
+\r
+ @retval EFI_SUCCESS All Capsule On Disk flags are cleared\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+CoDClearCapsuleOnDiskFlag(\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Relocate Capsule on Disk from EFI system partition.\r
+\r
+ Two solution to deliver Capsule On Disk:\r
+ Solution A: If PcdCapsuleInRamSupport is enabled, relocate Capsule On Disk to memory and call UpdateCapsule().\r
+ Solution B: If PcdCapsuleInRamSupport is disabled, relocate Capsule On Disk to a platform-specific NV storage\r
+ device with BlockIo protocol.\r
+\r
+ Device enumeration like USB costs time, user can input MaxRetry to tell function to retry.\r
+ Function will stall 100ms between each retry.\r
+\r
+ Side Effects:\r
+ Capsule Delivery Supported Flag in OsIndication variable and BootNext variable will be cleared.\r
+ Solution B: Content corruption. Block IO write directly touches low level write. Orignal partitions, file\r
+ systems of the relocation device will be corrupted.\r
+\r
+ @param[in] MaxRetry Max Connection Retry. Stall 100ms between each connection try to ensure\r
+ devices like USB can get enumerated. Input 0 means no retry.\r
+\r
+ @retval EFI_SUCCESS Capsule on Disk images are successfully relocated.\r
\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+CoDRelocateCapsule(\r
+ UINTN MaxRetry\r
+ );\r
+\r
+/**\r
+ Remove the temp file from the root of EFI System Partition.\r
+ Device enumeration like USB costs time, user can input MaxRetry to tell function to retry.\r
+ Function will stall 100ms between each retry.\r
+\r
+ @param[in] MaxRetry Max Connection Retry. Stall 100ms between each connection try to ensure\r
+ devices like USB can get enumerated. Input 0 means no retry.\r
\r
+ @retval EFI_SUCCESS Remove the temp file successfully.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+CoDRemoveTempFile (\r
+ UINTN MaxRetry\r
+ );\r
+\r
+#endif\r
projects / mirror_edk2.git / blobdiff