/** @file\r
- Capsule Runtime Service.\r
+ Capsule Runtime Drivers produces two UEFI capsule runtime services.\r
+ (UpdateCapsule, QueryCapsuleCapabilities)\r
\r
Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
All rights reserved. This program and the accompanying materials\r
\r
#include "CapsuleService.h"\r
\r
+/**\r
+ Passes capsules to the firmware with both virtual and physical mapping. Depending on the intended\r
+ consumption, the firmware may process the capsule immediately. If the payload should persist\r
+ across a system reset, the reset value returned from EFI_QueryCapsuleCapabilities must\r
+ be passed into ResetSystem() and will cause the capsule to be processed by the firmware as\r
+ part of the reset process.\r
+\r
+ @param CapsuleHeaderArray Virtual pointer to an array of virtual pointers to the capsules\r
+ being passed into update capsule.\r
+ @param CapsuleCount Number of pointers to EFI_CAPSULE_HEADER in\r
+ CaspuleHeaderArray.\r
+ @param ScatterGatherList Physical pointer to a set of\r
+ EFI_CAPSULE_BLOCK_DESCRIPTOR that describes the\r
+ location in physical memory of a set of capsules.\r
+\r
+ @retval EFI_SUCCESS Valid capsule was passed. If\r
+ CAPSULE_FLAGS_PERSIT_ACROSS_RESET is not set, the\r
+ capsule has been successfully processed by the firmware.\r
+ @retval EFI_DEVICE_ERROR The capsule update was started, but failed due to a device error.\r
+ @retval EFI_INVALID_PARAMETER CapsuleCount is Zero, or CapsuleImage is not valid.\r
+ For across reset capsule image, ScatterGatherList is NULL.\r
+ @retval EFI_UNSUPPORTED CapsuleImage is not recognized by the firmware.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
UpdateCapsule (\r
IN UINTN CapsuleCount,\r
IN EFI_PHYSICAL_ADDRESS ScatterGatherList OPTIONAL\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- This code finds whether the capsules need reset to update, if not, update immediately.\r
-\r
-Arguments:\r
-\r
- CapsuleHeaderArray A array of pointers to capsule headers passed in\r
- CapsuleCount The number of capsule\r
- ScatterGatherList Physical address of datablock list points to capsule\r
-\r
-Returns:\r
-\r
- EFI STATUS\r
- EFI_SUCCESS Valid capsule was passed.If CAPSULE_FLAG_PERSIT_ACROSS_RESET is\r
- not set, the capsule has been successfully processed by the firmware.\r
- If it set, the ScattlerGatherList is successfully to be set.\r
- EFI_INVALID_PARAMETER CapsuleCount is less than 1,CapsuleGuid is not supported.\r
- EFI_DEVICE_ERROR Failed to SetVariable or ProcessFirmwareVolume.\r
-\r
---*/\r
{\r
UINTN ArrayNumber;\r
EFI_STATUS Status;\r
EFI_CAPSULE_HEADER *CapsuleHeader;\r
-\r
+ \r
+ //\r
+ // Capsule Count can't be less than one.\r
+ //\r
if (CapsuleCount < 1) {\r
return EFI_INVALID_PARAMETER;\r
}\r
// Assume that capsules have the same flags on reseting or not.\r
//\r
CapsuleHeader = CapsuleHeaderArray[0];\r
-\r
+ \r
+ //\r
+ // Process across reset capsule image.\r
+ //\r
if ((CapsuleHeader->Flags & CAPSULE_FLAGS_PERSIST_ACROSS_RESET) != 0) {\r
//\r
// Check if the platform supports update capsule across a system reset\r
return Status;\r
}\r
//\r
- // Successfully set the capsule image address into variable.\r
+ // Successfully set the capsule image address into EFI variable.\r
//\r
return EFI_SUCCESS;\r
}\r
}\r
\r
//\r
- // The rest occurs in the condition of non-reset mode\r
- // Now Runtime mode doesn't support the non-reset capsule image.\r
+ // Process the non-reset capsule image.\r
//\r
if (EfiAtRuntime ()) {\r
+ //\r
+ // Runtime mode doesn't support the non-reset capsule image.\r
+ //\r
return EFI_UNSUPPORTED;\r
}\r
\r
//\r
// Here should be in the boot-time for non-reset capsule image\r
- // Default process to Update Capsule image into Flash.\r
+ // Platform specific update for the non-reset capsule image.\r
//\r
- for (ArrayNumber = 0; ArrayNumber < CapsuleCount ; ArrayNumber++) {\r
+ for (ArrayNumber = 0; ArrayNumber < CapsuleCount; ArrayNumber++) {\r
Status = ProcessCapsuleImage (CapsuleHeaderArray[ArrayNumber]);\r
if (EFI_ERROR (Status)) {\r
return Status;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Returns if the capsule can be supported via UpdateCapsule().\r
+\r
+ @param CapsuleHeaderArray Virtual pointer to an array of virtual pointers to the capsules\r
+ being passed into update capsule.\r
+ @param CapsuleCount Number of pointers to EFI_CAPSULE_HEADER in\r
+ CaspuleHeaderArray.\r
+ @param MaxiumCapsuleSize On output the maximum size that UpdateCapsule() can\r
+ support as an argument to UpdateCapsule() via\r
+ CapsuleHeaderArray and ScatterGatherList.\r
+ @param ResetType Returns the type of reset required for the capsule update.\r
\r
+ @retval EFI_SUCCESS Valid answer returned.\r
+ @retval EFI_UNSUPPORTED The capsule image is not supported on this platform, and\r
+ MaximumCapsuleSize and ResetType are undefined.\r
+ @retval EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL, or ResetTyep is NULL,\r
+ Or CapsuleCount is Zero, or CapsuleImage is not valid.\r
\r
+**/\r
EFI_STATUS\r
EFIAPI\r
QueryCapsuleCapabilities (\r
OUT UINT64 *MaxiumCapsuleSize,\r
OUT EFI_RESET_TYPE *ResetType\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- This code is to query about capsule capability.\r
-\r
-Arguments:\r
-\r
- CapsuleHeaderArray A array of pointers to capsule headers passed in\r
- CapsuleCount The number of capsule\r
- MaxiumCapsuleSize Max capsule size is supported\r
- ResetType Reset type the capsule indicates, if reset is not needed,return EfiResetCold.\r
- If reset is needed, return EfiResetWarm.\r
-\r
-Returns:\r
-\r
- EFI STATUS\r
- EFI_SUCCESS Valid answer returned\r
- EFI_INVALID_PARAMETER MaxiumCapsuleSize is NULL,ResetType is NULL.CapsuleCount is less than 1,CapsuleGuid is not supported.\r
- EFI_UNSUPPORTED The capsule type is not supported.\r
-\r
---*/\r
{\r
UINTN ArrayNumber;\r
EFI_CAPSULE_HEADER *CapsuleHeader;\r
\r
+ //\r
+ // Capsule Count can't be less than one.\r
+ //\r
if (CapsuleCount < 1) {\r
return EFI_INVALID_PARAMETER;\r
}\r
-\r
+ \r
+ //\r
+ // Check whether input paramter is valid\r
+ //\r
if ((MaxiumCapsuleSize == NULL) ||(ResetType == NULL)) {\r
return EFI_INVALID_PARAMETER;\r
}\r
return EFI_INVALID_PARAMETER;\r
}\r
//\r
- // Check Capsule image without populate flag by firmware support capsule function \r
+ // Check Capsule image without populate flag is supported by firmware\r
//\r
if (((CapsuleHeader->Flags & CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE) == 0) && \r
(SupportCapsuleImage (CapsuleHeader) != EFI_SUCCESS)) {\r
}\r
\r
//\r
- //Assume that capsules have the same flags on reseting or not.\r
+ // Assume that capsules have the same flags on reseting or not.\r
//\r
CapsuleHeader = CapsuleHeaderArray[0];\r
if ((CapsuleHeader->Flags & CAPSULE_FLAGS_PERSIST_ACROSS_RESET) != 0) {\r
*ResetType = EfiResetWarm;\r
*MaxiumCapsuleSize = FixedPcdGet32(PcdMaxSizePopulateCapsule);\r
} else {\r
+ //\r
+ // For non-reset capsule image.\r
+ //\r
*ResetType = EfiResetCold;\r
*MaxiumCapsuleSize = FixedPcdGet32(PcdMaxSizeNonPopulateCapsule);\r
}\r
}\r
\r
\r
+/**\r
+\r
+ This code is to install UEFI capsule runtime service.\r
+\r
+ @param ImageHandle The firmware allocated handle for the EFI image. \r
+ @param SystemTable A pointer to the EFI System Table.\r
+\r
+ @retval EFI_SUCCESS UEFI Capsule Runtime Services are installed successfully. \r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
CapsuleServiceInitialize (\r
IN EFI_HANDLE ImageHandle,\r
IN EFI_SYSTEM_TABLE *SystemTable\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- This code is capsule runtime service initialization.\r
-\r
-Arguments:\r
-\r
- ImageHandle The image handle\r
- SystemTable The system table.\r
-\r
-Returns:\r
-\r
- EFI STATUS\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
EFI_HANDLE NewHandle;\r
-\r
+ \r
+ //\r
+ // Install capsule runtime services into UEFI runtime service tables.\r
+ //\r
SystemTable->RuntimeServices->UpdateCapsule = UpdateCapsule;\r
SystemTable->RuntimeServices->QueryCapsuleCapabilities = QueryCapsuleCapabilities;\r
\r
//\r
- // Now install the Capsule Architectural Protocol on a new handle\r
+ // Install the Capsule Architectural Protocol on a new handle\r
+ // to signify the capsule runtime services are ready.\r
//\r
NewHandle = NULL;\r
\r