1 /** @file 2 Definitions for the Socket layer driver. 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 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 #ifndef _SOCKET_H_ 15 #define _SOCKET_H_ 16 17 #include <Efi/EfiSocketLib.h> 18 19 //------------------------------------------------------------------------------ 20 // Constants 21 //------------------------------------------------------------------------------ 22 23 #define DEBUG_SOCKET 0x20000000 ///< Display Socket related messages 24 #define DEBUG_BIND 0x10000000 ///< Display bind related messages 25 #define DEBUG_LISTEN 0x08000000 ///< Display listen related messages 26 #define DEBUG_CONNECTION 0x04000000 ///< Display connection list related messages 27 #define DEBUG_POLL 0x02000000 ///< Display poll messages 28 #define DEBUG_ACCEPT 0x01000000 ///< Display accept related messages 29 #define DEBUG_RX 0x00800000 ///< Display receive messages 30 #define DEBUG_TX 0x00400000 ///< Display transmit messages 31 #define DEBUG_CLOSE 0x00200000 ///< Display close messages 32 #define DEBUG_CONNECT 0x00100000 ///< Display connect messages 33 #define DEBUG_OPTION 0x00080000 ///< Display option messages 34 35 #define MAX_PENDING_CONNECTIONS 1 ///< Maximum connection FIFO depth 36 #define MAX_RX_DATA 0x01000000 ///< Maximum receive data size 37 #define MAX_TX_DATA ( MAX_RX_DATA * 2 ) ///< Maximum buffered transmit data in bytes 38 #define RX_PACKET_DATA 0x00100000 ///< Maximum number of bytes in a RX packet 39 #define MAX_UDP_RETRANSMIT 16 ///< UDP retransmit attempts to handle address not mapped 40 41 #define ESL_STRUCTURE_ALIGNMENT_BYTES 15 ///< Number of bytes for structure alignment 42 #define ESL_STRUCTURE_ALIGNMENT_MASK ( ~ESL_STRUCTURE_ALIGNMENT_BYTES ) ///< Mask to align structures 43 44 #define LAYER_SIGNATURE SIGNATURE_32 ('S','k','t','L') ///< ESL_LAYER memory signature 45 #define SERVICE_SIGNATURE SIGNATURE_32 ('S','k','t','S') ///< ESL_SERVICE memory signature 46 #define SOCKET_SIGNATURE SIGNATURE_32 ('S','c','k','t') ///< ESL_SOCKET memory signature 47 #define PORT_SIGNATURE SIGNATURE_32 ('P','o','r','t') ///< ESL_PORT memory signature 48 49 50 /** 51 Socket states 52 **/ 53 typedef enum 54 { 55 SOCKET_STATE_NOT_CONFIGURED = 0, ///< socket call was successful 56 SOCKET_STATE_BOUND, ///< bind call was successful 57 SOCKET_STATE_LISTENING, ///< listen call was successful 58 SOCKET_STATE_NO_PORTS, ///< No ports available 59 SOCKET_STATE_IN_FIFO, ///< Socket on FIFO 60 SOCKET_STATE_CONNECTING, ///< Connecting to a remote system 61 SOCKET_STATE_CONNECTED, ///< Accept or connect call was successful 62 63 // 64 // Close state must be the last in the list 65 // 66 SOCKET_STATE_CLOSED ///< Close call was successful 67 } SOCKET_STATE; 68 69 70 /** 71 Port states 72 **/ 73 typedef enum 74 { 75 PORT_STATE_ALLOCATED = 0, ///< Port allocated 76 PORT_STATE_OPEN, ///< Port opened 77 PORT_STATE_RX_ERROR, ///< Receive error detected 78 79 // 80 // Close state must be last in the list! 81 // 82 // Using < <= > >= in tests code to detect port close state 83 // machine has started 84 // 85 PORT_STATE_CLOSE_STARTED, ///< Close started on port 86 PORT_STATE_CLOSE_TX_DONE, ///< Transmits shutdown 87 PORT_STATE_CLOSE_DONE, ///< Port close operation complete 88 PORT_STATE_CLOSE_RX_DONE ///< Receives shutdown 89 } PORT_STATE; 90 91 //------------------------------------------------------------------------------ 92 // Data Types 93 //------------------------------------------------------------------------------ 94 95 typedef struct _ESL_IO_MGMT ESL_IO_MGMT;///< Forward declaration 96 typedef struct _ESL_PACKET ESL_PACKET; ///< Forward declaration 97 typedef struct _ESL_PORT ESL_PORT; ///< Forward declaration 98 typedef struct _ESL_SOCKET ESL_SOCKET; ///< Forward declaration 99 100 /** 101 Receive context for SOCK_RAW sockets using IPv4. 102 **/ 103 typedef struct 104 { 105 EFI_IP4_RECEIVE_DATA * pRxData; ///< Receive operation description 106 } ESL_IP4_RX_DATA; 107 108 109 /** 110 Transmit context for SOCK_RAW sockets using IPv4. 111 **/ 112 typedef struct 113 { 114 EFI_IP4_OVERRIDE_DATA Override; ///< Override data 115 EFI_IP4_TRANSMIT_DATA TxData; ///< Transmit operation description 116 UINT8 Buffer[ 1 ]; ///< Data buffer 117 } ESL_IP4_TX_DATA; 118 119 120 /** 121 Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4. 122 **/ 123 typedef struct 124 { 125 EFI_TCP4_RECEIVE_DATA RxData; ///< Receive operation description 126 UINT8 Buffer[ RX_PACKET_DATA ]; ///< Data buffer 127 } ESL_TCP4_RX_DATA; 128 129 130 /** 131 Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv4. 132 **/ 133 typedef struct 134 { 135 EFI_TCP4_TRANSMIT_DATA TxData; ///< Transmit operation description 136 UINT8 Buffer[ 1 ]; ///< Data buffer 137 } ESL_TCP4_TX_DATA; 138 139 140 /** 141 Receive context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6. 142 **/ 143 typedef struct 144 { 145 EFI_TCP6_RECEIVE_DATA RxData; ///< Receive operation description 146 UINT8 Buffer[ RX_PACKET_DATA ]; ///< Data buffer 147 } ESL_TCP6_RX_DATA; 148 149 150 /** 151 Transmit context for SOCK_STREAM and SOCK_SEQPACKET sockets using TCPv6. 152 **/ 153 typedef struct 154 { 155 EFI_TCP6_TRANSMIT_DATA TxData; ///< Transmit operation description 156 UINT8 Buffer[ 1 ]; ///< Data buffer 157 } ESL_TCP6_TX_DATA; 158 159 160 /** 161 Receive context for SOCK_DGRAM sockets using UDPv4. 162 **/ 163 typedef struct 164 { 165 EFI_UDP4_SESSION_DATA Session; ///< Remote network address 166 EFI_UDP4_RECEIVE_DATA * pRxData; ///< Receive operation description 167 } ESL_UDP4_RX_DATA; 168 169 170 /** 171 Transmit context for SOCK_DGRAM sockets using UDPv4. 172 **/ 173 typedef struct 174 { 175 EFI_UDP4_SESSION_DATA Session; ///< Remote network address 176 EFI_UDP4_TRANSMIT_DATA TxData; ///< Transmit operation description 177 UINTN RetransmitCount; ///< Retransmit to handle ARP negotiation 178 UINT8 Buffer[ 1 ]; ///< Data buffer 179 } ESL_UDP4_TX_DATA; 180 181 182 /** 183 Receive context for SOCK_DGRAM sockets using UDPv6. 184 **/ 185 typedef struct 186 { 187 EFI_UDP6_SESSION_DATA Session; ///< Remote network address 188 EFI_UDP6_RECEIVE_DATA * pRxData; ///< Receive operation description 189 } ESL_UDP6_RX_DATA; 190 191 192 /** 193 Transmit context for SOCK_DGRAM sockets using UDPv6. 194 **/ 195 typedef struct 196 { 197 EFI_UDP6_SESSION_DATA Session; ///< Remote network address 198 EFI_UDP6_TRANSMIT_DATA TxData; ///< Transmit operation description 199 UINTN RetransmitCount; ///< Retransmit to handle ARP negotiation 200 UINT8 Buffer[ 1 ]; ///< Data buffer 201 } ESL_UDP6_TX_DATA; 202 203 204 /** 205 Network specific context for transmit and receive packets. 206 **/ 207 typedef struct _ESL_PACKET { 208 ESL_PACKET * pNext; ///< Next packet in the receive list 209 size_t PacketSize; ///< Size of this data structure 210 size_t ValidBytes; ///< Length of valid data in bytes 211 UINT8 * pBuffer; ///< Current data pointer 212 union { 213 ESL_IP4_RX_DATA Ip4Rx; ///< Receive operation description 214 ESL_IP4_TX_DATA Ip4Tx; ///< Transmit operation description 215 ESL_TCP4_RX_DATA Tcp4Rx; ///< Receive operation description 216 ESL_TCP4_TX_DATA Tcp4Tx; ///< Transmit operation description 217 ESL_TCP6_RX_DATA Tcp6Rx; ///< Receive operation description 218 ESL_TCP6_TX_DATA Tcp6Tx; ///< Transmit operation description 219 ESL_UDP4_RX_DATA Udp4Rx; ///< Receive operation description 220 ESL_UDP4_TX_DATA Udp4Tx; ///< Transmit operation description 221 ESL_UDP6_RX_DATA Udp6Rx; ///< Receive operation description 222 ESL_UDP6_TX_DATA Udp6Tx; ///< Transmit operation description 223 } Op; ///< Network specific context 224 } GCC_ESL_PACKET; 225 226 /** 227 Service control structure 228 229 The driver uses this structure to manage the network devices. 230 **/ 231 typedef struct _ESL_SERVICE { 232 UINTN Signature; ///< Structure identification 233 234 // 235 // Links 236 // 237 ESL_SERVICE * pNext; ///< Next service in the service list 238 239 // 240 // Service data 241 // 242 CONST ESL_SOCKET_BINDING * pSocketBinding; ///< Name and shutdown routine 243 EFI_HANDLE Controller; ///< Controller for the service 244 EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///< Network layer service binding interface 245 246 // 247 // Network data 248 // 249 ESL_PORT * pPortList; ///< List of ports using this service 250 }GCC_ESL_SERVICE; 251 252 /** 253 IO management structure 254 255 This structure manages a single operation with the network. 256 **/ 257 typedef struct _ESL_IO_MGMT { 258 ESL_IO_MGMT * pNext; ///< Next TX management structure 259 ESL_PORT * pPort; ///< Port structure address 260 ESL_PACKET * pPacket; ///< Packet structure address 261 union { 262 EFI_IP4_COMPLETION_TOKEN Ip4Rx; ///< IP4 receive token 263 EFI_IP4_COMPLETION_TOKEN Ip4Tx; ///< IP4 transmit token 264 EFI_TCP4_IO_TOKEN Tcp4Rx; ///< TCP4 receive token 265 EFI_TCP4_IO_TOKEN Tcp4Tx; ///< TCP4 transmit token 266 EFI_TCP6_IO_TOKEN Tcp6Rx; ///< TCP6 receive token 267 EFI_TCP6_IO_TOKEN Tcp6Tx; ///< TCP6 transmit token 268 EFI_UDP4_COMPLETION_TOKEN Udp4Rx; ///< UDP4 receive token 269 EFI_UDP4_COMPLETION_TOKEN Udp4Tx; ///< UDP4 transmit token 270 EFI_UDP6_COMPLETION_TOKEN Udp6Rx; ///< UDP6 receive token 271 EFI_UDP6_COMPLETION_TOKEN Udp6Tx; ///< UDP6 transmit token 272 } Token; ///< Completion token for the network operation 273 } GCC_IO_MGMT; 274 275 /** 276 IP4 context structure 277 278 The driver uses this structure to manage the IP4 connections. 279 **/ 280 typedef struct { 281 // 282 // IP4 context 283 // 284 EFI_IP4_MODE_DATA ModeData; ///< IP4 mode data, includes configuration data 285 EFI_IPv4_ADDRESS DestinationAddress; ///< Default destination address 286 } ESL_IP4_CONTEXT; 287 288 289 /** 290 TCP4 context structure 291 292 The driver uses this structure to manage the TCP4 connections. 293 **/ 294 typedef struct { 295 // 296 // TCP4 context 297 // 298 EFI_TCP4_CONFIG_DATA ConfigData; ///< TCP4 configuration data 299 EFI_TCP4_OPTION Option; ///< TCP4 port options 300 301 // 302 // Tokens 303 // 304 EFI_TCP4_LISTEN_TOKEN ListenToken; ///< Listen control 305 EFI_TCP4_CONNECTION_TOKEN ConnectToken; ///< Connection control 306 EFI_TCP4_CLOSE_TOKEN CloseToken; ///< Close control 307 } ESL_TCP4_CONTEXT; 308 309 /** 310 TCP6 context structure 311 312 The driver uses this structure to manage the TCP6 connections. 313 **/ 314 typedef struct { 315 // 316 // TCP6 context 317 // 318 EFI_TCP6_CONFIG_DATA ConfigData; ///< TCP6 configuration data 319 EFI_TCP6_OPTION Option; ///< TCP6 port options 320 321 // 322 // Tokens 323 // 324 EFI_TCP6_LISTEN_TOKEN ListenToken; ///< Listen control 325 EFI_TCP6_CONNECTION_TOKEN ConnectToken; ///< Connection control 326 EFI_TCP6_CLOSE_TOKEN CloseToken; ///< Close control 327 } ESL_TCP6_CONTEXT; 328 329 /** 330 UDP4 context structure 331 332 The driver uses this structure to manage the UDP4 connections. 333 **/ 334 typedef struct { 335 // 336 // UDP4 context 337 // 338 EFI_UDP4_CONFIG_DATA ConfigData; ///< UDP4 configuration data 339 } ESL_UDP4_CONTEXT; 340 341 /** 342 UDP6 context structure 343 344 The driver uses this structure to manage the UDP6 connections. 345 **/ 346 typedef struct { 347 // 348 // UDP6 context 349 // 350 EFI_UDP6_CONFIG_DATA ConfigData; ///< UDP6 configuration data 351 } ESL_UDP6_CONTEXT; 352 353 354 /** 355 Configure the network layer. 356 357 @param [in] pProtocol Protocol structure address 358 @param [in] pConfigData Address of the confiuration data 359 360 @return Returns EFI_SUCCESS if the operation is successfully 361 started. 362 **/ 363 typedef 364 EFI_STATUS 365 (EFIAPI * PFN_NET_CONFIGURE) ( 366 IN VOID * pProtocol, 367 IN VOID * pConfigData 368 ); 369 370 /** 371 Hand an I/O operation to the network layer. 372 373 @param [in] pProtocol Protocol structure address 374 @param [in] pToken Completion token address 375 376 @return Returns EFI_SUCCESS if the operation is successfully 377 started. 378 **/ 379 typedef 380 EFI_STATUS 381 (EFIAPI * PFN_NET_IO_START) ( 382 IN VOID * pProtocol, 383 IN VOID * pToken 384 ); 385 386 /** 387 Poll the LAN adapter for receive packets. 388 389 @param [in] pProtocol Protocol structure address 390 @param [in] pToken Completion token address 391 392 @return Returns EFI_SUCCESS if the operation is successfully 393 started. 394 **/ 395 typedef 396 EFI_STATUS 397 (EFIAPI * PFN_NET_POLL) ( 398 IN VOID * pProtocol 399 ); 400 401 /** 402 Port control structure 403 404 The driver uses this structure to manager the socket's connection 405 with the network driver. 406 **/ 407 typedef struct _ESL_PORT { 408 UINTN Signature; ///< Structure identification 409 410 // 411 // List links 412 // 413 ESL_PORT * pLinkService; ///< Link in service port list 414 ESL_PORT * pLinkSocket; ///< Link in socket port list 415 416 // 417 // Structures 418 // 419 ESL_SERVICE * pService; ///< Service for this port 420 ESL_SOCKET * pSocket; ///< Socket for this port 421 422 // 423 // Eliminate the pService references during port close 424 // 425 EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///< Service binding for network layer 426 CONST ESL_SOCKET_BINDING * pSocketBinding; ///< Socket binding for network layer 427 428 // 429 // Port management 430 // 431 EFI_HANDLE Handle; ///< Network port handle 432 PORT_STATE State; ///< State of the port 433 UINTN DebugFlags; ///< Debug flags used to close the port 434 BOOLEAN bCloseNow; ///< TRUE = Close the port immediately 435 BOOLEAN bConfigured; ///< TRUE = Configure call made to network layer 436 PFN_NET_CONFIGURE pfnConfigure; ///< Configure the network layer 437 438 // 439 // Transmit data management 440 // 441 BOOLEAN bTxFlowControl; ///< TX flow control applied 442 PFN_NET_IO_START pfnTxStart; ///< Start a transmit on the network 443 ESL_IO_MGMT * pTxActive; ///< Normal data queue 444 ESL_IO_MGMT * pTxFree; ///< Normal free queue 445 446 ESL_IO_MGMT * pTxOobActive; ///< Urgent data queue 447 ESL_IO_MGMT * pTxOobFree; ///< Urgent free queue 448 449 // 450 // Receive data management 451 // 452 PFN_NET_IO_START pfnRxCancel; ///< Cancel a receive on the network 453 PFN_NET_POLL pfnRxPoll; ///< Poll the LAN adapter for receive packets 454 PFN_NET_IO_START pfnRxStart; ///< Start a receive on the network 455 ESL_IO_MGMT * pRxActive; ///< Active receive operation queue 456 ESL_IO_MGMT * pRxFree; ///< Free structure queue 457 458 // 459 // Protocol specific management data 460 // 461 union { 462 VOID * v; ///< VOID pointer 463 EFI_IP4_PROTOCOL * IPv4; ///< IP4 protocol pointer 464 EFI_TCP4_PROTOCOL * TCPv4; ///< TCP4 protocol pointer 465 EFI_TCP6_PROTOCOL * TCPv6; ///< TCP6 protocol pointer 466 EFI_UDP4_PROTOCOL * UDPv4; ///< UDP4 protocol pointer 467 EFI_UDP6_PROTOCOL * UDPv6; ///< UDP6 protocol pointer 468 } pProtocol; ///< Protocol structure address 469 union { 470 ESL_IP4_CONTEXT Ip4; ///< IPv4 management data 471 ESL_TCP4_CONTEXT Tcp4; ///< TCPv4 management data 472 ESL_TCP6_CONTEXT Tcp6; ///< TCPv6 management data 473 ESL_UDP4_CONTEXT Udp4; ///< UDPv4 management data 474 ESL_UDP6_CONTEXT Udp6; ///< UDPv6 management data 475 } Context; ///< Network specific context 476 }GCC_ESL_PORT; 477 478 /** 479 Accept a network connection. 480 481 @param [in] pSocket Address of the socket structure. 482 483 @param [in] pSockAddr Address of a buffer to receive the remote 484 network address. 485 486 @param [in, out] pSockAddrLength Length in bytes of the address buffer. 487 On output specifies the length of the 488 remote network address. 489 490 @retval EFI_SUCCESS Remote address is available 491 @retval Others Remote address not available 492 493 **/ 494 typedef 495 EFI_STATUS 496 (* PFN_API_ACCEPT) ( 497 IN ESL_SOCKET * pSocket, 498 IN struct sockaddr * pSockAddr, 499 IN OUT socklen_t * pSockAddrLength 500 ); 501 502 /** 503 Poll for completion of the connection attempt. 504 505 @param [in] pSocket Address of an ::ESL_SOCKET structure. 506 507 @retval EFI_SUCCESS The connection was successfully established. 508 @retval EFI_NOT_READY The connection is in progress, call this routine again. 509 @retval Others The connection attempt failed. 510 511 **/ 512 typedef 513 EFI_STATUS 514 (* PFN_API_CONNECT_POLL) ( 515 IN ESL_SOCKET * pSocket 516 ); 517 518 /** 519 Attempt to connect to a remote TCP port 520 521 This routine starts the connection processing for a SOCK_STREAM 522 or SOCK_SEQPAKCET socket using the TCP network layer. 523 524 This routine is called by ::EslSocketConnect to initiate the TCP 525 network specific connect operations. 526 527 @param [in] pSocket Address of an ::ESL_SOCKET structure. 528 529 @retval EFI_SUCCESS The connection was successfully established. 530 @retval EFI_NOT_READY The connection is in progress, call this routine again. 531 @retval Others The connection attempt failed. 532 533 **/ 534 typedef 535 EFI_STATUS 536 (* PFN_API_CONNECT_START) ( 537 IN ESL_SOCKET * pSocket 538 ); 539 540 /** 541 Get the local socket address 542 543 @param [in] pPort Address of an ::ESL_PORT structure. 544 545 @param [out] pAddress Network address to receive the local system address 546 547 **/ 548 typedef 549 VOID 550 (* PFN_API_LOCAL_ADDR_GET) ( 551 IN ESL_PORT * pPort, 552 OUT struct sockaddr * pAddress 553 ); 554 555 /** 556 Set the local port address. 557 558 This routine sets the local port address. 559 560 This support routine is called by ::EslSocketPortAllocate. 561 562 @param [in] ppPort Address of an ESL_PORT structure 563 @param [in] pSockAddr Address of a sockaddr structure that contains the 564 connection point on the local machine. An IPv4 address 565 of INADDR_ANY specifies that the connection is made to 566 all of the network stacks on the platform. Specifying a 567 specific IPv4 address restricts the connection to the 568 network stack supporting that address. Specifying zero 569 for the port causes the network layer to assign a port 570 number from the dynamic range. Specifying a specific 571 port number causes the network layer to use that port. 572 @param [in] bBindTest TRUE = run bind testing 573 574 @retval EFI_SUCCESS The operation was successful 575 576 **/ 577 typedef 578 EFI_STATUS 579 (* PFN_API_LOCAL_ADDR_SET) ( 580 IN ESL_PORT * pPort, 581 IN CONST struct sockaddr * pSockAddr, 582 IN BOOLEAN bBindTest 583 ); 584 585 /** 586 Process the completion event 587 588 This routine handles the I/O completion event. 589 590 This routine is called by the low level network driver when 591 the operation is completed. 592 593 @param [in] Event The receive completion event 594 595 @param [in] pIo The address of an ::ESL_IO_MGMT structure 596 597 **/ 598 typedef 599 VOID 600 (* PFN_API_IO_COMPLETE) ( 601 IN EFI_EVENT Event, 602 IN ESL_IO_MGMT * pIo 603 ); 604 605 /** 606 Determine if the socket is configured. 607 608 609 @param [in] pSocket Address of a ESL_SOCKET structure 610 611 @retval EFI_SUCCESS - The port is connected 612 @retval EFI_NOT_STARTED - The port is not connected 613 614 **/ 615 typedef 616 EFI_STATUS 617 (* PFN_API_IS_CONFIGURED) ( 618 IN ESL_SOCKET * pSocket 619 ); 620 621 /** 622 Establish the known port to listen for network connections. 623 624 @param [in] pSocket Address of the socket structure. 625 626 @retval EFI_SUCCESS - Socket successfully created 627 @retval Other - Failed to enable the socket for listen 628 629 **/ 630 typedef 631 EFI_STATUS 632 (* PFN_API_LISTEN) ( 633 IN ESL_SOCKET * pSocket 634 ); 635 636 /** 637 Get the option value 638 639 Retrieve the protocol options one at a time by name. 640 641 @param [in] pSocket Address of a ESL_SOCKET structure 642 @param [in] OptionName Name of the option 643 @param [out] ppOptionData Buffer to receive address of option value 644 @param [out] pOptionLength Buffer to receive the option length 645 646 @retval EFI_SUCCESS - Socket data successfully received 647 648 **/ 649 typedef 650 EFI_STATUS 651 (* PFN_API_OPTION_GET) ( 652 IN ESL_SOCKET * pSocket, 653 IN int OptionName, 654 OUT CONST void ** __restrict ppOptionData, 655 OUT socklen_t * __restrict pOptionLength 656 ); 657 658 /** 659 Set the option value 660 661 Adjust the protocol options one at a time by name. 662 663 @param [in] pSocket Address of a ESL_SOCKET structure 664 @param [in] OptionName Name of the option 665 @param [in] pOptionValue Buffer containing the option value 666 @param [in] OptionLength Length of the buffer in bytes 667 668 @retval EFI_SUCCESS - Option successfully set 669 670 **/ 671 typedef 672 EFI_STATUS 673 (* PFN_API_OPTION_SET) ( 674 IN ESL_SOCKET * pSocket, 675 IN int OptionName, 676 IN CONST void * pOptionValue, 677 IN socklen_t OptionLength 678 ); 679 680 /** 681 Free a receive packet 682 683 This routine performs the network specific operations necessary 684 to free a receive packet. 685 686 This routine is called by ::EslSocketPortCloseTxDone to free a 687 receive packet. 688 689 @param [in] pPacket Address of an ::ESL_PACKET structure. 690 @param [in, out] pRxBytes Address of the count of RX bytes 691 692 **/ 693 typedef 694 VOID 695 (* PFN_API_PACKET_FREE) ( 696 IN ESL_PACKET * pPacket, 697 IN OUT size_t * pRxBytes 698 ); 699 700 /** 701 Initialize the network specific portions of an ::ESL_PORT structure. 702 703 This routine initializes the network specific portions of an 704 ::ESL_PORT structure for use by the socket. 705 706 This support routine is called by ::EslSocketPortAllocate 707 to connect the socket with the underlying network adapter 708 running the IPv4 protocol. 709 710 @param [in] ppPort Address of an ESL_PORT structure 711 @param [in] DebugFlags Flags for debug messages 712 713 @retval EFI_SUCCESS - Socket successfully created 714 715 **/ 716 typedef 717 EFI_STATUS 718 (* PFN_API_PORT_ALLOC) ( 719 IN ESL_PORT * pPort, 720 IN UINTN DebugFlags 721 ); 722 723 /** 724 Close a network specific port. 725 726 This routine releases the resources allocated by the 727 network specific PortAllocate routine. 728 729 This routine is called by ::EslSocketPortCloseRxDone as 730 the last step of closing processing. 731 See the \ref PortCloseStateMachine section. 732 733 @param [in] pPort Address of an ::ESL_PORT structure. 734 735 @retval EFI_SUCCESS The port is closed 736 @retval other Port close error 737 738 **/ 739 typedef 740 EFI_STATUS 741 (* PFN_API_PORT_CLOSE) ( 742 IN ESL_PORT * pPort 743 ); 744 745 /** 746 Perform the network specific close operation on the port. 747 748 This routine performs the network specific operation to 749 shutdown receive operations on the port. 750 751 This routine is called by the ::EslSocketPortCloseTxDone 752 routine after the port completes all of the transmission. 753 754 @param [in] pPort Address of an ::ESL_PORT structure. 755 756 @retval EFI_SUCCESS The port is closed, not normally returned 757 @retval EFI_NOT_READY The port is still closing 758 @retval EFI_ALREADY_STARTED Error, the port is in the wrong state, 759 most likely the routine was called already. 760 761 **/ 762 typedef 763 EFI_STATUS 764 (* PFN_API_PORT_CLOSE_OP) ( 765 IN ESL_PORT * pPort 766 ); 767 768 /** 769 Receive data from a network connection. 770 771 This routine attempts to return buffered data to the caller. The 772 data is removed from the urgent queue if the message flag MSG_OOB 773 is specified, otherwise data is removed from the normal queue. 774 See the \ref ReceiveEngine section. 775 776 This routine is called by ::EslSocketReceive to handle the network 777 specific receive operation. 778 779 @param [in] pPort Address of an ::ESL_PORT structure. 780 781 @param [in] pPacket Address of an ::ESL_PACKET structure. 782 783 @param [in] pbConsumePacket Address of a BOOLEAN indicating if the packet is to be consumed 784 785 @param [in] BufferLength Length of the the buffer 786 787 @param [in] pBuffer Address of a buffer to receive the data. 788 789 @param [in] pDataLength Number of received data bytes in the buffer. 790 791 @param [out] pAddress Network address to receive the remote system address 792 793 @param [out] pSkipBytes Address to receive the number of bytes skipped 794 795 @return Returns the address of the next free byte in the buffer. 796 797 **/ 798 typedef 799 UINT8 * 800 (* PFN_API_RECEIVE) ( 801 IN ESL_PORT * pPort, 802 IN ESL_PACKET * pPacket, 803 IN BOOLEAN * pbConsumePacket, 804 IN size_t BufferLength, 805 IN UINT8 * pBuffer, 806 OUT size_t * pDataLength, 807 OUT struct sockaddr * pAddress, 808 OUT size_t * pSkipBytes 809 ); 810 811 /** 812 Get the remote socket address 813 814 @param [in] pPort Address of an ::ESL_PORT structure. 815 816 @param [out] pAddress Network address to receive the remote system address 817 818 **/ 819 typedef 820 VOID 821 (* PFN_API_REMOTE_ADDR_GET) ( 822 IN ESL_PORT * pPort, 823 OUT struct sockaddr * pAddress 824 ); 825 826 /** 827 Set the remote address 828 829 This routine sets the remote address in the port. 830 831 This routine is called by ::EslSocketConnect to specify the 832 remote network address. 833 834 @param [in] pPort Address of an ::ESL_PORT structure. 835 836 @param [in] pSockAddr Network address of the remote system. 837 838 @param [in] SockAddrLength Length in bytes of the network address. 839 840 @retval EFI_SUCCESS The operation was successful 841 842 **/ 843 typedef 844 EFI_STATUS 845 (* PFN_API_REMOTE_ADDR_SET) ( 846 IN ESL_PORT * pPort, 847 IN CONST struct sockaddr * pSockAddr, 848 IN socklen_t SockAddrLength 849 ); 850 851 /** 852 Start a receive operation 853 854 This routine prepares a packet for the receive operation. 855 See the \ref ReceiveEngine section. 856 857 This support routine is called by EslSocketRxStart. 858 859 @param [in] pPort Address of an ::ESL_PORT structure. 860 @param [in] pIo Address of an ::ESL_IO_MGMT structure. 861 862 **/ 863 typedef 864 VOID 865 (* PFN_API_RX_START) ( 866 IN ESL_PORT * pPort, 867 IN ESL_IO_MGMT * pIo 868 ); 869 870 /** 871 Buffer data for transmission over a network connection. 872 873 @param [in] pSocket Address of a ESL_SOCKET structure 874 875 @param [in] Flags Message control flags 876 877 @param [in] BufferLength Length of the the buffer 878 879 @param [in] pBuffer Address of a buffer to receive the data. 880 881 @param [in] pDataLength Number of received data bytes in the buffer. 882 883 @param [in] pAddress Network address of the remote system address 884 885 @param [in] AddressLength Length of the remote network address structure 886 887 @retval EFI_SUCCESS - Socket data successfully buffered 888 889 **/ 890 typedef 891 EFI_STATUS 892 (* PFN_API_TRANSMIT) ( 893 IN ESL_SOCKET * pSocket, 894 IN int Flags, 895 IN size_t BufferLength, 896 IN CONST UINT8 * pBuffer, 897 OUT size_t * pDataLength, 898 IN const struct sockaddr * pAddress, 899 IN socklen_t AddressLength 900 ); 901 902 /** 903 Process the transmit completion 904 905 This routine calls ::EslSocketTxComplete to handle the 906 transmit completion. 907 908 This routine is called by the network layers upon the completion 909 of a transmit operation. 910 911 @param [in] Event The urgent transmit completion event 912 913 @param [in] pIo The ESL_IO_MGMT structure address 914 915 **/ 916 typedef 917 VOID 918 (* PFN_API_TX_COMPLETE) ( 919 IN EFI_EVENT Event, 920 IN ESL_IO_MGMT * pIo 921 ); 922 923 /** 924 Verify the adapter's IP address 925 926 This support routine is called by EslSocketBindTest. 927 928 @param [in] pPort Address of an ::ESL_PORT structure. 929 @param [in] pConfigData Address of the configuration data 930 931 @retval EFI_SUCCESS - The IP address is valid 932 @retval EFI_NOT_STARTED - The IP address is invalid 933 934 **/ 935 typedef 936 EFI_STATUS 937 (* PFN_API_VERIFY_LOCAL_IP_ADDRESS) ( 938 IN ESL_PORT * pPort, 939 IN VOID * pConfigData 940 ); 941 942 /** 943 Socket type control structure 944 945 This driver uses this structure to define the API for the socket type. 946 **/ 947 typedef struct { 948 CONST CHAR8 * pName; ///< Protocol name 949 int DefaultProtocol; ///< Default protocol 950 UINTN ConfigDataOffset; ///< Offset in ::ESL_PORT to the configuration data 951 UINTN ServiceListOffset; ///< Offset in ::ESL_LAYER for the list of services 952 socklen_t MinimumAddressLength; ///< Minimum address length in bytes 953 socklen_t AddressLength; ///< Address length in bytes 954 sa_family_t AddressFamily; ///< Address family 955 UINTN RxPacketBytes; ///< Length of the RX packet allocation 956 UINTN RxZeroBytes; ///< Number of bytes to zero in RX packet 957 UINTN RxBufferOffset; ///< Offset of buffer address in ESL_IO_MGMT structure 958 BOOLEAN bOobSupported; ///< TRUE if out-of-band messages are supported 959 int BindTestErrno; ///< errno value if EslSocketBindTest fails 960 PFN_API_ACCEPT pfnAccept; ///< Accept a network connection 961 PFN_API_CONNECT_POLL pfnConnectPoll; ///< Poll for connection complete 962 PFN_API_CONNECT_START pfnConnectStart; ///< Start the connection to a remote system 963 PFN_API_IS_CONFIGURED pfnIsConfigured; ///< Determine if the socket is configured 964 PFN_API_LOCAL_ADDR_GET pfnLocalAddrGet; ///< Get the local address 965 PFN_API_LOCAL_ADDR_SET pfnLocalAddrSet; ///< Set the local address 966 PFN_API_LISTEN pfnListen; ///< Listen for connections on known server port 967 PFN_API_OPTION_GET pfnOptionGet; ///< Get the option value 968 PFN_API_OPTION_SET pfnOptionSet; ///< Set the option value 969 PFN_API_PACKET_FREE pfnPacketFree; ///< Free the receive packet 970 PFN_API_PORT_ALLOC pfnPortAllocate; ///< Allocate the network specific resources for the port 971 PFN_API_PORT_CLOSE pfnPortClose; ///< Close the network specific resources for the port 972 PFN_API_PORT_CLOSE_OP pfnPortCloseOp; ///< Perform the close operation on the port 973 BOOLEAN bPortCloseComplete; ///< TRUE = Close is complete after close operation 974 PFN_API_RECEIVE pfnReceive; ///< Attempt to receive some data 975 PFN_API_REMOTE_ADDR_GET pfnRemoteAddrGet; ///< Get remote address 976 PFN_API_REMOTE_ADDR_SET pfnRemoteAddrSet; ///< Set the remote system address 977 PFN_API_IO_COMPLETE pfnRxComplete; ///< RX completion 978 PFN_API_RX_START pfnRxStart; ///< Start a network specific receive operation 979 PFN_API_TRANSMIT pfnTransmit; ///< Attempt to buffer a packet for transmit 980 PFN_API_TX_COMPLETE pfnTxComplete; ///< TX completion for normal data 981 PFN_API_TX_COMPLETE pfnTxOobComplete; ///< TX completion for urgent data 982 PFN_API_VERIFY_LOCAL_IP_ADDRESS pfnVerifyLocalIpAddress; ///< Verify the local IP address 983 } ESL_PROTOCOL_API; 984 985 986 /** 987 Socket control structure 988 989 The driver uses this structure to manage the socket. 990 **/ 991 typedef struct _ESL_SOCKET { 992 UINTN Signature; ///< Structure identification 993 994 // 995 // Protocol binding 996 // 997 EFI_SOCKET_PROTOCOL SocketProtocol; ///< Socket protocol declaration 998 CONST ESL_PROTOCOL_API * pApi; ///< API for the protocol 999 1000 // 1001 // Socket management 1002 // 1003 ESL_SOCKET * pNext; ///< Next socket in the list of sockets 1004 int errno; ///< Error information for this socket 1005 EFI_STATUS Status; ///< Asyncronous error information for this socket 1006 SOCKET_STATE State; ///< Socket state 1007 UINT32 DebugFlags; ///< Debug flags 1008 1009 // 1010 // Socket options 1011 // 1012 BOOLEAN bIncludeHeader; ///< TRUE if including the IP header 1013 BOOLEAN bListenCalled; ///< TRUE if listen was successfully called 1014 BOOLEAN bOobInLine; ///< TRUE if out-of-band messages are to be received inline with normal data 1015 BOOLEAN bReUseAddr; ///< TRUE if using same address is allowed 1016 1017 // 1018 // Socket data 1019 // 1020 int Domain; ///< Specifies family of protocols 1021 int Type; ///< Specifies how to make network connection 1022 int Protocol; ///< Specifies lower layer protocol to use 1023 BOOLEAN bAddressSet; ///< Set when the address is specified 1024 BOOLEAN bConfigured; ///< Set after the socket is configured 1025 1026 BOOLEAN bRxDisable; ///< Receive disabled via shutdown 1027 size_t RxBytes; ///< Total Rx bytes 1028 size_t RxOobBytes; ///< Urgent Rx bytes 1029 EFI_STATUS RxError; ///< Error during receive 1030 1031 BOOLEAN bTxDisable; ///< Transmit disabled via shutdown 1032 size_t TxBytes; ///< Normal Tx bytes 1033 size_t TxOobBytes; ///< Urgent Tx bytes 1034 EFI_STATUS TxError; ///< Error during transmit 1035 1036 // 1037 // Pending connection data 1038 // 1039 BOOLEAN bConnected; ///< Set when connected, cleared by poll 1040 EFI_STATUS ConnectStatus; ///< Connection status 1041 UINTN MaxFifoDepth; ///< Maximum FIFO depth 1042 UINTN FifoDepth; ///< Number of sockets in the FIFO 1043 ESL_SOCKET * pFifoHead; ///< Head of the FIFO 1044 ESL_SOCKET * pFifoTail; ///< Tail of the FIFO 1045 ESL_SOCKET * pNextConnection; ///< Link in the FIFO 1046 1047 // 1048 // Network use 1049 // 1050 ESL_PORT * pPortList; ///< List of ports managed by this socket 1051 EFI_EVENT WaitAccept; ///< Wait for accept completion 1052 1053 // 1054 // Receive data management 1055 // 1056 UINT32 MaxRxBuf; ///< Maximum size of the receive buffer 1057 struct timeval RxTimeout; ///< Receive timeout 1058 ESL_PACKET * pRxFree; ///< Free packet list 1059 ESL_PACKET * pRxOobPacketListHead;///< Urgent data list head 1060 ESL_PACKET * pRxOobPacketListTail;///< Urgent data list tail 1061 ESL_PACKET * pRxPacketListHead; ///< Normal data list head 1062 ESL_PACKET * pRxPacketListTail; ///< Normal data list tail 1063 1064 // 1065 // Transmit data management 1066 // 1067 UINTN TxPacketOffset; ///< Offset for data pointer in ::ESL_PACKET 1068 UINTN TxTokenEventOffset; ///< Offset to the Event in the TX token 1069 UINTN TxTokenOffset; ///< Offset for data pointer in TX token 1070 UINT32 MaxTxBuf; ///< Maximum size of the transmit buffer 1071 ESL_PACKET * pTxOobPacketListHead;///< Urgent data list head 1072 ESL_PACKET * pTxOobPacketListTail;///< Urgent data list tail 1073 ESL_PACKET * pTxPacketListHead; ///< Normal data list head 1074 ESL_PACKET * pTxPacketListTail; ///< Normal data list tail 1075 }GCC_ESL_SOCKET; 1076 1077 #define SOCKET_FROM_PROTOCOL(a) CR (a, ESL_SOCKET, SocketProtocol, SOCKET_SIGNATURE) ///< Locate ESL_SOCKET from protocol 1078 1079 /** 1080 Socket layer control structure 1081 1082 The driver uses this structure to manage the driver. 1083 **/ 1084 typedef struct { 1085 UINTN Signature; ///< Structure identification 1086 1087 // 1088 // Service binding interface 1089 // 1090 CONST EFI_SERVICE_BINDING_PROTOCOL * pServiceBinding; ///< Driver's binding 1091 1092 // 1093 // Image data 1094 // 1095 EFI_HANDLE ImageHandle; ///< Image handle 1096 1097 // 1098 // Network services 1099 // 1100 ESL_SERVICE * pIp4List; ///< List of Ip4 services 1101 ESL_SERVICE * pTcp4List; ///< List of Tcp4 services 1102 ESL_SERVICE * pTcp6List; ///< List of Tcp6 services 1103 ESL_SERVICE * pUdp4List; ///< List of Udp4 services 1104 ESL_SERVICE * pUdp6List; ///< List of Udp6 services 1105 1106 // 1107 // Socket management 1108 // 1109 ESL_SOCKET * pSocketList; ///< List of sockets 1110 } ESL_LAYER; 1111 1112 #define LAYER_FROM_SERVICE(a) CR (a, ESL_LAYER, ServiceBinding, LAYER_SIGNATURE) ///< Locate ESL_LAYER from service binding 1113 1114 //------------------------------------------------------------------------------ 1115 // Data 1116 //------------------------------------------------------------------------------ 1117 1118 extern ESL_LAYER mEslLayer; 1119 1120 extern CONST ESL_PROTOCOL_API cEslIp4Api; 1121 extern CONST ESL_PROTOCOL_API cEslIp6Api; 1122 extern CONST ESL_PROTOCOL_API cEslTcp4Api; 1123 extern CONST ESL_PROTOCOL_API cEslTcp6Api; 1124 extern CONST ESL_PROTOCOL_API cEslUdp4Api; 1125 extern CONST ESL_PROTOCOL_API cEslUdp6Api; 1126 1127 extern CONST EFI_SERVICE_BINDING_PROTOCOL mEfiServiceBinding; 1128 1129 //------------------------------------------------------------------------------ 1130 // Socket Support Routines 1131 //------------------------------------------------------------------------------ 1132 1133 /** 1134 Allocate and initialize a ESL_SOCKET structure. 1135 1136 This support function allocates an ::ESL_SOCKET structure 1137 and installs a protocol on ChildHandle. If pChildHandle is a 1138 pointer to NULL, then a new handle is created and returned in 1139 pChildHandle. If pChildHandle is not a pointer to NULL, then 1140 the protocol installs on the existing pChildHandle. 1141 1142 @param [in, out] pChildHandle Pointer to the handle of the child to create. 1143 If it is NULL, then a new handle is created. 1144 If it is a pointer to an existing UEFI handle, 1145 then the protocol is added to the existing UEFI 1146 handle. 1147 @param [in] DebugFlags Flags for debug messages 1148 @param [in, out] ppSocket The buffer to receive an ::ESL_SOCKET structure address. 1149 1150 @retval EFI_SUCCESS The protocol was added to ChildHandle. 1151 @retval EFI_INVALID_PARAMETER ChildHandle is NULL. 1152 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create 1153 the child 1154 @retval other The child handle was not created 1155 1156 **/ 1157 EFI_STATUS 1158 EFIAPI 1159 EslSocketAllocate ( 1160 IN OUT EFI_HANDLE * pChildHandle, 1161 IN UINTN DebugFlags, 1162 IN OUT ESL_SOCKET ** ppSocket 1163 ); 1164 1165 /** 1166 Test the bind configuration. 1167 1168 @param [in] pPort Address of the ::ESL_PORT structure. 1169 @param [in] ErrnoValue errno value if test fails 1170 1171 @retval EFI_SUCCESS The connection was successfully established. 1172 @retval Others The connection attempt failed. 1173 1174 **/ 1175 EFI_STATUS 1176 EslSocketBindTest ( 1177 IN ESL_PORT * pPort, 1178 IN int ErrnoValue 1179 ); 1180 1181 /** 1182 Copy a fragmented buffer into a destination buffer. 1183 1184 This support routine copies a fragmented buffer to the caller specified buffer. 1185 1186 This routine is called by ::EslIp4Receive and ::EslUdp4Receive. 1187 1188 @param [in] FragmentCount Number of fragments in the table 1189 1190 @param [in] pFragmentTable Address of an EFI_IP4_FRAGMENT_DATA structure 1191 1192 @param [in] BufferLength Length of the the buffer 1193 1194 @param [in] pBuffer Address of a buffer to receive the data. 1195 1196 @param [in] pDataLength Number of received data bytes in the buffer. 1197 1198 @return Returns the address of the next free byte in the buffer. 1199 1200 **/ 1201 UINT8 * 1202 EslSocketCopyFragmentedBuffer ( 1203 IN UINT32 FragmentCount, 1204 IN EFI_IP4_FRAGMENT_DATA * pFragmentTable, 1205 IN size_t BufferLength, 1206 IN UINT8 * pBuffer, 1207 OUT size_t * pDataLength 1208 ); 1209 1210 /** 1211 Free the socket. 1212 1213 This routine frees the socket structure and handle resources. 1214 1215 The ::close routine calls EslServiceFreeProtocol which then calls 1216 this routine to free the socket context structure and close the 1217 handle. 1218 1219 @param [in] pSocketProtocol Address of an ::EFI_SOCKET_PROTOCOL structure. 1220 1221 @param [out] pErrno Address to receive the errno value upon completion. 1222 1223 @retval EFI_SUCCESS The socket resources were returned successfully. 1224 1225 **/ 1226 EFI_STATUS 1227 EslSocketFree ( 1228 IN EFI_SOCKET_PROTOCOL * pSocketProtocol, 1229 IN int * pErrno 1230 ); 1231 1232 /** 1233 Free the ESL_IO_MGMT event and structure 1234 1235 This support routine walks the free list to close the event in 1236 the ESL_IO_MGMT structure and remove the structure from the free 1237 list. 1238 1239 See the \ref TransmitEngine section. 1240 1241 @param [in] pPort Address of an ::ESL_PORT structure 1242 @param [in] ppFreeQueue Address of the free queue head 1243 @param [in] DebugFlags Flags for debug messages 1244 @param [in] pEventName Zero terminated string containing the event name 1245 1246 @retval EFI_SUCCESS - The structures were properly initialized 1247 1248 **/ 1249 EFI_STATUS 1250 EslSocketIoFree ( 1251 IN ESL_PORT * pPort, 1252 IN ESL_IO_MGMT ** ppFreeQueue, 1253 IN UINTN DebugFlags, 1254 IN CHAR8 * pEventName 1255 ); 1256 1257 /** 1258 Initialize the ESL_IO_MGMT structures 1259 1260 This support routine initializes the ESL_IO_MGMT structure and 1261 places them on to a free list. 1262 1263 This routine is called by the PortAllocate routines to prepare 1264 the transmit engines. See the \ref TransmitEngine section. 1265 1266 @param [in] pPort Address of an ::ESL_PORT structure 1267 @param [in, out] ppIo Address containing the first structure address. Upon 1268 return this buffer contains the next structure address. 1269 @param [in] TokenCount Number of structures to initialize 1270 @param [in] ppFreeQueue Address of the free queue head 1271 @param [in] DebugFlags Flags for debug messages 1272 @param [in] pEventName Zero terminated string containing the event name 1273 @param [in] pfnCompletion Completion routine address 1274 1275 @retval EFI_SUCCESS - The structures were properly initialized 1276 1277 **/ 1278 EFI_STATUS 1279 EslSocketIoInit ( 1280 IN ESL_PORT * pPort, 1281 IN ESL_IO_MGMT ** ppIo, 1282 IN UINTN TokenCount, 1283 IN ESL_IO_MGMT ** ppFreeQueue, 1284 IN UINTN DebugFlags, 1285 IN CHAR8 * pEventName, 1286 IN PFN_API_IO_COMPLETE pfnCompletion 1287 ); 1288 1289 /** 1290 Determine if the socket is configured 1291 1292 This support routine is called to determine if the socket if the 1293 configuration call was made to the network layer. The following 1294 routines call this routine to verify that they may be successful 1295 in their operations: 1296 <ul> 1297 <li>::EslSocketGetLocalAddress</li> 1298 <li>::EslSocketGetPeerAddress</li> 1299 <li>::EslSocketPoll</li> 1300 <li>::EslSocketReceive</li> 1301 <li>::EslSocketTransmit</li> 1302 </ul> 1303 1304 @param [in] pSocket Address of an ::ESL_SOCKET structure 1305 1306 @retval EFI_SUCCESS - The socket is configured 1307 1308 **/ 1309 EFI_STATUS 1310 EslSocketIsConfigured ( 1311 IN ESL_SOCKET * pSocket 1312 ); 1313 1314 /** 1315 Allocate a packet for a receive or transmit operation 1316 1317 This support routine is called by ::EslSocketRxStart and the 1318 network specific TxBuffer routines to get buffer space for the 1319 next operation. 1320 1321 @param [in] ppPacket Address to receive the ::ESL_PACKET structure 1322 @param [in] LengthInBytes Length of the packet structure 1323 @param [in] ZeroBytes Length of packet to zero 1324 @param [in] DebugFlags Flags for debug messages 1325 1326 @retval EFI_SUCCESS - The packet was allocated successfully 1327 1328 **/ 1329 EFI_STATUS 1330 EslSocketPacketAllocate ( 1331 IN ESL_PACKET ** ppPacket, 1332 IN size_t LengthInBytes, 1333 IN size_t ZeroBytes, 1334 IN UINTN DebugFlags 1335 ); 1336 1337 /** 1338 Free a packet used for receive or transmit operation 1339 1340 This support routine is called by the network specific Close 1341 and TxComplete routines and during error cases in RxComplete 1342 and TxBuffer. Note that the network layers typically place 1343 receive packets on the ESL_SOCKET::pRxFree list for reuse. 1344 1345 @param [in] pPacket Address of an ::ESL_PACKET structure 1346 @param [in] DebugFlags Flags for debug messages 1347 1348 @retval EFI_SUCCESS - The packet was allocated successfully 1349 1350 **/ 1351 EFI_STATUS 1352 EslSocketPacketFree ( 1353 IN ESL_PACKET * pPacket, 1354 IN UINTN DebugFlags 1355 ); 1356 1357 /** 1358 Allocate and initialize a ESL_PORT structure. 1359 1360 This routine initializes an ::ESL_PORT structure for use by 1361 the socket. This routine calls a routine via 1362 ESL_PROTOCOL_API::pfnPortAllocate to initialize the network 1363 specific resources. The resources are released later by the 1364 \ref PortCloseStateMachine. 1365 1366 This support routine is called by ::EslSocketBind and 1367 ::EslTcp4ListenComplete to connect the socket with the 1368 underlying network adapter to the socket. 1369 1370 @param [in] pSocket Address of an ::ESL_SOCKET structure. 1371 @param [in] pService Address of an ::ESL_SERVICE structure. 1372 @param [in] ChildHandle TCP4 child handle 1373 @param [in] pSockAddr Address of a sockaddr structure that contains the 1374 connection point on the local machine. An IPv4 address 1375 of INADDR_ANY specifies that the connection is made to 1376 all of the network stacks on the platform. Specifying a 1377 specific IPv4 address restricts the connection to the 1378 network stack supporting that address. Specifying zero 1379 for the port causes the network layer to assign a port 1380 number from the dynamic range. Specifying a specific 1381 port number causes the network layer to use that port. 1382 @param [in] bBindTest TRUE if EslSocketBindTest should be called 1383 @param [in] DebugFlags Flags for debug messages 1384 @param [out] ppPort Buffer to receive new ::ESL_PORT structure address 1385 1386 @retval EFI_SUCCESS - Socket successfully created 1387 1388 **/ 1389 EFI_STATUS 1390 EslSocketPortAllocate ( 1391 IN ESL_SOCKET * pSocket, 1392 IN ESL_SERVICE * pService, 1393 IN EFI_HANDLE ChildHandle, 1394 IN CONST struct sockaddr * pSockAddr, 1395 IN BOOLEAN bBindTest, 1396 IN UINTN DebugFlags, 1397 OUT ESL_PORT ** ppPort 1398 ); 1399 1400 /** 1401 Close a port. 1402 1403 This routine releases the resources allocated by ::EslSocketPortAllocate. 1404 This routine calls ESL_PROTOCOL_API::pfnPortClose to release the network 1405 specific resources. 1406 1407 This routine is called by: 1408 <ul> 1409 <li>::EslIp4PortAllocate - Port initialization failure</li> 1410 <li>::EslSocketPortCloseRxDone - Last step of close processing</li> 1411 <li>::EslTcp4ConnectComplete - Connection failure and reducint the port list to a single port</li> 1412 <li>::EslTcp4PortAllocate - Port initialization failure</li> 1413 <li>::EslUdp4PortAllocate - Port initialization failure</li> 1414 </ul> 1415 See the \ref PortCloseStateMachine section. 1416 1417 @param [in] pPort Address of an ::ESL_PORT structure. 1418 1419 @retval EFI_SUCCESS The port is closed 1420 @retval other Port close error 1421 1422 **/ 1423 EFI_STATUS 1424 EslSocketPortClose ( 1425 IN ESL_PORT * pPort 1426 ); 1427 1428 /** 1429 Process the port close completion event 1430 1431 This routine attempts to complete the port close operation. 1432 1433 This routine is called by the TCP layer upon completion of 1434 the close operation. 1435 See the \ref PortCloseStateMachine section. 1436 1437 @param [in] Event The close completion event 1438 1439 @param [in] pPort Address of an ::ESL_PORT structure. 1440 1441 **/ 1442 VOID 1443 EslSocketPortCloseComplete ( 1444 IN EFI_EVENT Event, 1445 IN ESL_PORT * pPort 1446 ); 1447 1448 /** 1449 Port close state 3 1450 1451 This routine determines the state of the receive operations and 1452 continues the close operation after the pending receive operations 1453 are cancelled. 1454 1455 This routine is called by 1456 <ul> 1457 <li>::EslIp4RxComplete</li> 1458 <li>::EslSocketPortCloseComplete</li> 1459 <li>::EslSocketPortCloseTxDone</li> 1460 <li>::EslUdp4RxComplete</li> 1461 </ul> 1462 to determine the state of the receive operations. 1463 See the \ref PortCloseStateMachine section. 1464 1465 @param [in] pPort Address of an ::ESL_PORT structure. 1466 1467 @retval EFI_SUCCESS The port is closed 1468 @retval EFI_NOT_READY The port is still closing 1469 @retval EFI_ALREADY_STARTED Error, the port is in the wrong state, 1470 most likely the routine was called already. 1471 1472 **/ 1473 EFI_STATUS 1474 EslSocketPortCloseRxDone ( 1475 IN ESL_PORT * pPort 1476 ); 1477 1478 /** 1479 Start the close operation on a port, state 1. 1480 1481 This routine marks the port as closed and initiates the \ref 1482 PortCloseStateMachine. The first step is to allow the \ref 1483 TransmitEngine to run down. 1484 1485 This routine is called by ::EslSocketCloseStart to initiate the socket 1486 network specific close operation on the socket. 1487 1488 @param [in] pPort Address of an ::ESL_PORT structure. 1489 @param [in] bCloseNow Set TRUE to abort active transfers 1490 @param [in] DebugFlags Flags for debug messages 1491 1492 @retval EFI_SUCCESS The port is closed, not normally returned 1493 @retval EFI_NOT_READY The port has started the closing process 1494 @retval EFI_ALREADY_STARTED Error, the port is in the wrong state, 1495 most likely the routine was called already. 1496 1497 **/ 1498 EFI_STATUS 1499 EslSocketPortCloseStart ( 1500 IN ESL_PORT * pPort, 1501 IN BOOLEAN bCloseNow, 1502 IN UINTN DebugFlags 1503 ); 1504 1505 /** 1506 Port close state 2 1507 1508 This routine determines the state of the transmit engine and 1509 continue the close operation after the transmission is complete. 1510 The next step is to stop the \ref ReceiveEngine. 1511 See the \ref PortCloseStateMachine section. 1512 1513 This routine is called by ::EslSocketPortCloseStart to determine 1514 if the transmission is complete. 1515 1516 @param [in] pPort Address of an ::ESL_PORT structure. 1517 1518 @retval EFI_SUCCESS The port is closed, not normally returned 1519 @retval EFI_NOT_READY The port is still closing 1520 @retval EFI_ALREADY_STARTED Error, the port is in the wrong state, 1521 most likely the routine was called already. 1522 1523 **/ 1524 EFI_STATUS 1525 EslSocketPortCloseTxDone ( 1526 IN ESL_PORT * pPort 1527 ); 1528 1529 /** 1530 Cancel the receive operations 1531 1532 This routine cancels a pending receive operation. 1533 See the \ref ReceiveEngine section. 1534 1535 This routine is called by ::EslSocketShutdown when the socket 1536 layer is being shutdown. 1537 1538 @param [in] pPort Address of an ::ESL_PORT structure 1539 @param [in] pIo Address of an ::ESL_IO_MGMT structure 1540 1541 **/ 1542 VOID 1543 EslSocketRxCancel ( 1544 IN ESL_PORT * pPort, 1545 IN ESL_IO_MGMT * pIo 1546 ); 1547 1548 /** 1549 Process the receive completion 1550 1551 This routine queues the data in FIFO order in either the urgent 1552 or normal data queues depending upon the type of data received. 1553 See the \ref ReceiveEngine section. 1554 1555 This routine is called when some data is received by: 1556 <ul> 1557 <li>::EslIp4RxComplete</li> 1558 <li>::EslTcp4RxComplete</li> 1559 <li>::EslUdp4RxComplete</li> 1560 </ul> 1561 1562 @param [in] pIo Address of an ::ESL_IO_MGMT structure 1563 @param [in] Status Receive status 1564 @param [in] LengthInBytes Length of the receive data 1565 @param [in] bUrgent TRUE if urgent data is received and FALSE 1566 for normal data. 1567 1568 **/ 1569 VOID 1570 EslSocketRxComplete ( 1571 IN ESL_IO_MGMT * pIo, 1572 IN EFI_STATUS Status, 1573 IN UINTN LengthInBytes, 1574 IN BOOLEAN bUrgent 1575 ); 1576 1577 /** 1578 Poll a socket for pending receive activity. 1579 1580 This routine is called at elivated TPL and extends the idle 1581 loop which polls a socket down into the LAN driver layer to 1582 determine if there is any receive activity. 1583 1584 The ::EslSocketPoll, ::EslSocketReceive and ::EslSocketTransmit 1585 routines call this routine when there is nothing to do. 1586 1587 @param [in] pSocket Address of an ::EFI_SOCKET structure. 1588 1589 **/ 1590 VOID 1591 EslSocketRxPoll ( 1592 IN ESL_SOCKET * pSocket 1593 ); 1594 1595 /** 1596 Start a receive operation 1597 1598 This routine posts a receive buffer to the network adapter. 1599 See the \ref ReceiveEngine section. 1600 1601 This support routine is called by: 1602 <ul> 1603 <li>::EslIp4Receive to restart the receive engine to release flow control.</li> 1604 <li>::EslIp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li> 1605 <li>::EslIp4SocketIsConfigured to start the recevie engine for the new socket.</li> 1606 <li>::EslTcp4ListenComplete to start the recevie engine for the new socket.</li> 1607 <li>::EslTcp4Receive to restart the receive engine to release flow control.</li> 1608 <li>::EslTcp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li> 1609 <li>::EslUdp4Receive to restart the receive engine to release flow control.</li> 1610 <li>::EslUdp4RxComplete to continue the operation of the receive engine if flow control is not being applied.</li> 1611 <li>::EslUdp4SocketIsConfigured to start the recevie engine for the new socket.</li> 1612 </ul> 1613 1614 @param [in] pPort Address of an ::ESL_PORT structure. 1615 1616 **/ 1617 VOID 1618 EslSocketRxStart ( 1619 IN ESL_PORT * pPort 1620 ); 1621 1622 /** 1623 Complete the transmit operation 1624 1625 This support routine handles the transmit completion processing for 1626 the various network layers. It frees the ::ESL_IO_MGMT structure 1627 and and frees packet resources by calling ::EslSocketPacketFree. 1628 Transmit errors are logged in ESL_SOCKET::TxError. 1629 See the \ref TransmitEngine section. 1630 1631 This routine is called by: 1632 <ul> 1633 <li>::EslIp4TxComplete</li> 1634 <li>::EslTcp4TxComplete</li> 1635 <li>::EslTcp4TxOobComplete</li> 1636 <li>::EslUdp4TxComplete</li> 1637 </ul> 1638 1639 @param [in] pIo Address of an ::ESL_IO_MGMT structure 1640 @param [in] LengthInBytes Length of the data in bytes 1641 @param [in] Status Transmit operation status 1642 @param [in] pQueueType Zero terminated string describing queue type 1643 @param [in] ppQueueHead Transmit queue head address 1644 @param [in] ppQueueTail Transmit queue tail address 1645 @param [in] ppActive Active transmit queue address 1646 @param [in] ppFree Free transmit queue address 1647 1648 **/ 1649 VOID 1650 EslSocketTxComplete ( 1651 IN ESL_IO_MGMT * pIo, 1652 IN UINT32 LengthInBytes, 1653 IN EFI_STATUS Status, 1654 IN CONST CHAR8 * pQueueType, 1655 IN ESL_PACKET ** ppQueueHead, 1656 IN ESL_PACKET ** ppQueueTail, 1657 IN ESL_IO_MGMT ** ppActive, 1658 IN ESL_IO_MGMT ** ppFree 1659 ); 1660 1661 /** 1662 Transmit data using a network connection. 1663 1664 This support routine starts a transmit operation on the 1665 underlying network layer. 1666 1667 The network specific code calls this routine to start a 1668 transmit operation. See the \ref TransmitEngine section. 1669 1670 @param [in] pPort Address of an ::ESL_PORT structure 1671 @param [in] ppQueueHead Transmit queue head address 1672 @param [in] ppQueueTail Transmit queue tail address 1673 @param [in] ppActive Active transmit queue address 1674 @param [in] ppFree Free transmit queue address 1675 1676 **/ 1677 VOID 1678 EslSocketTxStart ( 1679 IN ESL_PORT * pPort, 1680 IN ESL_PACKET ** ppQueueHead, 1681 IN ESL_PACKET ** ppQueueTail, 1682 IN ESL_IO_MGMT ** ppActive, 1683 IN ESL_IO_MGMT ** ppFree 1684 ); 1685 1686 //------------------------------------------------------------------------------ 1687 1688 #endif // _SOCKET_H_ 1689