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`.
34*ItemUpdater*s will likely listen for standard D-Bus signals to identify new
35images being created.
36
37### *ItemUpdater*
38
39The *ItemUpdater* is responsible for monitoring for new `Software.Version` elements
40being created to identify versions that are applicable to the inventory
41element(s) it is managing.  The *ItemUpdater* should dynamically create
42an `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`
47and `Software.Activation` under `/xyz/openbmc_project/software/<id>`.
48Application of the software image is then handled through the
49`RequestedActivation` property of the `Software.Activation` interface.
50
51The *ItemUpdater* should, if possible, also create its own
52`xyz.openbmc_project.Software.Version` objects, and appropriate associations
53for software versions that are currently present on the managed inventory
54element(s).  This provides a mechanism for interrogation of the
55software versions when the *ImageManager* no longer contains a copy.
56
57## Details
58
59### Image Identifier
60
61The *ImageManager* and *ItemUpdater* should use a common, though perhaps
62implementation specific, algorithm for the `<id>` portion of a D-Bus path for
63each `Software.Version`.  This allows the same software version to be contained
64in multiple locations but represented by the same object path.
65
66A reasonable algorithm might be:
67`echo <Version.Version> <Version.Purpose> | sha512sum | cut -b 1-8`
68
69> TODO: May need an issue against the REST server to 'merge' two copies of
70>       a single D-Bus object into a single REST object.
71
72### Activation States
73
74`xyz.openbmc_project.Software.Activation` has a property Activation that can
75be in the following states:
76
771. *NotReady* - Indicating that the *ItemUpdater* is still processing the
78                version and it is therefore not ready for activation.  This
79                might be used on an image that has a security header while
80                verification is being performed.
812. *Invalid* - Indicating that, while the `Software.Version.Purpose` suggested
82               the image was valid for a managed element, a detailed analysis
83               by the *ItemUpdater* showed that it was not.  Reasons may
84               include image corruption detected via CRC or security
85               verification failure.  An event may be recorded with additional
86               details.
873. *Ready* - Indicating that the `Software.Version` can be activated.
884. *Activating* - Indicating that the `Software.Version` is in the process of
89                  being activated.
905. *Active* - The `Software.Version` is active on the managed element.  Note
91              that on systems with redundant storage devices a version might
92              be *Active* but not the primary version.
936. *Failed* - The `Software.Version` or the storage medium on which it is stored
94              has failed.  An event may be recorded with additional details.
957. *Staged* - The `Software.Version` is in staged flash region. This will be
96              moved from staged flash region to active flash region upon reset.
97              Staged flash region is the designated flash area which is used to
98              store the integrity validated firmware image that comes in during
99              firmware update process. Note that the staged image is not
100              necessarily a functional firmware.
101
102### Image Apply Time
103
104`xyz.openbmc_project.Software.ApplyTime` has a property called
105RequestedApplyTime that indicates when the newly applied software image will
106be activated.  RequestedApplyTime is a D-Bus property that maps to the
107"ApplyTime" property in the Redfish UpdateService schema. Below are the
108currently supported values and the value can be supplied through
109HttpPushUriApplyTime object:
110
1111. *Immediate* - Indicating that the `Software.Version` needs to be activated
112                 immediately.
1132. *OnReset* - Indicating that the `Software.Version` needs to be activated
114               on the next reset.
115
116### Blocking State Transitions
117
118It is sometimes useful to block a system state transition while activations
119are being performed.  For example, we do not want to boot a managed host while
120its BIOS is being updated.  In order to facilitate this, the interface
121`xyz.openbmc_project.Software.ActivationBlocksTransition` may be added to any
122object with `Software.Activation` to indicate this behavior.  See that
123interface for more details.
124
125It is strongly suggested that any activations are completed prior to a managed
126BMC reboot.  This could be facilitated with systemd service specifiers.
127
128### Software Versions
129
130All version identifiers are implementation specific strings.  No format
131should be assumed.
132
133Some software versions are a collection of images, each with their own version
134identifiers.  The `xyz.openbmc_project.Software.ExtendedVersion` interface
135can be added to any `Software.Version` to express the versioning of the
136aggregation.
137
138### Activation Progress
139
140The `xyz.openbmc_project.Software.ActivationProgress` interface is provided
141to show current progress while a software version is *Activating*.  It is
142expected that an *ItemUpdater* will dynamically create this interface while
143the version is *Activating* and dynamically remove it when the activation is
144complete (or failed).
145
146### Handling Redundancy
147
148The `xyz.openbmc_project.Software.RedundancyPriority` interface is provided to
149express the relationship between two (or more) software versions activated for
150a single managed element.  It is expected that all installed versions are listed
151as *Active* and the `Priority` shows which version is the primary and which are
152available for redundancy.
153
154Prior to `Activation`, it can be useful to indicate a desired
155`RedundancyPriority`.  This can be done by setting the `Priority` on the
156`RequestedRedundancyPriority` interface.  Some *ItemUpdater* implementations
157may not honor this field or be unable to comply with the request, in which
158case the resulting `Activation` may result in one of two conditions: a
159`ActivationState = Failed` or an `ActivateState = Active`` with a
160`RedundancyPriority = 0 (High)`.
161
162## REST use-cases
163
164### Find all software versions on the system, either active or available.
165
166List `/xyz/openbmc_project/software/`.  This list can be filtered to just
167active listing `.../software/active/` and following the `software_version`
168association to retrieve version information.  To list just "functional" or
169running versions list `/xyz/openbmc_project/software/functional/`.
170
171### Find all software versions on a managed element.
172
173List `/xyz/openbmc_project/inventory/.../<item>/activation` association.
174
175### Upload new version via REST
176
177HTTP PUT to `/xyz/openbmc_project/software/`.  *ImageManager* will assign the
178`<id>` when called for Object.Add().
179
180### Upload new version via ???
181
182Need additional interfaces defined for alternative upload methods.
183
184### Activate a version.
185
186Modify `RequestedActivation` to *Active* on the desired `Activation`.
187
188### Switch primary image.
189
190Set `Priority` to 0 on the desired `RedundancyPriority` interface.
191
192