[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection |
Date: |
Fri, 04 Sep 2015 08:39:53 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Michael Roth <address@hidden> writes:
> Quoting Markus Armbruster (2015-09-03 12:01:20)
>> Michael Roth <address@hidden> writes:
>>
>> > Quoting Eric Blake (2015-09-03 09:31:01)
>> >> On 09/03/2015 03:26 AM, Markus Armbruster wrote:
>> >> >>
>> >> >> I think we need to be careful that these descriptions are not
>> >> >> interpreted by clients as an alternative to the more-specific
>> >> >> constraints in the QAPI schema though. 'query-schema' seems
>> >> >> a bit misleading in that regard, it appears to be more like
>> >> >> 'query-schema-encoding' in function. But not sure it's worth
>> >> >> renaming or anything so long as the documentation is clear.
>> >> >
>> >> > You have a point: "schema" can mean two related, yet different things.
>> >> > There's the QAPI schema, and there's the QMP (the wire protocol) schema.
>> >> > QMP introspection is about the latter, not the former.
>> >> >
>> >> > If we want to avoid the ambiguity, we could call the command
>> >> > query-qmp-schema or something.
>> >> >
>> >> > Renaming query-schema now might confuse people coming from my KVM Forum
>> >> > talk slightly, but if we can agree on a better name, let's do it.
>> >>
>> >> I'm okay if you want to use 'query-qmp-schema'; it's a bit longer, but
>> >> more precise, and doesn't cause too much grief to change the name at
>> >> this point in the game.
>> >
>> > I'm also okay with this. It avoids confusion down that road if we
>> > ever introduced, say, a query-ber-schema or something.
>> >
>> > I have some minor reservations: I think query-qmp-schema-mapping or
>> > query-qmp-schema-encoding, i.e. "give me information on how the
>> > [QAPI] schema maps to the QMP wire protocol", is more correct.
>> > query-qmp-schema reads like "give me the complete schema for the
>> > QMP wire protocol", which makes it more tempting to treat the
>> > result as a complete schema, rather than a component of what's
>> > defined by the QAPI schema.
>>
>> Well, it *is* the schema for the QMP wire protocol. Which happens to be
>> mechanically derived from the QAPI schema.
>
> True, but the separation from QMP wire schema and QAPI interface schema
> wouldn't be clear to most users. It would be fairly tempting/reasonable
> for the author of a QMP client to assume the "QMP schema" was the
> definitive source for how a client should interact with QEMU without
> realizing or finding the need to reference the QAPI schema for more
> specific constraints (like integer ranges).
The constraints not expressed in the QMP schema generally aren't
expressed in the QAPI schema either, only its comments.
Nevertheless, I quite agree our documentation should refer readers to
the QAPI schema, because it's the source code, and as such it's written
for humans. The value of query-qmp-schema is just for machines.
> I'm somewhat harping on this because that's exactly the misconception
> I had when I first looked at this series, which is why the loss of
> information like integer ranges didn't seem acceptable to me initially.
>
> But I don't really have a problem with query-qmp-schema, the naming
> comments are more a suggestion of the sort of confusion we should
> try to clear up in the accompanying documentation.
>
>>
>> > But in all likelihood trying to cram all that information into the
>> > command name would probably just be confusing to most, so a simpler
>> > name with clear documentation seems reasonable.
>>
>> I think query-qmp-schema hits the sweet spot between "ambiguous because
>> it's too short" and "too long because we tried to make it unambiguous".
>> I'll adopt it in v5.
>>
>> Regarding clear documentation: we don't have to get it perfect in the
>> initial commit, but I'm of course happy to address review of RFC PATCH
>> v4 in v5.
>>
>
> Thanks, sounds reasonable to me.
Okay, we got a plan. Thanks!
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Michael Roth, 2015/09/01
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Eric Blake, 2015/09/01
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Michael Roth, 2015/09/01
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Markus Armbruster, 2015/09/02
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Michael Roth, 2015/09/02
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Markus Armbruster, 2015/09/03
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Eric Blake, 2015/09/03
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Michael Roth, 2015/09/03
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Markus Armbruster, 2015/09/03
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection, Michael Roth, 2015/09/03
- Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection,
Markus Armbruster <=