]> git.proxmox.com Git - mirror_edk2.git/commitdiff
1) Add descriptions for the enum values or struc members for the following types:
authormdkinney <mdkinney@6f19259b-4bc3-4df7-8a09-765794883524>
Sun, 7 Dec 2008 23:08:08 +0000 (23:08 +0000)
committermdkinney <mdkinney@6f19259b-4bc3-4df7-8a09-765794883524>
Sun, 7 Dec 2008 23:08:08 +0000 (23:08 +0000)
  EFI_ALLOCATION_TYPE
  EFI_MEKORY_DESCRITOR
  EFI_TIMER_DEALY
  EFI_RESET_TYPE
  EFI_INTERFACE_TYPE
  EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
  EFI_LOCATE_SEARCH_TYPE
  EFI_CAPSULE_BLOCK_DESCRIPTOR
  EFI_CAPSULE_HEADER

2) Rearrange some content to eliminate the need for the forward declaration of EFI_SYSTEM_TABLE
3) Update signature declarations to use EFI_SIGNATURE_64().
4) Move macro NEXT_MEMORY_DESCRITOR() from this file to the UEFI Library.  It is not part of the UEFI Specification.
5) Fix hot key related type names to match the UEFI Specification

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

MdePkg/Include/Uefi/UefiSpec.h

index 6eed067320570e139ea21a414d442217816a26b6..df3b373278e976bdf6736fc67eeffb31ef39dc7d 100644 (file)
 #include <Protocol/SimpleTextOut.h>\r
 \r
 ///\r
-/// Enumeration of memory allocation.\r
+/// Enumeration of EFI memory allocation types.\r
 ///\r
 typedef enum {\r
+  ///\r
+  /// Allocate any available range of pages that satisfies the request\r
+  ///\r
   AllocateAnyPages,\r
+  ///\r
+  /// Allocate any available range of pages whose uppermost address is less than \r
+  /// or equal to a specified maximum address\r
+  ///\r
   AllocateMaxAddress,\r
+  ///\r
+  /// Allocate pages at a specified address\r
+  ///\r
   AllocateAddress,\r
+  ///\r
+  /// Maximum enumeration value that may be used for bounds checking\r
+  ///\r
   MaxAllocateType\r
 } EFI_ALLOCATE_TYPE;\r
 \r
