1description: >
2    Implement the Hoth command control interface.
3
4methods:
5    - name: SendHostCommand
6      description: >
7          Send a host command to Hoth and return the response.
8          This will block on Hoth completing its internal operations.
9          Critical host commands like LoadTokens are banned.
10          This method should be called from the IPMI HostCommand passthrough.
11      parameters:
12          - name: Command
13            type: array[byte]
14            description: >
15                Data to write to Hoth SPI host command offset.
16      returns:
17          - name: Response
18            type: array[byte]
19            description: >
20                Data read from Hoth SPI host command offset.
21      errors:
22          - self.Error.CommandFailure
23          - self.Error.ResponseFailure
24          - self.Error.InterfaceError
25          - xyz.openbmc_project.Common.Error.Timeout
26
27    - name: SendTrustedHostCommand
28      description: >
29          Send a host command to Hoth and return the response.
30          This will block on Hoth completing its internal operations.
31          Critical host commands like LoadTokens are allowed.
32          This method should be called from the BMC.
33      parameters:
34          - name: Command
35            type: array[byte]
36            description: >
37                Data to write to Hoth SPI host command offset.
38      returns:
39          - name: Response
40            type: array[byte]
41            description: >
42                Data read from Hoth SPI host command offset.
43      errors:
44          - self.Error.CommandFailure
45          - self.Error.ResponseFailure
46          - self.Error.InterfaceError
47          - xyz.openbmc_project.Common.Error.Timeout
48
49    - name: SendHostCommandAsync
50      description: >
51          Send a host command to Hoth and immediately return without waiting for
52          response. Caller can either poll with calls to GetHostCommandResponse
53          until retrieving the response, or wait for a ResponseReady signal.
54      parameters:
55          - name: Command
56            type: array[byte]
57            description: >
58                Data to write to Hoth SPI host command offset.
59      returns:
60          - name: CallToken
61            type: uint64
62            description: >
63                The representation for the call made
64      errors:
65          - self.Error.CommandFailure
66
67    - name: GetHostCommandResponse
68      description: >
69          Read the response from Hoth mailbox.
70      parameters:
71          - name: CallToken
72            type: uint64
73            description: >
74                The token returned from SendHostCommandAsync()
75      returns:
76          - name: Response
77            type: array[byte]
78            description: >
79                Data read from Hoth SPI host command offset
80      errors:
81          - self.Error.ResponseFailure
82          - self.Error.ResponseNotFound
83          - self.Error.InterfaceError
84
85    - name: UpdateFirmware
86      description: >
87          Write given firmware data to the Hoth firmware partition in EEPROM.
88      parameters:
89          - name: FirmwareData
90            type: array[byte]
91            description: >
92                Hoth firmware image
93      errors:
94          - self.Error.FirmwareFailure
95
96    - name: GetFirmwareUpdateStatus
97      description: >
98          Get the status of the firmware update process.
99      returns:
100          - name: Status
101            type: enum[self.FirmwareUpdateStatus]
102            description: >
103                Status of the firmware update
104
105    - name: InitiatePayload
106      description: >
107          Initiates erasure of the EEPROM staging area. Note that this will lock up
108          access to Hoth for an extended time and may go over the kernel's SPI
109          write timeout. Calling multiple small ErasePayload is recommended.
110      errors:
111          - self.Error.CommandFailure
112          - self.Error.ResponseFailure
113          - self.Error.InterfaceError
114
115    - name: GetInitiatePayloadStatus
116      description: >
117          Get the status of the payload initiation process.
118      returns:
119          - name: Status
120            type: enum[self.FirmwareUpdateStatus]
121            description: >
122                Status of the payload initiation
123
124    - name: ErasePayload
125      description: >
126          Erases the given size starting at the specified offset of the staging
127          partition.
128      parameters:
129          - name: Offset
130            type: uint32
131            description: >
132                Offset of the staging partition to start erasing from.
133          - name: Size
134            type: uint32
135            description: >
136                Size of the staging partition to erase.
137      errors:
138          - self.Error.CommandFailure
139          - self.Error.ResponseFailure
140          - self.Error.InterfaceError
141
142    - name: SendPayload
143      description: >
144          Chunk and send the binary specified in the image path
145      parameters:
146          - name: ImagePath
147            type: string
148            description: >
149                Firmware image path
150      errors:
151          - self.Error.FirmwareFailure
152          - self.Error.InterfaceError
153
154    - name: GetSendPayloadStatus
155      description: >
156          Get the status of the send payload process.
157      returns:
158          - name: Status
159            type: enum[self.FirmwareUpdateStatus]
160            description: >
161                Status of the send payload process.
162
163    - name: VerifyPayload
164      description: >
165          Initiates the verification process without activating the staging area
166      errors:
167          - self.Error.InterfaceError
168
169    - name: GetVerifyPayloadStatus
170      description: >
171          Get the status of the payload verification process.
172      returns:
173          - name: Status
174            type: enum[self.FirmwareUpdateStatus]
175            description: >
176                Status of the payload verification
177
178    - name: ActivatePayload
179      description: >
180          Activates the staging area as persistent or non-persistent for next boot
181          if verification was successful.
182      parameters:
183          - name: MakePersistent
184            type: boolean
185            description: >
186                Flag to determine whether to activate the staged image as persistent
187                or non-persistent for next boot.
188      errors:
189          - self.Error.CommandFailure
190          - self.Error.ResponseFailure
191          - self.Error.InterfaceError
192
193    - name: GetPayloadSize
194      description: >
195          Determines the max size of the payload region.
196      returns:
197          - name: Size
198            type: uint32
199            description: >
200                The size of the payload region
201      errors:
202          - self.Error.CommandFailure
203          - self.Error.ResponseFailure
204          - self.Error.InterfaceError
205
206    - name: Confirm
207      description: >
208          Prevents hoth from rolling back and using the previous image.
209          When an image can be comfirmed to be working well, this command is given,
210          which disarms the hoth watchdog.
211      errors:
212          - self.Error.CommandFailure
213          - self.Error.ResponseFailure
214          - self.Error.InterfaceError
215
216    - name: GetTotalBootTime
217      description: >
218          Get total time spending from reset to HVNGOOD.
219      returns:
220          - name: Time
221            type: uint32
222            description: >
223                Time in microseconds.
224      errors:
225          - self.Error.ResponseFailure
226          - self.Error.ExpectedInfoNotFound
227
228    - name: GetFirmwareUpdateTime
229      description: >
230          Get time spending in the self update routine. Since a proper self update
231          involves a reset, this time is always expected to be low.
232      returns:
233          - name: Time
234            type: uint32
235            description: >
236                Time in microseconds.
237      errors:
238          - self.Error.ResponseFailure
239          - self.Error.ExpectedInfoNotFound
240
241    - name: GetFirmwareMirroringTime
242      description: >
243          Get time spending in mirroing the self-update. This time is a reasonable
244          proxy for the total self update time.
245      returns:
246          - name: Time
247            type: uint32
248            description: >
249                Time in microseconds.
250      errors:
251          - self.Error.ResponseFailure
252          - self.Error.ExpectedInfoNotFound
253
254    - name: GetPayloadValidationTime
255      description: >
256          Get time spending in validating the payload, copying mutable regions and/or
257          dealing with failsafe fallback.
258      returns:
259          - name: Time
260            type: uint32
261            description: >
262                Time in microseconds.
263      errors:
264          - self.Error.ResponseFailure
265          - self.Error.ExpectedInfoNotFound
266
267signals:
268    - name: HostCommandResponseReady
269      description: >
270          This signal is broadcast when a response is ready for the call that
271          returned CallToken.
272      properties:
273          - name: CallToken
274            type: uint64
275            description: >
276                The token returned from SendHostCommandAsync()
277
278enumerations:
279    - name: FirmwareUpdateStatus
280      description: >
281          The status of a firmware update through hothd
282      values:
283          - name: "None"
284            description: >
285                No update initiated
286          - name: "InProgress"
287            description: >
288                Update still in progress
289          - name: "Error"
290            description: >
291                Update has failed
292          - name: "Done"
293            description: >
294                Update has completed successfully
295