Add the detailed descriptions for the structure data member in these protocol.

[mirror_edk2.git] / MdePkg / Include / Protocol / DevicePath.h

diff --git a/MdePkg/Include/Protocol/DevicePath.h b/MdePkg/Include/Protocol/DevicePath.h
index 56e5cec85b33604df9d9371c567c337a78fa53eb..16e8eb4289e3f6c316a7fd8a84f3174bb1223bb2 100644 (file)
--- a/MdePkg/Include/Protocol/DevicePath.h
+++ b/MdePkg/Include/Protocol/DevicePath.h
@@ -29,12 +29,8 @@
     0x9576e91, 0x6d3f, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \\r
   }\r
 \r
-//\r
-// Protocol GUID defined in EFI1.1.\r
-// \r
-\r
 ///\r
-/// Device Path information\r
+/// Device Path guid definition for backward-compatible with EFI1.1.\r
 ///\r
 #define DEVICE_PATH_PROTOCOL  EFI_DEVICE_PATH_PROTOCOL_GUID\r
 \r
@@ -67,7 +63,7 @@ typedef struct {
 } EFI_DEVICE_PATH_PROTOCOL;\r
 \r
 ///\r
-/// For backward-compatible with EFI1.1.\r
+/// Device Path protocol definition for backward-compatible with EFI1.1.\r
 /// \r
 typedef EFI_DEVICE_PATH_PROTOCOL  EFI_DEVICE_PATH;\r
 \r
@@ -77,9 +73,13 @@ typedef EFI_DEVICE_PATH_PROTOCOL  EFI_DEVICE_PATH;
 #define HARDWARE_DEVICE_PATH      0x01\r
 \r
 ///\r
-/// PCI Device Path\r
+/// PCI Device Path SubType\r
 ///\r
 #define HW_PCI_DP                 0x01\r
+\r
+///\r
+/// PCI Device Path\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -93,9 +93,13 @@ typedef struct {
 } PCI_DEVICE_PATH;\r
 \r
 ///\r
-/// PCCARD Device Path\r
+/// PCCARD Device Path SubType\r
 ///\r
 #define HW_PCCARD_DP              0x02\r
+\r
+///\r
+/// PCCARD Device Path\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -105,9 +109,13 @@ typedef struct {
 } PCCARD_DEVICE_PATH;\r
 \r
 ///\r
-/// Memory Mapped Device Path\r
+/// Memory Mapped Device Path SubType\r
 ///\r
 #define HW_MEMMAP_DP              0x03\r
+\r
+///\r
+/// Memory Mapped Device Path\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -124,12 +132,16 @@ typedef struct {
   EFI_PHYSICAL_ADDRESS            EndingAddress;\r
 } MEMMAP_DEVICE_PATH;\r
 \r
+///\r
+/// Hardware Vendor Device Path SubType\r
+///\r
+#define HW_VENDOR_DP              0x04\r
+\r
 ///\r
 /// The Vendor Device Path allows the creation of vendor-defined Device Paths. A vendor must\r
 /// allocate a Vendor GUID for a Device Path. The Vendor GUID can then be used to define the\r
 /// contents on the n bytes that follow in the Vendor Device Path node.\r
 ///\r
-#define HW_VENDOR_DP              0x04\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -142,9 +154,13 @@ typedef struct {
 } VENDOR_DEVICE_PATH;\r
 \r
 ///\r
-/// Controller Device Path\r
+/// Controller Device Path SubType\r
 ///\r
 #define HW_CONTROLLER_DP          0x05\r
+\r
+///\r
+/// Controller Device Path\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -154,12 +170,12 @@ typedef struct {
 } CONTROLLER_DEVICE_PATH;\r
 \r
 ///\r
-/// ACPI Device Paths\r
+/// ACPI Device Paths \r
 ///\r
 #define ACPI_DEVICE_PATH          0x02\r
 \r
 ///\r
