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