blob: 429f01dcea0a09b84280c74079f52c273cd75bc3 [file] [log] [blame]
John Edward Broadbent2b2784a2022-02-03 19:54:34 -08001description: >
Patrick Williams8da396c2022-03-14 14:21:02 -05002 Implement the Hoth command control interface.
John Edward Broadbent2b2784a2022-02-03 19:54:34 -08003
4methods:
Patrick Williams8da396c2022-03-14 14:21:02 -05005 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -080026
Patrick Williams8da396c2022-03-14 14:21:02 -050027 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -080048
Patrick Williams8da396c2022-03-14 14:21:02 -050049 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -080066
Patrick Williams8da396c2022-03-14 14:21:02 -050067 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -080084
Patrick Williams8da396c2022-03-14 14:21:02 -050085 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -080095
Patrick Williams8da396c2022-03-14 14:21:02 -050096 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800104
Patrick Williams8da396c2022-03-14 14:21:02 -0500105 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800114
Patrick Williams8da396c2022-03-14 14:21:02 -0500115 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800123
Patrick Williams8da396c2022-03-14 14:21:02 -0500124 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800141
Patrick Williams8da396c2022-03-14 14:21:02 -0500142 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800153
Patrick Williams8da396c2022-03-14 14:21:02 -0500154 - 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.
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800162
Patrick Williams8da396c2022-03-14 14:21:02 -0500163 - name: VerifyPayload
164 description: >
165 Initiates the verification process without activating the staging area
166 errors:
167 - self.Error.InterfaceError
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800168
Patrick Williams8da396c2022-03-14 14:21:02 -0500169 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800177
Patrick Williams8da396c2022-03-14 14:21:02 -0500178 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800192
Patrick Williams8da396c2022-03-14 14:21:02 -0500193 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800205
Patrick Williams8da396c2022-03-14 14:21:02 -0500206 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800215
Patrick Williams8da396c2022-03-14 14:21:02 -0500216 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800227
Patrick Williams8da396c2022-03-14 14:21:02 -0500228 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800240
Patrick Williams8da396c2022-03-14 14:21:02 -0500241 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800253
Patrick Williams8da396c2022-03-14 14:21:02 -0500254 - 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
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800266
267signals:
Patrick Williams8da396c2022-03-14 14:21:02 -0500268 - 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()
John Edward Broadbent2b2784a2022-02-03 19:54:34 -0800277
278enumerations:
Patrick Williams8da396c2022-03-14 14:21:02 -0500279 - 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