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
  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 ///
 157 /// The IP session for an IP receive packet.
 158 ///
 159 typedef struct _EFI_NET_SESSION_DATA {
 160   EFI_IP_ADDRESS        Source;     ///< Source IP of the received packet
 161   EFI_IP_ADDRESS        Dest;       ///< Destination IP of the received packet
 162   IP_IO_IP_HEADER       IpHdr;      ///< IP header of the received packet
 163   UINT8                 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 UINT8                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   UINT8                         IpVersion;
 253 } IP_IO;
 254
 255 ///
 256 /// The struct is for the user to pass IP configuration and callbacks to IP_IO.
 257 /// It is used by IpIoOpen().
 258 ///
 259 typedef struct _IP_IO_OPEN_DATA {
 260   IP_IO_IP_CONFIG_DATA IpConfigData;    ///< Configuration of the IP instance
 261   VOID                 *RcvdContext;    ///< Context data used by receive callback
 262   VOID                 *SndContext;     ///< Context data used by send callback
 263   PKT_RCVD_NOTIFY      PktRcvdNotify;   ///< Receive callback
 264   PKT_SENT_NOTIFY      PktSentNotify;   ///< Send callback
 265 } IP_IO_OPEN_DATA;
 266
 267 ///
 268 /// Internal struct book-keeping send request of IP_IO.
 269 ///
 270 /// An IP_IO_SEND_ENTRY will be created each time a send request is issued to
 271 /// IP_IO via IpIoSend().
 272 ///
 273 typedef struct _IP_IO_SEND_ENTRY {
 274   LIST_ENTRY                Entry;
 275   IP_IO                     *IpIo;
 276   VOID                      *Context;
 277   VOID                      *NotifyData;
 278   VOID                      *Ip;
 279   NET_BUF                   *Pkt;
 280   IP_IO_IP_COMPLETION_TOKEN SndToken;
 281 } IP_IO_SEND_ENTRY;
 282
 283 ///
 284 /// The IP_IO_IP_INFO is used in IpIoSend() to override the default IP instance
 285 /// in IP_IO.
 286 ///
 287 typedef struct _IP_IO_IP_INFO {
 288   EFI_IP_ADDRESS            Addr;
 289   IP_IO_IP_MASK             PreMask;
 290   LIST_ENTRY                Entry;
 291   EFI_HANDLE                ChildHandle;
 292   VOID                      *Ip;
 293   IP_IO_IP_COMPLETION_TOKEN DummyRcvToken;
 294   INTN                      RefCnt;
 295   UINT8                     IpVersion;
 296 } IP_IO_IP_INFO;
 297
 298 /**
 299   Create a new IP_IO instance.
 300
 301   This function uses IP4/IP6 service binding protocol in Controller to create
 302   an IP4/IP6 child (aka IP4/IP6 instance).
 303
 304   @param[in]  Image             The image handle of the driver or application that
 305                                 consumes IP_IO.
 306   @param[in]  Controller        The controller handle that has IP4 or IP6 service
 307                                 binding protocol installed.
 308   @param[in]  IpVersion         The version of the IP protocol to use, either
 309                                 IPv4 or IPv6.
 310
 311   @return Pointer to a newly created IP_IO instance, or NULL if failed.
 312
 313 **/
 314 IP_IO *
 315 EFIAPI
 316 IpIoCreate (
 317   IN EFI_HANDLE Image,
 318   IN EFI_HANDLE Controller,
 319   IN UINT8      IpVersion
 320   );
 321
 322 /**
 323   Destroy an IP_IO instance.
 324
 325   This function is paired with IpIoCreate(). The IP_IO will be closed first.
 326   Resource will be freed afterwards. See IpIoClose().
 327
 328   @param[in, out]  IpIo         Pointer to the IP_IO instance that needs to be
 329                                 destroyed.
 330
 331   @retval          EFI_SUCCESS  The IP_IO instance destroyed successfully.
 332   @retval          Others       Error condition occurred.
 333
 334 **/
 335 EFI_STATUS
 336 EFIAPI
 337 IpIoDestroy (
 338   IN OUT IP_IO *IpIo
 339   );
 340
 341 /**
 342   Stop an IP_IO instance.
 343
 344   This function is paired with IpIoOpen(). The IP_IO will be unconfigured, and all
 345   pending send/receive tokens will be canceled.
 346
 347   @param[in, out]  IpIo            Pointer to the IP_IO instance that needs to stop.
 348
 349   @retval          EFI_SUCCESS     The IP_IO instance stopped successfully.
 350   @retval          Others          Error condition occurred.
 351
 352 **/
 353 EFI_STATUS
 354 EFIAPI
 355 IpIoStop (
 356   IN OUT IP_IO *IpIo
 357   );
 358
 359 /**
 360   Open an IP_IO instance for use.
 361
 362   This function is called after IpIoCreate(). It is used for configuring the IP
 363   instance and register the callbacks and their context data for sending and
 364   receiving IP packets.
 365
 366   @param[in, out]  IpIo               Pointer to an IP_IO instance that needs
 367                                       to open.
 368   @param[in]       OpenData           The configuration data and callbacks for
 369                                       the IP_IO instance.
 370
 371   @retval          EFI_SUCCESS        The IP_IO instance opened with OpenData
 372                                       successfully.
 373   @retval          EFI_ACCESS_DENIED  The IP_IO instance is configured, avoid to
 374                                       reopen it.
 375   @retval          Others             Error condition occurred.
 376
 377 **/
 378 EFI_STATUS
 379 EFIAPI
 380 IpIoOpen (
 381   IN OUT IP_IO           *IpIo,
 382   IN     IP_IO_OPEN_DATA *OpenData
 383   );
 384
 385 /**
 386   Send out an IP packet.
 387
 388   This function is called after IpIoOpen(). The data to be sent are wrapped in
 389   Pkt. The IP instance wrapped in IpIo is used for sending by default, but can be
 390   overriden by Sender. Other sending configurations, such as source address and gateway
 391   address, are specified in OverrideData.
 392
 393   @param[in, out]  IpIo                  Pointer to an IP_IO instance used for sending IP
 394                                          packet.
 395   @param[in, out]  Pkt                   Pointer to the IP packet to be sent.
 396   @param[in]       Sender                Optional. The IP protocol instance used for sending.
 397   @param[in]       Context               Optional context data.
 398   @param[in]       NotifyData            Optional notify data.
 399   @param[in]       Dest                  The destination IP address to send this packet to.
 400   @param[in]       OverrideData          The data to override some configuration of the IP
 401                                          instance used for sending.
 402
 403   @retval          EFI_SUCCESS           The operation is completed successfully.
 404   @retval          EFI_NOT_STARTED       The IpIo is not configured.
 405   @retval          EFI_OUT_OF_RESOURCES  Failed due to resource limit.
 406
 407 **/
 408 EFI_STATUS
 409 EFIAPI
 410 IpIoSend (
 411   IN OUT IP_IO          *IpIo,
 412   IN OUT NET_BUF        *Pkt,
 413   IN     IP_IO_IP_INFO  *Sender        OPTIONAL,
 414   IN     VOID           *Context       OPTIONAL,
 415   IN     VOID           *NotifyData    OPTIONAL,
 416   IN     EFI_IP_ADDRESS *Dest,
 417   IN     IP_IO_OVERRIDE *OverrideData  OPTIONAL
 418   );
 419
 420 /**
 421   Cancel the IP transmit token which wraps this Packet.
 422
 423   @param[in]  IpIo                  Pointer to the IP_IO instance.
 424   @param[in]  Packet                Pointer to the packet of NET_BUF to cancel.
 425
 426 **/
 427 VOID
 428 EFIAPI
 429 IpIoCancelTxToken (
 430   IN IP_IO  *IpIo,
 431   IN VOID   *Packet
 432   );
 433
 434 /**
 435   Add a new IP instance for sending data.
 436
 437   The function is used to add the IP_IO to the IP_IO sending list. The caller
 438   can later use IpIoFindSender() to get the IP_IO and call IpIoSend() to send
 439   data.
 440
 441   @param[in, out]  IpIo               Pointer to an IP_IO instance to add a new IP
 442                                       instance for sending purposes.
 443
 444   @return Pointer to the created IP_IO_IP_INFO structure, NULL if failed.
 445
 446 **/
 447 IP_IO_IP_INFO *
 448 EFIAPI
 449 IpIoAddIp (
 450   IN OUT IP_IO  *IpIo
 451   );
 452
 453 /**
 454   Configure the IP instance of this IpInfo and start the receiving if IpConfigData
 455   is not NULL.
 456
 457   @param[in, out]  IpInfo          Pointer to the IP_IO_IP_INFO instance.
 458   @param[in, out]  IpConfigData    The IP4 or IP6 configure data used to configure
 459                                    the IP instance. If NULL, the IP instance is reset.
 460                                    If UseDefaultAddress is set to TRUE, and the configure
 461                                    operation succeeds, the default address information
 462                                    is written back in this IpConfigData.
 463
 464   @retval          EFI_SUCCESS     The IP instance of this IpInfo is configured successfully,
 465                                    or there is no need to reconfigure it.
 466   @retval          Others          Configuration failed.
 467
 468 **/
 469 EFI_STATUS
 470 EFIAPI
 471 IpIoConfigIp (
 472   IN OUT IP_IO_IP_INFO        *IpInfo,
 473   IN OUT VOID                 *IpConfigData OPTIONAL
 474   );
 475
 476 /**
 477   Destroy an IP instance maintained in IpIo->IpList for
 478   sending purpose.
 479
 480   This function pairs with IpIoAddIp(). The IpInfo is previously created by
 481   IpIoAddIp(). The IP_IO_IP_INFO::RefCnt is decremented and the IP instance
 482   will be dstroyed if the RefCnt is zero.
 483
 484   @param[in]  IpIo                  Pointer to the IP_IO instance.
 485   @param[in]  IpInfo                Pointer to the IpInfo to be removed.
 486
 487 **/
 488 VOID
 489 EFIAPI
 490 IpIoRemoveIp (
 491   IN IP_IO            *IpIo,
 492   IN IP_IO_IP_INFO    *IpInfo
 493   );
 494
 495 /**
 496   Find the first IP protocol maintained in IpIo whose local
 497   address is the same as Src.
 498
 499   This function is called when the caller needs the IpIo to send data to the
 500   specified Src. The IpIo was added previously by IpIoAddIp().
 501
 502   @param[in, out]  IpIo              Pointer to the pointer of the IP_IO instance.
 503   @param[in]       IpVersion         The version of the IP protocol to use, either
 504                                      IPv4 or IPv6.
 505   @param[in]       Src               The local IP address.
 506
 507   @return Pointer to the IP protocol can be used for sending purpose and its local
 508           address is the same with Src.
 509
 510 **/
 511 IP_IO_IP_INFO *
 512 EFIAPI
 513 IpIoFindSender (
 514   IN OUT IP_IO           **IpIo,
 515   IN     UINT8           IpVersion,
 516   IN     EFI_IP_ADDRESS  *Src
 517   );
 518
 519 /**
 520   Get the ICMP error map information.
 521
 522   The ErrorStatus will be returned. The IsHard and Notify are optional. If they
 523   are not NULL, this routine will fill them.
 524
 525   @param[in]   IcmpError             IcmpError Type.
 526   @param[in]   IpVersion             The version of the IP protocol to use,
 527                                      either IPv4 or IPv6.
 528
 529   @param[out]  IsHard                Whether it is a hard error.
 530   @param[out]  Notify                Whether it need to notify SockError.
 531
 532   @return ICMP Error Status, such as EFI_NETWORK_UNREACHABLE.
 533
 534 **/
 535 EFI_STATUS
 536 EFIAPI
 537 IpIoGetIcmpErrStatus (
 538   IN  UINT8       IcmpError,
 539   IN  UINT8       IpVersion,
 540   OUT BOOLEAN     *IsHard  OPTIONAL,
 541   OUT BOOLEAN     *Notify  OPTIONAL
 542   );
 543
 544 /**
 545   Refresh the remote peer's Neighbor Cache entries.
 546
 547   This function is called when the caller needs the IpIo to refresh the existing
 548   IPv6 neighbor cache entries since the neighbor is considered reachable by the
 549   node has recently received a confirmation that packets sent recently to the
 550   neighbor were received by its IP layer.
 551
 552   @param[in]   IpIo                  Pointer to an IP_IO instance
 553   @param[in]   Neighbor              The IP address of the neighbor
 554   @param[in]   Timeout               Time in 100-ns units that this entry will
 555                                      remain in the neighbor cache. A value of
 556                                      zero means that the entry is permanent.
 557                                      A value of non-zero means that the entry is
 558                                      dynamic and will be deleted after Timeout.
 559
 560   @retval      EFI_SUCCESS           The operation is completed successfully.
 561   @retval      EFI_NOT_STARTED       The IpIo is not configured.
 562   @retval      EFI_INVALID_PARAMETER Neighbor Address is invalid.
 563   @retval      EFI_NOT_FOUND         The neighbor cache entry is not in the
 564                                      neighbor table.
 565   @retval      EFI_OUT_OF_RESOURCES  Failed due to resource limit.
 566
 567 **/
 568 EFI_STATUS
 569 IpIoRefreshNeighbor (
 570   IN IP_IO           *IpIo,
 571   IN EFI_IP_ADDRESS  *Neighbor,
 572   IN UINT32          Timeout
 573   );
 574
 575 #endif
 576