1. add some comments for structures

[mirror_edk2.git] / MdePkg / Include / IndustryStandard / PeImage.h

diff --git a/MdePkg/Include/IndustryStandard/PeImage.h b/MdePkg/Include/IndustryStandard/PeImage.h
index fc01e78273e2b88795fb50aa58b43d9a017810b2..97a17e5eb5fcf0ce469b6d0e4ba4bcd8730d2d48 100644 (file)
--- a/MdePkg/Include/IndustryStandard/PeImage.h
+++ b/MdePkg/Include/IndustryStandard/PeImage.h
@@ -21,9 +21,9 @@
 #ifndef __PE_IMAGE_H__\r
 #define __PE_IMAGE_H__\r
 \r
-///\r
-/// PE32+ Subsystem type for EFI images\r
-///\r
+//\r
+// PE32+ Subsystem type for EFI images\r
+//\r
 #define EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION         10\r
 #define EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER 11\r
 #define EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER      12\r
@@ -32,9 +32,9 @@
 #define EFI_IMAGE_SUBSYSTEM_SAL_RUNTIME_DRIVER      13 ///< defined PI Specification, 1.0\r
 \r
 \r
-///\r
-/// PE32+ Machine type for EFI images\r
-///\r
+//\r
+// PE32+ Machine type for EFI images\r
+//\r
 #define IMAGE_FILE_MACHINE_I386     0x014c\r
 #define IMAGE_FILE_MACHINE_IA64     0x0200\r
 #define IMAGE_FILE_MACHINE_EBC      0x0EBC\r
@@ -48,9 +48,9 @@
 #define EFI_IMAGE_MACHINE_EBC       IMAGE_FILE_MACHINE_EBC  \r
 #define EFI_IMAGE_MACHINE_X64       IMAGE_FILE_MACHINE_X64\r
 \r
-///\r
-/// EXE file formats\r
-///\r
+//\r
+// EXE file formats\r
+//\r
 #define EFI_IMAGE_DOS_SIGNATURE     SIGNATURE_16('M', 'Z')\r
 #define EFI_IMAGE_OS2_SIGNATURE     SIGNATURE_16('N', 'E')\r
 #define EFI_IMAGE_OS2_SIGNATURE_LE  SIGNATURE_16('L', 'E')\r
@@ -100,9 +100,9 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_FILE_HEADER        20\r
 \r
-///\r
-/// Characteristics\r
-///\r
+//\r
+// Characteristics\r
+//\r
 #define EFI_IMAGE_FILE_RELOCS_STRIPPED      BIT0     ///< 0x0001  Relocation info stripped from file.\r
 #define EFI_IMAGE_FILE_EXECUTABLE_IMAGE     BIT1     ///< 0x0002  File is executable  (i.e. no unresolved externel references).\r
 #define EFI_IMAGE_FILE_LINE_NUMS_STRIPPED   BIT2     ///< 0x0004  Line nunbers stripped from file.\r
