Software: add initial software-version mgmt

Change-Id: I3b50488b8383c595b4b41375ea0d62d62bdc0eed
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>

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.