From e5b9e19fdc1dd291744e3971f68749712a2af9ef Mon Sep 17 00:00:00 2001 From: lpleahy Date: Fri, 9 Sep 2011 00:08:59 +0000 Subject: 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 --- StdLib/BsdSocketLib/socket.c | 6 ++ StdLib/EfiSocketLib/DxeSupport.c | 44 +++++++----- StdLib/EfiSocketLib/Init.c | 44 ++++++++---- StdLib/EfiSocketLib/Ip4.c | 5 -- StdLib/EfiSocketLib/Socket.c | 77 ++++++++++++--------- StdLib/EfiSocketLib/Socket.h | 124 +++++++++++++++++++++++----------- StdLib/EfiSocketLib/Tcp4.c | 5 -- StdLib/EfiSocketLib/Udp4.c | 5 -- StdLib/EfiSocketLib/UseEfiSocketLib.c | 36 +++++++--- StdLib/Include/Efi/EfiSocketLib.h | 28 ++++---- StdLib/UseSocketDxe/UseSocketDxe.c | 21 ++++-- 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 +/** + 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: + + + 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: + + + 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 (
  • ::EslSocketTransmit
    • - @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: + + + @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. -- cgit v1.1