Document BMC flash update enhancements

The BMC flash update process was enhanced to allow the images to be
written to flash while the system is operational allowing progress
to be mointored.

Update the documentation describing how to use the new interfaces.
Also add or update the description of the prior interface.

Fixes: openbmc/openbmc#293
Signed-off-by: Milton Miller <[email protected]>
Signed-off-by: Jeremy Kerr <[email protected]>

code-update.md

@@ -29,36 +29,91 @@ that can be updated on the BMC:
 
     The OpenBMC bootloader
 
+Preparing for BMC code Update
+-----------------------------
+
+The BMC normally runs with the read-write and read-only file systems
+mounted, which means these images may be read (and written, for the
+read-write filesystem) at any time.  Because the updates are distributed
+as complete file system images, these filesystems have to be unmounted
+to replace them with new images.  To unmount these file systems all
+applications must be stopped.
+
+By default an orderly `reboot` will stop all applications and unmount
+the root filesystem, and the images copied into the `/run/initramfs`
+directory will be applied at that point before restarting.  This also
+applied to the `shutdown` and `halt` commands -- they will write the
+flash before stopping.
+
+As an alternative, the an option can be parsed by the `init` script in
+the initramfs to copy the required contents of these filesystems into
+RAM so the images can be applied while the rest of the application stack
+is running and progress can be monitored over the network.  The
+`update` script can then be called to write the images while the
+system is operational and its progress ouput monitored.
+
 Update from the OpenBMC shell
 -----------------------------
 
-To update from the OpenBMC shell, copy one or more of these `image-*` files to
-the directory:
+To update from the OpenBMC shell, follow the steps in this section.
+
+It is recommended that the BMC be prepared for update:
+
+    fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
+    reboot
+
+Copy one or more of these `image-*` files to the directory:
 
     /run/initramfs/
 
-(preserving the filename), then reboot. Before the system reboots, the new image
-will be copied to the appropriate flash partition.
+(preserving the filename), then run the `update` script to apply the images:
+
+    /run/initramfs/update
+
+then reboot to finish applying:
 
+    reboot
+
+During the reboot process the `update` script will be invoked after
+the file systems are unmounted to complete the update process.
+
+Some optional features are available, see the help for more details:
+
+    /run/initramfs/update --help
 
 Update via REST
 ---------------
 
 An OpenBMC system can download an update image from a TFTP server, and apply
 updates, controlled via REST. The general procedure is:
 
- 1. Configure update settings
- 2. Initiate update
- 3. Check flash status
+ 1. Prepare system for update
+ 2. Configure update settings
+ 3. Initiate update
+ 4. Check flash status
+ 5. Reboot the BMC
+
+### Prepare system for update
+
+Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc` object:
+
+    curl -b cjar -k -H "Content-Type: application/json" -X POST \
+        -d '{"data": ["<TFTP server IP address>", "<filename>"]}' \
+        https://bmc/org/openbmc/control/flash/bmc/action/prepareForUpdate
+
+This will setup the u-boot environment and reboot the BMC.   If no other
+images were pending the BMC should return in about 2 minutes.
+
 
 ### Configure update settings
 
 There are a few settings available to control the update process:
 
- * `preserve_network_settings`: Preserve network settings, only needed if updating uboot
- * `restore_application_defaults`: update read-only file system
+ * `preserve_network_settings`: Preserve network settings, only needed if updating the whole flash
+ * `restore_application_defaults`: update (clear) the read-write file system
  * `update_kernel_and_apps_only`: update kernel and initramfs
- * `clear_persistent_files`: Erase persistent files
+ * `clear_persistent_files`: ignore the persistent file list when reseting applications defaults
+ * `auto_apply`: Attempt to write the images by invoking the `Apply` method after the images are unpacked.
 
 To configure the update settings, perform a REST PUT to
 `/control/flash/bmc/attr/<setting>`. For example:
@@ -77,15 +132,44 @@ Perform a POST to invoke the `updateViaTftp` method of the `/flash/bmc` object:
 
 ### Check flash status
 
-You can query the progress of the flash with a simple GET request:
+You can query the progress of the download and image verificaton with
+a simple GET request:
 
     curl -b cjar -k https://bmc/org/openbmc/control/flash/bmc
 
+Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc` object:
+
+    curl -b cjar -k -H "Content-Type: application/json" -X POST \
+        -d '{"data": []}' \
+        https://bmc/org/openbmc/control/flash/bmc/action/GetUpdateProgress
+
+
+Note: the status will not advance from `Writing images to flash` without
+calling the `GetUpdateProgress` method.
+
+If the status is `Image ready to apply.` then you can either initiate
+a reboot or call the Apply method to start the process of writing the
+flash.
+
+### Reboot the BMC
+
+To start using the new images, reboot the BMC using the warmReset method
+of the BMC control object:
+
+
+    curl -b cjar -k -H "Content-Type: application/json" -X POST \
+        -d '{"data": []}' \
+        https://bmc/org/openbmc/control/bmc0/action/warmReset
+
+
 Host code update
 ================
 
