1# Host Code Update
2
3Reference:
4https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software
5
6Following are the steps to update the host firmware (or "BIOS"). This assumes
7the host is not accessing its firmware.
8
91. Get a squashfs image:
10
11- Build op-build: https://github.com/open-power/op-build
12- After building, the image should be a tarball in the output/images directory
13  called <system type>.pnor.squashfs.tar
14
152. Transfer the generated squashfs image to the BMC via one of the following
16   methods:
17
18- Method 1: Via scp: Copy the generated squashfs image to the `/tmp/images/`
19  directory on the BMC.
20- Method 2: Via REST Upload:
21  https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images
22- Method 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
23  method of `/xyz/openbmc_project/software`.
24
25  ```
26  curl -b cjar -k -H "Content-Type: application/json" -X POST \
27    -d '{"data": ["<filename>", "<TFTP server IP address"]}' \
28    https://${bmc}/xyz/openbmc_project/software/action/DownloadViaTFTP
29  ```
30
313. Note the version id generated for that image file. The version id is a hash
32   value of 8 hexadecimal numbers, generated by SHA-512 hashing the version
33   string contained in the image and taking the first 8 characters. Get the
34   version id via one of the following methods:
35
36- Method 1: From the BMC command line, note the most recent directory name
37  created under `/tmp/images/`, in this example it'd be `2a1022fe`:
38
39  ```
40  # ls -l /tmp/images/
41  total 0
42  drwx------    2 root     root            80 Aug 22 07:54 2a1022fe
43  drwx------    2 root     root            80 Aug 22 07:53 488449a2
44  ```
45
46- Method 2: This method _only_ works if there are no `Ready` images at the start
47  of transferring the image. Using the REST API, note the object that has its
48  Activation property set to Ready, in this example it'd be `2a1022fe`:
49
50  ```
51  $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/enumerate
52  {
53    "data": {
54      "/xyz/openbmc_project/software/2a1022fe": {
55        "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
56  ```
57
58- Method 3: Calculate the version id beforehand from the image with:
59
60  ```
61  tar xfO <squashfs image tar> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
62  ```
63
644. To initiate the update, set the `RequestedActivation` property of the desired
65   image to `Active`, substitute `<id>` with the hash value noted on the
66   previous step, this will write the contents of the image to a UBI volume in
67   the PNOR chip via one of the following methods:
68
69- Method 1: From the BMC command line:
70
71  ```
72  busctl set-property org.open_power.Software.Host.Updater \
73    /xyz/openbmc_project/software/<id> \
74    xyz.openbmc_project.Software.Activation RequestedActivation s \
75    xyz.openbmc_project.Software.Activation.RequestedActivations.Active
76
77  ```
78
79- Method 2: Using the REST API:
80
81  ```
82  curl -b cjar -k -H "Content-Type: application/json" -X PUT \
83    -d '{"data":
84    "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
85    https://${bmc}/xyz/openbmc_project/software/<id>/attr/RequestedActivation
86  ```
87
885. (Optional) Check the flash progress. This interface is only available during
89   the activation progress and is not present once the activation is completed
90   via one of the following:
91
92- Method 1: From the BMC command line:
93
94  ```
95  busctl get-property org.open_power.Software.Host.Updater \
96    /xyz/openbmc_project/software/<id> \
97    xyz.openbmc_project.Software.Activation Progress
98  ```
99
100- Method 2: Using the REST API:
101
102  ```
103  curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>/attr/Progress
104  ```
105
1066. Check the activation is complete by verifying the Activation property is set
107   to Active via one of the following methods:
108
109- Method 1: From the BMC command line:
110
111  ```
112  busctl get-property org.open_power.Software.Host.Updater \
113    /xyz/openbmc_project/software/<id> \
114    xyz.openbmc_project.Software.Activation Activation
115  ```
116
117- Method 2: Using the REST API:
118
119  ```
120  curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
121  ```
122
123### Patching the host firmware
124
125Copy the partition binary file to `/usr/local/share/pnor/` on the BMC.
126
127The partition binary file must be named the same as the partition name that
128intends to patch, ex: `ATTR_TMP`.
129
130### Associations, MANIFEST File, Deleting an Image, Software Field Mode, and Software Factory Reset
131
132Information about associations, the MANIFEST file, deleting an image, software
133field mode, and software factory reset can be found at
134[code-update.md#associations](code-update.md#associations)
135
136### Implementation
137
138https://github.com/openbmc/openpower-pnor-code-mgmt
139