StdLib/EfiSocketLib/Socket.h

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