Finish the Doxygen comment updates for EfiSocketLib and UseSocketDxe.

Signed-off by: Lee Leahy


git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/branches/EADK@12303 6f19259b-4bc3-4df7-8a09-765794883524

11 files changed, 251 insertions, 144 deletions

diff --git a/StdLib/BsdSocketLib/socket.c b/StdLib/BsdSocketLib/socket.c
index d0a5089..4f49777 100644
--- a/StdLib/BsdSocketLib/socket.c
+++ b/StdLib/BsdSocketLib/socket.c
@@ -15,6 +15,12 @@
 #include <SocketInternals.h>

 

 

+/**

+  File system interface for the socket layer.

+

+  This data structure defines the routines for the various

+  file system functions associated with the socket layer.

+**/

 const struct fileops SocketOperations = {

   BslSocketClose,     //  close

   BslSocketRead,      //  read

diff --git a/StdLib/EfiSocketLib/DxeSupport.c b/StdLib/EfiSocketLib/DxeSupport.c
index 89181a9..284fa9c 100644
--- a/StdLib/EfiSocketLib/DxeSupport.c
+++ b/StdLib/EfiSocketLib/DxeSupport.c
@@ -16,15 +16,16 @@
 

 

 /**

-  Creates a child handle and installs a protocol.

+  Creates a child handle and installs gEfiSocketProtocolGuid.

 

-  When the socket application is linked against UseSocketDxe, the ::socket

-  routine indirectly calls this routine in SocketDxe to create a child

-  handle if necessary and install the socket protocol on the handle.

-  Upon return, EslServiceGetProtocol in UseSocketLib returns the

-  ::EFI_SOCKET_PROTOCOL address to the socket routine.

+  This routine creates a child handle for the socket driver and

+  installs the ::gEfiSocketProtocolGuid on that handle with a pointer

+  to the ::EFI_SOCKET_PROTOCOL structure address.

 

-  @param [in] pThis        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.

+  This routine is called by ::EslServiceGetProtocol in UseSocketDxe

+  when the socket application is linked with UseSocketDxe.

+

+  @param [in] pThis        Address of the EFI_SERVICE_BINDING_PROTOCOL structure.

   @param [in] pChildHandle Pointer to the handle of the child to create. If it is NULL,

                            then a new handle is created. If it is a pointer to an existing UEFI handle, 

                            then the protocol is added to the existing UEFI handle.

@@ -64,15 +65,14 @@ EslDxeCreateChild (
 

 

 /**

-  Destroys a child handle with a protocol installed on it.

-  

-  When the socket application is linked against UseSocketDxe, the ::close

-  routine indirectly calls this routine in SocketDxe to undo the operations

-  done by the ::EslDxeCreateChild routine.  This routine removes the socket

-  protocol from the handle and then destroys the child handle if there are

-  no other protocols attached.

+  Removes gEfiSocketProtocolGuid and destroys the child handle.

+

+  This routine uninstalls ::gEfiSocketProtocolGuid from the child handle

+  and destroys the child handle if necessary.

 

-  @param [in] pThis       Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.

+  This routine is called from ???.

+  

+  @param [in] pThis       Address of the EFI_SERVICE_BINDING_PROTOCOL structure.

   @param [in] ChildHandle Handle of the child to destroy

 

   @retval EFI_SUCCESS           The protocol was removed from ChildHandle.

@@ -226,8 +226,12 @@ EslDxeDestroyChild (
 /**

 Install the socket service

 

-SocketDxe uses this routine to announce the socket interface to

-the rest of EFI.

+This routine installs the ::gEfiSocketServiceBindingProtocolGuid

+on the SocketDxe image handle to announce the availability

+of the socket layer to the rest of EFI.

+

+SocketDxe's EntryPoint routine calls this routine to

+make the socket layer available.

 

 @param [in] pImageHandle      Address of the image handle

 

@@ -271,9 +275,13 @@ EslDxeInstall (
 /**

 Uninstall the socket service

 

-SocketDxe uses this routine to notify EFI that the socket layer

+This routine removes the gEfiSocketServiceBindingProtocolGuid from

+the SocketDxe image handle to notify EFI that the socket layer

 is no longer available.

 

+SocketDxe's DriverUnload routine calls this routine to remove the

+socket layer.

+

 @param [in] ImageHandle       Handle for the image.

 

 @retval EFI_SUCCESS     Service installed successfully

diff --git a/StdLib/EfiSocketLib/Init.c b/StdLib/EfiSocketLib/Init.c
index 91c5714..88d2065 100644
--- a/StdLib/EfiSocketLib/Init.c
+++ b/StdLib/EfiSocketLib/Init.c
@@ -18,12 +18,22 @@
 /**

   EFI Socket Library Constructor

 

-  Constructor listed in the EfiSocketLib.inf file.  This routine

-  supports an implementation dependent constructor depending upon

-  whether the library is linked to an application or to the SocketDxe

-  driver.

-

-  @retval EFI_SUCCESS       The initialization was successful

+  This routine supports an implementation dependent constructor

+  depending upon whether the library is linked to a socket

+  application or the SocketDxe driver.  The following modules

+  declare the redirection for the constructor in ::mpfnEslConstructor:

+  <ul>

+    <li>StdLib/EfiSocketLib/UseSocketLib.c - Application links against EfiSocketLib</li>

+    <li>StdLib/SocketDxe/EntryUnload.c - SocketDxe links against EfiSocketLib</li>

+  </ul>

+

+  The EfiSocketLib.inf file lists ::EslConstructor as the CONSTRUCTOR

+  in the [Defines] section.  As a result, this routine is called by

+  the ProcessLibraryConstructorList routine of the AutoGen.c module

+  in the Build directory associated with the socket application or

+  the SocketDxe driver.

+

+  @retval EFI_SUCCESS       The socket layer initialization was successful

 

  **/

 EFI_STATUS

@@ -59,12 +69,22 @@ EslConstructor (
 /**

   EFI Socket Library Destructor

 

-  Destructor listed in the EfiSocketLib.inf file.  This routine

-  supports an implementation dependent destructor depending upon

-  whether the library is linked to an application or to the SocketDxe

-  driver.

-

-  @retval EFI_SUCCESS       The shutdown was successful

+  This routine supports an implementation dependent destructor

+  depending upon whether the library is linked to a socket

+  application or the SocketDxe driver.  The following modules

+  declare the redirection for the destructor in ::mpfnEslDestructor:

+  <ul>

+    <li>StdLib/EfiSocketLib/UseSocketLib.c - Application links against EfiSocketLib</li>

+    <li>StdLib/SocketDxe/EntryUnload.c - SocketDxe links against EfiSocketLib</li>

+  </ul>

+

+  The EfiSocketLib.inf file lists ::EslDestructor as the DESTRUCTOR

+  in the [Defines] section.  As a result, this routine is called by

+  the ProcessLibraryDestructorList routine of the AutoGen.c module

+  in the Build directory associated with the socket application or

+  the SocketDxe driver.

+

+  @retval EFI_SUCCESS       The socket layer shutdown was successful

 

  **/

 EFI_STATUS

diff --git a/StdLib/EfiSocketLib/Ip4.c b/StdLib/EfiSocketLib/Ip4.c
index 9db5480..d91638c 100644
--- a/StdLib/EfiSocketLib/Ip4.c
+++ b/StdLib/EfiSocketLib/Ip4.c
@@ -543,11 +543,6 @@ EslIp4Initialize (
   DBG_ENTER ( );

 

   //

-  //  Identify the service

-  //

-  pService->NetworkType = NETWORK_TYPE_IP4;

-

-  //

   //  Connect this service to the service list

   //

   pLayer = &mEslLayer;

diff --git a/StdLib/EfiSocketLib/Socket.c b/StdLib/EfiSocketLib/Socket.c
index 9b04d5b..9f8d67e 100644
--- a/StdLib/EfiSocketLib/Socket.c
+++ b/StdLib/EfiSocketLib/Socket.c
@@ -78,7 +78,7 @@ CONST ESL_SOCKET_BINDING cEslSocketBinding[] = {
 CONST UINTN cEslSocketBindingEntries = DIM ( cEslSocketBinding );

 

 /**

-  APIs to support the various socket types

+  APIs to support the various socket types for the v4 network stack.

 **/

 CONST ESL_PROTOCOL_API * cEslAfInetApi[] = {

   NULL,             //  0

@@ -89,8 +89,15 @@ CONST ESL_PROTOCOL_API * cEslAfInetApi[] = {
   &cEslTcp4Api      //  SOCK_SEQPACKET

 };

 

+/**

+  Number of entries in the v4 API array ::cEslAfInetApi.

+**/

 CONST int cEslAfInetApiSize = DIM ( cEslAfInetApi );

 

+

+/**

+  APIs to support the various socket types for the v6 network stack.

+**/

 CONST ESL_PROTOCOL_API * cEslAfInet6Api[] = {

   NULL,             //  0

   NULL,             //  SOCK_STREAM

@@ -100,8 +107,15 @@ CONST ESL_PROTOCOL_API * cEslAfInet6Api[] = {
   NULL              //  SOCK_SEQPACKET

 };

 

+/**

+  Number of entries in the v6 API array ::cEslAfInet6Api.

+**/

 CONST int cEslAfInet6ApiSize = DIM ( cEslAfInet6Api );

 

+

+/**

+  Global management structure for the socket layer.

+**/

 ESL_LAYER mEslLayer;

 

 

@@ -272,7 +286,7 @@ EslSocket (
   associated with the new socket and the remote network address

   if requested.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] pSockAddr       Address of a buffer to receive the remote

                               network address.

@@ -456,7 +470,7 @@ EslSocketAccept (
 /**

   Allocate and initialize a ESL_SOCKET structure.

   

-  This support function allocates a ::ESL_SOCKET structure

+  This support function allocates an ::ESL_SOCKET structure

   and installs a protocol on ChildHandle.  If pChildHandle is a

   pointer to NULL, then a new handle is created and returned in

   pChildHandle.  If pChildHandle is not a pointer to NULL, then

@@ -468,7 +482,7 @@ EslSocketAccept (
                                 then the protocol is added to the existing UEFI

                                 handle.

   @param [in] DebugFlags        Flags for debug messages

-  @param [in, out] ppSocket     The buffer to receive the ::ESL_SOCKET structure address.

+  @param [in, out] ppSocket     The buffer to receive an ::ESL_SOCKET structure address.

 

   @retval EFI_SUCCESS           The protocol was added to ChildHandle.

   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.

@@ -612,7 +626,7 @@ EslSocketAllocate (
   The ::bind routine calls this routine to connect a name

   (network address and port) to a socket on the local machine.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] pSockAddr Address of a sockaddr structure that contains the

                         connection point on the local machine.  An IPv4 address

@@ -624,7 +638,7 @@ EslSocketAllocate (
                         number from the dynamic range.  Specifying a specific

                         port number causes the network layer to use that port.

 

-  @param [in] SockAddrLen   Specifies the length in bytes of the sockaddr structure.

+  @param [in] SockAddrLength  Specifies the length in bytes of the sockaddr structure.

 

   @param [out] pErrno   Address to receive the errno value upon completion.

 

@@ -750,7 +764,7 @@ EslSocketBind (
   close operation is complete.  The close operation needs to

   reverse the operations of the ::EslSocketAllocate routine.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [out] pErrno         Address to receive the errno value upon completion.

 

   @retval EFI_SUCCESS     Socket successfully closed

@@ -893,7 +907,7 @@ EslSocketClosePoll (
   the ::EslSocketClosePoll routine to determine when the

   socket is closed.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] bCloseNow       Boolean to control close behavior

   @param [out] pErrno         Address to receive the errno value upon completion.

 

@@ -1004,7 +1018,7 @@ EslSocketCloseStart (
   is designed to be polled by the connect routine for completion

   of the network connection.

   

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] pSockAddr       Network address of the remote system.

     

@@ -1190,7 +1204,7 @@ EslSocketConnect (
   The ::getsockname routine calls this routine to obtain the network

   address associated with the local host connection point.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [out] pAddress       Network address to receive the local system address

 

@@ -1304,7 +1318,7 @@ EslSocketGetLocalAddress (
   The ::getpeername routine calls this routine to obtain the network

   address of the remote connection point.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [out] pAddress       Network address to receive the remote system address

 

@@ -1418,11 +1432,11 @@ EslSocketGetPeerAddress (
 

   See the \ref TransmitEngine section.

 

-  @param [in] pPort         The ESL_PORT structure address

+  @param [in] pPort         Address of an ::ESL_PORT structure

   @param [in] ppFreeQueue   Address of the free queue head

   @param [in] DebugFlags    Flags for debug messages

   @param [in] pEventName    Zero terminated string containing the event name

-  @param [in] EventOffset   Offset in the event in the ESL_IO_MGMT structure

+  @param [in] EventOffset   Offset of the event in the ::ESL_IO_MGMT structure

 

   @retval EFI_SUCCESS - The structures were properly initialized

 

@@ -1433,7 +1447,8 @@ EslSocketIoFree (
   IN ESL_IO_MGMT ** ppFreeQueue,

   IN UINTN DebugFlags,

   IN CHAR8 * pEventName,

-  IN UINT32 EventOffset )

+  IN UINT32 EventOffset

+  )

 {

   UINT8 * pBuffer;

   EFI_EVENT * pEvent;

@@ -1498,14 +1513,14 @@ EslSocketIoFree (
   This routine is called by the PortAllocate routines to prepare

   the transmit engines.  See the \ref TransmitEngine section.

 

-  @param [in] pPort         The ESL_PORT structure address

-  @param [in, out], ppIo    Address containing the first structure address.  Upon

+  @param [in] pPort         Address of an ::ESL_PORT structure

+  @param [in, out] ppIo     Address containing the first structure address.  Upon

                             return this buffer contains the next structure address.

   @param [in] TokenCount    Number of structures to initialize

   @param [in] ppFreeQueue   Address of the free queue head

   @param [in] DebugFlags    Flags for debug messages

   @param [in] pEventName    Zero terminated string containing the event name

-  @param [in] EventOffset   Offset in the event in the ESL_IO_MGMT structure

+  @param [in] EventOffset   Offset of the event in the ::ESL_IO_MGMT structure

   @param [in] pfnCompletion Completion routine address

 

   @retval EFI_SUCCESS - The structures were properly initialized

@@ -1520,7 +1535,8 @@ EslSocketIoInit (
   IN UINTN DebugFlags,

   IN CHAR8 * pEventName,

   IN UINTN EventOffset,

-  IN EFI_EVENT_NOTIFY pfnCompletion )

+  IN EFI_EVENT_NOTIFY pfnCompletion

+  )

 {

   ESL_IO_MGMT * pEnd;

   EFI_EVENT * pEvent;

@@ -1611,7 +1627,7 @@ EslSocketIoInit (
     <li>::EslSocketTransmit</li>

   </ul>

 

-  @param [in] pSocket       The ::ESL_SOCKET structure address

+  @param [in] pSocket       Address of an ::ESL_SOCKET structure

 

   @retval EFI_SUCCESS - The socket is configured

 

@@ -1686,7 +1702,7 @@ EslSocketIsConfigured (
   remove the next connection from the FIFO and get the associated

   socket and address.

 

-  @param [in] pSocketProtocol Address of the socket protocol structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] Backlog         Backlog specifies the maximum FIFO depth for

                               the connections waiting for the application

@@ -1851,7 +1867,7 @@ EslSocketListen (
   The ::getsockopt routine calls this routine to retrieve the

   socket options one at a time by name.

 

-  @param [in] pSocketProtocol   Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol   Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] level             Option protocol level

   @param [in] OptionName        Name of the option

   @param [out] pOptionValue     Buffer to receive the option value

@@ -2037,7 +2053,7 @@ EslSocketOptionGet (
   The ::setsockopt routine calls this routine to adjust the socket

   options one at a time by name.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] level           Option protocol level

   @param [in] OptionName      Name of the option

   @param [in] pOptionValue    Buffer containing the option value

@@ -2276,7 +2292,7 @@ EslSocketPacketAllocate (
   and TxBuffer.  Note that the network layers typically place

   receive packets on the ESL_SOCKET::pRxFree list for reuse.

 

-  @param [in] pPacket     Address of the ESL_PACKET structure

+  @param [in] pPacket     Address of an ::ESL_PACKET structure

   @param [in] DebugFlags  Flags for debug messages

 

   @retval EFI_SUCCESS - The packet was allocated successfully

@@ -2329,7 +2345,7 @@ EslSocketPacketFree (
   needs to be serviced as a result of connection, error, receive or

   transmit activity.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] Events    Events of interest for this socket

 

@@ -2489,7 +2505,7 @@ EslSocketPoll (
   is received from the remote system.  Note that the other routines

   ::recv and ::read are layered on top of ::recvfrom.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] Flags           Message control flags

   

@@ -2634,7 +2650,7 @@ EslSocketReceive (
   The ::shutdown routine calls this routine to stop receive and transmit

   operations on the socket.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] How             Which operations to stop

   

@@ -2761,7 +2777,7 @@ EslSocketShutdown (
   The ::sendto routine calls this routine to send data to the remote

   system.  Note that ::send and ::write are layered on top of ::sendto.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] Flags           Message control flags

   

@@ -2930,8 +2946,8 @@ EslSocketTransmit (
   The network specific code calls this routine during its transmit

   complete processing.  See the \ref TransmitEngine section.

 

-  @param [in] pPort           Address of a ESL_PORT structure

-  @param [in] pIo             Address of the ESL_IO_MGMT structure

+  @param [in] pPort           Address of an ::ESL_PORT structure

+  @param [in] pIo             Address of an ::ESL_IO_MGMT structure

   @param [in] ppActive        Active transmit queue address

   @param [in] ppFree          Free transmit queue address

 

@@ -2991,8 +3007,7 @@ EslSocketTxComplete (
   The network specific code calls this routine to start a

   transmit operation.  See the \ref TransmitEngine section.

 

-  @param [in] pPort           Address of a ESL_PORT structure

-  @param [in] pToken          Address of either the OOB or normal transmit token

+  @param [in] pPort           Address of an ::ESL_PORT structure

   @param [in] ppQueueHead     Transmit queue head address

   @param [in] ppQueueTail     Transmit queue tail address

   @param [in] ppActive        Active transmit queue address

diff --git a/StdLib/EfiSocketLib/Socket.h b/StdLib/EfiSocketLib/Socket.h
index dec3614..120fa17 100644
--- a/StdLib/EfiSocketLib/Socket.h
+++ b/StdLib/EfiSocketLib/Socket.h
@@ -34,29 +34,22 @@
 

 #define MAX_PENDING_CONNECTIONS     1   ///<  Maximum connection FIFO depth

 #define MAX_RX_DATA         65536       ///<  Maximum receive data size

-#define MAX_TX_DATA         ( MAX_RX_DATA * 2 )

+#define MAX_TX_DATA         ( MAX_RX_DATA * 2 ) ///<  Maximum buffered transmit data in bytes

 #define RX_PACKET_DATA      16384       ///<  Maximum number of bytes in a RX packet

 #define MAX_UDP_RETRANSMIT  16          ///<  UDP retransmit attempts to handle address not mapped

 

-#define ESL_STRUCTURE_ALIGNMENT_BYTES   15

-#define ESL_STRUCTURE_ALIGNMENT_MASK    ( ~ESL_STRUCTURE_ALIGNMENT_BYTES )

+#define ESL_STRUCTURE_ALIGNMENT_BYTES   15  ///<  Number of bytes for structure alignment

+#define ESL_STRUCTURE_ALIGNMENT_MASK    ( ~ESL_STRUCTURE_ALIGNMENT_BYTES )  ///<  Mask to align structures

 

 #define LAYER_SIGNATURE           SIGNATURE_32 ('S','k','t','L')  ///<  ESL_LAYER memory signature

 #define SERVICE_SIGNATURE         SIGNATURE_32 ('S','k','t','S')  ///<  ESL_SERVICE memory signature

 #define SOCKET_SIGNATURE          SIGNATURE_32 ('S','c','k','t')  ///<  ESL_SOCKET memory signature

 #define PORT_SIGNATURE            SIGNATURE_32 ('P','o','r','t')  ///<  ESL_PORT memory signature

 

-typedef enum

-{

-  NETWORK_TYPE_UNKNOWN = 0,

-  NETWORK_TYPE_IP4,

-  NETWORK_TYPE_IP6,

-  NETWORK_TYPE_TCP4,

-  NETWORK_TYPE_TCP6,

-  NETWORK_TYPE_UDP4,

-  NETWORK_TYPE_UDP6

-} NETWORK_TYPE;

 

+/**

+  Socket states

+**/

 typedef enum

 {

   SOCKET_STATE_NOT_CONFIGURED = 0,  ///<  socket call was successful

@@ -73,6 +66,10 @@ typedef enum
   SOCKET_STATE_CLOSED               ///<  Close call was successful

 } SOCKET_STATE;

 

+

+/**

+  Port states

+**/

 typedef enum

 {

   PORT_STATE_ALLOCATED = 0, ///<  Port allocated

@@ -97,11 +94,18 @@ typedef struct _ESL_PACKET ESL_PACKET;  ///<  Forward declaration
 typedef struct _ESL_PORT ESL_PORT;      ///<  Forward declaration

 typedef struct _ESL_SOCKET ESL_SOCKET;  ///<  Forward declaration

 

+/**

+  Receive context for SOCK_RAW sockets using IPv4.

+**/

 typedef struct

 {

   EFI_IP4_RECEIVE_DATA * pRxData;       ///<  Receive operation description

 } ESL_IP4_RX_DATA;

 

+

+/**

+  Transmit context for SOCK_RAW sockets using IPv4.

+**/

 typedef struct

 {

   EFI_IP4_OVERRIDE_DATA Override;       ///<  Override data

@@ -109,6 +113,10 @@ typedef struct
   UINT8 Buffer[ 1 ];                    ///<  Data buffer

 } ESL_IP4_TX_DATA;

 

+

+/**

+  Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.

+**/

 typedef struct

 {

   EFI_TCP4_RECEIVE_DATA RxData;         ///<  Receive operation description

@@ -117,18 +125,30 @@ typedef struct
   UINT8 Buffer[ RX_PACKET_DATA ];       ///<  Data buffer

 } ESL_TCP4_RX_DATA;

 

+

+/**

+  Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4.

+**/

 typedef struct

 {

   EFI_TCP4_TRANSMIT_DATA TxData;        ///<  Transmit operation description

   UINT8 Buffer[ 1 ];                    ///<  Data buffer

 } ESL_TCP4_TX_DATA;

 

+

+/**

+  Receive context for SOCK_DGRAM sockets using UDPv4.

+**/

 typedef struct

 {

   EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address

   EFI_UDP4_RECEIVE_DATA * pRxData;      ///<  Receive operation description

 } ESL_UDP4_RX_DATA;

 

+

+/**

+  Transmit context for SOCK_DGRAM sockets using UDPv4.

+**/

 typedef struct

 {

   EFI_UDP4_SESSION_DATA Session;        ///<  Remote network address

@@ -137,6 +157,10 @@ typedef struct
   UINT8 Buffer[ 1 ];                    ///<  Data buffer

 } ESL_UDP4_TX_DATA;

 

+

+/**

+  Network specific context for transmit and receive packets.

+**/

 typedef struct _ESL_PACKET {

   ESL_PACKET * pNext;                   ///<  Next packet in the receive list

   size_t PacketSize;                    ///<  Size of this data structure

@@ -147,7 +171,7 @@ typedef struct _ESL_PACKET {
     ESL_TCP4_TX_DATA Tcp4Tx;            ///<  Transmit operation description

     ESL_UDP4_RX_DATA Udp4Rx;            ///<  Receive operation description

     ESL_UDP4_TX_DATA Udp4Tx;            ///<  Transmit operation description

-  } Op;

+  } Op;                                 ///<  Network specific context

 } GCC_ESL_PACKET;

 

 /**

@@ -173,7 +197,6 @@ typedef struct _ESL_SERVICE {
   //

   //  Network data

   //

-  NETWORK_TYPE NetworkType; ///<  Type of network service

   ESL_PORT * pPortList;     ///<  List of ports using this service

 }GCC_ESL_SERVICE;

 

@@ -206,7 +229,7 @@ typedef struct _ESL_IO_MGMT {
     EFI_IP4_COMPLETION_TOKEN Ip4Tx;   ///<  IP4 transmit token

     EFI_TCP4_IO_TOKEN Tcp4Tx;         ///<  TCP4 transmit token

     EFI_UDP4_COMPLETION_TOKEN Udp4Tx; ///<  UDP4 transmit token

-  } Token;

+  } Token;                            ///<  Completion token for the network operation

 };

 

 /**

@@ -319,7 +342,6 @@ typedef struct _ESL_PORT {
   //

   ESL_SERVICE * pService;       ///<  Service for this port

   ESL_SOCKET * pSocket;         ///<  Socket for this port

-//  PFN_CLOSE_PORT pfnClosePort;  ///<  Routine to immediately close the port

   PFN_PORT_CLOSE_START * pfnCloseStart; ///<  Routine to start closing the port

 

   //

@@ -347,7 +369,7 @@ typedef struct _ESL_PORT {
     ESL_IP4_CONTEXT Ip4;        ///<  IPv4 management data

     ESL_TCP4_CONTEXT Tcp4;      ///<  TCPv4 management data

     ESL_UDP4_CONTEXT Udp4;      ///<  UDPv4 management data

-  } Context;

+  } Context;                    ///<  Network specific context

 }GCC_ESL_PORT;

 

 /**

@@ -802,7 +824,7 @@ extern CONST EFI_SERVICE_BINDING_PROTOCOL mEfiServiceBinding;
 /**

   Allocate and initialize a ESL_SOCKET structure.

   

-  The ::SocketAllocate() function allocates a ESL_SOCKET structure

+  This support function allocates an ::ESL_SOCKET structure

   and installs a protocol on ChildHandle.  If pChildHandle is a

   pointer to NULL, then a new handle is created and returned in

   pChildHandle.  If pChildHandle is not a pointer to NULL, then

@@ -814,11 +836,11 @@ extern CONST EFI_SERVICE_BINDING_PROTOCOL mEfiServiceBinding;
                                 then the protocol is added to the existing UEFI

                                 handle.

   @param [in] DebugFlags        Flags for debug messages

-  @param [in, out] ppSocket     The buffer to receive the ESL_SOCKET structure address.

+  @param [in, out] ppSocket     The buffer to receive an ::ESL_SOCKET structure address.

 

   @retval EFI_SUCCESS           The protocol was added to ChildHandle.

   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.

-  @retval EFI_OUT_OF_RESOURCES  There are not enough resources availabe to create

+  @retval EFI_OUT_OF_RESOURCES  There are not enough resources available to create

                                 the child

   @retval other                 The child handle was not created

   

@@ -838,11 +860,13 @@ EslSocketAllocate (
   the ESL_IO_MGMT structure and remove the structure from the free

   list.

 

-  @param [in] pPort         The ESL_PORT structure address

+  See the \ref TransmitEngine section.

+

+  @param [in] pPort         Address of an ::ESL_PORT structure

   @param [in] ppFreeQueue   Address of the free queue head

   @param [in] DebugFlags    Flags for debug messages

   @param [in] pEventName    Zero terminated string containing the event name

-  @param [in] EventOffset   Offset in the event in the ESL_IO_MGMT structure

+  @param [in] EventOffset   Offset of the event in the ::ESL_IO_MGMT structure

 

   @retval EFI_SUCCESS - The structures were properly initialized

 

@@ -853,22 +877,26 @@ EslSocketIoFree (
   IN ESL_IO_MGMT ** ppFreeQueue,

   IN UINTN DebugFlags,

   IN CHAR8 * pEventName,

-  IN UINT32 EventOffset );

+  IN UINT32 EventOffset

+  );

 

 /**

   Initialize the ESL_IO_MGMT structures

 

   This support routine initializes the ESL_IO_MGMT structure and

-  places it on to a free list.

+  places them on to a free list.

+

+  This routine is called by the PortAllocate routines to prepare

+  the transmit engines.  See the \ref TransmitEngine section.

 

-  @param [in] pPort         The ESL_PORT structure address

-  @param [in, out], ppIo    Address containing the first structure address.  Upon

+  @param [in] pPort         Address of an ::ESL_PORT structure

+  @param [in, out] ppIo     Address containing the first structure address.  Upon

                             return this buffer contains the next structure address.

   @param [in] TokenCount    Number of structures to initialize

   @param [in] ppFreeQueue   Address of the free queue head

   @param [in] DebugFlags    Flags for debug messages

   @param [in] pEventName    Zero terminated string containing the event name

-  @param [in] EventOffset   Offset in the event in the ESL_IO_MGMT structure

+  @param [in] EventOffset   Offset of the event in the ::ESL_IO_MGMT structure

   @param [in] pfnCompletion Completion routine address

 

   @retval EFI_SUCCESS - The structures were properly initialized

@@ -883,12 +911,25 @@ EslSocketIoInit (
   IN UINTN DebugFlags,

   IN CHAR8 * pEventName,

   IN UINTN EventOffset,

-  IN EFI_EVENT_NOTIFY pfnCompletion );

+  IN EFI_EVENT_NOTIFY pfnCompletion

+  );

 

 /**

   Determine if the socket is configured

 

-  @param [in] pSocket       The ESL_SOCKET structure address

+  This support routine is called to determine if the socket if the

+  configuration call was made to the network layer.  The following

+  routines call this routine to verify that they may be successful

+  in their operations:

+  <ul>

+    <li>::EslSocketGetLocalAddress</li>

+    <li>::EslSocketGetPeerAddress</li>

+    <li>::EslSocketPoll</li>

+    <li>::EslSocketReceive</li>

+    <li>::EslSocketTransmit</li>

+  </ul>

+

+  @param [in] pSocket       Address of an ::ESL_SOCKET structure

 

   @retval EFI_SUCCESS - The socket is configured

 

@@ -901,7 +942,10 @@ EslSocketIsConfigured (
 /**

   Allocate a packet for a receive or transmit operation

 

-  @param [in] ppPacket      Address to receive the ESL_PACKET structure

+  This support routine is called by the network specific RxStart

+  and TxBuffer routines to get buffer space for the next operation.

+

+  @param [in] ppPacket      Address to receive the ::ESL_PACKET structure

   @param [in] LengthInBytes Length of the packet structure

   @param [in] DebugFlags    Flags for debug messages

 

@@ -918,7 +962,12 @@ EslSocketPacketAllocate (
 /**

   Free a packet used for receive or transmit operation

 

-  @param [in] pPacket     Address of the ESL_PACKET structure

+  This support routine is called by the network specific Close

+  and TxComplete routines and during error cases in RxComplete

+  and TxBuffer.  Note that the network layers typically place

+  receive packets on the ESL_SOCKET::pRxFree list for reuse.

+

+  @param [in] pPacket     Address of an ::ESL_PACKET structure

   @param [in] DebugFlags  Flags for debug messages

 

   @retval EFI_SUCCESS - The packet was allocated successfully

@@ -937,10 +986,10 @@ EslSocketPacketFree (
   the active queue and returns it to the free queue.

 

   The network specific code calls this routine during its transmit

-  complete processing.

+  complete processing.  See the \ref TransmitEngine section.

 

-  @param [in] pPort           Address of a ESL_PORT structure

-  @param [in] pIo             Address of the ESL_IO_MGMT structure

+  @param [in] pPort           Address of an ::ESL_PORT structure

+  @param [in] pIo             Address of an ::ESL_IO_MGMT structure

   @param [in] ppActive        Active transmit queue address

   @param [in] ppFree          Free transmit queue address

 

@@ -960,10 +1009,9 @@ EslSocketTxComplete (
   underlying network layer.

 

   The network specific code calls this routine to start a

-  transmit operation.

+  transmit operation.  See the \ref TransmitEngine section.

 

-  @param [in] pPort           Address of a ESL_PORT structure

-  @param [in] pToken          Address of either the OOB or normal transmit token

+  @param [in] pPort           Address of an ::ESL_PORT structure

   @param [in] ppQueueHead     Transmit queue head address

   @param [in] ppQueueTail     Transmit queue tail address

   @param [in] ppActive        Active transmit queue address

diff --git a/StdLib/EfiSocketLib/Tcp4.c b/StdLib/EfiSocketLib/Tcp4.c
index 20deaba..f8741ec 100644
--- a/StdLib/EfiSocketLib/Tcp4.c
+++ b/StdLib/EfiSocketLib/Tcp4.c
@@ -1021,11 +1021,6 @@ EslTcp4Initialize (
   DBG_ENTER ( );

 

   //

-  //  Identify the service

-  //

-  pService->NetworkType = NETWORK_TYPE_TCP4;

-

-  //

   //  Connect this service to the service list

   //

   pLayer = &mEslLayer;

diff --git a/StdLib/EfiSocketLib/Udp4.c b/StdLib/EfiSocketLib/Udp4.c
index 7148d1a..116355a 100644
--- a/StdLib/EfiSocketLib/Udp4.c
+++ b/StdLib/EfiSocketLib/Udp4.c
@@ -551,11 +551,6 @@ EslUdp4Initialize (
   DBG_ENTER ( );

 

   //

-  //  Identify the service

-  //

-  pService->NetworkType = NETWORK_TYPE_UDP4;

-

-  //

   //  Connect this service to the service list

   //

   pLayer = &mEslLayer;

diff --git a/StdLib/EfiSocketLib/UseEfiSocketLib.c b/StdLib/EfiSocketLib/UseEfiSocketLib.c
index 6c03e3e..1c122af 100644
--- a/StdLib/EfiSocketLib/UseEfiSocketLib.c
+++ b/StdLib/EfiSocketLib/UseEfiSocketLib.c
@@ -47,12 +47,17 @@ CONST EFI_GUID mEslUdp4ServiceGuid = {
 /**

   Connect to the EFI socket library

 

-  This routine is called from the socket routine in BsdSocketLib

-  to create the data structure for a socket.  This specific

-  implementation is used when an application links directly to

-  the EslSocketLib.

+  This routine creates the ::ESL_SOCKET structure and returns

+  the API (::EFI_SOCKET_PROTOCOL address) to the socket file

+  system layer in BsdSocketLib.

 

-  @param [in] ppSocketProtocol  Address to receive the socket protocol address

+  This routine is called from the ::socket routine in BsdSocketLib

+  to create the data structure and initialize the API for a socket.

+  Note that this implementation is only used by socket applications

+  that link directly to EslSocketLib.

+

+  @param [in] ppSocketProtocol  Address to receive the ::EFI_SOCKET_PROTOCOL

+                                structure address

 

   @return       Value for ::errno, zero (0) indicates success.

 

@@ -102,9 +107,15 @@ EslServiceGetProtocol (
 /**

   Connect to the network layer

 

-  Constructor for the EfiSocketLib when the library is linked

-  directly to an application.  This routine locates the network

-  devices and makes them available to EfiSocketLib.

+  This routine is the constructor for the EfiSocketLib when the

+  library is linked directly to an application.  This routine

+  walks the ::cEslSocketBinding table to create ::ESL_SERVICE

+  structures, associated with the network adapters, which this

+  routine links to the ::ESL_LAYER structure.

+

+  This routine is called from ::EslConstructor as a result of the

+  constructor redirection in ::mpfnEslConstructor at the end of this

+  file.

 

   @retval EFI_SUCCESS   Successfully connected to the network layer

 

@@ -195,8 +206,13 @@ EslServiceNetworkConnect (
   Disconnect from the network layer

 

   Destructor for the EfiSocketLib when the library is linked

-  directly to an application.  This routine breaks any connections

-  to the network devices and removes them from use by EfiSocketLib.

+  directly to an application.  This routine walks the

+  ::cEslSocketBinding table to remove the ::ESL_SERVICE

+  structures (network connections) from the ::ESL_LAYER structure.

+

+  This routine is called from ::EslDestructor as a result of the

+  destructor redirection in ::mpfnEslDestructor at the end of this

+  file.

 

   @retval EFI_SUCCESS   Successfully disconnected from the network layer

 

diff --git a/StdLib/Include/Efi/EfiSocketLib.h b/StdLib/Include/Efi/EfiSocketLib.h
index 6a786a2..f8e9e98 100644
--- a/StdLib/Include/Efi/EfiSocketLib.h
+++ b/StdLib/Include/Efi/EfiSocketLib.h
@@ -343,7 +343,7 @@ EslServiceUnload (
   The ::bind routine calls this routine to connect a name

   (network address and port) to a socket on the local machine.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] pSockAddr Address of a sockaddr structure that contains the

                         connection point on the local machine.  An IPv4 address

@@ -355,7 +355,7 @@ EslServiceUnload (
                         number from the dynamic range.  Specifying a specific

                         port number causes the network layer to use that port.

 

-  @param [in] SockAddrLen   Specifies the length in bytes of the sockaddr structure.

+  @param [in] SockAddrLength  Specifies the length in bytes of the sockaddr structure.

 

   @param [out] pErrno   Address to receive the errno value upon completion.

 

@@ -380,7 +380,7 @@ EslSocketBind (
   close operation is complete.  The close operation needs to

   reverse the operations of the ::EslSocketAllocate routine.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [out] pErrno         Address to receive the errno value upon completion.

 

   @retval EFI_SUCCESS     Socket successfully closed

@@ -410,7 +410,7 @@ EslSocketClosePoll (
   the ::EslSocketClosePoll routine to determine when the

   socket is closed.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] bCloseNow       Boolean to control close behavior

   @param [out] pErrno         Address to receive the errno value upon completion.

 

@@ -439,7 +439,7 @@ EslSocketCloseStart (
   is designed to be polled by the connect routine for completion

   of the network connection.

   

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] pSockAddr       Network address of the remote system.

     

@@ -469,7 +469,7 @@ EslSocketConnect (
   The ::getsockname routine calls this routine to obtain the network

   address associated with the local host connection point.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [out] pAddress       Network address to receive the local system address

 

@@ -497,7 +497,7 @@ EslSocketGetLocalAddress (
   The ::getpeername routine calls this routine to obtain the network

   address of the remote connection point.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [out] pAddress       Network address to receive the remote system address

 

@@ -530,7 +530,7 @@ EslSocketGetPeerAddress (
   remove the next connection from the FIFO and get the associated

   socket and address.

 

-  @param [in] pSocketProtocol Address of the socket protocol structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] Backlog         Backlog specifies the maximum FIFO depth for

                               the connections waiting for the application

@@ -559,7 +559,7 @@ EslSocketListen (
   The ::getsockopt routine calls this routine to retrieve the

   socket options one at a time by name.

 

-  @param [in] pSocketProtocol   Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol   Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] level             Option protocol level

   @param [in] OptionName        Name of the option

   @param [out] pOptionValue     Buffer to receive the option value

@@ -589,7 +589,7 @@ EslSocketOptionGet (
   The ::setsockopt routine calls this routine to adjust the socket

   options one at a time by name.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   @param [in] level           Option protocol level

   @param [in] OptionName      Name of the option

   @param [in] pOptionValue    Buffer containing the option value

@@ -619,7 +619,7 @@ EslSocketOptionSet (
   needs to be serviced as a result of connection, error, receive or

   transmit activity.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

 

   @param [in] Events    Events of interest for this socket

 

@@ -650,7 +650,7 @@ EslSocketPoll (
   is received from the remote system.  Note that the other routines

   ::recv and ::read are layered on top of ::recvfrom.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] Flags           Message control flags

   

@@ -690,7 +690,7 @@ EslSocketReceive (
   The ::shutdown routine calls this routine to stop receive and transmit

   operations on the socket.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] How             Which operations to stop

   

@@ -718,7 +718,7 @@ EslSocketShutdown (
   The ::sendto routine calls this routine to send data to the remote

   system.  Note that ::send and ::write are layered on top of ::sendto.

 

-  @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure.

+  @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.

   

   @param [in] Flags           Message control flags

   

diff --git a/StdLib/UseSocketDxe/UseSocketDxe.c b/StdLib/UseSocketDxe/UseSocketDxe.c
index d5cf213..58a1222 100644
--- a/StdLib/UseSocketDxe/UseSocketDxe.c
+++ b/StdLib/UseSocketDxe/UseSocketDxe.c
@@ -25,12 +25,21 @@
 /**

   Connect to the EFI socket library

 

-  This routine is called from the socket routine in BsdSocketLib

-  to create the data structure for a socket.  This specific

-  implementation is used when an application links to UseSocketDxe

-  and redirects all requests to the SocketDxe driver.

-

-  @param [in] ppSocketProtocol  Address to receive the socket protocol address

+  This routine establishes a connection to the socket driver

+  and returns the API (::EFI_SOCKET_PROTOCOL address) to the

+  socket file system layer in BsdSocketLib.  This routine looks for

+  the gEfiSocketServiceBindingProtocolGuid to locate the socket

+  driver.  This routine then creates a child handle and locates

+  the gEfiSocketProtocolGuid protocol on that handle to get the

+  ::EFI_SOCKET_PROTOCOL structure address.

+

+  This routine is called from the ::socket routine in BsdSocketLib

+  to create the data structure and initialize the API for a socket.

+  Note that this implementation is only used by socket applications

+  that link directly to UseSocketDxe.

+

+  @param [in] ppSocketProtocol  Address to receive the ::EFI_SOCKET_PROTOCOL

+                                structure address

 

   @return       Value for ::errno, zero (0) indicates success.