NetworkPkg/TcpDxe/TcpFunc.h

   1 /** @file
   2   Declaration of external functions shared in TCP driver.
   3
   4   Copyright (c) 2009 - 2014, Intel Corporation. All rights reserved.<BR>
   5
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _TCP_FUNC_H_
  17 #define _TCP_FUNC_H_
  18
  19 #include "TcpOption.h"
  20
  21 #define TCP_COMP_VAL(Min, Max, Default, Val) \
  22   ((((Val) <= (Max)) && ((Val) >= (Min))) ? (Val) : (Default))
  23
  24 /**
  25   Timeout handler prototype.
  26
  27   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
  28
  29 **/
  30 typedef
  31 VOID
  32 (*TCP_TIMER_HANDLER) (
  33   IN OUT TCP_CB *Tcb
  34   );
  35
  36 //
  37 // Functions in TcpMisc.c
  38 //
  39
  40 /**
  41   Initialize the Tcb locally related members.
  42
  43   @param[in, out]  Tcb               Pointer to the TCP_CB of this TCP instance.
  44
  45 **/
  46 VOID
  47 TcpInitTcbLocal (
  48   IN OUT TCP_CB *Tcb
  49   );
  50
  51 /**
  52   Initialize the peer related members.
  53
  54   @param[in, out]  Tcb    Pointer to the TCP_CB of this TCP instance.
  55   @param[in]       Seg    Pointer to the segment that contains the peer's intial information.
  56   @param[in]       Opt    Pointer to the options announced by the peer.
  57
  58 **/
  59 VOID
  60 TcpInitTcbPeer (
  61   IN OUT TCP_CB     *Tcb,
  62   IN     TCP_SEG    *Seg,
  63   IN     TCP_OPTION *Opt
  64   );
  65
  66 /**
  67   Try to find one Tcb whose <Ip, Port> equals to <IN Addr, IN Port>.
  68
  69   @param[in]  Addr     Pointer to the IP address needs to match.
  70   @param[in]  Port     The port number needs to match.
  71   @param[in]  Version  IP_VERSION_4 indicates TCP is running on IP4 stack.
  72                        IP_VERSION_6 indicates TCP is running on IP6 stack.
  73
  74
  75   @retval     TRUE     The Tcb which matches the <Addr Port> pairs exists.
  76   @retval     FALSE    Otherwise
  77
  78 **/
  79 BOOLEAN
  80 TcpFindTcbByPeer (
  81   IN EFI_IP_ADDRESS  *Addr,
  82   IN TCP_PORTNO      Port,
  83   IN UINT8           Version
  84   );
  85
  86 /**
  87   Locate the TCP_CB related to the socket pair.
  88
  89   @param[in]  LocalPort      The local port number.
  90   @param[in]  LocalIp        The local IP address.
  91   @param[in]  RemotePort     The remote port number.
  92   @param[in]  RemoteIp       The remote IP address.
  93   @param[in]  Version        IP_VERSION_4 indicates TCP is running on IP4 stack,
  94                              IP_VERSION_6 indicates TCP is running on IP6 stack.
  95   @param[in]  Syn            If TRUE, the listen sockets are searched.
  96
  97   @return Pointer to the related TCP_CB. If NULL, no match is found.
  98
  99 **/
 100 TCP_CB *
 101 TcpLocateTcb (
 102   IN TCP_PORTNO      LocalPort,
 103   IN EFI_IP_ADDRESS  *LocalIp,
 104   IN TCP_PORTNO      RemotePort,
 105   IN EFI_IP_ADDRESS  *RemoteIp,
 106   IN UINT8           Version,
 107   IN BOOLEAN         Syn
 108   );
 109
 110 /**
 111   Insert a Tcb into the proper queue.
 112
 113   @param[in]  Tcb               Pointer to the TCP_CB to be inserted.
 114
 115   @retval 0                     The Tcb was inserted successfully.
 116   @retval -1                    An error condition occurred.
 117
 118 **/
 119 INTN
 120 TcpInsertTcb (
 121   IN TCP_CB *Tcb
 122   );
 123
 124 /**
 125   Clone a TCP_CB from Tcb.
 126
 127   @param[in]  Tcb                   Pointer to the TCP_CB to be cloned.
 128
 129   @return Pointer to the new cloned TCP_CB. If NULL, an error condition occurred.
 130
 131 **/
 132 TCP_CB *
 133 TcpCloneTcb (
 134   IN TCP_CB *Tcb
 135   );
 136
 137 /**
 138   Compute an ISS to be used by a new connection.
 139
 140   @return The result ISS.
 141
 142 **/
 143 TCP_SEQNO
 144 TcpGetIss (
 145   VOID
 146   );
 147
 148 /**
 149   Get the local mss.
 150
 151   @param[in]  Sock        Pointer to the socket to get mss.
 152
 153   @return The mss size.
 154
 155 **/
 156 UINT16
 157 TcpGetRcvMss (
 158   IN SOCKET  *Sock
 159   );
 160
 161 /**
 162   Set the Tcb's state.
 163
 164   @param[in]  Tcb                   Pointer to the TCP_CB of this TCP instance.
 165   @param[in]  State                 The state to be set.
 166
 167 **/
 168 VOID
 169 TcpSetState (
 170   IN TCP_CB *Tcb,
 171   IN UINT8  State
 172   );
 173
 174 /**
 175   Compute the TCP segment's checksum.
 176
 177   @param[in]  Nbuf       Pointer to the buffer that contains the TCP segment.
 178   @param[in]  HeadSum    The checksum value of the fixed part of pseudo header.
 179
 180   @return The checksum value.
 181
 182 **/
 183 UINT16
 184 TcpChecksum (
 185   IN NET_BUF *Nbuf,
 186   IN UINT16  HeadSum
 187   );
 188
 189 /**
 190   Translate the information from the head of the received TCP
 191   segment Nbuf contains, and fill it into a TCP_SEG structure.
 192
 193   @param[in]       Tcb           Pointer to the TCP_CB of this TCP instance.
 194   @param[in, out]  Nbuf          Pointer to the buffer contains the TCP segment.
 195
 196   @return Pointer to the TCP_SEG that contains the translated TCP head information.
 197
 198 **/
 199 TCP_SEG *
 200 TcpFormatNetbuf (
 201   IN     TCP_CB  *Tcb,
 202   IN OUT NET_BUF *Nbuf
 203   );
 204
 205 /**
 206   Initialize an active connection,
 207
 208   @param[in, out]  Tcb          Pointer to the TCP_CB that wants to initiate a
 209                                 connection.
 210
 211 **/
 212 VOID
 213 TcpOnAppConnect (
 214   IN OUT TCP_CB  *Tcb
 215   );
 216
 217 /**
 218   Application has consumed some data, check whether
 219   to send a window update ack or a delayed ack.
 220
 221   @param[in]  Tcb        Pointer to the TCP_CB of this TCP instance.
 222
 223 **/
 224 VOID
 225 TcpOnAppConsume (
 226   IN TCP_CB *Tcb
 227   );
 228
 229 /**
 230   Initiate the connection close procedure, called when
 231   applications want to close the connection.
 232
 233   @param[in, out]  Tcb          Pointer to the TCP_CB of this TCP instance.
 234
 235 **/
 236 VOID
 237 TcpOnAppClose (
 238   IN OUT TCP_CB *Tcb
 239   );
 240
 241 /**
 242   Check whether the application's newly delivered data can be sent out.
 243
 244   @param[in, out]  Tcb          Pointer to the TCP_CB of this TCP instance.
 245
 246   @retval 0                     The data has been sent out successfully.
 247   @retval -1                    The Tcb is not in a state that data is permitted to
 248                                 be sent out.
 249
 250 **/
 251 INTN
 252 TcpOnAppSend (
 253   IN OUT TCP_CB *Tcb
 254   );
 255
 256 /**
 257   Abort the connection by sending a reset segment: called
 258   when the application wants to abort the connection.
 259
 260   @param[in]  Tcb                   Pointer to the TCP_CB of the TCP instance.
 261
 262 **/
 263 VOID
 264 TcpOnAppAbort (
 265   IN TCP_CB *Tcb
 266   );
 267
 268 /**
 269   Reset the connection related with Tcb.
 270
 271   @param[in]  Tcb         Pointer to the TCP_CB of the connection to be reset.
 272
 273 **/
 274 VOID
 275 TcpResetConnection (
 276   IN TCP_CB *Tcb
 277   );
 278
 279 /**
 280   Install the device path protocol on the TCP instance.
 281
 282   @param[in]  Sock          Pointer to the socket representing the TCP instance.
 283
 284   @retval EFI_SUCCESS           The device path protocol installed.
 285   @retval other                 Failed to install the device path protocol.
 286
 287 **/
 288 EFI_STATUS
 289 TcpInstallDevicePath (
 290   IN SOCKET *Sock
 291   );
 292
 293
 294 //
 295 // Functions in TcpOutput.c
 296 //
 297
 298 /**
 299   Compute the sequence space left in the old receive window.
 300
 301   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 302
 303   @return The sequence space left in the old receive window.
 304
 305 **/
 306 UINT32
 307 TcpRcvWinOld (
 308   IN TCP_CB *Tcb
 309   );
 310
 311 /**
 312   Compute the current receive window.
 313
 314   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 315
 316   @return The size of the current receive window, in bytes.
 317
 318 **/
 319 UINT32
 320 TcpRcvWinNow (
 321   IN TCP_CB *Tcb
 322   );
 323
 324 /**
 325   Get the maximum SndNxt.
 326
 327   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 328
 329   @return The sequence number of the maximum SndNxt.
 330
 331 **/
 332 TCP_SEQNO
 333 TcpGetMaxSndNxt (
 334   IN TCP_CB *Tcb
 335   );
 336
 337 /**
 338   Compute how much data to send.
 339
 340   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 341   @param[in]  Force   If TRUE, ignore the sender's SWS avoidance algorithm
 342                       and send out data by force.
 343
 344   @return The length of the data that can be sent. If 0, no data can be sent.
 345
 346 **/
 347 UINT32
 348 TcpDataToSend (
 349   IN TCP_CB *Tcb,
 350   IN INTN   Force
 351   );
 352
 353 /**
 354   Retransmit the segment from sequence Seq.
 355
 356   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 357   @param[in]  Seq     The sequence number of the segment to be retransmitted.
 358
 359   @retval 0       The retransmission succeeded.
 360   @retval -1      An error condition occurred.
 361
 362 **/
 363 INTN
 364 TcpRetransmit (
 365   IN TCP_CB    *Tcb,
 366   IN TCP_SEQNO Seq
 367   );
 368
 369 /**
 370   Check whether to send data/SYN/FIN and piggyback an ACK.
 371
 372   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 373   @param[in]       Force   If TRUE, ignore the sender's SWS avoidance algorithm
 374                            and send out data by force.
 375
 376   @return The number of bytes sent.
 377
 378 **/
 379 INTN
 380 TcpToSendData (
 381   IN OUT TCP_CB *Tcb,
 382   IN     INTN   Force
 383   );
 384
 385 /**
 386   Check whether to send an ACK or delayed ACK.
 387
 388   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 389
 390 **/
 391 VOID
 392 TcpToSendAck (
 393   IN OUT TCP_CB *Tcb
 394   );
 395
 396 /**
 397   Send an ACK immediately.
 398
 399   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 400
 401 **/
 402 VOID
 403 TcpSendAck (
 404   IN OUT TCP_CB *Tcb
 405   );
 406
 407 /**
 408   Send a zero probe segment. It can be used by keepalive and zero window probe.
 409
 410   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 411
 412   @retval 0       The zero probe segment was sent out successfully.
 413   @retval other   An error condition occurred.
 414
 415 **/
 416 INTN
 417 TcpSendZeroProbe (
 418   IN OUT TCP_CB *Tcb
 419   );
 420
 421 /**
 422   Send a RESET segment in response to the segment received.
 423
 424   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance, may be NULL.
 425   @param[in]  Head    TCP header of the segment that triggers the reset.
 426   @param[in]  Len     Length of the segment that triggers the reset.
 427   @param[in]  Local   Local IP address.
 428   @param[in]  Remote  Remote peer's IP address.
 429   @param[in]  Version IP_VERSION_4 indicates TCP is running on IP4 stack,
 430                       IP_VERSION_6 indicates TCP is running on IP6 stack.
 431
 432   @retval     0       A reset is sent or no need to send it.
 433   @retval     -1      No reset is sent.
 434
 435 **/
 436 INTN
 437 TcpSendReset (
 438   IN TCP_CB          *Tcb,
 439   IN TCP_HEAD        *Head,
 440   IN INT32           Len,
 441   IN EFI_IP_ADDRESS  *Local,
 442   IN EFI_IP_ADDRESS  *Remote,
 443   IN UINT8           Version
 444   );
 445
 446 /**
 447   Verify that the segment is in good shape.
 448
 449   @param[in]  Nbuf    Buffer that contains the segment to be checked.
 450
 451   @retval     0       The segment is broken.
 452   @retval     1       The segment is in good shape.
 453
 454 **/
 455 INTN
 456 TcpVerifySegment (
 457   IN NET_BUF *Nbuf
 458   );
 459
 460 //
 461 // Functions from TcpInput.c
 462 //
 463
 464 /**
 465   Process the received ICMP error messages for TCP.
 466
 467   @param[in]  Nbuf     Buffer that contains part of the TCP segment without IP header
 468                        truncated from the ICMP error packet.
 469   @param[in]  IcmpErr  The ICMP error code interpreted from an ICMP error packet.
 470   @param[in]  Src      Source address of the ICMP error message.
 471   @param[in]  Dst      Destination address of the ICMP error message.
 472   @param[in]  Version  IP_VERSION_4 indicates IP4 stack, IP_VERSION_6 indicates
 473                        IP6 stack.
 474
 475 **/
 476 VOID
 477 TcpIcmpInput (
 478   IN NET_BUF         *Nbuf,
 479   IN UINT8           IcmpErr,
 480   IN EFI_IP_ADDRESS  *Src,
 481   IN EFI_IP_ADDRESS  *Dst,
 482   IN UINT8           Version
 483   );
 484
 485 /**
 486   Process the received TCP segments.
 487
 488   @param[in]  Nbuf     Buffer that contains received TCP segment without an IP header.
 489   @param[in]  Src      Source address of the segment, or the peer's IP address.
 490   @param[in]  Dst      Destination address of the segment, or the local end's IP
 491                        address.
 492   @param[in]  Version  IP_VERSION_4 indicates IP4 stack, IP_VERSION_6 indicates
 493                        IP6 stack.
 494
 495   @retval 0        The segment processed successfully. It is either accepted or
 496                    discarded. But no connection is reset by the segment.
 497   @retval -1       A connection is reset by the segment.
 498
 499 **/
 500 INTN
 501 TcpInput (
 502   IN NET_BUF         *Nbuf,
 503   IN EFI_IP_ADDRESS  *Src,
 504   IN EFI_IP_ADDRESS  *Dst,
 505   IN UINT8           Version
 506   );
 507
 508 //
 509 // Functions in TcpTimer.c
 510 //
 511
 512 /**
 513   Close the TCP connection.
 514
 515   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 516
 517 **/
 518 VOID
 519 TcpClose (
 520   IN OUT TCP_CB *Tcb
 521   );
 522
 523 /**
 524   Heart beat timer handler, queues the DPC at TPL_CALLBACK.
 525
 526   @param[in]  Event    Timer event signaled, ignored.
 527   @param[in]  Context  Context of the timer event, ignored.
 528
 529 **/
 530 VOID
 531 EFIAPI
 532 TcpTicking (
 533   IN EFI_EVENT Event,
 534   IN VOID      *Context
 535   );
 536
 537 /**
 538   Enable a TCP timer.
 539
 540   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 541   @param[in]       Timer    The index of the timer to be enabled.
 542   @param[in]       TimeOut  The timeout value of this timer.
 543
 544 **/
 545 VOID
 546 TcpSetTimer (
 547   IN OUT TCP_CB *Tcb,
 548   IN     UINT16 Timer,
 549   IN     UINT32 TimeOut
 550   );
 551
 552 /**
 553   Clear one TCP timer.
 554
 555   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 556   @param[in]       Timer    The index of the timer to be cleared.
 557
 558 **/
 559 VOID
 560 TcpClearTimer (
 561   IN OUT TCP_CB *Tcb,
 562   IN     UINT16 Timer
 563   );
 564
 565 /**
 566   Clear all TCP timers.
 567
 568   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 569
 570 **/
 571 VOID
 572 TcpClearAllTimer (
 573   IN OUT TCP_CB *Tcb
 574   );
 575
 576 /**
 577   Enable the window prober timer and set the timeout value.
 578
 579   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 580
 581 **/
 582 VOID
 583 TcpSetProbeTimer (
 584   IN OUT TCP_CB *Tcb
 585   );
 586
 587 /**
 588   Enable the keepalive timer and set the timeout value.
 589
 590   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 591
 592 **/
 593 VOID
 594 TcpSetKeepaliveTimer (
 595   IN OUT TCP_CB *Tcb
 596   );
 597
 598 //
 599 // Functions in TcpIo.c
 600 //
 601
 602 /**
 603   Packet receive callback function provided to IP_IO. Used to call
 604   the proper function to handle the packet received by IP.
 605
 606   @param[in] Status        Result of the receive request.
 607   @param[in] IcmpErr       Valid when Status is EFI_ICMP_ERROR.
 608   @param[in] NetSession    The IP session for the received packet.
 609   @param[in] Pkt           Packet received.
 610   @param[in] Context       The data provided by the user for the received packet when
 611                            the callback is registered in IP_IO_OPEN_DATA::RcvdContext.
 612                            This is an optional parameter that may be NULL.
 613
 614 **/
 615 VOID
 616 EFIAPI
 617 TcpRxCallback (
 618   IN EFI_STATUS                       Status,
 619   IN UINT8                            IcmpErr,
 620   IN EFI_NET_SESSION_DATA             *NetSession,
 621   IN NET_BUF                          *Pkt,
 622   IN VOID                             *Context    OPTIONAL
 623   );
 624
 625 /**
 626   Send the segment to IP via IpIo function.
 627
 628   @param[in]  Tcb                Pointer to the TCP_CB of this TCP instance.
 629   @param[in]  Nbuf               Pointer to the TCP segment to be sent.
 630   @param[in]  Src                Source address of the TCP segment.
 631   @param[in]  Dest               Destination address of the TCP segment.
 632   @param[in]  Version            IP_VERSION_4 or IP_VERSION_6
 633
 634   @retval 0                      The segment was sent out successfully.
 635   @retval -1                     The segment failed to be sent.
 636
 637 **/
 638 INTN
 639 TcpSendIpPacket (
 640   IN TCP_CB          *Tcb,
 641   IN NET_BUF         *Nbuf,
 642   IN EFI_IP_ADDRESS  *Src,
 643   IN EFI_IP_ADDRESS  *Dest,
 644   IN UINT8           Version
 645   );
 646
 647 /**
 648   Refresh the remote peer's Neighbor Cache State if already exists.
 649
 650   @param[in]  Tcb                Pointer to the TCP_CB of this TCP instance.
 651   @param[in]  Neighbor           Source address of the TCP segment.
 652   @param[in]  Timeout            Time in 100-ns units that this entry will remain
 653                                  in the neighbor cache. A value of zero means that
 654                                  the entry  is permanent. A value of non-zero means
 655                                  that the entry is  dynamic and will be deleted
 656                                  after Timeout.
 657
 658   @retval EFI_SUCCESS            Successfully updated the neighbor relationship.
 659   @retval EFI_NOT_STARTED        The IpIo is not configured.
 660   @retval EFI_INVALID_PARAMETER  Any input parameter is invalid.
 661   @retval EFI_OUT_OF_RESOURCES   Failed to allocate some resources.
 662   @retval EFI_NOT_FOUND          This entry is not in the neighbor table.
 663
 664 **/
 665 EFI_STATUS
 666 Tcp6RefreshNeighbor (
 667   IN TCP_CB          *Tcb,
 668   IN EFI_IP_ADDRESS  *Neighbor,
 669   IN UINT32          Timeout
 670   );
 671
 672 //
 673 // Functions in TcpDispatcher.c
 674 //
 675
 676 /**
 677   The procotol handler provided to the socket layer, used to
 678   dispatch the socket level requests by calling the corresponding
 679   TCP layer functions.
 680
 681   @param[in]  Sock               Pointer to the socket of this TCP instance.
 682   @param[in]  Request            The code of this operation request.
 683   @param[in]  Data               Pointer to the operation specific data passed in
 684                                  together with the operation request. This is an
 685                                  optional parameter that may be NULL.
 686
 687   @retval EFI_SUCCESS            The socket request completed successfully.
 688   @retval other                  The error status returned by the corresponding TCP
 689                                  layer function.
 690
 691 **/
 692 EFI_STATUS
 693 TcpDispatcher (
 694   IN SOCKET                  *Sock,
 695   IN UINT8                   Request,
 696   IN VOID                    *Data    OPTIONAL
 697   );
 698
 699 #endif