blob: 429f01dcea0a09b84280c74079f52c273cd75bc3 [file] [log] [blame]
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