On 09/25/2015 08:03 AM, marcandre.lur...@redhat.com wrote: > From: Marc-André Lureau <marcandre.lur...@redhat.com> > > Moving the remaining bits of documentation to the schema files. > > Signed-off-by: Marc-André Lureau <marcandre.lur...@redhat.com> > --- > 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