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 - 2010, Intel Corporation. All rights reserved.<BR>
12 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
119 If Node is NULL, then ASSERT().
121 @param Node A pointer to a device path node data structure.
123 @return a pointer to the device path node that follows the device path node
127 EFI_DEVICE_PATH_PROTOCOL
*
133 ASSERT (Node
!= NULL
);
134 return (EFI_DEVICE_PATH_PROTOCOL
*)((UINT8
*)(Node
) + DevicePathNodeLength(Node
));
138 Determines if a device path node is an end node of a device path.
139 This includes nodes that are the end of a device path instance and nodes that
140 are the end of an entire device path.
142 Determines if the device path node specified by Node is an end node of a device path.
143 This includes nodes that are the end of a device path instance and nodes that are the
144 end of an entire device path. If Node represents an end node of a device path,
145 then TRUE is returned. Otherwise, FALSE is returned.
147 If Node is NULL, then ASSERT().
149 @param Node A pointer to a device path node data structure.
151 @retval TRUE The device path node specified by Node is an end node of a
153 @retval FALSE The device path node specified by Node is not an end node of
159 IsDevicePathEndType (
163 ASSERT (Node
!= NULL
);
164 return (BOOLEAN
) (DevicePathType (Node
) == END_DEVICE_PATH_TYPE
);
168 Determines if a device path node is an end node of an entire device path.
170 Determines if a device path node specified by Node is an end node of an entire
171 device path. If Node represents the end of an entire device path, then TRUE is
172 returned. Otherwise, FALSE is returned.
174 If Node is NULL, then ASSERT().
176 @param Node A pointer to a device path node data structure.
178 @retval TRUE The device path node specified by Node is the end of an entire
180 @retval FALSE The device path node specified by Node is not the end of an
190 ASSERT (Node
!= NULL
);
191 return (BOOLEAN
) (IsDevicePathEndType (Node
) && DevicePathSubType(Node
) == END_ENTIRE_DEVICE_PATH_SUBTYPE
);
195 Determines if a device path node is an end node of a device path instance.
197 Determines if a device path node specified by Node is an end node of a device
198 path instance. If Node represents the end of a device path instance, then TRUE
199 is returned. Otherwise, FALSE is returned.
201 If Node is NULL, then ASSERT().
203 @param Node A pointer to a device path node data structure.
205 @retval TRUE The device path node specified by Node is the end of a device
207 @retval FALSE The device path node specified by Node is not the end of a
208 device path instance.
213 IsDevicePathEndInstance (
217 ASSERT (Node
!= NULL
);
218 return (BOOLEAN
) (IsDevicePathEndType (Node
) && DevicePathSubType(Node
) == END_INSTANCE_DEVICE_PATH_SUBTYPE
);
222 Sets the length, in bytes, of a device path node.
224 Sets the length of the device path node specified by Node to the value specified
225 by NodeLength. NodeLength is returned. Node is not required to be aligned on
226 a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
227 be used to set the contents of the Length field.
229 If Node is NULL, then ASSERT().
230 If NodeLength >= 0x10000, then ASSERT().
232 @param Node A pointer to a device path node data structure.
233 @param Length The length, in bytes, of the device path node.
240 SetDevicePathNodeLength (
245 ASSERT (Node
!= NULL
);
246 ASSERT (Length
< 0x10000);
247 return WriteUnaligned16 ((UINT16
*)&((EFI_DEVICE_PATH_PROTOCOL
*)(Node
))->Length
[0], (UINT16
)(Length
));
251 Fills in all the fields of a device path node that is the end of an entire device path.
253 Fills in all the fields of a device path node specified by Node so Node represents
254 the end of an entire device path. The Type field of Node is set to
255 END_DEVICE_PATH_TYPE, the SubType field of Node is set to
256 END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
257 END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary,
258 so it is recommended that a function such as WriteUnaligned16() be used to set
259 the contents of the Length field.
261 If Node is NULL, then ASSERT().
263 @param Node A pointer to a device path node data structure.
268 SetDevicePathEndNode (
272 ASSERT (Node
!= NULL
);
273 CopyMem (Node
, &mUefiDevicePathLibEndDevicePath
, sizeof (mUefiDevicePathLibEndDevicePath
));
277 Returns the size of a device path in bytes.
279 This function returns the size, in bytes, of the device path data structure
280 specified by DevicePath including the end of device path node. If DevicePath
281 is NULL, then 0 is returned.
283 @param DevicePath A pointer to a device path data structure.
285 @retval 0 If DevicePath is NULL.
286 @retval Others The size of a device path in bytes.
292 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
295 CONST EFI_DEVICE_PATH_PROTOCOL
*Start
;
297 if (DevicePath
== NULL
) {
302 // Search for the end of the device path structure
305 while (!IsDevicePathEnd (DevicePath
)) {
306 DevicePath
= NextDevicePathNode (DevicePath
);
310 // Compute the size and add back in the size of the end device path structure
312 return ((UINTN
) DevicePath
- (UINTN
) Start
) + DevicePathNodeLength (DevicePath
);
316 Creates a new copy of an existing device path.
318 This function allocates space for a new copy of the device path specified by DevicePath.
319 If DevicePath is NULL, then NULL is returned. If the memory is successfully
320 allocated, then the contents of DevicePath are copied to the newly allocated
321 buffer, and a pointer to that buffer is returned. Otherwise, NULL is returned.
322 The memory for the new device path is allocated from EFI boot services memory.
323 It is the responsibility of the caller to free the memory allocated.
325 @param DevicePath A pointer to a device path data structure.
327 @retval NULL If DevicePath is NULL.
328 @retval Others A pointer to the duplicated device path.
331 EFI_DEVICE_PATH_PROTOCOL
*
333 DuplicateDevicePath (
334 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
342 Size
= GetDevicePathSize (DevicePath
);
348 // Allocate space for duplicate device path
351 return AllocateCopyPool (Size
, DevicePath
);
355 Creates a new device path by appending a second device path to a first device path.
357 This function creates a new device path by appending a copy of SecondDevicePath
358 to a copy of FirstDevicePath in a newly allocated buffer. Only the end-of-device-path
359 device node from SecondDevicePath is retained. The newly created device path is
360 returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of
361 SecondDevicePath is returned. If SecondDevicePath is NULL, then it is ignored,
362 and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and
363 SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
365 If there is not enough memory for the newly allocated buffer, then NULL is returned.
366 The memory for the new device path is allocated from EFI boot services memory.
367 It is the responsibility of the caller to free the memory allocated.
369 @param FirstDevicePath A pointer to a device path data structure.
370 @param SecondDevicePath A pointer to a device path data structure.
372 @retval NULL If there is not enough memory for the newly allocated buffer.
373 @retval Others A pointer to the new device path if success.
374 Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
377 EFI_DEVICE_PATH_PROTOCOL
*
380 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FirstDevicePath
, OPTIONAL
381 IN CONST EFI_DEVICE_PATH_PROTOCOL
*SecondDevicePath OPTIONAL
387 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
388 EFI_DEVICE_PATH_PROTOCOL
*DevicePath2
;
391 // If there's only 1 path, just duplicate it.
393 if (FirstDevicePath
== NULL
) {
394 return DuplicateDevicePath ((SecondDevicePath
!= NULL
) ? SecondDevicePath
: &mUefiDevicePathLibEndDevicePath
);
397 if (SecondDevicePath
== NULL
) {
398 return DuplicateDevicePath (FirstDevicePath
);
402 // Allocate space for the combined device path. It only has one end node of
403 // length EFI_DEVICE_PATH_PROTOCOL.
405 Size1
= GetDevicePathSize (FirstDevicePath
);
406 Size2
= GetDevicePathSize (SecondDevicePath
);
407 Size
= Size1
+ Size2
- END_DEVICE_PATH_LENGTH
;
409 NewDevicePath
= AllocatePool (Size
);
411 if (NewDevicePath
!= NULL
) {
412 NewDevicePath
= CopyMem (NewDevicePath
, FirstDevicePath
, Size1
);
414 // Over write FirstDevicePath EndNode and do the copy
416 DevicePath2
= (EFI_DEVICE_PATH_PROTOCOL
*) ((CHAR8
*) NewDevicePath
+
417 (Size1
- END_DEVICE_PATH_LENGTH
));
418 CopyMem (DevicePath2
, SecondDevicePath
, Size2
);
421 return NewDevicePath
;
425 Creates a new path by appending the device node to the device path.
427 This function creates a new device path by appending a copy of the device node
428 specified by DevicePathNode to a copy of the device path specified by DevicePath
429 in an allocated buffer. The end-of-device-path device node is moved after the
430 end of the appended device node.
431 If DevicePathNode is NULL then a copy of DevicePath is returned.
432 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
433 path device node is returned.
434 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
435 device node is returned.
436 If there is not enough memory to allocate space for the new device path, then
438 The memory is allocated from EFI boot services memory. It is the responsibility
439 of the caller to free the memory allocated.
441 @param DevicePath A pointer to a device path data structure.
442 @param DevicePathNode A pointer to a single device path node.
444 @retval NULL If there is not enough memory for the new device path.
445 @retval Others A pointer to the new device path if success.
446 A copy of DevicePathNode followed by an end-of-device-path node
447 if both FirstDevicePath and SecondDevicePath are NULL.
448 A copy of an end-of-device-path node if both FirstDevicePath
449 and SecondDevicePath are NULL.
452 EFI_DEVICE_PATH_PROTOCOL
*
454 AppendDevicePathNode (
455 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
456 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathNode OPTIONAL
459 EFI_DEVICE_PATH_PROTOCOL
*TempDevicePath
;
460 EFI_DEVICE_PATH_PROTOCOL
*NextNode
;
461 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
464 if (DevicePathNode
== NULL
) {
465 return DuplicateDevicePath ((DevicePath
!= NULL
) ? DevicePath
: &mUefiDevicePathLibEndDevicePath
);
468 // Build a Node that has a terminator on it
470 NodeLength
= DevicePathNodeLength (DevicePathNode
);
472 TempDevicePath
= AllocatePool (NodeLength
+ END_DEVICE_PATH_LENGTH
);
473 if (TempDevicePath
== NULL
) {
476 TempDevicePath
= CopyMem (TempDevicePath
, DevicePathNode
, NodeLength
);
478 // Add and end device path node to convert Node to device path
480 NextNode
= NextDevicePathNode (TempDevicePath
);
481 SetDevicePathEndNode (NextNode
);
483 // Append device paths
485 NewDevicePath
= AppendDevicePath (DevicePath
, TempDevicePath
);
487 FreePool (TempDevicePath
);
489 return NewDevicePath
;
493 Creates a new device path by appending the specified device path instance to the specified device
496 This function creates a new device path by appending a copy of the device path
497 instance specified by DevicePathInstance to a copy of the device path specified
498 by DevicePath in a allocated buffer.
499 The end-of-device-path device node is moved after the end of the appended device
500 path instance and a new end-of-device-path-instance node is inserted between.
501 If DevicePath is NULL, then a copy if DevicePathInstance is returned.
502 If DevicePathInstance is NULL, then NULL is returned.
503 If there is not enough memory to allocate space for the new device path, then
505 The memory is allocated from EFI boot services memory. It is the responsibility
506 of the caller to free the memory allocated.
508 @param DevicePath A pointer to a device path data structure.
509 @param DevicePathInstance A pointer to a device path instance.
511 @return A pointer to the new device path.
514 EFI_DEVICE_PATH_PROTOCOL
*
516 AppendDevicePathInstance (
517 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
518 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathInstance OPTIONAL
521 EFI_DEVICE_PATH_PROTOCOL
*NewDevicePath
;
522 EFI_DEVICE_PATH_PROTOCOL
*TempDevicePath
;
526 if (DevicePath
== NULL
) {
527 return DuplicateDevicePath (DevicePathInstance
);
530 if (DevicePathInstance
== NULL
) {
534 SrcSize
= GetDevicePathSize (DevicePath
);
535 InstanceSize
= GetDevicePathSize (DevicePathInstance
);
537 NewDevicePath
= AllocatePool (SrcSize
+ InstanceSize
);
538 if (NewDevicePath
!= NULL
) {
540 TempDevicePath
= CopyMem (NewDevicePath
, DevicePath
, SrcSize
);;
542 while (!IsDevicePathEnd (TempDevicePath
)) {
543 TempDevicePath
= NextDevicePathNode (TempDevicePath
);
546 TempDevicePath
->SubType
= END_INSTANCE_DEVICE_PATH_SUBTYPE
;
547 TempDevicePath
= NextDevicePathNode (TempDevicePath
);
548 CopyMem (TempDevicePath
, DevicePathInstance
, InstanceSize
);
551 return NewDevicePath
;
555 Creates a copy of the current device path instance and returns a pointer to the next device path
558 This function creates a copy of the current device path instance. It also updates
559 DevicePath to point to the next device path instance in the device path (or NULL
560 if no more) and updates Size to hold the size of the device path instance copy.
561 If DevicePath is NULL, then NULL is returned.
562 If there is not enough memory to allocate space for the new device path, then
564 The memory is allocated from EFI boot services memory. It is the responsibility
565 of the caller to free the memory allocated.
566 If Size is NULL, then ASSERT().
568 @param DevicePath On input, this holds the pointer to the current
569 device path instance. On output, this holds
570 the pointer to the next device path instance
571 or NULL if there are no more device path
572 instances in the device path pointer to a
573 device path data structure.
574 @param Size On output, this holds the size of the device
575 path instance, in bytes or zero, if DevicePath
578 @return A pointer to the current device path instance.
581 EFI_DEVICE_PATH_PROTOCOL
*
583 GetNextDevicePathInstance (
584 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
,
588 EFI_DEVICE_PATH_PROTOCOL
*DevPath
;
589 EFI_DEVICE_PATH_PROTOCOL
*ReturnValue
;
592 ASSERT (Size
!= NULL
);
594 if (DevicePath
== NULL
|| *DevicePath
== NULL
) {
600 // Find the end of the device path instance
602 DevPath
= *DevicePath
;
603 while (!IsDevicePathEndType (DevPath
)) {
604 DevPath
= NextDevicePathNode (DevPath
);
608 // Compute the size of the device path instance
610 *Size
= ((UINTN
) DevPath
- (UINTN
) (*DevicePath
)) + sizeof (EFI_DEVICE_PATH_PROTOCOL
);
613 // Make a copy and return the device path instance
615 Temp
= DevPath
->SubType
;
616 DevPath
->SubType
= END_ENTIRE_DEVICE_PATH_SUBTYPE
;
617 ReturnValue
= DuplicateDevicePath (*DevicePath
);
618 DevPath
->SubType
= Temp
;
621 // If DevPath is the end of an entire device path, then another instance
622 // does not follow, so *DevicePath is set to NULL.
624 if (DevicePathSubType (DevPath
) == END_ENTIRE_DEVICE_PATH_SUBTYPE
) {
627 *DevicePath
= NextDevicePathNode (DevPath
);
634 Creates a device node.
636 This function creates a new device node in a newly allocated buffer of size
637 NodeLength and initializes the device path node header with NodeType and NodeSubType.
638 The new device path node is returned.
639 If NodeLength is smaller than a device path header, then NULL is returned.
640 If there is not enough memory to allocate space for the new device path, then
642 The memory is allocated from EFI boot services memory. It is the responsibility
643 of the caller to free the memory allocated.
645 @param NodeType The device node type for the new device node.
646 @param NodeSubType The device node sub-type for the new device node.
647 @param NodeLength The length of the new device node.
649 @return The new device path.
652 EFI_DEVICE_PATH_PROTOCOL
*
656 IN UINT8 NodeSubType
,
660 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
662 if (NodeLength
< sizeof (EFI_DEVICE_PATH_PROTOCOL
)) {
664 // NodeLength is less than the size of the header.
669 DevicePath
= AllocateZeroPool (NodeLength
);
670 if (DevicePath
!= NULL
) {
671 DevicePath
->Type
= NodeType
;
672 DevicePath
->SubType
= NodeSubType
;
673 SetDevicePathNodeLength (DevicePath
, NodeLength
);
680 Determines if a device path is single or multi-instance.
682 This function returns TRUE if the device path specified by DevicePath is
684 Otherwise, FALSE is returned. If DevicePath is NULL, then FALSE is returned.
686 @param DevicePath A pointer to a device path data structure.
688 @retval TRUE DevicePath is multi-instance.
689 @retval FALSE DevicePath is not multi-instance or DevicePath
695 IsDevicePathMultiInstance (
696 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
699 CONST EFI_DEVICE_PATH_PROTOCOL
*Node
;
701 if (DevicePath
== NULL
) {
706 while (!IsDevicePathEnd (Node
)) {
707 if (IsDevicePathEndInstance (Node
)) {
711 Node
= NextDevicePathNode (Node
);
719 Retrieves the device path protocol from a handle.
721 This function returns the device path protocol from the handle specified by Handle.
722 If Handle is NULL or Handle does not contain a device path protocol, then NULL
725 @param Handle The handle from which to retrieve the device
728 @return The device path protocol from the handle specified by Handle.
731 EFI_DEVICE_PATH_PROTOCOL
*
733 DevicePathFromHandle (
737 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
740 Status
= gBS
->HandleProtocol (
742 &gEfiDevicePathProtocolGuid
,
745 if (EFI_ERROR (Status
)) {
752 Allocates a device path for a file and appends it to an existing device path.
754 If Device is a valid device handle that contains a device path protocol, then a device path for
755 the file specified by FileName is allocated and appended to the device path associated with the
756 handle Device. The allocated device path is returned. If Device is NULL or Device is a handle
757 that does not support the device path protocol, then a device path containing a single device
758 path node for the file specified by FileName is allocated and returned.
759 The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
760 of the caller to free the memory allocated.
762 If FileName is NULL, then ASSERT().
763 If FileName is not aligned on a 16-bit boundary, then ASSERT().
765 @param Device A pointer to a device handle. This parameter
766 is optional and may be NULL.
767 @param FileName A pointer to a Null-terminated Unicode string.
769 @return The allocated device path.
772 EFI_DEVICE_PATH_PROTOCOL
*
775 IN EFI_HANDLE Device
, OPTIONAL
776 IN CONST CHAR16
*FileName
780 FILEPATH_DEVICE_PATH
*FilePath
;
781 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
782 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePath
;
786 Size
= (UINT16
) StrSize (FileName
);
788 FileDevicePath
= AllocatePool (Size
+ SIZE_OF_FILEPATH_DEVICE_PATH
+ END_DEVICE_PATH_LENGTH
);
789 if (FileDevicePath
!= NULL
) {
790 FilePath
= (FILEPATH_DEVICE_PATH
*) FileDevicePath
;
791 FilePath
->Header
.Type
= MEDIA_DEVICE_PATH
;
792 FilePath
->Header
.SubType
= MEDIA_FILEPATH_DP
;
793 CopyMem (&FilePath
->PathName
, FileName
, Size
);
794 SetDevicePathNodeLength (&FilePath
->Header
, Size
+ SIZE_OF_FILEPATH_DEVICE_PATH
);
795 SetDevicePathEndNode (NextDevicePathNode (&FilePath
->Header
));
797 if (Device
!= NULL
) {
798 DevicePath
= DevicePathFromHandle (Device
);
801 DevicePath
= AppendDevicePath (DevicePath
, FileDevicePath
);
802 FreePool (FileDevicePath
);