Document the UBI layout BMC code update process

OpenBMC supports two code update layouts, the default non-UBI
layout and the UBI layout which is used on Witherspoon. This
document is the UBI layout code update. This document describes
how to code update with the UBI layout. A lot of this information
was taken from openbmc/docs/code-update.md#host-code-update and
adapted for the BMC code update. More to come.

Change-Id: I640f222aa85fbf544da8555237392a30818685de
Signed-off-by: Gunnar Mills <gmills@us.ibm.com>

1 files changed, 104 insertions, 0 deletions

diff --git a/ubi-code-update.md b/ubi-code-update.md
new file mode 100644
index 0000000..aa1a9e2
--- /dev/null
+++ b/ubi-code-update.md
@@ -0,0 +1,104 @@
+BMC UBI Code Update
+==============
+
+Two BMC Code Updates layouts are available:
+
+ * Static, non-UBI layout - The default code update
+
+ * UBI layout - enabled via obmc-ubi-fs machine feature
+
+This document describes the UBI code update. The non-UBI code update can be
+found here: https://github.com/openbmc/docs/blob/master/code-update.md#openbmc--host-code-update
+
+The following are the steps to update the BMC if the UBI layout is enabled.
+
+1. Get a UBI BMC image tar:
+After building OpenBMC, you will end up with a set of image files in
+`tmp/deploy/images/<platform>/`. `obmc-phosphor-image-<platform>.ubi.mtd.tar` is
+the UBI BMC tar image.
+
+2. Transfer the generated UBI BMC image to the BMC via one of the following
+methods:
+  * Method 1: Via scp: Copy the generated UBI BMC image to the `/tmp/images/`
+    directory on the BMC.
+  * Method 2: Via REST Upload:
+  https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images
+  * Method 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
+    method of `/xyz/openbmc_project/software`.
+
+3. Note the version id generated for that image file. The version id is a hash
+value of 8 hexadecimal numbers, generated by SHA-512 hashing the version
+string contained in the image and taking the first 8 characters. Get the
+version id via one of the following methods:
+
+  * Method 1: From the BMC command line, note the most recent directory name
+    created under `/tmp/images/`, in this example it'd be `2a1022fe`:
+
+      ```
+      # ls -l /tmp/images/
+      total 0
+      drwx------    2 root     root            80 Aug 22 07:54 2a1022fe
+      drwx------    2 root     root            80 Aug 22 07:53 488449a2
+      ```
+
+  * Method 2: This method *only* works if there are no `Ready` images at the
+    start of transferring the image. Using the REST API, note the object that
+    has its Activation property set to Ready, in this example it'd be `2a1022fe`:
+
+      ```
+      $ curl -b cjar -k https://bmc/xyz/openbmc_project/software/enumerate
+      {
+        "data": {
+          "/xyz/openbmc_project/software/2a1022fe": {
+            "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
+      ```
+
+ * Method 3: Calculate the version id beforehand from the image with:
+
+      ```
+      tar xfO <UBI BMC tar image> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
+      ```
+
+
+4. To initiate the update, set the `RequestedActivation` property of the desired
+image to `Active`, substitute ``<id>`` with the hash value noted on the previous
+step, this will write the contents of the image to a UBI volume in the BMC chip
+via one of the following methods:
+
+  * Method 1: From the BMC command line:
+
+      ```
+      busctl set-property xyz.openbmc_project.Software.BMC.Updater \
+        /xyz/openbmc_project/software/<id> \
+        xyz.openbmc_project.Software.Activation RequestedActivation s \
+        xyz.openbmc_project.Software.Activation.RequestedActivations.Active
+
+      ```
+
+  * Method 2: Using the REST API:
+
+      ```
+      curl -b cjar -k -H "Content-Type: application/json" -X PUT \
+        -d '{"data":
+        "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
+        https://bmc/xyz/openbmc_project/software/<id>/attr/RequestedActivation
+      ```
+
+5. (Optional) Check the flash progress. This interface is only available during
+the activation progress and is not present once the activation is completed
+via one of the following:
+
+  * Method 1: From the BMC command line:
+
+      ```
+      busctl get-property xyz.openbmc_project.Software.BMC.Updater  \
+        /xyz/openbmc_project/software/<id> \
+        xyz.openbmc_project.Software.Activation Progress
+      ```
+
+  * Method 2: Using the REST API:
+
+      ```
+      curl -b cjar -k https://bmc/xyz/openbmc_project/software/<id>/attr/Progress
+      ```
+