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