docs/designs/psu-firmware-update.md

7 Created: 2019-06-03
25 - [phosphor-bmc-code-mgmt][2] implements BMC code update, and it supports all
27 - [openpower-pnor-code-mgmt][3] implements BIOS code update, and it only
30 - Both of the above use the same [Software DBus interface][1].
32 For PSU firmware update, it is preferred to re-use the same function for the
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.
55 So the below checks are optional and expected to be handled by vendor-specific
67 - When the APIs are invoked;
68 - When a new version is updated together with BMC code update;
69 - When a PSU is replaced with an old version of the firmware.
75 It will re-use the current interfaces to upload, verify, and activate the image.
78    - Add a new [VersionPurpose][4] for PSU;
79    - Re-use the existing `ExtendedVersion` as an additional string for
80      vendor-specific purpose, e.g. to indicate the PSU model.
81 2. Re-use the existing functions implemented by [phosphor-bmc-code-mgmt][2] for
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
89    - The service will be started by default when BMC starts;
90    - On start, the service will check the PSU's existing firmware and create the
92    - The service shall watch the interface added on
94    - When a new object with PSU `VersionPurpose` is added, the service will
96    - The service shall check the `ExtendedVersion` to make sure the image
98    - The service will have a configuration file to describe the PSU model and
99      its related vendor-specific tools.
100    - The service will find the matched vendor-specific tool to perform the code
101      update. For example, if a vendor specific tool `foo` is configured in
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
108      the signature will be saved to a pre-defined directory in read-write
110 4. The vendor-specific tool shall run all the checks it needs to be run, before
113 5. When the vendor-specific tool returns errors, the PSU update will be aborted
116    non-functional, and when the update is done, it shall set the related sensors
128    - The pre-defined directory in read-only filesystem, which is part of BMC
130    - The other pre-defined directory in read-write filesystem, which is the
134 3. If PSU update is needed, the service will find the matched vendor-specific
150 3. If yes, the service will find the matched vendor-specific tool to perform the
159 vendor-specific tools. It will be a bit simpler but loses the unified interface
165 It is possible to re-use the `VersionPurpose.Other` to represent the PSU image's
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
189 - Link the vendor specific tool with PSU models.
190 - Get the sensors related to the PSU.
191 - etc.
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
204 - Verify the PSU code update is performed after a PSU with old (or different, if
208   https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software
209 [2]: https://github.com/openbmc/phosphor-bmc-code-mgmt/
210 [3]: https://github.com/openbmc/openpower-pnor-code-mgmt/
212 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/57b878d048f929643276f1bf7fdf750abc4bde8b/…
214 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/…