From a88c31639bb24c73383a4528a5b77066e805148b Mon Sep 17 00:00:00 2001 From: lpleahy Date: Fri, 30 Sep 2011 23:02:35 +0000 Subject: Update the sockets library code * Passes conformance and functional tests. * Builds with GCC 4.4 compiler. Signed-off by: lpleahy git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12497 6f19259b-4bc3-4df7-8a09-765794883524 --- StdLib/Include/Efi/EfiSocketLib.h | 456 +++++++++++++++++++++--------------- StdLib/Include/Protocol/EfiSocket.h | 332 ++++++++++++++------------ 2 files changed, 442 insertions(+), 346 deletions(-) (limited to 'StdLib/Include') diff --git a/StdLib/Include/Efi/EfiSocketLib.h b/StdLib/Include/Efi/EfiSocketLib.h index f54d4c8fe3..802fbca40b 100644 --- a/StdLib/Include/Efi/EfiSocketLib.h +++ b/StdLib/Include/Efi/EfiSocketLib.h @@ -19,6 +19,7 @@ #include #include +#include #include #include @@ -49,12 +50,12 @@ #define DBG_EXIT_STATUS(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: %r\n", Status )) ///< Display routine exit with status value #define DBG_EXIT_TF(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", returning %s\n", (FALSE == Status) ? L"FALSE" : L"TRUE" )) ///< Display routine with TRUE/FALSE value #else // _MSC_VER -#define DBG_ENTER() -#define DBG_EXIT() -#define DBG_EXIT_DEC(Status) -#define DBG_EXIT_HEX(Status) -#define DBG_EXIT_STATUS(Status) -#define DBG_EXIT_TF(Status) +#define DBG_ENTER() ///< Display routine entry +#define DBG_EXIT() ///< Display routine exit +#define DBG_EXIT_DEC(Status) ///< Display routine exit with decimal value +#define DBG_EXIT_HEX(Status) ///< Display routine exit with hex value +#define DBG_EXIT_STATUS(Status) ///< Display routine exit with status value +#define DBG_EXIT_TF(Status) ///< Display routine with TRUE/FALSE value #endif // _MSC_VER #define DIM(x) ( sizeof ( x ) / sizeof ( x[0] )) ///< Compute the number of entries in an array @@ -71,12 +72,27 @@ #if !defined(MDEPKG_NDEBUG) +/** + Verify that the TPL is at the correct level +**/ +#define VERIFY_AT_TPL(tpl) \ +{ \ + EFI_TPL PreviousTpl; \ + \ + PreviousTpl = EfiGetCurrentTpl ( ); \ + if ( PreviousTpl != tpl ) { \ + DEBUG (( DEBUG_ERROR | DEBUG_TPL, \ + "Current TPL: %d, New TPL: %d\r\n", \ + PreviousTpl, tpl )); \ + ASSERT ( PreviousTpl == tpl ); \ + } \ +} + #define VERIFY_TPL(tpl) \ { \ EFI_TPL PreviousTpl; \ \ - PreviousTpl = gBS->RaiseTPL ( TPL_HIGH_LEVEL ); \ - gBS->RestoreTPL ( PreviousTpl ); \ + PreviousTpl = EfiGetCurrentTpl ( ); \ if ( PreviousTpl > tpl ) { \ DEBUG (( DEBUG_ERROR | DEBUG_TPL, \ "Current TPL: %d, New TPL: %d\r\n", \ @@ -87,10 +103,14 @@ #else // MDEPKG_NDEBUG -#define VERIFY_TPL(tpl) +#define VERIFY_AT_TPL(tpl) ///< Verify that the TPL is at the correct level +#define VERIFY_TPL(tpl) ///< Verify that the TPL is at the correct level #endif // MDEPKG_NDEBUG +/** + Raise TPL to the specified level +**/ #define RAISE_TPL(PreviousTpl, tpl) \ VERIFY_TPL ( tpl ); \ PreviousTpl = gBS->RaiseTPL ( tpl ); \ @@ -98,29 +118,20 @@ "%d: TPL\r\n", \ tpl )) +/** + Restore the TPL to the previous value +**/ #define RESTORE_TPL(tpl) \ - gBS->RestoreTPL ( tpl ); \ DEBUG (( DEBUG_TPL | DEBUG_TPL, \ "%d: TPL\r\n", \ - tpl )) + tpl )); \ + gBS->RestoreTPL ( tpl ) //------------------------------------------------------------------------------ // Data Types //------------------------------------------------------------------------------ -typedef struct _DT_SERVICE DT_SERVICE; ///< Forward delcaration - -typedef -EFI_STATUS -(EFIAPI * PFN_SB_INITIALIZE) ( - DT_SERVICE * pService - ); - -typedef -VOID -(EFIAPI * PFN_SB_SHUTDOWN) ( - DT_SERVICE * pService - ); +typedef struct _ESL_SERVICE ESL_SERVICE; ///< Forward delcaration /** Protocol binding and installation control structure @@ -130,172 +141,190 @@ VOID typedef struct { CHAR16 * pName; ///< Protocol name EFI_GUID * pNetworkBinding; ///< Network service binding protocol for socket support + EFI_GUID * pNetworkProtocolGuid;///< Network protocol GUID CONST EFI_GUID * pTagGuid; ///< Tag to mark protocol in use - PFN_SB_INITIALIZE pfnInitialize;///< Routine to initialize the service - PFN_SB_SHUTDOWN pfnShutdown; ///< Routine to shutdown the service -} DT_SOCKET_BINDING; + UINTN ServiceListOffset; ///< Offset in ::ESL_LAYER for the list of services + UINTN RxIo; ///< Number of receive ESL_IO_MGMT structures for data + UINTN TxIoNormal; ///< Number of transmit ESL_IO_MGMT structures for normal data + UINTN TxIoUrgent; ///< Number of transmit ESL_IO_MGMT structures for urgent data +} ESL_SOCKET_BINDING; //------------------------------------------------------------------------------ // GUIDs //------------------------------------------------------------------------------ -extern CONST EFI_GUID mEslRawServiceGuid; -extern CONST EFI_GUID mEslTcp4ServiceGuid; -extern CONST EFI_GUID mEslUdp4ServiceGuid; +extern CONST EFI_GUID mEslIp4ServiceGuid; ///< Tag GUID for the IPv4 layer +extern CONST EFI_GUID mEslTcp4ServiceGuid; ///< Tag GUID for the TCPv4 layer +extern CONST EFI_GUID mEslUdp4ServiceGuid; ///< Tag GUID for the UDPv4 layer //------------------------------------------------------------------------------ // Data //------------------------------------------------------------------------------ -extern CONST DT_SOCKET_BINDING cEslSocketBinding []; -extern CONST UINTN cEslSocketBindingEntries; +extern CONST ESL_SOCKET_BINDING cEslSocketBinding[];///< List of network service bindings +extern CONST UINTN cEslSocketBindingEntries; ///< Number of network service bindings //------------------------------------------------------------------------------ -// Service Support Routines +// DXE Support Routines //------------------------------------------------------------------------------ /** - Connect to the network service bindings + Creates a child handle and installs a protocol. - Walk the network service protocols on the controller handle and - locate any that are not in use. Create service structures to - manage the service binding for the socket driver. + 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. - @param [in] BindingHandle Handle for protocol binding. - @param [in] Controller Handle of device to work with. + @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. + @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. - @retval EFI_SUCCESS This driver is added to Controller. - @retval other This driver does not support this device. + @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 + the child + @retval other The child handle was not created **/ EFI_STATUS EFIAPI -EslServiceConnect ( - IN EFI_HANDLE BindingHandle, - IN EFI_HANDLE Controller +EslDxeCreateChild ( + IN EFI_SERVICE_BINDING_PROTOCOL * pThis, + IN OUT EFI_HANDLE * pChildHandle ); /** - Shutdown the network connections to this controller by removing - NetworkInterfaceIdentifier protocol and closing the DevicePath - and PciIo protocols on Controller. + 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. - @param [in] BindingHandle Handle for protocol binding. - @param [in] Controller Handle of device to stop driver on. + @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. + @param [in] ChildHandle Handle of the child to destroy - @retval EFI_SUCCESS This driver is removed Controller. - @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. - @retval other This driver was not removed from this device. + @retval EFI_SUCCESS The protocol was removed from ChildHandle. + @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed. + @retval EFI_INVALID_PARAMETER Child handle is not a valid UEFI Handle. + @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle + because its services are being used. + @retval other The child handle was not destroyed **/ EFI_STATUS EFIAPI -EslServiceDisconnect ( - IN EFI_HANDLE BindingHandle, - IN EFI_HANDLE Controller +EslDxeDestroyChild ( + IN EFI_SERVICE_BINDING_PROTOCOL * pThis, + IN EFI_HANDLE ChildHandle ); /** Install the socket service +SocketDxe uses this routine to announce the socket interface to +the rest of EFI. + @param [in] pImageHandle Address of the image handle @retval EFI_SUCCESS Service installed successfully **/ EFI_STATUS EFIAPI -EslServiceInstall ( +EslDxeInstall ( IN EFI_HANDLE * pImageHandle ); -/** -Initialize the service layer - -@param [in] ImageHandle Handle for the image. - -**/ -VOID -EFIAPI -EslServiceLoad ( - IN EFI_HANDLE ImageHandle - ); - /** Uninstall the socket service +SocketDxe uses this routine to notify EFI that the socket layer +is no longer available. + @param [in] ImageHandle Handle for the image. @retval EFI_SUCCESS Service installed successfully **/ EFI_STATUS EFIAPI -EslServiceUninstall ( +EslDxeUninstall ( IN EFI_HANDLE ImageHandle ); +//------------------------------------------------------------------------------ +// Service Support Routines +//------------------------------------------------------------------------------ + /** - Shutdown the service layer + Connect to the network service bindings + + Walk the network service protocols on the controller handle and + locate any that are not in use. Create ::ESL_SERVICE structures to + manage the network layer interfaces for the socket driver. Tag + each of the network interfaces that are being used. Finally, this + routine calls ESL_SOCKET_BINDING::pfnInitialize to prepare the network + interface for use by the socket layer. + + @param [in] BindingHandle Handle for protocol binding. + @param [in] Controller Handle of device to work with. + + @retval EFI_SUCCESS This driver is added to Controller. + @retval other This driver does not support this device. **/ -VOID +EFI_STATUS EFIAPI -EslServiceUnload ( - VOID +EslServiceConnect ( + IN EFI_HANDLE BindingHandle, + IN EFI_HANDLE Controller ); -//------------------------------------------------------------------------------ -// Socket Service Binding Protocol Routines -//------------------------------------------------------------------------------ - /** - Creates a child handle and installs a protocol. - - The CreateChild() function 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 the protocol installs on the existing pChildHandle. + Shutdown the connections to the network layer by locating the + tags on the network interfaces established by ::EslServiceConnect. + This routine calls ESL_SOCKET_BINDING::pfnShutdown to shutdown the any + activity on the network interface and then free the ::ESL_SERVICE + structures. - @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. - @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. + @param [in] BindingHandle Handle for protocol binding. + @param [in] Controller Handle of device to stop driver on. - @retval EFI_SUCCES 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 - the child - @retval other The child handle was not created + @retval EFI_SUCCESS This driver is removed Controller. + @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. + @retval other This driver was not removed from this device. **/ EFI_STATUS EFIAPI -EslSocketCreateChild ( - IN EFI_SERVICE_BINDING_PROTOCOL * pThis, - IN OUT EFI_HANDLE * pChildHandle +EslServiceDisconnect ( + IN EFI_HANDLE BindingHandle, + IN EFI_HANDLE Controller ); /** - Destroys a child handle with a protocol installed on it. +Initialize the service layer - The DestroyChild() function does the opposite of CreateChild(). It removes a protocol - that was installed by CreateChild() from ChildHandle. If the removed protocol is the - last protocol on ChildHandle, then ChildHandle is destroyed. +@param [in] ImageHandle Handle for the image. - @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. - @param [in] ChildHandle Handle of the child to destroy +**/ +VOID +EFIAPI +EslServiceLoad ( + IN EFI_HANDLE ImageHandle + ); - @retval EFI_SUCCES The protocol was removed from ChildHandle. - @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed. - @retval EFI_INVALID_PARAMETER Child handle is not a valid UEFI Handle. - @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle - because its services are being used. - @retval other The child handle was not destroyed +/** + Shutdown the service layer **/ -EFI_STATUS +VOID EFIAPI -EslSocketDestroyChild ( - IN EFI_SERVICE_BINDING_PROTOCOL * pThis, - IN EFI_HANDLE ChildHandle +EslServiceUnload ( + VOID ); //------------------------------------------------------------------------------ @@ -305,11 +334,13 @@ EslSocketDestroyChild ( /** Bind a name to a socket. - The ::SocketBind routine connects a name to a socket on the local machine. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls the network specific layer to save the network + address of the local connection point. - @param [in] pSocketProtocol Address of the socket protocol structure. + 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 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 @@ -321,7 +352,7 @@ EslSocketDestroyChild ( 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. @@ -331,7 +362,7 @@ EslSocketDestroyChild ( EFI_STATUS EslSocketBind ( IN EFI_SOCKET_PROTOCOL * pSocketProtocol, - IN const struct sockaddr * pSockAddr, + IN CONST struct sockaddr * pSockAddr, IN socklen_t SockAddrLength, OUT int * pErrno ); @@ -339,9 +370,14 @@ EslSocketBind ( /** Determine if the socket is closed - Reverses the operations of the ::SocketAllocate() routine. + This routine checks the state of the socket to determine if + the network specific layer has completed the close operation. + + The ::close routine polls this routine to determine when the + close operation is complete. The close operation needs to + reverse the operations of the ::EslSocketAllocate routine. - @param [in] pSocketProtocol Address of the 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 @@ -359,11 +395,19 @@ EslSocketClosePoll ( /** Start the close operation on the socket - Start closing the socket by closing all of the ports. Upon - completion, the ::SocketPoll() routine finishes closing the - socket. + This routine calls the network specific layer to initiate the + close state machine. This routine then calls the network + specific layer to determine if the close state machine has gone + to completion. The result from this poll is returned to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::close routine calls this routine to start the close + operation which reverses the operations of the + ::EslSocketAllocate routine. The close routine then polls + the ::EslSocketClosePoll routine to determine when the + socket is closed. + + @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. @@ -383,35 +427,23 @@ EslSocketCloseStart ( /** Connect to a remote system via the network. - The ::SocketConnect routine attempts to establish a connection to a - socket on the local or remote system using the specified address. - The POSIX - connect - documentation is available online. - - There are three states associated with a connection: -
    -
  • Not connected
    • -
  • Connection in progress
    • -
  • Connected
    • -
