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