Moved the MdePkg to OldMdePkg so that new code in MdePkg does not break existing...
[mirror_edk2.git] / OldMdePkg / Library / UefiDevicePathLib / UefiDevicePathLib.c
CommitLineData
878ddf1f 1/** @file\r
2 Device Path services. The thing to remember is device paths are built out of\r
3 nodes. The device path is terminated by an end node that is length\r
4 sizeof(EFI_DEVICE_PATH_PROTOCOL). That would be why there is sizeof(EFI_DEVICE_PATH_PROTOCOL)\r
5 all over this file.\r
6\r
7 The only place where multi-instance device paths are supported is in\r
8 environment varibles. Multi-instance device paths should never be placed\r
9 on a Handle.\r
10\r
11 Copyright (c) 2006, Intel Corporation \r
12 All rights reserved. This program and the accompanying materials \r
13 are licensed and made available under the terms and conditions of the BSD License \r
14 which accompanies this distribution. The full text of the license may be found at \r
15 http://opensource.org/licenses/bsd-license.php \r
16\r
17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
19\r
20 Module Name: UefiDevicePathLib.c\r
21\r
22**/\r
23\r
24/**\r
add13dc2 25 Returns the size of a device path in bytes.\r
878ddf1f 26\r
add13dc2 27 This function returns the size, in bytes, of the device path data structure specified by\r
28 DevicePath including the end of device path node. If DevicePath is NULL, then 0 is returned.\r
29\r
30 @param DevicePath A pointer to a device path data structure.\r
878ddf1f 31\r
32 @return The size of a device path in bytes.\r
33\r
34**/\r
35UINTN\r
36EFIAPI\r
37GetDevicePathSize (\r
38 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
39 )\r
40{\r
41 CONST EFI_DEVICE_PATH_PROTOCOL *Start;\r
42\r
43 if (DevicePath == NULL) {\r
44 return 0;\r
45 }\r
46\r
47 //\r
48 // Search for the end of the device path structure\r
49 //\r
50 Start = DevicePath;\r
51 while (!EfiIsDevicePathEnd (DevicePath)) {\r
52 DevicePath = EfiNextDevicePathNode (DevicePath);\r
53 }\r
54\r
55 //\r
56 // Compute the size and add back in the size of the end device path structure\r
57 //\r
58 return ((UINTN) DevicePath - (UINTN) Start) + sizeof (EFI_DEVICE_PATH_PROTOCOL);\r
59}\r
60\r
61/**\r
add13dc2 62 Creates a new device path by appending a second device path to a first device path.\r
878ddf1f 63\r
add13dc2 64 This function allocates space for a new copy of the device path specified by DevicePath. If\r
65 DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the\r
66 contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer\r
67 is returned. Otherwise, NULL is returned. \r
68 \r
69 @param DevicePath A pointer to a device path data structure.\r
878ddf1f 70\r
add13dc2 71 @return A pointer to the duplicated device path.\r
878ddf1f 72\r
73**/\r
74EFI_DEVICE_PATH_PROTOCOL *\r
75EFIAPI\r
76DuplicateDevicePath (\r
add13dc2 77 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
878ddf1f 78 )\r
79{\r
80 EFI_DEVICE_PATH_PROTOCOL *NewDevicePath;\r
81 UINTN Size;\r
82\r
83 //\r
84 // Compute the size\r
85 //\r
86 Size = GetDevicePathSize (DevicePath);\r
87 if (Size == 0) {\r
88 return NULL;\r
89 }\r
90\r
91 //\r
92 // Allocate space for duplicate device path\r
93 //\r
94 NewDevicePath = AllocateCopyPool (Size, DevicePath);\r
95\r
96 return NewDevicePath;\r
97}\r
98\r
99/**\r
add13dc2 100 Creates a new device path by appending a second device path to a first device path.\r
878ddf1f 101\r
add13dc2 102 This function creates a new device path by appending a copy of SecondDevicePath to a copy of\r
103 FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from\r
104 SecondDevicePath is retained. The newly created device path is returned. \r
105 If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned. \r
106 If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned. \r
107 If both FirstDevicePath and SecondDevicePath are NULL, then NULL is returned. \r
108 If there is not enough memory for the newly allocated buffer, then NULL is returned.\r
109 The memory for the new device path is allocated from EFI boot services memory. It is the\r
110 responsibility of the caller to free the memory allocated.\r
878ddf1f 111\r
add13dc2 112 @param FirstDevicePath A pointer to a device path data structure.\r
113 @param SecondDevicePath A pointer to a device path data structure.\r
114\r
115 @return A pointer to the new device path.\r
878ddf1f 116\r
117**/\r
118EFI_DEVICE_PATH_PROTOCOL *\r
119EFIAPI\r
120AppendDevicePath (\r
add13dc2 121 IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath, OPTIONAL\r
122 IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath OPTIONAL\r
878ddf1f 123 )\r
124{\r
125 UINTN Size;\r
126 UINTN Size1;\r
127 UINTN Size2;\r
128 EFI_DEVICE_PATH_PROTOCOL *NewDevicePath;\r
129 EFI_DEVICE_PATH_PROTOCOL *DevicePath2;\r
130\r
131 //\r
add13dc2 132 // If there's only 1 path, just duplicate it.\r
878ddf1f 133 //\r
134 if (FirstDevicePath == NULL) {\r
135 return DuplicateDevicePath (SecondDevicePath);\r
136 }\r
137\r
138 if (SecondDevicePath == NULL) {\r
139 return DuplicateDevicePath (FirstDevicePath);\r
140 }\r
141\r
142 //\r
143 // Allocate space for the combined device path. It only has one end node of\r
add13dc2 144 // length EFI_DEVICE_PATH_PROTOCOL.\r
878ddf1f 145 //\r
146 Size1 = GetDevicePathSize (FirstDevicePath);\r
147 Size2 = GetDevicePathSize (SecondDevicePath);\r
148 Size = Size1 + Size2 - sizeof (EFI_DEVICE_PATH_PROTOCOL);\r
149\r
150 NewDevicePath = AllocatePool (Size);\r
151\r
152 if (NewDevicePath != NULL) {\r
153 NewDevicePath = CopyMem (NewDevicePath, FirstDevicePath, Size1);\r
154 //\r
add13dc2 155 // Over write FirstDevicePath EndNode and do the copy\r
878ddf1f 156 //\r
add13dc2 157 DevicePath2 = (EFI_DEVICE_PATH_PROTOCOL *) ((CHAR8 *) NewDevicePath +\r
158 (Size1 - sizeof (EFI_DEVICE_PATH_PROTOCOL)));\r
878ddf1f 159 CopyMem (DevicePath2, SecondDevicePath, Size2);\r
160 }\r
161\r
162 return NewDevicePath;\r
163}\r
164\r
165/**\r
add13dc2 166 Creates a new path by appending the device node to the device path.\r
878ddf1f 167\r
add13dc2 168 This function creates a new device path by appending a copy of the device node specified by\r
169 DevicePathNode to a copy of the device path specified by DevicePath in an allocated buffer.\r
170 The end-of-device-path device node is moved after the end of the appended device node.\r
171 If DevicePath is NULL, then NULL is returned.\r
172 If DevicePathNode is NULL, then NULL is returned.\r
173 If there is not enough memory to allocate space for the new device path, then NULL is returned. \r
174 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to\r
175 free the memory allocated.\r
176\r
177 @param DevicePath A pointer to a device path data structure.\r
178 @param DevicePathNode A pointer to a single device path node.\r
878ddf1f 179\r
180 @return A pointer to the new device path.\r
878ddf1f 181\r
182**/\r
183EFI_DEVICE_PATH_PROTOCOL *\r
184EFIAPI\r
185AppendDevicePathNode (\r
add13dc2 186 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
187 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode OPTIONAL\r
878ddf1f 188 )\r
189{\r
5f10fa01 190 EFI_DEVICE_PATH_PROTOCOL *TempDevicePath;\r
878ddf1f 191 EFI_DEVICE_PATH_PROTOCOL *NextNode;\r
192 EFI_DEVICE_PATH_PROTOCOL *NewDevicePath;\r
193 UINTN NodeLength;\r
878ddf1f 194\r
add13dc2 195 if (DevicePath == NULL || DevicePathNode == NULL) {\r
196 return NULL;\r
197 }\r
878ddf1f 198 //\r
199 // Build a Node that has a terminator on it\r
200 //\r
5f10fa01 201 NodeLength = DevicePathNodeLength (DevicePathNode);\r
878ddf1f 202\r
5f10fa01 203 TempDevicePath = AllocatePool (NodeLength + sizeof (EFI_DEVICE_PATH_PROTOCOL));\r
204 if (TempDevicePath == NULL) {\r
205 return NULL;\r
878ddf1f 206 }\r
5f10fa01 207 TempDevicePath = CopyMem (TempDevicePath, DevicePathNode, NodeLength);\r
208 //\r
209 // Add and end device path node to convert Node to device path\r
210 //\r
211 NextNode = NextDevicePathNode (TempDevicePath);\r
212 SetDevicePathEndNode (NextNode);\r
213 //\r
214 // Append device paths\r
215 //\r
216 NewDevicePath = AppendDevicePath (DevicePath, TempDevicePath);\r
217\r
218 FreePool (TempDevicePath);\r
219\r
878ddf1f 220 return NewDevicePath;\r
221}\r
222\r
223/**\r
add13dc2 224 Creates a new device path by appending the specified device path instance to the specified device\r
225 path.\r
226 \r
227 This function creates a new device path by appending a copy of the device path instance specified\r
228 by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer.\r
229 The end-of-device-path device node is moved after the end of the appended device path instance\r
230 and a new end-of-device-path-instance node is inserted between. \r
231 If DevicePath is NULL, then a copy if DevicePathInstance is returned.\r
232 If DevicePathInstance is NULL, then NULL is returned.\r
233 If there is not enough memory to allocate space for the new device path, then NULL is returned. \r
234 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to\r
235 free the memory allocated.\r
236 \r
237 @param DevicePath A pointer to a device path data structure.\r
238 @param DevicePathInstance A pointer to a device path instance.\r
878ddf1f 239\r
240 @return A pointer to the new device path.\r
878ddf1f 241\r
242**/\r
243EFI_DEVICE_PATH_PROTOCOL *\r
244EFIAPI\r
245AppendDevicePathInstance (\r
add13dc2 246 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
247 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance OPTIONAL\r
878ddf1f 248 )\r
249{\r
250 EFI_DEVICE_PATH_PROTOCOL *NewDevicePath;\r
add13dc2 251 EFI_DEVICE_PATH_PROTOCOL *TempDevicePath;\r
878ddf1f 252 UINTN SrcSize;\r
253 UINTN InstanceSize;\r
254\r
add13dc2 255 if (DevicePath == NULL) {\r
256 return DuplicateDevicePath (DevicePathInstance);\r
257 }\r
258\r
259 if (DevicePathInstance == NULL) {\r
260 return NULL;\r
878ddf1f 261 }\r
262\r
add13dc2 263 SrcSize = GetDevicePathSize (DevicePath);\r
264 InstanceSize = GetDevicePathSize (DevicePathInstance);\r
878ddf1f 265\r
266 NewDevicePath = AllocatePool (SrcSize + InstanceSize);\r
267 if (NewDevicePath != NULL) {\r
268 \r
add13dc2 269 TempDevicePath = CopyMem (NewDevicePath, DevicePath, SrcSize);;\r
878ddf1f 270 \r
add13dc2 271 while (!IsDevicePathEnd (TempDevicePath)) {\r
272 TempDevicePath = NextDevicePathNode (TempDevicePath);\r
878ddf1f 273 }\r
274 \r
add13dc2 275 TempDevicePath->SubType = END_INSTANCE_DEVICE_PATH_SUBTYPE;\r
276 TempDevicePath = NextDevicePathNode (TempDevicePath);\r
277 CopyMem (TempDevicePath, DevicePathInstance, InstanceSize);\r
878ddf1f 278 }\r
279\r
280 return NewDevicePath;\r
281}\r
282\r
283/**\r
add13dc2 284 Creates a copy of the current device path instance and returns a pointer to the next device path\r
285 instance.\r
286\r
287 This function creates a copy of the current device path instance. It also updates DevicePath to\r
288 point to the next device path instance in the device path (or NULL if no more) and updates Size\r
289 to hold the size of the device path instance copy.\r
290 If DevicePath is NULL, then NULL is returned.\r
291 If there is not enough memory to allocate space for the new device path, then NULL is returned. \r
292 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to\r
293 free the memory allocated.\r
294 If Size is NULL, then ASSERT().\r
295 \r
296 @param DevicePath On input, this holds the pointer to the current device path\r
297 instance. On output, this holds the pointer to the next device\r
298 path instance or NULL if there are no more device path\r
299 instances in the device path pointer to a device path data\r
300 structure.\r
301 @param Size On output, this holds the size of the device path instance, in\r
302 bytes or zero, if DevicePath is NULL.\r
878ddf1f 303\r
add13dc2 304 @return A pointer to the current device path instance.\r
878ddf1f 305\r
306**/\r
307EFI_DEVICE_PATH_PROTOCOL *\r
308EFIAPI\r
309GetNextDevicePathInstance (\r
add13dc2 310 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,\r
311 OUT UINTN *Size\r
878ddf1f 312 )\r
313{\r
314 EFI_DEVICE_PATH_PROTOCOL *DevPath;\r
315 EFI_DEVICE_PATH_PROTOCOL *ReturnValue;\r
316 UINT8 Temp;\r
317\r
878ddf1f 318 ASSERT (Size != NULL);\r
add13dc2 319\r
320 if (DevicePath == NULL || *DevicePath == NULL) {\r
878ddf1f 321 *Size = 0;\r
322 return NULL;\r
323 }\r
324\r
325 //\r
326 // Find the end of the device path instance\r
327 //\r
328 DevPath = *DevicePath;\r
329 while (!IsDevicePathEndType (DevPath)) {\r
330 DevPath = NextDevicePathNode (DevPath);\r
331 }\r
332\r
333 //\r
334 // Compute the size of the device path instance\r
335 //\r
336 *Size = ((UINTN) DevPath - (UINTN) (*DevicePath)) + sizeof (EFI_DEVICE_PATH_PROTOCOL);\r
337 \r
338 //\r
339 // Make a copy and return the device path instance\r
340 //\r
341 Temp = DevPath->SubType;\r
342 DevPath->SubType = END_ENTIRE_DEVICE_PATH_SUBTYPE;\r
343 ReturnValue = DuplicateDevicePath (*DevicePath);\r
344 DevPath->SubType = Temp;\r
345\r
346 //\r
347 // If DevPath is the end of an entire device path, then another instance\r
348 // does not follow, so *DevicePath is set to NULL.\r
349 //\r
350 if (DevicePathSubType (DevPath) == END_ENTIRE_DEVICE_PATH_SUBTYPE) {\r
351 *DevicePath = NULL;\r
352 } else {\r
353 *DevicePath = NextDevicePathNode (DevPath);\r
354 }\r
355\r
356 return ReturnValue;\r
357}\r
358\r
359/**\r
add13dc2 360 Creates a copy of the current device path instance and returns a pointer to the next device path\r
361 instance.\r
362\r
363 This function creates a new device node in a newly allocated buffer of size NodeLength and\r
364 initializes the device path node header with NodeType and NodeSubType. The new device path node\r
365 is returned.\r
366 If NodeLength is smaller than a device path header, then NULL is returned. \r
367 If there is not enough memory to allocate space for the new device path, then NULL is returned. \r
368 The memory is allocated from EFI boot services memory. It is the responsibility of the caller to\r
369 free the memory allocated.\r
370\r
371 @param NodeType The device node type for the new device node.\r
372 @param NodeSubType The device node sub-type for the new device node.\r
373 @param NodeLength The length of the new device node.\r
374\r
375 @return The new device path.\r
376\r
377**/\r
378EFI_DEVICE_PATH_PROTOCOL *\r
379EFIAPI\r
380CreateDeviceNode (\r
381 IN UINT8 NodeType,\r
382 IN UINT8 NodeSubType,\r
383 IN UINT16 NodeLength\r
384 )\r
385{\r
386 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
387\r
388 if (NodeLength < sizeof (EFI_DEVICE_PATH_PROTOCOL)) {\r
389 //\r
390 // NodeLength is less than the size of the header.\r
391 //\r
392 return NULL;\r
393 }\r
394 \r
395 DevicePath = AllocatePool (NodeLength);\r
396 if (DevicePath != NULL) {\r
397 DevicePath->Type = NodeType;\r
398 DevicePath->SubType = NodeSubType;\r
c4898a01 399 SetDevicePathNodeLength (DevicePath, NodeLength);\r
add13dc2 400 }\r
401\r
402 return DevicePath;\r
403}\r
404\r
405/**\r
406 Determines if a device path is single or multi-instance.\r
407\r
408 This function returns TRUE if the device path specified by DevicePath is multi-instance.\r
409 Otherwise, FALSE is returned. If DevicePath is NULL, then FALSE is returned.\r
878ddf1f 410\r
add13dc2 411 @param DevicePath A pointer to a device path data structure.\r
878ddf1f 412\r
add13dc2 413 @retval TRUE DevicePath is multi-instance.\r
414 @retval FALSE DevicePath is not multi-instance or DevicePath is NULL.\r
878ddf1f 415\r
416**/\r
417BOOLEAN\r
418EFIAPI\r
419IsDevicePathMultiInstance (\r
420 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
421 )\r
422{\r
add13dc2 423 CONST EFI_DEVICE_PATH_PROTOCOL *Node;\r
878ddf1f 424\r
425 if (DevicePath == NULL) {\r
426 return FALSE;\r
427 }\r
428\r
429 Node = DevicePath;\r
430 while (!EfiIsDevicePathEnd (Node)) {\r
431 if (EfiIsDevicePathEndInstance (Node)) {\r
432 return TRUE;\r
433 }\r
434\r
435 Node = EfiNextDevicePathNode (Node);\r
436 }\r
437\r
438 return FALSE;\r
439}\r
440\r
add13dc2 441\r
878ddf1f 442/**\r
add13dc2 443 Retrieves the device path protocol from a handle.\r
878ddf1f 444\r
add13dc2 445 This function returns the device path protocol from the handle specified by Handle. If Handle is\r
446 NULL or Handle does not contain a device path protocol, then NULL is returned.\r
447 \r
448 @param Handle The handle from which to retrieve the device path protocol.\r
878ddf1f 449\r
add13dc2 450 @return The device path protocol from the handle specified by Handle.\r
878ddf1f 451\r
452**/\r
453EFI_DEVICE_PATH_PROTOCOL *\r
454EFIAPI\r
455DevicePathFromHandle (\r
add13dc2 456 IN EFI_HANDLE Handle\r
878ddf1f 457 )\r
458{\r
459 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
460 EFI_STATUS Status;\r
461\r
462 Status = gBS->HandleProtocol (\r
463 Handle,\r
464 &gEfiDevicePathProtocolGuid,\r
465 (VOID *) &DevicePath\r
466 );\r
467 if (EFI_ERROR (Status)) {\r
468 DevicePath = NULL;\r
469 }\r
470 return DevicePath;\r
471}\r
472\r
473/**\r
add13dc2 474 Allocates a device path for a file and appends it to an existing device path.\r
878ddf1f 475\r
add13dc2 476 If Device is a valid device handle that contains a device path protocol, then a device path for\r
477 the file specified by FileName is allocated and appended to the device path associated with the\r
478 handle Device. The allocated device path is returned. If Device is NULL or Device is a handle\r
479 that does not support the device path protocol, then a device path containing a single device\r
480 path node for the file specified by FileName is allocated and returned.\r
481 If FileName is NULL, then ASSERT().\r
878ddf1f 482\r
add13dc2 483 @param Device A pointer to a device handle. This parameter is optional and\r
484 may be NULL.\r
485 @param FileName A pointer to a Null-terminated Unicode string.\r
486\r
487 @return The allocated device path.\r
878ddf1f 488\r
489**/\r
490EFI_DEVICE_PATH_PROTOCOL *\r
491EFIAPI\r
492FileDevicePath (\r
add13dc2 493 IN EFI_HANDLE Device, OPTIONAL\r
494 IN CONST CHAR16 *FileName\r
878ddf1f 495 )\r
496{\r
add13dc2 497 UINTN Size;\r
498 FILEPATH_DEVICE_PATH *FilePath;\r
878ddf1f 499 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
28c73f6e 500 EFI_DEVICE_PATH_PROTOCOL *FileDevicePath;\r
add13dc2 501\r
502 DevicePath = NULL;\r
503\r
504 Size = StrSize (FileName);\r
28c73f6e 505 FileDevicePath = AllocatePool (Size + SIZE_OF_FILEPATH_DEVICE_PATH + EFI_END_DEVICE_PATH_LENGTH);\r
506 if (FileDevicePath != NULL) {\r
507 FilePath = (FILEPATH_DEVICE_PATH *) FileDevicePath;\r
508 FilePath->Header.Type = MEDIA_DEVICE_PATH;\r
509 FilePath->Header.SubType = MEDIA_FILEPATH_DP;\r
add13dc2 510 CopyMem (&FilePath->PathName, FileName, Size);\r
28c73f6e 511 SetDevicePathNodeLength (&FilePath->Header, Size + SIZE_OF_FILEPATH_DEVICE_PATH);\r
512 SetDevicePathEndNode (NextDevicePathNode (&FilePath->Header));\r
513\r
878ddf1f 514 if (Device != NULL) {\r
515 DevicePath = DevicePathFromHandle (Device);\r
516 }\r
28c73f6e 517\r
518 DevicePath = AppendDevicePath (DevicePath, FileDevicePath);\r
519 FreePool (FileDevicePath);\r
878ddf1f 520 }\r
add13dc2 521\r
878ddf1f 522 return DevicePath;\r
523}\r
524\r