[mirror_edk2.git] / StdLib / EfiSocketLib / Socket.h

/** @file\r
  Definitions for the Socket layer driver.\r
\r
  Copyright (c) 2011, Intel Corporation\r
  All rights reserved. This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
#ifndef _SOCKET_H_\r
#define _SOCKET_H_\r
\r
#include <Efi/EfiSocketLib.h>\r
\r
//------------------------------------------------------------------------------\r
//  Constants\r
//------------------------------------------------------------------------------\r
\r
#define DEBUG_SOCKET        0x20000000  ///<  Display Socket related messages\r
#define DEBUG_BIND          0x10000000  ///<  Display bind related messages\r
#define DEBUG_LISTEN        0x08000000  ///<  Display listen related messages\r
#define DEBUG_CONNECTION    0x04000000  ///<  Display connection list related messages\r
#define DEBUG_POLL          0x02000000  ///<  Display poll messages\r
#define DEBUG_ACCEPT        0x01000000  ///<  Display accept related messages\r
#define DEBUG_RX            0x00800000  ///<  Display receive messages\r
#define DEBUG_TX            0x00400000  ///<  Display transmit messages\r
#define DEBUG_CLOSE         0x00200000  ///<  Display close messages\r
#define DEBUG_CONNECT       0x00100000  ///<  Display connect messages\r
#define DEBUG_OPTION        0x00080000  ///<  Display option messages\r
\r
#define MAX_PENDING_CONNECTIONS     1   ///<  Maximum connection FIFO depth\r
#define MAX_RX_DATA         0x01000000  ///<  Maximum receive data size\r
#define MAX_TX_DATA         ( MAX_RX_DATA * 2 ) ///<  Maximum buffered transmit data in bytes\r
#define RX_PACKET_DATA      0x00100000  ///<  Maximum number of bytes in a RX packet\r
#define MAX_UDP_RETRANSMIT  16          ///<  UDP retransmit attempts to handle address not mapped\r
\r
#define ESL_STRUCTURE_ALIGNMENT_BYTES   15  ///<  Number of bytes for structure alignment\r
#define ESL_STRUCTURE_ALIGNMENT_MASK    ( ~ESL_STRUCTURE_ALIGNMENT_BYTES )  ///<  Mask to align structures\r
\r
#define LAYER_SIGNATURE           SIGNATURE_32 ('S','k','t','L')  ///<  ESL_LAYER memory signature\r
#define SERVICE_SIGNATURE         SIGNATURE_32 ('S','k','t','S')  ///<  ESL_SERVICE memory signature\r
#define SOCKET_SIGNATURE          SIGNATURE_32 ('S','c','k','t')  ///<  ESL_SOCKET memory signature\r
#define PORT_SIGNATURE            SIGNATURE_32 ('P','o','r','t')  ///<  ESL_PORT memory signature\r
\r
\r
/**\r
  Socket states\r
**/\r
typedef enum\r
{\r
  SOCKET_STATE_NOT_CONFIGURED = 0,  ///<  socket call was successful\r
  SOCKET_STATE_BOUND,               ///<  bind call was successful\r
  SOCKET_STATE_LISTENING,           ///<  listen call was successful\r
  SOCKET_STATE_NO_PORTS,            ///<  No ports available\r
  SOCKET_STATE_IN_FIFO,             ///<  Socket on FIFO\r
  SOCKET_STATE_CONNECTING,          ///<  Connecting to a remote system\r
  SOCKET_STATE_CONNECTED,           ///<  Accept or connect call was successful\r
\r
  //\r
  //  Close state must be the last in the list\r
  //\r
  SOCKET_STATE_CLOSED               ///<  Close call was successful\r
} SOCKET_STATE;\r
\r
\r
/**\r
  Port states\r
**/\r
typedef enum\r
{\r
  PORT_STATE_ALLOCATED = 0, ///<  Port allocated\r
  PORT_STATE_OPEN,          ///<  Port opened\r
  PORT_STATE_RX_ERROR,      ///<  Receive error detected\r
\r
  //\r
  //  Close state must be last in the list!\r
  //\r
  //  Using < <= > >= in tests code to detect port close state\r
  //  machine has started\r
  //\r
  PORT_STATE_CLOSE_STARTED, ///<  Close started on port\r
  PORT_STATE_CLOSE_TX_DONE, ///<  Transmits shutdown\r
  PORT_STATE_CLOSE_DONE,    ///<  Port close operation complete\r
  PORT_STATE_CLOSE_RX_DONE  ///<  Receives shutdown\r
} PORT_STATE;\r
\r
//------------------------------------------------------------------------------\r
//  Data Types\r
//------------------------------------------------------------------------------\r
\r
typedef struct _ESL_IO_MGMT ESL_IO_MGMT;///<  Forward declaration\r
typedef struct _ESL_PACKET ESL_PACKET;  ///<  Forward declaration\r
typedef struct _ESL_PORT ESL_PORT;      ///<  Forward declaration\r
typedef struct _ESL_SOCKET ESL_SOCKET;  ///<  Forward declaration\r
\r
/**\r
  Receive context for SOCK_RAW sockets using IPv4.\r
**/\r
typedef struct\r
{\r
  EFI_IP4_RECEIVE_DATA * pRxData;       ///<  Receive operation description\r
} ESL_IP4_RX_DATA;\r
\r
\r
/**\r
  Transmit context for SOCK_RAW sockets using IPv4.\r
**/\r
typedef struct\r
{\r
  EFI_IP4_OVERRIDE_DATA Override;       ///<  Override data\r
  EFI_IP4_TRANSMIT_DATA TxData;         ///<  Transmit operation description\r
  UINT8 Buffer[ 1 ];                    ///<  Data buffer\r
} ESL_IP4_TX_DATA;\r
\r
\r
/**\r
  Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.\r
**/\r
typedef struct\r
{\r
  EFI_TCP4_RECEIVE_DATA RxData;         ///<  Receive operation description\r
  UINT8 Buffer[ RX_PACKET_DATA ];       ///<  Data buffer\r
} ESL_TCP4_RX_DATA;\r
\r
\r
/**\r
  Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.\r
**/\r
typedef struct\r
{\r
  EFI_TCP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description\r
  UINT8 Buffer[ 1 ];                    ///<  Data buffer\r
} ESL_TCP4_TX_DATA;\r
\r
\r
/**\r
  Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6.\r
**/\r
typedef struct\r
{\r
  EFI_TCP6_RECEIVE_DATA RxData;         ///<  Receive operation description\r
  UINT8 Buffer[ RX_PACKET_DATA ];       ///<  Data buffer\r
} ESL_TCP6_RX_DATA;\r
\r
\r
/**\r
  Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6.\r
**/\r
typedef struct\r
{\r
  EFI_TCP6_TRANSMIT_DATA TxData;        ///<  Transmit operation description\r
  UINT8 Buffer[ 1 ];                    ///<  Data buffer\r
} ESL_TCP6_TX_DATA;\r
\r
\r
/**\r
  Receive context for SOCK_DGRAM sockets using UDPv4.\r
**/\r
typedef struct\r
{\r
  EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address\r
  EFI_UDP4_RECEIVE_DATA * pRxData;      ///<  Receive operation description\r
} ESL_UDP4_RX_DATA;\r
\r
\r
/**\r
  Transmit context for SOCK_DGRAM sockets using UDPv4.\r
**/\r
typedef struct\r
{\r
  EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address\r
  EFI_UDP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description\r
  UINTN RetransmitCount;                ///<  Retransmit to handle ARP negotiation\r
  UINT8 Buffer[ 1 ];                    ///<  Data buffer\r
} ESL_UDP4_TX_DATA;\r
\r
\r
/**\r
  Receive context for SOCK_DGRAM sockets using UDPv6.\r
**/\r
typedef struct\r
{\r
  EFI_UDP6_SESSION_DATA Session;        ///<  Remote network address\r
  EFI_UDP6_RECEIVE_DATA * pRxData;      ///<  Receive operation description\r
} ESL_UDP6_RX_DATA;\r
\r
\r
/**\r
  Transmit context for SOCK_DGRAM sockets using UDPv6.\r
**/\r
typedef struct\r
{\r
  EFI_UDP6_SESSION_DATA Session;        ///<  Remote network address\r
  EFI_UDP6_TRANSMIT_DATA TxData;        ///<  Transmit operation description\r
  UINTN RetransmitCount;                ///<  Retransmit to handle ARP negotiation\r
  UINT8 Buffer[ 1 ];                    ///<  Data buffer\r
} ESL_UDP6_TX_DATA;\r
\r
\r
/**\r
  Network specific context for transmit and receive packets.\r
**/\r
typedef struct _ESL_PACKET {\r
  ESL_PACKET * pNext;                   ///<  Next packet in the receive list\r
  size_t PacketSize;                    ///<  Size of this data structure\r
  size_t ValidBytes;                    ///<  Length of valid data in bytes\r
  UINT8 * pBuffer;                      ///<  Current data pointer\r
  union {\r
    ESL_IP4_RX_DATA Ip4Rx;              ///<  Receive operation description\r
    ESL_IP4_TX_DATA Ip4Tx;              ///<  Transmit operation description\r
    ESL_TCP4_RX_DATA Tcp4Rx;            ///<  Receive operation description\r
    ESL_TCP4_TX_DATA Tcp4Tx;            ///<  Transmit operation description\r
    ESL_TCP6_RX_DATA Tcp6Rx;            ///<  Receive operation description\r
    ESL_TCP6_TX_DATA Tcp6Tx;            ///<  Transmit operation description\r
    ESL_UDP4_RX_DATA Udp4Rx;            ///<  Receive operation description\r
    ESL_UDP4_TX_DATA Udp4Tx;            ///<  Transmit operation description\r
    ESL_UDP6_RX_DATA Udp6Rx;            ///<  Receive operation description\r
    ESL_UDP6_TX_DATA Udp6Tx;            ///<  Transmit operation description\r
  } Op;                                 ///<  Network specific context\r
} GCC_ESL_PACKET;\r
\r
/**\r
  Service control structure\r
\r
  The driver uses this structure to manage the network devices.\r
**/\r
typedef struct _ESL_SERVICE {\r
  UINTN Signature;          ///<  Structure identification\r
\r
  //\r
  //  Links\r
  //\r
  ESL_SERVICE * pNext;      ///<  Next service in the service list\r
\r
  //\r
  //  Service data\r
  //\r
  CONST ESL_SOCKET_BINDING * pSocketBinding;      ///<  Name and shutdown routine\r
  EFI_HANDLE Controller;                          ///<  Controller for the service\r
  EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Network layer service binding interface\r
\r
  //\r
  //  Network data\r
  //\r
  ESL_PORT * pPortList;     ///<  List of ports using this service\r
}GCC_ESL_SERVICE;\r
\r
/**\r
  IO management structure\r
\r
  This structure manages a single operation with the network.\r
**/\r
typedef struct _ESL_IO_MGMT {\r
  ESL_IO_MGMT * pNext;                ///<  Next TX management structure\r
  ESL_PORT * pPort;                   ///<  Port structure address\r
  ESL_PACKET * pPacket;               ///<  Packet structure address\r
  union {\r
    EFI_IP4_COMPLETION_TOKEN Ip4Rx;   ///<  IP4 receive token\r
    EFI_IP4_COMPLETION_TOKEN Ip4Tx;   ///<  IP4 transmit token\r
    EFI_TCP4_IO_TOKEN Tcp4Rx;         ///<  TCP4 receive token\r
    EFI_TCP4_IO_TOKEN Tcp4Tx;         ///<  TCP4 transmit token\r
    EFI_TCP6_IO_TOKEN Tcp6Rx;         ///<  TCP6 receive token\r
    EFI_TCP6_IO_TOKEN Tcp6Tx;         ///<  TCP6 transmit token\r
    EFI_UDP4_COMPLETION_TOKEN Udp4Rx; ///<  UDP4 receive token\r
    EFI_UDP4_COMPLETION_TOKEN Udp4Tx; ///<  UDP4 transmit token\r
    EFI_UDP6_COMPLETION_TOKEN Udp6Rx; ///<  UDP6 receive token\r
    EFI_UDP6_COMPLETION_TOKEN Udp6Tx; ///<  UDP6 transmit token\r
  } Token;                            ///<  Completion token for the network operation\r
} GCC_IO_MGMT;\r
\r
/**\r
  IP4 context structure\r
\r
  The driver uses this structure to manage the IP4 connections.\r
**/\r
typedef struct {\r
  //\r
  //  IP4 context\r
  //\r
  EFI_IP4_MODE_DATA ModeData;           ///<  IP4 mode data, includes configuration data\r
  EFI_IPv4_ADDRESS DestinationAddress;  ///<  Default destination address\r
} ESL_IP4_CONTEXT;\r
\r
\r
/**\r
  TCP4 context structure\r
\r
  The driver uses this structure to manage the TCP4 connections.\r
**/\r
typedef struct {\r
  //\r
  //  TCP4 context\r
  //\r
  EFI_TCP4_CONFIG_DATA ConfigData;        ///<  TCP4 configuration data\r
  EFI_TCP4_OPTION Option;                 ///<  TCP4 port options\r
\r
  //\r
  //  Tokens\r
  //\r
  EFI_TCP4_LISTEN_TOKEN ListenToken;      ///<  Listen control\r
  EFI_TCP4_CONNECTION_TOKEN ConnectToken; ///<  Connection control\r
  EFI_TCP4_CLOSE_TOKEN CloseToken;        ///<  Close control\r
} ESL_TCP4_CONTEXT;\r
\r
/**\r
  TCP6 context structure\r
\r
  The driver uses this structure to manage the TCP6 connections.\r
**/\r
typedef struct {\r
  //\r
  //  TCP6 context\r
  //\r
  EFI_TCP6_CONFIG_DATA ConfigData;        ///<  TCP6 configuration data\r
  EFI_TCP6_OPTION Option;                 ///<  TCP6 port options\r
\r
  //\r
  //  Tokens\r
  //\r
  EFI_TCP6_LISTEN_TOKEN ListenToken;      ///<  Listen control\r
  EFI_TCP6_CONNECTION_TOKEN ConnectToken; ///<  Connection control\r
  EFI_TCP6_CLOSE_TOKEN CloseToken;        ///<  Close control\r
} ESL_TCP6_CONTEXT;\r
\r
/**\r
  UDP4 context structure\r
\r
  The driver uses this structure to manage the UDP4 connections.\r
**/\r
typedef struct {\r
  //\r
  //  UDP4 context\r
  //\r
  EFI_UDP4_CONFIG_DATA ConfigData;  ///<  UDP4 configuration data\r
} ESL_UDP4_CONTEXT;\r
\r
/**\r
  UDP6 context structure\r
\r
  The driver uses this structure to manage the UDP6 connections.\r
**/\r
typedef struct {\r
  //\r
  //  UDP6 context\r
  //\r
  EFI_UDP6_CONFIG_DATA ConfigData;  ///<  UDP6 configuration data\r
} ESL_UDP6_CONTEXT;\r
\r
\r
/**\r
  Configure the network layer.\r
\r
  @param [in] pProtocol   Protocol structure address\r
  @param [in] pConfigData Address of the confiuration data\r
\r
  @return   Returns EFI_SUCCESS if the operation is successfully\r
            started.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * PFN_NET_CONFIGURE) (\r
  IN VOID * pProtocol,\r
  IN VOID * pConfigData\r
  );\r
\r
/**\r
  Hand an I/O operation to the network layer.\r
\r
  @param [in] pProtocol   Protocol structure address\r
  @param [in] pToken      Completion token address\r
\r
  @return   Returns EFI_SUCCESS if the operation is successfully\r
            started.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * PFN_NET_IO_START) (\r
  IN VOID * pProtocol,\r
  IN VOID * pToken\r
  );\r
\r
/**\r
  Poll the LAN adapter for receive packets.\r
\r
  @param [in] pProtocol   Protocol structure address\r
  @param [in] pToken      Completion token address\r
\r
  @return   Returns EFI_SUCCESS if the operation is successfully\r
            started.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * PFN_NET_POLL) (\r
  IN VOID * pProtocol\r
  );\r
\r
/**\r
  Port control structure\r
\r
  The driver uses this structure to manager the socket's connection\r
  with the network driver.\r
**/\r
typedef struct _ESL_PORT {\r
  UINTN Signature;              ///<  Structure identification\r
\r
  //\r
  //  List links\r
  //\r
  ESL_PORT * pLinkService;      ///<  Link in service port list\r
  ESL_PORT * pLinkSocket;       ///<  Link in socket port list\r
\r
  //\r
  //  Structures\r
  //\r
  ESL_SERVICE * pService;       ///<  Service for this port\r
  ESL_SOCKET * pSocket;         ///<  Socket for this port\r
\r
  //\r
  //  Eliminate the pService references during port close\r
  //\r
  EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Service binding for network layer\r
  CONST ESL_SOCKET_BINDING * pSocketBinding;      ///<  Socket binding for network layer\r
\r
  //\r
  //  Port management\r
  //\r
  EFI_HANDLE Handle;              ///<  Network port handle\r
  PORT_STATE State;               ///<  State of the port\r
  UINTN DebugFlags;               ///<  Debug flags used to close the port\r
  BOOLEAN bCloseNow;              ///<  TRUE = Close the port immediately\r
  BOOLEAN bConfigured;            ///<  TRUE = Configure call made to network layer\r
  PFN_NET_CONFIGURE pfnConfigure; ///<  Configure the network layer\r
\r
  //\r
  //  Transmit data management\r
  //\r
  BOOLEAN bTxFlowControl;       ///<  TX flow control applied\r
  PFN_NET_IO_START pfnTxStart;  ///<  Start a transmit on the network\r
  ESL_IO_MGMT * pTxActive;      ///<  Normal data queue\r
  ESL_IO_MGMT * pTxFree;        ///<  Normal free queue\r
\r
  ESL_IO_MGMT * pTxOobActive;   ///<  Urgent data queue\r
  ESL_IO_MGMT * pTxOobFree;     ///<  Urgent free queue\r
\r
  //\r
  //  Receive data management\r
  //\r
  PFN_NET_IO_START pfnRxCancel; ///<  Cancel a receive on the network\r
  PFN_NET_POLL pfnRxPoll;       ///<  Poll the LAN adapter for receive packets\r
  PFN_NET_IO_START pfnRxStart;  ///<  Start a receive on the network\r
  ESL_IO_MGMT * pRxActive;      ///<  Active receive operation queue\r
  ESL_IO_MGMT * pRxFree;        ///<  Free structure queue\r
\r
  //\r
  //  Protocol specific management data\r
  //\r
  union {\r
    VOID * v;                   ///<  VOID pointer\r
    EFI_IP4_PROTOCOL * IPv4;    ///<  IP4 protocol pointer\r
    EFI_TCP4_PROTOCOL * TCPv4;  ///<  TCP4 protocol pointer\r
    EFI_TCP6_PROTOCOL * TCPv6;  ///<  TCP6 protocol pointer\r
    EFI_UDP4_PROTOCOL * UDPv4;  ///<  UDP4 protocol pointer\r
    EFI_UDP6_PROTOCOL * UDPv6;  ///<  UDP6 protocol pointer\r
  } pProtocol;                  ///<  Protocol structure address\r
  union {\r
    ESL_IP4_CONTEXT Ip4;        ///<  IPv4 management data\r
    ESL_TCP4_CONTEXT Tcp4;      ///<  TCPv4 management data\r
    ESL_TCP6_CONTEXT Tcp6;      ///<  TCPv6 management data\r
    ESL_UDP4_CONTEXT Udp4;      ///<  UDPv4 management data\r
    ESL_UDP6_CONTEXT Udp6;      ///<  UDPv6 management data\r
  } Context;                    ///<  Network specific context\r
}GCC_ESL_PORT;\r
\r
/**\r
  Accept a network connection.\r
\r
  @param [in] pSocket   Address of the socket structure.\r
\r
  @param [in] pSockAddr       Address of a buffer to receive the remote\r
                              network address.\r
\r
  @param [in, out] pSockAddrLength  Length in bytes of the address buffer.\r
                                    On output specifies the length of the\r
                                    remote network address.\r
\r
  @retval EFI_SUCCESS   Remote address is available\r
  @retval Others        Remote address not available\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_ACCEPT) (\r
  IN ESL_SOCKET * pSocket,\r
  IN struct sockaddr * pSockAddr,\r
  IN OUT socklen_t * pSockAddrLength\r
  );\r
\r
/**\r
  Poll for completion of the connection attempt.\r
\r
  @param [in] pSocket   Address of an ::ESL_SOCKET structure.\r
\r
  @retval EFI_SUCCESS   The connection was successfully established.\r
  @retval EFI_NOT_READY The connection is in progress, call this routine again.\r
  @retval Others        The connection attempt failed.\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_CONNECT_POLL) (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Attempt to connect to a remote TCP port\r
\r
  This routine starts the connection processing for a SOCK_STREAM\r
  or SOCK_SEQPAKCET socket using the TCP network layer.\r
\r
  This routine is called by ::EslSocketConnect to initiate the TCP\r
  network specific connect operations.\r
\r
  @param [in] pSocket   Address of an ::ESL_SOCKET structure.\r
\r
  @retval EFI_SUCCESS   The connection was successfully established.\r
  @retval EFI_NOT_READY The connection is in progress, call this routine again.\r
  @retval Others        The connection attempt failed.\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_CONNECT_START) (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Get the local socket address\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
  @param [out] pAddress   Network address to receive the local system address\r
\r
**/\r
typedef\r
VOID\r
(* PFN_API_LOCAL_ADDR_GET) (\r
  IN ESL_PORT * pPort,\r
  OUT struct sockaddr * pAddress\r
  );\r
