MdePkg UefiDevicePathLib: Validate before touch input buffer.
[mirror_edk2.git] / MdePkg / Library / UefiDevicePathLib / UefiDevicePathLibOptionalDevicePathProtocol.c
CommitLineData
4d0a30a4
RN
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) 2013, Intel Corporation. All rights reserved.<BR>\r
12 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**/\r
21\r
22\r
23#include "UefiDevicePathLib.h"\r
24\r
25GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_UTILITIES_PROTOCOL *mDevicePathLibDevicePathUtilities = NULL;\r
26GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_TO_TEXT_PROTOCOL *mDevicePathLibDevicePathToText = NULL;\r
27GLOBAL_REMOVE_IF_UNREFERENCED EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL *mDevicePathLibDevicePathFromText = NULL;\r
28\r
29/**\r
30 The constructor function caches the pointer to DevicePathUtilites protocol,\r
31 DevicePathToText protocol and DevicePathFromText protocol.\r
32 \r
33 The constructor function locates these three protocols from protocol database.\r
34 It will caches the pointer to local protocol instance if that operation fails\r
35 and it will always return EFI_SUCCESS. \r
36\r
37 @param ImageHandle The firmware allocated handle for the EFI image.\r
38 @param SystemTable A pointer to the EFI System Table.\r
39 \r
40 @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.\r
41\r
42**/\r
43EFI_STATUS\r
44EFIAPI\r
45UefiDevicePathLibOptionalDevicePathProtocolConstructor (\r
46 IN EFI_HANDLE ImageHandle,\r
47 IN EFI_SYSTEM_TABLE *SystemTable\r
48 )\r
49{\r
50 EFI_STATUS Status;\r
51\r
52 Status = gBS->LocateProtocol (\r
53 &gEfiDevicePathUtilitiesProtocolGuid,\r
54 NULL,\r
55 (VOID**) &mDevicePathLibDevicePathUtilities\r
56 );\r
57 ASSERT_EFI_ERROR (Status);\r
58 ASSERT (mDevicePathLibDevicePathUtilities != NULL);\r
59 return Status;\r
60}\r
61\r
62/**\r
63 Returns the size of a device path in bytes.\r
64\r
65 This function returns the size, in bytes, of the device path data structure \r
66 specified by DevicePath including the end of device path node.\r
67 If DevicePath is NULL or invalid, then 0 is returned.\r
68\r
69 @param DevicePath A pointer to a device path data structure.\r
70\r
71 @retval 0 If DevicePath is NULL or invalid.\r
72 @retval Others The size of a device path in bytes.\r
73\r
74**/\r
75UINTN\r
76EFIAPI\r
77GetDevicePathSize (\r
78 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
79 )\r
80{\r
81 if (mDevicePathLibDevicePathUtilities != NULL) {\r
82 return mDevicePathLibDevicePathUtilities->GetDevicePathSize (DevicePath);\r
83 } else {\r
84 return UefiDevicePathLibGetDevicePathSize (DevicePath);\r
85 }\r
86}\r
87\r
88/**\r
89 Creates a new copy of an existing device path.\r
90\r
91 This function allocates space for a new copy of the device path specified by DevicePath. \r
92 If DevicePath is NULL, then NULL is returned. If the memory is successfully \r
93 allocated, then the contents of DevicePath are copied to the newly allocated \r
94 buffer, and a pointer to that buffer is returned. Otherwise, NULL is returned. \r
95 The memory for the new device path is allocated from EFI boot services memory. \r
96 It is the responsibility of the caller to free the memory allocated. \r
97 \r
98 @param DevicePath A pointer to a device path data structure.\r
99\r
100 @retval NULL DevicePath is NULL or invalid.\r
101 @retval Others A pointer to the duplicated device path.\r
102 \r
103**/\r
104EFI_DEVICE_PATH_PROTOCOL *\r
105EFIAPI\r
106DuplicateDevicePath (\r
107 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
108 )\r
109{\r
110 if (mDevicePathLibDevicePathUtilities != NULL) {\r
111 return mDevicePathLibDevicePathUtilities->DuplicateDevicePath (DevicePath);\r
112 } else {\r
113 return UefiDevicePathLibDuplicateDevicePath (DevicePath);\r
114 }\r
115}\r
116\r
117/**\r
118 Creates a new device path by appending a second device path to a first device path.\r
119\r
120 This function creates a new device path by appending a copy of SecondDevicePath \r
121 to a copy of FirstDevicePath in a newly allocated buffer. Only the end-of-device-path \r
122 device node from SecondDevicePath is retained. The newly created device path is \r
123 returned. If FirstDevicePath is NULL, then it is ignored, and a duplicate of \r
124 SecondDevicePath is returned. If SecondDevicePath is NULL, then it is ignored, \r
125 and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and \r
126 SecondDevicePath are NULL, then a copy of an end-of-device-path is returned. \r
127 \r
128 If there is not enough memory for the newly allocated buffer, then NULL is returned.\r
129 The memory for the new device path is allocated from EFI boot services memory. \r
130 It is the responsibility of the caller to free the memory allocated.\r
131\r
132 @param FirstDevicePath A pointer to a device path data structure.\r
133 @param SecondDevicePath A pointer to a device path data structure.\r
134 \r
135 @retval NULL If there is not enough memory for the newly allocated buffer.\r
136 @retval NULL If FirstDevicePath or SecondDevicePath is invalid.\r
137 @retval Others A pointer to the new device path if success.\r
138 Or a copy an end-of-device-path if both FirstDevicePath and SecondDevicePath are NULL.\r
139\r
140**/\r
141EFI_DEVICE_PATH_PROTOCOL *\r
142EFIAPI\r
143AppendDevicePath (\r
144 IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath, OPTIONAL\r
145 IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath OPTIONAL\r
146 )\r
147{\r
148 if (mDevicePathLibDevicePathUtilities != NULL) {\r
149 return mDevicePathLibDevicePathUtilities->AppendDevicePath (FirstDevicePath, SecondDevicePath);\r
150 } else {\r
151 return UefiDevicePathLibAppendDevicePath (FirstDevicePath, SecondDevicePath);\r
152 }\r
153}\r
154\r
155/**\r
156 Creates a new path by appending the device node to the device path.\r
157\r
158 This function creates a new device path by appending a copy of the device node \r
159 specified by DevicePathNode to a copy of the device path specified by DevicePath \r
160 in an allocated buffer. The end-of-device-path device node is moved after the \r
161 end of the appended device node.\r
162 If DevicePathNode is NULL then a copy of DevicePath is returned.\r
163 If DevicePath is NULL then a copy of DevicePathNode, followed by an end-of-device \r
164 path device node is returned.\r
165 If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path \r
166 device node is returned.\r
167 If there is not enough memory to allocate space for the new device path, then \r
168 NULL is returned. \r
169 The memory is allocated from EFI boot services memory. It is the responsibility \r
170 of the caller to free the memory allocated.\r
171\r
172 @param DevicePath A pointer to a device path data structure.\r
173 @param DevicePathNode A pointer to a single device path node.\r
174\r
175 @retval NULL If there is not enough memory for the new device path.\r
176 @retval Others A pointer to the new device path if success.\r
177 A copy of DevicePathNode followed by an end-of-device-path node \r
178 if both FirstDevicePath and SecondDevicePath are NULL.\r
179 A copy of an end-of-device-path node if both FirstDevicePath \r
180 and SecondDevicePath are NULL.\r
181\r
182**/\r
183EFI_DEVICE_PATH_PROTOCOL *\r
184EFIAPI\r
185AppendDevicePathNode (\r
186 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
187 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode OPTIONAL\r
188 )\r
189{\r
190 if (mDevicePathLibDevicePathUtilities != NULL) {\r
191 return mDevicePathLibDevicePathUtilities->AppendDeviceNode (DevicePath, DevicePathNode);\r
192 } else {\r
193 return UefiDevicePathLibAppendDevicePathNode (DevicePath, DevicePathNode);\r
194 }\r
195}\r
196\r
197/**\r
198 Creates a new device path by appending the specified device path instance to the specified device\r
199 path.\r
200 \r
201 This function creates a new device path by appending a copy of the device path \r
202 instance specified by DevicePathInstance to a copy of the device path specified \r
203 by DevicePath in a allocated buffer.\r
204 The end-of-device-path device node is moved after the end of the appended device \r
205 path instance and a new end-of-device-path-instance node is inserted between. \r
206 If DevicePath is NULL, then a copy if DevicePathInstance is returned.\r
207 If DevicePathInstance is NULL, then NULL is returned.\r
208 If DevicePath or DevicePathInstance is invalid, then NULL is returned.\r
209 If there is not enough memory to allocate space for the new device path, then \r
210 NULL is returned. \r
211 The memory is allocated from EFI boot services memory. It is the responsibility \r
212 of the caller to free the memory allocated.\r
213 \r
214 @param DevicePath A pointer to a device path data structure.\r
215 @param DevicePathInstance A pointer to a device path instance.\r
216\r
217 @return A pointer to the new device path.\r
218\r
219**/\r
220EFI_DEVICE_PATH_PROTOCOL *\r
221EFIAPI\r
222AppendDevicePathInstance (\r
223 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, OPTIONAL\r
224 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathInstance OPTIONAL\r
225 )\r
226{\r
227 if (mDevicePathLibDevicePathUtilities != NULL) {\r
228 return mDevicePathLibDevicePathUtilities->AppendDevicePathInstance (DevicePath, DevicePathInstance);\r
229 } else {\r
230 return UefiDevicePathLibAppendDevicePathInstance (DevicePath, DevicePathInstance);\r
231 }\r
232}\r
233\r
234/**\r
235 Creates a copy of the current device path instance and returns a pointer to the next device path\r
236 instance.\r
237\r
238 This function creates a copy of the current device path instance. It also updates \r
239 DevicePath to point to the next device path instance in the device path (or NULL \r
240 if no more) and updates Size to hold the size of the device path instance copy.\r
241 If DevicePath is NULL, then NULL is returned.\r
242 If DevicePath points to a invalid device path, then NULL is returned.\r
243 If there is not enough memory to allocate space for the new device path, then \r
244 NULL is returned. \r
245 The memory is allocated from EFI boot services memory. It is the responsibility \r
246 of the caller to free the memory allocated.\r
247 If Size is NULL, then ASSERT().\r
248 \r
249 @param DevicePath On input, this holds the pointer to the current \r
250 device path instance. On output, this holds \r
251 the pointer to the next device path instance \r
252 or NULL if there are no more device path\r
253 instances in the device path pointer to a \r
254 device path data structure.\r
255 @param Size On output, this holds the size of the device \r
256 path instance, in bytes or zero, if DevicePath \r
257 is NULL.\r
258\r
259 @return A pointer to the current device path instance.\r
260\r
261**/\r
262EFI_DEVICE_PATH_PROTOCOL *\r
263EFIAPI\r
264GetNextDevicePathInstance (\r
265 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,\r
266 OUT UINTN *Size\r
267 )\r
268{\r
269 if (mDevicePathLibDevicePathUtilities != NULL) {\r
270 return mDevicePathLibDevicePathUtilities->GetNextDevicePathInstance (DevicePath, Size);\r
271 } else {\r
272 return UefiDevicePathLibGetNextDevicePathInstance (DevicePath, Size);\r
273 }\r
274}\r
275\r
276/**\r
277 Creates a device node.\r
278\r
279 This function creates a new device node in a newly allocated buffer of size \r
280 NodeLength and initializes the device path node header with NodeType and NodeSubType. \r
281 The new device path node is returned.\r
282 If NodeLength is smaller than a device path header, then NULL is returned. \r
283 If there is not enough memory to allocate space for the new device path, then \r
284 NULL is returned. \r
285 The memory is allocated from EFI boot services memory. It is the responsibility \r
286 of the caller to free the memory allocated.\r
287\r
288 @param NodeType The device node type for the new device node.\r
289 @param NodeSubType The device node sub-type for the new device node.\r
290 @param NodeLength The length of the new device node.\r
291\r
292 @return The new device path.\r
293\r
294**/\r
295EFI_DEVICE_PATH_PROTOCOL *\r
296EFIAPI\r
297CreateDeviceNode (\r
298 IN UINT8 NodeType,\r
299 IN UINT8 NodeSubType,\r
300 IN UINT16 NodeLength\r
301 )\r
302{\r
303 if (mDevicePathLibDevicePathUtilities != NULL) {\r
304 return mDevicePathLibDevicePathUtilities->CreateDeviceNode (NodeType, NodeSubType, NodeLength);\r
305 } else {\r
306 return UefiDevicePathLibCreateDeviceNode (NodeType, NodeSubType, NodeLength);\r
307 }\r
308}\r
309\r
310/**\r
311 Determines if a device path is single or multi-instance.\r
312\r
313 This function returns TRUE if the device path specified by DevicePath is\r
314 multi-instance.\r
315 Otherwise, FALSE is returned.\r
316 If DevicePath is NULL or invalid, then FALSE is returned.\r
317\r
318 @param DevicePath A pointer to a device path data structure.\r
319\r
320 @retval TRUE DevicePath is multi-instance.\r
321 @retval FALSE DevicePath is not multi-instance, or DevicePath \r
322 is NULL or invalid.\r
323\r
324**/\r
325BOOLEAN\r
326EFIAPI\r
327IsDevicePathMultiInstance (\r
328 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath\r
329 )\r
330{\r
331 if (mDevicePathLibDevicePathUtilities != NULL) {\r
332 return mDevicePathLibDevicePathUtilities->IsDevicePathMultiInstance (DevicePath);\r
333 } else {\r
334 return UefiDevicePathLibIsDevicePathMultiInstance (DevicePath);\r
335 }\r
336}\r
337\r
338/**\r
339 Locate and return the protocol instance identified by the ProtocolGuid.\r
340\r
341 @param ProtocolGuid The GUID of the protocol.\r
342\r
343 @return A pointer to the protocol instance or NULL when absent.\r
344**/\r
345VOID *\r
346UefiDevicePathLibLocateProtocol (\r
347 EFI_GUID *ProtocolGuid\r
348 )\r
349{\r
350 EFI_STATUS Status;\r
351 VOID *Protocol;\r
352 Status = gBS->LocateProtocol (\r
353 ProtocolGuid,\r
354 NULL,\r
355 (VOID**) &Protocol\r
356 );\r
357 if (EFI_ERROR (Status)) {\r
358 return NULL;\r
359 } else {\r
360 return Protocol;\r
361 }\r
362}\r
363\r
364/**\r
365 Converts a device node to its string representation.\r
366\r
367 @param DeviceNode A Pointer to the device node to be converted.\r
368 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation\r
369 of the display node is used, where applicable. If DisplayOnly\r
370 is FALSE, then the longer text representation of the display node\r
371 is used.\r
372 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text\r
373 representation for a device node can be used, where applicable.\r
374\r
375 @return A pointer to the allocated text representation of the device node or NULL if DeviceNode\r
376 is NULL or there was insufficient memory.\r
377\r
378**/\r
379CHAR16 *\r
380EFIAPI\r
381ConvertDeviceNodeToText (\r
382 IN CONST EFI_DEVICE_PATH_PROTOCOL *DeviceNode,\r
383 IN BOOLEAN DisplayOnly,\r
384 IN BOOLEAN AllowShortcuts\r
385 )\r
386{\r
387 if (mDevicePathLibDevicePathToText == NULL) {\r
388 mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);\r
389 }\r
390 if (mDevicePathLibDevicePathToText != NULL) {\r
391 return mDevicePathLibDevicePathToText->ConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);\r
392 }\r
393\r
394 return UefiDevicePathLibConvertDeviceNodeToText (DeviceNode, DisplayOnly, AllowShortcuts);\r
395}\r
396\r
397/**\r
398 Converts a device path to its text representation.\r
399\r
400 @param DevicePath A Pointer to the device to be converted.\r
401 @param DisplayOnly If DisplayOnly is TRUE, then the shorter text representation\r
402 of the display node is used, where applicable. If DisplayOnly\r
403 is FALSE, then the longer text representation of the display node\r
404 is used.\r
405 @param AllowShortcuts If AllowShortcuts is TRUE, then the shortcut forms of text\r
406 representation for a device node can be used, where applicable.\r
407\r
408 @return A pointer to the allocated text representation of the device path or\r
409 NULL if DeviceNode is NULL or there was insufficient memory.\r
410\r
411**/\r
412CHAR16 *\r
413EFIAPI\r
414ConvertDevicePathToText (\r
415 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,\r
416 IN BOOLEAN DisplayOnly,\r
417 IN BOOLEAN AllowShortcuts\r
418 )\r
419{\r
420 if (mDevicePathLibDevicePathToText == NULL) {\r
421 mDevicePathLibDevicePathToText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathToTextProtocolGuid);\r
422 }\r
423 if (mDevicePathLibDevicePathToText != NULL) {\r
424 return mDevicePathLibDevicePathToText->ConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);\r
425 }\r
426\r
427 return UefiDevicePathLibConvertDevicePathToText (DevicePath, DisplayOnly, AllowShortcuts);\r
428}\r
429\r
430/**\r
431 Convert text to the binary representation of a device node.\r
432\r
433 @param TextDeviceNode TextDeviceNode points to the text representation of a device\r
434 node. Conversion starts with the first character and continues\r
435 until the first non-device node character.\r
436\r
437 @return A pointer to the EFI device node or NULL if TextDeviceNode is NULL or there was\r
438 insufficient memory or text unsupported.\r
439\r
440**/\r
441EFI_DEVICE_PATH_PROTOCOL *\r
442EFIAPI\r
443ConvertTextToDeviceNode (\r
444 IN CONST CHAR16 *TextDeviceNode\r
445 )\r
446{\r
447 if (mDevicePathLibDevicePathFromText == NULL) {\r
448 mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);\r
449 }\r
450 if (mDevicePathLibDevicePathFromText != NULL) {\r
451 return mDevicePathLibDevicePathFromText->ConvertTextToDeviceNode (TextDeviceNode);\r
452 }\r
453\r
454 return UefiDevicePathLibConvertTextToDeviceNode (TextDeviceNode);\r
455}\r
456\r
457/**\r
458 Convert text to the binary representation of a device path.\r
459\r
460\r
461 @param TextDevicePath TextDevicePath points to the text representation of a device\r
462 path. Conversion starts with the first character and continues\r
463 until the first non-device node character.\r
464\r
465 @return A pointer to the allocated device path or NULL if TextDeviceNode is NULL or\r
466 there was insufficient memory.\r
467\r
468**/\r
469EFI_DEVICE_PATH_PROTOCOL *\r
470EFIAPI\r
471ConvertTextToDevicePath (\r
472 IN CONST CHAR16 *TextDevicePath\r
473 )\r
474{\r
475 if (mDevicePathLibDevicePathFromText == NULL) {\r
476 mDevicePathLibDevicePathFromText = UefiDevicePathLibLocateProtocol (&gEfiDevicePathFromTextProtocolGuid);\r
477 }\r
478 if (mDevicePathLibDevicePathFromText != NULL) {\r
479 return mDevicePathLibDevicePathFromText->ConvertTextToDevicePath (TextDevicePath);\r
480 }\r
481\r
482 return UefiDevicePathLibConvertTextToDevicePath (TextDevicePath);\r
483}\r
484\r