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