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