xref: /openbmc/phosphor-ipmi-flash/README.md (revision 0077e34cfaca539f750014aa63ff491dca70ee1d)
1# Secure Flash Update Mechanism
2
3This document describes the OpenBmc software implementing the secure flash
4update mechanism.
5
6The primary details are [here](https://github.com/openbmc/docs/blob/master/designs/firmware-update-via-blobs.md).
7
8## Building and using the host-tool
9
10This repo contains a host-tool implementation for talking to the corresponding
11BMC blob handler.
12
13### Building the host-tool
14
15The host-tool depends on ipmi-blob-tool and pciutils.
16
17#### Building libpciaccess
18
19Check out the [xorg-macros source](https://gitlab.freedesktop.org/xorg/util/macros).
20
21Then run these commands in the source directory.
22
23```
24./autogen.sh --prefix=/usr
25make install
26```
27
28Check out the [libpciaccess source](https://gitlab.freedesktop.org/xorg/lib/libpciaccess).
29
30Then run these commands in the source directory.
31
32```
33./autogen.sh
34make
35make install
36```
37
38#### Building ipmi-blob-tool
39
40Check out the [ipmi-blob-tool source](https://github.com/openbmc/ipmi-blob-tool).
41
42Then run these commands in the source directory.
43
44```
45./bootstrap.sh
46./configure
47make
48make install
49```
50
51#### Building fmtlib
52
53Check out the [fmtlib source](https://github.com/fmtlib/fmt).
54
55Then run these commands in the source directory.
56
57```
58mkdir build && cd build
59cmake ..
60make
61make install
62```
63
64#### Building span-lite
65
66Check out the [span-lite source](https://github.com/martinmoene/span-lite).
67
68Then run these commands in the source directory.
69
70```
71mkdir build && cd build
72cmake ..
73make
74make install
75```
76
77#### Building stdplus
78
79Check out the [stdplus source](https://github.com/openbmc/stdplus).
80
81Then run these commands in the source directory.
82
83```
84meson setup -Dexamples=false -Dtests=disabled builddir
85ninja -C builddir
86ninja -C builddir install
87```
88
89#### Building burn_my_bmc (the host-tool)
90
91Check out the [phosphor-ipmi-flash source](https://github.com/openbmc/phosphor-ipmi-flash).
92
93Then run these commands in the source directory.
94
95```
96./bootstrap.sh
97./configure --disable-build-bmc-blob-handler
98make
99make install
100```
101
102*NOTE:* When building from the OpenBMC SDK your configuration call will be:
103
104```
105./configure --enable-oe-sdk --host "$(uname -m)" --disable-build-bmc-blob-handler AR=x86_64-openbmc-linux-gcc-ar RANLIB=x86_64-openbmc-linux-gcc-ranlib
106```
107
108### Parameters
109
110The host-tool has parameters that let the caller specify every required detail.
111
112The required parameters are:
113
114 Parameter  | Options  | Meaning
115----------- | -------- | -------
116`command`   | `update` | The tool should try to update the BMC firmware.
117`interface` | `ipmibt`, `ipmilpc`, `ipmipci`, `ipminet`, `ipmipci-skip-bridge-disable` | The data transport mechanism, typically `ipmilpc`. The `ipmipci-skip-bridge-disable` is `ipmipci` but does not disable the bridge after.
118`image`     | path     | The BMC firmware image file (or tarball)
119`sig`       | path     | The path to a signature file to send to the BMC along with the image file.
120`type`      | blob ending | The ending of the blob id.  For instance `/flash/image` becomes a type of `image`.
121
122If you're using an LPC data transfer mechanism, you'll need two additional
123parameters: `address` and `length`.  These values indicate where on the host
124you've reserved memory to be used for the transfer window.
125
126If you're using a net data transfer mechanism, you'll also need two additional
127parameters: `hostname` and `port`. These specify which address and port the tool
128should attempt to connect to the BMC using. If unspecified, the `port` option
129defaults to 623, the same port as IPMI LAN+.
130
131## Introduction
132
133This supports three methods of providing the image to stage. You can send the
134file over IPMI packets, which is a very slow process. A 32-MiB image can take
135~3 hours to send via this method.  This can be done in <1 minutes via the PCI or
136net bridge, or just a few minutes via LPC depending on the size of the mapped
137area.
138
139This is implemented as a phosphor blob handler.
140
141The image must be signed via the production or development keys, the former
142being required for production builds. The image itself and the image signature
143are separately sent to the BMC for verification. The verification package
144source is beyond the scope of this design.
145
146Basically the IPMI OEM handler receives the image in one fashion or another and
147then triggers the `verify_image` service. Then, the user polls until the result
148is reported. This is because the image verification process can exceed 10
149seconds.
150
151### Using Legacy Images
152
153The image flashing mechanism itself is the initramfs stage during reboot. It
154will check for files named "`image-*`" and flash them appropriately for each
155name to section. The IPMI command creates a file `/run/initramfs/bmc-image` and
156writes the contents there. It was found that writing it in /tmp could cause OOM
157errors moving it on low memory systems, whereas renaming a file within the same
158folder seems to only update the directory inode's contents.
159
160### Using UBI
161
162The staging file path can be controlled via software configuration.  The image
163is assumed to be the tarball contents and is written into `/tmp/{tarball_name}.gz`
164
165TODO: Flesh out the UBI approach.
166
167## Configuration
168
169To use `phosphor-ipmi-flash` a platform must provide a configuration.  A
170platform can configure multiple interfaces, such as both lpc and pci.  However,
171a platform should only configure either static layout updates, or ubi.  If
172enabling lpc, the platform must specify either aspeed or nuvoton.  The system
173also supports receiving BIOS updates.
174
175The following are the two primary configuration options, which control how the
176update is treated.
177
178Option                   | Meaning
179------------------------ | -------
180`--enable-static-layout` | Enable treating the update as a static layout update.
181`--enable-tarball-ubi`   | Enable treating the update as a tarball for UBI update.
182`--enable-host-bios`     | Enable receiving the update for a host bios update.
183
184The following are configuration options for how the host and BMC are meant to
185transfer the data.  By default, the data-in-IPMI mechanism is enabled.
186
187There are three configurable data transport mechanisms, either staging the bytes
188via the LPC memory region, the PCI-to-AHB memory region, or sending over a
189network connection.  Because there is only one `MAPPED_ADDRESS` variable at
190present, a platform should not configure LPC and P2A at the same time.  The
191platform's device-tree may have the region locked to a specific driver
192(lpc-aspeed-ctrl), preventing the region from other use.
193
194***NOTE:*** It will likely be possible to configure both LPC and P2A in the near
195future.
196
197Variable              | Default | Meaning
198--------------------- | ------- | -------
199`MAPPED_ADDRESS`      | 0       | The address used for mapping P2A or LPC into the BMC's memory-space.
200
201If a platform enables p2a as the transport mechanism, a specific vendor must be
202selected via the following configuration option.  Currently, only one is
203supported.
204
205Option                 | Meaning
206-----------------------| -------
207`--enable-aspeed-p2a`  | Use with ASPEED parts.
208
209If a platform enables lpc as the transport mechanism, a specific vendor must be
210selected via the following configuration option.  Currently, only two are
211supported.
212
213Option                 | Meaning
214---------------------- | -------
215`--enable-aspeed-lpc`  | Use with ASPEED parts.
216`--enable-nuvoton-lpc` | Use with Nuvoton parts.
217
218A platform may also enable the network transport mechanism.
219
220NOTE: This mechanism is only intended to be used in-band and not exposed
221externally, as it doesn't implement any encryption or integrity verification.
222
223Option                | Meaning
224----------------------| -------
225`--enable-net-bridge` | Enable net transport bridge
226
227There are also options to control an optional clean up mechanism.
228
229Option                    | Meaning
230------------------------- | -------
231`--enable-cleanup-delete` | Provide a simple blob id that deletes artifacts.
232
233If the update mechanism desired is simply a BMC reboot, a platform can just
234enable that directly.
235
236Option                   | Meaning
237------------------------ | -------
238`--enable-reboot-update` | Enable use of reboot update mechanism.
239
240If you would like the update status to be tracked with a status file, this
241option can be enabled. Note that `--enable-update-status` option and the above
242`--enable-reboot-update` option cannot be enabled at the same time.
243
244Option                   | Meaning
245------------------------ | -------
246`--enable-update-status` | Enable use of update status file.
247
248If you would like to use host memory access to update on a PPC platform, this configuration option needs to be enabled.
249
250Option          | Meaning
251--------------- | -------
252`--enable-ppc`  | Enable PPC host memory access.
253
254### Internal Configuration Details
255
256The following variables can be set to whatever you wish, however they have
257usable default values.
258
259Variable                      | Default                    | Meaning
260----------------------------- | -------------------------- | -------------------------------------------------------------------------
261`STATIC_HANDLER_STAGED_NAME`  | `/run/initramfs/bmc-image` | The filename where to write the staged firmware image for static updates.
262`TARBALL_STAGED_NAME`         | `/tmp/image-update.tar`    | The filename where to write the UBI update tarball.
263`HASH_FILENAME`               | `/tmp/bmc.sig`             | The file to use for the hash provided.
264`PREPARATION_DBUS_SERVICE`    | `phosphor-ipmi-flash-bmc-prepare.target` | The systemd target started when the host starts to send an update.
265`VERIFY_STATUS_FILENAME`      | `/tmp/bmc.verify`          | The file checked for the verification status.
266`VERIFY_DBUS_SERVICE`         | `phosphor-ipmi-flash-bmc-verify.target`  | The systemd target started for verification.
267`UPDATE_DBUS_SERVICE`         | `phosphor-ipmi-flash-bmc-update.target`  | The systemd target started for updating the BMC.
268`UPDATE_STATUS_FILENAME`      | `/tmp/bmc.update`  | The file checked for the update status.
269`BIOS_STAGED_NAME`            | `/tmp/bios-image`  | The file to use for staging the bios firmware update.
270`BIOS_VERIFY_STATUS_FILENAME` | `/tmp/bios.verify` | The file checked for the verification status.
271`PREPARATION_BIOS_TARGET`     | `phosphor-ipmi-flash-bios-prepare.target` | The systemd target when the host starts to send an update.
272`VERIFY_BIOS_TARGET`          | `phosphor-ipmi-flash-bios-verify.target`  | The systemd target started for verification.
273`UPDATE_BIOS_TARGET`          | `phosphor-ipmi-flash-bios-update.target`  | The systemd target started for updating the BIOS.
274
275## JSON Configuration
276
277Read the [details](bmc_json_config.md) of the json configuration.  The json configurations are used to configure the BMC's flash handler behaviors.
278
279## Flash State Machine Details
280
281[This document](ipmi_flash.md) describes the details of the state machine
282implemented and how different interactions with it will respond.  This also
283describes how a host-side tool is expected to talk to it (triggering different
284states and actions).
285