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