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