Add comments for enumeration, structure data members those are referred by UefiService, Runtime Service, Dxe Service and Pei Service.

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

MdePkg/Include/IndustryStandard/Tpm12.h

@@ -151,7 +151,7 @@ typedef UINT32                      TPM_KEY_CONTROL;
 ///
 typedef UINT32                      TPM_NV_INDEX;
 ///
-/// The family ID. Families ID¡¯s are automatically assigned a sequence number by the TPM. 
+/// The family ID. Families ID's are automatically assigned a sequence number by the TPM. 
 /// A trusted process can set the FamilyID value in an individual row to NULL, which 
 /// invalidates that row. The family ID resets to NULL on each change of TPM Owner.
 ///

MdePkg/Include/Pi/PiDxeCis.h

@@ -24,9 +24,28 @@
 /// Global Coherencey Domain types - Memory type
 ///
 typedef enum {
+  ///
+  /// A memory region that is visible to the boot processor. However, there are no system
+  /// components that are currently decoding this memory region.
+  ///
   EfiGcdMemoryTypeNonExistent,
+  ///
+  /// A memory region that is visible to the boot processor. This memory region is being
+  /// decoded by a system component, but the memory region is not considered to be either
+  /// system memory or memory-mapped I/O.
+  ///
   EfiGcdMemoryTypeReserved,
+  ///
+  /// A memory region that is visible to the boot processor. A memory controller is
+  /// currently decoding this memory region and the memory controller is producing a
+  /// tested system memory region that is available to the memory services.
+  ///
   EfiGcdMemoryTypeSystemMemory,
+  ///
+  /// A memory region that is visible to the boot processor. This memory region is
+  /// currently being decoded by a component as memory-mapped I/O that can be used to
+  /// access I/O devices in the platform.
+  ///
   EfiGcdMemoryTypeMemoryMappedIo,
   EfiGcdMemoryTypeMaximum
 } EFI_GCD_MEMORY_TYPE;
