From patchwork Wed Nov 11 17:50:02 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Blake X-Patchwork-Id: 543009 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id C27B11402A8 for ; Thu, 12 Nov 2015 04:51:33 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; secure) header.d=comcast.net header.i=@comcast.net header.b=QV18dRHv; dkim-atps=neutral Received: from localhost ([::1]:42156 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZwZYR-0003Su-Ue for incoming@patchwork.ozlabs.org; Wed, 11 Nov 2015 12:51:31 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41646) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZwZXq-0003AK-61 for qemu-devel@nongnu.org; Wed, 11 Nov 2015 12:51:17 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZwZXE-0003I6-PJ for qemu-devel@nongnu.org; Wed, 11 Nov 2015 12:50:54 -0500 Received: from resqmta-po-03v.sys.comcast.net ([96.114.154.162]:33262) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZwZXE-0003Hu-Jg for qemu-devel@nongnu.org; Wed, 11 Nov 2015 12:50:16 -0500 Received: from resomta-po-18v.sys.comcast.net ([96.114.154.242]) by resqmta-po-03v.sys.comcast.net with comcast id gHpo1r0035E3ZMc01HqEwQ; Wed, 11 Nov 2015 17:50:14 +0000 Received: from red.redhat.com ([24.10.254.122]) by resomta-po-18v.sys.comcast.net with comcast id gHqA1r00E2fD5rL01HqDF6; Wed, 11 Nov 2015 17:50:14 +0000 From: Eric Blake To: qemu-devel@nongnu.org Date: Wed, 11 Nov 2015 10:50:02 -0700 Message-Id: <1447264202-19554-1-git-send-email-eblake@redhat.com> X-Mailer: git-send-email 2.4.3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; s=q20140121; t=1447264214; bh=tkZA9shFHNsNgXaQmLrTbz+rWWwuwvHFgu5s2022BI0=; h=Received:Received:From:To:Subject:Date:Message-Id; b=QV18dRHvI/Wcr+r53fETCwkp9V7z+Fwla/RLM7GFuiQ65AYVx+m+5GPJ7j7xOfmCW +46SK7eUvVCkaP8OYHsQlxSTQ3qhtdREixTQc0myZvkkZVYrvUeYf6PQwuxuDuDRZR Lm00MCFbPjRCi3Vg8sh0+OB/QM6IryAvrqtdwoEjZvCmwEvn+KpWOwMDCs0aP+p00R TMeV9r7O675MH/BvPhp/FbJq8n3YK/K4ZNDSN2x5ZWJ6Az2nxDUJdovVjB1Cu3bNlo gxssZkawIVDCrX1vxiYNHksOzA7QfvYq3ILFFMHnsztw3Ivc9X15mNY2YLeJ2zL94D vzyugGjF2lryQ== X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 96.114.154.162 Cc: Markus Armbruster , Michael Roth Subject: [Qemu-devel] [PATCH for-2.5] qapi: Document introspection stability considerations X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org We are not ready (and might never be ready) to declare introspection stable between releases. Clients written to control multiple versions of qemu, and desiring to know whether a particular member is supported for a given command, must be prepared to locate that member in spite of qapi changes that may affect the member's location or type within the overall object, even though such changes did not break QMP wire back-compatibility. Signed-off-by: Eric Blake --- docs/qapi-code-gen.txt | 11 +++++++++++ qapi/introspect.json | 9 +++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index f9fa6f3..ceb9a78 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -514,6 +514,17 @@ exactly the server (QEMU) supports. For this purpose, QMP provides introspection via command query-qmp-schema. QGA currently doesn't support introspection. +While Client JSON Protocol wire compatibility should be maintained +between qemu versions, we cannot make the same guarantees for +introspection stability. For example, one version of qemu may provide +a non-variant optional member of a struct, and a later version rework +the member to instead be non-optional and associated with a variant. +Likewise, one version of qemu may list a member with open-ended type +'str', and a later version could convert it to a finite set of strings +via an enum type; or a member may be converted from a specific type to +an alternate that represents a choice between the original type and +something else. + query-qmp-schema returns a JSON array of SchemaInfo objects. These objects together describe the wire ABI, as defined in the QAPI schema. There is no specified order to the SchemaInfo objects returned; a diff --git a/qapi/introspect.json b/qapi/introspect.json index e7c4c3e..9e9369e 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -22,6 +22,15 @@ # what's there), not interface specification. The specification is in # the QAPI schema. # +# Furthermore, while we strive to keep the QMP wire format +# backwards-compatible across qemu versions, the introspection output +# is not guaranteed to have the same stability. For example, one +# version of qemu may list an object member as an optional +# non-variant, while another lists the same member only through the +# object's variants; or the type of a member may change from a generic +# string into a specific enum or from one specific type into an +# alternate that includes the original type alongside something else. +# # Returns: array of @SchemaInfo, where each element describes an # entity in the ABI: command, event, type, ... #