Add comments for enumeration, structure data members those are referred by UefiServic...

[mirror_edk2.git] / MdePkg / Include / Pi / PiFirmwareFile.h

diff --git a/MdePkg/Include/Pi/PiFirmwareFile.h b/MdePkg/Include/Pi/PiFirmwareFile.h
index 65f47a59b450f00c5bb73157629a2cbc313adfe7..8d5dd336f91236cd85faf59b0b336cddd9438cf9 100644 (file)
--- a/MdePkg/Include/Pi/PiFirmwareFile.h
+++ b/MdePkg/Include/Pi/PiFirmwareFile.h
@@ -27,9 +27,27 @@
 /// \r
 typedef union {\r
   struct {\r
+    ///\r
+    /// The IntegrityCheck.Checksum.Header field is an 8-bit checksum of the file\r
+    /// header. The State and IntegrityCheck.Checksum.File fields are assumed\r
+    /// to be zero and the checksum is calculated such that the entire header sums to zero.\r
+    ///\r
     UINT8   Header;\r
+    ///\r
+    /// If the FFS_ATTRIB_CHECKSUM (see definition below) bit of the Attributes\r
+    /// field is set to one, the IntegrityCheck.Checksum.File field is an 8-bit\r
+    /// checksum of the entire file The State field and the file tail are assumed to be zero\r
+    /// and the checksum is calculated such that the entire file sums to zero.\r
+    /// If the FFS_ATTRIB_CHECKSUM bit of the Attributes field is cleared to zero,\r
+    /// the IntegrityCheck.Checksum.File field must be initialized with a value of\r
+    /// 0x55AA. The IntegrityCheck.Checksum.File field is valid any time the\r
+    /// EFI_FILE_DATA_VALID bit is set in the State field.\r
+    ///\r
     UINT8   File;\r
   } Checksum;\r
+  ///\r
+  /// This is the full 16 bits of the IntegrityCheck field.\r
+  ///\r
   UINT16    Checksum16;\r
 } EFI_FFS_INTEGRITY_CHECK;\r
 \r
@@ -81,11 +99,29 @@ typedef UINT8 EFI_FFS_FILE_STATE;
 /// contents and state of the files.\r
 /// \r
 typedef struct {\r
+  ///\r
+  /// This GUID is the file name. It is used to uniquely identify the file.\r
+  ///\r
   EFI_GUID                Name;\r
+  ///\r
+  /// Used to verify the integrity of the file.\r
+  ///\r
   EFI_FFS_INTEGRITY_CHECK IntegrityCheck;\r
+  ///\r
+  /// Identifies the type of file.\r
+  ///\r
   EFI_FV_FILETYPE         Type;\r
+  ///\r
+  /// Declares various file attribute bits.\r
+  ///\r
   EFI_FFS_FILE_ATTRIBUTES Attributes;\r
+  ///\r
+  /// The length of the file in bytes, including the FFS header.\r
+  ///\r
   UINT8                   Size[3];\r
+  ///\r
+  /// Used to track the state of the file throughout the life of the file from creation to deletion.\r
+  ///\r
   EFI_FFS_FILE_STATE      State;\r
 } EFI_FFS_FILE_HEADER;\r
 \r
@@ -125,8 +161,15 @@ typedef UINT8 EFI_SECTION_TYPE;
 /// Common section header\r
 /// \r
 typedef struct {\r
+  ///\r
+  /// A 24-bit unsigned integer that contains the total size of the section in bytes, \r
+  /// including the EFI_COMMON_SECTION_HEADER.\r
+  ///\r
   UINT8             Size[3];\r
   EFI_SECTION_TYPE  Type;\r
+  ///\r
+  /// Declares the section type.\r
+  ///\r
 } EFI_COMMON_SECTION_HEADER;\r
 \r
 ///\r
@@ -145,8 +188,17 @@ typedef EFI_COMMON_SECTION_HEADER EFI_COMPATIBILITY16_SECTION;
 /// section data is compressed.\r
 /// \r
 typedef struct {\r
+  ///\r
+  /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.\r
+  ///\r
   EFI_COMMON_SECTION_HEADER   CommonHeader;\r
+  ///\r
+  /// UINT32 that indicates the size of the section data after decompression.\r
+  ///\r
   UINT32                      UncompressedLength;\r
+  ///\r
+  /// Indicates which compression algorithm is used.\r
+  ///\r
   UINT8                       CompressionType;\r
 } EFI_COMPRESSION_SECTION;\r
 \r
@@ -164,7 +216,13 @@ typedef EFI_COMMON_SECTION_HEADER EFI_FIRMWARE_VOLUME_IMAGE_SECTION;
 /// Leaf section which contains a single GUID.\r
 /// \r
 typedef struct {\r
+  ///\r
+  /// Common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.\r
+  ///\r
   EFI_COMMON_SECTION_HEADER   CommonHeader;\r
+  ///\r
+  /// This GUID is defined by the creator of the file. It is a vendor-defined file type.\r
+  ///\r
   EFI_GUID                    SubTypeGuid;\r
 } EFI_FREEFORM_SUBTYPE_GUID_SECTION;\r
 \r
@@ -177,9 +235,21 @@ typedef struct {
 /// Leaf section which is encapsulation defined by specific GUID\r
 /// \r
 typedef struct {\r
+  ///\r
+  /// Common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.\r
+  ///\r
   EFI_COMMON_SECTION_HEADER   CommonHeader;\r
+  ///\r
+  /// GUID that defines the format of the data that follows. It is a vendor-defined section type.\r
+  ///\r
   EFI_GUID                    SectionDefinitionGuid;\r
+  ///\r
+  /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.\r
+  ///\r
   UINT16                      DataOffset;\r
+  ///\r
+  /// Bit field that declares some specific characteristics of the section contents.\r
+  ///\r
   UINT16                      Attributes;\r
 } EFI_GUID_DEFINED_SECTION;\r
 \r