On 09/25/2015 08:03 AM, [email protected] wrote: > From: Marc-André Lureau <[email protected]> > > Moving the remaining bits of documentation to the schema files. > > Signed-off-by: Marc-André Lureau <[email protected]> > --- > qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++- > qmp-commands.hx | 62 > -------------------------------------------------------- > 2 files changed, 47 insertions(+), 63 deletions(-) > > diff --git a/qapi-schema.json b/qapi-schema.json > index 1383011..c8ee75d 100644 > --- a/qapi-schema.json > +++ b/qapi-schema.json > @@ -1,6 +1,52 @@ > # -*- 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.
Do we really still have that clean division?
> +#
> +# 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.
The server replies in a single line, but the client is free to send in
multiple lines.
> +#
> +# 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 (QMP/qmp-spec.txt) for detailed
> +# information on the Server command and response formats.
Stale comment, pointing to the wrong file name (commit 7537fe04 moved it
from QMP/ to docs/qmp/) (and Markus has a patch pending that moves it
from docs/qmp/qmp-spec.txt to docs/qmp-spec.txt).
> +#
> +# = 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.
Wow - some of this stuff has bit-rotted over time. I don't know how much
command completion we support for QMP (I guess it depends whether you
are using qmp-shell or a straight monitor connection), and while we do
still have badly defined commands, they are now the exception and we
have made a lot of progress in fixing things.
> +#
> +# 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
Umm, we still don't have a documented deprecation policy.
> +#
> +# 2. DO NOT rely on anything which is not explicit documented
s/explicit/explicitly/
> +#
> +# 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)
> #
> -# QAPI Schema
>
> # QAPI common definitions
> { 'include': 'qapi/common.json' }
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
