MdeModulePkg/Include/Library/NetLib.h

   1 /** @file
   2   This library is only intended to be used by UEFI network stack modules.
   3   It provides basic functions for the UEFI network stack.
   4
   5 Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>
   6 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<BR>
   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 _NET_LIB_H_
  17 #define _NET_LIB_H_
  18
  19 #include <Protocol/Ip6.h>
  20
  21 #include <Library/BaseLib.h>
  22 #include <Library/BaseMemoryLib.h>
  23
  24 typedef UINT32          IP4_ADDR;
  25 typedef UINT32          TCP_SEQNO;
  26 typedef UINT16          TCP_PORTNO;
  27
  28
  29 #define  NET_ETHER_ADDR_LEN    6
  30 #define  NET_IFTYPE_ETHERNET   0x01
  31
  32 #define  NET_VLAN_TAG_LEN      4
  33 #define  ETHER_TYPE_VLAN       0x8100
  34
  35 #define  EFI_IP_PROTO_UDP      0x11
  36 #define  EFI_IP_PROTO_TCP      0x06
  37 #define  EFI_IP_PROTO_ICMP     0x01
  38 #define  IP4_PROTO_IGMP        0x02
  39 #define  IP6_ICMP              58
  40 #define  DNS_MAX_NAME_SIZE     255
  41 #define  DNS_MAX_MESSAGE_SIZE  512
  42
  43 //
  44 // The address classification
  45 //
  46 #define  IP4_ADDR_CLASSA       1     // Deprecated
  47 #define  IP4_ADDR_CLASSB       2     // Deprecated
  48 #define  IP4_ADDR_CLASSC       3     // Deprecated
  49 #define  IP4_ADDR_CLASSD       4
  50 #define  IP4_ADDR_CLASSE       5
  51
  52 #define  IP4_MASK_NUM          33
  53 #define  IP6_PREFIX_NUM        129
  54
  55 #define  IP4_MASK_MAX          32
  56 #define  IP6_PREFIX_MAX        128
  57
  58 #define  IP6_HOP_BY_HOP        0
  59 #define  IP6_DESTINATION       60
  60 #define  IP6_ROUTING           43
  61 #define  IP6_FRAGMENT          44
  62 #define  IP6_AH                51
  63 #define  IP6_ESP               50
  64 #define  IP6_NO_NEXT_HEADER    59
  65
  66 #define  IP_VERSION_4          4
  67 #define  IP_VERSION_6          6
  68
  69 #define  IP6_PREFIX_LENGTH     64
  70
  71 //
  72 // DNS QTYPE values
  73 //
  74 #define  DNS_TYPE_A            1
  75 #define  DNS_TYPE_NS           2
  76 #define  DNS_TYPE_CNAME        5
  77 #define  DNS_TYPE_SOA          6
  78 #define  DNS_TYPE_WKS          11
  79 #define  DNS_TYPE_PTR          12
  80 #define  DNS_TYPE_HINFO        13
  81 #define  DNS_TYPE_MINFO        14
  82 #define  DNS_TYPE_MX           15
  83 #define  DNS_TYPE_TXT          16
  84 #define  DNS_TYPE_AAAA         28
  85 #define  DNS_TYPE_SRV_RR       33
  86 #define  DNS_TYPE_AXFR         252
  87 #define  DNS_TYPE_MAILB        253
  88 #define  DNS_TYPE_ANY          255
  89
  90 //
  91 // DNS QCLASS values
  92 //
  93 #define  DNS_CLASS_INET        1
  94 #define  DNS_CLASS_CH          3
  95 #define  DNS_CLASS_HS          4
  96 #define  DNS_CLASS_ANY         255
  97
  98 //
  99 // Number of 100ns units time Interval for network media state detect
 100 //
 101 #define MEDIA_STATE_DETECT_TIME_INTERVAL  1000000U
 102
 103
 104 #pragma pack(1)
 105
 106 //
 107 // Ethernet head definition
 108 //
 109 typedef struct {
 110   UINT8                 DstMac [NET_ETHER_ADDR_LEN];
 111   UINT8                 SrcMac [NET_ETHER_ADDR_LEN];
 112   UINT16                EtherType;
 113 } ETHER_HEAD;
 114
 115 //
 116 // 802.1Q VLAN Tag Control Information
 117 //
 118 typedef union {
 119   struct {
 120     UINT16              Vid      : 12;  // Unique VLAN identifier (0 to 4094)
 121     UINT16              Cfi      : 1;   // Canonical Format Indicator
 122     UINT16              Priority : 3;   // 802.1Q priority level (0 to 7)
 123   } Bits;
 124   UINT16                Uint16;
 125 } VLAN_TCI;
 126
 127 #define VLAN_TCI_CFI_CANONICAL_MAC      0
 128 #define VLAN_TCI_CFI_NON_CANONICAL_MAC  1
 129
 130 //
 131 // The EFI_IP4_HEADER is hard to use because the source and
 132 // destination address are defined as EFI_IPv4_ADDRESS, which
 133 // is a structure. Two structures can't be compared or masked
 134 // directly. This is why there is an internal representation.
 135 //
 136 typedef struct {
 137   UINT8                 HeadLen : 4;
 138   UINT8                 Ver     : 4;
 139   UINT8                 Tos;
 140   UINT16                TotalLen;
 141   UINT16                Id;
 142   UINT16                Fragment;
 143   UINT8                 Ttl;
 144   UINT8                 Protocol;
 145   UINT16                Checksum;
 146   IP4_ADDR              Src;
 147   IP4_ADDR              Dst;
 148 } IP4_HEAD;
 149
 150
 151 //
 152 // ICMP head definition. Each ICMP message is categorized as either an error
 153 // message or query message. Two message types have their own head format.
 154 //
 155 typedef struct {
 156   UINT8                 Type;
 157   UINT8                 Code;
 158   UINT16                Checksum;
 159 } IP4_ICMP_HEAD;
 160
 161 typedef struct {
 162   IP4_ICMP_HEAD         Head;
 163   UINT32                Fourth; // 4th filed of the head, it depends on Type.
 164   IP4_HEAD              IpHead;
 165 } IP4_ICMP_ERROR_HEAD;
 166
 167 typedef struct {
 168   IP4_ICMP_HEAD         Head;
 169   UINT16                Id;
 170   UINT16                Seq;
 171 } IP4_ICMP_QUERY_HEAD;
 172
 173 typedef struct {
 174   UINT8                 Type;
 175   UINT8                 Code;
 176   UINT16                Checksum;
 177 } IP6_ICMP_HEAD;
 178
 179 typedef struct {
 180   IP6_ICMP_HEAD         Head;
 181   UINT32                Fourth;
 182   EFI_IP6_HEADER        IpHead;
 183 } IP6_ICMP_ERROR_HEAD;
 184
 185 typedef struct {
 186   IP6_ICMP_HEAD         Head;
 187   UINT32                Fourth;
 188 } IP6_ICMP_INFORMATION_HEAD;
 189
 190 //
 191 // UDP header definition
 192 //
 193 typedef struct {
 194   UINT16                SrcPort;
 195   UINT16                DstPort;
 196   UINT16                Length;
 197   UINT16                Checksum;
 198 } EFI_UDP_HEADER;
 199
 200 //
 201 // TCP header definition
 202 //
 203 typedef struct {
 204   TCP_PORTNO            SrcPort;
 205   TCP_PORTNO            DstPort;
 206   TCP_SEQNO             Seq;
 207   TCP_SEQNO             Ack;
 208   UINT8                 Res     : 4;
 209   UINT8                 HeadLen : 4;
 210   UINT8                 Flag;
 211   UINT16                Wnd;
 212   UINT16                Checksum;
 213   UINT16                Urg;
 214 } TCP_HEAD;
 215
 216 #pragma pack()
 217
 218 #define NET_MAC_EQUAL(pMac1, pMac2, Len)     \
 219     (CompareMem ((pMac1), (pMac2), Len) == 0)
 220
 221 #define NET_MAC_IS_MULTICAST(Mac, BMac, Len) \
 222     (((*((UINT8 *) Mac) & 0x01) == 0x01) && (!NET_MAC_EQUAL (Mac, BMac, Len)))
 223
 224 #define NTOHL(x)  SwapBytes32 (x)
 225
 226 #define HTONL(x)  NTOHL(x)
 227
 228 #define NTOHS(x)  SwapBytes16 (x)
 229
 230 #define HTONS(x)   NTOHS(x)
 231 #define NTOHLL(x)  SwapBytes64 (x)
 232 #define HTONLL(x)  NTOHLL(x)
 233 #define NTOHLLL(x) Ip6Swap128 (x)
 234 #define HTONLLL(x) NTOHLLL(x)
 235
 236 //
 237 // Test the IP's attribute, All the IPs are in host byte order.
 238 //
 239 #define IP4_IS_MULTICAST(Ip)              (((Ip) & 0xF0000000) == 0xE0000000)
 240 #define IP4_IS_UNSPECIFIED(Ip)            ((Ip) == 0)
 241 #define IP4_IS_LOCAL_BROADCAST(Ip)        ((Ip) == 0xFFFFFFFF)
 242 #define IP4_NET_EQUAL(Ip1, Ip2, NetMask)  (((Ip1) & (NetMask)) == ((Ip2) & (NetMask)))
 243 #define IP4_IS_VALID_NETMASK(Ip)          (NetGetMaskLength (Ip) != (IP4_MASK_MAX + 1))
 244
 245 #define IP6_IS_MULTICAST(Ip6)             (((Ip6)->Addr[0]) == 0xFF)
 246
 247 //
 248 // Convert the EFI_IP4_ADDRESS to plain UINT32 IP4 address.
 249 //
 250 #define EFI_IP4(EfiIpAddr)       (*(IP4_ADDR *) ((EfiIpAddr).Addr))
 251 #define EFI_NTOHL(EfiIp)         (NTOHL (EFI_IP4 ((EfiIp))))
 252 #define EFI_IP4_EQUAL(Ip1, Ip2)  (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv4_ADDRESS)) == 0)
 253
 254 #define EFI_IP6_EQUAL(Ip1, Ip2)  (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv6_ADDRESS)) == 0)
 255
 256 #define IP4_COPY_ADDRESS(Dest, Src) (CopyMem ((Dest), (Src), sizeof (EFI_IPv4_ADDRESS)))
 257 #define IP6_COPY_ADDRESS(Dest, Src) (CopyMem ((Dest), (Src), sizeof (EFI_IPv6_ADDRESS)))
 258 #define IP6_COPY_LINK_ADDRESS(Mac1, Mac2) (CopyMem ((Mac1), (Mac2), sizeof (EFI_MAC_ADDRESS)))
 259
 260 //
 261 // The debug level definition. This value is also used as the
 262 // syslog's severity level. Don't change it.
 263 //
 264 #define NETDEBUG_LEVEL_TRACE   5
 265 #define NETDEBUG_LEVEL_WARNING 4
 266 #define NETDEBUG_LEVEL_ERROR   3
 267
 268 //
 269 // Network debug message is sent out as syslog packet.
 270 //
 271 #define NET_SYSLOG_FACILITY    16                 // Syslog local facility local use
 272 #define NET_SYSLOG_PACKET_LEN  512
 273 #define NET_SYSLOG_TX_TIMEOUT  (500 * 1000 * 10)  // 500ms
 274 #define NET_DEBUG_MSG_LEN      470                // 512 - (ether+ip4+udp4 head length)
 275
 276 //
 277 // The debug output expects the ASCII format string, Use %a to print ASCII
 278 // string, and %s to print UNICODE string. PrintArg must be enclosed in ().
 279 // For example: NET_DEBUG_TRACE ("Tcp", ("State transit to %a\n", Name));
 280 //
 281 #define NET_DEBUG_TRACE(Module, PrintArg) \
 282   NetDebugOutput ( \
 283     NETDEBUG_LEVEL_TRACE, \
 284     Module, \
 285     __FILE__, \
 286     __LINE__, \
 287     NetDebugASPrint PrintArg \
 288     )
 289
 290 #define NET_DEBUG_WARNING(Module, PrintArg) \
 291   NetDebugOutput ( \
 292     NETDEBUG_LEVEL_WARNING, \
 293     Module, \
 294     __FILE__, \
 295     __LINE__, \
 296     NetDebugASPrint PrintArg \
 297     )
 298
 299 #define NET_DEBUG_ERROR(Module, PrintArg) \
 300   NetDebugOutput ( \
 301     NETDEBUG_LEVEL_ERROR, \
 302     Module, \
 303     __FILE__, \
 304     __LINE__, \
 305     NetDebugASPrint PrintArg \
 306     )
 307
 308 /**
 309   Allocate a buffer, then format the message to it. This is a
 310   help function for the NET_DEBUG_XXX macros. The PrintArg of
 311   these macros treats the variable length print parameters as a
 312   single parameter, and pass it to the NetDebugASPrint. For
 313   example, NET_DEBUG_TRACE ("Tcp", ("State transit to %a\n", Name))
 314   if extracted to:
 315
 316          NetDebugOutput (
 317            NETDEBUG_LEVEL_TRACE,
 318            "Tcp",
 319            __FILE__,
 320            __LINE__,
 321            NetDebugASPrint ("State transit to %a\n", Name)
 322          )
 323
 324   @param Format  The ASCII format string.
 325   @param ...     The variable length parameter whose format is determined
 326                  by the Format string.
 327
 328   @return        The buffer containing the formatted message,
 329                  or NULL if memory allocation failed.
 330
 331 **/
 332 CHAR8 *
 333 EFIAPI
 334 NetDebugASPrint (
 335   IN CHAR8                  *Format,
 336   ...
 337   );
 338
 339 /**
 340   Builds an UDP4 syslog packet and send it using SNP.
 341
 342   This function will locate a instance of SNP then send the message through it.
 343   Because it isn't open the SNP BY_DRIVER, apply caution when using it.
 344
 345   @param Level    The severity level of the message.
 346   @param Module   The Module that generates the log.
 347   @param File     The file that contains the log.
 348   @param Line     The exact line that contains the log.
 349   @param Message  The user message to log.
 350
 351   @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
 352   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the packet
 353   @retval EFI_SUCCESS           The log is discard because that it is more verbose
 354                                 than the mNetDebugLevelMax. Or, it has been sent out.
 355 **/
 356 EFI_STATUS
 357 EFIAPI
 358 NetDebugOutput (
 359   IN UINT32                    Level,
 360   IN UINT8                     *Module,
 361   IN UINT8                     *File,
 362   IN UINT32                    Line,
 363   IN UINT8                     *Message
 364   );
 365
 366
 367 /**
 368   Return the length of the mask.
 369
 370   Return the length of the mask. Valid values are 0 to 32.
 371   If the mask is invalid, return the invalid length 33, which is IP4_MASK_NUM.
 372   NetMask is in the host byte order.
 373
 374   @param[in]  NetMask              The netmask to get the length from.
 375
 376   @return The length of the netmask, or IP4_MASK_NUM (33) if the mask is invalid.
 377
 378 **/
 379 INTN
 380 EFIAPI
 381 NetGetMaskLength (
 382   IN IP4_ADDR               NetMask
 383   );
 384
 385 /**
 386   Return the class of the IP address, such as class A, B, C.
 387   Addr is in host byte order.
 388
 389   [ATTENTION]
 390   Classful addressing (IP class A/B/C) has been deprecated according to RFC4632.
 391   Caller of this function could only check the returned value against
 392   IP4_ADDR_CLASSD (multicast) or IP4_ADDR_CLASSE (reserved) now.
 393
 394   The address of class A  starts with 0.
 395   If the address belong to class A, return IP4_ADDR_CLASSA.
 396   The address of class B  starts with 10.
 397   If the address belong to class B, return IP4_ADDR_CLASSB.
 398   The address of class C  starts with 110.
 399   If the address belong to class C, return IP4_ADDR_CLASSC.
 400   The address of class D  starts with 1110.
 401   If the address belong to class D, return IP4_ADDR_CLASSD.
 402   The address of class E  starts with 1111.
 403   If the address belong to class E, return IP4_ADDR_CLASSE.
 404
 405
 406   @param[in]   Addr                  The address to get the class from.
 407
 408   @return IP address class, such as IP4_ADDR_CLASSA.
 409
 410 **/
 411 INTN
 412 EFIAPI
 413 NetGetIpClass (
 414   IN IP4_ADDR               Addr
 415   );
 416
 417 /**
 418   Check whether the IP is a valid unicast address according to
 419   the netmask.
 420
 421   ASSERT if NetMask is zero.
 422
 423   If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address,
 424   except when the originator is one of the endpoints of a point-to-point link with a 31-bit
 425   mask (RFC3021), or a 32bit NetMask (all 0xFF) is used for special network environment (e.g.
 426   PPP link).
 427
 428   @param[in]  Ip                    The IP to check against.
 429   @param[in]  NetMask               The mask of the IP.
 430
 431   @return TRUE if IP is a valid unicast address on the network, otherwise FALSE.
 432
 433 **/
 434 BOOLEAN
 435 EFIAPI
 436 NetIp4IsUnicast (
 437   IN IP4_ADDR               Ip,
 438   IN IP4_ADDR               NetMask
 439   );
 440
 441 /**
 442   Check whether the incoming IPv6 address is a valid unicast address.
 443
 444   ASSERT if Ip6 is NULL.
 445
 446   If the address is a multicast address has binary 0xFF at the start, it is not
 447   a valid unicast address. If the address is unspecified ::, it is not a valid
 448   unicast address to be assigned to any node. If the address is loopback address
 449   ::1, it is also not a valid unicast address to be assigned to any physical
 450   interface.
 451
 452   @param[in]  Ip6                   The IPv6 address to check against.
 453
 454   @return TRUE if Ip6 is a valid unicast address on the network, otherwise FALSE.
 455
 456 **/
 457 BOOLEAN
 458 EFIAPI
 459 NetIp6IsValidUnicast (
 460   IN EFI_IPv6_ADDRESS       *Ip6
 461   );
 462
 463
 464 /**
 465   Check whether the incoming Ipv6 address is the unspecified address or not.
 466
 467   ASSERT if Ip6 is NULL.
 468
 469   @param[in] Ip6   - Ip6 address, in network order.
 470
 471   @retval TRUE     - Yes, incoming Ipv6 address is the unspecified address.
 472   @retval FALSE    - The incoming Ipv6 address is not the unspecified address
 473
 474 **/
 475 BOOLEAN
 476 EFIAPI
 477 NetIp6IsUnspecifiedAddr (
 478   IN EFI_IPv6_ADDRESS       *Ip6
 479   );
 480
 481 /**
 482   Check whether the incoming Ipv6 address is a link-local address.
 483
 484   ASSERT if Ip6 is NULL.
 485
 486   @param[in] Ip6   - Ip6 address, in network order.
 487
 488   @retval TRUE  - The incoming Ipv6 address is a link-local address.
 489   @retval FALSE - The incoming Ipv6 address is not a link-local address.
 490
 491 **/
 492 BOOLEAN
 493 EFIAPI
 494 NetIp6IsLinkLocalAddr (
 495   IN EFI_IPv6_ADDRESS *Ip6
 496   );
 497
 498 /**
 499   Check whether the Ipv6 address1 and address2 are on the connected network.
 500
 501   ASSERT if Ip1 or Ip2 is NULL.
 502   ASSERT if PrefixLength exceeds or equals to IP6_PREFIX_MAX.
 503
 504   @param[in] Ip1          - Ip6 address1, in network order.
 505   @param[in] Ip2          - Ip6 address2, in network order.
 506   @param[in] PrefixLength - The prefix length of the checking net.
 507
 508   @retval TRUE            - Yes, the Ipv6 address1 and address2 are connected.
 509   @retval FALSE           - No the Ipv6 address1 and address2 are not connected.
 510
 511 **/
 512 BOOLEAN
 513 EFIAPI
 514 NetIp6IsNetEqual (
 515   EFI_IPv6_ADDRESS *Ip1,
 516   EFI_IPv6_ADDRESS *Ip2,
 517   UINT8            PrefixLength
 518   );
 519
 520 /**
 521   Switches the endianess of an IPv6 address.
 522
 523   ASSERT if Ip6 is NULL.
 524
 525   This function swaps the bytes in a 128-bit IPv6 address to switch the value
 526   from little endian to big endian or vice versa. The byte swapped value is
 527   returned.
 528
 529   @param  Ip6 Points to an IPv6 address.
 530
 531   @return The byte swapped IPv6 address.
 532
 533 **/
 534 EFI_IPv6_ADDRESS *
 535 EFIAPI
 536 Ip6Swap128 (
 537   EFI_IPv6_ADDRESS *Ip6
 538   );
 539
 540 extern IP4_ADDR gIp4AllMasks[IP4_MASK_NUM];
 541
 542
 543 extern EFI_IPv4_ADDRESS  mZeroIp4Addr;
 544
 545 #define NET_IS_DIGIT(Ch)            (('0' <= (Ch)) && ((Ch) <= '9'))
 546 #define NET_IS_HEX(Ch)              ((('0' <= (Ch)) && ((Ch) <= '9')) || (('A' <= (Ch)) && ((Ch) <= 'F')) || (('a' <= (Ch)) && ((Ch) <= 'f')))
 547 #define NET_ROUNDUP(size, unit)     (((size) + (unit) - 1) & (~((unit) - 1)))
 548 #define NET_IS_LOWER_CASE_CHAR(Ch)  (('a' <= (Ch)) && ((Ch) <= 'z'))
 549 #define NET_IS_UPPER_CASE_CHAR(Ch)  (('A' <= (Ch)) && ((Ch) <= 'Z'))
 550
 551 #define TICKS_PER_MS            10000U
 552 #define TICKS_PER_SECOND        10000000U
 553
 554 #define NET_RANDOM(Seed)        ((UINT32) ((UINT32) (Seed) * 1103515245UL + 12345) % 4294967295UL)
 555
 556 /**
 557   Extract a UINT32 from a byte stream.
 558
 559   ASSERT if Buf is NULL.
 560
 561   This function copies a UINT32 from a byte stream, and then converts it from Network
 562   byte order to host byte order. Use this function to avoid alignment error.
 563
 564   @param[in]  Buf                 The buffer to extract the UINT32.
 565
 566   @return The UINT32 extracted.
 567
 568 **/
 569 UINT32
 570 EFIAPI
 571 NetGetUint32 (
 572   IN UINT8                  *Buf
 573   );
 574
 575 /**
 576   Puts a UINT32 into the byte stream in network byte order.
 577
 578   ASSERT if Buf is NULL.
 579
 580   Converts a UINT32 from host byte order to network byte order, then copies it to the
 581   byte stream.
 582
 583   @param[in, out]  Buf          The buffer in which to put the UINT32.
 584   @param[in]       Data         The data to be converted and put into the byte stream.
 585
 586 **/
 587 VOID
 588 EFIAPI
 589 NetPutUint32 (
 590   IN OUT UINT8                 *Buf,
 591   IN     UINT32                Data
 592   );
 593
 594 /**
 595   Initialize a random seed using current time and monotonic count.
 596
 597   Get current time and monotonic count first. Then initialize a random seed
 598   based on some basic mathematics operation on the hour, day, minute, second,
 599   nanosecond and year of the current time and the monotonic count value.
 600
 601   @return The random seed initialized with current time.
 602
 603 **/
 604 UINT32
 605 EFIAPI
 606 NetRandomInitSeed (
 607   VOID
 608   );
 609
 610
 611 #define NET_LIST_USER_STRUCT(Entry, Type, Field)        \
 612           BASE_CR(Entry, Type, Field)
 613
 614 #define NET_LIST_USER_STRUCT_S(Entry, Type, Field, Sig)  \
 615           CR(Entry, Type, Field, Sig)
 616
 617 //
 618 // Iterate through the double linked list. It is NOT delete safe
 619 //
 620 #define NET_LIST_FOR_EACH(Entry, ListHead) \
 621   for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
 622
 623 //
 624 // Iterate through the double linked list. This is delete-safe.
 625 // Don't touch NextEntry. Also, don't use this macro if list
 626 // entries other than the Entry may be deleted when processing
 627 // the current Entry.
 628 //
 629 #define NET_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
 630   for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink; \
 631       Entry != (ListHead); \
 632       Entry = NextEntry, NextEntry = Entry->ForwardLink \
 633      )
 634
 635 //
 636 // Make sure the list isn't empty before getting the first/last record.
 637 //
 638 #define NET_LIST_HEAD(ListHead, Type, Field)  \
 639           NET_LIST_USER_STRUCT((ListHead)->ForwardLink, Type, Field)
 640
 641 #define NET_LIST_TAIL(ListHead, Type, Field)  \
 642           NET_LIST_USER_STRUCT((ListHead)->BackLink, Type, Field)
 643
 644
 645 /**
 646   Remove the first node entry on the list, and return the removed node entry.
 647
 648   Removes the first node entry from a doubly linked list. It is up to the caller of
 649   this function to release the memory used by the first node, if that is required. On
 650   exit, the removed node is returned.
 651
 652   If Head is NULL, then ASSERT().
 653   If Head was not initialized, then ASSERT().
 654   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
 655   linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,
 656   then ASSERT().
 657
 658   @param[in, out]  Head                  The list header.
 659
 660   @return The first node entry that is removed from the list, NULL if the list is empty.
 661
 662 **/
 663 LIST_ENTRY *
 664 EFIAPI
 665 NetListRemoveHead (
 666   IN OUT LIST_ENTRY            *Head
 667   );
 668
 669 /**
 670   Remove the last node entry on the list and return the removed node entry.
 671
 672   Removes the last node entry from a doubly linked list. It is up to the caller of
 673   this function to release the memory used by the first node, if that is required. On
 674   exit, the removed node is returned.
 675
 676   If Head is NULL, then ASSERT().
 677   If Head was not initialized, then ASSERT().
 678   If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
 679   linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,
 680   then ASSERT().
 681
 682   @param[in, out]  Head                  The list head.
 683
 684   @return The last node entry that is removed from the list, NULL if the list is empty.
 685
 686 **/
 687 LIST_ENTRY *
 688 EFIAPI
 689 NetListRemoveTail (
 690   IN OUT LIST_ENTRY            *Head
 691   );
 692
 693 /**
 694   Insert a new node entry after a designated node entry of a doubly linked list.
 695
 696   ASSERT if PrevEntry or NewEntry is NULL.
 697
 698   Inserts a new node entry designated by NewEntry after the node entry designated by PrevEntry
 699   of the doubly linked list.
 700
 701   @param[in, out]  PrevEntry             The entry after which to insert.
 702   @param[in, out]  NewEntry              The new entry to insert.
 703
 704 **/
 705 VOID
 706 EFIAPI
 707 NetListInsertAfter (
 708   IN OUT LIST_ENTRY         *PrevEntry,
 709   IN OUT LIST_ENTRY         *NewEntry
 710   );
 711
 712 /**
 713   Insert a new node entry before a designated node entry of a doubly linked list.
 714
 715   ASSERT if PostEntry or NewEntry is NULL.
 716
 717   Inserts a new node entry designated by NewEntry before the node entry designated by PostEntry
 718   of the doubly linked list.
 719
 720   @param[in, out]  PostEntry             The entry to insert before.
 721   @param[in, out]  NewEntry              The new entry to insert.
 722
 723 **/
 724 VOID
 725 EFIAPI
 726 NetListInsertBefore (
 727   IN OUT LIST_ENTRY     *PostEntry,
 728   IN OUT LIST_ENTRY     *NewEntry
 729   );
 730
 731 /**
 732   Callback function which provided by user to remove one node in NetDestroyLinkList process.
 733
 734   @param[in]    Entry           The entry to be removed.
 735   @param[in]    Context         Pointer to the callback context corresponds to the Context in NetDestroyLinkList.
 736
 737   @retval EFI_SUCCESS           The entry has been removed successfully.
 738   @retval Others                Fail to remove the entry.
 739
 740 **/
 741 typedef
 742 EFI_STATUS
 743 (EFIAPI *NET_DESTROY_LINK_LIST_CALLBACK) (
 744   IN LIST_ENTRY         *Entry,
 745   IN VOID               *Context   OPTIONAL
 746   );
 747
 748 /**
 749   Safe destroy nodes in a linked list, and return the length of the list after all possible operations finished.
 750
 751   Destroy network children list by list traversals is not safe due to graph dependencies between nodes.
 752   This function performs a safe traversal to destroy these nodes by checking to see if the node being destroyed
 753   has been removed from the list or not.
 754   If it has been removed, then restart the traversal from the head.
 755   If it hasn't been removed, then continue with the next node directly.
 756   This function will end the iterate and return the CallBack's last return value if error happens,
 757   or retrun EFI_SUCCESS if 2 complete passes are made with no changes in the number of children in the list.
 758
 759   @param[in]    List             The head of the list.
 760   @param[in]    CallBack         Pointer to the callback function to destroy one node in the list.
 761   @param[in]    Context          Pointer to the callback function's context: corresponds to the
 762                                  parameter Context in NET_DESTROY_LINK_LIST_CALLBACK.
 763   @param[out]   ListLength       The length of the link list if the function returns successfully.
 764
 765   @retval EFI_SUCCESS            Two complete passes are made with no changes in the number of children.
 766   @retval EFI_INVALID_PARAMETER  The input parameter is invalid.
 767   @retval Others                 Return the CallBack's last return value.
 768
 769 **/
 770 EFI_STATUS
 771 EFIAPI
 772 NetDestroyLinkList (
 773   IN   LIST_ENTRY                       *List,
 774   IN   NET_DESTROY_LINK_LIST_CALLBACK   CallBack,
 775   IN   VOID                             *Context,    OPTIONAL
 776   OUT  UINTN                            *ListLength  OPTIONAL
 777   );
 778
 779 /**
 780   This function checks the input Handle to see if it's one of these handles in ChildHandleBuffer.
 781
 782   @param[in]  Handle             Handle to be checked.
 783   @param[in]  NumberOfChildren   Number of Handles in ChildHandleBuffer.
 784   @param[in]  ChildHandleBuffer  An array of child handles to be freed. May be NULL
 785                                  if NumberOfChildren is 0.
 786
 787   @retval TRUE                   Found the input Handle in ChildHandleBuffer.
 788   @retval FALSE                  Can't find the input Handle in ChildHandleBuffer.
 789
 790 **/
 791 BOOLEAN
 792 EFIAPI
 793 NetIsInHandleBuffer (
 794   IN  EFI_HANDLE          Handle,
 795   IN  UINTN               NumberOfChildren,
 796   IN  EFI_HANDLE          *ChildHandleBuffer OPTIONAL
 797   );
 798
 799 //
 800 // Object container: EFI network stack spec defines various kinds of
 801 // tokens. The drivers can share code to manage those objects.
 802 //
 803 typedef struct {
 804   LIST_ENTRY                Link;
 805   VOID                      *Key;
 806   VOID                      *Value;
 807 } NET_MAP_ITEM;
 808
 809 typedef struct {
 810   LIST_ENTRY                Used;
 811   LIST_ENTRY                Recycled;
 812   UINTN                     Count;
 813 } NET_MAP;
 814
 815 #define NET_MAP_INCREAMENT  64
 816
 817 /**
 818   Initialize the netmap. Netmap is a reposity to keep the <Key, Value> pairs.
 819
 820   Initialize the forward and backward links of two head nodes donated by Map->Used
 821   and Map->Recycled of two doubly linked lists.
 822   Initializes the count of the <Key, Value> pairs in the netmap to zero.
 823
 824   If Map is NULL, then ASSERT().
 825   If the address of Map->Used is NULL, then ASSERT().
 826   If the address of Map->Recycled is NULl, then ASSERT().
 827
 828   @param[in, out]  Map                   The netmap to initialize.
 829
 830 **/
 831 VOID
 832 EFIAPI
 833 NetMapInit (
 834   IN OUT NET_MAP                *Map
 835   );
 836
 837 /**
 838   To clean up the netmap, that is, release allocated memories.
 839
 840   Removes all nodes of the Used doubly linked list and frees memory of all related netmap items.
 841   Removes all nodes of the Recycled doubly linked list and free memory of all related netmap items.
 842   The number of the <Key, Value> pairs in the netmap is set to zero.
 843
 844   If Map is NULL, then ASSERT().
 845
 846   @param[in, out]  Map                   The netmap to clean up.
 847
 848 **/
 849 VOID
 850 EFIAPI
 851 NetMapClean (
 852   IN OUT NET_MAP            *Map
 853   );
 854
 855 /**
 856   Test whether the netmap is empty and return true if it is.
 857
 858   If the number of the <Key, Value> pairs in the netmap is zero, return TRUE.
 859
 860   If Map is NULL, then ASSERT().
 861
 862   @param[in]  Map                   The net map to test.
 863
 864   @return TRUE if the netmap is empty, otherwise FALSE.
 865
 866 **/
 867 BOOLEAN
 868 EFIAPI
 869 NetMapIsEmpty (
 870   IN NET_MAP                *Map
 871   );
 872
 873 /**
 874   Return the number of the <Key, Value> pairs in the netmap.
 875
 876   If Map is NULL, then ASSERT().
 877
 878   @param[in]  Map                   The netmap to get the entry number.
 879
 880   @return The entry number in the netmap.
 881
 882 **/
 883 UINTN
 884 EFIAPI
 885 NetMapGetCount (
 886   IN NET_MAP                *Map
 887   );
 888
 889 /**
 890   Allocate an item to save the <Key, Value> pair to the head of the netmap.
 891
 892   Allocate an item to save the <Key, Value> pair and add corresponding node entry
 893   to the beginning of the Used doubly linked list. The number of the <Key, Value>
 894   pairs in the netmap increase by 1.
 895
 896   If Map is NULL, then ASSERT().
 897   If Key is NULL, then ASSERT().
 898
 899   @param[in, out]  Map                   The netmap to insert into.
 900   @param[in]       Key                   The user's key.
 901   @param[in]       Value                 The user's value for the key.
 902
 903   @retval EFI_OUT_OF_RESOURCES  Failed to allocate the memory for the item.
 904   @retval EFI_SUCCESS           The item is inserted to the head.
 905
 906 **/
 907 EFI_STATUS
 908 EFIAPI
 909 NetMapInsertHead (
 910   IN OUT NET_MAP            *Map,
 911   IN VOID                   *Key,
 912   IN VOID                   *Value    OPTIONAL
 913   );
 914
 915 /**
 916   Allocate an item to save the <Key, Value> pair to the tail of the netmap.
 917
 918   Allocate an item to save the <Key, Value> pair and add corresponding node entry
 919   to the tail of the Used doubly linked list. The number of the <Key, Value>
 920   pairs in the netmap increase by 1.
 921
 922   If Map is NULL, then ASSERT().
 923   If Key is NULL, then ASSERT().
 924
 925   @param[in, out]  Map                   The netmap to insert into.
 926   @param[in]       Key                   The user's key.
 927   @param[in]       Value                 The user's value for the key.
 928
 929   @retval EFI_OUT_OF_RESOURCES  Failed to allocate the memory for the item.
 930   @retval EFI_SUCCESS           The item is inserted to the tail.
 931
 932 **/
 933 EFI_STATUS
 934 EFIAPI
 935 NetMapInsertTail (
 936   IN OUT NET_MAP            *Map,
 937   IN VOID                   *Key,
 938   IN VOID                   *Value    OPTIONAL
 939   );
 940
 941 /**
 942   Finds the key in the netmap and returns the point to the item containing the Key.
 943
 944   Iterate the Used doubly linked list of the netmap to get every item. Compare the key of every
 945   item with the key to search. It returns the point to the item contains the Key if found.
 946
 947   If Map is NULL, then ASSERT().
 948   If Key is NULL, then ASSERT().
 949
 950   @param[in]  Map                   The netmap to search within.
 951   @param[in]  Key                   The key to search.
 952
 953   @return The point to the item contains the Key, or NULL if Key isn't in the map.
 954
 955 **/
 956 NET_MAP_ITEM *
 957 EFIAPI
 958 NetMapFindKey (
 959   IN  NET_MAP               *Map,
 960   IN  VOID                  *Key
 961   );
 962
 963 /**
 964   Remove the node entry of the item from the netmap and return the key of the removed item.
 965
 966   Remove the node entry of the item from the Used doubly linked list of the netmap.
 967   The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node
 968   entry of the item to the Recycled doubly linked list of the netmap. If Value is not NULL,
 969   Value will point to the value of the item. It returns the key of the removed item.
 970
 971   If Map is NULL, then ASSERT().
 972   If Item is NULL, then ASSERT().
 973   if item in not in the netmap, then ASSERT().
 974
 975   @param[in, out]  Map                   The netmap to remove the item from.
 976   @param[in, out]  Item                  The item to remove.
 977   @param[out]      Value                 The variable to receive the value if not NULL.
 978
 979   @return                                The key of the removed item.
 980
 981 **/
 982 VOID *
 983 EFIAPI
 984 NetMapRemoveItem (
 985   IN  OUT NET_MAP             *Map,
 986   IN  OUT NET_MAP_ITEM        *Item,
 987   OUT VOID                    **Value           OPTIONAL
 988   );
 989
 990 /**
 991   Remove the first node entry on the netmap and return the key of the removed item.
 992
 993   Remove the first node entry from the Used doubly linked list of the netmap.
 994   The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node
 995   entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,
 996   parameter Value will point to the value of the item. It returns the key of the removed item.
 997
 998   If Map is NULL, then ASSERT().
 999   If the Used doubly linked list is empty, then ASSERT().
1000
1001   @param[in, out]  Map                   The netmap to remove the head from.
1002   @param[out]      Value                 The variable to receive the value if not NULL.
1003
1004   @return                                The key of the item removed.
1005
1006 **/
1007 VOID *
1008 EFIAPI
1009 NetMapRemoveHead (
1010   IN OUT NET_MAP            *Map,
1011   OUT VOID                  **Value         OPTIONAL
1012   );
1013
1014 /**
1015   Remove the last node entry on the netmap and return the key of the removed item.
1016
1017   Remove the last node entry from the Used doubly linked list of the netmap.
1018   The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node
1019   entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,
1020   parameter Value will point to the value of the item. It returns the key of the removed item.
1021
1022   If Map is NULL, then ASSERT().
1023   If the Used doubly linked list is empty, then ASSERT().
1024
1025   @param[in, out]  Map                   The netmap to remove the tail from.
1026   @param[out]      Value                 The variable to receive the value if not NULL.
1027
1028   @return                                The key of the item removed.
1029
1030 **/
1031 VOID *
1032 EFIAPI
1033 NetMapRemoveTail (
1034   IN OUT NET_MAP            *Map,
1035   OUT VOID                  **Value       OPTIONAL
1036   );
1037
1038 typedef
1039 EFI_STATUS
1040 (EFIAPI *NET_MAP_CALLBACK) (
1041   IN NET_MAP                *Map,
1042   IN NET_MAP_ITEM           *Item,
1043   IN VOID                   *Arg
1044   );
1045
1046 /**
1047   Iterate through the netmap and call CallBack for each item.
1048
1049   It will continue the traverse if CallBack returns EFI_SUCCESS, otherwise, break
1050   from the loop. It returns the CallBack's last return value. This function is
1051   delete safe for the current item.
1052
1053   If Map is NULL, then ASSERT().
1054   If CallBack is NULL, then ASSERT().
1055
1056   @param[in]  Map                   The Map to iterate through.
1057   @param[in]  CallBack              The callback function to call for each item.
1058   @param[in]  Arg                   The opaque parameter to the callback.
1059
1060   @retval EFI_SUCCESS            There is no item in the netmap, or CallBack for each item
1061                                  returns EFI_SUCCESS.
1062   @retval Others                 It returns the CallBack's last return value.
1063
1064 **/
1065 EFI_STATUS
1066 EFIAPI
1067 NetMapIterate (
1068   IN NET_MAP                *Map,
1069   IN NET_MAP_CALLBACK       CallBack,
1070   IN VOID                   *Arg      OPTIONAL
1071   );
1072
1073
1074 //
1075 // Helper functions to implement driver binding and service binding protocols.
1076 //
1077 /**
1078   Create a child of the service that is identified by ServiceBindingGuid.
1079
1080   Get the ServiceBinding Protocol first, then use it to create a child.
1081
1082   If ServiceBindingGuid is NULL, then ASSERT().
1083   If ChildHandle is NULL, then ASSERT().
1084
1085   @param[in]       Controller            The controller which has the service installed.
1086   @param[in]       Image                 The image handle used to open service.
1087   @param[in]       ServiceBindingGuid    The service's Guid.
1088   @param[in, out]  ChildHandle           The handle to receive the created child.
1089
1090   @retval EFI_SUCCESS           The child was successfully created.
1091   @retval Others                Failed to create the child.
1092
1093 **/
1094 EFI_STATUS
1095 EFIAPI
1096 NetLibCreateServiceChild (
1097   IN  EFI_HANDLE            Controller,
1098   IN  EFI_HANDLE            Image,
1099   IN  EFI_GUID              *ServiceBindingGuid,
1100   IN  OUT EFI_HANDLE        *ChildHandle
1101   );
1102
1103 /**
1104   Destroy a child of the service that is identified by ServiceBindingGuid.
1105
1106   Get the ServiceBinding Protocol first, then use it to destroy a child.
1107
1108   If ServiceBindingGuid is NULL, then ASSERT().
1109
1110   @param[in]   Controller            The controller which has the service installed.
1111   @param[in]   Image                 The image handle used to open service.
1112   @param[in]   ServiceBindingGuid    The service's Guid.
1113   @param[in]   ChildHandle           The child to destroy.
1114
1115   @retval EFI_SUCCESS           The child was destroyed.
1116   @retval Others                Failed to destroy the child.
1117
1118 **/
1119 EFI_STATUS
1120 EFIAPI
1121 NetLibDestroyServiceChild (
1122   IN  EFI_HANDLE            Controller,
1123   IN  EFI_HANDLE            Image,
1124   IN  EFI_GUID              *ServiceBindingGuid,
1125   IN  EFI_HANDLE            ChildHandle
1126   );
1127
1128 /**
1129   Get handle with Simple Network Protocol installed on it.
1130
1131   There should be MNP Service Binding Protocol installed on the input ServiceHandle.
1132   If Simple Network Protocol is already installed on the ServiceHandle, the
1133   ServiceHandle will be returned. If SNP is not installed on the ServiceHandle,
1134   try to find its parent handle with SNP installed.
1135
1136   @param[in]   ServiceHandle    The handle where network service binding protocols are
1137                                 installed on.
1138   @param[out]  Snp              The pointer to store the address of the SNP instance.
1139                                 This is an optional parameter that may be NULL.
1140
1141   @return The SNP handle, or NULL if not found.
1142
1143 **/
1144 EFI_HANDLE
1145 EFIAPI
1146 NetLibGetSnpHandle (
1147   IN   EFI_HANDLE                  ServiceHandle,
1148   OUT  EFI_SIMPLE_NETWORK_PROTOCOL **Snp  OPTIONAL
1149   );
1150
1151 /**
1152   Retrieve VLAN ID of a VLAN device handle.
1153
1154   Search VLAN device path node in Device Path of specified ServiceHandle and
1155   return its VLAN ID. If no VLAN device path node found, then this ServiceHandle
1156   is not a VLAN device handle, and 0 will be returned.
1157
1158   @param[in]   ServiceHandle    The handle where network service binding protocols are
1159                                 installed on.
1160
1161   @return VLAN ID of the device handle, or 0 if not a VLAN device.
1162
1163 **/
1164 UINT16
1165 EFIAPI
1166 NetLibGetVlanId (
1167   IN EFI_HANDLE             ServiceHandle
1168   );
1169
1170 /**
1171   Find VLAN device handle with specified VLAN ID.
1172
1173   The VLAN child device handle is created by VLAN Config Protocol on ControllerHandle.
1174   This function will append VLAN device path node to the parent device path,
1175   and then use LocateDevicePath() to find the correct VLAN device handle.
1176
1177   @param[in]   ControllerHandle The handle where network service binding protocols are
1178                                 installed on.
1179   @param[in]   VlanId           The configured VLAN ID for the VLAN device.
1180
1181   @return The VLAN device handle, or NULL if not found.
1182
1183 **/
1184 EFI_HANDLE
1185 EFIAPI
1186 NetLibGetVlanHandle (
1187   IN EFI_HANDLE             ControllerHandle,
1188   IN UINT16                 VlanId
1189   );
1190
1191 /**
1192   Get MAC address associated with the network service handle.
1193
1194   If MacAddress is NULL, then ASSERT().
1195   If AddressSize is NULL, then ASSERT().
1196
1197   There should be MNP Service Binding Protocol installed on the input ServiceHandle.
1198   If SNP is installed on the ServiceHandle or its parent handle, MAC address will
1199   be retrieved from SNP. If no SNP found, try to get SNP mode data use MNP.
1200
1201   @param[in]   ServiceHandle    The handle where network service binding protocols are
1202                                 installed on.
1203   @param[out]  MacAddress       The pointer to store the returned MAC address.
1204   @param[out]  AddressSize      The length of returned MAC address.
1205
1206   @retval EFI_SUCCESS           MAC address was returned successfully.
1207   @retval Others                Failed to get SNP mode data.
1208
1209 **/
1210 EFI_STATUS
1211 EFIAPI
1212 NetLibGetMacAddress (
1213   IN  EFI_HANDLE            ServiceHandle,
1214   OUT EFI_MAC_ADDRESS       *MacAddress,
1215   OUT UINTN                 *AddressSize
1216   );
1217
1218 /**
1219   Convert MAC address of the NIC associated with specified Service Binding Handle
1220   to a unicode string. Callers are responsible for freeing the string storage.
1221
1222   If MacString is NULL, then ASSERT().
1223
1224   Locate simple network protocol associated with the Service Binding Handle and
1225   get the mac address from SNP. Then convert the mac address into a unicode
1226   string. It takes 2 unicode characters to represent a 1 byte binary buffer.
1227   Plus one unicode character for the null-terminator.
1228
1229   @param[in]   ServiceHandle         The handle where network service binding protocol is
1230                                      installed.
1231   @param[in]   ImageHandle           The image handle used to act as the agent handle to
1232                                      get the simple network protocol. This parameter is
1233                                      optional and may be NULL.
1234   @param[out]  MacString             The pointer to store the address of the string
1235                                      representation of  the mac address.
1236
1237   @retval EFI_SUCCESS           Converted the mac address a unicode string successfully.
1238   @retval EFI_OUT_OF_RESOURCES  There are not enough memory resources.
1239   @retval Others                Failed to open the simple network protocol.
1240
1241 **/
1242 EFI_STATUS
1243 EFIAPI
1244 NetLibGetMacString (
1245   IN  EFI_HANDLE            ServiceHandle,
1246   IN  EFI_HANDLE            ImageHandle, OPTIONAL
1247   OUT CHAR16                **MacString
1248   );
1249
1250 /**
1251   Detect media status for specified network device.
1252
1253   If MediaPresent is NULL, then ASSERT().
1254
1255   The underlying UNDI driver may or may not support reporting media status from
1256   GET_STATUS command (PXE_STATFLAGS_GET_STATUS_NO_MEDIA_SUPPORTED). This routine
1257   will try to invoke Snp->GetStatus() to get the media status. If media is already
1258   present, it returns directly. If media is not present, it will stop SNP and then
1259   restart SNP to get the latest media status. This provides an opportunity to get
1260   the correct media status for old UNDI driver, which doesn't support reporting
1261   media status from GET_STATUS command.
1262   Note: there are two limitations for the current algorithm:
1263   1) For UNDI with this capability, when the cable is not attached, there will
1264      be an redundant Stop/Start() process.
1265   2) for UNDI without this capability, in case that network cable is attached when
1266      Snp->Initialize() is invoked while network cable is unattached later,
1267      NetLibDetectMedia() will report MediaPresent as TRUE, causing upper layer
1268      apps to wait for timeout time.
1269
1270   @param[in]   ServiceHandle    The handle where network service binding protocols are
1271                                 installed.
1272   @param[out]  MediaPresent     The pointer to store the media status.
1273
1274   @retval EFI_SUCCESS           Media detection success.
1275   @retval EFI_INVALID_PARAMETER ServiceHandle is not a valid network device handle.
1276   @retval EFI_UNSUPPORTED       The network device does not support media detection.
1277   @retval EFI_DEVICE_ERROR      SNP is in an unknown state.
1278
1279 **/
1280 EFI_STATUS
1281 EFIAPI
1282 NetLibDetectMedia (
1283   IN  EFI_HANDLE            ServiceHandle,
1284   OUT BOOLEAN               *MediaPresent
1285   );
1286
1287 /**
1288   Detect media state for a network device. This routine will wait for a period of time at
1289   a specified checking interval when a certain network is under connecting until connection
1290   process finishes or timeout. If Aip protocol is supported by low layer drivers, three kinds
1291   of media states can be detected: EFI_SUCCESS, EFI_NOT_READY and EFI_NO_MEDIA, represents
1292   connected state, connecting state and no media state respectively. When function detects
1293   the current state is EFI_NOT_READY, it will loop to wait for next time's check until state
1294   turns to be EFI_SUCCESS or EFI_NO_MEDIA. If Aip protocol is not supported, function will
1295   call NetLibDetectMedia() and return state directly.
1296
1297   @param[in]   ServiceHandle    The handle where network service binding protocols are
1298                                 installed on.
1299   @param[in]   Timeout          The maximum number of 100ns units to wait when network
1300                                 is connecting. Zero value means detect once and return
1301                                 immediately.
1302   @param[out]  MediaState       The pointer to the detected media state.
1303
1304   @retval EFI_SUCCESS           Media detection success.
1305   @retval EFI_INVALID_PARAMETER ServiceHandle is not a valid network device handle or
1306                                 MediaState pointer is NULL.
1307   @retval EFI_DEVICE_ERROR      A device error occurred.
1308   @retval EFI_TIMEOUT           Network is connecting but timeout.
1309
1310 **/
1311 EFI_STATUS
1312 EFIAPI
1313 NetLibDetectMediaWaitTimeout (
1314   IN  EFI_HANDLE            ServiceHandle,
1315   IN  UINT64                Timeout,
1316   OUT EFI_STATUS            *MediaState
1317   );
1318
1319
1320 /**
1321   Create an IPv4 device path node.
1322
1323   If Node is NULL, then ASSERT().
1324
1325   The header type of IPv4 device path node is MESSAGING_DEVICE_PATH.
1326   The header subtype of IPv4 device path node is MSG_IPv4_DP.
1327   The length of the IPv4 device path node in bytes is 19.
1328   Get other information from parameters to make up the whole IPv4 device path node.
1329
1330   @param[in, out]  Node                  The pointer to the IPv4 device path node.
1331   @param[in]       Controller            The controller handle.
1332   @param[in]       LocalIp               The local IPv4 address.
1333   @param[in]       LocalPort             The local port.
1334   @param[in]       RemoteIp              The remote IPv4 address.
1335   @param[in]       RemotePort            The remote port.
1336   @param[in]       Protocol              The protocol type in the IP header.
1337   @param[in]       UseDefaultAddress     Whether this instance is using default address or not.
1338
1339 **/
1340 VOID
1341 EFIAPI
1342 NetLibCreateIPv4DPathNode (
1343   IN OUT IPv4_DEVICE_PATH  *Node,
1344   IN EFI_HANDLE            Controller,
1345   IN IP4_ADDR              LocalIp,
1346   IN UINT16                LocalPort,
1347   IN IP4_ADDR              RemoteIp,
1348   IN UINT16                RemotePort,
1349   IN UINT16                Protocol,
1350   IN BOOLEAN               UseDefaultAddress
1351   );
1352
1353 /**
1354   Create an IPv6 device path node.
1355
1356   If Node is NULL, then ASSERT().
1357   If LocalIp is NULL, then ASSERT().
1358   If RemoteIp is NULL, then ASSERT().
1359
1360   The header type of IPv6 device path node is MESSAGING_DEVICE_PATH.
1361   The header subtype of IPv6 device path node is MSG_IPv6_DP.
1362   The length of the IPv6 device path node in bytes is 43.
1363   Get other information from parameters to make up the whole IPv6 device path node.
1364
1365   @param[in, out]  Node                  The pointer to the IPv6 device path node.
1366   @param[in]       Controller            The controller handle.
1367   @param[in]       LocalIp               The local IPv6 address.
1368   @param[in]       LocalPort             The local port.
1369   @param[in]       RemoteIp              The remote IPv6 address.
1370   @param[in]       RemotePort            The remote port.
1371   @param[in]       Protocol              The protocol type in the IP header.
1372
1373 **/
1374 VOID
1375 EFIAPI
1376 NetLibCreateIPv6DPathNode (
1377   IN OUT IPv6_DEVICE_PATH  *Node,
1378   IN EFI_HANDLE            Controller,
1379   IN EFI_IPv6_ADDRESS      *LocalIp,
1380   IN UINT16                LocalPort,
1381   IN EFI_IPv6_ADDRESS      *RemoteIp,
1382   IN UINT16                RemotePort,
1383   IN UINT16                Protocol
1384   );
1385
1386
1387 /**
1388   Find the UNDI/SNP handle from controller and protocol GUID.
1389
1390   If ProtocolGuid is NULL, then ASSERT().
1391
1392   For example, IP will open an MNP child to transmit/receive
1393   packets. When MNP is stopped, IP should also be stopped. IP
1394   needs to find its own private data that is related the IP's
1395   service binding instance that is installed on the UNDI/SNP handle.
1396   The controller is then either an MNP or an ARP child handle. Note that
1397   IP opens these handles using BY_DRIVER. Use that information to get the
1398   UNDI/SNP handle.
1399
1400   @param[in]  Controller            The protocol handle to check.
1401   @param[in]  ProtocolGuid          The protocol that is related with the handle.
1402
1403   @return The UNDI/SNP handle or NULL for errors.
1404
1405 **/
1406 EFI_HANDLE
1407 EFIAPI
1408 NetLibGetNicHandle (
1409   IN EFI_HANDLE             Controller,
1410   IN EFI_GUID               *ProtocolGuid
1411   );
1412
1413 /**
1414   This is the default unload handle for all the network drivers.
1415
1416   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1417   Uninstall all the protocols installed in the driver entry point.
1418
1419   @param[in]  ImageHandle       The drivers' driver image.
1420
1421   @retval EFI_SUCCESS           The image is unloaded.
1422   @retval Others                Failed to unload the image.
1423
1424 **/
1425 EFI_STATUS
1426 EFIAPI
1427 NetLibDefaultUnload (
1428   IN EFI_HANDLE             ImageHandle
1429   );
1430
1431 /**
1432   Convert one Null-terminated ASCII string (decimal dotted) to EFI_IPv4_ADDRESS.
1433
1434   @param[in]      String         The pointer to the Ascii string.
1435   @param[out]     Ip4Address     The pointer to the converted IPv4 address.
1436
1437   @retval EFI_SUCCESS            Converted to an IPv4 address successfully.
1438   @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip4Address is NULL.
1439
1440 **/
1441 EFI_STATUS
1442 EFIAPI
1443 NetLibAsciiStrToIp4 (
1444   IN CONST CHAR8                 *String,
1445   OUT      EFI_IPv4_ADDRESS      *Ip4Address
1446   );
1447
1448 /**
1449   Convert one Null-terminated ASCII string to EFI_IPv6_ADDRESS. The format of the
1450   string is defined in RFC 4291 - Text Representation of Addresses.
1451
1452   @param[in]      String         The pointer to the Ascii string.
1453   @param[out]     Ip6Address     The pointer to the converted IPv6 address.
1454
1455   @retval EFI_SUCCESS            Converted to an IPv6 address successfully.
1456   @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip6Address is NULL.
1457
1458 **/
1459 EFI_STATUS
1460 EFIAPI
1461 NetLibAsciiStrToIp6 (
1462   IN CONST CHAR8                 *String,
1463   OUT      EFI_IPv6_ADDRESS      *Ip6Address
1464   );
1465
1466 /**
1467   Convert one Null-terminated Unicode string (decimal dotted) to EFI_IPv4_ADDRESS.
1468
1469   @param[in]      String         The pointer to the Ascii string.
1470   @param[out]     Ip4Address     The pointer to the converted IPv4 address.
1471
1472   @retval EFI_SUCCESS            Converted to an IPv4 address successfully.
1473   @retval EFI_INVALID_PARAMETER  The string is mal-formatted or Ip4Address is NULL.
1474
1475 **/
1476 EFI_STATUS
1477 EFIAPI
1478 NetLibStrToIp4 (
1479   IN CONST CHAR16                *String,
1480   OUT      EFI_IPv4_ADDRESS      *Ip4Address
1481   );
1482
1483 /**
1484   Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS.  The format of
1485   the string is defined in RFC 4291 - Text Representation of Addresses.
1486
1487   @param[in]      String         The pointer to the Ascii string.
1488   @param[out]     Ip6Address     The pointer to the converted IPv6 address.
1489
1490   @retval EFI_SUCCESS            Converted to an IPv6 address successfully.
1491   @retval EFI_INVALID_PARAMETER  The string is malformatted or Ip6Address is NULL.
1492
1493 **/
1494 EFI_STATUS
1495 EFIAPI
1496 NetLibStrToIp6 (
1497   IN CONST CHAR16                *String,
1498   OUT      EFI_IPv6_ADDRESS      *Ip6Address
1499   );
1500
1501 /**
1502   Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS and prefix length.
1503   The format of the string is defined in RFC 4291 - Text Representation of Addresses
1504   Prefixes: ipv6-address/prefix-length.
1505
1506   @param[in]      String         The pointer to the Ascii string.
1507   @param[out]     Ip6Address     The pointer to the converted IPv6 address.
1508   @param[out]     PrefixLength   The pointer to the converted prefix length.
1509
1510   @retval EFI_SUCCESS            Converted to an  IPv6 address successfully.
1511   @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip6Address is NULL.
1512
1513 **/
1514 EFI_STATUS
1515 EFIAPI
1516 NetLibStrToIp6andPrefix (
1517   IN CONST CHAR16                *String,
1518   OUT      EFI_IPv6_ADDRESS      *Ip6Address,
1519   OUT      UINT8                 *PrefixLength
1520   );
1521
1522 /**
1523
1524   Convert one EFI_IPv6_ADDRESS to Null-terminated Unicode string.
1525   The text representation of address is defined in RFC 4291.
1526
1527   @param[in]       Ip6Address     The pointer to the IPv6 address.
1528   @param[out]      String         The buffer to return the converted string.
1529   @param[in]       StringSize     The length in bytes of the input String.
1530
1531   @retval EFI_SUCCESS             Convert to string successfully.
1532   @retval EFI_INVALID_PARAMETER   The input parameter is invalid.
1533   @retval EFI_BUFFER_TOO_SMALL    The BufferSize is too small for the result. BufferSize has been
1534                                   updated with the size needed to complete the request.
1535 **/
1536 EFI_STATUS
1537 EFIAPI
1538 NetLibIp6ToStr (
1539   IN         EFI_IPv6_ADDRESS      *Ip6Address,
1540   OUT        CHAR16                *String,
1541   IN         UINTN                 StringSize
1542   );
1543
1544 //
1545 // Various signatures
1546 //
1547 #define  NET_BUF_SIGNATURE    SIGNATURE_32 ('n', 'b', 'u', 'f')
1548 #define  NET_VECTOR_SIGNATURE SIGNATURE_32 ('n', 'v', 'e', 'c')
1549 #define  NET_QUE_SIGNATURE    SIGNATURE_32 ('n', 'b', 'q', 'u')
1550
1551
1552 #define  NET_PROTO_DATA       64   // Opaque buffer for protocols
1553 #define  NET_BUF_HEAD         1    // Trim or allocate space from head
1554 #define  NET_BUF_TAIL         0    // Trim or allocate space from tail
1555 #define  NET_VECTOR_OWN_FIRST 0x01  // We allocated the 1st block in the vector
1556
1557 #define NET_CHECK_SIGNATURE(PData, SIGNATURE) \
1558   ASSERT (((PData) != NULL) && ((PData)->Signature == (SIGNATURE)))
1559
1560 //
1561 // Single memory block in the vector.
1562 //
1563 typedef struct {
1564   UINT32              Len;        // The block's length
1565   UINT8               *Bulk;      // The block's Data
1566 } NET_BLOCK;
1567
1568 typedef VOID (EFIAPI *NET_VECTOR_EXT_FREE) (VOID *Arg);
1569
1570 //
1571 //NET_VECTOR contains several blocks to hold all packet's
1572 //fragments and other house-keeping stuff for sharing. It
1573 //doesn't specify the where actual packet fragment begins.
1574 //
1575 typedef struct {
1576   UINT32              Signature;
1577   INTN                RefCnt;  // Reference count to share NET_VECTOR.
1578   NET_VECTOR_EXT_FREE Free;    // external function to free NET_VECTOR
1579   VOID                *Arg;    // opaque argument to Free
1580   UINT32              Flag;    // Flags, NET_VECTOR_OWN_FIRST
1581   UINT32              Len;     // Total length of the associated BLOCKs
1582
1583   UINT32              BlockNum;
1584   NET_BLOCK           Block[1];
1585 } NET_VECTOR;
1586
1587 //
1588 //NET_BLOCK_OP operates on the NET_BLOCK. It specifies
1589 //where the actual fragment begins and ends
1590 //
1591 typedef struct {
1592   UINT8               *BlockHead;   // Block's head, or the smallest valid Head
1593   UINT8               *BlockTail;   // Block's tail. BlockTail-BlockHead=block length
1594   UINT8               *Head;        // 1st byte of the data in the block
1595   UINT8               *Tail;        // Tail of the data in the block, Tail-Head=Size
1596   UINT32              Size;         // The size of the data
1597 } NET_BLOCK_OP;
1598
1599 typedef union {
1600   IP4_HEAD          *Ip4;
1601   EFI_IP6_HEADER    *Ip6;
1602 } NET_IP_HEAD;
1603
1604 //
1605 //NET_BUF is the buffer manage structure used by the
1606 //network stack. Every network packet may be fragmented. The Vector points to
1607 //memory blocks used by each fragment, and BlockOp
1608 //specifies where each fragment begins and ends.
1609 //
1610 //It also contains an opaque area for the protocol to store
1611 //per-packet information. Protocol must be careful not
1612 //to overwrite the members after that.
1613 //
1614 typedef struct {
1615   UINT32         Signature;
1616   INTN           RefCnt;
1617   LIST_ENTRY     List;                       // The List this NET_BUF is on
1618
1619   NET_IP_HEAD    Ip;                         // Network layer header, for fast access
1620   TCP_HEAD       *Tcp;                       // Transport layer header, for fast access
1621   EFI_UDP_HEADER *Udp;                       // User Datagram Protocol header
1622   UINT8          ProtoData [NET_PROTO_DATA]; //Protocol specific data
1623
1624   NET_VECTOR     *Vector;                    // The vector containing the packet
1625
1626   UINT32         BlockOpNum;                 // Total number of BlockOp in the buffer
1627   UINT32         TotalSize;                  // Total size of the actual packet
1628   NET_BLOCK_OP   BlockOp[1];                 // Specify the position of actual packet
1629 } NET_BUF;
1630
1631 //
1632 //A queue of NET_BUFs. It is a thin extension of
1633 //NET_BUF functions.
1634 //
1635 typedef struct {
1636   UINT32              Signature;
1637   INTN                RefCnt;
1638   LIST_ENTRY          List;       // The List this buffer queue is on
1639
1640   LIST_ENTRY          BufList;    // list of queued buffers
1641   UINT32              BufSize;    // total length of DATA in the buffers
1642   UINT32              BufNum;     // total number of buffers on the chain
1643 } NET_BUF_QUEUE;
1644
1645 //
1646 // Pseudo header for TCP and UDP checksum
1647 //
1648 #pragma pack(1)
1649 typedef struct {
1650   IP4_ADDR            SrcIp;
1651   IP4_ADDR            DstIp;
1652   UINT8               Reserved;
1653   UINT8               Protocol;
1654   UINT16              Len;
1655 } NET_PSEUDO_HDR;
1656
1657 typedef struct {
1658   EFI_IPv6_ADDRESS    SrcIp;
1659   EFI_IPv6_ADDRESS    DstIp;
1660   UINT32              Len;
1661   UINT32              Reserved:24;
1662   UINT32              NextHeader:8;
1663 } NET_IP6_PSEUDO_HDR;
1664 #pragma pack()
1665
1666 //
1667 // The fragment entry table used in network interfaces. This is
1668 // the same as NET_BLOCK now. Use two different to distinguish
1669 // the two in case that NET_BLOCK be enhanced later.
1670 //
1671 typedef struct {
1672   UINT32              Len;
1673   UINT8               *Bulk;
1674 } NET_FRAGMENT;
1675
1676 #define NET_GET_REF(PData)      ((PData)->RefCnt++)
1677 #define NET_PUT_REF(PData)      ((PData)->RefCnt--)
1678 #define NETBUF_FROM_PROTODATA(Info) BASE_CR((Info), NET_BUF, ProtoData)
1679
1680 #define NET_BUF_SHARED(Buf) \
1681   (((Buf)->RefCnt > 1) || ((Buf)->Vector->RefCnt > 1))
1682
1683 #define NET_VECTOR_SIZE(BlockNum) \
1684   (sizeof (NET_VECTOR) + ((BlockNum) - 1) * sizeof (NET_BLOCK))
1685
1686 #define NET_BUF_SIZE(BlockOpNum)  \
1687   (sizeof (NET_BUF) + ((BlockOpNum) - 1) * sizeof (NET_BLOCK_OP))
1688
1689 #define NET_HEADSPACE(BlockOp)  \
1690   ((UINTN)((BlockOp)->Head) - (UINTN)((BlockOp)->BlockHead))
1691
1692 #define NET_TAILSPACE(BlockOp)  \
1693   ((UINTN)((BlockOp)->BlockTail) - (UINTN)((BlockOp)->Tail))
1694
1695 /**
1696   Allocate a single block NET_BUF. Upon allocation, all the
1697   free space is in the tail room.
1698
1699   @param[in]  Len              The length of the block.
1700
1701   @return                      The pointer to the allocated NET_BUF, or NULL if the
1702                                allocation failed due to resource limitations.
1703
1704 **/
1705 NET_BUF  *
1706 EFIAPI
1707 NetbufAlloc (
1708   IN UINT32                 Len
1709   );
1710
1711 /**
1712   Free the net buffer and its associated NET_VECTOR.
1713
1714   Decrease the reference count of the net buffer by one. Free the associated net
1715   vector and itself if the reference count of the net buffer is decreased to 0.
1716   The net vector free operation decreases the reference count of the net
1717   vector by one, and performs the resource free operation when the reference count
1718   of the net vector is 0.
1719
1720   @param[in]  Nbuf                  The pointer to the NET_BUF to be freed.
1721
1722 **/
1723 VOID
1724 EFIAPI
1725 NetbufFree (
1726   IN NET_BUF                *Nbuf
1727   );
1728
1729 /**
1730   Get the index of NET_BLOCK_OP that contains the byte at Offset in the net
1731   buffer.
1732
1733   For example, this function can be used to retrieve the IP header in the packet. It
1734   also can be used to get the fragment that contains the byte used
1735   mainly by the library implementation itself.
1736
1737   @param[in]   Nbuf      The pointer to the net buffer.
1738   @param[in]   Offset    The offset of the byte.
1739   @param[out]  Index     Index of the NET_BLOCK_OP that contains the byte at
1740                          Offset.
1741
1742   @return       The pointer to the Offset'th byte of data in the net buffer, or NULL
1743                 if there is no such data in the net buffer.
1744
1745 **/
1746 UINT8  *
1747 EFIAPI
1748 NetbufGetByte (
1749   IN  NET_BUF               *Nbuf,
1750   IN  UINT32                Offset,
1751   OUT UINT32                *Index  OPTIONAL
1752   );
1753
1754 /**
1755   Create a copy of the net buffer that shares the associated net vector.
1756
1757   The reference count of the newly created net buffer is set to 1. The reference
1758   count of the associated net vector is increased by one.
1759
1760   @param[in]  Nbuf              The pointer to the net buffer to be cloned.
1761
1762   @return                       The pointer to the cloned net buffer, or NULL if the
1763                                 allocation failed due to resource limitations.
1764
1765 **/
1766 NET_BUF *
1767 EFIAPI
1768 NetbufClone (
1769   IN NET_BUF                *Nbuf
1770   );
1771
1772 /**
1773   Create a duplicated copy of the net buffer with data copied and HeadSpace
1774   bytes of head space reserved.
1775
1776   The duplicated net buffer will allocate its own memory to hold the data of the
1777   source net buffer.
1778
1779   @param[in]       Nbuf         The pointer to the net buffer to be duplicated from.
1780   @param[in, out]  Duplicate    The pointer to the net buffer to duplicate to. If
1781                                 NULL, a new net buffer is allocated.
1782   @param[in]      HeadSpace     The length of the head space to reserve.
1783
1784   @return                       The pointer to the duplicated net buffer, or NULL if
1785                                 the allocation failed due to resource limitations.
1786
1787 **/
1788 NET_BUF  *
1789 EFIAPI
1790 NetbufDuplicate (
1791   IN NET_BUF                *Nbuf,
1792   IN OUT NET_BUF            *Duplicate        OPTIONAL,
1793   IN UINT32                 HeadSpace
1794   );
1795
1796 /**
1797   Create a NET_BUF structure which contains Len byte data of Nbuf starting from
1798   Offset.
1799
1800   A new NET_BUF structure will be created but the associated data in NET_VECTOR
1801   is shared. This function exists to perform IP packet fragmentation.
1802
1803   @param[in]  Nbuf         The pointer to the net buffer to be extracted.
1804   @param[in]  Offset       Starting point of the data to be included in the new
1805                            net buffer.
1806   @param[in]  Len          The bytes of data to be included in the new net buffer.
1807   @param[in]  HeadSpace    The bytes of the head space to reserve for the protocol header.
1808
1809   @return                  The pointer to the cloned net buffer, or NULL if the
1810                            allocation failed due to resource limitations.
1811
1812 **/
1813 NET_BUF  *
1814 EFIAPI
1815 NetbufGetFragment (
1816   IN NET_BUF                *Nbuf,
1817   IN UINT32                 Offset,
1818   IN UINT32                 Len,
1819   IN UINT32                 HeadSpace
1820   );
1821
1822 /**
1823   Reserve some space in the header room of the net buffer.
1824
1825   Upon allocation, all the space is in the tail room of the buffer. Call this
1826   function to move space to the header room. This function is quite limited
1827   in that it can only reserve space from the first block of an empty NET_BUF not
1828   built from the external. However, it should be enough for the network stack.
1829
1830   @param[in, out]  Nbuf     The pointer to the net buffer.
1831   @param[in]       Len      The length of buffer to be reserved from the header.
1832
1833 **/
1834 VOID
1835 EFIAPI
1836 NetbufReserve (
1837   IN OUT NET_BUF            *Nbuf,
1838   IN UINT32                 Len
1839   );
1840
1841 /**
1842   Allocate Len bytes of space from the header or tail of the buffer.
1843
1844   @param[in, out]  Nbuf       The pointer to the net buffer.
1845   @param[in]       Len        The length of the buffer to be allocated.
1846   @param[in]       FromHead   The flag to indicate whether to reserve the data
1847                               from head (TRUE) or tail (FALSE).
1848
1849   @return                     The pointer to the first byte of the allocated buffer,
1850                               or NULL, if there is no sufficient space.
1851
1852 **/
1853 UINT8*
1854 EFIAPI
1855 NetbufAllocSpace (
1856   IN OUT NET_BUF            *Nbuf,
1857   IN UINT32                 Len,
1858   IN BOOLEAN                FromHead
1859   );
1860
1861 /**
1862   Trim Len bytes from the header or the tail of the net buffer.
1863
1864   @param[in, out]  Nbuf         The pointer to the net buffer.
1865   @param[in]       Len          The length of the data to be trimmed.
1866   @param[in]      FromHead      The flag to indicate whether trim data is from the
1867                                 head (TRUE) or the tail (FALSE).
1868
1869   @return    The length of the actual trimmed data, which may be less
1870              than Len if the TotalSize of Nbuf is less than Len.
1871
1872 **/
1873 UINT32
1874 EFIAPI
1875 NetbufTrim (
1876   IN OUT NET_BUF            *Nbuf,
1877   IN UINT32                 Len,
1878   IN BOOLEAN                FromHead
1879   );
1880
1881 /**
1882   Copy Len bytes of data from the specific offset of the net buffer to the
1883   destination memory.
1884
1885   The Len bytes of data may cross several fragments of the net buffer.
1886
1887   @param[in]   Nbuf         The pointer to the net buffer.
1888   @param[in]   Offset       The sequence number of the first byte to copy.
1889   @param[in]   Len          The length of the data to copy.
1890   @param[in]   Dest         The destination of the data to copy to.
1891
1892   @return           The length of the actual copied data, or 0 if the offset
1893                     specified exceeds the total size of net buffer.
1894
1895 **/
1896 UINT32
1897 EFIAPI
1898 NetbufCopy (
1899   IN NET_BUF                *Nbuf,
1900   IN UINT32                 Offset,
1901   IN UINT32                 Len,
1902   IN UINT8                  *Dest
1903   );
1904
1905 /**
1906   Build a NET_BUF from external blocks.
1907
1908   A new NET_BUF structure will be created from external blocks. An additional block
1909   of memory will be allocated to hold reserved HeadSpace bytes of header room
1910   and existing HeadLen bytes of header, but the external blocks are shared by the
1911   net buffer to avoid data copying.
1912
1913   @param[in]  ExtFragment           The pointer to the data block.
1914   @param[in]  ExtNum                The number of the data blocks.
1915   @param[in]  HeadSpace             The head space to be reserved.
1916   @param[in]  HeadLen               The length of the protocol header. The function
1917                                     pulls this amount of data into a linear block.
1918   @param[in]  ExtFree               The pointer to the caller-provided free function.
1919   @param[in]  Arg                   The argument passed to ExtFree when ExtFree is
1920                                     called.
1921
1922   @return                  The pointer to the net buffer built from the data blocks,
1923                            or NULL if the allocation failed due to resource
1924                            limit.
1925
1926 **/
1927 NET_BUF  *
1928 EFIAPI
1929 NetbufFromExt (
1930   IN NET_FRAGMENT           *ExtFragment,
1931   IN UINT32                 ExtNum,
1932   IN UINT32                 HeadSpace,
1933   IN UINT32                 HeadLen,
1934   IN NET_VECTOR_EXT_FREE    ExtFree,
1935   IN VOID                   *Arg          OPTIONAL
1936   );
1937
1938 /**
1939   Build a fragment table to contain the fragments in the net buffer. This is the
1940   opposite operation of the NetbufFromExt.
1941
1942   @param[in]       Nbuf                  Points to the net buffer.
1943   @param[in, out]  ExtFragment           The pointer to the data block.
1944   @param[in, out]  ExtNum                The number of the data blocks.
1945
1946   @retval EFI_BUFFER_TOO_SMALL  The number of non-empty blocks is bigger than
1947                                 ExtNum.
1948   @retval EFI_SUCCESS           The fragment table was built successfully.
1949
1950 **/
1951 EFI_STATUS
1952 EFIAPI
1953 NetbufBuildExt (
1954   IN NET_BUF                *Nbuf,
1955   IN OUT NET_FRAGMENT       *ExtFragment,
1956   IN OUT UINT32             *ExtNum
1957   );
1958
1959 /**
1960   Build a net buffer from a list of net buffers.
1961
1962   All the fragments will be collected from the list of NEW_BUF, and then a new
1963   net buffer will be created through NetbufFromExt.
1964
1965   @param[in]   BufList    A List of the net buffer.
1966   @param[in]   HeadSpace  The head space to be reserved.
1967   @param[in]   HeaderLen  The length of the protocol header. The function
1968                           pulls this amount of data into a linear block.
1969   @param[in]   ExtFree    The pointer to the caller provided free function.
1970   @param[in]   Arg        The argument passed to ExtFree when ExtFree is called.
1971
1972   @return                 The pointer to the net buffer built from the list of net
1973                           buffers.
1974
1975 **/
1976 NET_BUF  *
1977 EFIAPI
1978 NetbufFromBufList (
1979   IN LIST_ENTRY             *BufList,
1980   IN UINT32                 HeadSpace,
1981   IN UINT32                 HeaderLen,
1982   IN NET_VECTOR_EXT_FREE    ExtFree,
1983   IN VOID                   *Arg              OPTIONAL
1984   );
1985
1986 /**
1987   Free a list of net buffers.
1988
1989   @param[in, out]  Head              The pointer to the head of linked net buffers.
1990
1991 **/
1992 VOID
1993 EFIAPI
1994 NetbufFreeList (
1995   IN OUT LIST_ENTRY         *Head
1996   );
1997
1998 /**
1999   Initiate the net buffer queue.
2000
2001   @param[in, out]  NbufQue   The pointer to the net buffer queue to be initialized.
2002
2003 **/
2004 VOID
2005 EFIAPI
2006 NetbufQueInit (
2007   IN OUT NET_BUF_QUEUE          *NbufQue
2008   );
2009
2010 /**
2011   Allocate and initialize a net buffer queue.
2012
2013   @return         The pointer to the allocated net buffer queue, or NULL if the
2014                   allocation failed due to resource limit.
2015
2016 **/
2017 NET_BUF_QUEUE  *
2018 EFIAPI
2019 NetbufQueAlloc (
2020   VOID
2021   );
2022
2023 /**
2024   Free a net buffer queue.
2025
2026   Decrease the reference count of the net buffer queue by one. The real resource
2027   free operation isn't performed until the reference count of the net buffer
2028   queue is decreased to 0.
2029
2030   @param[in]  NbufQue               The pointer to the net buffer queue to be freed.
2031
2032 **/
2033 VOID
2034 EFIAPI
2035 NetbufQueFree (
2036   IN NET_BUF_QUEUE          *NbufQue
2037   );
2038
2039 /**
2040   Remove a net buffer from the head in the specific queue and return it.
2041
2042   @param[in, out]  NbufQue               The pointer to the net buffer queue.
2043
2044   @return           The pointer to the net buffer removed from the specific queue,
2045                     or NULL if there is no net buffer in the specific queue.
2046
2047 **/
2048 NET_BUF  *
2049 EFIAPI
2050 NetbufQueRemove (
2051   IN OUT NET_BUF_QUEUE          *NbufQue
2052   );
2053
2054 /**
2055   Append a net buffer to the net buffer queue.
2056
2057   @param[in, out]  NbufQue            The pointer to the net buffer queue.
2058   @param[in, out]  Nbuf               The pointer to the net buffer to be appended.
2059
2060 **/
2061 VOID
2062 EFIAPI
2063 NetbufQueAppend (
2064   IN OUT NET_BUF_QUEUE          *NbufQue,
2065   IN OUT NET_BUF                *Nbuf
2066   );
2067
2068 /**
2069   Copy Len bytes of data from the net buffer queue at the specific offset to the
2070   destination memory.
2071
2072   The copying operation is the same as NetbufCopy, but applies to the net buffer
2073   queue instead of the net buffer.
2074
2075   @param[in]   NbufQue         The pointer to the net buffer queue.
2076   @param[in]   Offset          The sequence number of the first byte to copy.
2077   @param[in]   Len             The length of the data to copy.
2078   @param[out]  Dest            The destination of the data to copy to.
2079
2080   @return       The length of the actual copied data, or 0 if the offset
2081                 specified exceeds the total size of net buffer queue.
2082
2083 **/
2084 UINT32
2085 EFIAPI
2086 NetbufQueCopy (
2087   IN NET_BUF_QUEUE          *NbufQue,
2088   IN UINT32                 Offset,
2089   IN UINT32                 Len,
2090   OUT UINT8                 *Dest
2091   );
2092
2093 /**
2094   Trim Len bytes of data from the buffer queue and free any net buffer
2095   that is completely trimmed.
2096
2097   The trimming operation is the same as NetbufTrim but applies to the net buffer
2098   queue instead of the net buffer.
2099
2100   @param[in, out]  NbufQue               The pointer to the net buffer queue.
2101   @param[in]       Len                   The length of the data to trim.
2102
2103   @return   The actual length of the data trimmed.
2104
2105 **/
2106 UINT32
2107 EFIAPI
2108 NetbufQueTrim (
2109   IN OUT NET_BUF_QUEUE      *NbufQue,
2110   IN UINT32                 Len
2111   );
2112
2113
2114 /**
2115   Flush the net buffer queue.
2116
2117   @param[in, out]  NbufQue               The pointer to the queue to be flushed.
2118
2119 **/
2120 VOID
2121 EFIAPI
2122 NetbufQueFlush (
2123   IN OUT NET_BUF_QUEUE          *NbufQue
2124   );
2125
2126 /**
2127   Compute the checksum for a bulk of data.
2128
2129   @param[in]   Bulk                  The pointer to the data.
2130   @param[in]   Len                   The length of the data, in bytes.
2131
2132   @return    The computed checksum.
2133
2134 **/
2135 UINT16
2136 EFIAPI
2137 NetblockChecksum (
2138   IN UINT8                  *Bulk,
2139   IN UINT32                 Len
2140   );
2141
2142 /**
2143   Add two checksums.
2144
2145   @param[in]   Checksum1             The first checksum to be added.
2146   @param[in]   Checksum2             The second checksum to be added.
2147
2148   @return         The new checksum.
2149
2150 **/
2151 UINT16
2152 EFIAPI
2153 NetAddChecksum (
2154   IN UINT16                 Checksum1,
2155   IN UINT16                 Checksum2
2156   );
2157
2158 /**
2159   Compute the checksum for a NET_BUF.
2160
2161   @param[in]   Nbuf                  The pointer to the net buffer.
2162
2163   @return    The computed checksum.
2164
2165 **/
2166 UINT16
2167 EFIAPI
2168 NetbufChecksum (
2169   IN NET_BUF                *Nbuf
2170   );
2171
2172 /**
2173   Compute the checksum for TCP/UDP pseudo header.
2174
2175   Src and Dst are in network byte order, and Len is in host byte order.
2176
2177   @param[in]   Src                   The source address of the packet.
2178   @param[in]   Dst                   The destination address of the packet.
2179   @param[in]   Proto                 The protocol type of the packet.
2180   @param[in]   Len                   The length of the packet.
2181
2182   @return   The computed checksum.
2183
2184 **/
2185 UINT16
2186 EFIAPI
2187 NetPseudoHeadChecksum (
2188   IN IP4_ADDR               Src,
2189   IN IP4_ADDR               Dst,
2190   IN UINT8                  Proto,
2191   IN UINT16                 Len
2192   );
2193
2194 /**
2195   Compute the checksum for the TCP6/UDP6 pseudo header.
2196
2197   Src and Dst are in network byte order, and Len is in host byte order.
2198
2199   @param[in]   Src                   The source address of the packet.
2200   @param[in]   Dst                   The destination address of the packet.
2201   @param[in]   NextHeader            The protocol type of the packet.
2202   @param[in]   Len                   The length of the packet.
2203
2204   @return   The computed checksum.
2205
2206 **/
2207 UINT16
2208 EFIAPI
2209 NetIp6PseudoHeadChecksum (
2210   IN EFI_IPv6_ADDRESS       *Src,
2211   IN EFI_IPv6_ADDRESS       *Dst,
2212   IN UINT8                  NextHeader,
2213   IN UINT32                 Len
2214   );
2215
2216 /**
2217   The function frees the net buffer which allocated by the IP protocol. It releases
2218   only the net buffer and doesn't call the external free function.
2219
2220   This function should be called after finishing the process of mIpSec->ProcessExt()
2221   for outbound traffic. The (EFI_IPSEC2_PROTOCOL)->ProcessExt() allocates a new
2222   buffer for the ESP, so there needs a function to free the old net buffer.
2223
2224   @param[in]  Nbuf       The network buffer to be freed.
2225
2226 **/
2227 VOID
2228 NetIpSecNetbufFree (
2229   NET_BUF   *Nbuf
2230   );
2231
2232 /**
2233   This function obtains the system guid from the smbios table.
2234
2235   If SystemGuid is NULL, then ASSERT().
2236
2237   @param[out]  SystemGuid     The pointer of the returned system guid.
2238
2239   @retval EFI_SUCCESS         Successfully obtained the system guid.
2240   @retval EFI_NOT_FOUND       Did not find the SMBIOS table.
2241
2242 **/
2243 EFI_STATUS
2244 EFIAPI
2245 NetLibGetSystemGuid (
2246   OUT EFI_GUID              *SystemGuid
2247   );
2248
2249 /**
2250   Create Dns QName according the queried domain name.
2251
2252   If DomainName is NULL, then ASSERT().
2253
2254   QName is a domain name represented as a sequence of labels,
2255   where each label consists of a length octet followed by that
2256   number of octets. The QName terminates with the zero
2257   length octet for the null label of the root. Caller should
2258   take responsibility to free the buffer in returned pointer.
2259
2260   @param  DomainName    The pointer to the queried domain name string.
2261
2262   @retval NULL          Failed to fill QName.
2263   @return               QName filled successfully.
2264
2265 **/
2266 CHAR8 *
2267 EFIAPI
2268 NetLibCreateDnsQName (
2269   IN  CHAR16              *DomainName
2270   );
2271
2272 #endif