| description: > |
| Implement the Hoth command control interface. |
| |
| methods: |
| - name: SendHostCommand |
| description: > |
| Send a host command to Hoth and return the response. This will block |
| on Hoth completing its internal operations. Critical host commands |
| like LoadTokens are banned. This method should be called from the IPMI |
| HostCommand passthrough. |
| parameters: |
| - name: Command |
| type: array[byte] |
| description: > |
| Data to write to Hoth SPI host command offset. |
| returns: |
| - name: Response |
| type: array[byte] |
| description: > |
| Data read from Hoth SPI host command offset. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| - xyz.openbmc_project.Common.Error.Timeout |
| |
| - name: SendTrustedHostCommand |
| description: > |
| Send a host command to Hoth and return the response. This will block |
| on Hoth completing its internal operations. Critical host commands |
| like LoadTokens are allowed. This method should be called from the |
| BMC. |
| parameters: |
| - name: Command |
| type: array[byte] |
| description: > |
| Data to write to Hoth SPI host command offset. |
| returns: |
| - name: Response |
| type: array[byte] |
| description: > |
| Data read from Hoth SPI host command offset. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| - xyz.openbmc_project.Common.Error.Timeout |
| |
| - name: SendHostCommandAsync |
| description: > |
| Send a host command to Hoth and immediately return without waiting for |
| response. Caller can either poll with calls to GetHostCommandResponse |
| until retrieving the response, or wait for a ResponseReady signal. |
| parameters: |
| - name: Command |
| type: array[byte] |
| description: > |
| Data to write to Hoth SPI host command offset. |
| returns: |
| - name: CallToken |
| type: uint64 |
| description: > |
| The representation for the call made |
| errors: |
| - self.Error.CommandFailure |
| |
| - name: GetHostCommandResponse |
| description: > |
| Read the response from Hoth mailbox. |
| parameters: |
| - name: CallToken |
| type: uint64 |
| description: > |
| The token returned from SendHostCommandAsync() |
| returns: |
| - name: Response |
| type: array[byte] |
| description: > |
| Data read from Hoth SPI host command offset |
| errors: |
| - self.Error.ResponseFailure |
| - self.Error.ResponseNotFound |
| - self.Error.InterfaceError |
| |
| - name: UpdateFirmware |
| description: > |
| Write given firmware data to the Hoth firmware partition in EEPROM. |
| parameters: |
| - name: FirmwareData |
| type: array[byte] |
| description: > |
| Hoth firmware image |
| errors: |
| - self.Error.FirmwareFailure |
| |
| - name: GetFirmwareUpdateStatus |
| description: > |
| Get the status of the firmware update process. |
| returns: |
| - name: Status |
| type: enum[self.FirmwareUpdateStatus] |
| description: > |
| Status of the firmware update |
| |
| - name: InitiatePayload |
| description: > |
| Initiates erasure of the EEPROM staging area. Note that this will lock |
| up access to Hoth for an extended time and may go over the kernel's |
| SPI write timeout. Calling multiple small ErasePayload is recommended. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| |
| - name: GetInitiatePayloadStatus |
| description: > |
| Get the status of the payload initiation process. |
| returns: |
| - name: Status |
| type: enum[self.FirmwareUpdateStatus] |
| description: > |
| Status of the payload initiation |
| |
| - name: ErasePayload |
| description: > |
| Erases the given size starting at the specified offset of the staging |
| partition. |
| parameters: |
| - name: Offset |
| type: uint32 |
| description: > |
| Offset of the staging partition to start erasing from. |
| - name: Size |
| type: uint32 |
| description: > |
| Size of the staging partition to erase. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| |
| - name: SendPayload |
| description: > |
| Chunk and send the binary specified in the image path |
| parameters: |
| - name: ImagePath |
| type: string |
| description: > |
| Firmware image path |
| errors: |
| - self.Error.FirmwareFailure |
| - self.Error.InterfaceError |
| |
| - name: GetSendPayloadStatus |
| description: > |
| Get the status of the send payload process. |
| returns: |
| - name: Status |
| type: enum[self.FirmwareUpdateStatus] |
| description: > |
| Status of the send payload process. |
| |
| - name: VerifyPayload |
| description: > |
| Initiates the verification process without activating the staging area |
| errors: |
| - self.Error.InterfaceError |
| |
| - name: GetVerifyPayloadStatus |
| description: > |
| Get the status of the payload verification process. |
| returns: |
| - name: Status |
| type: enum[self.FirmwareUpdateStatus] |
| description: > |
| Status of the payload verification |
| |
| - name: ActivatePayload |
| description: > |
| Activates the staging area as persistent or non-persistent for next |
| boot if verification was successful. |
| parameters: |
| - name: MakePersistent |
| type: boolean |
| description: > |
| Flag to determine whether to activate the staged image as |
| persistent or non-persistent for next boot. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| |
| - name: GetPayloadSize |
| description: > |
| Determines the max size of the payload region. |
| returns: |
| - name: Size |
| type: uint32 |
| description: > |
| The size of the payload region |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| |
| - name: Confirm |
| description: > |
| Prevents hoth from rolling back and using the previous image. When an |
| image can be comfirmed to be working well, this command is given, |
| which disarms the hoth watchdog. |
| errors: |
| - self.Error.CommandFailure |
| - self.Error.ResponseFailure |
| - self.Error.InterfaceError |
| |
| - name: GetTotalBootTime |
| description: > |
| Get total time spending from reset to HVNGOOD. |
| returns: |
| - name: Time |
| type: uint32 |
| description: > |
| Time in microseconds. |
| errors: |
| - self.Error.ResponseFailure |
| - self.Error.ExpectedInfoNotFound |
| |
| - name: GetFirmwareUpdateTime |
| description: > |
| Get time spending in the self update routine. Since a proper self |
| update involves a reset, this time is always expected to be low. |
| returns: |
| - name: Time |
| type: uint32 |
| description: > |
| Time in microseconds. |
| errors: |
| - self.Error.ResponseFailure |
| - self.Error.ExpectedInfoNotFound |
| |
| - name: GetFirmwareMirroringTime |
| description: > |
| Get time spending in mirroing the self-update. This time is a |
| reasonable proxy for the total self update time. |
| returns: |
| - name: Time |
| type: uint32 |
| description: > |
| Time in microseconds. |
| errors: |
| - self.Error.ResponseFailure |
| - self.Error.ExpectedInfoNotFound |
| |
| - name: GetPayloadValidationTime |
| description: > |
| Get time spending in validating the payload, copying mutable regions |
| and/or dealing with failsafe fallback. |
| returns: |
| - name: Time |
| type: uint32 |
| description: > |
| Time in microseconds. |
| errors: |
| - self.Error.ResponseFailure |
| - self.Error.ExpectedInfoNotFound |
| |
| signals: |
| - name: HostCommandResponseReady |
| description: > |
| This signal is broadcast when a response is ready for the call that |
| returned CallToken. |
| properties: |
| - name: CallToken |
| type: uint64 |
| description: > |
| The token returned from SendHostCommandAsync() |
| |
| enumerations: |
| - name: FirmwareUpdateStatus |
| description: > |
| The status of a firmware update through hothd |
| values: |
| - name: "None" |
| description: > |
| No update initiated |
| - name: "InProgress" |
| description: > |
| Update still in progress |
| - name: "Error" |
| description: > |
| Update has failed |
| - name: "Done" |
| description: > |
| Update has completed successfully |