2 Provides library functions to construct and parse UEFI Device Paths.
4 This library provides defines, macros, and functions to help create and parse
5 EFI_DEVICE_PATH_PROTOCOL structures. The macros that help create and parse device
6 path nodes make use of the ReadUnaligned16() and WriteUnaligned16() functions from
7 the Base Library, so this library class has an implied dependency on the Base Library.
9 Copyright (c) 2006 - 2008, Intel Corporation<BR>
10 All rights reserved. This program and the accompanying materials
11 are licensed and made available under the terms and conditions of the BSD License
12 which accompanies this distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #ifndef __DEVICE_PATH_LIB_H__
21 #define __DEVICE_PATH_LIB_H__
23 #define END_DEVICE_PATH_LENGTH (sizeof (EFI_DEVICE_PATH_PROTOCOL))
26 Returns the Type field of a device path node.
28 Returns the Type field of the device path node specified by Node.
30 If Node is NULL, then ASSERT().
32 @param Node A pointer to a device path node data structure.
34 @return The Type field of the device path node specified by Node.
43 Returns the SubType field of a device path node.
45 Returns the SubType field of the device path node specified by Node.
47 If Node is NULL, then ASSERT().
49 @param Node A pointer to a device path node data structure.
51 @return The SubType field of the device path node specified by Node.
60 Returns the 16-bit Length field of a device path node.
62 Returns the 16-bit Length field of the device path node specified by Node.
63 Node is not required to be aligned on a 16-bit boundary, so it is recommended
64 that a function such as ReadUnaligned16() be used to extract the contents of
67 If Node is NULL, then ASSERT().
69 @param Node A pointer to a device path node data structure.
71 @return The 16-bit Length field of the device path node specified by Node.
75 DevicePathNodeLength (
80 Returns a pointer to the next node in a device path.
82 Returns a pointer to the device path node that follows the device path node specified by Node.
84 If Node is NULL, then ASSERT().
86 @param Node A pointer to a device path node data structure.
88 @return a pointer to the device path node that follows the device path node specified by Node.
91 EFI_DEVICE_PATH_PROTOCOL
*
97 Determines if a device path node is an end node of a device path.
98 This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path.
100 Determines if the device path node specified by Node is an end node of a device path.
101 This includes nodes that are the end of a device path instance and nodes that are the
102 end of an entire device path. If Node represents an end node of a device path,
103 then TRUE is returned. Otherwise, FALSE is returned.
105 If Node is NULL, then ASSERT().
107 @param Node A pointer to a device path node data structure.
109 @retval TRUE The device path node specified by Node is an end node of a device path.
110 @retval FALSE The device path node specified by Node is not an end node of a device path.
114 IsDevicePathEndType (
119 Determines if a device path node is an end node of an entire device path.
121 Determines if a device path node specified by Node is an end node of an entire device path.
122 If Node represents the end of an entire device path, then TRUE is returned. Otherwise, FALSE is returned.
124 If Node is NULL, then ASSERT().
126 @param Node A pointer to a device path node data structure.
128 @retval TRUE The device path node specified by Node is the end of an entire device path.
129 @retval FALSE The device path node specified by Node is not the end of an entire device path.
138 Determines if a device path node is an end node of a device path instance.
140 Determines if a device path node specified by Node is an end node of a device path instance.
141 If Node represents the end of a device path instance, then TRUE is returned. Otherwise, FALSE is returned.
143 If Node is NULL, then ASSERT().
145 @param Node A pointer to a device path node data structure.
147 @retval TRUE The device path node specified by Node is the end of a device path instance.
148 @retval FALSE The device path node specified by Node is not the end of a device path instance.
152 IsDevicePathEndInstance (
157 Sets the length, in bytes, of a device path node.
159 Sets the length of the device path node specified by Node to the value specified
160 by NodeLength. NodeLength is returned. Node is not required to be aligned on
161 a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()
162 be used to set the contents of the Length field.
164 If Node is NULL, then ASSERT().
165 If NodeLength >= 0x10000, then ASSERT().
167 @param Node A pointer to a device path node data structure.
168 @param Length The length, in bytes, of the device path node.
174 SetDevicePathNodeLength (
180 Fills in all the fields of a device path node that is the end of an entire device path.
182 Fills in all the fields of a device path node specified by Node so Node represents
183 the end of an entire device path. The Type field of Node is set to
184 END_DEVICE_PATH_TYPE, the SubType field of Node is set to
185 END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to
186 END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary,
187 so it is recommended that a function such as WriteUnaligned16() be used to set
188 the contents of the Length field.
190 If Node is NULL, then ASSERT().
192 @param Node A pointer to a device path node data structure.
196 SetDevicePathEndNode (
201 Returns the size of a device path in bytes.
203 This function returns the size, in bytes, of the device path data structure specified by
204 DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned.
206 @param DevicePath A pointer to a device path data structure.
208 @retval 0 If DevicePath is NULL.
209 @retval Others The size of a device path in bytes.
215 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
219 Creates a new copy of an existing device path.
221 This function allocates space for a new copy of the device path specified by DevicePath. If
222 DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the
223 contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer
224 is returned. Otherwise, NULL is returned.
225 The memory for the new device path is allocated from EFI boot services memory.
226 It is the responsibility of the caller to free the memory allocated.
228 @param DevicePath A pointer to a device path data structure.
230 @retval NULL If DevicePath is NULL.
231 @retval Others A pointer to the duplicated device path.
234 EFI_DEVICE_PATH_PROTOCOL
*
236 DuplicateDevicePath (
237 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
241 Creates a new device path by appending a second device path to a first device path.
243 This function creates a new device path by appending a copy of SecondDevicePath to a copy of
244 FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from
245 SecondDevicePath is retained. The newly created device path is returned.
246 If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned.
247 If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned.
248 If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is
250 If there is not enough memory for the newly allocated buffer, then NULL is returned.
251 The memory for the new device path is allocated from EFI boot services memory. It is the
252 responsibility of the caller to free the memory allocated.
254 @param FirstDevicePath A pointer to a device path data structure.
255 @param SecondDevicePath A pointer to a device path data structure.
257 @retval NULL If there is not enough memory for the newly allocated buffer.
258 @retval Others A pointer to the new device path if success.
259 Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.
262 EFI_DEVICE_PATH_PROTOCOL
*
265 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FirstDevicePath
, OPTIONAL
266 IN CONST EFI_DEVICE_PATH_PROTOCOL
*SecondDevicePath OPTIONAL
270 Creates a new path by appending the device node to the device path.
272 This function creates a new device path by appending a copy of the device node specified by
273 DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.
274 The end-of-device-path device node is moved after the end of the appended device node.
275 If DevicePathNode is NULL then a copy of DevicePath is returned.
276 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device path device
278 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node
280 If there is not enough memory to allocate space for the new device path, then NULL is returned.
281 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
282 free the memory allocated.
284 @param DevicePath A pointer to a device path data structure.
285 @param DevicePathNode A pointer to a single device path node.
287 @retval NULL If there is not enough memory for the new device path.
288 @retval Others A pointer to the new device path if success.
289 A copy of DevicePathNode followed by an end-of-device-path node
290 if both FirstDevicePath and SecondDevicePath are NULL.
291 A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL.
294 EFI_DEVICE_PATH_PROTOCOL
*
296 AppendDevicePathNode (
297 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
298 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathNode OPTIONAL
302 Creates a new device path by appending the specified device path instance to the specified device
305 This function creates a new device path by appending a copy of the device path instance specified
306 by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.
307 The end-of-device-path device node is moved after the end of the appended device path instance
308 and a new end-of-device-path-instance node is inserted between.
309 If DevicePath is NULL, then a copy if DevicePathInstance is returned.
310 If DevicePathInstance is NULL, then NULL is returned.
311 If there is not enough memory to allocate space for the new device path, then NULL is returned.
312 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
313 free the memory allocated.
315 @param DevicePath A pointer to a device path data structure.
316 @param DevicePathInstance A pointer to a device path instance.
318 @return A pointer to the new device path.
321 EFI_DEVICE_PATH_PROTOCOL
*
323 AppendDevicePathInstance (
324 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
, OPTIONAL
325 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePathInstance OPTIONAL
329 Creates a copy of the current device path instance and returns a pointer to the next device path
332 This function creates a copy of the current device path instance. It also updates DevicePath to
333 point to the next device path instance in the device path (or NULL if no more) and updates Size
334 to hold the size of the device path instance copy.
335 If DevicePath is NULL, then NULL is returned.
336 If there is not enough memory to allocate space for the new device path, then NULL is returned.
337 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
338 free the memory allocated.
339 If Size is NULL, then ASSERT().
341 @param DevicePath On input, this holds the pointer to the current device path
342 instance. On output, this holds the pointer to the next device
343 path instance or NULL if there are no more device path
344 instances in the device path pointer to a device path data
346 @param Size On output, this holds the size of the device path instance, in
347 bytes or zero, if DevicePath is NULL.
349 @return A pointer to the current device path instance.
352 EFI_DEVICE_PATH_PROTOCOL
*
354 GetNextDevicePathInstance (
355 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
,
360 Creates a device node.
362 This function creates a new device node in a newly allocated buffer of size NodeLength and
363 initializes the device path node header with NodeType and NodeSubType. The new device path node
365 If NodeLength is smaller than a device path header, then NULL is returned.
366 If there is not enough memory to allocate space for the new device path, then NULL is returned.
367 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to
368 free the memory allocated.
370 @param NodeType The device node type for the new device node.
371 @param NodeSubType The device node sub-type for the new device node.
372 @param NodeLength The length of the new device node.
374 @return The new device path.
377 EFI_DEVICE_PATH_PROTOCOL
*
381 IN UINT8 NodeSubType
,
386 Determines if a device path is single or multi-instance.
388 This function returns TRUE if the device path specified by DevicePath is multi-instance.
389 Otherwise, FALSE is returned. If DevicePath is NULL, then FALSE is returned.
391 @param DevicePath A pointer to a device path data structure.
393 @retval TRUE DevicePath is multi-instance.
394 @retval FALSE DevicePath is not multi-instance or DevicePath is NULL.
399 IsDevicePathMultiInstance (
400 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
404 Retrieves the device path protocol from a handle.
406 This function returns the device path protocol from the handle specified by Handle. If Handle is
407 NULL or Handle does not contain a device path protocol, then NULL is returned.
409 @param Handle The handle from which to retrieve the device path protocol.
411 @return The device path protocol from the handle specified by Handle.
414 EFI_DEVICE_PATH_PROTOCOL
*
416 DevicePathFromHandle (
421 Allocates a device path for a file and appends it to an existing device path.
423 If Device is a valid device handle that contains a device path protocol, then a device path for
424 the file specified by FileName is allocated and appended to the device path associated with the
425 handle Device. The allocated device path is returned. If Device is NULL or Device is a handle
426 that does not support the device path protocol, then a device path containing a single device
427 path node for the file specified by FileName is allocated and returned.
428 The memory for the new device path is allocated from EFI boot services memory. It is the responsibility
429 of the caller to free the memory allocated.
431 If FileName is NULL, then ASSERT().
432 If FileName is not aligned on a 16-bit boundary, then ASSERT().
434 @param Device A pointer to a device handle. This parameter is optional and
436 @param FileName A pointer to a Null-terminated Unicode string.
438 @return The allocated device path.
441 EFI_DEVICE_PATH_PROTOCOL
*
444 IN EFI_HANDLE Device
, OPTIONAL
445 IN CONST CHAR16
*FileName