yaml/com/google/gbmc/Hoth.interface.yaml

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