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

1 # In-Band Update of BMC Firmware (and others) using OEM IPMI Blob Transport
32 Please read the IPMI BLOB protocol design as primer
33 [here](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
40   layout) flash images. Leveraging the BLOB protocol allows a system to provide
61 OpenBMC supports a BLOB protocol that provides primitives. These primitives
63 for specific "blobs." A blob in this context is a file path that is strictly
66 Sending the firmware image over the BLOB protocol will be done via routing the
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
73 To enforce sequencing control, the design requires that only one blob be open at
74 a time. If the verification blob is open, the other blobs cannot be opened, and
75 likewise if a client has a data blob open, the verification blob cannot be
80 The BLOB protocol allows a handler to specify a list of blob ids. This list will
84 the list of supported mechanisms for the blob.
86 The blob ids for the mechanisms will be as follows:
88 | Flash Blob Id    | Type            |
95 responses it will return given the blob opened, based on the flags provided to
103 The following blob ids are defined for storing the hash for the image:
105 | Hash Blob     | Id Mechanism                    |
107 | `/flash/hash` | Whichever flash blob was opened |
120 #### Verification Blob
122 The following blob id is defined once the image or hash upload has started. Its
127 | Trigger Blob    | Note                     |
132 successfully, it'll add an update blob id, defined below.
136 #### Update Blob
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
140 blob id to trigger the update mechanism.
143 blob id.
145 | Update Blob     | Note                     |
151 #### Cleanup Blob
153 The cleanup blob id is always present. The goal of this blob is to handle
158 The cleanup blob has no state or knowledge and is meant to provide a simple
160 BMC. The cleanup blob will delete a list of files. The cleanup blob has no state
166 To trigger the cleanup, simply open the blob, commit, and close. It has no
170 | Cleanup Blob     | Note                      |
179 Other mechanisms can readily be added by adding more blob ids or flags to the
247 mechanisms in place to ensure cleanup. If a session is left open after the blob
258 ### Blob Primitives
260 The update mechanism will implement the Blob primitives as follows.
264 The blob open primitive allows supplying blob specific flags. These flags are
275 /* These bits start in the blob specific range of the flags. */
343 If this command is called on the session for the verify blob id, it'll trigger a
354 verify blob.
382 Blob stat on a blob_id (not SessionStat) will return the capabilities of the
474 The write meta command's blob will be this structure:
495 is not an expected performance impact, as the blob handler existing only
496 generates a couple extra entries during the blob enumerate command's response.
522 [Secure Flash Update Mechanism](https://github.com/openbmc/phosphor-ipmi-flash/blob/master/README.m…