openbmc/phosphor-ipmi-blobs/README.md

1 # Phosphor Blob Transfer Interface
3 This document describes the commands implementing a generic blob transfer
5 to blob-specific implementations. Introduction This mechanism supports reading
6 and writing from a generic blob store. This mechanism can be leveraged to
12 - Opening a blob for reading or writing
13 - Writing blob content
14 - Committing a blob
15 - Polling until the blob has been committed
16 - Closing a blob
17 - Reading blob content
18 - Deleting a blob
26 Aspeed") MMIO bridges are currently unsupported. Blob Identifiers Blobs are
28 implementation-specific blob identifiers; some blobs may have single well-known
30 the rest of the blob name. For example, "/g/bmc_firmware" may represent a single
31 well-known blob that supports BMC firmware updates, whereas "/g/skm/[N]" may
33 when opening the blob.
35 Blob identifiers are limited based on the maximum size of the IPMI packet. This
43 [openbmc oen](https://github.com/openbmc/phosphor-host-ipmid/blob/194375f2676715a0e0697bab63234a4ef…
47 The following details each subcommand in the blob spec. In the following, any
78     uint32_t blob_idx; /* 0-based index of blob to retrieve. */
82 The BMC will return the corresponding blob identifier:
91 Note that the index for a given blob ID is not expected to be stable across a
93 to `BmcBlobEnumerate`, to collect all blob IDs. Callers can then call
94 `BmcBlobStat` with each blob ID. If this process is interleaved with Open or
106     char     blob_id[]; /* Must correspond to a valid blob. */
110 The flags field allows the caller to specify whether the blob is being opened
118     <bits 8-15 given blob-specific definitions>
122 If the `WRITE` flag is specified, the BMC will mark the specified blob as "open
123 for writing". Optional blob-specific behavior: if the blob has been open for
129 blob identifier.
140 The BmcBlobRead command is used to read blob data. It expects to receive a body
152 Blob handlers may require the blob’s "state" to equal `OPEN_R` before reading is
169 offset or if the host tries to read at the end of the blob, an empty successful
202     uint8_t  commit_data[]; /* Optional blob-specific commit data. */
206 Each blob defines its own commit behavior. A BMC firmware blob may be verified
229 The BMC marks the specified blob as closed. On success, the BMC returns a
234 The `BmcBlobDelete` command is used to delete a blob. Not all blobs will support
240     char     blob_id[]; /* Must correspond to a valid blob. */
244 If the operation is supported, the blob is deleted. On success, the BMC returns
246 the blob.
250 The `BmcBlobStat` command is used to retrieve statistics about a blob. Not all
257     char     blob_id[]; /* Must correspond to a valid blob. */
267     uint32_t size; /* Size in bytes of the blob. */
269     uint8_t  metadata[]; /* Optional blob-specific metadata. */
283     <bits 8-15 given blob-specific definitions>
287 If the state is `COMMITTING`, the blob is not currently available for reading or
288 writing. If the state is `COMMITTED`, the blob may be available for reading.
290 The size field may be zero if the blob does not support reading.
292 Immediately following this structure are optional blob-specific bytes. The
298 If the blob is open or committed but has been inactive for longer than the
299 specified activity timeout, the blob is closed, and blob_status is set to
305 However, this command operates on sessions, rather than blob IDs. Not all blobs
307 useful than raw blob IDs.
320     uint32_t size; /* Size in bytes of the blob. */
322     uint8_t  metadata[]; /* Optional blob-specific metadata. */
329 blob-specific, and not all blobs must support it.
364 Each blob type will define an operation for cleansing stale sessions. This could
368 associated blob type’s cleansing routine will be invoked, and the associated
374 The blob manager provides the following calling contract guarantees:
376 - The blob manager will only call `open()` on your handler if the handler
378 - The blob manager will only call a session-based command against your handler
382 - The blob manager will only call `delete()` on a blob if there are no open
383   sessions to that blob id.