-Using a similar method, we can update the host firmware (or "BIOS"), by
-performing a POST request to call the `updateViaTftp` method of
+The host firmware (or "BIOS") can be updated in a similar method.  Because
+the BMC does not use the host firmware it is updated when the download is
+completed.  This assumes the host is not accessing its firmware.
+
+Perform a POST request to call the `updateViaTftp` method of
 `/control/flash/bios` (instead of `/control/flash/bmc` used above). To initiate
 the update:
 

dbus-interfaces.md

@@ -306,13 +306,18 @@ notifications.
 The control.BmcFlash interface allows applications update the BMC firmware.
 
 ### methods
-| name            | in signature | out signature | description                 |
-| --------------- | ------------ | ------------- | --------------------------- |
-| `updateViaTftp` | `ss`         | `void`        | **Perform a BMC firmware update using a TFTP server.**|
-|                 | `s`          |               | The ipv4 address of the TFTP server hosting the firmware image file.|
-|                 | `s`          |               | The name of the file containing the BMC firmware image.|
-| `update`        | `s`          | `void`        | **Perform a BMC firmware update with a file already on the BMC.**|
-|                 | `s`          |               | The name of the file containing the BMC firmware image.|
+| name                | in signature | out signature | description                 |
+| ------------------- | ------------ | ------------- | --------------------------- |
+| `updateViaTftp`     | `ss`         | `void`        | **Perform a BMC firmware update using a TFTP server.**|
+|                     | `s`          |               | The ipv4 address of the TFTP server hosting the firmware image file.|
+|                     | `s`          |               | The name of the file containing the BMC firmware image.|
+| `update`            | `s`          | `void`        | **Perform a BMC firmware update with a file already on the BMC.**|
+|                     | `s`          |               | The name of the file containing the BMC firmware image.|
+| `PrepareForUpdate`  | `void`       | `void`        | **Reboot BMC with Flash content cached in RAM **|
+| `Abort`             | `void`       | `void`        | **Abort any pending, broken, or in-progress flash update**|
+| `Apply`             | `void`       | `void`        | **Initiate writing image into flash**|
+| `GetUpdateProgress` | `void`       | `s`           | **Display progress log `Apply` phase**|
+|                     |              | `s`           | The `state` and log output from `Apply` |
 
 ### signals
 | name           | signature | description                              |
@@ -324,12 +329,13 @@ The control.BmcFlash interface allows applications update the BMC firmware.
 ### properties
 | name                           | signature | description                     |
 | ------------------------------ | --------- | ------------------------------- |
-| `status`                       | `s`       | **?**                           |
+| `status`                       | `s`       | **Description of the phase of the update**        |
 | `filename`                     | `s`       | **The name of the file containing the BMC firmware image.**|
 | `preserve_network_settings`    | `b`       | **Perform a factory reset.**    |
-| `restore_application_defaults` | `b`       | **Perform a factory reset.**    |
-| `update_kernel_and_apps`       | `b`       | **Perform a factory reset.**    |
-| `clear_persistent_files`       | `b`       | **Perform a factory reset.**    |
+| `restore_application_defaults` | `b`       | **Clear modified files in read-write filesystem.**    |
+| `update_kernel_and_apps`       | `b`       | **Do not update bootloader (requires image pieces).**    |
+| `clear_persistent_files`       | `b`       | **Also remove persistent files when updating read-write filesystem.**    |
+| `auto_apply`                   | `b`       | **Attempt to apply image after unpacking (cleared if image verification fails)**    |
 
 ### namespace
 | path                             | required | description |