-/// ACPI Device Path\r
+/// ACPI Device Path SubType\r
 ///\r
 #define ACPI_DP                   0x01\r
 typedef struct {\r
@@ -181,7 +197,7 @@ typedef struct {
 } ACPI_HID_DEVICE_PATH;\r
 \r
 ///\r
-/// Expanded ACPI Device Path.\r
+/// Expanded ACPI Device Path SubType\r
 ///\r
 #define ACPI_EXTENDED_DP          0x02\r
 typedef struct {\r
@@ -227,13 +243,16 @@ typedef struct {
 #define PNP_EISA_ID_MASK          0xffff\r
 #define EISA_ID_TO_NUM(_Id)       ((_Id) >> 16)\r
 \r
+///\r
+/// ACPI _ADR Device Path SubType\r
+///\r
+#define ACPI_ADR_DP               0x03\r
 \r
 ///\r
 /// The _ADR device path is used to contain video output device attributes to support the Graphics\r
 /// Output Protocol. The device path can contain multiple _ADR entries if multiple video output\r
 /// devices are displaying the same output.\r
 ///\r
-#define ACPI_ADR_DP               0x03\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -242,9 +261,9 @@ typedef struct {
   /// least one _ADR value is required.\r
   ///\r
   UINT32                          ADR;\r
-  ///\r
-  /// This device path may optionally contain more than one _ADR entry.\r
-  ///\r
+  //\r
+  // This device path may optionally contain more than one _ADR entry.\r
+  //\r
 } ACPI_ADR_DEVICE_PATH;\r
 \r
 #define ACPI_ADR_DISPLAY_TYPE_OTHER             0\r
@@ -272,7 +291,7 @@ typedef struct {
 #define MESSAGING_DEVICE_PATH     0x03\r
 \r
 ///\r
-/// ATAPI Device Path\r
+/// ATAPI Device Path SubType\r
 ///\r
 #define MSG_ATAPI_DP              0x01\r
 typedef struct {\r
@@ -292,7 +311,7 @@ typedef struct {
 } ATAPI_DEVICE_PATH;\r
 \r
 ///\r
-/// SCSI Device Path\r
+/// SCSI Device Path SubType\r
 ///\r
 #define MSG_SCSI_DP               0x02\r
 typedef struct {\r
@@ -308,7 +327,7 @@ typedef struct {
 } SCSI_DEVICE_PATH;\r
 \r
 ///\r
-/// Fibre Channel\r
+/// Fibre Channel SubType\r
 ///\r
 #define MSG_FIBRECHANNEL_DP       0x03\r
 typedef struct {\r
@@ -328,7 +347,7 @@ typedef struct {
 } FIBRECHANNEL_DEVICE_PATH;\r
 \r
 ///\r
-/// 1394 Device Path\r
+/// 1394 Device Path SubType\r
 ///\r
 #define MSG_1394_DP               0x04\r
 typedef struct {\r
@@ -344,7 +363,7 @@ typedef struct {
 } F1394_DEVICE_PATH;\r
 \r
 ///\r
-/// USB Device Path\r
+/// USB Device Path SubType\r
 ///\r
 #define MSG_USB_DP                0x05\r
 typedef struct {\r
@@ -360,7 +379,7 @@ typedef struct {
 } USB_DEVICE_PATH;\r
 \r
 ///\r
-/// USB Class Device Path\r
+/// USB Class Device Path SubType\r
 ///\r
 #define MSG_USB_CLASS_DP          0x0f\r
 typedef struct {\r
@@ -393,10 +412,13 @@ typedef struct {
 } USB_CLASS_DEVICE_PATH;\r
 \r
 ///\r
-/// This device path describes a USB device using its serial number.\r
-/// USB WWID Device Path\r
+/// USB WWID Device Path SubType\r
 ///\r
 #define MSG_USB_WWID_DP           0x10\r
+\r
+///\r
+/// This device path describes a USB device using its serial number.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL      Header;\r
   ///\r
@@ -421,7 +443,7 @@ typedef struct {
 } USB_WWID_DEVICE_PATH;\r
 \r
 ///\r
-/// Device Logical Unit\r
+/// Device Logical Unit SubType\r
 ///\r
 #define MSG_DEVICE_LOGICAL_UNIT_DP  0x11\r
 typedef struct {\r
@@ -433,7 +455,7 @@ typedef struct {
 } DEVICE_LOGICAL_UNIT_DEVICE_PATH;\r
 \r
 ///\r
-/// SATA Device Path\r
+/// SATA Device Path SubType\r
 ///\r
 #define MSG_SATA_DP               0x12\r
 typedef struct {\r
@@ -456,7 +478,7 @@ typedef struct {
 } SATA_DEVICE_PATH;\r
 \r
 ///\r
-/// I2O Device Path \r
+/// I2O Device Path SubType\r
 ///\r
 #define MSG_I2O_DP                0x06\r
 typedef struct {\r
@@ -468,7 +490,7 @@ typedef struct {
 } I2O_DEVICE_PATH;\r
 \r
 ///\r
-/// MAC Address Device Path\r
+/// MAC Address Device Path SubType\r
 ///\r
 #define MSG_MAC_ADDR_DP           0x0b\r
 typedef struct {\r
@@ -484,7 +506,7 @@ typedef struct {
 } MAC_ADDR_DEVICE_PATH;\r
 \r
 ///\r
-/// IPv4 Device Path\r
+/// IPv4 Device Path SubType\r
 ///\r
 #define MSG_IPv4_DP               0x0c\r
 typedef struct {\r
@@ -517,7 +539,7 @@ typedef struct {
 } IPv4_DEVICE_PATH;\r
 \r
 ///\r
-/// IPv6 Device Path\r
+/// IPv6 Device Path SubType\r
 ///\r
 #define MSG_IPv6_DP               0x0d\r
 typedef struct {\r
@@ -550,7 +572,7 @@ typedef struct {
 } IPv6_DEVICE_PATH;\r
 \r
 ///\r
-/// InfiniBand Device Path\r
+/// InfiniBand Device Path SubType\r
 ///\r
 #define MSG_INFINIBAND_DP         0x09\r
 typedef struct {\r
@@ -591,7 +613,7 @@ typedef struct {
 #define INFINIBAND_RESOURCE_FLAG_NETWORK_PROTOCOL           0x10\r
 \r
 ///\r
-/// UART Device Path\r
+/// UART Device Path SubType\r
 ///\r
 #define MSG_UART_DP               0x0e\r
 typedef struct {\r
@@ -641,15 +663,16 @@ typedef VENDOR_DEVICE_PATH        VENDOR_DEFINED_DEVICE_PATH;
 #define DEVICE_PATH_MESSAGING_VT_100_PLUS EFI_VT_100_PLUS_GUID\r
 #define DEVICE_PATH_MESSAGING_VT_UTF8     EFI_VT_UTF8_GUID\r
 \r
+#define DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL   EFI_UART_DEVICE_PATH_GUID\r
+\r
 ///\r
 /// A new device path node is defined to declare flow control characteristics.\r
 /// UART Flow Control Messaging Device Path\r
 ///\r
-#define DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL   EFI_UART_DEVICE_PATH_GUID\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
-  /// DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL\r
+  /// DEVICE_PATH_MESSAGING_UART_FLOW_CONTROL GUID\r
   ///\r
   EFI_GUID                        Guid;\r
   ///\r
@@ -661,14 +684,14 @@ typedef struct {
   UINT32                          FlowControlMap;\r
 } UART_FLOW_CONTROL_DEVICE_PATH;\r
 \r
+#define DEVICE_PATH_MESSAGING_SAS                 EFI_SAS_DEVICE_PATH_GUID\r
 ///\r
 /// Serial Attached SCSI (SAS) devices.\r
 ///\r
-#define DEVICE_PATH_MESSAGING_SAS                 EFI_SAS_DEVICE_PATH_GUID\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
-  /// DEVICE_PATH_MESSAGING_SAS\r
+  /// DEVICE_PATH_MESSAGING_SAS GUID\r
   ///\r
   EFI_GUID                        Guid;\r
   ///\r
@@ -694,7 +717,7 @@ typedef struct {
 } SAS_DEVICE_PATH;\r
 \r
 ///\r
-/// iSCSI Device Path Node (Base Information)\r
+/// iSCSI Device Path SubType\r
 ///\r
 #define MSG_ISCSI_DP              0x13\r
 typedef struct {\r
@@ -738,10 +761,13 @@ typedef struct {
 #define MEDIA_DEVICE_PATH         0x04\r
 \r
 ///\r
-/// The Hard Drive Media Device Path is used to represent a partition on a hard drive.\r
-/// Hard Drive Media Device Path\r
+/// Hard Drive Media Device Path SubType\r
 ///\r
 #define MEDIA_HARDDRIVE_DP        0x01\r
+\r
+///\r
+/// The Hard Drive Media Device Path is used to represent a partition on a hard drive.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -787,10 +813,13 @@ typedef struct {
 #define SIGNATURE_TYPE_GUID       0x02\r
 \r
 ///\r
-/// The CD-ROM Media Device Path is used to define a system partition that exists on a CD-ROM.\r
-/// CD-ROM Media Device Path\r
+/// CD-ROM Media Device Path SubType\r
 ///\r
 #define MEDIA_CDROM_DP            0x02\r
+\r
+///\r
+/// The CD-ROM Media Device Path is used to define a system partition that exists on a CD-ROM.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -807,13 +836,13 @@ typedef struct {
   UINT64                          PartitionSize;\r
 } CDROM_DEVICE_PATH;\r
 \r
-///\r
-/// Use VENDOR_DEVICE_PATH struct\r
-///\r
-#define MEDIA_VENDOR_DP           0x03\r
+//\r
+// Use VENDOR_DEVICE_PATH struct\r
+//\r
+#define MEDIA_VENDOR_DP           0x03  ///< Media vendor device path subtype\r
 \r
 ///\r
-/// File Path Media Device Path\r
+/// File Path Media Device Path SubType\r
 ///\r
 #define MEDIA_FILEPATH_DP         0x04\r
 typedef struct {\r
@@ -826,12 +855,16 @@ typedef struct {
 \r
 #define SIZE_OF_FILEPATH_DEVICE_PATH  EFI_FIELD_OFFSET(FILEPATH_DEVICE_PATH,PathName)\r
 \r
+///\r
+/// Media Protocol Device Path SubType\r
+///\r
+#define MEDIA_PROTOCOL_DP         0x05\r
+\r
 ///\r
 /// The Media Protocol Device Path is used to denote the protocol that is being \r
 /// used in a device path at the location of the path specified. \r
 /// Many protocols are inherent to the style of device path.\r
 ///\r
-#define MEDIA_PROTOCOL_DP         0x05\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -841,10 +874,13 @@ typedef struct {
 } MEDIA_PROTOCOL_DEVICE_PATH;\r
 \r
 ///\r
-/// This type is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware volume.\r
-/// PIWG Firmware Volume Device Path.\r
+/// PIWG Firmware Volume Device Path SubType\r
 ///\r
 #define MEDIA_PIWG_FW_VOL_DP      0x7\r
+\r
+///\r
+/// This device path is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware volume.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -854,10 +890,13 @@ typedef struct {
 } MEDIA_FW_VOL_DEVICE_PATH;\r
 \r
 ///\r
-/// This type is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware file.\r
-/// PIWG Firmware Volume Device Path\r
+/// PIWG Firmware Volume Device Path SubType\r
 ///\r
 #define MEDIA_PIWG_FW_FILE_DP     0x6\r
+\r
+///\r
+/// This device path is used by systems implementing the UEFI PI Specification 1.0 to describe a firmware file.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -867,11 +906,18 @@ typedef struct {
 } MEDIA_FW_VOL_FILEPATH_DEVICE_PATH;\r
 \r
 ///\r
-/// This Device Path is used to describe the booting of non-EFI-aware operating systems.\r
 /// BIOS Boot Specification Device Path\r
 ///\r
 #define BBS_DEVICE_PATH           0x05\r
+\r
+///\r
+/// BIOS Boot Specification Device Path SubType\r
+///\r
 #define BBS_BBS_DP                0x01\r
+\r
+///\r
+/// This Device Path is used to describe the booting of non-EFI-aware operating systems.\r
+///\r
 typedef struct {\r
   EFI_DEVICE_PATH_PROTOCOL        Header;\r
   ///\r
@@ -904,7 +950,6 @@ typedef struct {
 ///\r
 /// Union of all possible Device Paths and pointers to Device Paths\r
 ///\r
-\r
 typedef union {\r
   EFI_DEVICE_PATH_PROTOCOL             DevPath;\r
   PCI_DEVICE_PATH                      Pci;\r