openbmc_project/Software/README.md

1 # Software Version Management and Image Update
5 There are two types of processes involved in software version management and
12    likely for an inventory item, to determine which software versions are
21 The _ImageManager_ would provide interfaces at `/xyz/openbmc_project/software`
26 `/xyz/openbmc_project/software/<id>` object. In addition, the
32 all of the properties of `xyz.openbmc_project.Software.Version` and
38 The _ItemUpdater_ is responsible for monitoring for new `Software.Version`
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
46 `Software.Activation` under `/xyz/openbmc_project/software/<id>`. Application of
47 the software image is then handled through the `RequestedActivation` property of
48 the `Software.Activation` interface.
50 In many cases, the _ItemUpdater_'s creation of the `Software.Activation`
52 `Software.Version` instance (ie. `/xyz/openbmc_project/software/<id>`). This is
53 appropriate when the software image can be applied to exactly one device in the
57 _ItemUpdater_ should create `Software.Activation` interfaces as a sub-path of
58 the corresponding image, such as `/xyz/openbmc_project/software/<id>/<device>`.
61 `xyz.openbmc_project.Software.Version` objects, and appropriate associations for
62 software versions that are currently present on the managed inventory
63 element(s). This provides a mechanism for interrogation of the software versions
72 each `Software.Version`. This allows the same software version to be contained
80 Identifying that a particular Software image is for a particular system element
87 Early on implementations used the `Software.Version.Purpose` property and a
88 custom string in the `Software.ExtendedVersion` to align software images with
90 enumeration values and inconsistent implementations of software update routines.
93 identifiers that can be used to map to common software implementations, in a
95 Software update should leverage these `Compatible.Names` properties to create a
96 consistent mapping of `Software.Version` instances to the system element the
99 At the same path as the `Software.Version`, an _ImageManager_ should create an
106 - `<org>.Software.Element.<identifier>.Type.<type>`
116   documented in the `<org>/Software/Element/<identifier>.interface` file under
132 `xyz.openbmc_project.Software.Activation` has a property Activation that can be
138 2. _Invalid_ - Indicating that, while the `Software.Version.Purpose` suggested
143 3. _Ready_ - Indicating that the `Software.Version` can be activated.
144 4. _Activating_ - Indicating that the `Software.Version` is in the process of
146 5. _Active_ - The `Software.Version` is active on the managed element. Note that
149 6. _Failed_ - The `Software.Version` or the storage medium on which it is stored
151 7. _Staged_ - The `Software.Version` is in staged flash region. This will be
159 `xyz.openbmc_project.Software.ApplyTime` has a property called
160 RequestedApplyTime that indicates when the newly applied software image will be
165 1. _Immediate_ - Indicating that the `Software.Version` needs to be activated
167 2. _OnReset_ - Indicating that the `Software.Version` needs to be activated on
175 `xyz.openbmc_project.Software.ActivationBlocksTransition` may be added to any
176 object with `Software.Activation` to indicate this behavior. See that interface
182 ### Software Versions
187 Some software versions are a collection of images, each with their own version
188 identifiers. The `xyz.openbmc_project.Software.ExtendedVersion` interface can be
189 added to any `Software.Version` to express the versioning of the aggregation.
191 In addition, the `xyz.openbmc_project.Software.MinimumVersion` interface can
192 communicate the minimum software version that a component must have to operate.
193 The minimum version check is an optional software feature of the item updater.
197 The `xyz.openbmc_project.Software.ActivationProgress` interface is provided to
198 show current progress while a software version is _Activating_. It is expected
205 The `xyz.openbmc_project.Software.RedundancyPriority` interface is provided to
206 express the relationship between two (or more) software versions activated for a
233 same software image (as in a multi-host design). The _ImageManager_ may
234 optionally monitor the `Software.Activation` signals and actively garbage
235 collect an image once all `Software.Activation` under the `.../software/<id>`
238 ### Software Settings
240 The `xyz.openbmc_project.Software.Settings` interface is provided to show the
241 settings of the given software. The `Software.Settings` should be added to along
242 side `Software.Version` to represent its state from the same service.
245 busctl introspect $SERVICE /xyz/openbmc_project/software/software_0
247 xyz.openbmc_project.Software.Version   interface   -
250 xyz.openbmc_project.Software.Settings  interface   -
256 information on how the software is managed.
260 ### Find all software versions on the system, either active or available
262 List `/xyz/openbmc_project/software/`. This list can be filtered to just active
263 listing `.../software/active/` and following the `software_version` association
265 list `/xyz/openbmc_project/software/functional/`.
267 ### Find all software versions on a managed element
273 HTTP PUT to `/xyz/openbmc_project/software/`. _ImageManager_ will assign the