MdeModulePkg/Include/Library/IpIoLib.h

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