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
  34 #define MAX_PENDING_CONNECTIONS     1   ///<  Maximum connection FIFO depth
  35 #define MAX_RX_DATA         65536       ///<  Maximum receive data size
  36 #define MAX_TX_DATA         ( MAX_RX_DATA * 2 )
  37 #define RX_PACKET_DATA      16384       ///<  Maximum number of bytes in a RX packet
  38
  39 #define LAYER_SIGNATURE             SIGNATURE_32('S','k','t','L') ///<  DT_LAYER memory signature
  40 #define SERVICE_SIGNATURE           SIGNATURE_32('S','k','t','S') ///<  DT_SERVICE memory signature
  41 #define SOCKET_SIGNATURE            SIGNATURE_32('S','c','k','t') ///<  DT_SOCKET memory signature
  42 #define PORT_SIGNATURE              SIGNATURE_32('P','o','r','t') ///<  DT_PORT memory signature
  43
  44 typedef enum
  45 {
  46   NETWORK_TYPE_UNKNOWN = 0,
  47   NETWORK_TYPE_RAW,
  48   NETWORK_TYPE_TCP4,
  49   NETWORK_TYPE_TCP6,
  50   NETWORK_TYPE_UDP4,
  51   NETWORK_TYPE_UDP6
  52 } NETWORK_TYPE;
  53
  54 typedef enum
  55 {
  56   SOCKET_STATE_NOT_CONFIGURED = 0,  ///<  socket call was successful
  57   SOCKET_STATE_BOUND,               ///<  bind call was successful
  58   SOCKET_STATE_LISTENING,           ///<  listen call was successful
  59   SOCKET_STATE_NO_PORTS,            ///<  No ports available
  60   SOCKET_STATE_IN_FIFO,             ///<  Socket on FIFO
  61   SOCKET_STATE_CONNECTING,          ///<  Connecting to a remote system
  62   SOCKET_STATE_CONNECTED,           ///<  Accept or connect call was successful
  63
  64   //
  65   //  Close state must be the last in the list
  66   //
  67   SOCKET_STATE_CLOSED               ///<  Close call was successful
  68 } SOCKET_STATE;
  69
  70 typedef enum
  71 {
  72   PORT_STATE_ALLOCATED = 0, ///<  Port allocated
  73   PORT_STATE_OPEN,          ///<  Port opened
  74   PORT_STATE_RX_ERROR,      ///<  Receive error detected
  75
  76   //
  77   //  Close state must be last in the list
  78   //
  79   PORT_STATE_CLOSE_STARTED, ///<  Close started on port
  80   PORT_STATE_CLOSE_TX_DONE, ///<  Transmits shutdown
  81   PORT_STATE_CLOSE_RX_DONE, ///<  Receives shutdown
  82   PORT_STATE_CLOSE_DONE     ///<  Port close operation complete
  83 } PORT_STATE;
  84
  85 //------------------------------------------------------------------------------
  86 //  Data Types
  87 //------------------------------------------------------------------------------
  88
  89 typedef struct _DT_PACKET DT_PACKET;    ///<  Forward declaration
  90 typedef struct _DT_PORT DT_PORT;        ///<  Forward declaration
  91 typedef struct _DT_SOCKET DT_SOCKET;    ///<  Forward declaration
  92
  93 typedef struct
  94 {
  95   EFI_TCP4_RECEIVE_DATA RxData;         ///<  Receive operation description
  96   size_t ValidBytes;                    ///<  Length of valid data in bytes
  97   UINT8 * pBuffer;                      ///<  Current data pointer
  98   UINT8 Buffer [ RX_PACKET_DATA ];      ///<  Data buffer
  99 } DT_TCP4_RX_DATA;
 100
 101 typedef struct
 102 {
 103   EFI_TCP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 104   UINT8 Buffer [ 1 ];                   ///<  Data buffer
 105 } DT_TCP4_TX_DATA;
 106
 107 typedef struct
 108 {
 109   EFI_UDP4_SESSION_DATA Session;        ///< * Remote network address
 110   EFI_UDP4_RECEIVE_DATA * pRxData;      ///< * Receive operation description
 111 } DT_UDP4_RX_DATA;
 112
 113 typedef struct
 114 {
 115   EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address
 116   EFI_UDP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description
 117   UINT8 Buffer [ 1 ];                   ///<  Data buffer
 118 } DT_UDP4_TX_DATA;
 119
 120 typedef struct _DT_PACKET {
 121   DT_PACKET * pNext;                    ///<  Next packet in the receive list
 122   size_t PacketSize;                    ///<  Size of this data structure
 123   union {
 124     DT_TCP4_RX_DATA Tcp4Rx;             ///<  Receive operation description
 125     DT_TCP4_TX_DATA Tcp4Tx;             ///<  Transmit operation description
 126     DT_UDP4_RX_DATA Udp4Rx;             ///<  Receive operation description
 127     DT_UDP4_TX_DATA Udp4Tx;             ///<  Transmit operation description
 128   } Op;
 129 } GCC_DT_PACKET;
 130
 131 /**
 132   Service control structure
 133
 134   The driver uses this structure to manage the network devices.
 135 **/
 136 typedef struct _DT_SERVICE {
 137   UINTN Signature;          ///<  Structure identification
 138
 139   //
 140   //  Links
 141   //
 142   DT_SERVICE * pNext;       ///<  Next service in the service list
 143
 144   //
 145   //  Service data
 146   //
 147   CONST DT_SOCKET_BINDING * pSocketBinding; ///<  Name and shutdown routine
 148   EFI_HANDLE Controller;    ///<  Controller for the service
 149   VOID * pInterface;        ///<  Network layer service binding interface
 150
 151   //
 152   //  Network data
 153   //
 154   NETWORK_TYPE NetworkType; ///<  Type of network service
 155   DT_PORT * pPortList;      ///<  List of ports using this service
 156 }GCC_DT_SERVICE;
 157
 158 /**
 159   Start the close operation on a TCP4 port.
 160
 161   @param [in] pPort       Address of the port structure.
 162   @param [in] bAbort      Set TRUE to abort active transfers
 163   @param [in] DebugFlags  Flags for debug messages
 164
 165 **/
 166 typedef
 167 EFI_STATUS
 168 PFN_PORT_CLOSE_START (
 169   IN DT_PORT * pPort,
 170   IN BOOLEAN bAbort,
 171   IN UINTN DebugFlags
 172   );
 173
 174 /**
 175   TCP4 context structure
 176
 177   The driver uses this structure to manage the TCP4 connections.
 178 **/
 179 typedef struct {
 180   //
 181   //  TCP4 context
 182   //
 183   EFI_HANDLE Handle;                ///<  TCP4 port handle
 184   EFI_TCP4_PROTOCOL * pProtocol;    ///<  TCP4 protocol pointer
 185   EFI_TCP4_CONFIG_DATA ConfigData;  ///<  TCP4 configuration data
 186   EFI_TCP4_OPTION Option;           ///<  TCP4 port options
 187   BOOLEAN bConfigured;              ///<  TRUE if configuration was successful
 188
 189   //
 190   //  Tokens
 191   //
 192   EFI_TCP4_LISTEN_TOKEN ListenToken;  ///<  Listen control
 193   EFI_TCP4_CONNECTION_TOKEN ConnectToken; ///<  Connection control
 194   EFI_TCP4_CLOSE_TOKEN CloseToken;    ///<  Close control
 195
 196   //
 197   //  Receive data management
 198   //
 199   EFI_TCP4_IO_TOKEN RxToken;        ///<  Receive token
 200   DT_PACKET * pReceivePending;      ///<  Receive operation in progress
 201
 202   //
 203   //  Transmit data management
 204   //
 205   EFI_TCP4_IO_TOKEN TxOobToken;     ///<  Urgent data token
 206   DT_PACKET * pTxOobPacket;         ///<  Urgent data in progress
 207
 208   EFI_TCP4_IO_TOKEN TxToken;        ///<  Normal data token
 209   DT_PACKET * pTxPacket;            ///<  Normal transmit in progress
 210 } DT_TCP4_CONTEXT;
 211
 212 /**
 213   UDP4 context structure
 214
 215   The driver uses this structure to manage the UDP4 connections.
 216 **/
 217 typedef struct {
 218   //
 219   //  UDP4 context
 220   //
 221   EFI_HANDLE Handle;                ///<  UDP4 port handle
 222   EFI_UDP4_PROTOCOL * pProtocol;    ///<  UDP4 protocol pointer
 223   EFI_UDP4_CONFIG_DATA ConfigData;  ///<  UDP4 configuration data
 224   BOOLEAN bConfigured;              ///<  TRUE if configuration was successful
 225
 226   //
 227   //  Receive data management
 228   //
 229   EFI_UDP4_COMPLETION_TOKEN RxToken;///<  Receive token
 230   DT_PACKET * pReceivePending;      ///<  Receive operation in progress
 231
 232   //
 233   //  Transmit data management
 234   //
 235   EFI_UDP4_COMPLETION_TOKEN TxToken;///<  Transmit token
 236   DT_PACKET * pTxPacket;            ///<  Transmit in progress
 237 } DT_UDP4_CONTEXT;
 238
 239
 240 /**
 241   Port control structure
 242
 243   The driver uses this structure to manager the socket's connection
 244   with the network driver.
 245 **/
 246 typedef struct _DT_PORT {
 247   UINTN Signature;              ///<  Structure identification
 248
 249   //
 250   //  List links
 251   //
 252   DT_PORT * pLinkService;       ///<  Link in service port list
 253   DT_PORT * pLinkSocket;        ///<  Link in socket port list
 254
 255   //
 256   //  Structures
 257   //
 258   DT_SERVICE * pService;        ///<  Service for this port
 259   DT_SOCKET * pSocket;          ///<  Socket for this port
 260 //  PFN_CLOSE_PORT pfnClosePort;  ///<  Routine to immediately close the port
 261   PFN_PORT_CLOSE_START * pfnCloseStart; ///<  Routine to start closing the port
 262
 263   //
 264   //  Protocol specific management data
 265   //
 266   PORT_STATE State;             ///<  State of the port
 267   UINTN DebugFlags;             ///<  Debug flags used to close the port
 268   BOOLEAN bCloseNow;            ///<  TRUE = Close the port immediately
 269
 270   union {
 271     DT_TCP4_CONTEXT Tcp4;       ///<  TCPv4 management data
 272     DT_UDP4_CONTEXT Udp4;       ///<  UDPv4 management data
 273   } Context;
 274 }GCC_DT_PORT;
 275
 276 /**
 277   Socket control structure
 278
 279   The driver uses this structure to manage the socket.
 280 **/
 281 typedef struct _DT_SOCKET {
 282   UINTN Signature;          ///<  Structure identification
 283
 284   //
 285   //  Protocol binding
 286   //
 287   EFI_SOCKET_PROTOCOL SocketProtocol; ///<  Socket protocol declaration
 288
 289   //
 290   //  Socket management
 291   //
 292   DT_SOCKET * pNext;            ///<  Next socket in the list of sockets
 293   int errno;                    ///<  Error information for this socket
 294   EFI_STATUS Status;            ///<  Asyncronous error information for this socket
 295   SOCKET_STATE State;           ///<  Socket state
 296
 297   //
 298   //  Socket data
 299   //
 300   int Domain;                   ///<  Specifies family of protocols
 301   int Type;                     ///<  Specifies how to make network connection
 302   int Protocol;                 ///<  Specifies lower layer protocol to use
 303   BOOLEAN bConfigured;          ///<  Set after the socket is configured
 304
 305   BOOLEAN bRxDisable;           ///<  Receive disabled via shutdown
 306   size_t RxBytes;               ///<  Total Rx bytes
 307   size_t RxOobBytes;            ///<  Urgent Rx bytes
 308   EFI_STATUS RxError;           ///<  Error during receive
 309
 310   BOOLEAN bTxDisable;           ///<  Transmit disabled via shutdown
 311   size_t TxBytes;               ///<  Normal Tx bytes
 312   size_t TxOobBytes;            ///<  Urgent Tx bytes
 313   EFI_STATUS TxError;           ///<  Error during transmit
 314
 315   //
 316   //  Pending connection data
 317   //
 318   BOOLEAN bConnected;           ///<  Set when connected, cleared by poll
 319   EFI_STATUS ConnectStatus;     ///<  Connection status
 320   UINTN MaxFifoDepth;           ///<  Maximum FIFO depth
 321   UINTN FifoDepth;              ///<  Number of sockets in the FIFO
 322   DT_SOCKET * pFifoHead;        ///<  Head of the FIFO
 323   DT_SOCKET * pFifoTail;        ///<  Tail of the FIFO
 324   DT_SOCKET * pNextConnection;  ///<  Link in the FIFO
 325
 326   //
 327   //  Network use
 328   //
 329   DT_PORT * pPortList;          ///<  List of ports managed by this socket
 330   EFI_EVENT WaitAccept;         ///<  Wait for accept completion
 331
 332   //
 333   //  Receive data management
 334   //
 335   UINT32 MaxRxBuf;                  ///<  Maximum size of the receive buffer
 336   struct timeval RxTimeout;         ///<  Receive timeout
 337   DT_PACKET * pRxFree;              ///<  Free packet list
 338   DT_PACKET * pRxOobPacketListHead; ///<  Urgent data list head
 339   DT_PACKET * pRxOobPacketListTail; ///<  Urgent data list tail
 340   DT_PACKET * pRxPacketListHead;    ///<  Normal data list head
 341   DT_PACKET * pRxPacketListTail;    ///<  Normal data list tail
 342
 343   //
 344   //  Transmit data management
 345   //
 346   UINT32 MaxTxBuf;                  ///<  Maximum size of the transmit buffer
 347   DT_PACKET * pTxOobPacketListHead; ///<  Urgent data list head
 348   DT_PACKET * pTxOobPacketListTail; ///<  Urgent data list tail
 349   DT_PACKET * pTxPacketListHead;    ///<  Normal data list head
 350   DT_PACKET * pTxPacketListTail;    ///<  Normal data list tail
 351 }GCC_DT_SOCKET;
 352
 353 #define SOCKET_FROM_PROTOCOL(a)  CR(a, DT_SOCKET, SocketProtocol, SOCKET_SIGNATURE) ///< Locate DT_SOCKET from protocol
 354
 355 /**
 356   Socket layer control structure
 357
 358   The driver uses this structure to manage the driver.
 359 **/
 360 typedef struct {
 361   UINTN Signature;              ///<  Structure identification
 362
 363   //
 364   //  Service binding interface
 365   //
 366   EFI_SERVICE_BINDING_PROTOCOL ServiceBinding;///<  Driver's binding
 367
 368   //
 369   //  Image data
 370   //
 371   EFI_HANDLE ImageHandle;       ///<  Image handle
 372
 373   //
 374   //  Network services
 375   //
 376   DT_SERVICE * pTcp4List;       ///<  List of Tcp4 services
 377   DT_SERVICE * pUdp4List;       ///<  List of Udp4 services
 378
 379   //
 380   //  Socket management
 381   //
 382   DT_SOCKET * pSocketList;      ///<  List of sockets
 383
 384   //
 385   //  TCP4 service
 386   //
 387   UINTN TcpCloseMax4;           ///<  Number of entries in the ring buffer
 388   UINTN TcpCloseIn4;            ///<  Offset into TcpClose4 ring buffer - Close request
 389   UINTN TcpCloseOut4;           ///<  Offset into TcpClose4 ring buffer - Close operation
 390   EFI_TCP4_PROTOCOL ** ppTcpClose4; ///<  Ring buffer to close TCP4 ports
 391 } DT_LAYER;
 392
 393 #define LAYER_FROM_SERVICE(a) CR(a, DT_LAYER, ServiceBinding, LAYER_SIGNATURE) ///< Locate DT_LAYER from service binding
 394
 395 //------------------------------------------------------------------------------
 396 // Data
 397 //------------------------------------------------------------------------------
 398
 399 extern DT_LAYER mEslLayer;
 400
 401 //------------------------------------------------------------------------------
 402 // Socket Support Routines
 403 //------------------------------------------------------------------------------
 404
 405 /**
 406   Allocate and initialize a DT_SOCKET structure.
 407
 408   The ::SocketAllocate() function allocates a DT_SOCKET structure
 409   and installs a protocol on ChildHandle.  If pChildHandle is a
 410   pointer to NULL, then a new handle is created and returned in
 411   pChildHandle.  If pChildHandle is not a pointer to NULL, then
 412   the protocol installs on the existing pChildHandle.
 413
 414   @param [in, out] pChildHandle Pointer to the handle of the child to create.
 415                                 If it is NULL, then a new handle is created.
 416                                 If it is a pointer to an existing UEFI handle,
 417                                 then the protocol is added to the existing UEFI
 418                                 handle.
 419   @param [in] DebugFlags        Flags for debug messages
 420   @param [in, out] ppSocket     The buffer to receive the DT_SOCKET structure address.
 421
 422   @retval EFI_SUCCESS           The protocol was added to ChildHandle.
 423   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
 424   @retval EFI_OUT_OF_RESOURCES  There are not enough resources availabe to create
 425                                 the child
 426   @retval other                 The child handle was not created
 427
 428 **/
 429 EFI_STATUS
 430 EFIAPI
 431 EslSocketAllocate (
 432   IN OUT EFI_HANDLE * pChildHandle,
 433   IN     UINTN DebugFlags,
 434   IN OUT DT_SOCKET ** ppSocket
 435   );
 436
 437 /**
 438   Allocate a packet for a receive or transmit operation
 439
 440   @param [in] ppPacket      Address to receive the DT_PACKET structure
 441   @param [in] LengthInBytes Length of the packet structure
 442   @param [in] DebugFlags    Flags for debug messages
 443
 444   @retval EFI_SUCCESS - The packet was allocated successfully
 445
 446  **/
 447 EFI_STATUS
 448 EslSocketPacketAllocate (
 449   IN DT_PACKET ** ppPacket,
 450   IN size_t LengthInBytes,
 451   IN UINTN DebugFlags
 452   );
 453
 454 /**
 455   Free a packet used for receive or transmit operation
 456
 457   @param [in] pPacket     Address of the DT_PACKET structure
 458   @param [in] DebugFlags  Flags for debug messages
 459
 460   @retval EFI_SUCCESS - The packet was allocated successfully
 461
 462  **/
 463 EFI_STATUS
 464 EslSocketPacketFree (
 465   IN DT_PACKET * pPacket,
 466   IN UINTN DebugFlags
 467   );
 468
 469 //------------------------------------------------------------------------------
 470 // Tcp4 Routines
 471 //------------------------------------------------------------------------------
 472
 473 /**
 474   Accept a network connection.
 475
 476   The SocketAccept routine waits for a network connection to the socket.
 477   It is able to return the remote network address to the caller if
 478   requested.
 479
 480   @param [in] pSocket   Address of the socket structure.
 481
 482   @param [in] pSockAddr       Address of a buffer to receive the remote
 483                               network address.
 484
 485   @param [in, out] pSockAddrLength  Length in bytes of the address buffer.
 486                                     On output specifies the length of the
 487                                     remote network address.
 488
 489   @retval EFI_SUCCESS   Remote address is available
 490   @retval Others        Remote address not available
 491
 492  **/
 493 EFI_STATUS
 494 EslTcpAccept4 (
 495   IN DT_SOCKET * pSocket,
 496   IN struct sockaddr * pSockAddr,
 497   IN OUT socklen_t * pSockAddrLength
 498   );
 499
 500 /**
 501   Bind a name to a socket.
 502
 503   The ::TcpBind4 routine connects a name to A TCP4 stack on the local machine.
 504
 505   @param [in] pSocket   Address of the socket structure.
 506
 507   @param [in] pSockAddr Address of a sockaddr structure that contains the
 508                         connection point on the local machine.  An IPv4 address
 509                         of INADDR_ANY specifies that the connection is made to
 510                         all of the network stacks on the platform.  Specifying a
 511                         specific IPv4 address restricts the connection to the
 512                         network stack supporting that address.  Specifying zero
 513                         for the port causes the network layer to assign a port
 514                         number from the dynamic range.  Specifying a specific
 515                         port number causes the network layer to use that port.
 516
 517   @param [in] SockAddrLen   Specifies the length in bytes of the sockaddr structure.
 518
 519   @retval EFI_SUCCESS - Socket successfully created
 520
 521  **/
 522 EFI_STATUS
 523 EslTcpBind4 (
 524   IN DT_SOCKET * pSocket,
 525   IN const struct sockaddr * pSockAddr,
 526   IN socklen_t SockAddrLength
 527   );
 528
 529 /**
 530   Poll for completion of the connection attempt.
 531
 532   The ::TcpConnectPoll4 routine determines when the connection
 533   attempt transitions from being in process to being complete.
 534
 535   @param [in] pSocket         Address of the socket structure.
 536
 537   @retval EFI_SUCCESS   The connection was successfully established.
 538   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 539   @retval Others        The connection attempt failed.
 540
 541  **/
 542 EFI_STATUS
 543 EslTcpConnectPoll4 (
 544   IN DT_SOCKET * pSocket
 545   );
 546
 547 /**
 548   Connect to a remote system via the network.
 549
 550   The ::TcpConnectStart4= routine starts the connection processing
 551   for a TCP4 port.
 552
 553   @param [in] pSocket         Address of the socket structure.
 554
 555   @param [in] pSockAddr       Network address of the remote system.
 556
 557   @param [in] SockAddrLength  Length in bytes of the network address.
 558
 559   @retval EFI_SUCCESS   The connection was successfully established.
 560   @retval EFI_NOT_READY The connection is in progress, call this routine again.
 561   @retval Others        The connection attempt failed.
 562
 563  **/
 564 EFI_STATUS
 565 EslTcpConnectStart4 (
 566   IN DT_SOCKET * pSocket,
 567   IN const struct sockaddr * pSockAddr,
 568   IN socklen_t SockAddrLength
 569   );
 570
 571 /**
 572   Initialize the TCP4 service.
 573
 574   This routine initializes the TCP4 service after its service binding
 575   protocol was located on a controller.
 576
 577   @param [in] pService             DT_SERVICE structure address
 578
 579   @retval EFI_SUCCESS          The service was properly initialized
 580   @retval other                A failure occurred during the service initialization
 581
 582 **/
 583 EFI_STATUS
 584 EFIAPI
 585 EslTcpInitialize4 (
 586   IN DT_SERVICE * pService
 587   );
 588
 589 /**
 590   Get the local socket address
 591
 592   @param [in] pSocket             Address of the socket structure.
 593
 594   @param [out] pAddress           Network address to receive the local system address
 595
 596   @param [in,out] pAddressLength  Length of the local network address structure
 597
 598   @retval EFI_SUCCESS - Address available
 599   @retval Other - Failed to get the address
 600
 601 **/
 602 EFI_STATUS
 603 EslTcpGetLocalAddress4 (
 604   IN DT_SOCKET * pSocket,
 605   OUT struct sockaddr * pAddress,
 606   IN OUT socklen_t * pAddressLength
 607   );
 608
 609 /**
 610   Get the remote socket address
 611
 612   @param [in] pSocket             Address of the socket structure.
 613
 614   @param [out] pAddress           Network address to receive the remote system address
 615
 616   @param [in,out] pAddressLength  Length of the remote network address structure
 617
 618   @retval EFI_SUCCESS - Address available
 619   @retval Other - Failed to get the address
 620
 621 **/
 622 EFI_STATUS
 623 EslTcpGetRemoteAddress4 (
 624   IN DT_SOCKET * pSocket,
 625   OUT struct sockaddr * pAddress,
 626   IN OUT socklen_t * pAddressLength
 627   );
 628
 629 /**
 630   Establish the known port to listen for network connections.
 631
 632   The ::Tcp4Listen routine places the port into a state that enables connection
 633   attempts.  Connections are placed into FIFO order in a queue to be serviced
 634   by the application.  The application calls the ::Tcp4Accept routine to remove
 635   the next connection from the queue and get the associated socket.  The
 636   <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">POSIX</a>
 637   documentation for the listen routine is available online for reference.
 638
 639   @param [in] pSocket     Address of the socket structure.
 640
 641   @retval EFI_SUCCESS - Socket successfully created
 642   @retval Other - Failed to enable the socket for listen
 643
 644 **/
 645 EFI_STATUS
 646 EslTcpListen4 (
 647   IN DT_SOCKET * pSocket
 648   );
 649
 650 /**
 651   Process the connection attempt
 652
 653   A system has initiated a connection attempt with a socket in the
 654   listen state.  Attempt to complete the connection.
 655
 656   @param  Event         The listeen completion event
 657
 658   @param  pPort         The DT_PORT structure address
 659
 660 **/
 661 VOID
 662 EslTcpListenComplete4 (
 663   IN EFI_EVENT Event,
 664   IN DT_PORT * pPort
 665   );
 666
 667 /**
 668   Allocate and initialize a DT_PORT structure.
 669
 670   @param [in] pSocket     Address of the socket structure.
 671   @param [in] pService    Address of the DT_SERVICE structure.
 672   @param [in] ChildHandle TCP4 child handle
 673   @param [in] pIpAddress  Buffer containing IP4 network address of the local host
 674   @param [in] PortNumber  Tcp4 port number
 675   @param [in] DebugFlags  Flags for debug messages
 676   @param [out] ppPort     Buffer to receive new DT_PORT structure address
 677
 678   @retval EFI_SUCCESS - Socket successfully created
 679
 680  **/
 681 EFI_STATUS
 682 EslTcpPortAllocate4 (
 683   IN DT_SOCKET * pSocket,
 684   IN DT_SERVICE * pService,
 685   IN EFI_HANDLE ChildHandle,
 686   IN CONST UINT8 *pIpAddress,
 687   IN UINT16 PortNumber,
 688   IN UINTN DebugFlags,
 689   OUT DT_PORT ** ppPort
 690   );
 691
 692 /**
 693   Close a TCP4 port.
 694
 695   This routine releases the resources allocated by
 696   ::TcpPortAllocate4().
 697
 698   @param [in] pPort       Address of the port structure.
 699
 700   @retval EFI_SUCCESS     The port is closed
 701   @retval other           Port close error
 702
 703 **/
 704 EFI_STATUS
 705 EslTcpPortClose4 (
 706   IN DT_PORT * pPort
 707   );
 708
 709 /**
 710   Process the port close completion
 711
 712   @param  Event         The close completion event
 713
 714   @param  pPort         The DT_PORT structure address
 715
 716 **/
 717 VOID
 718 EslTcpPortCloseComplete4 (
 719   IN EFI_EVENT Event,
 720   IN DT_PORT * pPort
 721   );
 722
 723 /**
 724   Port close state 3
 725
 726   Continue the close operation after the receive is complete.
 727
 728   @param [in] pPort       Address of the port structure.
 729
 730   @retval EFI_SUCCESS         The port is closed
 731   @retval EFI_NOT_READY       The port is still closing
 732   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
 733                               most likely the routine was called already.
 734
 735 **/
 736 EFI_STATUS
 737 EslTcpPortCloseRxDone4 (
 738   IN DT_PORT * pPort
 739   );
 740
 741 /**
 742   Start the close operation on a TCP4 port.
 743
 744   @param [in] pPort       Address of the port structure.
 745   @param [in] bAbort      Set TRUE to abort active transfers
 746   @param [in] DebugFlags  Flags for debug messages
 747
 748 **/
 749 EFI_STATUS
 750 EslTcpPortCloseStart4 (
 751   IN DT_PORT * pPort,
 752   IN BOOLEAN bAbort,
 753   IN UINTN DebugFlags
 754   );
 755
 756 /**
 757   Port close state 2
 758
 759   Continue the close operation after the transmission is complete.
 760
 761   @param [in] pPort       Address of the port structure.
 762
 763   @retval EFI_NOT_READY       The port is still closing
 764   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
 765                               most likely the routine was called already.
 766
 767 **/
 768 EFI_STATUS
 769 EslTcpPortCloseTxDone4 (
 770   IN DT_PORT * pPort
 771   );
 772
 773 /**
 774   Receive data from a network connection.
 775
 776
 777   @param [in] pSocket         Address of a DT_SOCKET structure
 778
 779   @param [in] Flags           Message control flags
 780
 781   @param [in] BufferLength    Length of the the buffer
 782
 783   @param [in] pBuffer         Address of a buffer to receive the data.
 784
 785   @param [in] pDataLength     Number of received data bytes in the buffer.
 786
 787   @param [out] pAddress       Network address to receive the remote system address
 788
 789   @param [in,out] pAddressLength  Length of the remote network address structure
 790
 791   @retval EFI_SUCCESS - Socket data successfully received
 792
 793  **/
 794 EFI_STATUS
 795 EslTcpReceive4 (
 796   IN DT_SOCKET * pSocket,
 797   IN INT32 Flags,
 798   IN size_t BufferLength,
 799   IN UINT8 * pBuffer,
 800   OUT size_t * pDataLength,
 801   OUT struct sockaddr * pAddress,
 802   IN OUT socklen_t * pAddressLength
 803   );
 804
 805 /**
 806   Cancel the receive operations
 807
 808   @param [in] pSocket         Address of a DT_SOCKET structure
 809
 810   @retval EFI_SUCCESS - The cancel was successful
 811
 812  **/
 813 EFI_STATUS
 814 EslTcpRxCancel4 (
 815   IN DT_SOCKET * pSocket
 816   );
 817
 818 /**
 819   Process the receive completion
 820
 821   Buffer the data that was just received.
 822
 823   @param  Event         The receive completion event
 824
 825   @param  pPort         The DT_PORT structure address
 826
 827 **/
 828 VOID
 829 EslTcpRxComplete4 (
 830   IN EFI_EVENT Event,
 831   IN DT_PORT * pPort
 832   );
 833
 834 /**
 835   Start a receive operation
 836
 837   @param [in] pPort       Address of the DT_PORT structure.
 838
 839  **/
 840 VOID
 841 EslTcpRxStart4 (
 842   IN DT_PORT * pPort
 843   );
 844
 845 /**
 846   Shutdown the TCP4 service.
 847
 848   This routine undoes the work performed by ::TcpInitialize4.
 849
 850   @param [in] pService             DT_SERVICE structure address
 851
 852 **/
 853 VOID
 854 EFIAPI
 855 EslTcpShutdown4 (
 856   IN DT_SERVICE * pService
 857   );
 858
 859 /**
 860   Determine if the socket is configured.
 861
 862
 863   @param [in] pSocket         Address of a DT_SOCKET structure
 864
 865   @retval EFI_SUCCESS - The port is connected
 866   @retval EFI_NOT_STARTED - The port is not connected
 867
 868  **/
 869  EFI_STATUS
 870  EslTcpSocketIsConfigured4 (
 871   IN DT_SOCKET * pSocket
 872   );
 873
 874 /**
 875   Buffer data for transmission over a network connection.
 876
 877   This routine is called by the socket layer API to buffer
 878   data for transmission.  When necessary, this routine will
 879   start the transmit engine that performs the data transmission
 880   on the network connection.
 881
 882   @param [in] pSocket         Address of a DT_SOCKET structure
 883
 884   @param [in] Flags           Message control flags
 885
 886   @param [in] BufferLength    Length of the the buffer
 887
 888   @param [in] pBuffer         Address of a buffer to receive the data.
 889
 890   @param [in] pDataLength     Number of received data bytes in the buffer.
 891
 892   @retval EFI_SUCCESS - Socket data successfully buffered
 893
 894  **/
 895 EFI_STATUS
 896 EslTcpTxBuffer4 (
 897   IN DT_SOCKET * pSocket,
 898   IN int Flags,
 899   IN size_t BufferLength,
 900   IN CONST UINT8 * pBuffer,
 901   OUT size_t * pDataLength
 902   );
 903
 904 /**
 905   Process the normal data transmit completion
 906
 907   @param  Event         The normal transmit completion event
 908
 909   @param  pPort         The DT_PORT structure address
 910
 911 **/
 912 VOID
 913 EslTcpTxComplete4 (
 914   IN EFI_EVENT Event,
 915   IN DT_PORT * pPort
 916   );
 917
 918 /**
 919   Process the urgent data transmit completion
 920
 921   @param  Event         The urgent transmit completion event
 922
 923   @param  pPort         The DT_PORT structure address
 924
 925 **/
 926 VOID
 927 EslTcpTxOobComplete4 (
 928   IN EFI_EVENT Event,
 929   IN DT_PORT * pPort
 930   );
 931
 932 /**
 933   Transmit data using a network connection.
 934
 935
 936   @param [in] pPort           Address of a DT_PORT structure
 937   @param [in] pToken          Address of either the OOB or normal transmit token
 938   @param [in] ppQueueHead     Transmit queue head address
 939   @param [in] ppQueueTail     Transmit queue tail address
 940   @param [in] ppPacket        Active transmit packet address
 941
 942  **/
 943 VOID
 944 EslTcpTxStart4 (
 945   IN DT_PORT * pPort,
 946   IN EFI_TCP4_IO_TOKEN * pToken,
 947   IN DT_PACKET ** ppQueueHead,
 948   IN DT_PACKET ** ppQueueTail,
 949   IN DT_PACKET ** ppPacket
 950   );
 951
 952 //------------------------------------------------------------------------------
 953 // Udp4 Routines
 954 //------------------------------------------------------------------------------
 955
 956 /**
 957   Bind a name to a socket.
 958
 959   The ::UdpBind4 routine connects a name to a UDP4 stack on the local machine.
 960
 961   @param [in] pSocket   Address of the socket structure.
 962
 963   @param [in] pSockAddr Address of a sockaddr structure that contains the
 964                         connection point on the local machine.  An IPv4 address
 965                         of INADDR_ANY specifies that the connection is made to
 966                         all of the network stacks on the platform.  Specifying a
 967                         specific IPv4 address restricts the connection to the
 968                         network stack supporting that address.  Specifying zero
 969                         for the port causes the network layer to assign a port
 970                         number from the dynamic range.  Specifying a specific
 971                         port number causes the network layer to use that port.
 972
 973   @param [in] SockAddrLen   Specifies the length in bytes of the sockaddr structure.
 974
 975   @retval EFI_SUCCESS - Socket successfully created
 976
 977  **/
 978 EFI_STATUS
 979 EslUdpBind4 (
 980   IN DT_SOCKET * pSocket,
 981   IN const struct sockaddr * pSockAddr,
 982   IN socklen_t SockAddrLength
 983   );
 984
 985 /**
 986   Initialize the UDP4 service.
 987
 988   This routine initializes the UDP4 service after its service binding
 989   protocol was located on a controller.
 990
 991   @param [in] pService        DT_SERVICE structure address
 992
 993   @retval EFI_SUCCESS         The service was properly initialized
 994   @retval other               A failure occurred during the service initialization
 995
 996 **/
 997 EFI_STATUS
 998 EFIAPI
 999 EslUdpInitialize4 (
1000   IN DT_SERVICE * pService
1001   );
1002
1003 /**
1004   Allocate and initialize a DT_PORT structure.
1005
1006   @param [in] pSocket     Address of the socket structure.
1007   @param [in] pService    Address of the DT_SERVICE structure.
1008   @param [in] ChildHandle Udp4 child handle
1009   @param [in] pIpAddress  Buffer containing IP4 network address of the local host
1010   @param [in] PortNumber  Udp4 port number
1011   @param [in] DebugFlags  Flags for debug messages
1012   @param [out] ppPort     Buffer to receive new DT_PORT structure address
1013
1014   @retval EFI_SUCCESS - Socket successfully created
1015
1016  **/
1017 EFI_STATUS
1018 EslUdpPortAllocate4 (
1019   IN DT_SOCKET * pSocket,
1020   IN DT_SERVICE * pService,
1021   IN EFI_HANDLE ChildHandle,
1022   IN CONST UINT8 * pIpAddress,
1023   IN UINT16 PortNumber,
1024   IN UINTN DebugFlags,
1025   OUT DT_PORT ** ppPort
1026   );
1027
1028 /**
1029   Close a UDP4 port.
1030
1031   This routine releases the resources allocated by
1032   ::UdpPortAllocate4().
1033
1034   @param [in] pPort       Address of the port structure.
1035
1036   @retval EFI_SUCCESS     The port is closed
1037   @retval other           Port close error
1038
1039 **/
1040 EFI_STATUS
1041 EslUdpPortClose4 (
1042   IN DT_PORT * pPort
1043   );
1044
1045 /**
1046   Start the close operation on a UDP4 port, state 1.
1047
1048   Closing a port goes through the following states:
1049   1. Port close starting - Mark the port as closing and wait for transmission to complete
1050   2. Port TX close done - Transmissions complete, close the port and abort the receives
1051   3. Port RX close done - Receive operations complete, close the port
1052   4. Port closed - Release the port resources
1053
1054   @param [in] pPort       Address of the port structure.
1055   @param [in] bCloseNow   Set TRUE to abort active transfers
1056   @param [in] DebugFlags  Flags for debug messages
1057
1058   @retval EFI_SUCCESS         The port is closed, not normally returned
1059   @retval EFI_NOT_READY       The port has started the closing process
1060   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
1061                               most likely the routine was called already.
1062
1063 **/
1064 EFI_STATUS
1065 EslUdpPortCloseStart4 (
1066   IN DT_PORT * pPort,
1067   IN BOOLEAN bCloseNow,
1068   IN UINTN DebugFlags
1069   );
1070
1071 /**
1072   Port close state 2
1073
1074   Continue the close operation after the transmission is complete.
1075
1076   @param [in] pPort       Address of the port structure.
1077
1078   @retval EFI_SUCCESS         The port is closed, not normally returned
1079   @retval EFI_NOT_READY       The port is still closing
1080   @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,
1081                               most likely the routine was called already.
1082
1083 **/
1084 EFI_STATUS
1085 EslUdpPortCloseTxDone4 (
1086   IN DT_PORT * pPort
1087   );
1088
1089 /**
1090   Connect to a remote system via the network.
1091
1092   The ::UdpConnectStart4= routine sets the remote address for the connection.
1093
1094   @param [in] pSocket         Address of the socket structure.
1095
1096   @param [in] pSockAddr       Network address of the remote system.
1097
1098   @param [in] SockAddrLength  Length in bytes of the network address.
1099
1100   @retval EFI_SUCCESS   The connection was successfully established.
1101   @retval EFI_NOT_READY The connection is in progress, call this routine again.
1102   @retval Others        The connection attempt failed.
1103
1104  **/
1105 EFI_STATUS
1106 EslUdpConnect4 (
1107   IN DT_SOCKET * pSocket,
1108   IN const struct sockaddr * pSockAddr,
1109   IN socklen_t SockAddrLength
1110   );
1111
1112 /**
1113   Get the local socket address
1114
1115   @param [in] pSocket             Address of the socket structure.
1116
1117   @param [out] pAddress           Network address to receive the local system address
1118
1119   @param [in,out] pAddressLength  Length of the local network address structure
1120
1121   @retval EFI_SUCCESS - Address available
1122   @retval Other - Failed to get the address
1123
1124 **/
1125 EFI_STATUS
1126 EslUdpGetLocalAddress4 (
1127   IN DT_SOCKET * pSocket,
1128   OUT struct sockaddr * pAddress,
1129   IN OUT socklen_t * pAddressLength
1130   );
1131
1132 /**
1133   Get the remote socket address
1134
1135   @param [in] pSocket             Address of the socket structure.
1136
1137   @param [out] pAddress           Network address to receive the remote system address
1138
1139   @param [in,out] pAddressLength  Length of the remote network address structure
1140
1141   @retval EFI_SUCCESS - Address available
1142   @retval Other - Failed to get the address
1143
1144 **/
1145 EFI_STATUS
1146 EslUdpGetRemoteAddress4 (
1147   IN DT_SOCKET * pSocket,
1148   OUT struct sockaddr * pAddress,
1149   IN OUT socklen_t * pAddressLength
1150   );
1151
1152 /**
1153   Receive data from a network connection.
1154
1155   To minimize the number of buffer copies, the ::UdpRxComplete4
1156   routine queues the UDP4 driver's buffer to a list of datagrams
1157   waiting to be received.  The socket driver holds on to the
1158   buffers from the UDP4 driver until the application layer requests
1159   the data or the socket is closed.
1160
1161   The application calls this routine in the socket layer to
1162   receive datagrams from one or more remote systems. This routine
1163   removes the next available datagram from the list of datagrams
1164   and copies the data from the UDP4 driver's buffer into the
1165   application's buffer.  The UDP4 driver's buffer is then returned.
1166
1167   @param [in] pSocket         Address of a DT_SOCKET structure
1168
1169   @param [in] Flags           Message control flags
1170
1171   @param [in] BufferLength    Length of the the buffer
1172
1173   @param [in] pBuffer         Address of a buffer to receive the data.
1174
1175   @param [in] pDataLength     Number of received data bytes in the buffer.
1176
1177   @param [out] pAddress       Network address to receive the remote system address
1178
1179   @param [in,out] pAddressLength  Length of the remote network address structure
1180
1181   @retval EFI_SUCCESS - Socket data successfully received
1182
1183 **/
1184 EFI_STATUS
1185 EslUdpReceive4 (
1186   IN DT_SOCKET * pSocket,
1187   IN INT32 Flags,
1188   IN size_t BufferLength,
1189   IN UINT8 * pBuffer,
1190   OUT size_t * pDataLength,
1191   OUT struct sockaddr * pAddress,
1192   IN OUT socklen_t * pAddressLength
1193   );
1194
1195 /**
1196   Cancel the receive operations
1197
1198   @param [in] pSocket         Address of a DT_SOCKET structure
1199
1200   @retval EFI_SUCCESS - The cancel was successful
1201
1202  **/
1203 EFI_STATUS
1204 EslUdpRxCancel4 (
1205   IN DT_SOCKET * pSocket
1206   );
1207
1208 /**
1209   Process the receive completion
1210
1211   Keep the UDP4 driver's buffer and append it to the list of
1212   datagrams for the application to receive.  The UDP4 driver's
1213   buffer will be returned by either ::UdpReceive4 or
1214   ::UdpPortCloseTxDone4.
1215
1216   @param  Event         The receive completion event
1217
1218   @param  pPort         The DT_PORT structure address
1219
1220 **/
1221 VOID
1222 EslUdpRxComplete4 (
1223   IN EFI_EVENT Event,
1224   IN DT_PORT * pPort
1225   );
1226
1227 /**
1228   Start a receive operation
1229
1230   @param [in] pPort       Address of the DT_PORT structure.
1231
1232  **/
1233 VOID
1234 EslUdpRxStart4 (
1235   IN DT_PORT * pPort
1236   );
1237
1238 /**
1239   Determine if the socket is configured.
1240
1241
1242   @param [in] pSocket         Address of a DT_SOCKET structure
1243
1244   @retval EFI_SUCCESS - The port is connected
1245   @retval EFI_NOT_STARTED - The port is not connected
1246
1247  **/
1248  EFI_STATUS
1249  EslUdpSocketIsConfigured4 (
1250   IN DT_SOCKET * pSocket
1251   );
1252
1253 /**
1254   Process the transmit completion
1255
1256   @param  Event         The normal transmit completion event
1257
1258   @param  pPort         The DT_PORT structure address
1259
1260 **/
1261 VOID
1262 EslUdpTxComplete4 (
1263   IN EFI_EVENT Event,
1264   IN DT_PORT * pPort
1265   );
1266
1267 /**
1268   Shutdown the UDP4 service.
1269
1270   This routine undoes the work performed by ::UdpInitialize4.
1271
1272   @param [in] pService        DT_SERVICE structure address
1273
1274 **/
1275 VOID
1276 EFIAPI
1277 EslUdpShutdown4 (
1278   IN DT_SERVICE * pService
1279   );
1280
1281 /**
1282   Buffer data for transmission over a network connection.
1283
1284   This routine is called by the socket layer API to buffer
1285   data for transmission.  The data is copied into a local buffer
1286   freeing the application buffer for reuse upon return.  When
1287   necessary, this routine will start the transmit engine that
1288   performs the data transmission on the network connection.  The
1289   transmit engine transmits the data a packet at a time over the
1290   network connection.
1291
1292   Transmission errors are returned during the next transmission or
1293   during the close operation.  Only buffering errors are returned
1294   during the current transmission attempt.
1295
1296   @param [in] pSocket         Address of a DT_SOCKET structure
1297
1298   @param [in] Flags           Message control flags
1299
1300   @param [in] BufferLength    Length of the the buffer
1301
1302   @param [in] pBuffer         Address of a buffer to receive the data.
1303
1304   @param [in] pDataLength     Number of received data bytes in the buffer.
1305
1306   @param [in] pAddress        Network address of the remote system address
1307
1308   @param [in] AddressLength   Length of the remote network address structure
1309
1310   @retval EFI_SUCCESS - Socket data successfully buffered
1311
1312 **/
1313 EFI_STATUS
1314 EslUdpTxBuffer4 (
1315   IN DT_SOCKET * pSocket,
1316   IN int Flags,
1317   IN size_t BufferLength,
1318   IN CONST UINT8 * pBuffer,
1319   OUT size_t * pDataLength,
1320   IN const struct sockaddr * pAddress,
1321   IN socklen_t AddressLength
1322   );
1323
1324 /**
1325   Transmit data using a network connection.
1326
1327   @param [in] pPort           Address of a DT_PORT structure
1328
1329  **/
1330 VOID
1331 EslUdpTxStart4 (
1332   IN DT_PORT * pPort
1333   );
1334
1335 //------------------------------------------------------------------------------
1336
1337 #endif  //  _SOCKET_H_