From nobody Sun Sep 28 16:34:03 2025 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=1756831914; cv=none; d=zohomail.com; s=zohoarc; b=HE+uaZlfePLDKUcqx+NRC9Cmn0/z5yPEs3x7kZDs5ITSz0L1Vw6iAp3txVKDEUOvC6o0GRYMa2NTii9S+VxY8w9tpZYRvbksnhsb8vcA/qDODlYj4/uIs/a8uSN606n+q5IOQNWiFhB2x5Sic8ayRjAxDiFrW1jPA2JUBeQbOaU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1756831914; h=Content-Type: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=JPTO+LPEzNEOE+7bSlvoPAbn0JAQ047SagKkIcn3yp8=; b=AV+s0H3LB8VbBsi5a0fOYfsQLGapZwy5DthAcxFIWhY80lGmkHw9dxo2uWNQhzq9/zokPYyAWJA/SVJqHc61Md25xIkS/lYUyzqmalYsPzfsSS8UGfE45qpSq2AW8BunlgfploAMrDjVhrPI379PXCQENMtoyofkbDf/xeu+MTg= 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 1756831914478480.4837609089599; Tue, 2 Sep 2025 09:51:54 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1utUDi-0008G9-Ji; Tue, 02 Sep 2025 12:50:58 -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 1utUDh-0008Ff-0V for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:57 -0400 Received: from mail-ed1-x533.google.com ([2a00:1450:4864:20::533]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1utUDe-0004QI-LF for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:56 -0400 Received: by mail-ed1-x533.google.com with SMTP id 4fb4d7f45d1cf-61cebce2f78so10440327a12.1 for ; Tue, 02 Sep 2025 09:50:54 -0700 (PDT) Received: from draig.lan ([185.126.160.19]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-61cfc4bbbd1sm9960037a12.34.2025.09.02.09.50.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Sep 2025 09:50:49 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id B7D005F8D7; Tue, 02 Sep 2025 17:50:48 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1756831853; x=1757436653; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=JPTO+LPEzNEOE+7bSlvoPAbn0JAQ047SagKkIcn3yp8=; b=NBF5SrxPYZ3w6asH9XjlyepbioiuVhF8KtO7XhjClfie4LgZ4lQvhdNwic7swjRBXn HfdCt9H39+oBkQryXPqrLZDuuiHPEsoRIkoIHJirl1p2IwE2Yh3F0l/4phhpMMB9FzfG BzhmmcuvYy+CFChIzNgUHs+PhErua3c+GioUTvnnwrYw0dkso0WzN94fFtTcC63i6cSi +3caGi/c6/3K54jH5BslrHdhBCnpdg/q3t2e5JA/RgSFc2jpgReJIiiZrEwvFbRL+Zt7 XpwtFowsn4eBjEh7u7fZ/LaCTxbyzQFKpS5NbarodCj1SZ0Tm2o9mzoXsePGthtk8atM BbLQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1756831853; x=1757436653; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=JPTO+LPEzNEOE+7bSlvoPAbn0JAQ047SagKkIcn3yp8=; b=paYKxx7ezzfDJ4zO7FkzyuKtmgxxSzkA1MhoJNTdBQdtUbqkX8w6FxzlvPxRzAqPby xlF773M6udKd9qwpqT6DPZxAro/ppGCshVsFRy9KJNE+/D5dSH+pS7najOW4tWX47Qhv HlLI7TDz9BId0MezEhcCM3gX1zX2Z2PkLP0v7/DLZqrHcIzBNvMCGAKN3h+yiAuvCB4G 8ceIM9VXxN8EjpS2VswxD6YYxIeh8sfKR7y3JR5IGOIF4s3ntymfNA51GdiOTwdDMG4p N/P9GLOH2njkPr4NEDcvUzWChw+G4BZ9h0E5HtS8q8vP+RpdQVYAo54OqYHqs030Vxbo lZbw== X-Gm-Message-State: AOJu0Yz3Nk4OUiy10dYGPM3ZGNjK2bmEww4rKJ3Si6cCN+QLDZg7jG9r RrIU8BXXzVhcin9Rjq4/5i35qKt/1bvM/0gRt3oRFy7OIL6yrimr4ydoBLvUyi9k1ME= X-Gm-Gg: ASbGnctIEoYTnNmE46Hg7bmCY6oBlPv673ZHwvNUVdkrhxi5yxxRG86t2fO/lhduNVu ffWLMIsysrVblN0f7jp5szxXBVdBG77Y4QR//22H5INJsv5OoRA+EvRTJM8iRZELRYWFLDxQ7ZY NGOeL4A5rikRC6iSzORa9/djhuD1LO8M7hR8p1LyZs+evU/cy1//a4EDLxQJHy9qvHqLyYRkqSD z1vk9359F76GlKIsWB5bnCoF3+cBR9FEp73TmKh7kP33eBwCxEKrTyyp7wCwEH0ReI9fe54TD9A PYFYU2DMAiTTST3AOzd1yqPf3wY+Oki6J/htyR2qQ8VYUokFP8EUumpQlOD40X04mgaJ6Pzh6Wh XKwgpYUkjWURkF4q0dhTKh3c= X-Google-Smtp-Source: AGHT+IHtnqw/QdjhejWTIrkOri4pNOQ9Curwu5/znzs8bCP0KcSCwiDucG8nA2vpfxOKZeNwX8XMbA== X-Received: by 2002:a05:6402:34d0:b0:61e:92a2:351e with SMTP id 4fb4d7f45d1cf-61e92a23870mr6927763a12.37.1756831852843; Tue, 02 Sep 2025 09:50:52 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Thanos Makatos , John Levon , =?UTF-8?q?Alex=20Benn=C3=A9e?= Subject: [PATCH 1/4] docs/system: split VirtIO devices from the rest Date: Tue, 2 Sep 2025 17:50:45 +0100 Message-ID: <20250902165048.1653323-2-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250902165048.1653323-1-alex.bennee@linaro.org> References: <20250902165048.1653323-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::533; envelope-from=alex.bennee@linaro.org; helo=mail-ed1-x533.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.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 @linaro.org) X-ZM-MESSAGEID: 1756831916670116600 In an effort to tidy up our device documentation split the VirtIO docs from the rest of the index and put the index to them at the front of the list. Sort the remaining entries alphabetically and tweak the references appropriately. Add a short preface to the VirtIO section nudging users to use VirtIO unless they specifically want a particular piece of hardware emulation. Signed-off-by: Alex Benn=C3=A9e Reviewed-by: John Levon Reviewed-by: Manos Pitsidianakis --- docs/system/device-emulation.rst | 18 +++++------ docs/system/devices/vfio-user.rst | 2 +- docs/system/devices/virtio/index.rst | 30 +++++++++++++++++++ .../devices/{ =3D> virtio}/vhost-user-input.rst | 0 .../devices/{ =3D> virtio}/vhost-user-rng.rst | 0 .../devices/{ =3D> virtio}/vhost-user.rst | 0 .../devices/{ =3D> virtio}/virtio-gpu.rst | 0 .../devices/{ =3D> virtio}/virtio-pmem.rst | 0 .../devices/{ =3D> virtio}/virtio-snd.rst | 0 9 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 docs/system/devices/virtio/index.rst rename docs/system/devices/{ =3D> virtio}/vhost-user-input.rst (100%) rename docs/system/devices/{ =3D> virtio}/vhost-user-rng.rst (100%) rename docs/system/devices/{ =3D> virtio}/vhost-user.rst (100%) rename docs/system/devices/{ =3D> virtio}/virtio-gpu.rst (100%) rename docs/system/devices/{ =3D> virtio}/virtio-pmem.rst (100%) rename docs/system/devices/{ =3D> virtio}/virtio-snd.rst (100%) diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulatio= n.rst index 911381643f1..db714ad47aa 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -82,22 +82,18 @@ Emulated Devices .. toctree:: :maxdepth: 1 =20 + devices/virtio/index.rst + devices/can.rst + devices/canokey.rst devices/ccid.rst devices/cxl.rst - devices/vfio-user.rst - devices/ivshmem.rst + devices/igb.rst devices/ivshmem-flat.rst + devices/ivshmem.rst devices/keyboard.rst devices/net.rst devices/nvme.rst - devices/usb.rst - devices/vhost-user.rst - devices/virtio-gpu.rst - devices/virtio-pmem.rst - devices/virtio-snd.rst - devices/vhost-user-input.rst - devices/vhost-user-rng.rst - devices/canokey.rst devices/usb-u2f.rst - devices/igb.rst + devices/usb.rst + devices/vfio-user.rst diff --git a/docs/system/devices/vfio-user.rst b/docs/system/devices/vfio-u= ser.rst index b6dcaa5615e..30c2215f4ea 100644 --- a/docs/system/devices/vfio-user.rst +++ b/docs/system/devices/vfio-user.rst @@ -6,7 +6,7 @@ vfio-user =20 QEMU includes a ``vfio-user`` client. The ``vfio-user`` specification allo= ws for implementing (PCI) devices in userspace outside of QEMU; it is similar to -``vhost-user`` in this respect (see :doc:`vhost-user`), but can emulate ar= bitrary +``vhost-user`` in this respect (see :doc:`virtio/vhost-user`), but can emu= late arbitrary PCI devices, not just ``virtio``. Whereas ``vfio`` is handled by the host kernel, ``vfio-user``, while similar in implementation, is handled entirel= y in userspace. diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/vir= tio/index.rst new file mode 100644 index 00000000000..bb44b14423e --- /dev/null +++ b/docs/system/devices/virtio/index.rst @@ -0,0 +1,30 @@ +VirtIO Devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +VirtIO devices are paravirtualized devices designed to be efficient to +emulate and virtualize. Unless you are specifically trying to exercise +a driver for some particular hardware they are the recommend device +models to use for virtual machines. + +The `VirtIO specification`_ is an open standard managed by OASIS. It +describes how a *driver* in a guest operating system interacts with +the *device* model provided by QEMU. Multiple Operating Systems +support drivers for VirtIO with Linux perhaps having the widest range +of device types supported. + +The device implementation can either be provided wholly by QEMU, or in +concert with the kernel (known as *vhost*). The device implementation +can also be off-loaded to an external process via :ref:`vhost user +`. + +.. toctree:: + :maxdepth: 1 + + virtio-gpu.rst + virtio-pmem.rst + virtio-snd.rst + vhost-user.rst + vhost-user-input.rst + vhost-user-rng.rst + +.. _VirtIO specification: https://docs.oasis-open.org/virtio/virtio/v1.3/v= irtio-v1.3.html diff --git a/docs/system/devices/vhost-user-input.rst b/docs/system/devices= /virtio/vhost-user-input.rst similarity index 100% rename from docs/system/devices/vhost-user-input.rst rename to docs/system/devices/virtio/vhost-user-input.rst diff --git a/docs/system/devices/vhost-user-rng.rst b/docs/system/devices/v= irtio/vhost-user-rng.rst similarity index 100% rename from docs/system/devices/vhost-user-rng.rst rename to docs/system/devices/virtio/vhost-user-rng.rst diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/virti= o/vhost-user.rst similarity index 100% rename from docs/system/devices/vhost-user.rst rename to docs/system/devices/virtio/vhost-user.rst diff --git a/docs/system/devices/virtio-gpu.rst b/docs/system/devices/virti= o/virtio-gpu.rst similarity index 100% rename from docs/system/devices/virtio-gpu.rst rename to docs/system/devices/virtio/virtio-gpu.rst diff --git a/docs/system/devices/virtio-pmem.rst b/docs/system/devices/virt= io/virtio-pmem.rst similarity index 100% rename from docs/system/devices/virtio-pmem.rst rename to docs/system/devices/virtio/virtio-pmem.rst diff --git a/docs/system/devices/virtio-snd.rst b/docs/system/devices/virti= o/virtio-snd.rst similarity index 100% rename from docs/system/devices/virtio-snd.rst rename to docs/system/devices/virtio/virtio-snd.rst --=20 2.47.2 From nobody Sun Sep 28 16:34:03 2025 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=1756831899; cv=none; d=zohomail.com; s=zohoarc; b=XqI+8MgiKvZlPRMYhUWHfmB9loyy41VMhfRZF5r0aMdvVFkYQPHB3EO8sj3lb8SottAnEm3sdOnqc2/0ne70moNl70TPuIzEZ0zI4Yzymfe+Cnc3l8NkIcr19TMJ8b7KAT7R51AdtWiC/bO0IDvKplSRWb07gdSaa87W/Lo0E4Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1756831899; h=Content-Type: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=BrVjWsHcZyingugi7ctu2XV6MLij18kQAJ1wqTXEpSY=; b=HDDkCL4qhFSldD5h1EA7JCRt3EjaWF4lQGnTBK1NVWcui9tPbFH1N03UVXNk1CjGbNKuAo1206eFOUPvwNGIbmIwb4a4Idzec2bsv7B8/udh+G1iLlMP8Y42Q6t4HYoGOiskm6CCf/a9lBjxuyhAKpF7wmAB593v7+cxg6hHgcw= 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 1756831899208335.2479890674949; Tue, 2 Sep 2025 09:51:39 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1utUDf-0008Ey-Mz; Tue, 02 Sep 2025 12:50:55 -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 1utUDe-0008E7-5I for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:54 -0400 Received: from mail-ej1-x62d.google.com ([2a00:1450:4864:20::62d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1utUDc-0004PO-DG for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:53 -0400 Received: by mail-ej1-x62d.google.com with SMTP id a640c23a62f3a-b0449b1b56eso201125166b.1 for ; Tue, 02 Sep 2025 09:50:51 -0700 (PDT) Received: from draig.lan ([185.126.160.19]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b0420a16c32sm624240866b.94.2025.09.02.09.50.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Sep 2025 09:50:49 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id D0C1B5F8D8; Tue, 02 Sep 2025 17:50:48 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1756831850; x=1757436650; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=BrVjWsHcZyingugi7ctu2XV6MLij18kQAJ1wqTXEpSY=; b=Q3xuiQKLQzcPuXotfKoE3v3OJZkcAZiVvcHsK8amhD3uUAL5Mrsb2nLK1vNlxkL5ZI KgFTirI5DINOXc7RHJOLygXLarEBfNLll7L2EadzgyaPgUvAY1alVzHYrgDBeI/dXI20 sircMSYpEAeZN7t30DuqMNplc78O1+HDUr36DQEjJRFzfZtXqU/7maULGt6GwBSoZFKK iWNaZbS1zzqTjyK5mPIR/quoDGBU2qvXnR5rzHgTBPU/KuAf6JFOjwTvLlF3DIDJQBLh NEZFqzIq1ow+zG5IV2atT+aaQVV+K8p4P4l/9SDAZTnjg3PPu7LeonrDqOXaetkCwScG Na5w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1756831850; x=1757436650; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=BrVjWsHcZyingugi7ctu2XV6MLij18kQAJ1wqTXEpSY=; b=DPt4YiYU8nBQyG0+HQkfSXPV42QsiFt09vIQ0v4VDbvra1QytxaUH+xKFiexIQIG2e HrYiuO8eX9tq1NWL+OtzD9dvVxH1LBTly5SwRiI0jDTWbYMlH9cWX6Cu1Lrjs1iN5IfD m9GGShIjDtUfdaIrSkhDdTkEESak4EBMXzggi4QviUZjusapdjiPv6iLrXravskZ8QjI 5pS/6r42GsFQbxLvxgdP0nlP4L0MhC9HLmCyyaRZOB22rW2LkTMRMNfz87roLDIYHOUB 4LrQhTmIRKyqmDYXoLK3UaqMFVGusL1qlNjS1O7e+ODbavvwrdUirZvq6ts5GU4QyuCX rjWQ== X-Gm-Message-State: AOJu0Ywz5EX3xUhFYgnDJAF3jm4bZWfFSPhplPap3BD6gXxlHMUNr6bD SRlLTovbx2UL1azqbTSIrQOLJ4vTZ0W01RBXtgJqosUb6p12iFamBo2GbzqV12aHxO8= X-Gm-Gg: ASbGncvkHw8gcgFOraqtDDnAek+Sf4G/M/lv3sFEMjzwksnzvnzlwlWz10sYfEevQzB N9O1yy/OxuIS+PooPuRZvOkw2aHQUkTVkoFPoPMD0XhmSKt0mPlzDlWkFSAxjTVmP70Q7Z/p7WM Temz40UYAgGUjIRb7is6CSdF5J/PuoxpG8ErPTshP4u28w9K1yXNTPvAlwkc183Imn0Q1Wn0FL8 WLIM7QBvIo/eZch/IF4M/mQvKQ+KTZjbhEvLuaPkD3E+0vZ7UZzIluGX4+smyZFv/J3FSCDmHzy IcSaEyCJJ6qts2tPFCDgJSyONQmMOATjKA2pkIvGp7r4HD+Q9mYFonMzH7ZHTGko3nBGtDfQ3/o WsBgMjWUBTVTXKHEu6eATKpjwqEUpE6EuFw== X-Google-Smtp-Source: AGHT+IEeJxb8P67X8byzzu7f7TFVuVXRh5jN2TohRy1M0QtxrvsUlbJ3XKN1eTbeHz06pKr96Exj7Q== X-Received: by 2002:a17:906:9f90:b0:afe:d1cb:6327 with SMTP id a640c23a62f3a-b01d976c577mr1262831866b.48.1756831850326; Tue, 02 Sep 2025 09:50:50 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Thanos Makatos , John Levon , =?UTF-8?q?Alex=20Benn=C3=A9e?= Subject: [PATCH 2/4] docs/system: unify the naming style for VirtIO devices Date: Tue, 2 Sep 2025 17:50:46 +0100 Message-ID: <20250902165048.1653323-3-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250902165048.1653323-1-alex.bennee@linaro.org> References: <20250902165048.1653323-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::62d; envelope-from=alex.bennee@linaro.org; helo=mail-ej1-x62d.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.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 @linaro.org) X-ZM-MESSAGEID: 1756831900815124100 This makes the index look a little neater. Signed-off-by: Alex Benn=C3=A9e Reviewed-by: John Levon --- docs/system/devices/virtio/virtio-gpu.rst | 2 +- docs/system/devices/virtio/virtio-pmem.rst | 6 ++---- docs/system/devices/virtio/virtio-snd.rst | 2 +- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/system/devices/virtio/virtio-gpu.rst b/docs/system/device= s/virtio/virtio-gpu.rst index b7eb0fc0e72..39d2fd2d21c 100644 --- a/docs/system/devices/virtio/virtio-gpu.rst +++ b/docs/system/devices/virtio/virtio-gpu.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0-or-later =20 -virtio-gpu +VirtIO GPU =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 This document explains the setup and usage of the virtio-gpu device. diff --git a/docs/system/devices/virtio/virtio-pmem.rst b/docs/system/devic= es/virtio/virtio-pmem.rst index c82ac067315..0c24de83ec7 100644 --- a/docs/system/devices/virtio/virtio-pmem.rst +++ b/docs/system/devices/virtio/virtio-pmem.rst @@ -1,7 +1,5 @@ - -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -virtio pmem -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +VirtIO Persistent Memory +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 This document explains the setup and usage of the virtio pmem device. The virtio pmem device is a paravirtualized persistent memory device diff --git a/docs/system/devices/virtio/virtio-snd.rst b/docs/system/device= s/virtio/virtio-snd.rst index 2a9187fd701..3c797f66e03 100644 --- a/docs/system/devices/virtio/virtio-snd.rst +++ b/docs/system/devices/virtio/virtio-snd.rst @@ -1,4 +1,4 @@ -virtio sound +VirtIO Sound =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 This document explains the setup and usage of the Virtio sound device. --=20 2.47.2 From nobody Sun Sep 28 16:34:03 2025 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=1756831914; cv=none; d=zohomail.com; s=zohoarc; b=PShP+YcGiTtjbJ3DsVxjmZs9jNn7oczqMMIJCdHmdaM4KqzqeLbmB9HI11QF+IEGqBQDYCIFu5s8NUJo2R7f3wsx4UoHhyqx/azTCjgAcQyi96lbJTEPkcKtTGKxBcWdkkJG1VzST7Yw5TvijseVhz/FF5NZ5WrTlYLfBFoMulc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1756831914; h=Content-Type: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=gjXCcr5SxY559gyNm3UTAVjtJgfAK9rwGGuds/G0kqg=; b=agBqpFMjJXXPI3GFThezD3Mn9pPc+E6JSPV8JvixjNt1a6gKqtyCS4XJP1nCa2zq0nkSFNgX2WyQ+5WQCX48lKAHZTxB5VYmMpnCZGHMf5A03cv9qKseeKcMZFNPJnkHf7iRaTHjAN3o/b11H/DxYRj5xo9MRvI3xyHXHXxkCa8= 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 1756831914117772.0904397492847; Tue, 2 Sep 2025 09:51:54 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1utUDi-0008G0-Fw; Tue, 02 Sep 2025 12:50:58 -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 1utUDg-0008F2-M5 for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:56 -0400 Received: from mail-ed1-x52e.google.com ([2a00:1450:4864:20::52e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1utUDd-0004Q1-Rj for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:55 -0400 Received: by mail-ed1-x52e.google.com with SMTP id 4fb4d7f45d1cf-6188b7550c0so6821999a12.2 for ; Tue, 02 Sep 2025 09:50:53 -0700 (PDT) Received: from draig.lan ([185.126.160.19]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-61cfc1c7a27sm10059861a12.10.2025.09.02.09.50.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Sep 2025 09:50:49 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id E618A5F8DC; Tue, 02 Sep 2025 17:50:48 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1756831852; x=1757436652; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=gjXCcr5SxY559gyNm3UTAVjtJgfAK9rwGGuds/G0kqg=; b=u2zdlewFuU7CfCt4Rj8lYbkfotr3IurGdYNmFUMVBH7OdVP7P4BeePIau+x6yJRWlC /G/qRYsUi+oXbZMUvxBHdG/UcnKeNeExk8ocOqd6t8yLtsYTyrZEK6F74UKifT094rrY FA4ntRqldjfAa+n5arZCKywY2HTZv7nIVhZUXag8w99MptPzPqnrduq8mobYA3g3Bd8+ veUQyLJG7j5NmdT328SSc8YauhO2Ba9sfHBCiBkLm4KR0SXDyvG+wqThY2BH31VjSkzu dqrWTQKF0EIIXeDI6Tl2Ya1374+Ne5wsOZsaWg+qRIBBHr9KHOJHHyAabSR4RY1vLUWB 9DdQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1756831852; x=1757436652; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=gjXCcr5SxY559gyNm3UTAVjtJgfAK9rwGGuds/G0kqg=; b=YoDh4zvwfo9NY392ZrixMObSTOD5CecTfb+JVTwmJoKlEXJcOfCu6BaEc5uopqJsdn SBkBkEFYiZqh035corFmATHAwvGCKbwmGitsZCvVXTNpoJ6JpEmHVrwMOSihFXHBvSZi ZWpbXY3EqbqLwjwTHRjaeXQ1yKkefRs928Kj6lS2G1/DAeE8Du/FhJYV708RgRFFAIBu Ob2bWV+nL+xc7ax5m/cw7pQE7aQBG8Ho+/Ui/YTeZJYouEN3oM4lCTlhzC/vFHGq8xFk h7g5x5gMpoyLmHL7MJto1AHIin8/SOROTdACdQMzVXiMIJgiDkf5FbGZCvGgXg8y9pKG ZkHQ== X-Gm-Message-State: AOJu0YxkfN5IHX4ZNMyPsl1VR4JaVNF900VsD2CEqrFpewI87qWpQY0I ltkHOjn4i0B/18Q5G1ViBT0rpRwRZCfifo3Gjqsb8CM4j6Ej98rEDYgleh4q1gJXVBo= X-Gm-Gg: ASbGnctV3El1Hd+jdfCyMt6aDZDVbaM9GBpKwQ8O9x7mqOZCaCrLJOZHYtkZgrGOw4N hKze6c4roKFPY8JTR0gEBeN7rsjrIJ+HJNBckfeuTdd4MEXcm2S1KUJ2T8M8EV1O5/VU54J4etF 5EsWx10vwnRdixhtuSRnAoCueEPQU/kYz/daNiSA2lfpJvhq8NZxd4swtLwyVK0PWZApU2JU/si mG421T6lqNwzBnFjcNm4O/IsHt23jwt8PaQxJSsA5EfwNYr7fYv6jw1WaB6PeaOfDhfoquwN23B 7+57R5KIw+/OtieYeKdQXUteSfgFEfqS8UK7x7zw4JxCeU9bnbEUEA/KJlWZTJ0NhAWH1PKB+Mb Hfi/G2JAYnwepOHbOs/hTCQpIiYf41mrFXQ== X-Google-Smtp-Source: AGHT+IGOWt+NRiEMdKqSQlZDyXZvX9DyYW6Kaunul6gvZvz4hzTLGgTUuOGkHtj4o9YgUkZukTY44g== X-Received: by 2002:a05:6402:90c:b0:61c:61bb:e836 with SMTP id 4fb4d7f45d1cf-61d26988ecdmr9711708a12.11.1756831852056; Tue, 02 Sep 2025 09:50:52 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Thanos Makatos , John Levon , =?UTF-8?q?Alex=20Benn=C3=A9e?= Subject: [PATCH 3/4] docs/system: drop vhost-user-rng docs Date: Tue, 2 Sep 2025 17:50:47 +0100 Message-ID: <20250902165048.1653323-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250902165048.1653323-1-alex.bennee@linaro.org> References: <20250902165048.1653323-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::52e; envelope-from=alex.bennee@linaro.org; helo=mail-ed1-x52e.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.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 @linaro.org) X-ZM-MESSAGEID: 1756831914648116600 This is a fairly lightweight document which doesn't add much to the general advice in vhost-user. Update the vhost-user docs to point directly at the rust-vmm repo. Signed-off-by: Alex Benn=C3=A9e Reviewed-by: John Levon --- docs/system/devices/virtio/index.rst | 1 - docs/system/devices/virtio/vhost-user-rng.rst | 41 ------------------- docs/system/devices/virtio/vhost-user.rst | 2 +- 3 files changed, 1 insertion(+), 43 deletions(-) delete mode 100644 docs/system/devices/virtio/vhost-user-rng.rst diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/vir= tio/index.rst index bb44b14423e..7f931737cc1 100644 --- a/docs/system/devices/virtio/index.rst +++ b/docs/system/devices/virtio/index.rst @@ -25,6 +25,5 @@ can also be off-loaded to an external process via :ref:`v= host user virtio-snd.rst vhost-user.rst vhost-user-input.rst - vhost-user-rng.rst =20 .. _VirtIO specification: https://docs.oasis-open.org/virtio/virtio/v1.3/v= irtio-v1.3.html diff --git a/docs/system/devices/virtio/vhost-user-rng.rst b/docs/system/de= vices/virtio/vhost-user-rng.rst deleted file mode 100644 index ead14053264..00000000000 --- a/docs/system/devices/virtio/vhost-user-rng.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _vhost_user_rng: - -QEMU vhost-user-rng - RNG emulation -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Background ----------- - -What follows builds on the material presented in vhost-user.rst - it should -be reviewed before moving forward with the content in this file. - -Description ------------ - -The vhost-user-rng device implementation was designed to work with a random -number generator daemon such as the one found in the vhost-device crate of -the rust-vmm project available on github [1]. - -[1]. https://github.com/rust-vmm/vhost-device - -Examples --------- - -The daemon should be started first: - -:: - - host# vhost-device-rng --socket-path=3Drng.sock -c 1 -m 512 -p 1000 - -The QEMU invocation needs to create a chardev socket the device can -use to communicate as well as share the guests memory over a memfd. - -:: - - host# qemu-system \ - -chardev socket,path=3D$(PATH)/rng.sock,id=3Drng0 \ - -device vhost-user-rng-pci,chardev=3Drng0 \ - -m 4096 \ - -object memory-backend-file,id=3Dmem,size=3D4G,mem-path=3D/dev/shm,s= hare=3Don \ - -numa node,memdev=3Dmem \ - ... diff --git a/docs/system/devices/virtio/vhost-user.rst b/docs/system/device= s/virtio/vhost-user.rst index bddf8df5ed5..9c9a28df380 100644 --- a/docs/system/devices/virtio/vhost-user.rst +++ b/docs/system/devices/virtio/vhost-user.rst @@ -45,7 +45,7 @@ platform details for what sort of virtio bus to use. - :ref:`vhost_user_input` * - vhost-user-rng - Entropy driver - - :ref:`vhost_user_rng` + - See https://github.com/rust-vmm/vhost-device * - vhost-user-scmi - System Control and Management Interface - See https://github.com/rust-vmm/vhost-device --=20 2.47.2 From nobody Sun Sep 28 16:34:03 2025 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=1756831878; cv=none; d=zohomail.com; s=zohoarc; b=BnhhJLcXbxYm97sQQrD2EtXy3PuiWL0qmSNU+eIdKqnKpXSwQQf7Mx2sGkNRAX0NsAK+RdFoV5fkY4Ie0+Ykdkcvsutz4tb0Cm2xjzajE8gRbHr7AESvCygKWiopX+RJe0pgNzCf13VGbUsPkrNqSKACgYktYUMsrD9kuLZcV18= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1756831878; h=Content-Type: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=WT25vLnlnlxahwzUq/9pnYWfOU5FHn9MQChZKROLaP8=; b=SEsCHcWjOedu9zxkJGOOvKR9F7BPWBtalAS98TmYa7t+1E0/7l5JuUeDagNr2mAmMw8CXFS2UdYUPPeJUvQa2oddjr4vvpA3SvUYSnCU71k3nmnT8UfPPXaodxNXCelUt0GhYWkvrsIlOuX6cHfCEGjdQm5ERhboXRqt0IuokgQ= 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 1756831878485200.24538911796594; Tue, 2 Sep 2025 09:51:18 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1utUDl-0008HF-9v; Tue, 02 Sep 2025 12:51:01 -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 1utUDh-0008Fp-VG for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:57 -0400 Received: from mail-ej1-x62b.google.com ([2a00:1450:4864:20::62b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1utUDf-0004Qi-CI for qemu-devel@nongnu.org; Tue, 02 Sep 2025 12:50:57 -0400 Received: by mail-ej1-x62b.google.com with SMTP id a640c23a62f3a-b0431c12df3so343053566b.1 for ; Tue, 02 Sep 2025 09:50:54 -0700 (PDT) Received: from draig.lan ([185.126.160.19]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b04190700a4sm696958166b.63.2025.09.02.09.50.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Sep 2025 09:50:50 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 0F3955F8DF; Tue, 02 Sep 2025 17:50:49 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1756831854; x=1757436654; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=WT25vLnlnlxahwzUq/9pnYWfOU5FHn9MQChZKROLaP8=; b=qKyu9e68K50/XMqNqfWHdE8q4JmvBqt851lTrO+ItA4jOsH1rB2/IAQjWdtkK3459a KQe/eNPQAG39vAaxnhX2B8I8R/i5BAQ5IsQoWukq4fby0Sbzee3L12rJAJIlwoIlGmN4 MKYjKCmbqOKCQRS15YzmZaqFvz4r2LnzWwPa0MIvxAlG30XgRCpwLP50V5KcXJoPKf4C sumOxAHHMH0KVm2NcOrawk8Rezsmb6JzSSD22mjo4CXRhW6XdHcniHl+VThvT0MqVQCl QWtctpyJwKbnSQYloB8KTXmtHoWwKbrOKMRGIdzz0azS46fL+GC2eE0gVzxrzd+g/lF4 7Q6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1756831854; x=1757436654; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=WT25vLnlnlxahwzUq/9pnYWfOU5FHn9MQChZKROLaP8=; b=tx7nnmverkK0so/QWSPano+1wpJ/VxhJ0t5kKxP6DWIuFY/phDK0xnRnCJ5mbS9l3b KtPfVB9FVpkl7BVEFz/v8zeTdmk5ZNOSEDaymRCyd6rnS9TSkgfVS7rp9hq2vBzYygOE VEvKVplVgWtH3da7FGCb/Y1a7dtM5Y55TlppWQXA4Zu30P8xhF+aB7hAQqUkunV4DubF hPfEBbU6PiFjaRBl7NoCaD/sMPj+M4bK1S1ew1K9ahJEDfq9DMZQAc2qlMBzlrrRYYUJ jlC99We22EiCQspigCbvPVQPhptgLYLAsC699zaHcNFDmEt2IQkwYWW2UOzOovXLTnnT T08g== X-Gm-Message-State: AOJu0YwREpI/OZ2gwP3sM9GrfGcr/n+Fia+7ziKjBCfOXUWWETMcijSb CNVuKA03OhdAjywkVaqlH1Xf4zFUB282LayQwH75V0KFw5PUWs/Kr3rUjDJ48tfsutA= X-Gm-Gg: ASbGncv7MSRynApcHE79XIcBbP2vmbJRfHjVI4iwwP/HkBL4xx1wH28LgWNlwsxAeOc 9XqIlUR0P46dZKBB7JAfCFLiQ+8emI66/kXINWrOjYwfIozXYb/Ip8U7Vo8gLTq0JQU1Q4+YU3e RIchgsv8FeciCJJ2nQVCHr1eOdqDf1ietY1E02t5Qpx+pWGwLi4VCMjIIJdz/w3gGOQTFXvfPMR BLQaN64WzquFin24Yd8WkBQuMA7mphDFMod5FMzTZvmBbgZ2aW3MmilMHCFQ3sty6GXCN/wCaOx UkUX1burxD4WK0/UELhlV16kWScF0WWBbYk8htMDD3xI8l7M5MpoW7FuFjsForef+a0iKipO2kM 8KFvjiXUEOXLmncXuppE4LBw= X-Google-Smtp-Source: AGHT+IEAcrNNsRTK0Ud485h0nhmLpFHTDruH1qnwukJVPGEW6I3805c9yKqwj93H0gGDERiMjcXNPw== X-Received: by 2002:a17:906:4786:b0:afe:e7f1:28a2 with SMTP id a640c23a62f3a-b01d8c7835emr1281760466b.23.1756831853581; Tue, 02 Sep 2025 09:50:53 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Thanos Makatos , John Levon , =?UTF-8?q?Alex=20Benn=C3=A9e?= Subject: [PATCH 4/4] docs/system: merge vhost-user-input into vhost-user-contrib Date: Tue, 2 Sep 2025 17:50:48 +0100 Message-ID: <20250902165048.1653323-5-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250902165048.1653323-1-alex.bennee@linaro.org> References: <20250902165048.1653323-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::62b; envelope-from=alex.bennee@linaro.org; helo=mail-ej1-x62b.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.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 @linaro.org) X-ZM-MESSAGEID: 1756831880867124100 We might as well group all the contrib submissions together and gently dissuade people from using them in production. Update the references in vhost-user to neatly refer to the storage daemon and the various external rust backends. Signed-off-by: Alex Benn=C3=A9e Reviewed-by: Manos Pitsidianakis --- docs/system/devices/virtio/index.rst | 2 +- .../devices/virtio/vhost-user-contrib.rst | 87 +++++++++++++++++++ .../devices/virtio/vhost-user-input.rst | 45 ---------- docs/system/devices/virtio/vhost-user.rst | 22 ++--- docs/system/devices/virtio/virtio-gpu.rst | 2 + 5 files changed, 101 insertions(+), 57 deletions(-) create mode 100644 docs/system/devices/virtio/vhost-user-contrib.rst delete mode 100644 docs/system/devices/virtio/vhost-user-input.rst diff --git a/docs/system/devices/virtio/index.rst b/docs/system/devices/vir= tio/index.rst index 7f931737cc1..04588fa78ab 100644 --- a/docs/system/devices/virtio/index.rst +++ b/docs/system/devices/virtio/index.rst @@ -24,6 +24,6 @@ can also be off-loaded to an external process via :ref:`v= host user virtio-pmem.rst virtio-snd.rst vhost-user.rst - vhost-user-input.rst + vhost-user-contrib.rst =20 .. _VirtIO specification: https://docs.oasis-open.org/virtio/virtio/v1.3/v= irtio-v1.3.html diff --git a/docs/system/devices/virtio/vhost-user-contrib.rst b/docs/syste= m/devices/virtio/vhost-user-contrib.rst new file mode 100644 index 00000000000..10a92c19e82 --- /dev/null +++ b/docs/system/devices/virtio/vhost-user-contrib.rst @@ -0,0 +1,87 @@ +vhost-user daemons in contrib +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +QEMU provides a number of :ref:`vhost_user` daemons in the contrib +directory. They were often written when vhost-user was initially added +to the code base. You should also consider if other vhost-user daemons +such as those from the rust-vmm `vhost-device repository`_ are better +suited for production use. + +.. _vhost-device repository: https://github.com/rust-vmm/vhost-device + +.. _vhost_user_block: + +vhost-user-block - block device +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +vhost-user-block is a backed for exposing block devices. It can +present a flat file or block device as a simple block device to the +guest. You almost certainly want to use the :ref:`storage-daemon` +instead which supports the wide variety of storage modes and exports a +number of interfaces include vhost-user. + +.. _vhost_user_gpu: + +vhost-user-gpu - gpu device +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +vhost-user-gpu presents a paravirtualized GPU and display controller. +You probably want to use the internal :ref:`virtio_gpu` implementation +if you want the latest features. There is also a `vhost_device_gpu`_ +daemon as part of the rust-vmm project. + +.. _vhost_device_gpu: https://github.com/rust-vmm/vhost-device/tree/main/v= host-device-gpu + +.. _vhost_user_input: + +vhost-user-input - Input emulation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The Virtio input device is a paravirtualized device for input events. + +Description +----------- + +The vhost-user-input device implementation was designed to work with a dae= mon +polling on input devices and passes input events to the guest. + +QEMU provides a backend implementation in contrib/vhost-user-input. + +Linux kernel support +-------------------- + +Virtio input requires a guest Linux kernel built with the +``CONFIG_VIRTIO_INPUT`` option. + +Examples +-------- + +The backend daemon should be started first: + +:: + + host# vhost-user-input --socket-path=3Dinput.sock \ + --evdev-path=3D/dev/input/event17 + +The QEMU invocation needs to create a chardev socket to communicate with t= he +backend daemon and access the VirtIO queues with the guest over the +:ref:`shared memory `. + +:: + + host# qemu-system \ + -chardev socket,path=3D/tmp/input.sock,id=3Dmouse0 \ + -device vhost-user-input-pci,chardev=3Dmouse0 \ + -m 4096 \ + -object memory-backend-file,id=3Dmem,size=3D4G,mem-path=3D/dev/shm,s= hare=3Don \ + -numa node,memdev=3Dmem \ + ... + + +.. _vhost_user_scsi: + +vhost-user-scsi - SCSI controller +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D + +The vhost-user-scsi daemon can proxy iSCSI devices onto a virtualized +SCSI controller. diff --git a/docs/system/devices/virtio/vhost-user-input.rst b/docs/system/= devices/virtio/vhost-user-input.rst deleted file mode 100644 index 118eb78101c..00000000000 --- a/docs/system/devices/virtio/vhost-user-input.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _vhost_user_input: - -QEMU vhost-user-input - Input emulation -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -This document describes the setup and usage of the Virtio input device. -The Virtio input device is a paravirtualized device for input events. - -Description ------------ - -The vhost-user-input device implementation was designed to work with a dae= mon -polling on input devices and passes input events to the guest. - -QEMU provides a backend implementation in contrib/vhost-user-input. - -Linux kernel support --------------------- - -Virtio input requires a guest Linux kernel built with the -``CONFIG_VIRTIO_INPUT`` option. - -Examples --------- - -The backend daemon should be started first: - -:: - - host# vhost-user-input --socket-path=3Dinput.sock \ - --evdev-path=3D/dev/input/event17 - -The QEMU invocation needs to create a chardev socket to communicate with t= he -backend daemon and access the VirtIO queues with the guest over the -:ref:`shared memory `. - -:: - - host# qemu-system \ - -chardev socket,path=3D/tmp/input.sock,id=3Dmouse0 \ - -device vhost-user-input-pci,chardev=3Dmouse0 \ - -m 4096 \ - -object memory-backend-file,id=3Dmem,size=3D4G,mem-path=3D/dev/shm,s= hare=3Don \ - -numa node,memdev=3Dmem \ - ... diff --git a/docs/system/devices/virtio/vhost-user.rst b/docs/system/device= s/virtio/vhost-user.rst index 9c9a28df380..f556a840e99 100644 --- a/docs/system/devices/virtio/vhost-user.rst +++ b/docs/system/devices/virtio/vhost-user.rst @@ -27,37 +27,37 @@ platform details for what sort of virtio bus to use. - Notes * - vhost-user-blk - Block storage - - See contrib/vhost-user-blk + - :ref:`storage-daemon` * - vhost-user-fs - File based storage driver - - See https://gitlab.com/virtio-fs/virtiofsd + - `virtiofsd `_ * - vhost-user-gpio - Proxy gpio pins to host - - See https://github.com/rust-vmm/vhost-device + - `vhost-device-gpio `_ * - vhost-user-gpu - GPU driver - - See contrib/vhost-user-gpu + - `vhost-device-gpu `_ or :ref:`vhost_user_gpu` * - vhost-user-i2c - Proxy i2c devices to host - - See https://github.com/rust-vmm/vhost-device + - `vhost-device-i2c `_ * - vhost-user-input - Generic input driver - - :ref:`vhost_user_input` + - `vhost-device-input `_ or :ref:`vhost_user_input` * - vhost-user-rng - Entropy driver - - See https://github.com/rust-vmm/vhost-device + - `vhost-device-rng `_ * - vhost-user-scmi - System Control and Management Interface - - See https://github.com/rust-vmm/vhost-device + - `vhost-device-scmi `_ * - vhost-user-snd - Audio device - - See https://github.com/rust-vmm/vhost-device/staging + - `vhost-device-sound `_ * - vhost-user-scsi - SCSI based storage - - See contrib/vhost-user-scsi + - :ref:`vhost_user_scsi` * - vhost-user-vsock - Socket based communication - - See https://github.com/rust-vmm/vhost-device + - `vhost-device-vsock `_ =20 The referenced *daemons* are not exhaustive, any conforming backend implementing the device and using the vhost-user protocol should work. diff --git a/docs/system/devices/virtio/virtio-gpu.rst b/docs/system/device= s/virtio/virtio-gpu.rst index 39d2fd2d21c..0f4bb304a9b 100644 --- a/docs/system/devices/virtio/virtio-gpu.rst +++ b/docs/system/devices/virtio/virtio-gpu.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0-or-later =20 +.. _virtio_gpu: + VirtIO GPU =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.47.2