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