@@ -114,9 +114,9 @@ typedef struct {
 #define EFI_IMAGE_FILE_DLL                  BIT13    ///< 0x2000  File is a DLL.\r
 #define EFI_IMAGE_FILE_BYTES_REVERSED_HI    BIT15    ///< 0x8000  Bytes of machine word are reversed.\r
 \r
-///\r
-/// Other Machine Types\r
-///\r
+//\r
+// Other Machine Types\r
+//\r
 #define EFI_IMAGE_FILE_MACHINE_UNKNOWN      0       ///< Any machine type\r
 #define EFI_IMAGE_FILE_MACHINE_I386         0x14c   ///< Intel 386.\r
 #define EFI_IMAGE_FILE_MACHINE_R3000        0x162   ///< MIPS* little-endian, 0540 big-endian\r
@@ -136,9 +136,9 @@ typedef struct {
 \r
 #define EFI_IMAGE_ROM_OPTIONAL_HDR_MAGIC      0x107\r
 \r
-///\r
-/// Directory Entries\r
-///\r
+//\r
+// Directory Entries\r
+//\r
 #define EFI_IMAGE_DIRECTORY_ENTRY_EXPORT      0\r
 #define EFI_IMAGE_DIRECTORY_ENTRY_IMPORT      1\r
 #define EFI_IMAGE_DIRECTORY_ENTRY_RESOURCE    2\r
@@ -160,7 +160,10 @@ typedef struct {
 /// after NT additional fields.\r
 ///\r
 #define EFI_IMAGE_NT_OPTIONAL_HDR32_MAGIC 0x10b\r
-\r
+          \r
+///\r
+/// Optional Header Standard Fields for PE32\r
+///\r
 typedef struct {\r
   ///\r
   /// Standard fields.\r
@@ -175,7 +178,7 @@ typedef struct {
   UINT32                    BaseOfCode;\r
   UINT32                    BaseOfData;  ///< PE32 contains this additional field, which is absent in PE32+\r
   ///\r
-  /// NT additional fields.\r
+  /// Optional Header Windows-Specific Fields.\r
   ///\r
   UINT32                    ImageBase;\r
   UINT32                    SectionAlignment;\r
@@ -209,10 +212,13 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_NT_OPTIONAL_HDR64_MAGIC 0x20b\r
 \r
+///\r
+/// Optional Header Standard Fields for PE32+\r
+///\r
 typedef struct {\r
-  //\r
-  // Standard fields.\r
-  //\r
+  ///\r
+  /// Standard fields.\r
+  ///\r
   UINT16                    Magic;\r
   UINT8                     MajorLinkerVersion;\r
   UINT8                     MinorLinkerVersion;\r
@@ -221,9 +227,9 @@ typedef struct {
   UINT32                    SizeOfUninitializedData;\r
   UINT32                    AddressOfEntryPoint;\r
   UINT32                    BaseOfCode;\r
-  //\r
-  // NT additional fields.\r
-  //\r
+  ///\r
+  /// Optional Header Windows-Specific Fields.\r
+  ///\r
   UINT64                    ImageBase;\r
   UINT32                    SectionAlignment;\r
   UINT32                    FileAlignment;\r
@@ -331,9 +337,9 @@ typedef EFI_IMAGE_NT_HEADERS64    EFI_IMAGE_NT_HEADERS;
         ) \\r
     )\r
 \r
-///\r
-/// Other Windows Subsystem Values\r
-///\r
+//\r
+// Other Windows Subsystem Values\r
+//\r
 #define EFI_IMAGE_SUBSYSTEM_UNKNOWN     0\r
 #define EFI_IMAGE_SUBSYSTEM_NATIVE      1\r
 #define EFI_IMAGE_SUBSYSTEM_WINDOWS_GUI 2\r
@@ -346,6 +352,9 @@ typedef EFI_IMAGE_NT_HEADERS64    EFI_IMAGE_NT_HEADERS;
 ///\r
 #define EFI_IMAGE_SIZEOF_SHORT_NAME 8\r
 \r
+///\r
+/// Section Table, this table immediately follows the optional header\r
+///\r
 typedef struct {\r
   UINT8 Name[EFI_IMAGE_SIZEOF_SHORT_NAME];\r
   union {\r
@@ -367,9 +376,9 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_SECTION_HEADER       40\r
          \r
-///\r
-/// Section Flags Values\r
-///\r
+//\r
+// Section Flags Values\r
+//\r
 #define EFI_IMAGE_SCN_TYPE_NO_PAD                  BIT3   ///< 0x00000008  ///< Reserved.\r
 #define EFI_IMAGE_SCN_CNT_CODE                     BIT5   ///< 0x00000020\r
 #define EFI_IMAGE_SCN_CNT_INITIALIZED_DATA         BIT6   ///< 0x00000040\r
@@ -401,17 +410,17 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_SYMBOL 18\r
 \r
-///\r
-/// Symbols have a section number of the section in which they are\r
-/// defined. Otherwise, section numbers have the following meanings:\r
-///\r
+//\r
+// Symbols have a section number of the section in which they are\r
+// defined. Otherwise, section numbers have the following meanings:\r
+//\r
 #define EFI_IMAGE_SYM_UNDEFINED (UINT16) 0  ///< Symbol is undefined or is common.\r
 #define EFI_IMAGE_SYM_ABSOLUTE  (UINT16) -1 ///< Symbol is an absolute value.\r
 #define EFI_IMAGE_SYM_DEBUG     (UINT16) -2 ///< Symbol is a special debug item.\r
 \r
-///\r
-/// Symbol Type (fundamental) values.\r
-///\r
+//\r
+// Symbol Type (fundamental) values.\r
+//\r
 #define EFI_IMAGE_SYM_TYPE_NULL   0   ///< no type.\r
 #define EFI_IMAGE_SYM_TYPE_VOID   1   ///< no valid type.\r
 #define EFI_IMAGE_SYM_TYPE_CHAR   2   ///< type character.\r
@@ -429,17 +438,17 @@ typedef struct {
 #define EFI_IMAGE_SYM_TYPE_UINT   14\r
 #define EFI_IMAGE_SYM_TYPE_DWORD  15\r
 \r
-///\r
-/// Symbol Type (derived) values.\r
-///\r
+//\r
+// Symbol Type (derived) values.\r
+//\r
 #define EFI_IMAGE_SYM_DTYPE_NULL      0 ///< no derived type.\r
 #define EFI_IMAGE_SYM_DTYPE_POINTER   1\r
 #define EFI_IMAGE_SYM_DTYPE_FUNCTION  2\r
 #define EFI_IMAGE_SYM_DTYPE_ARRAY     3\r
 \r
-///\r
-/// Storage classes.\r
-///\r
+//\r
+// Storage classes.\r
+//\r
 #define EFI_IMAGE_SYM_CLASS_END_OF_FUNCTION   ((UINT8) -1)\r
 #define EFI_IMAGE_SYM_CLASS_NULL              0\r
 #define EFI_IMAGE_SYM_CLASS_AUTOMATIC         1\r
@@ -477,18 +486,18 @@ typedef struct {
 #define EFI_IMAGE_N_BTSHFT  4\r
 #define EFI_IMAGE_N_TSHIFT  2\r
 \r
-///\r
-/// Communal selection types.\r
-///\r
+//\r
+// Communal selection types.\r
+//\r
 #define EFI_IMAGE_COMDAT_SELECT_NODUPLICATES    1\r
 #define EFI_IMAGE_COMDAT_SELECT_ANY             2\r
 #define EFI_IMAGE_COMDAT_SELECT_SAME_SIZE       3\r
 #define EFI_IMAGE_COMDAT_SELECT_EXACT_MATCH     4\r
 #define EFI_IMAGE_COMDAT_SELECT_ASSOCIATIVE     5\r
                                        \r
-///\r
-/// the following values only be referred in PeCoff, not defined in PECOFF.\r
-///\r
+//\r
+// the following values only be referred in PeCoff, not defined in PECOFF.\r
+//\r
 #define EFI_IMAGE_WEAK_EXTERN_SEARCH_NOLIBRARY  1\r
 #define EFI_IMAGE_WEAK_EXTERN_SEARCH_LIBRARY    2\r
 #define EFI_IMAGE_WEAK_EXTERN_SEARCH_ALIAS      3\r
@@ -507,9 +516,9 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_RELOCATION 10\r
 \r
-///\r
-/// I386 relocation types.\r
-///\r
+//\r
+// I386 relocation types.\r
+//\r
 #define EFI_IMAGE_REL_I386_ABSOLUTE 0x0000  ///< Reference is absolute, no relocation is necessary\r
 #define EFI_IMAGE_REL_I386_DIR16    0x0001  ///< Direct 16-bit reference to the symbols virtual address\r
 #define EFI_IMAGE_REL_I386_REL16    0x0002  ///< PC-relative 16-bit reference to the symbols virtual address\r
@@ -520,9 +529,9 @@ typedef struct {
 #define EFI_IMAGE_REL_I386_SECREL   0x000B\r
 #define EFI_IMAGE_REL_I386_REL32    0x0014  ///< PC-relative 32-bit reference to the symbols virtual address\r
 \r
-/// \r
-/// x64 processor relocation types.\r
-/// \r
+// \r
+// x64 processor relocation types.\r
+// \r
 #define IMAGE_REL_AMD64_ABSOLUTE  0x0000\r
 #define IMAGE_REL_AMD64_ADDR64    0x0001\r
 #define IMAGE_REL_AMD64_ADDR32    0x0002\r
@@ -554,9 +563,9 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_BASE_RELOCATION  8\r
 \r
-///\r
-/// Based relocation types.\r
-///\r
+//\r
+// Based relocation types.\r
+//\r
 #define EFI_IMAGE_REL_BASED_ABSOLUTE      0\r
 #define EFI_IMAGE_REL_BASED_HIGH          1\r
 #define EFI_IMAGE_REL_BASED_LOW           2\r
@@ -583,9 +592,9 @@ typedef struct {
 ///\r
 #define EFI_IMAGE_SIZEOF_LINENUMBER 6\r
 \r
-///\r
-/// Archive format.\r
-///\r
+//\r
+// Archive format.\r
+//\r
 #define EFI_IMAGE_ARCHIVE_START_SIZE        8\r
 #define EFI_IMAGE_ARCHIVE_START             "!<arch>\n"\r
 #define EFI_IMAGE_ARCHIVE_END               "`\n"\r
@@ -593,6 +602,9 @@ typedef struct {
 #define EFI_IMAGE_ARCHIVE_LINKER_MEMBER     "/               "\r
 #define EFI_IMAGE_ARCHIVE_LONGNAMES_MEMBER  "//              "\r
 \r
+///\r
+/// Archive Member Headers\r
+///\r
 typedef struct {\r
   UINT8 Name[16];     ///< File member name - `/' terminated.\r
   UINT8 Date[12];     ///< File member date - decimal.\r
@@ -609,9 +621,9 @@ typedef struct {
 #define EFI_IMAGE_SIZEOF_ARCHIVE_MEMBER_HDR 60\r
 \r
 \r
-///\r
-/// DLL Support\r
-///\r
+//\r
+// DLL Support\r
+//\r
 \r
 ///\r
 /// Export Directory Table\r
@@ -638,6 +650,9 @@ typedef struct {
   UINT8   Name[1];\r
 } EFI_IMAGE_IMPORT_BY_NAME;\r
 \r
+///\r
+/// Import Address Table RVA (Thunk Table)\r
+///\r
 typedef struct {\r
   union {\r
     UINT32                    Function;\r