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