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