This library is only intended to be used by UEFI network stack modules.\r
It provides basic functions for the UEFI network stack.\r
\r
-Copyright (c) 2005 - 2010, Intel Corporation\r
-All rights reserved. This program and the accompanying materials\r
+Copyright (c) 2005 - 2017, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution. The full text of the license may be found at\r
+which accompanies this distribution. The full text of the license may be found at<BR>\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
#include <Protocol/Ip6.h>\r
\r
#include <Library/BaseLib.h>\r
+#include <Library/BaseMemoryLib.h>\r
\r
typedef UINT32 IP4_ADDR;\r
typedef UINT32 TCP_SEQNO;\r
#define EFI_IP_PROTO_ICMP 0x01\r
#define IP4_PROTO_IGMP 0x02\r
#define IP6_ICMP 58\r
+#define DNS_MAX_NAME_SIZE 255\r
+#define DNS_MAX_MESSAGE_SIZE 512\r
\r
//\r
// The address classification\r
//\r
-#define IP4_ADDR_CLASSA 1\r
-#define IP4_ADDR_CLASSB 2\r
-#define IP4_ADDR_CLASSC 3\r
+#define IP4_ADDR_CLASSA 1 // Deprecated\r
+#define IP4_ADDR_CLASSB 2 // Deprecated\r
+#define IP4_ADDR_CLASSC 3 // Deprecated\r
#define IP4_ADDR_CLASSD 4\r
#define IP4_ADDR_CLASSE 5\r
\r
#define IP4_MASK_NUM 33\r
#define IP6_PREFIX_NUM 129\r
\r
+#define IP4_MASK_MAX 32 \r
+#define IP6_PREFIX_MAX 128\r
+\r
#define IP6_HOP_BY_HOP 0\r
#define IP6_DESTINATION 60\r
+#define IP6_ROUTING 43\r
#define IP6_FRAGMENT 44\r
#define IP6_AH 51\r
#define IP6_ESP 50\r
#define IP_VERSION_4 4\r
#define IP_VERSION_6 6\r
\r
+#define IP6_PREFIX_LENGTH 64\r
+\r
+//\r
+// DNS QTYPE values\r
+//\r
+#define DNS_TYPE_A 1\r
+#define DNS_TYPE_NS 2\r
+#define DNS_TYPE_CNAME 5\r
+#define DNS_TYPE_SOA 6\r
+#define DNS_TYPE_WKS 11\r
+#define DNS_TYPE_PTR 12\r
+#define DNS_TYPE_HINFO 13\r
+#define DNS_TYPE_MINFO 14\r
+#define DNS_TYPE_MX 15\r
+#define DNS_TYPE_TXT 16\r
+#define DNS_TYPE_AAAA 28\r
+#define DNS_TYPE_SRV_RR 33\r
+#define DNS_TYPE_AXFR 252\r
+#define DNS_TYPE_MAILB 253\r
+#define DNS_TYPE_ANY 255\r
+\r
+//\r
+// DNS QCLASS values\r
+//\r
+#define DNS_CLASS_INET 1\r
+#define DNS_CLASS_CH 3\r
+#define DNS_CLASS_HS 4\r
+#define DNS_CLASS_ANY 255\r
+\r
#pragma pack(1)\r
\r
//\r
// Test the IP's attribute, All the IPs are in host byte order.\r
//\r
#define IP4_IS_MULTICAST(Ip) (((Ip) & 0xF0000000) == 0xE0000000)\r
+#define IP4_IS_UNSPECIFIED(Ip) ((Ip) == 0)\r
#define IP4_IS_LOCAL_BROADCAST(Ip) ((Ip) == 0xFFFFFFFF)\r
#define IP4_NET_EQUAL(Ip1, Ip2, NetMask) (((Ip1) & (NetMask)) == ((Ip2) & (NetMask)))\r
-#define IP4_IS_VALID_NETMASK(Ip) (NetGetMaskLength (Ip) != IP4_MASK_NUM)\r
+#define IP4_IS_VALID_NETMASK(Ip) (NetGetMaskLength (Ip) != (IP4_MASK_MAX + 1))\r
\r
#define IP6_IS_MULTICAST(Ip6) (((Ip6)->Addr[0]) == 0xFF)\r
\r
\r
#define EFI_IP6_EQUAL(Ip1, Ip2) (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv6_ADDRESS)) == 0)\r
\r
+#define IP4_COPY_ADDRESS(Dest, Src) (CopyMem ((Dest), (Src), sizeof (EFI_IPv4_ADDRESS)))\r
#define IP6_COPY_ADDRESS(Dest, Src) (CopyMem ((Dest), (Src), sizeof (EFI_IPv6_ADDRESS)))\r
#define IP6_COPY_LINK_ADDRESS(Mac1, Mac2) (CopyMem ((Mac1), (Mac2), sizeof (EFI_MAC_ADDRESS)))\r
\r
//\r
// The debug level definition. This value is also used as the\r
-// syslog's servity level. Don't change it.\r
+// syslog's severity level. Don't change it.\r
//\r
#define NETDEBUG_LEVEL_TRACE 5\r
#define NETDEBUG_LEVEL_WARNING 4\r
by the Format string.\r
\r
@return The buffer containing the formatted message,\r
- or NULL if failed to allocate memory.\r
+ or NULL if memory allocation failed.\r
\r
**/\r
CHAR8 *\r
+EFIAPI\r
NetDebugASPrint (\r
IN CHAR8 *Format,\r
...\r
This function will locate a instance of SNP then send the message through it.\r
Because it isn't open the SNP BY_DRIVER, apply caution when using it.\r
\r
- @param Level The servity level of the message.\r
- @param Module The Moudle that generates the log.\r
+ @param Level The severity level of the message.\r
+ @param Module The Module that generates the log.\r
@param File The file that contains the log.\r
@param Line The exact line that contains the log.\r
@param Message The user message to log.\r
than the mNetDebugLevelMax. Or, it has been sent out.\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetDebugOutput (\r
IN UINT32 Level,\r
IN UINT8 *Module,\r
Return the class of the IP address, such as class A, B, C.\r
Addr is in host byte order.\r
\r
+ [ATTENTION]\r
+ Classful addressing (IP class A/B/C) has been deprecated according to RFC4632.\r
+ Caller of this function could only check the returned value against\r
+ IP4_ADDR_CLASSD (multicast) or IP4_ADDR_CLASSE (reserved) now.\r
+\r
The address of class A starts with 0.\r
If the address belong to class A, return IP4_ADDR_CLASSA.\r
The address of class B starts with 10.\r
\r
/**\r
Check whether the IP is a valid unicast address according to\r
- the netmask. If NetMask is zero, use the IP address's class to get the default mask.\r
-\r
- If Ip is 0, IP is not a valid unicast address.\r
- Class D address is used for multicasting and class E address is reserved for future. If Ip\r
- belongs to class D or class E, Ip is not a valid unicast address.\r
- If all bits of the host address of Ip are 0 or 1, Ip is not a valid unicast address.\r
-\r
+ the netmask. \r
+\r
+ ASSERT if NetMask is zero.\r
+ \r
+ If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address,\r
+ except when the originator is one of the endpoints of a point-to-point link with a 31-bit\r
+ mask (RFC3021).\r
+ \r
@param[in] Ip The IP to check against.\r
@param[in] NetMask The mask of the IP.\r
\r
- @return TRUE if Ip is a valid unicast address on the network, otherwise FALSE.\r
+ @return TRUE if IP is a valid unicast address on the network, otherwise FALSE.\r
\r
**/\r
BOOLEAN\r
\r
**/\r
BOOLEAN\r
+EFIAPI\r
NetIp6IsValidUnicast (\r
IN EFI_IPv6_ADDRESS *Ip6\r
);\r
\r
@param[in] Ip6 - Ip6 address, in network order.\r
\r
- @retval TRUE - Yes, unspecified\r
- @retval FALSE - No\r
+ @retval TRUE - Yes, incoming Ipv6 address is the unspecified address.\r
+ @retval FALSE - The incoming Ipv6 address is not the unspecified address\r
\r
**/\r
BOOLEAN\r
+EFIAPI\r
NetIp6IsUnspecifiedAddr (\r
IN EFI_IPv6_ADDRESS *Ip6\r
);\r
\r
@param[in] Ip6 - Ip6 address, in network order.\r
\r
- @retval TRUE - Yes, link-local address\r
- @retval FALSE - No\r
+ @retval TRUE - The incoming Ipv6 address is a link-local address.\r
+ @retval FALSE - The incoming Ipv6 address is not a link-local address.\r
\r
**/\r
BOOLEAN\r
+EFIAPI\r
NetIp6IsLinkLocalAddr (\r
IN EFI_IPv6_ADDRESS *Ip6\r
);\r
@param[in] Ip2 - Ip6 address2, in network order.\r
@param[in] PrefixLength - The prefix length of the checking net.\r
\r
- @retval TRUE - Yes, connected.\r
- @retval FALSE - No.\r
+ @retval TRUE - Yes, the Ipv6 address1 and address2 are connected.\r
+ @retval FALSE - No the Ipv6 address1 and address2 are not connected.\r
\r
**/\r
BOOLEAN\r
+EFIAPI\r
NetIp6IsNetEqual (\r
EFI_IPv6_ADDRESS *Ip1,\r
EFI_IPv6_ADDRESS *Ip2,\r
);\r
\r
/**\r
- Switches the endianess of an IPv6 address\r
+ Switches the endianess of an IPv6 address.\r
\r
This function swaps the bytes in a 128-bit IPv6 address to switch the value\r
from little endian to big endian or vice versa. The byte swapped value is\r
returned.\r
\r
- @param Ip6 Points to an IPv6 address\r
+ @param Ip6 Points to an IPv6 address.\r
\r
@return The byte swapped IPv6 address.\r
\r
**/\r
EFI_IPv6_ADDRESS *\r
+EFIAPI\r
Ip6Swap128 (\r
EFI_IPv6_ADDRESS *Ip6\r
);\r
extern EFI_IPv4_ADDRESS mZeroIp4Addr;\r
\r
#define NET_IS_DIGIT(Ch) (('0' <= (Ch)) && ((Ch) <= '9'))\r
+#define NET_IS_HEX(Ch) ((('0' <= (Ch)) && ((Ch) <= '9')) || (('A' <= (Ch)) && ((Ch) <= 'F')) || (('a' <= (Ch)) && ((Ch) <= 'f')))\r
#define NET_ROUNDUP(size, unit) (((size) + (unit) - 1) & (~((unit) - 1)))\r
#define NET_IS_LOWER_CASE_CHAR(Ch) (('a' <= (Ch)) && ((Ch) <= 'z'))\r
#define NET_IS_UPPER_CASE_CHAR(Ch) (('A' <= (Ch)) && ((Ch) <= 'Z'))\r
/**\r
Puts a UINT32 into the byte stream in network byte order.\r
\r
- Converts a UINT32 from host byte order to network byte order, and then copies it to the\r
+ Converts a UINT32 from host byte order to network byte order, then copies it to the\r
byte stream.\r
\r
- @param[in, out] Buf The buffer to put the UINT32.\r
- @param[in] Data The data to put.\r
+ @param[in, out] Buf The buffer in which to put the UINT32.\r
+ @param[in] Data The data to be converted and put into the byte stream.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Initialize a random seed using current time.\r
+ Initialize a random seed using current time and monotonic count.\r
\r
- Get current time first. Then initialize a random seed based on some basic\r
- mathematical operations on the hour, day, minute, second, nanosecond and year\r
- of the current time.\r
+ Get current time and monotonic count first. Then initialize a random seed \r
+ based on some basic mathematics operation on the hour, day, minute, second,\r
+ nanosecond and year of the current time and the monotonic count value.\r
\r
- @return The random seed, initialized with current time.\r
+ @return The random seed initialized with current time.\r
\r
**/\r
UINT32\r
IN OUT LIST_ENTRY *NewEntry\r
);\r
\r
+/**\r
+ Callback function which provided by user to remove one node in NetDestroyLinkList process.\r
+ \r
+ @param[in] Entry The entry to be removed.\r
+ @param[in] Context Pointer to the callback context corresponds to the Context in NetDestroyLinkList.\r
+\r
+ @retval EFI_SUCCESS The entry has been removed successfully.\r
+ @retval Others Fail to remove the entry.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *NET_DESTROY_LINK_LIST_CALLBACK) (\r
+ IN LIST_ENTRY *Entry,\r
+ IN VOID *Context OPTIONAL\r
+ );\r
+\r
+/**\r
+ Safe destroy nodes in a linked list, and return the length of the list after all possible operations finished.\r
+\r
+ Destroy network children list by list traversals is not safe due to graph dependencies between nodes.\r
+ This function performs a safe traversal to destroy these nodes by checking to see if the node being destroyed\r
+ has been removed from the list or not.\r
+ If it has been removed, then restart the traversal from the head.\r
+ If it hasn't been removed, then continue with the next node directly.\r
+ This function will end the iterate and return the CallBack's last return value if error happens,\r
+ or retrun EFI_SUCCESS if 2 complete passes are made with no changes in the number of children in the list. \r
+\r
+ @param[in] List The head of the list.\r
+ @param[in] CallBack Pointer to the callback function to destroy one node in the list.\r
+ @param[in] Context Pointer to the callback function's context: corresponds to the\r
+ parameter Context in NET_DESTROY_LINK_LIST_CALLBACK.\r
+ @param[out] ListLength The length of the link list if the function returns successfully.\r
+\r
+ @retval EFI_SUCCESS Two complete passes are made with no changes in the number of children.\r
+ @retval EFI_INVALID_PARAMETER The input parameter is invalid.\r
+ @retval Others Return the CallBack's last return value.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+NetDestroyLinkList (\r
+ IN LIST_ENTRY *List,\r
+ IN NET_DESTROY_LINK_LIST_CALLBACK CallBack,\r
+ IN VOID *Context, OPTIONAL\r
+ OUT UINTN *ListLength OPTIONAL\r
+ );\r
+\r
+/**\r
+ This function checks the input Handle to see if it's one of these handles in ChildHandleBuffer.\r
+\r
+ @param[in] Handle Handle to be checked.\r
+ @param[in] NumberOfChildren Number of Handles in ChildHandleBuffer.\r
+ @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL\r
+ if NumberOfChildren is 0.\r
+\r
+ @retval TRUE Found the input Handle in ChildHandleBuffer.\r
+ @retval FALSE Can't find the input Handle in ChildHandleBuffer.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+NetIsInHandleBuffer (\r
+ IN EFI_HANDLE Handle,\r
+ IN UINTN NumberOfChildren,\r
+ IN EFI_HANDLE *ChildHandleBuffer OPTIONAL\r
+ );\r
\r
//\r
// Object container: EFI network stack spec defines various kinds of\r
\r
typedef\r
EFI_STATUS\r
-(*NET_MAP_CALLBACK) (\r
+(EFIAPI *NET_MAP_CALLBACK) (\r
IN NET_MAP *Map,\r
IN NET_MAP_ITEM *Item,\r
IN VOID *Arg\r
/**\r
Iterate through the netmap and call CallBack for each item.\r
\r
- It will contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break\r
+ It will continue the traverse if CallBack returns EFI_SUCCESS, otherwise, break\r
from the loop. It returns the CallBack's last return value. This function is\r
delete safe for the current item.\r
\r
@param[in] CallBack The callback function to call for each item.\r
@param[in] Arg The opaque parameter to the callback.\r
\r
- @retval EFI_SUCCESS There is no item in the netmap or CallBack for each item\r
- return EFI_SUCCESS.\r
+ @retval EFI_SUCCESS There is no item in the netmap, or CallBack for each item\r
+ returns EFI_SUCCESS.\r
@retval Others It returns the CallBack's last return value.\r
\r
**/\r
@param[in] ServiceBindingGuid The service's Guid.\r
@param[in] ChildHandle The child to destroy.\r
\r
- @retval EFI_SUCCESS The child is successfully destroyed.\r
+ @retval EFI_SUCCESS The child was destroyed.\r
@retval Others Failed to destroy the child.\r
\r
**/\r
@param[out] MacAddress The pointer to store the returned MAC address.\r
@param[out] AddressSize The length of returned MAC address.\r
\r
- @retval EFI_SUCCESS MAC address is returned successfully.\r
+ @retval EFI_SUCCESS MAC address was returned successfully.\r
@retval Others Failed to get SNP mode data.\r
\r
**/\r
Plus one unicode character for the null-terminator.\r
\r
@param[in] ServiceHandle The handle where network service binding protocol is\r
- installed on.\r
+ installed.\r
@param[in] ImageHandle The image handle used to act as the agent handle to\r
- get the simple network protocol.\r
+ get the simple network protocol. This parameter is\r
+ optional and may be NULL.\r
@param[out] MacString The pointer to store the address of the string\r
representation of the mac address.\r
\r
- @retval EFI_SUCCESS Convert the mac address a unicode string successfully.\r
- @retval EFI_OUT_OF_RESOURCES There are not enough memory resource.\r
+ @retval EFI_SUCCESS Converted the mac address a unicode string successfully.\r
+ @retval EFI_OUT_OF_RESOURCES There are not enough memory resources.\r
@retval Others Failed to open the simple network protocol.\r
\r
**/\r
EFIAPI\r
NetLibGetMacString (\r
IN EFI_HANDLE ServiceHandle,\r
- IN EFI_HANDLE ImageHandle,\r
+ IN EFI_HANDLE ImageHandle, OPTIONAL\r
OUT CHAR16 **MacString\r
);\r
\r
+/**\r
+ Detect media status for specified network device.\r
+\r
+ The underlying UNDI driver may or may not support reporting media status from\r
+ GET_STATUS command (PXE_STATFLAGS_GET_STATUS_NO_MEDIA_SUPPORTED). This routine\r
+ will try to invoke Snp->GetStatus() to get the media status. If media is already\r
+ present, it returns directly. If media is not present, it will stop SNP and then\r
+ restart SNP to get the latest media status. This provides an opportunity to get \r
+ the correct media status for old UNDI driver, which doesn't support reporting \r
+ media status from GET_STATUS command.\r
+ Note: there are two limitations for the current algorithm:\r
+ 1) For UNDI with this capability, when the cable is not attached, there will\r
+ be an redundant Stop/Start() process.\r
+ 2) for UNDI without this capability, in case that network cable is attached when\r
+ Snp->Initialize() is invoked while network cable is unattached later,\r
+ NetLibDetectMedia() will report MediaPresent as TRUE, causing upper layer\r
+ apps to wait for timeout time.\r
+\r
+ @param[in] ServiceHandle The handle where network service binding protocols are\r
+ installed.\r
+ @param[out] MediaPresent The pointer to store the media status.\r
+\r
+ @retval EFI_SUCCESS Media detection success.\r
+ @retval EFI_INVALID_PARAMETER ServiceHandle is not a valid network device handle.\r
+ @retval EFI_UNSUPPORTED The network device does not support media detection.\r
+ @retval EFI_DEVICE_ERROR SNP is in an unknown state.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+NetLibDetectMedia (\r
+ IN EFI_HANDLE ServiceHandle,\r
+ OUT BOOLEAN *MediaPresent\r
+ );\r
+\r
/**\r
Create an IPv4 device path node.\r
\r
The header type of IPv4 device path node is MESSAGING_DEVICE_PATH.\r
The header subtype of IPv4 device path node is MSG_IPv4_DP.\r
The length of the IPv4 device path node in bytes is 19.\r
- Get other info from parameters to make up the whole IPv4 device path node.\r
+ Get other information from parameters to make up the whole IPv4 device path node.\r
\r
- @param[in, out] Node Pointer to the IPv4 device path node.\r
+ @param[in, out] Node The pointer to the IPv4 device path node.\r
@param[in] Controller The controller handle.\r
@param[in] LocalIp The local IPv4 address.\r
@param[in] LocalPort The local port.\r
The header type of IPv6 device path node is MESSAGING_DEVICE_PATH.\r
The header subtype of IPv6 device path node is MSG_IPv6_DP.\r
The length of the IPv6 device path node in bytes is 43.\r
- Get other info from parameters to make up the whole IPv6 device path node.\r
+ Get other information from parameters to make up the whole IPv6 device path node.\r
\r
- @param[in, out] Node Pointer to the IPv6 device path node.\r
+ @param[in, out] Node The pointer to the IPv6 device path node.\r
@param[in] Controller The controller handle.\r
@param[in] LocalIp The local IPv6 address.\r
@param[in] LocalPort The local port.\r
\r
For example, IP will open an MNP child to transmit/receive\r
packets. When MNP is stopped, IP should also be stopped. IP\r
- needs to find its own private data which is related the IP's\r
- service binding instance that is install on UNDI/SNP handle.\r
- Now, the controller is either a MNP or ARP child handle. But\r
- IP opens these handle BY_DRIVER, use that info, we can get the\r
+ needs to find its own private data that is related the IP's\r
+ service binding instance that is installed on the UNDI/SNP handle.\r
+ The controller is then either an MNP or an ARP child handle. Note that\r
+ IP opens these handles using BY_DRIVER. Use that information to get the\r
UNDI/SNP handle.\r
\r
- @param[in] Controller Then protocol handle to check.\r
+ @param[in] Controller The protocol handle to check.\r
@param[in] ProtocolGuid The protocol that is related with the handle.\r
\r
@return The UNDI/SNP handle or NULL for errors.\r
@param[in] String The pointer to the Ascii string.\r
@param[out] Ip4Address The pointer to the converted IPv4 address.\r
\r
- @retval EFI_SUCCESS Convert to IPv4 address successfully. \r
- @retval EFI_INVALID_PARAMETER The string is mal-formated or Ip4Address is NULL.\r
+ @retval EFI_SUCCESS Converted to an IPv4 address successfully.\r
+ @retval EFI_INVALID_PARAMETER The string is malformatted, or Ip4Address is NULL.\r
\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetLibAsciiStrToIp4 (\r
IN CONST CHAR8 *String,\r
OUT EFI_IPv4_ADDRESS *Ip4Address\r
\r
/**\r
Convert one Null-terminated ASCII string to EFI_IPv6_ADDRESS. The format of the\r
- string is defined in RFC 4291 - Text Pepresentation of Addresses.\r
+ string is defined in RFC 4291 - Text Representation of Addresses.\r
\r
@param[in] String The pointer to the Ascii string.\r
@param[out] Ip6Address The pointer to the converted IPv6 address.\r
\r
- @retval EFI_SUCCESS Convert to IPv6 address successfully. \r
- @retval EFI_INVALID_PARAMETER The string is mal-formated or Ip6Address is NULL.\r
+ @retval EFI_SUCCESS Converted to an IPv6 address successfully.\r
+ @retval EFI_INVALID_PARAMETER The string is malformatted, or Ip6Address is NULL.\r
\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetLibAsciiStrToIp6 (\r
IN CONST CHAR8 *String,\r
OUT EFI_IPv6_ADDRESS *Ip6Address\r
@param[in] String The pointer to the Ascii string.\r
@param[out] Ip4Address The pointer to the converted IPv4 address.\r
\r
- @retval EFI_SUCCESS Convert to IPv4 address successfully. \r
- @retval EFI_INVALID_PARAMETER The string is mal-formated or Ip4Address is NULL.\r
- @retval EFI_OUT_OF_RESOURCES Fail to perform the operation due to lack of resource.\r
+ @retval EFI_SUCCESS Converted to an IPv4 address successfully.\r
+ @retval EFI_INVALID_PARAMETER The string is mal-formatted or Ip4Address is NULL.\r
\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetLibStrToIp4 (\r
IN CONST CHAR16 *String,\r
OUT EFI_IPv4_ADDRESS *Ip4Address\r
\r
/**\r
Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS. The format of\r
- the string is defined in RFC 4291 - Text Pepresentation of Addresses.\r
+ the string is defined in RFC 4291 - Text Representation of Addresses.\r
\r
@param[in] String The pointer to the Ascii string.\r
@param[out] Ip6Address The pointer to the converted IPv6 address.\r
\r
- @retval EFI_SUCCESS Convert to IPv6 address successfully. \r
- @retval EFI_INVALID_PARAMETER The string is mal-formated or Ip6Address is NULL.\r
- @retval EFI_OUT_OF_RESOURCES Fail to perform the operation due to lack of resource.\r
+ @retval EFI_SUCCESS Converted to an IPv6 address successfully.\r
+ @retval EFI_INVALID_PARAMETER The string is malformatted or Ip6Address is NULL.\r
\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetLibStrToIp6 (\r
IN CONST CHAR16 *String,\r
OUT EFI_IPv6_ADDRESS *Ip6Address\r
\r
/**\r
Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS and prefix length.\r
- The format of the string is defined in RFC 4291 - Text Pepresentation of Addresses\r
+ The format of the string is defined in RFC 4291 - Text Representation of Addresses\r
Prefixes: ipv6-address/prefix-length.\r
\r
@param[in] String The pointer to the Ascii string.\r
@param[out] Ip6Address The pointer to the converted IPv6 address.\r
@param[out] PrefixLength The pointer to the converted prefix length.\r
\r
- @retval EFI_SUCCESS Convert to IPv6 address successfully. \r
- @retval EFI_INVALID_PARAMETER The string is mal-formated or Ip6Address is NULL.\r
- @retval EFI_OUT_OF_RESOURCES Fail to perform the operation due to lack of resource.\r
+ @retval EFI_SUCCESS Converted to an IPv6 address successfully.\r
+ @retval EFI_INVALID_PARAMETER The string is malformatted, or Ip6Address is NULL.\r
\r
**/\r
EFI_STATUS\r
+EFIAPI\r
NetLibStrToIp6andPrefix (\r
IN CONST CHAR16 *String,\r
OUT EFI_IPv6_ADDRESS *Ip6Address,\r
OUT UINT8 *PrefixLength\r
);\r
\r
+/**\r
+\r
+ Convert one EFI_IPv6_ADDRESS to Null-terminated Unicode string.\r
+ The text representation of address is defined in RFC 4291.\r
+ \r
+ @param[in] Ip6Address The pointer to the IPv6 address.\r
+ @param[out] String The buffer to return the converted string.\r
+ @param[in] StringSize The length in bytes of the input String.\r
+ \r
+ @retval EFI_SUCCESS Convert to string successfully.\r
+ @retval EFI_INVALID_PARAMETER The input parameter is invalid.\r
+ @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small for the result. BufferSize has been \r
+ updated with the size needed to complete the request.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+NetLibIp6ToStr (\r
+ IN EFI_IPv6_ADDRESS *Ip6Address,\r
+ OUT CHAR16 *String,\r
+ IN UINTN StringSize\r
+ );\r
+\r
//\r
// Various signatures\r
//\r
UINT8 *Bulk; // The block's Data\r
} NET_BLOCK;\r
\r
-typedef VOID (*NET_VECTOR_EXT_FREE) (VOID *Arg);\r
+typedef VOID (EFIAPI *NET_VECTOR_EXT_FREE) (VOID *Arg);\r
\r
//\r
//NET_VECTOR contains several blocks to hold all packet's\r
UINT32 Signature;\r
INTN RefCnt; // Reference count to share NET_VECTOR.\r
NET_VECTOR_EXT_FREE Free; // external function to free NET_VECTOR\r
- VOID *Arg; // opeque argument to Free\r
+ VOID *Arg; // opaque argument to Free\r
UINT32 Flag; // Flags, NET_VECTOR_OWN_FIRST\r
- UINT32 Len; // Total length of the assocated BLOCKs\r
+ UINT32 Len; // Total length of the associated BLOCKs\r
\r
UINT32 BlockNum;\r
NET_BLOCK Block[1];\r
(sizeof (NET_BUF) + ((BlockOpNum) - 1) * sizeof (NET_BLOCK_OP))\r
\r
#define NET_HEADSPACE(BlockOp) \\r
- (UINTN)((BlockOp)->Head - (BlockOp)->BlockHead)\r
+ ((UINTN)((BlockOp)->Head) - (UINTN)((BlockOp)->BlockHead))\r
\r
#define NET_TAILSPACE(BlockOp) \\r
- (UINTN)((BlockOp)->BlockTail - (BlockOp)->Tail)\r
+ ((UINTN)((BlockOp)->BlockTail) - (UINTN)((BlockOp)->Tail))\r
\r
/**\r
Allocate a single block NET_BUF. Upon allocation, all the\r
\r
@param[in] Len The length of the block.\r
\r
- @return Pointer to the allocated NET_BUF, or NULL if the\r
- allocation failed due to resource limit.\r
+ @return The pointer to the allocated NET_BUF, or NULL if the\r
+ allocation failed due to resource limitations.\r
\r
**/\r
NET_BUF *\r
vector by one, and performs the resource free operation when the reference count\r
of the net vector is 0.\r
\r
- @param[in] Nbuf Pointer to the NET_BUF to be freed.\r
+ @param[in] Nbuf The pointer to the NET_BUF to be freed.\r
\r
**/\r
VOID\r
also can be used to get the fragment that contains the byte used\r
mainly by the library implementation itself.\r
\r
- @param[in] Nbuf Pointer to the net buffer.\r
+ @param[in] Nbuf The pointer to the net buffer.\r
@param[in] Offset The offset of the byte.\r
@param[out] Index Index of the NET_BLOCK_OP that contains the byte at\r
Offset.\r
\r
- @return Pointer to the Offset'th byte of data in the net buffer, or NULL\r
+ @return The pointer to the Offset'th byte of data in the net buffer, or NULL\r
if there is no such data in the net buffer.\r
\r
**/\r
The reference count of the newly created net buffer is set to 1. The reference\r
count of the associated net vector is increased by one.\r
\r
- @param[in] Nbuf Pointer to the net buffer to be cloned.\r
+ @param[in] Nbuf The pointer to the net buffer to be cloned.\r
\r
- @return Pointer to the cloned net buffer, or NULL if the\r
- allocation failed due to resource limit.\r
+ @return The pointer to the cloned net buffer, or NULL if the\r
+ allocation failed due to resource limitations.\r
\r
**/\r
NET_BUF *\r
The duplicated net buffer will allocate its own memory to hold the data of the\r
source net buffer.\r
\r
- @param[in] Nbuf Pointer to the net buffer to be duplicated from.\r
- @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if\r
- NULL a new net buffer is allocated.\r
- @param[in] HeadSpace Length of the head space to reserve.\r
+ @param[in] Nbuf The pointer to the net buffer to be duplicated from.\r
+ @param[in, out] Duplicate The pointer to the net buffer to duplicate to. If\r
+ NULL, a new net buffer is allocated.\r
+ @param[in] HeadSpace The length of the head space to reserve.\r
\r
- @return Pointer to the duplicated net buffer, or NULL if\r
- the allocation failed due to resource limit.\r
+ @return The pointer to the duplicated net buffer, or NULL if\r
+ the allocation failed due to resource limitations.\r
\r
**/\r
NET_BUF *\r
Offset.\r
\r
A new NET_BUF structure will be created but the associated data in NET_VECTOR\r
- is shared. This function exists to do IP packet fragmentation.\r
+ is shared. This function exists to perform IP packet fragmentation.\r
\r
- @param[in] Nbuf Pointer to the net buffer to be extracted.\r
+ @param[in] Nbuf The pointer to the net buffer to be extracted.\r
@param[in] Offset Starting point of the data to be included in the new\r
net buffer.\r
- @param[in] Len Bytes of data to be included in the new net buffer.\r
- @param[in] HeadSpace Bytes of head space to reserve for protocol header.\r
+ @param[in] Len The bytes of data to be included in the new net buffer.\r
+ @param[in] HeadSpace The bytes of the head space to reserve for the protocol header.\r
\r
- @return Pointer to the cloned net buffer, or NULL if the\r
- allocation failed due to resource limit.\r
+ @return The pointer to the cloned net buffer, or NULL if the\r
+ allocation failed due to resource limitations.\r
\r
**/\r
NET_BUF *\r
Reserve some space in the header room of the net buffer.\r
\r
Upon allocation, all the space is in the tail room of the buffer. Call this\r
- function to move some space to the header room. This function is quite limited\r
+ function to move space to the header room. This function is quite limited\r
in that it can only reserve space from the first block of an empty NET_BUF not\r
- built from the external. But it should be enough for the network stack.\r
+ built from the external. However, it should be enough for the network stack.\r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in, out] Nbuf The pointer to the net buffer.\r
@param[in] Len The length of buffer to be reserved from the header.\r
\r
**/\r
/**\r
Allocate Len bytes of space from the header or tail of the buffer.\r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in, out] Nbuf The pointer to the net buffer.\r
@param[in] Len The length of the buffer to be allocated.\r
- @param[in] FromHead The flag to indicate whether reserve the data\r
+ @param[in] FromHead The flag to indicate whether to reserve the data\r
from head (TRUE) or tail (FALSE).\r
\r
- @return Pointer to the first byte of the allocated buffer,\r
- or NULL if there is no sufficient space.\r
+ @return The pointer to the first byte of the allocated buffer,\r
+ or NULL, if there is no sufficient space.\r
\r
**/\r
UINT8*\r
);\r
\r
/**\r
- Trim Len bytes from the header or tail of the net buffer.\r
+ Trim Len bytes from the header or the tail of the net buffer.\r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in, out] Nbuf The pointer to the net buffer.\r
@param[in] Len The length of the data to be trimmed.\r
- @param[in] FromHead The flag to indicate whether trim data from head\r
- (TRUE) or tail (FALSE).\r
+ @param[in] FromHead The flag to indicate whether trim data is from the \r
+ head (TRUE) or the tail (FALSE).\r
\r
- @return Length of the actually trimmed data, which may be less\r
+ @return The length of the actual trimmed data, which may be less\r
than Len if the TotalSize of Nbuf is less than Len.\r
\r
**/\r
\r
The Len bytes of data may cross several fragments of the net buffer.\r
\r
- @param[in] Nbuf Pointer to the net buffer.\r
+ @param[in] Nbuf The pointer to the net buffer.\r
@param[in] Offset The sequence number of the first byte to copy.\r
- @param[in] Len Length of the data to copy.\r
+ @param[in] Len The length of the data to copy.\r
@param[in] Dest The destination of the data to copy to.\r
\r
@return The length of the actual copied data, or 0 if the offset\r
and existing HeadLen bytes of header, but the external blocks are shared by the\r
net buffer to avoid data copying.\r
\r
- @param[in] ExtFragment Pointer to the data block.\r
+ @param[in] ExtFragment The pointer to the data block.\r
@param[in] ExtNum The number of the data blocks.\r
@param[in] HeadSpace The head space to be reserved.\r
@param[in] HeadLen The length of the protocol header. The function\r
pulls this amount of data into a linear block.\r
- @param[in] ExtFree Pointer to the caller-provided free function.\r
+ @param[in] ExtFree The pointer to the caller-provided free function.\r
@param[in] Arg The argument passed to ExtFree when ExtFree is\r
called.\r
\r
- @return Pointer to the net buffer built from the data blocks,\r
+ @return The pointer to the net buffer built from the data blocks,\r
or NULL if the allocation failed due to resource\r
limit.\r
\r
Build a fragment table to contain the fragments in the net buffer. This is the\r
opposite operation of the NetbufFromExt.\r
\r
- @param[in] Nbuf Point to the net buffer.\r
- @param[in, out] ExtFragment Pointer to the data block.\r
+ @param[in] Nbuf Points to the net buffer.\r
+ @param[in, out] ExtFragment The pointer to the data block.\r
@param[in, out] ExtNum The number of the data blocks.\r
\r
@retval EFI_BUFFER_TOO_SMALL The number of non-empty blocks is bigger than\r
ExtNum.\r
- @retval EFI_SUCCESS Fragment table is built successfully.\r
+ @retval EFI_SUCCESS The fragment table was built successfully.\r
\r
**/\r
EFI_STATUS\r
/**\r
Build a net buffer from a list of net buffers.\r
\r
- All the fragments will be collected from the list of NEW_BUF and then a new\r
+ All the fragments will be collected from the list of NEW_BUF, and then a new\r
net buffer will be created through NetbufFromExt.\r
\r
@param[in] BufList A List of the net buffer.\r
@param[in] HeadSpace The head space to be reserved.\r
@param[in] HeaderLen The length of the protocol header. The function\r
pulls this amount of data into a linear block.\r
- @param[in] ExtFree Pointer to the caller provided free function.\r
+ @param[in] ExtFree The pointer to the caller provided free function.\r
@param[in] Arg The argument passed to ExtFree when ExtFree is called.\r
\r
- @return Pointer to the net buffer built from the list of net\r
+ @return The pointer to the net buffer built from the list of net\r
buffers.\r
\r
**/\r
/**\r
Free a list of net buffers.\r
\r
- @param[in, out] Head Pointer to the head of linked net buffers.\r
+ @param[in, out] Head The pointer to the head of linked net buffers.\r
\r
**/\r
VOID\r
/**\r
Initiate the net buffer queue.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue to be initialized.\r
+ @param[in, out] NbufQue The pointer to the net buffer queue to be initialized.\r
\r
**/\r
VOID\r
/**\r
Allocate and initialize a net buffer queue.\r
\r
- @return Pointer to the allocated net buffer queue, or NULL if the\r
+ @return The pointer to the allocated net buffer queue, or NULL if the\r
allocation failed due to resource limit.\r
\r
**/\r
free operation isn't performed until the reference count of the net buffer\r
queue is decreased to 0.\r
\r
- @param[in] NbufQue Pointer to the net buffer queue to be freed.\r
+ @param[in] NbufQue The pointer to the net buffer queue to be freed.\r
\r
**/\r
VOID\r
/**\r
Remove a net buffer from the head in the specific queue and return it.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue.\r
+ @param[in, out] NbufQue The pointer to the net buffer queue.\r
\r
- @return Pointer to the net buffer removed from the specific queue,\r
+ @return The pointer to the net buffer removed from the specific queue,\r
or NULL if there is no net buffer in the specific queue.\r
\r
**/\r
/**\r
Append a net buffer to the net buffer queue.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue.\r
- @param[in, out] Nbuf Pointer to the net buffer to be appended.\r
+ @param[in, out] NbufQue The pointer to the net buffer queue.\r
+ @param[in, out] Nbuf The pointer to the net buffer to be appended.\r
\r
**/\r
VOID\r
Copy Len bytes of data from the net buffer queue at the specific offset to the\r
destination memory.\r
\r
- The copying operation is the same as NetbufCopy but applies to the net buffer\r
+ The copying operation is the same as NetbufCopy, but applies to the net buffer\r
queue instead of the net buffer.\r
\r
- @param[in] NbufQue Pointer to the net buffer queue.\r
+ @param[in] NbufQue The pointer to the net buffer queue.\r
@param[in] Offset The sequence number of the first byte to copy.\r
- @param[in] Len Length of the data to copy.\r
+ @param[in] Len The length of the data to copy.\r
@param[out] Dest The destination of the data to copy to.\r
\r
@return The length of the actual copied data, or 0 if the offset\r
);\r
\r
/**\r
- Trim Len bytes of data from the queue header and release any net buffer\r
- that is trimmed wholely.\r
+ Trim Len bytes of data from the buffer queue and free any net buffer\r
+ that is completely trimmed.\r
\r
The trimming operation is the same as NetbufTrim but applies to the net buffer\r
queue instead of the net buffer.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue.\r
- @param[in] Len Length of the data to trim.\r
+ @param[in, out] NbufQue The pointer to the net buffer queue.\r
+ @param[in] Len The length of the data to trim.\r
\r
@return The actual length of the data trimmed.\r
\r
/**\r
Flush the net buffer queue.\r
\r
- @param[in, out] NbufQue Pointer to the queue to be flushed.\r
+ @param[in, out] NbufQue The pointer to the queue to be flushed.\r
\r
**/\r
VOID\r
/**\r
Compute the checksum for a bulk of data.\r
\r
- @param[in] Bulk Pointer to the data.\r
- @param[in] Len Length of the data, in bytes.\r
+ @param[in] Bulk The pointer to the data.\r
+ @param[in] Len The length of the data, in bytes.\r
\r
@return The computed checksum.\r
\r
/**\r
Compute the checksum for a NET_BUF.\r
\r
- @param[in] Nbuf Pointer to the net buffer.\r
+ @param[in] Nbuf The pointer to the net buffer.\r
\r
@return The computed checksum.\r
\r
);\r
\r
/**\r
- Compute the checksum for TCP6/UDP6 pseudo header.\r
+ Compute the checksum for the TCP6/UDP6 pseudo header.\r
\r
Src and Dst are in network byte order, and Len is in host byte order.\r
\r
\r
**/\r
UINT16\r
+EFIAPI\r
NetIp6PseudoHeadChecksum (\r
IN EFI_IPv6_ADDRESS *Src,\r
IN EFI_IPv6_ADDRESS *Dst,\r
IN UINT8 NextHeader,\r
IN UINT32 Len\r
);\r
+\r
+/**\r
+ The function frees the net buffer which allocated by the IP protocol. It releases \r
+ only the net buffer and doesn't call the external free function. \r
+\r
+ This function should be called after finishing the process of mIpSec->ProcessExt() \r
+ for outbound traffic. The (EFI_IPSEC2_PROTOCOL)->ProcessExt() allocates a new \r
+ buffer for the ESP, so there needs a function to free the old net buffer.\r
+\r
+ @param[in] Nbuf The network buffer to be freed.\r
+\r
+**/\r
+VOID\r
+NetIpSecNetbufFree (\r
+ NET_BUF *Nbuf\r
+ );\r
+\r
+/**\r
+ This function obtains the system guid from the smbios table.\r
+\r
+ @param[out] SystemGuid The pointer of the returned system guid.\r
+\r
+ @retval EFI_SUCCESS Successfully obtained the system guid.\r
+ @retval EFI_NOT_FOUND Did not find the SMBIOS table.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+NetLibGetSystemGuid (\r
+ OUT EFI_GUID *SystemGuid\r
+ );\r
+\r
+/**\r
+ Create Dns QName according the queried domain name. \r
+ QName is a domain name represented as a sequence of labels, \r
+ where each label consists of a length octet followed by that \r
+ number of octets. The QName terminates with the zero \r
+ length octet for the null label of the root. Caller should \r
+ take responsibility to free the buffer in returned pointer.\r
+\r
+ @param DomainName The pointer to the queried domain name string. \r
+\r
+ @retval NULL Failed to fill QName.\r
+ @return QName filled successfully.\r
+ \r
+**/ \r
+CHAR8 *\r
+EFIAPI\r
+NetLibCreateDnsQName (\r
+ IN CHAR16 *DomainName\r
+ );\r
+\r
#endif\r