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
2008-12-10 08:22:03 +00:00
parent 2c6d600e1c
commit 1bf793701b
11 changed files with 602 additions and 40 deletions
--- a/MdePkg/Include/Uefi/UefiGpt.h
+++ b/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;

--- a/MdePkg/Include/Uefi/UefiMultiPhase.h
+++ b/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];
--- a/MdePkg/Include/Uefi/UefiSpec.h
+++ b/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<63><65>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 <20>C 0xFFFF are defined by CapsuleGuid. Flag values
+  /// of 0x10000 <20>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
-// that contain the same CapsuleGuid value. The array must be
-// prefixed by a UINT32 that represents the size of the 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
+/// 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,10 +2026,27 @@ 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;
-//EFI_INPUT_KEY      Keys[];
+  ///
+  /// 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;

 #define EFI_KEY_OPTION_SHIFT     0x00000001