Re: [PATCH 2/4] qapi: Create module 'monitor'

[Markus Armbruster]

Kevin Wolf <address@hidden> writes:

> misc.json contains definitions that are related to the system emulator,
> so it can't be used for the storage daemon. This patch moves basic
> functionality that is related to the monitor itself into a new
> monitor.json, which could be used in tools as well.
>
> Signed-off-by: Kevin Wolf <address@hidden>
> ---
>  qapi/misc.json             | 212 ------------------------------------
>  qapi/monitor.json          | 218 +++++++++++++++++++++++++++++++++++++
>  qapi/qapi-schema.json      |   1 +
>  monitor/monitor-internal.h |   1 +
>  monitor/hmp-cmds.c         |   1 +
>  monitor/qmp-cmds.c         |   1 +
>  monitor/qmp.c              |   2 +-
>  tests/qmp-test.c           |   2 +-
>  ui/gtk.c                   |   1 +
>  qapi/Makefile.objs         |   4 +-
>  10 files changed, 227 insertions(+), 216 deletions(-)
>  create mode 100644 qapi/monitor.json
>
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 33b94e3589..cf656e9d4b 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -7,159 +7,6 @@
>  
>  { 'include': 'common.json' }
>  
> -##
> -# @qmp_capabilities:
> -#
> -# Enable QMP capabilities.
> -#
> -# Arguments:
> -#
> -# @enable:   An optional list of QMPCapability values to enable.  The
> -#            client must not enable any capability that is not
> -#            mentioned in the QMP greeting message.  If the field is not
> -#            provided, it means no QMP capabilities will be enabled.
> -#            (since 2.12)
> -#
> -# Example:
> -#
> -# -> { "execute": "qmp_capabilities",
> -#      "arguments": { "enable": [ "oob" ] } }
> -# <- { "return": {} }
> -#
> -# Notes: This command is valid exactly when first connecting: it must be
> -# issued before any other command will be accepted, and will fail once the
> -# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
> -#
> -# The QMP client needs to explicitly enable QMP capabilities, otherwise
> -# all the QMP capabilities will be turned off by default.
> -#
> -# Since: 0.13
> -#
> -##
> -{ 'command': 'qmp_capabilities',
> -  'data': { '*enable': [ 'QMPCapability' ] },
> -  'allow-preconfig': true }
> -
> -##
> -# @QMPCapability:
> -#
> -# Enumeration of capabilities to be advertised during initial client
> -# connection, used for agreeing on particular QMP extension behaviors.
> -#
> -# @oob:   QMP ability to support out-of-band requests.
> -#         (Please refer to qmp-spec.txt for more information on OOB)
> -#
> -# Since: 2.12
> -#
> -##
> -{ 'enum': 'QMPCapability',
> -  'data': [ 'oob' ] }
> -
> -##
> -# @VersionTriple:
> -#
> -# A three-part version number.
> -#
> -# @major:  The major version number.
> -#
> -# @minor:  The minor version number.
> -#
> -# @micro:  The micro version number.
> -#
> -# Since: 2.4
> -##
> -{ 'struct': 'VersionTriple',
> -  'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
> -
> -
> -##
> -# @VersionInfo:
> -#
> -# A description of QEMU's version.
> -#
> -# @qemu:        The version of QEMU.  By current convention, a micro
> -#               version of 50 signifies a development branch.  A micro 
> version
> -#               greater than or equal to 90 signifies a release candidate for
> -#               the next minor version.  A micro version of less than 50
> -#               signifies a stable release.
> -#
> -# @package:     QEMU will always set this field to an empty string.  
> Downstream
> -#               versions of QEMU should set this to a non-empty string.  The
> -#               exact format depends on the downstream however it highly
> -#               recommended that a unique name is used.
> -#
> -# Since: 0.14.0
> -##
> -{ 'struct': 'VersionInfo',
> -  'data': {'qemu': 'VersionTriple', 'package': 'str'} }
> -
> -##
> -# @query-version:
> -#
> -# Returns the current version of QEMU.
> -#
> -# Returns:  A @VersionInfo object describing the current version of QEMU.
> -#
> -# Since: 0.14.0
> -#
> -# Example:
> -#
> -# -> { "execute": "query-version" }
> -# <- {
> -#       "return":{
> -#          "qemu":{
> -#             "major":0,
> -#             "minor":11,
> -#             "micro":5
> -#          },
> -#          "package":""
> -#       }
> -#    }
> -#
> -##
> -{ 'command': 'query-version', 'returns': 'VersionInfo',
> -  'allow-preconfig': true }
> -
> -##
> -# @CommandInfo:
> -#
> -# Information about a QMP command
> -#
> -# @name: The command name
> -#
> -# Since: 0.14.0
> -##
> -{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }
> -
> -##
> -# @query-commands:
> -#
> -# Return a list of supported QMP commands by this server
> -#
> -# Returns: A list of @CommandInfo for all supported commands
> -#
> -# Since: 0.14.0
> -#
> -# Example:
> -#
> -# -> { "execute": "query-commands" }
> -# <- {
> -#      "return":[
> -#         {
> -#            "name":"query-balloon"
> -#         },
> -#         {
> -#            "name":"system_powerdown"
> -#         }
> -#      ]
> -#    }
> -#
> -# Note: This example has been shortened as the real response is too long.
> -#
> -##
> -{ 'command': 'query-commands', 'returns': ['CommandInfo'],
> -  'allow-preconfig': true }
> -
>  ##
>  # @LostTickPolicy:
>  #
> @@ -300,48 +147,6 @@
>  ##
>  { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
>  
> -##
> -# @EventInfo:
> -#
> -# Information about a QMP event
> -#
> -# @name: The event name
> -#
> -# Since: 1.2.0
> -##
> -{ 'struct': 'EventInfo', 'data': {'name': 'str'} }
> -
> -##
> -# @query-events:
> -#
> -# Return information on QMP events.
> -#
> -# Returns: A list of @EventInfo.
> -#
> -# Since: 1.2.0
> -#
> -# Note: This command is deprecated, because its output doesn't reflect
> -# compile-time configuration.  Use query-qmp-schema instead.
> -#
> -# Example:
> -#
> -# -> { "execute": "query-events" }
> -# <- {
> -#      "return": [
> -#          {
> -#             "name":"SHUTDOWN"
> -#          },
> -#          {
> -#             "name":"RESET"
> -#          }
> -#       ]
> -#    }
> -#
> -# Note: This example has been shortened as the real response is too long.
> -#
> -##
> -{ 'command': 'query-events', 'returns': ['EventInfo'] }
> -
>  ##
>  # @IOThreadInfo:
>  #
> @@ -764,23 +569,6 @@
>  ##
>  { 'command': 'query-pci', 'returns': ['PciInfo'] }
>  
> -##
> -# @quit:
> -#
> -# This command will cause the QEMU process to exit gracefully.  While every
> -# attempt is made to send the QMP response before terminating, this is not
> -# guaranteed.  When using this interface, a premature EOF would not be
> -# unexpected.
> -#
> -# Since: 0.14.0
> -#
> -# Example:
> -#
> -# -> { "execute": "quit" }
> -# <- { "return": {} }
> -##
> -{ 'command': 'quit' }
> -
>  ##
>  # @stop:
>  #
> diff --git a/qapi/monitor.json b/qapi/monitor.json
> new file mode 100644
> index 0000000000..a82a18da1a
> --- /dev/null
> +++ b/qapi/monitor.json
> @@ -0,0 +1,218 @@
> +# -*- Mode: Python -*-
> +#
> +
> +##
> +# = Monitor definitions (shared between system emulator and tools)
> +##
> +
> +##
> +# @qmp_capabilities:
> +#
> +# Enable QMP capabilities.
> +#
> +# Arguments:
> +#
> +# @enable:   An optional list of QMPCapability values to enable.  The
> +#            client must not enable any capability that is not
> +#            mentioned in the QMP greeting message.  If the field is not
> +#            provided, it means no QMP capabilities will be enabled.
> +#            (since 2.12)
> +#
> +# Example:
> +#
> +# -> { "execute": "qmp_capabilities",
> +#      "arguments": { "enable": [ "oob" ] } }
> +# <- { "return": {} }
> +#
> +# Notes: This command is valid exactly when first connecting: it must be
> +# issued before any other command will be accepted, and will fail once the
> +# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
> +#
> +# The QMP client needs to explicitly enable QMP capabilities, otherwise
> +# all the QMP capabilities will be turned off by default.
> +#
> +# Since: 0.13
> +#
> +##
> +{ 'command': 'qmp_capabilities',
> +  'data': { '*enable': [ 'QMPCapability' ] },
> +  'allow-preconfig': true }
> +
> +##
> +# @QMPCapability:
> +#
> +# Enumeration of capabilities to be advertised during initial client
> +# connection, used for agreeing on particular QMP extension behaviors.
> +#
> +# @oob:   QMP ability to support out-of-band requests.
> +#         (Please refer to qmp-spec.txt for more information on OOB)
> +#
> +# Since: 2.12
> +#
> +##
> +{ 'enum': 'QMPCapability',
> +  'data': [ 'oob' ] }
> +
> +##
> +# @VersionTriple:
> +#
> +# A three-part version number.
> +#
> +# @major:  The major version number.
> +#
> +# @minor:  The minor version number.
> +#
> +# @micro:  The micro version number.
> +#
> +# Since: 2.4
> +##
> +{ 'struct': 'VersionTriple',
> +  'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
> +
> +
> +##
> +# @VersionInfo:
> +#
> +# A description of QEMU's version.
> +#
> +# @qemu:        The version of QEMU.  By current convention, a micro
> +#               version of 50 signifies a development branch.  A micro 
> version
> +#               greater than or equal to 90 signifies a release candidate for
> +#               the next minor version.  A micro version of less than 50
> +#               signifies a stable release.
> +#
> +# @package:     QEMU will always set this field to an empty string.  
> Downstream
> +#               versions of QEMU should set this to a non-empty string.  The
> +#               exact format depends on the downstream however it highly
> +#               recommended that a unique name is used.
> +#
> +# Since: 0.14.0
> +##
> +{ 'struct': 'VersionInfo',
> +  'data': {'qemu': 'VersionTriple', 'package': 'str'} }
> +
> +##
> +# @query-version:
> +#
> +# Returns the current version of QEMU.
> +#
> +# Returns:  A @VersionInfo object describing the current version of QEMU.
> +#
> +# Since: 0.14.0
> +#
> +# Example:
> +#
> +# -> { "execute": "query-version" }
> +# <- {
> +#       "return":{
> +#          "qemu":{
> +#             "major":0,
> +#             "minor":11,
> +#             "micro":5
> +#          },
> +#          "package":""
> +#       }
> +#    }
> +#
> +##
> +{ 'command': 'query-version', 'returns': 'VersionInfo',
> +  'allow-preconfig': true }

Borderline.  I guess you move query-version (along with VersionInfo,
VersionTriple) because qmp_greeting() uses it.

> +
> +##
> +# @CommandInfo:
> +#
> +# Information about a QMP command
> +#
> +# @name: The command name
> +#
> +# Since: 0.14.0
> +##
> +{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }
> +
> +##
> +# @query-commands:
> +#
> +# Return a list of supported QMP commands by this server
> +#
> +# Returns: A list of @CommandInfo for all supported commands
> +#
> +# Since: 0.14.0
> +#
> +# Example:
> +#
> +# -> { "execute": "query-commands" }
> +# <- {
> +#      "return":[
> +#         {
> +#            "name":"query-balloon"
> +#         },
> +#         {
> +#            "name":"system_powerdown"
> +#         }
> +#      ]
> +#    }
> +#
> +# Note: This example has been shortened as the real response is too long.
> +#
> +##
> +{ 'command': 'query-commands', 'returns': ['CommandInfo'],
> +  'allow-preconfig': true }
> +
> +##
> +# @EventInfo:
> +#
> +# Information about a QMP event
> +#
> +# @name: The event name
> +#
> +# Since: 1.2.0
> +##
> +{ 'struct': 'EventInfo', 'data': {'name': 'str'} }
> +
> +##
> +# @query-events:
> +#
> +# Return information on QMP events.
> +#
> +# Returns: A list of @EventInfo.
> +#
> +# Since: 1.2.0
> +#
> +# Note: This command is deprecated, because its output doesn't reflect
> +# compile-time configuration.  Use query-qmp-schema instead.
> +#
> +# Example:
> +#
> +# -> { "execute": "query-events" }
> +# <- {
> +#      "return": [
> +#          {
> +#             "name":"SHUTDOWN"
> +#          },
> +#          {
> +#             "name":"RESET"
> +#          }
> +#       ]
> +#    }
> +#
> +# Note: This example has been shortened as the real response is too long.
> +#
> +##
> +{ 'command': 'query-events', 'returns': ['EventInfo'] }
> +
> +##
> +# @quit:
> +#
> +# This command will cause the QEMU process to exit gracefully.  While every
> +# attempt is made to send the QMP response before terminating, this is not
> +# guaranteed.  When using this interface, a premature EOF would not be
> +# unexpected.
> +#
> +# Since: 0.14.0
> +#
> +# Example:
> +#
> +# -> { "execute": "quit" }
> +# <- { "return": {} }
> +##
> +{ 'command': 'quit' }

Borderline.

Perhaps it's just a matter of naming.  monitor.json suggests it's about
the monitor.  It's in fact about QMP, plus whatever else any program
sporting a QMP monitor has.  Can we find a name for that?  Hmm...
control.json?

[...]
> diff --git a/qapi/Makefile.objs b/qapi/Makefile.objs
> index dd3f5e6f94..519b6f1a8e 100644
> --- a/qapi/Makefile.objs
> +++ b/qapi/Makefile.objs
> @@ -6,8 +6,8 @@ util-obj-y += qmp-event.o
>  util-obj-y += qapi-util.o
>  
>  QAPI_COMMON_MODULES = audio authz block-core block char common crypto
> -QAPI_COMMON_MODULES += dump error introspect job machine migration misc net
> -QAPI_COMMON_MODULES += qdev qom rdma rocker run-state sockets tpm
> +QAPI_COMMON_MODULES += dump error introspect job machine migration misc 
> monitor

Long line.

> +QAPI_COMMON_MODULES += net qdev qom rdma rocker run-state sockets tpm
>  QAPI_COMMON_MODULES += trace transaction ui
>  QAPI_TARGET_MODULES = machine-target misc-target
>  QAPI_MODULES = $(QAPI_COMMON_MODULES) $(QAPI_TARGET_MODULES)