From nobody Mon Feb 9 17:37:29 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1713501654; cv=none; d=zohomail.com; s=zohoarc; b=BI1nZ8ZGTaK5ahmHEqVT0nBLEsEfl0+BIzlvdpjlf6/M3AmByHzR17gpuFamFovSc1WcTQr5gN60HW+FERHQ2UWTxuQrU0JYEMPbpMoZ/cnbOAZRjH3/Wh4sKrkf0vbzBpFajS5jcbEAwsoCuUhfw1NIQ99Rf3i+7Apjbt2bG08= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1713501654; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=aT7Zt+MnqDBeB3Aa1m9yjVj+44B/I2Lh5VoQCq7rSj8=; b=D52ivz/UCAcXRoLq3pAe0UbBIxFafdZs0UHK+oGTLJDs39Huhk0EAhMnONYdlJPstfgmZtn8dcLo8dNOz56eKtK5QOv9UHtVICFuh+sh2dvRHY2cGxHKcsej0jo+m+u7fYqfao0L4qeC2yzXw/L6dB06LANE6Oy8+fdiyp3bUSc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1713501654444542.6379463081682; Thu, 18 Apr 2024 21:40:54 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rxg1Q-0007W7-2S; Fri, 19 Apr 2024 00:38:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rxg1G-0007TO-MZ for qemu-devel@nongnu.org; Fri, 19 Apr 2024 00:38:38 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rxg1E-0004DM-V7 for qemu-devel@nongnu.org; Fri, 19 Apr 2024 00:38:38 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-260-mNEPjwTxN4-f2B3iwoVt8g-1; Fri, 19 Apr 2024 00:38:32 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EF6A8810602; Fri, 19 Apr 2024 04:38:31 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.8.7]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4AC424011FF7; Fri, 19 Apr 2024 04:38:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713501516; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=aT7Zt+MnqDBeB3Aa1m9yjVj+44B/I2Lh5VoQCq7rSj8=; b=gmnTtJkNLUCOUBl5JdFTECCgtxW2hes5fceUHYbcIx20Et3P+1Qf/FcAcCuwxAYKIsfeQ2 jnpZhbrR2Q0NS9/ysRtfVjdMaFBqzMjLxXTm43TESwpobLJxvJ+g5dfUfj/fARR+shM1kW LNjQkQyj4b//snts9DjOTJMB+Ozxjos= X-MC-Unique: mNEPjwTxN4-f2B3iwoVt8g-1 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Markus Armbruster , Victor Toso de Carvalho , Peter Maydell , Paolo Bonzini , John Snow Subject: [PATCH 14/27] docs/qapi-domain: add qapi:alternate directive Date: Fri, 19 Apr 2024 00:38:02 -0400 Message-ID: <20240419043820.178731-15-jsnow@redhat.com> In-Reply-To: <20240419043820.178731-1-jsnow@redhat.com> References: <20240419043820.178731-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-2.067, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1713501655440100002 Content-Type: text/plain; charset="utf-8" Add the .. qapi:alternate:: directive, object, and qapi:alt:`name` cross-reference role. Add the "Choices:" field list for describing alternate choices. Like other field lists that reference QAPI types, a forthcoming commit will add cross-referencing support to this field. RFC: In the future, it would be nice to directly inline Alternates as part of the type information in the containing object (i.e. directly in arguments/members) - but that's a task for another series. For now, the branch "names" are documented just like qapidoc.py does, even though this information is superfluous for user documentation. Room for future improvement, but not now. Signed-off-by: John Snow --- docs/qapi/index.rst | 7 +++++++ docs/sphinx/qapi-domain.py | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst index cf794e6e739..9bfe4d9f454 100644 --- a/docs/qapi/index.rst +++ b/docs/qapi/index.rst @@ -127,3 +127,10 @@ Explicit cross-referencing syntax for QAPI modules is = available with is treated solely as a read-only manifest of blocks to copy. :value always: The bitmap is always synchronized with the operation, regardless of whether or not the operation was successful. + +.. qapi:alternate:: BlockDirtyBitmapOrStr + :since: 4.1 + + :choice str local: name of the bitmap, attached to the same node as + target bitmap. + :choice BlockDirtyBitmap external: bitmap with specified node diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py index 6759c39290d..c6eb6324594 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -305,6 +305,22 @@ class QAPIEnum(QAPIObject): ) =20 =20 +class QAPIAlternate(QAPIObject): + """Description of a QAPI Alternate.""" + + doc_field_types =3D QAPIObject.doc_field_types.copy() + doc_field_types.extend( + [ + TypedField( + "choice", + label=3D_("Choices"), + names=3D("choice",), + can_collapse=3DTrue, + ), + ] + ) + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -458,6 +474,7 @@ class QAPIDomain(Domain): "module": ObjType(_("module"), "mod", "obj"), "command": ObjType(_("command"), "cmd", "obj"), "enum": ObjType(_("enum"), "enum", "obj", "type"), + "alternate": ObjType(_("alternate"), "alt", "obj", "type"), } =20 # Each of these provides a ReST directive, @@ -466,6 +483,7 @@ class QAPIDomain(Domain): "module": QAPIModule, "command": QAPICommand, "enum": QAPIEnum, + "alternate": QAPIAlternate, } =20 # These are all cross-reference roles; e.g. @@ -475,6 +493,7 @@ class QAPIDomain(Domain): "mod": QAPIXRefRole(), "cmd": QAPIXRefRole(), "enum": QAPIXRefRole(), + "alt": QAPIXRefRole(), "type": QAPIXRefRole(), # reference any data type (excludes modul= es, commands, events) "obj": QAPIXRefRole(), # reference *any* type of QAPI object. } --=20 2.44.0