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.
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
215 #### PLDM Image Packaging
217 The PLDM for
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
222 will parse the entity manager configuration to identify applicable PLDM
223 descriptors, which can include but are not limited to the following -
225 | PLDM Package Descriptor | Decsriptor Type |                                                      …
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)
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
363 PLDM image is one such example of multi part image format. Sometimes, for multi
377 A service intended to process firmware updates via a multi-part image, without
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
389 defined by the PLDM Type 5 specification, and initiates firmware updates for
390 relevant PLDM devices, also ensuring component updates are ordered per firmware
391 device. This implementation does not cover scenario where PLDM package can be
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`
406     subgraph PLDM["pldmd"]
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;
422     class PLDM pldm;
429 - For same type devices, extend the Dbus path to specify device instance, for
438 - Different type hardware components:
443   devices using PLDM specification. Such updates can be invoked in parallel from
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.