MdeModulePkg/Include/Library/IpIoLib.h

   1 /** @file
   2   This library provides IpIo layer upon EFI IP4 Protocol.
   3
   4 Copyright (c) 2005 - 2008, Intel Corporation.<BR>
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _IP_IO_H_
  16 #define _IP_IO_H_
  17
  18 #include <Protocol/Ip4.h>
  19
  20 #include <Library/NetLib.h>
  21
  22 //
  23 // type and code define for ICMP protocol error got
  24 // from IP
  25 //
  26 #define ICMP_TYPE_UNREACH              3
  27 #define ICMP_TYPE_TIMXCEED             11
  28 #define ICMP_TYPE_PARAMPROB            12
  29 #define ICMP_TYPE_SOURCEQUENCH         4
  30
  31 #define ICMP_CODE_UNREACH_NET          0
  32 #define ICMP_CODE_UNREACH_HOST         1
  33 #define ICMP_CODE_UNREACH_PROTOCOL     2
  34 #define ICMP_CODE_UNREACH_PORT         3
  35 #define ICMP_CODE_UNREACH_NEEDFRAG     4
  36 #define ICMP_CODE_UNREACH_SRCFAIL      5
  37 #define ICMP_CODE_UNREACH_NET_UNKNOWN  6
  38 #define ICMP_CODE_UNREACH_HOST_UNKNOWN 7
  39 #define ICMP_CODE_UNREACH_ISOLATED     8
  40 #define ICMP_CODE_UNREACH_NET_PROHIB   9
  41 #define ICMP_CODE_UNREACH_HOST_PROHIB  10
  42 #define ICMP_CODE_UNREACH_TOSNET       11
  43 #define ICMP_CODE_UNREACH_TOSHOST      12
  44
  45 /**
  46   Get the IP header length from EFI_IP4_HEADER struct. HeaderLength is
  47   Internet header length in 32-bit words, so HeaderLength<<2 is the real
  48   length of IP header.
  49
  50   @param[out] HdrPtr   A pointer to EFI_IP4_HEADER
  51
  52   @return The IP header length
  53 **/
  54 #define EFI_IP4_HEADER_LEN(HdrPtr) ((HdrPtr)->HeaderLength << 2)
  55
  56 /**
  57   To types of ICMP error which consist of ICMP header, IP header and original
  58   datagram's data, get length from sum of ICMP header length, IP header length
  59   and first 64 bits of datagram's data length.
  60
  61   @param[in] IpHdr   A pointer to EFI_IP4_HEADER
  62
  63   @return The ICMP error length
  64 **/
  65 #define ICMP_ERRLEN(IpHdr) \
  66   (sizeof(IP4_ICMP_HEAD) + EFI_IP4_HEADER_LEN(IpHdr) + 8)
  67
  68 /**
  69   Get the packet header from NET_BUF.
  70
  71   @param[out]  Buf    A pointer to NET_BUF
  72   @param[in]   Type   Header type
  73
  74   @return The pointer to packet header
  75 **/
  76 #define NET_PROTO_HDR(Buf, Type)  ((Type *) ((Buf)->BlockOp[0].Head))
  77
  78
  79 extern EFI_IP4_CONFIG_DATA  mIpIoDefaultIpConfigData;
  80
  81 ///
  82 /// This error will be delivered to the
  83 /// listening transportation layer protocol
  84 /// that consumes IpIO.
  85 ///
  86 typedef enum {
  87   ICMP_ERR_UNREACH_NET      = 0,
  88   ICMP_ERR_UNREACH_HOST,
  89   ICMP_ERR_UNREACH_PROTOCOL,
  90   ICMP_ERR_UNREACH_PORT,
  91   ICMP_ERR_MSGSIZE,
  92   ICMP_ERR_UNREACH_SRCFAIL,
  93   ICMP_ERR_TIMXCEED_INTRANS,
  94   ICMP_ERR_TIMXCEED_REASS,
  95   ICMP_ERR_QUENCH,
  96   ICMP_ERR_PARAMPROB
  97 } ICMP_ERROR;
  98
  99 ///
 100 /// The helper struct for IpIoGetIcmpErrStatus(). It is internal-use only.
 101 ///
 102 typedef struct {
 103   BOOLEAN     IsHard;
 104   BOOLEAN     Notify;
 105 } ICMP_ERROR_INFO;
 106
 107 ///
 108 /// The IP session for an IP receive packet.
 109 ///
 110 typedef struct _EFI_NET_SESSION_DATA {
 111   IP4_ADDR        Source;     ///< Source IP of the received packet
 112   IP4_ADDR        Dest;       ///< Destination IP of the received packet
 113   EFI_IP4_HEADER  *IpHdr;     ///< IP4 header of the received packet
 114 } EFI_NET_SESSION_DATA;
 115
 116 /**
 117   The prototype is called back when an IP packet is received.
 118
 119   @param[in] Status        Result of the receive request
 120   @param[in] IcmpErr       Valid when Status is EFI_ICMP_ERROR
 121   @param[in] NetSession    The IP session for the received packet
 122   @param[in] Pkt           Packet received
 123   @param[in] Context       The data provided by user for the received packet when
 124                            the callback is registered in IP_IO_OPEN_DATA::RcvdContext.
 125
 126 **/
 127 typedef
 128 VOID
 129 (*PKT_RCVD_NOTIFY) (
 130   IN EFI_STATUS           Status,
 131   IN ICMP_ERROR           IcmpErr,
 132   IN EFI_NET_SESSION_DATA *NetSession,
 133   IN NET_BUF              *Pkt,
 134   IN VOID                 *Context
 135   );
 136
 137 /**
 138   The prototype is called back when an IP packet is sent.
 139
 140   @param[in] Status        Result of the sending
 141   @param[in] Context       The data provided by user for the received packet when
 142                            the callback is registered in IP_IO_OPEN_DATA::SndContext.
 143   @param[in] Sender        A pointer to EFI_IP4_PROTOCOL for sender
 144   @param[in] NotifyData    Context data specified when calling IpIoSend()
 145
 146 **/
 147 typedef
 148 VOID
 149 (*PKT_SENT_NOTIFY) (
 150   IN EFI_STATUS  Status,
 151   IN VOID        *Context,
 152   IN VOID        *Sender,
 153   IN VOID        *NotifyData
 154   );
 155
 156 ///
 157 /// The data structure wraps Ip4 instance. It is used by IpIo Library to do all
 158 /// Ip4 operations.
 159 ///
 160 typedef struct _IP_IO {
 161   ///
 162   /// The node used to link this IpIo to the active IpIo list.
 163   ///
 164   LIST_ENTRY                    Entry;
 165
 166   ///
 167   /// The list used to maintain the IP instance for different sending purpose.
 168   ///
 169   LIST_ENTRY                    IpList;
 170
 171   EFI_HANDLE                    Controller;
 172   EFI_HANDLE                    Image;
 173   EFI_HANDLE                    ChildHandle;
 174   //
 175   // The IP instance consumed by this IP_IO
 176   //
 177   EFI_IP4_PROTOCOL              *Ip;
 178   BOOLEAN                       IsConfigured;
 179
 180   ///
 181   /// Some ip config data can be changed
 182   ///
 183   UINT8                         Protocol;
 184
 185   ///
 186   /// Token and event used to get data from IP
 187   ///
 188   EFI_IP4_COMPLETION_TOKEN      RcvToken;
 189
 190   ///
 191   /// List entry used to link the token passed to IP_IO
 192   ///
 193   LIST_ENTRY                    PendingSndList;
 194
 195   //
 196   // User interface used to get notify from IP_IO
 197   //
 198   VOID                          *RcvdContext;    ///< See IP_IO_OPEN_DATA::RcvdContext
 199   VOID                          *SndContext;     ///< See IP_IO_OPEN_DATA::SndContext
 200   PKT_RCVD_NOTIFY               PktRcvdNotify;   ///< See IP_IO_OPEN_DATA::PktRcvdNotify
 201   PKT_SENT_NOTIFY               PktSentNotify;   ///< See IP_IO_OPEN_DATA::PktSentNotify
 202 } IP_IO;
 203
 204 ///
 205 /// The struct is used for user to pass IP configuration and callbacks to IP_IO.
 206 /// It is used by IpIoOpen().
 207 ///
 208 typedef struct _IP_IO_OPEN_DATA {
 209   EFI_IP4_CONFIG_DATA IpConfigData;    ///< Configuration of the IP instance
 210   VOID                *RcvdContext;    ///< Context data used by receive callback
 211   VOID                *SndContext;     ///< Context data used by send callback
 212   PKT_RCVD_NOTIFY     PktRcvdNotify;   ///< Receive callback
 213   PKT_SENT_NOTIFY     PktSentNotify;   ///< Send callback
 214 } IP_IO_OPEN_DATA;
 215
 216 ///
 217 /// Internal struct book-keeping send request of IP_IO.
 218 ///
 219 /// An IP_IO_SEND_ENTRY will be created each time a send request is issued to
 220 /// IP_IO via IpIoSend().
 221 ///
 222 typedef struct _IP_IO_SEND_ENTRY {
 223   LIST_ENTRY                Entry;
 224   IP_IO                     *IpIo;
 225   VOID                      *Context;
 226   VOID                      *NotifyData;
 227   EFI_IP4_PROTOCOL          *Ip;
 228   NET_BUF                   *Pkt;
 229   EFI_IP4_COMPLETION_TOKEN  *SndToken;
 230 } IP_IO_SEND_ENTRY;
 231
 232 typedef EFI_IP4_OVERRIDE_DATA IP_IO_OVERRIDE;
 233
 234 ///
 235 /// The IP_IO_IP_INFO is used in IpIoSend() to override the default IP instance
 236 /// in IP_IO.
 237 ///
 238 typedef struct _IP_IO_IP_INFO {
 239   IP4_ADDR                  Addr;
 240   IP4_ADDR                  SubnetMask;
 241   LIST_ENTRY                Entry;
 242   EFI_HANDLE                ChildHandle;
 243   EFI_IP4_PROTOCOL          *Ip;
 244   EFI_IP4_COMPLETION_TOKEN  DummyRcvToken;
 245   INTN                      RefCnt;
 246 } IP_IO_IP_INFO;
 247
 248 /**
 249   Create a new IP_IO instance.
 250
 251   This function uses IP4 service binding protocol in Controller to create an IP4
 252   child (aka IP4 instance).
 253
 254   @param[in]  Image             The image handle of the driver or application that
 255                                 consumes IP_IO.
 256   @param[in]  Controller        The controller handle that has IP4 service binding
 257                                 protocol installed.
 258
 259   @return Pointer to a newly created IP_IO instance, or NULL if failed.
 260
 261 **/
 262 IP_IO *
 263 EFIAPI
 264 IpIoCreate (
 265   IN EFI_HANDLE Image,
 266   IN EFI_HANDLE Controller
 267   );
 268
 269 /**
 270   Destroy an IP_IO instance.
 271
 272   This function is paired with IpIoCreate(). The IP_IO will be closed first.
 273   Resource will be freed afterwards. See IpIoClose().
 274
 275   @param[in, out]  IpIo         Pointer to the IP_IO instance that needs to be
 276                                 destroyed.
 277
 278   @retval          EFI_SUCCESS  The IP_IO instance destroyed successfully.
 279   @retval          Others       Error condition occurred.
 280
 281 **/
 282 EFI_STATUS
 283 EFIAPI
 284 IpIoDestroy (
 285   IN OUT IP_IO *IpIo
 286   );
 287
 288 /**
 289   Stop an IP_IO instance.
 290
 291   This function is paired with IpIoOpen(). The IP_IO will be unconfigured and all
 292   the pending send/receive tokens will be canceled.
 293
 294   @param[in, out]  IpIo            Pointer to the IP_IO instance that needs to stop.
 295
 296   @retval          EFI_SUCCESS     The IP_IO instance stopped successfully.
 297   @retval          Others          Error condition occurred.
 298
 299 **/
 300 EFI_STATUS
 301 EFIAPI
 302 IpIoStop (
 303   IN OUT IP_IO *IpIo
 304   );
 305
 306 /**
 307   Open an IP_IO instance for use.
 308
 309   This function is called after IpIoCreate(). It is used for configuring the IP
 310   instance and register the callbacks and their context data for sending and
 311   receiving IP packets.
 312
 313   @param[in, out]  IpIo               Pointer to an IP_IO instance that needs
 314                                       to open.
 315   @param[in]       OpenData           The configuration data and callbacks for
 316                                       the IP_IO instance.
 317
 318   @retval          EFI_SUCCESS        The IP_IO instance opened with OpenData
 319                                       successfully.
 320   @retval          EFI_ACCESS_DENIED  The IP_IO instance is configured, avoid to
 321                                       reopen it.
 322   @retval          Others             Error condition occurred.
 323
 324 **/
 325 EFI_STATUS
 326 EFIAPI
 327 IpIoOpen (
 328   IN OUT IP_IO           *IpIo,
 329   IN     IP_IO_OPEN_DATA *OpenData
 330   );
 331
 332 /**
 333   Send out an IP packet.
 334
 335   This function is called after IpIoOpen(). The data to be sent are wrapped in
 336   Pkt. The IP instance wrapped in IpIo is used for sending by default but can be
 337   overriden by Sender. Other sending configs, like source address and gateway
 338   address etc., are specified in OverrideData.
 339
 340   @param[in, out]  IpIo                  Pointer to an IP_IO instance used for sending IP
 341                                          packet.
 342   @param[in, out]  Pkt                   Pointer to the IP packet to be sent.
 343   @param[in]       Sender                The IP protocol instance used for sending.
 344   @param[in]       Context               Optional context data.
 345   @param[in]       NotifyData            Optional notify data.
 346   @param[in]       Dest                  The destination IP address to send this packet to.
 347   @param[in]       OverrideData          The data to override some configuration of the IP
 348                                          instance used for sending.
 349
 350   @retval          EFI_SUCCESS           The operation is completed successfully.
 351   @retval          EFI_NOT_STARTED       The IpIo is not configured.
 352   @retval          EFI_OUT_OF_RESOURCES  Failed due to resource limit.
 353
 354 **/
 355 EFI_STATUS
 356 EFIAPI
 357 IpIoSend (
 358   IN OUT IP_IO          *IpIo,
 359   IN OUT NET_BUF        *Pkt,
 360   IN     IP_IO_IP_INFO  *Sender        OPTIONAL,
 361   IN     VOID           *Context       OPTIONAL,
 362   IN     VOID           *NotifyData    OPTIONAL,
 363   IN     IP4_ADDR       Dest,
 364   IN     IP_IO_OVERRIDE *OverrideData  OPTIONAL
 365   );
 366
 367 /**
 368   Cancel the IP transmit token which wraps this Packet.
 369
 370   @param[in]  IpIo                  Pointer to the IP_IO instance.
 371   @param[in]  Packet                Pointer to the packet of NET_BUF to cancel.
 372
 373 **/
 374 VOID
 375 EFIAPI
 376 IpIoCancelTxToken (
 377   IN IP_IO  *IpIo,
 378   IN VOID   *Packet
 379   );
 380
 381 /**
 382   Add a new IP instance for sending data.
 383
 384   The function is used to add the IP_IO to the IP_IO sending list. The caller
 385   can later use IpIoFindSender() to get the IP_IO and call IpIoSend() to send
 386   data.
 387
 388   @param[in, out]  IpIo               Pointer to a IP_IO instance to add a new IP
 389                                       instance for sending purpose.
 390
 391   @return Pointer to the created IP_IO_IP_INFO structure, NULL if failed.
 392
 393 **/
 394 IP_IO_IP_INFO *
 395 EFIAPI
 396 IpIoAddIp (
 397   IN OUT IP_IO  *IpIo
 398   );
 399
 400 /**
 401   Configure the IP instance of this IpInfo and start the receiving if Ip4ConfigData
 402   is not NULL.
 403
 404   @param[in, out]  IpInfo          Pointer to the IP_IO_IP_INFO instance.
 405   @param[in, out]  Ip4ConfigData   The IP4 configure data used to configure the IP
 406                                    instance, if NULL the IP instance is reset. If
 407                                    UseDefaultAddress is set to TRUE, and the configure
 408                                    operation succeeds, the default address information
 409                                    is written back in this Ip4ConfigData.
 410
 411   @retval          EFI_SUCCESS     The IP instance of this IpInfo is configured successfully
 412                                    or no need to reconfigure it.
 413   @retval          Others          Configuration fails.
 414
 415 **/
 416 EFI_STATUS
 417 EFIAPI
 418 IpIoConfigIp (
 419   IN OUT IP_IO_IP_INFO        *IpInfo,
 420   IN OUT EFI_IP4_CONFIG_DATA  *Ip4ConfigData OPTIONAL
 421   );
 422
 423 /**
 424   Destroy an IP instance maintained in IpIo->IpList for
 425   sending purpose.
 426
 427   This function pairs with IpIoAddIp(). The IpInfo is previously created by
 428   IpIoAddIp(). The IP_IO_IP_INFO::RefCnt is decremented and the IP instance
 429   will be dstroyed if the RefCnt is zero.
 430
 431   @param[in]  IpIo                  Pointer to the IP_IO instance.
 432   @param[in]  IpInfo                Pointer to the IpInfo to be removed.
 433
 434 **/
 435 VOID
 436 EFIAPI
 437 IpIoRemoveIp (
 438   IN IP_IO            *IpIo,
 439   IN IP_IO_IP_INFO    *IpInfo
 440   );
 441
 442 /**
 443   Find the first IP protocol maintained in IpIo whose local
 444   address is the same with Src.
 445
 446   This function is called when the caller needs the IpIo to send data to the
 447   specified Src. The IpIo was added previously by IpIoAddIp().
 448
 449   @param[in, out]  IpIo              Pointer to the pointer of the IP_IO instance.
 450   @param[in]       Src               The local IP address.
 451
 452   @return Pointer to the IP protocol can be used for sending purpose and its local
 453           address is the same with Src.
 454
 455 **/
 456 IP_IO_IP_INFO *
 457 EFIAPI
 458 IpIoFindSender (
 459   IN OUT IP_IO     **IpIo,
 460   IN     IP4_ADDR  Src
 461   );
 462
 463 /**
 464   Get the ICMP error map information.
 465
 466   The ErrorStatus will be returned. The IsHard and Notify are optional. If they
 467   are not NULL, this routine will fill them.
 468
 469   @param[in]   IcmpError             IcmpError Type.
 470   @param[out]  IsHard                Whether it is a hard error.
 471   @param[out]  Notify                Whether it need to notify SockError.
 472
 473   @return ICMP Error Status, such as EFI_NETWORK_UNREACHABLE.
 474
 475 **/
 476 EFI_STATUS
 477 EFIAPI
 478 IpIoGetIcmpErrStatus (
 479   IN  ICMP_ERROR  IcmpError,
 480   OUT BOOLEAN     *IsHard  OPTIONAL,
 481   OUT BOOLEAN     *Notify  OPTIONAL
 482   );
 483
 484 #endif