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