MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c

   1 /** @file
   2   Help functions to access UDP service, it is used by both the DHCP and MTFTP.
   3
   4 Copyright (c) 2005 - 2007, Intel Corporation.<BR>
   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<BR>
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12 **/
  13
  14 #include <Uefi.h>
  15
  16 #include <Protocol/Udp4.h>
  17
  18 #include <Library/UdpIoLib.h>
  19 #include <Library/BaseLib.h>
  20 #include <Library/DebugLib.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24 #include <Library/DpcLib.h>
  25
  26
  27 /**
  28   Free a UDP_TX_TOKEN. The TX event is closed.
  29
  30   @param[in]  Token                 The UDP_TX_TOKEN to release.
  31
  32 **/
  33 VOID
  34 UdpIoFreeTxToken (
  35   IN UDP_TX_TOKEN           *Token
  36   )
  37 {
  38   gBS->CloseEvent (Token->UdpToken.Event);
  39   gBS->FreePool (Token);
  40 }
  41
  42 /**
  43   Free a UDP_RX_TOKEN. The RX event is closed.
  44
  45   @param[in]  Token                 The UDP_RX_TOKEN to release.
  46
  47 **/
  48 VOID
  49 UdpIoFreeRxToken (
  50   IN UDP_RX_TOKEN           *Token
  51   )
  52 {
  53   gBS->CloseEvent (Token->UdpToken.Event);
  54   gBS->FreePool (Token);
  55 }
  56
  57 /**
  58   The callback function when the packet is sent by UDP.
  59
  60   It will remove the packet from the local list then call
  61   the packet owner's callback function set by UdpIoSendDatagram.
  62
  63   @param[in]  Context               The UDP TX Token.
  64
  65 **/
  66 VOID
  67 EFIAPI
  68 UdpIoOnDgramSentDpc (
  69   IN VOID                   *Context
  70   )
  71 {
  72   UDP_TX_TOKEN              *Token;
  73
  74   Token   = (UDP_TX_TOKEN *) Context;
  75   ASSERT (Token->Signature == UDP_IO_TX_SIGNATURE);
  76
  77   RemoveEntryList (&Token->Link);
  78   Token->CallBack (Token->Packet, NULL, Token->UdpToken.Status, Token->Context);
  79
  80   UdpIoFreeTxToken (Token);
  81 }
  82
  83 /**
  84   Request UdpIoOnDgramSentDpc as a DPC at TPL_CALLBACK.
  85
  86   @param[in]  Event                 The event signaled.
  87   @param[in]  Context               The UDP TX Token.
  88
  89 **/
  90 VOID
  91 EFIAPI
  92 UdpIoOnDgramSent (
  93   IN EFI_EVENT              Event,
  94   IN VOID                   *Context
  95   )
  96 {
  97   //
  98   // Request UdpIoOnDgramSentDpc as a DPC at TPL_CALLBACK
  99   //
 100   QueueDpc (TPL_CALLBACK, UdpIoOnDgramSentDpc, Context);
 101 }
 102
 103 /**
 104   Recycle the received UDP data.
 105
 106   @param[in]  Context               The UDP_RX_TOKEN.
 107
 108 **/
 109 VOID
 110 UdpIoRecycleDgram (
 111   IN VOID                   *Context
 112   )
 113 {
 114   UDP_RX_TOKEN              *Token;
 115
 116   Token = (UDP_RX_TOKEN *) Context;
 117   gBS->SignalEvent (Token->UdpToken.Packet.RxData->RecycleSignal);
 118   UdpIoFreeRxToken (Token);
 119 }
 120
 121 /**
 122   The event handle for UDP receive request.
 123
 124   It will build a NET_BUF from the recieved UDP data, then deliver it
 125   to the receiver.
 126
 127   @param[in]  Context               The UDP RX token.
 128
 129 **/
 130 VOID
 131 EFIAPI
 132 UdpIoOnDgramRcvdDpc (
 133   IN VOID                   *Context
 134   )
 135 {
 136   EFI_UDP4_COMPLETION_TOKEN *UdpToken;
 137   EFI_UDP4_RECEIVE_DATA     *UdpRxData;
 138   EFI_UDP4_SESSION_DATA     *UdpSession;
 139   UDP_RX_TOKEN              *Token;
 140   UDP_POINTS                Points;
 141   NET_BUF                   *Netbuf;
 142
 143   Token   = (UDP_RX_TOKEN *) Context;
 144
 145   ASSERT ((Token->Signature == UDP_IO_RX_SIGNATURE) &&
 146           (Token == Token->UdpIo->RecvRequest));
 147
 148   //
 149   // Clear the receive request first in case that the caller
 150   // wants to restart the receive in the callback.
 151   //
 152   Token->UdpIo->RecvRequest = NULL;
 153
 154   UdpToken  = &Token->UdpToken;
 155   UdpRxData = UdpToken->Packet.RxData;
 156
 157   if (EFI_ERROR (UdpToken->Status) || (UdpRxData == NULL)) {
 158     if (UdpToken->Status != EFI_ABORTED) {
 159       //
 160       // Invoke the CallBack only if the reception is not actively aborted.
 161       //
 162       Token->CallBack (NULL, NULL, UdpToken->Status, Token->Context);
 163     }
 164
 165     UdpIoFreeRxToken (Token);
 166     return;
 167   }
 168
 169   //
 170   // Build a NET_BUF from the UDP receive data, then deliver it up.
 171   //
 172   Netbuf = NetbufFromExt (
 173              (NET_FRAGMENT *) UdpRxData->FragmentTable,
 174              UdpRxData->FragmentCount,
 175              0,
 176              (UINT32) Token->HeadLen,
 177              UdpIoRecycleDgram,
 178              Token
 179              );
 180
 181   if (Netbuf == NULL) {
 182     gBS->SignalEvent (UdpRxData->RecycleSignal);
 183     Token->CallBack (NULL, NULL, EFI_OUT_OF_RESOURCES, Token->Context);
 184
 185     UdpIoFreeRxToken (Token);
 186     return;
 187   }
 188
 189   UdpSession        = &UdpRxData->UdpSession;
 190   Points.LocalPort  = UdpSession->DestinationPort;
 191   Points.RemotePort = UdpSession->SourcePort;
 192
 193   CopyMem (&Points.LocalAddr, &UdpSession->DestinationAddress, sizeof (IP4_ADDR));
 194   CopyMem (&Points.RemoteAddr, &UdpSession->SourceAddress, sizeof (IP4_ADDR));
 195   Points.LocalAddr  = NTOHL (Points.LocalAddr);
 196   Points.RemoteAddr = NTOHL (Points.RemoteAddr);
 197
 198   Token->CallBack (Netbuf, &Points, EFI_SUCCESS, Token->Context);
 199 }
 200
 201 /**
 202   Request UdpIoOnDgramRcvdDpc() as a DPC at TPL_CALLBACK.
 203
 204   @param[in]  Event                 The UDP receive request event.
 205   @param[in]  Context               The UDP RX token.
 206
 207 **/
 208 VOID
 209 EFIAPI
 210 UdpIoOnDgramRcvd (
 211   IN EFI_EVENT              Event,
 212   IN VOID                   *Context
 213   )
 214 {
 215   //
 216   // Request UdpIoOnDgramRcvdDpc as a DPC at TPL_CALLBACK
 217   //
 218   QueueDpc (TPL_CALLBACK, UdpIoOnDgramRcvdDpc, Context);
 219 }
 220
 221 /**
 222   Create a UDP_RX_TOKEN to wrap the request.
 223
 224   @param[in]  UdpIo                 The UdpIo to receive packets from.
 225   @param[in]  CallBack              The function to call when receive finished.
 226   @param[in]  Context               The opaque parameter to the CallBack.
 227   @param[in]  HeadLen               The head length to reserver for the packet.
 228
 229   @return The Wrapped request or NULL if failed to allocate resources or some errors happened.
 230
 231 **/
 232 UDP_RX_TOKEN *
 233 UdpIoCreateRxToken (
 234   IN UDP_IO_PORT            *UdpIo,
 235   IN UDP_IO_CALLBACK        CallBack,
 236   IN VOID                   *Context,
 237   IN UINT32                 HeadLen
 238   )
 239 {
 240   UDP_RX_TOKEN              *Token;
 241   EFI_STATUS                Status;
 242
 243   Token = AllocatePool (sizeof (UDP_RX_TOKEN));
 244
 245   if (Token == NULL) {
 246     return NULL;
 247   }
 248
 249   Token->Signature              = UDP_IO_RX_SIGNATURE;
 250   Token->UdpIo                  = UdpIo;
 251   Token->CallBack               = CallBack;
 252   Token->Context                = Context;
 253   Token->HeadLen                = HeadLen;
 254
 255   Token->UdpToken.Status        = EFI_NOT_READY;
 256   Token->UdpToken.Packet.RxData = NULL;
 257
 258   Status = gBS->CreateEvent (
 259                   EVT_NOTIFY_SIGNAL,
 260                   TPL_NOTIFY,
 261                   UdpIoOnDgramRcvd,
 262                   Token,
 263                   &Token->UdpToken.Event
 264                   );
 265
 266   if (EFI_ERROR (Status)) {
 267     gBS->FreePool (Token);
 268     return NULL;
 269   }
 270
 271   return Token;
 272 }
 273
 274 /**
 275   Wrap a transmit request into a UDP_TX_TOKEN.
 276
 277   @param[in]  UdpIo                 The UdpIo port to send packet to.
 278   @param[in]  Packet                The user's packet.
 279   @param[in]  EndPoint              The local and remote access point.
 280   @param[in]  Gateway               The overrided next hop.
 281   @param[in]  CallBack              The function to call when transmission completed.
 282   @param[in]  Context               The opaque parameter to the call back.
 283
 284   @return The wrapped transmission request or NULL if failed to allocate resources
 285           or for some errors.
 286
 287 **/
 288 UDP_TX_TOKEN *
 289 UdpIoWrapTx (
 290   IN UDP_IO_PORT            *UdpIo,
 291   IN NET_BUF                *Packet,
 292   IN UDP_POINTS             *EndPoint  OPTIONAL,
 293   IN IP4_ADDR               Gateway,
 294   IN UDP_IO_CALLBACK        CallBack,
 295   IN VOID                   *Context
 296   )
 297 {
 298   UDP_TX_TOKEN              *Token;
 299   EFI_UDP4_COMPLETION_TOKEN *UdpToken;
 300   EFI_UDP4_TRANSMIT_DATA    *UdpTxData;
 301   EFI_STATUS                Status;
 302   UINT32                    Count;
 303   IP4_ADDR                  Ip;
 304
 305   Token = AllocatePool (sizeof (UDP_TX_TOKEN) +
 306                            sizeof (EFI_UDP4_FRAGMENT_DATA) * (Packet->BlockOpNum - 1));
 307
 308   if (Token == NULL) {
 309     return NULL;
 310   }
 311
 312   Token->Signature  = UDP_IO_TX_SIGNATURE;
 313   InitializeListHead (&Token->Link);
 314
 315   Token->UdpIo      = UdpIo;
 316   Token->CallBack   = CallBack;
 317   Token->Packet     = Packet;
 318   Token->Context    = Context;
 319
 320   UdpToken          = &(Token->UdpToken);
 321   UdpToken->Status  = EFI_NOT_READY;
 322
 323   Status = gBS->CreateEvent (
 324                   EVT_NOTIFY_SIGNAL,
 325                   TPL_NOTIFY,
 326                   UdpIoOnDgramSent,
 327                   Token,
 328                   &UdpToken->Event
 329                   );
 330
 331   if (EFI_ERROR (Status)) {
 332     gBS->FreePool (Token);
 333     return NULL;
 334   }
 335
 336   UdpTxData                 = &Token->UdpTxData;
 337   UdpToken->Packet.TxData   = UdpTxData;
 338
 339   UdpTxData->UdpSessionData = NULL;
 340   UdpTxData->GatewayAddress = NULL;
 341
 342   if (EndPoint != NULL) {
 343     Ip = HTONL (EndPoint->LocalAddr);
 344     CopyMem (&Token->UdpSession.SourceAddress, &Ip, sizeof (EFI_IPv4_ADDRESS));
 345
 346     Ip = HTONL (EndPoint->RemoteAddr);
 347     CopyMem (&Token->UdpSession.DestinationAddress, &Ip, sizeof (EFI_IPv4_ADDRESS));
 348
 349     Token->UdpSession.SourcePort      = EndPoint->LocalPort;
 350     Token->UdpSession.DestinationPort = EndPoint->RemotePort;
 351     UdpTxData->UdpSessionData         = &Token->UdpSession;
 352   }
 353
 354   if (Gateway != 0) {
 355     Ip = HTONL (Gateway);
 356     CopyMem (&Token->Gateway, &Ip, sizeof (EFI_IPv4_ADDRESS));
 357
 358     UdpTxData->GatewayAddress = &Token->Gateway;
 359   }
 360
 361   UdpTxData->DataLength = Packet->TotalSize;
 362   Count                 = Packet->BlockOpNum;
 363   NetbufBuildExt (Packet, (NET_FRAGMENT *) UdpTxData->FragmentTable, &Count);
 364   UdpTxData->FragmentCount = Count;
 365
 366   return Token;
 367 }
 368
 369 /**
 370   Create a UDP_IO_PORT to access the UDP service. It will create and configure
 371   a UDP child.
 372
 373   The function will locate the UDP service binding prototype on the Controller
 374   parameter and use it to create a UDP child (aka Udp instance). Then the UDP
 375   child will be configured by calling Configure function prototype. Any failures
 376   in creating or configure the UDP child will lead to the failure of UDP_IO_PORT
 377   creation.
 378
 379   @param[in]  Controller            The controller that has the UDP service binding.
 380                                     protocol installed.
 381   @param[in]  Image                 The image handle for the driver.
 382   @param[in]  Configure             The function to configure the created UDP child.
 383   @param[in]  Context               The opaque parameter for the Configure funtion.
 384
 385   @return Newly-created UDP_IO_PORT or NULL if failed.
 386
 387 **/
 388 UDP_IO_PORT *
 389 EFIAPI
 390 UdpIoCreatePort (
 391   IN  EFI_HANDLE            Controller,
 392   IN  EFI_HANDLE            Image,
 393   IN  UDP_IO_CONFIG         Configure,
 394   IN  VOID                  *Context
 395   )
 396 {
 397   UDP_IO_PORT               *UdpIo;
 398   EFI_STATUS                Status;
 399
 400   ASSERT (Configure != NULL);
 401
 402   UdpIo = AllocatePool (sizeof (UDP_IO_PORT));
 403
 404   if (UdpIo == NULL) {
 405     return NULL;
 406   }
 407
 408   UdpIo->Signature    = UDP_IO_SIGNATURE;
 409   InitializeListHead (&UdpIo->Link);
 410   UdpIo->RefCnt       = 1;
 411
 412   UdpIo->Controller   = Controller;
 413   UdpIo->Image        = Image;
 414
 415   InitializeListHead (&UdpIo->SentDatagram);
 416   UdpIo->RecvRequest  = NULL;
 417   UdpIo->UdpHandle    = NULL;
 418
 419   //
 420   // Create a UDP child then open and configure it
 421   //
 422   Status = NetLibCreateServiceChild (
 423              Controller,
 424              Image,
 425              &gEfiUdp4ServiceBindingProtocolGuid,
 426              &UdpIo->UdpHandle
 427              );
 428
 429   if (EFI_ERROR (Status)) {
 430     goto FREE_MEM;
 431   }
 432
 433   Status = gBS->OpenProtocol (
 434                   UdpIo->UdpHandle,
 435                   &gEfiUdp4ProtocolGuid,
 436                   (VOID **) &UdpIo->Udp,
 437                   Image,
 438                   Controller,
 439                   EFI_OPEN_PROTOCOL_BY_DRIVER
 440                   );
 441
 442   if (EFI_ERROR (Status)) {
 443     goto FREE_CHILD;
 444   }
 445
 446   if (EFI_ERROR (Configure (UdpIo, Context))) {
 447     goto CLOSE_PROTOCOL;
 448   }
 449
 450   Status = UdpIo->Udp->GetModeData (UdpIo->Udp, NULL, NULL, NULL, &UdpIo->SnpMode);
 451
 452   if (EFI_ERROR (Status)) {
 453     goto CLOSE_PROTOCOL;
 454   }
 455
 456   return UdpIo;
 457
 458 CLOSE_PROTOCOL:
 459   gBS->CloseProtocol (UdpIo->UdpHandle, &gEfiUdp4ProtocolGuid, Image, Controller);
 460
 461 FREE_CHILD:
 462   NetLibDestroyServiceChild (
 463     Controller,
 464     Image,
 465     &gEfiUdp4ServiceBindingProtocolGuid,
 466     UdpIo->UdpHandle
 467     );
 468
 469 FREE_MEM:
 470   gBS->FreePool (UdpIo);
 471   return NULL;
 472 }
 473
 474 /**
 475   Cancel all the sent datagram that pass the selection criteria of ToCancel.
 476   If ToCancel is NULL, all the datagrams are cancelled.
 477
 478   @param[in]  UdpIo                 The UDP_IO_PORT to cancel packet.
 479   @param[in]  IoStatus              The IoStatus to return to the packet owners.
 480   @param[in]  ToCancel              The select funtion to test whether to cancel this
 481                                     packet or not.
 482   @param[in]  Context               The opaque parameter to the ToCancel.
 483
 484 **/
 485 VOID
 486 EFIAPI
 487 UdpIoCancelDgrams (
 488   IN UDP_IO_PORT            *UdpIo,
 489   IN EFI_STATUS             IoStatus,
 490   IN UDP_IO_TO_CANCEL       ToCancel,        OPTIONAL
 491   IN VOID                   *Context
 492   )
 493 {
 494   LIST_ENTRY                *Entry;
 495   LIST_ENTRY                *Next;
 496   UDP_TX_TOKEN              *Token;
 497
 498   NET_LIST_FOR_EACH_SAFE (Entry, Next, &UdpIo->SentDatagram) {
 499     Token = NET_LIST_USER_STRUCT (Entry, UDP_TX_TOKEN, Link);
 500
 501     if ((ToCancel == NULL) || (ToCancel (Token, Context))) {
 502       UdpIo->Udp->Cancel (UdpIo->Udp, &Token->UdpToken);
 503     }
 504   }
 505 }
 506
 507 /**
 508   Free the UDP_IO_PORT and all its related resources.
 509
 510   The function will cancel all sent datagram and receive request.
 511
 512   @param[in]  UdpIo                 The UDP_IO_PORT to free.
 513
 514   @retval EFI_SUCCESS           The UDP_IO_PORT is freed.
 515
 516 **/
 517 EFI_STATUS
 518 EFIAPI
 519 UdpIoFreePort (
 520   IN  UDP_IO_PORT           *UdpIo
 521   )
 522 {
 523   UDP_RX_TOKEN  *RxToken;
 524
 525   //
 526   // Cancel all the sent datagram and receive requests. The
 527   // callbacks of transmit requests are executed to allow the
 528   // caller to release the resource. The callback of receive
 529   // request are NOT executed. This is because it is most
 530   // likely that the current user of the UDP IO port is closing
 531   // itself.
 532   //
 533   UdpIoCancelDgrams (UdpIo, EFI_ABORTED, NULL, NULL);
 534
 535   if ((RxToken = UdpIo->RecvRequest) != NULL) {
 536     UdpIo->Udp->Cancel (UdpIo->Udp, &RxToken->UdpToken);
 537   }
 538
 539   //
 540   // Close then destory the UDP child
 541   //
 542   gBS->CloseProtocol (
 543          UdpIo->UdpHandle,
 544          &gEfiUdp4ProtocolGuid,
 545          UdpIo->Image,
 546          UdpIo->Controller
 547          );
 548
 549   NetLibDestroyServiceChild (
 550     UdpIo->Controller,
 551     UdpIo->Image,
 552     &gEfiUdp4ServiceBindingProtocolGuid,
 553     UdpIo->UdpHandle
 554     );
 555
 556   if (!IsListEmpty(&UdpIo->Link)) {
 557     RemoveEntryList (&UdpIo->Link);
 558   }
 559
 560   gBS->FreePool (UdpIo);
 561   return EFI_SUCCESS;
 562 }
 563
 564
 565 /**
 566   Clean up the UDP_IO_PORT without freeing it. The function is called when
 567   user wants to re-use the UDP_IO_PORT later.
 568
 569   It will release all the transmitted datagrams and receive request. It will
 570   also configure NULL for the UDP instance.
 571
 572   @param[in]  UdpIo                 The UDP_IO_PORT to clean up.
 573
 574 **/
 575 VOID
 576 EFIAPI
 577 UdpIoCleanPort (
 578   IN  UDP_IO_PORT           *UdpIo
 579   )
 580 {
 581   UDP_RX_TOKEN              *RxToken;
 582
 583   //
 584   // Cancel all the sent datagram and receive requests.
 585   //
 586   UdpIoCancelDgrams (UdpIo, EFI_ABORTED, NULL, NULL);
 587
 588   if ((RxToken = UdpIo->RecvRequest) != NULL) {
 589     UdpIo->Udp->Cancel (UdpIo->Udp, &RxToken->UdpToken);
 590   }
 591
 592   UdpIo->Udp->Configure (UdpIo->Udp, NULL);
 593 }
 594
 595 /**
 596   Send a packet through the UDP_IO_PORT.
 597
 598   The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called
 599   when the packet is sent. The optional parameter EndPoint overrides the default
 600   address pair if specified.
 601
 602   @param[in]  UdpIo                 The UDP_IO_PORT to send the packet through.
 603   @param[in]  Packet                The packet to send.
 604   @param[in]  EndPoint              The local and remote access point. Override the
 605                                     default address pair set during configuration.
 606   @param[in]  Gateway               The gateway to use.
 607   @param[in]  CallBack              The function being called when packet is
 608                                     transmitted or failed.
 609   @param[in]  Context               The opaque parameter passed to CallBack.
 610
 611   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet.
 612   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for
 613                                 transmission.
 614
 615 **/
 616 EFI_STATUS
 617 EFIAPI
 618 UdpIoSendDatagram (
 619   IN  UDP_IO_PORT           *UdpIo,
 620   IN  NET_BUF               *Packet,
 621   IN  UDP_POINTS            *EndPoint, OPTIONAL
 622   IN  IP4_ADDR              Gateway,
 623   IN  UDP_IO_CALLBACK       CallBack,
 624   IN  VOID                  *Context
 625   )
 626 {
 627   UDP_TX_TOKEN              *Token;
 628   EFI_STATUS                Status;
 629
 630   Token = UdpIoWrapTx (UdpIo, Packet, EndPoint, Gateway, CallBack, Context);
 631
 632   if (Token == NULL) {
 633     return EFI_OUT_OF_RESOURCES;
 634   }
 635
 636   //
 637   // Insert the tx token into SendDatagram list before transmitting it. Remove
 638   // it from the list if the returned status is not EFI_SUCCESS.
 639   //
 640   InsertHeadList (&UdpIo->SentDatagram, &Token->Link);
 641   Status = UdpIo->Udp->Transmit (UdpIo->Udp, &Token->UdpToken);
 642   if (EFI_ERROR (Status)) {
 643     RemoveEntryList (&Token->Link);
 644     UdpIoFreeTxToken (Token);
 645     return Status;
 646   }
 647
 648   return EFI_SUCCESS;
 649 }
 650
 651
 652 /**
 653   The select function to cancel a single sent datagram.
 654
 655   @param[in]  Token                 The UDP_TX_TOKEN to test against
 656   @param[in]  Context               The NET_BUF of the sent datagram
 657
 658   @retval TRUE              The packet is to be cancelled.
 659   @retval FALSE             The packet is not to be cancelled.
 660 **/
 661 BOOLEAN
 662 UdpIoCancelSingleDgram (
 663   IN UDP_TX_TOKEN           *Token,
 664   IN VOID                   *Context
 665   )
 666 {
 667   NET_BUF                   *Packet;
 668
 669   Packet = (NET_BUF *) Context;
 670
 671   if (Token->Packet == Packet) {
 672     return TRUE;
 673   }
 674
 675   return FALSE;
 676 }
 677
 678 /**
 679   Cancel a single sent datagram.
 680
 681   @param[in]  UdpIo                 The UDP_IO_PORT to cancel the packet from
 682   @param[in]  Packet                The packet to cancel
 683
 684 **/
 685 VOID
 686 EFIAPI
 687 UdpIoCancelSentDatagram (
 688   IN  UDP_IO_PORT           *UdpIo,
 689   IN  NET_BUF               *Packet
 690   )
 691 {
 692   UdpIoCancelDgrams (UdpIo, EFI_ABORTED, UdpIoCancelSingleDgram, Packet);
 693 }
 694
 695 /**
 696   Issue a receive request to the UDP_IO_PORT.
 697
 698   This function is called when upper-layer needs packet from UDP for processing.
 699   Only one receive request is acceptable at a time so a common usage model is
 700   to invoke this function inside its Callback function when the former packet
 701   is processed.
 702
 703   @param[in]  UdpIo                 The UDP_IO_PORT to receive the packet from.
 704   @param[in]  CallBack              The call back function to execute when the packet
 705                                     is received.
 706   @param[in]  Context               The opaque context passed to Callback.
 707   @param[in] HeadLen                The length of the upper-layer's protocol header.
 708
 709   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 710                                 one receive request is supported at a time.
 711   @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 712   @retval EFI_SUCCESS           The receive request is issued successfully.
 713
 714 **/
 715 EFI_STATUS
 716 EFIAPI
 717 UdpIoRecvDatagram (
 718   IN  UDP_IO_PORT           *UdpIo,
 719   IN  UDP_IO_CALLBACK       CallBack,
 720   IN  VOID                  *Context,
 721   IN  UINT32                HeadLen
 722   )
 723 {
 724   UDP_RX_TOKEN              *Token;
 725   EFI_STATUS                Status;
 726
 727   if (UdpIo->RecvRequest != NULL) {
 728     return EFI_ALREADY_STARTED;
 729   }
 730
 731   Token = UdpIoCreateRxToken (UdpIo, CallBack, Context, HeadLen);
 732
 733   if (Token == NULL) {
 734     return EFI_OUT_OF_RESOURCES;
 735   }
 736
 737   UdpIo->RecvRequest = Token;
 738   Status = UdpIo->Udp->Receive (UdpIo->Udp, &Token->UdpToken);
 739
 740   if (EFI_ERROR (Status)) {
 741     UdpIo->RecvRequest = NULL;
 742     UdpIoFreeRxToken (Token);
 743   }
 744
 745   return Status;
 746 }