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>
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
+ ```
+