Update code comments according to intel framework specification.

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

IntelFrameworkPkg/Include/Guid/Capsule.h

@@ -1,5 +1,5 @@
 /** @file
-  GUIDs used for EFI Capsule
+  Framework Capule related Definition.
 
   Copyright (c) 2007 - 2009, Intel Corporation
   All rights reserved. This program and the accompanying materials
@@ -10,11 +10,8 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-  Module Name:  Capsule.h
-
   @par Revision Reference:
-  GUIDs defined in Capsule Spec Version 0.9
+  Capsule Spec Version 0.9
-
 **/
 
 #ifndef _CAPSULE_GUID_H__
@@ -39,11 +36,11 @@
     0x98B8D59B, 0xE8BA, 0x48EE, {0x98, 0xDD, 0xC2, 0x95, 0x39, 0x2F, 0x1E, 0xDB } \
   }
 
-//
+///
-// Bits in the flags field of the capsule header
+/// Bits in the flags field of the capsule header
-//
+/// This flag is set if the capsule can support setup changes and clear if it cannot.
-#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001  // supports setup changes
+///
-
+#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001
 
 #define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE  SIGNATURE_32 ('C', 'B', 'D', 'S')
 
@@ -67,19 +64,82 @@ typedef struct {
 } EFI_CAPSULE_OEM_HEADER;
 
 typedef struct {
+  ///
+  /// A defined GUID that indicates the start of a capsule.
+  ///
   EFI_GUID  CapsuleGuid;
+  ///
+  /// The size of the EFI_CAPSULE_HEADER structure.
+  ///
   UINT32    HeaderSize;
+  ///
+  /// A bit-mapped list describing the capsule<6C><65>s attributes. 
+  /// All undefined bits should be written as zero (0)
+  ///
   UINT32    Flags;
+  ///
+  /// The length in bytes (27,415 for an image containing 27,415 bytes) of the entire image
+  /// including all headers. If the this value is greater than the size of the data presented in
+  /// the capsule body, this means that the image is separated across multiple media. If this
+  /// value is less than the size of the data, it is an error.
+  ///
   UINT32    CapsuleImageSize;
+  ///
+  /// A zero-based number that enables a capsule to be split into pieces and then
+  /// recombined for easier transfer across media with limited size. The lower the
+  /// SequenceNumber, the earlier in the final image that the part of the capsule is to
+  /// appear. In capsules that are not split, this value shall be zero.
+  ///
   UINT32    SequenceNumber;
+  ///
+  /// Used to group the various pieces of a split capsule to ensure that they comprise the
+  /// same base image. It is valid for this item to be zero, in which case the capsule cannot
+  /// be split into components.
+  ///
   EFI_GUID  InstanceId;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of an EFI string that
+  /// contains a description of the identity of the subcapsules that make up the capsule. If
+  /// the capsule is not split, this value should be zero. The same string should be
+  /// presented for all subcapsules that constitute the same capsule.
+  ///
   UINT32    OffsetToSplitInformation;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of the part of the
+  /// capsule that is to be transferred to DXE.
+  ///
   UINT32    OffsetToCapsuleBody;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of the OEM-defined
+  /// header. This value must be less than OffsetToCapsuleBody.
+  ///
   UINT32    OffsetToOemDefinedHeader;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of human-readable
+  /// text that describes the entity that created the capsule. This value must be less than OffsetToCapsuleBody.
+  ///
   UINT32    OffsetToAuthorInformation;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of human-readable
+  /// text that describes the revision of the capsule and/or the capsule<6C><65>s contents. This
+  /// value must be less than OffsetToCapsuleBody.
+  ///
   UINT32    OffsetToRevisionInformation;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of a one-line (less
+  /// than 40 Unicode characters in any language) description of the capsule. It is intended
+  /// to be used by OS-present applications when providing a list of capsules from which
+  /// the user can choose. This value must be less than OffsetToCapsuleBody.
+  ///
   UINT32    OffsetToShortDescription;
+  ///
+  /// The offset in bytes from the beginning of the header to the start of an EFI string
+  ///
   UINT32    OffsetToLongDescription;
+  ///
+  /// This field is reserved for future use by this specification. For future compatibility,
+  /// this field must be set to zero
+  ///
   UINT32    OffsetToApplicableDevices;
 } FRAMEWORK_EFI_CAPSULE_HEADER;
 

IntelFrameworkPkg/Include/Ppi/SectionExtraction.h

@@ -99,7 +99,7 @@ EFI_STATUS
   authenticate the file encapsulation of other domain-specific wrapping.
 **/
 struct _EFI_PEI_SECTION_EXTRACTION_PPI {
-  EFI_PEI_GET_SECTION PeiGetSection;  ///< Retrieves a section from within a section file.
+  EFI_PEI_GET_SECTION GetSection;  ///< Retrieves a section from within a section file.
 };
 
 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;

IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h

@@ -14,8 +14,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-  Module Name:  FrameworkFormCallback.h
-
   @par Revision Reference:
   This protocol is defined in HII spec 0.92.
 
@@ -39,32 +37,26 @@
 //
 typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;
 
-
-#define RESET_REQUIRED  1 // Flags setting to signify that the callback operation resulted in an eventual
-// reset to be done upon exit of the browser
-//
-#define EXIT_REQUIRED   2   // Flags setting to signify that after the processing of the callback results - exit the browser
-#define SAVE_REQUIRED   4   // Flags setting to signify that after the processing of the callback results - save the NV data
-#define NV_CHANGED      8   // Flags setting to signify that after the processing of the callback results - turn the NV flag on
-#define NV_NOT_CHANGED  16  // Flags setting to signify that after the processing of the callback results - turn the NV flag off
 #pragma pack(1)
 typedef struct {
-  UINT8   OpCode;           // Likely a string, numeric, or one-of
+  UINT8   OpCode;           ///< Likely a string, numeric, or one-of
-  UINT8   Length;           // Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet
+  UINT8   Length;           ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet
-  UINT16  Flags;            // Flags settings to determine what behavior is desired from the browser after the callback
+  UINT16  Flags;            ///< Flags settings to determine what behavior is desired from the browser after the callback
-  VOID    *Data;            // The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately
+  VOID    *Data;            ///< The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately
-  // If the OpCode is a OneOf or Numeric type - Data is a UINT16 value
+  ///
-  // If the OpCode is a String type - Data is a CHAR16[x] type
+  /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value
-  // If the OpCode is a Checkbox type - Data is a UINT8 value
+  /// If the OpCode is a String type - Data is a CHAR16[x] type
-  // If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure
+  /// If the OpCode is a Checkbox type - Data is a UINT8 value
-  //
+  /// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure
+  ///
 } FRAMEWORK_EFI_IFR_DATA_ENTRY;
 
 typedef struct {
-  VOID                *NvRamMap;  // If the flag of the op-code specified retrieval of a copy of the NVRAM map,
+  VOID                *NvRamMap;  ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map,
+  //
   // this is a pointer to a buffer copy
   //
-  UINT32              EntryCount; // How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries
+  UINT32              EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries
   //
   // FRAMEWORK_EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.
   //
@@ -72,15 +64,15 @@ typedef struct {
 
 
 typedef union {
-  FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  // Primarily used by those who call back to their drivers and use HII as a repository
+  FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  ///< Primarily used by those who call back to their drivers and use HII as a repository
-  FRAMEWORK_EFI_IFR_PACKET      DataPacket; // Primarily used by those which do not use HII as a repository
+  FRAMEWORK_EFI_IFR_PACKET      DataPacket; ///< Primarily used by those which do not use HII as a repository
-  CHAR16                        String[1];  // If returning an error - fill the string with null-terminated contents
+  CHAR16                        String[1];  ///< If returning an error - fill the string with null-terminated contents
-} EFI_HII_CALLBACK_PACKET;
+} FRAMEWORK_EFI_HII_CALLBACK_PACKET;
 
 typedef struct {
   FRAMEWORK_EFI_IFR_OP_HEADER Header;
-  UINT16            QuestionId;   // Offset into the map
+  UINT16            QuestionId;   ///< Offset into the map
-  UINT8             StorageWidth; // Width of the value
+  UINT8             StorageWidth; ///< Width of the value
   //
   // CHAR8             Data[1];      // The Data itself
   //
@@ -179,7 +171,7 @@ EFI_STATUS
   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,
   IN     UINT16                        KeyValue,
   IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,
-  OUT    EFI_HII_CALLBACK_PACKET       **Packet
+  OUT    FRAMEWORK_EFI_HII_CALLBACK_PACKET       **Packet
   );
 
 /**