Code scrub for the Capsule, SecurityStub, and Crc32 library instance.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5441 6f19259b-4bc3-4df7-8a09-765794883524

11 files changed, 255 insertions, 162 deletions

diff --git a/MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.c b/MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.c
index 1b88b3a612..66546f12f8 100644
--- a/MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.c
+++ b/MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.c
@@ -1,7 +1,7 @@
-/**@file

-  Capsule Library Null instance. 

+/** @file

+  Null Dxe Capsule Library instance.

 

-Copyright (c) 2007 Intel Corporation

+Copyright (c) 2007 - 2008 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

@@ -15,11 +15,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Library/CapsuleLib.h>

 

 /**

-  Those capsules supported by the firmwares.

+  Check those capsules are supported by the firmwares.

   

   @param  CapsuleHeader    Point to the UEFI capsule image to be checked.

   

-  @retval EFI_SUCESS       Input capsule is supported by firmware.

   @retval EFI_UNSUPPORTED  Input capsule is not supported by the firmware.

 **/

 EFI_STATUS

@@ -36,7 +35,6 @@ SupportCapsuleImage (
   

   @param  CapsuleHeader    Point to the UEFI capsule image to be processed. 

    

-  @retval EFI_SUCESS       Process Capsule Image successfully. 

   @retval EFI_UNSUPPORTED  Capsule image is not supported by the firmware.

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.c b/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.c
index 167f281365..99f7285108 100644
--- a/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.c
+++ b/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.c
@@ -27,6 +27,21 @@ typedef struct {
   UINT32                    CRC32Checksum;

 } CRC32_SECTION_HEADER;

 

+/**

+

+  The implementation of Crc32 guided section GetInfo() to get 

+  size and attribute of the guided section.

+

+  @param InputSection       Buffer containing the input GUIDed section to be processed.

+  @param OutputBufferSize   The size of OutputBuffer.

+  @param ScratchBufferSize  The size of ScratchBuffer.

+  @param SectionAttribute   The attribute of the input guided section.

+

+  @retval EFI_SUCCESS            The size of destination buffer, the size of scratch buffer and 

+                                 the attribute of the input section are successull retrieved.

+  @retval EFI_INVALID_PARAMETER  The GUID in InputSection does not match this instance guid.

+

+**/

 EFI_STATUS

 EFIAPI

 Crc32GuidedSectionGetInfo (

@@ -35,26 +50,10 @@ Crc32GuidedSectionGetInfo (
   OUT UINT32      *ScratchBufferSize,

   OUT UINT16      *SectionAttribute

   )

-/*++

-

-Routine Description:

-

-  The implementation of Crc32 guided section GetInfo().

-

-Arguments:

-  InputSection          Buffer containing the input GUIDed section to be processed. 

-  OutputBufferSize      The size of OutputBuffer.

-  ScratchBufferSize     The size of ScratchBuffer.

-  SectionAttribute      The attribute of the input guided section.

-

-Returns:

-

-  EFI_SUCCESS           - The size of destination buffer and the size of scratch buffer are successull retrieved.

-  EFI_INVALID_PARAMETER - The source data is corrupted, or

-                          The GUID in InputSection does not match this instance guid.

-

---*/

 {

+  //

+  // Check whether the input guid section is recognized.

+  //

   if (!CompareGuid (

         &gEfiCrc32GuidedSectionExtractionProtocolGuid, 

         &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {

@@ -71,6 +70,20 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+

+  The implementation of Crc32 Guided section extraction to get the section data.

+

+  @param InputSection    Buffer containing the input GUIDed section to be processed.

+  @param OutputBuffer    to contain the output data, which is allocated by the caller.

+  @param ScratchBuffer   A pointer to a caller-allocated buffer for function internal use.

+  @param AuthenticationStatus A pointer to a caller-allocated UINT32 that indicates the

+                         authentication status of the output buffer.

+

+  @retval EFI_SUCCESS            Section Data and Auth Status is extracted successfully.

+  @retval EFI_INVALID_PARAMETER  The GUID in InputSection does not match this instance guid.

+

+**/

 EFI_STATUS

 EFIAPI

 Crc32GuidedSectionHandler (

@@ -79,28 +92,6 @@ Crc32GuidedSectionHandler (
   IN        VOID    *ScratchBuffer,        OPTIONAL

   OUT       UINT32  *AuthenticationStatus

   )

-/*++

-

-Routine Description:

-

-  The implementation of Crc32 Guided section extraction.

-

-Arguments:

-  InputSection           Buffer containing the input GUIDed section to be processed. 

-  OutputBuffer           OutputBuffer to point to the start of the section's contents.

-                         if guided data is not prcessed. Otherwise,

-                         OutputBuffer to contain the output data, which is allocated by the caller.

-  ScratchBuffer          A pointer to a caller-allocated buffer for function internal use. 

-  AuthenticationStatus   A pointer to a caller-allocated UINT32 that indicates the

-                         authentication status of the output buffer. 
-

-Returns:

-

-  RETURN_SUCCESS           - Decompression is successfull

-  RETURN_INVALID_PARAMETER - The source data is corrupted, or

-                             The GUID in InputSection does not match this instance guid.

-

---*/

 {

   EFI_STATUS                Status;

   CRC32_SECTION_HEADER      *Crc32SectionHeader;

@@ -108,12 +99,18 @@ Returns:
   UINT32                    OutputBufferSize;

   VOID                      *DummyInterface;

 

+  //

+  // Check whether the input guid section is recognized.

+  //

   if (!CompareGuid (

         &gEfiCrc32GuidedSectionExtractionProtocolGuid, 

         &(((EFI_GUID_DEFINED_SECTION *) InputSection)->SectionDefinitionGuid))) {

     return EFI_INVALID_PARAMETER;

   }

-

+  

+  //

+  // Init Checksum value to Zero.

+  //

   Crc32Checksum = 0;

   //

   // Points to the Crc32 section header

@@ -134,6 +131,9 @@ Returns:
   //

   Status = gBS->LocateProtocol (&gEfiSecurityPolicyProtocolGuid, NULL, &DummyInterface);

   if (!EFI_ERROR (Status)) {

+    //

+    // If SecurityPolicy Protocol exist, AUTH platform override bit is set.

+    //

     *AuthenticationStatus |= EFI_AUTH_STATUS_PLATFORM_OVERRIDE;

   } else {

     //

@@ -142,9 +142,15 @@ Returns:
     Status = gBS->CalculateCrc32 (*OutputBuffer, OutputBufferSize, &Crc32Checksum);

     if (Status == EFI_SUCCESS) {

       if (Crc32Checksum != Crc32SectionHeader->CRC32Checksum) {

+        //

+        // If Crc32 checksum is not matched, AUTH tested failed bit is set.

+        //

         *AuthenticationStatus |= EFI_AUTH_STATUS_TEST_FAILED;

       }

     } else {

+      //

+      // If Crc32 checksum is not calculated, AUTH not tested bit is set.

+      //

       *AuthenticationStatus |= EFI_AUTH_STATUS_NOT_TESTED;

     }

   }

@@ -152,11 +158,11 @@ Returns:
   return EFI_SUCCESS;

 }

 

-/**
+/**

   Register Crc32 section handler.

-
+

   @retval  RETURN_SUCCESS            Register successfully.

-  @retval  RETURN_OUT_OF_RESOURCES   No enough memory to store this handler.
+  @retval  RETURN_OUT_OF_RESOURCES   No enough memory to register this handler.

 **/

 EFI_STATUS

 EFIAPI

diff --git a/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.inf b/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.inf
index b5cbdcecf1..170d0bed43 100644
--- a/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.inf
+++ b/MdeModulePkg/Library/DxeCrc32GuidedSectionExtractLib/DxeCrc32GuidedSectionExtractLib.inf
@@ -1,7 +1,7 @@
 #/** @file

-# Component description file for Crc32SectionExtract library.

+# Crc32SectionExtract library instance registers Crc32 handler into ExtractGuidedSectionLib.

 #

-# Copyright (c) 2006 - 2007, Intel Corporation

+# Copyright (c) 2006 - 2008, 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

@@ -19,6 +19,7 @@
   FILE_GUID                      = 387A2490-81FC-4E7C-8E0A-3E58C30FCD0B

   MODULE_TYPE                    = DXE_DRIVER

   VERSION_STRING                 = 1.0

+  LIBRARY_CLASS                  = NULL|DXE_CORE DXE_DRIVER DXE_RUNTIME_DRIVER DXE_SAL_DRIVER DXE_SMM_DRIVER UEFI_APPLICATION UEFI_DRIVER

   EDK_RELEASE_VERSION            = 0x00020000

   EFI_SPECIFICATION_VERSION      = 0x00020000

 

diff --git a/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.c b/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.c
index 5e63e1ede9..40acc57c95 100644
--- a/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.c
+++ b/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.c
@@ -1,5 +1,6 @@
 /** @file

-  Recovery Library. This library class defines a set of methods related do recovery.

+  Null Recovery Library instance. 

+  This library class defines a set of methods related do recovery.

 

 Copyright (c) 2006 - 2008, Intel Corporation. <BR>

 All rights reserved. This program and the accompanying materials

@@ -16,8 +17,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 /**

   Calling this function causes the system do recovery.

   

-  @retval EFI_SUCESS   Sucess to do recovery.

-  @retval Others       Fail to do recovery.

+  @retval EFI_UNSUPPORTED       Recovery is not supported.

 **/

 EFI_STATUS

 EFIAPI

diff --git a/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf b/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf
index 404eadd676..10ea0cdbea 100644
--- a/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf
+++ b/MdeModulePkg/Library/PeiRecoveryLibNull/PeiRecoveryLibNull.inf
@@ -1,6 +1,6 @@
 #/** @file

 #  

-#    Recovery for PEIM

+#  Null Recovery library instance for PEIM module

 #  

 #  Copyright (c) 2006 - 2008, Intel Corporation. <BR>

 #  All rights reserved. This program and the accompanying materials

@@ -37,8 +37,4 @@
   MdePkg/MdePkg.dec

   MdeModulePkg/MdeModulePkg.dec

 

-[LibraryClasses]

-  BaseLib

-

-  

   
\ No newline at end of file
diff --git a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleRuntimeDxe.inf b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleRuntimeDxe.inf
index f971f2b1c7..b1ee94db69 100644
--- a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleRuntimeDxe.inf
+++ b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleRuntimeDxe.inf
@@ -50,7 +50,7 @@
   gEfiCapsuleVendorGuid                         # SOMETIMES_CONSUMED

 

 [Protocols]

-  gEfiCapsuleArchProtocolGuid                   # PROTOCOL ALWAYS_CONSUMED

+  gEfiCapsuleArchProtocolGuid                   # PROTOCOL ALWAYS_PRODUCED

 

 [FeaturePcd.common]

   gEfiMdeModulePkgTokenSpaceGuid.PcdSupportUpdateCapsuleRest

diff --git a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
index 35ae46bb40..dbb9563188 100644
--- a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
+++ b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
@@ -1,5 +1,6 @@
 /** @file

-  Capsule Runtime Service.

+  Capsule Runtime Drivers produces two UEFI capsule runtime services.

+  (UpdateCapsule, QueryCapsuleCapabilities)

 

 Copyright (c) 2006 - 2008, Intel Corporation. <BR>

 All rights reserved. This program and the accompanying materials

@@ -14,6 +15,30 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 #include "CapsuleService.h"

 

+/**

+  Passes capsules to the firmware with both virtual and physical mapping. Depending on the intended

+  consumption, the firmware may process the capsule immediately. If the payload should persist

+  across a system reset, the reset value returned from EFI_QueryCapsuleCapabilities must

+  be passed into ResetSystem() and will cause the capsule to be processed by the firmware as

+  part of the reset process.

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  ScatterGatherList     Physical pointer to a set of

+                                EFI_CAPSULE_BLOCK_DESCRIPTOR that describes the

+                                location in physical memory of a set of capsules.

+

+  @retval EFI_SUCCESS           Valid capsule was passed. If

+                                CAPSULE_FLAGS_PERSIT_ACROSS_RESET is not set, the

+                                capsule has been successfully processed by the firmware.

+  @retval EFI_DEVICE_ERROR      The capsule update was started, but failed due to a device error.

+  @retval EFI_INVALID_PARAMETER CapsuleCount is Zero, or CapsuleImage is not valid.

+                                For across reset capsule image, ScatterGatherList is NULL.

+  @retval EFI_UNSUPPORTED       CapsuleImage is not recognized by the firmware.

+

+**/

 EFI_STATUS

 EFIAPI

 UpdateCapsule (

@@ -21,33 +46,14 @@ UpdateCapsule (
   IN UINTN                   CapsuleCount,

   IN EFI_PHYSICAL_ADDRESS    ScatterGatherList OPTIONAL

   )

-/*++

-

-Routine Description:

-

-  This code finds whether the capsules need reset to update, if not, update immediately.

-

-Arguments:

-

-  CapsuleHeaderArray             A array of pointers to capsule headers passed in

-  CapsuleCount                   The number of capsule

-  ScatterGatherList              Physical address of datablock list points to capsule

-

-Returns:

-

-  EFI STATUS

-  EFI_SUCCESS                    Valid capsule was passed.If CAPSULE_FLAG_PERSIT_ACROSS_RESET is

-                                 not set, the capsule has been successfully processed by the firmware.

-                                 If it set, the ScattlerGatherList is successfully to be set.

-  EFI_INVALID_PARAMETER          CapsuleCount is less than 1,CapsuleGuid is not supported.

-  EFI_DEVICE_ERROR               Failed to SetVariable or ProcessFirmwareVolume.

-

---*/

 {

   UINTN                     ArrayNumber;

   EFI_STATUS                Status;

   EFI_CAPSULE_HEADER        *CapsuleHeader;

-

+  

+  //

+  // Capsule Count can't be less than one.

+  //

   if (CapsuleCount < 1) {

     return EFI_INVALID_PARAMETER;

   }

@@ -76,7 +82,10 @@ Returns:
   // Assume that capsules have the same flags on reseting or not.

   //

   CapsuleHeader = CapsuleHeaderArray[0];

-

+  

+  //

+  //  Process across reset capsule image.

+  //

   if ((CapsuleHeader->Flags & CAPSULE_FLAGS_PERSIST_ACROSS_RESET) != 0) {

     //

     // Check if the platform supports update capsule across a system reset

@@ -107,25 +116,27 @@ Returns:
         return Status;

       }

       //

-      // Successfully set the capsule image address into variable.

+      // Successfully set the capsule image address into EFI variable.

       //

       return EFI_SUCCESS;

     }

   }

 

   //

-  // The rest occurs in the condition of non-reset mode

-  // Now Runtime mode doesn't support the non-reset capsule image.

+  // Process the non-reset capsule image.

   //

   if (EfiAtRuntime ()) {

+    //

+    // Runtime mode doesn't support the non-reset capsule image.

+    //

     return EFI_UNSUPPORTED;

   }

 

   //

   // Here should be in the boot-time for non-reset capsule image

-  // Default process to Update Capsule image into Flash.

+  // Platform specific update for the non-reset capsule image.

   //

-  for (ArrayNumber = 0; ArrayNumber < CapsuleCount ; ArrayNumber++) {

+  for (ArrayNumber = 0; ArrayNumber < CapsuleCount; ArrayNumber++) {

     Status = ProcessCapsuleImage (CapsuleHeaderArray[ArrayNumber]);

     if (EFI_ERROR (Status)) {

       return Status;

@@ -135,8 +146,25 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  Returns if the capsule can be supported via UpdateCapsule().

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  MaxiumCapsuleSize     On output the maximum size that UpdateCapsule() can

+                                support as an argument to UpdateCapsule() via

+                                CapsuleHeaderArray and ScatterGatherList.

+  @param  ResetType             Returns the type of reset required for the capsule update.

 

+  @retval EFI_SUCCESS           Valid answer returned.

+  @retval EFI_UNSUPPORTED       The capsule image is not supported on this platform, and

+                                MaximumCapsuleSize and ResetType are undefined.

+  @retval EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL, or ResetTyep is NULL,

+                                Or CapsuleCount is Zero, or CapsuleImage is not valid.

 

+**/

 EFI_STATUS

 EFIAPI

 QueryCapsuleCapabilities (

@@ -145,36 +173,20 @@ QueryCapsuleCapabilities (
   OUT UINT64               *MaxiumCapsuleSize,

   OUT EFI_RESET_TYPE       *ResetType

   )

-/*++

-

-Routine Description:

-

-  This code is to query about capsule capability.

-

-Arguments:

-

-  CapsuleHeaderArray              A array of pointers to capsule headers passed in

-  CapsuleCount                    The number of capsule

-  MaxiumCapsuleSize               Max capsule size is supported

-  ResetType                       Reset type the capsule indicates, if reset is not needed,return EfiResetCold.

-                                  If reset is needed, return EfiResetWarm.

-

-Returns:

-

-  EFI STATUS

-  EFI_SUCCESS                     Valid answer returned

-  EFI_INVALID_PARAMETER           MaxiumCapsuleSize is NULL,ResetType is NULL.CapsuleCount is less than 1,CapsuleGuid is not supported.

-  EFI_UNSUPPORTED                 The capsule type is not supported.

-

---*/

 {

   UINTN                     ArrayNumber;

   EFI_CAPSULE_HEADER        *CapsuleHeader;

 

+  //

+  // Capsule Count can't be less than one.

+  //

   if (CapsuleCount < 1) {

     return EFI_INVALID_PARAMETER;

   }

-

+  

+  //

+  // Check whether input paramter is valid

+  //

   if ((MaxiumCapsuleSize == NULL) ||(ResetType == NULL)) {

     return EFI_INVALID_PARAMETER;

   }

@@ -191,7 +203,7 @@ Returns:
       return EFI_INVALID_PARAMETER;

     }

     //

-    // Check Capsule image without populate flag by firmware support capsule function  

+    // Check Capsule image without populate flag is supported by firmware

     //

     if (((CapsuleHeader->Flags & CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE) == 0) && 

         (SupportCapsuleImage (CapsuleHeader) != EFI_SUCCESS)) {

@@ -200,7 +212,7 @@ Returns:
   }

 

   //

-  //Assume that capsules have the same flags on reseting or not.

+  // Assume that capsules have the same flags on reseting or not.

   //

   CapsuleHeader = CapsuleHeaderArray[0];

   if ((CapsuleHeader->Flags & CAPSULE_FLAGS_PERSIST_ACROSS_RESET) != 0) {

@@ -213,6 +225,9 @@ Returns:
     *ResetType = EfiResetWarm;

     *MaxiumCapsuleSize = FixedPcdGet32(PcdMaxSizePopulateCapsule);

   } else {

+    //

+    // For non-reset capsule image.

+    //

     *ResetType = EfiResetCold;

     *MaxiumCapsuleSize = FixedPcdGet32(PcdMaxSizeNonPopulateCapsule);

   }

@@ -220,37 +235,35 @@ Returns:
 }

 

 

+/**

+

+  This code is to install UEFI capsule runtime service.

+

+  @param  ImageHandle    The firmware allocated handle for the EFI image.  

+  @param  SystemTable    A pointer to the EFI System Table.

+

+  @retval EFI_SUCCESS    UEFI Capsule Runtime Services are installed successfully. 

+

+**/

 EFI_STATUS

 EFIAPI

 CapsuleServiceInitialize (

   IN EFI_HANDLE         ImageHandle,

   IN EFI_SYSTEM_TABLE   *SystemTable

   )

-/*++

-

-Routine Description:

-

-  This code is capsule runtime service initialization.

-

-Arguments:

-

-  ImageHandle          The image handle

-  SystemTable          The system table.

-

-Returns:

-

-  EFI STATUS

-

---*/

 {

   EFI_STATUS  Status;

   EFI_HANDLE  NewHandle;

-

+  

+  //

+  // Install capsule runtime services into UEFI runtime service tables.

+  //

   SystemTable->RuntimeServices->UpdateCapsule                    = UpdateCapsule;

   SystemTable->RuntimeServices->QueryCapsuleCapabilities         = QueryCapsuleCapabilities;

 

   //

-  // Now install the Capsule Architectural Protocol on a new handle

+  // Install the Capsule Architectural Protocol on a new handle

+  // to signify the capsule runtime services are ready.

   //

   NewHandle = NULL;

 

diff --git a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.h b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.h
index b9aa6f8c91..989f3a4632 100644
--- a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.h
+++ b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.h
@@ -1,5 +1,5 @@
 /** @file

-  Capsule Runtime Service

+  Include the required header files for Capsule Runtime Service drivers.

 

 Copyright (c) 2006 - 2008, Intel Corporation. <BR>

 All rights reserved. This program and the accompanying materials

@@ -28,6 +28,30 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Library/UefiBootServicesTableLib.h>

 #include <Library/CapsuleLib.h>

 

+/**

+  Passes capsules to the firmware with both virtual and physical mapping. Depending on the intended

+  consumption, the firmware may process the capsule immediately. If the payload should persist

+  across a system reset, the reset value returned from EFI_QueryCapsuleCapabilities must

+  be passed into ResetSystem() and will cause the capsule to be processed by the firmware as

+  part of the reset process.

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  ScatterGatherList     Physical pointer to a set of

+                                EFI_CAPSULE_BLOCK_DESCRIPTOR that describes the

+                                location in physical memory of a set of capsules.

+

+  @retval EFI_SUCCESS           Valid capsule was passed. If

+                                CAPSULE_FLAGS_PERSIT_ACROSS_RESET is not set, the

+                                capsule has been successfully processed by the firmware.

+  @retval EFI_DEVICE_ERROR      The capsule update was started, but failed due to a device error.

+  @retval EFI_INVALID_PARAMETER CapsuleCount is Zero, or CapsuleImage is not valid.

+                                For across reset capsule image, ScatterGatherList is NULL.

+  @retval EFI_UNSUPPORTED       CapsuleImage is not recognized by the firmware.

+

+**/

 EFI_STATUS

 EFIAPI

 UpdateCapsule(

@@ -36,6 +60,25 @@ UpdateCapsule(
   IN EFI_PHYSICAL_ADDRESS    ScatterGatherList OPTIONAL

   );

 

+/**

+  Returns if the capsule can be supported via UpdateCapsule().

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  MaxiumCapsuleSize     On output the maximum size that UpdateCapsule() can

+                                support as an argument to UpdateCapsule() via

+                                CapsuleHeaderArray and ScatterGatherList.

+  @param  ResetType             Returns the type of reset required for the capsule update.

+

+  @retval EFI_SUCCESS           Valid answer returned.

+  @retval EFI_UNSUPPORTED       The capsule image is not supported on this platform, and

+                                MaximumCapsuleSize and ResetType are undefined.

+  @retval EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL, or ResetTyep is NULL,

+                                Or CapsuleCount is Zero, or CapsuleImage is not valid.

+

+**/

 EFI_STATUS

 EFIAPI

 QueryCapsuleCapabilities(

diff --git a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.c b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.c
index 2eb325ec56..f60c98ca43 100644
--- a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.c
+++ b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.c
@@ -1,7 +1,8 @@
 /** @file

-  This driver supports platform security service.

+  This driver implements one sample platform security service, which does 

+  nothing and always return EFI_SUCCESS.

   

-  Copyright (c) 2006 - 2007, Intel Corporation                                              

+  Copyright (c) 2006 - 2008, 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        

@@ -60,18 +61,8 @@ EFI_SECURITY_ARCH_PROTOCOL  mSecurityStub = {
   @param  File             This is a pointer to the device path of the file that is

                            being dispatched. This will optionally be used for logging.

 

-  @retval EFI_SUCCESS           The file specified by File did authenticate, and the

-                                platform policy dictates that the DXE Core may use File.

-  @retval EFI_INVALID_PARAMETER Driver is NULL.

-  @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and

-                                the platform policy dictates that File should be placed

-                                in the untrusted state. A file may be promoted from

-                                the untrusted to the trusted state at a future time

-                                with a call to the Trust() DXE Service.

-  @retval EFI_ACCESS_DENIED     The file specified by File did not authenticate, and

-                                the platform policy dictates that File should not be

-                                used for any purpose.

-

+  @retval EFI_SUCCESS            Do nothing and return.

+  @retval EFI_INVALID_PARAMETER  File is NULL.

 **/

 EFI_STATUS

 EFIAPI

@@ -90,15 +81,14 @@ SecurityStubAuthenticateState (
 

 

 /**

-  The user Entry Point for DXE driver. The user code starts with this function

+  The user Entry Point installs SAP. The user code starts with this function

   as the real entry point for the image goes into a library that calls this 

   function.

 

-  @param[in] ImageHandle    The firmware allocated handle for the EFI image.  

-  @param[in] SystemTable    A pointer to the EFI System Table.

+  @param ImageHandle    The firmware allocated handle for the EFI image.  

+  @param SystemTable    A pointer to the EFI System Table.

   

-  @retval EFI_SUCCESS       The entry point is executed successfully.

-  @retval other             Some error occurs when executing this entry point.

+  @retval EFI_SUCCESS   Install the sample Security Architectural Protocol successfully.

 

 **/

 EFI_STATUS

@@ -126,5 +116,5 @@ SecurityStubInitialize (
                   );

   ASSERT_EFI_ERROR (Status);

 

-  return Status;

+  return EFI_SUCCESS;

 }

diff --git a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.h b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.h
index dedc14afdb..574957101d 100644
--- a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.h
+++ b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStub.h
@@ -1,7 +1,7 @@
 /** @file

-  Some definitions for Security Architectural Protocol stub driver

+  Inlcude the required definitions for Security Architectural Protocol stub driver

 

-  Copyright (c) 2006 - 2007, Intel Corporation                                              

+  Copyright (c) 2006 - 2008, 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        

@@ -12,8 +12,8 @@
 

 **/

 

-#ifndef _SECURITY_STUB_ARCH_PROTOCOL_H

-#define _SECURITY_STUB_ARCH_PROTOCOL_H

+#ifndef __SECURITY_STUB_ARCH_PROTOCOL_H__

+#define __SECURITY_STUB_ARCH_PROTOCOL_H__

 

 

 //

@@ -28,6 +28,41 @@
 //

 // Function prototypes

 //

+/**

+  The EFI_SECURITY_ARCH_PROTOCOL (SAP) is used to abstract platform-specific 

+  policy from the DXE core response to an attempt to use a file that returns a 

+  given status for the authentication check from the section extraction protocol.  

+

+  The possible responses in a given SAP implementation may include locking 

+  flash upon failure to authenticate, attestation logging for all signed drivers, 

+  and other exception operations.  The File parameter allows for possible logging 

+  within the SAP of the driver.

+

+  If File is NULL, then EFI_INVALID_PARAMETER is returned.

+

+  If the file specified by File with an authentication status specified by 

+  AuthenticationStatus is safe for the DXE Core to use, then EFI_SUCCESS is returned.

+

+  If the file specified by File with an authentication status specified by 

+  AuthenticationStatus is not safe for the DXE Core to use under any circumstances, 

+  then EFI_ACCESS_DENIED is returned.

+

+  If the file specified by File with an authentication status specified by 

+  AuthenticationStatus is not safe for the DXE Core to use right now, but it 

+  might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is 

+  returned.

+

+  @param  This             The EFI_SECURITY_ARCH_PROTOCOL instance.

+  @param  AuthenticationStatus 

+                           This is the authentication type returned from the Section

+                           Extraction protocol. See the Section Extraction Protocol

+                           Specification for details on this type.

+  @param  File             This is a pointer to the device path of the file that is

+                           being dispatched. This will optionally be used for logging.

+

+  @retval EFI_SUCCESS            Do nothing and return.

+  @retval EFI_INVALID_PARAMETER  File is NULL.

+**/

 EFI_STATUS

 EFIAPI

 SecurityStubAuthenticateState (

@@ -36,6 +71,17 @@ SecurityStubAuthenticateState (
   IN  EFI_DEVICE_PATH_PROTOCOL           *File

   );

 

+/**

+  The user Entry Point for DXE driver. The user code starts with this function

+  as the real entry point for the image goes into a library that calls this 

+  function.

+

+  @param ImageHandle    The firmware allocated handle for the EFI image.  

+  @param SystemTable    A pointer to the EFI System Table.

+  

+  @retval EFI_SUCCESS   Install the sample Security Architectural Protocol successfully.

+

+**/

 EFI_STATUS

 EFIAPI

 SecurityStubInitialize (

diff --git a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStubDxe.inf b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStubDxe.inf
index ef6bc23f02..dffb422ff1 100644
--- a/MdeModulePkg/Universal/SecurityStubDxe/SecurityStubDxe.inf
+++ b/MdeModulePkg/Universal/SecurityStubDxe/SecurityStubDxe.inf
@@ -1,7 +1,7 @@
 #/** @file

-#  Component description file for SecurityStub module

+#  Sample SecurityStub module implements the dummy platform security service.

 #

-#  Copyright (c) 2006 - 2007, Intel Corporation

+#  Copyright (c) 2006 - 2008, 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