docs: add more details to the state transitions
Add more details to the state transitions, as well as an expected
transition sequence for an update. Further patches will elaborate on
the expected behavior of the commands at each state to show which are
accepted.
Signed-off-by: Patrick Venture <venture@google.com>
Change-Id: I45d36b13a1dad640fa2b497f18151724cd3d86e5
diff --git a/ipmi_flash.md b/ipmi_flash.md
index 53eb920..ade81b2 100644
--- a/ipmi_flash.md
+++ b/ipmi_flash.md
@@ -10,26 +10,65 @@
At each state, each method has a specific effect, depending on a variety of
details, and sometimes the behavior is consistent regardless of overall state.
+Opening the active image or hash always fails:
+
+* `open(/flash/active/image)` returns false -- file cannot be opened.
+* `open(/flash/active/hash)` returns false -- file cannot be opened.
+
+The two files are only present once their corresponding blob has been opened.
+
## `notYetStarted`
**The starting state.**
+* `open(/flash/image)`
+* `open(/flash/tarball)`
+* `open(/flash/hash)`
+* `open(/flash/verify)`
+* `open(/flash/update)`
+
## `uploadInProgress`
**The BMC is expecting to receive bytes.**
+* `open(/flash/*)` returns false because `fileOpen == true`
+
+* `close(/flash/*)` triggers `state -> verificationPending`
+
+* `commit(/flash/*)` returns false
+
## `verificationPending`
**The BMC is ready for verification or more bytes.**
+* `open(/flash/image)` triggers `state -> uploadInProgress`
+* `open(/flash/tarball)` triggers `state -> uploadInProgress`
+* `open(/flash/hash)` triggers `state -> uploadInProgress`
+
+* `open(/flash/verify)`
+
+* `open(/flash/update)`
+
+* `commit(/flash/verify)` `state -> verificationStarted`
+
## `verificationStarted`
**The verification process has started, no more writes allowed.**
+* `open(/flash/*)` returns false because `state == verificationStarted`
+
+* `close(/flash/verify)` `state -> verificationCompleted`
+
## `verificationCompleted`
**The verification process has completed.**
+* `open(/flash/image)`
+* `open(/flash/tarball)`
+* `open(/flash/hash)`
+* `open(/flash/verify)`
+* `open(/flash/update)`
+
## `updatePending`
**The update process is pending.**
@@ -38,6 +77,31 @@
**The update process has started.**
+* `open(/flash/*)`r eturns false because `fileOpen == true`
+
## `updatedCompleted`
**The update has completed (optional state to reach)**
+
+# Expected State Transition Sequence
+
+Action | Before | After
+:----------------------- | :----: | :----------------:
+1. getBlobList() | NYS | NYS
+2. stat(/flash/image) | NYS | NYS
+3. open(/flash/image) | NYS | UIP
+4. write(...) | UIP | UIP
+5. close(/flash/image) | UIP | VP
+6. open(/flash/hash) | VP | UIP
+7. write(...) | UIP | UIP
+8. close(/flash/hash) | UIP | VP
+9. open(/flash/verify) | VP | VP
+10. commit(...) | VP | VS
+11. sessionStat(...) | VS | VS (if !completed)
+11. sessionStat(...) | VS | VC (if completed)
+12. close(/flash/verify) | VC | UP
+13. open(/flash/update) | UP | UP
+14. commit(...) | UP | US
+15. sessionStat(...) | US | US (if !completed)
+15. sessionStat(...) | US | UC (if completed)
+16. close(/flash/update) | UC | NYS