diff options
author | Patrick Williams <patrick@stwcx.xyz> | 2016-11-23 07:27:01 -0600 |
---|---|---|
committer | Patrick Williams <patrick@stwcx.xyz> | 2017-01-24 21:40:40 +0000 |
commit | 3350f3edfb8afa936d3571690b83397ffdf19f11 (patch) | |
tree | efdbb2eb63b3856b548574254d7696799bc44aec /xyz/openbmc_project/Software | |
parent | 3b0cbc9ac0ad2ea38df48c82140b0a29f317bb77 (diff) | |
download | phosphor-dbus-interfaces-3350f3edfb8afa936d3571690b83397ffdf19f11.tar.gz phosphor-dbus-interfaces-3350f3edfb8afa936d3571690b83397ffdf19f11.zip |
Software: add initial software-version mgmt
Change-Id: I3b50488b8383c595b4b41375ea0d62d62bdc0eed
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Diffstat (limited to 'xyz/openbmc_project/Software')
7 files changed, 291 insertions, 0 deletions
diff --git a/xyz/openbmc_project/Software/Activation.interface.yaml b/xyz/openbmc_project/Software/Activation.interface.yaml new file mode 100644 index 0000000..37c9cb9 --- /dev/null +++ b/xyz/openbmc_project/Software/Activation.interface.yaml @@ -0,0 +1,49 @@ +description: > + Activation state for an associated xyz.openbmc_project.Software.Version. +properties: + - name: Activation + type: enum[self.Activations] + description: > + The current Activation state of the Software.Version. + - name: RequestedActivation + type: enum[self.RequestedActivations] + description: > + The desired Activation state of the Software.Version. +enumerations: + - name: Activations + description: > + The possible Activation states of the Software.Version. + values: + - name: NotReady + description: > + The system is still analyzing the Software.Version and is + currently unable to activate. + - name: Invalid + description: > + The Software.Version is invalid and unable to be activated. + - name: Ready + description: > + The Software.Version has been processed and is ready for + Activation. + - name: Activating + description: > + The Software.Version is in the process of being Activated. + - name: Active + description: > + The Software.Version is currently Active. + - name: Failed + description: > + The Software.Version failed during or after Activation. + - name: RequestedActivations + description: > + The possible RequestedActivation states of a Software.Version. + values: + - name: None + description: > + No action has been directed for this Software.Version. + - name: Active + description: > + The Software.Version has been requested for Activation. +# TODO: Specify "EAGAIN" type error when requested is unable to be acted on +# due to current system state. Currently, sdbusplus does not support +# errors on properties. diff --git a/xyz/openbmc_project/Software/ActivationBlocksTransition.interface.yaml b/xyz/openbmc_project/Software/ActivationBlocksTransition.interface.yaml new file mode 100644 index 0000000..51fbc8e --- /dev/null +++ b/xyz/openbmc_project/Software/ActivationBlocksTransition.interface.yaml @@ -0,0 +1,13 @@ +description: > + Empty interface to indicate that the associated `Software.Version` should + prevent a state transition of the associated managed element while the + `Software.Version` is in `Activating` state. + + The specific state transition(s) to prevent are left to the implementation. + A typical use of this would be to prevent (delay) the power-on of a + managed host while the BIOS is being updated. The managed host, via + systemd transitions, might start the power-on sequence and then wait for + any object with this `ActivationBlocksTransition` interface to no longer be + in `Activating` state. Causal ordering of dbus operations can prove that + no update is currently being performed and the power-on sequence may safely + continue. diff --git a/xyz/openbmc_project/Software/ActivationProgress.interface.yaml b/xyz/openbmc_project/Software/ActivationProgress.interface.yaml new file mode 100644 index 0000000..9f96246 --- /dev/null +++ b/xyz/openbmc_project/Software/ActivationProgress.interface.yaml @@ -0,0 +1,8 @@ +description: > + Activation progress for an associated xyz.openbmc_project.Software.Version. +properties: + - name: Progress + type: uint8 + description: > + An integer between 0 and 100 representing the percentage complete of + the current activation progress. diff --git a/xyz/openbmc_project/Software/ExtendedVersion.interface.yaml b/xyz/openbmc_project/Software/ExtendedVersion.interface.yaml new file mode 100644 index 0000000..0bcc419 --- /dev/null +++ b/xyz/openbmc_project/Software/ExtendedVersion.interface.yaml @@ -0,0 +1,7 @@ +description: > + An extended version string for a xyz.openbmc_project.Software.Version. +properties: + - name: ExtendedVersion + type: string + description: > + Extended version of the level. diff --git a/xyz/openbmc_project/Software/README.md b/xyz/openbmc_project/Software/README.md new file mode 100644 index 0000000..f732e56 --- /dev/null +++ b/xyz/openbmc_project/Software/README.md @@ -0,0 +1,159 @@ +# 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. + +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 dbus 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/active/`, an association of type +`{activation,software_version}` between the `Software.Version` and +`Software.Activation`, and an association of type `{active_image,item}` between +the `Inventory.Item` and `Software.Activation`. 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 dbus 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 dbus 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>/active_image` 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. + diff --git a/xyz/openbmc_project/Software/RedundancyPriority.interface.yaml b/xyz/openbmc_project/Software/RedundancyPriority.interface.yaml new file mode 100644 index 0000000..4f7ba27 --- /dev/null +++ b/xyz/openbmc_project/Software/RedundancyPriority.interface.yaml @@ -0,0 +1,23 @@ +description: > + The priority, for redundancy purposes, of the associated + xyz.openbmc_project.Software.Version. +properties: + - name: Priority + type: uint8 + description: > + The priority order specified for the associated Software.Version, + represented as a value between 0 (High) and 127 (Low). Any value + above 127 has implementation-specific purpose. + + Only one Software.Version, per associated device, may be at any + particular priority. A requested priority change may cause other + Software.Versions to change priority. + + A dual-sided redundancy model could be represented by two + Software.Version associations, one of which is at priority 0 and the + other at priority 1. When a new image is Activated, the old + priority-1 association is deleted, the old priority-0 association + becomes priority-1, and the new image is assigned priority-0. +# TODO: Specify "EAGAIN" type error when priority is unable to be modified +# due to current system state. Currently, sdbusplus does not support +# errors on properties. diff --git a/xyz/openbmc_project/Software/Version.interface.yaml b/xyz/openbmc_project/Software/Version.interface.yaml new file mode 100644 index 0000000..f655af0 --- /dev/null +++ b/xyz/openbmc_project/Software/Version.interface.yaml @@ -0,0 +1,32 @@ +description: > + Simple definition of a Software or Firmware version. +properties: + - name: Version + type: string + description: > + The version identifier. + - name: Purpose + type: enum[self.VersionPurpose] + description: > + The purpose of the version. As in, what can it be used for or + applied to? +enumerations: + - name: VersionPurpose + description: > + An enumeration of possible purposes of the version. + values: + - name: Unknown + description: > + The version is of unknown purpose. + - name: Other + description: > + The version is of some other purpose. + - name: System + description: > + The version is an aggregate for the system as a whole. + - name: BMC + description: > + The version is a version for the BMC. + - name: Host + description: > + The version is a version for a managed host. |