From patchwork Fri Sep 15 10:25:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hanna Czenczek X-Patchwork-Id: 13386840 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6501BEE6452 for ; Fri, 15 Sep 2023 10:27:22 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qh61p-0007Dk-NR; Fri, 15 Sep 2023 06:26:25 -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 1qh61D-0006cZ-El for qemu-devel@nongnu.org; Fri, 15 Sep 2023 06:25:51 -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 1qh61A-0002mF-3M for qemu-devel@nongnu.org; Fri, 15 Sep 2023 06:25:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1694773538; h=from:from: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; bh=1bKJvo7eC/DS/g3Qo8pX+3+4mjexf2CS6l0L7VJ7PFA=; b=bjuEKYTl52sBVTmBf/BZVVuqdo/Gn/vcbMuZVIXCVhymILIGQddYYW4PT9SZWWaaCehYqH P//LvnHrme1bI3Ty+XSYcfv7PZaLw5Fu+TKah3fAK2xU2aMsZx2nuDeIya78HQqZjeUsDI Cu3PeKg1hWeivLfudnx8ukHTvkfwsQE= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-608-67TS3hLON3umOp0DRKT5MA-1; Fri, 15 Sep 2023 06:25:36 -0400 X-MC-Unique: 67TS3hLON3umOp0DRKT5MA-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6D229803497 for ; Fri, 15 Sep 2023 10:25:36 +0000 (UTC) Received: from localhost (unknown [10.39.194.19]) by smtp.corp.redhat.com (Postfix) with ESMTPS id EB6CB409AFC1; Fri, 15 Sep 2023 10:25:35 +0000 (UTC) From: Hanna Czenczek To: qemu-devel@nongnu.org, virtio-fs@redhat.com Cc: Hanna Czenczek , Stefan Hajnoczi , "Michael S . Tsirkin" , =?utf-8?q?Eugenio_P=C3=A9rez?= , German Maglione Subject: [PATCH v3 2/5] vhost-user.rst: Clarify enabling/disabling vrings Date: Fri, 15 Sep 2023 12:25:27 +0200 Message-ID: <20230915102531.55894-3-hreitz@redhat.com> In-Reply-To: <20230915102531.55894-1-hreitz@redhat.com> References: <20230915102531.55894-1-hreitz@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.1 Received-SPF: pass client-ip=170.10.133.124; envelope-from=hreitz@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H3=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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Currently, the vhost-user documentation says that rings are to be initialized in a disabled state when VHOST_USER_F_PROTOCOL_FEATURES is negotiated. However, by the time of feature negotiation, all rings have already been initialized, so it is not entirely clear what this means. At least the vhost-user-backend Rust crate's implementation interpreted it to mean that whenever this feature is negotiated, all rings are to put into a disabled state, which means that every SET_FEATURES call would disable all rings, effectively halting the device. This is problematic because the VHOST_F_LOG_ALL feature is also set or cleared this way, which happens during migration. Doing so should not halt the device. Other implementations have interpreted this to mean that the device is to be initialized with all rings disabled, and a subsequent SET_FEATURES call that does not set VHOST_USER_F_PROTOCOL_FEATURES will enable all of them. Here, SET_FEATURES will never disable any ring. This interpretation does not suffer the problem of unintentionally halting the device whenever features are set or cleared, so it seems better and more reasonable. We should clarify this in the documentation. Signed-off-by: Hanna Czenczek --- docs/interop/vhost-user.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index bb4dd0fd60..9b9b802c60 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -409,12 +409,20 @@ and stop ring upon receiving ``VHOST_USER_GET_VRING_BASE``. Rings can be enabled or disabled by ``VHOST_USER_SET_VRING_ENABLE``. -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the -ring starts directly in the enabled state. - -If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is -initialized in a disabled state and is enabled by -``VHOST_USER_SET_VRING_ENABLE`` with parameter 1. +If ``VHOST_USER_SET_FEATURES`` does not negotiate +``VHOST_USER_F_PROTOCOL_FEATURES``, rings are enabled immediately when +started. + +If ``VHOST_USER_SET_FEATURES`` does negotiate +``VHOST_USER_F_PROTOCOL_FEATURES``, each ring will remain in the disabled +state until ``VHOST_USER_SET_VRING_ENABLE`` enables it with parameter 1. + +Back-end implementations that support ``VHOST_USER_F_PROTOCOL_FEATURES`` +should implement this by initializing each ring in a disabled state, and +enabling them when ``VHOST_USER_SET_FEATURES`` is used without +negotiating ``VHOST_USER_F_PROTOCOL_FEATURES``. Other than that, rings +should only be enabled and disabled through +``VHOST_USER_SET_VRING_ENABLE``. While processing the rings (whether they are enabled or not), the back-end must support changing some configuration aspects on the fly.