X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdeModulePkg%2FInclude%2FLibrary%2FNetLib.h;h=b057cbd2cee4b4f74b9e05548d17bb146cc9b085;hp=1a0fdb28ba894fa4e8a482def07f7d94eeb662d0;hb=f324bf4dbeda4d64b769bd005331e8f9404b692d;hpb=d7db0902808f59f71421cc2fc5012da4a47a32b9 diff --git a/MdeModulePkg/Include/Library/NetLib.h b/MdeModulePkg/Include/Library/NetLib.h index 1a0fdb28ba..b057cbd2ce 100644 --- a/MdeModulePkg/Include/Library/NetLib.h +++ b/MdeModulePkg/Include/Library/NetLib.h @@ -1,5 +1,6 @@ /** @file - This library provides basic function for UEFI network stack. + Ihis library is only intended to be used by UEFI network stack modules. + It provides basic function for UEFI network stack. Copyright (c) 2005 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials @@ -15,12 +16,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _NET_LIB_H_ #define _NET_LIB_H_ -#include -#include -#include -#include -#include -#include #include typedef UINT32 IP4_ADDR; @@ -166,29 +161,42 @@ typedef struct { #define EFI_IP4_EQUAL(Ip1, Ip2) (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv4_ADDRESS)) == 0) /** - Return the length of the mask. If the mask is invalid, - return the invalid length 33, which is IP4_MASK_NUM. + Return the length of the mask. + + Return the length of the mask, the correct value is from 0 to 32. + If the mask is invalid, return the invalid length 33, which is IP4_MASK_NUM. NetMask is in the host byte order. - @param NetMask The netmask to get the length from - - @return The length of the netmask, IP4_MASK_NUM if the mask isn't - @return supported. + @param[in] NetMask The netmask to get the length from. + @return The length of the netmask, IP4_MASK_NUM if the mask is invalid. + **/ INTN EFIAPI NetGetMaskLength ( - IN IP4_ADDR Mask + IN IP4_ADDR NetMask ); /** - Return the class of the address, such as class a, b, c. + Return the class of the IP address, such as class A, B, C. Addr is in host byte order. - - @param Addr The address to get the class from - - @return IP address class, such as IP4_ADDR_CLASSA + + The address of class A starts with 0. + If the address belong to class A, return IP4_ADDR_CLASSA. + The address of class B starts with 10. + If the address belong to class B, return IP4_ADDR_CLASSB. + The address of class C starts with 110. + If the address belong to class C, return IP4_ADDR_CLASSC. + The address of class D starts with 1110. + If the address belong to class D, return IP4_ADDR_CLASSD. + The address of class E starts with 1111. + If the address belong to class E, return IP4_ADDR_CLASSE. + + + @param[in] Addr The address to get the class from. + + @return IP address class, such as IP4_ADDR_CLASSA. **/ INTN @@ -199,22 +207,27 @@ NetGetIpClass ( /** Check whether the IP is a valid unicast address according to - the netmask. If NetMask is zero, use the IP address's class to - get the default mask. + the netmask. If NetMask is zero, use the IP address's class to get the default mask. + + If Ip is 0, IP is not a valid unicast address. + Class D address is used for multicasting and class E address is reserved for future. If Ip + belongs to class D or class E, IP is not a valid unicast address. + If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address. - @param Ip The IP to check againist - @param NetMask The mask of the IP + @param[in] Ip The IP to check against. + @param[in] NetMask The mask of the IP. - @return TRUE if IP is a valid unicast address on the network, otherwise FALSE + @return TRUE if IP is a valid unicast address on the network, otherwise FALSE. **/ BOOLEAN +EFIAPI Ip4IsUnicast ( IN IP4_ADDR Ip, IN IP4_ADDR NetMask ); -extern IP4_ADDR gIp4AllMasks [IP4_MASK_NUM]; +extern IP4_ADDR gIp4AllMasks[IP4_MASK_NUM]; extern EFI_IPv4_ADDRESS mZeroIp4Addr; @@ -230,10 +243,12 @@ extern EFI_IPv4_ADDRESS mZeroIp4Addr; #define NET_RANDOM(Seed) ((UINT32) ((UINT32) (Seed) * 1103515245UL + 12345) % 4294967295UL) /** - Extract a UINT32 from a byte stream, then convert it to host - byte order. Use this function to avoid alignment error. + Extract a UINT32 from a byte stream. + + Copy a UINT32 from a byte stream, then converts it from Network + byte order to host byte order. Use this function to avoid alignment error. - @param Buf The buffer to extract the UINT32. + @param[in] Buf The buffer to extract the UINT32. @return The UINT32 extracted. @@ -245,27 +260,29 @@ NetGetUint32 ( ); /** - Put a UINT32 to the byte stream. Convert it from host byte order - to network byte order before putting. - - @param Buf The buffer to put the UINT32 - @param Data The data to put - - @return None - + Put a UINT32 to the byte stream in network byte order. + + Converts a UINT32 from host byte order to network byte order. Then copy it to the + byte stream. + + @param[in, out] Buf The buffer to put the UINT32. + @param[in] Data The data to put. + **/ VOID EFIAPI NetPutUint32 ( - IN UINT8 *Buf, - IN UINT32 Data + IN OUT UINT8 *Buf, + IN UINT32 Data ); /** Initialize a random seed using current time. - - None - + + Get current time first. Then initialize a random seed based on some basic + mathematics operation on the hour, day, minute, second, nanosecond and year + of the current time. + @return The random seed initialized with current time. **/ @@ -311,63 +328,85 @@ NetRandomInitSeed ( /** - Remove the first entry on the list + Remove the first node entry on the list, and return the removed node entry. + + Removes the first node Entry from a doubly linked list. It is up to the caller of + this function to release the memory used by the first node if that is required. On + exit, the removed node is returned. - @param Head The list header + If Head is NULL, then ASSERT(). + If Head was not initialized, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list including the head node is greater than or equal to PcdMaximumLinkedListLength, + then ASSERT(). - @return The entry that is removed from the list, NULL if the list is empty. + @param[in, out] Head The list header. + + @return The first node entry that is removed from the list, NULL if the list is empty. **/ LIST_ENTRY * EFIAPI NetListRemoveHead ( - LIST_ENTRY *Head + IN OUT LIST_ENTRY *Head ); /** - Remove the last entry on the list + Remove the last node entry on the list and and return the removed node entry. + + Removes the last node entry from a doubly linked list. It is up to the caller of + this function to release the memory used by the first node if that is required. On + exit, the removed node is returned. - @param Head The list head + If Head is NULL, then ASSERT(). + If Head was not initialized, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list including the head node is greater than or equal to PcdMaximumLinkedListLength, + then ASSERT(). + + @param[in, out] Head The list head. - @return The entry that is removed from the list, NULL if the list is empty. + @return The last node entry that is removed from the list, NULL if the list is empty. **/ LIST_ENTRY * EFIAPI NetListRemoveTail ( - LIST_ENTRY *Head + IN OUT LIST_ENTRY *Head ); /** - Insert the NewEntry after the PrevEntry. - - @param PrevEntry The previous entry to insert after - @param NewEntry The new entry to insert - - @return None + Insert a new node entry after a designated node entry of a doubly linked list. + + Inserts a new node entry donated by NewEntry after the node entry donated by PrevEntry + of the doubly linked list. + + @param[in, out] PrevEntry The previous entry to insert after. + @param[in, out] NewEntry The new entry to insert. **/ VOID EFIAPI NetListInsertAfter ( - IN LIST_ENTRY *PrevEntry, - IN LIST_ENTRY *NewEntry + IN OUT LIST_ENTRY *PrevEntry, + IN OUT LIST_ENTRY *NewEntry ); /** - Insert the NewEntry before the PostEntry. - - @param PostEntry The entry to insert before - @param NewEntry The new entry to insert - - @return None + Insert a new node entry before a designated node entry of a doubly linked list. + + Inserts a new node entry donated by NewEntry after the node entry donated by PostEntry + of the doubly linked list. + + @param[in, out] PostEntry The entry to insert before. + @param[in, out] NewEntry The new entry to insert. **/ VOID EFIAPI NetListInsertBefore ( - IN LIST_ENTRY *PostEntry, - IN LIST_ENTRY *NewEntry + IN OUT LIST_ENTRY *PostEntry, + IN OUT LIST_ENTRY *NewEntry ); @@ -391,36 +430,51 @@ typedef struct { /** Initialize the netmap. Netmap is a reposity to keep the pairs. - - @param Map The netmap to initialize - - @return None + + Initialize the forward and backward links of two head nodes donated by Map->Used + and Map->Recycled of two doubly linked lists. + Initializes the count of the pairs in the netmap to zero. + + If Map is NULL, then ASSERT(). + If the address of Map->Used is NULL, then ASSERT(). + If the address of Map->Recycled is NULl, then ASSERT(). + + @param[in, out] Map The netmap to initialize. **/ VOID EFIAPI NetMapInit ( - IN NET_MAP *Map + IN OUT NET_MAP *Map ); /** To clean up the netmap, that is, release allocated memories. - - @param Map The netmap to clean up. - - @return None + + Removes all nodes of the Used doubly linked list and free memory of all related netmap items. + Removes all nodes of the Recycled doubly linked list and free memory of all related netmap items. + The number of the pairs in the netmap is set to be zero. + + If Map is NULL, then ASSERT(). + + @param[in, out] Map The netmap to clean up. **/ VOID EFIAPI NetMapClean ( - IN NET_MAP *Map + IN OUT NET_MAP *Map ); /** - Test whether the netmap is empty - - @param Map The net map to test + Test whether the netmap is empty and return true if it is. + + If the number of the pairs in the netmap is zero, return TRUE. + + If Map is NULL, then ASSERT(). + + + @param[in] Map The net map to test. @return TRUE if the netmap is empty, otherwise FALSE. @@ -434,7 +488,7 @@ NetMapIsEmpty ( /** Return the number of the pairs in the netmap. - @param Map The netmap to get the entry number + @param[in] Map The netmap to get the entry number. @return The entry number in the netmap. @@ -447,19 +501,25 @@ NetMapGetCount ( /** Allocate an item to save the pair to the head of the netmap. + + Allocate an item to save the pair and add corresponding node entry + to the beginning of the Used doubly linked list. The number of the + pairs in the netmap increase by 1. - @param Map The netmap to insert into - @param Key The user's key - @param Value The user's value for the key + If Map is NULL, then ASSERT(). + + @param[in, out] Map The netmap to insert into. + @param[in] Key The user's key. + @param[in] Value The user's value for the key. - @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item - @retval EFI_SUCCESS The item is inserted to the head + @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item. + @retval EFI_SUCCESS The item is inserted to the head. **/ EFI_STATUS EFIAPI NetMapInsertHead ( - IN NET_MAP *Map, + IN OUT NET_MAP *Map, IN VOID *Key, IN VOID *Value OPTIONAL ); @@ -467,32 +527,43 @@ NetMapInsertHead ( /** Allocate an item to save the pair to the tail of the netmap. - @param Map The netmap to insert into - @param Key The user's key - @param Value The user's value for the key + Allocate an item to save the pair and add corresponding node entry + to the tail of the Used doubly linked list. The number of the + pairs in the netmap increase by 1. - @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item - @retval EFI_SUCCESS The item is inserted to the tail + If Map is NULL, then ASSERT(). + + @param[in, out] Map The netmap to insert into. + @param[in] Key The user's key. + @param[in] Value The user's value for the key. + + @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the item. + @retval EFI_SUCCESS The item is inserted to the tail. **/ EFI_STATUS EFIAPI NetMapInsertTail ( - IN NET_MAP *Map, + IN OUT NET_MAP *Map, IN VOID *Key, IN VOID *Value OPTIONAL ); /** - Find the key in the netmap + Find the key in the netmap and returns the point to the item contains the Key. + + Iterate the Used doubly linked list of the netmap to get every item. Compare the key of every + item with the key to search. It returns the point to the item contains the Key if found. - @param Map The netmap to search within - @param Key The key to search + If Map is NULL, then ASSERT(). + + @param[in] Map The netmap to search within. + @param[in] Key The key to search. @return The point to the item contains the Key, or NULL if Key isn't in the map. **/ -NET_MAP_ITEM * +NET_MAP_ITEM * EFIAPI NetMapFindKey ( IN NET_MAP *Map, @@ -500,53 +571,78 @@ NetMapFindKey ( ); /** - Remove the item from the netmap - - @param Map The netmap to remove the item from - @param Item The item to remove - @param Value The variable to receive the value if not NULL - - @return The key of the removed item. + Remove the node entry of the item from the netmap and return the key of the removed item. + + Remove the node entry of the item from the Used doubly linked list of the netmap. + The number of the pairs in the netmap decrease by 1. Then add the node + entry of the item to the Recycled doubly linked list of the netmap. If Value is not NULL, + Value will point to the value of the item. It returns the key of the removed item. + + If Map is NULL, then ASSERT(). + If Item is NULL, then ASSERT(). + if item in not in the netmap, then ASSERT(). + + @param[in, out] Map The netmap to remove the item from. + @param[in, out] Item The item to remove. + @param[out] Value The variable to receive the value if not NULL. + + @return The key of the removed item. **/ VOID * EFIAPI NetMapRemoveItem ( - IN NET_MAP *Map, - IN NET_MAP_ITEM *Item, - OUT VOID **Value OPTIONAL + IN OUT NET_MAP *Map, + IN OUT NET_MAP_ITEM *Item, + OUT VOID **Value OPTIONAL ); /** - Remove the first entry on the netmap. + Remove the first node entry on the netmap and return the key of the removed item. - @param Map The netmap to remove the head from - @param Value The variable to receive the value if not NULL + Remove the first node entry from the Used doubly linked list of the netmap. + The number of the pairs in the netmap decrease by 1. Then add the node + entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL, + parameter Value will point to the value of the item. It returns the key of the removed item. + + If Map is NULL, then ASSERT(). + If the Used doubly linked list is empty, then ASSERT(). + + @param[in, out] Map The netmap to remove the head from. + @param[out] Value The variable to receive the value if not NULL. - @return The key of the item removed + @return The key of the item removed. **/ VOID * EFIAPI NetMapRemoveHead ( - IN NET_MAP *Map, - OUT VOID **Value OPTIONAL + IN OUT NET_MAP *Map, + OUT VOID **Value OPTIONAL ); /** - Remove the last entry on the netmap. + Remove the last node entry on the netmap and return the key of the removed item. - @param Map The netmap to remove the tail from - @param Value The variable to receive the value if not NULL + Remove the last node entry from the Used doubly linked list of the netmap. + The number of the pairs in the netmap decrease by 1. Then add the node + entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL, + parameter Value will point to the value of the item. It returns the key of the removed item. + + If Map is NULL, then ASSERT(). + If the Used doubly linked list is empty, then ASSERT(). + + @param[in, out] Map The netmap to remove the tail from. + @param[out] Value The variable to receive the value if not NULL. - @return The key of the item removed + @return The key of the item removed. **/ VOID * EFIAPI NetMapRemoveTail ( - IN NET_MAP *Map, - OUT VOID **Value OPTIONAL + IN OUT NET_MAP *Map, + OUT VOID **Value OPTIONAL ); typedef @@ -558,16 +654,22 @@ EFI_STATUS ); /** - Iterate through the netmap and call CallBack for each item. It will - contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break - from the loop. It returns the CallBack's last return value. This - function is delete safe for the current item. - - @param Map The Map to iterate through - @param CallBack The callback function to call for each item. - @param Arg The opaque parameter to the callback - - @return It returns the CallBack's last return value. + Iterate through the netmap and call CallBack for each item. + + It will contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break + from the loop. It returns the CallBack's last return value. This function is + delete safe for the current item. + + If Map is NULL, then ASSERT(). + If CallBack is NULL, then ASSERT(). + + @param[in] Map The Map to iterate through. + @param[in] CallBack The callback function to call for each item. + @param[in] Arg The opaque parameter to the callback. + + @retval EFI_SUCCESS There is no item in the netmap or CallBack for each item + return EFI_SUCCESS. + @retval Others It returns the CallBack's last return value. **/ EFI_STATUS @@ -575,7 +677,7 @@ EFIAPI NetMapIterate ( IN NET_MAP *Map, IN NET_MAP_CALLBACK CallBack, - IN VOID *Arg OPTIONAL + IN VOID *Arg ); @@ -584,11 +686,16 @@ NetMapIterate ( // /** Create a child of the service that is identified by ServiceBindingGuid. + + Get the ServiceBinding Protocol first, then use it to create a child. - @param ControllerHandle The controller which has the service installed. - @param ImageHandle The image handle used to open service. - @param ServiceBindingGuid The service's Guid. - @param ChildHandle The handle to receive the create child + If ServiceBindingGuid is NULL, then ASSERT(). + If ChildHandle is NULL, then ASSERT(). + + @param[in] Controller The controller which has the service installed. + @param[in] Image The image handle used to open service. + @param[in] ServiceBindingGuid The service's Guid. + @param[in, out] ChildHandle The handle to receive the create child. @retval EFI_SUCCESS The child is successfully created. @retval Others Failed to create the child. @@ -597,19 +704,23 @@ NetMapIterate ( EFI_STATUS EFIAPI NetLibCreateServiceChild ( - IN EFI_HANDLE ControllerHandle, - IN EFI_HANDLE ImageHandle, + IN EFI_HANDLE Controller, + IN EFI_HANDLE Image, IN EFI_GUID *ServiceBindingGuid, - OUT EFI_HANDLE *ChildHandle + IN OUT EFI_HANDLE *ChildHandle ); /** Destory a child of the service that is identified by ServiceBindingGuid. - - @param ControllerHandle The controller which has the service installed. - @param ImageHandle The image handle used to open service. - @param ServiceBindingGuid The service's Guid. - @param ChildHandle The child to destory + + Get the ServiceBinding Protocol first, then use it to destroy a child. + + If ServiceBindingGuid is NULL, then ASSERT(). + + @param[in] Controller The controller which has the service installed. + @param[in] Image The image handle used to open service. + @param[in] ServiceBindingGuid The service's Guid. + @param[in] ChildHandle The child to destory. @retval EFI_SUCCESS The child is successfully destoried. @retval Others Failed to destory the child. @@ -618,8 +729,8 @@ NetLibCreateServiceChild ( EFI_STATUS EFIAPI NetLibDestroyServiceChild ( - IN EFI_HANDLE ControllerHandle, - IN EFI_HANDLE ImageHandle, + IN EFI_HANDLE Controller, + IN EFI_HANDLE Image, IN EFI_GUID *ServiceBindingGuid, IN EFI_HANDLE ChildHandle ); @@ -629,36 +740,47 @@ NetLibDestroyServiceChild ( SnpHandle to a unicode string. Callers are responsible for freeing the string storage. - @param SnpHandle The handle where the simple network protocol is - installed on. - @param ImageHandle The image handle used to act as the agent handle to - get the simple network protocol. - @param MacString The pointer to store the address of the string - representation of the mac address. + Get the mac address of the Simple Network protocol from the SnpHandle. Then convert + the mac address into a unicode string. It takes 2 unicode characters to represent + a 1 byte binary buffer. Plus one unicode character for the null-terminator. + + @param[in] SnpHandle The handle where the simple network protocol is + installed on. + @param[in] ImageHandle The image handle used to act as the agent handle to + get the simple network protocol. + @param[out] MacString The pointer to store the address of the string + representation of the mac address. + + @retval EFI_SUCCESS Convert the mac address a unicode string successfully. @retval EFI_OUT_OF_RESOURCES There are not enough memory resource. - @retval other Failed to open the simple network protocol. + @retval Others Failed to open the simple network protocol. **/ EFI_STATUS EFIAPI NetLibGetMacString ( - IN EFI_HANDLE SnpHandle, - IN EFI_HANDLE ImageHandle, - IN OUT CHAR16 **MacString + IN EFI_HANDLE SnpHandle, + IN EFI_HANDLE ImageHandle, + OUT CHAR16 **MacString ); /** Create an IPv4 device path node. - - @param Node Pointer to the IPv4 device path node. - @param Controller The handle where the NIC IP4 config protocol resides. - @param LocalIp The local IPv4 address. - @param LocalPort The local port. - @param RemoteIp The remote IPv4 address. - @param RemotePort The remote port. - @param Protocol The protocol type in the IP header. - @param UseDefaultAddress Whether this instance is using default address or not. + + The header type of IPv4 device path node is MESSAGING_DEVICE_PATH. + The header subtype of IPv4 device path node is MSG_IPv4_DP. + The length of the IPv4 device path node in bytes is 19. + Get other info from parameters to make up the whole IPv4 device path node. + + @param[in, out] Node Pointer to the IPv4 device path node. + @param[in] Controller The handle where the NIC IP4 config protocol resides. + @param[in] LocalIp The local IPv4 address. + @param[in] LocalPort The local port. + @param[in] RemoteIp The remote IPv4 address. + @param[in] RemotePort The remote port. + @param[in] Protocol The protocol type in the IP header. + @param[in] UseDefaultAddress Whether this instance is using default address or not. **/ VOID @@ -676,6 +798,7 @@ NetLibCreateIPv4DPathNode ( /** Find the UNDI/SNP handle from controller and protocol GUID. + For example, IP will open a MNP child to transmit/receive packets, when MNP is stopped, IP should also be stopped. IP needs to find its own private data which is related the IP's @@ -684,10 +807,10 @@ NetLibCreateIPv4DPathNode ( IP opens these handle BY_DRIVER, use that info, we can get the UNDI/SNP handle. - @param Controller Then protocol handle to check - @param ProtocolGuid The protocol that is related with the handle. + @param[in] Controller Then protocol handle to check. + @param[in] ProtocolGuid The protocol that is related with the handle. - @return The UNDI/SNP handle or NULL. + @return The UNDI/SNP handle or NULL for errors. **/ EFI_HANDLE @@ -700,14 +823,14 @@ NetLibGetNicHandle ( /** Add a Deferred Procedure Call to the end of the DPC queue. - @param DpcTpl The EFI_TPL that the DPC should be invoked. - @param DpcProcedure Pointer to the DPC's function. - @param DpcContext Pointer to the DPC's context. Passed to DpcProcedure - when DpcProcedure is invoked. + @param[in] DpcTpl The EFI_TPL that the DPC should be invoked. + @param[in] DpcProcedure Pointer to the DPC's function. + @param[in] DpcContext Pointer to the DPC's context. Passed to DpcProcedure + when DpcProcedure is invoked. @retval EFI_SUCCESS The DPC was queued. - @retval EFI_INVALID_PARAMETER DpcTpl is not a valid EFI_TPL. - DpcProcedure is NULL. + @retval EFI_INVALID_PARAMETER DpcTpl is not a valid EFI_TPL, or DpcProcedure + is NULL. @retval EFI_OUT_OF_RESOURCES There are not enough resources available to add the DPC to the queue. @@ -721,7 +844,10 @@ NetLibQueueDpc ( ); /** - Add a Deferred Procedure Call to the end of the DPC queue. + Dispatch the queue of DPCs. ALL DPCs that have been queued with a DpcTpl + value greater than or equal to the current TPL are invoked in the order that + they were queued. DPCs with higher DpcTpl values are invoked before DPCs with + lower DpcTpl values. @retval EFI_SUCCESS One or more DPCs were invoked. @retval EFI_NOT_FOUND No DPCs were invoked. @@ -736,7 +862,10 @@ NetLibDispatchDpc ( /** This is the default unload handle for all the network drivers. - @param ImageHandle The drivers' driver image. + Disconnect the driver specified by ImageHandle from all the devices in the handle database. + Uninstall all the protocols installed in the driver entry point. + + @param[in] ImageHandle The drivers' driver image. @retval EFI_SUCCESS The image is unloaded. @retval Others Failed to unload the image. @@ -752,9 +881,9 @@ typedef enum { // //Various signatures // - NET_BUF_SIGNATURE = EFI_SIGNATURE_32 ('n', 'b', 'u', 'f'), - NET_VECTOR_SIGNATURE = EFI_SIGNATURE_32 ('n', 'v', 'e', 'c'), - NET_QUE_SIGNATURE = EFI_SIGNATURE_32 ('n', 'b', 'q', 'u'), + NET_BUF_SIGNATURE = SIGNATURE_32 ('n', 'b', 'u', 'f'), + NET_VECTOR_SIGNATURE = SIGNATURE_32 ('n', 'v', 'e', 'c'), + NET_QUE_SIGNATURE = SIGNATURE_32 ('n', 'b', 'q', 'u'), NET_PROTO_DATA = 64, // Opaque buffer for protocols @@ -897,10 +1026,10 @@ typedef struct { Allocate a single block NET_BUF. Upon allocation, all the free space is in the tail room. - @param Len The length of the block. + @param[in] Len The length of the block. - @retval * Pointer to the allocated NET_BUF. If NULL the - allocation failed due to resource limit. + @return Pointer to the allocated NET_BUF, or NULL if the + allocation failed due to resource limit. **/ NET_BUF * @@ -910,11 +1039,15 @@ NetbufAlloc ( ); /** - Free the buffer and its associated NET_VECTOR. - - @param Nbuf Pointer to the NET_BUF to be freed. - - @return None. + Free the net buffer and its associated NET_VECTOR. + + Decrease the reference count of the net buffer by one. Free the associated net + vector and itself if the reference count of the net buffer is decreased to 0. + The net vector free operation just decrease the reference count of the net + vector by one and do the real resource free operation when the reference count + of the net vector is 0. + + @param[in] Nbuf Pointer to the NET_BUF to be freed. **/ VOID @@ -924,17 +1057,20 @@ NetbufFree ( ); /** - Get the position of some byte in the net buffer. This can be used - to, for example, retrieve the IP header in the packet. It also - returns the fragment that contains the byte which is used mainly by - the buffer implementation itself. + Get the index of NET_BLOCK_OP that contains the byte at Offset in the net + buffer. + + This can be used to, for example, retrieve the IP header in the packet. It + also can be used to get the fragment that contains the byte which is used + mainly by the library implementation itself. - @param Nbuf Pointer to the net buffer. - @param Offset The index or offset of the byte - @param Index Index of the fragment that contains the block + @param[in] Nbuf Pointer to the net buffer. + @param[in] Offset The offset of the byte. + @param[out] Index Index of the NET_BLOCK_OP that contains the byte at + Offset. - @retval * Pointer to the nth byte of data in the net buffer. - If NULL, there is no such data in the net buffer. + @return Pointer to the Offset'th byte of data in the net buffer, or NULL + if there is no such data in the net buffer. **/ UINT8 * @@ -942,57 +1078,66 @@ EFIAPI NetbufGetByte ( IN NET_BUF *Nbuf, IN UINT32 Offset, - OUT UINT32 *Index OPTIONAL + OUT UINT32 *Index OPTIONAL ); /** - Create a copy of NET_BUF that share the associated NET_DATA. + Create a copy of the net buffer that shares the associated net vector. + + The reference count of the newly created net buffer is set to 1. The reference + count of the associated net vector is increased by one. - @param Nbuf Pointer to the net buffer to be cloned. + @param[in] Nbuf Pointer to the net buffer to be cloned. - @retval * Pointer to the cloned net buffer. + @return Pointer to the cloned net buffer, or NULL if the + allocation failed due to resource limit. **/ -NET_BUF * +NET_BUF * EFIAPI NetbufClone ( IN NET_BUF *Nbuf ); /** - Create a duplicated copy of Nbuf, data is copied. Also leave some - head space before the data. - - @param Nbuf Pointer to the net buffer to be cloned. - @param Duplicate Pointer to the net buffer to duplicate to, if NULL - a new net buffer is allocated. - @param HeadSpace Length of the head space to reserve - - @retval * Pointer to the duplicated net buffer. + Create a duplicated copy of the net buffer with data copied and HeadSpace + bytes of head space reserved. + + The duplicated net buffer will allocate its own memory to hold the data of the + source net buffer. + + @param[in] Nbuf Pointer to the net buffer to be duplicated from. + @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if + NULL a new net buffer is allocated. + @param[in] HeadSpace Length of the head space to reserve. + + @return Pointer to the duplicated net buffer, or NULL if + the allocation failed due to resource limit. **/ NET_BUF * EFIAPI NetbufDuplicate ( IN NET_BUF *Nbuf, - IN NET_BUF *Duplicate OPTIONAL, + IN OUT NET_BUF *Duplicate OPTIONAL, IN UINT32 HeadSpace ); /** - Create a NET_BUF structure which contains Len byte data of - Nbuf starting from Offset. A new NET_BUF structure will be - created but the associated data in NET_VECTOR is shared. - This function exists to do IP packet fragmentation. + Create a NET_BUF structure which contains Len byte data of Nbuf starting from + Offset. + + A new NET_BUF structure will be created but the associated data in NET_VECTOR + is shared. This function exists to do IP packet fragmentation. - @param Nbuf Pointer to the net buffer to be cloned. - @param Offset Starting point of the data to be included in new - buffer. - @param Len How many data to include in new data - @param HeadSpace How many bytes of head space to reserve for - protocol header + @param[in] Nbuf Pointer to the net buffer to be extracted. + @param[in] Offset Starting point of the data to be included in the new + net buffer. + @param[in] Len Bytes of data to be included in the new net buffer. + @param[in] HeadSpace Bytes of head space to reserve for protocol header. - @retval * Pointer to the cloned net buffer. + @return Pointer to the cloned net buffer, or NULL if the + allocation failed due to resource limit. **/ NET_BUF * @@ -1005,75 +1150,77 @@ NetbufGetFragment ( ); /** - Reserve some space in the header room of the buffer. - Upon allocation, all the space are in the tail room - of the buffer. Call this function to move some space - to the header room. This function is quite limited in - that it can only reserver space from the first block - of an empty NET_BUF not built from the external. But - it should be enough for the network stack. + Reserve some space in the header room of the net buffer. - @param Nbuf Pointer to the net buffer. - @param Len The length of buffer to be reserverd. + Upon allocation, all the space are in the tail room of the buffer. Call this + function to move some space to the header room. This function is quite limited + in that it can only reserve space from the first block of an empty NET_BUF not + built from the external. But it should be enough for the network stack. - @return None. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of buffer to be reserved from the header. **/ VOID EFIAPI NetbufReserve ( - IN NET_BUF *Nbuf, + IN OUT NET_BUF *Nbuf, IN UINT32 Len ); /** - Allocate some space from the header or tail of the buffer. + Allocate Len bytes of space from the header or tail of the buffer. - @param Nbuf Pointer to the net buffer. - @param Len The length of the buffer to be allocated. - @param FromHead The flag to indicate whether reserve the data from - head or tail. TRUE for from head, and FALSE for - from tail. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of the buffer to be allocated. + @param[in] FromHead The flag to indicate whether reserve the data + from head (TRUE) or tail (FALSE). - @retval * Pointer to the first byte of the allocated buffer. + @return Pointer to the first byte of the allocated buffer, + or NULL if there is no sufficient space. **/ -UINT8 * +UINT8* EFIAPI NetbufAllocSpace ( - IN NET_BUF *Nbuf, + IN OUT NET_BUF *Nbuf, IN UINT32 Len, IN BOOLEAN FromHead ); /** - Trim some data from the header or tail of the buffer. + Trim Len bytes from the header or tail of the net buffer. - @param Nbuf Pointer to the net buffer. - @param Len The length of the data to be trimmed. - @param FromHead The flag to indicate whether trim data from head or - tail. TRUE for from head, and FALSE for from tail. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of the data to be trimmed. + @param[in] FromHead The flag to indicate whether trim data from head + (TRUE) or tail (FALSE). - @retval UINTN Length of the actually trimmed data. + @return Length of the actually trimmed data, which is possible to be less + than Len because the TotalSize of Nbuf is less than Len. **/ UINT32 EFIAPI NetbufTrim ( - IN NET_BUF *Nbuf, + IN OUT NET_BUF *Nbuf, IN UINT32 Len, IN BOOLEAN FromHead ); /** - Copy the data from the specific offset to the destination. - - @param Nbuf Pointer to the net buffer. - @param Offset The sequence number of the first byte to copy. - @param Len Length of the data to copy. - @param Dest The destination of the data to copy to. - - @retval UINTN The length of the copied data. + Copy Len bytes of data from the specific offset of the net buffer to the + destination memory. + + The Len bytes of data may cross the several fragments of the net buffer. + + @param[in] Nbuf Pointer to the net buffer. + @param[in] Offset The sequence number of the first byte to copy. + @param[in] Len Length of the data to copy. + @param[in] Dest The destination of the data to copy to. + + @return The length of the actual copied data, or 0 if the offset + specified exceeds the total size of net buffer. **/ UINT32 @@ -1086,19 +1233,25 @@ NetbufCopy ( ); /** - Build a NET_BUF from external blocks. - - @param ExtFragment Pointer to the data block. - @param ExtNum The number of the data block. - @param HeadSpace The head space to be reserved. - @param HeadLen The length of the protocol header, This function - will pull that number of data into a linear block. - @param ExtFree Pointer to the caller provided free function. - @param Arg The argument passed to ExtFree when ExtFree is - called. - - @retval * Pointer to the net buffer built from the data - blocks. + Build a NET_BUF from external blocks. + + A new NET_BUF structure will be created from external blocks. Additional block + of memory will be allocated to hold reserved HeadSpace bytes of header room + and existing HeadLen bytes of header but the external blocks are shared by the + net buffer to avoid data copying. + + @param[in] ExtFragment Pointer to the data block. + @param[in] ExtNum The number of the data blocks. + @param[in] HeadSpace The head space to be reserved. + @param[in] HeadLen The length of the protocol header, This function + will pull that number of data into a linear block. + @param[in] ExtFree Pointer to the caller provided free function. + @param[in] Arg The argument passed to ExtFree when ExtFree is + called. + + @return Pointer to the net buffer built from the data blocks, + or NULL if the allocation failed due to resource + limit. **/ NET_BUF * @@ -1113,38 +1266,41 @@ NetbufFromExt ( ); /** - Build a fragment table to contain the fragments in the - buffer. This is the opposite of the NetbufFromExt. - - @param Nbuf Point to the net buffer - @param ExtFragment Pointer to the data block. - @param ExtNum The number of the data block. + Build a fragment table to contain the fragments in the net buffer. This is the + opposite operation of the NetbufFromExt. + + @param[in] Nbuf Point to the net buffer. + @param[in, out] ExtFragment Pointer to the data block. + @param[in, out] ExtNum The number of the data blocks. - @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than ExtNum - @retval EFI_SUCCESS Fragment table built. + @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than + ExtNum. + @retval EFI_SUCCESS Fragment table is built successfully. **/ EFI_STATUS EFIAPI NetbufBuildExt ( IN NET_BUF *Nbuf, - IN NET_FRAGMENT *ExtFragment, - IN UINT32 *ExtNum + IN OUT NET_FRAGMENT *ExtFragment, + IN OUT UINT32 *ExtNum ); /** - Build a NET_BUF from a list of NET_BUF. - - @param BufList A List of NET_BUF. - @param HeadSpace The head space to be reserved. - @param HeaderLen The length of the protocol header, This function - will pull that number of data into a linear block. - @param ExtFree Pointer to the caller provided free function. - @param Arg The argument passed to ExtFree when ExtFree is - called. - - @retval * Pointer to the net buffer built from the data - blocks. + Build a net buffer from a list of net buffers. + + All the fragments will be collected from the list of NEW_BUF and then a new + net buffer will be created through NetbufFromExt. + + @param[in] BufList A List of the net buffer. + @param[in] HeadSpace The head space to be reserved. + @param[in] HeaderLen The length of the protocol header, This function + will pull that number of data into a linear block. + @param[in] ExtFree Pointer to the caller provided free function. + @param[in] Arg The argument passed to ExtFree when ExtFree is called. + + @return Pointer to the net buffer built from the list of net + buffers. **/ NET_BUF * @@ -1154,43 +1310,38 @@ NetbufFromBufList ( IN UINT32 HeadSpace, IN UINT32 HeaderLen, IN NET_VECTOR_EXT_FREE ExtFree, - IN VOID *Arg OPTIONAL + IN VOID *Arg OPTIONAL ); /** Free a list of net buffers. - @param Head Pointer to the head of linked net buffers. - - @return None. + @param[in, out] Head Pointer to the head of linked net buffers. **/ VOID EFIAPI NetbufFreeList ( - IN LIST_ENTRY *Head + IN OUT LIST_ENTRY *Head ); /** Initiate the net buffer queue. - @param NbufQue Pointer to the net buffer queue to be initiated. - - @return None. + @param[in, out] NbufQue Pointer to the net buffer queue to be initialized. **/ VOID EFIAPI NetbufQueInit ( - IN NET_BUF_QUEUE *NbufQue + IN OUT NET_BUF_QUEUE *NbufQue ); /** - Allocate an initialized net buffer queue. - - None. + Allocate and initialize a net buffer queue. - @retval * Pointer to the allocated net buffer queue. + @return Pointer to the allocated net buffer queue, or NULL if the + allocation failed due to resource limit. **/ NET_BUF_QUEUE * @@ -1200,11 +1351,13 @@ NetbufQueAlloc ( ); /** - Free a net buffer queue. + Free a net buffer queue. + + Decrease the reference count of the net buffer queue by one. The real resource + free operation isn't performed until the reference count of the net buffer + queue is decreased to 0. - @param NbufQue Poitner to the net buffer queue to be freed. - - @return None. + @param[in] NbufQue Pointer to the net buffer queue to be freed. **/ VOID @@ -1214,45 +1367,48 @@ NetbufQueFree ( ); /** - Remove a net buffer from head in the specific queue. + Remove a net buffer from the head in the specific queue and return it. - @param NbufQue Pointer to the net buffer queue. + @param[in, out] NbufQue Pointer to the net buffer queue. - @retval * Pointer to the net buffer removed from the specific - queue. + @return Pointer to the net buffer removed from the specific queue, + or NULL if there is no net buffer in the specific queue. **/ NET_BUF * EFIAPI NetbufQueRemove ( - IN NET_BUF_QUEUE *NbufQue + IN OUT NET_BUF_QUEUE *NbufQue ); /** - Append a buffer to the end of the queue. + Append a net buffer to the net buffer queue. - @param NbufQue Pointer to the net buffer queue. - @param Nbuf Pointer to the net buffer to be appended. - - @return None. + @param[in, out] NbufQue Pointer to the net buffer queue. + @param[in, out] Nbuf Pointer to the net buffer to be appended. **/ VOID EFIAPI NetbufQueAppend ( - IN NET_BUF_QUEUE *NbufQue, - IN NET_BUF *Nbuf + IN OUT NET_BUF_QUEUE *NbufQue, + IN OUT NET_BUF *Nbuf ); /** - Copy some data from the buffer queue to the destination. - - @param NbufQue Pointer to the net buffer queue. - @param Offset The sequence number of the first byte to copy. - @param Len Length of the data to copy. - @param Dest The destination of the data to copy to. - - @retval UINTN The length of the copied data. + Copy Len bytes of data from the net buffer queue at the specific offset to the + destination memory. + + The copying operation is the same as NetbufCopy but applies to the net buffer + queue instead of the net buffer. + + @param[in] NbufQue Pointer to the net buffer queue. + @param[in] Offset The sequence number of the first byte to copy. + @param[in] Len Length of the data to copy. + @param[out] Dest The destination of the data to copy to. + + @return The length of the actual copied data, or 0 if the offset + specified exceeds the total size of net buffer queue. **/ UINT32 @@ -1261,23 +1417,26 @@ NetbufQueCopy ( IN NET_BUF_QUEUE *NbufQue, IN UINT32 Offset, IN UINT32 Len, - IN UINT8 *Dest + OUT UINT8 *Dest ); /** - Trim some data from the queue header, release the buffer if - whole buffer is trimmed. + Trim Len bytes of data from the queue header, release any of the net buffer + whom is trimmed wholely. + + The trimming operation is the same as NetbufTrim but applies to the net buffer + queue instead of the net buffer. - @param NbufQue Pointer to the net buffer queue. - @param Len Length of the data to trim. + @param[in, out] NbufQue Pointer to the net buffer queue. + @param[in] Len Length of the data to trim. - @retval UINTN The length of the data trimmed. + @return The actual length of the data trimmed. **/ UINT32 EFIAPI NetbufQueTrim ( - IN NET_BUF_QUEUE *NbufQue, + IN OUT NET_BUF_QUEUE *NbufQue, IN UINT32 Len ); @@ -1285,24 +1444,22 @@ NetbufQueTrim ( /** Flush the net buffer queue. - @param NbufQue Pointer to the queue to be flushed. - - @return None. + @param[in, out] NbufQue Pointer to the queue to be flushed. **/ VOID EFIAPI NetbufQueFlush ( - IN NET_BUF_QUEUE *NbufQue + IN OUT NET_BUF_QUEUE *NbufQue ); /** - Compute checksum for a bulk of data. + Compute the checksum for a bulk of data. - @param Bulk Pointer to the data. - @param Len Length of the data, in bytes. + @param[in] Bulk Pointer to the data. + @param[in] Len Length of the data, in bytes. - @retval UINT16 The computed checksum. + @return The computed checksum. **/ UINT16 @@ -1315,10 +1472,10 @@ NetblockChecksum ( /** Add two checksums. - @param Checksum1 The first checksum to be added. - @param Checksum2 The second checksum to be added. + @param[in] Checksum1 The first checksum to be added. + @param[in] Checksum2 The second checksum to be added. - @retval UINT16 The new checksum. + @return The new checksum. **/ UINT16 @@ -1331,9 +1488,9 @@ NetAddChecksum ( /** Compute the checksum for a NET_BUF. - @param Nbuf Pointer to the net buffer. + @param[in] Nbuf Pointer to the net buffer. - @retval UINT16 The computed checksum. + @return The computed checksum. **/ UINT16 @@ -1343,16 +1500,16 @@ NetbufChecksum ( ); /** - Compute the checksum for TCP/UDP pseudo header. - Src, Dst are in network byte order. and Len is - in host byte order. + Compute the checksum for TCP/UDP pseudo header. + + Src and Dst are in network byte order, and Len is in host byte order. - @param Src The source address of the packet. - @param Dst The destination address of the packet. - @param Proto The protocol type of the packet. - @param Len The length of the packet. + @param[in] Src The source address of the packet. + @param[in] Dst The destination address of the packet. + @param[in] Proto The protocol type of the packet. + @param[in] Len The length of the packet. - @retval UINT16 The computed checksum. + @return The computed checksum. **/ UINT16