# -*- Mode: Python -*-
# vim: filetype=python
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.
# SPDX-License-Identifier: GPL-2.0-or-later

##
# = ACPI
##

##
# @AcpiTableOptions:
#
# Specify an ACPI table on the command line to load.
#
# At most one of @file and @data can be specified.  The list of files
# specified by any one of them is loaded and concatenated in order.
# If both are omitted, @data is implied.
#
# Other fields / optargs can be used to override fields of the generic
# ACPI table header; refer to the ACPI specification 5.0, section
# 5.2.6 System Description Table Header.  If a header field is not
# overridden, then the corresponding value from the concatenated blob
# is used (in case of @file), or it is filled in with a hard-coded
# value (in case of @data).
#
# String fields are copied into the matching ACPI member from lowest
# address upwards, and silently truncated / NUL-padded to length.
#
# @sig: table signature / identifier (4 bytes)
#
# @rev: table revision number (dependent on signature, 1 byte)
#
# @oem_id: OEM identifier (6 bytes)
#
# @oem_table_id: OEM table identifier (8 bytes)
#
# @oem_rev: OEM-supplied revision number (4 bytes)
#
# @asl_compiler_id: identifier of the utility that created the table
#     (4 bytes)
#
# @asl_compiler_rev: revision number of the utility that created the
#     table (4 bytes)
#
# @file: colon (:) separated list of pathnames to load and concatenate
#     as table data.  The resultant binary blob is expected to have an
#     ACPI table header.  At least one file is required.  This field
#     excludes @data.
#
# @data: colon (:) separated list of pathnames to load and concatenate
#     as table data.  The resultant binary blob must not have an ACPI
#     table header.  At least one file is required.  This field
#     excludes @file.
#
# Since: 1.5
##
{ 'struct': 'AcpiTableOptions',
  'data': {
    '*sig':               'str',
    '*rev':               'uint8',
    '*oem_id':            'str',
    '*oem_table_id':      'str',
    '*oem_rev':           'uint32',
    '*asl_compiler_id':   'str',
    '*asl_compiler_rev':  'uint32',
    '*file':              'str',
    '*data':              'str' }}

##
# @ACPISlotType:
#
# @DIMM: memory slot
#
# @CPU: logical CPU slot (since 2.7)
##
{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }

##
# @ACPIOSTInfo:
#
# OSPM Status Indication for a device For description of possible
# values of @source and @status fields see "_OST (OSPM Status
# Indication)" chapter of ACPI5.0 spec.
#
# @device: device ID associated with slot
#
# @slot: slot ID, unique per slot of a given @slot-type
#
# @slot-type: type of the slot
#
# @source: an integer containing the source event
#
# @status: an integer containing the status code
#
# Since: 2.1
##
{ 'struct': 'ACPIOSTInfo',
  'data'  : { '*device': 'str',
              'slot': 'str',
              'slot-type': 'ACPISlotType',
              'source': 'int',
              'status': 'int' } }

##
# @query-acpi-ospm-status:
#
# Return a list of ACPIOSTInfo for devices that support status
# reporting via ACPI _OST method.
#
# Since: 2.1
#
# Example:
#
#     -> { "execute": "query-acpi-ospm-status" }
#     <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
#                      { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
#                      { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
#                      { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
#        ]}
##
{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }

##
# @ACPI_DEVICE_OST:
#
# Emitted when guest executes ACPI _OST method.
#
# @info: OSPM Status Indication
#
# Since: 2.1
#
# Example:
#
#     <- { "event": "ACPI_DEVICE_OST",
#          "data": { "info": { "device": "d1", "slot": "0",
#                              "slot-type": "DIMM", "source": 1, "status": 0 } },
#          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
##
{ 'event': 'ACPI_DEVICE_OST',
     'data': { 'info': 'ACPIOSTInfo' } }