From nobody Mon Feb 9 16:19:46 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1635416776; cv=none; d=zohomail.com; s=zohoarc; b=AQ8/Yl1O/49UJLKXX2bkwg3SD8voF4iSv6JzzVVPsWIwev2SEPKGXq6HD6xByo6QgFgoq+2/vvv8TsTzgI+h5Edf3kfNfdaYlWu4kcN2f4UqoDZr4/UX9w1/lrEgja5zulhX3sniBbPcCBhfOlIu3fvZAnQGFnI+2eJ7IFKO3J8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1635416776; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Dp4F6ngLK3CgvfvwPruQc5xxR7Q7Xdo+ZW7ud9zLFuI=; b=koK6vWkhuBAzrosXSama5DAnsBmiOfcFLnHVDOC2JxSa9Bgbr1oIyilKqFY3YEp+/7sKJrEKClJxDlDrL6o28YJFG9iPPKgRQ7cAYUXnXdcpYUW3moRs0D9SGOypt+p50Gsadp2KIiDDrgFZ1GRyb6hZBzR3r7TwgBfMyNGrrgE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1635416776202100.16155290384313; Thu, 28 Oct 2021 03:26:16 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-480-yr4AtTpEPwuaccAPz_uwNA-1; Thu, 28 Oct 2021 06:26:13 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 395A780363B; Thu, 28 Oct 2021 10:26:08 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1842D6F951; Thu, 28 Oct 2021 10:26:08 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id D758E1832DD4; Thu, 28 Oct 2021 10:26:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 19SAPjOC007392 for ; Thu, 28 Oct 2021 06:25:45 -0400 Received: by smtp.corp.redhat.com (Postfix) id 77A655E272; Thu, 28 Oct 2021 10:25:45 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-7.ams2.redhat.com [10.36.112.7]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 12B285DF36; Thu, 28 Oct 2021 10:25:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 3A46011380AA; Thu, 28 Oct 2021 12:25:20 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1635416775; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Dp4F6ngLK3CgvfvwPruQc5xxR7Q7Xdo+ZW7ud9zLFuI=; b=HE/Q82dPiPu7rt8WyjIrpYxOieJIKncGiYRq+Fq5HzMIy1ecQkiTN0ZgFGlwuU+iHHEwi+ E9nguTXr3P0ymXpKEAcr7bgiUIIIMOJ6x3arSrigHjFXzkP+PL/gkzUISSLe+c4zGBuzz/ 75hgG50LHpVgaHE4ySNxooQjQv9lr98= X-MC-Unique: yr4AtTpEPwuaccAPz_uwNA-1 From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PATCH v2 1/9] qapi: New special feature flag "unstable" Date: Thu, 28 Oct 2021 12:25:12 +0200 Message-Id: <20211028102520.747396-2-armbru@redhat.com> In-Reply-To: <20211028102520.747396-1-armbru@redhat.com> References: <20211028102520.747396-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Cc: kwolf@redhat.com, pkrempa@redhat.com, ehabkost@redhat.com, qemu-block@nongnu.org, quintela@redhat.com, libvir-list@redhat.com, eblake@redhat.com, dgilbert@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, philmd@redhat.com, jsnow@redhat.com, libguestfs@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1635416777616100004 Content-Type: text/plain; charset="utf-8" By convention, names starting with "x-" are experimental. The parts of external interfaces so named may be withdrawn or changed incompatibly in future releases. The naming convention makes unstable interfaces easy to recognize. Promoting something from experimental to stable involves a name change. Client code needs to be updated. Occasionally bothersome. Worse, the convention is not universally observed: * QOM type "input-barrier" has properties "x-origin", "y-origin". Looks accidental, but it's ABI since 4.2. * QOM types "memory-backend-file", "memory-backend-memfd", "memory-backend-ram", and "memory-backend-epc" have a property "x-use-canonical-path-for-ramblock-id" that is documented to be stable despite its name. We could document these exceptions, but documentation helps only humans. We want to recognize "unstable" in code, like "deprecated". So support recognizing it the same way: introduce new special feature flag "unstable". It will be treated specially by the QAPI generator, like the existing feature flag "deprecated", and unlike regular feature flags. This commit updates documentation and prepares tests. The next commit updates the QAPI schema. The remaining patches update the QAPI generator and wire up -compat policy checking. Management applications can then use query-qmp-schema and -compat to manage or guard against use of unstable interfaces the same way as for deprecated interfaces. docs/devel/qapi-code-gen.txt no longer mandates the naming convention. Using it anyway might help writers of programs that aren't full-fledged management applications. Not using it can save us bothersome renames. We'll see how that shakes out. Signed-off-by: Markus Armbruster Reviewed-by: Juan Quintela Reviewed-by: John Snow --- docs/devel/qapi-code-gen.rst | 9 ++++++--- tests/qapi-schema/qapi-schema-test.json | 7 +++++-- tests/qapi-schema/qapi-schema-test.out | 5 +++++ 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 4071c9074a..38f2d7aad3 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -713,6 +713,10 @@ member as deprecated. It is not supported elsewhere s= o far. Interfaces so marked may be withdrawn in future releases in accordance with QEMU's deprecation policy. =20 +Feature "unstable" marks a command, event, enum value, or struct +member as unstable. It is not supported elsewhere so far. Interfaces +so marked may be withdrawn or changed incompatibly in future releases. + =20 Naming rules and reserved names ------------------------------- @@ -746,9 +750,8 @@ Member name ``u`` and names starting with ``has-`` or `= `has_`` are reserved for the generator, which uses them for unions and for tracking optional members. =20 -Any name (command, event, type, member, or enum value) beginning with -``x-`` is marked experimental, and may be withdrawn or changed -incompatibly in a future release. +Names beginning with ``x-`` used to signify "experimental". This +convention has been replaced by special feature "unstable". =20 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let you violate naming rules. Use for new code is strongly discouraged. See diff --git a/tests/qapi-schema/qapi-schema-test.json b/tests/qapi-schema/qa= pi-schema-test.json index b677ab861d..43b8697002 100644 --- a/tests/qapi-schema/qapi-schema-test.json +++ b/tests/qapi-schema/qapi-schema-test.json @@ -273,7 +273,7 @@ 'data': { 'foo': { 'type': 'int', 'features': [ 'deprecated' ] } }, 'features': [ 'feature1' ] } { 'struct': 'FeatureStruct2', - 'data': { 'foo': 'int' }, + 'data': { 'foo': { 'type': 'int', 'features': [ 'unstable' ] } }, 'features': [ { 'name': 'feature1' } ] } { 'struct': 'FeatureStruct3', 'data': { 'foo': 'int' }, @@ -331,7 +331,7 @@ { 'command': 'test-command-features1', 'features': [ 'deprecated' ] } { 'command': 'test-command-features3', - 'features': [ 'feature1', 'feature2' ] } + 'features': [ 'unstable', 'feature1', 'feature2' ] } =20 { 'command': 'test-command-cond-features1', 'features': [ { 'name': 'feature1', 'if': 'TEST_IF_FEATURE_1'} ] } @@ -348,3 +348,6 @@ =20 { 'event': 'TEST_EVENT_FEATURES1', 'features': [ 'deprecated' ] } + +{ 'event': 'TEST_EVENT_FEATURES2', + 'features': [ 'unstable' ] } diff --git a/tests/qapi-schema/qapi-schema-test.out b/tests/qapi-schema/qap= i-schema-test.out index 16846dbeb8..1f9585fa9b 100644 --- a/tests/qapi-schema/qapi-schema-test.out +++ b/tests/qapi-schema/qapi-schema-test.out @@ -308,6 +308,7 @@ object FeatureStruct1 feature feature1 object FeatureStruct2 member foo: int optional=3DFalse + feature unstable feature feature1 object FeatureStruct3 member foo: int optional=3DFalse @@ -373,6 +374,7 @@ command test-command-features1 None -> None feature deprecated command test-command-features3 None -> None gen=3DTrue success_response=3DTrue boxed=3DFalse oob=3DFalse preconfig= =3DFalse + feature unstable feature feature1 feature feature2 command test-command-cond-features1 None -> None @@ -394,6 +396,9 @@ event TEST_EVENT_FEATURES0 FeatureStruct1 event TEST_EVENT_FEATURES1 None boxed=3DFalse feature deprecated +event TEST_EVENT_FEATURES2 None + boxed=3DFalse + feature unstable module include/sub-module.json include sub-sub-module.json object SecondArrayRef --=20 2.31.1