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