- Notifications
You must be signed in to change notification settings - Fork349
Capsule Based System Firmware Update DSC FDF
Back toCapsule Based System Firmware Update
Add the followingCAPSULE_ENABLE define to the[Defines] section with a defaultvalue ofFALSE. The capsule-based system firmware update feature can be enabled bypassing in-D CAPSULE_ENABLE flag on to the EDK II build command.
# # Used to enable/disable capsule update features. The default is FALSE for disabled. # Add -D CAPSULE_ENABLE to the build command line to enable capsule update features. # The build process generates a capsule update image along with the UEFI application # CapsuleApp.efi. These 2 files must be transferred to storage media to in order for # a user to boot to UEFI Shell and use CapsuleApp.efi to submit the signed capsule. # Once the system is rebooted, the signed capsule is authenticated and the firmware is # update with the new system firmware version. # DEFINE CAPSULE_ENABLE = FALSEMake sure the following library mappings are in the[LibraryClasses] section. The path tothePlatformFlashAccessLib must be updated to match the path to the implementation providedin the previous step. These library mappings are required to support building the modules thatprovide the Firmware Management Protocol for the system firmware, the UEFI application to testcapsule-based firmware update, along with the modules that authenticate a signed system firmwareupdate capsule
[LibraryClasses] OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf BaseCryptLib|CryptoPkg/Library/BaseCryptLib/BaseCryptLib.inf!if $(CAPSULE_ENABLE) CapsuleLib|MdeModulePkg/Library/DxeCapsuleLibFmp/DxeCapsuleLib.inf!else CapsuleLib|MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.inf!endif EdkiiSystemCapsuleLib|SignedCapsulePkg/Library/EdkiiSystemCapsuleLib/EdkiiSystemCapsuleLib.inf FmpAuthenticationLib|MdeModulePkg/Library/FmpAuthenticationLibNull/FmpAuthenticationLibNull.inf IniParsingLib|SignedCapsulePkg/Library/IniParsingLib/IniParsingLib.inf PlatformFlashAccessLib|<Your Platform Package>/Feature/Capsule/Library/PlatformFlashAccessLib/PlatformFlashAccessLibDxe.infMake sure the following library mappings are in the[LibraryClasses.common.DXE_RUNTIME_DRIVER]
[LibraryClasses.common.DXE_RUNTIME_DRIVER]!if $(CAPSULE_ENABLE) CapsuleLib|MdeModulePkg/Library/DxeCapsuleLibFmp/DxeRuntimeCapsuleLib.inf!endifAdd the PCD
PcdEdkiiSystemFirmwareImageDescriptorto the[PcdsDynamicExDefault]section with a value of{0x0}and a maximum size large enough to hold theEDKII_SYSTEM_FIRMWARE_IMAGE_DESCRIPTORstructure and its associated Unicode stringsthat are implemented in the.aslcfile describedhere.Add the PCD
PcdSystemFmpCapsuleImageTypeIdGuidto the same[PcdsDynamicExDefault]section. This PCD is an array of one or moreIMAGE_TYPE_ID_GUIDvalues. In the simplestconfiguration, this PCD is set to the oneIMAGE_TYPE_ID_GUIDvalue from the the.aslcfile describedhere.The PCD value is an array of 16-bytes.Add the PCD
PcdEdkiiSystemFirmwareFileGuidto the same[PcdsDynamicExDefault]section. This PCD is set to a GUID value that is an array of 16-bytes. The GUIDvalue may be set to the same GUID value in theFileGuidstatement from the System FirmwareUpdate Configuration INI file describedhere.In the simplest configuration, this PCD is set in the DSC file to theFileGuidvalue from theINI file.
NOTE: The INI file syntax does support more complex capsule-base system firmware updatescenarios where the capsule may contain multiple FFS files with update content to supportmultiple platforms or boards. For this use case, a platform module must detect the currentplatform or board and set the appropriatePcdEdkiiSystemFirmwareFileGuid value.
The example below uses aPcdEdkiiSystemFirmwareImageDescriptor size of 0x100 bytes, asingle GUID value forPcdSystemFmpCapsuleImageTypeIdGuid, and a GUID value forPcdEdkiiSystemFirmwareFileGuid that matchesFileGuid statement in the INI file.
[PcdsDynamicExDefault.common.DEFAULT]!if $(CAPSULE_ENABLE) gEfiSignedCapsulePkgTokenSpaceGuid.PcdEdkiiSystemFirmwareImageDescriptor|{0x0}|VOID*|0x100 gEfiMdeModulePkgTokenSpaceGuid.PcdSystemFmpCapsuleImageTypeIdGuid|{0xc0, 0x20, 0xaf, 0x62, 0x16, 0x70, 0x4a, 0x42, 0x9b, 0xf8, 0x9c, 0xcc, 0x86, 0x58, 0x40, 0x90} gEfiSignedCapsulePkgTokenSpaceGuid.PcdEdkiiSystemFirmwareFileGuid|{0x31, 0x1c, 0x96, 0x20, 0xdc, 0x66, 0xa5, 0x48, 0x89, 0x1c, 0x25, 0x43, 0x8b, 0xde, 0x14, 0x30}!endifAdd the platform specific System Firmware Descriptor PEIM implemented in an earlier step tothe[Components] section with the rest of the PEIMs.NOTE: The example below uses aPEI CPU architecture of IA32. Replace IA32 with PEI CPU Architecture for your platform.
[Components.IA32]!if $(CAPSULE_ENABLE) # FMP image descriptor <Your Platform Package>/Feature/Capsule/SystemFirmwareDescriptor/SystemFirmwareDescriptor.inf!endifUpdate BdsDxe.inf<LibraryClasses> section to use the PKCS7 based FMP Authentication Libraryfrom theSecurityPkg. IfCAPSULE_ENABLE isFALSE, then use the Null FMP Authentication Library.IfCAPSULE_ENABLE isTRUE, then add the EsrtDxe module, the SystemFirmwareUpdateDxe module,and the UEFI Application CapsuleApp to the[Components] section.NOTE: The example below uses aDXE CPU architecture of X64. Replace X64 with DXE CPU Architecture for your platform.
[Components.X64] MdeModulePkg/Universal/BdsDxe/BdsDxe.inf { <LibraryClasses>!if $(CAPSULE_ENABLE) FmpAuthenticationLib|SecurityPkg/Library/FmpAuthenticationLibPkcs7/FmpAuthenticationLibPkcs7.inf!else FmpAuthenticationLib|MdeModulePkg/Library/FmpAuthenticationLibNull/FmpAuthenticationLibNull.inf!endif }!if $(CAPSULE_ENABLE) MdeModulePkg/Universal/EsrtDxe/EsrtDxe.inf SignedCapsulePkg/Universal/SystemFirmwareUpdate/SystemFirmwareReportDxe.inf { <LibraryClasses> FmpAuthenticationLib|SecurityPkg/Library/FmpAuthenticationLibPkcs7/FmpAuthenticationLibPkcs7.inf } SignedCapsulePkg/Universal/SystemFirmwareUpdate/SystemFirmwareUpdateDxe.inf { <LibraryClasses> FmpAuthenticationLib|SecurityPkg/Library/FmpAuthenticationLibPkcs7/FmpAuthenticationLibPkcs7.inf } MdeModulePkg/Application/CapsuleApp/CapsuleApp.inf { <LibraryClasses> PcdLib|MdePkg/Library/DxePcdLib/DxePcdLib.inf }!endifAdd the SystemFirmwareDescriptor PEIM implemented in a earlier step to the FV thatcontains other PEIMs so it is dispatched on every boot.
!if $(CAPSULE_ENABLE) # FMP image descriptorINF RuleOverride = FMP_IMAGE_DESC <Your Platform Package>/Feature/Capsule/SystemFirmwareDescriptor/SystemFirmwareDescriptor.inf!endifAdd the EsrtDxe, SystemFirmwareReportDxe, and thetest signing key file to theFV contains other DXE modules so they are dispatched on every boot.
!if $(CAPSULE_ENABLE)INF MdeModulePkg/Universal/EsrtDxe/EsrtDxe.infINF SignedCapsulePkg/Universal/SystemFirmwareUpdate/SystemFirmwareReportDxe.infFILE FREEFORM = PCD(gEfiSignedCapsulePkgTokenSpaceGuid.PcdEdkiiPkcs7TestPublicKeyFileGuid) { SECTION RAW = BaseTools/Source/Python/Pkcs7Sign/TestRoot.cer SECTION UI = "Pkcs7TestRoot" }!endifAdd the following[FV] sections to the platform FDF file to build the FVs thatcontains FFS files with the update payloads. These FVs are added to an FMP payloadthat is wrapped into a capsule that is signed using a PKCS7 certificate.
- The
FILE RAWstatement with the# PcdEdkiiSystemFirmwareFileGuidcomment mustbe updated with the same GUID value as theFileGuidstatements from the System FirmwareUpdate Configuration INI file describedhere.In the simplest configuration, there is only oneFileGuidGUID value used in the INIfile. If an INI file describes updates for multiple platforms or boards, then multipleFileGuidGUID value may be used. AFILE RAWstatement for eachFileGuidvalue must beprovided in the[FV]section.
!if $(CAPSULE_ENABLE)[FV.CapsuleDispatchFv]FvAlignment = 16ERASE_POLARITY = 1MEMORY_MAPPED = TRUESTICKY_WRITE = TRUELOCK_CAP = TRUELOCK_STATUS = TRUEWRITE_DISABLED_CAP = TRUEWRITE_ENABLED_CAP = TRUEWRITE_STATUS = TRUEWRITE_LOCK_CAP = TRUEWRITE_LOCK_STATUS = TRUEREAD_DISABLED_CAP = TRUEREAD_ENABLED_CAP = TRUEREAD_STATUS = TRUEREAD_LOCK_CAP = TRUEREAD_LOCK_STATUS = TRUEINF SignedCapsulePkg/Universal/SystemFirmwareUpdate/SystemFirmwareUpdateDxe.inf[FV.SystemFirmwareUpdateCargo]FvAlignment = 16ERASE_POLARITY = 1MEMORY_MAPPED = TRUESTICKY_WRITE = TRUELOCK_CAP = TRUELOCK_STATUS = TRUEWRITE_DISABLED_CAP = TRUEWRITE_ENABLED_CAP = TRUEWRITE_STATUS = TRUEWRITE_LOCK_CAP = TRUEWRITE_LOCK_STATUS = TRUEREAD_DISABLED_CAP = TRUEREAD_ENABLED_CAP = TRUEREAD_STATUS = TRUEREAD_LOCK_CAP = TRUEREAD_LOCK_STATUS = TRUEFILE RAW = 26961C31-66DC-48A5-891C-25438BDE1430 { # PcdEdkiiSystemFirmwareFileGuid FD = <Your Platform FD Name> }FILE RAW = ce57b167-b0e4-41e8-a897-5f4feb781d40 { # gEdkiiSystemFmpCapsuleDriverFvFileGuid FV = CapsuleDispatchFv }FILE RAW = 812136D3-4D3A-433A-9418-29BB9BF78F6E { # gEdkiiSystemFmpCapsuleConfigFileGuid <Your Platform Package>/Feature/Capsule/SystemFirmwareUpdateConfig/SystemFirmwareUpdateConfig.ini }!endifAdd the following[FmpPayload] section to the platform FDF file to build the FMP payloadand that is wrapped into a capsule that is signed using a PKCS7 certificate.
- The
IMAGE_TYPE_IDstatement with the# PcdSystemFmpCapsuleImageTypeIdGuidcomment mustbe set to theIMAGE_TYPE_ID_GUIDvalue from the the.aslcfile describedhere.
!if $(CAPSULE_ENABLE)[FmpPayload.FmpPayloadSystemFirmwarePkcs7]IMAGE_HEADER_INIT_VERSION = 0x02IMAGE_TYPE_ID = 62af20c0-7016-424a-9bf8-9ccc86584090 # PcdSystemFmpCapsuleImageTypeIdGuidIMAGE_INDEX = 0x1HARDWARE_INSTANCE = 0x0MONOTONIC_COUNT = 0x2CERTIFICATE_GUID = 4AAFD29D-68DF-49EE-8AA9-347D375665A7 # PKCS7FV = SystemFirmwareUpdateCargo!endifAdd the following[Capsule] section to the platform FDF file to wrap the FMP payloadinto capsule that is signed using a PKCS7 certificate.
!if $(CAPSULE_ENABLE)[Capsule.<YourPlatformName>FirmwareUpdateCapsuleFmpPkcs7]CAPSULE_GUID = 6dcbd5ed-e82d-4c44-bda1-7194199ad92a # gEfiFmpCapsuleGuidCAPSULE_FLAGS = PersistAcrossReset,InitiateResetCAPSULE_HEADER_SIZE = 0x20CAPSULE_HEADER_INIT_VERSION = 0x1FMP_PAYLOAD = FmpPayloadSystemFirmwarePkcs7!endifAdd the following[Rule] required to add the platform specific SystemFirmwareDescriptorPEIM to the PEI FV.
[Rule.Common.PEIM.FMP_IMAGE_DESC] FILE PEIM = $(NAMED_GUID) { RAW BIN |.acpi PEI_DEPEX PEI_DEPEX Optional $(INF_OUTPUT)/$(MODULE_NAME).depex PE32 PE32 Align=4K $(INF_OUTPUT)/$(MODULE_NAME).efi UI STRING="$(MODULE_NAME)" Optional VERSION STRING="$(INF_VERSION)" Optional BUILD_NUM=$(BUILD_NUMBER) }Home
Getting Started with EDK II
Build Instructions
EDK II Platforms
EDK II Documents
EDK II Release Planning
Reporting Issues
Reporting Security Issues
Community Information
Inclusive Language
Additional Projects &Tasks
Training
Community Support
Community Virtual Meetings
GHSA GitHub Security Advisories Process (Draft)
Infosec-GHSA-Process-Proposal (Draft)