docs/designs/code-update.md

1 # Code Update Design
19 1. Current code update flow is complex as it involves 3 different daemons -
20    Image Manager, Image Updater and Update Service.
21 2. Update invocation flow has no explicit interface but rather depends upon the
32 - [Code Update Design](https://github.com/openbmc/docs/tree/master/architecture/code-update)
33 - [PLDM for Firmware Update Specification](https://www.dmtf.org/sites/default/files/standards/docum…
34 - [Redfish Firmware Update White Paper](https://www.dmtf.org/sites/default/files/standards/document…
38 1. Able to start an update, given a firmware image and update settings.
39    - Update settings shall be able to specify when to apply the image, for
42 2. Able to retrieve the update progress and status.
46    a firmware update.
47 5. Update request shall respond back immediately, so client can query the status
48    while update is in progress.
50 7. Able to support update for different type of hardware components such as
53 9. Able to update multiple hardware components of same type running different
57 10. Able to update multiple components in parallel.
59     update while the code update is in flight.
60 12. Able to update the components with a multi part image when no Targets are
78 CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at /xyz/openbmc_project/Sof…
83 CL ->> BMCW: HTTP POST: /redfish/v1/UpdateService/update <br> (Image, settings, RedfishTargetURIArr…
94   CU ->> CU: << Delegate Update for asynchronous processing >>
102           BMCW --) BMCW: Process notifications<br> and update Task attributes
106   and << Asynchronous Update in Progress >>
120       note over CU: Start Update
124       note over CU: Finish Update
131           CU ->> CU: Update functional association to System Inventory Item
132           CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at ObjectPath
142   above flow) handling its update process and would need to implement the
145 - Since, there would be single daemon handling the update (as compared to
151 The DBus Interface for code update will consist of following -
155 …Update](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/65738)                    …
156 …ew      | Interface to identify the multi part updater which can do code update based on the multi…
160 …ng   |                     Signifies barrier for state transitions while update is in progress    …
164 Introduction of xyz.openbmc_project.Software.Update interface streamlines the
165 update invocation flow and hence addresses the [Issue# 2](#problem-description)
197 xyz.openbmc_project.Software.Update.StartUpdate return value will propagate any
199 Any asynchronous errors which happen during the update process will be notified
201 update. Also, a phosphor-logging event will be created and sent back to client
218 [Firmware Update Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP026…
221 update images for non-PLDM devices as well. For such devices, the CodeUpdater
269 ### Pre and Post Update Conditions
272 executed before or after the update process. One such example of a post update
274 update process for some updaters, it is often ideal to define them as structured
275 hooks within the firmware update process. This section aims to establish such
281 post update systemd targets, as defined by the JSON schema definition below:
289       "description": "The definition for the pre and post update targets",
298           "decsription": "The systemd target service that should be run before starting an update."
302 …"description": "The systemd target service that should be run after an update has finished success…
334 #### Executing Pre/Post Update Services
345 #### Handling Pre/Post Update Service Completion
347 For a triggered pre/post update service, the CodeUpdater waits for completion by
356 To handle ever-hanging tasks, pre and post update services can specify
368 update, the client may target the logical firmware device which further knows
369 how to update the corresponding child components for supplied component images.
370 The user can also update the specific component by providing the image package
378 explicit update targets, is required to implement the
387 xyz.openbmc_project.Software.Update D-Bus interfaces. Upon receiving a PLDM
392 used to update PLDM and Non-PLDM devices.
397 - `xyz.openbmc_project.Software.Update`
427 ### Update multiple devices of same type
432   returned from xyz.openbmc_project.Software.Update.StartUpdate.
442   components with common features, for example, PLDMd may handle update for
448   BMCWeb will trigger xyz.openbmc_project.Software.Update.StartUpdate on
451   [Update multiple devices of same type](#update-multiple-devices-of-same-type).
458 path for a version update which will help to block any interruptions from
470 case scenario when device is busy, for example, due to update in progress.
479 various hardware update services within the system and start them based on
480 update request. These on-demand services update the hardware and interfaces
488 - Under normal operating conditions (no update in flight), only Software Manager
497   to start each update daemon at system startup to get the running version.
503 model where Update interface can have get methods for status and progress (for
523   current proposal, the only change will be in update invocation flow.
529 stacks. As all the code update daemons gets moved to the new flow, Servers would
546 - VR Update
547 - CPLD Update
552 update invocation -
559 | [pldm](https://github.com/openbmc/pldm/tree/master/fw-update)                   | Jagpal Singh Gi…