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
7Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
8This program and the accompanying materials are licensed and made available under
9the terms and conditions of the BSD License that accompanies this distribution.
10The full text of the license may be found at
11http://opensource.org/licenses/bsd-license.php.
12
13THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14WITHOUT 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**/
38BOOLEAN
39EFIAPI
40IsDevicePathValid (
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**/
57UINT8
58EFIAPI
59DevicePathType (
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**/
75UINT8
76EFIAPI
77DevicePathSubType (
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**/
96UINTN
97EFIAPI
98DevicePathNodeLength (
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**/
114EFI_DEVICE_PATH_PROTOCOL *
115EFIAPI
116NextDevicePathNode (
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**/
138BOOLEAN
139EFIAPI
140IsDevicePathEndType (
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**/
159BOOLEAN
160EFIAPI
161IsDevicePathEnd (
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**/
180BOOLEAN
181EFIAPI
182IsDevicePathEndInstance (
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**/
204UINT16
205EFIAPI
206SetDevicePathNodeLength (
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**/
227VOID
228EFIAPI
229SetDevicePathEndNode (
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**/
246UINTN
247EFIAPI
248GetDevicePathSize (
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**/
268EFI_DEVICE_PATH_PROTOCOL *
269EFIAPI
270DuplicateDevicePath (
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**/
297EFI_DEVICE_PATH_PROTOCOL *
298EFIAPI
299AppendDevicePath (
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**/
329EFI_DEVICE_PATH_PROTOCOL *
330EFIAPI
331AppendDevicePathNode (
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**/
357EFI_DEVICE_PATH_PROTOCOL *
358EFIAPI
359AppendDevicePathInstance (
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**/
389EFI_DEVICE_PATH_PROTOCOL *
390EFIAPI
391GetNextDevicePathInstance (
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**/
414EFI_DEVICE_PATH_PROTOCOL *
415EFIAPI
416CreateDeviceNode (
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**/
435BOOLEAN
436EFIAPI
437IsDevicePathMultiInstance (
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**/
452EFI_DEVICE_PATH_PROTOCOL *
453EFIAPI
454DevicePathFromHandle (
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**/
479EFI_DEVICE_PATH_PROTOCOL *
480EFIAPI
481FileDevicePath (
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**/
501CHAR16 *
502EFIAPI
503ConvertDevicePathToText (
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**/
524CHAR16 *
525EFIAPI
526ConvertDeviceNodeToText (
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**/
543EFI_DEVICE_PATH_PROTOCOL *
544EFIAPI
545ConvertTextToDeviceNode (
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**/
560EFI_DEVICE_PATH_PROTOCOL *
561EFIAPI
562ConvertTextToDevicePath (
563  IN CONST CHAR16 *TextDevicePath
564  );
565
566#endif
567