Changeset 77662 in vbox for trunk/src/VBox/Devices/EFI/FirmwareNew/MdeModulePkg/Include/Library/NetLib.h

Timestamp:

Mar 12, 2019 12:40:12 PM (6 years ago)

Author:

vboxsync

Message:

EFI: First step in UDK2018 merge. Does not build yet.

Location:

trunk/src/VBox/Devices/EFI/FirmwareNew

Files:

• . (modified) (1 prop)
• MdeModulePkg/Include/Library/NetLib.h (modified) (46 diffs)

trunk/src/VBox/Devices/EFI/FirmwareNew/MdeModulePkg/Include/Library/NetLib.h

@@ -3 +3 @@
   It provides basic functions for the UEFI network stack.
 
-Copyright (c) 2005 - 2012, Intel Corporation. All rights reserved.<BR>
+Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>
 This program and the accompanying materials
 are licensed and made available under the terms and conditions of the BSD License
@@ -38 +38 @@
 #define  IP4_PROTO_IGMP        0x02
 #define  IP6_ICMP              58
+#define  DNS_MAX_NAME_SIZE     255
+#define  DNS_MAX_MESSAGE_SIZE  512
 
 //
 // The address classification
 //
-#define  IP4_ADDR_CLASSA       1
-#define  IP4_ADDR_CLASSB       2
-#define  IP4_ADDR_CLASSC       3
+#define  IP4_ADDR_CLASSA       1     // Deprecated
+#define  IP4_ADDR_CLASSB       2     // Deprecated
+#define  IP4_ADDR_CLASSC       3     // Deprecated
 #define  IP4_ADDR_CLASSD       4
 #define  IP4_ADDR_CLASSE       5
@@ -50 +52 @@
 #define  IP4_MASK_NUM          33
 #define  IP6_PREFIX_NUM        129
+
+#define  IP4_MASK_MAX          32
+#define  IP6_PREFIX_MAX        128
 
 #define  IP6_HOP_BY_HOP        0
@@ -63 +68 @@
 
 #define  IP6_PREFIX_LENGTH     64
+
+//
+// DNS QTYPE values
+//
+#define  DNS_TYPE_A            1
+#define  DNS_TYPE_NS           2
+#define  DNS_TYPE_CNAME        5
+#define  DNS_TYPE_SOA          6
+#define  DNS_TYPE_WKS          11
+#define  DNS_TYPE_PTR          12
+#define  DNS_TYPE_HINFO        13
+#define  DNS_TYPE_MINFO        14
+#define  DNS_TYPE_MX           15
+#define  DNS_TYPE_TXT          16
+#define  DNS_TYPE_AAAA         28
+#define  DNS_TYPE_SRV_RR       33
+#define  DNS_TYPE_AXFR         252
+#define  DNS_TYPE_MAILB        253
+#define  DNS_TYPE_ANY          255
+
+//
+// DNS QCLASS values
+//
+#define  DNS_CLASS_INET        1
+#define  DNS_CLASS_CH          3
+#define  DNS_CLASS_HS          4
+#define  DNS_CLASS_ANY         255
+
+//
+// Number of 100ns units time Interval for network media state detect
+//
+#define MEDIA_STATE_DETECT_TIME_INTERVAL  1000000U
+
 
 #pragma pack(1)
@@ -200 +238 @@
 //
 #define IP4_IS_MULTICAST(Ip)              (((Ip) & 0xF0000000) == 0xE0000000)
+#define IP4_IS_UNSPECIFIED(Ip)            ((Ip) == 0)
 #define IP4_IS_LOCAL_BROADCAST(Ip)        ((Ip) == 0xFFFFFFFF)
 #define IP4_NET_EQUAL(Ip1, Ip2, NetMask)  (((Ip1) & (NetMask)) == ((Ip2) & (NetMask)))
-#define IP4_IS_VALID_NETMASK(Ip)          (NetGetMaskLength (Ip) != IP4_MASK_NUM)
+#define IP4_IS_VALID_NETMASK(Ip)          (NetGetMaskLength (Ip) != (IP4_MASK_MAX + 1))
 
 #define IP6_IS_MULTICAST(Ip6)             (((Ip6)->Addr[0]) == 0xFF)
@@ -221 +260 @@
 //
 // The debug level definition. This value is also used as the
-// syslog's servity level. Don't change it.
+// syslog's severity level. Don't change it.
 //
 #define NETDEBUG_LEVEL_TRACE   5
@@ -304 +343 @@
   Because it isn't open the SNP BY_DRIVER, apply caution when using it.
 
-  @param Level    The servity level of the message.
-  @param Module   The Moudle that generates the log.
+  @param Level    The severity level of the message.
+  @param Module   The Module that generates the log.
   @param File     The file that contains the log.
   @param Line     The exact line that contains the log.
