1OpenBMC Code Update 2=================== 3 4**Important Note:** 5* The REST APIs described below are deprecated. 6 Please follow [code-update.md](code-update.md) for the new APIs to do code 7 update. 8* The rest part of this document is still valid. 9 10The host code update can be found here: 11[host-code-update.md](host-code-update.md) 12 13After building OpenBMC, you will end up with a set of image files in 14`tmp/deploy/images/<platform>/`. The `image-*` symlinks correspond to components 15that can be updated on the BMC: 16 17 * `image-bmc` → `obmc-phosphor-image-<platform>-<timestamp>.static.mtd` 18 19 The complete flash image for the BMC 20 21 * `image-kernel` → `fitImage-obmc-phosphor-initramfs-<platform>.bin` 22 23 The OpenBMC kernel FIT image (including the kernel, device tree, and initramfs) 24 25 * `image-rofs` → `obmc-phosphor-image-<platform>.squashfs-xz` 26 27 The read-only OpenBMC filesystem 28 29 * `image-rwfs` → `rwfs.jffs2` 30 31 The read-write filesystem for persistent changes to the OpenBMC filesystem 32 33 * `image-u-boot` → `u-boot.bin` 34 35 The OpenBMC bootloader 36 37Additionally, there are two tarballs created that can be deployed and unpacked by REST: 38 39 * `<platform>-<timestamp>.all.tar` 40 41 The complete BMC flash content: A single file (`image-bmc`) wrapped in a 42 tar archive. 43 44 * `<platform>-<timestamp>.tar` 45 46 Partitioned BMC flash content: Multiple files wrapped in a tar archive, 47 one for each of the u-boot, kernel, ro and rw partitions. 48 49Preparing for BMC code Update 50----------------------------- 51 52The BMC normally runs with the read-write and read-only file systems 53mounted, which means these images may be read (and written, for the 54read-write filesystem) at any time. Because the updates are distributed 55as complete file system images, these filesystems have to be unmounted 56to replace them with new images. To unmount these file systems all 57applications must be stopped. 58 59By default, an orderly `reboot` will stop all applications and unmount 60the root filesystem, and the images copied into the `/run/initramfs` 61directory will be applied at that point before restarting. This also 62applied to the `shutdown` and `halt` commands -- they will write the 63flash before stopping. 64 65As an alternative, an option can be parsed by the `init` script in 66the initramfs to copy the required contents of these filesystems into 67RAM so the images can be applied while the rest of the application stack 68is running and progress can be monitored over the network. The 69`update` script can then be called to write the images while the 70system is operational and its progress output monitored. 71 72Update from the OpenBMC shell 73----------------------------- 74 75To update from the OpenBMC shell, follow the steps in this section. 76 77It is recommended that the BMC be prepared for update (note that the 78environment variable needs to be set twice for initramfs be able to 79read it due to the U-Boot redundant environments): 80 81 fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram 82 fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram 83 reboot 84 85Copy one or more of these `image-*` files to the directory: 86 87 /run/initramfs/ 88 89(preserving the filename), then run the `update` script to apply the images: 90 91 /run/initramfs/update 92 93then reboot to finish applying: 94 95 reboot 96 97During the reboot process, the `update` script will be invoked after 98the file systems are unmounted to complete the update process. 99 100Some optional features are available, see the help for more details: 101 102 /run/initramfs/update --help 103 104Update via REST 105--------------- 106 107An OpenBMC system can download an update image from a TFTP server, and apply 108updates, controlled via REST. The general procedure is: 109 110 1. Prepare system for update 111 2. Configure update settings 112 3. Initiate update 113 4. Check flash status 114 5. Apply update 115 6. Reboot the BMC 116 117### Prepare system for update 118 119Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc` object: 120 121 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 122 -d '{"data": []}' \ 123 https://${bmc}/org/openbmc/control/flash/bmc/action/prepareForUpdate 124 125This will setup the u-boot environment and reboot the BMC. If no other 126images were pending the BMC should return in about 2 minutes. 127 128 129### Configure update settings 130 131There are a few settings available to control the update process: 132 133 * `preserve_network_settings`: Preserve network settings, only needed if updating the whole flash 134 * `restore_application_defaults`: update (clear) the read-write file system 135 * `update_kernel_and_apps`: update kernel and initramfs. 136 If the partitioned tarball will be used for update then this option 137 must be set. Otherwise, if the complete tarball will be used then 138 this option must not be set. 139 * `clear_persistent_files`: ignore the persistent file list when resetting applications defaults 140 * `auto_apply`: Attempt to write the images by invoking the `Apply` method after the images are unpacked. 141 142To configure the update settings, perform a REST PUT to 143`/control/flash/bmc/attr/<setting>`. For example: 144 145 curl -b cjar -k -H "Content-Type: application/json" -X PUT \ 146 -d '{"data": 1}' \ 147 https://${bmc}/org/openbmc/control/flash/bmc/attr/preserve_network_settings 148 149### Initiate update 150 151Perform a POST to invoke the `updateViaTftp` method of the `/flash/bmc` object: 152 153 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 154 -d '{"data": ["<TFTP server IP address>", "<filename>"]}' \ 155 https://${bmc}/org/openbmc/control/flash/bmc/action/updateViaTftp 156 157Note the `<filename>` shall be a tarball. 158 159### Check flash status 160 161You can query the progress of the download and image verification with 162a simple GET request: 163 164 curl -b cjar -k https://${bmc}/org/openbmc/control/flash/bmc 165 166Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc` object: 167 168 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 169 -d '{"data": []}' \ 170 https://${bmc}/org/openbmc/control/flash/bmc/action/GetUpdateProgress 171 172Note: 173 174 * During downloading the tarball, the progress status is `Downloading` 175 * After the tarball is downloaded and verified, the progress status becomes `Image ready to apply`. 176 177### Apply update 178If the status is `Image ready to apply.` then you can either initiate 179a reboot or call the Apply method to start the process of writing the 180flash: 181 182 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 183 -d '{"data": []}' \ 184 https://${bmc}/org/openbmc/control/flash/bmc/action/Apply 185 186Now the image is being flashed, you can check the progress with above step’s command as well. 187 188* During flashing the image, the status becomes `Writing images to flash` 189* After it's flashed and verified, the status becomes `Apply Complete. Reboot to take effect.` 190 191### Reboot the BMC 192 193To start using the new images, reboot the BMC using the warmReset method 194of the BMC control object: 195 196 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 197 -d '{"data": []}' \ 198 https://${bmc}/org/openbmc/control/bmc0/action/warmReset 199 200