Skip to content

Commit 6dc787f

Browse files
moidxmoidx
authored
[spec] Initial FW update draft. (#38)
This document is still WIP but it is being open sourced to request feedback from the community. Signed-off-by: Miguel Osorio <[email protected]>
1 parent 04ef745 commit 6dc787f

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎docs/src/specification/services/fwupdate.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Firmware Update
2+
3+
Status: Draft
4+
5+
## Overview
6+
7+
This section details the OpenPRoT firmware update mechanism, incorporating the
8+
DMTF standards for PLDM and SPDM, while emphasizing the security and resilience
9+
principles of the project.
10+
11+
Goals
12+
13+
* To provide a secure and reliable method for updating OpenPRoT firmware.
14+
* To ensure that firmware updates are authenticated and authorized.
15+
* To provide a recovery mechanism in the event of a failed update.
16+
* To align with industry standards for firmware updates (PLDM, SPDM).
17+
18+
Use Cases
19+
20+
* Updating the OpenPRoT firmware itself.
21+
* Updating the firmware of downstream devices managed by OpenPRoT.
22+
* Applying critical security updates and bug fixes.
23+
* Updating firmware to enable new features.
24+
25+
## PLDM for Firmware Update
26+
27+
OpenPRoT devices will support **PLDM Type 5 version 1.3.0** for Firmware
28+
Updates. This will be the primary mechanism for transferring firmware images and
29+
metadata to the device. PLDM provides a standardized method for managing
30+
firmware updates and is particularly well-suited for out-of-band management
31+
scenarios.
32+
33+
### PLDM Firmware Update Package
34+
35+
The firmware update package is essential for conveying the information required
36+
for the PLDM Firmware Update commands.
37+
38+
*Package Header*
39+
40+
The package will contain a header that describes the contents of the firmware
41+
update package, including:
42+
43+
* Overall packaging version and date.
44+
* Device identifier records to specify the target OpenPRoT devices.
45+
* Downstream device identifier records to describe target downstream devices.
46+
* Component image information, including classification, offset, size, and
47+
version.
48+
* A checksum for integrity verification.
49+
* Package Payload: Contains the actual firmware component images to be updated
50+
51+
#### Package Header Information
52+
53+
Field | Size (bytes) | Definition
54+
:-------------------------- | :----------- | :---------
55+
PackageHeaderIdentifier | 16 | Set to 0x7B291C996DB64208801B0202E6463C78 (v1.3.0 UUID) (big endian)
56+
PackageHeaderFormatRevision | 1 | Set to 0x04 (v1.3.0 header format revision)
57+
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.
58+
PackageReleaseDateTime | 13 | The date and time when this package was released in timestamp104 formatting. Refer to the PLDM Base Specification for field format definition.
59+
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.
60+
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.
61+
PackageVersionStringLength | 1 | Length, in bytes, of the PackageVersionString field.
62+
PackageVersionString | Variable | Package version information, up to 255 bytes. Contains a variable type string describing the version of this firmware update package.
63+
DeviceIDRecordCount | uint8 | The count of firmware device ID records that are defined within this package.
64+
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.
65+
66+
#### Firmware Device ID Descriptor
67+
68+
Field | Size (bytes) | Definition
69+
:----------------------------------- | :----------- | :---------
70+
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.
71+
DescriptorCount | 1 | The number of descriptors included within the RecordDescriptors field for this record.
72+
DeviceUpdateOptionFlags | 4 | 32-bit field where each bit represents an update option. bit 0 is set to 1 (Continue component updates after failure).
73+
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.
74+
ComponentImageSetVersionStringLength | 1 | Length, in bytes, of the ComponentImageSetVersionString.
75+
FirmwareDevicePackageDataLength | 2 | Length in bytes of the FirmwareDevicePackageData field. If no data is provided, set to 0x0000.
76+
ReferenceManifestLength | 4 | Length in bytes of the ReferenceManifestData field. If no data is provided, set to 0x00000000.
77+
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
78+
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.
79+
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.
80+
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.
81+
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.
82+
83+
#### Downstream Device ID Descriptor
84+
85+
Field | Size | Definition
86+
:---------------------------- | :--- | :---------
87+
DownstreamDeviceIDRecordCount | 1 | 0
88+
89+
#### Component Image Information
90+
91+
ComponentClassification | 2 | 0x000A: Downstream EEPROM, Downstream SoC Firmware, and OpenPRoT RT Image (Firmware), 0x0001: Downstream SoC Manifest (Other)
92+
:--------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------
93+
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
94+
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.
95+
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)
96+
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)
97+
ComponentLocationOffset | 4 | Offset in bytes from byte 0 of the package header to where the component image begins.
98+
ComponentSize | 4 | Size in bytes of the Component image.
99+
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.
100+
ComponentVersionStringLength | 1 | Length, in bytes, of the ComponentVersionString.
101+
ComponentVersionString | Variable | Component version information, up to 255 bytes. Contains a variable type string describing the component version.
102+
ComponentOpaqueDataLength | 4 | Length in bytes of the ComponentOpaqueData field. If no data is provided, set to 0x00000000.
103+
ComponentOpaqueData | Variable | Optional data transferred to the FD/FDP during the firmware update
104+
105+
## Component Identifiers
106+
107+
| Component Image | Name | Description |
108+
| :-------------- | :------------------------ | :----------------------------- |
109+
| 0x0 | OpenPRoT RT Image | OpenPRoT manifest and firmware |
110+
: : : images (e.g. BL0, RT :
111+
: : : firmware). :
112+
| 0x1 | Downstream SoC Manifest | SoC manifest covering firmware |
113+
: : : images. Used to stage :
114+
: : : verification of the firmware :
115+
: : : payload. :
116+
| 0x2 | Downstream SoC Firmware | SoC firmware payload. |
117+
| 0x3 | Downstream EEPROM | Bulk update of downstream |
118+
: : : EEPROM :
119+
| \>= 0x1000 | Vendor defined components | |
120+
121+
## PLDM Firmware Update Process
122+
123+
The update process will involve the following steps:
124+
125+
1. **RequestUpdate**: The Update Agent (UA) initiates the firmware update by
126+
sending the `RequestUpdate` command to the OpenPRoT device. We refer to
127+
OpenPRoT as the Firmware Device (FD).
128+
2. **GetPackageData**: If there is optional package data for the Firmware
129+
Device (FD), the UA will transfer it to the FD prior to transferring
130+
component images.
131+
3. **GetDeviceMetaData**: The UA may also optionally retrieve FD metadata that
132+
will be saved and restored after all components are updated.
133+
4. **PassComponentTable**: The UA will send the `PassComponentTable` command
134+
with information about the component images to be updated. This includes the
135+
identifier, component comparison stamp, classification, and version
136+
information for each component image.
137+
5. **UpdateComponent**: The UA will send the `UpdateComponent` command for each
138+
component, which includes: component classification, component version,
139+
component size, and update options. The UA will subsequently transfer
140+
component images using the `RequestFirmwareData` command..
141+
6. **TransferComplete**: After successfully transferring component data, the FD
142+
will send a `TransferComplete` command.
143+
7. **VerifyComplete**: Once a component transfer is complete the FD will
144+
perform a verification of the image.
145+
8. **ApplyComplete**: The FD will use the `ApplyComplete` command to signal
146+
that the component image has been successfully applied.
147+
9. **ActivateFirmware**: After all components are transferred, the UA sends the
148+
`ActivateFirmware` command. If self-contained activation is supported, the
149+
FD should immediately enable the new component images. Otherwise, the
150+
component enters a "pending activation" state which will require a reset to
151+
complete the activation.
152+
10. **GetStatus**: The UA will periodically use the `GetStatus` command to
153+
detect when the activation process has completed.
154+
155+
For downstream device updates, the UA will use `RequestDownstreamDeviceUpdate`
156+
to initiate the update sequence on the FDP. The rest of the process is similar,
157+
with the FDP acting as a proxy for the downstream device.
158+
159+
##### PLDM Firmware Update Error Handling and Recovery
160+
161+
* The PLDM specification defines a set of completion codes for error
162+
conditions.
163+
* OpenPRoT will adhere to the timing specifications defined in the PLDM
164+
specification (DSP0240 and DSP0267) for command timeouts and retries.
165+
* The `CancelUpdateComponent` command is available to cancel the update of a
166+
component image, and the `CancelUpdate` command can be used to exit from
167+
update mode. The UA should attempt to complete the update and avoid
168+
cancelling if possible.
169+
* OpenPRoT devices **will implement a dual-bank approach for firmware**
170+
components. This will allow for a fallback to a known-good firmware image in
171+
case of a failed update. If a power loss occurs prior to the
172+
`ActivateFirmware` command, the FD will continue to use the currently active
173+
image, and the UA can restart the firmware update process.

0 commit comments

Comments
 (0)