FmpDevicePkg: Add DSC file to build all package components
[mirror_edk2.git] / FmpDevicePkg / Library / FmpDeviceLibNull / FmpDeviceLib.c
CommitLineData
403d4bcd
KM
1/** @file\r
2 Provides firmware device specific services to support updates of a firmware\r
3 image stored in a firmware device.\r
4\r
5 Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
6 Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>\r
7\r
8 Redistribution and use in source and binary forms, with or without\r
9 modification, are permitted provided that the following conditions are met:\r
10 1. Redistributions of source code must retain the above copyright notice,\r
11 this list of conditions and the following disclaimer.\r
12 2. Redistributions in binary form must reproduce the above copyright notice,\r
13 this list of conditions and the following disclaimer in the documentation\r
14 and/or other materials provided with the distribution.\r
15\r
16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND\r
17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\r
18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\r
19 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,\r
20 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,\r
21 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
22 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
23 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE\r
24 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF\r
25 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
26\r
27**/\r
28\r
29#include <PiDxe.h>\r
30#include <Library/FmpDeviceLib.h>\r
31\r
32/**\r
33 Provide a function to install the Firmware Management Protocol instance onto a\r
34 device handle when the device is managed by a driver that follows the UEFI\r
35 Driver Model. If the device is not managed by a driver that follows the UEFI\r
36 Driver Model, then EFI_UNSUPPORTED is returned.\r
37\r
38 @param[in] FmpInstaller Function that installs the Firmware Management\r
39 Protocol.\r
40\r
41 @retval EFI_SUCCESS The device is managed by a driver that follows the\r
42 UEFI Driver Model. FmpInstaller must be called on\r
43 each Driver Binding Start().\r
44 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
45 the UEFI Driver Model.\r
46 @retval other The Firmware Management Protocol for this firmware\r
47 device is not installed. The firmware device is\r
48 still locked using FmpDeviceLock().\r
49\r
50**/\r
51EFI_STATUS\r
52EFIAPI\r
53RegisterFmpInstaller (\r
54 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Function\r
55 )\r
56{\r
57 return EFI_UNSUPPORTED;\r
58}\r
59\r
60/**\r
61 Returns the size, in bytes, of the firmware image currently stored in the\r
62 firmware device. This function is used to by the GetImage() and\r
63 GetImageInfo() services of the Firmware Management Protocol. If the image\r
64 size can not be determined from the firmware device, then 0 must be returned.\r
65\r
66 @param[out] Size Pointer to the size, in bytes, of the firmware image\r
67 currently stored in the firmware device.\r
68\r
69 @retval EFI_SUCCESS The size of the firmware image currently\r
70 stored in the firmware device was returned.\r
71 @retval EFI_INVALID_PARAMETER Size is NULL.\r
72 @retval EFI_UNSUPPORTED The firmware device does not support reporting\r
73 the size of the currently stored firmware image.\r
74 @retval EFI_DEVICE_ERROR An error occurred attempting to determine the\r
75 size of the firmware image currently stored in\r
76 in the firmware device.\r
77\r
78**/\r
79EFI_STATUS\r
80EFIAPI\r
81FmpDeviceGetSize (\r
82 IN UINTN *Size\r
83 )\r
84{\r
85 if (Size == NULL) {\r
86 return EFI_INVALID_PARAMETER;\r
87 }\r
88 *Size = 0;\r
89 return EFI_SUCCESS;\r
90}\r
91\r
92/**\r
93 Returns the GUID value used to fill in the ImageTypeId field of the\r
94 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
95 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,\r
96 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is\r
97 returned, then ImageTypeId is set to the Guid returned from this function.\r
98\r
99 @param[out] Guid Double pointer to a GUID value that is updated to point to\r
100 to a GUID value. The GUID value is not allocated and must\r
101 not be modified or freed by the caller.\r
102\r
103 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
104 to the returned Guid value.\r
105 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
106 to gEfiCallerIdGuid.\r
107\r
108**/\r
109EFI_STATUS\r
110EFIAPI\r
111FmpDeviceGetImageTypeIdGuidPtr (\r
112 OUT EFI_GUID **Guid\r
113 )\r
114{\r
115 return EFI_UNSUPPORTED;\r
116}\r
117\r
118/**\r
119 Returns values used to fill in the AttributesSupported and AttributesSettings\r
120 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the\r
121 GetImageInfo() service of the Firmware Management Protocol. The following\r
122 bit values from the Firmware Management Protocol may be combined:\r
123 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE\r
124 IMAGE_ATTRIBUTE_RESET_REQUIRED\r
125 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED\r
126 IMAGE_ATTRIBUTE_IN_USE\r
127 IMAGE_ATTRIBUTE_UEFI_IMAGE\r
128\r
129 @param[out] Supported Attributes supported by this firmware device.\r
130 @param[out] Setting Attributes settings for this firmware device.\r
131\r
132 @retval EFI_SUCCESS The attributes supported by the firmware\r
133 device were returned.\r
134 @retval EFI_INVALID_PARAMETER Supported is NULL.\r
135 @retval EFI_INVALID_PARAMETER Setting is NULL.\r
136\r
137**/\r
138EFI_STATUS\r
139EFIAPI\r
140FmpDeviceGetAttributes (\r
141 IN OUT UINT64 *Supported,\r
142 IN OUT UINT64 *Setting\r
143 )\r
144{\r
145 if (Supported == NULL || Setting == NULL) {\r
146 return EFI_INVALID_PARAMETER;\r
147 }\r
148 *Supported = 0;\r
149 *Setting = 0;\r
150 return EFI_SUCCESS;\r
151}\r
152\r
153/**\r
154 Returns the value used to fill in the LowestSupportedVersion field of the\r
155 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
156 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
157 the firmware device supports a method to report the LowestSupportedVersion\r
158 value from the currently stored firmware image. If the value can not be\r
159 reported for the firmware image currently stored in the firmware device, then\r
160 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error\r
161 occurs attempting to retrieve the LowestSupportedVersion value for the\r
162 currently stored firmware image.\r
163\r
164 @note It is recommended that all firmware devices support a method to report\r
165 the LowestSupportedVersion value from the currently stored firmware\r
166 image.\r
167\r
168 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved\r
169 from the currently stored firmware image.\r
170\r
171 @retval EFI_SUCCESS The lowest supported version of currently stored\r
172 firmware image was returned in LowestSupportedVersion.\r
173 @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
174 report the lowest supported version of the currently\r
175 stored firmware image.\r
176 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest\r
177 supported version of the currently stored firmware\r
178 image.\r
179\r
180**/\r
181EFI_STATUS\r
182EFIAPI\r
183FmpDeviceGetLowestSupportedVersion (\r
184 OUT UINT32 *LowestSupportedVersion\r
185 )\r
186{\r
187 return EFI_UNSUPPORTED;\r
188}\r
189\r
190/**\r
191 Returns the Null-terminated Unicode string that is used to fill in the\r
192 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is\r
193 returned by the GetImageInfo() service of the Firmware Management Protocol.\r
194 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().\r
195\r
196 @note It is recommended that all firmware devices support a method to report\r
197 the VersionName string from the currently stored firmware image.\r
198\r
199 @param[out] VersionString The version string retrieved from the currently\r
200 stored firmware image.\r
201\r
202 @retval EFI_SUCCESS The version string of currently stored\r
203 firmware image was returned in Version.\r
204 @retval EFI_INVALID_PARAMETER VersionString is NULL.\r
205 @retval EFI_UNSUPPORTED The firmware device does not support a method\r
206 to report the version string of the currently\r
207 stored firmware image.\r
208 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
209 version string of the currently stored\r
210 firmware image.\r
211 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the\r
212 buffer for the version string of the currently\r
213 stored firmware image.\r
214\r
215**/\r
216EFI_STATUS\r
217EFIAPI\r
218FmpDeviceGetVersionString (\r
219 OUT CHAR16 **VersionString\r
220 )\r
221{\r
222 if (VersionString == NULL) {\r
223 return EFI_INVALID_PARAMETER;\r
224 }\r
225 *VersionString = NULL;\r
226 return EFI_UNSUPPORTED;\r
227}\r
228\r
229/**\r
230 Returns the value used to fill in the Version field of the\r
231 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
232 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
233 the firmware device supports a method to report the Version value from the\r
234 currently stored firmware image. If the value can not be reported for the\r
235 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED\r
236 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting\r
237 to retrieve the LowestSupportedVersion value for the currently stored firmware\r
238 image.\r
239\r
240 @note It is recommended that all firmware devices support a method to report\r
241 the Version value from the currently stored firmware image.\r
242\r
243 @param[out] Version The version value retrieved from the currently stored\r
244 firmware image.\r
245\r
246 @retval EFI_SUCCESS The version of currently stored firmware image was\r
247 returned in Version.\r
248 @retval EFI_UNSUPPORTED The firmware device does not support a method to\r
249 report the version of the currently stored firmware\r
250 image.\r
251 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version\r
252 of the currently stored firmware image.\r
253\r
254**/\r
255EFI_STATUS\r
256EFIAPI\r
257FmpDeviceGetVersion (\r
258 OUT UINT32 *Version\r
259 )\r
260{\r
261 return EFI_UNSUPPORTED;\r
262}\r
263\r
264/**\r
265 Returns a copy of the firmware image currently stored in the firmware device.\r
266\r
267 @note It is recommended that all firmware devices support a method to retrieve\r
268 a copy currently stored firmware image. This can be used to support\r
269 features such as recovery and rollback.\r
270\r
271 @param[out] Image Pointer to a caller allocated buffer where the\r
272 currently stored firmware image is copied to.\r
273 @param[in out] ImageSize Pointer the size, in bytes, of the Image buffer.\r
274 On return, points to the size, in bytes, of firmware\r
275 image currently stored in the firmware device.\r
276\r
277 @retval EFI_SUCCESS Image contains a copy of the firmware image\r
278 currently stored in the firmware device, and\r
279 ImageSize contains the size, in bytes, of the\r
280 firmware image currently stored in the\r
281 firmware device.\r
282 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small\r
283 to hold the firmware image currently stored in\r
284 the firmware device. The buffer size required\r
285 is returned in ImageSize.\r
286 @retval EFI_INVALID_PARAMETER The Image is NULL.\r
287 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.\r
288 @retval EFI_UNSUPPORTED The operation is not supported.\r
289 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
290 firmware image currently stored in the firmware\r
291 device.\r
292\r
293**/\r
294EFI_STATUS\r
295EFIAPI\r
296FmpDeviceGetImage (\r
297 IN OUT VOID *Image,\r
298 IN IN OUT UINTN *ImageSize\r
299 )\r
300{\r
301 return EFI_UNSUPPORTED;\r
302}\r
303\r
304/**\r
305 Checks if a new firmware image is valid for the firmware device. This\r
306 function allows firmware update operation to validate the firmware image\r
307 before FmpDeviceSetImage() is called.\r
308\r
309 @param[in] Image Points to a new firmware image.\r
310 @param[in] ImageSize Size, in bytes, of a new firmware image.\r
311 @param[out] ImageUpdatable Indicates if a new firmware image is valid for\r
312 a firmware update to the firmware device. The\r
313 following values from the Firmware Management\r
314 Protocol are supported:\r
315 IMAGE_UPDATABLE_VALID\r
316 IMAGE_UPDATABLE_INVALID\r
317 IMAGE_UPDATABLE_INVALID_TYPE\r
318 IMAGE_UPDATABLE_INVALID_OLD\r
319 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
320\r
321 @retval EFI_SUCCESS The image was successfully checked. Additional\r
322 status information is returned in\r
323 ImageUpdateable.\r
324 @retval EFI_INVALID_PARAMETER Image is NULL.\r
325 @retval EFI_INVALID_PARAMETER ImageUpdateable is NULL.\r
326\r
327**/\r
328EFI_STATUS\r
329EFIAPI\r
330FmpDeviceCheckImage (\r
331 IN CONST VOID *Image,\r
332 IN UINTN ImageSize,\r
333 OUT UINT32 *ImageUpdateable\r
334 )\r
335{\r
336 return EFI_SUCCESS;\r
337}\r
338\r
339/**\r
340 Updates a firmware device with a new firmware image. This function returns\r
341 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
342 is updatable, the function should perform the following minimal validations\r
343 before proceeding to do the firmware image update.\r
344 - Validate that the image is a supported image for this firmware device.\r
345 Return EFI_ABORTED if the image is not supported. Additional details\r
346 on why the image is not a supported image may be returned in AbortReason.\r
347 - Validate the data from VendorCode if is not NULL. Firmware image\r
348 validation must be performed before VendorCode data validation.\r
349 VendorCode data is ignored or considered invalid if image validation\r
350 fails. Return EFI_ABORTED if the VendorCode data is invalid.\r
351\r
352 VendorCode enables vendor to implement vendor-specific firmware image update\r
353 policy. Null if the caller did not specify the policy or use the default\r
354 policy. As an example, vendor can implement a policy to allow an option to\r
355 force a firmware image update when the abort reason is due to the new firmware\r
356 image version is older than the current firmware image version or bad image\r
357 checksum. Sensitive operations such as those wiping the entire firmware image\r
358 and render the device to be non-functional should be encoded in the image\r
359 itself rather than passed with the VendorCode. AbortReason enables vendor to\r
360 have the option to provide a more detailed description of the abort reason to\r
361 the caller.\r
362\r
363 @param[in] Image Points to the new firmware image.\r
364 @param[in] ImageSize Size, in bytes, of the new firmware image.\r
365 @param[in] VendorCode This enables vendor to implement vendor-specific\r
366 firmware image update policy. NULL indicates\r
367 the caller did not specify the policy or use the\r
368 default policy.\r
369 @param[in] Progress A function used to report the progress of\r
370 updating the firmware device with the new\r
371 firmware image.\r
372 @param[in] CapsuleFwVersion The version of the new firmware image from the\r
373 update capsule that provided the new firmware\r
374 image.\r
375 @param[out] AbortReason A pointer to a pointer to a Null-terminated\r
376 Unicode string providing more details on an\r
377 aborted operation. The buffer is allocated by\r
378 this function with\r
379 EFI_BOOT_SERVICES.AllocatePool(). It is the\r
380 caller's responsibility to free this buffer with\r
381 EFI_BOOT_SERVICES.FreePool().\r
382\r
383 @retval EFI_SUCCESS The firmware device was successfully updated\r
384 with the new firmware image.\r
385 @retval EFI_ABORTED The operation is aborted. Additional details\r
386 are provided in AbortReason.\r
387 @retval EFI_INVALID_PARAMETER The Image was NULL.\r
388 @retval EFI_UNSUPPORTED The operation is not supported.\r
389\r
390**/\r
391EFI_STATUS\r
392EFIAPI\r
393FmpDeviceSetImage (\r
394 IN CONST VOID *Image,\r
395 IN UINTN ImageSize,\r
396 IN CONST VOID *VendorCode, OPTIONAL\r
397 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL\r
398 IN UINT32 CapsuleFwVersion,\r
399 OUT CHAR16 **AbortReason\r
400 )\r
401{\r
402 return EFI_UNSUPPORTED;\r
403}\r
404\r
405/**\r
406 Lock the firmware device that contains a firmware image. Once a firmware\r
407 device is locked, any attempts to modify the firmware image contents in the\r
408 firmware device must fail.\r
409\r
410 @note It is recommended that all firmware devices support a lock method to\r
411 prevent modifications to a stored firmware image.\r
412\r
413 @note A firmware device lock mechanism is typically only cleared by a full\r
414 system reset (not just sleep state/low power mode).\r
415\r
416 @retval EFI_SUCCESS The firmware device was locked.\r
417 @retval EFI_UNSUPPORTED The firmware device does not support locking\r
418\r
419**/\r
420EFI_STATUS\r
421EFIAPI\r
422FmpDeviceLock (\r
423 VOID\r
424 )\r
425{\r
426 return EFI_UNSUPPORTED;\r
427}\r