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