docs/designs/firmware-update-via-blobs.md

1 # In-Band Update of BMC Firmware (and others) using OEM IPMI Blob Transport
5 Created: 2018-10-18
19 update mechanism that can be done in-band between the host and the BMC.
21 In-band here refers to a communications channel that is directly connected
27 1. LPC Memory-Mapped Region
33 [primer](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
39 - Any update mechanism must provide support for UBI tarballs and legacy (static
40   layout) flash images. Leveraging the BLOB protocol allows a system to provide
43 - Any update mechanism must allow for triggering an image verification step
46 - Any update mechanism must allow implementing the data staging via different
47   in-band mechanisms.
49 - Any update mechanism must provide a handshake or equivalent protocol for
51   the P2A bridge and what region to use or whether to turn on the LPC memory map
54 - Any update mechanism must attempt to maintain security, insomuch as not
67 [phosphor-ipmi-flash design](https://github.com/openbmc/phosphor-ipmi-flash/blob/master/README.md)
68 through a BLOB handler. This is meant to supplant `phosphor-ipmi-flash`'s
69 current approach to centralize on one flexible handler.
83 identify the mechanism selected by the client-side. The stat command will return
88 | Flash Blob Id    | Type            |
89 | ---------------- | --------------- |
90 | `/flash/image`   | Static Layout   |
91 | `/flash/tarball` | UBI             |
92 | `/flash/bios`    | Host BIOS image |
94 The flash handler will determine what commands it should expect to receive and
95 responses it will return given the blob opened, based on the flags provided to
98 The flash handler will only allow one of the above blobs to be opened for a
99 sequence of commands, such that you cannot open `/flash/image` and then open
100 `/flash/bios` without completing (or later aborting) the first update process
106 | ------------- | ------------------------------- |
107 | `/flash/hash` | Whichever flash blob was opened |
109 The flash handler will only allow one open file at a time, such that if the host
117 When a transfer is active, it'll create a blob_id of `/flash/active/image` and
118 `/flash/active/hash`.
125 Further on the ideal command sequence below.
128 | --------------- | ------------------------ |
129 | `/flash/verify` | Verify Trigger Mechanism |
138 The update blob id is available once `/flash/verify` is closed with a valid
139 image or tarball. The update blob needs to be opened and commit() called on that
142 The update process can be checked periodically by calling stat() on the update
146 | --------------- | ------------------------ |
147 | `/flash/update` | Trigger Update Mechanism |
154 deletion of update artifacts on failure, or success. It can be implemented to do
162 process. The host tool will only use it on failure cases. Any other tool
171 | ---------------- | ------------------------- |
172 | `/flash/cleanup` | Trigger Cleanup Mechanism |
176 Similarly to the OEM IPMI Flash protocol, the flash image will be staged in a
177 compile-time configured location.
184 The update mechanism will expect a specific sequence of commands depending on
192 1. Open (`/flash/hash`)
195 1. Open (`/flash/verify`)
199 1. Open (`/flash/update`)
210 1. Open (`/flash/hash`)
214 1. Open (`/flash/verify`)
218 1. Open (`/flash/update`)
230 1. Open (`/flash/hash`)
235 1. Open (`/flash/verify`)
239 1. Open (`/flash/update`)
266 mechanisms on a platform, see the `Stat` command below.
289 hash) indicating they are in progress. The name will be `flash/active/image` and
290 `flash/active/hash` which has no meaning beyond representing the current update
304 The write command's contents will depend on the transport mechanism. This
337 If this command is called on the session of the firmware image itself, nothing
338 will happen at present. It will return a no-op success.
340 If this command is called on the session for the hash image, nothing will happen
341 at present. It will return a no-op success.
343 If this command is called on the session for the verify blob id, it'll trigger a
349 on that response are below under BmcBlobSessionStat.
353 Close must be called on the firmware image and the hash file before opening the
357 have a specific behavior depending on the update. If it's UBI, it'll perform the
382 Blob stat on a blob_id (not SessionStat) will return the capabilities of the
390     uint32_t size; /* 0 - it's set to zero when there's no session */
397 If called pre-commit, it'll return the following information:
408 If it's called and the data transport mechanism is P2A, it'll return a 32-bit
424 If called post-commit on the verify file session, it'll return:
444 If called post-commit on the update file session, it'll return:
470 configuration data to the BMC for the in-band update. Currently that is only
486 There is currently another implementation in-use by Google that leverages the
501 the entire process has individual unit-tests that verify flags are checked, as
522 [Secure Flash Update Mechanism](https://github.com/openbmc/phosphor-ipmi-flash/blob/master/README.m…