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.
725 @retval EFI_SUCCESS The image was successfully checked.
726 @retval EFI_ABORTED The operation is aborted.
727 @retval EFI_INVALID_PARAMETER The Image was NULL.
728 @retval EFI_UNSUPPORTED The operation is not supported.
729 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
735 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
737 IN CONST VOID
*Image
,
739 OUT UINT32
*ImageUpdatable
743 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
745 VOID
*FmpPayloadHeader
;
746 UINTN FmpPayloadSize
;
748 UINT32 FmpHeaderSize
;
752 UINTN PublicKeyDataLength
;
753 UINT8
*PublicKeyDataXdr
;
754 UINT8
*PublicKeyDataXdrEnd
;
755 EFI_FIRMWARE_IMAGE_DEP
*Dependencies
;
756 UINT32 DependenciesSize
;
758 Status
= EFI_SUCCESS
;
760 FmpPayloadHeader
= NULL
;
766 DependenciesSize
= 0;
768 if (!FeaturePcdGet (PcdFmpDeviceStorageAccessEnable
)) {
769 return EFI_UNSUPPORTED
;
773 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - This is NULL.\n", mImageIdName
));
774 Status
= EFI_INVALID_PARAMETER
;
779 // Retrieve the private context structure
781 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
782 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
785 // Make sure the descriptor has already been loaded or refreshed
787 PopulateDescriptor (Private
);
789 if (ImageUpdatable
== NULL
) {
790 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - ImageUpdatable Pointer Parameter is NULL.\n", mImageIdName
));
791 Status
= EFI_INVALID_PARAMETER
;
796 //Set to valid and then if any tests fail it will update this flag.
798 *ImageUpdatable
= IMAGE_UPDATABLE_VALID
;
801 // Set to satisfied and then if dependency evaluates to false it will update this flag.
803 Private
->DependenciesSatisfied
= TRUE
;
806 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - Image Pointer Parameter is NULL.\n", mImageIdName
));
808 // not sure if this is needed
810 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
811 return EFI_INVALID_PARAMETER
;
814 PublicKeyDataXdr
= PcdGetPtr (PcdFmpDevicePkcs7CertBufferXdr
);
815 PublicKeyDataXdrEnd
= PublicKeyDataXdr
+ PcdGetSize (PcdFmpDevicePkcs7CertBufferXdr
);
817 if (PublicKeyDataXdr
== NULL
|| (PublicKeyDataXdr
== PublicKeyDataXdrEnd
)) {
818 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Invalid certificate, skipping it.\n", mImageIdName
));
819 Status
= EFI_ABORTED
;
822 // Try each key from PcdFmpDevicePkcs7CertBufferXdr
824 for (Index
= 1; PublicKeyDataXdr
< PublicKeyDataXdrEnd
; Index
++) {
828 "FmpDxe(%s): Certificate #%d [%p..%p].\n",
836 if ((PublicKeyDataXdr
+ sizeof (UINT32
)) > PublicKeyDataXdrEnd
) {
838 // Key data extends beyond end of PCD
840 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Certificate size extends beyond end of PCD, skipping it.\n", mImageIdName
));
841 Status
= EFI_ABORTED
;
845 // Read key length stored in big-endian format
847 PublicKeyDataLength
= SwapBytes32 (*(UINT32
*)(PublicKeyDataXdr
));
849 // Point to the start of the key data
851 PublicKeyDataXdr
+= sizeof (UINT32
);
852 if (PublicKeyDataXdr
+ PublicKeyDataLength
> PublicKeyDataXdrEnd
) {
854 // Key data extends beyond end of PCD
856 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Certificate extends beyond end of PCD, skipping it.\n", mImageIdName
));
857 Status
= EFI_ABORTED
;
860 PublicKeyData
= PublicKeyDataXdr
;
861 Status
= AuthenticateFmpImage (
862 (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
,
867 if (!EFI_ERROR (Status
)) {
870 PublicKeyDataXdr
+= PublicKeyDataLength
;
871 PublicKeyDataXdr
= (UINT8
*)ALIGN_POINTER (PublicKeyDataXdr
, sizeof (UINT32
));
875 if (EFI_ERROR (Status
)) {
876 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - Authentication Failed %r.\n", mImageIdName
, Status
));
881 // Check to make sure index is 1
883 if (ImageIndex
!= 1) {
884 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckImage() - Image Index Invalid.\n", mImageIdName
));
885 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID_TYPE
;
886 Status
= EFI_INVALID_PARAMETER
;
891 // Get the dependency from Image.
893 Dependencies
= GetImageDependency ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, &DependenciesSize
);
896 // Check the FmpPayloadHeader
898 FmpPayloadHeader
= GetFmpHeader ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, DependenciesSize
, &FmpPayloadSize
);
899 if (FmpPayloadHeader
== NULL
) {
900 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetFmpHeader failed.\n", mImageIdName
));
901 Status
= EFI_ABORTED
;
904 Status
= GetFmpPayloadHeaderVersion (FmpPayloadHeader
, FmpPayloadSize
, &Version
);
905 if (EFI_ERROR (Status
)) {
906 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetFmpPayloadHeaderVersion failed %r.\n", mImageIdName
, Status
));
907 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
908 Status
= EFI_SUCCESS
;
913 // Check the lowest supported version
915 if (Version
< Private
->Descriptor
.LowestSupportedImageVersion
) {
918 "FmpDxe(%s): CheckTheImage() - Version Lower than lowest supported version. 0x%08X < 0x%08X\n",
919 mImageIdName
, Version
, Private
->Descriptor
.LowestSupportedImageVersion
)
921 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID_OLD
;
922 Status
= EFI_SUCCESS
;
927 // Evaluate dependency expression
929 Private
->DependenciesSatisfied
= CheckFmpDependency (Private
->Descriptor
.ImageTypeId
, Version
, Dependencies
, DependenciesSize
);
930 if (!Private
->DependenciesSatisfied
) {
931 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - Dependency check failed.\n", mImageIdName
));
932 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
933 Status
= EFI_SUCCESS
;
938 // Get the FmpHeaderSize so we can determine the real payload size
940 Status
= GetFmpPayloadHeaderSize (FmpPayloadHeader
, FmpPayloadSize
, &FmpHeaderSize
);
941 if (EFI_ERROR (Status
)) {
942 DEBUG ((DEBUG_ERROR
, "FmpDxe: CheckTheImage() - GetFmpPayloadHeaderSize failed %r.\n", Status
));
943 *ImageUpdatable
= IMAGE_UPDATABLE_INVALID
;
944 Status
= EFI_SUCCESS
;
949 // Call FmpDevice Lib Check Image on the
950 // Raw payload. So all headers need stripped off
952 AllHeaderSize
= GetAllHeaderSize ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, FmpHeaderSize
+ DependenciesSize
);
953 if (AllHeaderSize
== 0) {
954 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - GetAllHeaderSize failed.\n", mImageIdName
));
955 Status
= EFI_ABORTED
;
958 RawSize
= ImageSize
- AllHeaderSize
;
961 // FmpDeviceLib CheckImage function to do any specific checks
963 Status
= FmpDeviceCheckImage ((((UINT8
*)Image
) + AllHeaderSize
), RawSize
, ImageUpdatable
);
964 if (EFI_ERROR (Status
)) {
965 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): CheckTheImage() - FmpDeviceLib CheckImage failed. Status = %r\n", mImageIdName
, Status
));
973 Updates the firmware image of the device.
975 This function updates the hardware with the new firmware image.
976 This function returns EFI_UNSUPPORTED if the firmware image is not updatable.
977 If the firmware image is updatable, the function should perform the following minimal validations
978 before proceeding to do the firmware image update.
979 - Validate the image authentication if image has attribute
980 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED. The function returns
981 EFI_SECURITY_VIOLATION if the validation fails.
982 - Validate the image is a supported image for this device. The function returns EFI_ABORTED if
983 the image is unsupported. The function can optionally provide more detailed information on
984 why the image is not a supported image.
985 - Validate the data from VendorCode if not null. Image validation must be performed before
986 VendorCode data validation. VendorCode data is ignored or considered invalid if image
987 validation failed. The function returns EFI_ABORTED if the data is invalid.
989 VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if
990 the caller did not specify the policy or use the default policy. As an example, vendor can implement
991 a policy to allow an option to force a firmware image update when the abort reason is due to the new
992 firmware image version is older than the current firmware image version or bad image checksum.
993 Sensitive operations such as those wiping the entire firmware image and render the device to be
994 non-functional should be encoded in the image itself rather than passed with the VendorCode.
995 AbortReason enables vendor to have the option to provide a more detailed description of the abort
996 reason to the caller.
998 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
999 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
1000 The number is between 1 and DescriptorCount.
1001 @param[in] Image Points to the new image.
1002 @param[in] ImageSize Size of the new image in bytes.
1003 @param[in] VendorCode This enables vendor to implement vendor-specific firmware image update policy.
1004 Null indicates the caller did not specify the policy or use the default policy.
1005 @param[in] Progress A function used by the driver to report the progress of the firmware update.
1006 @param[out] AbortReason A pointer to a pointer to a null-terminated string providing more
1007 details for the aborted operation. The buffer is allocated by this function
1008 with AllocatePool(), and it is the caller's responsibility to free it with a
1011 @retval EFI_SUCCESS The device was successfully updated with the new image.
1012 @retval EFI_ABORTED The operation is aborted.
1013 @retval EFI_INVALID_PARAMETER The Image was NULL.
1014 @retval EFI_UNSUPPORTED The operation is not supported.
1015 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
1021 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1022 IN UINT8 ImageIndex
,
1023 IN CONST VOID
*Image
,
1025 IN CONST VOID
*VendorCode
,
1026 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress
,
1027 OUT CHAR16
**AbortReason
1031 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1033 BOOLEAN BooleanValue
;
1034 UINT32 FmpHeaderSize
;
1036 UINTN FmpPayloadSize
;
1037 UINT32 AllHeaderSize
;
1038 UINT32 IncomingFwVersion
;
1039 UINT32 LastAttemptStatus
;
1041 UINT32 LowestSupportedVersion
;
1042 EFI_FIRMWARE_IMAGE_DEP
*Dependencies
;
1043 UINT32 DependenciesSize
;
1045 Status
= EFI_SUCCESS
;
1048 BooleanValue
= FALSE
;
1053 IncomingFwVersion
= 0;
1054 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL
;
1055 Dependencies
= NULL
;
1056 DependenciesSize
= 0;
1058 if (!FeaturePcdGet (PcdFmpDeviceStorageAccessEnable
)) {
1059 return EFI_UNSUPPORTED
;
1063 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - This is NULL.\n", mImageIdName
));
1064 Status
= EFI_INVALID_PARAMETER
;
1069 // Retrieve the private context structure
1071 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (This
);
1072 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1075 // Make sure the descriptor has already been loaded or refreshed
1077 PopulateDescriptor (Private
);
1080 // Set to 0 to clear any previous results.
1082 SetLastAttemptVersionInVariable (Private
, IncomingFwVersion
);
1085 // if we have locked the device, then skip the set operation.
1086 // it should be blocked by hardware too but we can catch here even faster
1088 if (Private
->FmpDeviceLocked
) {
1089 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Device is already locked. Can't update.\n", mImageIdName
));
1090 Status
= EFI_UNSUPPORTED
;
1095 // Call check image to verify the image
1097 Status
= CheckTheImage (This
, ImageIndex
, Image
, ImageSize
, &Updateable
);
1098 if (EFI_ERROR (Status
)) {
1099 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Check The Image failed with %r.\n", mImageIdName
, Status
));
1100 if (Status
== EFI_SECURITY_VIOLATION
) {
1101 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_AUTH_ERROR
;
1107 // Get the dependency from Image.
1109 Dependencies
= GetImageDependency ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, &DependenciesSize
);
1112 // No functional error in CheckTheImage. Attempt to get the Version to
1113 // support better error reporting.
1115 FmpHeader
= GetFmpHeader ( (EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, ImageSize
, DependenciesSize
, &FmpPayloadSize
);
1116 if (FmpHeader
== NULL
) {
1117 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetFmpHeader failed.\n", mImageIdName
));
1118 Status
= EFI_ABORTED
;
1121 Status
= GetFmpPayloadHeaderVersion (FmpHeader
, FmpPayloadSize
, &IncomingFwVersion
);
1122 if (!EFI_ERROR (Status
)) {
1124 // Set to actual value
1126 SetLastAttemptVersionInVariable (Private
, IncomingFwVersion
);
1130 if (Updateable
!= IMAGE_UPDATABLE_VALID
) {
1133 "FmpDxe(%s): SetTheImage() - Check The Image returned that the Image was not valid for update. Updatable value = 0x%X.\n",
1134 mImageIdName
, Updateable
)
1136 if (Private
->DependenciesSatisfied
== FALSE
) {
1137 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_UNSATISFIED_DEPENDENCIES
;
1139 Status
= EFI_ABORTED
;
1143 if (Progress
== NULL
) {
1144 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Invalid progress callback\n", mImageIdName
));
1145 Status
= EFI_INVALID_PARAMETER
;
1149 mProgressFunc
= Progress
;
1152 // Checking the image is at least 1%
1154 Status
= Progress (1);
1155 if (EFI_ERROR (Status
)) {
1156 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - Progress Callback failed with Status %r.\n", mImageIdName
, Status
));
1160 //Check System Power
1162 Status
= CheckSystemPower (&BooleanValue
);
1163 if (EFI_ERROR (Status
)) {
1164 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemPower - API call failed %r.\n", mImageIdName
, Status
));
1167 if (!BooleanValue
) {
1168 Status
= EFI_ABORTED
;
1171 "FmpDxe(%s): SetTheImage() - CheckSystemPower - returned False. Update not allowed due to System Power.\n", mImageIdName
)
1173 LastAttemptStatus
= LAST_ATTEMPT_STATUS_ERROR_PWR_EVT_BATT
;
1180 //Check System Thermal
1182 Status
= CheckSystemThermal (&BooleanValue
);
1183 if (EFI_ERROR (Status
)) {
1184 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemThermal - API call failed %r.\n", mImageIdName
, Status
));
1187 if (!BooleanValue
) {
1188 Status
= EFI_ABORTED
;
1191 "FmpDxe(%s): SetTheImage() - CheckSystemThermal - returned False. Update not allowed due to System Thermal.\n", mImageIdName
)
1199 //Check System Environment
1201 Status
= CheckSystemEnvironment (&BooleanValue
);
1202 if (EFI_ERROR (Status
)) {
1203 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - CheckSystemEnvironment - API call failed %r.\n", mImageIdName
, Status
));
1206 if (!BooleanValue
) {
1207 Status
= EFI_ABORTED
;
1210 "FmpDxe(%s): SetTheImage() - CheckSystemEnvironment - returned False. Update not allowed due to System Environment.\n", mImageIdName
)
1218 // Save LastAttemptStatus as error so that if SetImage never returns the error
1219 // state is recorded.
1221 SetLastAttemptStatusInVariable (Private
, LastAttemptStatus
);
1224 // Strip off all the headers so the device can process its firmware
1226 Status
= GetFmpPayloadHeaderSize (FmpHeader
, FmpPayloadSize
, &FmpHeaderSize
);
1227 if (EFI_ERROR (Status
)) {
1228 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetFmpPayloadHeaderSize failed %r.\n", mImageIdName
, Status
));
1232 AllHeaderSize
= GetAllHeaderSize ((EFI_FIRMWARE_IMAGE_AUTHENTICATION
*)Image
, FmpHeaderSize
+ DependenciesSize
);
1233 if (AllHeaderSize
== 0) {
1234 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() - GetAllHeaderSize failed.\n", mImageIdName
));
1235 Status
= EFI_ABORTED
;
1240 // Indicate that control is handed off to FmpDeviceLib
1245 //Copy the requested image to the firmware using the FmpDeviceLib
1247 Status
= FmpDeviceSetImage (
1248 (((UINT8
*)Image
) + AllHeaderSize
),
1249 ImageSize
- AllHeaderSize
,
1255 if (EFI_ERROR (Status
)) {
1256 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() SetImage from FmpDeviceLib failed. Status = %r.\n", mImageIdName
, Status
));
1261 // Store the dependency
1263 if (Private
->Descriptor
.AttributesSetting
& IMAGE_ATTRIBUTE_DEPENDENCY
) {
1264 Status
= SaveFmpDependency (Dependencies
, DependenciesSize
);
1265 if (EFI_ERROR (Status
)) {
1266 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): SetTheImage() SaveFmpDependency from FmpDependencyCheckLib failed. (%r)\n", mImageIdName
, Status
));
1268 Status
= EFI_SUCCESS
;
1272 // Finished the update without error
1273 // Indicate that control has been returned from FmpDeviceLib
1278 // Update the version stored in variable
1280 if (!Private
->RuntimeVersionSupported
) {
1281 Version
= DEFAULT_VERSION
;
1282 GetFmpPayloadHeaderVersion (FmpHeader
, FmpPayloadSize
, &Version
);
1283 SetVersionInVariable (Private
, Version
);
1287 // Update lowest supported variable
1289 LowestSupportedVersion
= DEFAULT_LOWESTSUPPORTEDVERSION
;
1290 GetFmpPayloadHeaderLowestSupportedVersion (FmpHeader
, FmpPayloadSize
, &LowestSupportedVersion
);
1291 SetLowestSupportedVersionInVariable (Private
, LowestSupportedVersion
);
1293 LastAttemptStatus
= LAST_ATTEMPT_STATUS_SUCCESS
;
1296 mProgressFunc
= NULL
;
1298 if (Private
!= NULL
) {
1299 SetLastAttemptStatusInVariable (Private
, LastAttemptStatus
);
1302 if (Progress
!= NULL
) {
1304 // Set progress to 100 after everything is done including recording Status.
1310 // Need repopulate after SetImage is called to
1311 // update LastAttemptVersion and LastAttemptStatus.
1313 if (Private
!= NULL
) {
1314 Private
->DescriptorPopulated
= FALSE
;
1321 Returns information about the firmware package.
1323 This function returns package information.
1325 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1326 @param[out] PackageVersion A version number that represents all the firmware images in the device.
1327 The format is vendor specific and new version must have a greater value
1328 than the old version. If PackageVersion is not supported, the value is
1329 0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version
1330 comparison is to be performed using PackageVersionName. A value of
1331 0xFFFFFFFD indicates that package version update is in progress.
1332 @param[out] PackageVersionName A pointer to a pointer to a null-terminated string representing
1333 the package version name. The buffer is allocated by this function with
1334 AllocatePool(), and it is the caller's responsibility to free it with a
1336 @param[out] PackageVersionNameMaxLen The maximum length of package version name if device supports update of
1337 package version name. A value of 0 indicates the device does not support
1338 update of package version name. Length is the number of Unicode characters,
1339 including the terminating null character.
1340 @param[out] AttributesSupported Package attributes that are supported by this device. See 'Package Attribute
1341 Definitions' for possible returned values of this parameter. A value of 1
1342 indicates the attribute is supported and the current setting value is
1343 indicated in AttributesSetting. A value of 0 indicates the attribute is not
1344 supported and the current setting value in AttributesSetting is meaningless.
1345 @param[out] AttributesSetting Package attributes. See 'Package Attribute Definitions' for possible returned
1346 values of this parameter
1348 @retval EFI_SUCCESS The package information was successfully returned.
1349 @retval EFI_UNSUPPORTED The operation is not supported.
1355 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1356 OUT UINT32
*PackageVersion
,
1357 OUT CHAR16
**PackageVersionName
,
1358 OUT UINT32
*PackageVersionNameMaxLen
,
1359 OUT UINT64
*AttributesSupported
,
1360 OUT UINT64
*AttributesSetting
1363 return EFI_UNSUPPORTED
;
1367 Updates information about the firmware package.
1369 This function updates package information.
1370 This function returns EFI_UNSUPPORTED if the package information is not updatable.
1371 VendorCode enables vendor to implement vendor-specific package information update policy.
1372 Null if the caller did not specify this policy or use the default policy.
1374 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
1375 @param[in] Image Points to the authentication image.
1376 Null if authentication is not required.
1377 @param[in] ImageSize Size of the authentication image in bytes.
1378 0 if authentication is not required.
1379 @param[in] VendorCode This enables vendor to implement vendor-specific firmware
1380 image update policy.
1381 Null indicates the caller did not specify this policy or use
1383 @param[in] PackageVersion The new package version.
1384 @param[in] PackageVersionName A pointer to the new null-terminated Unicode string representing
1385 the package version name.
1386 The string length is equal to or less than the value returned in
1387 PackageVersionNameMaxLen.
1389 @retval EFI_SUCCESS The device was successfully updated with the new package
1391 @retval EFI_INVALID_PARAMETER The PackageVersionName length is longer than the value
1392 returned in PackageVersionNameMaxLen.
1393 @retval EFI_UNSUPPORTED The operation is not supported.
1394 @retval EFI_SECURITY_VIOLATION The operation could not be performed due to an authentication failure.
1400 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*This
,
1401 IN CONST VOID
*Image
,
1403 IN CONST VOID
*VendorCode
,
1404 IN UINT32 PackageVersion
,
1405 IN CONST CHAR16
*PackageVersionName
1408 return EFI_UNSUPPORTED
;
1412 Event notification function that is invoked when the event GUID specified by
1413 PcdFmpDeviceLockEventGuid is signaled.
1415 @param[in] Event Event whose notification function is being invoked.
1416 @param[in] Context The pointer to the notification function's context,
1417 which is implementation-dependent.
1421 FmpDxeLockEventNotify (
1427 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1429 if (Context
== NULL
) {
1430 ASSERT (Context
!= NULL
);
1434 Private
= (FIRMWARE_MANAGEMENT_PRIVATE_DATA
*)Context
;
1436 if (!Private
->FmpDeviceLocked
) {
1438 // Lock the firmware device
1440 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1441 Status
= FmpDeviceLock();
1442 if (EFI_ERROR (Status
)) {
1443 if (Status
!= EFI_UNSUPPORTED
) {
1444 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLock() returned error. Status = %r\n", mImageIdName
, Status
));
1446 DEBUG ((DEBUG_WARN
, "FmpDxe(%s): FmpDeviceLock() returned error. Status = %r\n", mImageIdName
, Status
));
1449 Private
->FmpDeviceLocked
= TRUE
;
1454 Function to install FMP instance.
1456 @param[in] Handle The device handle to install a FMP instance on.
1458 @retval EFI_SUCCESS FMP Installed
1459 @retval EFI_INVALID_PARAMETER Handle was invalid
1460 @retval other Error installing FMP
1465 InstallFmpInstance (
1466 IN EFI_HANDLE Handle
1470 EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*Fmp
;
1471 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1474 // Only allow a single FMP Protocol instance to be installed
1476 Status
= gBS
->OpenProtocol (
1478 &gEfiFirmwareManagementProtocolGuid
,
1482 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1484 if (!EFI_ERROR (Status
)) {
1485 return EFI_ALREADY_STARTED
;
1489 // Allocate FMP Protocol instance
1491 Private
= AllocateCopyPool (
1492 sizeof (mFirmwareManagementPrivateDataTemplate
),
1493 &mFirmwareManagementPrivateDataTemplate
1495 if (Private
== NULL
) {
1496 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to allocate memory for private structure.\n", mImageIdName
));
1497 Status
= EFI_OUT_OF_RESOURCES
;
1502 // Initialize private context data structure
1504 Private
->Handle
= Handle
;
1505 Private
->FmpDeviceContext
= NULL
;
1506 Status
= FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1507 if (Status
== EFI_UNSUPPORTED
) {
1508 Private
->FmpDeviceContext
= NULL
;
1509 } else if (EFI_ERROR (Status
)) {
1514 // Make sure the descriptor has already been loaded or refreshed
1516 PopulateDescriptor (Private
);
1518 if (IsLockFmpDeviceAtLockEventGuidRequired ()) {
1520 // Register all UEFI Variables used by this module to be locked.
1522 Status
= LockAllFmpVariables (Private
);
1523 if (EFI_ERROR (Status
)) {
1524 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to register variables to lock. Status = %r.\n", mImageIdName
, Status
));
1526 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): All variables registered to lock\n", mImageIdName
));
1530 // Create and register notify function to lock the FMP device.
1532 Status
= gBS
->CreateEventEx (
1535 FmpDxeLockEventNotify
,
1538 &Private
->FmpDeviceLockEvent
1540 if (EFI_ERROR (Status
)) {
1541 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Failed to register notification. Status = %r\n", mImageIdName
, Status
));
1543 ASSERT_EFI_ERROR (Status
);
1545 DEBUG ((DEBUG_VERBOSE
, "FmpDxe(%s): Not registering notification to call FmpDeviceLock() because mfg mode\n", mImageIdName
));
1549 // Install FMP Protocol and FMP Progress Protocol
1551 Status
= gBS
->InstallMultipleProtocolInterfaces (
1553 &gEfiFirmwareManagementProtocolGuid
, &Private
->Fmp
,
1554 &gEdkiiFirmwareManagementProgressProtocolGuid
, &mFmpProgress
,
1557 if (EFI_ERROR (Status
)) {
1558 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol install error. Status = %r.\n", mImageIdName
, Status
));
1564 if (EFI_ERROR (Status
)) {
1565 if (Private
!= NULL
) {
1566 if (Private
->FmpDeviceLockEvent
!= NULL
) {
1567 gBS
->CloseEvent (Private
->FmpDeviceLockEvent
);
1569 if (Private
->Descriptor
.VersionName
!= NULL
) {
1570 FreePool (Private
->Descriptor
.VersionName
);
1572 if (Private
->FmpDeviceContext
!= NULL
) {
1573 FmpDeviceSetContext (NULL
, &Private
->FmpDeviceContext
);
1575 if (Private
->VersionVariableName
!= NULL
) {
1576 FreePool (Private
->VersionVariableName
);
1578 if (Private
->LsvVariableName
!= NULL
) {
1579 FreePool (Private
->LsvVariableName
);
1581 if (Private
->LastAttemptStatusVariableName
!= NULL
) {
1582 FreePool (Private
->LastAttemptStatusVariableName
);
1584 if (Private
->LastAttemptVersionVariableName
!= NULL
) {
1585 FreePool (Private
->LastAttemptVersionVariableName
);
1587 if (Private
->FmpStateVariableName
!= NULL
) {
1588 FreePool (Private
->FmpStateVariableName
);
1598 Function to uninstall FMP instance.
1600 @param[in] Handle The device handle to install a FMP instance on.
1602 @retval EFI_SUCCESS FMP Installed
1603 @retval EFI_INVALID_PARAMETER Handle was invalid
1604 @retval other Error installing FMP
1609 UninstallFmpInstance (
1610 IN EFI_HANDLE Handle
1614 EFI_FIRMWARE_MANAGEMENT_PROTOCOL
*Fmp
;
1615 FIRMWARE_MANAGEMENT_PRIVATE_DATA
*Private
;
1617 Status
= gBS
->OpenProtocol (
1619 &gEfiFirmwareManagementProtocolGuid
,
1623 EFI_OPEN_PROTOCOL_GET_PROTOCOL
1625 if (EFI_ERROR (Status
)) {
1626 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol open error. Status = %r.\n", mImageIdName
, Status
));
1630 Private
= FIRMWARE_MANAGEMENT_PRIVATE_DATA_FROM_THIS (Fmp
);
1631 FmpDeviceSetContext (Private
->Handle
, &Private
->FmpDeviceContext
);
1633 if (Private
->FmpDeviceLockEvent
!= NULL
) {
1634 gBS
->CloseEvent (Private
->FmpDeviceLockEvent
);
1637 Status
= gBS
->UninstallMultipleProtocolInterfaces (
1639 &gEfiFirmwareManagementProtocolGuid
, &Private
->Fmp
,
1640 &gEdkiiFirmwareManagementProgressProtocolGuid
, &mFmpProgress
,
1643 if (EFI_ERROR (Status
)) {
1644 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): Protocol uninstall error. Status = %r.\n", mImageIdName
, Status
));
1648 if (Private
->Descriptor
.VersionName
!= NULL
) {
1649 FreePool (Private
->Descriptor
.VersionName
);
1651 if (Private
->FmpDeviceContext
!= NULL
) {
1652 FmpDeviceSetContext (NULL
, &Private
->FmpDeviceContext
);
1654 if (Private
->VersionVariableName
!= NULL
) {
1655 FreePool (Private
->VersionVariableName
);
1657 if (Private
->LsvVariableName
!= NULL
) {
1658 FreePool (Private
->LsvVariableName
);
1660 if (Private
->LastAttemptStatusVariableName
!= NULL
) {
1661 FreePool (Private
->LastAttemptStatusVariableName
);
1663 if (Private
->LastAttemptVersionVariableName
!= NULL
) {
1664 FreePool (Private
->LastAttemptVersionVariableName
);
1666 if (Private
->FmpStateVariableName
!= NULL
) {
1667 FreePool (Private
->FmpStateVariableName
);
1675 Unloads the application and its installed protocol.
1677 @param ImageHandle Handle that identifies the image to be unloaded.
1678 @param SystemTable The system table.
1680 @retval EFI_SUCCESS The image has been unloaded.
1685 FmpDxeLibDestructor (
1686 IN EFI_HANDLE ImageHandle
,
1687 IN EFI_SYSTEM_TABLE
*SystemTable
1690 if (mFmpSingleInstance
) {
1691 return UninstallFmpInstance (ImageHandle
);
1697 Main entry for this driver/library.
1699 @param[in] ImageHandle Image handle this driver.
1700 @param[in] SystemTable Pointer to SystemTable.
1706 IN EFI_HANDLE ImageHandle
,
1707 IN EFI_SYSTEM_TABLE
*SystemTable
1713 // Verify that a new FILE_GUID value has been provided in the <Defines>
1714 // section of this module. The FILE_GUID is the ESRT GUID that must be
1715 // unique for each updatable firmware image.
1717 if (CompareGuid (&mDefaultModuleFileGuid
, &gEfiCallerIdGuid
)) {
1718 DEBUG ((DEBUG_ERROR
, "FmpDxe: Use of default FILE_GUID detected. FILE_GUID must be set to a unique value.\n"));
1720 return EFI_UNSUPPORTED
;
1724 // Get the ImageIdName value for the EFI_FIRMWARE_IMAGE_DESCRIPTOR from a PCD.
1726 mImageIdName
= (CHAR16
*) PcdGetPtr (PcdFmpDeviceImageIdName
);
1727 if (PcdGetSize (PcdFmpDeviceImageIdName
) <= 2 || mImageIdName
[0] == 0) {
1729 // PcdFmpDeviceImageIdName must be set to a non-empty Unicode string
1731 DEBUG ((DEBUG_ERROR
, "FmpDxe(%g): PcdFmpDeviceImageIdName is an empty string.\n", &gEfiCallerIdGuid
));
1733 return EFI_UNSUPPORTED
;
1737 // Detects if PcdFmpDevicePkcs7CertBufferXdr contains a test key.
1742 // Fill in FMP Progress Protocol fields for Version 1
1744 mFmpProgress
.Version
= 1;
1745 mFmpProgress
.ProgressBarForegroundColor
.Raw
= PcdGet32 (PcdFmpDeviceProgressColor
);
1746 mFmpProgress
.WatchdogSeconds
= PcdGet8 (PcdFmpDeviceProgressWatchdogTimeInSeconds
);
1748 // The lock event GUID is retrieved from PcdFmpDeviceLockEventGuid.
1749 // If PcdFmpDeviceLockEventGuid is not the size of an EFI_GUID, then
1750 // gEfiEndOfDxeEventGroupGuid is used.
1752 mLockGuid
= &gEfiEndOfDxeEventGroupGuid
;
1753 if (PcdGetSize (PcdFmpDeviceLockEventGuid
) == sizeof (EFI_GUID
)) {
1754 mLockGuid
= (EFI_GUID
*)PcdGetPtr (PcdFmpDeviceLockEventGuid
);
1756 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): Lock GUID: %g\n", mImageIdName
, mLockGuid
));
1759 // Register with library the install function so if the library uses
1760 // UEFI driver model/driver binding protocol it can install FMP on its device handle
1761 // If library is simple lib that does not use driver binding then it should return
1762 // unsupported and this will install the FMP instance on the ImageHandle
1764 Status
= RegisterFmpInstaller (InstallFmpInstance
);
1765 if (Status
== EFI_UNSUPPORTED
) {
1766 mFmpSingleInstance
= TRUE
;
1767 DEBUG ((DEBUG_INFO
, "FmpDxe(%s): FmpDeviceLib registration returned EFI_UNSUPPORTED. Installing single FMP instance.\n", mImageIdName
));
1768 Status
= RegisterFmpUninstaller (UninstallFmpInstance
);
1769 if (Status
== EFI_UNSUPPORTED
) {
1770 Status
= InstallFmpInstance (ImageHandle
);
1772 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib RegisterFmpInstaller and RegisterFmpUninstaller do not match.\n", mImageIdName
));
1773 Status
= EFI_UNSUPPORTED
;
1775 } else if (EFI_ERROR (Status
)) {
1776 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib registration returned %r. No FMP installed.\n", mImageIdName
, Status
));
1780 "FmpDxe(%s): FmpDeviceLib registration returned EFI_SUCCESS. Expect FMP to be installed during the BDS/Device connection phase.\n",
1783 Status
= RegisterFmpUninstaller (UninstallFmpInstance
);
1784 if (EFI_ERROR (Status
)) {
1785 DEBUG ((DEBUG_ERROR
, "FmpDxe(%s): FmpDeviceLib RegisterFmpInstaller and RegisterFmpUninstaller do not match.\n", mImageIdName
));