<html><head><meta http-equiv="content-type" content="text/html; charset=UTF-8"><style>body { line-height: 1.5; }blockquote { margin-top: 0px; margin-bottom: 0px; margin-left: 0.5em; }body { font-size: 10.5pt; font-family: 'Segoe UI'; color: rgb(0, 0, 0); line-height: 1.5; }</style></head><body>
<div><span></span>T<span style="color: rgb(33, 33, 33); font-family: Roboto, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 13px; orphans: 2; white-space: pre-wrap; widows: 2; line-height: 1.5; background-color: transparent;">his is cool draft for one of the satellite firmware update. Thanks for the good start. </span></div><div><span style="color: rgb(33, 33, 33); font-family: Roboto, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 13px; orphans: 2; white-space: pre-wrap; widows: 2; line-height: 1.5; background-color: transparent;">Have some comments and more considerations, already in the gerrit design review. We can talk more about them.</span></div><div><span style="color: rgb(33, 33, 33); font-family: Roboto, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 13px; orphans: 2; white-space: pre-wrap; widows: 2; line-height: 1.5; background-color: transparent;"><br></span></div>
<div><br></div><hr style="width: 210px; height: 1px;" color="#b5c4df" size="1" align="left">
<div><span><div style="MARGIN: 10px; FONT-FAMILY: verdana; FONT-SIZE: 10pt"><div>yuan.li@linux.intel.com</div></div></span></div>
<blockquote style="margin-Top: 0px; margin-Bottom: 0px; margin-Left: 0.5em"><div> </div><div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm"><div style="PADDING-RIGHT: 8px; PADDING-LEFT: 8px; FONT-SIZE: 12px;FONT-FAMILY:tahoma;COLOR:#000000; BACKGROUND: #efefef; PADDING-BOTTOM: 8px; PADDING-TOP: 8px"><div><b>From:</b> <a href="mailto:mine260309@gmail.com">Lei YU</a></div><div><b>Date:</b> 2019-06-20 10:53</div><div><b>To:</b> <a href="mailto:openbmc@lists.ozlabs.org">OpenBMC Maillist</a></div><div><b>Subject:</b> Re: [Design][v2] PSU firmware update</div></div></div><div><div>This doc is submitted to</div>
<div>https://gerrit.openbmc-project.xyz/c/openbmc/docs/+/22821</div>
<div>Please review the doc in gerrit.</div>
<div>Thanks!</div>
<div> </div>
<div> </div>
<div>On Mon, Jun 17, 2019 at 3:36 PM Lei YU <mine260309@gmail.com> wrote:</div>
<div>></div>
<div>> Hi All,</div>
<div>></div>
<div>> This is the v2-updated design doc of PSU firmware update.</div>
<div>> It will be posted to gerrit for review after we have resolved comments</div>
<div>> in the mailing list.</div>
<div>></div>
<div>> # PSU firmware update</div>
<div>></div>
<div>> Author:</div>
<div>> Lei YU <mine260309@gmail.com> <LeiYU></div>
<div>> Primary assignee:</div>
<div>> None</div>
<div>> Other contributors:</div>
<div>> Su Xiao <suxiao@inspur.com></div>
<div>> Derek Howard <derekh@us.ibm.com></div>
<div>> Created:</div>
<div>> 2019-06-03</div>
<div>></div>
<div>></div>
<div>> ## Problem Description</div>
<div>></div>
<div>> There is no support in OpenBMC to update the firmware for PSUs.</div>
<div>></div>
<div>></div>
<div>> ## Background and References</div>
<div>></div>
<div>> In OpenBMC, there is an existing interface for [software update][1].</div>
<div>></div>
<div>> The update process consists of:</div>
<div>> 1. Uploading an image to BMC;</div>
<div>> 2. Processing the image to check the version and purpose of the image;</div>
<div>> 3. Verifying and activating the image.</div>
<div>></div>
<div>> Currently, BMC and PNOR firmware update are supported:</div>
<div>> * [phosphor-bmc-code-mgmt][2] implements BMC code update, and it supports all</div>
<div>> the above 3 processes.</div>
<div>> * [openpower-pnor-code-mgmt][3] implements PNOR code update, and it only</div>
<div>> implements "verifying and activating" the image. It shares the function of</div>
<div>> the above 1 & 2 processes.</div>
<div>></div>
<div>> For PSU firmware code update, it is preferred to re-use the same function for</div>
<div>> the above 1 & 2.</div>
<div>></div>
<div>></div>
<div>> ## Requirements</div>
<div>></div>
<div>> The PSU firmware shall be updated in the below cases:</div>
<div>> 1. The user manually invoke the APIs to do the update;</div>
<div>> 2. After BMC code update and if there is a newer PSU image in BMC's filesystem,</div>
<div>> BMC shall update the PSU firmware;</div>
<div>> 3. When a PSU is replaced and the version is older than the one in BMC's</div>
<div>> filesystem, BMC shall update the PSU firmware.</div>
<div>> 4. There are cases that a system could use different models of PSUs, and thus</div>
<div>> different PSU firmware images need to be supported.</div>
<div>></div>
<div>> For some PSUs, it is risky to do PSU code update while the host is running to</div>
<div>> avoid power loss. This shall be handled by vendor-specific tools, but not in</div>
<div>> the generic framework.</div>
<div>></div>
<div>> So the below checks are optional and expected to be handled by vendor-specific</div>
<div>> tool:</div>
<div>> 1. If the host is powered off;</div>
<div>> 2. If the redundant PSUs are all connected;</div>
<div>> 3. If the AC input and DC standby output is OK on all the PSUs;</div>
<div>></div>
<div>></div>
<div>> ## Proposed Design</div>
<div>></div>
<div>> As described in the above requirements, there are different cases PSU firmware</div>
<div>> is updated:</div>
<div>> * When the APIs are invoked;</div>
<div>> * When a new version is updated together with BMC code update;</div>
<div>> * When a PSU is replaced with an old version of the firmware.</div>
<div>></div>
<div>> ### Update by API</div>
<div>></div>
<div>> This method is usually used by users who manually update PSU firmware.</div>
<div>></div>
<div>> It will re-use the current interfaces to upload, verify, and activate the</div>
<div>> image.</div>
<div>></div>
<div>> 1. The "Version" interface needs to be extended:</div>
<div>> * Add a new [VersionPurpose][4] for PSU;</div>
<div>> * Re-use the existing ExtendedVersion as an additional string for</div>
<div>> vendor-specific purpose, e.g. to indicate the PSU model.</div>
<div>> 2. Re-use the existing functions implemented by [phosphor-bmc-code-mgmt][2] for</div>
<div>> uploading and processing the image.</div>
<div>> * The PSU update image shall be a tarball consists of a MANIFEST, images,</div>
<div>> and signatures</div>
<div>> 3. There will be a new service that implements the [Activation][5] interface to</div>
<div>> update the PSU firmware.</div>
<div>> * The service will be started by default when BMC starts;</div>
<div>> * On start, the service will check the PSU's existing firmware and create</div>
<div>> the Version and Activation interfaces;</div>
<div>> * The service will verify the signature of the image;</div>
<div>> * The service shall check the ExtendedVersion to make sure the image matches</div>
<div>> the PSU model.</div>
<div>> * The service will have a configure file to describe the PSU model and its</div>
<div>> related vendor-specific tools.</div>
<div>> * The service will find the matched vendor-specific tool to perform the code</div>
<div>> update.</div>
<div>> * When the PSU code update is completed, an informational event log shall be</div>
<div>> created.</div>
<div>> * When the PSU code update is completed, the image, MANIFEST, and optionally</div>
<div>> the signature will be saved to a pre-defined directory in read-write</div>
<div>> filesystem for future use, in case a new PSU with old firmware is plugged.</div>
<div>> 4. The vendor-specific tool shall run all the checks it needs to be run, before</div>
<div>> and after the PSU update, and return a status to the above service to</div>
<div>> indicate the result.</div>
<div>> 5. When the vendor-specific tool returns errors, the PSU update will be aborted</div>
<div>> and an error event log shall be created.</div>
<div>> 6. During the update, the vendor-specific tool shall set the related sensors to</div>
<div>> non-functional, and when the update is done, it shall set the related</div>
<div>> sensors back to functional.</div>
<div>></div>
<div>> ### Update by new BMC image</div>
<div>></div>
<div>> When BMC is updated and a new version of PSU firmware is included, it shall be</div>
<div>> updated to the PSU.</div>
<div>> This will be done by the same service described above.</div>
<div>></div>
<div>> 1. On start, the service will check the PSU image, model and version in its</div>
<div>> filesystem, compare with the ones in PSU hardware and decide if PSU firmware</div>
<div>> update shall be performed.</div>
<div>> 2. There could be two places containing the PSU images:</div>
<div>> * The pre-defined directory in read-only filesystem, which is part of BMC</div>
<div>> image.</div>
<div>> * The other pre-defined directory in read-write filesystem, which is the</div>
<div>> location for the saved PSU images by API update.</div>
<div>> Both places shall be checked and a newer version will be selected to compare</div>
<div>> with the PSU hardware.</div>
<div>> 3. If PSU update is needed, the service will find the matched vendor-specific</div>
<div>> tool to perform the code update.</div>
<div>> 4. The following process will be the same as [Update by API].</div>
<div>></div>
<div>> ### Update on replaced PSU</div>
<div>></div>
<div>> When a PSU is replaced, and the firmware version is older than the one in BMC</div>
<div>> filesystem, it shall be updated.</div>
<div>> This will be done by the same service described above.</div>
<div>></div>
<div>> 1. On start, the service will subscribe to the PropertiesChanged signal to</div>
<div>> the PSU object path to monitor the PSU presence status.</div>
<div>> (Or maybe subscribe the InterfacesAded/Removed signal?)</div>
<div>> 2. When a PSU's presence status is changed from false to true (or the</div>
<div>> InterfacesAdded event occurs), the service will check the new PSU's model,</div>
<div>> firmware version to decide if the firmware needs to be updated.</div>
<div>> 3. If yes, the service will find the matched vendor-specific tool to perform</div>
<div>> the code update.</div>
<div>> 4. The following process will be the same as [Update by API].</div>
<div>></div>
<div>> ## Alternatives Considered</div>
<div>></div>
<div>> ### General implementation</div>
<div>></div>
<div>> The PSU firmware update could be implemented by separated recipes that only</div>
<div>> call vendor-specific tools.</div>
<div>> It will be a bit simpler but loses the unified interface provided by OpenBMC's</div>
<div>> existing [software update interface][1], and thus it will become difficult to</div>
<div>> use a standard API to the PSU firmware update.</div>
<div>></div>
<div>> ### VersionPurpose</div>
<div>> It is possible to re-use the VersionPurpose.Other to represent the PSU image's</div>
<div>> version purpose.</div>
<div>> But that requires additional information about the image, otherwise, there is</div>
<div>> no way to tell if the image is for PSU, or CPLD, or other peripherals.</div>
<div>> A new VersionPurpose.PSU is more specific and makes it easier to implement and</div>
<div>> friendly for the user.</div>
<div>></div>
<div>> ### Additional string</div>
<div>> The design proposal uses ExtendedVersion as the additional string for</div>
<div>> vendor-specific purpose, e.g. to indicate the PSU model, so the implementation</div>
<div>> could check and compare if the image matches the PSU model.</div>
<div>> It is possible to make it optional or remove this additional string, then the</div>
<div>> implementation will not verify if the image matches the PSU. It could be OK if</div>
<div>> we trust the user who is uploading the correct image, especially the image</div>
<div>> shall be signed.</div>
<div>> But it is always risky in case the image does not match the PSU, and cause</div>
<div>> unintended damage if the incorrect PSU firmware is updated.</div>
<div>></div>
<div>></div>
<div>> ## Impacts</div>
<div>></div>
<div>> This design only introduces a new VersionPurpose enum into the dbus interfaces.</div>
<div>> The newly introduced PSU firmware update service will be a new service that</div>
<div>> implements existing [Activation][5] interface.</div>
<div>> So the impacts are minimal to existing systems.</div>
<div>></div>
<div>></div>
<div>> ## Testing</div>
<div>></div>
<div>> It requires the manual tests to verify the PSU code update process.</div>
<div>> * Verify the PSU code update is done on all PSUs successfully;</div>
<div>> * Verify the PSU code update will fail if the vendor-specific tool fails on</div>
<div>> pre-condition check, of fails on updating PSU.</div>
<div>> * Verify the PSU code update is performed after a new BMC image is updated</div>
<div>> containing a new version of PSU firmware.</div>
<div>> * Verify the PSU code update is performed after a PSU with old firmware is</div>
<div>> plugged in.</div>
<div>></div>
<div>></div>
<div>> [1]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/Software</div>
<div>> [2]: https://github.com/openbmc/phosphor-bmc-code-mgmt/</div>
<div>> [3]: https://github.com/openbmc/openpower-pnor-code-mgmt/</div>
<div>> [4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/57b878d048f929643276f1bf7fdf750abc4bde8b/xyz/openbmc_project/Software/Version.interface.yaml#L14</div>
<div>> [5]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Software/Activation.interface.yaml</div>
</div></blockquote>
</body></html>