@@ -35,8 +54,20 @@ typedef enum {
 /// Global Coherencey Domain types - IO type
 ///
 typedef enum {
+  ///
+  /// An I/O region that is visible to the boot processor. However, there are no system
+  /// components that are currently decoding this I/O region.
+  ///
   EfiGcdIoTypeNonExistent,
+  ///
+  /// An I/O region that is visible to the boot processor. This I/O region is currently being
+  /// decoded by a system component, but the I/O region cannot be used to access I/O devices.
+  ///
   EfiGcdIoTypeReserved,
+  ///
+  /// An I/O region that is visible to the boot processor. This I/O region is currently being
+  /// decoded by a system component that is producing I/O ports that can be used to access I/O devices.
+  ///
   EfiGcdIoTypeIo,
   EfiGcdIoTypeMaximum
 } EFI_GCD_IO_TYPE;
@@ -45,10 +76,30 @@ typedef enum {
 /// The type of allocation to perform.
 /// 
 typedef enum {
+  ///
+  /// The GCD memory space map is searched from the lowest address up to the highest address
+  /// looking for unallocated memory ranges.
+  ///
   EfiGcdAllocateAnySearchBottomUp,
+  ///
+  /// The GCD memory space map is searched from the lowest address up 
+  /// to the specified MaxAddress looking for unallocated memory ranges.
+  ///
   EfiGcdAllocateMaxAddressSearchBottomUp,
+  ///
+  /// The GCD memory space map is checked to see if the memory range starting 
+  /// at the specified Address is available.
+  ///
   EfiGcdAllocateAddress,
+  ///
+  /// The GCD memory space map is searched from the highest address down to the lowest address 
+  /// looking for unallocated memory ranges.
+  ///
   EfiGcdAllocateAnySearchTopDown,
+  ///
+  /// The GCD memory space map is searched from the specified MaxAddress 
+  /// down to the lowest address looking for unallocated memory ranges.
+  ///
   EfiGcdAllocateMaxAddressSearchTopDown,
   EfiGcdMaxAllocateType
 } EFI_GCD_ALLOCATE_TYPE;
@@ -606,6 +657,10 @@ EFI_STATUS
 #define DXE_SERVICES_REVISION   ((1<<16) | (00))
 
 typedef struct {
+  ///
+  /// The table header for the DXE Services Table.
+  /// This header contains the DXE_SERVICES_SIGNATURE and DXE_SERVICES_REVISION values.
+  ///
   EFI_TABLE_HEADER                Hdr;
 
   //

MdePkg/Include/Pi/PiFirmwareFile.h

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

MdePkg/Include/Pi/PiFirmwareVolume.h

@@ -91,7 +91,13 @@ typedef UINT32  EFI_FVB_ATTRIBUTES_2;
 
 
 typedef struct {
+  ///
+  /// The number of sequential blocks which are of the same size.
+  ///
   UINT32 NumBlocks;
+  ///
+  /// The size of the blocks.
+  ///
   UINT32 Length;
 } EFI_FV_BLOCK_MAP_ENTRY;
 
@@ -99,16 +105,53 @@ typedef struct {
 /// Describes the features and layout of the firmware volume.
 ///
 typedef struct {
+  ///
+  /// The first 16 bytes are reserved to allow for the reset vector of 
+  /// processors whose reset vector is at address 0.
+  ///
   UINT8                     ZeroVector[16];
+  ///
+  /// Declares the file system with which the firmware volume is formatted.
+  ///
   EFI_GUID                  FileSystemGuid;
+  ///
+  /// Length in bytes of the complete firmware volume, including the header.
+  ///
   UINT64                    FvLength;
+  ///
+  /// Set to EFI_FVH_SIGNATURE
+  ///
   UINT32                    Signature;
+  ///
+  /// Declares capabilities and power-on defaults for the firmware volume.
+  ///
   EFI_FVB_ATTRIBUTES_2      Attributes;
+  ///
+  /// Length in bytes of the complete firmware volume header.
+  ///
   UINT16                    HeaderLength;
+  ///
+  /// A 16-bit checksum of the firmware volume header. A valid header sums to zero.
+  ///
   UINT16                    Checksum;
+  ///
+  /// Offset, relative to the start of the header, of the extended header
+  /// (EFI_FIRMWARE_VOLUME_EXT_HEADER) or zero if there is no extended header.
+  ///
   UINT16                    ExtHeaderOffset;
+  ///
+  /// This field must always be set to zero.
+  ///
   UINT8                     Reserved[1];
+  ///
+  /// Set to 2. Future versions of this specification may define new header fields and will
+  /// increment the Revision field accordingly.
+  ///
   UINT8                     Revision;
+  ///
+  /// An array of run-length encoded FvBlockMapEntry structures. The array is
+  /// terminated with an entry of {0,0}.
+  ///
   EFI_FV_BLOCK_MAP_ENTRY    BlockMap[1];
 } EFI_FIRMWARE_VOLUME_HEADER;
 
@@ -123,7 +166,13 @@ typedef struct {
 /// Extension header pointed by ExtHeaderOffset of volume header.
 /// 
 typedef struct {
+  ///
+  /// Firmware volume name.
+  ///
   EFI_GUID  FvName;
+  ///
+  /// Size of the rest of the extension header, including this structure.
+  ///
   UINT32    ExtHeaderSize;
 } EFI_FIRMWARE_VOLUME_EXT_HEADER;
 
@@ -131,7 +180,13 @@ typedef struct {
 /// Entry struture for describing FV extension header
 /// 
 typedef struct {
+  ///
+  /// Size of this header extension.
+  ///
   UINT16    ExtEntrySize;
+  ///
+  /// Type of the header.
+  ///
   UINT16    ExtEntryType;
 } EFI_FIRMWARE_VOLUME_EXT_ENTRY;
 
@@ -140,13 +195,18 @@ typedef struct {
 /// This extension header provides a mapping between a GUID and an OEM file type.
 /// 
 typedef struct {
+  ///
+  /// Standard extension entry, with the type EFI_FV_EXT_TYPE_OEM_TYPE.
+  ///
   EFI_FIRMWARE_VOLUME_EXT_ENTRY Hdr;
+  ///
+  /// A bit mask, one bit for each file type between 0xC0 (bit 0) and 0xDF (bit 31). If a bit
+  /// is '1', then the GUID entry exists in Types. If a bit is '0' then no GUID entry exists in Types.
+  ///
   UINT32    TypeMask;
-
+  ///
-  //
+  /// An array of GUIDs, each GUID representing an OEM file type.
-  // Array of GUIDs. 
+  /// 
-  // Each GUID represents an OEM file type.
-  // 
   EFI_GUID  Types[1];
 } EFI_FIRMWARE_VOLUME_EXT_ENTRY_OEM_TYPE;
 

MdePkg/Include/Pi/PiHob.h

@@ -43,8 +43,17 @@
 /// All HOBs must contain this generic HOB header.
 /// 
 typedef struct {
+  ///
+  /// Identifies the HOB data structure type.
+  ///
   UINT16    HobType;
+  ///
+  /// The length in bytes of the HOB.
+  ///
   UINT16    HobLength;
+  ///
+  /// This field must always be set to zero.
+  ///
   UINT32    Reserved;
 } EFI_HOB_GENERIC_HEADER;
 
@@ -59,13 +68,41 @@ typedef struct {
 /// This HOB must be the first one in the HOB list.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_HANDOFF.
+  ///
   EFI_HOB_GENERIC_HEADER  Header;
+  ///
+  /// The version number pertaining to the PHIT HOB definition.
+  /// This value is 4 bytes in length to provide an 8-byte aligned entry 
+  /// when it is combined with the 4-byte BootMode.
+  ///
   UINT32                  Version;
+  ///
+  /// The system boot mode as determined during the HOB producer phase.
+  ///
   EFI_BOOT_MODE           BootMode;
+  ///
+  /// The highest address location of memory that is allocated for use by the HOB producer
+  /// phase. This address must be 4-KB aligned to meet page restrictions of UEFI.
+  ///
   EFI_PHYSICAL_ADDRESS    EfiMemoryTop;
+  ///
+  /// The lowest address location of memory that is allocated for use by the HOB producer phase.
+  ///
   EFI_PHYSICAL_ADDRESS    EfiMemoryBottom;
+  ///
+  /// The highest address location of free memory that is currently available 
+  /// for use by the HOB producer phase.
+  ///
   EFI_PHYSICAL_ADDRESS    EfiFreeMemoryTop;
+  ///
+  /// The lowest address location of free memory that is available for use by the HOB producer phase.
+  ///
   EFI_PHYSICAL_ADDRESS    EfiFreeMemoryBottom;
+  ///
+  /// The end of the HOB list.
+  ///
   EFI_PHYSICAL_ADDRESS    EfiEndOfHobList;
 } EFI_HOB_HANDOFF_INFO_TABLE;
 
@@ -112,11 +149,17 @@ typedef struct {
 ///
 /// Describes all memory ranges used during the HOB producer 
 /// phase that exist outside the HOB list. This HOB type 
-/// describes how memory is used, 
+/// describes how memory is used, not the physical attributes of memory.
-/// not the physical attributes of memory.
 ///
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.
+  ///
   EFI_HOB_GENERIC_HEADER            Header;
+  ///
+  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the
+  /// various attributes of the logical memory allocation.
+  ///
   EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
   //
   // Additional data pertaining to the "Name" Guid memory
@@ -131,7 +174,14 @@ typedef struct {
 /// content in the HOB producer phase is executing.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.
+  ///
   EFI_HOB_GENERIC_HEADER            Header;
+  ///
+  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the
+  /// various attributes of the logical memory allocation.
+  ///
   EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
 } EFI_HOB_MEMORY_ALLOCATION_STACK;
 
@@ -142,7 +192,14 @@ typedef struct {
 /// register overflow store.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.
+  ///
   EFI_HOB_GENERIC_HEADER            Header;
+  ///
+  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the
+  /// various attributes of the logical memory allocation.
+  ///
   EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
 } EFI_HOB_MEMORY_ALLOCATION_BSP_STORE;
 
@@ -150,9 +207,24 @@ typedef struct {
 /// Defines the location and entry point of the HOB consumer phase.
 ///
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION.
+  ///
   EFI_HOB_GENERIC_HEADER            Header;
+  ///
+  /// An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the
+  /// various attributes of the logical memory allocation.
+  ///
   EFI_HOB_MEMORY_ALLOCATION_HEADER  MemoryAllocationHeader;
+  ///
+  /// The GUID specifying the values of the firmware file system name 
+  /// that contains the HOB consumer phase component.
+  ///
   EFI_GUID                          ModuleName;
+  ///
+  /// The address of the memory-mapped firmware volume 
+  /// that contains the HOB consumer phase firmware file.
+  ///
   EFI_PHYSICAL_ADDRESS              EntryPoint;
 } EFI_HOB_MEMORY_ALLOCATION_MODULE;
 
@@ -211,11 +283,30 @@ typedef UINT32 EFI_RESOURCE_ATTRIBUTE_TYPE;
 /// host bus during the HOB producer phase.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_RESOURCE_DESCRIPTOR.
+  ///
   EFI_HOB_GENERIC_HEADER      Header;
+  ///
+  /// A GUID representing the owner of the resource. This GUID is used by HOB
+  /// consumer phase components to correlate device ownership of a resource.
+  ///
   EFI_GUID                    Owner;
+  ///
+  /// Resource type enumeration as defined by EFI_RESOURCE_TYPE.
+  ///
   EFI_RESOURCE_TYPE           ResourceType;
+  ///
+  /// Resource attributes as defined by EFI_RESOURCE_ATTRIBUTE_TYPE.
+  ///
   EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute;
+  ///
+  /// Physical start address of the resource region. 
+  ///
   EFI_PHYSICAL_ADDRESS        PhysicalStart;
+  ///
+  /// Number of bytes of the resource region.
+  ///
   UINT64                      ResourceLength;
 } EFI_HOB_RESOURCE_DESCRIPTOR;
 
@@ -224,20 +315,34 @@ typedef struct {
 /// maintain and manage HOBs with specific GUID.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_GUID_EXTENSION.
+  ///
   EFI_HOB_GENERIC_HEADER      Header;
+  ///
+  /// A GUID that defines the contents of this HOB.
+  ///
   EFI_GUID                    Name;
-
+  //
-  ///
+  // Guid specific data goes here
-  /// Guid specific data goes here
+  //
-  ///
 } EFI_HOB_GUID_TYPE;
 
 ///
 /// Details the location of firmware volumes that contain firmware files.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV.
+  ///
   EFI_HOB_GENERIC_HEADER Header;
+  ///
+  /// The physical memory-mapped base address of the firmware volume.
+  ///
   EFI_PHYSICAL_ADDRESS   BaseAddress;
+  ///
+  /// The length in bytes of the firmware volume.
+  ///
   UINT64                 Length;
 } EFI_HOB_FIRMWARE_VOLUME;
 
@@ -246,10 +351,25 @@ typedef struct {
 /// from a file within another firmware volume.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV2.
+  ///
   EFI_HOB_GENERIC_HEADER  Header;
+  ///
+  /// The physical memory-mapped base address of the firmware volume.
+  ///
   EFI_PHYSICAL_ADDRESS    BaseAddress;
+  ///
+  /// The length in bytes of the firmware volume.
+  ///
   UINT64                  Length;
+  ///
+  /// The name of the firmware volume.
+  ///
   EFI_GUID                FvName;
+  ///
+  /// The name of the firmware file which contained this firmware volume.
+  ///
   EFI_GUID                FileName;
 } EFI_HOB_FIRMWARE_VOLUME2;
 
@@ -258,9 +378,21 @@ typedef struct {
 /// Describes processor information, such as address space and I/O space capabilities.
 ///
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_CPU.
+  ///
   EFI_HOB_GENERIC_HEADER  Header;
+  ///
+  /// Identifies the maximum physical memory addressability of the processor.
+  ///
   UINT8                   SizeOfMemorySpace;
+  ///
+  /// Identifies the maximum physical I/O addressability of the processor.
+  ///
   UINT8                   SizeOfIoSpace;
+  ///
+  /// This field will always be set to zero.
+  ///
   UINT8                   Reserved[6];
 } EFI_HOB_CPU;
 
@@ -269,6 +401,9 @@ typedef struct {
 /// Describes pool memory allocations.
 /// 
 typedef struct {
+  ///
+  /// The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_POOL.
+  ///
   EFI_HOB_GENERIC_HEADER  Header;
 } EFI_HOB_MEMORY_POOL;
 

MdePkg/Include/Pi/PiMultiPhase.h

@@ -86,8 +86,17 @@ typedef UINT32 EFI_STATUS_CODE_VALUE;
 /// the structure and is Size bytes long.
 ///
 typedef struct {
+  ///
+  /// The size of the structure. This is specified to enable future expansion.
+  ///
   UINT16    HeaderSize;
+  ///
+  /// The size of the data in bytes. This does not include the size of the header structure.
+  ///
   UINT16    Size;
+  ///
+  /// The GUID defining the type of the data.
+  ///
   EFI_GUID  Type;
 } EFI_STATUS_CODE_DATA;
 

MdePkg/Include/Pi/PiPeiCis.h

@@ -94,8 +94,18 @@ EFI_STATUS
 /// The data structure through which a PEIM describes available services to the PEI Foundation.
 /// 
 typedef struct {
+  ///
+  /// This field is a set of flags describing the characteristics of this imported table entry.
+  /// All flags are defined as EFI_PEI_PPI_DESCRIPTOR_***, which can also be combined into one.
+  ///
   UINTN     Flags;
+  ///
+  /// The address of the EFI_GUID that names the interface.
+  ///
   EFI_GUID  *Guid;
+  ///
+  /// A pointer to the PPI. It contains the information necessary to install a service.
+  ///
   VOID      *Ppi;
 } EFI_PEI_PPI_DESCRIPTOR;
 
@@ -104,24 +114,20 @@ typedef struct {
 /// Foundation where to invoke the notification service.
 /// 
 struct _EFI_PEI_NOTIFY_DESCRIPTOR {
+  ///
+  /// Details if the type of notification is callback or dispatch.
+  ///
   UINTN                       Flags;
+  ///
+  /// The address of the EFI_GUID that names the interface.
+  ///
   EFI_GUID                    *Guid;
+  ///
+  /// Address of the notification callback function itself within the PEIM.
+  ///
   EFI_PEIM_NOTIFY_ENTRY_POINT Notify;
 };
 
-///
-/// Describes request of the module to be loaded to 
-/// the permanent memory once it is available. Unlike most of the other HOBs, 
-/// this HOB is produced and consumed during the HOB producer phase.
-/// 
-typedef struct _EFI_HOB_LOAD_PEIM {
-  EFI_HOB_GENERIC_HEADER            Header;
-  EFI_PEI_FILE_HANDLE               FileHandle;
-  EFI_PEIM_ENTRY_POINT2             EntryPoint;
-  EFI_PEIM_ENTRY_POINT2             InMemEntryPoint;
-} EFI_HOB_LOAD_PEIM;
-
-
 /**
   This service is the first one provided by the PEI Foundation.  This function 
   installs an interface in the PEI PPI database by GUID.  The purpose of the 

MdePkg/Include/Protocol/PciIo.h

@@ -91,7 +91,7 @@ typedef enum {
   EfiPciIoOperationBusMasterWrite,
   ///
   /// Provides both read and write access to system memory by both the processor and a
-  /// bus master. The buffer is coherent from both the processor¡¯s and the bus master's point of view.
+  /// bus master. The buffer is coherent from both the processor's and the bus master's point of view.
   ///
   EfiPciIoOperationBusMasterCommonBuffer,
   EfiPciIoOperationMaximum
@@ -104,11 +104,11 @@ typedef enum {
 ///
 typedef enum {
   ///
-  /// Retrieve the PCI controller¡¯s current attributes, and return them in Result.
+  /// Retrieve the PCI controller's current attributes, and return them in Result.
   ///
   EfiPciIoAttributeOperationGet,
   ///
-  /// Set the PCI controller¡¯s current attributes to Attributes.
+  /// Set the PCI controller's current attributes to Attributes.
   ///
   EfiPciIoAttributeOperationSet,
   ///

MdePkg/Include/Uefi/UefiGpt.h

@@ -32,15 +32,53 @@
 /// GPT Partition Table Header
 ///
 typedef struct {
+  ///
+  /// The table header for the GPT partition Table.
+  /// This header contains EFI_PTAB_HEADER_ID
+  ///
   EFI_TABLE_HEADER  Header;
+  ///
+  /// The LBA that contains this data structure.
+  ///
   EFI_LBA           MyLBA;
+  ///
+  /// LBA address of the alternate GUID Partition Table Header.
+  ///
   EFI_LBA           AlternateLBA;
+  ///
+  /// The first usable logical block that may be used
+  /// by a partition described by a GUID Partition Entry.
+  ///
   EFI_LBA           FirstUsableLBA;
+  ///
+  /// The last usable logical block that may be used
+  /// by a partition described by a GUID Partition Entry.
+  ///
   EFI_LBA           LastUsableLBA;
+  ///
+  /// GUID that can be used to uniquely identify the disk.
+  ///
   EFI_GUID          DiskGUID;
+  ///
+  /// The starting LBA of the GUID Partition Entry array.
+  ///
   EFI_LBA           PartitionEntryLBA;
+  ///
+  /// The number of Partition Entries in the GUID Partition Entry array.
+  ///
   UINT32            NumberOfPartitionEntries;
+  ///
+  /// The size, in bytes, of each the GUID Partition
+  /// Entry structures in the GUID Partition Entry
+  /// array. Must be a multiple of 8.
+  ///
   UINT32            SizeOfPartitionEntry;
+  ///
+  /// The CRC32 of the GUID Partition Entry array.
+  /// Starts at PartitionEntryLBA and is
+  /// computed over a byte length of
+  /// NumberOfPartitionEntries * SizeOfPartitionEntry.
+  ///
   UINT32            PartitionEntryArrayCRC32;
 } EFI_PARTITION_TABLE_HEADER;
 
@@ -48,11 +86,35 @@ typedef struct {
 /// GPT Partition Entry
 ///
 typedef struct {
+  ///
+  /// Unique ID that defines the purpose and type of this Partition. A value of
+  /// zero defines that this partition entry is not being used.
+  ///
   EFI_GUID  PartitionTypeGUID;
+  ///
+  /// GUID that is unique for every partition entry. Every partition ever
+  /// created will have a unique GUID.
+  /// This GUID must be assigned when the GUID Partition Entry is created.
+  ///
   EFI_GUID  UniquePartitionGUID;
+  ///
+  /// Starting LBA of the partition defined by this entry
+  ///
   EFI_LBA   StartingLBA;
+  ///
+  /// Ending LBA of the partition defined by this entry.
+  ///
   EFI_LBA   EndingLBA;
+  ///
+  /// Attribute bits, all bits reserved by UEFI
+  /// Bit 0 Required for the platform to function.
+  /// Bits 1-47 Undefined and must be zero.
+  /// Bits 48-63 Reserved for GUID specific use.
+  ///
   UINT64    Attributes;
+  ///
+  /// Unicode string.
+  ///
   CHAR16    PartitionName[36];
 } EFI_PARTITION_ENTRY;
 

MdePkg/Include/Uefi/UefiMultiPhase.h

@@ -21,32 +21,100 @@
 /// Enumeration of memory types introduced in UEFI.
 /// 
 typedef enum {
+  ///
+  /// Not used.
+  ///
   EfiReservedMemoryType,
+  ///
+  /// The code portions of a loaded application. 
+  /// (Note that UEFI OS loaders are UEFI applications.)
+  ///
   EfiLoaderCode,
+  ///
+  /// The data portions of a loaded application and the default data allocation
+  /// type used by an application to allocate pool memory.
+  ///
   EfiLoaderData,
+  ///
+  /// The code portions of a loaded Boot Services Driver
+  ///
   EfiBootServicesCode,
+  ///
+  /// The data portions of a loaded Boot Serves Driver, and the default data
+  /// allocation type used by a Boot Services Driver to allocate pool memory.
+  ///
   EfiBootServicesData,
+  ///
+  /// The code portions of a loaded Runtime Services Driver.
+  ///
   EfiRuntimeServicesCode,
+  ///
+  /// The data portions of a loaded Runtime Services Driver and the default
+  /// data allocation type used by a Runtime Services Driver to allocate pool memory.
+  ///
   EfiRuntimeServicesData,
+  ///
+  /// Free (unallocated) memory.
+  ///
   EfiConventionalMemory,
+  ///
+  /// Memory in which errors have been detected.
+  ///
   EfiUnusableMemory,
+  ///
+  /// Memory that holds the ACPI tables.
+  ///
   EfiACPIReclaimMemory,
+  ///
+  /// Address space reserved for use by the firmware.
+  ///
   EfiACPIMemoryNVS,
+  ///
+  /// Used by system firmware to request that a memory-mapped IO region
+  /// be mapped by the OS to a virtual address so it can be accessed by EFI runtime services.
+  ///
   EfiMemoryMappedIO,
+  ///
+  /// System memory-mapped IO region that is used to translate memory
+  /// cycles to IO cycles by the processor.
+  ///
   EfiMemoryMappedIOPortSpace,
+  ///
+  /// Address space reserved by the firmware for code that is part of the processor.
+  ///
   EfiPalCode,
   EfiMaxMemoryType
 } EFI_MEMORY_TYPE;
 
-
 ///
 /// Data structure that precedes all of the standard EFI table types.
 /// 
 typedef struct {
+  ///
+  /// A 64-bit signature that identifies the type of table that follows.
+  /// Unique signatures have been generated for the EFI System Table,
+  /// the EFI Boot Services Table, and the EFI Runtime Services Table.
+  ///
   UINT64  Signature;
+  ///
+  /// The revision of the EFI Specification to which this table
+  /// conforms. The upper 16 bits of this field contain the major
+  /// revision value, and the lower 16 bits contain the minor revision
+  /// value. The minor revision values are limited to the range of 00..99.
+  ///
   UINT32  Revision;
+  ///
+  /// The size, in bytes, of the entire table including the EFI_TABLE_HEADER.
+  ///
   UINT32  HeaderSize;
+  ///
+  /// The 32-bit CRC for the entire table. This value is computed by
+  /// setting this field to 0, and computing the 32-bit CRC for HeaderSize bytes.
+  ///
   UINT32  CRC32;
+  ///
+  /// Reserved field that must be set to 0.
+  ///
   UINT32  Reserved;
 } EFI_TABLE_HEADER;
 
@@ -104,9 +172,9 @@ typedef struct _WIN_CERTIFICATE {
 #define EFI_CERT_TYPE_RSA2048_SHA256_GUID \
   {0xa7717414, 0xc616, 0x4977, {0x94, 0x20, 0x84, 0x47, 0x12, 0xa7, 0x35, 0xbf } }
 
-//
+///
-// WIN_CERTIFICATE_UEFI_GUID.CertData
+/// WIN_CERTIFICATE_UEFI_GUID.CertData
-// 
+/// 
 typedef struct _EFI_CERT_BLOCK_RSA_2048_SHA256 {
   UINT32  HashType;
   UINT8   PublicKey[256];

MdePkg/Include/Uefi/UefiSpec.h

@@ -689,8 +689,27 @@ EFI_STATUS
 /// real time clock device as exposed through the EFI interfaces.
 ///
 typedef struct {
+  ///
+  /// Provides the reporting resolution of the real-time clock device in
+  /// counts per second. For a normal PC-AT CMOS RTC device, this
+  /// value would be 1 Hz, or 1, to indicate that the device only reports
+  /// the time to the resolution of 1 second.
+  ///
   UINT32    Resolution;
+  ///
+  /// Provides the timekeeping accuracy of the real-time clock in an
+  /// error rate of 1E-6 parts per million. For a clock with an accuracy
+  /// of 50 parts per million, the value in this field would be
+  /// 50,000,000.
+  ///
   UINT32    Accuracy;
+  ///
+  /// A TRUE indicates that a time set operation clears the device¡¯s
+  /// time below the Resolution reporting level. A FALSE
+  /// indicates that the state below the Resolution level of the
+  /// device is not cleared when the time is set. Normal PC-AT CMOS
+  /// RTC devices set this value to FALSE.
+  ///
   BOOLEAN   SetsToZero;
 } EFI_TIME_CAPABILITIES;
 
@@ -1527,9 +1546,22 @@ EFI_STATUS
 /// EFI Capsule Block Descriptor
 ///
 typedef struct {
+  ///
+  /// Length in bytes of the data pointed to by DataBlock/ContinuationPointer.
+  ///
   UINT64                  Length;
   union {
+    ///
+    /// Physical address of the data block. This member of the union is
+    /// used if Length is not equal to zero.
+    ///
     EFI_PHYSICAL_ADDRESS  DataBlock;
+    ///
+    /// Physical address of another block of
+    /// EFI_CAPSULE_BLOCK_DESCRIPTOR structures. This
+    /// member of the union is used if Length is equal to zero. If
+    /// ContinuationPointer is zero this entry represents the end of the list.
+    ///
     EFI_PHYSICAL_ADDRESS  ContinuationPointer;
   } Union;
 } EFI_CAPSULE_BLOCK_DESCRIPTOR;
@@ -1538,19 +1570,41 @@ typedef struct {
 /// EFI Capsule Header
 ///
 typedef struct {
+  ///
+  /// A GUID that defines the contents of a capsule.
+  ///
   EFI_GUID          CapsuleGuid;
+  ///
+  /// The size of the capsule header. This may be larger than the size of
+  /// the EFI_CAPSULE_HEADER since CapsuleGuid may imply
+  /// extended header entries
+  ///
   UINT32            HeaderSize;
+  ///
+  /// Bit-mapped list describing the capsule attributes. The Flag values
+  /// of 0x0000 ¨C 0xFFFF are defined by CapsuleGuid. Flag values
+  /// of 0x10000 ¨C 0xFFFF0000 are defined by this specification
+  ///
   UINT32            Flags;
+  ///
+  /// Size in bytes of the capsule.
+  ///
   UINT32            CapsuleImageSize;
 } EFI_CAPSULE_HEADER;
 
-//
+///
-// The EFI System Table entry must point to an array of capsules
+/// The EFI System Table entry must point to an array of capsules
-// that contain the same CapsuleGuid value. The array must be
+/// that contain the same CapsuleGuid value. The array must be
-// prefixed by a UINT32 that represents the size of the array of capsules.
+/// prefixed by a UINT32 that represents the size of the array of capsules.
-//
+///
 typedef struct {
+  ///
+  /// the size of the array of capsules.
+  ///
   UINT32   CapsuleArrayNumber;
+  ///
+  /// Point to an array of capsules that contain the same CapsuleGuid value.
+  ///
   VOID*    CapsulePtr[1];
 } EFI_CAPSULE_TABLE;
 
@@ -1929,14 +1983,40 @@ EFI_STATUS
 ///
 typedef union {
   struct {
+    ///
+    /// Indicates the revision of the EFI_KEY_OPTION structure. This revision level should be 0.
+    ///
     UINT32  Revision        : 8;
+    ///
+    /// Either the left or right Shift keys must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  ShiftPressed    : 1;
+    ///
+    /// Either the left or right Control keys must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  ControlPressed  : 1;
+    ///
+    /// Either the left or right Alt keys must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  AltPressed      : 1;
+    ///
+    /// Either the left or right Logo keys must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  LogoPressed     : 1;
+    ///
+    /// The Menu key must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  MenuPressed     : 1;
+    ///
+    /// The SysReq key must be pressed (1) or must not be pressed (0).
+    ///
     UINT32  SysReqPessed    : 1;
     UINT32  Reserved        : 16;
+    ///
+    /// Specifies the actual number of entries in EFI_KEY_OPTION.Keys, from 0-3. If
+    /// zero, then only the shift state is considered. If more than one, then the boot option will
+    /// only be launched if all of the specified keys are pressed with the same shift state.
+    ///
     UINT32  InputKeyCount   : 2;
   } Options;
   UINT32  PackedValue;
@@ -1946,9 +2026,26 @@ typedef union {
 /// EFI Key Option
 ///
 typedef struct {
-  EFI_BOOT_KEY_DATA  KeyOptions;
+  ///
+  /// Specifies options about how the key will be processed.
+  ///
+  EFI_BOOT_KEY_DATA  KeyData;
+  ///
+  /// The CRC-32 which should match the CRC-32 of the entire EFI_LOAD_OPTION to
+  /// which BootOption refers. If the CRC-32s do not match this value, then this key
+  /// option is ignored.
+  ///
   UINT32             BootOptionCrc;
+  ///
+  /// The Boot#### option which will be invoked if this key is pressed and the boot option
+  /// is active (LOAD_OPTION_ACTIVE is set).
+  ///
   UINT16             BootOption;
+  ///
+  /// The key codes to compare against those returned by the
+  /// EFI_SIMPLE_TEXT_INPUT and EFI_SIMPLE_TEXT_INPUT_EX protocols.
+  /// The number of key codes (0-3) is specified by the EFI_KEY_CODE_COUNT field in KeyOptions.
+  ///
   //EFI_INPUT_KEY      Keys[];
 } EFI_KEY_OPTION;