@@ -347 +386 @@
   Return the class of the IP address, such as class A, B, C.
   Addr is in host byte order.
+
+  [ATTENTION]
+  Classful addressing (IP class A/B/C) has been deprecated according to RFC4632.
+  Caller of this function could only check the returned value against
+  IP4_ADDR_CLASSD (multicast) or IP4_ADDR_CLASSE (reserved) now.
 
   The address of class A  starts with 0.
@@ -373 +417 @@
 /**
   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.
-
-  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 not a valid unicast address.
+  the netmask.
+
+  ASSERT if NetMask is zero.
+
+  If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address,
+  except when the originator is one of the endpoints of a point-to-point link with a 31-bit
+  mask (RFC3021).
 
   @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.
 
 **/
@@ -395 +440 @@
 /**
   Check whether the incoming IPv6 address is a valid unicast address.
+
+  ASSERT if Ip6 is NULL.
 
   If the address is a multicast address has binary 0xFF at the start, it is not
@@ -417 +464 @@
   Check whether the incoming Ipv6 address is the unspecified address or not.
 
+  ASSERT if Ip6 is NULL.
+
   @param[in] Ip6   - Ip6 address, in network order.
 
@@ -432 +481 @@
   Check whether the incoming Ipv6 address is a link-local address.
 
+  ASSERT if Ip6 is NULL.
+
   @param[in] Ip6   - Ip6 address, in network order.
 
@@ -446 +497 @@
 /**
   Check whether the Ipv6 address1 and address2 are on the connected network.
+
+  ASSERT if Ip1 or Ip2 is NULL.
+  ASSERT if PrefixLength exceeds or equals to IP6_PREFIX_MAX.
 
   @param[in] Ip1          - Ip6 address1, in network order.
@@ -466 +520 @@
   Switches the endianess of an IPv6 address.
 
+  ASSERT if Ip6 is NULL.
+
   This function swaps the bytes in a 128-bit IPv6 address to switch the value
   from little endian to big endian or vice versa. The byte swapped value is
@@ -487 +543 @@
 
 #define NET_IS_DIGIT(Ch)            (('0' <= (Ch)) && ((Ch) <= '9'))
+#define NET_IS_HEX(Ch)              ((('0' <= (Ch)) && ((Ch) <= '9')) || (('A' <= (Ch)) && ((Ch) <= 'F')) || (('a' <= (Ch)) && ((Ch) <= 'f')))
 #define NET_ROUNDUP(size, unit)     (((size) + (unit) - 1) & (~((unit) - 1)))
 #define NET_IS_LOWER_CASE_CHAR(Ch)  (('a' <= (Ch)) && ((Ch) <= 'z'))
@@ -499 +556 @@
   Extract a UINT32 from a byte stream.
 
+  ASSERT if Buf is NULL.
+
   This function copies a UINT32 from a byte stream, and then converts it from Network
   byte order to host byte order. Use this function to avoid alignment error.
@@ -515 +574 @@
 /**
   Puts a UINT32 into the byte stream in network byte order.
+
+  ASSERT if Buf is NULL.
 
   Converts a UINT32 from host byte order to network byte order, then copies it to the
@@ -531 +592 @@
 
 /**
-  Initialize a random seed using current time.
-
-  Get current time first. Then initialize a random seed based on some basic
-  mathematical operations on the hour, day, minute, second, nanosecond and year
-  of the current time.
-
-  @return The random seed, initialized with current time.
+  Initialize a random seed using current time and monotonic count.
+
+  Get current time and monotonic count 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 and the monotonic count value.
+
+  @return The random seed initialized with current time.
 
 **/
@@ -632 +693 @@
   Insert a new node entry after a designated node entry of a doubly linked list.
 
+  ASSERT if PrevEntry or NewEntry is NULL.
+
   Inserts a new node entry designated by NewEntry after the node entry designated by PrevEntry
   of the doubly linked list.
