2 * Copyright (c) 2017 Netflix, Inc.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
13 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 * Taken from MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.h
33 Definition for Device Path library.
35 Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
36 SPDX-License-Identifier: BSD-2-Clause-Patent
40 #ifndef _UEFI_DEVICE_PATH_LIB_H_
41 #define _UEFI_DEVICE_PATH_LIB_H_
43 #include <Protocol/DevicePathUtilities.h>
44 #include <Protocol/DebugPort.h>
45 #include <Protocol/DevicePathToText.h>
46 #include <Protocol/DevicePathFromText.h>
47 #include <Guid/PcAnsi.h>
48 #include <Library/DebugLib.h>
49 #include <Library/PrintLib.h>
50 #include <Library/BaseLib.h>
51 #include <Library/BaseMemoryLib.h>
52 #include <Library/MemoryAllocationLib.h>
53 #include <Library/UefiBootServicesTableLib.h>
54 #include <Library/DevicePathLib.h>
55 #include <Library/PcdLib.h>
56 #include <IndustryStandard/Bluetooth.h>
58 #define IS_COMMA(a) ((a) == ',')
59 #define IS_HYPHEN(a) ((a) == '-')
60 #define IS_DOT(a) ((a) == '.')
61 #define IS_LEFT_PARENTH(a) ((a) == '(')
62 #define IS_RIGHT_PARENTH(a) ((a) == ')')
63 #define IS_SLASH(a) ((a) == '/')
64 #define IS_NULL(a) ((a) == '\0')
67 // Private Data structure
76 EFI_DEVICE_PATH_PROTOCOL *
77 (*DEVICE_PATH_FROM_TEXT) (
83 (*DEVICE_PATH_TO_TEXT) (
84 IN OUT POOL_PRINT *Str,
86 IN BOOLEAN DisplayOnly,
87 IN BOOLEAN AllowShortcuts
93 DEVICE_PATH_TO_TEXT Function;
94 } DEVICE_PATH_TO_TEXT_TABLE;
99 } DEVICE_PATH_TO_TEXT_GENERIC_TABLE;
102 const char *DevicePathNodeText;
103 DEVICE_PATH_FROM_TEXT Function;
104 } DEVICE_PATH_FROM_TEXT_TABLE;
109 BOOLEAN SubClassExist;
113 #define USB_CLASS_AUDIO 1
114 #define USB_CLASS_CDCCONTROL 2
115 #define USB_CLASS_HID 3
116 #define USB_CLASS_IMAGE 6
117 #define USB_CLASS_PRINTER 7
118 #define USB_CLASS_MASS_STORAGE 8
119 #define USB_CLASS_HUB 9
120 #define USB_CLASS_CDCDATA 10
121 #define USB_CLASS_SMART_CARD 11
122 #define USB_CLASS_VIDEO 14
123 #define USB_CLASS_DIAGNOSTIC 220
124 #define USB_CLASS_WIRELESS 224
126 #define USB_CLASS_RESERVE 254
127 #define USB_SUBCLASS_FW_UPDATE 1
128 #define USB_SUBCLASS_IRDA_BRIDGE 2
129 #define USB_SUBCLASS_TEST 3
131 #define RFC_1700_UDP_PROTOCOL 17
132 #define RFC_1700_TCP_PROTOCOL 6
137 EFI_DEVICE_PATH_PROTOCOL Header;
139 UINT8 VendorDefinedData[1];
140 } VENDOR_DEFINED_HARDWARE_DEVICE_PATH;
143 EFI_DEVICE_PATH_PROTOCOL Header;
145 UINT8 VendorDefinedData[1];
146 } VENDOR_DEFINED_MESSAGING_DEVICE_PATH;
149 EFI_DEVICE_PATH_PROTOCOL Header;
151 UINT8 VendorDefinedData[1];
152 } VENDOR_DEFINED_MEDIA_DEVICE_PATH;
155 EFI_DEVICE_PATH_PROTOCOL Header;
159 CHAR8 HidUidCidStr[3];
160 } ACPI_EXTENDED_HID_DEVICE_PATH_WITH_STR;
163 EFI_DEVICE_PATH_PROTOCOL Header;
164 UINT16 NetworkProtocol;
167 UINT16 TargetPortalGroupTag;
169 } ISCSI_DEVICE_PATH_WITH_NAME;
172 EFI_DEVICE_PATH_PROTOCOL Header;
174 UINT8 VendorDefinedData[1];
175 } VENDOR_DEVICE_PATH_WITH_DATA;
179 #ifdef FreeBSD /* Remove these on FreeBSD */
182 Returns the size of a device path in bytes.
184 This function returns the size, in bytes, of the device path data structure
185 specified by DevicePath including the end of device path node.
186 If DevicePath is NULL or invalid, then 0 is returned.
188 @param DevicePath A pointer to a device path data structure.
190 @retval 0 If DevicePath is NULL or invalid.
191 @retval Others The size of a device path in bytes.
196 UefiDevicePathLibGetDevicePathSize (
197 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
201 Creates a new copy of an existing device path.
203 This function allocates space for a new copy of the device path specified by DevicePath.
204 If DevicePath is NULL, then NULL is returned. If the memory is successfully
205 allocated, then the contents of DevicePath are copied to the newly allocated
206 buffer, and a pointer to that buffer is returned. Otherwise, NULL is returned.
207 The memory for the new device path is allocated from EFI boot services memory.
208 It is the responsibility of the caller to free the memory allocated.
210 @param DevicePath A pointer to a device path data structure.
212 @retval NULL DevicePath is NULL or invalid.
213 @retval Others A pointer to the duplicated device path.
216 EFI_DEVICE_PATH_PROTOCOL *
218 UefiDevicePathLibDuplicateDevicePath (
219 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
223 Creates a new device path by appending a second device path to a first device path.
225 This function creates a new device path by appending a copy of SecondDevicePath
226 to a copy of FirstDevicePath in a newly allocated buffer. Only the end-of-device-path
227 device node from SecondDevicePath is retained. The newly created device path is
228 returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
229 SecondDevicePath is returned. If SecondDevicePath is NULL, then it is ignored,
230 and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
231 SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
233 If there is not enough memory for the newly allocated buffer, then NULL is returned.
234 The memory for the new device path is allocated from EFI boot services memory.
235 It is the responsibility of the caller to free the memory allocated.
237 @param FirstDevicePath A pointer to a device path data structure.
238 @param SecondDevicePath A pointer to a device path data structure.
240 @retval NULL If there is not enough memory for the newly allocated buffer.
241 @retval NULL If FirstDevicePath or SecondDevicePath is invalid.
242 @retval Others A pointer to the new device path if success.
243 Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
246 EFI_DEVICE_PATH_PROTOCOL *
248 UefiDevicePathLibAppendDevicePath (
249 IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath OPTIONAL,
250 IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath OPTIONAL
254 Creates a new path by appending the device node to the device path.
256 This function creates a new device path by appending a copy of the device node
257 specified by DevicePathNode to a copy of the device path specified by DevicePath
258 in an allocated buffer. The end-of-device-path device node is moved after the
259 end of the appended device node.
260 If DevicePathNode is NULL then a copy of DevicePath is returned.
261 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
262 path device node is returned.
263 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
264 device node is returned.
265 If there is not enough memory to allocate space for the new device path, then
267 The memory is allocated from EFI boot services memory. It is the responsibility
268 of the caller to free the memory allocated.
270 @param DevicePath A pointer to a device path data structure.
271 @param DevicePathNode A pointer to a single device path node.
273 @retval NULL If there is not enough memory for the new device path.
274 @retval Others A pointer to the new device path if success.
275 A copy of DevicePathNode followed by an end-of-device-path node
276 if both FirstDevicePath and SecondDevicePath are NULL.
277 A copy of an end-of-device-path node if both FirstDevicePath
278 and SecondDevicePath are NULL.
281 EFI_DEVICE_PATH_PROTOCOL *
283 UefiDevicePathLibAppendDevicePathNode (
284 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath OPTIONAL,
285 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode OPTIONAL
289 Creates a new device path by appending the specified device path instance to the specified device
292 This function creates a new device path by appending a copy of the device path
293 instance specified by DevicePathInstance to a copy of the device path specified
294 by DevicePath in a allocated buffer.
295 The end-of-device-path device node is moved after the end of the appended device
296 path instance and a new end-of-device-path-instance node is inserted between.
297 If DevicePath is NULL, then a copy if DevicePathInstance is returned.
298 If DevicePathInstance is NULL, then NULL is returned.
299 If DevicePath or DevicePathInstance is invalid, then NULL is returned.
300 If there is not enough memory to allocate space for the new device path, then
302 The memory is allocated from EFI boot services memory. It is the responsibility
303 of the caller to free the memory allocated.
305 @param DevicePath A pointer to a device path data structure.
306 @param DevicePathInstance A pointer to a device path instance.
308 @return A pointer to the new device path.
311 EFI_DEVICE_PATH_PROTOCOL *
313 UefiDevicePathLibAppendDevicePathInstance (
314 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath OPTIONAL,
315 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance OPTIONAL
319 Creates a copy of the current device path instance and returns a pointer to the next device path
322 This function creates a copy of the current device path instance. It also updates
323 DevicePath to point to the next device path instance in the device path (or NULL
324 if no more) and updates Size to hold the size of the device path instance copy.
325 If DevicePath is NULL, then NULL is returned.
326 If DevicePath points to a invalid device path, then NULL is returned.
327 If there is not enough memory to allocate space for the new device path, then
329 The memory is allocated from EFI boot services memory. It is the responsibility
330 of the caller to free the memory allocated.
331 If Size is NULL, then ASSERT().
333 @param DevicePath On input, this holds the pointer to the current
334 device path instance. On output, this holds
335 the pointer to the next device path instance
336 or NULL if there are no more device path
337 instances in the device path pointer to a
338 device path data structure.
339 @param Size On output, this holds the size of the device
340 path instance, in bytes or zero, if DevicePath
343 @return A pointer to the current device path instance.
346 EFI_DEVICE_PATH_PROTOCOL *
348 UefiDevicePathLibGetNextDevicePathInstance (
349 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,
354 Creates a device node.
356 This function creates a new device node in a newly allocated buffer of size
357 NodeLength and initializes the device path node header with NodeType and NodeSubType.
358 The new device path node is returned.
359 If NodeLength is smaller than a device path header, then NULL is returned.
360 If there is not enough memory to allocate space for the new device path, then
362 The memory is allocated from EFI boot services memory. It is the responsibility
363 of the caller to free the memory allocated.
365 @param NodeType The device node type for the new device node.
366 @param NodeSubType The device node sub-type for the new device node.
367 @param NodeLength The length of the new device node.
369 @return The new device path.
372 EFI_DEVICE_PATH_PROTOCOL *
374 UefiDevicePathLibCreateDeviceNode (
376 IN UINT8 NodeSubType,
381 Determines if a device path is single or multi-instance.
383 This function returns TRUE if the device path specified by DevicePath is
385 Otherwise, FALSE is returned.
386 If DevicePath is NULL or invalid, then FALSE is returned.
388 @param DevicePath A pointer to a device path data structure.
390 @retval TRUE DevicePath is multi-instance.
391 @retval FALSE DevicePath is not multi-instance, or DevicePath
397 UefiDevicePathLibIsDevicePathMultiInstance (
398 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath
402 Converts a device path to its text representation.
404 @param DevicePath A Pointer to the device to be converted.
405 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation
406 of the display node is used, where applicable. If DisplayOnly
407 is FALSE, then the longer text representation of the display node
409 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text
410 representation for a device node can be used, where applicable.
412 @return A pointer to the allocated text representation of the device path or
413 NULL if DeviceNode is NULL or there was insufficient memory.
418 UefiDevicePathLibConvertDevicePathToText (
419 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
420 IN BOOLEAN DisplayOnly,
421 IN BOOLEAN AllowShortcuts
425 Converts a device node to its string representation.
427 @param DeviceNode A Pointer to the device node to be converted.
428 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation
429 of the display node is used, where applicable. If DisplayOnly
430 is FALSE, then the longer text representation of the display node
432 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text
433 representation for a device node can be used, where applicable.
435 @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
436 is NULL or there was insufficient memory.
441 UefiDevicePathLibConvertDeviceNodeToText (
442 IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode,
443 IN BOOLEAN DisplayOnly,
444 IN BOOLEAN AllowShortcuts
448 Convert text to the binary representation of a device node.
450 @param TextDeviceNode TextDeviceNode points to the text representation of a device
451 node. Conversion starts with the first character and continues
452 until the first non-device node character.
454 @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
455 insufficient memory or text unsupported.
458 EFI_DEVICE_PATH_PROTOCOL *
460 UefiDevicePathLibConvertTextToDeviceNode (
461 IN CONST CHAR16 *TextDeviceNode
465 Convert text to the binary representation of a device path.
468 @param TextDevicePath TextDevicePath points to the text representation of a device
469 path. Conversion starts with the first character and continues
470 until the first non-device node character.
472 @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
473 there was insufficient memory.
476 EFI_DEVICE_PATH_PROTOCOL *
478 UefiDevicePathLibConvertTextToDevicePath (
479 IN CONST CHAR16 *TextDevicePath
484 * Small FreeBSD shim layer. Fast and lose hacks to make this code work with FreeBSD.
489 #define _PCD_GET_MODE_32_PcdMaximumDevicePathNodeCount 1000
490 #define MAX_UINTN UINTPTR_MAX
492 #define AllocatePool(x) malloc(x)
493 #define AllocateZeroPool(x) calloc(1,x)
494 #define AsciiStrLen(s) strlen(s)
495 #define CopyGuid(dst, src) memcpy(dst, src, sizeof(uuid_t))
496 #define CopyMem(d, s, l) memcpy(d, s, l)
497 #define FreePool(x) free(x)
498 #define LShiftU64(x, s) ((x) << s)
499 #define ReadUnaligned64(x) le64dec(x)
500 #define ReallocatePool(old, new, ptr) realloc(ptr, new)
502 * Quirky StrCmp returns 0 if equal, 1 if not. This is what the code
503 * expects, though that expectation is likely a bug (it casts the
504 * return value. EDK2's StrCmp returns values just like C's strcmp,
505 * but the parse code casts this to an UINTN, which is bogus. This
506 * definition papers over that bogusness to do the right thing. If
507 * iSCSI protocol string processing is ever fixed, we can remove this
508 * bletcherous kludge.
510 #define StrCmp(a, b) (strcmp(a, b) != 0)
511 #define StrCpyS(d, l, s) strcpy(d, s)
512 #define StrHexToUint64(x) strtoll(x, NULL, 16)
513 #define StrHexToUintn(x) strtoll(x, NULL, 16)
514 #define StrLen(x) strlen(x)
515 #define StrSize(x) (strlen(x) + 1)
516 #define StrnCatS(d, l, s, len) strncat(d, s, len)
517 #define StrnCmp(a, b, n) strncmp(a, b, n)
518 #define StrnLenS(str, max) strlen(str)
519 #define Strtoi(x) strtol(x, NULL, 0)
520 #define Strtoi64(x, y) *(long long *)y = strtoll(x, NULL, 0)
521 #define SwapBytes64(u64) bswap64(u64)
522 #define UnicodeStrToAsciiStrS(src, dest, len) strlcpy(dest, src, len)
523 #define ZeroMem(p,l) memset(p, 0, l)
529 * Define AllocateCopyPool and others so that we "forget" about the
530 * previous non-static deifnition since we want these to be static
533 #define AllocateCopyPool AllocateCopyPoolFreeBSD
534 #define CompareGuid CompareGuidFreeBSD
535 #define StrHexToBytes StrHexToBytesFreeBSD
536 #define StrToGuid StrToGuidFreeBSD
537 #define WriteUnaligned64 WriteUnaligned64FreeBSD
540 AllocateCopyPool(size_t l, const void *p)
551 static inline BOOLEAN
552 CompareGuid (const GUID *g1, const GUID *g2)
554 uint32_t ignored_status;
556 return (uuid_compare((const uuid_t *)g1, (const uuid_t *)g2,
557 &ignored_status) == 0);
561 StrHexToBytes(const char *str, size_t len, uint8_t *buf, size_t buflen)
567 * Sanity check preconditions.
569 if (buflen != len / 2 || (len % 2) == 1)
571 for (i = 0; i < len; i += 2) {
572 if (!isxdigit(str[i]) || !isxdigit(str[i + 1]))
577 buf[i / 2] = strtol(hex, NULL, 16);
583 StrToGuid(const char *str, GUID *guid)
587 uuid_from_string(str, (uuid_t *)guid, &status);
591 WriteUnaligned64(void *ptr, uint64_t val)
593 memcpy(ptr, &val, sizeof(val));
597 * Hack to allow converting %g to %s in printfs. Hack because
598 * it's single entry, uses a static buffer, etc. Sufficient for
599 * the day for this file though. IF you ever have to convert
600 * two %g's in one format, punt. Did I mention this was super lame.
601 * Not to mention it's name.... Also, the error GUID is horrific.
603 static inline const char *
604 guid_str(const GUID *g)
606 static char buf[36 + 1];
608 int32_t ignored_status;
610 uuid_to_string((const uuid_t *)g, &str, &ignored_status);
612 strlcpy(buf, str, sizeof(buf));
614 strlcpy(buf, "groot-cannot-decode-guid-groot-smash",
615 sizeof(buf)); /* ^^^^^^^ 36 characters ^^^^^^^ */
619 #define G(x) guid_str((const GUID *)(const void *)x)
622 #undef GLOBAL_REMOVE_IF_UNREFERENCED
623 #define GLOBAL_REMOVE_IF_UNREFERENCED static