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