2 UEFI Device Path Library.
4 Copyright (c) 2006, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 Module Name: UefiDevicePathLib.c
17 STATIC EFI_DEVICE_PATH_UTILITIES_PROTOCOL
*mDevicePathUtilities
= NULL
;
20 The constructor function caches the pointer to DevicePathUtilites protocol.
22 The constructor function locates DevicePathUtilities protocol from protocol database.
23 It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
25 @param ImageHandle The firmware allocated handle for the EFI image.
26 @param SystemTable A pointer to the EFI System Table.
28 @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.
33 DevicePathLibConstructor (
34 IN EFI_HANDLE ImageHandle
,
35 IN EFI_SYSTEM_TABLE
*SystemTable
40 Status
= gBS
->LocateProtocol (
41 &gEfiDevicePathUtilitiesProtocolGuid
,
43 (VOID
**) &mDevicePathUtilities
45 ASSERT_EFI_ERROR (Status
);
46 ASSERT (mDevicePathUtilities
!= NULL
);
52 This function returns the size, in bytes,
53 of the device path data structure specified by DevicePath.
54 If DevicePath is NULL, then 0 is returned.
56 @param DevicePath A pointer to a device path data structure.
58 @return The size of a device path in bytes.
64 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
67 return mDevicePathUtilities
->GetDevicePathSize (DevicePath
);
71 This function allocates space for a new copy of the device path
72 specified by DevicePath.
74 @param DevicePath A pointer to a device path data structure.
76 @return The duplicated device path.
79 EFI_DEVICE_PATH_PROTOCOL
*
82 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
85 return mDevicePathUtilities
->DuplicateDevicePath (DevicePath
);
89 This function appends the device path SecondDevicePath
90 to every device path instance in FirstDevicePath.
92 @param FirstDevicePath A pointer to a device path data structure.
94 @param SecondDevicePath A pointer to a device path data structure.
96 @return A pointer to the new device path is returned.
97 NULL is returned if space for the new device path could not be allocated from pool.
98 It is up to the caller to free the memory used by FirstDevicePath and SecondDevicePath
99 if they are no longer needed.
102 EFI_DEVICE_PATH_PROTOCOL
*
105 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FirstDevicePath
,
106 IN CONST EFI_DEVICE_PATH_PROTOCOL
*SecondDevicePath
109 return mDevicePathUtilities
->AppendDevicePath (FirstDevicePath
, SecondDevicePath
);
113 This function appends the device path node SecondDevicePath
114 to every device path instance in FirstDevicePath.
116 @param FirstDevicePath A pointer to a device path data structure.
118 @param SecondDevicePath A pointer to a single device path node.
120 @return A pointer to the new device path.
121 If there is not enough temporary pool memory available to complete this function,
122 then NULL is returned.
125 EFI_DEVICE_PATH_PROTOCOL
*
127 AppendDevicePathNode (
128 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FirstDevicePath
,
129 IN CONST EFI_DEVICE_PATH_PROTOCOL
*SecondDevicePath
132 return mDevicePathUtilities
->AppendDeviceNode (FirstDevicePath
, SecondDevicePath
);
136 This function appends the device path instance Instance to the device path Source.
137 If Source is NULL, then a new device path with one instance is created.
139 @param Source A pointer to a device path data structure.
140 @param Instance A pointer to a device path instance.
142 @return A pointer to the new device path.
143 If there is not enough temporary pool memory available to complete this function,
144 then NULL is returned.
147 EFI_DEVICE_PATH_PROTOCOL
*
149 AppendDevicePathInstance (
150 IN CONST EFI_DEVICE_PATH_PROTOCOL
*Source
,
151 IN CONST EFI_DEVICE_PATH_PROTOCOL
*Instance
154 return mDevicePathUtilities
->AppendDevicePathInstance (Source
, Instance
);
158 Function retrieves the next device path instance from a device path data structure.
160 @param DevicePath A pointer to a device path data structure.
162 @param Size A pointer to the size of a device path instance in bytes.
164 @return This function returns a pointer to the current device path instance.
165 In addition, it returns the size in bytes of the current device path instance in Size,
166 and a pointer to the next device path instance in DevicePath.
167 If there are no more device path instances in DevicePath, then DevicePath will be set to NULL.
170 EFI_DEVICE_PATH_PROTOCOL
*
172 GetNextDevicePathInstance (
173 IN OUT EFI_DEVICE_PATH_PROTOCOL
**DevicePath
,
177 ASSERT (DevicePath
!= NULL
);
178 ASSERT (Size
!= NULL
);
179 return mDevicePathUtilities
->GetNextDevicePathInstance (DevicePath
, Size
);
183 Return TRUE is this is a multi instance device path.
185 @param DevicePath A pointer to a device path data structure.
187 @retval TRUE If DevicePath is multi-instance.
188 @retval FALSE If DevicePath is not multi-instance or DevicePath is NULL.
193 IsDevicePathMultiInstance (
194 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
197 return mDevicePathUtilities
->IsDevicePathMultiInstance (DevicePath
);
201 This function retrieves the device path protocol from a handle.
203 @param Handle The handle from which to retrieve the device path protocol.
205 @return This function returns the device path protocol from the handle specified by Handle.
206 If Handle is NULL or Handle does not contain a device path protocol, then NULL is returned.
209 EFI_DEVICE_PATH_PROTOCOL
*
211 DevicePathFromHandle (
215 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
218 Status
= gBS
->HandleProtocol (
220 &gEfiDevicePathProtocolGuid
,
223 if (EFI_ERROR (Status
)) {
230 This function allocates a device path for a file and appends it to an existing device path.
232 @param Device A pointer to a device handle. This parameter is optional and may be NULL.
233 @param FileName A pointer to a Null-terminated Unicode string.
235 @return If Device is a valid device handle that contains a device path protocol,
236 then a device path for the file specified by FileName is allocated
237 and appended to the device path associated with the handle Device. The allocated device path is returned.
238 If Device is NULL or Device is a handle that does not support the device path protocol,
239 then a device path containing a single device path node for the file specified by FileName
240 is allocated and returned.
243 EFI_DEVICE_PATH_PROTOCOL
*
246 IN EFI_HANDLE Device
, OPTIONAL
247 IN CONST CHAR16
*FileName
251 FILEPATH_DEVICE_PATH
*FilePath
;
252 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
253 EFI_DEVICE_PATH_PROTOCOL
*FileDevicePathNode
;
257 Size
= StrSize (FileName
);
258 FileDevicePathNode
= mDevicePathUtilities
->CreateDeviceNode (
261 (UINT16
) (Size
+ SIZE_OF_FILEPATH_DEVICE_PATH
)
263 if (FileDevicePathNode
!= NULL
) {
264 FilePath
= (FILEPATH_DEVICE_PATH
*) FileDevicePathNode
;
265 CopyMem (&FilePath
->PathName
, FileName
, Size
);
266 if (Device
!= NULL
) {
267 DevicePath
= DevicePathFromHandle (Device
);
269 DevicePath
= AppendDevicePathNode (DevicePath
, FileDevicePathNode
);
270 FreePool (FileDevicePathNode
);