MdePkg/Include/Protocol/PxeBaseCode.h

   1 /** @file
   2   EFI PXE Base Code Protocol definitions, which is used to access PXE-compatible
   3   devices for network access and network booting.
   4
   5   Copyright (c) 2006 - 2008, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15 #ifndef __PXE_BASE_CODE_PROTOCOL_H__
  16 #define __PXE_BASE_CODE_PROTOCOL_H__
  17
  18 ///
  19 /// PXE Base Code protocol
  20 ///
  21 #define EFI_PXE_BASE_CODE_PROTOCOL_GUID \
  22   { \
  23     0x03c4e603, 0xac28, 0x11d3, {0x9a, 0x2d, 0x00, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  24   }
  25
  26 typedef struct _EFI_PXE_BASE_CODE_PROTOCOL  EFI_PXE_BASE_CODE_PROTOCOL;
  27
  28 ///
  29 /// Protocol defined in EFI1.1.
  30 ///
  31 typedef EFI_PXE_BASE_CODE_PROTOCOL  EFI_PXE_BASE_CODE;
  32
  33 ///
  34 /// Default IP TTL and ToS.
  35 ///
  36 #define DEFAULT_TTL 16
  37 #define DEFAULT_ToS 0
  38
  39 ///
  40 /// ICMP error format
  41 ///
  42 typedef struct {
  43   UINT8   Type;
  44   UINT8   Code;
  45   UINT16  Checksum;
  46   union {
  47     UINT32  reserved;
  48     UINT32  Mtu;
  49     UINT32  Pointer;
  50     struct {
  51       UINT16  Identifier;
  52       UINT16  Sequence;
  53     } Echo;
  54   } u;
  55   UINT8 Data[494];
  56 } EFI_PXE_BASE_CODE_ICMP_ERROR;
  57
  58 ///
  59 /// TFTP error format
  60 ///
  61 typedef struct {
  62   UINT8 ErrorCode;
  63   CHAR8 ErrorString[127];
  64 } EFI_PXE_BASE_CODE_TFTP_ERROR;
  65
  66 ///
  67 /// IP Receive Filter definitions
  68 ///
  69 #define EFI_PXE_BASE_CODE_MAX_IPCNT 8
  70
  71 ///
  72 /// IP Receive Filter structure
  73 ///
  74 typedef struct {
  75   UINT8           Filters;
  76   UINT8           IpCnt;
  77   UINT16          reserved;
  78   EFI_IP_ADDRESS  IpList[EFI_PXE_BASE_CODE_MAX_IPCNT];
  79 } EFI_PXE_BASE_CODE_IP_FILTER;
  80
  81 #define EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP            0x0001
  82 #define EFI_PXE_BASE_CODE_IP_FILTER_BROADCAST             0x0002
  83 #define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS           0x0004
  84 #define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS_MULTICAST 0x0008
  85
  86 ///
  87 /// ARP cache entries
  88 ///
  89 typedef struct {
  90   EFI_IP_ADDRESS  IpAddr;
  91   EFI_MAC_ADDRESS MacAddr;
  92 } EFI_PXE_BASE_CODE_ARP_ENTRY;
  93
  94 ///
  95 /// ARP route table entries
  96 ///
  97 typedef struct {
  98   EFI_IP_ADDRESS  IpAddr;
  99   EFI_IP_ADDRESS  SubnetMask;
 100   EFI_IP_ADDRESS  GwAddr;
 101 } EFI_PXE_BASE_CODE_ROUTE_ENTRY;
 102
 103 //
 104 // UDP definitions
 105 //
 106 typedef UINT16  EFI_PXE_BASE_CODE_UDP_PORT;
 107
 108 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_SRC_IP    0x0001
 109 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_SRC_PORT  0x0002
 110 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_DEST_IP   0x0004
 111 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_DEST_PORT 0x0008
 112 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_USE_FILTER    0x0010
 113 #define EFI_PXE_BASE_CODE_UDP_OPFLAGS_MAY_FRAGMENT  0x0020
 114
 115 //
 116 // Discover() definitions
 117 //
 118 #define EFI_PXE_BASE_CODE_BOOT_TYPE_BOOTSTRAP         0
 119 #define EFI_PXE_BASE_CODE_BOOT_TYPE_MS_WINNT_RIS      1
 120 #define EFI_PXE_BASE_CODE_BOOT_TYPE_INTEL_LCM         2
 121 #define EFI_PXE_BASE_CODE_BOOT_TYPE_DOSUNDI           3
 122 #define EFI_PXE_BASE_CODE_BOOT_TYPE_NEC_ESMPRO        4
 123 #define EFI_PXE_BASE_CODE_BOOT_TYPE_IBM_WSoD          5
 124 #define EFI_PXE_BASE_CODE_BOOT_TYPE_IBM_LCCM          6
 125 #define EFI_PXE_BASE_CODE_BOOT_TYPE_CA_UNICENTER_TNG  7
 126 #define EFI_PXE_BASE_CODE_BOOT_TYPE_HP_OPENVIEW       8
 127 #define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_9         9
 128 #define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_10        10
 129 #define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_11        11
 130 #define EFI_PXE_BASE_CODE_BOOT_TYPE_NOT_USED_12       12
 131 #define EFI_PXE_BASE_CODE_BOOT_TYPE_REDHAT_INSTALL    13
 132 #define EFI_PXE_BASE_CODE_BOOT_TYPE_REDHAT_BOOT       14
 133 #define EFI_PXE_BASE_CODE_BOOT_TYPE_REMBO             15
 134 #define EFI_PXE_BASE_CODE_BOOT_TYPE_BEOBOOT           16
 135 //
 136 // 17 through 32767 are reserved
 137 // 32768 through 65279 are for vendor use
 138 // 65280 through 65534 are reserved
 139 //
 140 #define EFI_PXE_BASE_CODE_BOOT_TYPE_PXETEST   65535
 141
 142 #define EFI_PXE_BASE_CODE_BOOT_LAYER_MASK     0x7FFF
 143 #define EFI_PXE_BASE_CODE_BOOT_LAYER_INITIAL  0x0000
 144
 145 ///
 146 /// Discover() server list structure.
 147 ///
 148 typedef struct {
 149   UINT16          Type;
 150   BOOLEAN         AcceptAnyResponse;
 151   UINT8           Reserved;
 152   EFI_IP_ADDRESS  IpAddr;
 153 } EFI_PXE_BASE_CODE_SRVLIST;
 154
 155 ///
 156 /// Discover() information override structure.
 157 ///
 158 typedef struct {
 159   BOOLEAN                   UseMCast;
 160   BOOLEAN                   UseBCast;
 161   BOOLEAN                   UseUCast;
 162   BOOLEAN                   MustUseList;
 163   EFI_IP_ADDRESS            ServerMCastIp;
 164   UINT16                    IpCnt;
 165   EFI_PXE_BASE_CODE_SRVLIST SrvList[1];
 166 } EFI_PXE_BASE_CODE_DISCOVER_INFO;
 167
 168 ///
 169 /// TFTP opcode definitions
 170 ///
 171 typedef enum {
 172   EFI_PXE_BASE_CODE_TFTP_FIRST,
 173   EFI_PXE_BASE_CODE_TFTP_GET_FILE_SIZE,
 174   EFI_PXE_BASE_CODE_TFTP_READ_FILE,
 175   EFI_PXE_BASE_CODE_TFTP_WRITE_FILE,
 176   EFI_PXE_BASE_CODE_TFTP_READ_DIRECTORY,
 177   EFI_PXE_BASE_CODE_MTFTP_GET_FILE_SIZE,
 178   EFI_PXE_BASE_CODE_MTFTP_READ_FILE,
 179   EFI_PXE_BASE_CODE_MTFTP_READ_DIRECTORY,
 180   EFI_PXE_BASE_CODE_MTFTP_LAST
 181 } EFI_PXE_BASE_CODE_TFTP_OPCODE;
 182
 183 ///
 184 /// MTFTP information. This information is required
 185 /// to start or join a multicast TFTP session. It is also required to
 186 /// perform the "get file size" and "read directory" operations of MTFTP.
 187 ///
 188 typedef struct {
 189   EFI_IP_ADDRESS              MCastIp;
 190   EFI_PXE_BASE_CODE_UDP_PORT  CPort;
 191   EFI_PXE_BASE_CODE_UDP_PORT  SPort;
 192   UINT16                      ListenTimeout;
 193   UINT16                      TransmitTimeout;
 194 } EFI_PXE_BASE_CODE_MTFTP_INFO;
 195
 196 ///
 197 /// DHCPV4 Packet structure
 198 ///
 199 typedef struct {
 200   UINT8   BootpOpcode;
 201   UINT8   BootpHwType;
 202   UINT8   BootpHwAddrLen;
 203   UINT8   BootpGateHops;
 204   UINT32  BootpIdent;
 205   UINT16  BootpSeconds;
 206   UINT16  BootpFlags;
 207   UINT8   BootpCiAddr[4];
 208   UINT8   BootpYiAddr[4];
 209   UINT8   BootpSiAddr[4];
 210   UINT8   BootpGiAddr[4];
 211   UINT8   BootpHwAddr[16];
 212   UINT8   BootpSrvName[64];
 213   UINT8   BootpBootFile[128];
 214   UINT32  DhcpMagik;
 215   UINT8   DhcpOptions[56];
 216 } EFI_PXE_BASE_CODE_DHCPV4_PACKET;
 217
 218 ///
 219 /// Packet structure
 220 ///
 221 typedef union {
 222   UINT8                           Raw[1472];
 223   EFI_PXE_BASE_CODE_DHCPV4_PACKET Dhcpv4;
 224   //
 225   //  EFI_PXE_BASE_CODE_DHCPV6_PACKET     Dhcpv6;
 226   //
 227 } EFI_PXE_BASE_CODE_PACKET;
 228
 229 //
 230 // PXE Base Code Mode structure
 231 //
 232 #define EFI_PXE_BASE_CODE_MAX_ARP_ENTRIES   8
 233 #define EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES 8
 234
 235 ///
 236 /// EFI_PXE_BASE_CODE_MODE
 237 /// The data values in this structure are read-only and
 238 /// are updated by the code that produces the
 239 /// EFI_PXE_BASE_CODE_PROTOCOL functions.
 240 ///
 241 typedef struct {
 242   BOOLEAN                       Started;
 243   BOOLEAN                       Ipv6Available;
 244   BOOLEAN                       Ipv6Supported;
 245   BOOLEAN                       UsingIpv6;
 246   BOOLEAN                       BisSupported;
 247   BOOLEAN                       BisDetected;
 248   BOOLEAN                       AutoArp;
 249   BOOLEAN                       SendGUID;
 250   BOOLEAN                       DhcpDiscoverValid;
 251   BOOLEAN                       DhcpAckReceived;
 252   BOOLEAN                       ProxyOfferReceived;
 253   BOOLEAN                       PxeDiscoverValid;
 254   BOOLEAN                       PxeReplyReceived;
 255   BOOLEAN                       PxeBisReplyReceived;
 256   BOOLEAN                       IcmpErrorReceived;
 257   BOOLEAN                       TftpErrorReceived;
 258   BOOLEAN                       MakeCallbacks;
 259   UINT8                         TTL;
 260   UINT8                         ToS;
 261   EFI_IP_ADDRESS                StationIp;
 262   EFI_IP_ADDRESS                SubnetMask;
 263   EFI_PXE_BASE_CODE_PACKET      DhcpDiscover;
 264   EFI_PXE_BASE_CODE_PACKET      DhcpAck;
 265   EFI_PXE_BASE_CODE_PACKET      ProxyOffer;
 266   EFI_PXE_BASE_CODE_PACKET      PxeDiscover;
 267   EFI_PXE_BASE_CODE_PACKET      PxeReply;
 268   EFI_PXE_BASE_CODE_PACKET      PxeBisReply;
 269   EFI_PXE_BASE_CODE_IP_FILTER   IpFilter;
 270   UINT32                        ArpCacheEntries;
 271   EFI_PXE_BASE_CODE_ARP_ENTRY   ArpCache[EFI_PXE_BASE_CODE_MAX_ARP_ENTRIES];
 272   UINT32                        RouteTableEntries;
 273   EFI_PXE_BASE_CODE_ROUTE_ENTRY RouteTable[EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES];
 274   EFI_PXE_BASE_CODE_ICMP_ERROR  IcmpError;
 275   EFI_PXE_BASE_CODE_TFTP_ERROR  TftpError;
 276 } EFI_PXE_BASE_CODE_MODE;
 277
 278 //
 279 // PXE Base Code Interface Function definitions
 280 //
 281
 282 /**
 283   Enables the use of the PXE Base Code Protocol functions.
 284
 285   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 286   @param  UseIpv6               Specifies the type of IP addresses that are to be used during the session
 287                                 that is being started. Set to TRUE for IPv6 addresses, and FALSE for
 288                                 IPv4 addresses.
 289
 290   @retval EFI_SUCCESS           The PXE Base Code Protocol was started.
 291   @retval EFI_DEVICE_ERROR      The network device encountered an error during this oper
 292   @retval EFI_UNSUPPORTED       UseIpv6 is TRUE, but the Ipv6Supported field of the
 293                                 EFI_PXE_BASE_CODE_MODE structure is FALSE.
 294   @retval EFI_ALREADY_STARTED   The PXE Base Code Protocol is already in the started state.
 295   @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid
 296                                 EFI_PXE_BASE_CODE_PROTOCOL structure.
 297   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough memory or other resources to start the
 298                                 PXE Base Code Protocol.
 299
 300 **/
 301 typedef
 302 EFI_STATUS
 303 (EFIAPI *EFI_PXE_BASE_CODE_START)(
 304   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 305   IN BOOLEAN                               UseIpv6
 306   );
 307
 308 /**
 309   Disables the use of the PXE Base Code Protocol functions.
 310
 311   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 312
 313   @retval EFI_SUCCESS           The PXE Base Code Protocol was stopped.
 314   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is already in the stopped state.
 315   @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid
 316                                 EFI_PXE_BASE_CODE_PROTOCOL structure.
 317   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 318
 319 **/
 320 typedef
 321 EFI_STATUS
 322 (EFIAPI *EFI_PXE_BASE_CODE_STOP)(
 323   IN EFI_PXE_BASE_CODE_PROTOCOL    *This
 324   );
 325
 326 /**
 327   Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6
 328   S.A.R.R (solicit / advertise / request / reply) sequence.
 329
 330   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 331   @param  SortOffers            TRUE if the offers received should be sorted. Set to FALSE to try the
 332                                 offers in the order that they are received.
 333
 334   @retval EFI_SUCCESS           Valid DHCP has completed.
 335   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 336   @retval EFI_INVALID_PARAMETER The This parameter is NULL or does not point to a valid
 337                                 EFI_PXE_BASE_CODE_PROTOCOL structure.
 338   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 339   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough memory to complete the DHCP Protocol.
 340   @retval EFI_ABORTED           The callback function aborted the DHCP Protocol.
 341   @retval EFI_TIMEOUT           The DHCP Protocol timed out.
 342   @retval EFI_ICMP_ERROR        An ICMP error packet was received during the DHCP session.
 343   @retval EFI_NO_RESPONSE       Valid PXE offer was not received.
 344
 345 **/
 346 typedef
 347 EFI_STATUS
 348 (EFIAPI *EFI_PXE_BASE_CODE_DHCP)(
 349   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 350   IN BOOLEAN                               SortOffers
 351   );
 352
 353 /**
 354   Attempts to complete the PXE Boot Server and/or boot image discovery sequence.
 355
 356   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 357   @param  Type                  The type of bootstrap to perform.
 358   @param  Layer                 Pointer to the boot server layer number to discover, which must be
 359                                 PXE_BOOT_LAYER_INITIAL when a new server type is being
 360                                 discovered.
 361   @param  UseBis                TRUE if Boot Integrity Services are to be used. FALSE otherwise.
 362   @param  Info                  Pointer to a data structure that contains additional information on the
 363                                 type of discovery operation that is to be performed.
 364
 365   @retval EFI_SUCCESS           The Discovery sequence has been completed.
 366   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 367   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 368   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 369   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough memory to complete Discovery.
 370   @retval EFI_ABORTED           The callback function aborted the Discovery sequence.
 371   @retval EFI_TIMEOUT           The Discovery sequence timed out.
 372   @retval EFI_ICMP_ERROR        An ICMP error packet was received during the PXE discovery
 373                                 session.
 374
 375 **/
 376 typedef
 377 EFI_STATUS
 378 (EFIAPI *EFI_PXE_BASE_CODE_DISCOVER)(
 379   IN EFI_PXE_BASE_CODE_PROTOCOL           *This,
 380   IN UINT16                               Type,
 381   IN UINT16                               *Layer,
 382   IN BOOLEAN                              UseBis,
 383   IN EFI_PXE_BASE_CODE_DISCOVER_INFO      *Info   OPTIONAL
 384   );
 385
 386 /**
 387   Used to perform TFTP and MTFTP services.
 388
 389   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 390   @param  Operation             The type of operation to perform.
 391   @param  BufferPtr             A pointer to the data buffer.
 392   @param  Overwrite             Only used on write file operations. TRUE if a file on a remote server can
 393                                 be overwritten.
 394   @param  BufferSize            For get-file-size operations, *BufferSize returns the size of the
 395                                 requested file.
 396   @param  BlockSize             The requested block size to be used during a TFTP transfer.
 397   @param  ServerIp              The TFTP / MTFTP server IP address.
 398   @param  Filename              A Null-terminated ASCII string that specifies a directory name or a file
 399                                 name.
 400   @param  Info                  Pointer to the MTFTP information.
 401   @param  DontUseBuffer         Set to FALSE for normal TFTP and MTFTP read file operation.
 402
 403   @retval EFI_SUCCESS           The TFTP/MTFTP operation was completed.
 404   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 405   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 406   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 407   @retval EFI_BUFFER_TOO_SMALL  The buffer is not large enough to complete the read operation.
 408   @retval EFI_ABORTED           The callback function aborted the TFTP/MTFTP operation.
 409   @retval EFI_TIMEOUT           The TFTP/MTFTP operation timed out.
 410   @retval EFI_ICMP_ERROR        An ICMP error packet was received during the MTFTP session.
 411   @retval EFI_TFTP_ERROR        A TFTP error packet was received during the MTFTP session.
 412
 413 **/
 414 typedef
 415 EFI_STATUS
 416 (EFIAPI *EFI_PXE_BASE_CODE_MTFTP)(
 417   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,
 418   IN EFI_PXE_BASE_CODE_TFTP_OPCODE             Operation,
 419   IN OUT VOID                                  *BufferPtr OPTIONAL,
 420   IN BOOLEAN                                   Overwrite,
 421   IN OUT UINT64                                *BufferSize,
 422   IN UINTN                                     *BlockSize OPTIONAL,
 423   IN EFI_IP_ADDRESS                            *ServerIp,
 424   IN UINT8                                     *Filename  OPTIONAL,
 425   IN EFI_PXE_BASE_CODE_MTFTP_INFO              *Info      OPTIONAL,
 426   IN BOOLEAN                                   DontUseBuffer
 427   );
 428
 429 /**
 430   Writes a UDP packet to the network interface.
 431
 432   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 433   @param  OpFlags               The UDP operation flags.
 434   @param  DestIp                The destination IP address.
 435   @param  DestPort              The destination UDP port number.
 436   @param  GatewayIp             The gateway IP address.
 437   @param  SrcIp                 The source IP address.
 438   @param  SrcPort               The source UDP port number.
 439   @param  HeaderSize            An optional field which may be set to the length of a header at
 440                                 HeaderPtr to be prefixed to the data at BufferPtr.
 441   @param  HeaderPtr             If HeaderSize is not NULL, a pointer to a header to be prefixed to the
 442                                 data at BufferPtr.
 443   @param  BufferSize            A pointer to the size of the data at BufferPtr.
 444   @param  BufferPtr             A pointer to the data to be written.
 445
 446   @retval EFI_SUCCESS           The UDP Write operation was completed.
 447   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 448   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 449   @retval EFI_BAD_BUFFER_SIZE   The buffer is too long to be transmitted.
 450   @retval EFI_ABORTED           The callback function aborted the UDP Write operation.
 451   @retval EFI_TIMEOUT           The UDP Write operation timed out.
 452   @retval EFI_ICMP_ERROR        An ICMP error packet was received during the UDP write session.
 453
 454 **/
 455 typedef
 456 EFI_STATUS
 457 (EFIAPI *EFI_PXE_BASE_CODE_UDP_WRITE)(
 458   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,
 459   IN UINT16                                    OpFlags,
 460   IN EFI_IP_ADDRESS                            *DestIp,
 461   IN EFI_PXE_BASE_CODE_UDP_PORT                *DestPort,
 462   IN EFI_IP_ADDRESS                            *GatewayIp,  OPTIONAL
 463   IN EFI_IP_ADDRESS                            *SrcIp,      OPTIONAL
 464   IN OUT EFI_PXE_BASE_CODE_UDP_PORT            *SrcPort,    OPTIONAL
 465   IN UINTN                                     *HeaderSize, OPTIONAL
 466   IN VOID                                      *HeaderPtr,  OPTIONAL
 467   IN UINTN                                     *BufferSize,
 468   IN VOID                                      *BufferPtr
 469   );
 470
 471 /**
 472   Reads a UDP packet from the network interface.
 473
 474   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 475   @param  OpFlags               The UDP operation flags.
 476   @param  DestIp                The destination IP address.
 477   @param  DestPort              The destination UDP port number.
 478   @param  GatewayIp             The gateway IP address.
 479   @param  SrcIp                 The source IP address.
 480   @param  SrcPort               The source UDP port number.
 481   @param  HeaderSize            An optional field which may be set to the length of a header at
 482                                 HeaderPtr to be prefixed to the data at BufferPtr.
 483   @param  HeaderPtr             If HeaderSize is not NULL, a pointer to a header to be prefixed to the
 484                                 data at BufferPtr.
 485   @param  BufferSize            A pointer to the size of the data at BufferPtr.
 486   @param  BufferPtr             A pointer to the data to be read.
 487
 488   @retval EFI_SUCCESS           The UDP Write operation was completed.
 489   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 490   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 491   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 492   @retval EFI_BUFFER_TOO_SMALL  The packet is larger than Buffer can hold.
 493   @retval EFI_ABORTED           The callback function aborted the UDP Read operation.
 494   @retval EFI_TIMEOUT           The UDP Read operation timed out.
 495
 496 **/
 497 typedef
 498 EFI_STATUS
 499 (EFIAPI *EFI_PXE_BASE_CODE_UDP_READ)(
 500   IN EFI_PXE_BASE_CODE_PROTOCOL                *This,
 501   IN UINT16                                    OpFlags,
 502   IN OUT EFI_IP_ADDRESS                        *DestIp,     OPTIONAL
 503   IN OUT EFI_PXE_BASE_CODE_UDP_PORT            *DestPort,   OPTIONAL
 504   IN OUT EFI_IP_ADDRESS                        *SrcIp,      OPTIONAL
 505   IN OUT EFI_PXE_BASE_CODE_UDP_PORT            *SrcPort,    OPTIONAL
 506   IN UINTN                                     *HeaderSize, OPTIONAL
 507   IN VOID                                      *HeaderPtr,  OPTIONAL
 508   IN OUT UINTN                                 *BufferSize,
 509   IN VOID                                      *BufferPtr
 510   );
 511
 512 /**
 513   Updates the IP receive filters of a network device and enables software filtering.
 514
 515   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 516   @param  NewFilter             Pointer to the new set of IP receive filters.
 517
 518   @retval EFI_SUCCESS           The IP receive filter settings were updated.
 519   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 520   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 521
 522 **/
 523 typedef
 524 EFI_STATUS
 525 (EFIAPI *EFI_PXE_BASE_CODE_SET_IP_FILTER)(
 526   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 527   IN EFI_PXE_BASE_CODE_IP_FILTER           *NewFilter
 528   );
 529
 530 /**
 531   Uses the ARP protocol to resolve a MAC address.
 532
 533   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 534   @param  IpAddr                Pointer to the IP address that is used to resolve a MAC address.
 535   @param  MacAddr               If not NULL, a pointer to the MAC address that was resolved with the
 536                                 ARP protocol.
 537
 538   @retval EFI_SUCCESS           The IP or MAC address was resolved.
 539   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 540   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 541   @retval EFI_DEVICE_ERROR      The network device encountered an error during this operation.
 542   @retval EFI_ABORTED           The callback function aborted the ARP Protocol.
 543   @retval EFI_TIMEOUT           The ARP Protocol encountered a timeout condition.
 544
 545 **/
 546 typedef
 547 EFI_STATUS
 548 (EFIAPI *EFI_PXE_BASE_CODE_ARP)(
 549   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 550   IN EFI_IP_ADDRESS                        *IpAddr,
 551   IN EFI_MAC_ADDRESS                       *MacAddr OPTIONAL
 552   );
 553
 554 /**
 555   Updates the parameters that affect the operation of the PXE Base Code Protocol.
 556
 557   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 558   @param  NewAutoArp            If not NULL, a pointer to a value that specifies whether to replace the
 559                                 current value of AutoARP.
 560   @param  NewSendGUID           If not NULL, a pointer to a value that specifies whether to replace the
 561                                 current value of SendGUID.
 562   @param  NewTTL                If not NULL, a pointer to be used in place of the current value of TTL,
 563                                 the "time to live" field of the IP header.
 564   @param  NewToS                If not NULL, a pointer to be used in place of the current value of ToS,
 565                                 the "type of service" field of the IP header.
 566   @param  NewMakeCallback       If not NULL, a pointer to a value that specifies whether to replace the
 567                                 current value of the MakeCallback field of the Mode structure.
 568
 569   @retval EFI_SUCCESS           The new parameters values were updated.
 570   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 571   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 572
 573 **/
 574 typedef
 575 EFI_STATUS
 576 (EFIAPI *EFI_PXE_BASE_CODE_SET_PARAMETERS)(
 577   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 578   IN BOOLEAN                               *NewAutoArp,     OPTIONAL
 579   IN BOOLEAN                               *NewSendGUID,    OPTIONAL
 580   IN UINT8                                 *NewTTL,         OPTIONAL
 581   IN UINT8                                 *NewToS,         OPTIONAL
 582   IN BOOLEAN                               *NewMakeCallback OPTIONAL
 583   );
 584
 585 /**
 586   Updates the station IP address and/or subnet mask values of a network device.
 587
 588   @param  This                  Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 589   @param  NewStationIp          Pointer to the new IP address to be used by the network device.
 590   @param  NewSubnetMask         Pointer to the new subnet mask to be used by the network device.
 591
 592   @retval EFI_SUCCESS           The new station IP address and/or subnet mask were updated.
 593   @retval EFI_NOT_STARTED       The PXE Base Code Protocol is in the stopped state.
 594   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 595
 596 **/
 597 typedef
 598 EFI_STATUS
 599 (EFIAPI *EFI_PXE_BASE_CODE_SET_STATION_IP)(
 600   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 601   IN EFI_IP_ADDRESS                        *NewStationIp,   OPTIONAL
 602   IN EFI_IP_ADDRESS                        *NewSubnetMask   OPTIONAL
 603   );
 604
 605 /**
 606   Updates the contents of the cached DHCP and Discover packets.
 607
 608   @param  This                   Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.
 609   @param  NewDhcpDiscoverValid   Pointer to a value that will replace the current
 610                                  DhcpDiscoverValid field.
 611   @param  NewDhcpAckReceived     Pointer to a value that will replace the current
 612                                  DhcpAckReceived field.
 613   @param  NewProxyOfferReceived  Pointer to a value that will replace the current
 614                                  ProxyOfferReceived field.
 615   @param  NewPxeDiscoverValid    Pointer to a value that will replace the current
 616                                  ProxyOfferReceived field.
 617   @param  NewPxeReplyReceived    Pointer to a value that will replace the current
 618                                  PxeReplyReceived field.
 619   @param  NewPxeBisReplyReceived Pointer to a value that will replace the current
 620                                  PxeBisReplyReceived field.
 621   @param  NewDhcpDiscover        Pointer to the new cached DHCP Discover packet contents.
 622   @param  NewDhcpAck             Pointer to the new cached DHCP Ack packet contents.
 623   @param  NewProxyOffer          Pointer to the new cached Proxy Offer packet contents.
 624   @param  NewPxeDiscover         Pointer to the new cached PXE Discover packet contents.
 625   @param  NewPxeReply            Pointer to the new cached PXE Reply packet contents.
 626   @param  NewPxeBisReply         Pointer to the new cached PXE BIS Reply packet contents.
 627
 628   @retval EFI_SUCCESS            The cached packet contents were updated.
 629   @retval EFI_NOT_STARTED        The PXE Base Code Protocol is in the stopped state.
 630   @retval EFI_INVALID_PARAMETER  This is NULL or not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure.
 631
 632 **/
 633 typedef
 634 EFI_STATUS
 635 (EFIAPI *EFI_PXE_BASE_CODE_SET_PACKETS)(
 636   IN EFI_PXE_BASE_CODE_PROTOCOL            *This,
 637   BOOLEAN                                  *NewDhcpDiscoverValid,   OPTIONAL
 638   BOOLEAN                                  *NewDhcpAckReceived,     OPTIONAL
 639   BOOLEAN                                  *NewProxyOfferReceived,  OPTIONAL
 640   BOOLEAN                                  *NewPxeDiscoverValid,    OPTIONAL
 641   BOOLEAN                                  *NewPxeReplyReceived,    OPTIONAL
 642   BOOLEAN                                  *NewPxeBisReplyReceived, OPTIONAL
 643   IN EFI_PXE_BASE_CODE_PACKET              *NewDhcpDiscover,        OPTIONAL
 644   IN EFI_PXE_BASE_CODE_PACKET              *NewDhcpAck,             OPTIONAL
 645   IN EFI_PXE_BASE_CODE_PACKET              *NewProxyOffer,          OPTIONAL
 646   IN EFI_PXE_BASE_CODE_PACKET              *NewPxeDiscover,         OPTIONAL
 647   IN EFI_PXE_BASE_CODE_PACKET              *NewPxeReply,            OPTIONAL
 648   IN EFI_PXE_BASE_CODE_PACKET              *NewPxeBisReply          OPTIONAL
 649   );
 650
 651 //
 652 // PXE Base Code Protocol structure
 653 //
 654 #define EFI_PXE_BASE_CODE_PROTOCOL_REVISION   0x00010000
 655
 656 //
 657 // Revision defined in EFI1.1
 658 //
 659 #define EFI_PXE_BASE_CODE_INTERFACE_REVISION  EFI_PXE_BASE_CODE_PROTOCOL_REVISION
 660
 661 ///
 662 /// The EFI_PXE_BASE_CODE_PROTOCOL is used to control PXE-compatible devices.
 663 /// An EFI_PXE_BASE_CODE_PROTOCOL will be layered on top of an
 664 /// EFI_MANAGED_NETWORK_PROTOCOL protocol in order to perform packet level transactions.
 665 /// The EFI_PXE_BASE_CODE_PROTOCOL handle also supports the
 666 /// EFI_LOAD_FILE_PROTOCOL protocol. This provides a clean way to obtain control from the
 667 /// boot manager if the boot path is from the remote device.
 668 ///
 669 struct _EFI_PXE_BASE_CODE_PROTOCOL {
 670   ///
 671   ///  The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must
 672   ///  be backwards compatible. If a future version is not backwards compatible
 673   ///  it is not the same GUID.
 674   ///
 675   UINT64                            Revision;
 676   EFI_PXE_BASE_CODE_START           Start;
 677   EFI_PXE_BASE_CODE_STOP            Stop;
 678   EFI_PXE_BASE_CODE_DHCP            Dhcp;
 679   EFI_PXE_BASE_CODE_DISCOVER        Discover;
 680   EFI_PXE_BASE_CODE_MTFTP           Mtftp;
 681   EFI_PXE_BASE_CODE_UDP_WRITE       UdpWrite;
 682   EFI_PXE_BASE_CODE_UDP_READ        UdpRead;
 683   EFI_PXE_BASE_CODE_SET_IP_FILTER   SetIpFilter;
 684   EFI_PXE_BASE_CODE_ARP             Arp;
 685   EFI_PXE_BASE_CODE_SET_PARAMETERS  SetParameters;
 686   EFI_PXE_BASE_CODE_SET_STATION_IP  SetStationIp;
 687   EFI_PXE_BASE_CODE_SET_PACKETS     SetPackets;
 688   ///
 689   /// Pointer to the EFI_PXE_BASE_CODE_MODE data for this device.
 690   ///
 691   EFI_PXE_BASE_CODE_MODE            *Mode;
 692 };
 693
 694 extern EFI_GUID gEfiPxeBaseCodeProtocolGuid;
 695
 696 #endif