1# BMC-side state machine details
2
3***ONLY ONE BLOB IS ALLOWED OPEN AT A TIME***
4
5To avoid excessive complications, there is a restriction that only one blob
6within the firmware handler can be open at a time.
7
8The system starts in the `notYetStarted` state.
9
10At each state, each method has a specific effect, depending on a variety of
11details, and sometimes the behavior is consistent regardless of overall state.
12
13Opening the active image or hash always fails:
14
15*   `open(/flash/active/image)` returns false -- file cannot be opened.
16*   `open(/flash/active/hash)` returns false -- file cannot be opened.
17
18The two files are only present once their corresponding blob has been opened.
19
20# The state of fileOpen per state
21
22You can only open one file at a time, and some of the states exist only when a
23file is open.
24
25State                   | fileOpen
26:---------------------- | :-------
27`notYetStarted`         | `false`
28`uploadInProgress`      | `true`
29`verificationPending`   | `false`
30`verificationStarted`   | `true`
31`verificationCompleted` | `true`
32`updatePending`         | `false`
33`updateStarted`         | `true`
34`updatedCompleted`      | `true`
35
36# The states in the Firmware Handler State Machine
37
38## `notYetStarted`
39
40**The starting state.**
41
42*   `open(/flash/image)`
43*   `open(/flash/tarball)`
44*   `open(/flash/hash)`
45*   `open(/flash/verify)`
46*   `open(/flash/update)`
47
48## `uploadInProgress`
49
50**The BMC is expecting to receive bytes.**
51
52*   `open(/flash/*)` returns false because `fileOpen == true`
53
54*   `close(/flash/*)` triggers `state -> verificationPending`
55
56*   `commit(/flash/*)` returns false
57
58## `verificationPending`
59
60**The BMC is ready for verification or more bytes.**
61
62*   `open(/flash/image)` triggers `state -> uploadInProgress`
63*   `open(/flash/tarball)` triggers `state -> uploadInProgress`
64*   `open(/flash/hash)` triggers `state -> uploadInProgress`
65
66*   `open(/flash/verify)`
67
68*   `open(/flash/update)`
69
70*   `commit(/flash/verify)` `state -> verificationStarted`
71
72## `verificationStarted`
73
74**The verification process has started, no more writes allowed.**
75
76*   `open(/flash/*)` returns false because `state == verificationStarted`
77
78*   `close(/flash/verify)` `state -> verificationCompleted`
79
80## `verificationCompleted`
81
82**The verification process has completed.**
83
84*   `open(/flash/image)`
85*   `open(/flash/tarball)`
86*   `open(/flash/hash)`
87*   `open(/flash/verify)`
88*   `open(/flash/update)`
89
90## `updatePending`
91
92**The update process is pending.**
93
94## `updateStarted`
95
96**The update process has started.**
97
98*   `open(/flash/*)`r eturns false because `fileOpen == true`
99
100## `updatedCompleted`
101
102**The update has completed (optional state to reach)**
103
104# Expected State Transition Sequence
105
106If verification fails, the state still transitions to `verificationCompleted`
107and similarly, if the update fails the state still transitions to
108`updateCompleted`. It is up to the host-tool to check the result of the process
109by running the `stat()` command on their open session (either their session with
110the `verifyBlobId` or the `updateBlobId`.
111
112Action                     | Before | After
113:------------------------- | :----: | :----------------:
1141. `getBlobList()`         | NYS    | NYS
1152. `stat(/flash/image)`    | NYS    | NYS
1163. `open(/flash/image)`    | NYS    | UIP
1174. `write(...)`            | UIP    | UIP
1185. `close(/flash/image)`   | UIP    | VP
1196. `open(/flash/hash)`     | VP     | UIP
1207. `write(...)`            | UIP    | UIP
1218. `close(/flash/hash)`    | UIP    | VP
1229. `open(/flash/verify)`   | VP     | VP
12310. `commit(...)`          | VP     | VS
12411. `sessionStat(...)`     | VS     | VS (if !completed)
12511. `sessionStat(...)`     | VS     | VC (if completed)
12612. `close(/flash/verify)` | VC     | UP
12713. `open(/flash/update)`  | UP     | UP
12814. `commit(...)`          | UP     | US
12915. `sessionStat(...)`     | US     | US (if !completed)
13015. `sessionStat(...)`     | US     | UC (if completed)
13116. `close(/flash/update)` | UC     | NYS
132