docs/designs/code-update.md

7 - Deepak Kodihalli <deepak.kodihalli.83@gmail.com> @dkodihal
8 - Tom Joseph <rushtotom@gmail.com> @tomjose
17 [phosphor-bmc-code-mgmt](https://github.com/openbmc/phosphor-bmc-code-mgmt).
19 1. Current code update flow is complex as it involves 3 different daemons -
30 - [phosphor-bmc-code-mgmt](https://github.com/openbmc/phosphor-bmc-code-mgmt)
31 - [Software DBus Interface](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xy…
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…
39    - Update settings shall be able to specify when to apply the image, for
40      example immediately or on device reset or on-demand.
60 12. Able to update the components with a multi part image when no Targets are
62 13. Able to order component updates to a device as defined in the multi part
78 CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at /xyz/openbmc_project/Sof…
79 CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Version<br> at /xyz/openbmc_project/So…
80 CU ->> CU: Create Interface<br>xyz.openbmc_project.Software.Activation<br> at /xyz/openbmc_project/…
81 CU ->> CU: Create functional association <br> from Version to Inventory Item
83 CL ->> BMCW: HTTP POST: /redfish/v1/UpdateService/update <br> (Image, settings, RedfishTargetURIArr…
88   BMCW ->> CU: StartUpdate(Image, ApplyTime)
92 …CU ->> CU: Create Interface<br>xyz.openbmc_project.Software.Activation<br> at ObjectPath with Stat…
93   CU -->> BMCW: {ObjectPath, Success}
94   CU ->> CU: << Delegate Update for asynchronous processing >>
97 …BMCW ->> BMCW: Create Matcher<br>(PropertiesChanged,<br> xyz.openbmc_project.Software.Activation,<…
98 …BMCW ->> BMCW: Create Matcher<br>(PropertiesChanged,<br> xyz.openbmc_project.Software.ActivationPr…
99       BMCW ->> BMCW: Create Task<br> to handle matcher notifications
100       BMCW -->> CL: <TaskNum>
102           BMCW --) BMCW: Process notifications<br> and update Task attributes
103           CL ->> BMCW: /redfish/v1/TaskMonitor/<TaskNum>
104           BMCW -->>CL: TaskStatus
109         CU ->> CU: Activation.Status = Invalid
110         CU --) BMCW: Notify Activation.Status change
112       CU ->> CU: Activation.Status = Ready
113       CU --) BMCW: Notify Activation.Status change
115       CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Version<br> at ObjectPath
116 …   CU ->> CU: Create Interface<br>xyz.openbmc_project.Software.ActivationProgress<br> at ObjectPath
117 …CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.ActivationBlocksTransition<br> at Obj…
118       CU ->> CU: Activation.Status = Activating
119       CU --) BMCW: Notify Activation.Status change
122           CU --) BMCW: Notify ActivationProgress.Progress change
125       CU ->> CU: Activation.Status = Active
126       CU --) BMCW: Notify Activation.Status change
127       CU ->> CU: Delete Interface<br> xyz.openbmc_project.Software.ActivationBlocksTransition
128       CU ->> CU: Delete Interface<br> xyz.openbmc_project.Software.ActivationProgress
131           CU ->> CU: Update functional association to System Inventory Item
132           CU ->> CU: Create Interface<br> xyz.openbmc_project.Software.Update<br> at ObjectPath
141 - Each upgradable hardware type may have a separate daemon (\<deviceX\> as per
145 - Since, there would be single daemon handling the update (as compared to
147   [Issue# 1](#problem-description) and [Requirement# 4](#requirements).
149 ### Proposed D-Bus Interface
151 The DBus Interface for code update will consist of following -
154 …--------------------------------------------------------------------------------------------------…
155 | [xyz.openbmc_project.Software.Update](https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfac…
156 …-dbus-interfaces/+/78905)                                                                         …
157 | [xyz.openbmc_project.Software.Version](https://github.com/openbmc/phosphor-dbus-interfaces/blob/m…
158 | [xyz.openbmc_project.Software.Activation](https://github.com/openbmc/phosphor-dbus-interfaces/blo…
159 | [xyz.openbmc_project.Software.ActivationProgress](https://github.com/openbmc/phosphor-dbus-interf…
160 ….Software.ActivationBlocksTransition](https://github.com/openbmc/phosphor-dbus-interfaces/blob/mas…
161 | [xyz.openbmc_project.Software.RedundancyPriority](https://github.com/openbmc/phosphor-dbus-interf…
162 | [xyz.openbmc_project.Software.Asset](https://github.com/openbmc/phosphor-dbus-interfaces/tree/mas…
165 update invocation flow and hence addresses the [Issue# 2](#problem-description)
180 flash-banks and xyz.openbmc_project.Software.RedundancyPriority interface
201 update. Also, a phosphor-logging event will be created and sent back to client
220 and user-defined descriptors. This format can be utilized to package firmware
221 update images for non-PLDM devices as well. For such devices, the CodeUpdater
223 descriptors, which can include but are not limited to the following -
226 …---------------------: | :-------------: | :------------------------------------------------------…
227 …  [IANA Enterprise Id](https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers) of …
228 …XX\>) specified by hardware vendor in [phosphor-dbus-interfaces](https://github.com/openbmc/phosph…
232 The entity manager configuration can provide firmware-related information as
234 modeling device access details. These D-Bus objects can then be consumed by the
238 [refer](https://gerrit.openbmc.org/c/openbmc/entity-manager/+/75947)
240 The following example is one such instance of this definition for an i2c CPLD
261 - `Name`: The name of the firmware entity instance.
262 - `Type`: This field is used by the CodeUpdater service to determine which
264 - `VendorIANA`: This field maps to the `IANA Enterprise ID` descriptor in PLDM
266 - `CompatibleHardware`: This field maps to the `ASCII Model` descriptor in PLDM
280 The Code Updater daemon can be configured to execute platform-specific pre and
285   "$schema": "http://json-schema.org/draft-04/schema#",
311 - `Identifier` maps to `DeviceX` defined in the preceding sections.
356 To handle ever-hanging tasks, pre and post update services can specify
360 ### Multi part Images
362 A multi part image has multiple component images as part of one image package.
363 PLDM image is one such example of multi part image format. Sometimes, for multi
375 ### Multi part image handling w/o Targets
377 A service intended to process firmware updates via a multi-part image, without
380 a single instance of this interface. If no targets are provided, bmcweb searches
384 The PLDM package is an example of multi-part image format. At the application
387 xyz.openbmc_project.Software.Update D-Bus interfaces. Upon receiving a PLDM
388 package, pldmd parses the content, applies the component-matching algorithm as
392 used to update PLDM and Non-PLDM devices.
396 - `xyz.openbmc_project.Software.MultipartUpdate`
397 - `xyz.openbmc_project.Software.Update`
398 - `xyz.openbmc_project.Software.Activation`
399 - `xyz.openbmc_project.Software.ActivationProgress`
411     bmcweb <--> |MultipartUpdate D-Bus Intf<br>StartUpdate D-Bus Intf| PLDM
412     PLDM <--> |MCTP| F[PLDM endpoints]
415     classDef bmcweb fill:#f8f0ff,stroke:#333,stroke-width:1px;
416     classDef manager fill:#fff3e0,stroke:#333,stroke-width:1px;
417     classDef pldm fill:#e3f2fd,stroke:#333,stroke-width:1px;
418     classDef endpoints fill:#ffffff,stroke:#333,stroke-width:1px;
419     classDef libpldm fill:#ffcdd2,stroke:#333,stroke-width:1px;
429 - For same type devices, extend the Dbus path to specify device instance, for
438 - Different type hardware components:
446 - Similar type hardware component:
449   different D-Bus paths pertaining to each hardware instance. For more details
450   on D-Bus paths refer to
451   [Update multiple devices of same type](#update-multiple-devices-of-same-type).
457 `ActivationBlocksTransitions` interface will be created on the specific D-Bus
480 update request. These on-demand services update the hardware and interfaces
485 - Most of the DBus interfaces gets implemented by Software Manager and vendors
488 - Under normal operating conditions (no update in flight), only Software Manager
493 - Imposes the need of a common image format as Software Manager needs to parse
495 - Limitation in the design, as there is a need to get the current running
508 - Server doesn't have to maintain a Dbus matcher
510 - Easier implementation in Server as no asynchronous handlers would be required.
514 - Server would still need maintain some info so it can map client's task status
517 - Aforementioned [issue](https://github.com/openbmc/bmcweb/issues/202) is more
520 - Currently, activation and progress interfaces are being used in
530 be changed to only support new API stack. No user-api impact as design adheres
546 - VR Update
547 - CPLD Update
552 update invocation -
555 | :------------------------------------------------------------------------------ | :--------------…
556 | [phosphor-bmc-code-mgmt](https://github.com/openbmc/phosphor-bmc-code-mgmt)     | Jagpal Singh Gi…
558 | [phosphor-host-ipmid](https://github.com/openbmc/phosphor-host-ipmid)           | Jagpal Singh Gi…
559 | [pldm](https://github.com/openbmc/pldm/tree/master/fw-update)                   | Jagpal Singh Gi…
560 | [openpower-pnor-code-mgmt](https://github.com/openbmc/openpower-pnor-code-mgmt) | Adriana Kobylak…
561 | [openbmc-test-automation](https://github.com/openbmc/openbmc-test-automation)   | Adriana Kobylak…
564 [phosphor-psu-code-mgmt](https://github.com/openbmc/phosphor-psu-code-mgmt) code
577 be covered using openbmc-test-automation.