1*1370a723SSascha Wildner /** @file 2*1370a723SSascha Wildner Provides library functions to construct and parse UEFI Device Paths. 3*1370a723SSascha Wildner 4*1370a723SSascha Wildner This library provides defines, macros, and functions to help create and parse 5*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL structures. 6*1370a723SSascha Wildner 7*1370a723SSascha Wildner Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 8*1370a723SSascha Wildner SPDX-License-Identifier: BSD-2-Clause-Patent 9*1370a723SSascha Wildner 10*1370a723SSascha Wildner **/ 11*1370a723SSascha Wildner 12*1370a723SSascha Wildner #ifndef __DEVICE_PATH_LIB_H__ 13*1370a723SSascha Wildner #define __DEVICE_PATH_LIB_H__ 14*1370a723SSascha Wildner 15*1370a723SSascha Wildner #define END_DEVICE_PATH_LENGTH (sizeof (EFI_DEVICE_PATH_PROTOCOL)) 16*1370a723SSascha Wildner 17*1370a723SSascha Wildner /** 18*1370a723SSascha Wildner Determine whether a given device path is valid. 19*1370a723SSascha Wildner 20*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 21*1370a723SSascha Wildner @param MaxSize The maximum size of the device path data structure. 22*1370a723SSascha Wildner 23*1370a723SSascha Wildner @retval TRUE DevicePath is valid. 24*1370a723SSascha Wildner @retval FALSE DevicePath is NULL. 25*1370a723SSascha Wildner @retval FALSE Maxsize is less than sizeof(EFI_DEVICE_PATH_PROTOCOL). 26*1370a723SSascha Wildner @retval FALSE The length of any node node in the DevicePath is less 27*1370a723SSascha Wildner than sizeof (EFI_DEVICE_PATH_PROTOCOL). 28*1370a723SSascha Wildner @retval FALSE If MaxSize is not zero, the size of the DevicePath 29*1370a723SSascha Wildner exceeds MaxSize. 30*1370a723SSascha Wildner @retval FALSE If PcdMaximumDevicePathNodeCount is not zero, the node 31*1370a723SSascha Wildner count of the DevicePath exceeds PcdMaximumDevicePathNodeCount. 32*1370a723SSascha Wildner **/ 33*1370a723SSascha Wildner BOOLEAN 34*1370a723SSascha Wildner EFIAPI 35*1370a723SSascha Wildner IsDevicePathValid ( 36*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, 37*1370a723SSascha Wildner IN UINTN MaxSize 38*1370a723SSascha Wildner ); 39*1370a723SSascha Wildner 40*1370a723SSascha Wildner /** 41*1370a723SSascha Wildner Returns the Type field of a device path node. 42*1370a723SSascha Wildner 43*1370a723SSascha Wildner Returns the Type field of the device path node specified by Node. 44*1370a723SSascha Wildner 45*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 46*1370a723SSascha Wildner 47*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 48*1370a723SSascha Wildner 49*1370a723SSascha Wildner @return The Type field of the device path node specified by Node. 50*1370a723SSascha Wildner 51*1370a723SSascha Wildner **/ 52*1370a723SSascha Wildner UINT8 53*1370a723SSascha Wildner EFIAPI 54*1370a723SSascha Wildner DevicePathType ( 55*1370a723SSascha Wildner IN CONST VOID *Node 56*1370a723SSascha Wildner ); 57*1370a723SSascha Wildner 58*1370a723SSascha Wildner /** 59*1370a723SSascha Wildner Returns the SubType field of a device path node. 60*1370a723SSascha Wildner 61*1370a723SSascha Wildner Returns the SubType field of the device path node specified by Node. 62*1370a723SSascha Wildner 63*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 64*1370a723SSascha Wildner 65*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 66*1370a723SSascha Wildner 67*1370a723SSascha Wildner @return The SubType field of the device path node specified by Node. 68*1370a723SSascha Wildner 69*1370a723SSascha Wildner **/ 70*1370a723SSascha Wildner UINT8 71*1370a723SSascha Wildner EFIAPI 72*1370a723SSascha Wildner DevicePathSubType ( 73*1370a723SSascha Wildner IN CONST VOID *Node 74*1370a723SSascha Wildner ); 75*1370a723SSascha Wildner 76*1370a723SSascha Wildner /** 77*1370a723SSascha Wildner Returns the 16-bit Length field of a device path node. 78*1370a723SSascha Wildner 79*1370a723SSascha Wildner Returns the 16-bit Length field of the device path node specified by Node. 80*1370a723SSascha Wildner Node is not required to be aligned on a 16-bit boundary, so it is recommended 81*1370a723SSascha Wildner that a function such as ReadUnaligned16() be used to extract the contents of 82*1370a723SSascha Wildner the Length field. 83*1370a723SSascha Wildner 84*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 85*1370a723SSascha Wildner 86*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 87*1370a723SSascha Wildner 88*1370a723SSascha Wildner @return The 16-bit Length field of the device path node specified by Node. 89*1370a723SSascha Wildner 90*1370a723SSascha Wildner **/ 91*1370a723SSascha Wildner UINTN 92*1370a723SSascha Wildner EFIAPI 93*1370a723SSascha Wildner DevicePathNodeLength ( 94*1370a723SSascha Wildner IN CONST VOID *Node 95*1370a723SSascha Wildner ); 96*1370a723SSascha Wildner 97*1370a723SSascha Wildner /** 98*1370a723SSascha Wildner Returns a pointer to the next node in a device path. 99*1370a723SSascha Wildner 100*1370a723SSascha Wildner Returns a pointer to the device path node that follows the device path node specified by Node. 101*1370a723SSascha Wildner 102*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 103*1370a723SSascha Wildner 104*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 105*1370a723SSascha Wildner 106*1370a723SSascha Wildner @return a pointer to the device path node that follows the device path node specified by Node. 107*1370a723SSascha Wildner 108*1370a723SSascha Wildner **/ 109*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 110*1370a723SSascha Wildner EFIAPI 111*1370a723SSascha Wildner NextDevicePathNode ( 112*1370a723SSascha Wildner IN CONST VOID *Node 113*1370a723SSascha Wildner ); 114*1370a723SSascha Wildner 115*1370a723SSascha Wildner /** 116*1370a723SSascha Wildner Determines if a device path node is an end node of a device path. 117*1370a723SSascha Wildner This includes nodes that are the end of a device path instance and nodes that 118*1370a723SSascha Wildner are the end of an entire device path. 119*1370a723SSascha Wildner 120*1370a723SSascha Wildner Determines if the device path node specified by Node is an end node of a device path. 121*1370a723SSascha Wildner This includes nodes that are the end of a device path instance and nodes that are the 122*1370a723SSascha Wildner end of an entire device path. If Node represents an end node of a device path, 123*1370a723SSascha Wildner then TRUE is returned. Otherwise, FALSE is returned. 124*1370a723SSascha Wildner 125*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 126*1370a723SSascha Wildner 127*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 128*1370a723SSascha Wildner 129*1370a723SSascha Wildner @retval TRUE The device path node specified by Node is an end node of a device path. 130*1370a723SSascha Wildner @retval FALSE The device path node specified by Node is not an end node of a device path. 131*1370a723SSascha Wildner 132*1370a723SSascha Wildner **/ 133*1370a723SSascha Wildner BOOLEAN 134*1370a723SSascha Wildner EFIAPI 135*1370a723SSascha Wildner IsDevicePathEndType ( 136*1370a723SSascha Wildner IN CONST VOID *Node 137*1370a723SSascha Wildner ); 138*1370a723SSascha Wildner 139*1370a723SSascha Wildner /** 140*1370a723SSascha Wildner Determines if a device path node is an end node of an entire device path. 141*1370a723SSascha Wildner 142*1370a723SSascha Wildner Determines if a device path node specified by Node is an end node of an entire device path. 143*1370a723SSascha Wildner If Node represents the end of an entire device path, then TRUE is returned. 144*1370a723SSascha Wildner Otherwise, FALSE is returned. 145*1370a723SSascha Wildner 146*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 147*1370a723SSascha Wildner 148*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 149*1370a723SSascha Wildner 150*1370a723SSascha Wildner @retval TRUE The device path node specified by Node is the end of an entire device path. 151*1370a723SSascha Wildner @retval FALSE The device path node specified by Node is not the end of an entire device path. 152*1370a723SSascha Wildner 153*1370a723SSascha Wildner **/ 154*1370a723SSascha Wildner BOOLEAN 155*1370a723SSascha Wildner EFIAPI 156*1370a723SSascha Wildner IsDevicePathEnd ( 157*1370a723SSascha Wildner IN CONST VOID *Node 158*1370a723SSascha Wildner ); 159*1370a723SSascha Wildner 160*1370a723SSascha Wildner /** 161*1370a723SSascha Wildner Determines if a device path node is an end node of a device path instance. 162*1370a723SSascha Wildner 163*1370a723SSascha Wildner Determines if a device path node specified by Node is an end node of a device path instance. 164*1370a723SSascha Wildner If Node represents the end of a device path instance, then TRUE is returned. 165*1370a723SSascha Wildner Otherwise, FALSE is returned. 166*1370a723SSascha Wildner 167*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 168*1370a723SSascha Wildner 169*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 170*1370a723SSascha Wildner 171*1370a723SSascha Wildner @retval TRUE The device path node specified by Node is the end of a device path instance. 172*1370a723SSascha Wildner @retval FALSE The device path node specified by Node is not the end of a device path instance. 173*1370a723SSascha Wildner 174*1370a723SSascha Wildner **/ 175*1370a723SSascha Wildner BOOLEAN 176*1370a723SSascha Wildner EFIAPI 177*1370a723SSascha Wildner IsDevicePathEndInstance ( 178*1370a723SSascha Wildner IN CONST VOID *Node 179*1370a723SSascha Wildner ); 180*1370a723SSascha Wildner 181*1370a723SSascha Wildner /** 182*1370a723SSascha Wildner Sets the length, in bytes, of a device path node. 183*1370a723SSascha Wildner 184*1370a723SSascha Wildner Sets the length of the device path node specified by Node to the value specified 185*1370a723SSascha Wildner by NodeLength. NodeLength is returned. Node is not required to be aligned on 186*1370a723SSascha Wildner a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16() 187*1370a723SSascha Wildner be used to set the contents of the Length field. 188*1370a723SSascha Wildner 189*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 190*1370a723SSascha Wildner If NodeLength >= 0x10000, then ASSERT(). 191*1370a723SSascha Wildner If NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL), then ASSERT(). 192*1370a723SSascha Wildner 193*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 194*1370a723SSascha Wildner @param Length The length, in bytes, of the device path node. 195*1370a723SSascha Wildner 196*1370a723SSascha Wildner @return Length 197*1370a723SSascha Wildner 198*1370a723SSascha Wildner **/ 199*1370a723SSascha Wildner UINT16 200*1370a723SSascha Wildner EFIAPI 201*1370a723SSascha Wildner SetDevicePathNodeLength ( 202*1370a723SSascha Wildner IN OUT VOID *Node, 203*1370a723SSascha Wildner IN UINTN Length 204*1370a723SSascha Wildner ); 205*1370a723SSascha Wildner 206*1370a723SSascha Wildner /** 207*1370a723SSascha Wildner Fills in all the fields of a device path node that is the end of an entire device path. 208*1370a723SSascha Wildner 209*1370a723SSascha Wildner Fills in all the fields of a device path node specified by Node so Node represents 210*1370a723SSascha Wildner the end of an entire device path. The Type field of Node is set to 211*1370a723SSascha Wildner END_DEVICE_PATH_TYPE, the SubType field of Node is set to 212*1370a723SSascha Wildner END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to 213*1370a723SSascha Wildner END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary, 214*1370a723SSascha Wildner so it is recommended that a function such as WriteUnaligned16() be used to set 215*1370a723SSascha Wildner the contents of the Length field. 216*1370a723SSascha Wildner 217*1370a723SSascha Wildner If Node is NULL, then ASSERT(). 218*1370a723SSascha Wildner 219*1370a723SSascha Wildner @param Node A pointer to a device path node data structure. 220*1370a723SSascha Wildner 221*1370a723SSascha Wildner **/ 222*1370a723SSascha Wildner VOID 223*1370a723SSascha Wildner EFIAPI 224*1370a723SSascha Wildner SetDevicePathEndNode ( 225*1370a723SSascha Wildner OUT VOID *Node 226*1370a723SSascha Wildner ); 227*1370a723SSascha Wildner 228*1370a723SSascha Wildner /** 229*1370a723SSascha Wildner Returns the size of a device path in bytes. 230*1370a723SSascha Wildner 231*1370a723SSascha Wildner This function returns the size, in bytes, of the device path data structure 232*1370a723SSascha Wildner specified by DevicePath including the end of device path node. 233*1370a723SSascha Wildner If DevicePath is NULL or invalid, then 0 is returned. 234*1370a723SSascha Wildner 235*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 236*1370a723SSascha Wildner 237*1370a723SSascha Wildner @retval 0 If DevicePath is NULL or invalid. 238*1370a723SSascha Wildner @retval Others The size of a device path in bytes. 239*1370a723SSascha Wildner 240*1370a723SSascha Wildner **/ 241*1370a723SSascha Wildner UINTN 242*1370a723SSascha Wildner EFIAPI 243*1370a723SSascha Wildner GetDevicePathSize ( 244*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath 245*1370a723SSascha Wildner ); 246*1370a723SSascha Wildner 247*1370a723SSascha Wildner /** 248*1370a723SSascha Wildner Creates a new copy of an existing device path. 249*1370a723SSascha Wildner 250*1370a723SSascha Wildner This function allocates space for a new copy of the device path specified by DevicePath. If 251*1370a723SSascha Wildner DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the 252*1370a723SSascha Wildner contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer 253*1370a723SSascha Wildner is returned. Otherwise, NULL is returned. 254*1370a723SSascha Wildner The memory for the new device path is allocated from EFI boot services memory. 255*1370a723SSascha Wildner It is the responsibility of the caller to free the memory allocated. 256*1370a723SSascha Wildner 257*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 258*1370a723SSascha Wildner 259*1370a723SSascha Wildner @retval NULL DevicePath is NULL or invalid. 260*1370a723SSascha Wildner @retval Others A pointer to the duplicated device path. 261*1370a723SSascha Wildner 262*1370a723SSascha Wildner **/ 263*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 264*1370a723SSascha Wildner EFIAPI 265*1370a723SSascha Wildner DuplicateDevicePath ( 266*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath 267*1370a723SSascha Wildner ); 268*1370a723SSascha Wildner 269*1370a723SSascha Wildner /** 270*1370a723SSascha Wildner Creates a new device path by appending a second device path to a first device path. 271*1370a723SSascha Wildner 272*1370a723SSascha Wildner This function creates a new device path by appending a copy of SecondDevicePath to a copy of 273*1370a723SSascha Wildner FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from 274*1370a723SSascha Wildner SecondDevicePath is retained. The newly created device path is returned. 275*1370a723SSascha Wildner If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned. 276*1370a723SSascha Wildner If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned. 277*1370a723SSascha Wildner If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is 278*1370a723SSascha Wildner returned. 279*1370a723SSascha Wildner If there is not enough memory for the newly allocated buffer, then NULL is returned. 280*1370a723SSascha Wildner The memory for the new device path is allocated from EFI boot services memory. It is the 281*1370a723SSascha Wildner responsibility of the caller to free the memory allocated. 282*1370a723SSascha Wildner 283*1370a723SSascha Wildner @param FirstDevicePath A pointer to a device path data structure. 284*1370a723SSascha Wildner @param SecondDevicePath A pointer to a device path data structure. 285*1370a723SSascha Wildner 286*1370a723SSascha Wildner @retval NULL If there is not enough memory for the newly allocated buffer. 287*1370a723SSascha Wildner @retval NULL If FirstDevicePath or SecondDevicePath is invalid. 288*1370a723SSascha Wildner @retval Others A pointer to the new device path if success. 289*1370a723SSascha Wildner Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL. 290*1370a723SSascha Wildner 291*1370a723SSascha Wildner **/ 292*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 293*1370a723SSascha Wildner EFIAPI 294*1370a723SSascha Wildner AppendDevicePath ( 295*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath OPTIONAL, 296*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath OPTIONAL 297*1370a723SSascha Wildner ); 298*1370a723SSascha Wildner 299*1370a723SSascha Wildner /** 300*1370a723SSascha Wildner Creates a new path by appending the device node to the device path. 301*1370a723SSascha Wildner 302*1370a723SSascha Wildner This function creates a new device path by appending a copy of the device node specified by 303*1370a723SSascha Wildner DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer. 304*1370a723SSascha Wildner The end-of-device-path device node is moved after the end of the appended device node. 305*1370a723SSascha Wildner If DevicePathNode is NULL then a copy of DevicePath is returned. 306*1370a723SSascha Wildner If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device 307*1370a723SSascha Wildner node is returned. 308*1370a723SSascha Wildner If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node 309*1370a723SSascha Wildner is returned. 310*1370a723SSascha Wildner If there is not enough memory to allocate space for the new device path, then NULL is returned. 311*1370a723SSascha Wildner The memory is allocated from EFI boot services memory. It is the responsibility of the caller to 312*1370a723SSascha Wildner free the memory allocated. 313*1370a723SSascha Wildner 314*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 315*1370a723SSascha Wildner @param DevicePathNode A pointer to a single device path node. 316*1370a723SSascha Wildner 317*1370a723SSascha Wildner @retval NULL There is not enough memory for the new device path. 318*1370a723SSascha Wildner @retval Others A pointer to the new device path if success. 319*1370a723SSascha Wildner A copy of DevicePathNode followed by an end-of-device-path node 320*1370a723SSascha Wildner if both FirstDevicePath and SecondDevicePath are NULL. 321*1370a723SSascha Wildner A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL. 322*1370a723SSascha Wildner 323*1370a723SSascha Wildner **/ 324*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 325*1370a723SSascha Wildner EFIAPI 326*1370a723SSascha Wildner AppendDevicePathNode ( 327*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath OPTIONAL, 328*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode OPTIONAL 329*1370a723SSascha Wildner ); 330*1370a723SSascha Wildner 331*1370a723SSascha Wildner /** 332*1370a723SSascha Wildner Creates a new device path by appending the specified device path instance to the specified device 333*1370a723SSascha Wildner path. 334*1370a723SSascha Wildner 335*1370a723SSascha Wildner This function creates a new device path by appending a copy of the device path instance specified 336*1370a723SSascha Wildner by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer. 337*1370a723SSascha Wildner The end-of-device-path device node is moved after the end of the appended device path instance 338*1370a723SSascha Wildner and a new end-of-device-path-instance node is inserted between. 339*1370a723SSascha Wildner If DevicePath is NULL, then a copy if DevicePathInstance is returned. 340*1370a723SSascha Wildner If DevicePathInstance is NULL, then NULL is returned. 341*1370a723SSascha Wildner If DevicePath or DevicePathInstance is invalid, then NULL is returned. 342*1370a723SSascha Wildner If there is not enough memory to allocate space for the new device path, then NULL is returned. 343*1370a723SSascha Wildner The memory is allocated from EFI boot services memory. It is the responsibility of the caller to 344*1370a723SSascha Wildner free the memory allocated. 345*1370a723SSascha Wildner 346*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 347*1370a723SSascha Wildner @param DevicePathInstance A pointer to a device path instance. 348*1370a723SSascha Wildner 349*1370a723SSascha Wildner @return A pointer to the new device path. 350*1370a723SSascha Wildner 351*1370a723SSascha Wildner **/ 352*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 353*1370a723SSascha Wildner EFIAPI 354*1370a723SSascha Wildner AppendDevicePathInstance ( 355*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath OPTIONAL, 356*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance OPTIONAL 357*1370a723SSascha Wildner ); 358*1370a723SSascha Wildner 359*1370a723SSascha Wildner /** 360*1370a723SSascha Wildner Creates a copy of the current device path instance and returns a pointer to the next device path 361*1370a723SSascha Wildner instance. 362*1370a723SSascha Wildner 363*1370a723SSascha Wildner This function creates a copy of the current device path instance. It also updates DevicePath to 364*1370a723SSascha Wildner point to the next device path instance in the device path (or NULL if no more) and updates Size 365*1370a723SSascha Wildner to hold the size of the device path instance copy. 366*1370a723SSascha Wildner If DevicePath is NULL, then NULL is returned. 367*1370a723SSascha Wildner If DevicePath points to a invalid device path, then NULL is returned. 368*1370a723SSascha Wildner If there is not enough memory to allocate space for the new device path, then NULL is returned. 369*1370a723SSascha Wildner The memory is allocated from EFI boot services memory. It is the responsibility of the caller to 370*1370a723SSascha Wildner free the memory allocated. 371*1370a723SSascha Wildner If Size is NULL, then ASSERT(). 372*1370a723SSascha Wildner 373*1370a723SSascha Wildner @param DevicePath On input, this holds the pointer to the current device path 374*1370a723SSascha Wildner instance. On output, this holds the pointer to the next device 375*1370a723SSascha Wildner path instance or NULL if there are no more device path 376*1370a723SSascha Wildner instances in the device path pointer to a device path data 377*1370a723SSascha Wildner structure. 378*1370a723SSascha Wildner @param Size On output, this holds the size of the device path instance, in 379*1370a723SSascha Wildner bytes or zero, if DevicePath is NULL. 380*1370a723SSascha Wildner 381*1370a723SSascha Wildner @return A pointer to the current device path instance. 382*1370a723SSascha Wildner 383*1370a723SSascha Wildner **/ 384*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 385*1370a723SSascha Wildner EFIAPI 386*1370a723SSascha Wildner GetNextDevicePathInstance ( 387*1370a723SSascha Wildner IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath, 388*1370a723SSascha Wildner OUT UINTN *Size 389*1370a723SSascha Wildner ); 390*1370a723SSascha Wildner 391*1370a723SSascha Wildner /** 392*1370a723SSascha Wildner Creates a device node. 393*1370a723SSascha Wildner 394*1370a723SSascha Wildner This function creates a new device node in a newly allocated buffer of size NodeLength and 395*1370a723SSascha Wildner initializes the device path node header with NodeType and NodeSubType. The new device path node 396*1370a723SSascha Wildner is returned. 397*1370a723SSascha Wildner If NodeLength is smaller than a device path header, then NULL is returned. 398*1370a723SSascha Wildner If there is not enough memory to allocate space for the new device path, then NULL is returned. 399*1370a723SSascha Wildner The memory is allocated from EFI boot services memory. It is the responsibility of the caller to 400*1370a723SSascha Wildner free the memory allocated. 401*1370a723SSascha Wildner 402*1370a723SSascha Wildner @param NodeType The device node type for the new device node. 403*1370a723SSascha Wildner @param NodeSubType The device node sub-type for the new device node. 404*1370a723SSascha Wildner @param NodeLength The length of the new device node. 405*1370a723SSascha Wildner 406*1370a723SSascha Wildner @return The new device path. 407*1370a723SSascha Wildner 408*1370a723SSascha Wildner **/ 409*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 410*1370a723SSascha Wildner EFIAPI 411*1370a723SSascha Wildner CreateDeviceNode ( 412*1370a723SSascha Wildner IN UINT8 NodeType, 413*1370a723SSascha Wildner IN UINT8 NodeSubType, 414*1370a723SSascha Wildner IN UINT16 NodeLength 415*1370a723SSascha Wildner ); 416*1370a723SSascha Wildner 417*1370a723SSascha Wildner /** 418*1370a723SSascha Wildner Determines if a device path is single or multi-instance. 419*1370a723SSascha Wildner 420*1370a723SSascha Wildner This function returns TRUE if the device path specified by DevicePath is multi-instance. 421*1370a723SSascha Wildner Otherwise, FALSE is returned. 422*1370a723SSascha Wildner If DevicePath is NULL or invalid, then FALSE is returned. 423*1370a723SSascha Wildner 424*1370a723SSascha Wildner @param DevicePath A pointer to a device path data structure. 425*1370a723SSascha Wildner 426*1370a723SSascha Wildner @retval TRUE DevicePath is multi-instance. 427*1370a723SSascha Wildner @retval FALSE DevicePath is not multi-instance, or DevicePath is NULL or invalid. 428*1370a723SSascha Wildner 429*1370a723SSascha Wildner **/ 430*1370a723SSascha Wildner BOOLEAN 431*1370a723SSascha Wildner EFIAPI 432*1370a723SSascha Wildner IsDevicePathMultiInstance ( 433*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath 434*1370a723SSascha Wildner ); 435*1370a723SSascha Wildner 436*1370a723SSascha Wildner /** 437*1370a723SSascha Wildner Retrieves the device path protocol from a handle. 438*1370a723SSascha Wildner 439*1370a723SSascha Wildner This function returns the device path protocol from the handle specified by Handle. If Handle is 440*1370a723SSascha Wildner NULL or Handle does not contain a device path protocol, then NULL is returned. 441*1370a723SSascha Wildner 442*1370a723SSascha Wildner @param Handle The handle from which to retrieve the device path protocol. 443*1370a723SSascha Wildner 444*1370a723SSascha Wildner @return The device path protocol from the handle specified by Handle. 445*1370a723SSascha Wildner 446*1370a723SSascha Wildner **/ 447*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 448*1370a723SSascha Wildner EFIAPI 449*1370a723SSascha Wildner DevicePathFromHandle ( 450*1370a723SSascha Wildner IN EFI_HANDLE Handle 451*1370a723SSascha Wildner ); 452*1370a723SSascha Wildner 453*1370a723SSascha Wildner /** 454*1370a723SSascha Wildner Allocates a device path for a file and appends it to an existing device path. 455*1370a723SSascha Wildner 456*1370a723SSascha Wildner If Device is a valid device handle that contains a device path protocol, then a device path for 457*1370a723SSascha Wildner the file specified by FileName is allocated and appended to the device path associated with the 458*1370a723SSascha Wildner handle Device. The allocated device path is returned. If Device is NULL or Device is a handle 459*1370a723SSascha Wildner that does not support the device path protocol, then a device path containing a single device 460*1370a723SSascha Wildner path node for the file specified by FileName is allocated and returned. 461*1370a723SSascha Wildner The memory for the new device path is allocated from EFI boot services memory. It is the responsibility 462*1370a723SSascha Wildner of the caller to free the memory allocated. 463*1370a723SSascha Wildner 464*1370a723SSascha Wildner If FileName is NULL, then ASSERT(). 465*1370a723SSascha Wildner If FileName is not aligned on a 16-bit boundary, then ASSERT(). 466*1370a723SSascha Wildner 467*1370a723SSascha Wildner @param Device A pointer to a device handle. This parameter is optional and 468*1370a723SSascha Wildner may be NULL. 469*1370a723SSascha Wildner @param FileName A pointer to a Null-terminated Unicode string. 470*1370a723SSascha Wildner 471*1370a723SSascha Wildner @return The allocated device path. 472*1370a723SSascha Wildner 473*1370a723SSascha Wildner **/ 474*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 475*1370a723SSascha Wildner EFIAPI 476*1370a723SSascha Wildner FileDevicePath ( 477*1370a723SSascha Wildner IN EFI_HANDLE Device OPTIONAL, 478*1370a723SSascha Wildner IN CONST CHAR16 *FileName 479*1370a723SSascha Wildner ); 480*1370a723SSascha Wildner 481*1370a723SSascha Wildner /** 482*1370a723SSascha Wildner Converts a device path to its text representation. 483*1370a723SSascha Wildner 484*1370a723SSascha Wildner @param DevicePath A Pointer to the device to be converted. 485*1370a723SSascha Wildner @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation 486*1370a723SSascha Wildner of the display node is used, where applicable. If DisplayOnly 487*1370a723SSascha Wildner is FALSE, then the longer text representation of the display node 488*1370a723SSascha Wildner is used. 489*1370a723SSascha Wildner @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text 490*1370a723SSascha Wildner representation for a device node can be used, where applicable. 491*1370a723SSascha Wildner 492*1370a723SSascha Wildner @return A pointer to the allocated text representation of the device path or 493*1370a723SSascha Wildner NULL if DeviceNode is NULL or there was insufficient memory. 494*1370a723SSascha Wildner 495*1370a723SSascha Wildner **/ 496*1370a723SSascha Wildner CHAR16 * 497*1370a723SSascha Wildner EFIAPI 498*1370a723SSascha Wildner ConvertDevicePathToText ( 499*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, 500*1370a723SSascha Wildner IN BOOLEAN DisplayOnly, 501*1370a723SSascha Wildner IN BOOLEAN AllowShortcuts 502*1370a723SSascha Wildner ); 503*1370a723SSascha Wildner 504*1370a723SSascha Wildner /** 505*1370a723SSascha Wildner Converts a device node to its string representation. 506*1370a723SSascha Wildner 507*1370a723SSascha Wildner @param DeviceNode A Pointer to the device node to be converted. 508*1370a723SSascha Wildner @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation 509*1370a723SSascha Wildner of the display node is used, where applicable. If DisplayOnly 510*1370a723SSascha Wildner is FALSE, then the longer text representation of the display node 511*1370a723SSascha Wildner is used. 512*1370a723SSascha Wildner @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text 513*1370a723SSascha Wildner representation for a device node can be used, where applicable. 514*1370a723SSascha Wildner 515*1370a723SSascha Wildner @return A pointer to the allocated text representation of the device node or NULL if DeviceNode 516*1370a723SSascha Wildner is NULL or there was insufficient memory. 517*1370a723SSascha Wildner 518*1370a723SSascha Wildner **/ 519*1370a723SSascha Wildner CHAR16 * 520*1370a723SSascha Wildner EFIAPI 521*1370a723SSascha Wildner ConvertDeviceNodeToText ( 522*1370a723SSascha Wildner IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode, 523*1370a723SSascha Wildner IN BOOLEAN DisplayOnly, 524*1370a723SSascha Wildner IN BOOLEAN AllowShortcuts 525*1370a723SSascha Wildner ); 526*1370a723SSascha Wildner 527*1370a723SSascha Wildner /** 528*1370a723SSascha Wildner Convert text to the binary representation of a device node. 529*1370a723SSascha Wildner 530*1370a723SSascha Wildner @param TextDeviceNode TextDeviceNode points to the text representation of a device 531*1370a723SSascha Wildner node. Conversion starts with the first character and continues 532*1370a723SSascha Wildner until the first non-device node character. 533*1370a723SSascha Wildner 534*1370a723SSascha Wildner @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was 535*1370a723SSascha Wildner insufficient memory or text unsupported. 536*1370a723SSascha Wildner 537*1370a723SSascha Wildner **/ 538*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 539*1370a723SSascha Wildner EFIAPI 540*1370a723SSascha Wildner ConvertTextToDeviceNode ( 541*1370a723SSascha Wildner IN CONST CHAR16 *TextDeviceNode 542*1370a723SSascha Wildner ); 543*1370a723SSascha Wildner 544*1370a723SSascha Wildner /** 545*1370a723SSascha Wildner Convert text to the binary representation of a device path. 546*1370a723SSascha Wildner 547*1370a723SSascha Wildner @param TextDevicePath TextDevicePath points to the text representation of a device 548*1370a723SSascha Wildner path. Conversion starts with the first character and continues 549*1370a723SSascha Wildner until the first non-device node character. 550*1370a723SSascha Wildner 551*1370a723SSascha Wildner @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or 552*1370a723SSascha Wildner there was insufficient memory. 553*1370a723SSascha Wildner 554*1370a723SSascha Wildner **/ 555*1370a723SSascha Wildner EFI_DEVICE_PATH_PROTOCOL * 556*1370a723SSascha Wildner EFIAPI 557*1370a723SSascha Wildner ConvertTextToDevicePath ( 558*1370a723SSascha Wildner IN CONST CHAR16 *TextDevicePath 559*1370a723SSascha Wildner ); 560*1370a723SSascha Wildner 561*1370a723SSascha Wildner #endif 562