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

diff --git a/IntelFrameworkPkg/Include/Guid/Capsule.h b/IntelFrameworkPkg/Include/Guid/Capsule.h
index dc9d2be42ba2df9a967605cf3329ed52139ddb4f..90c82cb20eba3417cbdff1170af8594c73d9a182 100644 (file)
--- a/IntelFrameworkPkg/Include/Guid/Capsule.h
+++ b/IntelFrameworkPkg/Include/Guid/Capsule.h
@@ -1,5 +1,5 @@
 /** @file\r
 /** @file\r

-  GUIDs used for EFI Capsule\r
+  Framework Capule related Definition.\r

 \r
   Copyright (c) 2007 - 2009, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r
 \r
   Copyright (c) 2007 - 2009, Intel Corporation\r
   All rights reserved. This program and the accompanying materials\r


@@ -10,11 +10,8 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r

-  Module Name:  Capsule.h\r
-\r

   @par Revision Reference:\r
   @par Revision Reference:\r

-  GUIDs defined in Capsule Spec Version 0.9\r
-\r
+  Capsule Spec Version 0.9\r

 **/\r
 \r
 #ifndef _CAPSULE_GUID_H__\r
 **/\r
 \r
 #ifndef _CAPSULE_GUID_H__\r


@@ -39,11 +36,11 @@
     0x98B8D59B, 0xE8BA, 0x48EE, {0x98, 0xDD, 0xC2, 0x95, 0x39, 0x2F, 0x1E, 0xDB } \\r
   }\r
 \r
     0x98B8D59B, 0xE8BA, 0x48EE, {0x98, 0xDD, 0xC2, 0x95, 0x39, 0x2F, 0x1E, 0xDB } \\r
   }\r
 \r

-//\r
-// Bits in the flags field of the capsule header\r
-//\r
-#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001  // supports setup changes\r
-\r
+///\r
+/// Bits in the flags field of the capsule header\r
+/// This flag is set if the capsule can support setup changes and clear if it cannot.\r
+///\r
+#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001\r

 \r
 #define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE  SIGNATURE_32 ('C', 'B', 'D', 'S')\r
 \r
 \r
 #define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE  SIGNATURE_32 ('C', 'B', 'D', 'S')\r
 \r