@@ -71,26 +84,35 @@ typedef enum {
 #define EFI_MEMORY_DESCRIPTOR_VERSION 1\r
 \r
 ///\r
-/// Definition of memory descriptor\r
+/// Definition of an EFI memory descriptor\r
 ///\r
 typedef struct {\r
+  ///\r
+  /// Type of the memory region.  See EFI_MEMORY_TYPE\r
+  ///\r
   UINT32                Type;\r
+  ///\r
+  /// Physical address of the first byte of the memory region.  Must aligned \r
+  /// on a 4 KB boundary.\r
+  ///\r
   EFI_PHYSICAL_ADDRESS  PhysicalStart;\r
+  ///\r
+  /// Virtual address of the first byte of the memory region.  Must aligned \r
+  /// on a 4 KB boundary.\r
+  ///\r
   EFI_VIRTUAL_ADDRESS   VirtualStart;\r
+  ///\r
+  /// Number of 4KB pages in the memory region.\r
+  ///\r
   UINT64                NumberOfPages;\r
+  ///\r
+  /// Attributes of the memory region that describe the bit mask of capabilities\r
+  /// for that memory region, and not necessarily the current settings for that \r
+  /// memory region.\r
+  ///\r
   UINT64                Attribute;\r
 } EFI_MEMORY_DESCRIPTOR;\r
 \r
-///\r
-/// Build macros to find next EFI_MEMORY_DESCRIPTOR.\r
-///\r
-#define NEXT_MEMORY_DESCRIPTOR(_Ptr, _Size)   ((EFI_MEMORY_DESCRIPTOR *) (((UINT8 *) (_Ptr)) + (_Size)))\r
-\r
-///\r
-/// Declare forward referenced data structures\r
-///\r
-typedef struct _EFI_SYSTEM_TABLE   EFI_SYSTEM_TABLE;\r
-\r
 /**\r
   Allocates memory pages from the system.\r
 \r
@@ -427,8 +449,17 @@ EFI_STATUS
 /// Timer delay types\r
 ///\r
 typedef enum {\r
+  ///\r
+  /// An event's timer settings is to be cancelled and not trigger time is to be set\r
+  ///\r
   TimerCancel,\r
+  ///\r
+  /// An event is to be signalled periodically at a specified interval from the current time.\r
+  ///\r
   TimerPeriodic,\r
+  ///\r
+  /// An event is to be signalled once at a specified interval from the current time.\r
+  ///\r
   TimerRelative\r
 } EFI_TIMER_DELAY;\r
 \r
@@ -743,24 +774,6 @@ EFI_STATUS
   IN  EFI_TIME                     *Time   OPTIONAL\r
   );\r
 \r
-/**\r
-  This is the declaration of an EFI image entry point. This entry point is\r
-  the same for UEFI Applications, UEFI OS Loaders, and UEFI Drivers including\r
-  both device drivers and bus drivers.\r
-\r
-  @param  ImageHandle           The firmware allocated handle for the UEFI image.\r
-  @param  SystemTable           A pointer to the EFI System Table.\r
-\r
-  @retval EFI_SUCCESS           The operation completed successfully.\r
-  @retval Others                Some unexpected error happened.\r
-**/\r
-typedef\r
-EFI_STATUS\r
-(EFIAPI *EFI_IMAGE_ENTRY_POINT)(\r
-  IN  EFI_HANDLE                   ImageHandle,\r
-  IN  EFI_SYSTEM_TABLE             *SystemTable\r
-  );\r
-\r
 /**\r
   Loads an EFI image into memory.\r
 \r
@@ -919,10 +932,25 @@ EFI_STATUS
 /// Enumeration of reset types.\r
 ///\r
 typedef enum {\r
+  ///\r
+  /// Used to induce a system-wide reset. This sets all circuitry within the \r
+  /// system to its initial state.  This type of reset is asynchronous to system\r
+  /// operation and operates withgout regard to cycle boundaries.  EfiColdReset \r
+  /// is tantamount to a system power cycle.\r
+  ///\r
   EfiResetCold,\r
+  ///\r
+  /// Used to induce a system-wide initialization. The processors are set to their\r
+  /// initial state, and pending cycles are not corrupted.  If the system does \r
+  /// not support this reset type, then an EfiResetCold must be performed.\r
+  ///\r
   EfiResetWarm,\r
-  EfiResetShutdown,\r
-  EfiResetUpdate\r
+  ///\r
+  /// Used to induce en entry into power state equivalent to the ACPI G2/S5 or G3\r
+  /// state.  If the system does not support this reset type, then when the system\r
+  /// is rebooted, it should exhibit the EfiResetCold attributes.\r
+  ///\r
+  EfiResetShutdown\r
 } EFI_RESET_TYPE;\r
 \r
 /**\r
@@ -1032,11 +1060,13 @@ VOID
   IN UINT8    Value\r
   );\r
 \r
-\r
-//\r
-// Protocol handler functions\r
-//\r
+///\r
+/// Enumeration of EFI Interface Types\r
+///\r
 typedef enum {\r
+  ///\r
+  /// Indicates that the supplied protocol interface is supplied in native form.\r
+  ///\r
   EFI_NATIVE_INTERFACE\r
 } EFI_INTERFACE_TYPE;\r
 \r
@@ -1259,7 +1289,9 @@ EFI_STATUS
   IN EFI_HANDLE               ControllerHandle\r
   );\r
 \r
-\r
+///\r
+/// EFI Oprn Protocol Information Entry\r
+///\r
 typedef struct {\r
   EFI_HANDLE  AgentHandle;\r
   EFI_HANDLE  ControllerHandle;\r
@@ -1343,10 +1375,22 @@ EFI_STATUS
   OUT VOID                     **Registration\r
   );\r
 \r
-\r
+///\r
+/// Enumeration of EFI Locate Search Types\r
+///\r
 typedef enum {\r
+  ///\r
+  /// Retrieve all the handles in the handle database.\r
+  ///\r
   AllHandles,\r
+  ///\r
+  /// Retrieve the next handle fron a RegisterProtocolNotify() event.\r
+  ///\r
   ByRegisterNotify,\r
+  ///\r
+  /// Retrieve the set of handles from the handle database that support a \r
+  /// specified protocol.\r
+  ///\r
   ByProtocol\r
 } EFI_LOCATE_SEARCH_TYPE;\r
 \r
@@ -1426,7 +1470,6 @@ EFI_STATUS
   IN VOID                     *Table\r
   );\r
 \r
-\r
 /**\r
   Returns an array of handles that support the requested protocol in a buffer allocated from pool.\r
 \r
@@ -1480,14 +1523,20 @@ EFI_STATUS
   OUT VOID      **Interface\r
   );\r
 \r
+///\r
+/// EFI Capsule Block Descriptor\r
+///\r
 typedef struct {\r
-  UINT64                            Length;\r
+  UINT64                  Length;\r
   union {\r
     EFI_PHYSICAL_ADDRESS  DataBlock;\r
     EFI_PHYSICAL_ADDRESS  ContinuationPointer;\r
   } Union;\r
 } EFI_CAPSULE_BLOCK_DESCRIPTOR;\r
 \r
+///\r
+/// EFI Capsule Header\r
+///\r
 typedef struct {\r
   EFI_GUID          CapsuleGuid;\r
   UINT32            HeaderSize;\r
@@ -1603,14 +1652,14 @@ EFI_STATUS
 //\r
 // EFI Runtime Services Table\r
 //\r
-#define EFI_SYSTEM_TABLE_SIGNATURE      0x5453595320494249ULL\r
-#define EFI_SYSTEM_TABLE_REVISION       ((2<<16) | (10))\r
-#define EFI_2_10_SYSTEM_TABLE_REVISION  ((2<<16) | (10))\r
-#define EFI_2_00_SYSTEM_TABLE_REVISION  ((2<<16) | (00))\r
-#define EFI_1_10_SYSTEM_TABLE_REVISION  ((1<<16) | (10))\r
-#define EFI_1_02_SYSTEM_TABLE_REVISION  ((1<<16) | (02))\r
-\r
-#define EFI_RUNTIME_SERVICES_SIGNATURE  0x56524553544e5552ULL\r
+#define EFI_SYSTEM_TABLE_SIGNATURE      EFI_SIGNATURE_64 ('I','B','I',' ','S','Y','S','T')\r
+#define EFI_SYSTEM_TABLE_REVISION       ((2 << 16) | (10))\r
+#define EFI_2_10_SYSTEM_TABLE_REVISION  ((2 << 16) | (10))\r
+#define EFI_2_00_SYSTEM_TABLE_REVISION  ((2 << 16) | (00))\r
+#define EFI_1_10_SYSTEM_TABLE_REVISION  ((1 << 16) | (10))\r
+#define EFI_1_02_SYSTEM_TABLE_REVISION  ((1 << 16) | (02))\r
+\r
+#define EFI_RUNTIME_SERVICES_SIGNATURE  EFI_SIGNATURE_64 ('R','U','N','T','S','E','R','V')\r
 #define EFI_RUNTIME_SERVICES_REVISION   EFI_2_10_SYSTEM_TABLE_REVISION\r
 \r
 ///\r
@@ -1662,7 +1711,7 @@ typedef struct {
 } EFI_RUNTIME_SERVICES;\r
 \r
 \r
-#define EFI_BOOT_SERVICES_SIGNATURE   0x56524553544f4f42ULL\r
+#define EFI_BOOT_SERVICES_SIGNATURE   EFI_SIGNATURE_64 ('B','O','O','T','S','E','R','V')\r
 #define EFI_BOOT_SERVICES_REVISION    EFI_2_10_SYSTEM_TABLE_REVISION\r
 \r
 ///\r
@@ -1767,7 +1816,7 @@ typedef struct {
 /// Contains a set of GUID/pointer pairs comprised of the ConfigurationTable field in the\r
 /// EFI System Table.\r
 ///\r
-typedef struct{\r
+typedef struct {\r
   ///\r
   /// The 128-bit GUID value that uniquely identifies the system configuration table.\r
   ///\r
@@ -1781,7 +1830,7 @@ typedef struct{
 ///\r
 /// EFI System Table\r
 ///\r
-struct _EFI_SYSTEM_TABLE {\r
+typedef struct {\r
   ///\r
   /// The table header for the EFI System Table.\r
   ///\r
@@ -1840,7 +1889,25 @@ struct _EFI_SYSTEM_TABLE {
   /// The number of entries in the table is NumberOfTableEntries.\r
   ///\r
   EFI_CONFIGURATION_TABLE           *ConfigurationTable;\r
-};\r
+} EFI_SYSTEM_TABLE;\r
+\r
+/**\r
+  This is the declaration of an EFI image entry point. This entry point is\r
+  the same for UEFI Applications, UEFI OS Loaders, and UEFI Drivers including\r
+  both device drivers and bus drivers.\r
+\r
+  @param  ImageHandle           The firmware allocated handle for the UEFI image.\r
+  @param  SystemTable           A pointer to the EFI System Table.\r
+\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval Others                Some unexpected error happened.\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_IMAGE_ENTRY_POINT)(\r
+  IN  EFI_HANDLE                   ImageHandle,\r
+  IN  EFI_SYSTEM_TABLE             *SystemTable\r
+  );\r
 \r
 //\r
 // EFI Load Options Attributes\r
@@ -1857,6 +1924,9 @@ struct _EFI_SYSTEM_TABLE {
 #define EFI_BOOT_OPTION_SUPPORT_APP   0x00000002\r
 #define EFI_BOOT_OPTION_SUPPORT_COUNT 0x00000300\r
 \r
+///\r
+/// EFI Boot Key Data\r
+///\r
 typedef union {\r
   struct {\r
     UINT32  Revision        : 8;\r
@@ -1870,13 +1940,16 @@ typedef union {
     UINT32  InputKeyCount   : 2;\r
   } Options;\r
   UINT32  PackedValue;\r
-} HOT_KEY_EFI_KEY_DATA;\r
+} EFI_BOOT_KEY_DATA;\r
 \r
+///\r
+/// EFI Key Option\r
+///\r
 typedef struct {\r
-  HOT_KEY_EFI_KEY_DATA  KeyOptions;\r
-  UINT32                BootOptionCrc;\r
-  UINT16                BootOption;\r
-//EFI_INPUT_KEY         Keys[];\r
+  EFI_BOOT_KEY_DATA  KeyOptions;\r
+  UINT32             BootOptionCrc;\r
+  UINT16             BootOption;\r
+//EFI_INPUT_KEY      Keys[];\r
 } EFI_KEY_OPTION;\r
 \r
 #define EFI_KEY_OPTION_SHIFT     0x00000001\r
@@ -1887,7 +1960,6 @@ typedef struct {
 #define EFI_KEY_OPTION_SYSREQ    0x00000020\r
 #define EFI_KEY_CODE_COUNT       0x00000300\r
 \r
-\r
 //\r
 // EFI File location to boot from on removable media devices\r
 //\r