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