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