| # 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](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) 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](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) 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](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) 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](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | |
| RequestedComponentActivationMethod | 2 | Refer to RequestedComponentActivationMethoddefinition in[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | |
| 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 to[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) 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: | |
| 1. **RequestUpdate**: The Update Agent (UA) initiates the firmware update by | |
| sending the `RequestUpdate` command to the OpenPRoT device. We refer to | |
| OpenPRoT as the Firmware Device (FD). | |
| 2. **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. | |
| 3. **GetDeviceMetaData**: The UA may also optionally retrieve FD metadata that | |
| will be saved and restored after all components are updated. | |
| 4. **PassComponentTable**: The UA will send the `PassComponentTable` command | |
| with information about the component images to be updated. This includes the | |
| identifier, component comparison stamp, classification, and version | |
| information for each component image. | |
| 5. **UpdateComponent**: The UA will send the `UpdateComponent` command for each | |
| component, which includes: component classification, component version, | |
| component size, and update options. The UA will subsequently transfer | |
| component images using the `RequestFirmwareData` command.. | |
| 6. **TransferComplete**: After successfully transferring component data, the FD | |
| will send a `TransferComplete` command. | |
| 7. **VerifyComplete**: Once a component transfer is complete the FD will | |
| perform a verification of the image. | |
| 8. **ApplyComplete**: The FD will use the `ApplyComplete` command to signal | |
| that the component image has been successfully applied. | |
| 9. **ActivateFirmware**: After all components are transferred, the UA sends the | |
| `ActivateFirmware` command. 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. | |
| 10. **GetStatus**: The UA will periodically use the `GetStatus` command 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 `CancelUpdateComponent` command is available to cancel the update of a | |
| component image, and the `CancelUpdate` command 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 | |
| `ActivateFirmware` command, the FD will continue to use the currently active | |
| image, and the UA can restart the firmware update process. |