\r
/**\r
  Set the local port address.\r
\r
  This routine sets the local port address.\r
\r
  This support routine is called by ::EslSocketPortAllocate.\r
\r
  @param [in] ppPort      Address of an ESL_PORT structure\r
  @param [in] pSockAddr   Address of a sockaddr structure that contains the\r
                          connection point on the local machine.  An IPv4 address\r
                          of INADDR_ANY specifies that the connection is made to\r
                          all of the network stacks on the platform.  Specifying a\r
                          specific IPv4 address restricts the connection to the\r
                          network stack supporting that address.  Specifying zero\r
                          for the port causes the network layer to assign a port\r
                          number from the dynamic range.  Specifying a specific\r
                          port number causes the network layer to use that port.\r
  @param [in] bBindTest   TRUE = run bind testing\r
\r
  @retval EFI_SUCCESS     The operation was successful\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_LOCAL_ADDR_SET) (\r
  IN ESL_PORT * pPort,\r
  IN CONST struct sockaddr * pSockAddr,\r
  IN BOOLEAN bBindTest\r
  );\r
\r
/**\r
  Process the completion event\r
\r
  This routine handles the I/O completion event.\r
\r
  This routine is called by the low level network driver when\r
  the operation is completed.\r
\r
  @param [in] Event     The receive completion event\r
\r
  @param [in] pIo       The address of an ::ESL_IO_MGMT structure\r
\r
**/\r
typedef\r
VOID\r
(* PFN_API_IO_COMPLETE) (\r
  IN EFI_EVENT Event,\r
  IN ESL_IO_MGMT * pIo\r
  );\r
