commit 826e17355db0a575e0ad60e25bf82480ac711135
author Patrick Venture <venture@google.com> Fri May 31 08:42:18 2019 -0700
committer Patrick Venture <venture@google.com> Fri May 31 10:25:47 2019 -0700
tree 2c05adfb0ef9138055f360d5cec48d508dd4613a
parent 00d5f0de56f3e453be37c2ffc45418fb406396a2

README: add calling contract details

Provide contract details for what handlers can expect from the blob
manager.  This saves extra checks within the handler.

Incidental markdown cleanup.

Signed-off-by: Patrick Venture <venture@google.com>
Change-Id: I572fdfb9e726d9f4d1ba89bb92b38c67cd7f07e2

README.md

diff --git a/README.md b/README.md
index fcb4fdf..e3966c7 100644
--- a/README.md
+++ b/README.md
@@ -39,8 +39,9 @@
 If an identifier is malformed, e.g. does not have a trailing NUL-byte or is
 otherwise unrecognizable by the BMC, an error is returned.
 
-The OEM Number to use with these commands is [openbmc oen](https://github.com/openbmc/phosphor-host-ipmid/blob/194375f2676715a0e0697bab63234a4efe39fb96/include/ipmid/iana.hpp#L12)
- 49871.
+The OEM Number to use with these commands is
+[openbmc oen](https://github.com/openbmc/phosphor-host-ipmid/blob/194375f2676715a0e0697bab63234a4efe39fb96/include/ipmid/iana.hpp#L12)
+49871.
 
 ## Commands
 
@@ -204,9 +205,8 @@
 ```
 
 Each blob defines its own commit behavior. A BMC firmware blob may be verified
-and saved to the filesystem. Commit operations may require additional
-data, which
-would be provided following the structure in the IPMI packet.
+and saved to the filesystem. Commit operations may require additional data,
+which would be provided following the structure in the IPMI packet.
 
 The commit operation may exceed the IPMI timeout duration of ~5 seconds
 (implementation dependant). Callers are expected to poll on `BmcBlobSessionStat`
@@ -342,9 +342,9 @@
 ```
 
 Immediately following this structure are the bytes to write. The length of the
-entire packet is variable and handled at a higher level, therefore the number
-of bytes to write is the size of the command body less the OEN and sub-command
-(4 bytes) and less the structure size.
+entire packet is variable and handled at a higher level, therefore the number of
+bytes to write is the size of the command body less the OEN and sub-command (4
+bytes) and less the structure size.
 
 On success it will return a success completion code.
 
@@ -369,3 +369,14 @@
 associated blob type’s cleansing routine will be invoked, and the associated
 session ID will be freed. This function will be invoked from the `BmcBlobOpen`
 command handler, though not more than once every minute.
+
+## Handler Calling Contract
+
+The blob manager provides the following calling contract guarantees:
+
+*   The blob manager will only call `open()` on your handler if the handler
+    responds that they can handle the path.
+*   The blob manager will only call a session-based command against your handler
+    if that session is already open (e.g. `stat()` or `commit()`).
+    *   The caveat is the open command where the session is provided to the
+        handler within the call.