Firmware Update
Status: Draft
Overview
This section details the OpenPRoT firmware update mechanism, incorporating the DMTF standards for PLDM and SPDM, while emphasizing the security and resilience principles of the project.
Goals
- To provide a secure and reliable method for updating OpenPRoT firmware.
- To ensure that firmware updates are authenticated and authorized.
- To provide a recovery mechanism in the event of a failed update.
- To align with industry standards for firmware updates (PLDM, SPDM).
Use Cases
- Updating the OpenPRoT firmware itself.
- Updating the firmware of downstream devices managed by OpenPRoT.
- Applying critical security updates and bug fixes.
- Updating firmware to enable new features.
PLDM for Firmware Update
OpenPRoT devices will support PLDM Type 5 version 1.3.0 for Firmware Updates. This will be the primary mechanism for transferring firmware images and metadata to the device. PLDM provides a standardized method for managing firmware updates and is particularly well-suited for out-of-band management scenarios.
PLDM Firmware Update Package
The firmware update package is essential for conveying the information required for the PLDM Firmware Update commands.
Package Header
The package will contain a header that describes the contents of the firmware update package, including:
- Overall packaging version and date.
- Device identifier records to specify the target OpenPRoT devices.
- Downstream device identifier records to describe target downstream devices.
- Component image information, including classification, offset, size, and version.
- A checksum for integrity verification.
- Package Payload: Contains the actual firmware component images to be updated
Package Header Information
| Field | Size (bytes) | Definition |
|---|---|---|
| PackageHeaderIdentifier | 16 | Set to 0x7B291C996DB64208801B0202E6463C78 (v1.3.0 UUID) (big endian) |
| PackageHeaderFormatRevision | 1 | Set to 0x04 (v1.3.0 header format revision) |
| PackageHeaderSize | 2 | The total byte count of this header structure, including fields within the Package Header Information, Firmware Device Identification Area, Downstream Device Identification Area, Component Image Information Area, and Checksum sections. |
| PackageReleaseDateTime | 13 | The date and time when this package was released in timestamp104 formatting. Refer to the PLDM Base Specification for field format definition. |
| ComponentBitmapBitLength | 2 | Number of bits used to represent the bitmap in the ApplicableComponents field for a matching device. This value is a multiple of 8 and is large enough to contain a bit for each component in the package. |
| PackageVersionStringType | 1 | The type of string used in the PackageVersionString field. Refer to DMTF Firmware Update Specification v.1.3.0 Table 33 for values. |
| PackageVersionStringLength | 1 | Length, in bytes, of the PackageVersionString field. |
| PackageVersionString | Variable | Package version information, up to 255 bytes. Contains a variable type string describing the version of this firmware update package. |
| DeviceIDRecordCount | uint8 | The count of firmware device ID records that are defined within this package. |
| FirmwareDeviceIDRecords | Variable | Contains a record, a set of descriptors, and optional package data for each firmware device within the count provided from the DeviceIDRecordCount field. |
Firmware Device ID Descriptor
| Field | Size (bytes) | Definition |
|---|---|---|
| RecordLength | 2 | The total length in bytes for this record. The length includes the RecordLength, DescriptorCount, DeviceUpdateOptionFlags, ComponentImageSetVersionStringType, ComponentSetVersionStringLength, FirmwareDevicePackageDataLength, ApplicableComponents, ComponentImageSetVersionString, and RecordDescriptors, and FirmwareDevicePackageData fields. |
| DescriptorCount | 1 | The number of descriptors included within the RecordDescriptors field for this record. |
| DeviceUpdateOptionFlags | 4 | 32-bit field where each bit represents an update option. bit 0 is set to 1 (Continue component updates after failure). |
| ComponentImageSetVersionStringType | 1 | The type of string used in the ComponentImageSetVersionString field. Refer to DMTF Firmware Update Specification v.1.3.0 Table 33 for values. |
| ComponentImageSetVersionStringLength | 1 | Length, in bytes, of the ComponentImageSetVersionString. |
| FirmwareDevicePackageDataLength | 2 | Length in bytes of the FirmwareDevicePackageData field. If no data is provided, set to 0x0000. |
| ReferenceManifestLength | 4 | Length in bytes of the ReferenceManifestData field. If no data is provided, set to 0x00000000. |
| ApplicableComponents | Variable | Bitmap indicating which firmware components apply to devices matching this Device Identifier record. A set bit indicates the Nth component in the payload is applicable to this device. bit 0: OpenPRoT RT Image bit 1: Downstream SoC Manifest bit 2 : Downstream SoC Firmware bit 3:: Downstream EEPROM |
| ComponentImageSetVersionString | Variable | Component Image Set version information, up to 255 bytes. Describes the version of component images applicable to the firmware device indicated in this record. |
| RecordDescriptors | Variable | These descriptors are defined by the vendor. Refer to DMTF Firmware Update Specification v.1.3.0 Table 7 for details of these fields and the values that can be selected. |
| FirmwareDevicePackageData | Variable | Optional data provided within the firmware update package for the FD during the update process. If FirmwareDevicePackageDataLength is 0x0000, this field contains no data. |
| ReferenceManifestData | Variable | Optional data field containing a Reference Manifest for the firmware update. If present, it describes the firmware update provided by this package. If ReferenceManifestLength is 0x00000000, this field contains no data. |
Downstream Device ID Descriptor
| Field | Size | Definition |
|---|---|---|
| DownstreamDeviceIDRecordCount | 1 | 0 |
Component Image Information
| Field | Size | Definition |
|---|---|---|
| ComponentClassification | 2 | 0x000A: Downstream EEPROM, Downstream SoC Firmware, and OpenPRoT RT Image (Firmware), 0x0001: Downstream SoC Manifest (Other) |
| ComponentIdentifier | 2 | Unique value selected by the FD vendor to distinguish between component images. 0x0001: OpenPRoT RT Image, 0x0002: Downstream SoC Manifest, 0x0003: 0x0003: Downstream EEPROM 0x1000-0xFFFF - Reserved for other vendor-defined SoC images |
| ComponentComparisonStamp | 4 | Value used as a comparison in determining if a firmware component is down-level or up-level. When ComponentOptions bit 1 is set, this field should use a comparison stamp format (e.g., MajorMinorRevisionPatch). If not set, use 0xFFFFFFFF. |
| ComponentOptions | 2 | Refer to ComponentOptions definition in DMTF Firmware Update Specification v.1.3.0 |
| RequestedComponentActivationMethod | 2 | Refer to RequestedComponentActivationMethoddefinition inDMTF Firmware Update Specification v.1.3.0 |
| ComponentLocationOffset | 4 | Offset in bytes from byte 0 of the package header to where the component image begins. |
| ComponentSize | 4 | Size in bytes of the Component image. |
| ComponentVersionStringType | 1 | Type of string used in the ComponentVersionString field. Refer toDMTF Firmware Update Specification v.1.3.0 Table 33 for values. |
| ComponentVersionStringLength | 1 | Length, in bytes, of the ComponentVersionString. |
| ComponentVersionString | Variable | Component version information, up to 255 bytes. Contains a variable type string describing the component version. |
| ComponentOpaqueDataLength | 4 | Length in bytes of the ComponentOpaqueData field. If no data is provided, set to 0x00000000. |
| ComponentOpaqueData | Variable | Optional data transferred to the FD/FDP during the firmware update |
Component Identifiers
| Component Image | Name | Description |
|---|---|---|
| 0x0 | OpenPRoT RT Image | OpenPRoT manifest and firmware images (e.g. BL0, RT firmware). |
| 0x1 | Downstream SoC Manifest | SoC manifest covering firmware images. Used to stage verification of the firmware payload. |
| 0x2 | Downstream SoC Firmware | SoC firmware payload. |
| 0x3 | Downstream EEPROM | Bulk update of downstream EEPROM |
| >= 0x1000 | Vendor defined components |
PLDM Firmware Update Process
The update process will involve the following steps:
- RequestUpdate: The Update Agent (UA) initiates the firmware update by
sending the
RequestUpdatecommand to the OpenPRoT device. We refer to OpenPRoT as the Firmware Device (FD). - GetPackageData: If there is optional package data for the Firmware Device (FD), the UA will transfer it to the FD prior to transferring component images.
- GetDeviceMetaData: The UA may also optionally retrieve FD metadata that will be saved and restored after all components are updated.
- PassComponentTable: The UA will send the
PassComponentTablecommand with information about the component images to be updated. This includes the identifier, component comparison stamp, classification, and version information for each component image. - UpdateComponent: The UA will send the
UpdateComponentcommand for each component, which includes: component classification, component version, component size, and update options. The UA will subsequently transfer component images using theRequestFirmwareDatacommand.. - TransferComplete: After successfully transferring component data, the FD
will send a
TransferCompletecommand. - VerifyComplete: Once a component transfer is complete the FD will perform a verification of the image.
- ApplyComplete: The FD will use the
ApplyCompletecommand to signal that the component image has been successfully applied. - ActivateFirmware: After all components are transferred, the UA sends the
ActivateFirmwarecommand. If self-contained activation is supported, the FD should immediately enable the new component images. Otherwise, the component enters a "pending activation" state which will require a reset to complete the activation. - GetStatus: The UA will periodically use the
GetStatuscommand to detect when the activation process has completed.
For downstream device updates, the UA will use RequestDownstreamDeviceUpdate
to initiate the update sequence on the FDP. The rest of the process is similar,
with the FDP acting as a proxy for the downstream device.
PLDM Firmware Update Error Handling and Recovery
- The PLDM specification defines a set of completion codes for error conditions.
- OpenPRoT will adhere to the timing specifications defined in the PLDM specification (DSP0240 and DSP0267) for command timeouts and retries.
- The
CancelUpdateComponentcommand is available to cancel the update of a component image, and theCancelUpdatecommand can be used to exit from update mode. The UA should attempt to complete the update and avoid cancelling if possible. - OpenPRoT devices will implement a dual-bank approach for firmware
components. This will allow for a fallback to a known-good firmware image in
case of a failed update. If a power loss occurs prior to the
ActivateFirmwarecommand, the FD will continue to use the currently active image, and the UA can restart the firmware update process.