MdePkg DevicePathLib: Validate before touch input buffer.
[mirror_edk2.git] / MdePkg / Library / UefiDevicePathLibDevicePathProtocol / UefiDevicePathLib.c
CommitLineData
e386b444 1/** @file\r
f008fc32 2 Library instance that implement UEFI Device Path Library class based on protocol\r
3 gEfiDevicePathUtilitiesProtocolGuid.\r
e386b444 4\r
d9c2c954 5 Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>\r
19388d29 6 This program and the accompanying materials\r
e386b444 7 are licensed and made available under the terms and conditions of the BSD License\r
8 which accompanies this distribution. The full text of the license may be found at\r
2fc59a00 9 http://opensource.org/licenses/bsd-license.php.\r
e386b444 10\r
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
13\r
e386b444 14**/\r
15\r
c892d846 16\r
c7d265a9 17#include <Uefi.h>\r
c892d846 18\r
c7d265a9 19#include <Protocol/DevicePathUtilities.h>\r
4d0a30a4
RN
20#include <Protocol/DevicePathToText.h>\r
21#include <Protocol/DevicePathFromText.h>\r
c892d846 22\r
c7d265a9 23#include <Library/DevicePathLib.h>\r
24#include <Library/DebugLib.h>\r
25#include <Library/BaseLib.h>\r
26#include <Library/MemoryAllocationLib.h>\r
27#include <Library/BaseMemoryLib.h>\r
28#include <Library/UefiBootServicesTableLib.h>\r
771729c7 29#include <Library/PcdLib.h>\r
e386b444 30\r
4d0a30a4
RN
31GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_UTILITIES_PROTOCOL *mDevicePathLibDevicePathUtilities = NULL;\r
32GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_TO_TEXT_PROTOCOL *mDevicePathLibDevicePathToText = NULL;\r
33GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL *mDevicePathLibDevicePathFromText = NULL;\r
e386b444 34\r
3dc728fb 35//\r
36// Template for an end-of-device path node.\r
37//\r
38GLOBAL_REMOVE_IF_UNREFERENCED CONST EFI_DEVICE_PATH_PROTOCOL mUefiDevicePathLibEndDevicePath = {\r
39 END_DEVICE_PATH_TYPE,\r
40 END_ENTIRE_DEVICE_PATH_SUBTYPE,\r
41 {\r
42 END_DEVICE_PATH_LENGTH,\r
43 0\r
44 }\r
45};\r
46\r
e386b444 47/**\r
48 The constructor function caches the pointer to DevicePathUtilites protocol.\r
49 \r
50 The constructor function locates DevicePathUtilities protocol from protocol database.\r
51 It will ASSERT() if that operation fails and it will always return EFI_SUCCESS. \r
52\r
53 @param ImageHandle The firmware allocated handle for the EFI image.\r
54 @param SystemTable A pointer to the EFI System Table.\r
55 \r
56 @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.\r
57\r
58**/\r
59EFI_STATUS\r
60EFIAPI\r
61DevicePathLibConstructor (\r
62 IN EFI_HANDLE ImageHandle,\r
63 IN EFI_SYSTEM_TABLE *SystemTable\r
64 )\r
65{\r
66 EFI_STATUS Status;\r
67\r
68 Status = gBS->LocateProtocol (\r
69 &gEfiDevicePathUtilitiesProtocolGuid,\r
70 NULL,\r
4d0a30a4 71 (VOID**) &mDevicePathLibDevicePathUtilities\r
e386b444 72 );\r
73 ASSERT_EFI_ERROR (Status);\r
4d0a30a4 74 ASSERT (mDevicePathLibDevicePathUtilities != NULL);\r
e386b444 75 return Status;\r
76}\r
77\r
771729c7
RN
78/**\r
79 Determine whether a given device path is valid.\r
80 If DevicePath is NULL, then ASSERT().\r
81\r
82 @param DevicePath A pointer to a device path data structure.\r
83 @param MaxSize The maximum size of the device path data structure.\r
84\r
85 @retval TRUE DevicePath is valid.\r
86 @retval FALSE The length of any node node in the DevicePath is less\r
87 than sizeof (EFI_DEVICE_PATH_PROTOCOL).\r
88 @retval FALSE If MaxSize is not zero, the size of the DevicePath\r
89 exceeds MaxSize.\r
90 @retval FALSE If PcdMaximumDevicePathNodeCount is not zero, the node\r
91 count of the DevicePath exceeds PcdMaximumDevicePathNodeCount.\r
92**/\r
93BOOLEAN\r
94EFIAPI\r
95IsDevicePathValid (\r
96 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,\r
97 IN UINTN MaxSize\r
98 )\r
99{\r
100 UINTN Count;\r
101 UINTN Size;\r
102 UINTN NodeLength;\r
103\r
104 ASSERT (DevicePath != NULL);\r
105\r
c0cba3d5
ED
106 if (MaxSize == 0) {\r
107 MaxSize = MAX_UINTN;\r
108 }\r
109\r
110 //\r
111 // Validate the input size big enough to touch the first node.\r
112 //\r
113 if (MaxSize < sizeof (EFI_DEVICE_PATH_PROTOCOL)) {\r
114 return FALSE;\r
115 }\r
116\r
1420143f 117 for (Count = 0, Size = 0; !IsDevicePathEnd (DevicePath); DevicePath = NextDevicePathNode (DevicePath)) {\r
771729c7
RN
118 NodeLength = DevicePathNodeLength (DevicePath);\r
119 if (NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL)) {\r
120 return FALSE;\r
121 }\r
122\r
c0cba3d5
ED
123 if (NodeLength > MAX_UINTN - Size) {\r
124 return FALSE;\r
125 }\r
126 Size += NodeLength;\r
127\r
128 //\r
129 // Validate next node before touch it.\r
130 //\r
131 if (Size > MaxSize - END_DEVICE_PATH_LENGTH ) {\r
132 return FALSE;\r
771729c7
RN
133 }\r
134\r
135 if (PcdGet32 (PcdMaximumDevicePathNodeCount) > 0) {\r
136 Count++;\r
137 if (Count >= PcdGet32 (PcdMaximumDevicePathNodeCount)) {\r
138 return FALSE;\r
139 }\r
140 }\r
141 }\r
142\r
143 //\r
144 // Only return TRUE when the End Device Path node is valid.\r
145 //\r
146 return (BOOLEAN) (DevicePathNodeLength (DevicePath) == END_DEVICE_PATH_LENGTH);\r
147}\r
148\r
3dc728fb 149/**\r
150 Returns the Type field of a device path node.\r
151\r
152 Returns the Type field of the device path node specified by Node.\r
153\r
154 If Node is NULL, then ASSERT().\r
155\r
156 @param Node A pointer to a device path node data structure.\r
157\r
158 @return The Type field of the device path node specified by Node.\r
159\r
160**/\r
161UINT8\r
5cba121d 162EFIAPI\r
3dc728fb 163DevicePathType (\r
164 IN CONST VOID *Node\r
165 )\r
166{\r
167 ASSERT (Node != NULL);\r
168 return ((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Type;\r
169}\r
170\r
171/**\r
172 Returns the SubType field of a device path node.\r
173\r
174 Returns the SubType field of the device path node specified by Node.\r
175\r
176 If Node is NULL, then ASSERT().\r
177\r
178 @param Node A pointer to a device path node data structure.\r
179\r
180 @return The SubType field of the device path node specified by Node.\r
181\r
182**/\r
183UINT8\r
5cba121d 184EFIAPI\r
3dc728fb 185DevicePathSubType (\r
186 IN CONST VOID *Node\r
187 )\r
188{\r
189 ASSERT (Node != NULL);\r
190 return ((EFI_DEVICE_PATH_PROTOCOL *)(Node))->SubType;\r
191}\r
192\r
193/**\r
194 Returns the 16-bit Length field of a device path node.\r
195\r
196 Returns the 16-bit Length field of the device path node specified by Node. \r
197 Node is not required to be aligned on a 16-bit boundary, so it is recommended\r
198 that a function such as ReadUnaligned16() be used to extract the contents of \r
199 the Length field.\r
200\r
201 If Node is NULL, then ASSERT().\r
202\r
203 @param Node A pointer to a device path node data structure.\r
204\r
205 @return The 16-bit Length field of the device path node specified by Node.\r
206\r
207**/\r
208UINTN\r
5cba121d 209EFIAPI\r
3dc728fb 210DevicePathNodeLength (\r
211 IN CONST VOID *Node\r
212 )\r
213{\r
214 ASSERT (Node != NULL);\r
0b13fe74 215 return ReadUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0]);\r
3dc728fb 216}\r
217\r
218/**\r
219 Returns a pointer to the next node in a device path.\r
220\r
58380e9c 221 Returns a pointer to the device path node that follows the device path node \r
222 specified by Node.\r
3dc728fb 223\r
224 If Node is NULL, then ASSERT().\r
225\r
226 @param Node A pointer to a device path node data structure.\r
227\r
58380e9c 228 @return a pointer to the device path node that follows the device path node \r
229 specified by Node.\r
3dc728fb 230\r
231**/\r
232EFI_DEVICE_PATH_PROTOCOL *\r
5cba121d 233EFIAPI\r
3dc728fb 234NextDevicePathNode (\r
235 IN CONST VOID *Node\r
236 )\r
237{\r
238 ASSERT (Node != NULL);\r
239 return (EFI_DEVICE_PATH_PROTOCOL *)((UINT8 *)(Node) + DevicePathNodeLength(Node));\r
240}\r
241\r
242/**\r
243 Determines if a device path node is an end node of a device path.\r
58380e9c 244 This includes nodes that are the end of a device path instance and nodes that \r
245 are the end of an entire device path.\r
3dc728fb 246\r
247 Determines if the device path node specified by Node is an end node of a device path. \r
248 This includes nodes that are the end of a device path instance and nodes that are the \r
249 end of an entire device path. If Node represents an end node of a device path, \r
250 then TRUE is returned. Otherwise, FALSE is returned.\r
251\r
252 If Node is NULL, then ASSERT().\r
253\r
254 @param Node A pointer to a device path node data structure.\r
255\r
256 @retval TRUE The device path node specified by Node is an end node of a device path.\r
58380e9c 257 @retval FALSE The device path node specified by Node is not an end node of \r
258 a device path.\r
3dc728fb 259 \r
260**/\r
261BOOLEAN\r
5cba121d 262EFIAPI\r
3dc728fb 263IsDevicePathEndType (\r
264 IN CONST VOID *Node\r
265 )\r
266{\r
267 ASSERT (Node != NULL);\r
a357faa3 268 return (BOOLEAN) (DevicePathType (Node) == END_DEVICE_PATH_TYPE);\r
3dc728fb 269}\r
270\r
271/**\r
272 Determines if a device path node is an end node of an entire device path.\r
273\r
58380e9c 274 Determines if a device path node specified by Node is an end node of an entire \r
275 device path.\r
276 If Node represents the end of an entire device path, then TRUE is returned. \r
277 Otherwise, FALSE is returned.\r
3dc728fb 278\r
279 If Node is NULL, then ASSERT().\r
280\r
281 @param Node A pointer to a device path node data structure.\r
282\r
283 @retval TRUE The device path node specified by Node is the end of an entire device path.\r
284 @retval FALSE The device path node specified by Node is not the end of an entire device path.\r
285\r
286**/\r
287BOOLEAN\r
5cba121d 288EFIAPI\r
3dc728fb 289IsDevicePathEnd (\r
290 IN CONST VOID *Node\r
291 )\r
292{\r
293 ASSERT (Node != NULL);\r
1bfc7438 294 return (BOOLEAN) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_ENTIRE_DEVICE_PATH_SUBTYPE);\r
3dc728fb 295}\r
296\r
297/**\r
298 Determines if a device path node is an end node of a device path instance.\r
299\r
58380e9c 300 Determines if a device path node specified by Node is an end node of a device \r
301 path instance.\r
302 If Node represents the end of a device path instance, then TRUE is returned. \r
303 Otherwise, FALSE is returned.\r
3dc728fb 304\r
305 If Node is NULL, then ASSERT().\r
306\r
307 @param Node A pointer to a device path node data structure.\r
308\r
58380e9c 309 @retval TRUE The device path node specified by Node is the end of a device \r
310 path instance.\r
311 @retval FALSE The device path node specified by Node is not the end of a \r
312 device path instance.\r
3dc728fb 313\r
314**/\r
315BOOLEAN\r
5cba121d 316EFIAPI\r
3dc728fb 317IsDevicePathEndInstance (\r
318 IN CONST VOID *Node\r
319 )\r
320{\r
321 ASSERT (Node != NULL);\r
1bfc7438 322 return (BOOLEAN) (IsDevicePathEndType (Node) && DevicePathSubType(Node) == END_INSTANCE_DEVICE_PATH_SUBTYPE);\r
3dc728fb 323}\r
324\r
325/**\r
326 Sets the length, in bytes, of a device path node.\r
327\r
328 Sets the length of the device path node specified by Node to the value specified \r
329 by NodeLength. NodeLength is returned. Node is not required to be aligned on \r
330 a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16()\r
331 be used to set the contents of the Length field.\r
332\r
333 If Node is NULL, then ASSERT().\r
771729c7
RN
334 If NodeLength >= SIZE_64KB, then ASSERT().\r
335 If NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL), then ASSERT().\r
3dc728fb 336\r
337 @param Node A pointer to a device path node data structure.\r
338 @param Length The length, in bytes, of the device path node.\r
339\r
340 @return Length\r
341\r
342**/\r
343UINT16\r
5cba121d 344EFIAPI\r
3dc728fb 345SetDevicePathNodeLength (\r
9bb407c6 346 IN OUT VOID *Node,\r
8f0dd97e 347 IN UINTN Length\r
3dc728fb 348 )\r
349{\r
350 ASSERT (Node != NULL);\r
771729c7 351 ASSERT ((Length >= sizeof (EFI_DEVICE_PATH_PROTOCOL)) && (Length < SIZE_64KB));\r
8f0dd97e 352 return WriteUnaligned16 ((UINT16 *)&((EFI_DEVICE_PATH_PROTOCOL *)(Node))->Length[0], (UINT16)(Length));\r
3dc728fb 353}\r
354\r
355/**\r
356 Fills in all the fields of a device path node that is the end of an entire device path.\r
357\r
358 Fills in all the fields of a device path node specified by Node so Node represents \r
359 the end of an entire device path. The Type field of Node is set to \r
360 END_DEVICE_PATH_TYPE, the SubType field of Node is set to \r
361 END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to \r
362 END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary, \r
363 so it is recommended that a function such as WriteUnaligned16() be used to set \r
364 the contents of the Length field. \r
365\r
366 If Node is NULL, then ASSERT(). \r
367\r
368 @param Node A pointer to a device path node data structure.\r
369\r
370**/\r
371VOID\r
5cba121d 372EFIAPI\r
3dc728fb 373SetDevicePathEndNode (\r
9bb407c6 374 OUT VOID *Node\r
3dc728fb 375 )\r
376{\r
377 ASSERT (Node != NULL);\r
378 CopyMem (Node, &mUefiDevicePathLibEndDevicePath, sizeof (mUefiDevicePathLibEndDevicePath));\r
379}\r
380\r
e386b444 381/**\r
382 Returns the size of a device path in bytes.\r
383\r
771729c7
RN
384 This function returns the size, in bytes, of the device path data structure \r
385 specified by DevicePath including the end of device path node.\r
386 If DevicePath is NULL or invalid, then 0 is returned.\r
e386b444 387\r
771729c7
RN
388 @param DevicePath A pointer to a device path data structure.\r
389\r
390 @retval 0 If DevicePath is NULL or invalid.\r
391 @retval Others The size of a device path in bytes.\r
e386b444 392\r
393**/\r
394UINTN\r
395EFIAPI\r
396GetDevicePathSize (\r
397 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
398 )\r
399{\r
4d0a30a4 400 return mDevicePathLibDevicePathUtilities->GetDevicePathSize (DevicePath);\r
e386b444 401}\r
402\r
403/**\r
6a3f4ef9 404 Creates a new copy of an existing device path.\r
e386b444 405\r
58380e9c 406 This function allocates space for a new copy of the device path specified by \r
407 DevicePath. If DevicePath is NULL, then NULL is returned. \r
408 If the memory is successfully allocated, then the\r
e386b444 409 contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer\r
410 is returned. Otherwise, NULL is returned. \r
3e5c3238 411 The memory for the new device path is allocated from EFI boot services memory. \r
412 It is the responsibility of the caller to free the memory allocated. \r
e386b444 413 \r
414 @param DevicePath A pointer to a device path data structure.\r
415\r
771729c7 416 @retval NULL If DevicePath is NULL or invalid.\r
3e5c3238 417 @retval Others A pointer to the duplicated device path.\r
418 \r
e386b444 419**/\r
420EFI_DEVICE_PATH_PROTOCOL *\r
421EFIAPI\r
422DuplicateDevicePath (\r
423 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
424 )\r
425{\r
4d0a30a4 426 return mDevicePathLibDevicePathUtilities->DuplicateDevicePath (DevicePath);\r
e386b444 427}\r
428\r
429/**\r
430 Creates a new device path by appending a second device path to a first device path.\r
431\r
432 This function creates a new device path by appending a copy of SecondDevicePath to a copy of\r
433 FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from\r
434 SecondDevicePath is retained. The newly created device path is returned. \r
435 If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned. \r
436 If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned. \r
98a14db6 437 If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is\r
438 returned. \r
e386b444 439 If there is not enough memory for the newly allocated buffer, then NULL is returned.\r
440 The memory for the new device path is allocated from EFI boot services memory. It is the\r
441 responsibility of the caller to free the memory allocated.\r
442\r
443 @param FirstDevicePath A pointer to a device path data structure.\r
444 @param SecondDevicePath A pointer to a device path data structure.\r
3e5c3238 445 \r
446 @retval NULL If there is not enough memory for the newly allocated buffer.\r
771729c7 447 @retval NULL If FirstDevicePath or SecondDevicePath is invalid.\r
3e5c3238 448 @retval Others A pointer to the new device path if success.\r
58380e9c 449 Or a copy an end-of-device-path if both FirstDevicePath and \r
450 SecondDevicePath are NULL.\r
e386b444 451\r
452**/\r
453EFI_DEVICE_PATH_PROTOCOL *\r
454EFIAPI\r
455AppendDevicePath (\r
456 IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath, OPTIONAL\r
457 IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath OPTIONAL\r
458 )\r
459{\r
4d0a30a4 460 return mDevicePathLibDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);\r
e386b444 461}\r
462\r
463/**\r
464 Creates a new path by appending the device node to the device path.\r
465\r
58380e9c 466 This function creates a new device path by appending a copy of the device node \r
467 specified by DevicePathNode to a copy of the device path specified by DevicePath \r
468 in an allocated buffer.\r
e386b444 469 The end-of-device-path device node is moved after the end of the appended device node.\r
98a14db6 470 If DevicePathNode is NULL then a copy of DevicePath is returned.\r
58380e9c 471 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device \r
472 path device node is returned.\r
473 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path \r
474 device node is returned.\r
475 If there is not enough memory to allocate space for the new device path, then \r
476 NULL is returned. \r
477 The memory is allocated from EFI boot services memory. It is the responsibility \r
478 of the caller to free the memory allocated.\r
e386b444 479\r
480 @param DevicePath A pointer to a device path data structure.\r
481 @param DevicePathNode A pointer to a single device path node.\r
482\r
3e5c3238 483 @retval NULL If there is not enough memory for the new device path.\r
484 @retval Others A pointer to the new device path if success.\r
485 A copy of DevicePathNode followed by an end-of-device-path node \r
486 if both FirstDevicePath and SecondDevicePath are NULL.\r
58380e9c 487 A copy of an end-of-device-path node if both FirstDevicePath \r
488 and SecondDevicePath are NULL.\r
e386b444 489\r
490**/\r
491EFI_DEVICE_PATH_PROTOCOL *\r
492EFIAPI\r
493AppendDevicePathNode (\r
494 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
495 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode OPTIONAL\r
496 )\r
497{\r
4d0a30a4 498 return mDevicePathLibDevicePathUtilities->AppendDeviceNode (DevicePath, DevicePathNode);\r
e386b444 499}\r
500\r
501/**\r
58380e9c 502 Creates a new device path by appending the specified device path instance to \r
503 the specified device path.\r
e386b444 504 \r
58380e9c 505 This function creates a new device path by appending a copy of the device path \r
506 instance specified by DevicePathInstance to a copy of the device path specified \r
507 by DevicePath in a allocated buffer.\r
508 The end-of-device-path device node is moved after the end of the appended device \r
509 path instance and a new end-of-device-path-instance node is inserted between. \r
e386b444 510 If DevicePath is NULL, then a copy if DevicePathInstance is returned.\r
511 If DevicePathInstance is NULL, then NULL is returned.\r
771729c7 512 If DevicePath or DevicePathInstance is invalid, then NULL is returned.\r
58380e9c 513 If there is not enough memory to allocate space for the new device path, then \r
514 NULL is returned. \r
515 The memory is allocated from EFI boot services memory. It is the responsibility \r
516 of the caller to free the memory allocated.\r
e386b444 517 \r
518 @param DevicePath A pointer to a device path data structure.\r
519 @param DevicePathInstance A pointer to a device path instance.\r
520\r
521 @return A pointer to the new device path.\r
522\r
523**/\r
524EFI_DEVICE_PATH_PROTOCOL *\r
525EFIAPI\r
526AppendDevicePathInstance (\r
527 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
528 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance OPTIONAL\r
529 )\r
530{\r
4d0a30a4 531 return mDevicePathLibDevicePathUtilities->AppendDevicePathInstance (DevicePath, DevicePathInstance);\r
e386b444 532}\r
533\r
534/**\r
58380e9c 535 Creates a copy of the current device path instance and returns a pointer to the \r
536 next device path instance.\r
e386b444 537\r
58380e9c 538 This function creates a copy of the current device path instance. It also updates \r
539 DevicePath to point to the next device path instance in the device path (or NULL \r
540 if no more) and updates Size to hold the size of the device path instance copy.\r
e386b444 541 If DevicePath is NULL, then NULL is returned.\r
58380e9c 542 If there is not enough memory to allocate space for the new device path, then \r
543 NULL is returned. \r
544 The memory is allocated from EFI boot services memory. It is the responsibility \r
545 of the caller to free the memory allocated.\r
e386b444 546 If Size is NULL, then ASSERT().\r
547 \r
58380e9c 548 @param DevicePath On input, this holds the pointer to the current \r
549 device path instance. On output, this holds \r
550 the pointer to the next device path instance \r
551 or NULL if there are no more device path\r
552 instances in the device path pointer to a \r
553 device path data structure.\r
554 @param Size On output, this holds the size of the device \r
555 path instance, in bytes or zero, if DevicePath \r
556 is NULL.\r
e386b444 557\r
558 @return A pointer to the current device path instance.\r
559\r
560**/\r
561EFI_DEVICE_PATH_PROTOCOL *\r
562EFIAPI\r
563GetNextDevicePathInstance (\r
564 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,\r
565 OUT UINTN *Size\r
566 )\r
567{\r
568 ASSERT (Size != NULL);\r
4d0a30a4 569 return mDevicePathLibDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);\r
e386b444 570}\r
571\r
572/**\r
3e5c3238 573 Creates a device node.\r
e386b444 574\r
58380e9c 575 This function creates a new device node in a newly allocated buffer of size \r
576 NodeLength and initializes the device path node header with NodeType and NodeSubType. \r
577 The new device path node is returned.\r
e386b444 578 If NodeLength is smaller than a device path header, then NULL is returned. \r
58380e9c 579 If there is not enough memory to allocate space for the new device path, then \r
580 NULL is returned. \r
581 The memory is allocated from EFI boot services memory. It is the responsibility \r
0b13fe74 582 of the caller to free the memory allocated.\r
e386b444 583\r
584 @param NodeType The device node type for the new device node.\r
585 @param NodeSubType The device node sub-type for the new device node.\r
586 @param NodeLength The length of the new device node.\r
587\r
3e5c3238 588 @return The new device path.\r
e386b444 589\r
590**/\r
591EFI_DEVICE_PATH_PROTOCOL *\r
592EFIAPI\r
593CreateDeviceNode (\r
594 IN UINT8 NodeType,\r
595 IN UINT8 NodeSubType,\r
596 IN UINT16 NodeLength\r
597 )\r
598{\r
4d0a30a4 599 return mDevicePathLibDevicePathUtilities->CreateDeviceNode (NodeType, NodeSubType, NodeLength);\r
e386b444 600}\r
601\r
602/**\r
603 Determines if a device path is single or multi-instance.\r
604\r
771729c7 605 This function returns TRUE if the device path specified by DevicePath is\r
58380e9c 606 multi-instance.\r
771729c7
RN
607 Otherwise, FALSE is returned.\r
608 If DevicePath is NULL or invalid, then FALSE is returned.\r
e386b444 609\r
610 @param DevicePath A pointer to a device path data structure.\r
611\r
612 @retval TRUE DevicePath is multi-instance.\r
771729c7
RN
613 @retval FALSE DevicePath is not multi-instance, or DevicePath \r
614 is NULL or invalid.\r
e386b444 615\r
616**/\r
617BOOLEAN\r
618EFIAPI\r
619IsDevicePathMultiInstance (\r
620 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
621 )\r
622{\r
4d0a30a4 623 return mDevicePathLibDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);\r
e386b444 624}\r
625\r
626/**\r
627 Retrieves the device path protocol from a handle.\r
628\r
58380e9c 629 This function returns the device path protocol from the handle specified by Handle. \r
630 If Handle is NULL or Handle does not contain a device path protocol, then NULL \r
631 is returned.\r
e386b444 632 \r
58380e9c 633 @param Handle The handle from which to retrieve the device \r
634 path protocol.\r
e386b444 635\r
636 @return The device path protocol from the handle specified by Handle.\r
637\r
638**/\r
639EFI_DEVICE_PATH_PROTOCOL *\r
640EFIAPI\r
641DevicePathFromHandle (\r
642 IN EFI_HANDLE Handle\r
643 )\r
644{\r
645 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
646 EFI_STATUS Status;\r
647\r
648 Status = gBS->HandleProtocol (\r
649 Handle,\r
650 &gEfiDevicePathProtocolGuid,\r
651 (VOID *) &DevicePath\r
652 );\r
653 if (EFI_ERROR (Status)) {\r
654 DevicePath = NULL;\r
655 }\r
656 return DevicePath;\r
657}\r
658\r
659/**\r
660 Allocates a device path for a file and appends it to an existing device path.\r
661\r
58380e9c 662 If Device is a valid device handle that contains a device path protocol, then \r
663 a device path for the file specified by FileName is allocated and appended to \r
664 the device path associated with the handle Device. The allocated device path \r
665 is returned. If Device is NULL or Device is a handle that does not support the \r
666 device path protocol, then a device path containing a single device path node \r
667 for the file specified by FileName is allocated and returned.\r
668 The memory for the new device path is allocated from EFI boot services memory. \r
669 It is the responsibility of the caller to free the memory allocated.\r
3e5c3238 670 \r
e386b444 671 If FileName is NULL, then ASSERT().\r
3e5c3238 672 If FileName is not aligned on a 16-bit boundary, then ASSERT().\r
e386b444 673\r
58380e9c 674 @param Device A pointer to a device handle. This parameter \r
675 is optional and may be NULL.\r
e386b444 676 @param FileName A pointer to a Null-terminated Unicode string.\r
677\r
3e5c3238 678 @return The allocated device path.\r
e386b444 679\r
680**/\r
681EFI_DEVICE_PATH_PROTOCOL *\r
682EFIAPI\r
683FileDevicePath (\r
684 IN EFI_HANDLE Device, OPTIONAL\r
685 IN CONST CHAR16 *FileName\r
686 )\r
687{\r
688 UINTN Size;\r
689 FILEPATH_DEVICE_PATH *FilePath;\r
690 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
691 EFI_DEVICE_PATH_PROTOCOL *FileDevicePath;\r
692\r
693 DevicePath = NULL;\r
694\r
695 Size = StrSize (FileName);\r
e5dab016 696 FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + END_DEVICE_PATH_LENGTH);\r
e386b444 697 if (FileDevicePath != NULL) {\r
698 FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePath;\r
699 FilePath->Header.Type = MEDIA_DEVICE_PATH;\r
700 FilePath->Header.SubType = MEDIA_FILEPATH_DP;\r
701 CopyMem (&FilePath->PathName, FileName, Size);\r
702 SetDevicePathNodeLength (&FilePath->Header, Size + SIZE_OF_FILEPATH_DEVICE_PATH);\r
703 SetDevicePathEndNode (NextDevicePathNode (&FilePath->Header));\r
704\r
705 if (Device != NULL) {\r
706 DevicePath = DevicePathFromHandle (Device);\r
707 }\r
708\r
709 DevicePath = AppendDevicePath (DevicePath, FileDevicePath);\r
710 FreePool (FileDevicePath);\r
711 }\r
712\r
713 return DevicePath;\r
714}\r
4d0a30a4
RN
715\r
716/**\r
717 Locate and return the protocol instance identified by the ProtocolGuid.\r
718\r
719 @param ProtocolGuid The GUID of the protocol.\r
720\r
721 @return A pointer to the protocol instance or NULL when absent.\r
722**/\r
723VOID *\r
724UefiDevicePathLibLocateProtocol (\r
725 EFI_GUID *ProtocolGuid\r
726 )\r
727{\r
728 EFI_STATUS Status;\r
729 VOID *Protocol;\r
730 Status = gBS->LocateProtocol (\r
731 ProtocolGuid,\r
732 NULL,\r
733 (VOID**) &Protocol\r
734 );\r
735 if (EFI_ERROR (Status)) {\r
736 return NULL;\r
737 } else {\r
738 return Protocol;\r
739 }\r
740}\r
741\r
742/**\r
743 Converts a device node to its string representation.\r
744\r
745 @param DeviceNode A Pointer to the device node to be converted.\r
746 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation\r
747 of the display node is used, where applicable. If DisplayOnly\r
748 is FALSE, then the longer text representation of the display node\r
749 is used.\r
750 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text\r
751 representation for a device node can be used, where applicable.\r
752\r
753 @return A pointer to the allocated text representation of the device node or NULL if DeviceNode\r
754 is NULL or there was insufficient memory.\r
755\r
756**/\r
757CHAR16 *\r
758EFIAPI\r
759ConvertDeviceNodeToText (\r
760 IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode,\r
761 IN BOOLEAN DisplayOnly,\r
762 IN BOOLEAN AllowShortcuts\r
763 )\r
764{\r
765 if (mDevicePathLibDevicePathToText == NULL) {\r
766 mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);\r
767 }\r
768 if (mDevicePathLibDevicePathToText != NULL) {\r
769 return mDevicePathLibDevicePathToText->ConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);\r
770 } else {\r
771 return NULL;\r
772 }\r
773}\r
774\r
775/**\r
776 Converts a device path to its text representation.\r
777\r
778 @param DevicePath A Pointer to the device to be converted.\r
779 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation\r
780 of the display node is used, where applicable. If DisplayOnly\r
781 is FALSE, then the longer text representation of the display node\r
782 is used.\r
783 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text\r
784 representation for a device node can be used, where applicable.\r
785\r
786 @return A pointer to the allocated text representation of the device path or\r
787 NULL if DeviceNode is NULL or there was insufficient memory.\r
788\r
789**/\r
790CHAR16 *\r
791EFIAPI\r
792ConvertDevicePathToText (\r
793 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,\r
794 IN BOOLEAN DisplayOnly,\r
795 IN BOOLEAN AllowShortcuts\r
796 )\r
797{\r
798 if (mDevicePathLibDevicePathToText == NULL) {\r
799 mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);\r
800 }\r
801 if (mDevicePathLibDevicePathToText != NULL) {\r
802 return mDevicePathLibDevicePathToText->ConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);\r
803 } else {\r
804 return NULL;\r
805 }\r
806}\r
807\r
808/**\r
809 Convert text to the binary representation of a device node.\r
810\r
811 @param TextDeviceNode TextDeviceNode points to the text representation of a device\r
812 node. Conversion starts with the first character and continues\r
813 until the first non-device node character.\r
814\r
815 @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was\r
816 insufficient memory or text unsupported.\r
817\r
818**/\r
819EFI_DEVICE_PATH_PROTOCOL *\r
820EFIAPI\r
821ConvertTextToDeviceNode (\r
822 IN CONST CHAR16 *TextDeviceNode\r
823 )\r
824{\r
825 if (mDevicePathLibDevicePathFromText == NULL) {\r
826 mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);\r
827 }\r
828 if (mDevicePathLibDevicePathFromText != NULL) {\r
829 return mDevicePathLibDevicePathFromText->ConvertTextToDeviceNode (TextDeviceNode);\r
830 } else {\r
831 return NULL;\r
832 }\r
833}\r
834\r
835/**\r
836 Convert text to the binary representation of a device path.\r
837\r
838\r
839 @param TextDevicePath TextDevicePath points to the text representation of a device\r
840 path. Conversion starts with the first character and continues\r
841 until the first non-device node character.\r
842\r
843 @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or\r
844 there was insufficient memory.\r
845\r
846**/\r
847EFI_DEVICE_PATH_PROTOCOL *\r
848EFIAPI\r
849ConvertTextToDevicePath (\r
850 IN CONST CHAR16 *TextDevicePath\r
851 )\r
852{\r
853 if (mDevicePathLibDevicePathFromText == NULL) {\r
854 mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);\r
855 }\r
856 if (mDevicePathLibDevicePathFromText != NULL) {\r
857 return mDevicePathLibDevicePathFromText->ConvertTextToDevicePath (TextDevicePath);\r
858 } else {\r
859 return NULL;\r
860 }\r
861}\r
862\r