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
25| State                   | 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
112| Action                     | Before |       After        |
113| :------------------------- | :----: | :----------------: |
114| 1. `getBlobList()`         |  NYS   |        NYS         |
115| 2. `stat(/flash/image)`    |  NYS   |        NYS         |
116| 3. `open(/flash/image)`    |  NYS   |        UIP         |
117| 4. `write(...)`            |  UIP   |        UIP         |
118| 5. `close(/flash/image)`   |  UIP   |         VP         |
119| 6. `open(/flash/hash)`     |   VP   |        UIP         |
120| 7. `write(...)`            |  UIP   |        UIP         |
121| 8. `close(/flash/hash)`    |  UIP   |         VP         |
122| 9. `open(/flash/verify)`   |   VP   |         VP         |
123| 10. `commit(...)`          |   VP   |         VS         |
124| 11. `sessionStat(...)`     |   VS   | VS (if !completed) |
125| 11. `sessionStat(...)`     |   VS   | VC (if completed)  |
126| 12. `close(/flash/verify)` |   VC   |         UP         |
127| 13. `open(/flash/update)`  |   UP   |         UP         |
128| 14. `commit(...)`          |   UP   |         US         |
129| 15. `sessionStat(...)`     |   US   | US (if !completed) |
130| 15. `sessionStat(...)`     |   US   | UC (if completed)  |
131| 16. `close(/flash/update)` |   UC   |        NYS         |
132