Add Hoth interface
Create a new google namespace and add the Hoth interface to this
namespace.
Signed-off-by: John Edward Broadbent <jebr@google.com>
Change-Id: I001dc34ef081885b6094d3d1aab578b0d882b53a
diff --git a/yaml/com/google/gbmc/Hoth.interface.yaml b/yaml/com/google/gbmc/Hoth.interface.yaml
new file mode 100644
index 0000000..c15daf5
--- /dev/null
+++ b/yaml/com/google/gbmc/Hoth.interface.yaml
@@ -0,0 +1,294 @@
+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