1# Software Version Management and Image Update
2
3## Overview
4
5There are two types of processes involved in software version management and
6code update:
7
81. _ImageManager_ - This is a process which manages a collection of, likely
9   temporary, images located somewhere in a file system. These are images which
10   are available on the BMC for update.
112. _ItemUpdater_ - This is a process which manages specific storage elements,
12   likely for an inventory item, to determine which software versions are
13   installed onto that item. A specific example of this would be a process that
14   controls and updates the BIOS flash module for a managed host.
15
16A simple system design would be to include a single _ImageManager_ and two
17_ItemUpdater_(s): one for the BMC itself and one for the Host.
18
19### ImageManager
20
21The _ImageManager_ would provide interfaces at `/xyz/openbmc_project/software`
22to allow additional images to be added to the BMC, such as Object.Add() for REST
23and DownloadViaTFTP() for TFTP. The standard Object.Delete() interface would
24also be provided to facilitate removing images which are no longer needed.
25Images maintained in the file system would be presented as a corresponding
26`/xyz/openbmc_project/software/<id>` object. In addition, the
27`xyz.openbmc_project.Common.FilePath` interface would be provided to specify the
28location of the image.
29
30It is assumed that the _ImageManager_ has [at least] a bare minimum amount of
31parsing knowledge, perhaps due to a common image format, to allow it to populate
32all of the properties of `xyz.openbmc_project.Software.Version` and
33`xyz.openbmc_project.Inventory.Decorator.Compatible`. _ItemUpdater_(s) will
34likely listen for standard D-Bus signals to identify new images being created.
35
36### ItemUpdater
37
38The _ItemUpdater_ is responsible for monitoring for new `Software.Version`
39elements being created to identify versions that are applicable to the inventory
40element(s) it is managing. The _ItemUpdater_ should dynamically create an
41`xyz.openbmc_project.Software.Activation` interface under
42`/xyz/openbmc_project/software/`, an association of type
43`{active_image,software_version}` between the `Software.Version` and
44`Software.Activation` under `/xyz/openbmc_project/software/`, and an association
45of type `{activation,item}` between the `Inventory.Item` and
46`Software.Activation` under `/xyz/openbmc_project/software/<id>`. Application of
47the software image is then handled through the `RequestedActivation` property of
48the `Software.Activation` interface.
49
50In many cases, the _ItemUpdater_'s creation of the `Software.Activation`
51interface will be at the exact same path as the _ImageManager_'s
52`Software.Version` instance (ie. `/xyz/openbmc_project/software/<id>`). This is
53appropriate when the software image can be applied to exactly one device in the
54system at exactly one storage location. In cases where multiple devices could
55updated with the same image or multiple locations in the same device could hold
56the same image (such as a primary / secondary flash bank relationship), the
57_ItemUpdater_ should create `Software.Activation` interfaces as a sub-path of
58the corresponding image, such as `/xyz/openbmc_project/software/<id>/<device>`.
59
60The _ItemUpdater_ should, if possible, also create its own
61`xyz.openbmc_project.Software.Version` objects, and appropriate associations for
62software versions that are currently present on the managed inventory
63element(s). This provides a mechanism for interrogation of the software versions
64when the _ImageManager_ no longer contains a copy.
65
66## Details
67
68### Image Identifier
69
70The _ImageManager_ and _ItemUpdater_ should use a common, though perhaps
71implementation specific, algorithm for the `<id>` portion of a D-Bus path for
72each `Software.Version`. This allows the same software version to be contained
73in multiple locations but represented by the same object path.
74
75A reasonable algorithm might be:
76`echo <Version.Version> <Compatible.Names> | sha512sum | cut -b 1-8`
77
78### Compatibility
79
80Identifying that a particular Software image is for a particular system element
81can be challenging. For the BMC, two different images may both be the same size
82but for vastly different hardware. If the image for one system is applied onto
83the BMC for another it is quite possible that the image won't even boot
84properly. It is therefore important to be able to specify more details than
85simply "BMC" or "Host".
86
87Early on implementations used the `Software.Version.Purpose` property and a
88custom string in the `Software.ExtendedVersion` to align software images with
89appropriate hardware. This lead to an ever-increasing set of `Purpose`
90enumeration values and inconsistent implementations of software update routines.
91
92The `Inventory.Decorator.Compatible` interface was introduced to give
93identifiers that can be used to map to common software implementations, in a
94similar manner to how the Linux Device Tree compatible strings are used.
95Software update should leverage these `Compatible.Names` properties to create a
96consistent mapping of `Software.Version` instances to the system element the
97image is applicable to.
98
99At the same path as the `Software.Version`, an _ImageManager_ should create an
100`xyz.openbmc_project.Inventory.Decorator.Compatible` interface containing
101strings identifying the system element this image can be applied to.
102Correspondingly, the Inventory Item corresponding to the system element should
103have the same string in its `Inventory.Decorator.Compatible` interface. These
104strings shall be of the following format:
105
106- `<org>.Software.Element.<identifer>.Type.<type>`
107
108Where:
109
110- `<org>` corresponds to the organization owning the `<identifier>`, such as
111  `xyz.openbmc_project` or `com.foo_corp`.
112- `<identifier>` is a unique name for the element, such as `SystemFoo` or
113  `BoardBar`. Typically these would be code names for the hardware element such
114  as `Witherspoon`.
115- `<type>` is an identifier for sub-element the image corresponds to and is
116  documented in the `<org>/Software/Element/<identifier>.interface` file under
117  the `Type` enumeration.
118
119The following `<type>` are reserved for a particular meaning:
120
121- BMC - The image is for the BMC contained on that element.
122- Host - The image is the primary firmware for the managed host contained on
123  that element.
124
125If an image contains sub-sections which can be applied to multiple system
126elements, the image should contain `Compatible` strings for each sub-section. It
127is expected that the _ItemUpdater_ is aware of how to find the sub-section
128appropriate for any element(s) being Activated.
129
130### Activation States
131
132`xyz.openbmc_project.Software.Activation` has a property Activation that can be
133in the following states:
134
1351. _NotReady_ - Indicating that the _ItemUpdater_ is still processing the
136   version and it is therefore not ready for activation. This might be used on
137   an image that has a security header while verification is being performed.
1382. _Invalid_ - Indicating that, while the `Software.Version.Purpose` suggested
139   the image was valid for a managed element, a detailed analysis by the
140   _ItemUpdater_ showed that it was not. Reasons may include image corruption
141   detected via CRC or security verification failure. An event may be recorded
142   with additional details.
1433. _Ready_ - Indicating that the `Software.Version` can be activated.
1444. _Activating_ - Indicating that the `Software.Version` is in the process of
145   being activated.
1465. _Active_ - The `Software.Version` is active on the managed element. Note that
147   on systems with redundant storage devices a version might be _Active_ but not
148   the primary version.
1496. _Failed_ - The `Software.Version` or the storage medium on which it is stored
150   has failed. An event may be recorded with additional details.
1517. _Staged_ - The `Software.Version` is in staged flash region. This will be
152   moved from staged flash region to active flash region upon reset. Staged
153   flash region is the designated flash area which is used to store the
154   integrity validated firmware image that comes in during firmware update
155   process. Note that the staged image is not necessarily a functional firmware.
156
157### Image Apply Time
158
159`xyz.openbmc_project.Software.ApplyTime` has a property called
160RequestedApplyTime that indicates when the newly applied software image will be
161activated. RequestedApplyTime is a D-Bus property that maps to the "ApplyTime"
162property in the Redfish UpdateService schema. Below are the currently supported
163values and the value can be supplied through HttpPushUriApplyTime object:
164
1651. _Immediate_ - Indicating that the `Software.Version` needs to be activated
166   immediately.
1672. _OnReset_ - Indicating that the `Software.Version` needs to be activated on
168   the next reset.
169
170### Blocking State Transitions
171
172It is sometimes useful to block a system state transition while activations are
173being performed. For example, we do not want to boot a managed host while its
174BIOS is being updated. In order to facilitate this, the interface
175`xyz.openbmc_project.Software.ActivationBlocksTransition` may be added to any
176object with `Software.Activation` to indicate this behavior. See that interface
177for more details.
178
179It is strongly suggested that any activations are completed prior to a managed
180BMC reboot. This could be facilitated with systemd service specifiers.
181
182### Software Versions
183
184All version identifiers are implementation specific strings. No format should be
185assumed.
186
187Some software versions are a collection of images, each with their own version
188identifiers. The `xyz.openbmc_project.Software.ExtendedVersion` interface can be
189added to any `Software.Version` to express the versioning of the aggregation.
190
191In addition, the `xyz.openbmc_project.Software.MinimumVersion` interface can
192communicate the minimum software version that a component must have to operate.
193The minimum version check is an optional software feature of the item updater.
194
195### Activation Progress
196
197The `xyz.openbmc_project.Software.ActivationProgress` interface is provided to
198show current progress while a software version is _Activating_. It is expected
199that an _ItemUpdater_ will dynamically create this interface while the version
200is _Activating_ and dynamically remove it when the activation is complete (or
201failed).
202
203### Handling Redundancy
204
205The `xyz.openbmc_project.Software.RedundancyPriority` interface is provided to
206express the relationship between two (or more) software versions activated for a
207single managed element. It is expected that all installed versions are listed as
208_Active_ and the `Priority` shows which version is the primary and which are
209available for redundancy.
210
211Prior to `Activation`, it can be useful to indicate a desired
212`RedundancyPriority`. This can be done by setting the `Priority` on the
213`RequestedRedundancyPriority` interface. Some _ItemUpdater_ implementations may
214not honor this field or be unable to comply with the request, in which case the
215resulting `Activation` may result in one of two conditions: a
216`ActivationState = Failed` or an `ActivateState = Active` with a
217`RedundancyPriority = 0 (High)`.
218
219### Image Clean Up
220
221An _ItemUpdater_ is responsible for garbage collecting images contained on the
222elements it is managing. Often an element can only contain a single image so
223this is a natural side-effect of the update process. In other cases, the
224_ItemUpdater_ may remove images based on the `RedundancyPriority` assigned to an
225image.
226
227The _ImageManager_ should expose `Object.Delete()` methods to remove images from
228the BMC filesystem. It is possible that some _ItemUpdater_(s) will call this
229method once the `Version` is successfully activated.
230
231In some designs there may be multiple _ItemUpdater_ instances which are handling
232update for different system elements, all of which can potentially apply the
233same software image (as in a multi-host design). The _ImageManager_ may
234optionally monitor the `Software.Activation` signals and actively garbage
235collect an image once all `Software.Activation` under the `.../software/<id>`
236path are either `Active` or `Staged`.
237
238### Software Settings
239
240The `xyz.openbmc_project.Software.Settings` interface is provided to show the
241settings of the given software. The `Software.Settings` should be added to along
242side `Software.Version` to represent its state from the same service.
243
244```sh
245busctl introspect $SERVICE /xyz/openbmc_project/software/software_0
246...
247xyz.openbmc_project.Software.Version   interface   -
248.Purpose                               property    s
249.Version                               property    s
250xyz.openbmc_project.Software.Settings  interface   -
251.WriteProtected                        property    b
252...
253```
254
255The _ItemUpdater_ manages the fields such as `WriteProtected` to help provide
256information on how the software is managed.
257
258## REST use-cases
259
260### Find all software versions on the system, either active or available
261
262List `/xyz/openbmc_project/software/`. This list can be filtered to just active
263listing `.../software/active/` and following the `software_version` association
264to retrieve version information. To list just "functional" or running versions
265list `/xyz/openbmc_project/software/functional/`.
266
267### Find all software versions on a managed element
268
269List `/xyz/openbmc_project/inventory/.../<item>/activation` association.
270
271### Upload new version via REST
272
273HTTP PUT to `/xyz/openbmc_project/software/`. _ImageManager_ will assign the
274`<id>` when called for Object.Add().
275
276### Upload new version via ???
277
278Need additional interfaces defined for alternative upload methods.
279
280### Activate a version
281
282Modify `RequestedActivation` to _Active_ on the desired `Activation`.
283
284### Switch primary image
285
286Set `Priority` to 0 on the desired `RedundancyPriority` interface.
287