# -*- Mode: Python -*-
# vim: filetype=python
#

##
# = TPM (trusted platform module) devices
##

##
# @TpmModel:
#
# An enumeration of TPM models
#
# @tpm-tis: TPM TIS model
#
# @tpm-crb: TPM CRB model (since 2.12)
#
# @tpm-spapr: TPM SPAPR model (since 5.0)
#
# Since: 1.5
##
{ 'enum': 'TpmModel', 'data': [ 'tpm-tis', 'tpm-crb', 'tpm-spapr' ],
  'if': 'CONFIG_TPM' }

##
# @query-tpm-models:
#
# Return a list of supported TPM models
#
# Returns: a list of TpmModel
#
# Since: 1.5
#
# Example:
#
# -> { "execute": "query-tpm-models" }
# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
##
{ 'command': 'query-tpm-models', 'returns': ['TpmModel'],
  'if': 'CONFIG_TPM' }

##
# @TpmType:
#
# An enumeration of TPM types
#
# @passthrough: TPM passthrough type
#
# @emulator: Software Emulator TPM type (since 2.11)
#
# Since: 1.5
##
{ 'enum': 'TpmType', 'data': [ 'passthrough', 'emulator' ],
  'if': 'CONFIG_TPM' }

##
# @query-tpm-types:
#
# Return a list of supported TPM types
#
# Returns: a list of TpmType
#
# Since: 1.5
#
# Example:
#
# -> { "execute": "query-tpm-types" }
# <- { "return": [ "passthrough", "emulator" ] }
##
{ 'command': 'query-tpm-types', 'returns': ['TpmType'],
  'if': 'CONFIG_TPM' }

##
# @TPMPassthroughOptions:
#
# Information about the TPM passthrough type
#
# @path: string describing the path used for accessing the TPM device
#
# @cancel-path: string showing the TPM's sysfs cancel file for
#     cancellation of TPM commands while they are executing
#
# Since: 1.5
##
{ 'struct': 'TPMPassthroughOptions',
  'data': { '*path': 'str',
            '*cancel-path': 'str' },
  'if': 'CONFIG_TPM' }

##
# @TPMEmulatorOptions:
#
# Information about the TPM emulator type
#
# @chardev: Name of a unix socket chardev
#
# Since: 2.11
##
{ 'struct': 'TPMEmulatorOptions', 'data': { 'chardev' : 'str' },
  'if': 'CONFIG_TPM' }

##
# @TPMPassthroughOptionsWrapper:
#
# @data: Information about the TPM passthrough type
#
# Since: 1.5
##
{ 'struct': 'TPMPassthroughOptionsWrapper',
  'data': { 'data': 'TPMPassthroughOptions' },
  'if': 'CONFIG_TPM' }

##
# @TPMEmulatorOptionsWrapper:
#
# @data: Information about the TPM emulator type
#
# Since: 2.11
##
{ 'struct': 'TPMEmulatorOptionsWrapper',
  'data': { 'data': 'TPMEmulatorOptions' },
  'if': 'CONFIG_TPM' }

##
# @TpmTypeOptions:
#
# A union referencing different TPM backend types' configuration
# options
#
# @type:
#     - 'passthrough' The configuration options for the TPM
#       passthrough type
#     - 'emulator' The configuration options for TPM emulator backend
#       type
#
# Since: 1.5
##
{ 'union': 'TpmTypeOptions',
  'base': { 'type': 'TpmType' },
  'discriminator': 'type',
  'data': { 'passthrough' : 'TPMPassthroughOptionsWrapper',
            'emulator': 'TPMEmulatorOptionsWrapper' },
  'if': 'CONFIG_TPM' }

##
# @TPMInfo:
#
# Information about the TPM
#
# @id: The Id of the TPM
#
# @model: The TPM frontend model
#
# @options: The TPM (backend) type configuration options
#
# Since: 1.5
##
{ 'struct': 'TPMInfo',
  'data': {'id': 'str',
           'model': 'TpmModel',
           'options': 'TpmTypeOptions' },
  'if': 'CONFIG_TPM' }

##
# @query-tpm:
#
# Return information about the TPM device
#
# Returns: @TPMInfo on success
#
# Since: 1.5
#
# Example:
#
# -> { "execute": "query-tpm" }
# <- { "return":
#      [
#        { "model": "tpm-tis",
#          "options":
#            { "type": "passthrough",
#              "data":
#                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
#                  "path": "/dev/tpm0"
#                }
#            },
#          "id": "tpm0"
#        }
#      ]
#    }
##
{ 'command': 'query-tpm', 'returns': ['TPMInfo'],
  'if': 'CONFIG_TPM' }