From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42628) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZfUql-0006iL-UW for qemu-devel@nongnu.org; Fri, 25 Sep 2015 11:23:57 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZfUqi-00070X-RD for qemu-devel@nongnu.org; Fri, 25 Sep 2015 11:23:51 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46756) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZfUqi-0006zV-JN for qemu-devel@nongnu.org; Fri, 25 Sep 2015 11:23:48 -0400 References: <1443189844-20341-1-git-send-email-marcandre.lureau@redhat.com> <1443189844-20341-7-git-send-email-marcandre.lureau@redhat.com> From: Eric Blake Message-ID: <56056701.10306@redhat.com> Date: Fri, 25 Sep 2015 09:23:45 -0600 MIME-Version: 1.0 In-Reply-To: <1443189844-20341-7-git-send-email-marcandre.lureau@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="S5e30KhwGhHWG72vLTeVAh60e5HGD4g9H" Subject: Re: [Qemu-devel] [PATCH 06/36] qapi: move documentation bits in schema files List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: marcandre.lureau@redhat.com, qemu-devel@nongnu.org Cc: armbru@redhat.com, mdroth@linux.vnet.ibm.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --S5e30KhwGhHWG72vLTeVAh60e5HGD4g9H Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 09/25/2015 08:03 AM, marcandre.lureau@redhat.com wrote: > From: Marc-Andr=C3=A9 Lureau >=20 > Moving the remaining bits of documentation to the schema files. >=20 > Signed-off-by: Marc-Andr=C3=A9 Lureau > --- > qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++- > qmp-commands.hx | 62 ------------------------------------------------= -------- > 2 files changed, 47 insertions(+), 63 deletions(-) >=20 > 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 -*- > +## > +# =3D Introduction > +# > +# This document describes all commands currently supported by QMP. > +# > +# Most of the time their usage is exactly the same as in the user Moni= tor, this > +# means that any other document which also describe commands (the manp= age, > +# QEMU's manual, etc) can and should be consulted. > +# > +# QMP has two types of commands: regular and query commands. Regular c= ommands > +# usually change the Virtual Machine's state someway, while query comm= ands 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 format= ted 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 detail= ed > +# 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). > +# > +# =3D Stability Considerations > +# > +# The current QMP command set (described in this file) may be useful f= or 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 soo= n, 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 N= OT check > +# for specific errors classes or data (it's strongly recommende= d to only > +# check for the "error" key) > # > -# QAPI Schema > =20 > # QAPI common definitions > { 'include': 'qapi/common.json' } --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --S5e30KhwGhHWG72vLTeVAh60e5HGD4g9H Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJWBWcBAAoJEKeha0olJ0NqvZAH/ithMJTJC3n1rPrpoqctMqZL tAoVkRZb/ygOrGAWeqW0CtmDfiHGwbKlDcgrDwUmOn85YG0W5KkzHl9URO5bKQtz ZqHBRA0TgUiiYzt8suKx6T4JVMaZWpVwn4r9iQip1cYMhRENScKTrEJWMqI1YXEU +331v0UwxRK7FHHy72zIOZ+8QrNNV5b0VeeSW9RE72g5K/VfYd5kJAPQIDa5YSWm crOBA45UMP6PrRTWrzNCitdyZLNP8pXhPd/60CkgClxEEMTRVq3H3l98rNIPRef+ XxVEDNiNoHYZG1RMDhajqxpvYTO1JkE/AP1QBqE7DYMKC0rvwDoxpmHZyWwf9MU= =vX0h -----END PGP SIGNATURE----- --S5e30KhwGhHWG72vLTeVAh60e5HGD4g9H--