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