\r
/**\r
  Determine if the socket is configured.\r
\r
\r
  @param [in] pSocket         Address of a ESL_SOCKET structure\r
  \r
  @retval EFI_SUCCESS - The port is connected\r
  @retval EFI_NOT_STARTED - The port is not connected\r
\r
 **/\r
 typedef\r
 EFI_STATUS\r
 (* PFN_API_IS_CONFIGURED) (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Establish the known port to listen for network connections.\r
\r
  @param [in] pSocket     Address of the socket structure.\r
\r
  @retval EFI_SUCCESS - Socket successfully created\r
  @retval Other - Failed to enable the socket for listen\r
\r
**/\r
typedef\r
EFI_STATUS\r
(* PFN_API_LISTEN) (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Get the option value\r
\r
  Retrieve the protocol options one at a time by name.\r
\r
  @param [in] pSocket           Address of a ESL_SOCKET structure\r
  @param [in] OptionName        Name of the option\r
  @param [out] ppOptionData     Buffer to receive address of option value\r
  @param [out] pOptionLength    Buffer to receive the option length\r
\r
  @retval EFI_SUCCESS - Socket data successfully received\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_OPTION_GET) (\r
  IN ESL_SOCKET * pSocket,\r
  IN int OptionName,\r
  OUT CONST void ** __restrict ppOptionData,\r
  OUT socklen_t * __restrict pOptionLength\r
  );\r
\r
/**\r
  Set the option value\r
\r
  Adjust the protocol options one at a time by name.\r
\r
  @param [in] pSocket         Address of a ESL_SOCKET structure\r
  @param [in] OptionName      Name of the option\r
  @param [in] pOptionValue    Buffer containing the option value\r
  @param [in] OptionLength    Length of the buffer in bytes\r
\r
  @retval EFI_SUCCESS - Option successfully set\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_OPTION_SET) (\r
  IN ESL_SOCKET * pSocket,\r
  IN int OptionName,\r
  IN CONST void * pOptionValue,\r
  IN socklen_t OptionLength\r
  );\r
\r
/**\r
  Free a receive packet\r
\r
  This routine performs the network specific operations necessary\r
  to free a receive packet.\r
\r
  This routine is called by ::EslSocketPortCloseTxDone to free a\r
  receive packet.\r
\r
  @param [in] pPacket         Address of an ::ESL_PACKET structure.\r
  @param [in, out] pRxBytes   Address of the count of RX bytes\r
\r
**/\r
typedef\r
VOID\r
(* PFN_API_PACKET_FREE) (\r
  IN ESL_PACKET * pPacket,\r
  IN OUT size_t * pRxBytes\r
  );\r
\r
/**\r
  Initialize the network specific portions of an ::ESL_PORT structure.\r
\r
  This routine initializes the network specific portions of an\r
  ::ESL_PORT structure for use by the socket.\r
\r
  This support routine is called by ::EslSocketPortAllocate\r
  to connect the socket with the underlying network adapter\r
  running the IPv4 protocol.\r
\r
  @param [in] ppPort      Address of an ESL_PORT structure\r
  @param [in] DebugFlags  Flags for debug messages\r
\r
  @retval EFI_SUCCESS - Socket successfully created\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_PORT_ALLOC) (\r
  IN ESL_PORT * pPort,\r
  IN UINTN DebugFlags\r
  );\r
\r
/**\r
  Close a network specific port.\r
\r
  This routine releases the resources allocated by the\r
  network specific PortAllocate routine.\r
\r
  This routine is called by ::EslSocketPortCloseRxDone as\r
  the last step of closing processing.\r
  See the \ref PortCloseStateMachine section.\r
  \r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
  @retval EFI_SUCCESS     The port is closed\r
  @retval other           Port close error\r
\r
**/\r
typedef\r
EFI_STATUS\r
(* PFN_API_PORT_CLOSE) (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Perform the network specific close operation on the port.\r
\r
  This routine performs the network specific operation to\r
  shutdown receive operations on the port.\r
\r
  This routine is called by the ::EslSocketPortCloseTxDone\r
  routine after the port completes all of the transmission.\r
\r
  @param [in] pPort           Address of an ::ESL_PORT structure.\r
\r
  @retval EFI_SUCCESS         The port is closed, not normally returned\r
  @retval EFI_NOT_READY       The port is still closing\r
  @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,\r
                              most likely the routine was called already.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(* PFN_API_PORT_CLOSE_OP) (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Receive data from a network connection.\r
\r
  This routine attempts to return buffered data to the caller.  The\r
  data is removed from the urgent queue if the message flag MSG_OOB\r
  is specified, otherwise data is removed from the normal queue.\r
  See the \ref ReceiveEngine section.\r
\r
  This routine is called by ::EslSocketReceive to handle the network\r
  specific receive operation.\r
\r
  @param [in] pPort           Address of an ::ESL_PORT structure.\r
\r
  @param [in] pPacket         Address of an ::ESL_PACKET structure.\r
  \r
  @param [in] pbConsumePacket Address of a BOOLEAN indicating if the packet is to be consumed\r
  \r
  @param [in] BufferLength    Length of the the buffer\r
  \r
  @param [in] pBuffer         Address of a buffer to receive the data.\r
  \r
  @param [in] pDataLength     Number of received data bytes in the buffer.\r
\r
  @param [out] pAddress       Network address to receive the remote system address\r
\r
  @param [out] pSkipBytes     Address to receive the number of bytes skipped\r
\r
  @return   Returns the address of the next free byte in the buffer.\r
\r
 **/\r
typedef\r
UINT8 *\r
(* PFN_API_RECEIVE) (\r
  IN ESL_PORT * pPort,\r
  IN ESL_PACKET * pPacket,\r
  IN BOOLEAN * pbConsumePacket,\r
  IN size_t BufferLength,\r
  IN UINT8 * pBuffer,\r
  OUT size_t * pDataLength,\r
  OUT struct sockaddr * pAddress,\r
  OUT size_t * pSkipBytes\r
  );\r
\r
/**\r
  Get the remote socket address\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
  @param [out] pAddress   Network address to receive the remote system address\r
\r
**/\r
typedef\r
VOID\r
(* PFN_API_REMOTE_ADDR_GET) (\r
  IN ESL_PORT * pPort,\r
  OUT struct sockaddr * pAddress\r
  );\r
\r
/**\r
  Set the remote address\r
\r
  This routine sets the remote address in the port.\r
\r
  This routine is called by ::EslSocketConnect to specify the\r
  remote network address.\r
\r
  @param [in] pPort           Address of an ::ESL_PORT structure.\r
\r
  @param [in] pSockAddr       Network address of the remote system.\r
\r
  @param [in] SockAddrLength  Length in bytes of the network address.\r
\r
  @retval EFI_SUCCESS     The operation was successful\r
\r
 **/\r
typedef\r
EFI_STATUS\r
(* PFN_API_REMOTE_ADDR_SET) (\r
  IN ESL_PORT * pPort,\r
  IN CONST struct sockaddr * pSockAddr,\r
  IN socklen_t SockAddrLength\r
  );\r
\r
/**\r
  Start a receive operation\r
\r
  This routine prepares a packet for the receive operation.\r
  See the \ref ReceiveEngine section.\r
\r
  This support routine is called by EslSocketRxStart.\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
  @param [in] pIo         Address of an ::ESL_IO_MGMT structure.\r
\r
 **/\r
typedef\r
VOID\r
(* PFN_API_RX_START) (\r
  IN ESL_PORT * pPort,\r
  IN ESL_IO_MGMT * pIo\r
  );\r
\r
/**\r
  Buffer data for transmission over a network connection.\r
\r
  @param [in] pSocket         Address of a ESL_SOCKET structure\r
\r
  @param [in] Flags           Message control flags\r
\r
  @param [in] BufferLength    Length of the the buffer\r
\r
  @param [in] pBuffer         Address of a buffer to receive the data.\r
\r
  @param [in] pDataLength     Number of received data bytes in the buffer.\r
\r
  @param [in] pAddress        Network address of the remote system address\r
\r
  @param [in] AddressLength   Length of the remote network address structure\r
\r
  @retval EFI_SUCCESS - Socket data successfully buffered\r
\r
**/\r
typedef\r
EFI_STATUS\r
(* PFN_API_TRANSMIT) (\r
  IN ESL_SOCKET * pSocket,\r
  IN int Flags,\r
  IN size_t BufferLength,\r
  IN CONST UINT8 * pBuffer,\r
  OUT size_t * pDataLength,\r
  IN const struct sockaddr * pAddress,\r
  IN socklen_t AddressLength\r
  );\r
\r
/**\r
  Process the transmit completion\r
\r
  This routine calls ::EslSocketTxComplete to handle the\r
  transmit completion.\r
\r
  This routine is called by the network layers upon the completion\r
  of a transmit operation.\r
\r
  @param [in] Event     The urgent transmit completion event\r
\r
  @param [in] pIo       The ESL_IO_MGMT structure address\r
\r
**/\r
typedef\r
VOID\r
(* PFN_API_TX_COMPLETE) (\r
  IN EFI_EVENT Event,\r
  IN ESL_IO_MGMT * pIo\r
  );\r
\r
/**\r
  Socket type control structure\r
\r
  This driver uses this structure to define the API for the socket type.\r
**/\r
typedef struct {\r
  CONST CHAR8 * pName;                      ///<  Protocol name\r
  int DefaultProtocol;                      ///<  Default protocol\r
  UINTN ConfigDataOffset;                   ///<  Offset in ::ESL_PORT to the configuration data\r
  UINTN ServiceListOffset;                  ///<  Offset in ::ESL_LAYER for the list of services\r
  socklen_t MinimumAddressLength;           ///<  Minimum address length in bytes\r
  socklen_t AddressLength;                  ///<  Address length in bytes\r
  sa_family_t AddressFamily;                ///<  Address family\r
  UINTN RxPacketBytes;                      ///<  Length of the RX packet allocation\r
  UINTN RxZeroBytes;                        ///<  Number of bytes to zero in RX packet\r
  UINTN RxBufferOffset;                     ///<  Offset of buffer address in ESL_IO_MGMT structure\r
  BOOLEAN bOobSupported;                    ///<  TRUE if out-of-band messages are supported\r
  int BindTestErrno;                        ///<  errno value if EslSocketBindTest fails\r
  PFN_API_ACCEPT pfnAccept;                 ///<  Accept a network connection\r
  PFN_API_CONNECT_POLL pfnConnectPoll;      ///<  Poll for connection complete\r
  PFN_API_CONNECT_START pfnConnectStart;    ///<  Start the connection to a remote system\r
  PFN_API_IS_CONFIGURED pfnIsConfigured;    ///<  Determine if the socket is configured\r
  PFN_API_LOCAL_ADDR_GET pfnLocalAddrGet;   ///<  Get the local address\r
  PFN_API_LOCAL_ADDR_SET pfnLocalAddrSet;   ///<  Set the local address\r
  PFN_API_LISTEN pfnListen;                 ///<  Listen for connections on known server port\r
  PFN_API_OPTION_GET pfnOptionGet;          ///<  Get the option value\r
  PFN_API_OPTION_SET pfnOptionSet;          ///<  Set the option value\r
  PFN_API_PACKET_FREE pfnPacketFree;        ///<  Free the receive packet\r
  PFN_API_PORT_ALLOC pfnPortAllocate;       ///<  Allocate the network specific resources for the port\r
  PFN_API_PORT_CLOSE pfnPortClose;          ///<  Close the network specific resources for the port\r
  PFN_API_PORT_CLOSE_OP pfnPortCloseOp;     ///<  Perform the close operation on the port\r
  BOOLEAN bPortCloseComplete;               ///<  TRUE = Close is complete after close operation\r
  PFN_API_RECEIVE pfnReceive;               ///<  Attempt to receive some data\r
  PFN_API_REMOTE_ADDR_GET pfnRemoteAddrGet; ///<  Get remote address\r
  PFN_API_REMOTE_ADDR_SET pfnRemoteAddrSet; ///<  Set the remote system address\r
  PFN_API_IO_COMPLETE pfnRxComplete;        ///<  RX completion\r
  PFN_API_RX_START pfnRxStart;              ///<  Start a network specific receive operation\r
  PFN_API_TRANSMIT pfnTransmit;             ///<  Attempt to buffer a packet for transmit\r
  PFN_API_TX_COMPLETE pfnTxComplete;        ///<  TX completion for normal data\r
  PFN_API_TX_COMPLETE pfnTxOobComplete;     ///<  TX completion for urgent data\r
} ESL_PROTOCOL_API;\r
\r
\r
/**\r
  Socket control structure\r
\r
  The driver uses this structure to manage the socket.\r
**/\r
typedef struct _ESL_SOCKET {\r
  UINTN Signature;          ///<  Structure identification\r
\r
  //\r
  //  Protocol binding\r
  //\r
  EFI_SOCKET_PROTOCOL SocketProtocol; ///<  Socket protocol declaration\r
  CONST ESL_PROTOCOL_API * pApi;      ///<  API for the protocol\r
\r
  //\r
  //  Socket management\r
  //\r
  ESL_SOCKET * pNext;           ///<  Next socket in the list of sockets\r
  int errno;                    ///<  Error information for this socket\r
  EFI_STATUS Status;            ///<  Asyncronous error information for this socket\r
  SOCKET_STATE State;           ///<  Socket state\r
  UINT32 DebugFlags;            ///<  Debug flags\r
\r
  //\r
  //  Socket options\r
  //\r
  BOOLEAN bIncludeHeader;       ///<  TRUE if including the IP header\r
  BOOLEAN bListenCalled;        ///<  TRUE if listen was successfully called\r
  BOOLEAN bOobInLine;           ///<  TRUE if out-of-band messages are to be received inline with normal data\r
  BOOLEAN bReUseAddr;           ///<  TRUE if using same address is allowed\r
\r
  //\r
  //  Socket data\r
  //\r
  int Domain;                   ///<  Specifies family of protocols\r
  int Type;                     ///<  Specifies how to make network connection\r
  int Protocol;                 ///<  Specifies lower layer protocol to use\r
  BOOLEAN bAddressSet;          ///<  Set when the address is specified\r
  BOOLEAN bConfigured;          ///<  Set after the socket is configured\r
\r
  BOOLEAN bRxDisable;           ///<  Receive disabled via shutdown\r
  size_t RxBytes;               ///<  Total Rx bytes\r
  size_t RxOobBytes;            ///<  Urgent Rx bytes\r
  EFI_STATUS RxError;           ///<  Error during receive\r
\r
  BOOLEAN bTxDisable;           ///<  Transmit disabled via shutdown\r
  size_t TxBytes;               ///<  Normal Tx bytes\r
  size_t TxOobBytes;            ///<  Urgent Tx bytes\r
  EFI_STATUS TxError;           ///<  Error during transmit\r
\r
  //\r
  //  Pending connection data\r
  //\r
  BOOLEAN bConnected;           ///<  Set when connected, cleared by poll\r
  EFI_STATUS ConnectStatus;     ///<  Connection status\r
  UINTN MaxFifoDepth;           ///<  Maximum FIFO depth\r
  UINTN FifoDepth;              ///<  Number of sockets in the FIFO\r
  ESL_SOCKET * pFifoHead;       ///<  Head of the FIFO\r
  ESL_SOCKET * pFifoTail;       ///<  Tail of the FIFO\r
  ESL_SOCKET * pNextConnection; ///<  Link in the FIFO\r
\r
  //\r
  //  Network use\r
  //\r
  ESL_PORT * pPortList;         ///<  List of ports managed by this socket\r
  EFI_EVENT WaitAccept;         ///<  Wait for accept completion\r
\r
  //\r
  //  Receive data management\r
  //\r
  UINT32 MaxRxBuf;                  ///<  Maximum size of the receive buffer\r
  struct timeval RxTimeout;         ///<  Receive timeout\r
  ESL_PACKET * pRxFree;             ///<  Free packet list\r
  ESL_PACKET * pRxOobPacketListHead;///<  Urgent data list head\r
  ESL_PACKET * pRxOobPacketListTail;///<  Urgent data list tail\r
  ESL_PACKET * pRxPacketListHead;   ///<  Normal data list head\r
  ESL_PACKET * pRxPacketListTail;   ///<  Normal data list tail\r
\r
  //\r
  //  Transmit data management\r
  //\r
  UINTN TxPacketOffset;             ///<  Offset for data pointer in ::ESL_PACKET\r
  UINTN TxTokenEventOffset;         ///<  Offset to the Event in the TX token\r
  UINTN TxTokenOffset;              ///<  Offset for data pointer in TX token\r
  UINT32 MaxTxBuf;                  ///<  Maximum size of the transmit buffer\r
  ESL_PACKET * pTxOobPacketListHead;///<  Urgent data list head\r
  ESL_PACKET * pTxOobPacketListTail;///<  Urgent data list tail\r
  ESL_PACKET * pTxPacketListHead;   ///<  Normal data list head\r
  ESL_PACKET * pTxPacketListTail;   ///<  Normal data list tail\r
}GCC_ESL_SOCKET;\r
\r
#define SOCKET_FROM_PROTOCOL(a)  CR (a, ESL_SOCKET, SocketProtocol, SOCKET_SIGNATURE)  ///< Locate ESL_SOCKET from protocol\r
\r
/**\r
  Socket layer control structure\r
\r
  The driver uses this structure to manage the driver.\r
**/\r
typedef struct {\r
  UINTN Signature;              ///<  Structure identification\r
\r
  //\r
  //  Service binding interface\r
  //\r
  CONST EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///<  Driver's binding\r
\r
  //\r
  //  Image data\r
  //\r
  EFI_HANDLE ImageHandle;       ///<  Image handle\r
\r
  //\r
  //  Network services\r
  //\r
  ESL_SERVICE * pIp4List;       ///<  List of Ip4 services\r
  ESL_SERVICE * pTcp4List;      ///<  List of Tcp4 services\r
  ESL_SERVICE * pTcp6List;      ///<  List of Tcp6 services\r
  ESL_SERVICE * pUdp4List;      ///<  List of Udp4 services\r
  ESL_SERVICE * pUdp6List;      ///<  List of Udp6 services\r
\r
  //\r
  //  Socket management\r
  //\r
  ESL_SOCKET * pSocketList;     ///<  List of sockets\r
} ESL_LAYER;\r
\r
#define LAYER_FROM_SERVICE(a) CR (a, ESL_LAYER, ServiceBinding, LAYER_SIGNATURE) ///< Locate ESL_LAYER from service binding\r
\r
//------------------------------------------------------------------------------\r
// Data\r
//------------------------------------------------------------------------------\r
\r
extern ESL_LAYER mEslLayer;\r
\r
extern CONST ESL_PROTOCOL_API cEslIp4Api;\r
extern CONST ESL_PROTOCOL_API cEslIp6Api;\r
extern CONST ESL_PROTOCOL_API cEslTcp4Api;\r
extern CONST ESL_PROTOCOL_API cEslTcp6Api;\r
extern CONST ESL_PROTOCOL_API cEslUdp4Api;\r
extern CONST ESL_PROTOCOL_API cEslUdp6Api;\r
\r
extern CONST EFI_SERVICE_BINDING_PROTOCOL mEfiServiceBinding;\r
\r
//------------------------------------------------------------------------------\r
// Socket Support Routines\r
//------------------------------------------------------------------------------\r
\r
/**\r
  Allocate and initialize a ESL_SOCKET structure.\r
  \r
  This support function allocates an ::ESL_SOCKET structure\r
  and installs a protocol on ChildHandle.  If pChildHandle is a\r
  pointer to NULL, then a new handle is created and returned in\r
  pChildHandle.  If pChildHandle is not a pointer to NULL, then\r
  the protocol installs on the existing pChildHandle.\r
\r
  @param [in, out] pChildHandle Pointer to the handle of the child to create.\r
                                If it is NULL, then a new handle is created.\r
                                If it is a pointer to an existing UEFI handle, \r
                                then the protocol is added to the existing UEFI\r
                                handle.\r
  @param [in] DebugFlags        Flags for debug messages\r
  @param [in, out] ppSocket     The buffer to receive an ::ESL_SOCKET structure address.\r
\r
  @retval EFI_SUCCESS           The protocol was added to ChildHandle.\r
  @retval EFI_INVALID_PARAMETER ChildHandle is NULL.\r
  @retval EFI_OUT_OF_RESOURCES  There are not enough resources available to create\r
                                the child\r
  @retval other                 The child handle was not created\r
  \r
**/\r
EFI_STATUS\r
EFIAPI\r
EslSocketAllocate (\r
  IN OUT EFI_HANDLE * pChildHandle,\r
  IN     UINTN DebugFlags,\r
  IN OUT ESL_SOCKET ** ppSocket\r
  );\r
\r
/**\r
  Test the bind configuration.\r
\r
  @param [in] pPort       Address of the ::ESL_PORT structure.\r
  @param [in] ErrnoValue  errno value if test fails\r
\r
  @retval EFI_SUCCESS   The connection was successfully established.\r
  @retval Others        The connection attempt failed.\r
\r
 **/\r
EFI_STATUS\r
EslSocketBindTest (\r
  IN ESL_PORT * pPort,\r
  IN int ErrnoValue\r
  );\r
\r
/**\r
  Copy a fragmented buffer into a destination buffer.\r
\r
  This support routine copies a fragmented buffer to the caller specified buffer.\r
\r
  This routine is called by ::EslIp4Receive and ::EslUdp4Receive.\r
\r
  @param [in] FragmentCount   Number of fragments in the table\r
\r
  @param [in] pFragmentTable  Address of an EFI_IP4_FRAGMENT_DATA structure\r
\r
  @param [in] BufferLength    Length of the the buffer\r
\r
  @param [in] pBuffer         Address of a buffer to receive the data.\r
\r
  @param [in] pDataLength     Number of received data bytes in the buffer.\r
\r
  @return   Returns the address of the next free byte in the buffer.\r
\r
**/\r
UINT8 *\r
EslSocketCopyFragmentedBuffer (\r
  IN UINT32 FragmentCount,\r
  IN EFI_IP4_FRAGMENT_DATA * pFragmentTable,\r
  IN size_t BufferLength,\r
  IN UINT8 * pBuffer,\r
  OUT size_t * pDataLength\r
  );\r
\r
/**\r
  Free the socket.\r
\r
  This routine frees the socket structure and handle resources.\r
\r
  The ::close routine calls EslServiceFreeProtocol which then calls\r
  this routine to free the socket context structure and close the\r
  handle.\r
\r
  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.\r
  \r
  @param [out] pErrno         Address to receive the errno value upon completion.\r
\r
  @retval EFI_SUCCESS   The socket resources were returned successfully.\r
\r
 **/\r
EFI_STATUS\r
EslSocketFree (\r
  IN EFI_SOCKET_PROTOCOL * pSocketProtocol,\r
  IN int * pErrno\r
  );\r
\r
/**\r
  Free the ESL_IO_MGMT event and structure\r
\r
  This support routine walks the free list to close the event in\r
  the ESL_IO_MGMT structure and remove the structure from the free\r
  list.\r
\r
  See the \ref TransmitEngine section.\r
\r
  @param [in] pPort         Address of an ::ESL_PORT structure\r
  @param [in] ppFreeQueue   Address of the free queue head\r
  @param [in] DebugFlags    Flags for debug messages\r
  @param [in] pEventName    Zero terminated string containing the event name\r
\r
  @retval EFI_SUCCESS - The structures were properly initialized\r
\r
**/\r
EFI_STATUS\r
EslSocketIoFree (\r
  IN ESL_PORT * pPort,\r
  IN ESL_IO_MGMT ** ppFreeQueue,\r
  IN UINTN DebugFlags,\r
  IN CHAR8 * pEventName\r
  );\r
\r
/**\r
  Initialize the ESL_IO_MGMT structures\r
\r
  This support routine initializes the ESL_IO_MGMT structure and\r
  places them on to a free list.\r
\r
  This routine is called by the PortAllocate routines to prepare\r
  the transmit engines.  See the \ref TransmitEngine section.\r
\r
  @param [in] pPort         Address of an ::ESL_PORT structure\r
  @param [in, out] ppIo     Address containing the first structure address.  Upon\r
                            return this buffer contains the next structure address.\r
  @param [in] TokenCount    Number of structures to initialize\r
  @param [in] ppFreeQueue   Address of the free queue head\r
  @param [in] DebugFlags    Flags for debug messages\r
  @param [in] pEventName    Zero terminated string containing the event name\r
  @param [in] pfnCompletion Completion routine address\r
\r
  @retval EFI_SUCCESS - The structures were properly initialized\r
\r
**/\r
EFI_STATUS\r
EslSocketIoInit (\r
  IN ESL_PORT * pPort,\r
  IN ESL_IO_MGMT ** ppIo,\r
  IN UINTN TokenCount,\r
  IN ESL_IO_MGMT ** ppFreeQueue,\r
  IN UINTN DebugFlags,\r
  IN CHAR8 * pEventName,\r
  IN PFN_API_IO_COMPLETE pfnCompletion\r
  );\r
\r
/**\r
  Determine if the socket is configured\r
\r
  This support routine is called to determine if the socket if the\r
  configuration call was made to the network layer.  The following\r
  routines call this routine to verify that they may be successful\r
  in their operations:\r
  <ul>\r
    <li>::EslSocketGetLocalAddress</li>\r
    <li>::EslSocketGetPeerAddress</li>\r
    <li>::EslSocketPoll</li>\r
    <li>::EslSocketReceive</li>\r
    <li>::EslSocketTransmit</li>\r
  </ul>\r
\r
  @param [in] pSocket       Address of an ::ESL_SOCKET structure\r
\r
  @retval EFI_SUCCESS - The socket is configured\r
\r
**/\r
EFI_STATUS\r
EslSocketIsConfigured (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Allocate a packet for a receive or transmit operation\r
\r
  This support routine is called by ::EslSocketRxStart and the\r
  network specific TxBuffer routines to get buffer space for the\r
  next operation.\r
\r
  @param [in] ppPacket      Address to receive the ::ESL_PACKET structure\r
  @param [in] LengthInBytes Length of the packet structure\r
  @param [in] ZeroBytes     Length of packet to zero\r
  @param [in] DebugFlags    Flags for debug messages\r
\r
  @retval EFI_SUCCESS - The packet was allocated successfully\r
\r
 **/\r
EFI_STATUS\r
EslSocketPacketAllocate (\r
  IN ESL_PACKET ** ppPacket,\r
  IN size_t LengthInBytes,\r
  IN size_t ZeroBytes,\r
  IN UINTN DebugFlags\r
  );\r
\r
/**\r
  Free a packet used for receive or transmit operation\r
\r
  This support routine is called by the network specific Close\r
  and TxComplete routines and during error cases in RxComplete\r
  and TxBuffer.  Note that the network layers typically place\r
  receive packets on the ESL_SOCKET::pRxFree list for reuse.\r
\r
  @param [in] pPacket     Address of an ::ESL_PACKET structure\r
  @param [in] DebugFlags  Flags for debug messages\r
\r
  @retval EFI_SUCCESS - The packet was allocated successfully\r
\r
 **/\r
EFI_STATUS\r
EslSocketPacketFree (\r
  IN ESL_PACKET * pPacket,\r
  IN UINTN DebugFlags\r
  );\r
\r
/**\r
  Allocate and initialize a ESL_PORT structure.\r
\r
  This routine initializes an ::ESL_PORT structure for use by\r
  the socket.  This routine calls a routine via\r
  ESL_PROTOCOL_API::pfnPortAllocate to initialize the network\r
  specific resources.  The resources are released later by the\r
  \ref PortCloseStateMachine.\r
\r
  This support routine is called by ::EslSocketBind and\r
  ::EslTcp4ListenComplete to connect the socket with the\r
  underlying network adapter to the socket.\r
\r
  @param [in] pSocket     Address of an ::ESL_SOCKET structure.\r
  @param [in] pService    Address of an ::ESL_SERVICE structure.\r
  @param [in] ChildHandle TCP4 child handle\r
  @param [in] pSockAddr   Address of a sockaddr structure that contains the\r
                          connection point on the local machine.  An IPv4 address\r
                          of INADDR_ANY specifies that the connection is made to\r
                          all of the network stacks on the platform.  Specifying a\r
                          specific IPv4 address restricts the connection to the\r
                          network stack supporting that address.  Specifying zero\r
                          for the port causes the network layer to assign a port\r
                          number from the dynamic range.  Specifying a specific\r
                          port number causes the network layer to use that port.\r
  @param [in] bBindTest   TRUE if EslSocketBindTest should be called\r
  @param [in] DebugFlags  Flags for debug messages\r
  @param [out] ppPort     Buffer to receive new ::ESL_PORT structure address\r
\r
  @retval EFI_SUCCESS - Socket successfully created\r
\r
 **/\r
EFI_STATUS\r
EslSocketPortAllocate (\r
  IN ESL_SOCKET * pSocket,\r
  IN ESL_SERVICE * pService,\r
  IN EFI_HANDLE ChildHandle,\r
  IN CONST struct sockaddr * pSockAddr,\r
  IN BOOLEAN bBindTest,\r
  IN UINTN DebugFlags,\r
  OUT ESL_PORT ** ppPort\r
  );\r
\r
/**\r
  Close a port.\r
\r
  This routine releases the resources allocated by ::EslSocketPortAllocate.\r
  This routine calls ESL_PROTOCOL_API::pfnPortClose to release the network\r
  specific resources.\r
\r
  This routine is called by:\r
  <ul>\r
    <li>::EslIp4PortAllocate - Port initialization failure</li>\r
    <li>::EslSocketPortCloseRxDone - Last step of close processing</li>\r
    <li>::EslTcp4ConnectComplete - Connection failure and reducint the port list to a single port</li>\r
    <li>::EslTcp4PortAllocate - Port initialization failure</li>\r
    <li>::EslUdp4PortAllocate - Port initialization failure</li>\r
  </ul>\r
  See the \ref PortCloseStateMachine section.\r
  \r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
  @retval EFI_SUCCESS     The port is closed\r
  @retval other           Port close error\r
\r
**/\r
EFI_STATUS\r
EslSocketPortClose (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Process the port close completion event\r
\r
  This routine attempts to complete the port close operation.\r
\r
  This routine is called by the TCP layer upon completion of\r
  the close operation.\r
  See the \ref PortCloseStateMachine section.\r
\r
  @param [in] Event     The close completion event\r
\r
  @param [in] pPort     Address of an ::ESL_PORT structure.\r
\r
**/\r
VOID\r
EslSocketPortCloseComplete (\r
  IN EFI_EVENT Event,\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Port close state 3\r
\r
  This routine determines the state of the receive operations and\r
  continues the close operation after the pending receive operations\r
  are cancelled.\r
\r
  This routine is called by\r
  <ul>\r
    <li>::EslIp4RxComplete</li>\r
    <li>::EslSocketPortCloseComplete</li>\r
    <li>::EslSocketPortCloseTxDone</li>\r
    <li>::EslUdp4RxComplete</li>\r
  </ul>\r
  to determine the state of the receive operations.\r
  See the \ref PortCloseStateMachine section.\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
  @retval EFI_SUCCESS         The port is closed\r
  @retval EFI_NOT_READY       The port is still closing\r
  @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,\r
                              most likely the routine was called already.\r
\r
**/\r
EFI_STATUS\r
EslSocketPortCloseRxDone (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Start the close operation on a port, state 1.\r
\r
  This routine marks the port as closed and initiates the \ref\r
  PortCloseStateMachine. The first step is to allow the \ref\r
  TransmitEngine to run down.\r
\r
  This routine is called by ::EslSocketCloseStart to initiate the socket\r
  network specific close operation on the socket.\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
  @param [in] bCloseNow   Set TRUE to abort active transfers\r
  @param [in] DebugFlags  Flags for debug messages\r
\r
  @retval EFI_SUCCESS         The port is closed, not normally returned\r
  @retval EFI_NOT_READY       The port has started the closing process\r
  @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,\r
                              most likely the routine was called already.\r
\r
**/\r
EFI_STATUS\r
EslSocketPortCloseStart (\r
  IN ESL_PORT * pPort,\r
  IN BOOLEAN bCloseNow,\r
  IN UINTN DebugFlags\r
  );\r
\r
/**\r
  Port close state 2\r
\r
  This routine determines the state of the transmit engine and\r
  continue the close operation after the transmission is complete.\r
  The next step is to stop the \ref ReceiveEngine.\r
  See the \ref PortCloseStateMachine section.\r
\r
  This routine is called by ::EslSocketPortCloseStart to determine\r
  if the transmission is complete.\r
\r
  @param [in] pPort           Address of an ::ESL_PORT structure.\r
\r
  @retval EFI_SUCCESS         The port is closed, not normally returned\r
  @retval EFI_NOT_READY       The port is still closing\r
  @retval EFI_ALREADY_STARTED Error, the port is in the wrong state,\r
                              most likely the routine was called already.\r
\r
**/\r
EFI_STATUS\r
EslSocketPortCloseTxDone (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Cancel the receive operations\r
\r
  This routine cancels a pending receive operation.\r
  See the \ref ReceiveEngine section.\r
\r
  This routine is called by ::EslSocketShutdown when the socket\r
  layer is being shutdown.\r
\r
  @param [in] pPort     Address of an ::ESL_PORT structure\r
  @param [in] pIo       Address of an ::ESL_IO_MGMT structure\r
\r
 **/\r
VOID\r
EslSocketRxCancel (\r
  IN ESL_PORT * pPort,\r
  IN ESL_IO_MGMT * pIo\r
  );\r
\r
/**\r
  Process the receive completion\r
\r
  This routine queues the data in FIFO order in either the urgent\r
  or normal data queues depending upon the type of data received.\r
  See the \ref ReceiveEngine section.\r
\r
  This routine is called when some data is received by:\r
  <ul>\r
    <li>::EslIp4RxComplete</li>\r
    <li>::EslTcp4RxComplete</li>\r
    <li>::EslUdp4RxComplete</li>\r
  </ul>\r
\r
  @param [in] pIo           Address of an ::ESL_IO_MGMT structure\r
  @param [in] Status        Receive status\r
  @param [in] LengthInBytes Length of the receive data\r
  @param [in] bUrgent       TRUE if urgent data is received and FALSE\r
                            for normal data.\r
\r
**/\r
VOID\r
EslSocketRxComplete (\r
  IN ESL_IO_MGMT * pIo,\r
  IN EFI_STATUS Status,\r
  IN UINTN LengthInBytes,\r
  IN BOOLEAN bUrgent\r
  );\r
\r
/**\r
  Poll a socket for pending receive activity.\r
\r
  This routine is called at elivated TPL and extends the idle\r
  loop which polls a socket down into the LAN driver layer to\r
  determine if there is any receive activity.\r
\r
  The ::EslSocketPoll, ::EslSocketReceive and ::EslSocketTransmit\r
  routines call this routine when there is nothing to do.\r
\r
  @param [in] pSocket   Address of an ::EFI_SOCKET structure.\r
\r
 **/\r
VOID\r
EslSocketRxPoll (\r
  IN ESL_SOCKET * pSocket\r
  );\r
\r
/**\r
  Start a receive operation\r
\r
  This routine posts a receive buffer to the network adapter.\r
  See the \ref ReceiveEngine section.\r
\r
  This support routine is called by:\r
  <ul>\r
    <li>::EslIp4Receive to restart the receive engine to release flow control.</li>\r
    <li>::EslIp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>\r
    <li>::EslIp4SocketIsConfigured to start the recevie engine for the new socket.</li>\r
    <li>::EslTcp4ListenComplete to start the recevie engine for the new socket.</li>\r
    <li>::EslTcp4Receive to restart the receive engine to release flow control.</li>\r
    <li>::EslTcp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>\r
    <li>::EslUdp4Receive to restart the receive engine to release flow control.</li>\r
    <li>::EslUdp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li>\r
    <li>::EslUdp4SocketIsConfigured to start the recevie engine for the new socket.</li>\r
  </ul>\r
\r
  @param [in] pPort       Address of an ::ESL_PORT structure.\r
\r
 **/\r
VOID\r
EslSocketRxStart (\r
  IN ESL_PORT * pPort\r
  );\r
\r
/**\r
  Complete the transmit operation\r
\r
  This support routine handles the transmit completion processing for\r
  the various network layers.  It frees the ::ESL_IO_MGMT structure\r
  and and frees packet resources by calling ::EslSocketPacketFree.\r
  Transmit errors are logged in ESL_SOCKET::TxError.\r
  See the \ref TransmitEngine section.\r
\r
  This routine is called by:\r
  <ul>\r
    <li>::EslIp4TxComplete</li>\r
    <li>::EslTcp4TxComplete</li>\r
    <li>::EslTcp4TxOobComplete</li>\r
    <li>::EslUdp4TxComplete</li>\r
  </ul>\r
\r
  @param [in] pIo             Address of an ::ESL_IO_MGMT structure\r
  @param [in] LengthInBytes   Length of the data in bytes\r
  @param [in] Status          Transmit operation status\r
  @param [in] pQueueType      Zero terminated string describing queue type\r
  @param [in] ppQueueHead     Transmit queue head address\r
  @param [in] ppQueueTail     Transmit queue tail address\r
  @param [in] ppActive        Active transmit queue address\r
  @param [in] ppFree          Free transmit queue address\r
\r
 **/\r
VOID\r
EslSocketTxComplete (\r
  IN ESL_IO_MGMT * pIo,\r
  IN UINT32 LengthInBytes,\r
  IN EFI_STATUS Status,\r
  IN CONST CHAR8 * pQueueType,\r
  IN ESL_PACKET ** ppQueueHead,\r
  IN ESL_PACKET ** ppQueueTail,\r
  IN ESL_IO_MGMT ** ppActive,\r
  IN ESL_IO_MGMT ** ppFree\r
  );\r
\r
/**\r
  Transmit data using a network connection.\r
\r
  This support routine starts a transmit operation on the\r
  underlying network layer.\r
\r
  The network specific code calls this routine to start a\r
  transmit operation.  See the \ref TransmitEngine section.\r
\r
  @param [in] pPort           Address of an ::ESL_PORT structure\r
  @param [in] ppQueueHead     Transmit queue head address\r
  @param [in] ppQueueTail     Transmit queue tail address\r
  @param [in] ppActive        Active transmit queue address\r
  @param [in] ppFree          Free transmit queue address\r
\r
 **/\r
VOID\r
EslSocketTxStart (\r
  IN ESL_PORT * pPort,\r
  IN ESL_PACKET ** ppQueueHead,\r
  IN ESL_PACKET ** ppQueueTail,\r
  IN ESL_IO_MGMT ** ppActive,\r
  IN ESL_IO_MGMT ** ppFree\r
  );\r
\r
//------------------------------------------------------------------------------\r
\r
#endif  //  _SOCKET_H_\r