From patchwork Tue Jul 20 23:26:37 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 481602 Delivered-To: patch@linaro.org Received: by 2002:a17:907:d92:0:0:0:0 with SMTP id go18csp6005581ejc; Tue, 20 Jul 2021 16:30:54 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwJauq+IgB6q5QDisjzFrQgLfh7uzkj8+fdTuQi76u+TKNxFIqzxvlIzLVvgYZKtUdVv1fV X-Received: by 2002:a25:b321:: with SMTP id l33mr42742977ybj.434.1626823854749; Tue, 20 Jul 2021 16:30:54 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1626823854; cv=none; d=google.com; s=arc-20160816; b=02U40aq34ZV6Uxh/g6/iaM455OHLsHsIHlMtUq1ZK3rqSv59OusngDfTkExpdsSrBg qzCQmUYYwGE7wxYO/eHL1GozGh3NHMbpc61E4udp9jyZAJ3ha6akBi7KwO6RbGMV8bk4 vO8KZqQyvwAALBlK/zHccpMiyQaBaI6UoJMRb88qP1D76TJI4D2Gmq/DMG33/ZYIYA0P cuEZsxc8gpsM0DohUzzWUDHYk1uOsb6n3bgmeO4gRTjhSfn5Q3gyKIPfU8oPi6KtAvJL YJztZY0VH+RVjkF5niYfXAM5RuzYFOmznburocaye8EGKLlZZ3ITyiC+MLyZIsU6cs8D OMqA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=qkwgpt6wENAxEhm+bv1Rjetwu3EU3B/BVjqRfhhq3Pc=; b=HuRYMvVRqkx3c1C7lIhQn6b4B9fks9aB8K0unwgQCLLYEsRlJv5701w0RU/sAYF9k1 tl+KaLoSNkzmkqVr6boZ6g00uWz5sad50NO1yJSWK+GlJCY/bd79+ksEwOXDM4SO6IfP GVw2c0GVneDen1+nYasvUcyDOXbh/9jx8JbKvbmapRc4LXSAIrvzIaj1tfS1vfFxsAAY lmrhDzUz9hi8aQvG5r1MJ7l2wFTmmp9NSaCBvmZvvK9AtThCun24uPXNB7eCKc7JuJG0 zVY70hKQ9ES5kDr/9ZupdWqOhvpUsphVcHF4XAbsfQxkbxNd1L2nFryfoh2iVRJrMdfS R8BA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="oPwz/aJv"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id f18si23265514ybq.357.2021.07.20.16.30.54 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Tue, 20 Jul 2021 16:30:54 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="oPwz/aJv"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:58830 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m5zCQ-0000Dh-1d for patch@linaro.org; Tue, 20 Jul 2021 19:30:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41288) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m5z8r-00038A-3b for qemu-devel@nongnu.org; Tue, 20 Jul 2021 19:27:13 -0400 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:53805) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m5z8p-0005aK-Bx for qemu-devel@nongnu.org; Tue, 20 Jul 2021 19:27:12 -0400 Received: by mail-wm1-x32e.google.com with SMTP id w13so286338wmc.3 for ; Tue, 20 Jul 2021 16:27:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qkwgpt6wENAxEhm+bv1Rjetwu3EU3B/BVjqRfhhq3Pc=; b=oPwz/aJvcZxjW6fZQD4vBP0X2qH3W9qMvsogqJEnVLaN0A54K3lOGmo/BkuikWKqhZ IrSv0kBBWTk5w+WuXYXlUwO1H2s6Fw2HIv8XgLnjzRuao/IWl/dHQ0E8+Cv5SHTtf3dm yXbP0i44JXlBc6RjJDiqhgPf7f02R7tguDIisIbG0nIG0IzWfr4BQet5TcMjr4Ohn/je UgWVqIII7oVap3mAo6W3jpvMKvxdjIXzyC35mZnWa6JtZKXiYUOpwGCrANHx5I4J4Hcc YmyyUNOEdeWpLWDltVYhw6/qF38CpKQHJ87z5FD0thwerjW1CEoYeVY+HODjII9daE0f LCAA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=qkwgpt6wENAxEhm+bv1Rjetwu3EU3B/BVjqRfhhq3Pc=; b=ByfmlYd/6G/90hxbync7W9zLdUxnA91ONE9fSnwclyUanhTKpUmEntlMr1RwaMKmCh gtGmPSMR9X7tTUHK2dtWi99QeUZHGiEw2O+H5ro+IDJJJREOblWHTE1HxFVq+bm3EE2i cdInUZqnNSupsZzNbSRPmyBOeYkjVeDT6EpvdTSfu14VcP1qjYEwJH9YZZiBEn543jkh US4J4XtcBaGwolLlNt5i7SjBt2pNtdj9fOmVKbm87jVa+t3gMNg2NN39GOZDB9XT8cTy N/XtlNJnxHQf0luuzdDdHdIe0sVO+5aaVovBC4xDw/Qtza3fE7HxCpnVetGvIDhLFMPq f3Tg== X-Gm-Message-State: AOAM532uCFSAO0FGluKoeJfWC0zG0aKyuOuPzJ4nmsgkdXlKDa/NeGbP Lu/vMkn4qijSY9SfaTozAixA9w== X-Received: by 2002:a1c:9a97:: with SMTP id c145mr937221wme.42.1626823629901; Tue, 20 Jul 2021 16:27:09 -0700 (PDT) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id b6sm3608729wmj.34.2021.07.20.16.27.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 20 Jul 2021 16:27:07 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 175C71FF8F; Wed, 21 Jul 2021 00:27:04 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v1 03/29] docs: add a section on the generalities of vhost-user Date: Wed, 21 Jul 2021 00:26:37 +0100 Message-Id: <20210720232703.10650-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.32.0.264.g75ae10bc75 In-Reply-To: <20210720232703.10650-1-alex.bennee@linaro.org> References: <20210720232703.10650-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32e.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: fam@euphon.net, berrange@redhat.com, "Michael S. Tsirkin" , f4bug@amsat.org, stefanha@redhat.com, crosa@redhat.com, pbonzini@redhat.com, =?utf-8?q?Alex_Benn=C3=A9e?= , aurelien@aurel32.net Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" While we do mention some of this stuff in the various daemons and manuals the subtleties of the socket and memory sharing are sometimes missed. This document attempts to give some background on vhost-user daemons in general terms. Signed-off-by: Alex Bennée Reviewed-by: Stefan Hajnoczi Message-Id: <20210714182056.25888-4-alex.bennee@linaro.org> --- docs/interop/vhost-user.rst | 2 + docs/system/device-emulation.rst | 1 + docs/system/devices/vhost-user.rst | 59 ++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100644 docs/system/devices/vhost-user.rst -- 2.32.0.264.g75ae10bc75 diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index d6085f7045..7fc693521e 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -1,3 +1,5 @@ +.. _vhost_user_proto: + =================== Vhost-user Protocol =================== diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index 7af5dbefab..3bebb862b9 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -86,4 +86,5 @@ Emulated Devices devices/net.rst devices/nvme.rst devices/usb.rst + devices/vhost-user.rst devices/virtio-pmem.rst diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/vhost-user.rst new file mode 100644 index 0000000000..86128114fa --- /dev/null +++ b/docs/system/devices/vhost-user.rst @@ -0,0 +1,59 @@ +.. _vhost_user: + +vhost-user back ends +-------------------- + +vhost-user back ends are way to service the request of VirtIO devices +outside of QEMU itself. To do this there are a number of things +required. + +vhost-user device +=================== + +These are simple stub devices that ensure the VirtIO device is visible +to the guest. The code is mostly boilerplate although each device has +a ``chardev`` option which specifies the ID of the ``--chardev`` +device that connects via a socket to the vhost-user *daemon*. + +vhost-user daemon +================= + +This is a separate process that is connected to by QEMU via a socket +following the :ref:`vhost_user_proto`. There are a number of daemons +that can be built when enabled by the project although any daemon that +meets the specification for a given device can be used. + +Shared memory object +==================== + +In order for the daemon to access the VirtIO queues to process the +requests it needs access to the guest's address space. This is +achieved via the ``memory-backend-file`` or ``memory-backend-memfd`` +objects. A reference to a file-descriptor which can access this object +will be passed via the socket as part of the protocol negotiation. + +Currently the shared memory object needs to match the size of the main +system memory as defined by the ``-m`` argument. + +Example +======= + +First start you daemon. + +.. parsed-literal:: + + $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS + +The you start your QEMU instance specifying the device, chardev and +memory objects. + +.. parsed-literal:: + + $ |qemu_system| \\ + -m 4096 \\ + -chardev socket,id=ba1,path=/var/run/foo.sock \\ + -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\ + -object memory-backend-memfd,id=mem,size=4G,share=on \\ + -numa node,memdev=mem \\ + ... +