- In the "Not connected" state, calls to ::connect start the connection - processing and update the state to "Connection in progress". During - the "Connection in progress" state, connect polls for connection completion - and moves the state to "Connected" after the connection is established. - Note that these states are only visible when the file descriptor is marked - with O_NONBLOCK. Also, the POLL_WRITE bit is set when the connection - completes and may be used by poll or select as an indicator to call - connect again. - - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to establish + the remote system address and establish the connection to + the remote system. - @param [in] pSockAddr Network address of the remote system. + The ::connect routine calls this routine to establish a + connection with the specified remote system. This routine + is designed to be polled by the connect routine for completion + of the network connection. + + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. + @param [in] pSockAddr Network address of the remote system. + @param [in] SockAddrLength Length in bytes of the network address. - + @param [out] pErrno Address to receive the errno value upon completion. - + @retval EFI_SUCCESS The connection was successfully established. @retval EFI_NOT_READY The connection is in progress, call this routine again. @retval Others The connection attempt failed. @@ -428,8 +460,14 @@ EslSocketConnect ( /** Get the local address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the network + address of the local host connection point. + The ::getsockname routine calls this routine to obtain the network + address associated with the local host connection point. + + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. + @param [out] pAddress Network address to receive the local system address @param [in,out] pAddressLength Length of the local network address structure @@ -450,8 +488,14 @@ EslSocketGetLocalAddress ( /** Get the peer address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the remote + system connection point. + + The ::getpeername routine calls this routine to obtain the network + address of the remote connection point. + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. + @param [out] pAddress Network address to receive the remote system address @param [in,out] pAddressLength Length of the remote network address structure @@ -472,14 +516,18 @@ EslSocketGetPeerAddress ( /** Establish the known port to listen for network connections. - The ::SocketListen routine places the port into a state that enables connection - attempts. Connections are placed into FIFO order in a queue to be serviced - by the application. The application calls the ::SocketAccept routine to remove - the next connection from the queue and get the associated socket. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls into the network protocol layer to establish + a handler that is called upon connection completion. The handler + is responsible for inserting the connection into the FIFO. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::listen routine indirectly calls this routine to place the + socket into a state that enables connection attempts. Connections + are placed in a FIFO that is serviced by the application. The + application calls the ::accept (::EslSocketAccept) routine to + remove the next connection from the FIFO and get the associated + socket and address. + + @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 @@ -502,17 +550,19 @@ EslSocketListen ( /** Get the socket options - Retrieve the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. - @param [in] pSocketProtocol Address of the socket protocol structure. - @param [in] level Option protocol level - @param [in] option_name Name of the option - @param [out] option_value Buffer to receive the option value - @param [in,out] option_len Length of the buffer in bytes, - upon return length of the option value in bytes - @param [out] pErrno Address to receive the errno value upon completion. + The ::getsockopt routine calls this routine to retrieve the + socket options one at a time by name. + + @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 + @param [in,out] pOptionLength Length of the buffer in bytes, + upon return length of the option value in bytes + @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket data successfully received @@ -530,18 +580,20 @@ EslSocketOptionGet ( /** Set the socket options - Adjust the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. + + The ::setsockopt routine calls this routine to adjust the socket + options one at a time by name. - @param [in] pSocketProtocol Address of the socket protocol structure. + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. @param [in] level Option protocol level - @param [in] option_name Name of the option - @param [in] option_value Buffer containing the option value - @param [in] option_len Length of the buffer in bytes + @param [in] OptionName Name of the option + @param [in] pOptionValue Buffer containing the option value + @param [in] OptionLength Length of the buffer in bytes @param [out] pErrno Address to receive the errno value upon completion. - @retval EFI_SUCCESS - Socket data successfully received + @retval EFI_SUCCESS - Option successfully set **/ EFI_STATUS @@ -557,10 +609,14 @@ EslSocketOptionSet ( /** Poll a socket for pending activity. - The SocketPoll routine checks a socket for pending activity associated - with the event mask. Activity is returned in the detected event buffer. + This routine builds a detected event mask which is returned to + the caller in the buffer provided. + + The ::poll routine calls this routine to determine if the socket + needs to be serviced as a result of connection, error, receive or + transmit activity. - @param [in] pSocketProtocol Address of the socket protocol structure. + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. @param [in] Events Events of interest for this socket @@ -583,15 +639,22 @@ EslSocketPoll ( /** Receive data from a network connection. + This routine calls the network specific routine to remove the + next portion of data from the receive queue and return it to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::recvfrom routine calls this routine to determine if any data + 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 an ::EFI_SOCKET_PROTOCOL structure. + @param [in] Flags Message control flags - + @param [in] BufferLength Length of the the buffer - + @param [in] pBuffer Address of a buffer to receive the data. - + @param [in] pDataLength Number of received data bytes in the buffer. @param [out] pAddress Network address to receive the remote system address @@ -618,13 +681,16 @@ EslSocketReceive ( /** Shutdown the socket receive and transmit operations - The SocketShutdown routine stops the socket receive and transmit - operations. + This routine sets a flag to stop future transmissions and calls + the network specific layer to cancel the pending receive operation. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::shutdown routine calls this routine to stop receive and transmit + operations on the socket. + @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. + @param [in] How Which operations to stop - + @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket operations successfully shutdown @@ -640,17 +706,23 @@ EslSocketShutdown ( /** Send data using a network connection. - The SocketTransmit routine queues the data for transmission to the - remote network connection. + This routine calls the network specific layer to queue the data + for transmission. Eventually the buffer will reach the head of + the queue and will get transmitted over the network. For datagram + sockets there is no guarantee that the data reaches the application + running on the remote system. - @param [in] pSocketProtocol Address of the socket protocol structure. + 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 an ::EFI_SOCKET_PROTOCOL structure. + @param [in] Flags Message control flags - + @param [in] BufferLength Length of the the buffer - + @param [in] pBuffer Address of a buffer containing the data to send - + @param [in] pDataLength Address to receive the number of data bytes sent @param [in] pAddress Network address of the remote system address @@ -659,7 +731,7 @@ EslSocketShutdown ( @param [out] pErrno Address to receive the errno value upon completion. - @retval EFI_SUCCESS - Socket data successfully received + @retval EFI_SUCCESS - Socket data successfully queued for transmit **/ EFI_STATUS diff --git a/StdLib/Include/Protocol/EfiSocket.h b/StdLib/Include/Protocol/EfiSocket.h index e9e4604048..2664f01bdb 100644 --- a/StdLib/Include/Protocol/EfiSocket.h +++ b/StdLib/Include/Protocol/EfiSocket.h @@ -27,6 +27,9 @@ // Data Types //------------------------------------------------------------------------------ +/** +EfiSocketLib (SocketDxe) interface +**/ typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL; /** @@ -45,11 +48,11 @@ EFI_STATUS // Data //------------------------------------------------------------------------------ -extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; -extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; +extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; ///< Constructor address for EslSocketLib +extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; ///< Destructor address for EslSocketLib -extern EFI_GUID gEfiSocketProtocolGuid; -extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; +extern EFI_GUID gEfiSocketProtocolGuid; ///< Socket protocol GUID +extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; ///< Socket layer service binding protocol GUID //------------------------------------------------------------------------------ // Socket API @@ -58,11 +61,16 @@ extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; /** Accept a network connection. - The SocketAccept routine waits for a network connection to the socket. - It is able to return the remote network address to the caller if - requested. + This routine calls the network specific layer to remove the next + connection from the FIFO. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::accept calls this routine to poll for a network + connection to the socket. When a connection is available + this routine returns the ::EFI_SOCKET_PROTOCOL structure address + associated with the new socket and the remote network address + if requested. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] pSockAddr Address of a buffer to receive the remote network address. @@ -71,8 +79,9 @@ extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; On output specifies the length of the remote network address. - @param [out] ppSocketProtocol Address of a buffer to receive the socket protocol - instance associated with the new socket. + @param [out] ppSocketProtocol Address of a buffer to receive the + ::EFI_SOCKET_PROTOCOL instance + associated with the new socket. @param [out] pErrno Address to receive the errno value upon completion. @@ -93,11 +102,13 @@ EFI_STATUS /** Bind a name to a socket. - The ::SocketBind routine connects a name to a socket on the local machine. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls the network specific layer to save the network + address of the local connection point. - @param [in] pSocketProtocol Address of the socket protocol structure. + 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] pSockAddr Address of a sockaddr structure that contains the connection point on the local machine. An IPv4 address @@ -128,9 +139,14 @@ EFI_STATUS /** Determine if the socket is closed - Reverses the operations of the ::SocketAllocate() routine. + This routine checks the state of the socket to determine if + the network specific layer has completed the close operation. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::close routine polls this routine to determine when the + 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 [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS Socket successfully closed @@ -149,11 +165,19 @@ EFI_STATUS /** Start the close operation on the socket - Start closing the socket by closing all of the ports. Upon - completion, the ::pfnClosePoll() routine finishes closing the - socket. + This routine calls the network specific layer to initiate the + close state machine. This routine then calls the network + specific layer to determine if the close state machine has gone + to completion. The result from this poll is returned to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::close routine calls this routine to start the close + operation which reverses the operations of the + ::EslSocketAllocate routine. The close routine then polls + the ::EslSocketClosePoll routine to determine when the + socket is closed. + + @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. @param [in] bCloseNow Boolean to control close behavior @param [out] pErrno Address to receive the errno value upon completion. @@ -174,35 +198,23 @@ EFI_STATUS /** Connect to a remote system via the network. - The ::Connect routine attempts to establish a connection to a - socket on the local or remote system using the specified address. - The - POSIX - documentation is available online. - - There are three states associated with a connection: -
    -
  • Not connected
    • -
  • Connection in progress
    • -
  • Connected
    • -
- In the "Not connected" state, calls to ::connect start the connection - processing and update the state to "Connection in progress". During - the "Connection in progress" state, connect polls for connection completion - and moves the state to "Connected" after the connection is established. - Note that these states are only visible when the file descriptor is marked - with O_NONBLOCK. Also, the POLL_WRITE bit is set when the connection - completes and may be used by poll or select as an indicator to call - connect again. + This routine calls the network specific layer to establish + the remote system address and establish the connection to + the remote system. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::connect routine calls this routine to establish a + connection with the specified remote system. This routine + 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] pSockAddr Network address of the remote system. - + @param [in] SockAddrLength Length in bytes of the network address. - + @param [out] pErrno Address to receive the errno value upon completion. - + @retval EFI_SUCCESS The connection was successfully established. @retval EFI_NOT_READY The connection is in progress, call this routine again. @retval Others The connection attempt failed. @@ -220,8 +232,14 @@ EFI_STATUS /** Get the local address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the network + address of the local host connection point. + 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 [out] pAddress Network address to receive the local system address @param [in,out] pAddressLength Length of the local network address structure @@ -243,8 +261,14 @@ EFI_STATUS /** Get the peer address. - @param [in] pSocketProtocol Address of the socket protocol structure. + This routine calls the network specific layer to get the remote + system connection point. + 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 [out] pAddress Network address to receive the remote system address @param [in,out] pAddressLength Length of the remote network address structure @@ -266,12 +290,16 @@ EFI_STATUS /** Establish the known port to listen for network connections. - The ::SocketAisten routine places the port into a state that enables connection - attempts. Connections are placed into FIFO order in a queue to be serviced - by the application. The application calls the ::SocketAccept routine to remove - the next connection from the queue and get the associated socket. The - POSIX - documentation for the bind routine is available online for reference. + This routine calls into the network protocol layer to establish + a handler that is called upon connection completion. The handler + is responsible for inserting the connection into the FIFO. + + The ::listen routine indirectly calls this routine to place the + socket into a state that enables connection attempts. Connections + are placed in a FIFO that is serviced by the application. The + application calls the ::accept (::EslSocketAccept) routine to + remove the next connection from the FIFO and get the associated + socket and address. @param [in] pSocketProtocol Address of the socket protocol structure. @@ -297,11 +325,13 @@ EFI_STATUS /** Get the socket options - Retrieve the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. + + The ::getsockopt routine calls this routine to retrieve the + socket options one at a time by name. - @param [in] pSocketProtocol Address of the socket protocol structure. + @param [in] pSocketProtocol Address of the ::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 @@ -326,18 +356,20 @@ EFI_STATUS /** Set the socket options - Adjust the socket options one at a time by name. The - POSIX - documentation is available online. + This routine handles the socket level options and passes the + others to the network specific layer. - @param [in] pSocketProtocol Address of the socket protocol structure. + 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] level Option protocol level @param [in] OptionName Name of the option @param [in] pOptionValue Buffer containing the option value @param [in] OptionLength Length of the buffer in bytes @param [out] pErrno Address to receive the errno value upon completion. - @retval EFI_SUCCESS - Socket data successfully received + @retval EFI_SUCCESS - Option successfully set **/ typedef @@ -354,10 +386,14 @@ EFI_STATUS /** Poll a socket for pending activity. - The SocketPoll routine checks a socket for pending activity associated - with the event mask. Activity is returned in the detected event buffer. + This routine builds a detected event mask which is returned to + the caller in the buffer provided. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::poll routine calls this routine to determine if the socket + 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] Events Events of interest for this socket @@ -381,19 +417,22 @@ EFI_STATUS /** Receive data from a network connection. - The ::recv routine waits for receive data from a remote network - connection. The - POSIX - documentation is available online. + This routine calls the network specific routine to remove the + next portion of data from the receive queue and return it to the + caller. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::recvfrom routine calls this routine to determine if any data + 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] Flags Message control flags - + @param [in] BufferLength Length of the the buffer - + @param [in] pBuffer Address of a buffer to receive the data. - + @param [in] pDataLength Number of received data bytes in the buffer. @param [out] pAddress Network address to receive the remote system address @@ -418,54 +457,19 @@ EFI_STATUS IN int * pErrno ); -/** - Send data using a network connection. - - The SocketTransmit routine queues the data for transmission to the - remote network connection. - - @param [in] pSocketProtocol Address of the socket protocol structure. - - @param [in] Flags Message control flags - - @param [in] BufferLength Length of the the buffer - - @param [in] pBuffer Address of a buffer containing the data to send - - @param [in] pDataLength Address to receive the number of data bytes sent - - @param [in] pAddress Network address of the remote system address - - @param [in] AddressLength Length of the remote network address structure - - @param [out] pErrno Address to receive the errno value upon completion. - - @retval EFI_SUCCESS - Socket data successfully queued for transmission - - **/ -typedef -EFI_STATUS -(* PFN_SEND) ( - IN EFI_SOCKET_PROTOCOL * pSocketProtocol, - IN int Flags, - IN size_t BufferLength, - IN CONST UINT8 * pBuffer, - OUT size_t * pDataLength, - IN const struct sockaddr * pAddress, - IN socklen_t AddressLength, - IN int * pErrno - ); - /** Shutdown the socket receive and transmit operations - The SocketShutdown routine stops the socket receive and transmit - operations. + This routine sets a flag to stop future transmissions and calls + the network specific layer to cancel the pending receive operation. - @param [in] pSocketProtocol Address of the socket protocol structure. + 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] How Which operations to stop - + @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket operations successfully shutdown @@ -482,40 +486,18 @@ EFI_STATUS /** Initialize an endpoint for network communication. - The ::Socket routine initializes the communication endpoint by providing - the support for the socket library function ::socket. The - POSIX - documentation for the socket routine is available online for reference. + This routine initializes the communication endpoint. - @param [in] pSocketProtocol Address of the socket protocol structure. + The ::socket routine calls this routine indirectly to create + the communication endpoint. + @param [in] pSocketProtocol Address of the socket protocol structure. @param [in] domain Select the family of protocols for the client or server - application. - - @param [in] type Specifies how to make the network connection. The following values - are supported: -
    -
  • - SOCK_STREAM - Connect to TCP, provides a byte stream - that is manipluated by read, recv, send and write. -
    • -
  • - SOCK_SEQPACKET - Connect to TCP, provides sequenced packet stream - that is manipulated by read, recv, send and write. -
    • -
  • - SOCK_DGRAM - Connect to UDP, provides a datagram service that is - manipulated by recvfrom and sendto. -
    • -
- - @param [in] protocol Specifies the lower layer protocol to use. The following - values are supported: -
    -
  • IPPROTO_TCP
    • - This value must be combined with SOCK_STREAM. -
  • IPPROTO_UDP
    • - This value must be combined with SOCK_DGRAM. -
- + application. See the ::socket documentation for values. + @param [in] type Specifies how to make the network connection. + See the ::socket documentation for values. + @param [in] protocol Specifies the lower layer protocol to use. + See the ::socket documentation for values. @param [out] pErrno Address to receive the errno value upon completion. @retval EFI_SUCCESS - Socket successfully created @@ -534,6 +516,50 @@ EFI_STATUS IN int * pErrno ); +/** + Send data using a network connection. + + This routine calls the network specific layer to queue the data + for transmission. Eventually the buffer will reach the head of + the queue and will get transmitted over the network. For datagram + sockets there is no guarantee that the data reaches the application + running on the remote system. + + 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] Flags Message control flags + + @param [in] BufferLength Length of the the buffer + + @param [in] pBuffer Address of a buffer containing the data to send + + @param [in] pDataLength Address to receive the number of data bytes sent + + @param [in] pAddress Network address of the remote system address + + @param [in] AddressLength Length of the remote network address structure + + @param [out] pErrno Address to receive the errno value upon completion. + + @retval EFI_SUCCESS - Socket data successfully queued for transmit + + **/ +typedef +EFI_STATUS +(* PFN_TRANSMIT) ( + IN EFI_SOCKET_PROTOCOL * pSocketProtocol, + IN int Flags, + IN size_t BufferLength, + IN CONST UINT8 * pBuffer, + OUT size_t * pDataLength, + IN const struct sockaddr * pAddress, + IN socklen_t AddressLength, + IN int * pErrno + ); + //------------------------------------------------------------------------------ // Socket Protocol //------------------------------------------------------------------------------ @@ -551,13 +577,13 @@ typedef struct _EFI_SOCKET_PROTOCOL { PFN_GET_LOCAL pfnGetLocal; ///< Get local address PFN_GET_PEER pfnGetPeer; ///< Get peer address PFN_LISTEN pfnListen; ///< Enable connection attempts on known port - PFN_POLL pfnPoll; ///< Poll for socket activity PFN_OPTION_GET pfnOptionGet; ///< Get socket options PFN_OPTION_SET pfnOptionSet; ///< Set socket options + PFN_POLL pfnPoll; ///< Poll for socket activity PFN_RECEIVE pfnReceive; ///< Receive data from a socket - PFN_SEND pfnSend; ///< Transmit data using the socket PFN_SHUTDOWN pfnShutdown; ///< Shutdown receive and transmit operations PFN_SOCKET pfnSocket; ///< Initialize the socket + PFN_TRANSMIT pfnTransmit; ///< Transmit data using the socket } GCC_EFI_SOCKET_PROTOCOL; //------------------------------------------------------------------------------ @@ -565,9 +591,7 @@ typedef struct _EFI_SOCKET_PROTOCOL { //------------------------------------------------------------------------------ /** - Non blocking version of accept. - - See ::accept + Non blocking version of ::accept. @param [in] s Socket file descriptor returned from ::socket. @@ -578,7 +602,7 @@ typedef struct _EFI_SOCKET_PROTOCOL { contains the length of the remote network address. @return This routine returns zero if successful and -1 when an error occurs. - In the case of an error, errno contains more details. + In the case of an error, ::errno contains more details. **/ int @@ -589,12 +613,12 @@ AcceptNB ( ); /** - Connect to the socket driver + Connect to the EFI socket library @param [in] ppSocketProtocol Address to receive the socket protocol address - @retval 0 Successfully returned the socket protocol - @retval other Value for errno + @return Value for ::errno, zero (0) indicates success. + **/ int EslServiceGetProtocol ( -- cgit v1.2.3