Update comments for Protocol definitions to match UEFI spec.

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

diff --git a/MdePkg/Include/Protocol/PxeBaseCode.h b/MdePkg/Include/Protocol/PxeBaseCode.h
index 9fec1fd09c639f5cd81e7f533271978be4cbb3c4..afc0b664dff937aacba63ae01c707ebc8e83b76d 100644 (file)
--- a/MdePkg/Include/Protocol/PxeBaseCode.h
+++ b/MdePkg/Include/Protocol/PxeBaseCode.h
@@ -1,7 +1,8 @@
 /** @file\r
-  EFI PXE Base Code Protocol definitions.\r
+  EFI PXE Base Code Protocol definitions, which is used to access PXE-compatible \r
+  devices for network access and network booting.\r
 \r
-  Copyright (c) 2006, Intel Corporation                                                         \r
+  Copyright (c) 2006 - 2008, Intel Corporation                                                         \r
   All rights reserved. This program and the accompanying materials                          \r
   are licensed and made available under the terms and conditions of the BSD License         \r
   which accompanies this distribution.  The full text of the license may be found at        \r
@@ -14,9 +15,9 @@
 #ifndef __PXE_BASE_CODE_PROTOCOL_H__\r
 #define __PXE_BASE_CODE_PROTOCOL_H__\r
 \r
-//\r
-// PXE Base Code protocol\r
-//\r
+///\r
+/// PXE Base Code protocol\r
+///\r
 #define EFI_PXE_BASE_CODE_PROTOCOL_GUID \\r
   { \\r
     0x03c4e603, 0xac28, 0x11d3, {0x9a, 0x2d, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \\r
@@ -24,20 +25,20 @@
 \r
 typedef struct _EFI_PXE_BASE_CODE_PROTOCOL  EFI_PXE_BASE_CODE_PROTOCOL;\r
 \r
-//\r
-// Protocol defined in EFI1.1.\r
-// \r
+///\r
+/// Protocol defined in EFI1.1.\r
+/// \r
 typedef EFI_PXE_BASE_CODE_PROTOCOL  EFI_PXE_BASE_CODE;\r
 \r
-//\r
-// Default IP TTL and ToS.\r
-//\r
+///\r
+/// Default IP TTL and ToS.\r
+///\r
 #define DEFAULT_TTL 16\r
 #define DEFAULT_ToS 0\r
 \r
-//\r
-// ICMP error format\r
-//\r
+///\r
+/// ICMP error format\r
+///\r
 typedef struct {\r
   UINT8   Type;\r
   UINT8   Code;\r
@@ -54,17 +55,17 @@ typedef struct {
   UINT8 Data[494];\r
 } EFI_PXE_BASE_CODE_ICMP_ERROR;\r
 \r
-//\r
-// TFTP error format\r
-//\r
+///\r
+/// TFTP error format\r
+///\r
 typedef struct {\r
   UINT8 ErrorCode;\r
   CHAR8 ErrorString[127];\r
 } EFI_PXE_BASE_CODE_TFTP_ERROR;\r
 \r
-//\r
-// IP Receive Filter definitions\r
-//\r
+///\r
+/// IP Receive Filter definitions\r
+///\r
 #define EFI_PXE_BASE_CODE_MAX_IPCNT 8\r
 \r
 typedef struct {\r
@@ -79,9 +80,9 @@ typedef struct {
 #define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS           0x0004\r
 #define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS_MULTICAST 0x0008\r
 \r
-//\r
-// ARP Cache definitions\r
-//\r
+///\r
+/// ARP Cache definitions\r
+///\r
 typedef struct {\r
   EFI_IP_ADDRESS  IpAddr;\r
   EFI_MAC_ADDRESS MacAddr;\r
@@ -135,9 +136,9 @@ typedef UINT16  EFI_PXE_BASE_CODE_UDP_PORT;
 #define EFI_PXE_BASE_CODE_BOOT_LAYER_MASK     0x7FFF\r
 #define EFI_PXE_BASE_CODE_BOOT_LAYER_INITIAL  0x0000\r
 \r
-//\r
-// Discover() server list structure.\r
-//\r
+///\r
+/// Discover() server list structure.\r
+///\r
 typedef struct {\r
   UINT16          Type;\r
   BOOLEAN         AcceptAnyResponse;\r
@@ -145,9 +146,9 @@ typedef struct {
   EFI_IP_ADDRESS  IpAddr;\r
 } EFI_PXE_BASE_CODE_SRVLIST;\r
 \r
-//\r
-// Discover() information override structure.\r
-//\r
+///\r
+/// Discover() information override structure.\r
+///\r
 typedef struct {\r
   BOOLEAN                   UseMCast;\r
   BOOLEAN                   UseBCast;\r
@@ -158,9 +159,9 @@ typedef struct {
   EFI_PXE_BASE_CODE_SRVLIST SrvList[1];\r
 } EFI_PXE_BASE_CODE_DISCOVER_INFO;\r
 \r
-//\r
-// Mtftp() definitions\r
-//\r
+///\r
+/// Mtftp() definitions\r
+///\r
 typedef enum {\r
   EFI_PXE_BASE_CODE_TFTP_FIRST,\r
   EFI_PXE_BASE_CODE_TFTP_GET_FILE_SIZE,\r
@@ -181,6 +182,38 @@ typedef struct {
   UINT16                      TransmitTimeout;\r
 } EFI_PXE_BASE_CODE_MTFTP_INFO;\r
 \r
+///\r
+/// Packet definitions\r
+///\r
+typedef struct {\r
+  UINT8   BootpOpcode;\r
+  UINT8   BootpHwType;\r
+  UINT8   BootpHwAddrLen;\r
+  UINT8   BootpGateHops;\r
+  UINT32  BootpIdent;\r
+  UINT16  BootpSeconds;\r
+  UINT16  BootpFlags;\r
+  UINT8   BootpCiAddr[4];\r
+  UINT8   BootpYiAddr[4];\r
+  UINT8   BootpSiAddr[4];\r
+  UINT8   BootpGiAddr[4];\r
+  UINT8   BootpHwAddr[16];\r
+  UINT8   BootpSrvName[64];\r
+  UINT8   BootpBootFile[128];\r
+  UINT32  DhcpMagik;\r
+  UINT8   DhcpOptions[56];\r
+} EFI_PXE_BASE_CODE_DHCPV4_PACKET;\r
+\r
+typedef union {\r
+  UINT8                           Raw[1472];\r
+  EFI_PXE_BASE_CODE_DHCPV4_PACKET Dhcpv4;\r
+\r
+  ///\r
+  ///  EFI_PXE_BASE_CODE_DHCPV6_PACKET     Dhcpv6;\r
+  ///\r
+} EFI_PXE_BASE_CODE_PACKET;\r
+\r
+\r
 //\r
 // PXE Base Code Mode structure\r
 //\r
@@ -249,7 +282,7 @@ typedef struct {
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_START) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_START)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN BOOLEAN                               UseIpv6\r
   );\r
@@ -268,7 +301,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_STOP) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_STOP)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL    *This\r
   );\r
 \r
@@ -294,7 +327,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_DHCP) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_DHCP)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN BOOLEAN                               SortOffers\r
   );\r
@@ -324,7 +357,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_DISCOVER) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_DISCOVER)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL           *This,\r
   IN UINT16                               Type,\r
   IN UINT16                               *Layer,\r
@@ -362,7 +395,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_MTFTP) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_MTFTP)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,\r
   IN EFI_PXE_BASE_CODE_TFTP_OPCODE             Operation,\r
   IN OUT VOID                                  *BufferPtr OPTIONAL,\r
@@ -403,7 +436,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_UDP_WRITE) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_UDP_WRITE)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,\r
   IN UINT16                                    OpFlags,\r
   IN EFI_IP_ADDRESS                            *DestIp,\r
@@ -445,7 +478,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_UDP_READ) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_UDP_READ)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,\r
   IN UINT16                                    OpFlags,\r
   IN OUT EFI_IP_ADDRESS                        *DestIp,     OPTIONAL\r
@@ -471,7 +504,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_SET_IP_FILTER) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_SET_IP_FILTER)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN EFI_PXE_BASE_CODE_IP_FILTER           *NewFilter\r
   );\r
@@ -494,7 +527,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_ARP) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_ARP)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN EFI_IP_ADDRESS                        *IpAddr,\r
   IN EFI_MAC_ADDRESS                       *MacAddr OPTIONAL\r
@@ -522,7 +555,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_SET_PARAMETERS) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_SET_PARAMETERS)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN BOOLEAN                               *NewAutoArp,     OPTIONAL\r
   IN BOOLEAN                               *NewSendGUID,    OPTIONAL\r
@@ -545,7 +578,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_SET_STATION_IP) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_SET_STATION_IP)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   IN EFI_IP_ADDRESS                        *NewStationIp,   OPTIONAL\r
   IN EFI_IP_ADDRESS                        *NewSubnetMask   OPTIONAL\r
@@ -581,7 +614,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_PXE_BASE_CODE_SET_PACKETS) (\r
+(EFIAPI *EFI_PXE_BASE_CODE_SET_PACKETS)(\r
   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,\r
   BOOLEAN                                  *NewDhcpDiscoverValid,   OPTIONAL\r
   BOOLEAN                                  *NewDhcpAckReceived,     OPTIONAL\r
@@ -607,7 +640,20 @@ EFI_STATUS
 // \r
 #define EFI_PXE_BASE_CODE_INTERFACE_REVISION  EFI_PXE_BASE_CODE_PROTOCOL_REVISION\r
 \r
+///\r
+/// The EFI_PXE_BASE_CODE_PROTOCOL is used to control PXE-compatible devices.\r
+/// An EFI_PXE_BASE_CODE_PROTOCOL will be layered on top of an\r
+/// EFI_MANAGED_NETWORK_PROTOCOL protocol in order to perform packet level transactions.\r
+/// The EFI_PXE_BASE_CODE_PROTOCOL handle also supports the\r
+/// EFI_LOAD_FILE_PROTOCOL protocol. This provides a clean way to obtain control from the\r
+/// boot manager if the boot path is from the remote device.\r
+///\r
 struct _EFI_PXE_BASE_CODE_PROTOCOL {\r
+  ///\r
+  ///  The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must \r
+  ///  be backwards compatible. If a future version is not backwards compatible \r
+  ///  it is not the same GUID.\r
+  ///\r
   UINT64                            Revision;\r
   EFI_PXE_BASE_CODE_START           Start;\r
   EFI_PXE_BASE_CODE_STOP            Stop;\r
@@ -621,6 +667,9 @@ struct _EFI_PXE_BASE_CODE_PROTOCOL {
   EFI_PXE_BASE_CODE_SET_PARAMETERS  SetParameters;\r
   EFI_PXE_BASE_CODE_SET_STATION_IP  SetStationIp;\r
   EFI_PXE_BASE_CODE_SET_PACKETS     SetPackets;\r
+  ///\r
+  /// Pointer to the EFI_PXE_BASE_CODE_MODE data for this device.\r
+  ///\r
   EFI_PXE_BASE_CODE_MODE            *Mode;\r
 };\r
 \r