# -*- Mode: Python -*-
##
# = Introduction
#
# This document describes all commands currently supported by QMP.
#
# Most of the time their usage is exactly the same as in the user Monitor, this
# means that any other document which also describe commands (the manpage,
# QEMU's manual, etc) can and should be consulted.
#
# QMP has two types of commands: regular and query commands. Regular commands
# usually change the Virtual Machine's state someway, while query commands just
# return information. The sections below are divided accordingly.
#
# It's important to observe that all communication examples are formatted in
# a reader-friendly way, so that they're easier to understand. However, in real
# protocol usage, they're emitted as a single line.
#
# Also, the following notation is used to denote data flow:
#
# Example:
#
# | -> data issued by the Client
# | <- Server data response
#
# Please, refer to the QMP specification (docs/qmp-spec.txt) for
# detailed information on the Server command and response formats.
#
# = Stability Considerations
#
# The current QMP command set (described in this file) may be useful for a
# number of use cases, however it's limited and several commands have bad
# defined semantics, specially with regard to command completion.
#
# These problems are going to be solved incrementally in the next QEMU releases
# and we're going to establish a deprecation policy for badly defined commands.
#
# If you're planning to adopt QMP, please observe the following:
#
#     1. The deprecation policy will take effect and be documented soon, please
#        check the documentation of each used command as soon as a new release of
#        QEMU is available
#
#     2. DO NOT rely on anything which is not explicit documented
#
#     3. Errors, in special, are not documented. Applications should NOT check
#        for specific errors classes or data (it's strongly recommended to only
#        check for the "error" key)
#
##

{ 'pragma': { 'doc-required': true } }

# Whitelists to permit QAPI rule violations; think twice before you
# add to them!
{ 'pragma': {
    # Commands allowed to return a non-dictionary:
    'returns-whitelist': [
        'human-monitor-command',
        'qom-get',
        'query-migrate-cache-size',
        'query-tpm-models',
        'query-tpm-types',
        'ringbuf-read' ],
    'name-case-whitelist': [
        'ACPISlotType',         # DIMM, visible through query-acpi-ospm-status
        'CpuInfoMIPS',          # PC, visible through query-cpu
        'CpuInfoTricore',       # PC, visible through query-cpu
        'QapiErrorClass',       # all members, visible through errors
        'UuidInfo',             # UUID, visible through query-uuid
        'X86CPURegister32',     # all members, visible indirectly through qom-get
        'q_obj_CpuInfo-base'    # CPU, visible through query-cpu
    ] } }

# QAPI common definitions
{ 'include': 'qapi/common.json' }

##
# @X86CPURegister32:
#
# A X86 32-bit register
#
# Since: 1.5
##
{ 'enum': 'X86CPURegister32',
  'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }

##
# @X86CPUFeatureWordInfo:
#
# Information about a X86 CPU feature word
#
# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
#
# @cpuid-input-ecx: Input ECX value for CPUID instruction for that
#                   feature word
#
# @cpuid-register: Output register containing the feature bits
#
# @features: value of output register, containing the feature bits
#
# Since: 1.5
##
{ 'struct': 'X86CPUFeatureWordInfo',
  'data': { 'cpuid-input-eax': 'int',
            '*cpuid-input-ecx': 'int',
            'cpuid-register': 'X86CPURegister32',
            'features': 'int' } }

##
# @DummyForceArrays:
#
# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
#
# Since: 2.5
##
{ 'struct': 'DummyForceArrays',
  'data': { 'unused': ['X86CPUFeatureWordInfo'] } }