Add comments for these header files

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

16 files changed, 88 insertions, 52 deletions

diff --git a/MdeModulePkg/Include/Guid/BootState.h b/MdeModulePkg/Include/Guid/BootState.h
index d3a79ae915..1fa7bf588f 100644
--- a/MdeModulePkg/Include/Guid/BootState.h
+++ b/MdeModulePkg/Include/Guid/BootState.h
@@ -1,5 +1,7 @@
 /** @file

   This file defines variable name and variable GUID for boot state.

+  This variable is to mark if the machine has complete one boot cycle before.

+  After the complete boot, the variable BootState will be set to 1.

 

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

 All rights reserved. This program and the accompanying materials

diff --git a/MdeModulePkg/Include/Guid/CapsuleVendor.h b/MdeModulePkg/Include/Guid/CapsuleVendor.h
index 58ac355bd4..de92c2f4df 100644
--- a/MdeModulePkg/Include/Guid/CapsuleVendor.h
+++ b/MdeModulePkg/Include/Guid/CapsuleVendor.h
@@ -1,6 +1,7 @@
 /** @file

   This file defines capsule vendor guid for capsule variable and hob.

-  It also defines capsule varialbe name and capsule guid hob data structure. 

+  It also defines capsule varialbe name and capsule guid hob data structure,

+  which can be used to store the capsule image start address and length.

   They are used by EDKII implementation of capsule update across a system reset.

 

 Copyright (c) 2006 - 2008, Intel Corporation

diff --git a/MdeModulePkg/Include/Guid/GenericPlatformVariable.h b/MdeModulePkg/Include/Guid/GenericPlatformVariable.h
index f63fe9588d..3abf397580 100644
--- a/MdeModulePkg/Include/Guid/GenericPlatformVariable.h
+++ b/MdeModulePkg/Include/Guid/GenericPlatformVariable.h
@@ -1,7 +1,8 @@
 /** @file

   This file defines the genenic platform guid for EFI variable.

-  Generic drivers can use this guid with its variable name to specify 

-  its EFI variable without defining another new guid.

+  Common drivers without specific requirement 

+  can use this guid with their variable name to specify 

+  their EFI variable without defining another new guid.

 

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

 All rights reserved. This program and the accompanying materials

diff --git a/MdeModulePkg/Include/Guid/MemoryTypeInformation.h b/MdeModulePkg/Include/Guid/MemoryTypeInformation.h
index f765349ab1..2387942208 100644
--- a/MdeModulePkg/Include/Guid/MemoryTypeInformation.h
+++ b/MdeModulePkg/Include/Guid/MemoryTypeInformation.h
@@ -1,6 +1,7 @@
 /** @file

-  This file defines the memory type information guid, variable name and guid hob structure. 

-  This guid is used for Memory Type Information entries in the HOB list and EFI variable.

+  This file defines the memory type information guid for its variable and guid. 

+  It also defines memory type info varialbe name and data structure for varialbe and hob both,

+  which can be used to store the information for each memory type in EFI varialbe or HOB.

 

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

 All rights reserved. This program and the accompanying materials

@@ -24,8 +25,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 extern EFI_GUID gEfiMemoryTypeInformationGuid;

 

 typedef struct {

-  UINT32  Type;             /// EFI memory type defined in UEFI specification.

-  UINT32  NumberOfPages;    /// The pages of this type memory.

+  UINT32  Type;             ///> EFI memory type defined in UEFI specification.

+  UINT32  NumberOfPages;    ///> The pages of this type memory.

 } EFI_MEMORY_TYPE_INFORMATION;

 

 #endif

diff --git a/MdeModulePkg/Include/Guid/OverrideVariable.h b/MdeModulePkg/Include/Guid/OverrideVariable.h
index 3cd5b0333f..2e6601d5a5 100644
--- a/MdeModulePkg/Include/Guid/OverrideVariable.h
+++ b/MdeModulePkg/Include/Guid/OverrideVariable.h
@@ -1,7 +1,37 @@
 /** @file

   This file defines the platform driver override variable name and variable guid.

-

-Copyright (c) 2008, Intel Corporation

+  The variable(s) contain the override mappings from Controller Device Path to a set of Driver Device Paths.

+  

+  VariableLayout {

+  //

+  // NotEnd indicate whether the variable is the last one, and has no subsequent variable need to load.

+  // Each variable has MaximumVariableSize limitation, so multiple variables are required to store

+  // large mapping infos.

+  // The variable(s) name rule is PlatDriOver, PlatDriOver1, PlatDriOver2, ....

+  //

+  UINT32                         NotEnd;               //Zero is the last one.

+  //

+  // The entry which contains the mapping that Controller Device Path to a set of Driver Device Paths

+  // There are often multi mapping entries in a variable.

+  //

+  UINT32                         SIGNATURE;            //SIGNATURE_32('p','d','o','i')

+  UINT32                         DriverNum;

+  EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  ......

+  UINT32                         NotEnd;                //Zero is the last one.

+  UINT32                         SIGNATURE;

+  UINT32                         DriverNum;

+  EFI_DEVICE_PATH_PROTOCOL       ControllerDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  EFI_DEVICE_PATH_PROTOCOL       DriverDevicePath[];

+  ......

+  }

+

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

diff --git a/MdeModulePkg/Include/Guid/PeiPeCoffLoader.h b/MdeModulePkg/Include/Guid/PeiPeCoffLoader.h
index e92f9eaf3c..d6ccbfd193 100644
--- a/MdeModulePkg/Include/Guid/PeiPeCoffLoader.h
+++ b/MdeModulePkg/Include/Guid/PeiPeCoffLoader.h
@@ -2,7 +2,7 @@
   This file defines PeCoffLoader guid for PeCoffLoader entry in the HOB list.

   It also defines PE/COFF Loader APIs in PeCoffLoader Hob entry shared between SEC, PEI and DXE

 

-Copyright (c) 2006 - 2008, Intel Corporation                                                         

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

@@ -17,7 +17,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #define __PEI_PE_COFF_LOADER_H__

 

 //

-// MdePkg/Include/Common/PeCoffLoaderImageContext.h

+// Depend on PE_COFF_LOADER_IMAGE_CONTEXT structure definition in PeCoff library class.

 //

 #include <Library/PeCoffLib.h>

 

diff --git a/MdeModulePkg/Include/Guid/PeiPerformanceHob.h b/MdeModulePkg/Include/Guid/PeiPerformanceHob.h
index 1ae7e03f89..7aef6e4ad4 100644
--- a/MdeModulePkg/Include/Guid/PeiPerformanceHob.h
+++ b/MdeModulePkg/Include/Guid/PeiPerformanceHob.h
@@ -1,8 +1,9 @@
 /** @file

   This file defines performance guid for the performance entry in the HOB list, 

-  and define the PEI Performance HOB data structures.

+  and define the PEI Performance HOB data structures. 

+  This hob can be used to store the boot performance data of pei phase.

 

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

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

 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

@@ -30,17 +31,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 typedef struct {

   EFI_PHYSICAL_ADDRESS  Handle;

-  CHAR8                 Token[PEI_PERFORMANCE_STRING_SIZE];   /// Measured token string name 

-  CHAR8                 Module[PEI_PERFORMANCE_STRING_SIZE];  /// Module string name

-  UINT64                StartTimeStamp;                       /// Start time point

-  UINT64                EndTimeStamp;                         /// End time point

+  CHAR8                 Token[PEI_PERFORMANCE_STRING_SIZE];   ///> Measured token string name 

+  CHAR8                 Module[PEI_PERFORMANCE_STRING_SIZE];  ///> Module string name

+  UINT64                StartTimeStamp;                       ///> Start time point

+  UINT64                EndTimeStamp;                         ///> End time point

 } PEI_PERFORMANCE_LOG_ENTRY;

 

 //

 // The header must be aligned at 8 bytes.

 // 

 typedef struct {

-  UINT32                NumberOfEntries;  /// The number of all performance log entries

+  UINT32                NumberOfEntries;  ///> The number of all performance log entries

   UINT32                Reserved;

 } PEI_PERFORMANCE_LOG_HEADER;

 

diff --git a/MdeModulePkg/Include/Guid/PrimaryConsoleInDevice.h b/MdeModulePkg/Include/Guid/PrimaryConsoleInDevice.h
index 1471a53a47..1d60bb5f2e 100644
--- a/MdeModulePkg/Include/Guid/PrimaryConsoleInDevice.h
+++ b/MdeModulePkg/Include/Guid/PrimaryConsoleInDevice.h
@@ -1,8 +1,8 @@
 /** @file

   This guid is used to specify the primary console in device.

-  It will be installed into the virtual device handle for ConIn Splitter.

+  It will be installed as the protocol guid into the virtual device handle for ConIn Splitter.

 

-Copyright (c) 2006 - 2008, Intel Corporation

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

diff --git a/MdeModulePkg/Include/Guid/PrimaryConsoleOutDevice.h b/MdeModulePkg/Include/Guid/PrimaryConsoleOutDevice.h
index 67be727ab1..3ea238b43e 100644
--- a/MdeModulePkg/Include/Guid/PrimaryConsoleOutDevice.h
+++ b/MdeModulePkg/Include/Guid/PrimaryConsoleOutDevice.h
@@ -1,8 +1,8 @@
 /** @file

   This guid is used to specify the primary console out device.

-  It will be installed into the virtual device handle for ConOut Splitter.

+  It will be installed as the protocol guid into the virtual device handle for ConOut Splitter.

 

-Copyright (c) 2006 - 2008, Intel Corporation

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

diff --git a/MdeModulePkg/Include/Guid/PrimaryStandardErrorDevice.h b/MdeModulePkg/Include/Guid/PrimaryStandardErrorDevice.h
index 50031535e1..b53f86b7f9 100644
--- a/MdeModulePkg/Include/Guid/PrimaryStandardErrorDevice.h
+++ b/MdeModulePkg/Include/Guid/PrimaryStandardErrorDevice.h
@@ -1,8 +1,8 @@
 /** @file

   This guid is used to specify the primary StdErr device.

-  It will be installed into the virtual device handle for StdErr Splitter.

+  It will be installed as the protocol guid into the virtual device handle for StdErr Splitter.

 

-Copyright (c) 2006 - 2008, Intel Corporation

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

diff --git a/MdeModulePkg/Include/Guid/ShellFile.h b/MdeModulePkg/Include/Guid/ShellFile.h
index c51a5f20b9..91fb9d852d 100644
--- a/MdeModulePkg/Include/Guid/ShellFile.h
+++ b/MdeModulePkg/Include/Guid/ShellFile.h
@@ -1,5 +1,5 @@
 /** @file

-  This file defines FFS GUID Filename for EFI Shell.

+  This file defines File GUID for EFI Shell.

 

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

 All rights reserved. This program and the accompanying materials

diff --git a/MdeModulePkg/Include/Guid/SystemNvDataGuid.h b/MdeModulePkg/Include/Guid/SystemNvDataGuid.h
index ab45166f02..583f7a30bf 100644
--- a/MdeModulePkg/Include/Guid/SystemNvDataGuid.h
+++ b/MdeModulePkg/Include/Guid/SystemNvDataGuid.h
@@ -1,11 +1,15 @@
 /** @file

-  This file defines NvData Hob GUIDs for System Non Volatile HOB entries and the corresponding hob data structure.

-  NvData Hob is used to report the region of the system non volatile data 

-  for the specific purpose, such as FTW region, Error log region.

+  This file defines NvData Hob GUIDs for System Non Volatile HOB entries 

+  and the corresponding hob data structure. NvData Hob can be used to report 

+  the region of the system non volatile data for the specific purpose, 

+  such as FTW region, Error log region.

   

-  It also defines NvDataFv GUID used as the signature of FTW working block header.

+  It also defines NvDataFv GUID. 

+  This guid can be used as FileSystemGuid in EFI_FIRMWARE_VOLUME_HEADER if 

+  this FV image contains NV data, such as NV variable data.

+  This guid can also be used as the signature of FTW working block header.

 

-Copyright (c) 2006 - 2008, Intel Corporation                                                         

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

diff --git a/MdeModulePkg/Include/Guid/VariableInfo.h b/MdeModulePkg/Include/Guid/VariableInfo.h
index 45a7b87cb6..27a4dafea0 100644
--- a/MdeModulePkg/Include/Guid/VariableInfo.h
+++ b/MdeModulePkg/Include/Guid/VariableInfo.h
@@ -1,7 +1,8 @@
 /** @file

-  This file defines GUIDs used for variable list entries put in the EFI system table.

+  This file defines variable info guid and variable info entry.

+  This guid is used to specify the variable list put in the EFI system table.

 

-Copyright (c) 2006 - 2008, Intel Corporation

+Copyright (c) 2006 - 2009, 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,7 +16,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #ifndef __VARIABLE_INFO_GUID_H__

 #define __VARIABLE_INFO_GUID_H__

 

-// {DDCF3616-3275-4164-98B6-FE85707FFE7D}

 #define EFI_VARIABLE_INFO_GUID \

   { 0xddcf3616, 0x3275, 0x4164, { 0x98, 0xb6, 0xfe, 0x85, 0x70, 0x7f, 0xfe, 0x7d } }

 

@@ -25,19 +25,20 @@ extern EFI_GUID gEfiVariableInfoGuid;
 typedef struct _VARIABLE_INFO_ENTRY  VARIABLE_INFO_ENTRY;

 

 ///

-/// This list gets put in the EFI system table. It is produced by the Variable driver at

-/// Boot Services time and records read and write access to a given variable

+/// This structure contains the variable list that is put in EFI system table.

+/// The variable driver collects all used variables at boot service time and produce this list.

+/// This is an optional feature to dump all used variables in shell environment. 

 ///

 struct _VARIABLE_INFO_ENTRY {

-  VARIABLE_INFO_ENTRY *Next;       /// Pointer to next entry

-  EFI_GUID            VendorGuid;  /// Guid of Variable 

-  CHAR16              *Name;       /// Name of Variable 

-  UINT32              Attributes;  /// Attributes of variable defined in UEFI spec

-  UINT32              ReadCount;   /// Times to read this variable

-  UINT32              WriteCount;  /// Times to write this variable

-  UINT32              DeleteCount; /// Times to delete this variable

-  UINT32              CacheCount;  /// Times that cache hits this variable

-  BOOLEAN             Volatile;    /// TRUE if volatile FALSE if non-volatile

+  VARIABLE_INFO_ENTRY *Next;       ///> Pointer to next entry

+  EFI_GUID            VendorGuid;  ///> Guid of Variable 

+  CHAR16              *Name;       ///> Name of Variable 

+  UINT32              Attributes;  ///> Attributes of variable defined in UEFI spec

+  UINT32              ReadCount;   ///> Times to read this variable

+  UINT32              WriteCount;  ///> Times to write this variable

+  UINT32              DeleteCount; ///> Times to delete this variable

+  UINT32              CacheCount;  ///> Times that cache hits this variable

+  BOOLEAN             Volatile;    ///> TRUE if volatile FALSE if non-volatile

 };

 

 #endif

diff --git a/MdeModulePkg/Include/Ppi/FlashMap.h b/MdeModulePkg/Include/Ppi/FlashMap.h
index 63583bd012..1bd0e727fb 100644
--- a/MdeModulePkg/Include/Ppi/FlashMap.h
+++ b/MdeModulePkg/Include/Ppi/FlashMap.h
@@ -23,9 +23,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 typedef struct _PEI_FLASH_MAP_PPI PEI_FLASH_MAP_PPI;

 

-//

-// Functions

-//

 /**

   Get flash region information.

   

@@ -50,7 +47,6 @@ EFI_STATUS
   OUT EFI_FLASH_SUBAREA_ENTRY     **Entries

   );

 

-

 struct _PEI_FLASH_MAP_PPI {

   PEI_GET_FLASH_AREA_INFO GetAreaInfo;

 };

diff --git a/MdeModulePkg/Include/Ppi/OperatorPresence.h b/MdeModulePkg/Include/Ppi/OperatorPresence.h
index e31a76002d..ba8901679b 100644
--- a/MdeModulePkg/Include/Ppi/OperatorPresence.h
+++ b/MdeModulePkg/Include/Ppi/OperatorPresence.h
@@ -21,7 +21,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 typedef struct _PEI_OPERATOR_PRESENCE_PPI PEI_OPERATOR_PRESENCE_PPI;

 

 struct _PEI_OPERATOR_PRESENCE_PPI {

-  BOOLEAN                           OperatorPresent; /// TRUE if TPM Operator is detected.

+  BOOLEAN                           OperatorPresent; ///> TRUE if TPM Operator is detected.

 };

 

 extern EFI_GUID                     gPeiOperatorPresencePpiGuid;

diff --git a/MdeModulePkg/Library/DxePlatDriOverLib/PlatDriOverLib.c b/MdeModulePkg/Library/DxePlatDriOverLib/PlatDriOverLib.c
index f2aad41e7a..e9749d68d4 100644
--- a/MdeModulePkg/Library/DxePlatDriOverLib/PlatDriOverLib.c
+++ b/MdeModulePkg/Library/DxePlatDriOverLib/PlatDriOverLib.c
@@ -206,7 +206,7 @@ InitOverridesMapping (
       VariableIndex += ((sizeof(UINT32) - ((UINTN) (VariableIndex))) & (sizeof(UINT32) - 1));

 

       //

-      // Get all DriverDevicePath[]

+      // Get all DriverImageDevicePath[]

       //

       for (Index = 0; Index < DriverNumber; Index++) {

         //

@@ -240,10 +240,9 @@ InitOverridesMapping (
     // NotEnd indicates whether current variable is the end variable.

     //

     if (NotEnd != 0) {

-      UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", VariableNum);

+      UnicodeSPrint (OverrideVariableName, sizeof (OverrideVariableName), L"PlatDriOver%d", VariableNum++);

       VariableBuffer = GetVariableAndSize (OverrideVariableName, &gEfiOverrideVariableGuid, &BufferSize);

       ASSERT ((UINTN) VariableBuffer % sizeof(UINTN) == 0);

-      VariableNum++;

       if (VariableBuffer == NULL) {

         FreeMappingDatabase (MappingDataBase);

         return EFI_VOLUME_CORRUPTED;