NetworkPkg/TcpDxe/TcpFunc.h

   1 /** @file
   2   Declaration of external functions shared in TCP driver.
   3
   4   Copyright (c) 2009 - 2010, 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   Set the Tcp variable data.
 281
 282   @param[in]  TcpService        Tcp service data.
 283
 284   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to set the variable.
 285   @retval other                 Set variable failed.
 286
 287 **/
 288 EFI_STATUS
 289 TcpSetVariableData (
 290   IN TCP_SERVICE_DATA  *TcpService
 291   );
 292
 293 /**
 294   Clear the variable and free the resource.
 295
 296   @param[in]  TcpService            Tcp service data.
 297
 298 **/
 299 VOID
 300 TcpClearVariableData (
 301   IN TCP_SERVICE_DATA  *TcpService
 302   );
 303
 304 /**
 305   Install the device path protocol on the TCP instance.
 306
 307   @param[in]  Sock          Pointer to the socket representing the TCP instance.
 308
 309   @retval EFI_SUCCESS           The device path protocol installed.
 310   @retval other                 Failed to install the device path protocol.
 311
 312 **/
 313 EFI_STATUS
 314 TcpInstallDevicePath (
 315   IN SOCKET *Sock
 316   );
 317
 318
 319 //
 320 // Functions in TcpOutput.c
 321 //
 322
 323 /**
 324   Compute the sequence space left in the old receive window.
 325
 326   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 327
 328   @return The sequence space left in the old receive window.
 329
 330 **/
 331 UINT32
 332 TcpRcvWinOld (
 333   IN TCP_CB *Tcb
 334   );
 335
 336 /**
 337   Compute the current receive window.
 338
 339   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 340
 341   @return The size of the current receive window, in bytes.
 342
 343 **/
 344 UINT32
 345 TcpRcvWinNow (
 346   IN TCP_CB *Tcb
 347   );
 348
 349 /**
 350   Get the maximum SndNxt.
 351
 352   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 353
 354   @return The sequence number of the maximum SndNxt.
 355
 356 **/
 357 TCP_SEQNO
 358 TcpGetMaxSndNxt (
 359   IN TCP_CB *Tcb
 360   );
 361
 362 /**
 363   Compute how much data to send.
 364
 365   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 366   @param[in]  Force   If TRUE, ignore the sender's SWS avoidance algorithm
 367                       and send out data by force.
 368
 369   @return The length of the data that can be sent. If 0, no data can be sent.
 370
 371 **/
 372 UINT32
 373 TcpDataToSend (
 374   IN TCP_CB *Tcb,
 375   IN INTN   Force
 376   );
 377
 378 /**
 379   Retransmit the segment from sequence Seq.
 380
 381   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance.
 382   @param[in]  Seq     The sequence number of the segment to be retransmitted.
 383
 384   @retval 0       The retransmission succeeded.
 385   @retval -1      An error condition occurred.
 386
 387 **/
 388 INTN
 389 TcpRetransmit (
 390   IN TCP_CB    *Tcb,
 391   IN TCP_SEQNO Seq
 392   );
 393
 394 /**
 395   Check whether to send data/SYN/FIN and piggyback an ACK.
 396
 397   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 398   @param[in]       Force   If TRUE, ignore the sender's SWS avoidance algorithm
 399                            and send out data by force.
 400
 401   @return The number of bytes sent.
 402
 403 **/
 404 INTN
 405 TcpToSendData (
 406   IN OUT TCP_CB *Tcb,
 407   IN     INTN   Force
 408   );
 409
 410 /**
 411   Check whether to send an ACK or delayed ACK.
 412
 413   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 414
 415 **/
 416 VOID
 417 TcpToSendAck (
 418   IN OUT TCP_CB *Tcb
 419   );
 420
 421 /**
 422   Send an ACK immediately.
 423
 424   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 425
 426 **/
 427 VOID
 428 TcpSendAck (
 429   IN OUT TCP_CB *Tcb
 430   );
 431
 432 /**
 433   Send a zero probe segment. It can be used by keepalive and zero window probe.
 434
 435   @param[in, out]  Tcb     Pointer to the TCP_CB of this TCP instance.
 436
 437   @retval 0       The zero probe segment was sent out successfully.
 438   @retval other   An error condition occurred.
 439
 440 **/
 441 INTN
 442 TcpSendZeroProbe (
 443   IN OUT TCP_CB *Tcb
 444   );
 445
 446 /**
 447   Send a RESET segment in response to the segment received.
 448
 449   @param[in]  Tcb     Pointer to the TCP_CB of this TCP instance, may be NULL.
 450   @param[in]  Head    TCP header of the segment that triggers the reset.
 451   @param[in]  Len     Length of the segment that triggers the reset.
 452   @param[in]  Local   Local IP address.
 453   @param[in]  Remote  Remote peer's IP address.
 454   @param[in]  Version IP_VERSION_4 indicates TCP is running on IP4 stack,
 455                       IP_VERSION_6 indicates TCP is running on IP6 stack.
 456
 457   @retval     0       A reset is sent or no need to send it.
 458   @retval     -1      No reset is sent.
 459
 460 **/
 461 INTN
 462 TcpSendReset (
 463   IN TCP_CB          *Tcb,
 464   IN TCP_HEAD        *Head,
 465   IN INT32           Len,
 466   IN EFI_IP_ADDRESS  *Local,
 467   IN EFI_IP_ADDRESS  *Remote,
 468   IN UINT8           Version
 469   );
 470
 471 /**
 472   Verify that the segment is in good shape.
 473
 474   @param[in]  Nbuf    Buffer that contains the segment to be checked.
 475
 476   @retval     0       The segment is broken.
 477   @retval     1       The segment is in good shape.
 478
 479 **/
 480 INTN
 481 TcpVerifySegment (
 482   IN NET_BUF *Nbuf
 483   );
 484
 485 //
 486 // Functions from TcpInput.c
 487 //
 488
 489 /**
 490   Process the received ICMP error messages for TCP.
 491
 492   @param[in]  Nbuf     Buffer that contains part of the TCP segment without IP header
 493                        truncated from the ICMP error packet.
 494   @param[in]  IcmpErr  The ICMP error code interpreted from an ICMP error packet.
 495   @param[in]  Src      Source address of the ICMP error message.
 496   @param[in]  Dst      Destination address of the ICMP error message.
 497   @param[in]  Version  IP_VERSION_4 indicates IP4 stack, IP_VERSION_6 indicates
 498                        IP6 stack.
 499
 500 **/
 501 VOID
 502 TcpIcmpInput (
 503   IN NET_BUF         *Nbuf,
 504   IN UINT8           IcmpErr,
 505   IN EFI_IP_ADDRESS  *Src,
 506   IN EFI_IP_ADDRESS  *Dst,
 507   IN UINT8           Version
 508   );
 509
 510 /**
 511   Process the received TCP segments.
 512
 513   @param[in]  Nbuf     Buffer that contains received TCP segment without an IP header.
 514   @param[in]  Src      Source address of the segment, or the peer's IP address.
 515   @param[in]  Dst      Destination address of the segment, or the local end's IP
 516                        address.
 517   @param[in]  Version  IP_VERSION_4 indicates IP4 stack, IP_VERSION_6 indicates
 518                        IP6 stack.
 519
 520   @retval 0        The segment processed successfully. It is either accepted or
 521                    discarded. But no connection is reset by the segment.
 522   @retval -1       A connection is reset by the segment.
 523
 524 **/
 525 INTN
 526 TcpInput (
 527   IN NET_BUF         *Nbuf,
 528   IN EFI_IP_ADDRESS  *Src,
 529   IN EFI_IP_ADDRESS  *Dst,
 530   IN UINT8           Version
 531   );
 532
 533 //
 534 // Functions in TcpTimer.c
 535 //
 536
 537 /**
 538   Close the TCP connection.
 539
 540   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 541
 542 **/
 543 VOID
 544 TcpClose (
 545   IN OUT TCP_CB *Tcb
 546   );
 547
 548 /**
 549   Heart beat timer handler, queues the DPC at TPL_CALLBACK.
 550
 551   @param[in]  Event    Timer event signaled, ignored.
 552   @param[in]  Context  Context of the timer event, ignored.
 553
 554 **/
 555 VOID
 556 EFIAPI
 557 TcpTicking (
 558   IN EFI_EVENT Event,
 559   IN VOID      *Context
 560   );
 561
 562 /**
 563   Enable a TCP timer.
 564
 565   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 566   @param[in]       Timer    The index of the timer to be enabled.
 567   @param[in]       TimeOut  The timeout value of this timer.
 568
 569 **/
 570 VOID
 571 TcpSetTimer (
 572   IN OUT TCP_CB *Tcb,
 573   IN     UINT16 Timer,
 574   IN     UINT32 TimeOut
 575   );
 576
 577 /**
 578   Clear one TCP timer.
 579
 580   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 581   @param[in]       Timer    The index of the timer to be cleared.
 582
 583 **/
 584 VOID
 585 TcpClearTimer (
 586   IN OUT TCP_CB *Tcb,
 587   IN     UINT16 Timer
 588   );
 589
 590 /**
 591   Clear all TCP timers.
 592
 593   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 594
 595 **/
 596 VOID
 597 TcpClearAllTimer (
 598   IN OUT TCP_CB *Tcb
 599   );
 600
 601 /**
 602   Enable the window prober timer and set the timeout value.
 603
 604   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 605
 606 **/
 607 VOID
 608 TcpSetProbeTimer (
 609   IN OUT TCP_CB *Tcb
 610   );
 611
 612 /**
 613   Enable the keepalive timer and set the timeout value.
 614
 615   @param[in, out]  Tcb      Pointer to the TCP_CB of this TCP instance.
 616
 617 **/
 618 VOID
 619 TcpSetKeepaliveTimer (
 620   IN OUT TCP_CB *Tcb
 621   );
 622
 623 //
 624 // Functions in TcpIo.c
 625 //
 626
 627 /**
 628   Packet receive callback function provided to IP_IO. Used to call
 629   the proper function to handle the packet received by IP.
 630
 631   @param[in] Status        Result of the receive request.
 632   @param[in] IcmpErr       Valid when Status is EFI_ICMP_ERROR.
 633   @param[in] NetSession    The IP session for the received packet.
 634   @param[in] Pkt           Packet received.
 635   @param[in] Context       The data provided by the user for the received packet when
 636                            the callback is registered in IP_IO_OPEN_DATA::RcvdContext.
 637                            This is an optional parameter that may be NULL.
 638
 639 **/
 640 VOID
 641 EFIAPI
 642 TcpRxCallback (
 643   IN EFI_STATUS                       Status,
 644   IN UINT8                            IcmpErr,
 645   IN EFI_NET_SESSION_DATA             *NetSession,
 646   IN NET_BUF                          *Pkt,
 647   IN VOID                             *Context    OPTIONAL
 648   );
 649
 650 /**
 651   Send the segment to IP via IpIo function.
 652
 653   @param[in]  Tcb                Pointer to the TCP_CB of this TCP instance.
 654   @param[in]  Nbuf               Pointer to the TCP segment to be sent.
 655   @param[in]  Src                Source address of the TCP segment.
 656   @param[in]  Dest               Destination address of the TCP segment.
 657   @param[in]  Version            IP_VERSION_4 or IP_VERSION_6
 658
 659   @retval 0                      The segment was sent out successfully.
 660   @retval -1                     The segment failed to be sent.
 661
 662 **/
 663 INTN
 664 TcpSendIpPacket (
 665   IN TCP_CB          *Tcb,
 666   IN NET_BUF         *Nbuf,
 667   IN EFI_IP_ADDRESS  *Src,
 668   IN EFI_IP_ADDRESS  *Dest,
 669   IN UINT8           Version
 670   );
 671
 672 /**
 673   Refresh the remote peer's Neighbor Cache State if already exists.
 674
 675   @param[in]  Tcb                Pointer to the TCP_CB of this TCP instance.
 676   @param[in]  Neighbor           Source address of the TCP segment.
 677   @param[in]  Timeout            Time in 100-ns units that this entry will remain
 678                                  in the neighbor cache. A value of zero means that
 679                                  the entry  is permanent. A value of non-zero means
 680                                  that the entry is  dynamic and will be deleted
 681                                  after Timeout.
 682
 683   @retval EFI_SUCCESS            Successfully updated the neighbor relationship.
 684   @retval EFI_NOT_STARTED        The IpIo is not configured.
 685   @retval EFI_INVALID_PARAMETER  Any input parameter is invalid.
 686   @retval EFI_OUT_OF_RESOURCES   Failed to allocate some resources.
 687   @retval EFI_NOT_FOUND          This entry is not in the neighbor table.
 688
 689 **/
 690 EFI_STATUS
 691 Tcp6RefreshNeighbor (
 692   IN TCP_CB          *Tcb,
 693   IN EFI_IP_ADDRESS  *Neighbor,
 694   IN UINT32          Timeout
 695   );
 696
 697 //
 698 // Functions in TcpDispatcher.c
 699 //
 700
 701 /**
 702   The procotol handler provided to the socket layer, used to
 703   dispatch the socket level requests by calling the corresponding
 704   TCP layer functions.
 705
 706   @param[in]  Sock               Pointer to the socket of this TCP instance.
 707   @param[in]  Request            The code of this operation request.
 708   @param[in]  Data               Pointer to the operation specific data passed in
 709                                  together with the operation request. This is an
 710                                  optional parameter that may be NULL.
 711
 712   @retval EFI_SUCCESS            The socket request completed successfully.
 713   @retval other                  The error status returned by the corresponding TCP
 714                                  layer function.
 715
 716 **/
 717 EFI_STATUS
 718 TcpDispatcher (
 719   IN SOCKET                  *Sock,
 720   IN UINT8                   Request,
 721   IN VOID                    *Data    OPTIONAL
 722   );
 723
 724 #endif