44   Device Path services. The thing to remember is device paths are built out of
45   nodes. The device path is terminated by an end node that is length
49   The only place where multi-instance device paths are supported is in
50   environment varibles. Multi-instance device paths should never be placed
61 // Template for an end-of-device path node.
73   Determine whether a given device path is valid.
75   @param  DevicePath  A pointer to a device path data structure.
76   @param  MaxSize     The maximum size of the device path data structure.
148   // Only return TRUE when the End Device Path node is valid.  in IsDevicePathValid()
154   Returns the Type field of a device path node.
156   Returns the Type field of the device path node specified by Node.
160   @param  Node      A pointer to a device path node data structure.
162   @return The Type field of the device path node specified by Node.
176   Returns the SubType field of a device path node.
178   Returns the SubType field of the device path node specified by Node.
182   @param  Node      A pointer to a device path node data structure.
184   @return The SubType field of the device path node specified by Node.
198   Returns the 16-bit Length field of a device path node.
200   Returns the 16-bit Length field of the device path node specified by Node.
207   @param  Node      A pointer to a device path node data structure.
209   @return The 16-bit Length field of the device path node specified by Node.
225   Returns a pointer to the next node in a device path.
227   Returns a pointer to the device path node that follows the device path node
232   @param  Node      A pointer to a device path node data structure.
234   @return a pointer to the device path node that follows the device path node
249   Determines if a device path node is an end node of a device path.
250   This includes nodes that are the end of a device path instance and nodes that
251   are the end of an entire device path.
253   Determines if the device path node specified by Node is an end node of a device path.
254   This includes nodes that are the end of a device path instance and nodes that are the
255   end of an entire device path.  If Node represents an end node of a device path,
260   @param  Node      A pointer to a device path node data structure.
262   @retval TRUE      The device path node specified by Node is an end node of a
263                     device path.
264   @retval FALSE     The device path node specified by Node is not an end node of
265                     a device path.
279   Determines if a device path node is an end node of an entire device path.
281   Determines if a device path node specified by Node is an end node of an entire
282   device path. If Node represents the end of an entire device path, then TRUE is
287   @param  Node      A pointer to a device path node data structure.
289   @retval TRUE      The device path node specified by Node is the end of an entire
290                     device path.
291   @retval FALSE     The device path node specified by Node is not the end of an
292                     entire device path.
307   Determines if a device path node is an end node of a device path instance.
309   Determines if a device path node specified by Node is an end node of a device
310   path instance. If Node represents the end of a device path instance, then TRUE
315   @param  Node      A pointer to a device path node data structure.
317   @retval TRUE      The device path node specified by Node is the end of a device
319   @retval FALSE     The device path node specified by Node is not the end of a
320                     device path instance.
335   Sets the length, in bytes, of a device path node.
337   Sets the length of the device path node specified by Node to the value specified
346   @param  Node      A pointer to a device path node data structure.
347   @param  Length    The length, in bytes, of the device path node.
367   Fills in all the fields of a device path node that is the end of an entire device path.
369   Fills in all the fields of a device path node specified by Node so Node represents
370   the end of an entire device path.  The Type field of Node is set to
379   @param  Node      A pointer to a device path node data structure.
393   Returns the size of a device path in bytes.
395   This function returns the size, in bytes, of the device path data structure
396   specified by DevicePath including the end of device path node.
399   @param  DevicePath  A pointer to a device path data structure.
402   @retval Others      The size of a device path in bytes.
422   // Search for the end of the device path structure  in GetDevicePathSize()
430   // Compute the size and add back in the size of the end device path structure  in GetDevicePathSize()
436   Creates a new copy of an existing device path.
438   This function allocates space for a new copy of the device path specified by DevicePath.
442   The memory for the new device path is allocated from EFI boot services memory.
445   @param  DevicePath    A pointer to a device path data structure.
448   @retval Others        A pointer to the duplicated device path.
468   // Allocate space for duplicate device path  in DuplicateDevicePath()
475   Creates a new device path by appending a second device path to a first device path.
477   This function creates a new device path by appending a copy of SecondDevicePath
478   to a copy of FirstDevicePath in a newly allocated buffer.  Only the end-of-device-path
479   device node from SecondDevicePath is retained. The newly created device path is
483   SecondDevicePath are NULL, then a copy of an end-of-device-path is returned.
486   The memory for the new device path is allocated from EFI boot services memory.
489   @param  FirstDevicePath            A pointer to a device path data structure.
490   @param  SecondDevicePath           A pointer to a device path data structure.
494   @retval Others    A pointer to the new device path if success.
495 …             Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
527   // Allocate space for the combined device path. It only has one end node of  in AppendDevicePath()
550   Creates a new path by appending the device node to the device path.
552   This function creates a new device path by appending a copy of the device node
553   specified by DevicePathNode to a copy of the device path specified by DevicePath
554   in an allocated buffer. The end-of-device-path device node is moved after the
555   end of the appended device node.
557   If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device
558   path device node is returned.
559   If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path
560   device node is returned.
561   If there is not enough memory to allocate space for the new device path, then
566   @param  DevicePath                 A pointer to a device path data structure.
567   @param  DevicePathNode             A pointer to a single device path node.
569   @retval NULL      If there is not enough memory for the new device path.
570   @retval Others    A pointer to the new device path if success.
571                     A copy of DevicePathNode followed by an end-of-device-path node
573                     A copy of an end-of-device-path node if both FirstDevicePath
605   // Add and end device path node to convert Node to device path  in AppendDevicePathNode()
610   // Append device paths  in AppendDevicePathNode()
621   Creates a new device path by appending the specified device path instance to the specified device
624   This function creates a new device path by appending a copy of the device path
625   instance specified by DevicePathInstance to a copy of the device path specified
627   The end-of-device-path device node is moved after the end of the appended device
628   path instance and a new end-of-device-path-instance node is inserted between.
632   If there is not enough memory to allocate space for the new device path, then
637   @param  DevicePath                 A pointer to a device path data structure.
638   @param  DevicePathInstance         A pointer to a device path instance.
640   @return A pointer to the new device path.
687   Creates a copy of the current device path instance and returns a pointer to the next device path
690   This function creates a copy of the current device path instance. It also updates
691   DevicePath to point to the next device path instance in the device path (or NULL
692   if no more) and updates Size to hold the size of the device path instance copy.
694   If DevicePath points to a invalid device path, then NULL is returned.
695   If there is not enough memory to allocate space for the new device path, then
702                                      device path instance. On output, this holds
703                                      the pointer to the next device path instance
704                                      or NULL if there are no more device path
705                                      instances in the device path pointer to a
706                                      device path data structure.
707   @param  Size                       On output, this holds the size of the device
711   @return A pointer to the current device path instance.
737   // Find the end of the device path instance  in UefiDevicePathLibGetNextDevicePathInstance()
745   // Compute the size of the device path instance  in UefiDevicePathLibGetNextDevicePathInstance()
750   // Make a copy and return the device path instance  in UefiDevicePathLibGetNextDevicePathInstance()
758   // If DevPath is the end of an entire device path, then another instance  in UefiDevicePathLibGetNextDevicePathInstance()
772   Creates a device node.
774   This function creates a new device node in a newly allocated buffer of size
775   NodeLength and initializes the device path node header with NodeType and NodeSubType.
776   The new device path node is returned.
777   If NodeLength is smaller than a device path header, then NULL is returned.
778   If there is not enough memory to allocate space for the new device path, then
783   @param  NodeType                   The device node type for the new device node.
784   @param  NodeSubType                The device node sub-type for the new device node.
785   @param  NodeLength                 The length of the new device node.
787   @return The new device path.
819   Determines if a device path is single or multi-instance.
821   This function returns TRUE if the device path specified by DevicePath is
826   @param  DevicePath                 A pointer to a device path data structure.
862   Allocates a device path for a file and appends it to an existing device path.
864   If Device is a valid device handle that contains a device path protocol, then a device path for
865   the file specified by FileName  is allocated and appended to the device path associated with the
866   handle Device.  The allocated device path is returned.  If Device is NULL or Device is a handle
867   that does not support the device path protocol, then a device path containing a single device
869 …The memory for the new device path is allocated from EFI boot services memory. It is the responsib…
875   @param  Device                     A pointer to a device handle.  This parameter
879   @return The allocated device path.
885   IN EFI_HANDLE    Device      OPTIONAL,  in FileDevicePath()
906     if (Device != NULL) {  in FileDevicePath()
907       DevicePath = DevicePathFromHandle (Device);  in FileDevicePath()