docs/designs/psu-firmware-update.md

1 # PSU firmware update
32 For PSU firmware update, it is preferred to re-use the same function for the
37 The PSU firmware shall be updated in the below cases:
40 2. After BMC code update and if there is a newer PSU image in the BMC's
41    filesystem, BMC shall update the PSU firmware;
42 3. When a PSU is replaced and the version is older than the one in BMC's
43    filesystem, BMC shall update the PSU firmware.
45    above cases regardless of which PSU image is newer.
47    different PSU firmware images need to be supported.
49 For some PSUs, it is risky to do PSU code update while the host is running to
50 avoid power loss. This shall be handled by PSU vendor-specific tools, but not in
53 Note: The "vendor-specific" referred below is the PSU vendor-specific.
64 As described in the above requirements, there are different cases where the PSU
69 - When a PSU is replaced with an old version of the firmware.
73 This method is usually used by users who manually update PSU firmware.
78    - Add a new [VersionPurpose][4] for PSU;
80      vendor-specific purpose, e.g. to indicate the PSU model.
83    - The PSU update image shall be a tarball that consists of a MANIFEST,
85    - When the PSU image is uploaded and processed, a `VersionObject` shall be
88    update the PSU firmware.
90    - On start, the service will check the PSU's existing firmware and create the
94    - When a new object with PSU `VersionPurpose` is added, the service will
97      matches the PSU model.
98    - The service will have a configuration file to describe the PSU model and
102      `psu-update@foo.service` which executes `foo psu.bin`, the service will
103      find the `psu-update@foo.service` and start it by systemd, which performs
105    - When the PSU code update is completed, an informational event log shall be
107    - When the PSU code update is completed, the image, MANIFEST, and optionally
109      filesystem for future use, in case a new PSU with old firmware is plugged.
111    and after the PSU update, and return a status to the above service to
113 5. When the vendor-specific tool returns errors, the PSU update will be aborted
121 When BMC is updated and a new version of PSU firmware is included, it shall be
122 updated to the PSU. This will be done by the same service described above.
124 1. On start, the service will check the PSU image, model and version in its
125    filesystem, compare with the ones in PSU hardware and decide if PSU firmware
127 2. There could be two places containing the PSU images:
131      location for the saved PSU images by API update. Both places shall be
132      checked and a newer version will be selected to compare with the PSU
134 3. If PSU update is needed, the service will find the matched vendor-specific
138 ### Update on replaced PSU
140 When a PSU is replaced, and the firmware version is older than the one in BMC
145    PSU object path to monitor the PSU presence status. (Or maybe subscribe the
147 2. When a PSU's presence status is changed from false to true (or the
148    PropertiesChanged event occurs), the service will check the new PSU's model
158 The PSU firmware update could be implemented by separated recipes that only call
161 become difficult to use a standard API to the PSU firmware update.
165 It is possible to re-use the `VersionPurpose.Other` to represent the PSU image's
167 otherwise, there is no way to tell if the image is for PSU, or CPLD, or other
168 peripherals. A new `VersionPurpose.PSU` is more specific and makes it easier to
174 vendor-specific purpose, e.g. to indicate the PSU model, so the implementation
175 could check and compare if the image matches the PSU model. It is possible to
177 not verify if the image matches the PSU. It could be OK if we trust the user who
179 always risky in case the image does not match the PSU, and cause unintended
180 damage if the incorrect PSU firmware is updated.
185 interfaces. The newly introduced PSU firmware update service will be a new
189 - Link the vendor specific tool with PSU models.
190 - Get the sensors related to the PSU.
197 It requires the manual tests to verify the PSU code update process.
199 - Verify the PSU code update is done on all PSUs successfully;
200 - Verify the PSU code update will fail if the vendor-specific tool fails on
201   pre-condition check, of fails on updating PSU.
202 - Verify the PSU code update is performed after a new BMC image is updated
203   containing a new (or different, if 'override' used) version of PSU firmware.
204 - Verify the PSU code update is performed after a PSU with old (or different, if