@@ -648 +711 @@
 /**
   Insert a new node entry before a designated node entry of a doubly linked list.
+
+  ASSERT if PostEntry or NewEntry is NULL.
 
   Inserts a new node entry designated by NewEntry before the node entry designated by PostEntry
@@ -719 +784 @@
                                  if NumberOfChildren is 0.
 
-  @retval TURE                   Found the input Handle in ChildHandleBuffer.
+  @retval TRUE                   Found the input Handle in ChildHandleBuffer.
   @retval FALSE                  Can't find the input Handle in ChildHandleBuffer.
 
@@ -794 +859 @@
   If Map is NULL, then ASSERT().
 
-
   @param[in]  Map                   The net map to test.
 
@@ -808 +872 @@
 /**
   Return the number of the <Key, Value> pairs in the netmap.
+
+  If Map is NULL, then ASSERT().
 
   @param[in]  Map                   The netmap to get the entry number.
@@ -828 +894 @@
 
   If Map is NULL, then ASSERT().
+  If Key is NULL, then ASSERT().
 
   @param[in, out]  Map                   The netmap to insert into.
@@ -853 +920 @@
 
   If Map is NULL, then ASSERT().
+  If Key is NULL, then ASSERT().
 
   @param[in, out]  Map                   The netmap to insert into.
@@ -877 +945 @@
 
   If Map is NULL, then ASSERT().
+  If Key is NULL, then ASSERT().
 
   @param[in]  Map                   The netmap to search within.
@@ -977 +1046 @@
   Iterate through the netmap and call CallBack for each item.
 
-  It will contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break
+  It will continue 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.
@@ -1122 +1191 @@
   Get MAC address associated with the network service handle.
 
+  If MacAddress is NULL, then ASSERT().
+  If AddressSize is NULL, then ASSERT().
+
   There should be MNP Service Binding Protocol installed on the input ServiceHandle.
   If SNP is installed on the ServiceHandle or its parent handle, MAC address will
@@ -1146 +1218 @@
   Convert MAC address of the NIC associated with specified Service Binding Handle
   to a unicode string. Callers are responsible for freeing the string storage.
+
+  If MacString is NULL, then ASSERT().
 
   Locate simple network protocol associated with the Service Binding Handle and
@@ -1175 +1249 @@
 /**
   Detect media status for specified network device.
+
+  If MediaPresent is NULL, then ASSERT().
 
   The underlying UNDI driver may or may not support reporting media status from
@@ -1209 +1285 @@
 
 /**
+  Detect media state for a network device. This routine will wait for a period of time at
+  a specified checking interval when a certain network is under connecting until connection
+  process finishes or timeout. If Aip protocol is supported by low layer drivers, three kinds
+  of media states can be detected: EFI_SUCCESS, EFI_NOT_READY and EFI_NO_MEDIA, represents
+  connected state, connecting state and no media state respectively. When function detects
+  the current state is EFI_NOT_READY, it will loop to wait for next time's check until state
+  turns to be EFI_SUCCESS or EFI_NO_MEDIA. If Aip protocol is not supported, function will
+  call NetLibDetectMedia() and return state directly.
+
+  @param[in]   ServiceHandle    The handle where network service binding protocols are
+                                installed on.
+  @param[in]   Timeout          The maximum number of 100ns units to wait when network
+                                is connecting. Zero value means detect once and return
+                                immediately.
+  @param[out]  MediaState       The pointer to the detected media state.
+
+  @retval EFI_SUCCESS           Media detection success.
+  @retval EFI_INVALID_PARAMETER ServiceHandle is not a valid network device handle or
+                                MediaState pointer is NULL.
+  @retval EFI_DEVICE_ERROR      A device error occurred.
+  @retval EFI_TIMEOUT           Network is connecting but timeout.
+
+**/
+EFI_STATUS
+EFIAPI
+NetLibDetectMediaWaitTimeout (
+  IN  EFI_HANDLE            ServiceHandle,
+  IN  UINT64                Timeout,
+  OUT EFI_STATUS            *MediaState
+  );
+
+
+/**
   Create an IPv4 device path node.
+
+  If Node is NULL, then ASSERT().
 
   The header type of IPv4 device path node is MESSAGING_DEVICE_PATH.
@@ -1242 +1353 @@
   Create an IPv6 device path node.
 
+  If Node is NULL, then ASSERT().
+  If LocalIp is NULL, then ASSERT().
+  If RemoteIp is NULL, then ASSERT().
+
   The header type of IPv6 device path node is MESSAGING_DEVICE_PATH.
   The header subtype of IPv6 device path node is MSG_IPv6_DP.
@@ -1272 +1387 @@
   Find the UNDI/SNP handle from controller and protocol GUID.
 
+  If ProtocolGuid is NULL, then ASSERT().
+
   For example, IP will open an MNP child to transmit/receive
   packets. When MNP is stopped, IP should also be stopped. IP
@@ -1277 +1394 @@
   service binding instance that is installed on the UNDI/SNP handle.
   The controller is then either an MNP or an ARP child handle. Note that
-  IP opens these handles using BY_DRIVER. Use that infomation to get the
+  IP opens these handles using BY_DRIVER. Use that information to get the
   UNDI/SNP handle.
 
@@ -1318 +1435 @@
 
   @retval EFI_SUCCESS            Converted to an IPv4 address successfully.
-  @retval EFI_INVALID_PARAMETER  The string is malformated, or Ip4Address is NULL.
+  @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip4Address is NULL.
 
 **/
