1# PSU firmware update
2
3Author:
4   Lei YU <mine260309@gmail.com> <LeiYU>
5
6Primary assignee:
7   None
8
9Other contributors:
10   Su Xiao <suxiao@inspur.com>
11   Derek Howard <derekh@us.ibm.com>
12
13Created:
14   2019-06-03
15
16
17## Problem Description
18
19There is no support in OpenBMC to update the firmware for PSUs.
20
21
22## Background and References
23
24In OpenBMC, there is an existing interface for [software update][1].
25
26The update process consists of:
271. Uploading an image to the BMC;
282. Processing the image to check the version and purpose of the image;
293. Verifying and activating the image.
30
31Currently, BMC and BIOS firmware update are supported:
32* [phosphor-bmc-code-mgmt][2] implements BMC code update, and it supports all
33  the above 3 processes.
34* [openpower-pnor-code-mgmt][3] implements BIOS code update, and it only
35  implements "verifying and activating" the image. It shares the function of
36  the above 1 & 2 processes.
37* Both of the above use the same [Software DBus interface][1].
38
39For PSU firmware update, it is preferred to re-use the same function for the
40above 1 & 2.
41
42
43## Requirements
44
45The PSU firmware shall be updated in the below cases:
461. The user manually invokes the APIs to do the update;
472. After BMC code update and if there is a newer PSU image in the BMC's
48   filesystem, BMC shall update the PSU firmware;
493. When a PSU is replaced and the version is older than the one in BMC's
50   filesystem, BMC shall update the PSU firmware.
514. There are cases that a system could use different models of PSUs, and thus
52   different PSU firmware images need to be supported.
53
54For some PSUs, it is risky to do PSU code update while the host is running to
55avoid power loss. This shall be handled by PSU vendor-specific tools, but not
56in the generic framework.
57
58Note: The "vendor-specific" referred below is the PSU vendor-specific.
59
60So the below checks are optional and expected to be handled by vendor-specific
61tool:
621. If the host is powered off;
632. If the redundant PSUs are all connected;
643. If the AC input and DC standby output is OK on all the PSUs;
65
66
67## Proposed Design
68
69As described in the above requirements, there are different cases where the
70PSU firmware is updated:
71* When the APIs are invoked;
72* When a new version is updated together with BMC code update;
73* When a PSU is replaced with an old version of the firmware.
74
75### Update by API
76
77This method is usually used by users who manually update PSU firmware.
78
79It will re-use the current interfaces to upload, verify, and activate the
80image.
81
821. The "Version" interface needs to be extended:
83   * Add a new [VersionPurpose][4] for PSU;
84   * Re-use the existing `ExtendedVersion` as an additional string for
85     vendor-specific purpose, e.g. to indicate the PSU model.
862. Re-use the existing functions implemented by [phosphor-bmc-code-mgmt][2] for
87   uploading and processing the image.
88   * The PSU update image shall be a tarball that consists of a MANIFEST,
89     images, and signatures.
90   * When the PSU image is uploaded and processed, a `VersionObject` shall be
91     created to indicate the version and its purpose.
923. There will be a new service that implements the [Activation][5] interface to
93   update the PSU firmware.
94   * The service will be started by default when BMC starts;
95   * On start, the service will check the PSU's existing firmware and create
96     the `Version` and `Activation` interfaces.
97   * The service shall watch the interface added on
98     `/xyz/openbmc_project/Software`.
99   * When a new object with PSU `VersionPurpose` is added, the service will
100     verify the signature of the image;
101   * The service shall check the `ExtendedVersion` to make sure the image
102     matches the PSU model.
103   * The service will have a configuration file to describe the PSU model and
104     its related vendor-specific tools.
105   * The service will find the matched vendor-specific tool to perform the code
106     update.
107     For example, if a vendor specific tool `foo` is configured in
108     `psu-update@foo.service` which executes `foo psu.bin`, the service will
109     find the `psu-update@foo.service` and start it by systemd, which performs
110     the update.
111   * When the PSU code update is completed, an informational event log shall be
112     created.
113   * When the PSU code update is completed, the image, MANIFEST, and optionally
114     the signature will be saved to a pre-defined directory in read-write
115     filesystem for future use, in case a new PSU with old firmware is plugged.
1164. The vendor-specific tool shall run all the checks it needs to be run, before
117   and after the PSU update, and return a status to the above service to
118   indicate the result.
1195. When the vendor-specific tool returns errors, the PSU update will be aborted
120   and an error event log shall be created.
1216. During the update, the service shall set the related sensors to
122   non-functional, and when the update is done, it shall set the related
123   sensors back to functional.
124
125### Update by new BMC image
126
127When BMC is updated and a new version of PSU firmware is included, it shall be
128updated to the PSU.
129This will be done by the same service described above.
130
1311. On start, the service will check the PSU image, model and version in its
132   filesystem, compare with the ones in PSU hardware and decide if PSU firmware
133   update shall be performed.
1342. There could be two places containing the PSU images:
135   * The pre-defined directory in read-only filesystem, which is part of BMC
136     image.
137   * The other pre-defined directory in read-write filesystem, which is the
138     location for the saved PSU images by API update.
139   Both places shall be checked and a newer version will be selected to compare
140   with the PSU hardware.
1413. If PSU update is needed, the service will find the matched vendor-specific
142   tool to perform the code update.
1434. The following process will be the same as [Update by API].
144
145### Update on replaced PSU
146
147When a PSU is replaced, and the firmware version is older than the one in BMC
148filesystem, it shall be updated.
149This will be done by the same service described above.
150
1511. On start, the service will subscribe to the PropertiesChanged signal to
152   the PSU object path to monitor the PSU presence status.
153   (Or maybe subscribe the InterfacesAdded/Removed signal?)
1542. When a PSU's presence status is changed from false to true (or the
155   InterfacesAdded event occurs), the service will check the new PSU's model,
156   firmware version to decide if the firmware needs to be updated.
1573. If yes, the service will find the matched vendor-specific tool to perform
158   the code update.
1594. The following process will be the same as [Update by API].
160
161## Alternatives Considered
162
163### General implementation
164
165The PSU firmware update could be implemented by separated recipes that only
166call vendor-specific tools.
167It will be a bit simpler but loses the unified interface provided by OpenBMC's
168existing [software update interface][1], and thus it will become difficult to
169use a standard API to the PSU firmware update.
170
171### VersionPurpose
172It is possible to re-use the `VersionPurpose.Other` to represent the PSU
173image's version purpose.
174But that requires additional information about the image, otherwise, there is
175no way to tell if the image is for PSU, or CPLD, or other peripherals.
176A new `VersionPurpose.PSU` is more specific and makes it easier to implement
177and friendly for the user.
178
179### Additional string
180The design proposal uses `ExtendedVersion` as the additional string for
181vendor-specific purpose, e.g. to indicate the PSU model, so the implementation
182could check and compare if the image matches the PSU model.
183It is possible to make it optional or remove this additional string, then the
184implementation will not verify if the image matches the PSU. It could be OK if
185we trust the user who is uploading the correct image, especially the image
186shall be signed.
187But it is always risky in case the image does not match the PSU, and cause
188unintended damage if the incorrect PSU firmware is updated.
189
190
191## Impacts
192
193This design only introduces a new `VersionPurpose` enum into the dbus
194interfaces.
195The newly introduced PSU firmware update service will be a new service that
196implements existing [Activation][5] interface.
197There will be new configuration files for the service to:
198* Link the vendor specific tool with PSU models.
199* Get the sensors related to the PSU.
200* etc.
201
202So the impacts are minimal to existing systems.
203
204
205## Testing
206
207It requires the manual tests to verify the PSU code update process.
208* Verify the PSU code update is done on all PSUs successfully;
209* Verify the PSU code update will fail if the vendor-specific tool fails on
210  pre-condition check, of fails on updating PSU.
211* Verify the PSU code update is performed after a new BMC image is updated
212  containing a new version of PSU firmware.
213* Verify the PSU code update is performed after a PSU with old firmware is
214  plugged in.
215
216
217[1]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software
218[2]: https://github.com/openbmc/phosphor-bmc-code-mgmt/
219[3]: https://github.com/openbmc/openpower-pnor-code-mgmt/
220[4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/57b878d048f929643276f1bf7fdf750abc4bde8b/xyz/openbmc_project/Software/Version.interface.yaml#L14
221[5]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Activation.interface.yaml
222
223