From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39131) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YftBn-0000Rg-6M for qemu-devel@nongnu.org; Wed, 08 Apr 2015 12:50:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YftBi-0001lf-SF for qemu-devel@nongnu.org; Wed, 08 Apr 2015 12:50:55 -0400 Received: from mx1.redhat.com ([209.132.183.28]:58097) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YftBi-0001lQ-KN for qemu-devel@nongnu.org; Wed, 08 Apr 2015 12:50:50 -0400 Message-ID: <55255C68.3060407@redhat.com> Date: Wed, 08 Apr 2015 10:50:48 -0600 From: Eric Blake MIME-Version: 1.0 References: <1428206887-7921-1-git-send-email-eblake@redhat.com> <1428206887-7921-3-git-send-email-eblake@redhat.com> In-Reply-To: <1428206887-7921-3-git-send-email-eblake@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="nHC8VgqSNJXwsxbOt2p8lhEXldhFlivBJ" Subject: Re: [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerations List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: kwolf@redhat.com, Alberto Garcia , armbru@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --nHC8VgqSNJXwsxbOt2p8lhEXldhFlivBJ Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 04/04/2015 10:07 PM, Eric Blake wrote: > Go into more details about the various types of valid expressions > in a qapi schema, including tweaks to document fixes being done > later in the current patch series. Also fix some stale and missing > documentation in the QMP specification. >=20 > Signed-off-by: Eric Blake >=20 > --- >=20 > v6: split copyright change into another patch; merge in 1/5, 3/5, > and 5/5 of doc cleanup series; drop simple union with base docs, > and mention relation between simple and flat unions; mention QMP > is encoded as UTF-8; mention extensions of 'single \' quote' and > "\'"; mention that repeating json-object (dict) keys is unspecified. A bit of self-review: > +++ b/docs/qmp/qmp-spec.txt > @@ -13,8 +13,11 @@ Last revised in March 2015. > @@ -62,7 +78,19 @@ The greeting message format is: > - The "version" member contains the Server's version information (the = format > is the same of the query-version command) > - The "capabilities" member specify the availability of features beyon= d the > - baseline specification > + baseline specification; the order of elements in this array has no > + particular significance, so a client must search the entire array > + when looking for a particular capability > + > +When first connecting to the server, the connection is in a capability= > +exchange mode, further documented below. This sentence is redundant with the earlier sentence in the same section:= >> Right when connected the Server will issue a greeting message, which s= ignals >> that the connection has been successfully established and that the Ser= ver is >> ready for capabilities negotiation (for more information refer to sect= ion >> '4. Capabilities Negotiation'). I'll wait for other reviews before deciding whether it is easier to do as a patch that a maintainer squashes in on commit of v6, as a v7 respin, or as an independent followup patch. > 4. Capabilities Negotiation > ----------------------------- > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D >=20 > When a Client successfully establishes a connection, the Server is in > Capabilities Negotiation mode. Meanwhile, as this has just come up on the list, I'm now looking at how easy it would be to make capability negotiation give saner error messages= :) https://lists.gnu.org/archive/html/qemu-devel/2015-04/msg00833.html Which of course may mean further touching of this file, and therefore justifying a separate cleanup patch anyways. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --nHC8VgqSNJXwsxbOt2p8lhEXldhFlivBJ 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/ iQEcBAEBCAAGBQJVJVxoAAoJEKeha0olJ0NqWvwH/iIwc1snZygThQGGP/RO4K8e SvLHC9OEvSOHa7DZr+YwHmtQzaciFuUJUB9Q5CYgEgXpkv4JmqTICINEFS0NetVs VUdNidA6kC9f+5Ck2IhjyMOKPUV6oM/GdR5HDTg+kEjM8nnR+40kN8QZYc7DvQXM 9IjeiSLBEgMXkbwrQQXCaxxe5NGCr9Kzvn01LiY0Cd3vn+/FwAuHCOYIxJzvE0GZ CPQ7bsKucnuSNXujz0dapavUbIxp5vjHWEAeV0sFd97ojHudLnKsLZTtVGXEx7p7 uMYBD7SNy0s+DiSTX5Nv3YccRDSMjnIt9AmtkpDLo7N7gU4Bg4ObTvPKk0JL+wk= =3hOc -----END PGP SIGNATURE----- --nHC8VgqSNJXwsxbOt2p8lhEXldhFlivBJ--