1 /** @file 2 Definitions for the EFI Socket protocol. 3 4 Copyright (c) 2011, 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.php 9 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. 12 13 **/ 14 15 #ifndef _EFI_SOCKET_H_ 16 #define _EFI_SOCKET_H_ 17 18 #include <errno.h> 19 #include <Uefi.h> 20 21 #include <netinet/in.h> 22 23 #include <sys/poll.h> 24 #include <sys/socket.h> 25 26 //------------------------------------------------------------------------------ 27 // Data Types 28 //------------------------------------------------------------------------------ 29 30 /** 31 EfiSocketLib (SocketDxe) interface 32 **/ 33 typedef struct _EFI_SOCKET_PROTOCOL EFI_SOCKET_PROTOCOL; 34 35 /** 36 Constructor/Destructor 37 38 @retval EFI_SUCCESS The operation was successful 39 40 **/ 41 typedef 42 EFI_STATUS 43 (* PFN_ESL_xSTRUCTOR) ( 44 VOID 45 ); 46 47 //------------------------------------------------------------------------------ 48 // Data 49 //------------------------------------------------------------------------------ 50 51 extern PFN_ESL_xSTRUCTOR mpfnEslConstructor; ///< Constructor address for EslSocketLib 52 extern PFN_ESL_xSTRUCTOR mpfnEslDestructor; ///< Destructor address for EslSocketLib 53 54 extern EFI_GUID gEfiSocketProtocolGuid; ///< Socket protocol GUID 55 extern EFI_GUID gEfiSocketServiceBindingProtocolGuid; ///< Socket layer service binding protocol GUID 56 57 //------------------------------------------------------------------------------ 58 // Socket API 59 //------------------------------------------------------------------------------ 60 61 /** 62 Accept a network connection. 63 64 This routine calls the network specific layer to remove the next 65 connection from the FIFO. 66 67 The ::accept calls this routine to poll for a network 68 connection to the socket. When a connection is available 69 this routine returns the ::EFI_SOCKET_PROTOCOL structure address 70 associated with the new socket and the remote network address 71 if requested. 72 73 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 74 75 @param [in] pSockAddr Address of a buffer to receive the remote 76 network address. 77 78 @param [in, out] pSockAddrLength Length in bytes of the address buffer. 79 On output specifies the length of the 80 remote network address. 81 82 @param [out] ppSocketProtocol Address of a buffer to receive the 83 ::EFI_SOCKET_PROTOCOL instance 84 associated with the new socket. 85 86 @param [out] pErrno Address to receive the errno value upon completion. 87 88 @retval EFI_SUCCESS New connection successfully created 89 @retval EFI_NOT_READY No connection is available 90 91 **/ 92 typedef 93 EFI_STATUS 94 (* PFN_ACCEPT) ( 95 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 96 IN struct sockaddr * pSockAddr, 97 IN OUT socklen_t * pSockAddrLength, 98 IN EFI_SOCKET_PROTOCOL ** ppSocketProtocol, 99 IN int * pErrno 100 ); 101 102 /** 103 Bind a name to a socket. 104 105 This routine calls the network specific layer to save the network 106 address of the local connection point. 107 108 The ::bind routine calls this routine to connect a name 109 (network address and port) to a socket on the local machine. 110 111 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 112 113 @param [in] pSockAddr Address of a sockaddr structure that contains the 114 connection point on the local machine. An IPv4 address 115 of INADDR_ANY specifies that the connection is made to 116 all of the network stacks on the platform. Specifying a 117 specific IPv4 address restricts the connection to the 118 network stack supporting that address. Specifying zero 119 for the port causes the network layer to assign a port 120 number from the dynamic range. Specifying a specific 121 port number causes the network layer to use that port. 122 123 @param [in] SockAddrLen Specifies the length in bytes of the sockaddr structure. 124 125 @param [out] pErrno Address to receive the errno value upon completion. 126 127 @retval EFI_SUCCESS - Socket successfully created 128 129 **/ 130 typedef 131 EFI_STATUS 132 (* PFN_BIND) ( 133 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 134 IN const struct sockaddr * pSockAddr, 135 IN socklen_t SockAddrLength, 136 OUT int * pErrno 137 ); 138 139 /** 140 Determine if the socket is closed 141 142 This routine checks the state of the socket to determine if 143 the network specific layer has completed the close operation. 144 145 The ::close routine polls this routine to determine when the 146 close operation is complete. The close operation needs to 147 reverse the operations of the ::EslSocketAllocate routine. 148 149 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 150 @param [out] pErrno Address to receive the errno value upon completion. 151 152 @retval EFI_SUCCESS Socket successfully closed 153 @retval EFI_NOT_READY Close still in progress 154 @retval EFI_ALREADY Close operation already in progress 155 @retval Other Failed to close the socket 156 157 **/ 158 typedef 159 EFI_STATUS 160 (* PFN_CLOSE_POLL) ( 161 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 162 IN int * pErrno 163 ); 164 165 /** 166 Start the close operation on the socket 167 168 This routine calls the network specific layer to initiate the 169 close state machine. This routine then calls the network 170 specific layer to determine if the close state machine has gone 171 to completion. The result from this poll is returned to the 172 caller. 173 174 The ::close routine calls this routine to start the close 175 operation which reverses the operations of the 176 ::EslSocketAllocate routine. The close routine then polls 177 the ::EslSocketClosePoll routine to determine when the 178 socket is closed. 179 180 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 181 @param [in] bCloseNow Boolean to control close behavior 182 @param [out] pErrno Address to receive the errno value upon completion. 183 184 @retval EFI_SUCCESS Socket successfully closed 185 @retval EFI_NOT_READY Close still in progress 186 @retval EFI_ALREADY Close operation already in progress 187 @retval Other Failed to close the socket 188 189 **/ 190 typedef 191 EFI_STATUS 192 (* PFN_CLOSE_START) ( 193 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 194 IN BOOLEAN bCloseNow, 195 IN int * pErrno 196 ); 197 198 /** 199 Connect to a remote system via the network. 200 201 This routine calls the network specific layer to establish 202 the remote system address and establish the connection to 203 the remote system. 204 205 The ::connect routine calls this routine to establish a 206 connection with the specified remote system. This routine 207 is designed to be polled by the connect routine for completion 208 of the network connection. 209 210 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 211 212 @param [in] pSockAddr Network address of the remote system. 213 214 @param [in] SockAddrLength Length in bytes of the network address. 215 216 @param [out] pErrno Address to receive the errno value upon completion. 217 218 @retval EFI_SUCCESS The connection was successfully established. 219 @retval EFI_NOT_READY The connection is in progress, call this routine again. 220 @retval Others The connection attempt failed. 221 222 **/ 223 typedef 224 EFI_STATUS 225 (* PFN_CONNECT) ( 226 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 227 IN const struct sockaddr * pSockAddr, 228 IN socklen_t SockAddrLength, 229 IN int * pErrno 230 ); 231 232 /** 233 Get the local address. 234 235 This routine calls the network specific layer to get the network 236 address of the local host connection point. 237 238 The ::getsockname routine calls this routine to obtain the network 239 address associated with the local host connection point. 240 241 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 242 243 @param [out] pAddress Network address to receive the local system address 244 245 @param [in,out] pAddressLength Length of the local network address structure 246 247 @param [out] pErrno Address to receive the errno value upon completion. 248 249 @retval EFI_SUCCESS - Local address successfully returned 250 251 **/ 252 typedef 253 EFI_STATUS 254 (* PFN_GET_LOCAL) ( 255 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 256 OUT struct sockaddr * pAddress, 257 IN OUT socklen_t * pAddressLength, 258 IN int * pErrno 259 ); 260 261 /** 262 Get the peer address. 263 264 This routine calls the network specific layer to get the remote 265 system connection point. 266 267 The ::getpeername routine calls this routine to obtain the network 268 address of the remote connection point. 269 270 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 271 272 @param [out] pAddress Network address to receive the remote system address 273 274 @param [in,out] pAddressLength Length of the remote network address structure 275 276 @param [out] pErrno Address to receive the errno value upon completion. 277 278 @retval EFI_SUCCESS - Remote address successfully returned 279 280 **/ 281 typedef 282 EFI_STATUS 283 (* PFN_GET_PEER) ( 284 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 285 OUT struct sockaddr * pAddress, 286 IN OUT socklen_t * pAddressLength, 287 IN int * pErrno 288 ); 289 290 /** 291 Establish the known port to listen for network connections. 292 293 This routine calls into the network protocol layer to establish 294 a handler that is called upon connection completion. The handler 295 is responsible for inserting the connection into the FIFO. 296 297 The ::listen routine indirectly calls this routine to place the 298 socket into a state that enables connection attempts. Connections 299 are placed in a FIFO that is serviced by the application. The 300 application calls the ::accept (::EslSocketAccept) routine to 301 remove the next connection from the FIFO and get the associated 302 socket and address. 303 304 @param [in] pSocketProtocol Address of the socket protocol structure. 305 306 @param [in] Backlog Backlog specifies the maximum FIFO depth for 307 the connections waiting for the application 308 to call accept. Connection attempts received 309 while the queue is full are refused. 310 311 @param [out] pErrno Address to receive the errno value upon completion. 312 313 @retval EFI_SUCCESS - Socket successfully created 314 @retval Other - Failed to enable the socket for listen 315 316 **/ 317 typedef 318 EFI_STATUS 319 (* PFN_LISTEN) ( 320 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 321 IN INT32 Backlog, 322 OUT int * pErrno 323 ); 324 325 /** 326 Get the socket options 327 328 This routine handles the socket level options and passes the 329 others to the network specific layer. 330 331 The ::getsockopt routine calls this routine to retrieve the 332 socket options one at a time by name. 333 334 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 335 @param [in] level Option protocol level 336 @param [in] OptionName Name of the option 337 @param [out] pOptionValue Buffer to receive the option value 338 @param [in,out] pOptionLength Length of the buffer in bytes, 339 upon return length of the option value in bytes 340 @param [out] pErrno Address to receive the errno value upon completion. 341 342 @retval EFI_SUCCESS - Socket data successfully received 343 344 **/ 345 typedef 346 EFI_STATUS 347 (* PFN_OPTION_GET) ( 348 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 349 IN int level, 350 IN int OptionName, 351 OUT void * __restrict pOptionValue, 352 IN OUT socklen_t * __restrict pOptionLength, 353 IN int * pErrno 354 ); 355 356 /** 357 Set the socket options 358 359 This routine handles the socket level options and passes the 360 others to the network specific layer. 361 362 The ::setsockopt routine calls this routine to adjust the socket 363 options one at a time by name. 364 365 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 366 @param [in] level Option protocol level 367 @param [in] OptionName Name of the option 368 @param [in] pOptionValue Buffer containing the option value 369 @param [in] OptionLength Length of the buffer in bytes 370 @param [out] pErrno Address to receive the errno value upon completion. 371 372 @retval EFI_SUCCESS - Option successfully set 373 374 **/ 375 typedef 376 EFI_STATUS 377 (* PFN_OPTION_SET) ( 378 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 379 IN int level, 380 IN int OptionName, 381 IN CONST void * pOptionValue, 382 IN socklen_t OptionLength, 383 IN int * pErrno 384 ); 385 386 /** 387 Poll a socket for pending activity. 388 389 This routine builds a detected event mask which is returned to 390 the caller in the buffer provided. 391 392 The ::poll routine calls this routine to determine if the socket 393 needs to be serviced as a result of connection, error, receive or 394 transmit activity. 395 396 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 397 398 @param [in] Events Events of interest for this socket 399 400 @param [in] pEvents Address to receive the detected events 401 402 @param [out] pErrno Address to receive the errno value upon completion. 403 404 @retval EFI_SUCCESS - Socket successfully polled 405 @retval EFI_INVALID_PARAMETER - When pEvents is NULL 406 407 **/ 408 typedef 409 EFI_STATUS 410 (* PFN_POLL) ( 411 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 412 IN short Events, 413 IN short * pEvents, 414 IN int * pErrno 415 ); 416 417 /** 418 Receive data from a network connection. 419 420 This routine calls the network specific routine to remove the 421 next portion of data from the receive queue and return it to the 422 caller. 423 424 The ::recvfrom routine calls this routine to determine if any data 425 is received from the remote system. Note that the other routines 426 ::recv and ::read are layered on top of ::recvfrom. 427 428 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 429 430 @param [in] Flags Message control flags 431 432 @param [in] BufferLength Length of the the buffer 433 434 @param [in] pBuffer Address of a buffer to receive the data. 435 436 @param [in] pDataLength Number of received data bytes in the buffer. 437 438 @param [out] pAddress Network address to receive the remote system address 439 440 @param [in,out] pAddressLength Length of the remote network address structure 441 442 @param [out] pErrno Address to receive the errno value upon completion. 443 444 @retval EFI_SUCCESS - Socket data successfully received 445 446 **/ 447 typedef 448 EFI_STATUS 449 (* PFN_RECEIVE) ( 450 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 451 IN int Flags, 452 IN size_t BufferLength, 453 IN UINT8 * pBuffer, 454 OUT size_t * pDataLength, 455 OUT struct sockaddr * pAddress, 456 IN OUT socklen_t * pAddressLength, 457 IN int * pErrno 458 ); 459 460 /** 461 Shutdown the socket receive and transmit operations 462 463 This routine sets a flag to stop future transmissions and calls 464 the network specific layer to cancel the pending receive operation. 465 466 The ::shutdown routine calls this routine to stop receive and transmit 467 operations on the socket. 468 469 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 470 471 @param [in] How Which operations to stop 472 473 @param [out] pErrno Address to receive the errno value upon completion. 474 475 @retval EFI_SUCCESS - Socket operations successfully shutdown 476 477 **/ 478 typedef 479 EFI_STATUS 480 (* PFN_SHUTDOWN) ( 481 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 482 IN int How, 483 IN int * pErrno 484 ); 485 486 /** 487 Initialize an endpoint for network communication. 488 489 This routine initializes the communication endpoint. 490 491 The ::socket routine calls this routine indirectly to create 492 the communication endpoint. 493 494 @param [in] pSocketProtocol Address of the socket protocol structure. 495 @param [in] domain Select the family of protocols for the client or server 496 application. See the ::socket documentation for values. 497 @param [in] type Specifies how to make the network connection. 498 See the ::socket documentation for values. 499 @param [in] protocol Specifies the lower layer protocol to use. 500 See the ::socket documentation for values. 501 @param [out] pErrno Address to receive the errno value upon completion. 502 503 @retval EFI_SUCCESS - Socket successfully created 504 @retval EFI_INVALID_PARAMETER - Invalid domain value, errno = EAFNOSUPPORT 505 @retval EFI_INVALID_PARAMETER - Invalid type value, errno = EINVAL 506 @retval EFI_INVALID_PARAMETER - Invalid protocol value, errno = EINVAL 507 508 **/ 509 typedef 510 EFI_STATUS 511 (*PFN_SOCKET) ( 512 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 513 IN int domain, 514 IN int type, 515 IN int protocol, 516 IN int * pErrno 517 ); 518 519 /** 520 Send data using a network connection. 521 522 This routine calls the network specific layer to queue the data 523 for transmission. Eventually the buffer will reach the head of 524 the queue and will get transmitted over the network. For datagram 525 sockets there is no guarantee that the data reaches the application 526 running on the remote system. 527 528 The ::sendto routine calls this routine to send data to the remote 529 system. Note that ::send and ::write are layered on top of ::sendto. 530 531 @param [in] pSocketProtocol Address of the ::EFI_SOCKET_PROTOCOL structure. 532 533 @param [in] Flags Message control flags 534 535 @param [in] BufferLength Length of the the buffer 536 537 @param [in] pBuffer Address of a buffer containing the data to send 538 539 @param [in] pDataLength Address to receive the number of data bytes sent 540 541 @param [in] pAddress Network address of the remote system address 542 543 @param [in] AddressLength Length of the remote network address structure 544 545 @param [out] pErrno Address to receive the errno value upon completion. 546 547 @retval EFI_SUCCESS - Socket data successfully queued for transmit 548 549 **/ 550 typedef 551 EFI_STATUS 552 (* PFN_TRANSMIT) ( 553 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 554 IN int Flags, 555 IN size_t BufferLength, 556 IN CONST UINT8 * pBuffer, 557 OUT size_t * pDataLength, 558 IN const struct sockaddr * pAddress, 559 IN socklen_t AddressLength, 560 IN int * pErrno 561 ); 562 563 //------------------------------------------------------------------------------ 564 // Socket Protocol 565 //------------------------------------------------------------------------------ 566 567 /** 568 Socket protocol declaration 569 **/ 570 typedef struct _EFI_SOCKET_PROTOCOL { 571 EFI_HANDLE SocketHandle; ///< Handle for the socket 572 PFN_ACCEPT pfnAccept; ///< Accept a network connection 573 PFN_BIND pfnBind; ///< Bind a local address to the socket 574 PFN_CLOSE_POLL pfnClosePoll; ///< Determine if the socket is closed 575 PFN_CLOSE_START pfnCloseStart; ///< Start the close operation 576 PFN_CONNECT pfnConnect; ///< Connect to a remote system 577 PFN_GET_LOCAL pfnGetLocal; ///< Get local address 578 PFN_GET_PEER pfnGetPeer; ///< Get peer address 579 PFN_LISTEN pfnListen; ///< Enable connection attempts on known port 580 PFN_OPTION_GET pfnOptionGet; ///< Get socket options 581 PFN_OPTION_SET pfnOptionSet; ///< Set socket options 582 PFN_POLL pfnPoll; ///< Poll for socket activity 583 PFN_RECEIVE pfnReceive; ///< Receive data from a socket 584 PFN_SHUTDOWN pfnShutdown; ///< Shutdown receive and transmit operations 585 PFN_SOCKET pfnSocket; ///< Initialize the socket 586 PFN_TRANSMIT pfnTransmit; ///< Transmit data using the socket 587 } GCC_EFI_SOCKET_PROTOCOL; 588 589 //------------------------------------------------------------------------------ 590 // Non-blocking routines 591 //------------------------------------------------------------------------------ 592 593 /** 594 Non blocking version of ::accept. 595 596 @param [in] s Socket file descriptor returned from ::socket. 597 598 @param [in] address Address of a buffer to receive the remote network address. 599 600 @param [in, out] address_len Address of a buffer containing the Length in bytes 601 of the remote network address buffer. Upon return, 602 contains the length of the remote network address. 603 604 @return This routine returns zero if successful and -1 when an error occurs. 605 In the case of an error, ::errno contains more details. 606 607 **/ 608 int 609 AcceptNB ( 610 int s, 611 struct sockaddr * address, 612 socklen_t * address_len 613 ); 614 615 /** 616 Free the socket resources 617 618 This releases the socket resources allocated by calling 619 EslServiceGetProtocol. 620 621 This routine is called from the ::close routine in BsdSocketLib 622 to release the socket resources. 623 624 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL 625 structure 626 627 @return Value for ::errno, zero (0) indicates success. 628 629 **/ 630 int 631 EslServiceFreeProtocol ( 632 IN EFI_SOCKET_PROTOCOL * pSocketProtocol 633 ); 634 635 /** 636 Connect to the EFI socket library 637 638 @param [in] ppSocketProtocol Address to receive the socket protocol address 639 640 @return Value for ::errno, zero (0) indicates success. 641 642 **/ 643 int 644 EslServiceGetProtocol ( 645 IN EFI_SOCKET_PROTOCOL ** ppSocketProtocol 646 ); 647 648 //------------------------------------------------------------------------------ 649 650 #endif // _EFI_SOCKET_H_ 651