Remove #include <Protocol/LoadedImage.h>
[mirror_edk2.git] / MdeModulePkg / Include / Library / NetLib.h
CommitLineData
97b38d4e 1/** @file\r
2 This library provides basic function for UEFI network stack.\r
3\r
4Copyright (c) 2005 - 2008, Intel Corporation\r
5All rights reserved. This program and the accompanying materials\r
6are licensed and made available under the terms and conditions of the BSD License\r
7which accompanies this distribution. The full text of the license may be found at\r
8http://opensource.org/licenses/bsd-license.php\r
9\r
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
12\r
13**/\r
14\r
15#ifndef _NET_LIB_H_\r
16#define _NET_LIB_H_\r
17\r
18#include <Library/BaseMemoryLib.h>\r
19#include <Library/MemoryAllocationLib.h>\r
20#include <Protocol/DriverBinding.h>\r
21#include <Protocol/ComponentName.h>\r
22#include <Protocol/DriverConfiguration.h>\r
23#include <Protocol/DriverDiagnostics.h>\r
24#include <Protocol/Dpc.h>\r
25\r
26typedef UINT32 IP4_ADDR;\r
27typedef UINT32 TCP_SEQNO;\r
28typedef UINT16 TCP_PORTNO;\r
29\r
30typedef enum {\r
31 NET_ETHER_ADDR_LEN = 6,\r
32 NET_IFTYPE_ETHERNET = 0x01,\r
33\r
34 EFI_IP_PROTO_UDP = 0x11,\r
35 EFI_IP_PROTO_TCP = 0x06,\r
36 EFI_IP_PROTO_ICMP = 0x01,\r
37\r
38 //\r
d7db0902 39 // The address classification\r
97b38d4e 40 //\r
41 IP4_ADDR_CLASSA = 1,\r
42 IP4_ADDR_CLASSB,\r
43 IP4_ADDR_CLASSC,\r
44 IP4_ADDR_CLASSD,\r
45 IP4_ADDR_CLASSE,\r
46\r
47 IP4_MASK_NUM = 33\r
48} IP4_CLASS_TYPE;\r
49\r
50#pragma pack(1)\r
51\r
52//\r
53// Ethernet head definition\r
54//\r
55typedef struct {\r
56 UINT8 DstMac [NET_ETHER_ADDR_LEN];\r
57 UINT8 SrcMac [NET_ETHER_ADDR_LEN];\r
58 UINT16 EtherType;\r
59} ETHER_HEAD;\r
60\r
61\r
62//\r
63// The EFI_IP4_HEADER is hard to use because the source and\r
64// destination address are defined as EFI_IPv4_ADDRESS, which\r
65// is a structure. Two structures can't be compared or masked\r
66// directly. This is why there is an internal representation.\r
67//\r
68typedef struct {\r
69 UINT8 HeadLen : 4;\r
70 UINT8 Ver : 4;\r
71 UINT8 Tos;\r
72 UINT16 TotalLen;\r
73 UINT16 Id;\r
74 UINT16 Fragment;\r
75 UINT8 Ttl;\r
76 UINT8 Protocol;\r
77 UINT16 Checksum;\r
78 IP4_ADDR Src;\r
79 IP4_ADDR Dst;\r
80} IP4_HEAD;\r
81\r
82\r
83//\r
84// ICMP head definition. ICMP message is categoried as either an error\r
85// message or query message. Two message types have their own head format.\r
86//\r
87typedef struct {\r
88 UINT8 Type;\r
89 UINT8 Code;\r
90 UINT16 Checksum;\r
91} IP4_ICMP_HEAD;\r
92\r
93typedef struct {\r
94 IP4_ICMP_HEAD Head;\r
95 UINT32 Fourth; // 4th filed of the head, it depends on Type.\r
96 IP4_HEAD IpHead;\r
97} IP4_ICMP_ERROR_HEAD;\r
98\r
99typedef struct {\r
100 IP4_ICMP_HEAD Head;\r
101 UINT16 Id;\r
102 UINT16 Seq;\r
103} IP4_ICMP_QUERY_HEAD;\r
104\r
105\r
106//\r
107// UDP header definition\r
108//\r
109typedef struct {\r
110 UINT16 SrcPort;\r
111 UINT16 DstPort;\r
112 UINT16 Length;\r
113 UINT16 Checksum;\r
114} EFI_UDP4_HEADER;\r
115\r
116\r
117//\r
118// TCP header definition\r
119//\r
120typedef struct {\r
121 TCP_PORTNO SrcPort;\r
122 TCP_PORTNO DstPort;\r
123 TCP_SEQNO Seq;\r
124 TCP_SEQNO Ack;\r
125 UINT8 Res : 4;\r
126 UINT8 HeadLen : 4;\r
127 UINT8 Flag;\r
128 UINT16 Wnd;\r
129 UINT16 Checksum;\r
130 UINT16 Urg;\r
131} TCP_HEAD;\r
132\r
133#pragma pack()\r
134\r
135#define NET_MAC_EQUAL(pMac1, pMac2, Len) \\r
136 (CompareMem ((pMac1), (pMac2), Len) == 0)\r
137\r
138#define NET_MAC_IS_MULTICAST(Mac, BMac, Len) \\r
139 (((*((UINT8 *) Mac) & 0x01) == 0x01) && (!NET_MAC_EQUAL (Mac, BMac, Len)))\r
140\r
141#define NTOHL(x) (UINT32)((((UINT32) (x) & 0xff) << 24) | \\r
142 (((UINT32) (x) & 0xff00) << 8) | \\r
143 (((UINT32) (x) & 0xff0000) >> 8) | \\r
144 (((UINT32) (x) & 0xff000000) >> 24))\r
145\r
146#define HTONL(x) NTOHL(x)\r
147\r
148#define NTOHS(x) (UINT16)((((UINT16) (x) & 0xff) << 8) | \\r
149 (((UINT16) (x) & 0xff00) >> 8))\r
150\r
151#define HTONS(x) NTOHS(x)\r
152\r
153//\r
154// Test the IP's attribute, All the IPs are in host byte order.\r
155//\r
156#define IP4_IS_MULTICAST(Ip) (((Ip) & 0xF0000000) == 0xE0000000)\r
157#define IP4_IS_LOCAL_BROADCAST(Ip) ((Ip) == 0xFFFFFFFF)\r
158#define IP4_NET_EQUAL(Ip1, Ip2, NetMask) (((Ip1) & (NetMask)) == ((Ip2) & (NetMask)))\r
159#define IP4_IS_VALID_NETMASK(Ip) (NetGetMaskLength (Ip) != IP4_MASK_NUM)\r
160\r
161//\r
162// Convert the EFI_IP4_ADDRESS to plain UINT32 IP4 address.\r
163//\r
164#define EFI_IP4(EfiIpAddr) (*(IP4_ADDR *) ((EfiIpAddr).Addr))\r
165#define EFI_NTOHL(EfiIp) (NTOHL (EFI_IP4 ((EfiIp))))\r
166#define EFI_IP4_EQUAL(Ip1, Ip2) (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv4_ADDRESS)) == 0)\r
167\r
168/**\r
169 Return the length of the mask. If the mask is invalid,\r
170 return the invalid length 33, which is IP4_MASK_NUM.\r
171 NetMask is in the host byte order.\r
172\r
173 @param NetMask The netmask to get the length from\r
174\r
175 @return The length of the netmask, IP4_MASK_NUM if the mask isn't\r
176 @return supported.\r
177\r
178**/\r
179INTN\r
180EFIAPI\r
181NetGetMaskLength (\r
182 IN IP4_ADDR Mask\r
183 );\r
184\r
185/**\r
186 Return the class of the address, such as class a, b, c.\r
187 Addr is in host byte order.\r
188\r
189 @param Addr The address to get the class from\r
190\r
191 @return IP address class, such as IP4_ADDR_CLASSA\r
192\r
193**/\r
194INTN\r
195EFIAPI\r
196NetGetIpClass (\r
197 IN IP4_ADDR Addr\r
198 );\r
199\r
200/**\r
201 Check whether the IP is a valid unicast address according to\r
202 the netmask. If NetMask is zero, use the IP address's class to\r
203 get the default mask.\r
204\r
205 @param Ip The IP to check againist\r
206 @param NetMask The mask of the IP\r
207\r
208 @return TRUE if IP is a valid unicast address on the network, otherwise FALSE\r
209\r
210**/\r
211BOOLEAN\r
212Ip4IsUnicast (\r
213 IN IP4_ADDR Ip,\r
214 IN IP4_ADDR NetMask\r
215 );\r
216\r
217extern IP4_ADDR gIp4AllMasks [IP4_MASK_NUM];\r
218\r
219\r
220extern EFI_IPv4_ADDRESS mZeroIp4Addr;\r
221\r
222#define NET_IS_DIGIT(Ch) (('0' <= (Ch)) && ((Ch) <= '9'))\r
223#define NET_ROUNDUP(size, unit) (((size) + (unit) - 1) & (~((unit) - 1)))\r
224#define NET_IS_LOWER_CASE_CHAR(Ch) (('a' <= (Ch)) && ((Ch) <= 'z'))\r
225#define NET_IS_UPPER_CASE_CHAR(Ch) (('A' <= (Ch)) && ((Ch) <= 'Z'))\r
226\r
227#define TICKS_PER_MS 10000U\r
228#define TICKS_PER_SECOND 10000000U\r
229\r
230#define NET_RANDOM(Seed) ((UINT32) ((UINT32) (Seed) * 1103515245UL + 12345) % 4294967295UL)\r
231\r
232/**\r
233 Extract a UINT32 from a byte stream, then convert it to host\r
234 byte order. Use this function to avoid alignment error.\r
235\r
236 @param Buf The buffer to extract the UINT32.\r
237\r
238 @return The UINT32 extracted.\r
239\r
240**/\r
241UINT32\r
242EFIAPI\r
243NetGetUint32 (\r
244 IN UINT8 *Buf\r
245 );\r
246\r
247/**\r
248 Put a UINT32 to the byte stream. Convert it from host byte order\r
249 to network byte order before putting.\r
250\r
251 @param Buf The buffer to put the UINT32\r
252 @param Data The data to put\r
253\r
254 @return None\r
255\r
256**/\r
257VOID\r
258EFIAPI\r
259NetPutUint32 (\r
260 IN UINT8 *Buf,\r
261 IN UINT32 Data\r
262 );\r
263\r
264/**\r
265 Initialize a random seed using current time.\r
266\r
267 None\r
268\r
269 @return The random seed initialized with current time.\r
270\r
271**/\r
272UINT32\r
273EFIAPI\r
274NetRandomInitSeed (\r
275 VOID\r
276 );\r
277\r
278\r
279#define NET_LIST_USER_STRUCT(Entry, Type, Field) \\r
50d7ebad 280 BASE_CR(Entry, Type, Field)\r
97b38d4e 281\r
282#define NET_LIST_USER_STRUCT_S(Entry, Type, Field, Sig) \\r
283 CR(Entry, Type, Field, Sig)\r
284\r
285//\r
286// Iterate through the doule linked list. It is NOT delete safe\r
287//\r
288#define NET_LIST_FOR_EACH(Entry, ListHead) \\r
289 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)\r
290\r
291//\r
292// Iterate through the doule linked list. This is delete-safe.\r
293// Don't touch NextEntry. Also, don't use this macro if list\r
294// entries other than the Entry may be deleted when processing\r
295// the current Entry.\r
296//\r
297#define NET_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \\r
298 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink; \\r
299 Entry != (ListHead); \\r
300 Entry = NextEntry, NextEntry = Entry->ForwardLink \\r
301 )\r
302\r
303//\r
304// Make sure the list isn't empty before get the frist/last record.\r
305//\r
306#define NET_LIST_HEAD(ListHead, Type, Field) \\r
307 NET_LIST_USER_STRUCT((ListHead)->ForwardLink, Type, Field)\r
308\r
309#define NET_LIST_TAIL(ListHead, Type, Field) \\r
310 NET_LIST_USER_STRUCT((ListHead)->BackLink, Type, Field)\r
311\r
312\r
313/**\r
314 Remove the first entry on the list\r
315\r
316 @param Head The list header\r
317\r
318 @return The entry that is removed from the list, NULL if the list is empty.\r
319\r
320**/\r
321LIST_ENTRY *\r
322EFIAPI\r
323NetListRemoveHead (\r
324 LIST_ENTRY *Head\r
325 );\r
326\r
327/**\r
328 Remove the last entry on the list\r
329\r
330 @param Head The list head\r
331\r
332 @return The entry that is removed from the list, NULL if the list is empty.\r
333\r
334**/\r
335LIST_ENTRY *\r
336EFIAPI\r
337NetListRemoveTail (\r
338 LIST_ENTRY *Head\r
339 );\r
340\r
341/**\r
342 Insert the NewEntry after the PrevEntry.\r
343\r
344 @param PrevEntry The previous entry to insert after\r
345 @param NewEntry The new entry to insert\r
346\r
347 @return None\r
348\r
349**/\r
350VOID\r
351EFIAPI\r
352NetListInsertAfter (\r
353 IN LIST_ENTRY *PrevEntry,\r
354 IN LIST_ENTRY *NewEntry\r
355 );\r
356\r
357/**\r
358 Insert the NewEntry before the PostEntry.\r
359\r
360 @param PostEntry The entry to insert before\r
361 @param NewEntry The new entry to insert\r
362\r
363 @return None\r
364\r
365**/\r
366VOID\r
367EFIAPI\r
368NetListInsertBefore (\r
369 IN LIST_ENTRY *PostEntry,\r
370 IN LIST_ENTRY *NewEntry\r
371 );\r
372\r
373\r
374//\r
375// Object container: EFI network stack spec defines various kinds of\r
376// tokens. The drivers can share code to manage those objects.\r
377//\r
378typedef struct {\r
379 LIST_ENTRY Link;\r
380 VOID *Key;\r
381 VOID *Value;\r
382} NET_MAP_ITEM;\r
383\r
384typedef struct {\r
385 LIST_ENTRY Used;\r
386 LIST_ENTRY Recycled;\r
387 UINTN Count;\r
388} NET_MAP;\r
389\r
390#define NET_MAP_INCREAMENT 64\r
391\r
392/**\r
393 Initialize the netmap. Netmap is a reposity to keep the <Key, Value> pairs.\r
394\r
395 @param Map The netmap to initialize\r
396\r
397 @return None\r
398\r
399**/\r
400VOID\r
401EFIAPI\r
402NetMapInit (\r
403 IN NET_MAP *Map\r
404 );\r
405\r
406/**\r
407 To clean up the netmap, that is, release allocated memories.\r
408\r
409 @param Map The netmap to clean up.\r
410\r
411 @return None\r
412\r
413**/\r
414VOID\r
415EFIAPI\r
416NetMapClean (\r
417 IN NET_MAP *Map\r
418 );\r
419\r
420/**\r
421 Test whether the netmap is empty\r
422\r
423 @param Map The net map to test\r
424\r
425 @return TRUE if the netmap is empty, otherwise FALSE.\r
426\r
427**/\r
428BOOLEAN\r
429EFIAPI\r
430NetMapIsEmpty (\r
431 IN NET_MAP *Map\r
432 );\r
433\r
434/**\r
435 Return the number of the <Key, Value> pairs in the netmap.\r
436\r
437 @param Map The netmap to get the entry number\r
438\r
439 @return The entry number in the netmap.\r
440\r
441**/\r
442UINTN\r
443EFIAPI\r
444NetMapGetCount (\r
445 IN NET_MAP *Map\r
446 );\r
447\r
448/**\r
449 Allocate an item to save the <Key, Value> pair to the head of the netmap.\r
450\r
451 @param Map The netmap to insert into\r
452 @param Key The user's key\r
453 @param Value The user's value for the key\r
454\r
455 @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item\r
456 @retval EFI_SUCCESS The item is inserted to the head\r
457\r
458**/\r
459EFI_STATUS\r
460EFIAPI\r
461NetMapInsertHead (\r
462 IN NET_MAP *Map,\r
463 IN VOID *Key,\r
464 IN VOID *Value OPTIONAL\r
465 );\r
466\r
467/**\r
468 Allocate an item to save the <Key, Value> pair to the tail of the netmap.\r
469\r
470 @param Map The netmap to insert into\r
471 @param Key The user's key\r
472 @param Value The user's value for the key\r
473\r
474 @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item\r
475 @retval EFI_SUCCESS The item is inserted to the tail\r
476\r
477**/\r
478EFI_STATUS\r
479EFIAPI\r
480NetMapInsertTail (\r
481 IN NET_MAP *Map,\r
482 IN VOID *Key,\r
483 IN VOID *Value OPTIONAL\r
484 );\r
485\r
486/**\r
487 Find the key in the netmap\r
488\r
489 @param Map The netmap to search within\r
490 @param Key The key to search\r
491\r
492 @return The point to the item contains the Key, or NULL if Key isn't in the map.\r
493\r
494**/\r
495NET_MAP_ITEM *\r
496EFIAPI\r
497NetMapFindKey (\r
498 IN NET_MAP *Map,\r
499 IN VOID *Key\r
500 );\r
501\r
502/**\r
503 Remove the item from the netmap\r
504\r
505 @param Map The netmap to remove the item from\r
506 @param Item The item to remove\r
507 @param Value The variable to receive the value if not NULL\r
508\r
509 @return The key of the removed item.\r
510\r
511**/\r
512VOID *\r
513EFIAPI\r
514NetMapRemoveItem (\r
515 IN NET_MAP *Map,\r
516 IN NET_MAP_ITEM *Item,\r
517 OUT VOID **Value OPTIONAL\r
518 );\r
519\r
520/**\r
521 Remove the first entry on the netmap.\r
522\r
523 @param Map The netmap to remove the head from\r
524 @param Value The variable to receive the value if not NULL\r
525\r
526 @return The key of the item removed\r
527\r
528**/\r
529VOID *\r
530EFIAPI\r
531NetMapRemoveHead (\r
532 IN NET_MAP *Map,\r
533 OUT VOID **Value OPTIONAL\r
534 );\r
535\r
536/**\r
537 Remove the last entry on the netmap.\r
538\r
539 @param Map The netmap to remove the tail from\r
540 @param Value The variable to receive the value if not NULL\r
541\r
542 @return The key of the item removed\r
543\r
544**/\r
545VOID *\r
546EFIAPI\r
547NetMapRemoveTail (\r
548 IN NET_MAP *Map,\r
549 OUT VOID **Value OPTIONAL\r
550 );\r
551\r
552typedef\r
553EFI_STATUS\r
554(*NET_MAP_CALLBACK) (\r
555 IN NET_MAP *Map,\r
556 IN NET_MAP_ITEM *Item,\r
557 IN VOID *Arg\r
558 );\r
559\r
560/**\r
561 Iterate through the netmap and call CallBack for each item. It will\r
562 contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break\r
563 from the loop. It returns the CallBack's last return value. This\r
564 function is delete safe for the current item.\r
565\r
566 @param Map The Map to iterate through\r
567 @param CallBack The callback function to call for each item.\r
568 @param Arg The opaque parameter to the callback\r
569\r
570 @return It returns the CallBack's last return value.\r
571\r
572**/\r
573EFI_STATUS\r
574EFIAPI\r
575NetMapIterate (\r
576 IN NET_MAP *Map,\r
577 IN NET_MAP_CALLBACK CallBack,\r
578 IN VOID *Arg OPTIONAL\r
579 );\r
580\r
581\r
582//\r
583// Helper functions to implement driver binding and service binding protocols.\r
584//\r
585/**\r
586 Create a child of the service that is identified by ServiceBindingGuid.\r
587\r
588 @param ControllerHandle The controller which has the service installed.\r
589 @param ImageHandle The image handle used to open service.\r
590 @param ServiceBindingGuid The service's Guid.\r
591 @param ChildHandle The handle to receive the create child\r
592\r
593 @retval EFI_SUCCESS The child is successfully created.\r
594 @retval Others Failed to create the child.\r
595\r
596**/\r
597EFI_STATUS\r
598EFIAPI\r
599NetLibCreateServiceChild (\r
600 IN EFI_HANDLE ControllerHandle,\r
601 IN EFI_HANDLE ImageHandle,\r
602 IN EFI_GUID *ServiceBindingGuid,\r
603 OUT EFI_HANDLE *ChildHandle\r
604 );\r
605\r
606/**\r
607 Destory a child of the service that is identified by ServiceBindingGuid.\r
608\r
609 @param ControllerHandle The controller which has the service installed.\r
610 @param ImageHandle The image handle used to open service.\r
611 @param ServiceBindingGuid The service's Guid.\r
612 @param ChildHandle The child to destory\r
613\r
614 @retval EFI_SUCCESS The child is successfully destoried.\r
615 @retval Others Failed to destory the child.\r
616\r
617**/\r
618EFI_STATUS\r
619EFIAPI\r
620NetLibDestroyServiceChild (\r
621 IN EFI_HANDLE ControllerHandle,\r
622 IN EFI_HANDLE ImageHandle,\r
623 IN EFI_GUID *ServiceBindingGuid,\r
624 IN EFI_HANDLE ChildHandle\r
625 );\r
626\r
627/**\r
628 Convert the mac address of the simple network protocol installed on\r
629 SnpHandle to a unicode string. Callers are responsible for freeing the\r
630 string storage.\r
631\r
632 @param SnpHandle The handle where the simple network protocol is\r
633 installed on.\r
634 @param ImageHandle The image handle used to act as the agent handle to\r
635 get the simple network protocol.\r
636 @param MacString The pointer to store the address of the string\r
637 representation of the mac address.\r
638\r
639 @retval EFI_OUT_OF_RESOURCES There are not enough memory resource.\r
640 @retval other Failed to open the simple network protocol.\r
641\r
642**/\r
643EFI_STATUS\r
644EFIAPI\r
645NetLibGetMacString (\r
646 IN EFI_HANDLE SnpHandle,\r
647 IN EFI_HANDLE ImageHandle,\r
648 IN OUT CHAR16 **MacString\r
649 );\r
650\r
651/**\r
652 Create an IPv4 device path node.\r
653\r
654 @param Node Pointer to the IPv4 device path node.\r
655 @param Controller The handle where the NIC IP4 config protocol resides.\r
656 @param LocalIp The local IPv4 address.\r
657 @param LocalPort The local port.\r
658 @param RemoteIp The remote IPv4 address.\r
659 @param RemotePort The remote port.\r
660 @param Protocol The protocol type in the IP header.\r
661 @param UseDefaultAddress Whether this instance is using default address or not.\r
662\r
97b38d4e 663**/\r
664VOID\r
665EFIAPI\r
666NetLibCreateIPv4DPathNode (\r
667 IN OUT IPv4_DEVICE_PATH *Node,\r
668 IN EFI_HANDLE Controller,\r
669 IN IP4_ADDR LocalIp,\r
670 IN UINT16 LocalPort,\r
671 IN IP4_ADDR RemoteIp,\r
672 IN UINT16 RemotePort,\r
673 IN UINT16 Protocol,\r
674 IN BOOLEAN UseDefaultAddress\r
675 );\r
676\r
677/**\r
678 Find the UNDI/SNP handle from controller and protocol GUID.\r
679 For example, IP will open a MNP child to transmit/receive\r
680 packets, when MNP is stopped, IP should also be stopped. IP\r
681 needs to find its own private data which is related the IP's\r
682 service binding instance that is install on UNDI/SNP handle.\r
683 Now, the controller is either a MNP or ARP child handle. But\r
684 IP opens these handle BY_DRIVER, use that info, we can get the\r
685 UNDI/SNP handle.\r
686\r
687 @param Controller Then protocol handle to check\r
688 @param ProtocolGuid The protocol that is related with the handle.\r
689\r
690 @return The UNDI/SNP handle or NULL.\r
691\r
692**/\r
693EFI_HANDLE\r
694EFIAPI\r
695NetLibGetNicHandle (\r
696 IN EFI_HANDLE Controller,\r
697 IN EFI_GUID *ProtocolGuid\r
698 );\r
699\r
700/**\r
701 Add a Deferred Procedure Call to the end of the DPC queue.\r
702\r
703 @param DpcTpl The EFI_TPL that the DPC should be invoked.\r
704 @param DpcProcedure Pointer to the DPC's function.\r
705 @param DpcContext Pointer to the DPC's context. Passed to DpcProcedure\r
706 when DpcProcedure is invoked.\r
707\r
708 @retval EFI_SUCCESS The DPC was queued.\r
709 @retval EFI_INVALID_PARAMETER DpcTpl is not a valid EFI_TPL.\r
710 DpcProcedure is NULL.\r
711 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to\r
712 add the DPC to the queue.\r
713\r
714**/\r
715EFI_STATUS\r
716EFIAPI\r
717NetLibQueueDpc (\r
718 IN EFI_TPL DpcTpl,\r
719 IN EFI_DPC_PROCEDURE DpcProcedure,\r
720 IN VOID *DpcContext OPTIONAL\r
721 );\r
722\r
723/**\r
724 Add a Deferred Procedure Call to the end of the DPC queue.\r
725\r
726 @retval EFI_SUCCESS One or more DPCs were invoked.\r
727 @retval EFI_NOT_FOUND No DPCs were invoked.\r
728\r
729**/\r
730EFI_STATUS\r
731EFIAPI\r
732NetLibDispatchDpc (\r
733 VOID\r
734 );\r
735\r
736/**\r
737 This is the default unload handle for all the network drivers.\r
738\r
739 @param ImageHandle The drivers' driver image.\r
740\r
741 @retval EFI_SUCCESS The image is unloaded.\r
742 @retval Others Failed to unload the image.\r
743\r
744**/\r
745EFI_STATUS\r
746EFIAPI\r
747NetLibDefaultUnload (\r
748 IN EFI_HANDLE ImageHandle\r
749 );\r
750\r
751typedef enum {\r
752 //\r
753 //Various signatures\r
754 //\r
f3f2e05d 755 NET_BUF_SIGNATURE = SIGNATURE_32 ('n', 'b', 'u', 'f'),\r
756 NET_VECTOR_SIGNATURE = SIGNATURE_32 ('n', 'v', 'e', 'c'),\r
757 NET_QUE_SIGNATURE = SIGNATURE_32 ('n', 'b', 'q', 'u'),\r
97b38d4e 758\r
759\r
760 NET_PROTO_DATA = 64, // Opaque buffer for protocols\r
761 NET_BUF_HEAD = 1, // Trim or allocate space from head\r
762 NET_BUF_TAIL = 0, // Trim or allocate space from tail\r
763 NET_VECTOR_OWN_FIRST = 0x01 // We allocated the 1st block in the vector\r
764} NET_SIGNATURE_TYPE;\r
765\r
766#define NET_CHECK_SIGNATURE(PData, SIGNATURE) \\r
767 ASSERT (((PData) != NULL) && ((PData)->Signature == (SIGNATURE)))\r
768\r
769#define NET_SWAP_SHORT(Value) \\r
770 ((((Value) & 0xff) << 8) | (((Value) >> 8) & 0xff))\r
771\r
772//\r
773// Single memory block in the vector.\r
774//\r
775typedef struct {\r
776 UINT32 Len; // The block's length\r
777 UINT8 *Bulk; // The block's Data\r
778} NET_BLOCK;\r
779\r
780typedef VOID (*NET_VECTOR_EXT_FREE) (VOID *Arg);\r
781\r
782//\r
783//NET_VECTOR contains several blocks to hold all packet's\r
784//fragments and other house-keeping stuff for sharing. It\r
785//doesn't specify the where actual packet fragment begins.\r
786//\r
787typedef struct {\r
788 UINT32 Signature;\r
789 INTN RefCnt; // Reference count to share NET_VECTOR.\r
790 NET_VECTOR_EXT_FREE Free; // external function to free NET_VECTOR\r
791 VOID *Arg; // opeque argument to Free\r
792 UINT32 Flag; // Flags, NET_VECTOR_OWN_FIRST\r
793 UINT32 Len; // Total length of the assocated BLOCKs\r
794\r
795 UINT32 BlockNum;\r
796 NET_BLOCK Block[1];\r
797} NET_VECTOR;\r
798\r
799//\r
800//NET_BLOCK_OP operate on the NET_BLOCK, It specifies\r
801//where the actual fragment begins and where it ends\r
802//\r
803typedef struct {\r
804 UINT8 *BlockHead; // Block's head, or the smallest valid Head\r
805 UINT8 *BlockTail; // Block's tail. BlockTail-BlockHead=block length\r
806 UINT8 *Head; // 1st byte of the data in the block\r
807 UINT8 *Tail; // Tail of the data in the block, Tail-Head=Size\r
808 UINT32 Size; // The size of the data\r
809} NET_BLOCK_OP;\r
810\r
811\r
812//\r
813//NET_BUF is the buffer manage structure used by the\r
814//network stack. Every network packet may be fragmented,\r
815//and contains multiple fragments. The Vector points to\r
816//memory blocks used by the each fragment, and BlockOp\r
817//specifies where each fragment begins and ends.\r
818//\r
819//It also contains a opaque area for protocol to store\r
820//per-packet informations. Protocol must be caution not\r
821//to overwrite the members after that.\r
822//\r
823typedef struct {\r
824 UINT32 Signature;\r
825 INTN RefCnt;\r
826 LIST_ENTRY List; // The List this NET_BUF is on\r
827\r
828 IP4_HEAD *Ip; // Network layer header, for fast access\r
829 TCP_HEAD *Tcp; // Transport layer header, for fast access\r
830 UINT8 ProtoData [NET_PROTO_DATA]; //Protocol specific data\r
831\r
832 NET_VECTOR *Vector; // The vector containing the packet\r
833\r
834 UINT32 BlockOpNum; // Total number of BlockOp in the buffer\r
835 UINT32 TotalSize; // Total size of the actual packet\r
836 NET_BLOCK_OP BlockOp[1]; // Specify the position of actual packet\r
837} NET_BUF;\r
838\r
839\r
840//\r
841//A queue of NET_BUFs, It is just a thin extension of\r
842//NET_BUF functions.\r
843//\r
844typedef struct {\r
845 UINT32 Signature;\r
846 INTN RefCnt;\r
847 LIST_ENTRY List; // The List this buffer queue is on\r
848\r
849 LIST_ENTRY BufList; // list of queued buffers\r
850 UINT32 BufSize; // total length of DATA in the buffers\r
851 UINT32 BufNum; // total number of buffers on the chain\r
852} NET_BUF_QUEUE;\r
853\r
854//\r
855// Pseudo header for TCP and UDP checksum\r
856//\r
857#pragma pack(1)\r
858typedef struct {\r
859 IP4_ADDR SrcIp;\r
860 IP4_ADDR DstIp;\r
861 UINT8 Reserved;\r
862 UINT8 Protocol;\r
863 UINT16 Len;\r
864} NET_PSEUDO_HDR;\r
865#pragma pack()\r
866\r
867//\r
868// The fragment entry table used in network interfaces. This is\r
869// the same as NET_BLOCK now. Use two different to distinguish\r
870// the two in case that NET_BLOCK be enhanced later.\r
871//\r
872typedef struct {\r
873 UINT32 Len;\r
874 UINT8 *Bulk;\r
875} NET_FRAGMENT;\r
876\r
877#define NET_GET_REF(PData) ((PData)->RefCnt++)\r
878#define NET_PUT_REF(PData) ((PData)->RefCnt--)\r
50d7ebad 879#define NETBUF_FROM_PROTODATA(Info) BASE_CR((Info), NET_BUF, ProtoData)\r
97b38d4e 880\r
881#define NET_BUF_SHARED(Buf) \\r
882 (((Buf)->RefCnt > 1) || ((Buf)->Vector->RefCnt > 1))\r
883\r
884#define NET_VECTOR_SIZE(BlockNum) \\r
885 (sizeof (NET_VECTOR) + ((BlockNum) - 1) * sizeof (NET_BLOCK))\r
886\r
887#define NET_BUF_SIZE(BlockOpNum) \\r
888 (sizeof (NET_BUF) + ((BlockOpNum) - 1) * sizeof (NET_BLOCK_OP))\r
889\r
890#define NET_HEADSPACE(BlockOp) \\r
891 (UINTN)((BlockOp)->Head - (BlockOp)->BlockHead)\r
892\r
893#define NET_TAILSPACE(BlockOp) \\r
894 (UINTN)((BlockOp)->BlockTail - (BlockOp)->Tail)\r
895\r
896/**\r
897 Allocate a single block NET_BUF. Upon allocation, all the\r
898 free space is in the tail room.\r
899\r
900 @param Len The length of the block.\r
901\r
902 @retval * Pointer to the allocated NET_BUF. If NULL the\r
903 allocation failed due to resource limit.\r
904\r
905**/\r
906NET_BUF *\r
907EFIAPI\r
908NetbufAlloc (\r
909 IN UINT32 Len\r
910 );\r
911\r
912/**\r
913 Free the buffer and its associated NET_VECTOR.\r
914\r
915 @param Nbuf Pointer to the NET_BUF to be freed.\r
916\r
917 @return None.\r
918\r
919**/\r
920VOID\r
921EFIAPI\r
922NetbufFree (\r
923 IN NET_BUF *Nbuf\r
924 );\r
925\r
926/**\r
927 Get the position of some byte in the net buffer. This can be used\r
928 to, for example, retrieve the IP header in the packet. It also\r
929 returns the fragment that contains the byte which is used mainly by\r
930 the buffer implementation itself.\r
931\r
932 @param Nbuf Pointer to the net buffer.\r
933 @param Offset The index or offset of the byte\r
934 @param Index Index of the fragment that contains the block\r
935\r
936 @retval * Pointer to the nth byte of data in the net buffer.\r
937 If NULL, there is no such data in the net buffer.\r
938\r
939**/\r
940UINT8 *\r
941EFIAPI\r
942NetbufGetByte (\r
943 IN NET_BUF *Nbuf,\r
944 IN UINT32 Offset,\r
945 OUT UINT32 *Index OPTIONAL\r
946 );\r
947\r
948/**\r
949 Create a copy of NET_BUF that share the associated NET_DATA.\r
950\r
951 @param Nbuf Pointer to the net buffer to be cloned.\r
952\r
953 @retval * Pointer to the cloned net buffer.\r
954\r
955**/\r
956NET_BUF *\r
957EFIAPI\r
958NetbufClone (\r
959 IN NET_BUF *Nbuf\r
960 );\r
961\r
962/**\r
963 Create a duplicated copy of Nbuf, data is copied. Also leave some\r
964 head space before the data.\r
965\r
966 @param Nbuf Pointer to the net buffer to be cloned.\r
967 @param Duplicate Pointer to the net buffer to duplicate to, if NULL\r
968 a new net buffer is allocated.\r
969 @param HeadSpace Length of the head space to reserve\r
970\r
971 @retval * Pointer to the duplicated net buffer.\r
972\r
973**/\r
974NET_BUF *\r
975EFIAPI\r
976NetbufDuplicate (\r
977 IN NET_BUF *Nbuf,\r
978 IN NET_BUF *Duplicate OPTIONAL,\r
979 IN UINT32 HeadSpace\r
980 );\r
981\r
982/**\r
983 Create a NET_BUF structure which contains Len byte data of\r
984 Nbuf starting from Offset. A new NET_BUF structure will be\r
985 created but the associated data in NET_VECTOR is shared.\r
986 This function exists to do IP packet fragmentation.\r
987\r
988 @param Nbuf Pointer to the net buffer to be cloned.\r
989 @param Offset Starting point of the data to be included in new\r
990 buffer.\r
991 @param Len How many data to include in new data\r
992 @param HeadSpace How many bytes of head space to reserve for\r
993 protocol header\r
994\r
995 @retval * Pointer to the cloned net buffer.\r
996\r
997**/\r
998NET_BUF *\r
999EFIAPI\r
1000NetbufGetFragment (\r
1001 IN NET_BUF *Nbuf,\r
1002 IN UINT32 Offset,\r
1003 IN UINT32 Len,\r
1004 IN UINT32 HeadSpace\r
1005 );\r
1006\r
1007/**\r
1008 Reserve some space in the header room of the buffer.\r
1009 Upon allocation, all the space are in the tail room\r
1010 of the buffer. Call this function to move some space\r
1011 to the header room. This function is quite limited in\r
1012 that it can only reserver space from the first block\r
1013 of an empty NET_BUF not built from the external. But\r
1014 it should be enough for the network stack.\r
1015\r
1016 @param Nbuf Pointer to the net buffer.\r
1017 @param Len The length of buffer to be reserverd.\r
1018\r
1019 @return None.\r
1020\r
1021**/\r
1022VOID\r
1023EFIAPI\r
1024NetbufReserve (\r
1025 IN NET_BUF *Nbuf,\r
1026 IN UINT32 Len\r
1027 );\r
1028\r
1029/**\r
1030 Allocate some space from the header or tail of the buffer.\r
1031\r
1032 @param Nbuf Pointer to the net buffer.\r
1033 @param Len The length of the buffer to be allocated.\r
1034 @param FromHead The flag to indicate whether reserve the data from\r
1035 head or tail. TRUE for from head, and FALSE for\r
1036 from tail.\r
1037\r
1038 @retval * Pointer to the first byte of the allocated buffer.\r
1039\r
1040**/\r
1041UINT8 *\r
1042EFIAPI\r
1043NetbufAllocSpace (\r
1044 IN NET_BUF *Nbuf,\r
1045 IN UINT32 Len,\r
1046 IN BOOLEAN FromHead\r
1047 );\r
1048\r
1049/**\r
1050 Trim some data from the header or tail of the buffer.\r
1051\r
1052 @param Nbuf Pointer to the net buffer.\r
1053 @param Len The length of the data to be trimmed.\r
1054 @param FromHead The flag to indicate whether trim data from head or\r
1055 tail. TRUE for from head, and FALSE for from tail.\r
1056\r
1057 @retval UINTN Length of the actually trimmed data.\r
1058\r
1059**/\r
1060UINT32\r
1061EFIAPI\r
1062NetbufTrim (\r
1063 IN NET_BUF *Nbuf,\r
1064 IN UINT32 Len,\r
1065 IN BOOLEAN FromHead\r
1066 );\r
1067\r
1068/**\r
1069 Copy the data from the specific offset to the destination.\r
1070\r
1071 @param Nbuf Pointer to the net buffer.\r
1072 @param Offset The sequence number of the first byte to copy.\r
1073 @param Len Length of the data to copy.\r
1074 @param Dest The destination of the data to copy to.\r
1075\r
1076 @retval UINTN The length of the copied data.\r
1077\r
1078**/\r
1079UINT32\r
1080EFIAPI\r
1081NetbufCopy (\r
1082 IN NET_BUF *Nbuf,\r
1083 IN UINT32 Offset,\r
1084 IN UINT32 Len,\r
1085 IN UINT8 *Dest\r
1086 );\r
1087\r
1088/**\r
1089 Build a NET_BUF from external blocks.\r
1090\r
1091 @param ExtFragment Pointer to the data block.\r
1092 @param ExtNum The number of the data block.\r
1093 @param HeadSpace The head space to be reserved.\r
1094 @param HeadLen The length of the protocol header, This function\r
1095 will pull that number of data into a linear block.\r
1096 @param ExtFree Pointer to the caller provided free function.\r
1097 @param Arg The argument passed to ExtFree when ExtFree is\r
1098 called.\r
1099\r
1100 @retval * Pointer to the net buffer built from the data\r
1101 blocks.\r
1102\r
1103**/\r
1104NET_BUF *\r
1105EFIAPI\r
1106NetbufFromExt (\r
1107 IN NET_FRAGMENT *ExtFragment,\r
1108 IN UINT32 ExtNum,\r
1109 IN UINT32 HeadSpace,\r
1110 IN UINT32 HeadLen,\r
1111 IN NET_VECTOR_EXT_FREE ExtFree,\r
1112 IN VOID *Arg OPTIONAL\r
1113 );\r
1114\r
1115/**\r
1116 Build a fragment table to contain the fragments in the\r
1117 buffer. This is the opposite of the NetbufFromExt.\r
1118\r
1119 @param Nbuf Point to the net buffer\r
1120 @param ExtFragment Pointer to the data block.\r
1121 @param ExtNum The number of the data block.\r
1122\r
1123 @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than ExtNum\r
1124 @retval EFI_SUCCESS Fragment table built.\r
1125\r
1126**/\r
1127EFI_STATUS\r
1128EFIAPI\r
1129NetbufBuildExt (\r
1130 IN NET_BUF *Nbuf,\r
1131 IN NET_FRAGMENT *ExtFragment,\r
1132 IN UINT32 *ExtNum\r
1133 );\r
1134\r
1135/**\r
1136 Build a NET_BUF from a list of NET_BUF.\r
1137\r
1138 @param BufList A List of NET_BUF.\r
1139 @param HeadSpace The head space to be reserved.\r
1140 @param HeaderLen The length of the protocol header, This function\r
1141 will pull that number of data into a linear block.\r
1142 @param ExtFree Pointer to the caller provided free function.\r
1143 @param Arg The argument passed to ExtFree when ExtFree is\r
1144 called.\r
1145\r
1146 @retval * Pointer to the net buffer built from the data\r
1147 blocks.\r
1148\r
1149**/\r
1150NET_BUF *\r
1151EFIAPI\r
1152NetbufFromBufList (\r
1153 IN LIST_ENTRY *BufList,\r
1154 IN UINT32 HeadSpace,\r
1155 IN UINT32 HeaderLen,\r
1156 IN NET_VECTOR_EXT_FREE ExtFree,\r
1157 IN VOID *Arg OPTIONAL\r
1158 );\r
1159\r
1160/**\r
1161 Free a list of net buffers.\r
1162\r
1163 @param Head Pointer to the head of linked net buffers.\r
1164\r
1165 @return None.\r
1166\r
1167**/\r
1168VOID\r
1169EFIAPI\r
1170NetbufFreeList (\r
1171 IN LIST_ENTRY *Head\r
1172 );\r
1173\r
1174/**\r
1175 Initiate the net buffer queue.\r
1176\r
1177 @param NbufQue Pointer to the net buffer queue to be initiated.\r
1178\r
1179 @return None.\r
1180\r
1181**/\r
1182VOID\r
1183EFIAPI\r
1184NetbufQueInit (\r
1185 IN NET_BUF_QUEUE *NbufQue\r
1186 );\r
1187\r
1188/**\r
1189 Allocate an initialized net buffer queue.\r
1190\r
1191 None.\r
1192\r
1193 @retval * Pointer to the allocated net buffer queue.\r
1194\r
1195**/\r
1196NET_BUF_QUEUE *\r
1197EFIAPI\r
1198NetbufQueAlloc (\r
1199 VOID\r
1200 );\r
1201\r
1202/**\r
1203 Free a net buffer queue.\r
1204\r
1205 @param NbufQue Poitner to the net buffer queue to be freed.\r
1206\r
1207 @return None.\r
1208\r
1209**/\r
1210VOID\r
1211EFIAPI\r
1212NetbufQueFree (\r
1213 IN NET_BUF_QUEUE *NbufQue\r
1214 );\r
1215\r
1216/**\r
1217 Remove a net buffer from head in the specific queue.\r
1218\r
1219 @param NbufQue Pointer to the net buffer queue.\r
1220\r
1221 @retval * Pointer to the net buffer removed from the specific\r
1222 queue.\r
1223\r
1224**/\r
1225NET_BUF *\r
1226EFIAPI\r
1227NetbufQueRemove (\r
1228 IN NET_BUF_QUEUE *NbufQue\r
1229 );\r
1230\r
1231/**\r
1232 Append a buffer to the end of the queue.\r
1233\r
1234 @param NbufQue Pointer to the net buffer queue.\r
1235 @param Nbuf Pointer to the net buffer to be appended.\r
1236\r
1237 @return None.\r
1238\r
1239**/\r
1240VOID\r
1241EFIAPI\r
1242NetbufQueAppend (\r
1243 IN NET_BUF_QUEUE *NbufQue,\r
1244 IN NET_BUF *Nbuf\r
1245 );\r
1246\r
1247/**\r
1248 Copy some data from the buffer queue to the destination.\r
1249\r
1250 @param NbufQue Pointer to the net buffer queue.\r
1251 @param Offset The sequence number of the first byte to copy.\r
1252 @param Len Length of the data to copy.\r
1253 @param Dest The destination of the data to copy to.\r
1254\r
1255 @retval UINTN The length of the copied data.\r
1256\r
1257**/\r
1258UINT32\r
1259EFIAPI\r
1260NetbufQueCopy (\r
1261 IN NET_BUF_QUEUE *NbufQue,\r
1262 IN UINT32 Offset,\r
1263 IN UINT32 Len,\r
1264 IN UINT8 *Dest\r
1265 );\r
1266\r
1267/**\r
1268 Trim some data from the queue header, release the buffer if\r
1269 whole buffer is trimmed.\r
1270\r
1271 @param NbufQue Pointer to the net buffer queue.\r
1272 @param Len Length of the data to trim.\r
1273\r
1274 @retval UINTN The length of the data trimmed.\r
1275\r
1276**/\r
1277UINT32\r
1278EFIAPI\r
1279NetbufQueTrim (\r
1280 IN NET_BUF_QUEUE *NbufQue,\r
1281 IN UINT32 Len\r
1282 );\r
1283\r
1284\r
1285/**\r
1286 Flush the net buffer queue.\r
1287\r
1288 @param NbufQue Pointer to the queue to be flushed.\r
1289\r
1290 @return None.\r
1291\r
1292**/\r
1293VOID\r
1294EFIAPI\r
1295NetbufQueFlush (\r
1296 IN NET_BUF_QUEUE *NbufQue\r
1297 );\r
1298\r
1299/**\r
1300 Compute checksum for a bulk of data.\r
1301\r
1302 @param Bulk Pointer to the data.\r
1303 @param Len Length of the data, in bytes.\r
1304\r
1305 @retval UINT16 The computed checksum.\r
1306\r
1307**/\r
1308UINT16\r
1309EFIAPI\r
1310NetblockChecksum (\r
1311 IN UINT8 *Bulk,\r
1312 IN UINT32 Len\r
1313 );\r
1314\r
1315/**\r
1316 Add two checksums.\r
1317\r
1318 @param Checksum1 The first checksum to be added.\r
1319 @param Checksum2 The second checksum to be added.\r
1320\r
1321 @retval UINT16 The new checksum.\r
1322\r
1323**/\r
1324UINT16\r
1325EFIAPI\r
1326NetAddChecksum (\r
1327 IN UINT16 Checksum1,\r
1328 IN UINT16 Checksum2\r
1329 );\r
1330\r
1331/**\r
1332 Compute the checksum for a NET_BUF.\r
1333\r
1334 @param Nbuf Pointer to the net buffer.\r
1335\r
1336 @retval UINT16 The computed checksum.\r
1337\r
1338**/\r
1339UINT16\r
1340EFIAPI\r
1341NetbufChecksum (\r
1342 IN NET_BUF *Nbuf\r
1343 );\r
1344\r
1345/**\r
1346 Compute the checksum for TCP/UDP pseudo header.\r
1347 Src, Dst are in network byte order. and Len is\r
1348 in host byte order.\r
1349\r
1350 @param Src The source address of the packet.\r
1351 @param Dst The destination address of the packet.\r
1352 @param Proto The protocol type of the packet.\r
1353 @param Len The length of the packet.\r
1354\r
1355 @retval UINT16 The computed checksum.\r
1356\r
1357**/\r
1358UINT16\r
1359EFIAPI\r
1360NetPseudoHeadChecksum (\r
1361 IN IP4_ADDR Src,\r
1362 IN IP4_ADDR Dst,\r
1363 IN UINT8 Proto,\r
1364 IN UINT16 Len\r
1365 );\r
1366\r
1367#endif\r