2 Definitions for the EFI Socket layer library.
4 Copyright (c) 2011 - 2015, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef _EFI_SOCKET_LIB_H_
16 #define _EFI_SOCKET_LIB_H_
20 #include <Library/BaseMemoryLib.h>
21 #include <Library/DebugLib.h>
22 #include <Library/MemoryAllocationLib.h>
23 #include <Library/UefiBootServicesTableLib.h>
24 #include <Library/UefiLib.h>
26 #include <Protocol/EfiSocket.h>
27 #include <Protocol/Ip4Config2.h>
28 #include <Protocol/Ip6Config.h>
29 #include <Protocol/ServiceBinding.h>
30 #include <Protocol/Tcp4.h>
31 #include <Protocol/Tcp6.h>
32 #include <Protocol/Udp4.h>
33 #include <Protocol/Udp6.h>
37 //------------------------------------------------------------------------------
39 //------------------------------------------------------------------------------
41 #define DEBUG_TPL 0x40000000 ///< Display TPL change messages
43 #define TPL_SOCKETS TPL_CALLBACK ///< TPL for routine synchronization
45 //------------------------------------------------------------------------------
47 //------------------------------------------------------------------------------
49 #if defined(_MSC_VER) /* Handle Microsoft VC++ compiler specifics. */
50 #define DBG_ENTER() DEBUG (( DEBUG_INFO, "Entering " __FUNCTION__ "\n" )) ///< Display routine entry
51 #define DBG_EXIT() DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ "\n" )) ///< Display routine exit
52 #define DBG_EXIT_DEC(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: %d\n", Status )) ///< Display routine exit with decimal value
53 #define DBG_EXIT_HEX(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: 0x%08x\n", Status )) ///< Display routine exit with hex value
54 #define DBG_EXIT_STATUS(Status) DEBUG (( DEBUG_INFO, "Exiting " __FUNCTION__ ", Status: %r\n", Status )) ///< Display routine exit with status value
55 #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
57 #define DBG_ENTER() ///< Display routine entry
58 #define DBG_EXIT() ///< Display routine exit
59 #define DBG_EXIT_DEC(Status) ///< Display routine exit with decimal value
60 #define DBG_EXIT_HEX(Status) ///< Display routine exit with hex value
61 #define DBG_EXIT_STATUS(Status) ///< Display routine exit with status value
62 #define DBG_EXIT_TF(Status) ///< Display routine with TRUE/FALSE value
65 #define DIM(x) ( sizeof ( x ) / sizeof ( x[0] )) ///< Compute the number of entries in an array
70 This macro which is enabled when debug is enabled verifies that
71 the new TPL value is >= the current TPL value.
77 #if !defined(MDEPKG_NDEBUG)
80 Verify that the TPL is at the correct level
82 #define VERIFY_AT_TPL(tpl) \
84 EFI_TPL PreviousTpl; \
86 PreviousTpl = EfiGetCurrentTpl ( ); \
87 if ( PreviousTpl != tpl ) { \
88 DEBUG (( DEBUG_ERROR | DEBUG_TPL, \
89 "Current TPL: %d, New TPL: %d\r\n", \
90 PreviousTpl, tpl )); \
91 ASSERT ( PreviousTpl == tpl ); \
95 #define VERIFY_TPL(tpl) \
97 EFI_TPL PreviousTpl; \
99 PreviousTpl = EfiGetCurrentTpl ( ); \
100 if ( PreviousTpl > tpl ) { \
101 DEBUG (( DEBUG_ERROR | DEBUG_TPL, \
102 "Current TPL: %d, New TPL: %d\r\n", \
103 PreviousTpl, tpl )); \
104 ASSERT ( PreviousTpl <= tpl ); \
108 #else // MDEPKG_NDEBUG
110 #define VERIFY_AT_TPL(tpl) ///< Verify that the TPL is at the correct level
111 #define VERIFY_TPL(tpl) ///< Verify that the TPL is at the correct level
113 #endif // MDEPKG_NDEBUG
116 Raise TPL to the specified level
118 #define RAISE_TPL(PreviousTpl, tpl) \
119 VERIFY_TPL ( tpl ); \
120 PreviousTpl = gBS->RaiseTPL ( tpl );
123 Restore the TPL to the previous value
125 #define RESTORE_TPL(tpl) \
126 gBS->RestoreTPL ( tpl )
128 //------------------------------------------------------------------------------
130 //------------------------------------------------------------------------------
132 typedef struct _ESL_SERVICE ESL_SERVICE
; ///< Forward delcaration
135 Protocol binding and installation control structure
137 The driver uses this structure to simplify the driver binding processing.
140 CHAR16
* pName
; ///< Protocol name
141 EFI_GUID
* pNetworkBinding
; ///< Network service binding protocol for socket support
142 EFI_GUID
* pNetworkProtocolGuid
;///< Network protocol GUID
143 CONST EFI_GUID
* pTagGuid
; ///< Tag to mark protocol in use
144 UINTN ServiceListOffset
; ///< Offset in ::ESL_LAYER for the list of services
145 UINTN RxIo
; ///< Number of receive ESL_IO_MGMT structures for data
146 UINTN TxIoNormal
; ///< Number of transmit ESL_IO_MGMT structures for normal data
147 UINTN TxIoUrgent
; ///< Number of transmit ESL_IO_MGMT structures for urgent data
148 } ESL_SOCKET_BINDING
;
150 //------------------------------------------------------------------------------
152 //------------------------------------------------------------------------------
154 extern CONST EFI_GUID mEslIp4ServiceGuid
; ///< Tag GUID for the IPv4 layer
155 extern CONST EFI_GUID mEslIp6ServiceGuid
; ///< Tag GUID for the IPv6 layer
156 extern CONST EFI_GUID mEslTcp4ServiceGuid
; ///< Tag GUID for the TCPv4 layer
157 extern CONST EFI_GUID mEslTcp6ServiceGuid
; ///< Tag GUID for the TCPv6 layer
158 extern CONST EFI_GUID mEslUdp4ServiceGuid
; ///< Tag GUID for the UDPv4 layer
159 extern CONST EFI_GUID mEslUdp6ServiceGuid
; ///< Tag GUID for the UDPv6 layer
161 //------------------------------------------------------------------------------
163 //------------------------------------------------------------------------------
165 extern CONST ESL_SOCKET_BINDING cEslSocketBinding
[];///< List of network service bindings
166 extern CONST UINTN cEslSocketBindingEntries
; ///< Number of network service bindings
168 //------------------------------------------------------------------------------
169 // DXE Support Routines
170 //------------------------------------------------------------------------------
173 Creates a child handle and installs a protocol.
175 When the socket application is linked against UseSocketDxe, the ::socket
176 routine indirectly calls this routine in SocketDxe to create a child
177 handle if necessary and install the socket protocol on the handle.
178 Upon return, EslServiceGetProtocol in UseSocketLib returns the
179 ::EFI_SOCKET_PROTOCOL address to the socket routine.
181 @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
182 @param [in] pChildHandle Pointer to the handle of the child to create. If it is NULL,
183 then a new handle is created. If it is a pointer to an existing UEFI handle,
184 then the protocol is added to the existing UEFI handle.
186 @retval EFI_SUCCESS The protocol was added to ChildHandle.
187 @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
188 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create
190 @retval other The child handle was not created
196 IN EFI_SERVICE_BINDING_PROTOCOL
* pThis
,
197 IN OUT EFI_HANDLE
* pChildHandle
201 Destroys a child handle with a protocol installed on it.
203 When the socket application is linked against UseSocketDxe, the ::close
204 routine indirectly calls this routine in SocketDxe to undo the operations
205 done by the ::EslDxeCreateChild routine. This routine removes the socket
206 protocol from the handle and then destroys the child handle if there are
207 no other protocols attached.
209 @param [in] pThis Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
210 @param [in] ChildHandle Handle of the child to destroy
212 @retval EFI_SUCCESS The protocol was removed from ChildHandle.
213 @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed.
214 @retval EFI_INVALID_PARAMETER Child handle is not a valid UEFI Handle.
215 @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle
216 because its services are being used.
217 @retval other The child handle was not destroyed
223 IN EFI_SERVICE_BINDING_PROTOCOL
* pThis
,
224 IN EFI_HANDLE ChildHandle
228 Install the socket service
230 SocketDxe uses this routine to announce the socket interface to
233 @param [in] pImageHandle Address of the image handle
235 @retval EFI_SUCCESS Service installed successfully
240 IN EFI_HANDLE
* pImageHandle
244 Uninstall the socket service
246 SocketDxe uses this routine to notify EFI that the socket layer
247 is no longer available.
249 @param [in] ImageHandle Handle for the image.
251 @retval EFI_SUCCESS Service installed successfully
256 IN EFI_HANDLE ImageHandle
259 //------------------------------------------------------------------------------
260 // Service Support Routines
261 //------------------------------------------------------------------------------
264 Connect to the network service bindings
266 Walk the network service protocols on the controller handle and
267 locate any that are not in use. Create ::ESL_SERVICE structures to
268 manage the network layer interfaces for the socket driver. Tag
269 each of the network interfaces that are being used. Finally, this
270 routine calls ESL_SOCKET_BINDING::pfnInitialize to prepare the network
271 interface for use by the socket layer.
273 @param [in] BindingHandle Handle for protocol binding.
274 @param [in] Controller Handle of device to work with.
276 @retval EFI_SUCCESS This driver is added to Controller.
277 @retval other This driver does not support this device.
283 IN EFI_HANDLE BindingHandle
,
284 IN EFI_HANDLE Controller
288 Shutdown the connections to the network layer by locating the
289 tags on the network interfaces established by ::EslServiceConnect.
290 This routine calls ESL_SOCKET_BINDING::pfnShutdown to shutdown the any
291 activity on the network interface and then free the ::ESL_SERVICE
294 @param [in] BindingHandle Handle for protocol binding.
295 @param [in] Controller Handle of device to stop driver on.
297 @retval EFI_SUCCESS This driver is removed Controller.
298 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
299 @retval other This driver was not removed from this device.
304 EslServiceDisconnect (
305 IN EFI_HANDLE BindingHandle
,
306 IN EFI_HANDLE Controller
310 Initialize the service layer
312 @param [in] ImageHandle Handle for the image.
318 IN EFI_HANDLE ImageHandle
322 Shutdown the service layer
331 //------------------------------------------------------------------------------
332 // Socket Protocol Routines
333 //------------------------------------------------------------------------------
336 Bind a name to a socket.
338 This routine calls the network specific layer to save the network
339 address of the local connection point.
341 The ::bind routine calls this routine to connect a name
342 (network address and port) to a socket on the local machine.
344 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
346 @param [in] pSockAddr Address of a sockaddr structure that contains the
347 connection point on the local machine. An IPv4 address
348 of INADDR_ANY specifies that the connection is made to
349 all of the network stacks on the platform. Specifying a
350 specific IPv4 address restricts the connection to the
351 network stack supporting that address. Specifying zero
352 for the port causes the network layer to assign a port
353 number from the dynamic range. Specifying a specific
354 port number causes the network layer to use that port.
356 @param [in] SockAddrLength Specifies the length in bytes of the sockaddr structure.
358 @param [out] pErrno Address to receive the errno value upon completion.
360 @retval EFI_SUCCESS - Socket successfully created
365 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
366 IN CONST
struct sockaddr
* pSockAddr
,
367 IN socklen_t SockAddrLength
,
372 Determine if the socket is closed
374 This routine checks the state of the socket to determine if
375 the network specific layer has completed the close operation.
377 The ::close routine polls this routine to determine when the
378 close operation is complete. The close operation needs to
379 reverse the operations of the ::EslSocketAllocate routine.
381 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
382 @param [out] pErrno Address to receive the errno value upon completion.
384 @retval EFI_SUCCESS Socket successfully closed
385 @retval EFI_NOT_READY Close still in progress
386 @retval EFI_ALREADY Close operation already in progress
387 @retval Other Failed to close the socket
392 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
397 Start the close operation on the socket
399 This routine calls the network specific layer to initiate the
400 close state machine. This routine then calls the network
401 specific layer to determine if the close state machine has gone
402 to completion. The result from this poll is returned to the
405 The ::close routine calls this routine to start the close
406 operation which reverses the operations of the
407 ::EslSocketAllocate routine. The close routine then polls
408 the ::EslSocketClosePoll routine to determine when the
411 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
412 @param [in] bCloseNow Boolean to control close behavior
413 @param [out] pErrno Address to receive the errno value upon completion.
415 @retval EFI_SUCCESS Socket successfully closed
416 @retval EFI_NOT_READY Close still in progress
417 @retval EFI_ALREADY Close operation already in progress
418 @retval Other Failed to close the socket
422 EslSocketCloseStart (
423 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
424 IN BOOLEAN bCloseNow
,
429 Connect to a remote system via the network.
431 This routine calls the network specific layer to establish
432 the remote system address and establish the connection to
435 The ::connect routine calls this routine to establish a
436 connection with the specified remote system. This routine
437 is designed to be polled by the connect routine for completion
438 of the network connection.
440 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
442 @param [in] pSockAddr Network address of the remote system.
444 @param [in] SockAddrLength Length in bytes of the network address.
446 @param [out] pErrno Address to receive the errno value upon completion.
448 @retval EFI_SUCCESS The connection was successfully established.
449 @retval EFI_NOT_READY The connection is in progress, call this routine again.
450 @retval Others The connection attempt failed.
455 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
456 IN
const struct sockaddr
* pSockAddr
,
457 IN socklen_t SockAddrLength
,
462 Get the local address.
464 This routine calls the network specific layer to get the network
465 address of the local host connection point.
467 The ::getsockname routine calls this routine to obtain the network
468 address associated with the local host connection point.
470 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
472 @param [out] pAddress Network address to receive the local system address
474 @param [in,out] pAddressLength Length of the local network address structure
476 @param [out] pErrno Address to receive the errno value upon completion.
478 @retval EFI_SUCCESS - Local address successfully returned
482 EslSocketGetLocalAddress (
483 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
484 OUT
struct sockaddr
* pAddress
,
485 IN OUT socklen_t
* pAddressLength
,
490 Get the peer address.
492 This routine calls the network specific layer to get the remote
493 system connection point.
495 The ::getpeername routine calls this routine to obtain the network
496 address of the remote connection point.
498 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
500 @param [out] pAddress Network address to receive the remote system address
502 @param [in,out] pAddressLength Length of the remote network address structure
504 @param [out] pErrno Address to receive the errno value upon completion.
506 @retval EFI_SUCCESS - Remote address successfully returned
510 EslSocketGetPeerAddress (
511 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
512 OUT
struct sockaddr
* pAddress
,
513 IN OUT socklen_t
* pAddressLength
,
518 Establish the known port to listen for network connections.
520 This routine calls into the network protocol layer to establish
521 a handler that is called upon connection completion. The handler
522 is responsible for inserting the connection into the FIFO.
524 The ::listen routine indirectly calls this routine to place the
525 socket into a state that enables connection attempts. Connections
526 are placed in a FIFO that is serviced by the application. The
527 application calls the ::accept (::EslSocketAccept) routine to
528 remove the next connection from the FIFO and get the associated
531 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
533 @param [in] Backlog Backlog specifies the maximum FIFO depth for
534 the connections waiting for the application
535 to call accept. Connection attempts received
536 while the queue is full are refused.
538 @param [out] pErrno Address to receive the errno value upon completion.
540 @retval EFI_SUCCESS - Socket successfully created
541 @retval Other - Failed to enable the socket for listen
546 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
552 Get the socket options
554 This routine handles the socket level options and passes the
555 others to the network specific layer.
557 The ::getsockopt routine calls this routine to retrieve the
558 socket options one at a time by name.
560 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
561 @param [in] level Option protocol level
562 @param [in] OptionName Name of the option
563 @param [out] pOptionValue Buffer to receive the option value
564 @param [in,out] pOptionLength Length of the buffer in bytes,
565 upon return length of the option value in bytes
566 @param [out] pErrno Address to receive the errno value upon completion.
568 @retval EFI_SUCCESS - Socket data successfully received
573 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
576 OUT
void * __restrict option_value
,
577 IN OUT socklen_t
* __restrict option_len
,
582 Set the socket options
584 This routine handles the socket level options and passes the
585 others to the network specific layer.
587 The ::setsockopt routine calls this routine to adjust the socket
588 options one at a time by name.
590 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
591 @param [in] level Option protocol level
592 @param [in] OptionName Name of the option
593 @param [in] pOptionValue Buffer containing the option value
594 @param [in] OptionLength Length of the buffer in bytes
595 @param [out] pErrno Address to receive the errno value upon completion.
597 @retval EFI_SUCCESS - Option successfully set
602 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
605 IN CONST
void * option_value
,
606 IN socklen_t option_len
,
611 Poll a socket for pending activity.
613 This routine builds a detected event mask which is returned to
614 the caller in the buffer provided.
616 The ::poll routine calls this routine to determine if the socket
617 needs to be serviced as a result of connection, error, receive or
620 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
622 @param [in] Events Events of interest for this socket
624 @param [in] pEvents Address to receive the detected events
626 @param [out] pErrno Address to receive the errno value upon completion.
628 @retval EFI_SUCCESS - Socket successfully polled
629 @retval EFI_INVALID_PARAMETER - When pEvents is NULL
634 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
641 Receive data from a network connection.
643 This routine calls the network specific routine to remove the
644 next portion of data from the receive queue and return it to the
647 The ::recvfrom routine calls this routine to determine if any data
648 is received from the remote system. Note that the other routines
649 ::recv and ::read are layered on top of ::recvfrom.
651 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
653 @param [in] Flags Message control flags
655 @param [in] BufferLength Length of the the buffer
657 @param [in] pBuffer Address of a buffer to receive the data.
659 @param [in] pDataLength Number of received data bytes in the buffer.
661 @param [out] pAddress Network address to receive the remote system address
663 @param [in,out] pAddressLength Length of the remote network address structure
665 @param [out] pErrno Address to receive the errno value upon completion.
667 @retval EFI_SUCCESS - Socket data successfully received
672 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
674 IN
size_t BufferLength
,
676 OUT
size_t * pDataLength
,
677 OUT
struct sockaddr
* pAddress
,
678 IN OUT socklen_t
* pAddressLength
,
683 Shutdown the socket receive and transmit operations
685 This routine sets a flag to stop future transmissions and calls
686 the network specific layer to cancel the pending receive operation.
688 The ::shutdown routine calls this routine to stop receive and transmit
689 operations on the socket.
691 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
693 @param [in] How Which operations to stop
695 @param [out] pErrno Address to receive the errno value upon completion.
697 @retval EFI_SUCCESS - Socket operations successfully shutdown
702 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
708 Send data using a network connection.
710 This routine calls the network specific layer to queue the data
711 for transmission. Eventually the buffer will reach the head of
712 the queue and will get transmitted over the network. For datagram
713 sockets there is no guarantee that the data reaches the application
714 running on the remote system.
716 The ::sendto routine calls this routine to send data to the remote
717 system. Note that ::send and ::write are layered on top of ::sendto.
719 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure.
721 @param [in] Flags Message control flags
723 @param [in] BufferLength Length of the the buffer
725 @param [in] pBuffer Address of a buffer containing the data to send
727 @param [in] pDataLength Address to receive the number of data bytes sent
729 @param [in] pAddress Network address of the remote system address
731 @param [in] AddressLength Length of the remote network address structure
733 @param [out] pErrno Address to receive the errno value upon completion.
735 @retval EFI_SUCCESS - Socket data successfully queued for transmit
740 IN EFI_SOCKET_PROTOCOL
* pSocketProtocol
,
742 IN
size_t BufferLength
,
743 IN CONST UINT8
* pBuffer
,
744 OUT
size_t * pDataLength
,
745 IN
const struct sockaddr
* pAddress
,
746 IN socklen_t AddressLength
,
750 //------------------------------------------------------------------------------
752 #endif // _EFI_SOCKET_LIB_H_