@@ -1330 +1447 @@
 /**
   Convert one Null-terminated ASCII string to EFI_IPv6_ADDRESS. The format of the
-  string is defined in RFC 4291 - Text Pepresentation of Addresses.
+  string is defined in RFC 4291 - Text Representation of Addresses.
 
   @param[in]      String         The pointer to the Ascii string.
@@ -1336 +1453 @@
 
   @retval EFI_SUCCESS            Converted to an IPv6 address successfully.
-  @retval EFI_INVALID_PARAMETER  The string is malformated, or Ip6Address is NULL.
+  @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip6Address is NULL.
 
 **/
@@ -1353 +1470 @@
 
   @retval EFI_SUCCESS            Converted to an IPv4 address successfully.
-  @retval EFI_INVALID_PARAMETER  The string is mal-formated or Ip4Address is NULL.
-  @retval EFI_OUT_OF_RESOURCES   Failed to perform the operation due to lack of resources.
+  @retval EFI_INVALID_PARAMETER  The string is mal-formatted or Ip4Address is NULL.
 
 **/
@@ -1366 +1482 @@
 /**
   Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS.  The format of
-  the string is defined in RFC 4291 - Text Pepresentation of Addresses.
+  the string is defined in RFC 4291 - Text Representation of Addresses.
 
   @param[in]      String         The pointer to the Ascii string.
@@ -1372 +1488 @@
 
   @retval EFI_SUCCESS            Converted to an IPv6 address successfully.
-  @retval EFI_INVALID_PARAMETER  The string is malformated or Ip6Address is NULL.
-  @retval EFI_OUT_OF_RESOURCES   Failed to perform the operation due to a lack of resources.
+  @retval EFI_INVALID_PARAMETER  The string is malformatted or Ip6Address is NULL.
 
 **/
@@ -1385 +1500 @@
 /**
   Convert one Null-terminated Unicode string to EFI_IPv6_ADDRESS and prefix length.
-  The format of the string is defined in RFC 4291 - Text Pepresentation of Addresses
+  The format of the string is defined in RFC 4291 - Text Representation of Addresses
   Prefixes: ipv6-address/prefix-length.
 
@@ -1393 +1508 @@
 
   @retval EFI_SUCCESS            Converted to an  IPv6 address successfully.
-  @retval EFI_INVALID_PARAMETER  The string is malformated, or Ip6Address is NULL.
-  @retval EFI_OUT_OF_RESOURCES   Failed to perform the operation due to a lack of resources.
+  @retval EFI_INVALID_PARAMETER  The string is malformatted, or Ip6Address is NULL.
 
 **/
@@ -1462 +1576 @@
   INTN                RefCnt;  // Reference count to share NET_VECTOR.
   NET_VECTOR_EXT_FREE Free;    // external function to free NET_VECTOR
-  VOID                *Arg;    // opeque argument to Free
+  VOID                *Arg;    // opaque argument to Free
   UINT32              Flag;    // Flags, NET_VECTOR_OWN_FIRST
-  UINT32              Len;     // Total length of the assocated BLOCKs
+  UINT32              Len;     // Total length of the associated BLOCKs
 
   UINT32              BlockNum;
@@ -1573 +1687 @@
 
 #define NET_HEADSPACE(BlockOp)  \
-  (UINTN)((BlockOp)->Head - (BlockOp)->BlockHead)
+  ((UINTN)((BlockOp)->Head) - (UINTN)((BlockOp)->BlockHead))
 
 #define NET_TAILSPACE(BlockOp)  \
-  (UINTN)((BlockOp)->BlockTail - (BlockOp)->Tail)
+  ((UINTN)((BlockOp)->BlockTail) - (UINTN)((BlockOp)->Tail))
 
 /**
@@ -2118 +2232 @@
   This function obtains the system guid from the smbios table.
 
+  If SystemGuid is NULL, then ASSERT().
+
   @param[out]  SystemGuid     The pointer of the returned system guid.
 
@@ -2130 +2246 @@
   );
 
+/**
+  Create Dns QName according the queried domain name.
+
+  If DomainName is NULL, then ASSERT().
+
+  QName is a domain name represented as a sequence of labels,
+  where each label consists of a length octet followed by that
+  number of octets. The QName terminates with the zero
+  length octet for the null label of the root. Caller should
+  take responsibility to free the buffer in returned pointer.
+
+  @param  DomainName    The pointer to the queried domain name string.
+
+  @retval NULL          Failed to fill QName.
+  @return               QName filled successfully.
+
+**/
+CHAR8 *
+EFIAPI
+NetLibCreateDnsQName (
+  IN  CHAR16              *DomainName
+  );
+
 #endif