2 Provides firmware device specific services to support updates of a firmware
3 image stored in a firmware device.
5 Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>
6 Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
12 #ifndef __FMP_DEVICE_LIB__
13 #define __FMP_DEVICE_LIB__
15 #include <Protocol/FirmwareManagement.h>
18 Callback function that installs a Firmware Management Protocol instance onto
21 @param[in] Handle The device handle to install a Firmware Management
24 @retval EFI_SUCCESS A Firmware Management Protocol instance was
25 installed onto Handle.
26 @retval EFI_INVALID_PARAMETER Handle is invalid
27 @retval other A Firmware Management Protocol instance could
28 not be installed onto Handle.
33 (EFIAPI
*FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER
)(
38 Callback function that uninstalls a Firmware Management Protocol instance from
41 @param[in] Handle The device handle to uninstall a Firmware Management
44 @retval EFI_SUCCESS A Firmware Management Protocol instance was
45 uninstalled from Handle.
46 @retval EFI_INVALID_PARAMETER Handle is invalid
47 @retval other A Firmware Management Protocol instance could
48 not be uninstalled from Handle.
53 (EFIAPI
*FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER
)(
58 Provide a function to install the Firmware Management Protocol instance onto a
59 device handle when the device is managed by a driver that follows the UEFI
60 Driver Model. If the device is not managed by a driver that follows the UEFI
61 Driver Model, then EFI_UNSUPPORTED is returned.
63 @param[in] FmpInstaller Function that installs the Firmware Management
66 @retval EFI_SUCCESS The device is managed by a driver that follows the
67 UEFI Driver Model. FmpInstaller must be called on
68 each Driver Binding Start().
69 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
70 the UEFI Driver Model.
71 @retval other The Firmware Management Protocol for this firmware
72 device is not installed. The firmware device is
73 still locked using FmpDeviceLock().
78 RegisterFmpInstaller (
79 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER FmpInstaller
83 Provide a function to uninstall the Firmware Management Protocol instance from a
84 device handle when the device is managed by a driver that follows the UEFI
85 Driver Model. If the device is not managed by a driver that follows the UEFI
86 Driver Model, then EFI_UNSUPPORTED is returned.
88 @param[in] FmpUninstaller Function that installs the Firmware Management
91 @retval EFI_SUCCESS The device is managed by a driver that follows the
92 UEFI Driver Model. FmpUinstaller must be called on
93 each Driver Binding Stop().
94 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
95 the UEFI Driver Model.
96 @retval other The Firmware Management Protocol for this firmware
97 device is not installed. The firmware device is
98 still locked using FmpDeviceLock().
103 RegisterFmpUninstaller (
104 IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER FmpUninstaller
108 Set the device context for the FmpDeviceLib services when the device is
109 managed by a driver that follows the UEFI Driver Model. If the device is not
110 managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
111 is returned. Once a device context is set, the FmpDeviceLib services
112 operate on the currently set device context.
114 @param[in] Handle Device handle for the FmpDeviceLib services.
115 If Handle is NULL, then Context is freed.
116 @param[in, out] Context Device context for the FmpDeviceLib services.
117 If Context is NULL, then a new context is allocated
118 for Handle and the current device context is set and
119 returned in Context. If Context is not NULL, then
120 the current device context is set.
122 @retval EFI_SUCCESS The device is managed by a driver that follows the
124 @retval EFI_UNSUPPORTED The device is not managed by a driver that follows
125 the UEFI Driver Model.
126 @retval other The Firmware Management Protocol for this firmware
127 device is not installed. The firmware device is
128 still locked using FmpDeviceLock().
133 FmpDeviceSetContext (
134 IN EFI_HANDLE Handle
,
135 IN OUT VOID
**Context
139 Returns the size, in bytes, of the firmware image currently stored in the
140 firmware device. This function is used to by the GetImage() and
141 GetImageInfo() services of the Firmware Management Protocol. If the image
142 size can not be determined from the firmware device, then 0 must be returned.
144 @param[out] Size Pointer to the size, in bytes, of the firmware image
145 currently stored in the firmware device.
147 @retval EFI_SUCCESS The size of the firmware image currently
148 stored in the firmware device was returned.
149 @retval EFI_INVALID_PARAMETER Size is NULL.
150 @retval EFI_UNSUPPORTED The firmware device does not support reporting
151 the size of the currently stored firmware image.
152 @retval EFI_DEVICE_ERROR An error occurred attempting to determine the
153 size of the firmware image currently stored in
154 in the firmware device.
164 Returns the GUID value used to fill in the ImageTypeId field of the
165 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
166 service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,
167 then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is
168 returned, then ImageTypeId is set to the Guid returned from this function.
170 @param[out] Guid Double pointer to a GUID value that is updated to point to
171 to a GUID value. The GUID value is not allocated and must
172 not be modified or freed by the caller.
174 @retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
175 to the returned Guid value.
176 @retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
182 FmpDeviceGetImageTypeIdGuidPtr (
187 Returns values used to fill in the AttributesSupported and AttributesSettings
188 fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
189 GetImageInfo() service of the Firmware Management Protocol. The following
190 bit values from the Firmware Management Protocol may be combined:
191 IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
192 IMAGE_ATTRIBUTE_RESET_REQUIRED
193 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
194 IMAGE_ATTRIBUTE_IN_USE
195 IMAGE_ATTRIBUTE_UEFI_IMAGE
197 @param[out] Supported Attributes supported by this firmware device.
198 @param[out] Setting Attributes settings for this firmware device.
200 @retval EFI_SUCCESS The attributes supported by the firmware
201 device were returned.
202 @retval EFI_INVALID_PARAMETER Supported is NULL.
203 @retval EFI_INVALID_PARAMETER Setting is NULL.
208 FmpDeviceGetAttributes (
209 OUT UINT64
*Supported
,
214 Returns the value used to fill in the LowestSupportedVersion field of the
215 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
216 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
217 the firmware device supports a method to report the LowestSupportedVersion
218 value from the currently stored firmware image. If the value can not be
219 reported for the firmware image currently stored in the firmware device, then
220 EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error
221 occurs attempting to retrieve the LowestSupportedVersion value for the
222 currently stored firmware image.
224 @note It is recommended that all firmware devices support a method to report
225 the LowestSupportedVersion value from the currently stored firmware
228 @param[out] LowestSupportedVersion LowestSupportedVersion value retrieved
229 from the currently stored firmware image.
231 @retval EFI_SUCCESS The lowest supported version of currently stored
232 firmware image was returned in LowestSupportedVersion.
233 @retval EFI_UNSUPPORTED The firmware device does not support a method to
234 report the lowest supported version of the currently
235 stored firmware image.
236 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest
237 supported version of the currently stored firmware
243 FmpDeviceGetLowestSupportedVersion (
244 OUT UINT32
*LowestSupportedVersion
248 Returns the Null-terminated Unicode string that is used to fill in the
249 VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
250 returned by the GetImageInfo() service of the Firmware Management Protocol.
251 The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
253 @note It is recommended that all firmware devices support a method to report
254 the VersionName string from the currently stored firmware image.
256 @param[out] VersionString The version string retrieved from the currently
257 stored firmware image.
259 @retval EFI_SUCCESS The version string of currently stored
260 firmware image was returned in Version.
261 @retval EFI_INVALID_PARAMETER VersionString is NULL.
262 @retval EFI_UNSUPPORTED The firmware device does not support a method
263 to report the version string of the currently
264 stored firmware image.
265 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
266 version string of the currently stored
268 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the
269 buffer for the version string of the currently
270 stored firmware image.
275 FmpDeviceGetVersionString (
276 OUT CHAR16
**VersionString
280 Returns the value used to fill in the Version field of the
281 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
282 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
283 the firmware device supports a method to report the Version value from the
284 currently stored firmware image. If the value can not be reported for the
285 firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
286 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
287 to retrieve the LowestSupportedVersion value for the currently stored firmware
290 @note It is recommended that all firmware devices support a method to report
291 the Version value from the currently stored firmware image.
293 @param[out] Version The version value retrieved from the currently stored
296 @retval EFI_SUCCESS The version of currently stored firmware image was
298 @retval EFI_UNSUPPORTED The firmware device does not support a method to
299 report the version of the currently stored firmware
301 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version
302 of the currently stored firmware image.
307 FmpDeviceGetVersion (
312 Returns the value used to fill in the HardwareInstance field of the
313 EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
314 service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then
315 the firmware device supports a method to report the HardwareInstance value.
316 If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
317 must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting
318 to retrieve the HardwareInstance value for the firmware device.
320 @param[out] HardwareInstance The hardware instance value for the firmware
323 @retval EFI_SUCCESS The hardware instance for the current firmware
324 devide is returned in HardwareInstance.
325 @retval EFI_UNSUPPORTED The firmware device does not support a method to
326 report the hardware instance value.
327 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the hardware
333 FmpDeviceGetHardwareInstance (
334 OUT UINT64
*HardwareInstance
338 Returns a copy of the firmware image currently stored in the firmware device.
340 @note It is recommended that all firmware devices support a method to retrieve
341 a copy currently stored firmware image. This can be used to support
342 features such as recovery and rollback.
344 @param[out] Image Pointer to a caller allocated buffer where the
345 currently stored firmware image is copied to.
346 @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
347 On return, points to the size, in bytes, of firmware
348 image currently stored in the firmware device.
350 @retval EFI_SUCCESS Image contains a copy of the firmware image
351 currently stored in the firmware device, and
352 ImageSize contains the size, in bytes, of the
353 firmware image currently stored in the
355 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small
356 to hold the firmware image currently stored in
357 the firmware device. The buffer size required
358 is returned in ImageSize.
359 @retval EFI_INVALID_PARAMETER The Image is NULL.
360 @retval EFI_INVALID_PARAMETER The ImageSize is NULL.
361 @retval EFI_UNSUPPORTED The operation is not supported.
362 @retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the
363 firmware image currently stored in the firmware
371 IN OUT UINTN
*ImageSize
375 Checks if a new firmware image is valid for the firmware device. This
376 function allows firmware update operation to validate the firmware image
377 before FmpDeviceSetImage() is called.
379 @param[in] Image Points to a new firmware image.
380 @param[in] ImageSize Size, in bytes, of a new firmware image.
381 @param[out] ImageUpdatable Indicates if a new firmware image is valid for
382 a firmware update to the firmware device. The
383 following values from the Firmware Management
384 Protocol are supported:
385 IMAGE_UPDATABLE_VALID
386 IMAGE_UPDATABLE_INVALID
387 IMAGE_UPDATABLE_INVALID_TYPE
388 IMAGE_UPDATABLE_INVALID_OLD
389 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
391 @retval EFI_SUCCESS The image was successfully checked. Additional
392 status information is returned in
394 @retval EFI_INVALID_PARAMETER Image is NULL.
395 @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.
400 FmpDeviceCheckImage (
401 IN CONST VOID
*Image
,
403 OUT UINT32
*ImageUpdatable
407 Updates a firmware device with a new firmware image. This function returns
408 EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image
409 is updatable, the function should perform the following minimal validations
410 before proceeding to do the firmware image update.
411 - Validate that the image is a supported image for this firmware device.
412 Return EFI_ABORTED if the image is not supported. Additional details
413 on why the image is not a supported image may be returned in AbortReason.
414 - Validate the data from VendorCode if is not NULL. Firmware image
415 validation must be performed before VendorCode data validation.
416 VendorCode data is ignored or considered invalid if image validation
417 fails. Return EFI_ABORTED if the VendorCode data is invalid.
419 VendorCode enables vendor to implement vendor-specific firmware image update
420 policy. Null if the caller did not specify the policy or use the default
421 policy. As an example, vendor can implement a policy to allow an option to
422 force a firmware image update when the abort reason is due to the new firmware
423 image version is older than the current firmware image version or bad image
424 checksum. Sensitive operations such as those wiping the entire firmware image
425 and render the device to be non-functional should be encoded in the image
426 itself rather than passed with the VendorCode. AbortReason enables vendor to
427 have the option to provide a more detailed description of the abort reason to
430 @param[in] Image Points to the new firmware image.
431 @param[in] ImageSize Size, in bytes, of the new firmware image.
432 @param[in] VendorCode This enables vendor to implement vendor-specific
433 firmware image update policy. NULL indicates
434 the caller did not specify the policy or use the
436 @param[in] Progress A function used to report the progress of
437 updating the firmware device with the new
439 @param[in] CapsuleFwVersion The version of the new firmware image from the
440 update capsule that provided the new firmware
442 @param[out] AbortReason A pointer to a pointer to a Null-terminated
443 Unicode string providing more details on an
444 aborted operation. The buffer is allocated by
446 EFI_BOOT_SERVICES.AllocatePool(). It is the
447 caller's responsibility to free this buffer with
448 EFI_BOOT_SERVICES.FreePool().
450 @retval EFI_SUCCESS The firmware device was successfully updated
451 with the new firmware image.
452 @retval EFI_ABORTED The operation is aborted. Additional details
453 are provided in AbortReason.
454 @retval EFI_INVALID_PARAMETER The Image was NULL.
455 @retval EFI_UNSUPPORTED The operation is not supported.
461 IN CONST VOID
*Image
,
463 IN CONST VOID
*VendorCode
, OPTIONAL
464 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress
, OPTIONAL
465 IN UINT32 CapsuleFwVersion
,
466 OUT CHAR16
**AbortReason
470 Lock the firmware device that contains a firmware image. Once a firmware
471 device is locked, any attempts to modify the firmware image contents in the
472 firmware device must fail.
474 @note It is recommended that all firmware devices support a lock method to
475 prevent modifications to a stored firmware image.
477 @note A firmware device lock mechanism is typically only cleared by a full
478 system reset (not just sleep state/low power mode).
480 @retval EFI_SUCCESS The firmware device was locked.
481 @retval EFI_UNSUPPORTED The firmware device does not support locking