From nobody Sun May 19 00:17:18 2024 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=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1625683772; cv=none; d=zohomail.com; s=zohoarc; b=GkHruMgP6K5uDfSo2o2D8FwsqiWL0LQg4vZSktA6i1E5KU8PlxHPK+Dbchq9iU0tH3Iu5FacXZrIA2e1Nyn74w56fXu9eUaqugGTyXvb8R8aPWBDr2cF6GBeqVkS9TRkmFwvhtvdMteyhiq2d/ObP5KUojdMMPgo2sjvJAMqYbo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1625683772; 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=O7eiCiiOA1Sqqm1FgUzdGWyHxXgBgMmn6hDxRrW6WnA=; b=ZuTxDI0CcAIVtz/dLZDRas6Zgf1xyf5nx/T7Lm9mVoMx9G/10Rg/nzSoScXE2NRQzP07My0Y1Lyuj943NdXphfkAjzBlIl3JappfvdFQEtYSGQzS4Y+DKaxlUF7onqQ3UMKAUXV8wp+M4QsmbEmVTYIiK+C5AhqbOz89yLO8ZYk= 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 1625683772246261.17748740323213; Wed, 7 Jul 2021 11:49:32 -0700 (PDT) Received: from localhost ([::1]:33090 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m1Cbz-0004b6-3R for importer@patchew.org; Wed, 07 Jul 2021 14:49:31 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:35320) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m1CYa-0007XY-SE for qemu-devel@nongnu.org; Wed, 07 Jul 2021 14:46:00 -0400 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:37508) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m1CYU-0000mJ-3R for qemu-devel@nongnu.org; Wed, 07 Jul 2021 14:46:00 -0400 Received: by mail-wr1-x42f.google.com with SMTP id i94so4226140wri.4 for ; Wed, 07 Jul 2021 11:45:52 -0700 (PDT) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id l34sm8537166wms.45.2021.07.07.11.45.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 07 Jul 2021 11:45:50 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 4E96B1FF87; Wed, 7 Jul 2021 19:45:49 +0100 (BST) 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=O7eiCiiOA1Sqqm1FgUzdGWyHxXgBgMmn6hDxRrW6WnA=; b=KBFvqn+D+CdNXd9zqmjCbwWbFXxpR0/DnwZwbYMhx97Cngl75LbO2ZEGS3XgpDw7Tj JYQeS9fMbxIeylvr8Yhz2TR15wXdcCZg5qYcMaspssbYb+YXGnFppF6OnXzMeNYrBC6T XijnPXNWc8rLvrzU0KuFUV58xFBnTmmyniQ1YgZpUMEbnLCVMe+4E/ycgmMG+DKPS7x3 4/L3irCb7VomKhrV2YQhXBBhnorlEy+77m6v0pYQlOj1EMuDihLFMWWBkDG7xDaWgcwz UxL5rxlLtHdmQVziA2HnJgAJtofYLBr/sZXmBm4vzDNptlef8zmXVSH3+a+n/Joo0HpV BS0g== 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=O7eiCiiOA1Sqqm1FgUzdGWyHxXgBgMmn6hDxRrW6WnA=; b=BjbxpHMyp9AgSbNLaSJNI/lMmszI9S/LVHkBAzTbpFDa6U48DgmO11quujtSyZxWJI X42Z3VR1MGw9fAh/wACJbQaGSg9O2H07KqiOprpK7disNVWSMxreKK/P8yyTzNLxf0MA jwafveYFyIpRNkM/bZfJ7GferiSSql1VDMdQZ7ql+EGWV5u6MS46ICQnYWz6RvsFzb6z 8NrZ9gWFWr76oCF2J6bKx2QLtONuRyHn11uyFMNgMdLjV/+zmKEy0DiBafs+XV6t1idD 6XhjlPtaM2HCIwusGnlgAacISTghHUnvDHbZc2XXAfc8iqNXnrM8k9/RiwRfPz4Ev3PY JpJQ== X-Gm-Message-State: AOAM530VAyHXyTL/JpHqkpc8DeociNI8GpVgFsJbynbohgA2+lqL68Rb bxOLgfBVuKF7Lt17ciKTC9hGFw== X-Google-Smtp-Source: ABdhPJzTNBnLyyq0n/wUnVZ5MfhwQwXWyjV0/GeEFpD1m8KZ87c2bZV7J+IVcsTH9QNtogO5KcQKJw== X-Received: by 2002:a5d:4392:: with SMTP id i18mr9361765wrq.231.1625683551562; Wed, 07 Jul 2021 11:45:51 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v1 1/2] docs: collect the disparate device emulation docs into one section Date: Wed, 7 Jul 2021 19:45:48 +0100 Message-Id: <20210707184549.24436-2-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210707184549.24436-1-alex.bennee@linaro.org> References: <20210707184549.24436-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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=2a00:1450:4864:20::42f; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x42f.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: =?UTF-8?q?Alex=20Benn=C3=A9e?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1625683772668100001 While we are at it add a brief preamble that explains some of the common concepts in QEMU's device emulation which will hopefully lead to less confusing about our dizzying command line options. Signed-off-by: Alex Benn=C3=A9e --- docs/system/device-emulation.rst | 78 +++++++++++++++++++++++ docs/system/{ =3D> devices}/ivshmem.rst | 0 docs/system/{ =3D> devices}/net.rst | 0 docs/system/{ =3D> devices}/nvme.rst | 0 docs/system/{ =3D> devices}/usb.rst | 0 docs/system/{ =3D> devices}/virtio-pmem.rst | 0 docs/system/index.rst | 6 +- 7 files changed, 79 insertions(+), 5 deletions(-) create mode 100644 docs/system/device-emulation.rst rename docs/system/{ =3D> devices}/ivshmem.rst (100%) rename docs/system/{ =3D> devices}/net.rst (100%) rename docs/system/{ =3D> devices}/nvme.rst (100%) rename docs/system/{ =3D> devices}/usb.rst (100%) rename docs/system/{ =3D> devices}/virtio-pmem.rst (100%) diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulatio= n.rst new file mode 100644 index 0000000000..a0f00bc340 --- /dev/null +++ b/docs/system/device-emulation.rst @@ -0,0 +1,78 @@ +.. _device-emulation: + +Device Emulation +---------------- + +QEMU supports the emulation of a large number of devices from +peripherals such network cards and USB devices to integrated systems +on a chip (SoCs). Configuration of these is often a source of +confusion so it helps to have an understanding of some of the terms +used to describes devices within QEMU. + +Common Terms +~~~~~~~~~~~~ + +Device Front End +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +A device front end is how a device is presented to the guest. The type +of device presented should match the hardware that the guest operating +system is expecting to see. All devices can be specified with the +``--device`` command line option. Running QEMU with the command line +options ``--device help`` will list all devices it is aware of. Using +the command line ``--device foo,help`` will list the additional +configuration options available for that device. + +A front end is often paired with a back end, which describes how the +host's resources are used in the emulation. + +Device Buses +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +All devices exist on a BUS. Depending on the machine model you choose +(``-M foo``) a number of buses will have been automatically created. +In most cases the BUS a device is attached to can be inferred, for +example PCI devices are generally automatically allocated to the next +free slot of the PCI bus. However in complicated configurations you +can explicitly specify what bus a device is attached to and its +address. Some devices, for example a PCI SCSI host controller, will +add an additional bus to the system that other devices can be attached +to. + +Device Back End +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The back end describes how the data from the emulated device will be +processed by QEMU. The configuration of the back end is usually +specific to the class of device being emulated. For example serial +devices will be backed by a ``--chardev`` which can redirect the data +to a file or socket or some other system. Storage devices are handled +by ``--blockdev`` which will specify how blocks are handled, for +example being stored in a qcow2 file or accessing a raw host disk +partition. Back ends can sometimes be stacked to implement features +like snapshots. + +While the choice of back end is generally transparent to the guest +there are cases where features will not be reported to the guest if +the back end is unable to support it. + +Device Pass Through +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Device pass through is where the device is actually given access to +the underlying hardware. This can be as simple as exposing a single +USB device on the host system to the guest or dedicating a video card +in a PCI slot to the exclusive use of the guest. + + +Emulated Devices +~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + devices/ivshmem.rst =20 + devices/net.rst + devices/nvme.rst + devices/usb.rst + devices/virtio-pmem.rst diff --git a/docs/system/ivshmem.rst b/docs/system/devices/ivshmem.rst similarity index 100% rename from docs/system/ivshmem.rst rename to docs/system/devices/ivshmem.rst diff --git a/docs/system/net.rst b/docs/system/devices/net.rst similarity index 100% rename from docs/system/net.rst rename to docs/system/devices/net.rst diff --git a/docs/system/nvme.rst b/docs/system/devices/nvme.rst similarity index 100% rename from docs/system/nvme.rst rename to docs/system/devices/nvme.rst diff --git a/docs/system/usb.rst b/docs/system/devices/usb.rst similarity index 100% rename from docs/system/usb.rst rename to docs/system/devices/usb.rst diff --git a/docs/system/virtio-pmem.rst b/docs/system/devices/virtio-pmem.= rst similarity index 100% rename from docs/system/virtio-pmem.rst rename to docs/system/devices/virtio-pmem.rst diff --git a/docs/system/index.rst b/docs/system/index.rst index 6092eb2d91..641d243ba4 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -16,15 +16,12 @@ Contents: =20 quickstart invocation + device-emulation keys mux-chardev monitor images - net virtio-net-failover - usb - nvme - ivshmem linuxboot generic-loader guest-loader @@ -35,7 +32,6 @@ Contents: gdb managed-startup cpu-hotplug - virtio-pmem pr-manager targets security --=20 2.20.1 From nobody Sun May 19 00:17:18 2024 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=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1625683888; cv=none; d=zohomail.com; s=zohoarc; b=XUiyB3LpPRnPhF0XP/jfkMhTYdFbRVyR9QG7Px0snoVqNoDLy5V8rBHp2AZhf6gWAi1UVEzTahwW52YdEXzDQf2Xc5tcf5UeVwv5iy7FXgeDeWXKXhS9G6fsuGIIbclY0el4Wox874eTKdxeFjGkC9T+b+4yGc8cNoas3voGhE0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1625683888; 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=G7tH/UyjoZn7F4238YHQ3Au0z5gN4wRoSGJnmtNDE80=; b=FAYsuy1W7e7gIwKAs49VReVoI3mY0PAOJ/OXDz/aQv+opJdqdWZy3HZcVMsyasaCFV3Dn83ZQ1byQZYtGSCMkiiqlTO11CVecc2YcUc0cwqm40JhsVBb2geZySWzcfpqDxJ15LZ2D0q+r1MPeWSO+zIHvG1AUyOEtBtVMPlQfv8= 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 1625683888824401.9542229629134; Wed, 7 Jul 2021 11:51:28 -0700 (PDT) Received: from localhost ([::1]:36904 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m1Cdr-0007Ep-QB for importer@patchew.org; Wed, 07 Jul 2021 14:51:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:35326) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m1CYb-0007cH-W2 for qemu-devel@nongnu.org; Wed, 07 Jul 2021 14:46:02 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:41819) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1m1CYU-0000mQ-Oj for qemu-devel@nongnu.org; Wed, 07 Jul 2021 14:46:01 -0400 Received: by mail-wr1-x436.google.com with SMTP id u8so4199450wrq.8 for ; Wed, 07 Jul 2021 11:45:54 -0700 (PDT) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id s7sm21777158wrp.97.2021.07.07.11.45.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 07 Jul 2021 11:45:50 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 682FD1FF8C; Wed, 7 Jul 2021 19:45:49 +0100 (BST) 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=G7tH/UyjoZn7F4238YHQ3Au0z5gN4wRoSGJnmtNDE80=; b=Cr+VR0xZyi3AOQelEoy3JkHoRcX1HIhMW/OrSxlmZ7k31ZjLl4P8MdmfXMyzZSfAP9 z0SGClMy+d2jA5WpQpiSwnLbAo2erhHZH8lL0f0XiJa1pQpWDRdahk0FsGW2ep4eSgkI mBuODK3Y4JZGAbitnRjpcxpmbJX3V2oPhLXVgIR25KA9nGBzC1qyK+NqZBb3y/9AsfeG i7JsqofqtFXnbXJEU4YZNgLH+pndkHrFbh1N/VYvbWkZ8BZl4t49lCP5fftjT/xqdhDb jk97RUUbezUrbyKEqdhj/FaiEIeEhY74ZSsfOhG1ATVD4q92v8qnnoPiHmFH5lCBARfb oPSg== 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=G7tH/UyjoZn7F4238YHQ3Au0z5gN4wRoSGJnmtNDE80=; b=te64pt7zB1PUKxT5KUX/mSBp0aJ5t6JRRY0zuk05mIuvUa4DuLyNPTMaEPxuB0BXmp 4uM9CWeZFgNDPTN9J5U0IzewUONr8xX4+Yo7+f0QukC3BtrqfynYT0X8m1KVe/86QIA3 +/bzagPqVr9K3yzwycxfBoYOA5SISScvMxsdl8l0P15rt+gCGZ8hvzd1QageiDuO22Nf Epm9jftcOp6VaD5PCakYjnKdTbcf5+YrXV1ONB+jddA1koEzcdE8WBFCAGKDvLIeGtI8 ZjNf+iY+KEixrfa7uK5A4Ny+yuWQCh23P/awpwBHfCfJN5daQ359/D3lZzMemAkrLRm9 Tbow== X-Gm-Message-State: AOAM530eUCmgMdKx9B/5qVE1S5MO7rlKV0dEJM8wvE4OXgEVJQUs2762 MqH/s6AuraE7v1Nb3TFLpaBhqw== X-Google-Smtp-Source: ABdhPJxEWkrf72CENC15N6ZeQtzMgekMnxTDT/5SXUoYXJikpyxWsriDRt15eD5qiKbxyfu6WAHXpg== X-Received: by 2002:a5d:6c69:: with SMTP id r9mr28763296wrz.8.1625683553202; Wed, 07 Jul 2021 11:45:53 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Subject: [PATCH v1 2/2] docs: add a section on the generalities of vhost-user Date: Wed, 7 Jul 2021 19:45:49 +0100 Message-Id: <20210707184549.24436-3-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20210707184549.24436-1-alex.bennee@linaro.org> References: <20210707184549.24436-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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=2a00:1450:4864:20::436; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x436.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: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Stefan Hajnoczi , "Michael S. Tsirkin" Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1625683890506100001 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=C3=A9e Cc: Stefan Hajnoczi --- docs/interop/vhost-user.rst | 4 ++- docs/system/device-emulation.rst | 1 + docs/system/devices/vhost-user.rst | 57 ++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/system/devices/vhost-user.rst diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index d6085f7045..f46423b6f3 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -1,3 +1,5 @@ +.. _vhost_user_proto: + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Vhost-user Protocol =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -6,7 +8,7 @@ Vhost-user Protocol :Licence: This work is licensed under the terms of the GNU GPL, version 2 or later. See the COPYING file in the top-level directory. - + =20 .. contents:: Table of Contents =20 Introduction diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulatio= n.rst index a0f00bc340..5aca6ed66b 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -75,4 +75,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..ecb1107d4c --- /dev/null +++ b/docs/system/devices/vhost-user.rst @@ -0,0 +1,57 @@ +.. _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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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. The daemon +will open a socket and *listen* for a connection from QEMU at which +point the protocol will start its negotiation. + +Shared memory object +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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`` object. A reference to a +file-descriptor which can access this object will be passed via the +socket as part of the protocol negotiation. + +Example +=3D=3D=3D=3D=3D=3D=3D + +First start you daemon. + +.. parsed-literal:: + + $ virtio-foo --socket-path=3D/var/run/foo.sock $OTHER_ARGS + +The you start your QEMU instance specifying the device, chardev and +memory objects. + +.. parsed-literal:: + + $ |qemu_system| \\ + -chardev socket,id=3Dba1,path=3D/var/run/foo.sock \\ + -device vhost-user-foo,chardev=3Dba1,$OTHER_ARGS \\ + -object memory-backend-memfd,id=3Dmem,size=3D4G,share=3Don \\ + -numa node,memdev=3Dmem \\ + ... + --=20 2.20.1