MdeModulePkg/Include/Library/IpIoLib.h

   1 /** @file
   2   This library is only intended to be used by UEFI network stack modules.
   3   It provides the combined IpIo layer on the EFI IP4 Protocol and EFI IP6 protocol.
   4
   5 Copyright (c) 2005 - 2010, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 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 _IP_IO_H_
  17 #define _IP_IO_H_
  18
  19 #include <Protocol/Ip4.h>
  20 #include <Protocol/Ip6.h>
  21
  22 #include <Library/NetLib.h>
  23
  24 //
  25 // type and code define for ICMP protocol error
  26 // from IP
  27 //
  28 #define ICMP_TYPE_UNREACH              3
  29 #define ICMP_TYPE_TIMXCEED             11
  30 #define ICMP_TYPE_PARAMPROB            12
  31 #define ICMP_TYPE_SOURCEQUENCH         4
  32
  33 #define ICMP_CODE_UNREACH_NET          0
  34 #define ICMP_CODE_UNREACH_HOST         1
  35 #define ICMP_CODE_UNREACH_PROTOCOL     2
  36 #define ICMP_CODE_UNREACH_PORT         3
  37 #define ICMP_CODE_UNREACH_NEEDFRAG     4
  38 #define ICMP_CODE_UNREACH_SRCFAIL      5
  39 #define ICMP_CODE_UNREACH_NET_UNKNOWN  6
  40 #define ICMP_CODE_UNREACH_HOST_UNKNOWN 7
  41 #define ICMP_CODE_UNREACH_ISOLATED     8
  42 #define ICMP_CODE_UNREACH_NET_PROHIB   9
  43 #define ICMP_CODE_UNREACH_HOST_PROHIB  10
  44 #define ICMP_CODE_UNREACH_TOSNET       11
  45 #define ICMP_CODE_UNREACH_TOSHOST      12
  46
  47 /**
  48   Get the IP header length from the struct EFI_IP4_HEADER. HeaderLength is
  49   Internet header length in 32-bit words, so HeaderLength<<2 is the real
  50   length of IP header.
  51
  52   @param[out] HdrPtr   A pointer to EFI_IP4_HEADER.
  53
  54   @return The IP header length.
  55 **/
  56 #define EFI_IP4_HEADER_LEN(HdrPtr) ((HdrPtr)->HeaderLength << 2)
  57
  58 /**
  59   To types of ICMP error which consist of ICMP header, IP header and original
  60   datagram's data, get length from sum of ICMP header length, IP header length
  61   and first 64 bits of datagram's data length.
  62
  63   @param[in] IpHdr   A pointer to EFI_IP4_HEADER.
  64
  65   @return The ICMP error length.
  66 **/
  67 #define ICMP_ERRLEN(IpHdr) \
  68   (sizeof(IP4_ICMP_HEAD) + EFI_IP4_HEADER_LEN(IpHdr) + 8)
  69
  70 /**
  71   Get the packet header from NET_BUF.
  72
  73   @param[out]  Buf    A pointer to NET_BUF.
  74   @param[in]   Type   Header type.
  75
  76   @return The pointer to packet header.
  77 **/
  78 #define NET_PROTO_HDR(Buf, Type)  ((Type *) ((Buf)->BlockOp[0].Head))
  79
  80
  81 extern EFI_IP4_CONFIG_DATA  mIp4IoDefaultIpConfigData;
  82 extern EFI_IP6_CONFIG_DATA  mIp6IoDefaultIpConfigData;
  83
  84
  85 ///
  86 /// This error will be delivered to the
  87 /// listening transportation layer protocol
  88 /// that consumes IpIO.
  89 ///
  90
  91 #define  ICMP_ERR_UNREACH_NET           0
  92 #define  ICMP_ERR_UNREACH_HOST          1
  93 #define  ICMP_ERR_UNREACH_PROTOCOL      2
  94 #define  ICMP_ERR_UNREACH_PORT          3
  95 #define  ICMP_ERR_MSGSIZE               4
  96 #define  ICMP_ERR_UNREACH_SRCFAIL       5
  97 #define  ICMP_ERR_TIMXCEED_INTRANS      6
  98 #define  ICMP_ERR_TIMXCEED_REASS        7
  99 #define  ICMP_ERR_QUENCH                8
 100 #define  ICMP_ERR_PARAMPROB             9
 101
 102 #define  ICMP6_ERR_UNREACH_NET          0
 103 #define  ICMP6_ERR_UNREACH_HOST         1
 104 #define  ICMP6_ERR_UNREACH_PROTOCOL     2
 105 #define  ICMP6_ERR_UNREACH_PORT         3
 106 #define  ICMP6_ERR_PACKAGE_TOOBIG       4
 107 #define  ICMP6_ERR_TIMXCEED_HOPLIMIT    5
 108 #define  ICMP6_ERR_TIMXCEED_REASS       6
 109 #define  ICMP6_ERR_PARAMPROB_HEADER     7
 110 #define  ICMP6_ERR_PARAMPROB_NEXHEADER  8
 111 #define  ICMP6_ERR_PARAMPROB_IPV6OPTION 9
 112
 113 ///
 114 /// The helper struct for IpIoGetIcmpErrStatus(). It is for internal use only.
 115 ///
 116 typedef struct {
 117   BOOLEAN                   IsHard;
 118   BOOLEAN                   Notify;
 119 } ICMP_ERROR_INFO;
 120
 121 typedef union {
 122   EFI_IP4_COMPLETION_TOKEN  Ip4Token;
 123   EFI_IP6_COMPLETION_TOKEN  Ip6Token;
 124 } IP_IO_IP_COMPLETION_TOKEN;
 125
 126 typedef union {
 127   EFI_IP4_TRANSMIT_DATA     Ip4TxData;
 128   EFI_IP6_TRANSMIT_DATA     Ip6TxData;
 129 } IP_IO_IP_TX_DATA;
 130
 131 typedef union {
 132   EFI_IP4_RECEIVE_DATA      Ip4RxData;
 133   EFI_IP6_RECEIVE_DATA      Ip6RxData;
 134 } IP_IO_IP_RX_DATA;
 135
 136 typedef union {
 137   EFI_IP4_OVERRIDE_DATA     Ip4OverrideData;
 138   EFI_IP6_OVERRIDE_DATA     Ip6OverrideData;
 139 } IP_IO_OVERRIDE;
 140
 141 typedef union {
 142   EFI_IP4_CONFIG_DATA       Ip4CfgData;
 143   EFI_IP6_CONFIG_DATA       Ip6CfgData;
 144 } IP_IO_IP_CONFIG_DATA;
 145
 146 typedef union {
 147   EFI_IP4_HEADER            *Ip4Hdr;
 148   EFI_IP6_HEADER            *Ip6Hdr;
 149 } IP_IO_IP_HEADER;
 150
 151 typedef union {
 152   IP4_ADDR                  SubnetMask;
 153   UINT8                     PrefixLength;
 154 } IP_IO_IP_MASK;
 155
 156 typedef union {
 157   EFI_IP4_PROTOCOL  *Ip4;
 158   EFI_IP6_PROTOCOL  *Ip6;
 159 } IP_IO_IP_PROTOCOL;
 160
 161 ///
 162 /// The IP session for an IP receive packet.
 163 ///
 164 typedef struct _EFI_NET_SESSION_DATA {
 165   EFI_IP_ADDRESS        Source;     ///< Source IP of the received packet.
 166   EFI_IP_ADDRESS        Dest;       ///< Destination IP of the received packet.
 167   IP_IO_IP_HEADER       IpHdr;      ///< IP header of the received packet.
 168   UINT32                IpHdrLen;   ///< IP header length of the received packet.
 169                                     ///< For IPv6, it includes the IP6 header
 170                                     ///< length and extension header length. For
 171                                     ///< IPv4, it includes the IP4 header length
 172                                     ///< and options length.
 173   UINT8                 IpVersion;  ///< The IP version of the received packet.
 174 } EFI_NET_SESSION_DATA;
 175
 176 /**
 177   The prototype is called back when an IP packet is received.
 178
 179   @param[in] Status        The result of the receive request.
 180   @param[in] IcmpErr       Valid when Status is EFI_ICMP_ERROR.
 181   @param[in] NetSession    The IP session for the received packet.
 182   @param[in] Pkt           The packet received.
 183   @param[in] Context       The data provided by the user for the received packet when
 184                            the callback is registered in IP_IO_OPEN_DATA::RcvdContext.
 185
 186 **/
 187 typedef
 188 VOID
 189 (EFIAPI *PKT_RCVD_NOTIFY) (
 190   IN EFI_STATUS           Status,
 191   IN UINT8                IcmpErr,
 192   IN EFI_NET_SESSION_DATA *NetSession,
 193   IN NET_BUF              *Pkt,
 194   IN VOID                 *Context
 195   );
 196
 197 /**
 198   The prototype is called back when an IP packet is sent.
 199
 200   @param[in] Status        Result of the IP packet being sent.
 201   @param[in] Context       The data provided by user for the received packet when
 202                            the callback is registered in IP_IO_OPEN_DATA::SndContext.
 203   @param[in] Sender        A Union type to specify a pointer of EFI_IP4_PROTOCOL
 204                            or EFI_IP6_PROTOCOL.
 205   @param[in] NotifyData    The Context data specified when calling IpIoSend()
 206
 207 **/
 208 typedef
 209 VOID
 210 (EFIAPI *PKT_SENT_NOTIFY) (
 211   IN EFI_STATUS        Status,
 212   IN VOID              *Context,
 213   IN IP_IO_IP_PROTOCOL Sender,
 214   IN VOID              *NotifyData
 215   );
 216
 217 ///
 218 /// This data structure wraps Ip4/Ip6 instances. The IpIo Library uses it for all
 219 /// Ip4/Ip6 operations.
 220 ///
 221 typedef struct _IP_IO {
 222   ///
 223   /// The node used to link this IpIo to the active IpIo list.
 224   ///
 225   LIST_ENTRY                    Entry;
 226
 227   ///
 228   /// The list used to maintain the IP instance for different sending purpose.
 229   ///
 230   LIST_ENTRY                    IpList;
 231
 232   EFI_HANDLE                    Controller;
 233   EFI_HANDLE                    Image;
 234   EFI_HANDLE                    ChildHandle;
 235   //
 236   // The IP instance consumed by this IP_IO
 237   //
 238   IP_IO_IP_PROTOCOL             Ip;
 239   BOOLEAN                       IsConfigured;
 240
 241   ///
 242   /// Some ip configuration data can be changed.
 243   ///
 244   UINT8                         Protocol;
 245
 246   ///
 247   /// Token and event used to get data from IP.
 248   ///
 249   IP_IO_IP_COMPLETION_TOKEN     RcvToken;
 250
 251   ///
 252   /// List entry used to link the token passed to IP_IO.
 253   ///
 254   LIST_ENTRY                    PendingSndList;
 255
 256   //
 257   // User interface used to get notify from IP_IO
 258   //
 259   VOID                          *RcvdContext;    ///< See IP_IO_OPEN_DATA::RcvdContext.
 260   VOID                          *SndContext;     ///< See IP_IO_OPEN_DATA::SndContext.
 261   PKT_RCVD_NOTIFY               PktRcvdNotify;   ///< See IP_IO_OPEN_DATA::PktRcvdNotify.
 262   PKT_SENT_NOTIFY               PktSentNotify;   ///< See IP_IO_OPEN_DATA::PktSentNotify.
 263   UINT8                         IpVersion;
 264 } IP_IO;
 265
 266 ///
 267 /// The struct is for the user to pass IP configuration and callbacks to IP_IO.
 268 /// It is used by IpIoOpen().
 269 ///
 270 typedef struct _IP_IO_OPEN_DATA {
 271   IP_IO_IP_CONFIG_DATA IpConfigData;    ///< Configuration of the IP instance.
 272   VOID                 *RcvdContext;    ///< Context data used by receive callback.
 273   VOID                 *SndContext;     ///< Context data used by send callback.
 274   PKT_RCVD_NOTIFY      PktRcvdNotify;   ///< Receive callback.
 275   PKT_SENT_NOTIFY      PktSentNotify;   ///< Send callback.
 276 } IP_IO_OPEN_DATA;
 277
 278 ///
 279 /// Internal struct book-keeping send request of IP_IO.
 280 ///
 281 /// An IP_IO_SEND_ENTRY will be created each time a send request is issued to
 282 /// IP_IO via IpIoSend().
 283 ///
 284 typedef struct _IP_IO_SEND_ENTRY {
 285   LIST_ENTRY                Entry;
 286   IP_IO                     *IpIo;
 287   VOID                      *Context;
 288   VOID                      *NotifyData;
 289   IP_IO_IP_PROTOCOL         Ip;
 290   NET_BUF                   *Pkt;
 291   IP_IO_IP_COMPLETION_TOKEN SndToken;
 292 } IP_IO_SEND_ENTRY;
 293
 294 ///
 295 /// The IP_IO_IP_INFO is used in IpIoSend() to override the default IP instance
 296 /// in IP_IO.
 297 ///
 298 typedef struct _IP_IO_IP_INFO {
 299   EFI_IP_ADDRESS            Addr;
 300   IP_IO_IP_MASK             PreMask;
 301   LIST_ENTRY                Entry;
 302   EFI_HANDLE                ChildHandle;
 303   IP_IO_IP_PROTOCOL         Ip;
 304   IP_IO_IP_COMPLETION_TOKEN DummyRcvToken;
 305   INTN                      RefCnt;
 306   UINT8                     IpVersion;
 307 } IP_IO_IP_INFO;
 308
 309 /**
 310   Create a new IP_IO instance.
 311
 312   This function uses IP4/IP6 service binding protocol in Controller to create
 313   an IP4/IP6 child (aka IP4/IP6 instance).
 314
 315   @param[in]  Image             The image handle of the driver or application that
 316                                 consumes IP_IO.
 317   @param[in]  Controller        The controller handle that has IP4 or IP6 service
 318                                 binding protocol installed.
 319   @param[in]  IpVersion         The version of the IP protocol to use, either
 320                                 IPv4 or IPv6.
 321
 322   @return The pointer to a newly created IP_IO instance, or NULL if failed.
 323
 324 **/
 325 IP_IO *
 326 EFIAPI
 327 IpIoCreate (
 328   IN EFI_HANDLE Image,
 329   IN EFI_HANDLE Controller,
 330   IN UINT8      IpVersion
 331   );
 332
 333 /**
 334   Destroy an IP_IO instance.
 335
 336   This function is paired with IpIoCreate(). The IP_IO will be closed first.
 337   Resource will be freed afterwards. See IpIoClose().
 338
 339   @param[in, out]  IpIo         The pointer to the IP_IO instance that needs to be
 340                                 destroyed.
 341
 342   @retval          EFI_SUCCESS  The IP_IO instance was destroyed successfully.
 343   @retval          Others       An error condition occurred.
 344
 345 **/
 346 EFI_STATUS
 347 EFIAPI
 348 IpIoDestroy (
 349   IN OUT IP_IO *IpIo
 350   );
 351
 352 /**
 353   Stop an IP_IO instance.
 354
 355   This function is paired with IpIoOpen(). The IP_IO will be unconfigured, and all
 356   pending send/receive tokens will be canceled.
 357
 358   @param[in, out]  IpIo            The pointer to the IP_IO instance that needs to stop.
 359
 360   @retval          EFI_SUCCESS     The IP_IO instance stopped successfully.
 361   @retval          Others          Anrror condition occurred.
 362
 363 **/
 364 EFI_STATUS
 365 EFIAPI
 366 IpIoStop (
 367   IN OUT IP_IO *IpIo
 368   );
 369
 370 /**
 371   Open an IP_IO instance for use.
 372
 373   This function is called after IpIoCreate(). It is used for configuring the IP
 374   instance and register the callbacks and their context data for sending and
 375   receiving IP packets.
 376
 377   @param[in, out]  IpIo               The pointer to an IP_IO instance that needs
 378                                       to open.
 379   @param[in]       OpenData           The configuration data and callbacks for
 380                                       the IP_IO instance.
 381
 382   @retval          EFI_SUCCESS        The IP_IO instance opened with OpenData
 383                                       successfully.
 384   @retval          EFI_ACCESS_DENIED  The IP_IO instance is configured; avoid
 385                                       reopening it.
 386   @retval          Others             An error condition occurred.
 387
 388 **/
 389 EFI_STATUS
 390 EFIAPI
 391 IpIoOpen (
 392   IN OUT IP_IO           *IpIo,
 393   IN     IP_IO_OPEN_DATA *OpenData
 394   );
 395
 396 /**
 397   Send out an IP packet.
 398
 399   This function is called after IpIoOpen(). The data to be sent are wrapped in
 400   Pkt. The IP instance wrapped in IpIo is used for sending by default, but can be
 401   overriden by Sender. Other sending configurations, such as source address and gateway
 402   address, are specified in OverrideData.
 403
 404   @param[in, out]  IpIo                  The pointer to an IP_IO instance used for sending IP
 405                                          packet.
 406   @param[in, out]  Pkt                   The pointer to the IP packet to be sent.
 407   @param[in]       Sender                Optional. The IP protocol instance used for sending.
 408   @param[in]       Context               The optional context data.
 409   @param[in]       NotifyData            The optional notify data.
 410   @param[in]       Dest                  The destination IP address to send this packet to.
 411   @param[in]       OverrideData          The data to override some configuration of the IP
 412                                          instance used for sending.
 413
 414   @retval          EFI_SUCCESS           The operation completed successfully.
 415   @retval          EFI_NOT_STARTED       The IpIo is not configured.
 416   @retval          EFI_OUT_OF_RESOURCES  Failed due to resource limitations.
 417
 418 **/
 419 EFI_STATUS
 420 EFIAPI
 421 IpIoSend (
 422   IN OUT IP_IO          *IpIo,
 423   IN OUT NET_BUF        *Pkt,
 424   IN     IP_IO_IP_INFO  *Sender        OPTIONAL,
 425   IN     VOID           *Context       OPTIONAL,
 426   IN     VOID           *NotifyData    OPTIONAL,
 427   IN     EFI_IP_ADDRESS *Dest,
 428   IN     IP_IO_OVERRIDE *OverrideData  OPTIONAL
 429   );
 430
 431 /**
 432   Cancel the IP transmit token that wraps this Packet.
 433
 434   @param[in]  IpIo                  The pointer to the IP_IO instance.
 435   @param[in]  Packet                The pointer to the packet of NET_BUF to cancel.
 436
 437 **/
 438 VOID
 439 EFIAPI
 440 IpIoCancelTxToken (
 441   IN IP_IO  *IpIo,
 442   IN VOID   *Packet
 443   );
 444
 445 /**
 446   Add a new IP instance for sending data.
 447
 448   The function is used to add the IP_IO to the IP_IO sending list. The caller
 449   can later use IpIoFindSender() to get the IP_IO and call IpIoSend() to send
 450   data.
 451
 452   @param[in, out]  IpIo               The pointer to an IP_IO instance to add a new IP
 453                                       instance for sending purposes.
 454
 455   @return The pointer to the created IP_IO_IP_INFO structure; NULL if failed.
 456
 457 **/
 458 IP_IO_IP_INFO *
 459 EFIAPI
 460 IpIoAddIp (
 461   IN OUT IP_IO  *IpIo
 462   );
 463
 464 /**
 465   Configure the IP instance of this IpInfo and start the receiving if IpConfigData
 466   is not NULL.
 467
 468   @param[in, out]  IpInfo          The pointer to the IP_IO_IP_INFO instance.
 469   @param[in, out]  IpConfigData    The IP4 or IP6 configure data used to configure
 470                                    the IP instance. If NULL, the IP instance is reset.
 471                                    If UseDefaultAddress is set to TRUE, and the configure
 472                                    operation succeeds, the default address information
 473                                    is written back in this IpConfigData.
 474
 475   @retval          EFI_SUCCESS     The IP instance of this IpInfo was configured successfully,
 476                                    or there is no need to reconfigure it.
 477   @retval          Others          The configuration failed.
 478
 479 **/
 480 EFI_STATUS
 481 EFIAPI
 482 IpIoConfigIp (
 483   IN OUT IP_IO_IP_INFO        *IpInfo,
 484   IN OUT VOID                 *IpConfigData OPTIONAL
 485   );
 486
 487 /**
 488   Destroy an IP instance maintained in IpIo->IpList for
 489   sending purpose.
 490
 491   This function pairs with IpIoAddIp(). The IpInfo is previously created by
 492   IpIoAddIp(). The IP_IO_IP_INFO::RefCnt is decremented and the IP instance
 493   will be dstroyed if the RefCnt is zero.
 494
 495   @param[in]  IpIo                  The pointer to the IP_IO instance.
 496   @param[in]  IpInfo                The pointer to the IpInfo to be removed.
 497
 498 **/
 499 VOID
 500 EFIAPI
 501 IpIoRemoveIp (
 502   IN IP_IO            *IpIo,
 503   IN IP_IO_IP_INFO    *IpInfo
 504   );
 505
 506 /**
 507   Find the first IP protocol maintained in IpIo whose local
 508   address is the same as Src.
 509
 510   This function is called when the caller needs the IpIo to send data to the
 511   specified Src. The IpIo was added previously by IpIoAddIp().
 512
 513   @param[in, out]  IpIo              The pointer to the pointer of the IP_IO instance.
 514   @param[in]       IpVersion         The version of the IP protocol to use, either
 515                                      IPv4 or IPv6.
 516   @param[in]       Src               The local IP address.
 517
 518   @return The pointer to the IP protocol can be used for sending purpose and its local
 519           address is the same with Src.
 520
 521 **/
 522 IP_IO_IP_INFO *
 523 EFIAPI
 524 IpIoFindSender (
 525   IN OUT IP_IO           **IpIo,
 526   IN     UINT8           IpVersion,
 527   IN     EFI_IP_ADDRESS  *Src
 528   );
 529
 530 /**
 531   Get the ICMP error map information.
 532
 533   The ErrorStatus will be returned. The IsHard and Notify are optional. If they
 534   are not NULL, this routine will fill them.
 535
 536   @param[in]   IcmpError             IcmpError Type.
 537   @param[in]   IpVersion             The version of the IP protocol to use,
 538                                      either IPv4 or IPv6.
 539   @param[out]  IsHard                If TRUE, indicates that it is a hard error.
 540   @param[out]  Notify                If TRUE, SockError needs to be notified.
 541
 542   @return The ICMP Error Status, such as EFI_NETWORK_UNREACHABLE.
 543
 544 **/
 545 EFI_STATUS
 546 EFIAPI
 547 IpIoGetIcmpErrStatus (
 548   IN  UINT8       IcmpError,
 549   IN  UINT8       IpVersion,
 550   OUT BOOLEAN     *IsHard  OPTIONAL,
 551   OUT BOOLEAN     *Notify  OPTIONAL
 552   );
 553
 554 /**
 555   Refresh the remote peer's Neighbor Cache entries.
 556
 557   This function is called when the caller needs the IpIo to refresh the existing
 558   IPv6 neighbor cache entries since the neighbor is considered reachable by the
 559   node has recently received a confirmation that packets sent recently to the
 560   neighbor were received by its IP layer.
 561
 562   @param[in]   IpIo                  The pointer to an IP_IO instance
 563   @param[in]   Neighbor              The IP address of the neighbor
 564   @param[in]   Timeout               The time in 100-ns units that this entry will
 565                                      remain in the neighbor cache. A value of
 566                                      zero means that the entry is permanent.
 567                                      A value of non-zero means that the entry is
 568                                      dynamic and will be deleted after Timeout.
 569
 570   @retval      EFI_SUCCESS           The operation completed successfully.
 571   @retval      EFI_NOT_STARTED       The IpIo is not configured.
 572   @retval      EFI_INVALID_PARAMETER The Neighbor Address is invalid.
 573   @retval      EFI_NOT_FOUND         The neighbor cache entry is not in the
 574                                      neighbor table.
 575   @retval      EFI_OUT_OF_RESOURCES  Failed due to resource limitations.
 576
 577 **/
 578 EFI_STATUS
 579 IpIoRefreshNeighbor (
 580   IN IP_IO           *IpIo,
 581   IN EFI_IP_ADDRESS  *Neighbor,
 582   IN UINT32          Timeout
 583   );
 584
 585 #endif
 586