From nobody Tue Nov 4 18:50:17 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1530376471619438.0962298205583; Sat, 30 Jun 2018 09:34:31 -0700 (PDT) Received: from localhost ([::1]:47406 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fZIpK-0004Tk-0o for importer@patchew.org; Sat, 30 Jun 2018 12:34:22 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55954) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fZIj0-0008UN-MW for qemu-devel@nongnu.org; Sat, 30 Jun 2018 12:27:51 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fZIiz-0007bq-PE for qemu-devel@nongnu.org; Sat, 30 Jun 2018 12:27:50 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:44764 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fZIiz-0007b8-JX for qemu-devel@nongnu.org; Sat, 30 Jun 2018 12:27:49 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 333E2400B454 for ; Sat, 30 Jun 2018 16:27:49 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-16.ams2.redhat.com [10.36.116.16]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E3AC410FFE6B; Sat, 30 Jun 2018 16:27:46 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 06A7C1132D6B; Sat, 30 Jun 2018 18:27:45 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Sat, 30 Jun 2018 18:27:44 +0200 Message-Id: <20180630162744.15920-6-armbru@redhat.com> In-Reply-To: <20180630162744.15920-1-armbru@redhat.com> References: <20180630162744.15920-1-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Sat, 30 Jun 2018 16:27:49 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Sat, 30 Jun 2018 16:27:49 +0000 (UTC) for IP:'10.11.54.3' DOMAIN:'int-mx03.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'armbru@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PULL 5/5] docs: mention shared state protect for OOB X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Xu Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" From: Peter Xu Out-Of-Band handlers need to protect shared state if there is any. Mention it in the document. Meanwhile, touch up some other places too, either with better English, or reordering of bullets. Suggested-by: Markus Armbruster Reviewed-by: Markus Armbruster Signed-off-by: Peter Xu Message-Id: <20180620073223.31964-6-peterx@redhat.com> Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 88a70e4d45..94a7e8f4d0 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -666,22 +666,27 @@ command: =20 - They are executed in order, - They run only in main thread of QEMU, -- They have the BQL taken during execution. +- They run with the BQL held. =20 When a command is executed with OOB, the following changes occur: =20 - They can be completed before a pending in-band command, - They run in a dedicated monitor thread, -- They do not take the BQL during execution. +- They run with the BQL not held. =20 OOB command handlers must satisfy the following conditions: =20 -- It executes extremely fast, -- It does not take any lock, or, it can take very small locks if all - critical regions also follow the rules for OOB command handler code, +- It terminates quickly, - It does not invoke system calls that may block, - It does not access guest RAM that may block when userfaultfd is - enabled for postcopy live migration. + enabled for postcopy live migration, +- It takes only "fast" locks, i.e. all critical sections protected by + any lock it takes also satisfy the conditions for OOB command + handler code. + +The restrictions on locking limit access to shared state. Such access +requires synchronization, but OOB commands can't take the BQL or any +other "slow" lock. =20 If in doubt, do not implement OOB execution support. =20 --=20 2.17.1