@@ -67,19 +64,82 @@ typedef struct {
 } EFI_CAPSULE_OEM_HEADER;\r
 \r
 typedef struct {\r
 } EFI_CAPSULE_OEM_HEADER;\r
 \r
 typedef struct {\r

+  ///\r
+  /// A defined GUID that indicates the start of a capsule.\r
+  ///\r

   EFI_GUID  CapsuleGuid;\r
   EFI_GUID  CapsuleGuid;\r

+  ///\r
+  /// The size of the EFI_CAPSULE_HEADER structure.\r
+  ///\r

   UINT32    HeaderSize;\r
   UINT32    HeaderSize;\r

+  ///\r
+  /// A bit-mapped list describing the capsule¡¯s attributes. \r
+  /// All undefined bits should be written as zero (0)\r
+  ///\r

   UINT32    Flags;\r
   UINT32    Flags;\r

+  ///\r
+  /// The length in bytes (27,415 for an image containing 27,415 bytes) of the entire image\r
+  /// including all headers. If the this value is greater than the size of the data presented in\r
+  /// the capsule body, this means that the image is separated across multiple media. If this\r
+  /// value is less than the size of the data, it is an error.\r
+  ///\r

   UINT32    CapsuleImageSize;\r
   UINT32    CapsuleImageSize;\r

+  ///\r
+  /// A zero-based number that enables a capsule to be split into pieces and then\r
+  /// recombined for easier transfer across media with limited size. The lower the\r
+  /// SequenceNumber, the earlier in the final image that the part of the capsule is to\r
+  /// appear. In capsules that are not split, this value shall be zero.\r
+  ///\r

   UINT32    SequenceNumber;\r
   UINT32    SequenceNumber;\r

+  ///\r
+  /// Used to group the various pieces of a split capsule to ensure that they comprise the\r
+  /// same base image. It is valid for this item to be zero, in which case the capsule cannot\r
+  /// be split into components.\r
+  ///\r

   EFI_GUID  InstanceId;\r
   EFI_GUID  InstanceId;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of an EFI string that\r
+  /// contains a description of the identity of the subcapsules that make up the capsule. If\r
+  /// the capsule is not split, this value should be zero. The same string should be\r
+  /// presented for all subcapsules that constitute the same capsule.\r
+  ///\r

   UINT32    OffsetToSplitInformation;\r
   UINT32    OffsetToSplitInformation;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of the part of the\r
+  /// capsule that is to be transferred to DXE.\r
+  ///\r

   UINT32    OffsetToCapsuleBody;\r
   UINT32    OffsetToCapsuleBody;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of the OEM-defined\r
+  /// header. This value must be less than OffsetToCapsuleBody.\r
+  ///\r

   UINT32    OffsetToOemDefinedHeader;\r
   UINT32    OffsetToOemDefinedHeader;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of human-readable\r
+  /// text that describes the entity that created the capsule. This value must be less than OffsetToCapsuleBody.\r
+  ///\r

   UINT32    OffsetToAuthorInformation;\r
   UINT32    OffsetToAuthorInformation;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of human-readable\r
+  /// text that describes the revision of the capsule and/or the capsule¡¯s contents. This\r
+  /// value must be less than OffsetToCapsuleBody.\r
+  ///\r

   UINT32    OffsetToRevisionInformation;\r
   UINT32    OffsetToRevisionInformation;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of a one-line (less\r
+  /// than 40 Unicode characters in any language) description of the capsule. It is intended\r
+  /// to be used by OS-present applications when providing a list of capsules from which\r
+  /// the user can choose. This value must be less than OffsetToCapsuleBody.\r
+  ///\r

   UINT32    OffsetToShortDescription;\r
   UINT32    OffsetToShortDescription;\r

+  ///\r
+  /// The offset in bytes from the beginning of the header to the start of an EFI string\r
+  ///\r

   UINT32    OffsetToLongDescription;\r
   UINT32    OffsetToLongDescription;\r

+  ///\r
+  /// This field is reserved for future use by this specification. For future compatibility,\r
+  /// this field must be set to zero\r
+  ///\r

   UINT32    OffsetToApplicableDevices;\r
 } FRAMEWORK_EFI_CAPSULE_HEADER;\r
 \r
   UINT32    OffsetToApplicableDevices;\r
 } FRAMEWORK_EFI_CAPSULE_HEADER;\r
 \r

diff --git a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h
index 53e3d387cc739ede00b2347b7a269c3437397109..6ba75b7fc1fafd29f6f0ba1581728f61732338fc 100644 (file)
--- 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.\r
 **/\r
 struct _EFI_PEI_SECTION_EXTRACTION_PPI {\r
   authenticate the file encapsulation of other domain-specific wrapping.\r
 **/\r
 struct _EFI_PEI_SECTION_EXTRACTION_PPI {\r

-  EFI_PEI_GET_SECTION PeiGetSection;  ///< Retrieves a section from within a section file.\r
+  EFI_PEI_GET_SECTION GetSection;  ///< Retrieves a section from within a section file.\r

 };\r
 \r
 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;\r
 };\r
 \r
 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;\r

diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h
index e42459dd902f7953aeb581abb139359696a942e5..d762ad48d0c8fe4fa08f06573cd1fbee2869b483 100644 (file)
--- 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,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r

-  Module Name:  FrameworkFormCallback.h\r
-\r

   @par Revision Reference:\r
   This protocol is defined in HII spec 0.92.\r
 \r
   @par Revision Reference:\r
   This protocol is defined in HII spec 0.92.\r
 \r


@@ -39,32 +37,26 @@
 //\r
 typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;\r
 \r
 //\r
 typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;\r
 \r

