docs/designs/code-update.md

1 # Code Update Design
14 1. Current code update flow is complex as it involves 3 different daemons -
15    Image Manager, Image Updater and Update Service.
16 2. Update invocation flow has no explicit interface but rather depends upon the
27 - [Code Update Design](https://github.com/openbmc/docs/tree/master/architecture/code-update)
31 1. Able to start an update, given a firmware image and update settings.
32    - Update settings shall be able to specify when to apply the image, for
35 2. Able to retrieve the update progress and status.
39    a firmware update.
40 5. Update request shall respond back immediately, so client can query the status
41    while update is in progress.
43 7. Able to support update for different type of hardware components such as
46 9. Able to update multiple hardware components of same type running different
50 10. Able to update multiple components in parallel.
52     update while the code update is in flight.
67 CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at /xyz/openbmc_project/Sof…
72 CL ->> BMCW: HTTP POST: /redfish/v1/UpdateService/update <br> (Image, settings, RedfishTargetURIArr…
83   CU ->> CU: << Delegate Update for asynchronous processing >>
91           BMCW --) BMCW: Process notifications<br> and update Task attributes
95   and << Asynchronous Update in Progress >>
109       note over CU: Start Update
113       note over CU: Finish Update
120           CU ->> CU: Update functional association to System Inventory Item
121           CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at ObjectPath
131   above flow) handling its update process and would need to implement the
134 - Since, there would be single daemon handling the update (as compared to
140 The DBus Interface for code update will consist of following -
144 …Update](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/65738)                    …
148 …erface.yaml) |   Existing   | Signifies barrier for state transitions while update is in progress |
152 Introduction of xyz.openbmc_project.Software.Update interface streamlines the
153 update invocation flow and hence addresses the [Issue# 2](#problem-description)
185 xyz.openbmc_project.Software.Update.StartUpdate return value will propagate any
187 Any asynchronous errors which happen during the update process will be notified
189 update. Also, a phosphor-logging event will be created and sent back to client
206 [Firmware Update Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP026…
209 update images for non-PLDM devices as well. For such devices, the CodeUpdater
257 ### Pre and Post Update Conditions
260 executed before or after the update process. One such example of a post update
262 update process for some updaters, it is often ideal to define them as structured
263 hooks within the firmware update process. This section aims to establish such
269 post update systemd targets, as defined by the JSON schema definition below:
277       "description": "The definition for the pre and post update targets",
286           "decsription": "The systemd target service that should be run before starting an update."
290 …"description": "The systemd target service that should be run after an update has finished success…
322 #### Executing Pre/Post Update Services
333 #### Handling Pre/Post Update Service Completion
335 For a triggered pre/post update service, the CodeUpdater waits for completion by
344 To handle ever-hanging tasks, pre and post update services can specify
356 update, the client may target the logical firmware device which further knows
357 how to update the corresponding child components for supplied component images.
358 The user can also update the specific component by providing the image package
363 ### Update multiple devices of same type
368   returned from xyz.openbmc_project.Software.Update.StartUpdate.
378   components with common features, for example, PLDMd may handle update for
384   BMCWeb will trigger xyz.openbmc_project.Software.Update.StartUpdate on
387   [Update multiple devices of same type](#update-multiple-devices-of-same-type).
394 path for a version update which will help to block any interruptions from
406 case scenario when device is busy, for example, due to update in progress.
415 various hardware update services within the system and start them based on
416 update request. These on-demand services update the hardware and interfaces
424 - Under normal operating conditions (no update in flight), only Software Manager
433   to start each update daemon at system startup to get the running version.
439 model where Update interface can have get methods for status and progress (for
459   current proposal, the only change will be in update invocation flow.
465 stacks. As all the code update daemons gets moved to the new flow, Servers would
482 - VR Update
483 - CPLD Update
488 update invocation -
495 | [pldm](https://github.com/openbmc/pldm/tree/master/fw-update)                   | Jagpal Singh Gi…