2 Device Path services. The thing to remember is device paths are built out of
3 nodes. The device path is terminated by an end node that is length
4 sizeof(EFI_DEVICE_PATH_PROTOCOL). That would be why there is sizeof(EFI_DEVICE_PATH_PROTOCOL)
7 The only place where multi-instance device paths are supported is in
8 environment varibles. Multi-instance device paths should never be placed
11 Copyright (c) 2006 - 2009, Intel Corporation
12 All rights reserved. This program and the accompanying materials
13 are licensed and made available under the terms and conditions of the BSD License
14 which accompanies this distribution. The full text of the license may be found at
15 http://opensource.org/licenses/bsd-license.php
17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
25 #include <Library/DevicePathLib.h>
26 #include <Library/BaseMemoryLib.h>
27 #include <Library/DebugLib.h>
28 #include <Library/MemoryAllocationLib.h>
29 #include <Library/UefiBootServicesTableLib.h>
30 #include <Library/BaseLib.h>
33 // Template for an end-of-device path node.
35 GLOBAL_REMOVE_IF_UNREFERENCED CONST EFI_DEVICE_PATH_PROTOCOL mUefiDevicePathLibEndDevicePath
= {
37 END_ENTIRE_DEVICE_PATH_SUBTYPE
,
39 END_DEVICE_PATH_LENGTH
,
45 Returns the Type field of a device path node.
47 Returns the Type field of the device path node specified by Node.
49 If Node is NULL, then ASSERT().
51 @param Node A pointer to a device path node data structure.
53 @return The Type field of the device path node specified by Node.
62 ASSERT (Node
!= NULL
);
63 return ((EFI_DEVICE_PATH_PROTOCOL
*)(Node
))->Type
;
67 Returns the SubType field of a device path node.
69 Returns the SubType field of the device path node specified by Node.
71 If Node is NULL, then ASSERT().
73 @param Node A pointer to a device path node data structure.
75 @return The SubType field of the device path node specified by Node.
84 ASSERT (Node
!= NULL
);
85 return ((EFI_DEVICE_PATH_PROTOCOL
*)(Node
))->SubType
;
89 Returns the 16-bit Length field of a device path node.
91 Returns the 16-bit Length field of the device path node specified by Node.
92 Node is not required to be aligned on a 16-bit boundary, so it is recommended
93 that a function such as ReadUnaligned16() be used to extract the contents of
96 If Node is NULL, then ASSERT().
98 @param Node A pointer to a device path node data structure.
100 @return The 16-bit Length field of the device path node specified by Node.
105 DevicePathNodeLength (
109 ASSERT (Node
!= NULL
);
110 return ReadUnaligned16 ((UINT16
*)&((EFI_DEVICE_PATH_PROTOCOL
*)(Node
))->Length
[0]);
114 Returns a pointer to the next node in a device path.
116 Returns a pointer to the device path node that follows the device path node specified by Node.
118 If Node is NULL, then ASSERT().
120 @param Node A pointer to a device path node data structure.
122 @return a pointer to the device path node that follows the device path node specified by Node.
125 EFI_DEVICE_PATH_PROTOCOL
*
131 ASSERT (Node
!= NULL
);
132 return (EFI_DEVICE_PATH_PROTOCOL
*)((UINT8
*)(Node
) + DevicePathNodeLength(Node
));
136 Determines if a device path node is an end node of a device path.
137 This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.
139 Determines if the device path node specified by Node is an end node of a device path.
140 This includes nodes that are the end of a device path instance and nodes that are the
141 end of an entire device path. If Node represents an end node of a device path,
142 then TRUE is returned. Otherwise, FALSE is returned.
144 If Node is NULL, then ASSERT().
146 @param Node A pointer to a device path node data structure.
148 @retval TRUE The device path node specified by Node is an end node of a device path.
149 @retval FALSE The device path node specified by Node is not an end node of a device path.
154 IsDevicePathEndType (
158 ASSERT (Node
!= NULL
);
159 return (BOOLEAN
) (DevicePathType (Node
) == END_DEVICE_PATH_TYPE
);
163 Determines if a device path node is an end node of an entire device path.
165 Determines if a device path node specified by Node is an end node of an entire device path.
166 If Node represents the end of an entire device path, then TRUE is returned. Otherwise, FALSE is returned.
168 If Node is NULL, then ASSERT().
170 @param Node A pointer to a device path node data structure.
172 @retval TRUE The device path node specified by Node is the end of an entire device path.
173 @retval FALSE The device path node specified by Node is not the end of an entire device path.
182 ASSERT (Node
!= NULL
);
183 return (BOOLEAN
) (IsDevicePathEndType (Node
) && DevicePathSubType(Node
) == END_ENTIRE_DEVICE_PATH_SUBTYPE
);
187 Determines if a device path node is an end node of a device path instance.
189 Determines if a device path node specified by Node is an end node of a device path instance.
190 If Node represents the end of a device path instance, then TRUE is returned. Otherwise, FALSE is returned.
192 If Node is NULL, then ASSERT().
194 @param Node A pointer to a device path node data structure.
196 @retval TRUE The device path node specified by Node is the end of a device path instance.
197 @retval FALSE The device path node specified by Node is not the end of a device path instance.
202 IsDevicePathEndInstance (
206 ASSERT (Node
!= NULL
);
207 return (BOOLEAN
) (IsDevicePathEndType (Node
) && DevicePathSubType(Node
) == END_INSTANCE_DEVICE_PATH_SUBTYPE
);
211 Sets the length, in bytes, of a device path node.
213 Sets the length of the device path node specified by Node to the value specified
214 by NodeLength. NodeLength is returned. Node is not required to be aligned on
215 a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
216 be used to set the contents of the Length field.
218 If Node is NULL, then ASSERT().
219 If NodeLength >= 0x10000, then ASSERT().
221 @param Node A pointer to a device path node data structure.
222 @param Length The length, in bytes, of the device path node.
229 SetDevicePathNodeLength (
234 ASSERT (Node
!= NULL
);
235 ASSERT (Length
< 0x10000);
236 return WriteUnaligned16 ((UINT16
*)&((EFI_DEVICE_PATH_PROTOCOL
*)(Node
))->Length
[0], (UINT16
)(Length
));
240 Fills in all the fields of a device path node that is the end of an entire device path.
242 Fills in all the fields of a device path node specified by Node so Node represents
243 the end of an entire device path. The Type field of Node is set to
244 END_DEVICE_PATH_TYPE, the SubType field of Node is set to
245 END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
246 END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary,
247 so it is recommended that a function such as WriteUnaligned16() be used to set
248 the contents of the Length field.
250 If Node is NULL, then ASSERT().
252 @param Node A pointer to a device path node data structure.
257 SetDevicePathEndNode (
261 ASSERT (Node
!= NULL
);
262 CopyMem (Node
, &mUefiDevicePathLibEndDevicePath
, sizeof (mUefiDevicePathLibEndDevicePath
));
266 Returns the size of a device path in bytes.
268 This function returns the size, in bytes, of the device path data structure specified by
269 DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned.
271 @param DevicePath A pointer to a device path data structure.
273 @retval 0 If DevicePath is NULL.
274 @retval Others The size of a device path in bytes.
280 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
283 CONST EFI_DEVICE_PATH_PROTOCOL
*Start
;
285 if (DevicePath
== NULL
) {
290 // Search for the end of the device path structure
293 while (!IsDevicePathEnd (DevicePath
)) {
294 DevicePath
= NextDevicePathNode (DevicePath
);
298 // Compute the size and add back in the size of the end device path structure
300 return ((UINTN
) DevicePath
- (UINTN
) Start
) + DevicePathNodeLength (DevicePath
);
304 Creates a new copy of an existing device path.
306 This function allocates space for a new copy of the device path specified by DevicePath. If
307 DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the
308 contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
309 is returned. Otherwise, NULL is returned.
310 The memory for the new device path is allocated from EFI boot services memory.
311 It is the responsibility of the caller to free the memory allocated.
313 @param DevicePath A pointer to a device path data structure.
315 @retval NULL If DevicePath is NULL.
316 @retval Others A pointer to the duplicated device path.
319 EFI_DEVICE_PATH_PROTOCOL
*
321 DuplicateDevicePath (
322 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
330 Size
= GetDevicePathSize (DevicePath
);
336 // Allocate space for duplicate device path
339 return AllocateCopyPool (Size
, DevicePath
);
343 Creates a new device path by appending a second device path to a first device path.
345 This function creates a new device path by appending a copy of SecondDevicePath to a copy of
346 FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from
347 SecondDevicePath is retained. The newly created device path is returned.
348 If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
349 If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
350 If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
352 If there is not enough memory for the newly allocated buffer, then NULL is returned.
353 The memory for the new device path is allocated from EFI boot services memory. It is the
354 responsibility of the caller to free the memory allocated.
356 @param FirstDevicePath A pointer to a device path data structure.
357 @param SecondDevicePath A pointer to a device path data structure.
359 @retval NULL If there is not enough memory for the newly allocated buffer.
360 @retval Others A pointer to the new device path if success.
361 Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
364 EFI_DEVICE_PATH_PROTOCOL
*
367 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FirstDevicePath
, OPTIONAL
368 IN CONST EFI_DEVICE_PATH_PROTOCOL
*SecondDevicePath OPTIONAL
374 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
375 EFI_DEVICE_PATH_PROTOCOL
*DevicePath2
;
378 // If there's only 1 path, just duplicate it.
380 if (FirstDevicePath
== NULL
) {
381 return DuplicateDevicePath ((SecondDevicePath
!= NULL
) ? SecondDevicePath
: &mUefiDevicePathLibEndDevicePath
);
384 if (SecondDevicePath
== NULL
) {
385 return DuplicateDevicePath (FirstDevicePath
);
389 // Allocate space for the combined device path. It only has one end node of
390 // length EFI_DEVICE_PATH_PROTOCOL.
392 Size1
= GetDevicePathSize (FirstDevicePath
);
393 Size2
= GetDevicePathSize (SecondDevicePath
);
394 Size
= Size1
+ Size2
- END_DEVICE_PATH_LENGTH
;
396 NewDevicePath
= AllocatePool (Size
);
398 if (NewDevicePath
!= NULL
) {
399 NewDevicePath
= CopyMem (NewDevicePath
, FirstDevicePath
, Size1
);
401 // Over write FirstDevicePath EndNode and do the copy
403 DevicePath2
= (EFI_DEVICE_PATH_PROTOCOL
*) ((CHAR8
*) NewDevicePath
+
404 (Size1
- END_DEVICE_PATH_LENGTH
));
405 CopyMem (DevicePath2
, SecondDevicePath
, Size2
);
408 return NewDevicePath
;
412 Creates a new path by appending the device node to the device path.
414 This function creates a new device path by appending a copy of the device node specified by
415 DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
416 The end-of-device-path device node is moved after the end of the appended device node.
417 If DevicePathNode is NULL then a copy of DevicePath is returned.
418 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
420 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
422 If there is not enough memory to allocate space for the new device path, then NULL is returned.
423 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
424 free the memory allocated.
426 @param DevicePath A pointer to a device path data structure.
427 @param DevicePathNode A pointer to a single device path node.
429 @retval NULL If there is not enough memory for the new device path.
430 @retval Others A pointer to the new device path if success.
431 A copy of DevicePathNode followed by an end-of-device-path node
432 if both FirstDevicePath and SecondDevicePath are NULL.
433 A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
436 EFI_DEVICE_PATH_PROTOCOL
*
438 AppendDevicePathNode (
439 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
440 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathNode OPTIONAL
443 EFI_DEVICE_PATH_PROTOCOL
*TempDevicePath
;
444 EFI_DEVICE_PATH_PROTOCOL
*NextNode
;
445 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
448 if (DevicePathNode
== NULL
) {
449 return DuplicateDevicePath ((DevicePath
!= NULL
) ? DevicePath
: &mUefiDevicePathLibEndDevicePath
);
452 // Build a Node that has a terminator on it
454 NodeLength
= DevicePathNodeLength (DevicePathNode
);
456 TempDevicePath
= AllocatePool (NodeLength
+ END_DEVICE_PATH_LENGTH
);
457 if (TempDevicePath
== NULL
) {
460 TempDevicePath
= CopyMem (TempDevicePath
, DevicePathNode
, NodeLength
);
462 // Add and end device path node to convert Node to device path
464 NextNode
= NextDevicePathNode (TempDevicePath
);
465 SetDevicePathEndNode (NextNode
);
467 // Append device paths
469 NewDevicePath
= AppendDevicePath (DevicePath
, TempDevicePath
);
471 FreePool (TempDevicePath
);
473 return NewDevicePath
;
477 Creates a new device path by appending the specified device path instance to the specified device
480 This function creates a new device path by appending a copy of the device path instance specified
481 by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
482 The end-of-device-path device node is moved after the end of the appended device path instance
483 and a new end-of-device-path-instance node is inserted between.
484 If DevicePath is NULL, then a copy if DevicePathInstance is returned.
485 If DevicePathInstance is NULL, then NULL is returned.
486 If there is not enough memory to allocate space for the new device path, then NULL is returned.
487 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
488 free the memory allocated.
490 @param DevicePath A pointer to a device path data structure.
491 @param DevicePathInstance A pointer to a device path instance.
493 @return A pointer to the new device path.
496 EFI_DEVICE_PATH_PROTOCOL
*
498 AppendDevicePathInstance (
499 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
500 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathInstance OPTIONAL
503 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
504 EFI_DEVICE_PATH_PROTOCOL
*TempDevicePath
;
508 if (DevicePath
== NULL
) {
509 return DuplicateDevicePath (DevicePathInstance
);
512 if (DevicePathInstance
== NULL
) {
516 SrcSize
= GetDevicePathSize (DevicePath
);
517 InstanceSize
= GetDevicePathSize (DevicePathInstance
);
519 NewDevicePath
= AllocatePool (SrcSize
+ InstanceSize
);
520 if (NewDevicePath
!= NULL
) {
522 TempDevicePath
= CopyMem (NewDevicePath
, DevicePath
, SrcSize
);;
524 while (!IsDevicePathEnd (TempDevicePath
)) {
525 TempDevicePath
= NextDevicePathNode (TempDevicePath
);
528 TempDevicePath
->SubType
= END_INSTANCE_DEVICE_PATH_SUBTYPE
;
529 TempDevicePath
= NextDevicePathNode (TempDevicePath
);
530 CopyMem (TempDevicePath
, DevicePathInstance
, InstanceSize
);
533 return NewDevicePath
;
537 Creates a copy of the current device path instance and returns a pointer to the next device path
540 This function creates a copy of the current device path instance. It also updates DevicePath to
541 point to the next device path instance in the device path (or NULL if no more) and updates Size
542 to hold the size of the device path instance copy.
543 If DevicePath is NULL, then NULL is returned.
544 If there is not enough memory to allocate space for the new device path, then NULL is returned.
545 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
546 free the memory allocated.
547 If Size is NULL, then ASSERT().
549 @param DevicePath On input, this holds the pointer to the current device path
550 instance. On output, this holds the pointer to the next device
551 path instance or NULL if there are no more device path
552 instances in the device path pointer to a device path data
554 @param Size On output, this holds the size of the device path instance, in
555 bytes or zero, if DevicePath is NULL.
557 @return A pointer to the current device path instance.
560 EFI_DEVICE_PATH_PROTOCOL
*
562 GetNextDevicePathInstance (
563 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
,
567 EFI_DEVICE_PATH_PROTOCOL
*DevPath
;
568 EFI_DEVICE_PATH_PROTOCOL
*ReturnValue
;
571 ASSERT (Size
!= NULL
);
573 if (DevicePath
== NULL
|| *DevicePath
== NULL
) {
579 // Find the end of the device path instance
581 DevPath
= *DevicePath
;
582 while (!IsDevicePathEndType (DevPath
)) {
583 DevPath
= NextDevicePathNode (DevPath
);
587 // Compute the size of the device path instance
589 *Size
= ((UINTN
) DevPath
- (UINTN
) (*DevicePath
)) + sizeof (EFI_DEVICE_PATH_PROTOCOL
);
592 // Make a copy and return the device path instance
594 Temp
= DevPath
->SubType
;
595 DevPath
->SubType
= END_ENTIRE_DEVICE_PATH_SUBTYPE
;
596 ReturnValue
= DuplicateDevicePath (*DevicePath
);
597 DevPath
->SubType
= Temp
;
600 // If DevPath is the end of an entire device path, then another instance
601 // does not follow, so *DevicePath is set to NULL.
603 if (DevicePathSubType (DevPath
) == END_ENTIRE_DEVICE_PATH_SUBTYPE
) {
606 *DevicePath
= NextDevicePathNode (DevPath
);
613 Creates a device node.
615 This function creates a new device node in a newly allocated buffer of size NodeLength and
616 initializes the device path node header with NodeType and NodeSubType. The new device path node
618 If NodeLength is smaller than a device path header, then NULL is returned.
619 If there is not enough memory to allocate space for the new device path, then NULL is returned.
620 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
621 free the memory allocated.
623 @param NodeType The device node type for the new device node.
624 @param NodeSubType The device node sub-type for the new device node.
625 @param NodeLength The length of the new device node.
627 @return The new device path.
630 EFI_DEVICE_PATH_PROTOCOL
*
634 IN UINT8 NodeSubType
,
638 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
640 if (NodeLength
< sizeof (EFI_DEVICE_PATH_PROTOCOL
)) {
642 // NodeLength is less than the size of the header.
647 DevicePath
= AllocateZeroPool (NodeLength
);
648 if (DevicePath
!= NULL
) {
649 DevicePath
->Type
= NodeType
;
650 DevicePath
->SubType
= NodeSubType
;
651 SetDevicePathNodeLength (DevicePath
, NodeLength
);
658 Determines if a device path is single or multi-instance.
660 This function returns TRUE if the device path specified by DevicePath is multi-instance.
661 Otherwise, FALSE is returned. If DevicePath is NULL, then FALSE is returned.
663 @param DevicePath A pointer to a device path data structure.
665 @retval TRUE DevicePath is multi-instance.
666 @retval FALSE DevicePath is not multi-instance or DevicePath is NULL.
671 IsDevicePathMultiInstance (
672 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
675 CONST EFI_DEVICE_PATH_PROTOCOL
*Node
;
677 if (DevicePath
== NULL
) {
682 while (!IsDevicePathEnd (Node
)) {
683 if (IsDevicePathEndInstance (Node
)) {
687 Node
= NextDevicePathNode (Node
);
695 Retrieves the device path protocol from a handle.
697 This function returns the device path protocol from the handle specified by Handle. If Handle is
698 NULL or Handle does not contain a device path protocol, then NULL is returned.
700 @param Handle The handle from which to retrieve the device path protocol.
702 @return The device path protocol from the handle specified by Handle.
705 EFI_DEVICE_PATH_PROTOCOL
*
707 DevicePathFromHandle (
711 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
714 Status
= gBS
->HandleProtocol (
716 &gEfiDevicePathProtocolGuid
,
719 if (EFI_ERROR (Status
)) {
726 Allocates a device path for a file and appends it to an existing device path.
728 If Device is a valid device handle that contains a device path protocol, then a device path for
729 the file specified by FileName is allocated and appended to the device path associated with the
730 handle Device. The allocated device path is returned. If Device is NULL or Device is a handle
731 that does not support the device path protocol, then a device path containing a single device
732 path node for the file specified by FileName is allocated and returned.
733 The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
734 of the caller to free the memory allocated.
736 If FileName is NULL, then ASSERT().
737 If FileName is not aligned on a 16-bit boundary, then ASSERT().
739 @param Device A pointer to a device handle. This parameter is optional and
741 @param FileName A pointer to a Null-terminated Unicode string.
743 @return The allocated device path.
746 EFI_DEVICE_PATH_PROTOCOL
*
749 IN EFI_HANDLE Device
, OPTIONAL
750 IN CONST CHAR16
*FileName
754 FILEPATH_DEVICE_PATH
*FilePath
;
755 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
756 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePath
;
760 Size
= (UINT16
) StrSize (FileName
);
762 FileDevicePath
= AllocatePool (Size
+ SIZE_OF_FILEPATH_DEVICE_PATH
+ END_DEVICE_PATH_LENGTH
);
763 if (FileDevicePath
!= NULL
) {
764 FilePath
= (FILEPATH_DEVICE_PATH
*) FileDevicePath
;
765 FilePath
->Header
.Type
= MEDIA_DEVICE_PATH
;
766 FilePath
->Header
.SubType
= MEDIA_FILEPATH_DP
;
767 CopyMem (&FilePath
->PathName
, FileName
, Size
);
768 SetDevicePathNodeLength (&FilePath
->Header
, Size
+ SIZE_OF_FILEPATH_DEVICE_PATH
);
769 SetDevicePathEndNode (NextDevicePathNode (&FilePath
->Header
));
771 if (Device
!= NULL
) {
772 DevicePath
= DevicePathFromHandle (Device
);
775 DevicePath
= AppendDevicePath (DevicePath
, FileDevicePath
);
776 FreePool (FileDevicePath
);