-\r
-#define RESET_REQUIRED  1 // Flags setting to signify that the callback operation resulted in an eventual\r
-// reset to be done upon exit of the browser\r
-//\r
-#define EXIT_REQUIRED   2   // Flags setting to signify that after the processing of the callback results - exit the browser\r
-#define SAVE_REQUIRED   4   // Flags setting to signify that after the processing of the callback results - save the NV data\r
-#define NV_CHANGED      8   // Flags setting to signify that after the processing of the callback results - turn the NV flag on\r
-#define NV_NOT_CHANGED  16  // Flags setting to signify that after the processing of the callback results - turn the NV flag off\r

 #pragma pack(1)\r
 typedef struct {\r
 #pragma pack(1)\r
 typedef struct {\r

-  UINT8   OpCode;           // Likely a string, numeric, or one-of\r
-  UINT8   Length;           // Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet\r
-  UINT16  Flags;            // Flags settings to determine what behavior is desired from the browser after the callback\r
-  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\r
-  // If the OpCode is a OneOf or Numeric type - Data is a UINT16 value\r
-  // If the OpCode is a String type - Data is a CHAR16[x] type\r
-  // If the OpCode is a Checkbox type - Data is a UINT8 value\r
-  // If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure\r
-  //\r
+  UINT8   OpCode;           ///< Likely a string, numeric, or one-of\r
+  UINT8   Length;           ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet\r
+  UINT16  Flags;            ///< Flags settings to determine what behavior is desired from the browser after the callback\r
+  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\r
+  ///\r
+  /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value\r
+  /// If the OpCode is a String type - Data is a CHAR16[x] type\r
+  /// If the OpCode is a Checkbox type - Data is a UINT8 value\r
+  /// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure\r
+  ///\r

 } FRAMEWORK_EFI_IFR_DATA_ENTRY;\r
 \r
 typedef struct {\r
 } FRAMEWORK_EFI_IFR_DATA_ENTRY;\r
 \r
 typedef struct {\r

-  VOID                *NvRamMap;  // If the flag of the op-code specified retrieval of a copy of the NVRAM map,\r
+  VOID                *NvRamMap;  ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map,\r
+  //\r

   // this is a pointer to a buffer copy\r
   //\r
   // this is a pointer to a buffer copy\r
   //\r

-  UINT32              EntryCount; // How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries\r
+  UINT32              EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries\r

   //\r
   // FRAMEWORK_EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.\r
   //\r
   //\r
   // FRAMEWORK_EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.\r
   //\r


@@ -72,15 +64,15 @@ typedef struct {
 \r
 \r
 typedef union {\r
 \r
 \r
 typedef union {\r

-  FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  // Primarily used by those who call back to their drivers and use HII as a repository\r
-  FRAMEWORK_EFI_IFR_PACKET      DataPacket; // Primarily used by those which do not use HII as a repository\r
-  CHAR16                        String[1];  // If returning an error - fill the string with null-terminated contents\r
-} EFI_HII_CALLBACK_PACKET;\r
+  FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  ///< Primarily used by those who call back to their drivers and use HII as a repository\r
+  FRAMEWORK_EFI_IFR_PACKET      DataPacket; ///< Primarily used by those which do not use HII as a repository\r
+  CHAR16                        String[1];  ///< If returning an error - fill the string with null-terminated contents\r
+} FRAMEWORK_EFI_HII_CALLBACK_PACKET;\r

 \r
 typedef struct {\r
   FRAMEWORK_EFI_IFR_OP_HEADER Header;\r
 \r
 typedef struct {\r
   FRAMEWORK_EFI_IFR_OP_HEADER Header;\r

-  UINT16            QuestionId;   // Offset into the map\r
-  UINT8             StorageWidth; // Width of the value\r
+  UINT16            QuestionId;   ///< Offset into the map\r
+  UINT8             StorageWidth; ///< Width of the value\r

   //\r
   // CHAR8             Data[1];      // The Data itself\r
   //\r
   //\r
   // CHAR8             Data[1];      // The Data itself\r
   //\r


@@ -179,7 +171,7 @@ EFI_STATUS
   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
   IN     UINT16                        KeyValue,\r
   IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,\r
   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
   IN     UINT16                        KeyValue,\r
   IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,\r

-  OUT    EFI_HII_CALLBACK_PACKET       **Packet\r
+  OUT    FRAMEWORK_EFI_HII_CALLBACK_PACKET       **Packet\r

   );\r
 \r
 /**\r
   );\r
 \r
 /**\r