2 Produces a Firmware Management Protocol that supports updates to a firmware
3 image stored in a firmware device with platform and firmware device specific
4 information provided through PCDs and libraries.
6 Copyright (c) Microsoft Corporation.<BR>
7 Copyright (c) 2018 - 2020, Intel Corporation. All rights reserved.<BR>
9 SPDX-License-Identifier: BSD-2-Clause-Patent
14 #include "VariableSupport.h"
17 /// FILE_GUID from FmpDxe.inf. When FmpDxe.inf is used in a platform, the
18 /// FILE_GUID must always be overridden in the <Defines> section to provide
19 /// the ESRT GUID value associated with the updatable firmware image. A
20 /// check is made in this module's driver entry point to verify that a
21 /// new FILE_GUID value has been defined.
23 const EFI_GUID mDefaultModuleFileGuid
= {
24 0x78ef0a56, 0x1cf0, 0x4535, { 0xb5, 0xda, 0xf6, 0xfd, 0x2f, 0x40, 0x5a, 0x11 }
28 /// TRUE if FmpDeviceLib manages a single firmware storage device.
30 BOOLEAN mFmpSingleInstance
= FALSE
;
33 /// Firmware Management Protocol instance that is initialized in the entry
34 /// point from PCD settings.
36 EDKII_FIRMWARE_MANAGEMENT_PROGRESS_PROTOCOL mFmpProgress
;
39 // Template of the private context structure for the Firmware Management
42 const FIRMWARE_MANAGEMENT_PRIVATE_DATA mFirmwareManagementPrivateDataTemplate
= {
43 FIRMWARE_MANAGEMENT_PRIVATE_DATA_SIGNATURE
, // Signature
53 FALSE
, // DescriptorPopulated
59 { 0x00000000, 0x0000, 0x0000, {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00} },
65 0, // AttributesSupported
66 0, // AttributesSetting
68 0, // LowestSupportedImageVersion
69 0, // LastAttemptVersion
70 0, // LastAttemptStatus
75 TRUE
, // RuntimeVersionSupported
76 NULL
, // FmpDeviceLockEvent
77 FALSE
, // FmpDeviceLocked
78 NULL
, // FmpDeviceContext
79 NULL
, // VersionVariableName
80 NULL
, // LsvVariableName
81 NULL
, // LastAttemptStatusVariableName
82 NULL
, // LastAttemptVersionVariableName
83 NULL
, // FmpStateVariableName
84 TRUE
// DependenciesSatisfied
88 /// GUID that is used to create event used to lock the firmware storage device.
90 EFI_GUID
*mLockGuid
= NULL
;
93 /// Progress() function pointer passed into SetTheImage()
95 EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS mProgressFunc
= NULL
;
98 /// Null-terminated Unicode string retrieved from PcdFmpDeviceImageIdName.
100 CHAR16
*mImageIdName
= NULL
;
103 Callback function to report the process of the firmware updating.
105 Wrap the caller's version in this so that progress from the device lib is
106 within the expected range. Convert device lib 0% - 100% to 6% - 98%.
108 FmpDxe 1% - 5% for validation
109 FmpDeviceLib 6% - 98% for flashing/update
110 FmpDxe 99% - 100% finish
112 @param[in] Completion A value between 1 and 100 indicating the current
113 completion progress of the firmware update. Completion
114 progress is reported as from 1 to 100 percent. A value
115 of 0 is used by the driver to indicate that progress
116 reporting is not supported.
118 @retval EFI_SUCCESS The progress was updated.
119 @retval EFI_UNSUPPORTED Updating progress is not supported.
130 Status
= EFI_UNSUPPORTED
;
132 if (mProgressFunc
== NULL
) {
137 // Reserve 6% - 98% for the FmpDeviceLib. Call the real progress function.
139 Status
= mProgressFunc (((Completion
* 92) / 100) + 6);
141 if (Status
== EFI_UNSUPPORTED
) {
142 mProgressFunc
= NULL
;
149 Returns a pointer to the ImageTypeId GUID value. An attempt is made to get
150 the GUID value from the FmpDeviceLib. If the FmpDeviceLib does not provide
151 a GUID value, then PcdFmpDeviceImageTypeIdGuid is used. If the size of
152 PcdFmpDeviceImageTypeIdGuid is not the size of EFI_GUID, then gEfiCallerIdGuid
155 @retval The ImageTypeId GUID
164 EFI_GUID
*FmpDeviceLibGuid
;
165 UINTN ImageTypeIdGuidSize
;
167 FmpDeviceLibGuid
= NULL
;
168 Status
= FmpDeviceGetImageTypeIdGuidPtr (&FmpDeviceLibGuid
);
169 if (EFI_ERROR (Status
)) {
170 if (Status
!= EFI_UNSUPPORTED
) {
171 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib GetImageTypeIdGuidPtr() returned invalid error %r\n", mImageIdName
, Status
));
173 } else if (FmpDeviceLibGuid
== NULL
) {
174 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib GetImageTypeIdGuidPtr() returned invalid GUID\n", mImageIdName
));
175 Status
= EFI_NOT_FOUND
;
177 if (EFI_ERROR (Status
)) {
178 ImageTypeIdGuidSize
= PcdGetSize (PcdFmpDeviceImageTypeIdGuid
);
179 if (ImageTypeIdGuidSize
== sizeof (EFI_GUID
)) {
180 FmpDeviceLibGuid
= (EFI_GUID
*)PcdGetPtr (PcdFmpDeviceImageTypeIdGuid
);
182 DEBUG ((DEBUG_WARN
, "FmpDxe(%s): Fall back to ImageTypeIdGuid of gEfiCallerIdGuid\n", mImageIdName
));
183 FmpDeviceLibGuid
= &gEfiCallerIdGuid
;
186 return FmpDeviceLibGuid
;
190 Returns a pointer to the Null-terminated Unicode ImageIdName string.
192 @retval Null-terminated Unicode ImageIdName string.
196 GetImageTypeNameString (
204 Lowest supported version is a combo of three parts.
205 1. Check if the device lib has a lowest supported version
206 2. Check if we have a variable for lowest supported version (this will be updated with each capsule applied)
207 3. Check Fixed at build PCD
209 @param[in] Private Pointer to the private context structure for the
210 Firmware Management Protocol instance.
212 @retval The largest value
216 GetLowestSupportedVersion (
217 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
221 UINT32 DeviceLibLowestSupportedVersion
;
222 UINT32 VariableLowestSupportedVersion
;
226 // Get the LowestSupportedVersion.
229 if (!IsLowestSupportedVersionCheckRequired ()) {
231 // Any Version can pass the 0 LowestSupportedVersion check.
236 ReturnLsv
= PcdGet32 (PcdFmpDeviceBuildTimeLowestSupportedVersion
);
239 // Check the FmpDeviceLib
241 DeviceLibLowestSupportedVersion
= DEFAULT_LOWESTSUPPORTEDVERSION
;
242 Status
= FmpDeviceGetLowestSupportedVersion (&DeviceLibLowestSupportedVersion
);
243 if (EFI_ERROR (Status
)) {
244 DeviceLibLowestSupportedVersion
= DEFAULT_LOWESTSUPPORTEDVERSION
;
247 if (DeviceLibLowestSupportedVersion
> ReturnLsv
) {
248 ReturnLsv
= DeviceLibLowestSupportedVersion
;
252 // Check the lowest supported version UEFI variable for this device
254 VariableLowestSupportedVersion
= GetLowestSupportedVersionFromVariable (Private
);
255 if (VariableLowestSupportedVersion
> ReturnLsv
) {
256 ReturnLsv
= VariableLowestSupportedVersion
;
260 // Return the largest value
266 Populates the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure in the private
269 @param[in] Private Pointer to the private context structure for the
270 Firmware Management Protocol instance.
275 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
279 UINT32 DependenciesSize
;
281 if (Private
== NULL
) {
282 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): PopulateDescriptor() - Private is NULL.\n", mImageIdName
));
286 if (Private
->DescriptorPopulated
) {
290 Private
->Descriptor
.ImageIndex
= 1;
291 CopyGuid (&Private
->Descriptor
.ImageTypeId
, GetImageTypeIdGuid());
292 Private
->Descriptor
.ImageId
= Private
->Descriptor
.ImageIndex
;
293 Private
->Descriptor
.ImageIdName
= GetImageTypeNameString();
296 // Get the hardware instance from FmpDeviceLib
298 Status
= FmpDeviceGetHardwareInstance (&Private
->Descriptor
.HardwareInstance
);
299 if (Status
== EFI_UNSUPPORTED
) {
300 Private
->Descriptor
.HardwareInstance
= 0;
304 // Generate UEFI Variable names used to store status information for this
307 GenerateFmpVariableNames (Private
);
310 // Get the version. Some devices don't support getting the firmware version
311 // at runtime. If FmpDeviceLib does not support returning a version, then
312 // it is stored in a UEFI variable.
314 Status
= FmpDeviceGetVersion (&Private
->Descriptor
.Version
);
315 if (Status
== EFI_UNSUPPORTED
) {
316 Private
->RuntimeVersionSupported
= FALSE
;
317 Private
->Descriptor
.Version
= GetVersionFromVariable (Private
);
318 } else if (EFI_ERROR (Status
)) {
320 // Unexpected error. Use default version.
322 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetVersion() from FmpDeviceLib (%s) returned %r\n", mImageIdName
, GetImageTypeNameString(), Status
));
323 Private
->Descriptor
.Version
= DEFAULT_VERSION
;
327 // Free the current version name. Shouldn't really happen but this populate
328 // function could be called multiple times (to refresh).
330 if (Private
->Descriptor
.VersionName
!= NULL
) {
331 FreePool (Private
->Descriptor
.VersionName
);
332 Private
->Descriptor
.VersionName
= NULL
;
336 // Attempt to get the version string from the FmpDeviceLib
338 Status
= FmpDeviceGetVersionString (&Private
->Descriptor
.VersionName
);
339 if (Status
== EFI_UNSUPPORTED
) {
340 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): GetVersionString() unsupported in FmpDeviceLib.\n", mImageIdName
));
341 Private
->Descriptor
.VersionName
= AllocateCopyPool (
342 sizeof (VERSION_STRING_NOT_SUPPORTED
),
343 VERSION_STRING_NOT_SUPPORTED
345 } else if (EFI_ERROR (Status
)) {
346 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): GetVersionString() not available in FmpDeviceLib.\n", mImageIdName
));
347 Private
->Descriptor
.VersionName
= AllocateCopyPool (
348 sizeof (VERSION_STRING_NOT_AVAILABLE
),
349 VERSION_STRING_NOT_AVAILABLE
353 Private
->Descriptor
.LowestSupportedImageVersion
= GetLowestSupportedVersion (Private
);
356 // Get attributes from the FmpDeviceLib
358 FmpDeviceGetAttributes (
359 &Private
->Descriptor
.AttributesSupported
,
360 &Private
->Descriptor
.AttributesSetting
364 // Force set the updatable bits in the attributes;
366 Private
->Descriptor
.AttributesSupported
|= IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
;
367 Private
->Descriptor
.AttributesSetting
|= IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
;
370 // Force set the authentication bits in the attributes;
372 Private
->Descriptor
.AttributesSupported
|= (IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
);
373 Private
->Descriptor
.AttributesSetting
|= (IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
);
375 Private
->Descriptor
.Compatibilities
= 0;
378 // Get the size of the firmware image from the FmpDeviceLib
380 Status
= FmpDeviceGetSize (&Private
->Descriptor
.Size
);
381 if (EFI_ERROR (Status
)) {
382 Private
->Descriptor
.Size
= 0;
385 Private
->Descriptor
.LastAttemptVersion
= GetLastAttemptVersionFromVariable (Private
);
386 Private
->Descriptor
.LastAttemptStatus
= GetLastAttemptStatusFromVariable (Private
);
389 // Get the dependency from the FmpDependencyDeviceLib.
391 Private
->Descriptor
.Dependencies
= NULL
;
394 // Check the attribute IMAGE_ATTRIBUTE_DEPENDENCY
396 if (Private
->Descriptor
.AttributesSetting
& IMAGE_ATTRIBUTE_DEPENDENCY
) {
397 Private
->Descriptor
.Dependencies
= GetFmpDependency (&DependenciesSize
);
400 Private
->DescriptorPopulated
= TRUE
;
404 Returns information about the current firmware image(s) of the device.
406 This function allows a copy of the current firmware image to be created and saved.
407 The saved copy could later been used, for example, in firmware image recovery or rollback.
409 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
410 @param[in, out] ImageInfoSize A pointer to the size, in bytes, of the ImageInfo buffer.
411 On input, this is the size of the buffer allocated by the caller.
412 On output, it is the size of the buffer returned by the firmware
413 if the buffer was large enough, or the size of the buffer needed
414 to contain the image(s) information if the buffer was too small.
415 @param[in, out] ImageInfo A pointer to the buffer in which firmware places the current image(s)
416 information. The information is an array of EFI_FIRMWARE_IMAGE_DESCRIPTORs.
417 @param[out] DescriptorVersion A pointer to the location in which firmware returns the version number
418 associated with the EFI_FIRMWARE_IMAGE_DESCRIPTOR.
419 @param[out] DescriptorCount A pointer to the location in which firmware returns the number of
420 descriptors or firmware images within this device.
421 @param[out] DescriptorSize A pointer to the location in which firmware returns the size, in bytes,
422 of an individual EFI_FIRMWARE_IMAGE_DESCRIPTOR.
423 @param[out] PackageVersion A version number that represents all the firmware images in the device.
424 The format is vendor specific and new version must have a greater value
425 than the old version. If PackageVersion is not supported, the value is
426 0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version comparison
427 is to be performed using PackageVersionName. A value of 0xFFFFFFFD indicates
428 that package version update is in progress.
429 @param[out] PackageVersionName A pointer to a pointer to a null-terminated string representing the
430 package version name. The buffer is allocated by this function with
431 AllocatePool(), and it is the caller's responsibility to free it with a call
434 @retval EFI_SUCCESS The device was successfully updated with the new image.
435 @retval EFI_BUFFER_TOO_SMALL The ImageInfo buffer was too small. The current buffer size
436 needed to hold the image(s) information is returned in ImageInfoSize.
437 @retval EFI_INVALID_PARAMETER ImageInfoSize is NULL.
438 @retval EFI_DEVICE_ERROR Valid information could not be returned. Possible corrupted image.
444 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
445 IN OUT UINTN
*ImageInfoSize
,
446 IN OUT EFI_FIRMWARE_IMAGE_DESCRIPTOR
*ImageInfo
,
447 OUT UINT32
*DescriptorVersion
,
448 OUT UINT8
*DescriptorCount
,
449 OUT UINTN
*DescriptorSize
,
450 OUT UINT32
*PackageVersion
,
451 OUT CHAR16
**PackageVersionName
455 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
457 Status
= EFI_SUCCESS
;
460 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImageInfo() - This is NULL.\n", mImageIdName
));
461 Status
= EFI_INVALID_PARAMETER
;
466 // Retrieve the private context structure
468 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
469 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
472 // Check for valid pointer
474 if (ImageInfoSize
== NULL
) {
475 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImageInfo() - ImageInfoSize is NULL.\n", mImageIdName
));
476 Status
= EFI_INVALID_PARAMETER
;
481 // Check the buffer size
482 // NOTE: Check this first so caller can get the necessary memory size it must allocate.
484 if (*ImageInfoSize
< (sizeof (EFI_FIRMWARE_IMAGE_DESCRIPTOR
))) {
485 *ImageInfoSize
= sizeof (EFI_FIRMWARE_IMAGE_DESCRIPTOR
);
486 DEBUG ((DEBUG_VERBOSE
, "FmpDxe(%s): GetImageInfo() - ImageInfoSize is to small.\n", mImageIdName
));
487 Status
= EFI_BUFFER_TOO_SMALL
;
492 // Confirm that buffer isn't null
494 if ( (ImageInfo
== NULL
) || (DescriptorVersion
== NULL
) || (DescriptorCount
== NULL
) || (DescriptorSize
== NULL
)
495 || (PackageVersion
== NULL
)) {
496 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImageInfo() - Pointer Parameter is NULL.\n", mImageIdName
));
497 Status
= EFI_INVALID_PARAMETER
;
502 // Set the size to whatever we need
504 *ImageInfoSize
= sizeof (EFI_FIRMWARE_IMAGE_DESCRIPTOR
);
507 // Make sure the descriptor has already been loaded or refreshed
509 PopulateDescriptor (Private
);
512 // Copy the image descriptor
514 CopyMem (ImageInfo
, &Private
->Descriptor
, sizeof (EFI_FIRMWARE_IMAGE_DESCRIPTOR
));
516 *DescriptorVersion
= EFI_FIRMWARE_IMAGE_DESCRIPTOR_VERSION
;
517 *DescriptorCount
= 1;
518 *DescriptorSize
= sizeof (EFI_FIRMWARE_IMAGE_DESCRIPTOR
);
522 *PackageVersion
= 0xFFFFFFFF;
525 // Do not update PackageVersionName since it is not supported in this instance.
534 Retrieves a copy of the current firmware image of the device.
536 This function allows a copy of the current firmware image to be created and saved.
537 The saved copy could later been used, for example, in firmware image recovery or rollback.
539 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
540 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
541 The number is between 1 and DescriptorCount.
542 @param[in, out] Image Points to the buffer where the current image is copied to.
543 @param[in, out] ImageSize On entry, points to the size of the buffer pointed to by Image, in bytes.
544 On return, points to the length of the image, in bytes.
546 @retval EFI_SUCCESS The device was successfully updated with the new image.
547 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small to hold the
548 image. The current buffer size needed to hold the image is returned
550 @retval EFI_INVALID_PARAMETER The Image was NULL.
551 @retval EFI_NOT_FOUND The current image is not copied to the buffer.
552 @retval EFI_UNSUPPORTED The operation is not supported.
553 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
559 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
562 IN OUT UINTN
*ImageSize
566 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
569 if (!FeaturePcdGet (PcdFmpDeviceStorageAccessEnable
)) {
570 return EFI_UNSUPPORTED
;
573 Status
= EFI_SUCCESS
;
576 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImage() - This is NULL.\n", mImageIdName
));
577 Status
= EFI_INVALID_PARAMETER
;
582 // Retrieve the private context structure
584 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
585 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
588 // Check to make sure index is 1 (only 1 image for this device)
590 if (ImageIndex
!= 1) {
591 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImage() - Image Index Invalid.\n", mImageIdName
));
592 Status
= EFI_INVALID_PARAMETER
;
596 if (ImageSize
== NULL
) {
597 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImage() - ImageSize Pointer Parameter is NULL.\n", mImageIdName
));
598 Status
= EFI_INVALID_PARAMETER
;
603 // Check the buffer size
605 Status
= FmpDeviceGetSize (&Size
);
606 if (EFI_ERROR (Status
)) {
609 if (*ImageSize
< Size
) {
611 DEBUG ((DEBUG_VERBOSE
, "FmpDxe(%s): GetImage() - ImageSize is to small.\n", mImageIdName
));
612 Status
= EFI_BUFFER_TOO_SMALL
;
617 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetImage() - Image Pointer Parameter is NULL.\n", mImageIdName
));
618 Status
= EFI_INVALID_PARAMETER
;
622 Status
= FmpDeviceGetImage (Image
, ImageSize
);
629 Helper function to safely retrieve the FMP header from
630 within an EFI_FIRMWARE_IMAGE_AUTHENTICATION structure.
632 @param[in] Image Pointer to the image.
633 @param[in] ImageSize Size of the image.
634 @param[in] AdditionalHeaderSize Size of any headers that cannot be calculated by this function.
635 @param[out] PayloadSize An optional pointer to a UINTN that holds the size of the payload
636 (image size minus headers)
638 @retval !NULL Valid pointer to the header.
639 @retval NULL Structure is bad and pointer cannot be found.
644 IN CONST EFI_FIRMWARE_IMAGE_AUTHENTICATION
*Image
,
645 IN CONST UINTN ImageSize
,
646 IN CONST UINTN AdditionalHeaderSize
,
647 OUT UINTN
*PayloadSize OPTIONAL
651 // Check to make sure that operation can be safely performed.
653 if (((UINTN
)Image
+ sizeof (Image
->MonotonicCount
) + Image
->AuthInfo
.Hdr
.dwLength
) + AdditionalHeaderSize
< (UINTN
)Image
|| \
654 ((UINTN
)Image
+ sizeof (Image
->MonotonicCount
) + Image
->AuthInfo
.Hdr
.dwLength
) + AdditionalHeaderSize
>= (UINTN
)Image
+ ImageSize
) {
656 // Pointer overflow. Invalid image.
661 if (PayloadSize
!= NULL
) {
662 *PayloadSize
= ImageSize
- (sizeof (Image
->MonotonicCount
) + Image
->AuthInfo
.Hdr
.dwLength
+ AdditionalHeaderSize
);
665 return (VOID
*)((UINT8
*)Image
+ sizeof (Image
->MonotonicCount
) + Image
->AuthInfo
.Hdr
.dwLength
+ AdditionalHeaderSize
);
669 Helper function to safely calculate the size of all headers
670 within an EFI_FIRMWARE_IMAGE_AUTHENTICATION structure.
672 @param[in] Image Pointer to the image.
673 @param[in] AdditionalHeaderSize Size of any headers that cannot be calculated by this function.
675 @retval UINT32>0 Valid size of all the headers.
676 @retval 0 Structure is bad and size cannot be found.
681 IN CONST EFI_FIRMWARE_IMAGE_AUTHENTICATION
*Image
,
682 IN UINT32 AdditionalHeaderSize
685 UINT32 CalculatedSize
;
688 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): GetAllHeaderSize() - Image is NULL.\n", mImageIdName
));
692 CalculatedSize
= sizeof (Image
->MonotonicCount
) +
693 AdditionalHeaderSize
+
694 Image
->AuthInfo
.Hdr
.dwLength
;
697 // Check to make sure that operation can be safely performed.
699 if (CalculatedSize
< sizeof (Image
->MonotonicCount
) ||
700 CalculatedSize
< AdditionalHeaderSize
||
701 CalculatedSize
< Image
->AuthInfo
.Hdr
.dwLength
) {
703 // Integer overflow. Invalid image.
708 return CalculatedSize
;
712 Checks if the firmware image is valid for the device.
714 This function allows firmware update application to validate the firmware image without
715 invoking the SetImage() first.
717 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
718 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
719 The number is between 1 and DescriptorCount.
720 @param[in] Image Points to the new image.
721 @param[in] ImageSize Size of the new image in bytes.
722 @param[out] ImageUpdatable Indicates if the new image is valid for update. It also provides,
723 if available, additional information if the image is invalid.
724 @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt status to report
725 back to the ESRT table in case of error. If an error does not occur,
726 this function will set the value to LAST_ATTEMPT_STATUS_SUCCESS.
728 This function will return error codes that occur within this function
729 implementation within a driver range of last attempt error codes from
730 LAST_ATTEMPT_STATUS_DRIVER_MIN_ERROR_CODE_VALUE
731 to LAST_ATTEMPT_STATUS_DRIVER_MAX_ERROR_CODE_VALUE.
733 @retval EFI_SUCCESS The image was successfully checked.
734 @retval EFI_ABORTED The operation is aborted.
735 @retval EFI_INVALID_PARAMETER The Image was NULL.
736 @retval EFI_UNSUPPORTED The operation is not supported.
737 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
742 CheckTheImageInternal (
743 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
745 IN CONST VOID
*Image
,
747 OUT UINT32
*ImageUpdatable
,
748 OUT UINT32
*LastAttemptStatus
752 UINT32 LocalLastAttemptStatus
;
753 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
755 VOID
*FmpPayloadHeader
;
756 UINTN FmpPayloadSize
;
758 UINT32 FmpHeaderSize
;
762 UINTN PublicKeyDataLength
;
763 UINT8
*PublicKeyDataXdr
;
764 UINT8
*PublicKeyDataXdrEnd
;
765 EFI_FIRMWARE_IMAGE_DEP
*Dependencies
;
766 UINT32 DependenciesSize
;
768 Status
= EFI_SUCCESS
;
769 LocalLastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
771 FmpPayloadHeader
= NULL
;
777 DependenciesSize
= 0;
779 if (!FeaturePcdGet (PcdFmpDeviceStorageAccessEnable
)) {
780 return EFI_UNSUPPORTED
;
783 if (LastAttemptStatus
== NULL
) {
784 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImageInternal() - LastAttemptStatus is NULL.\n", mImageIdName
));
785 Status
= EFI_INVALID_PARAMETER
;
790 // A last attempt status error code will always override the success
791 // value before returning from the function
793 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
796 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - This is NULL.\n", mImageIdName
));
797 Status
= EFI_INVALID_PARAMETER
;
798 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_PROTOCOL_ARG_MISSING
;
803 // Retrieve the private context structure
805 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
806 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
809 // Make sure the descriptor has already been loaded or refreshed
811 PopulateDescriptor (Private
);
813 if (ImageUpdatable
== NULL
) {
814 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - ImageUpdatable Pointer Parameter is NULL.\n", mImageIdName
));
815 Status
= EFI_INVALID_PARAMETER
;
816 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_IMAGE_NOT_UPDATABLE
;
821 //Set to valid and then if any tests fail it will update this flag.
823 *ImageUpdatable
= IMAGE_UPDATABLE_VALID
;
826 // Set to satisfied and then if dependency evaluates to false it will update this flag.
828 Private
->DependenciesSatisfied
= TRUE
;
831 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - Image Pointer Parameter is NULL.\n", mImageIdName
));
833 // not sure if this is needed
835 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
836 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_IMAGE_NOT_PROVIDED
;
837 return EFI_INVALID_PARAMETER
;
840 PublicKeyDataXdr
= PcdGetPtr (PcdFmpDevicePkcs7CertBufferXdr
);
841 PublicKeyDataXdrEnd
= PublicKeyDataXdr
+ PcdGetSize (PcdFmpDevicePkcs7CertBufferXdr
);
843 if (PublicKeyDataXdr
== NULL
|| (PublicKeyDataXdr
== PublicKeyDataXdrEnd
)) {
844 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Invalid certificate, skipping it.\n", mImageIdName
));
845 Status
= EFI_ABORTED
;
846 LocalLastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_INVALID_CERTIFICATE
;
849 // Try each key from PcdFmpDevicePkcs7CertBufferXdr
851 for (Index
= 1; PublicKeyDataXdr
< PublicKeyDataXdrEnd
; Index
++) {
855 "FmpDxe(%s): Certificate #%d [%p..%p].\n",
863 if ((PublicKeyDataXdr
+ sizeof (UINT32
)) > PublicKeyDataXdrEnd
) {
865 // Key data extends beyond end of PCD
867 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Certificate size extends beyond end of PCD, skipping it.\n", mImageIdName
));
868 Status
= EFI_ABORTED
;
869 LocalLastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_INVALID_KEY_LENGTH_VALUE
;
873 // Read key length stored in big-endian format
875 PublicKeyDataLength
= SwapBytes32 (*(UINT32
*)(PublicKeyDataXdr
));
877 // Point to the start of the key data
879 PublicKeyDataXdr
+= sizeof (UINT32
);
880 if (PublicKeyDataXdr
+ PublicKeyDataLength
> PublicKeyDataXdrEnd
) {
882 // Key data extends beyond end of PCD
884 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Certificate extends beyond end of PCD, skipping it.\n", mImageIdName
));
885 Status
= EFI_ABORTED
;
886 LocalLastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_INVALID_KEY_LENGTH
;
889 PublicKeyData
= PublicKeyDataXdr
;
890 Status
= AuthenticateFmpImage (
891 (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
,
896 if (!EFI_ERROR (Status
)) {
899 PublicKeyDataXdr
+= PublicKeyDataLength
;
900 PublicKeyDataXdr
= (UINT8
*)ALIGN_POINTER (PublicKeyDataXdr
, sizeof (UINT32
));
904 if (EFI_ERROR (Status
)) {
905 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - Authentication Failed %r.\n", mImageIdName
, Status
));
906 if (LocalLastAttemptStatus
!= LAST_ATTEMPT_STATUS_SUCCESS
) {
907 *LastAttemptStatus
= LocalLastAttemptStatus
;
909 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_IMAGE_AUTH_FAILURE
;
915 // Check to make sure index is 1
917 if (ImageIndex
!= 1) {
918 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - Image Index Invalid.\n", mImageIdName
));
919 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID_TYPE
;
920 Status
= EFI_INVALID_PARAMETER
;
921 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_INVALID_IMAGE_INDEX
;
926 // Get the dependency from Image.
928 Dependencies
= GetImageDependency ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, &DependenciesSize
);
931 // Check the FmpPayloadHeader
933 FmpPayloadHeader
= GetFmpHeader ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, DependenciesSize
, &FmpPayloadSize
);
934 if (FmpPayloadHeader
== NULL
) {
935 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetFmpHeader failed.\n", mImageIdName
));
936 Status
= EFI_ABORTED
;
937 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_GET_FMP_HEADER
;
940 Status
= GetFmpPayloadHeaderVersion (FmpPayloadHeader
, FmpPayloadSize
, &Version
);
941 if (EFI_ERROR (Status
)) {
942 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetFmpPayloadHeaderVersion failed %r.\n", mImageIdName
, Status
));
943 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
944 Status
= EFI_SUCCESS
;
945 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_GET_FMP_HEADER_VERSION
;
950 // Check the lowest supported version
952 if (Version
< Private
->Descriptor
.LowestSupportedImageVersion
) {
955 "FmpDxe(%s): CheckTheImage() - Version Lower than lowest supported version. 0x%08X < 0x%08X\n",
956 mImageIdName
, Version
, Private
->Descriptor
.LowestSupportedImageVersion
)
958 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID_OLD
;
959 Status
= EFI_SUCCESS
;
960 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_VERSION_TOO_LOW
;
965 // Evaluate dependency expression
967 Private
->DependenciesSatisfied
= CheckFmpDependency (Private
->Descriptor
.ImageTypeId
, Version
, Dependencies
, DependenciesSize
);
968 if (!Private
->DependenciesSatisfied
) {
969 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - Dependency check failed.\n", mImageIdName
));
970 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
971 Status
= EFI_SUCCESS
;
976 // Get the FmpHeaderSize so we can determine the real payload size
978 Status
= GetFmpPayloadHeaderSize (FmpPayloadHeader
, FmpPayloadSize
, &FmpHeaderSize
);
979 if (EFI_ERROR (Status
)) {
980 DEBUG ((DEBUG_ERROR
, "FmpDxe: CheckTheImage() - GetFmpPayloadHeaderSize failed %r.\n", Status
));
981 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
982 Status
= EFI_SUCCESS
;
983 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_GET_FMP_HEADER_SIZE
;
988 // Call FmpDevice Lib Check Image on the
989 // Raw payload. So all headers need stripped off
991 AllHeaderSize
= GetAllHeaderSize ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, FmpHeaderSize
+ DependenciesSize
);
992 if (AllHeaderSize
== 0) {
993 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetAllHeaderSize failed.\n", mImageIdName
));
994 Status
= EFI_ABORTED
;
995 *LastAttemptStatus
= LAST_ATTEMPT_STATUS_DRIVER_ERROR_GET_ALL_HEADER_SIZE
;
998 RawSize
= ImageSize
- AllHeaderSize
;
1001 // FmpDeviceLib CheckImage function to do any specific checks
1003 Status
= FmpDeviceCheckImage ((((UINT8
*)Image
) + AllHeaderSize
), RawSize
, ImageUpdatable
);
1004 if (EFI_ERROR (Status
)) {
1005 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - FmpDeviceLib CheckImage failed. Status = %r\n", mImageIdName
, Status
));
1013 Checks if the firmware image is valid for the device.
1015 This function allows firmware update application to validate the firmware image without
1016 invoking the SetImage() first.
1018 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1019 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
1020 The number is between 1 and DescriptorCount.
1021 @param[in] Image Points to the new image.
1022 @param[in] ImageSize Size of the new image in bytes.
1023 @param[out] ImageUpdatable Indicates if the new image is valid for update. It also provides,
1024 if available, additional information if the image is invalid.
1026 @retval EFI_SUCCESS The image was successfully checked.
1027 @retval EFI_ABORTED The operation is aborted.
1028 @retval EFI_INVALID_PARAMETER The Image was NULL.
1029 @retval EFI_UNSUPPORTED The operation is not supported.
1030 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
1036 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1037 IN UINT8 ImageIndex
,
1038 IN CONST VOID
*Image
,
1040 OUT UINT32
*ImageUpdatable
1043 UINT32 LastAttemptStatus
;
1045 return CheckTheImageInternal (This
, ImageIndex
, Image
, ImageSize
, ImageUpdatable
, &LastAttemptStatus
);
1049 Updates the firmware image of the device.
1051 This function updates the hardware with the new firmware image.
1052 This function returns EFI_UNSUPPORTED if the firmware image is not updatable.
1053 If the firmware image is updatable, the function should perform the following minimal validations
1054 before proceeding to do the firmware image update.
1055 - Validate the image authentication if image has attribute
1056 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED. The function returns
1057 EFI_SECURITY_VIOLATION if the validation fails.
1058 - Validate the image is a supported image for this device. The function returns EFI_ABORTED if
1059 the image is unsupported. The function can optionally provide more detailed information on
1060 why the image is not a supported image.
1061 - Validate the data from VendorCode if not null. Image validation must be performed before
1062 VendorCode data validation. VendorCode data is ignored or considered invalid if image
1063 validation failed. The function returns EFI_ABORTED if the data is invalid.
1065 VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if
1066 the caller did not specify the policy or use the default policy. As an example, vendor can implement
1067 a policy to allow an option to force a firmware image update when the abort reason is due to the new
1068 firmware image version is older than the current firmware image version or bad image checksum.
1069 Sensitive operations such as those wiping the entire firmware image and render the device to be
1070 non-functional should be encoded in the image itself rather than passed with the VendorCode.
1071 AbortReason enables vendor to have the option to provide a more detailed description of the abort
1072 reason to the caller.
1074 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1075 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
1076 The number is between 1 and DescriptorCount.
1077 @param[in] Image Points to the new image.
1078 @param[in] ImageSize Size of the new image in bytes.
1079 @param[in] VendorCode This enables vendor to implement vendor-specific firmware image update policy.
1080 Null indicates the caller did not specify the policy or use the default policy.
1081 @param[in] Progress A function used by the driver to report the progress of the firmware update.
1082 @param[out] AbortReason A pointer to a pointer to a null-terminated string providing more
1083 details for the aborted operation. The buffer is allocated by this function
1084 with AllocatePool(), and it is the caller's responsibility to free it with a
1087 @retval EFI_SUCCESS The device was successfully updated with the new image.
1088 @retval EFI_ABORTED The operation is aborted.
1089 @retval EFI_INVALID_PARAMETER The Image was NULL.
1090 @retval EFI_UNSUPPORTED The operation is not supported.
1091 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
1097 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1098 IN UINT8 ImageIndex
,
1099 IN CONST VOID
*Image
,
1101 IN CONST VOID
*VendorCode
,
1102 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress
,
1103 OUT CHAR16
**AbortReason
1107 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1109 BOOLEAN BooleanValue
;
1110 UINT32 FmpHeaderSize
;
1112 UINTN FmpPayloadSize
;
1113 UINT32 AllHeaderSize
;
1114 UINT32 IncomingFwVersion
;
1115 UINT32 LastAttemptStatus
;
1117 UINT32 LowestSupportedVersion
;
1118 EFI_FIRMWARE_IMAGE_DEP
*Dependencies
;
1119 UINT32 DependenciesSize
;
1121 Status
= EFI_SUCCESS
;
1124 BooleanValue
= FALSE
;
1129 IncomingFwVersion
= 0;
1130 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL
;
1131 Dependencies
= NULL
;
1132 DependenciesSize
= 0;
1134 if (!FeaturePcdGet (PcdFmpDeviceStorageAccessEnable
)) {
1135 return EFI_UNSUPPORTED
;
1139 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - This is NULL.\n", mImageIdName
));
1140 Status
= EFI_INVALID_PARAMETER
;
1145 // Retrieve the private context structure
1147 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
1148 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1151 // Make sure the descriptor has already been loaded or refreshed
1153 PopulateDescriptor (Private
);
1156 // Set to 0 to clear any previous results.
1158 SetLastAttemptVersionInVariable (Private
, IncomingFwVersion
);
1161 // if we have locked the device, then skip the set operation.
1162 // it should be blocked by hardware too but we can catch here even faster
1164 if (Private
->FmpDeviceLocked
) {
1165 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Device is already locked. Can't update.\n", mImageIdName
));
1166 Status
= EFI_UNSUPPORTED
;
1171 // Call check image to verify the image
1173 Status
= CheckTheImage (This
, ImageIndex
, Image
, ImageSize
, &Updateable
);
1174 if (EFI_ERROR (Status
)) {
1175 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Check The Image failed with %r.\n", mImageIdName
, Status
));
1176 if (Status
== EFI_SECURITY_VIOLATION
) {
1177 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_AUTH_ERROR
;
1183 // Get the dependency from Image.
1185 Dependencies
= GetImageDependency ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, &DependenciesSize
);
1188 // No functional error in CheckTheImage. Attempt to get the Version to
1189 // support better error reporting.
1191 FmpHeader
= GetFmpHeader ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, DependenciesSize
, &FmpPayloadSize
);
1192 if (FmpHeader
== NULL
) {
1193 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetFmpHeader failed.\n", mImageIdName
));
1194 Status
= EFI_ABORTED
;
1197 Status
= GetFmpPayloadHeaderVersion (FmpHeader
, FmpPayloadSize
, &IncomingFwVersion
);
1198 if (!EFI_ERROR (Status
)) {
1200 // Set to actual value
1202 SetLastAttemptVersionInVariable (Private
, IncomingFwVersion
);
1206 if (Updateable
!= IMAGE_UPDATABLE_VALID
) {
1209 "FmpDxe(%s): SetTheImage() - Check The Image returned that the Image was not valid for update. Updatable value = 0x%X.\n",
1210 mImageIdName
, Updateable
)
1212 if (Private
->DependenciesSatisfied
== FALSE
) {
1213 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_UNSATISFIED_DEPENDENCIES
;
1215 Status
= EFI_ABORTED
;
1219 if (Progress
== NULL
) {
1220 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Invalid progress callback\n", mImageIdName
));
1221 Status
= EFI_INVALID_PARAMETER
;
1225 mProgressFunc
= Progress
;
1228 // Checking the image is at least 1%
1230 Status
= Progress (1);
1231 if (EFI_ERROR (Status
)) {
1232 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Progress Callback failed with Status %r.\n", mImageIdName
, Status
));
1236 //Check System Power
1238 Status
= CheckSystemPower (&BooleanValue
);
1239 if (EFI_ERROR (Status
)) {
1240 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemPower - API call failed %r.\n", mImageIdName
, Status
));
1243 if (!BooleanValue
) {
1244 Status
= EFI_ABORTED
;
1247 "FmpDxe(%s): SetTheImage() - CheckSystemPower - returned False. Update not allowed due to System Power.\n", mImageIdName
)
1249 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_PWR_EVT_BATT
;
1256 //Check System Thermal
1258 Status
= CheckSystemThermal (&BooleanValue
);
1259 if (EFI_ERROR (Status
)) {
1260 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemThermal - API call failed %r.\n", mImageIdName
, Status
));
1263 if (!BooleanValue
) {
1264 Status
= EFI_ABORTED
;
1267 "FmpDxe(%s): SetTheImage() - CheckSystemThermal - returned False. Update not allowed due to System Thermal.\n", mImageIdName
)
1275 //Check System Environment
1277 Status
= CheckSystemEnvironment (&BooleanValue
);
1278 if (EFI_ERROR (Status
)) {
1279 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemEnvironment - API call failed %r.\n", mImageIdName
, Status
));
1282 if (!BooleanValue
) {
1283 Status
= EFI_ABORTED
;
1286 "FmpDxe(%s): SetTheImage() - CheckSystemEnvironment - returned False. Update not allowed due to System Environment.\n", mImageIdName
)
1294 // Save LastAttemptStatus as error so that if SetImage never returns the error
1295 // state is recorded.
1297 SetLastAttemptStatusInVariable (Private
, LastAttemptStatus
);
1300 // Strip off all the headers so the device can process its firmware
1302 Status
= GetFmpPayloadHeaderSize (FmpHeader
, FmpPayloadSize
, &FmpHeaderSize
);
1303 if (EFI_ERROR (Status
)) {
1304 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetFmpPayloadHeaderSize failed %r.\n", mImageIdName
, Status
));
1308 AllHeaderSize
= GetAllHeaderSize ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, FmpHeaderSize
+ DependenciesSize
);
1309 if (AllHeaderSize
== 0) {
1310 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetAllHeaderSize failed.\n", mImageIdName
));
1311 Status
= EFI_ABORTED
;
1316 // Indicate that control is handed off to FmpDeviceLib
1321 //Copy the requested image to the firmware using the FmpDeviceLib
1323 Status
= FmpDeviceSetImage (
1324 (((UINT8
*)Image
) + AllHeaderSize
),
1325 ImageSize
- AllHeaderSize
,
1331 if (EFI_ERROR (Status
)) {
1332 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() SetImage from FmpDeviceLib failed. Status = %r.\n", mImageIdName
, Status
));
1337 // Store the dependency
1339 if (Private
->Descriptor
.AttributesSetting
& IMAGE_ATTRIBUTE_DEPENDENCY
) {
1340 Status
= SaveFmpDependency (Dependencies
, DependenciesSize
);
1341 if (EFI_ERROR (Status
)) {
1342 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() SaveFmpDependency from FmpDependencyCheckLib failed. (%r)\n", mImageIdName
, Status
));
1344 Status
= EFI_SUCCESS
;
1348 // Finished the update without error
1349 // Indicate that control has been returned from FmpDeviceLib
1354 // Update the version stored in variable
1356 if (!Private
->RuntimeVersionSupported
) {
1357 Version
= DEFAULT_VERSION
;
1358 GetFmpPayloadHeaderVersion (FmpHeader
, FmpPayloadSize
, &Version
);
1359 SetVersionInVariable (Private
, Version
);
1363 // Update lowest supported variable
1365 LowestSupportedVersion
= DEFAULT_LOWESTSUPPORTEDVERSION
;
1366 GetFmpPayloadHeaderLowestSupportedVersion (FmpHeader
, FmpPayloadSize
, &LowestSupportedVersion
);
1367 SetLowestSupportedVersionInVariable (Private
, LowestSupportedVersion
);
1369 LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
1372 mProgressFunc
= NULL
;
1374 if (Private
!= NULL
) {
1375 SetLastAttemptStatusInVariable (Private
, LastAttemptStatus
);
1378 if (Progress
!= NULL
) {
1380 // Set progress to 100 after everything is done including recording Status.
1386 // Need repopulate after SetImage is called to
1387 // update LastAttemptVersion and LastAttemptStatus.
1389 if (Private
!= NULL
) {
1390 Private
->DescriptorPopulated
= FALSE
;
1397 Returns information about the firmware package.
1399 This function returns package information.
1401 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1402 @param[out] PackageVersion A version number that represents all the firmware images in the device.
1403 The format is vendor specific and new version must have a greater value
1404 than the old version. If PackageVersion is not supported, the value is
1405 0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version
1406 comparison is to be performed using PackageVersionName. A value of
1407 0xFFFFFFFD indicates that package version update is in progress.
1408 @param[out] PackageVersionName A pointer to a pointer to a null-terminated string representing
1409 the package version name. The buffer is allocated by this function with
1410 AllocatePool(), and it is the caller's responsibility to free it with a
1412 @param[out] PackageVersionNameMaxLen The maximum length of package version name if device supports update of
1413 package version name. A value of 0 indicates the device does not support
1414 update of package version name. Length is the number of Unicode characters,
1415 including the terminating null character.
1416 @param[out] AttributesSupported Package attributes that are supported by this device. See 'Package Attribute
1417 Definitions' for possible returned values of this parameter. A value of 1
1418 indicates the attribute is supported and the current setting value is
1419 indicated in AttributesSetting. A value of 0 indicates the attribute is not
1420 supported and the current setting value in AttributesSetting is meaningless.
1421 @param[out] AttributesSetting Package attributes. See 'Package Attribute Definitions' for possible returned
1422 values of this parameter
1424 @retval EFI_SUCCESS The package information was successfully returned.
1425 @retval EFI_UNSUPPORTED The operation is not supported.
1431 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1432 OUT UINT32
*PackageVersion
,
1433 OUT CHAR16
**PackageVersionName
,
1434 OUT UINT32
*PackageVersionNameMaxLen
,
1435 OUT UINT64
*AttributesSupported
,
1436 OUT UINT64
*AttributesSetting
1439 return EFI_UNSUPPORTED
;
1443 Updates information about the firmware package.
1445 This function updates package information.
1446 This function returns EFI_UNSUPPORTED if the package information is not updatable.
1447 VendorCode enables vendor to implement vendor-specific package information update policy.
1448 Null if the caller did not specify this policy or use the default policy.
1450 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1451 @param[in] Image Points to the authentication image.
1452 Null if authentication is not required.
1453 @param[in] ImageSize Size of the authentication image in bytes.
1454 0 if authentication is not required.
1455 @param[in] VendorCode This enables vendor to implement vendor-specific firmware
1456 image update policy.
1457 Null indicates the caller did not specify this policy or use
1459 @param[in] PackageVersion The new package version.
1460 @param[in] PackageVersionName A pointer to the new null-terminated Unicode string representing
1461 the package version name.
1462 The string length is equal to or less than the value returned in
1463 PackageVersionNameMaxLen.
1465 @retval EFI_SUCCESS The device was successfully updated with the new package
1467 @retval EFI_INVALID_PARAMETER The PackageVersionName length is longer than the value
1468 returned in PackageVersionNameMaxLen.
1469 @retval EFI_UNSUPPORTED The operation is not supported.
1470 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
1476 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1477 IN CONST VOID
*Image
,
1479 IN CONST VOID
*VendorCode
,
1480 IN UINT32 PackageVersion
,
1481 IN CONST CHAR16
*PackageVersionName
1484 return EFI_UNSUPPORTED
;
1488 Event notification function that is invoked when the event GUID specified by
1489 PcdFmpDeviceLockEventGuid is signaled.
1491 @param[in] Event Event whose notification function is being invoked.
1492 @param[in] Context The pointer to the notification function's context,
1493 which is implementation-dependent.
1497 FmpDxeLockEventNotify (
1503 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1505 if (Context
== NULL
) {
1506 ASSERT (Context
!= NULL
);
1510 Private
= (FIRMWARE_MANAGEMENT_PRIVATE_DATA
*)Context
;
1512 if (!Private
->FmpDeviceLocked
) {
1514 // Lock the firmware device
1516 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1517 Status
= FmpDeviceLock();
1518 if (EFI_ERROR (Status
)) {
1519 if (Status
!= EFI_UNSUPPORTED
) {
1520 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLock() returned error. Status = %r\n", mImageIdName
, Status
));
1522 DEBUG ((DEBUG_WARN
, "FmpDxe(%s): FmpDeviceLock() returned error. Status = %r\n", mImageIdName
, Status
));
1525 Private
->FmpDeviceLocked
= TRUE
;
1530 Function to install FMP instance.
1532 @param[in] Handle The device handle to install a FMP instance on.
1534 @retval EFI_SUCCESS FMP Installed
1535 @retval EFI_INVALID_PARAMETER Handle was invalid
1536 @retval other Error installing FMP
1541 InstallFmpInstance (
1542 IN EFI_HANDLE Handle
1546 EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*Fmp
;
1547 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1550 // Only allow a single FMP Protocol instance to be installed
1552 Status
= gBS
->OpenProtocol (
1554 &gEfiFirmwareManagementProtocolGuid
,
1558 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1560 if (!EFI_ERROR (Status
)) {
1561 return EFI_ALREADY_STARTED
;
1565 // Allocate FMP Protocol instance
1567 Private
= AllocateCopyPool (
1568 sizeof (mFirmwareManagementPrivateDataTemplate
),
1569 &mFirmwareManagementPrivateDataTemplate
1571 if (Private
== NULL
) {
1572 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to allocate memory for private structure.\n", mImageIdName
));
1573 Status
= EFI_OUT_OF_RESOURCES
;
1578 // Initialize private context data structure
1580 Private
->Handle
= Handle
;
1581 Private
->FmpDeviceContext
= NULL
;
1582 Status
= FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1583 if (Status
== EFI_UNSUPPORTED
) {
1584 Private
->FmpDeviceContext
= NULL
;
1585 } else if (EFI_ERROR (Status
)) {
1590 // Make sure the descriptor has already been loaded or refreshed
1592 PopulateDescriptor (Private
);
1594 if (IsLockFmpDeviceAtLockEventGuidRequired ()) {
1596 // Register all UEFI Variables used by this module to be locked.
1598 Status
= LockAllFmpVariables (Private
);
1599 if (EFI_ERROR (Status
)) {
1600 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to register variables to lock. Status = %r.\n", mImageIdName
, Status
));
1602 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): All variables registered to lock\n", mImageIdName
));
1606 // Create and register notify function to lock the FMP device.
1608 Status
= gBS
->CreateEventEx (
1611 FmpDxeLockEventNotify
,
1614 &Private
->FmpDeviceLockEvent
1616 if (EFI_ERROR (Status
)) {
1617 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to register notification. Status = %r\n", mImageIdName
, Status
));
1619 ASSERT_EFI_ERROR (Status
);
1621 DEBUG ((DEBUG_VERBOSE
, "FmpDxe(%s): Not registering notification to call FmpDeviceLock() because mfg mode\n", mImageIdName
));
1625 // Install FMP Protocol and FMP Progress Protocol
1627 Status
= gBS
->InstallMultipleProtocolInterfaces (
1629 &gEfiFirmwareManagementProtocolGuid
, &Private
->Fmp
,
1630 &gEdkiiFirmwareManagementProgressProtocolGuid
, &mFmpProgress
,
1633 if (EFI_ERROR (Status
)) {
1634 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol install error. Status = %r.\n", mImageIdName
, Status
));
1640 if (EFI_ERROR (Status
)) {
1641 if (Private
!= NULL
) {
1642 if (Private
->FmpDeviceLockEvent
!= NULL
) {
1643 gBS
->CloseEvent (Private
->FmpDeviceLockEvent
);
1645 if (Private
->Descriptor
.VersionName
!= NULL
) {
1646 FreePool (Private
->Descriptor
.VersionName
);
1648 if (Private
->FmpDeviceContext
!= NULL
) {
1649 FmpDeviceSetContext (NULL
, &Private
->FmpDeviceContext
);
1651 if (Private
->VersionVariableName
!= NULL
) {
1652 FreePool (Private
->VersionVariableName
);
1654 if (Private
->LsvVariableName
!= NULL
) {
1655 FreePool (Private
->LsvVariableName
);
1657 if (Private
->LastAttemptStatusVariableName
!= NULL
) {
1658 FreePool (Private
->LastAttemptStatusVariableName
);
1660 if (Private
->LastAttemptVersionVariableName
!= NULL
) {
1661 FreePool (Private
->LastAttemptVersionVariableName
);
1663 if (Private
->FmpStateVariableName
!= NULL
) {
1664 FreePool (Private
->FmpStateVariableName
);
1674 Function to uninstall FMP instance.
1676 @param[in] Handle The device handle to install a FMP instance on.
1678 @retval EFI_SUCCESS FMP Installed
1679 @retval EFI_INVALID_PARAMETER Handle was invalid
1680 @retval other Error installing FMP
1685 UninstallFmpInstance (
1686 IN EFI_HANDLE Handle
1690 EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*Fmp
;
1691 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1693 Status
= gBS
->OpenProtocol (
1695 &gEfiFirmwareManagementProtocolGuid
,
1699 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1701 if (EFI_ERROR (Status
)) {
1702 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol open error. Status = %r.\n", mImageIdName
, Status
));
1706 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (Fmp
);
1707 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1709 if (Private
->FmpDeviceLockEvent
!= NULL
) {
1710 gBS
->CloseEvent (Private
->FmpDeviceLockEvent
);
1713 Status
= gBS
->UninstallMultipleProtocolInterfaces (
1715 &gEfiFirmwareManagementProtocolGuid
, &Private
->Fmp
,
1716 &gEdkiiFirmwareManagementProgressProtocolGuid
, &mFmpProgress
,
1719 if (EFI_ERROR (Status
)) {
1720 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol uninstall error. Status = %r.\n", mImageIdName
, Status
));
1724 if (Private
->Descriptor
.VersionName
!= NULL
) {
1725 FreePool (Private
->Descriptor
.VersionName
);
1727 if (Private
->FmpDeviceContext
!= NULL
) {
1728 FmpDeviceSetContext (NULL
, &Private
->FmpDeviceContext
);
1730 if (Private
->VersionVariableName
!= NULL
) {
1731 FreePool (Private
->VersionVariableName
);
1733 if (Private
->LsvVariableName
!= NULL
) {
1734 FreePool (Private
->LsvVariableName
);
1736 if (Private
->LastAttemptStatusVariableName
!= NULL
) {
1737 FreePool (Private
->LastAttemptStatusVariableName
);
1739 if (Private
->LastAttemptVersionVariableName
!= NULL
) {
1740 FreePool (Private
->LastAttemptVersionVariableName
);
1742 if (Private
->FmpStateVariableName
!= NULL
) {
1743 FreePool (Private
->FmpStateVariableName
);
1751 Unloads the application and its installed protocol.
1753 @param ImageHandle Handle that identifies the image to be unloaded.
1754 @param SystemTable The system table.
1756 @retval EFI_SUCCESS The image has been unloaded.
1761 FmpDxeLibDestructor (
1762 IN EFI_HANDLE ImageHandle
,
1763 IN EFI_SYSTEM_TABLE
*SystemTable
1766 if (mFmpSingleInstance
) {
1767 return UninstallFmpInstance (ImageHandle
);
1773 Main entry for this driver/library.
1775 @param[in] ImageHandle Image handle this driver.
1776 @param[in] SystemTable Pointer to SystemTable.
1782 IN EFI_HANDLE ImageHandle
,
1783 IN EFI_SYSTEM_TABLE
*SystemTable
1789 // Verify that a new FILE_GUID value has been provided in the <Defines>
1790 // section of this module. The FILE_GUID is the ESRT GUID that must be
1791 // unique for each updatable firmware image.
1793 if (CompareGuid (&mDefaultModuleFileGuid
, &gEfiCallerIdGuid
)) {
1794 DEBUG ((DEBUG_ERROR
, "FmpDxe: Use of default FILE_GUID detected. FILE_GUID must be set to a unique value.\n"));
1796 return EFI_UNSUPPORTED
;
1800 // Get the ImageIdName value for the EFI_FIRMWARE_IMAGE_DESCRIPTOR from a PCD.
1802 mImageIdName
= (CHAR16
*) PcdGetPtr (PcdFmpDeviceImageIdName
);
1803 if (PcdGetSize (PcdFmpDeviceImageIdName
) <= 2 || mImageIdName
[0] == 0) {
1805 // PcdFmpDeviceImageIdName must be set to a non-empty Unicode string
1807 DEBUG ((DEBUG_ERROR
, "FmpDxe(%g): PcdFmpDeviceImageIdName is an empty string.\n", &gEfiCallerIdGuid
));
1809 return EFI_UNSUPPORTED
;
1813 // Detects if PcdFmpDevicePkcs7CertBufferXdr contains a test key.
1818 // Fill in FMP Progress Protocol fields for Version 1
1820 mFmpProgress
.Version
= 1;
1821 mFmpProgress
.ProgressBarForegroundColor
.Raw
= PcdGet32 (PcdFmpDeviceProgressColor
);
1822 mFmpProgress
.WatchdogSeconds
= PcdGet8 (PcdFmpDeviceProgressWatchdogTimeInSeconds
);
1824 // The lock event GUID is retrieved from PcdFmpDeviceLockEventGuid.
1825 // If PcdFmpDeviceLockEventGuid is not the size of an EFI_GUID, then
1826 // gEfiEndOfDxeEventGroupGuid is used.
1828 mLockGuid
= &gEfiEndOfDxeEventGroupGuid
;
1829 if (PcdGetSize (PcdFmpDeviceLockEventGuid
) == sizeof (EFI_GUID
)) {
1830 mLockGuid
= (EFI_GUID
*)PcdGetPtr (PcdFmpDeviceLockEventGuid
);
1832 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): Lock GUID: %g\n", mImageIdName
, mLockGuid
));
1835 // Register with library the install function so if the library uses
1836 // UEFI driver model/driver binding protocol it can install FMP on its device handle
1837 // If library is simple lib that does not use driver binding then it should return
1838 // unsupported and this will install the FMP instance on the ImageHandle
1840 Status
= RegisterFmpInstaller (InstallFmpInstance
);
1841 if (Status
== EFI_UNSUPPORTED
) {
1842 mFmpSingleInstance
= TRUE
;
1843 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): FmpDeviceLib registration returned EFI_UNSUPPORTED. Installing single FMP instance.\n", mImageIdName
));
1844 Status
= RegisterFmpUninstaller (UninstallFmpInstance
);
1845 if (Status
== EFI_UNSUPPORTED
) {
1846 Status
= InstallFmpInstance (ImageHandle
);
1848 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib RegisterFmpInstaller and RegisterFmpUninstaller do not match.\n", mImageIdName
));
1849 Status
= EFI_UNSUPPORTED
;
1851 } else if (EFI_ERROR (Status
)) {
1852 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib registration returned %r. No FMP installed.\n", mImageIdName
, Status
));
1856 "FmpDxe(%s): FmpDeviceLib registration returned EFI_SUCCESS. Expect FMP to be installed during the BDS/Device connection phase.\n",
1859 Status
= RegisterFmpUninstaller (UninstallFmpInstance
);
1860 if (EFI_ERROR (Status
)) {
1861 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib RegisterFmpInstaller and RegisterFmpUninstaller do not match.\n", mImageIdName
));