xref: /freebsd-src/sys/contrib/edk2/Include/Library/DevicePathLib.h (revision 3245fa215aca18d135839a15c80ae1c905666a37)
10d1ba665SWarner Losh /** @file
20d1ba665SWarner Losh   Provides library functions to construct and parse UEFI Device Paths.
30d1ba665SWarner Losh 
40d1ba665SWarner Losh   This library provides defines, macros, and functions to help create and parse
50d1ba665SWarner Losh   EFI_DEVICE_PATH_PROTOCOL structures.
60d1ba665SWarner Losh 
7*3245fa21SMitchell Horne Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
8*3245fa21SMitchell Horne SPDX-License-Identifier: BSD-2-Clause-Patent
90d1ba665SWarner Losh 
100d1ba665SWarner Losh **/
110d1ba665SWarner Losh 
120d1ba665SWarner Losh #ifndef __DEVICE_PATH_LIB_H__
130d1ba665SWarner Losh #define __DEVICE_PATH_LIB_H__
140d1ba665SWarner Losh 
150d1ba665SWarner Losh #define END_DEVICE_PATH_LENGTH               (sizeof (EFI_DEVICE_PATH_PROTOCOL))
160d1ba665SWarner Losh 
170d1ba665SWarner Losh /**
180d1ba665SWarner Losh   Determine whether a given device path is valid.
190d1ba665SWarner Losh 
200d1ba665SWarner Losh   @param  DevicePath  A pointer to a device path data structure.
210d1ba665SWarner Losh   @param  MaxSize     The maximum size of the device path data structure.
220d1ba665SWarner Losh 
230d1ba665SWarner Losh   @retval TRUE        DevicePath is valid.
24*3245fa21SMitchell Horne   @retval FALSE       DevicePath is NULL.
25*3245fa21SMitchell Horne   @retval FALSE       Maxsize is less than sizeof(EFI_DEVICE_PATH_PROTOCOL).
260d1ba665SWarner Losh   @retval FALSE       The length of any node node in the DevicePath is less
270d1ba665SWarner Losh                       than sizeof (EFI_DEVICE_PATH_PROTOCOL).
280d1ba665SWarner Losh   @retval FALSE       If MaxSize is not zero, the size of the DevicePath
290d1ba665SWarner Losh                       exceeds MaxSize.
300d1ba665SWarner Losh   @retval FALSE       If PcdMaximumDevicePathNodeCount is not zero, the node
310d1ba665SWarner Losh                       count of the DevicePath exceeds PcdMaximumDevicePathNodeCount.
320d1ba665SWarner Losh **/
330d1ba665SWarner Losh BOOLEAN
340d1ba665SWarner Losh EFIAPI
350d1ba665SWarner Losh IsDevicePathValid (
360d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
370d1ba665SWarner Losh   IN       UINTN                    MaxSize
380d1ba665SWarner Losh   );
390d1ba665SWarner Losh 
400d1ba665SWarner Losh /**
410d1ba665SWarner Losh   Returns the Type field of a device path node.
420d1ba665SWarner Losh 
430d1ba665SWarner Losh   Returns the Type field of the device path node specified by Node.
440d1ba665SWarner Losh 
450d1ba665SWarner Losh   If Node is NULL, then ASSERT().
460d1ba665SWarner Losh 
470d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
480d1ba665SWarner Losh 
490d1ba665SWarner Losh   @return The Type field of the device path node specified by Node.
500d1ba665SWarner Losh 
510d1ba665SWarner Losh **/
520d1ba665SWarner Losh UINT8
530d1ba665SWarner Losh EFIAPI
540d1ba665SWarner Losh DevicePathType (
550d1ba665SWarner Losh   IN CONST VOID  *Node
560d1ba665SWarner Losh   );
570d1ba665SWarner Losh 
580d1ba665SWarner Losh /**
590d1ba665SWarner Losh   Returns the SubType field of a device path node.
600d1ba665SWarner Losh 
610d1ba665SWarner Losh   Returns the SubType field of the device path node specified by Node.
620d1ba665SWarner Losh 
630d1ba665SWarner Losh   If Node is NULL, then ASSERT().
640d1ba665SWarner Losh 
650d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
660d1ba665SWarner Losh 
670d1ba665SWarner Losh   @return The SubType field of the device path node specified by Node.
680d1ba665SWarner Losh 
690d1ba665SWarner Losh **/
700d1ba665SWarner Losh UINT8
710d1ba665SWarner Losh EFIAPI
720d1ba665SWarner Losh DevicePathSubType (
730d1ba665SWarner Losh   IN CONST VOID  *Node
740d1ba665SWarner Losh   );
750d1ba665SWarner Losh 
760d1ba665SWarner Losh /**
770d1ba665SWarner Losh   Returns the 16-bit Length field of a device path node.
780d1ba665SWarner Losh 
790d1ba665SWarner Losh   Returns the 16-bit Length field of the device path node specified by Node.
800d1ba665SWarner Losh   Node is not required to be aligned on a 16-bit boundary, so it is recommended
810d1ba665SWarner Losh   that a function such as ReadUnaligned16() be used to extract the contents of
820d1ba665SWarner Losh   the Length field.
830d1ba665SWarner Losh 
840d1ba665SWarner Losh   If Node is NULL, then ASSERT().
850d1ba665SWarner Losh 
860d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
870d1ba665SWarner Losh 
880d1ba665SWarner Losh   @return The 16-bit Length field of the device path node specified by Node.
890d1ba665SWarner Losh 
900d1ba665SWarner Losh **/
910d1ba665SWarner Losh UINTN
920d1ba665SWarner Losh EFIAPI
930d1ba665SWarner Losh DevicePathNodeLength (
940d1ba665SWarner Losh   IN CONST VOID  *Node
950d1ba665SWarner Losh   );
960d1ba665SWarner Losh 
970d1ba665SWarner Losh /**
980d1ba665SWarner Losh   Returns a pointer to the next node in a device path.
990d1ba665SWarner Losh 
1000d1ba665SWarner Losh   Returns a pointer to the device path node that follows the device path node specified by Node.
1010d1ba665SWarner Losh 
1020d1ba665SWarner Losh   If Node is NULL, then ASSERT().
1030d1ba665SWarner Losh 
1040d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
1050d1ba665SWarner Losh 
1060d1ba665SWarner Losh   @return a pointer to the device path node that follows the device path node specified by Node.
1070d1ba665SWarner Losh 
1080d1ba665SWarner Losh **/
1090d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
1100d1ba665SWarner Losh EFIAPI
1110d1ba665SWarner Losh NextDevicePathNode (
1120d1ba665SWarner Losh   IN CONST VOID  *Node
1130d1ba665SWarner Losh   );
1140d1ba665SWarner Losh 
1150d1ba665SWarner Losh /**
1160d1ba665SWarner Losh   Determines if a device path node is an end node of a device path.
1170d1ba665SWarner Losh   This includes nodes that are the end of a device path instance and nodes that
1180d1ba665SWarner Losh   are the end of an entire device path.
1190d1ba665SWarner Losh 
1200d1ba665SWarner Losh   Determines if the device path node specified by Node is an end node of a device path.
1210d1ba665SWarner Losh   This includes nodes that are the end of a device path instance and nodes that are the
1220d1ba665SWarner Losh   end of an entire device path.  If Node represents an end node of a device path,
1230d1ba665SWarner Losh   then TRUE is returned.  Otherwise, FALSE is returned.
1240d1ba665SWarner Losh 
1250d1ba665SWarner Losh   If Node is NULL, then ASSERT().
1260d1ba665SWarner Losh 
1270d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
1280d1ba665SWarner Losh 
1290d1ba665SWarner Losh   @retval TRUE      The device path node specified by Node is an end node of a device path.
1300d1ba665SWarner Losh   @retval FALSE     The device path node specified by Node is not an end node of a device path.
1310d1ba665SWarner Losh 
1320d1ba665SWarner Losh **/
1330d1ba665SWarner Losh BOOLEAN
1340d1ba665SWarner Losh EFIAPI
1350d1ba665SWarner Losh IsDevicePathEndType (
1360d1ba665SWarner Losh   IN CONST VOID  *Node
1370d1ba665SWarner Losh   );
1380d1ba665SWarner Losh 
1390d1ba665SWarner Losh /**
1400d1ba665SWarner Losh   Determines if a device path node is an end node of an entire device path.
1410d1ba665SWarner Losh 
1420d1ba665SWarner Losh   Determines if a device path node specified by Node is an end node of an entire device path.
1430d1ba665SWarner Losh   If Node represents the end of an entire device path, then TRUE is returned.
1440d1ba665SWarner Losh   Otherwise, FALSE is returned.
1450d1ba665SWarner Losh 
1460d1ba665SWarner Losh   If Node is NULL, then ASSERT().
1470d1ba665SWarner Losh 
1480d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
1490d1ba665SWarner Losh 
1500d1ba665SWarner Losh   @retval TRUE      The device path node specified by Node is the end of an entire device path.
1510d1ba665SWarner Losh   @retval FALSE     The device path node specified by Node is not the end of an entire device path.
1520d1ba665SWarner Losh 
1530d1ba665SWarner Losh **/
1540d1ba665SWarner Losh BOOLEAN
1550d1ba665SWarner Losh EFIAPI
1560d1ba665SWarner Losh IsDevicePathEnd (
1570d1ba665SWarner Losh   IN CONST VOID  *Node
1580d1ba665SWarner Losh   );
1590d1ba665SWarner Losh 
1600d1ba665SWarner Losh /**
1610d1ba665SWarner Losh   Determines if a device path node is an end node of a device path instance.
1620d1ba665SWarner Losh 
1630d1ba665SWarner Losh   Determines if a device path node specified by Node is an end node of a device path instance.
1640d1ba665SWarner Losh   If Node represents the end of a device path instance, then TRUE is returned.
1650d1ba665SWarner Losh   Otherwise, FALSE is returned.
1660d1ba665SWarner Losh 
1670d1ba665SWarner Losh   If Node is NULL, then ASSERT().
1680d1ba665SWarner Losh 
1690d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
1700d1ba665SWarner Losh 
1710d1ba665SWarner Losh   @retval TRUE      The device path node specified by Node is the end of a device path instance.
1720d1ba665SWarner Losh   @retval FALSE     The device path node specified by Node is not the end of a device path instance.
1730d1ba665SWarner Losh 
1740d1ba665SWarner Losh **/
1750d1ba665SWarner Losh BOOLEAN
1760d1ba665SWarner Losh EFIAPI
1770d1ba665SWarner Losh IsDevicePathEndInstance (
1780d1ba665SWarner Losh   IN CONST VOID  *Node
1790d1ba665SWarner Losh   );
1800d1ba665SWarner Losh 
1810d1ba665SWarner Losh /**
1820d1ba665SWarner Losh   Sets the length, in bytes, of a device path node.
1830d1ba665SWarner Losh 
1840d1ba665SWarner Losh   Sets the length of the device path node specified by Node to the value specified
1850d1ba665SWarner Losh   by NodeLength.  NodeLength is returned.  Node is not required to be aligned on
1860d1ba665SWarner Losh   a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
1870d1ba665SWarner Losh   be used to set the contents of the Length field.
1880d1ba665SWarner Losh 
1890d1ba665SWarner Losh   If Node is NULL, then ASSERT().
1900d1ba665SWarner Losh   If NodeLength >= 0x10000, then ASSERT().
1910d1ba665SWarner Losh   If NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL), then ASSERT().
1920d1ba665SWarner Losh 
1930d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
1940d1ba665SWarner Losh   @param  Length    The length, in bytes, of the device path node.
1950d1ba665SWarner Losh 
1960d1ba665SWarner Losh   @return Length
1970d1ba665SWarner Losh 
1980d1ba665SWarner Losh **/
1990d1ba665SWarner Losh UINT16
2000d1ba665SWarner Losh EFIAPI
2010d1ba665SWarner Losh SetDevicePathNodeLength (
2020d1ba665SWarner Losh   IN OUT VOID  *Node,
2030d1ba665SWarner Losh   IN UINTN     Length
2040d1ba665SWarner Losh   );
2050d1ba665SWarner Losh 
2060d1ba665SWarner Losh /**
2070d1ba665SWarner Losh   Fills in all the fields of a device path node that is the end of an entire device path.
2080d1ba665SWarner Losh 
2090d1ba665SWarner Losh   Fills in all the fields of a device path node specified by Node so Node represents
2100d1ba665SWarner Losh   the end of an entire device path.  The Type field of Node is set to
2110d1ba665SWarner Losh   END_DEVICE_PATH_TYPE, the SubType field of Node is set to
2120d1ba665SWarner Losh   END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
2130d1ba665SWarner Losh   END_DEVICE_PATH_LENGTH.  Node is not required to be aligned on a 16-bit boundary,
2140d1ba665SWarner Losh   so it is recommended that a function such as WriteUnaligned16() be used to set
2150d1ba665SWarner Losh   the contents of the Length field.
2160d1ba665SWarner Losh 
2170d1ba665SWarner Losh   If Node is NULL, then ASSERT().
2180d1ba665SWarner Losh 
2190d1ba665SWarner Losh   @param  Node      A pointer to a device path node data structure.
2200d1ba665SWarner Losh 
2210d1ba665SWarner Losh **/
2220d1ba665SWarner Losh VOID
2230d1ba665SWarner Losh EFIAPI
2240d1ba665SWarner Losh SetDevicePathEndNode (
2250d1ba665SWarner Losh   OUT VOID  *Node
2260d1ba665SWarner Losh   );
2270d1ba665SWarner Losh 
2280d1ba665SWarner Losh /**
2290d1ba665SWarner Losh   Returns the size of a device path in bytes.
2300d1ba665SWarner Losh 
2310d1ba665SWarner Losh   This function returns the size, in bytes, of the device path data structure
2320d1ba665SWarner Losh   specified by DevicePath including the end of device path node.
2330d1ba665SWarner Losh   If DevicePath is NULL or invalid, then 0 is returned.
2340d1ba665SWarner Losh 
2350d1ba665SWarner Losh   @param  DevicePath  A pointer to a device path data structure.
2360d1ba665SWarner Losh 
2370d1ba665SWarner Losh   @retval 0           If DevicePath is NULL or invalid.
2380d1ba665SWarner Losh   @retval Others      The size of a device path in bytes.
2390d1ba665SWarner Losh 
2400d1ba665SWarner Losh **/
2410d1ba665SWarner Losh UINTN
2420d1ba665SWarner Losh EFIAPI
2430d1ba665SWarner Losh GetDevicePathSize (
2440d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
2450d1ba665SWarner Losh   );
2460d1ba665SWarner Losh 
2470d1ba665SWarner Losh /**
2480d1ba665SWarner Losh   Creates a new copy of an existing device path.
2490d1ba665SWarner Losh 
2500d1ba665SWarner Losh   This function allocates space for a new copy of the device path specified by DevicePath.  If
2510d1ba665SWarner Losh   DevicePath is NULL, then NULL is returned.  If the memory is successfully allocated, then the
2520d1ba665SWarner Losh   contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
2530d1ba665SWarner Losh   is returned.  Otherwise, NULL is returned.
2540d1ba665SWarner Losh   The memory for the new device path is allocated from EFI boot services memory.
2550d1ba665SWarner Losh   It is the responsibility of the caller to free the memory allocated.
2560d1ba665SWarner Losh 
2570d1ba665SWarner Losh   @param  DevicePath                 A pointer to a device path data structure.
2580d1ba665SWarner Losh 
2590d1ba665SWarner Losh   @retval NULL    DevicePath is NULL or invalid.
2600d1ba665SWarner Losh   @retval Others  A pointer to the duplicated device path.
2610d1ba665SWarner Losh 
2620d1ba665SWarner Losh **/
2630d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
2640d1ba665SWarner Losh EFIAPI
2650d1ba665SWarner Losh DuplicateDevicePath (
2660d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
2670d1ba665SWarner Losh   );
2680d1ba665SWarner Losh 
2690d1ba665SWarner Losh /**
2700d1ba665SWarner Losh   Creates a new device path by appending a second device path to a first device path.
2710d1ba665SWarner Losh 
2720d1ba665SWarner Losh   This function creates a new device path by appending a copy of SecondDevicePath to a copy of
2730d1ba665SWarner Losh   FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path device node from
2740d1ba665SWarner Losh   SecondDevicePath is retained. The newly created device path is returned.
2750d1ba665SWarner Losh   If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
2760d1ba665SWarner Losh   If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
2770d1ba665SWarner Losh   If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
2780d1ba665SWarner Losh   returned.
2790d1ba665SWarner Losh   If there is not enough memory for the newly allocated buffer, then NULL is returned.
2800d1ba665SWarner Losh   The memory for the new device path is allocated from EFI boot services memory. It is the
2810d1ba665SWarner Losh   responsibility of the caller to free the memory allocated.
2820d1ba665SWarner Losh 
2830d1ba665SWarner Losh   @param  FirstDevicePath            A pointer to a device path data structure.
2840d1ba665SWarner Losh   @param  SecondDevicePath           A pointer to a device path data structure.
2850d1ba665SWarner Losh 
2860d1ba665SWarner Losh   @retval NULL      If there is not enough memory for the newly allocated buffer.
2870d1ba665SWarner Losh   @retval NULL      If FirstDevicePath or SecondDevicePath is invalid.
2880d1ba665SWarner Losh   @retval Others    A pointer to the new device path if success.
2890d1ba665SWarner Losh                     Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
2900d1ba665SWarner Losh 
2910d1ba665SWarner Losh **/
2920d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
2930d1ba665SWarner Losh EFIAPI
2940d1ba665SWarner Losh AppendDevicePath (
2950d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,  OPTIONAL
2960d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath  OPTIONAL
2970d1ba665SWarner Losh   );
2980d1ba665SWarner Losh 
2990d1ba665SWarner Losh /**
3000d1ba665SWarner Losh   Creates a new path by appending the device node to the device path.
3010d1ba665SWarner Losh 
3020d1ba665SWarner Losh   This function creates a new device path by appending a copy of the device node specified by
3030d1ba665SWarner Losh   DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
3040d1ba665SWarner Losh   The end-of-device-path device node is moved after the end of the appended device node.
3050d1ba665SWarner Losh   If DevicePathNode is NULL then a copy of DevicePath is returned.
3060d1ba665SWarner Losh   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
3070d1ba665SWarner Losh   node is returned.
3080d1ba665SWarner Losh   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
3090d1ba665SWarner Losh   is returned.
3100d1ba665SWarner Losh   If there is not enough memory to allocate space for the new device path, then NULL is returned.
3110d1ba665SWarner Losh   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
3120d1ba665SWarner Losh   free the memory allocated.
3130d1ba665SWarner Losh 
3140d1ba665SWarner Losh   @param  DevicePath                 A pointer to a device path data structure.
3150d1ba665SWarner Losh   @param  DevicePathNode             A pointer to a single device path node.
3160d1ba665SWarner Losh 
3170d1ba665SWarner Losh   @retval NULL      There is not enough memory for the new device path.
3180d1ba665SWarner Losh   @retval Others    A pointer to the new device path if success.
3190d1ba665SWarner Losh                     A copy of DevicePathNode followed by an end-of-device-path node
3200d1ba665SWarner Losh                     if both FirstDevicePath and SecondDevicePath are NULL.
3210d1ba665SWarner Losh                     A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
3220d1ba665SWarner Losh 
3230d1ba665SWarner Losh **/
3240d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
3250d1ba665SWarner Losh EFIAPI
3260d1ba665SWarner Losh AppendDevicePathNode (
3270d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,     OPTIONAL
3280d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode  OPTIONAL
3290d1ba665SWarner Losh   );
3300d1ba665SWarner Losh 
3310d1ba665SWarner Losh /**
3320d1ba665SWarner Losh   Creates a new device path by appending the specified device path instance to the specified device
3330d1ba665SWarner Losh   path.
3340d1ba665SWarner Losh 
3350d1ba665SWarner Losh   This function creates a new device path by appending a copy of the device path instance specified
3360d1ba665SWarner Losh   by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
3370d1ba665SWarner Losh   The end-of-device-path device node is moved after the end of the appended device path instance
3380d1ba665SWarner Losh   and a new end-of-device-path-instance node is inserted between.
3390d1ba665SWarner Losh   If DevicePath is NULL, then a copy if DevicePathInstance is returned.
3400d1ba665SWarner Losh   If DevicePathInstance is NULL, then NULL is returned.
3410d1ba665SWarner Losh   If DevicePath or DevicePathInstance is invalid, then NULL is returned.
3420d1ba665SWarner Losh   If there is not enough memory to allocate space for the new device path, then NULL is returned.
3430d1ba665SWarner Losh   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
3440d1ba665SWarner Losh   free the memory allocated.
3450d1ba665SWarner Losh 
3460d1ba665SWarner Losh   @param  DevicePath                 A pointer to a device path data structure.
3470d1ba665SWarner Losh   @param  DevicePathInstance         A pointer to a device path instance.
3480d1ba665SWarner Losh 
3490d1ba665SWarner Losh   @return A pointer to the new device path.
3500d1ba665SWarner Losh 
3510d1ba665SWarner Losh **/
3520d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
3530d1ba665SWarner Losh EFIAPI
3540d1ba665SWarner Losh AppendDevicePathInstance (
3550d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,        OPTIONAL
3560d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathInstance OPTIONAL
3570d1ba665SWarner Losh   );
3580d1ba665SWarner Losh 
3590d1ba665SWarner Losh /**
3600d1ba665SWarner Losh   Creates a copy of the current device path instance and returns a pointer to the next device path
3610d1ba665SWarner Losh   instance.
3620d1ba665SWarner Losh 
3630d1ba665SWarner Losh   This function creates a copy of the current device path instance. It also updates DevicePath to
3640d1ba665SWarner Losh   point to the next device path instance in the device path (or NULL if no more) and updates Size
3650d1ba665SWarner Losh   to hold the size of the device path instance copy.
3660d1ba665SWarner Losh   If DevicePath is NULL, then NULL is returned.
3670d1ba665SWarner Losh   If DevicePath points to a invalid device path, then NULL is returned.
3680d1ba665SWarner Losh   If there is not enough memory to allocate space for the new device path, then NULL is returned.
3690d1ba665SWarner Losh   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
3700d1ba665SWarner Losh   free the memory allocated.
3710d1ba665SWarner Losh   If Size is NULL, then ASSERT().
3720d1ba665SWarner Losh 
3730d1ba665SWarner Losh   @param  DevicePath                 On input, this holds the pointer to the current device path
3740d1ba665SWarner Losh                                      instance. On output, this holds the pointer to the next device
3750d1ba665SWarner Losh                                      path instance or NULL if there are no more device path
3760d1ba665SWarner Losh                                      instances in the device path pointer to a device path data
3770d1ba665SWarner Losh                                      structure.
3780d1ba665SWarner Losh   @param  Size                       On output, this holds the size of the device path instance, in
3790d1ba665SWarner Losh                                      bytes or zero, if DevicePath is NULL.
3800d1ba665SWarner Losh 
3810d1ba665SWarner Losh   @return A pointer to the current device path instance.
3820d1ba665SWarner Losh 
3830d1ba665SWarner Losh **/
3840d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
3850d1ba665SWarner Losh EFIAPI
3860d1ba665SWarner Losh GetNextDevicePathInstance (
3870d1ba665SWarner Losh   IN OUT EFI_DEVICE_PATH_PROTOCOL    **DevicePath,
3880d1ba665SWarner Losh   OUT UINTN                          *Size
3890d1ba665SWarner Losh   );
3900d1ba665SWarner Losh 
3910d1ba665SWarner Losh /**
3920d1ba665SWarner Losh   Creates a device node.
3930d1ba665SWarner Losh 
3940d1ba665SWarner Losh   This function creates a new device node in a newly allocated buffer of size NodeLength and
3950d1ba665SWarner Losh   initializes the device path node header with NodeType and NodeSubType.  The new device path node
3960d1ba665SWarner Losh   is returned.
3970d1ba665SWarner Losh   If NodeLength is smaller than a device path header, then NULL is returned.
3980d1ba665SWarner Losh   If there is not enough memory to allocate space for the new device path, then NULL is returned.
3990d1ba665SWarner Losh   The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
4000d1ba665SWarner Losh   free the memory allocated.
4010d1ba665SWarner Losh 
4020d1ba665SWarner Losh   @param  NodeType                   The device node type for the new device node.
4030d1ba665SWarner Losh   @param  NodeSubType                The device node sub-type for the new device node.
4040d1ba665SWarner Losh   @param  NodeLength                 The length of the new device node.
4050d1ba665SWarner Losh 
4060d1ba665SWarner Losh   @return The new device path.
4070d1ba665SWarner Losh 
4080d1ba665SWarner Losh **/
4090d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
4100d1ba665SWarner Losh EFIAPI
4110d1ba665SWarner Losh CreateDeviceNode (
4120d1ba665SWarner Losh   IN UINT8                           NodeType,
4130d1ba665SWarner Losh   IN UINT8                           NodeSubType,
4140d1ba665SWarner Losh   IN UINT16                          NodeLength
4150d1ba665SWarner Losh   );
4160d1ba665SWarner Losh 
4170d1ba665SWarner Losh /**
4180d1ba665SWarner Losh   Determines if a device path is single or multi-instance.
4190d1ba665SWarner Losh 
4200d1ba665SWarner Losh   This function returns TRUE if the device path specified by DevicePath is multi-instance.
4210d1ba665SWarner Losh   Otherwise, FALSE is returned.
4220d1ba665SWarner Losh   If DevicePath is NULL or invalid, then FALSE is returned.
4230d1ba665SWarner Losh 
4240d1ba665SWarner Losh   @param  DevicePath                 A pointer to a device path data structure.
4250d1ba665SWarner Losh 
4260d1ba665SWarner Losh   @retval  TRUE                      DevicePath is multi-instance.
4270d1ba665SWarner Losh   @retval  FALSE                     DevicePath is not multi-instance, or DevicePath is NULL or invalid.
4280d1ba665SWarner Losh 
4290d1ba665SWarner Losh **/
4300d1ba665SWarner Losh BOOLEAN
4310d1ba665SWarner Losh EFIAPI
4320d1ba665SWarner Losh IsDevicePathMultiInstance (
4330d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
4340d1ba665SWarner Losh   );
4350d1ba665SWarner Losh 
4360d1ba665SWarner Losh /**
4370d1ba665SWarner Losh   Retrieves the device path protocol from a handle.
4380d1ba665SWarner Losh 
4390d1ba665SWarner Losh   This function returns the device path protocol from the handle specified by Handle.  If Handle is
4400d1ba665SWarner Losh   NULL or Handle does not contain a device path protocol, then NULL is returned.
4410d1ba665SWarner Losh 
4420d1ba665SWarner Losh   @param  Handle                     The handle from which to retrieve the device path protocol.
4430d1ba665SWarner Losh 
4440d1ba665SWarner Losh   @return The device path protocol from the handle specified by Handle.
4450d1ba665SWarner Losh 
4460d1ba665SWarner Losh **/
4470d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
4480d1ba665SWarner Losh EFIAPI
4490d1ba665SWarner Losh DevicePathFromHandle (
4500d1ba665SWarner Losh   IN EFI_HANDLE                      Handle
4510d1ba665SWarner Losh   );
4520d1ba665SWarner Losh 
4530d1ba665SWarner Losh /**
4540d1ba665SWarner Losh   Allocates a device path for a file and appends it to an existing device path.
4550d1ba665SWarner Losh 
4560d1ba665SWarner Losh   If Device is a valid device handle that contains a device path protocol, then a device path for
4570d1ba665SWarner Losh   the file specified by FileName  is allocated and appended to the device path associated with the
4580d1ba665SWarner Losh   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
4590d1ba665SWarner Losh   that does not support the device path protocol, then a device path containing a single device
4600d1ba665SWarner Losh   path node for the file specified by FileName is allocated and returned.
4610d1ba665SWarner Losh   The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
4620d1ba665SWarner Losh   of the caller to free the memory allocated.
4630d1ba665SWarner Losh 
4640d1ba665SWarner Losh   If FileName is NULL, then ASSERT().
4650d1ba665SWarner Losh   If FileName is not aligned on a 16-bit boundary, then ASSERT().
4660d1ba665SWarner Losh 
4670d1ba665SWarner Losh   @param  Device                     A pointer to a device handle.  This parameter is optional and
4680d1ba665SWarner Losh                                      may be NULL.
4690d1ba665SWarner Losh   @param  FileName                   A pointer to a Null-terminated Unicode string.
4700d1ba665SWarner Losh 
4710d1ba665SWarner Losh   @return The allocated device path.
4720d1ba665SWarner Losh 
4730d1ba665SWarner Losh **/
4740d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
4750d1ba665SWarner Losh EFIAPI
4760d1ba665SWarner Losh FileDevicePath (
4770d1ba665SWarner Losh   IN EFI_HANDLE                      Device,     OPTIONAL
4780d1ba665SWarner Losh   IN CONST CHAR16                    *FileName
4790d1ba665SWarner Losh   );
4800d1ba665SWarner Losh 
4810d1ba665SWarner Losh /**
4820d1ba665SWarner Losh   Converts a device path to its text representation.
4830d1ba665SWarner Losh 
4840d1ba665SWarner Losh   @param DevicePath      A Pointer to the device to be converted.
4850d1ba665SWarner Losh   @param DisplayOnly     If DisplayOnly is TRUE, then the shorter text representation
4860d1ba665SWarner Losh                          of the display node is used, where applicable. If DisplayOnly
4870d1ba665SWarner Losh                          is FALSE, then the longer text representation of the display node
4880d1ba665SWarner Losh                          is used.
4890d1ba665SWarner Losh   @param AllowShortcuts  If AllowShortcuts is TRUE, then the shortcut forms of text
4900d1ba665SWarner Losh                          representation for a device node can be used, where applicable.
4910d1ba665SWarner Losh 
4920d1ba665SWarner Losh   @return A pointer to the allocated text representation of the device path or
4930d1ba665SWarner Losh           NULL if DeviceNode is NULL or there was insufficient memory.
4940d1ba665SWarner Losh 
4950d1ba665SWarner Losh **/
4960d1ba665SWarner Losh CHAR16 *
4970d1ba665SWarner Losh EFIAPI
4980d1ba665SWarner Losh ConvertDevicePathToText (
4990d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath,
5000d1ba665SWarner Losh   IN BOOLEAN                          DisplayOnly,
5010d1ba665SWarner Losh   IN BOOLEAN                          AllowShortcuts
5020d1ba665SWarner Losh   );
5030d1ba665SWarner Losh 
5040d1ba665SWarner Losh /**
5050d1ba665SWarner Losh   Converts a device node to its string representation.
5060d1ba665SWarner Losh 
5070d1ba665SWarner Losh   @param DeviceNode        A Pointer to the device node to be converted.
5080d1ba665SWarner Losh   @param DisplayOnly       If DisplayOnly is TRUE, then the shorter text representation
5090d1ba665SWarner Losh                            of the display node is used, where applicable. If DisplayOnly
5100d1ba665SWarner Losh                            is FALSE, then the longer text representation of the display node
5110d1ba665SWarner Losh                            is used.
5120d1ba665SWarner Losh   @param AllowShortcuts    If AllowShortcuts is TRUE, then the shortcut forms of text
5130d1ba665SWarner Losh                            representation for a device node can be used, where applicable.
5140d1ba665SWarner Losh 
5150d1ba665SWarner Losh   @return A pointer to the allocated text representation of the device node or NULL if DeviceNode
5160d1ba665SWarner Losh           is NULL or there was insufficient memory.
5170d1ba665SWarner Losh 
5180d1ba665SWarner Losh **/
5190d1ba665SWarner Losh CHAR16 *
5200d1ba665SWarner Losh EFIAPI
5210d1ba665SWarner Losh ConvertDeviceNodeToText (
5220d1ba665SWarner Losh   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DeviceNode,
5230d1ba665SWarner Losh   IN BOOLEAN                         DisplayOnly,
5240d1ba665SWarner Losh   IN BOOLEAN                         AllowShortcuts
5250d1ba665SWarner Losh   );
5260d1ba665SWarner Losh 
5270d1ba665SWarner Losh /**
5280d1ba665SWarner Losh   Convert text to the binary representation of a device node.
5290d1ba665SWarner Losh 
5300d1ba665SWarner Losh   @param TextDeviceNode  TextDeviceNode points to the text representation of a device
5310d1ba665SWarner Losh                          node. Conversion starts with the first character and continues
5320d1ba665SWarner Losh                          until the first non-device node character.
5330d1ba665SWarner Losh 
5340d1ba665SWarner Losh   @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was
5350d1ba665SWarner Losh           insufficient memory or text unsupported.
5360d1ba665SWarner Losh 
5370d1ba665SWarner Losh **/
5380d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
5390d1ba665SWarner Losh EFIAPI
5400d1ba665SWarner Losh ConvertTextToDeviceNode (
5410d1ba665SWarner Losh   IN CONST CHAR16 *TextDeviceNode
5420d1ba665SWarner Losh   );
5430d1ba665SWarner Losh 
5440d1ba665SWarner Losh /**
5450d1ba665SWarner Losh   Convert text to the binary representation of a device path.
5460d1ba665SWarner Losh 
5470d1ba665SWarner Losh   @param TextDevicePath  TextDevicePath points to the text representation of a device
5480d1ba665SWarner Losh                          path. Conversion starts with the first character and continues
5490d1ba665SWarner Losh                          until the first non-device node character.
5500d1ba665SWarner Losh 
5510d1ba665SWarner Losh   @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or
5520d1ba665SWarner Losh           there was insufficient memory.
5530d1ba665SWarner Losh 
5540d1ba665SWarner Losh **/
5550d1ba665SWarner Losh EFI_DEVICE_PATH_PROTOCOL *
5560d1ba665SWarner Losh EFIAPI
5570d1ba665SWarner Losh ConvertTextToDevicePath (
5580d1ba665SWarner Losh   IN CONST CHAR16 *TextDevicePath
5590d1ba665SWarner Losh   );
5600d1ba665SWarner Losh 
5610d1ba665SWarner Losh #endif
562