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