diff options
Diffstat (limited to 'code-update/ubi-code-update.md')
| -rw-r--r-- | code-update/ubi-code-update.md | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/code-update/ubi-code-update.md b/code-update/ubi-code-update.md new file mode 100644 index 0000000..80f6e41 --- /dev/null +++ b/code-update/ubi-code-update.md @@ -0,0 +1,118 @@ +OpenBMC 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: [code-update.md](code-update.md) + +### Steps to 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. The UBI BMC tar image contains 5 files: u-boot, +kernel, ro, and rw partitions and the MANIFEST file, which contains information +about the image such as the image purpose and version. A MANIFEST file might +look like +``` +purpose=xyz.openbmc_project.Software.Version.VersionPurpose.BMC +version=v1.99.10 +``` + +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 + ``` + +### Implementation + +More information about the implementation of the UBI code update can be found at +https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Software +and https://github.com/openbmc/phosphor-bmc-code-mgmt |
