diff options
| author | lpleahy <lpleahy@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-09-30 23:02:35 +0000 |
|---|---|---|
| committer | lpleahy <lpleahy@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-09-30 23:02:35 +0000 |
| commit | a88c31639bb24c73383a4528a5b77066e805148b (patch) | |
| tree | 058801cd8687b0a0c6f82459b56b2ad3beb43bf4 /StdLib/Include | |
| parent | df7499fcc1fbd6c825cabf19bbed379688416125 (diff) | |
| download | edk2-platforms-a88c31639bb24c73383a4528a5b77066e805148b.tar.xz | |
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
Diffstat (limited to 'StdLib/Include')
| -rw-r--r-- | StdLib/Include/Efi/EfiSocketLib.h | 456 | ||||
| -rw-r--r-- | StdLib/Include/Protocol/EfiSocket.h | 332 |
2 files changed, 442 insertions, 346 deletions
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 <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiLib.h>
@@ -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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html">connect</a>
- documentation is available online.
-
- There are three states associated with a connection:
- <ul>
- <li>Not connected</li>
- <li>Connection in progress</li>
- <li>Connected</li>
- </ul>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockopt.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html">POSIX</a>
- documentation is available online.
-
- There are three states associated with a connection:
- <ul>
- <li>Not connected</li>
- <li>Connection in progress</li>
- <li>Connected</li>
- </ul>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockopt.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html">POSIX</a>
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/recv.html">POSIX</a>
- 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
@@ -419,53 +458,18 @@ EFI_STATUS );
/**
- 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
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html">POSIX</a>
- 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:
- <ul>
- <li>
- SOCK_STREAM - Connect to TCP, provides a byte stream
- that is manipluated by read, recv, send and write.
- </li>
- <li>
- SOCK_SEQPACKET - Connect to TCP, provides sequenced packet stream
- that is manipulated by read, recv, send and write.
- </li>
- <li>
- SOCK_DGRAM - Connect to UDP, provides a datagram service that is
- manipulated by recvfrom and sendto.
- </li>
- </ul>
-
- @param [in] protocol Specifies the lower layer protocol to use. The following
- values are supported:
- <ul>
- <li>IPPROTO_TCP</li> - This value must be combined with SOCK_STREAM.</li>
- <li>IPPROTO_UDP</li> - This value must be combined with SOCK_DGRAM.</li>
- </ul>
-
+ 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 (
|