1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# Software Version Management and Image Update
## Overview
There are two types of processes involved in software version management and
code update:
1. *ImageManager* - This is a process which manages a collection of, likely
temporary, images located somewhere in a file system.
These are images which are available on the BMC for update.
2. *ItemUpdater* - This is a process which manages specific storage elements,
likely for an inventory item, to determine which software
versions are installed onto that item. A specific example of
this would be a process that controls and updates the BIOS
flash module for a managed host.
A simple system design would be to include a single *ImageManager* and two
*ItemUpdater*s: one for the BMC itself and one for the Host.
### ImageManager
The *ImageManager* would provide interfaces at `/xyz/openbmc_project/software`
to allow additional images to be added to the BMC, such as Object.Add() for
REST and DownloadViaTFTP() for TFTP. The standard Object.Delete() interface
would also be provided to facilitate removing images which are no longer
needed. Images maintained in the file system would be presented as a
corresponding `/xyz/openbmc_project/software/<id>` object. In addition, the
`xyz.openbmc_project.Common.FilePath` interface would be provided to specify
the location of the image.
It is assumed that the *ImageManager* has [at least] a bare minimum amount of
parsing knowledge, perhaps due to a common image format, to allow it to
populate all of the properties of `xyz.openbmc_project.Software.Version`.
*ItemUpdater*s will likely listen for standard D-Bus signals to identify new
images being created.
### *ItemUpdater*
The *ItemUpdater* is responsible for monitoring for new `Software.Version` elements
being created to identify versions that are applicable to the inventory
element(s) it is managing. The *ItemUpdater* should dynamically create
an `xyz.openbmc_project.Software.Activation` interface under
`/xyz/openbmc_project/software/`, an association of type
`{active_image,software_version}` between the `Software.Version` and
`Software.Activation` under `/xyz/openbmc_project/software/`, and an
association of type `{activation,item}` between the `Inventory.Item`
and `Software.Activation` under `/xyz/openbmc_project/software/<id>`.
Application of the software image is then handled through the
`RequestedActivation` property of the `Software.Activation` interface.
The *ItemUpdater* should, if possible, also create its own
`xyz.openbmc_project.Software.Version` objects, and appropriate associations
for software versions that are currently present on the managed inventory
element(s). This provides a mechanism for interrogation of the
software versions when the *ImageManager* no longer contains a copy.
## Details
### Image Identifier
The *ImageManager* and *ItemUpdater* should use a common, though perhaps
implementation specific, algorithm for the `<id>` portion of a D-Bus path for
each `Software.Version`. This allows the same software version to be contained
in multiple locations but represented by the same object path.
A reasonable algorithm might be:
`echo <Version.Version> <Version.Purpose> | sha512sum | cut -b 1-8`
> TODO: May need an issue against the REST server to 'merge' two copies of
> a single D-Bus object into a single REST object.
### Activation States
`xyz.openbmc_project.Software.Activation` has a property Activation that can
be in the following states:
1. *NotReady* - Indicating that the *ItemUpdater* is still processing the
version and it is therefore not ready for activation. This
might be used on an image that has a security header while
verification is being performed.
2. *Invalid* - Indicating that, while the `Software.Version.Purpose` suggested
the image was valid for a managed element, a detailed analysis
by the *ItemUpdater* showed that it was not. Reasons may
include image corruption detected via CRC or security
verification failure. An event may be recorded with additional
details.
3. *Ready* - Indicating that the `Software.Version` can be activated.
4. *Activating* - Indicating that the `Software.Version` is in the process of
being activated.
5. *Active* - The `Software.Version` is active on the managed element. Note
that on systems with redundant storage devices a version might
be *Active* but not the primary version.
6. *Failed* - The `Software.Version` or the storage medium on which it is stored
has failed. An event may be recorded with additional details.
### Blocking State Transitions
It is sometimes useful to block a system state transition while activations
are being performed. For example, we do not want to boot a managed host while
its BIOS is being updated. In order to facilitate this, the interface
`xyz.openbmc_project.Software.ActivationBlocksTransition` may be added to any
object with `Software.Activation` to indicate this behavior. See that
interface for more details.
It is strongly suggested that any activations are completed prior to a managed
BMC reboot. This could be facilitated with systemd service specifiers.
### Software Versions
All version identifiers are implementation specific strings. No format
should be assumed.
Some software versions are a collection of images, each with their own version
identifiers. The `xyz.openbmc_project.Software.ExtendedVersion` interface
can be added to any `Software.Version` to express the versioning of the
aggregation.
### Activation Progress
The `xyz.openbmc_project.Software.ActivationProgress` interface is provided
to show current progress while a software version is *Activating*. It is
expected that an *ItemUpdater* will dynamically create this interface while
the version is *Activating* and dynamically remove it when the activation is
complete (or failed).
### Handling Redundancy
The `xyz.openbmc_project.Software.RedundancyPriority` interface is provided to
express the relationship between two (or more) software versions activated for
a single managed element. It is expected that all installed versions are listed
as *Active* and the `Priority` shows which version is the primary and which are
available for redundancy.
## REST use-cases
### Find all software versions on the system, either active or available.
List `/xyz/openbmc_project/software/`. This list can be filtered to just
active listing `.../software/active/` and following the `software_version`
association to retrieve version information.
### Find all software versions on a managed element.
List `/xyz/openbmc_project/inventory/.../<item>/activation` association.
### Upload new version via REST
HTTP PUT to `/xyz/openbmc_project/software/`. *ImageManager* will assign the
`<id>` when called for Object.Add().
### Upload new version via ???
Need additional interfaces defined for alternative upload methods.
### Activate a version.
Modify `RequestedActivation` to *Active* on the desired `Activation`.
### Switch primary image.
Set `Priority` to 0 on the desired `RedundancyPriority` interface.
|
