StdLib/EfiSocketLib/Socket.h

   1 /** @file
   2   Definitions for the Socket layer driver.
   3
   4   Copyright (c) 2011, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14 #ifndef _SOCKET_H_
  15 #define _SOCKET_H_
  16
  17 #include <Efi/EfiSocketLib.h>
  18
  19 //------------------------------------------------------------------------------
  20 //  Constants
  21 //------------------------------------------------------------------------------
  22
  23 #define DEBUG_SOCKET        0x20000000  ///<  Display Socket related messages
  24 #define DEBUG_BIND          0x10000000  ///<  Display bind related messages
  25 #define DEBUG_LISTEN        0x08000000  ///<  Display listen related messages
  26 #define DEBUG_CONNECTION    0x04000000  ///<  Display connection list related messages
  27 #define DEBUG_POLL          0x02000000  ///<  Display poll messages
  28 #define DEBUG_ACCEPT        0x01000000  ///<  Display accept related messages
  29 #define DEBUG_RX            0x00800000  ///<  Display receive messages
  30 #define DEBUG_TX            0x00400000  ///<  Display transmit messages
  31 #define DEBUG_CLOSE         0x00200000  ///<  Display close messages
  32 #define DEBUG_CONNECT       0x00100000  ///<  Display connect messages
  33 #define DEBUG_OPTION        0x00080000  ///<  Display option messages
  34
  35 #define MAX_PENDING_CONNECTIONS     1   ///<  Maximum connection FIFO depth
  36 #define MAX_RX_DATA         65536       ///<  Maximum receive data size
  37 #define MAX_TX_DATA         ( MAX_RX_DATA * 2 ) ///<  Maximum buffered transmit data in bytes
  38 #define RX_PACKET_DATA      16384       ///<  Maximum number of bytes in a RX packet
  39 #define MAX_UDP_RETRANSMIT  16          ///<  UDP retransmit attempts to handle address not mapped
  40
  41 #define ESL_STRUCTURE_ALIGNMENT_BYTES   15  ///<  Number of bytes for structure alignment
  42 #define ESL_STRUCTURE_ALIGNMENT_MASK    ( ~ESL_STRUCTURE_ALIGNMENT_BYTES )  ///<  Mask to align structures
  43
  44 #define LAYER_SIGNATURE           SIGNATURE_32 ('S','k','t','L')  ///<  ESL_LAYER memory signature
  45 #define SERVICE_SIGNATURE         SIGNATURE_32 ('S','k','t','S')  ///<  ESL_SERVICE memory signature
  46 #define SOCKET_SIGNATURE          SIGNATURE_32 ('S','c','k','t')  ///<  ESL_SOCKET memory signature
  47 #define PORT_SIGNATURE            SIGNATURE_32 ('P','o','r','t')  ///<  ESL_PORT memory signature
  48
  49
  50 /**
  51   Socket states
  52 **/
  53 typedef enum
  54 {
  55   SOCKET_STATE_NOT_CONFIGURED = 0,  ///<  socket call was successful
  56   SOCKET_STATE_BOUND,               ///<  bind call was successful
  57   SOCKET_STATE_LISTENING,           ///<  listen call was successful
  58   SOCKET_STATE_NO_PORTS,            ///<  No ports available
  59   SOCKET_STATE_IN_FIFO,             ///<  Socket on FIFO
  60   SOCKET_STATE_CONNECTING,          ///<  Connecting to a remote system
  61   SOCKET_STATE_CONNECTED,           ///<  Accept or connect call was successful
  62
  63   //
  64   //  Close state must be the last in the list
  65   //
  66   SOCKET_STATE_CLOSED               ///<  Close call was successful
  67 } SOCKET_STATE;
  68
  69
  70 /**
  71   Port states
  72 **/
  73 typedef enum
  74 {
  75   PORT_STATE_ALLOCATED = 0, ///<  Port allocated
  76   PORT_STATE_OPEN,          ///<  Port opened
  77   PORT_STATE_RX_ERROR,      ///<  Receive error detected
  78
  79   //
  80   //  Close state must be last in the list!
  81   //
  82   //  Using < <= > >= in tests code to detect port close state
  83   //  machine has started
  84   //
  85   PORT_STATE_CLOSE_STARTED, ///<  Close started on port
  86   PORT_STATE_CLOSE_TX_DONE, ///<  Transmits shutdown
  87   PORT_STATE_CLOSE_DONE,    ///<  Port close operation complete
  88   PORT_STATE_CLOSE_RX_DONE  ///<  Receives shutdown
  89 } PORT_STATE;
  90
  91 //------------------------------------------------------------------------------
  92 //  Data Types
  93 //------------------------------------------------------------------------------
  94
  95 typedef struct _ESL_IO_MGMT ESL_IO_MGMT;///<  Forward declaration
  96 typedef struct _ESL_PACKET ESL_PACKET;  ///<  Forward declaration
  97 typedef struct _ESL_PORT ESL_PORT;      ///<  Forward declaration
  98 typedef struct _ESL_SOCKET ESL_SOCKET;  ///<  Forward declaration
  99
 100 /**
 101   Receive context for SOCK_RAW sockets using IPv4.
 102 **/
 103 typedef struct
 104 {
 105   EFI_IP4_RECEIVE_DATA * pRxData;       ///<  Receive operation description
 106 } ESL_IP4_RX_DATA;
 107
 108
 109 /**
 110   Transmit context for SOCK_RAW sockets using IPv4.
 111 **/
 112 typedef struct
 113 {
 114   EFI_IP4_OVERRIDE_DATA Override;       ///<  Override data
 115   EFI_IP4_TRANSMIT_DATA TxData;         ///<  Transmit operation description
 116   UINT8 Buffer[ 1 ];                    ///<  Data buffer
 117 } ESL_IP4_TX_DATA;
 118
 119
 120 /**
 121   Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.
 122 **/
 123 typedef struct
 124 {
 125   EFI_TCP4_RECEIVE_DATA RxData;         ///<  Receive operation description
 126   UINT8 Buffer[ RX_PACKET_DATA ];       ///<  Data buffer
 127 } ESL_TCP4_RX_DATA;
 128
 129
 130 /**
 131   Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.
 132 **/
 133 typedef struct
 134 {
 135   EFI_TCP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 136   UINT8 Buffer[ 1 ];                    ///<  Data buffer
 137 } ESL_TCP4_TX_DATA;
 138
 139
 140 /**
 141   Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6.
 142 **/
 143 typedef struct
 144 {
 145   EFI_TCP6_RECEIVE_DATA RxData;         ///<  Receive operation description
 146   UINT8 Buffer[ RX_PACKET_DATA ];       ///<  Data buffer
 147 } ESL_TCP6_RX_DATA;
 148
 149
 150 /**
 151   Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6.
 152 **/
 153 typedef struct
 154 {
 155   EFI_TCP6_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 156   UINT8 Buffer[ 1 ];                    ///<  Data buffer
 157 } ESL_TCP6_TX_DATA;
 158
 159
 160 /**
 161   Receive context for SOCK_DGRAM sockets using UDPv4.
 162 **/
 163 typedef struct
 164 {
 165   EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address
 166   EFI_UDP4_RECEIVE_DATA * pRxData;      ///<  Receive operation description
 167 } ESL_UDP4_RX_DATA;
 168
 169
 170 /**
 171   Transmit context for SOCK_DGRAM sockets using UDPv4.
 172 **/
 173 typedef struct
 174 {
 175   EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address
 176   EFI_UDP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 177   UINTN RetransmitCount;                ///<  Retransmit to handle ARP negotiation
 178   UINT8 Buffer[ 1 ];                    ///<  Data buffer
 179 } ESL_UDP4_TX_DATA;
 180
 181
 182 /**
 183   Receive context for SOCK_DGRAM sockets using UDPv6.
 184 **/
 185 typedef struct
 186 {
 187   EFI_UDP6_SESSION_DATA Session;        ///<  Remote network address
 188   EFI_UDP6_RECEIVE_DATA * pRxData;      ///<  Receive operation description
 189 } ESL_UDP6_RX_DATA;
 190
 191
 192 /**
 193   Transmit context for SOCK_DGRAM sockets using UDPv6.
 194 **/
 195 typedef struct
 196 {
 197   EFI_UDP6_SESSION_DATA Session;        ///<  Remote network address
 198   EFI_UDP6_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 199   UINTN RetransmitCount;                ///<  Retransmit to handle ARP negotiation
 200   UINT8 Buffer[ 1 ];                    ///<  Data buffer
 201 } ESL_UDP6_TX_DATA;
 202
 203
 204 /**
 205   Network specific context for transmit and receive packets.
 206 **/
 207 typedef struct _ESL_PACKET {
 208   ESL_PACKET * pNext;                   ///<  Next packet in the receive list
 209   size_t PacketSize;                    ///<  Size of this data structure
 210   size_t ValidBytes;                    ///<  Length of valid data in bytes
 211   UINT8 * pBuffer;                      ///<  Current data pointer
 212   union {
 213     ESL_IP4_RX_DATA Ip4Rx;              ///<  Receive operation description
 214     ESL_IP4_TX_DATA Ip4Tx;              ///<  Transmit operation description
 215     ESL_TCP4_RX_DATA Tcp4Rx;            ///<  Receive operation description
 216     ESL_TCP4_TX_DATA Tcp4Tx;            ///<  Transmit operation description
 217     ESL_TCP6_RX_DATA Tcp6Rx;            ///<  Receive operation description
 218     ESL_TCP6_TX_DATA Tcp6Tx;            ///<  Transmit operation description
 219     ESL_UDP4_RX_DATA Udp4Rx;            ///<  Receive operation description
 220     ESL_UDP4_TX_DATA Udp4Tx;            ///<  Transmit operation description
 221     ESL_UDP6_RX_DATA Udp6Rx;            ///<  Receive operation description
 222     ESL_UDP6_TX_DATA Udp6Tx;            ///<  Transmit operation description
 223   } Op;                                 ///<  Network specific context
 224 } GCC_ESL_PACKET;
 225
 226 /**
 227   Service control structure
 228
 229   The driver uses this structure to manage the network devices.
 230 **/
 231 typedef struct _ESL_SERVICE {
 232   UINTN Signature;          ///<  Structure identification
 233
 234   //
 235   //  Links
 236   //
 237   ESL_SERVICE * pNext;      ///<  Next service in the service list
 238
 239   //
 240   //  Service data
 241   //
 242   CONST ESL_SOCKET_BINDING * pSocketBinding;      ///<  Name and shutdown routine
 243   EFI_HANDLE Controller;                          ///<  Controller for the service
 244   EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Network layer service binding interface
 245
 246   //
 247   //  Network data
 248   //
 249   ESL_PORT * pPortList;     ///<  List of ports using this service
 250 }GCC_ESL_SERVICE;
 251
 252 /**
 253   IO management structure
 254
 255   This structure manages a single operation with the network.
 256 **/
 257 typedef struct _ESL_IO_MGMT {
 258   ESL_IO_MGMT * pNext;                ///<  Next TX management structure
 259   ESL_PORT * pPort;                   ///<  Port structure address
 260   ESL_PACKET * pPacket;               ///<  Packet structure address
 261   union {
 262     EFI_IP4_COMPLETION_TOKEN Ip4Rx;   ///<  IP4 receive token
 263     EFI_IP4_COMPLETION_TOKEN Ip4Tx;   ///<  IP4 transmit token
 264     EFI_TCP4_IO_TOKEN Tcp4Rx;         ///<  TCP4 receive token
 265     EFI_TCP4_IO_TOKEN Tcp4Tx;         ///<  TCP4 transmit token
 266     EFI_TCP6_IO_TOKEN Tcp6Rx;         ///<  TCP6 receive token
 267     EFI_TCP6_IO_TOKEN Tcp6Tx;         ///<  TCP6 transmit token
 268     EFI_UDP4_COMPLETION_TOKEN Udp4Rx; ///<  UDP4 receive token
 269     EFI_UDP4_COMPLETION_TOKEN Udp4Tx; ///<  UDP4 transmit token
 270     EFI_UDP6_COMPLETION_TOKEN Udp6Rx; ///<  UDP6 receive token
 271     EFI_UDP6_COMPLETION_TOKEN Udp6Tx; ///<  UDP6 transmit token
 272   } Token;                            ///<  Completion token for the network operation
 273 } GCC_IO_MGMT;
 274
 275 /**
 276   IP4 context structure
 277
 278   The driver uses this structure to manage the IP4 connections.
 279 **/
 280 typedef struct {
 281   //
 282   //  IP4 context
 283   //
 284   EFI_IP4_MODE_DATA ModeData;           ///<  IP4 mode data, includes configuration data
 285   EFI_IPv4_ADDRESS DestinationAddress;  ///<  Default destination address
 286 } ESL_IP4_CONTEXT;
 287
 288
 289 /**
 290   TCP4 context structure
 291
 292   The driver uses this structure to manage the TCP4 connections.
 293 **/
 294 typedef struct {
 295   //
 296   //  TCP4 context
 297   //
 298   EFI_TCP4_CONFIG_DATA ConfigData;        ///<  TCP4 configuration data
 299   EFI_TCP4_OPTION Option;                 ///<  TCP4 port options
 300
 301   //
 302   //  Tokens
 303   //
 304   EFI_TCP4_LISTEN_TOKEN ListenToken;      ///<  Listen control
 305   EFI_TCP4_CONNECTION_TOKEN ConnectToken; ///<  Connection control
 306   EFI_TCP4_CLOSE_TOKEN CloseToken;        ///<  Close control
 307 } ESL_TCP4_CONTEXT;
 308
 309 /**
 310   TCP6 context structure
 311
 312   The driver uses this structure to manage the TCP6 connections.
 313 **/
 314 typedef struct {
 315   //
 316   //  TCP6 context
 317   //
 318   EFI_TCP6_CONFIG_DATA ConfigData;        ///<  TCP6 configuration data
 319   EFI_TCP6_OPTION Option;                 ///<  TCP6 port options
 320
 321   //
 322   //  Tokens
 323   //
 324   EFI_TCP6_LISTEN_TOKEN ListenToken;      ///<  Listen control
 325   EFI_TCP6_CONNECTION_TOKEN ConnectToken; ///<  Connection control
 326   EFI_TCP6_CLOSE_TOKEN CloseToken;        ///<  Close control
 327 } ESL_TCP6_CONTEXT;
 328
 329 /**
 330   UDP4 context structure
 331
 332   The driver uses this structure to manage the UDP4 connections.
 333 **/
 334 typedef struct {
 335   //
 336   //  UDP4 context
 337   //
 338   EFI_UDP4_CONFIG_DATA ConfigData;  ///<  UDP4 configuration data
 339 } ESL_UDP4_CONTEXT;
 340
 341 /**
 342   UDP6 context structure
 343
 344   The driver uses this structure to manage the UDP6 connections.
 345 **/
 346 typedef struct {
 347   //
 348   //  UDP6 context
 349   //
 350   EFI_UDP6_CONFIG_DATA ConfigData;  ///<  UDP6 configuration data
 351 } ESL_UDP6_CONTEXT;
 352
 353
 354 /**
 355   Configure the network layer.
 356
 357   @param [in] pProtocol   Protocol structure address
 358   @param [in] pConfigData Address of the confiuration data
 359
 360   @return   Returns EFI_SUCCESS if the operation is successfully
 361             started.
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (* PFN_NET_CONFIGURE) (
 366   IN VOID * pProtocol,
 367   IN VOID * pConfigData
 368   );
 369
 370 /**
 371   Hand an I/O operation to the network layer.
 372
 373   @param [in] pProtocol   Protocol structure address
 374   @param [in] pToken      Completion token address
 375
 376   @return   Returns EFI_SUCCESS if the operation is successfully
 377             started.
 378 **/
 379 typedef
 380 EFI_STATUS
 381 (* PFN_NET_IO_START) (
 382   IN VOID * pProtocol,
 383   IN VOID * pToken
 384   );
 385
 386 /**
 387   Poll the LAN adapter for receive packets.
 388
 389   @param [in] pProtocol   Protocol structure address
 390   @param [in] pToken      Completion token address
 391
 392   @return   Returns EFI_SUCCESS if the operation is successfully
 393             started.
 394 **/
 395 typedef
 396 EFI_STATUS
 397 (* PFN_NET_POLL) (
 398   IN VOID * pProtocol
 399   );
 400
 401 /**
 402   Port control structure
 403
 404   The driver uses this structure to manager the socket's connection
 405   with the network driver.
 406 **/
 407 typedef struct _ESL_PORT {
 408   UINTN Signature;              ///<  Structure identification
 409
 410   //
 411   //  List links
 412   //
 413   ESL_PORT * pLinkService;      ///<  Link in service port list
 414   ESL_PORT * pLinkSocket;       ///<  Link in socket port list
 415
 416   //
 417   //  Structures
 418   //
 419   ESL_SERVICE * pService;       ///<  Service for this port
 420   ESL_SOCKET * pSocket;         ///<  Socket for this port
 421
 422   //
 423   //  Eliminate the pService references during port close
 424   //
 425   EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Service binding for network layer
 426   CONST ESL_SOCKET_BINDING * pSocketBinding;      ///<  Socket binding for network layer
 427
 428   //
 429   //  Port management
 430   //
 431   EFI_HANDLE Handle;              ///<  Network port handle
 432   PORT_STATE State;               ///<  State of the port
 433   UINTN DebugFlags;               ///<  Debug flags used to close the port
 434   BOOLEAN bCloseNow;              ///<  TRUE = Close the port immediately
 435   BOOLEAN bConfigured;            ///<  TRUE = Configure call made to network layer
 436   PFN_NET_CONFIGURE pfnConfigure; ///<  Configure the network layer
 437
 438   //
 439   //  Transmit data management
 440   //
 441   BOOLEAN bTxFlowControl;       ///<  TX flow control applied
 442   PFN_NET_IO_START pfnTxStart;  ///<  Start a transmit on the network
 443   ESL_IO_MGMT * pTxActive;      ///<  Normal data queue
 444   ESL_IO_MGMT * pTxFree;        ///<  Normal free queue
 445
 446   ESL_IO_MGMT * pTxOobActive;   ///<  Urgent data queue
 447   ESL_IO_MGMT * pTxOobFree;     ///<  Urgent free queue
 448
 449   //
 450   //  Receive data management
 451   //
 452   PFN_NET_IO_START pfnRxCancel; ///<  Cancel a receive on the network
 453   PFN_NET_POLL pfnRxPoll;       ///<  Poll the LAN adapter for receive packets
 454   PFN_NET_IO_START pfnRxStart;  ///<  Start a receive on the network
 455   ESL_IO_MGMT * pRxActive;      ///<  Active receive operation queue
 456   ESL_IO_MGMT * pRxFree;        ///<  Free structure queue
 457
 458   //
 459   //  Protocol specific management data
 460   //
 461   union {
 462     VOID * v;                   ///<  VOID pointer
 463     EFI_IP4_PROTOCOL * IPv4;    ///<  IP4 protocol pointer
 464     EFI_TCP4_PROTOCOL * TCPv4;  ///<  TCP4 protocol pointer
 465     EFI_TCP6_PROTOCOL * TCPv6;  ///<  TCP6 protocol pointer
 466     EFI_UDP4_PROTOCOL * UDPv4;  ///<  UDP4 protocol pointer
 467     EFI_UDP6_PROTOCOL * UDPv6;  ///<  UDP6 protocol pointer
 468   } pProtocol;                  ///<  Protocol structure address
 469   union {
 470     ESL_IP4_CONTEXT Ip4;        ///<  IPv4 management data
 471     ESL_TCP4_CONTEXT Tcp4;      ///<  TCPv4 management data
 472     ESL_TCP6_CONTEXT Tcp6;      ///<  TCPv6 management data
 473     ESL_UDP4_CONTEXT Udp4;      ///<  UDPv4 management data
 474     ESL_UDP6_CONTEXT Udp6;      ///<  UDPv6 management data
 475   } Context;                    ///<  Network specific context
 476 }GCC_ESL_PORT;
 477
 478 /**
 479   Accept a network connection.
 480
 481   @param [in] pSocket   Address of the socket structure.
 482
 483   @param [in] pSockAddr       Address of a buffer to receive the remote
 484                               network address.
 485
 486   @param [in, out] pSockAddrLength  Length in bytes of the address buffer.
 487                                     On output specifies the length of the
 488                                     remote network address.
 489
 490   @retval EFI_SUCCESS   Remote address is available
 491   @retval Others        Remote address not available
 492
 493  **/
 494 typedef
 495 EFI_STATUS
 496 (* PFN_API_ACCEPT) (
 497   IN ESL_SOCKET * pSocket,
 498   IN struct sockaddr * pSockAddr,
 499   IN OUT socklen_t * pSockAddrLength
 500   );
 501
 502 /**
 503   Poll for completion of the connection attempt.
 504
 505   @param [in] pSocket   Address of an ::ESL_SOCKET structure.
 506
 507   @retval EFI_SUCCESS   The connection was successfully established.
 508   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 509   @retval Others        The connection attempt failed.
 510
 511  **/
 512 typedef
 513 EFI_STATUS
 514 (* PFN_API_CONNECT_POLL) (
 515   IN ESL_SOCKET * pSocket
 516   );
 517
 518 /**
 519   Attempt to connect to a remote TCP port
 520
 521   This routine starts the connection processing for a SOCK_STREAM
 522   or SOCK_SEQPAKCET socket using the TCP network layer.
 523
 524   This routine is called by ::EslSocketConnect to initiate the TCP
 525   network specific connect operations.
 526
 527   @param [in] pSocket   Address of an ::ESL_SOCKET structure.
 528
 529   @retval EFI_SUCCESS   The connection was successfully established.
 530   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 531   @retval Others        The connection attempt failed.
 532
 533  **/
 534 typedef
 535 EFI_STATUS
 536 (* PFN_API_CONNECT_START) (
 537   IN ESL_SOCKET * pSocket
 538   );
 539
 540 /**
 541   Get the local socket address
 542
 543   @param [in] pPort       Address of an ::ESL_PORT structure.
 544
 545   @param [out] pAddress   Network address to receive the local system address
 546
 547 **/
 548 typedef
 549 VOID
 550 (* PFN_API_LOCAL_ADDR_GET) (
 551   IN ESL_PORT * pPort,
 552   OUT struct sockaddr * pAddress
 553   );
 554
 555 /**
 556   Set the local port address.
 557
 558   This routine sets the local port address.
 559
 560   This support routine is called by ::EslSocketPortAllocate.
 561
 562   @param [in] ppPort      Address of an ESL_PORT structure
 563   @param [in] pSockAddr   Address of a sockaddr structure that contains the
 564                           connection point on the local machine.  An IPv4 address
 565                           of INADDR_ANY specifies that the connection is made to
 566                           all of the network stacks on the platform.  Specifying a
 567                           specific IPv4 address restricts the connection to the
 568                           network stack supporting that address.  Specifying zero
 569                           for the port causes the network layer to assign a port
 570                           number from the dynamic range.  Specifying a specific
 571                           port number causes the network layer to use that port.
 572   @param [in] bBindTest   TRUE = run bind testing
 573
 574   @retval EFI_SUCCESS     The operation was successful
 575
 576  **/
 577 typedef
 578 EFI_STATUS
 579 (* PFN_API_LOCAL_ADDR_SET) (
 580   IN ESL_PORT * pPort,
 581   IN CONST struct sockaddr * pSockAddr,
 582   IN BOOLEAN bBindTest
 583   );
 584
 585 /**
 586   Process the completion event
 587
 588   This routine handles the I/O completion event.
 589
 590   This routine is called by the low level network driver when
 591   the operation is completed.
 592
 593   @param [in] Event     The receive completion event
 594
 595   @param [in] pIo       The address of an ::ESL_IO_MGMT structure
 596
 597 **/
 598 typedef
 599 VOID
 600 (* PFN_API_IO_COMPLETE) (
 601   IN EFI_EVENT Event,
 602   IN ESL_IO_MGMT * pIo
 603   );
 604
 605 /**
 606   Determine if the socket is configured.
 607
 608
 609   @param [in] pSocket         Address of a ESL_SOCKET structure
 610
 611   @retval EFI_SUCCESS - The port is connected
 612   @retval EFI_NOT_STARTED - The port is not connected
 613
 614  **/
 615  typedef
 616  EFI_STATUS
 617  (* PFN_API_IS_CONFIGURED) (
 618   IN ESL_SOCKET * pSocket
 619   );
 620
 621 /**
 622   Establish the known port to listen for network connections.
 623
 624   @param [in] pSocket     Address of the socket structure.
 625
 626   @retval EFI_SUCCESS - Socket successfully created
 627   @retval Other - Failed to enable the socket for listen
 628
 629 **/
 630 typedef
 631 EFI_STATUS
 632 (* PFN_API_LISTEN) (
 633   IN ESL_SOCKET * pSocket
 634   );
 635
 636 /**
 637   Get the option value
 638
 639   Retrieve the protocol options one at a time by name.
 640
 641   @param [in] pSocket           Address of a ESL_SOCKET structure
 642   @param [in] OptionName        Name of the option
 643   @param [out] ppOptionData     Buffer to receive address of option value
 644   @param [out] pOptionLength    Buffer to receive the option length
 645
 646   @retval EFI_SUCCESS - Socket data successfully received
 647
 648  **/
 649 typedef
 650 EFI_STATUS
 651 (* PFN_API_OPTION_GET) (
 652   IN ESL_SOCKET * pSocket,
 653   IN int OptionName,
 654   OUT CONST void ** __restrict ppOptionData,
 655   OUT socklen_t * __restrict pOptionLength
 656   );
 657
 658 /**
 659   Set the option value
 660
 661   Adjust the protocol options one at a time by name.
 662
 663   @param [in] pSocket         Address of a ESL_SOCKET structure
 664   @param [in] OptionName      Name of the option
 665   @param [in] pOptionValue    Buffer containing the option value
 666   @param [in] OptionLength    Length of the buffer in bytes
 667
 668   @retval EFI_SUCCESS - Option successfully set
 669
 670  **/
 671 typedef
 672 EFI_STATUS
 673 (* PFN_API_OPTION_SET) (
 674   IN ESL_SOCKET * pSocket,
 675   IN int OptionName,
 676   IN CONST void * pOptionValue,
 677   IN socklen_t OptionLength
 678   );
 679
 680 /**
 681   Free a receive packet
 682
 683   This routine performs the network specific operations necessary
 684   to free a receive packet.
 685
 686   This routine is called by ::EslSocketPortCloseTxDone to free a
 687   receive packet.
 688
 689   @param [in] pPacket         Address of an ::ESL_PACKET structure.
 690   @param [in, out] pRxBytes   Address of the count of RX bytes
 691
 692 **/
 693 typedef
 694 VOID
 695 (* PFN_API_PACKET_FREE) (
 696   IN ESL_PACKET * pPacket,
 697   IN OUT size_t * pRxBytes
 698   );
 699
 700 /**
 701   Initialize the network specific portions of an ::ESL_PORT structure.
 702
 703   This routine initializes the network specific portions of an
 704   ::ESL_PORT structure for use by the socket.
 705
 706   This support routine is called by ::EslSocketPortAllocate
 707   to connect the socket with the underlying network adapter
 708   running the IPv4 protocol.
 709
 710   @param [in] ppPort      Address of an ESL_PORT structure
 711   @param [in] DebugFlags  Flags for debug messages
 712
 713   @retval EFI_SUCCESS - Socket successfully created
 714
 715  **/
 716 typedef
 717 EFI_STATUS
 718 (* PFN_API_PORT_ALLOC) (
 719   IN ESL_PORT * pPort,
 720   IN UINTN DebugFlags
 721   );
 722
 723 /**
 724   Close a network specific port.
 725
 726   This routine releases the resources allocated by the
 727   network specific PortAllocate routine.
 728
 729   This routine is called by ::EslSocketPortCloseRxDone as
 730   the last step of closing processing.
 731   See the \ref PortCloseStateMachine section.
 732
 733   @param [in] pPort       Address of an ::ESL_PORT structure.
 734
 735   @retval EFI_SUCCESS     The port is closed
 736   @retval other           Port close error
 737
 738 **/
 739 typedef
 740 EFI_STATUS
 741 (* PFN_API_PORT_CLOSE) (
 742   IN ESL_PORT * pPort
 743   );
 744
 745 /**
 746   Perform the network specific close operation on the port.
 747
 748   This routine performs the network specific operation to
 749   shutdown receive operations on the port.
 750
 751   This routine is called by the ::EslSocketPortCloseTxDone
 752   routine after the port completes all of the transmission.
 753
 754   @param [in] pPort           Address of an ::ESL_PORT structure.
 755
 756   @retval EFI_SUCCESS         The port is closed, not normally returned
 757   @retval EFI_NOT_READY       The port is still closing
 758   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
 759                               most likely the routine was called already.
 760
 761 **/
 762 typedef
 763 EFI_STATUS
 764 (* PFN_API_PORT_CLOSE_OP) (
 765   IN ESL_PORT * pPort
 766   );
 767
 768 /**
 769   Receive data from a network connection.
 770
 771   This routine attempts to return buffered data to the caller.  The
 772   data is removed from the urgent queue if the message flag MSG_OOB
 773   is specified, otherwise data is removed from the normal queue.
 774   See the \ref ReceiveEngine section.
 775
 776   This routine is called by ::EslSocketReceive to handle the network
 777   specific receive operation.
 778
 779   @param [in] pPort           Address of an ::ESL_PORT structure.
 780
 781   @param [in] pPacket         Address of an ::ESL_PACKET structure.
 782
 783   @param [in] pbConsumePacket Address of a BOOLEAN indicating if the packet is to be consumed
 784
 785   @param [in] BufferLength    Length of the the buffer
 786
 787   @param [in] pBuffer         Address of a buffer to receive the data.
 788
 789   @param [in] pDataLength     Number of received data bytes in the buffer.
 790
 791   @param [out] pAddress       Network address to receive the remote system address
 792
 793   @param [out] pSkipBytes     Address to receive the number of bytes skipped
 794
 795   @return   Returns the address of the next free byte in the buffer.
 796
 797  **/
 798 typedef
 799 UINT8 *
 800 (* PFN_API_RECEIVE) (
 801   IN ESL_PORT * pPort,
 802   IN ESL_PACKET * pPacket,
 803   IN BOOLEAN * pbConsumePacket,
 804   IN size_t BufferLength,
 805   IN UINT8 * pBuffer,
 806   OUT size_t * pDataLength,
 807   OUT struct sockaddr * pAddress,
 808   OUT size_t * pSkipBytes
 809   );
 810
 811 /**
 812   Get the remote socket address
 813
 814   @param [in] pPort       Address of an ::ESL_PORT structure.
 815
 816   @param [out] pAddress   Network address to receive the remote system address
 817
 818 **/
 819 typedef
 820 VOID
 821 (* PFN_API_REMOTE_ADDR_GET) (
 822   IN ESL_PORT * pPort,
 823   OUT struct sockaddr * pAddress
 824   );
 825
 826 /**
 827   Set the remote address
 828
 829   This routine sets the remote address in the port.
 830
 831   This routine is called by ::EslSocketConnect to specify the
 832   remote network address.
 833
 834   @param [in] pPort           Address of an ::ESL_PORT structure.
 835
 836   @param [in] pSockAddr       Network address of the remote system.
 837
 838   @param [in] SockAddrLength  Length in bytes of the network address.
 839
 840   @retval EFI_SUCCESS     The operation was successful
 841
 842  **/
 843 typedef
 844 EFI_STATUS
 845 (* PFN_API_REMOTE_ADDR_SET) (
 846   IN ESL_PORT * pPort,
 847   IN CONST struct sockaddr * pSockAddr,
 848   IN socklen_t SockAddrLength
 849   );
 850
 851 /**
 852   Start a receive operation
 853
 854   This routine prepares a packet for the receive operation.
 855   See the \ref ReceiveEngine section.
 856
 857   This support routine is called by EslSocketRxStart.
 858
 859   @param [in] pPort       Address of an ::ESL_PORT structure.
 860   @param [in] pIo         Address of an ::ESL_IO_MGMT structure.
 861
 862  **/
 863 typedef
 864 VOID
 865 (* PFN_API_RX_START) (
 866   IN ESL_PORT * pPort,
 867   IN ESL_IO_MGMT * pIo
 868   );
 869
 870 /**
 871   Buffer data for transmission over a network connection.
 872
 873   @param [in] pSocket         Address of a ESL_SOCKET structure
 874
 875   @param [in] Flags           Message control flags
 876
 877   @param [in] BufferLength    Length of the the buffer
 878
 879   @param [in] pBuffer         Address of a buffer to receive the data.
 880
 881   @param [in] pDataLength     Number of received data bytes in the buffer.
 882
 883   @param [in] pAddress        Network address of the remote system address
 884
 885   @param [in] AddressLength   Length of the remote network address structure
 886
 887   @retval EFI_SUCCESS - Socket data successfully buffered
 888
 889 **/
 890 typedef
 891 EFI_STATUS
 892 (* PFN_API_TRANSMIT) (
 893   IN ESL_SOCKET * pSocket,
 894   IN int Flags,
 895   IN size_t BufferLength,
 896   IN CONST UINT8 * pBuffer,
 897   OUT size_t * pDataLength,
 898   IN const struct sockaddr * pAddress,
 899   IN socklen_t AddressLength
 900   );
 901
 902 /**
 903   Process the transmit completion
 904
 905   This routine calls ::EslSocketTxComplete to handle the
 906   transmit completion.
 907
 908   This routine is called by the network layers upon the completion
 909   of a transmit operation.
 910
 911   @param [in] Event     The urgent transmit completion event
 912
 913   @param [in] pIo       The ESL_IO_MGMT structure address
 914
 915 **/
 916 typedef
 917 VOID
 918 (* PFN_API_TX_COMPLETE) (
 919   IN EFI_EVENT Event,
 920   IN ESL_IO_MGMT * pIo
 921   );
 922
 923 /**
 924   Socket type control structure
 925
 926   This driver uses this structure to define the API for the socket type.
 927 **/
 928 typedef struct {
 929   CONST CHAR8 * pName;                      ///<  Protocol name
 930   int DefaultProtocol;                      ///<  Default protocol
 931   UINTN ConfigDataOffset;                   ///<  Offset in ::ESL_PORT to the configuration data
 932   UINTN ServiceListOffset;                  ///<  Offset in ::ESL_LAYER for the list of services
 933   socklen_t MinimumAddressLength;           ///<  Minimum address length in bytes
 934   socklen_t AddressLength;                  ///<  Address length in bytes
 935   sa_family_t AddressFamily;                ///<  Address family
 936   UINTN RxPacketBytes;                      ///<  Length of the RX packet allocation
 937   UINTN RxZeroBytes;                        ///<  Number of bytes to zero in RX packet
 938   UINTN RxBufferOffset;                     ///<  Offset of buffer address in ESL_IO_MGMT structure
 939   BOOLEAN bOobSupported;                    ///<  TRUE if out-of-band messages are supported
 940   int BindTestErrno;                        ///<  errno value if EslSocketBindTest fails
 941   PFN_API_ACCEPT pfnAccept;                 ///<  Accept a network connection
 942   PFN_API_CONNECT_POLL pfnConnectPoll;      ///<  Poll for connection complete
 943   PFN_API_CONNECT_START pfnConnectStart;    ///<  Start the connection to a remote system
 944   PFN_API_IS_CONFIGURED pfnIsConfigured;    ///<  Determine if the socket is configured
 945   PFN_API_LOCAL_ADDR_GET pfnLocalAddrGet;   ///<  Get the local address
 946   PFN_API_LOCAL_ADDR_SET pfnLocalAddrSet;   ///<  Set the local address
 947   PFN_API_LISTEN pfnListen;                 ///<  Listen for connections on known server port
 948   PFN_API_OPTION_GET pfnOptionGet;          ///<  Get the option value
 949   PFN_API_OPTION_SET pfnOptionSet;          ///<  Set the option value
 950   PFN_API_PACKET_FREE pfnPacketFree;        ///<  Free the receive packet
 951   PFN_API_PORT_ALLOC pfnPortAllocate;       ///<  Allocate the network specific resources for the port
 952   PFN_API_PORT_CLOSE pfnPortClose;          ///<  Close the network specific resources for the port
 953   PFN_API_PORT_CLOSE_OP pfnPortCloseOp;     ///<  Perform the close operation on the port
 954   BOOLEAN bPortCloseComplete;               ///<  TRUE = Close is complete after close operation
 955   PFN_API_RECEIVE pfnReceive;               ///<  Attempt to receive some data
 956   PFN_API_REMOTE_ADDR_GET pfnRemoteAddrGet; ///<  Get remote address
 957   PFN_API_REMOTE_ADDR_SET pfnRemoteAddrSet; ///<  Set the remote system address
 958   PFN_API_IO_COMPLETE pfnRxComplete;        ///<  RX completion
 959   PFN_API_RX_START pfnRxStart;              ///<  Start a network specific receive operation
 960   PFN_API_TRANSMIT pfnTransmit;             ///<  Attempt to buffer a packet for transmit
 961   PFN_API_TX_COMPLETE pfnTxComplete;        ///<  TX completion for normal data
 962   PFN_API_TX_COMPLETE pfnTxOobComplete;     ///<  TX completion for urgent data
 963 } ESL_PROTOCOL_API;
 964
 965
 966 /**
 967   Socket control structure
 968
 969   The driver uses this structure to manage the socket.
 970 **/
 971 typedef struct _ESL_SOCKET {
 972   UINTN Signature;          ///<  Structure identification
 973
 974   //
 975   //  Protocol binding
 976   //
 977   EFI_SOCKET_PROTOCOL SocketProtocol; ///<  Socket protocol declaration
 978   CONST ESL_PROTOCOL_API * pApi;      ///<  API for the protocol
 979
 980   //
 981   //  Socket management
 982   //
 983   ESL_SOCKET * pNext;           ///<  Next socket in the list of sockets
 984   int errno;                    ///<  Error information for this socket
 985   EFI_STATUS Status;            ///<  Asyncronous error information for this socket
 986   SOCKET_STATE State;           ///<  Socket state
 987   UINT32 DebugFlags;            ///<  Debug flags
 988
 989   //
 990   //  Socket options
 991   //
 992   BOOLEAN bIncludeHeader;       ///<  TRUE if including the IP header
 993   BOOLEAN bListenCalled;        ///<  TRUE if listen was successfully called
 994   BOOLEAN bOobInLine;           ///<  TRUE if out-of-band messages are to be received inline with normal data
 995   BOOLEAN bReUseAddr;           ///<  TRUE if using same address is allowed
 996
 997   //
 998   //  Socket data
 999   //
1000   int Domain;                   ///<  Specifies family of protocols
1001   int Type;                     ///<  Specifies how to make network connection
1002   int Protocol;                 ///<  Specifies lower layer protocol to use
1003   BOOLEAN bAddressSet;          ///<  Set when the address is specified
1004   BOOLEAN bConfigured;          ///<  Set after the socket is configured
1005
1006   BOOLEAN bRxDisable;           ///<  Receive disabled via shutdown
1007   size_t RxBytes;               ///<  Total Rx bytes
1008   size_t RxOobBytes;            ///<  Urgent Rx bytes
1009   EFI_STATUS RxError;           ///<  Error during receive
1010
1011   BOOLEAN bTxDisable;           ///<  Transmit disabled via shutdown
1012   size_t TxBytes;               ///<  Normal Tx bytes
1013   size_t TxOobBytes;            ///<  Urgent Tx bytes
1014   EFI_STATUS TxError;           ///<  Error during transmit
1015
1016   //
1017   //  Pending connection data
1018   //
1019   BOOLEAN bConnected;           ///<  Set when connected, cleared by poll
1020   EFI_STATUS ConnectStatus;     ///<  Connection status
1021   UINTN MaxFifoDepth;           ///<  Maximum FIFO depth
1022   UINTN FifoDepth;              ///<  Number of sockets in the FIFO
1023   ESL_SOCKET * pFifoHead;       ///<  Head of the FIFO
1024   ESL_SOCKET * pFifoTail;       ///<  Tail of the FIFO
1025   ESL_SOCKET * pNextConnection; ///<  Link in the FIFO
1026
1027   //
1028   //  Network use
1029   //
1030   ESL_PORT * pPortList;         ///<  List of ports managed by this socket
1031   EFI_EVENT WaitAccept;         ///<  Wait for accept completion
1032
1033   //
1034   //  Receive data management
1035   //
1036   UINT32 MaxRxBuf;                  ///<  Maximum size of the receive buffer
1037   struct timeval RxTimeout;         ///<  Receive timeout
1038   ESL_PACKET * pRxFree;             ///<  Free packet list
1039   ESL_PACKET * pRxOobPacketListHead;///<  Urgent data list head
1040   ESL_PACKET * pRxOobPacketListTail;///<  Urgent data list tail
1041   ESL_PACKET * pRxPacketListHead;   ///<  Normal data list head
1042   ESL_PACKET * pRxPacketListTail;   ///<  Normal data list tail
1043
1044   //
1045   //  Transmit data management
1046   //
1047   UINTN TxPacketOffset;             ///<  Offset for data pointer in ::ESL_PACKET
1048   UINTN TxTokenEventOffset;         ///<  Offset to the Event in the TX token
1049   UINTN TxTokenOffset;              ///<  Offset for data pointer in TX token
1050   UINT32 MaxTxBuf;                  ///<  Maximum size of the transmit buffer
1051   ESL_PACKET * pTxOobPacketListHead;///<  Urgent data list head
1052   ESL_PACKET * pTxOobPacketListTail;///<  Urgent data list tail
1053   ESL_PACKET * pTxPacketListHead;   ///<  Normal data list head
1054   ESL_PACKET * pTxPacketListTail;   ///<  Normal data list tail
1055 }GCC_ESL_SOCKET;
1056
1057 #define SOCKET_FROM_PROTOCOL(a)  CR (a, ESL_SOCKET, SocketProtocol, SOCKET_SIGNATURE)  ///< Locate ESL_SOCKET from protocol
1058
1059 /**
1060   Socket layer control structure
1061
1062   The driver uses this structure to manage the driver.
1063 **/
1064 typedef struct {
1065   UINTN Signature;              ///<  Structure identification
1066
1067   //
1068   //  Service binding interface
1069   //
1070   CONST EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Driver's binding
1071
1072   //
1073   //  Image data
1074   //
1075   EFI_HANDLE ImageHandle;       ///<  Image handle
1076
1077   //
1078   //  Network services
1079   //
1080   ESL_SERVICE * pIp4List;       ///<  List of Ip4 services
1081   ESL_SERVICE * pTcp4List;      ///<  List of Tcp4 services
1082   ESL_SERVICE * pTcp6List;      ///<  List of Tcp6 services
1083   ESL_SERVICE * pUdp4List;      ///<  List of Udp4 services
1084   ESL_SERVICE * pUdp6List;      ///<  List of Udp6 services
1085
1086   //
1087   //  Socket management
1088   //
1089   ESL_SOCKET * pSocketList;     ///<  List of sockets
1090 } ESL_LAYER;
1091
1092 #define LAYER_FROM_SERVICE(a) CR (a, ESL_LAYER, ServiceBinding, LAYER_SIGNATURE) ///< Locate ESL_LAYER from service binding
1093
1094 //------------------------------------------------------------------------------
1095 // Data
1096 //------------------------------------------------------------------------------
1097
1098 extern ESL_LAYER mEslLayer;
1099
1100 extern CONST ESL_PROTOCOL_API cEslIp4Api;
1101 extern CONST ESL_PROTOCOL_API cEslIp6Api;
1102 extern CONST ESL_PROTOCOL_API cEslTcp4Api;
1103 extern CONST ESL_PROTOCOL_API cEslTcp6Api;
1104 extern CONST ESL_PROTOCOL_API cEslUdp4Api;
1105 extern CONST ESL_PROTOCOL_API cEslUdp6Api;
1106
1107 extern CONST EFI_SERVICE_BINDING_PROTOCOL mEfiServiceBinding;
1108
1109 //------------------------------------------------------------------------------
1110 // Socket Support Routines
1111 //------------------------------------------------------------------------------
1112
1113 /**
1114   Allocate and initialize a ESL_SOCKET structure.
1115
1116   This support function allocates an ::ESL_SOCKET structure
1117   and installs a protocol on ChildHandle.  If pChildHandle is a
1118   pointer to NULL, then a new handle is created and returned in
1119   pChildHandle.  If pChildHandle is not a pointer to NULL, then
1120   the protocol installs on the existing pChildHandle.
1121
1122   @param [in, out] pChildHandle Pointer to the handle of the child to create.
1123                                 If it is NULL, then a new handle is created.
1124                                 If it is a pointer to an existing UEFI handle,
1125                                 then the protocol is added to the existing UEFI
1126                                 handle.
1127   @param [in] DebugFlags        Flags for debug messages
1128   @param [in, out] ppSocket     The buffer to receive an ::ESL_SOCKET structure address.
1129
1130   @retval EFI_SUCCESS           The protocol was added to ChildHandle.
1131   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
1132   @retval EFI_OUT_OF_RESOURCES  There are not enough resources available to create
1133                                 the child
1134   @retval other                 The child handle was not created
1135
1136 **/
1137 EFI_STATUS
1138 EFIAPI
1139 EslSocketAllocate (
1140   IN OUT EFI_HANDLE * pChildHandle,
1141   IN     UINTN DebugFlags,
1142   IN OUT ESL_SOCKET ** ppSocket
1143   );
1144
1145 /**
1146   Test the bind configuration.
1147
1148   @param [in] pPort       Address of the ::ESL_PORT structure.
1149   @param [in] ErrnoValue  errno value if test fails
1150
1151   @retval EFI_SUCCESS   The connection was successfully established.
1152   @retval Others        The connection attempt failed.
1153
1154  **/
1155 EFI_STATUS
1156 EslSocketBindTest (
1157   IN ESL_PORT * pPort,
1158   IN int ErrnoValue
1159   );
1160
1161 /**
1162   Copy a fragmented buffer into a destination buffer.
1163
1164   This support routine copies a fragmented buffer to the caller specified buffer.
1165
1166   This routine is called by ::EslIp4Receive and ::EslUdp4Receive.
1167
1168   @param [in] FragmentCount   Number of fragments in the table
1169
1170   @param [in] pFragmentTable  Address of an EFI_IP4_FRAGMENT_DATA structure
1171
1172   @param [in] BufferLength    Length of the the buffer
1173
1174   @param [in] pBuffer         Address of a buffer to receive the data.
1175
1176   @param [in] pDataLength     Number of received data bytes in the buffer.
1177
1178   @return   Returns the address of the next free byte in the buffer.
1179
1180 **/
1181 UINT8 *
1182 EslSocketCopyFragmentedBuffer (
1183   IN UINT32 FragmentCount,
1184   IN EFI_IP4_FRAGMENT_DATA * pFragmentTable,
1185   IN size_t BufferLength,
1186   IN UINT8 * pBuffer,
1187   OUT size_t * pDataLength
1188   );
1189
1190 /**
1191   Free the socket.
1192
1193   This routine frees the socket structure and handle resources.
1194
1195   The ::close routine calls EslServiceFreeProtocol which then calls
1196   this routine to free the socket context structure and close the
1197   handle.
1198
1199   @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
1200
1201   @param [out] pErrno         Address to receive the errno value upon completion.
1202
1203   @retval EFI_SUCCESS   The socket resources were returned successfully.
1204
1205  **/
1206 EFI_STATUS
1207 EslSocketFree (
1208   IN EFI_SOCKET_PROTOCOL * pSocketProtocol,
1209   IN int * pErrno
1210   );
1211
1212 /**
1213   Free the ESL_IO_MGMT event and structure
1214
1215   This support routine walks the free list to close the event in
1216   the ESL_IO_MGMT structure and remove the structure from the free
1217   list.
1218
1219   See the \ref TransmitEngine section.
1220
1221   @param [in] pPort         Address of an ::ESL_PORT structure
1222   @param [in] ppFreeQueue   Address of the free queue head
1223   @param [in] DebugFlags    Flags for debug messages
1224   @param [in] pEventName    Zero terminated string containing the event name
1225
1226   @retval EFI_SUCCESS - The structures were properly initialized
1227
1228 **/
1229 EFI_STATUS
1230 EslSocketIoFree (
1231   IN ESL_PORT * pPort,
1232   IN ESL_IO_MGMT ** ppFreeQueue,
1233   IN UINTN DebugFlags,
1234   IN CHAR8 * pEventName
1235   );
1236
1237 /**
1238   Initialize the ESL_IO_MGMT structures
1239
1240   This support routine initializes the ESL_IO_MGMT structure and
1241   places them on to a free list.
1242
1243   This routine is called by the PortAllocate routines to prepare
1244   the transmit engines.  See the \ref TransmitEngine section.
1245
1246   @param [in] pPort         Address of an ::ESL_PORT structure
1247   @param [in, out] ppIo     Address containing the first structure address.  Upon
1248                             return this buffer contains the next structure address.
1249   @param [in] TokenCount    Number of structures to initialize
1250   @param [in] ppFreeQueue   Address of the free queue head
1251   @param [in] DebugFlags    Flags for debug messages
1252   @param [in] pEventName    Zero terminated string containing the event name
1253   @param [in] pfnCompletion Completion routine address
1254
1255   @retval EFI_SUCCESS - The structures were properly initialized
1256
1257 **/
1258 EFI_STATUS
1259 EslSocketIoInit (
1260   IN ESL_PORT * pPort,
1261   IN ESL_IO_MGMT ** ppIo,
1262   IN UINTN TokenCount,
1263   IN ESL_IO_MGMT ** ppFreeQueue,
1264   IN UINTN DebugFlags,
1265   IN CHAR8 * pEventName,
1266   IN PFN_API_IO_COMPLETE pfnCompletion
1267   );
1268
1269 /**
1270   Determine if the socket is configured
1271
1272   This support routine is called to determine if the socket if the
1273   configuration call was made to the network layer.  The following
1274   routines call this routine to verify that they may be successful
1275   in their operations:
1276   <ul>
1277     <li>::EslSocketGetLocalAddress</li>
1278     <li>::EslSocketGetPeerAddress</li>
1279     <li>::EslSocketPoll</li>
1280     <li>::EslSocketReceive</li>
1281     <li>::EslSocketTransmit</li>
1282   </ul>
1283
1284   @param [in] pSocket       Address of an ::ESL_SOCKET structure
1285
1286   @retval EFI_SUCCESS - The socket is configured
1287
1288 **/
1289 EFI_STATUS
1290 EslSocketIsConfigured (
1291   IN ESL_SOCKET * pSocket
1292   );
1293
1294 /**
1295   Allocate a packet for a receive or transmit operation
1296
1297   This support routine is called by ::EslSocketRxStart and the
1298   network specific TxBuffer routines to get buffer space for the
1299   next operation.
1300
1301   @param [in] ppPacket      Address to receive the ::ESL_PACKET structure
1302   @param [in] LengthInBytes Length of the packet structure
1303   @param [in] ZeroBytes     Length of packet to zero
1304   @param [in] DebugFlags    Flags for debug messages
1305
1306   @retval EFI_SUCCESS - The packet was allocated successfully
1307
1308  **/
1309 EFI_STATUS
1310 EslSocketPacketAllocate (
1311   IN ESL_PACKET ** ppPacket,
1312   IN size_t LengthInBytes,
1313   IN size_t ZeroBytes,
1314   IN UINTN DebugFlags
1315   );
1316
1317 /**
1318   Free a packet used for receive or transmit operation
1319
1320   This support routine is called by the network specific Close
1321   and TxComplete routines and during error cases in RxComplete
1322   and TxBuffer.  Note that the network layers typically place
1323   receive packets on the ESL_SOCKET::pRxFree list for reuse.
1324
1325   @param [in] pPacket     Address of an ::ESL_PACKET structure
1326   @param [in] DebugFlags  Flags for debug messages
1327
1328   @retval EFI_SUCCESS - The packet was allocated successfully
1329
1330  **/
1331 EFI_STATUS
1332 EslSocketPacketFree (
1333   IN ESL_PACKET * pPacket,
1334   IN UINTN DebugFlags
1335   );
1336
1337 /**
1338   Allocate and initialize a ESL_PORT structure.
1339
1340   This routine initializes an ::ESL_PORT structure for use by
1341   the socket.  This routine calls a routine via
1342   ESL_PROTOCOL_API::pfnPortAllocate to initialize the network
1343   specific resources.  The resources are released later by the
1344   \ref PortCloseStateMachine.
1345
1346   This support routine is called by ::EslSocketBind and
1347   ::EslTcp4ListenComplete to connect the socket with the
1348   underlying network adapter to the socket.
1349
1350   @param [in] pSocket     Address of an ::ESL_SOCKET structure.
1351   @param [in] pService    Address of an ::ESL_SERVICE structure.
1352   @param [in] ChildHandle TCP4 child handle
1353   @param [in] pSockAddr   Address of a sockaddr structure that contains the
1354                           connection point on the local machine.  An IPv4 address
1355                           of INADDR_ANY specifies that the connection is made to
1356                           all of the network stacks on the platform.  Specifying a
1357                           specific IPv4 address restricts the connection to the
1358                           network stack supporting that address.  Specifying zero
1359                           for the port causes the network layer to assign a port
1360                           number from the dynamic range.  Specifying a specific
1361                           port number causes the network layer to use that port.
1362   @param [in] bBindTest   TRUE if EslSocketBindTest should be called
1363   @param [in] DebugFlags  Flags for debug messages
1364   @param [out] ppPort     Buffer to receive new ::ESL_PORT structure address
1365
1366   @retval EFI_SUCCESS - Socket successfully created
1367
1368  **/
1369 EFI_STATUS
1370 EslSocketPortAllocate (
1371   IN ESL_SOCKET * pSocket,
1372   IN ESL_SERVICE * pService,
1373   IN EFI_HANDLE ChildHandle,
1374   IN CONST struct sockaddr * pSockAddr,
1375   IN BOOLEAN bBindTest,
1376   IN UINTN DebugFlags,
1377   OUT ESL_PORT ** ppPort
1378   );
1379
1380 /**
1381   Close a port.
1382
1383   This routine releases the resources allocated by ::EslSocketPortAllocate.
1384   This routine calls ESL_PROTOCOL_API::pfnPortClose to release the network
1385   specific resources.
1386
1387   This routine is called by:
1388   <ul>
1389     <li>::EslIp4PortAllocate - Port initialization failure</li>
1390     <li>::EslSocketPortCloseRxDone - Last step of close processing</li>
1391     <li>::EslTcp4ConnectComplete - Connection failure and reducint the port list to a single port</li>
1392     <li>::EslTcp4PortAllocate - Port initialization failure</li>
1393     <li>::EslUdp4PortAllocate - Port initialization failure</li>
1394   </ul>
1395   See the \ref PortCloseStateMachine section.
1396
1397   @param [in] pPort       Address of an ::ESL_PORT structure.
1398
1399   @retval EFI_SUCCESS     The port is closed
1400   @retval other           Port close error
1401
1402 **/
1403 EFI_STATUS
1404 EslSocketPortClose (
1405   IN ESL_PORT * pPort
1406   );
1407
1408 /**
1409   Process the port close completion event
1410
1411   This routine attempts to complete the port close operation.
1412
1413   This routine is called by the TCP layer upon completion of
1414   the close operation.
1415   See the \ref PortCloseStateMachine section.
1416
1417   @param [in] Event     The close completion event
1418
1419   @param [in] pPort     Address of an ::ESL_PORT structure.
1420
1421 **/
1422 VOID
1423 EslSocketPortCloseComplete (
1424   IN EFI_EVENT Event,
1425   IN ESL_PORT * pPort
1426   );
1427
1428 /**
1429   Port close state 3
1430
1431   This routine determines the state of the receive operations and
1432   continues the close operation after the pending receive operations
1433   are cancelled.
1434
1435   This routine is called by
1436   <ul>
1437     <li>::EslIp4RxComplete</li>
1438     <li>::EslSocketPortCloseComplete</li>
1439     <li>::EslSocketPortCloseTxDone</li>
1440     <li>::EslUdp4RxComplete</li>
1441   </ul>
1442   to determine the state of the receive operations.
1443   See the \ref PortCloseStateMachine section.
1444
1445   @param [in] pPort       Address of an ::ESL_PORT structure.
1446
1447   @retval EFI_SUCCESS         The port is closed
1448   @retval EFI_NOT_READY       The port is still closing
1449   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
1450                               most likely the routine was called already.
1451
1452 **/
1453 EFI_STATUS
1454 EslSocketPortCloseRxDone (
1455   IN ESL_PORT * pPort
1456   );
1457
1458 /**
1459   Start the close operation on a port, state 1.
1460
1461   This routine marks the port as closed and initiates the \ref
1462   PortCloseStateMachine. The first step is to allow the \ref
1463   TransmitEngine to run down.
1464
1465   This routine is called by ::EslSocketCloseStart to initiate the socket
1466   network specific close operation on the socket.
1467
1468   @param [in] pPort       Address of an ::ESL_PORT structure.
1469   @param [in] bCloseNow   Set TRUE to abort active transfers
1470   @param [in] DebugFlags  Flags for debug messages
1471
1472   @retval EFI_SUCCESS         The port is closed, not normally returned
1473   @retval EFI_NOT_READY       The port has started the closing process
1474   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
1475                               most likely the routine was called already.
1476
1477 **/
1478 EFI_STATUS
1479 EslSocketPortCloseStart (
1480   IN ESL_PORT * pPort,
1481   IN BOOLEAN bCloseNow,
1482   IN UINTN DebugFlags
1483   );
1484
1485 /**
1486   Port close state 2
1487
1488   This routine determines the state of the transmit engine and
1489   continue the close operation after the transmission is complete.
1490   The next step is to stop the \ref ReceiveEngine.
1491   See the \ref PortCloseStateMachine section.
1492
1493   This routine is called by ::EslSocketPortCloseStart to determine
1494   if the transmission is complete.
1495
1496   @param [in] pPort           Address of an ::ESL_PORT structure.
1497
1498   @retval EFI_SUCCESS         The port is closed, not normally returned
1499   @retval EFI_NOT_READY       The port is still closing
1500   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
1501                               most likely the routine was called already.
1502
1503 **/
1504 EFI_STATUS
1505 EslSocketPortCloseTxDone (
1506   IN ESL_PORT * pPort
1507   );
1508
1509 /**
1510   Cancel the receive operations
1511
1512   This routine cancels a pending receive operation.
1513   See the \ref ReceiveEngine section.
1514
1515   This routine is called by ::EslSocketShutdown when the socket
1516   layer is being shutdown.
1517
1518   @param [in] pPort     Address of an ::ESL_PORT structure
1519   @param [in] pIo       Address of an ::ESL_IO_MGMT structure
1520
1521  **/
1522 VOID
1523 EslSocketRxCancel (
1524   IN ESL_PORT * pPort,
1525   IN ESL_IO_MGMT * pIo
1526   );
1527
1528 /**
1529   Process the receive completion
1530
1531   This routine queues the data in FIFO order in either the urgent
1532   or normal data queues depending upon the type of data received.
1533   See the \ref ReceiveEngine section.
1534
1535   This routine is called when some data is received by:
1536   <ul>
1537     <li>::EslIp4RxComplete</li>
1538     <li>::EslTcp4RxComplete</li>
1539     <li>::EslUdp4RxComplete</li>
1540   </ul>
1541
1542   @param [in] pIo           Address of an ::ESL_IO_MGMT structure
1543   @param [in] Status        Receive status
1544   @param [in] LengthInBytes Length of the receive data
1545   @param [in] bUrgent       TRUE if urgent data is received and FALSE
1546                             for normal data.
1547
1548 **/
1549 VOID
1550 EslSocketRxComplete (
1551   IN ESL_IO_MGMT * pIo,
1552   IN EFI_STATUS Status,
1553   IN UINTN LengthInBytes,
1554   IN BOOLEAN bUrgent
1555   );
1556
1557 /**
1558   Poll a socket for pending receive activity.
1559
1560   This routine is called at elivated TPL and extends the idle
1561   loop which polls a socket down into the LAN driver layer to
1562   determine if there is any receive activity.
1563
1564   The ::EslSocketPoll, ::EslSocketReceive and ::EslSocketTransmit
1565   routines call this routine when there is nothing to do.
1566
1567   @param [in] pSocket   Address of an ::EFI_SOCKET structure.
1568
1569  **/
1570 VOID
1571 EslSocketRxPoll (
1572   IN ESL_SOCKET * pSocket
1573   );
1574
1575 /**
1576   Start a receive operation
1577
1578   This routine posts a receive buffer to the network adapter.
1579   See the \ref ReceiveEngine section.
1580
1581   This support routine is called by:
1582   <ul>
1583     <li>::EslIp4Receive to restart the receive engine to release flow control.</li>
1584     <li>::EslIp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>
1585     <li>::EslIp4SocketIsConfigured to start the recevie engine for the new socket.</li>
1586     <li>::EslTcp4ListenComplete to start the recevie engine for the new socket.</li>
1587     <li>::EslTcp4Receive to restart the receive engine to release flow control.</li>
1588     <li>::EslTcp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>
1589     <li>::EslUdp4Receive to restart the receive engine to release flow control.</li>
1590     <li>::EslUdp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>
1591     <li>::EslUdp4SocketIsConfigured to start the recevie engine for the new socket.</li>
1592   </ul>
1593
1594   @param [in] pPort       Address of an ::ESL_PORT structure.
1595
1596  **/
1597 VOID
1598 EslSocketRxStart (
1599   IN ESL_PORT * pPort
1600   );
1601
1602 /**
1603   Complete the transmit operation
1604
1605   This support routine handles the transmit completion processing for
1606   the various network layers.  It frees the ::ESL_IO_MGMT structure
1607   and and frees packet resources by calling ::EslSocketPacketFree.
1608   Transmit errors are logged in ESL_SOCKET::TxError.
1609   See the \ref TransmitEngine section.
1610
1611   This routine is called by:
1612   <ul>
1613     <li>::EslIp4TxComplete</li>
1614     <li>::EslTcp4TxComplete</li>
1615     <li>::EslTcp4TxOobComplete</li>
1616     <li>::EslUdp4TxComplete</li>
1617   </ul>
1618
1619   @param [in] pIo             Address of an ::ESL_IO_MGMT structure
1620   @param [in] LengthInBytes   Length of the data in bytes
1621   @param [in] Status          Transmit operation status
1622   @param [in] pQueueType      Zero terminated string describing queue type
1623   @param [in] ppQueueHead     Transmit queue head address
1624   @param [in] ppQueueTail     Transmit queue tail address
1625   @param [in] ppActive        Active transmit queue address
1626   @param [in] ppFree          Free transmit queue address
1627
1628  **/
1629 VOID
1630 EslSocketTxComplete (
1631   IN ESL_IO_MGMT * pIo,
1632   IN UINT32 LengthInBytes,
1633   IN EFI_STATUS Status,
1634   IN CONST CHAR8 * pQueueType,
1635   IN ESL_PACKET ** ppQueueHead,
1636   IN ESL_PACKET ** ppQueueTail,
1637   IN ESL_IO_MGMT ** ppActive,
1638   IN ESL_IO_MGMT ** ppFree
1639   );
1640
1641 /**
1642   Transmit data using a network connection.
1643
1644   This support routine starts a transmit operation on the
1645   underlying network layer.
1646
1647   The network specific code calls this routine to start a
1648   transmit operation.  See the \ref TransmitEngine section.
1649
1650   @param [in] pPort           Address of an ::ESL_PORT structure
1651   @param [in] ppQueueHead     Transmit queue head address
1652   @param [in] ppQueueTail     Transmit queue tail address
1653   @param [in] ppActive        Active transmit queue address
1654   @param [in] ppFree          Free transmit queue address
1655
1656  **/
1657 VOID
1658 EslSocketTxStart (
1659   IN ESL_PORT * pPort,
1660   IN ESL_PACKET ** ppQueueHead,
1661   IN ESL_PACKET ** ppQueueTail,
1662   IN ESL_IO_MGMT ** ppActive,
1663   IN ESL_IO_MGMT ** ppFree
1664   );
1665
1666 //------------------------------------------------------------------------------
1667
1668 #endif  //  _SOCKET_H_