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

3 files changed, 91 insertions, 39 deletions

diff --git a/IntelFrameworkPkg/Include/Guid/Capsule.h b/IntelFrameworkPkg/Include/Guid/Capsule.h
index dc9d2be42b..90c82cb20e 100644
--- a/IntelFrameworkPkg/Include/Guid/Capsule.h
+++ b/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

-//

-#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001  // supports setup changes

-

+///

+/// 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

 

 #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¡¯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¡¯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;

 

diff --git a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h
index 53e3d387cc..6ba75b7fc1 100644
--- a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h
+++ b/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;

diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
index e42459dd90..d762ad48d0 100644
--- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
+++ b/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   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

-  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 Checkbox type - Data is a UINT8 value

-  // If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure

-  //

+  UINT8   OpCode;           ///< Likely a string, numeric, or one-of

+  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

+  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 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_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

-} EFI_HII_CALLBACK_PACKET;

+  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

+  CHAR16                        String[1];  ///< If returning an error - fill the string with null-terminated contents

+} FRAMEWORK_EFI_HII_CALLBACK_PACKET;

 

 typedef struct {

   FRAMEWORK_EFI_IFR_OP_HEADER Header;

-  UINT16            QuestionId;   // Offset into the map

-  UINT8             StorageWidth; // Width of the value

+  UINT16            QuestionId;   ///< Offset into the map

+  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

   );

 

 /**