| Message ID | 20231107180246.3456598-8-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | virtio: cleanup vhost-user-generic and reduce c&p | expand |
On Tue, Nov 07, 2023 at 06:02:46PM +0000, Alex Bennée wrote: > Make it clear the vhost-user-device is intended for expert use only. > > Signed-off-by: Alex Bennée <alex.bennee@linaro.org> > Message-Id: <20231009095937.195728-7-alex.bennee@linaro.org> > > --- > v5 > - split vhost-user-device out of the table > - sort the table alphabetically > - add sound and scmi devices > v6 > - add note re vhost-user-device > v7 > - fix patching description > --- > docs/system/devices/vhost-user-rng.rst | 2 + > docs/system/devices/vhost-user.rst | 70 +++++++++++++++++++++++++- > 2 files changed, 71 insertions(+), 1 deletion(-) > > diff --git a/docs/system/devices/vhost-user-rng.rst b/docs/system/devices/vhost-user-rng.rst > index a145d4105c..ead1405326 100644 > --- a/docs/system/devices/vhost-user-rng.rst > +++ b/docs/system/devices/vhost-user-rng.rst > @@ -1,3 +1,5 @@ > +.. _vhost_user_rng: > + > QEMU vhost-user-rng - RNG emulation > =================================== > > diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/vhost-user.rst > index a80e95a48a..c6afc4836f 100644 > --- a/docs/system/devices/vhost-user.rst > +++ b/docs/system/devices/vhost-user.rst > @@ -8,13 +8,81 @@ 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*. > > +Each device will have an virtio-mmio and virtio-pci variant. See your and ccw eventually? > +platform details for what sort of virtio bus to use. > + > +.. list-table:: vhost-user devices > + :widths: 20 20 60 > + :header-rows: 1 > + > + * - Device > + - Type > + - Notes > + * - vhost-user-blk > + - Block storage > + - See contrib/vhost-user-blk > + * - vhost-user-fs > + - File based storage driver > + - See https://gitlab.com/virtio-fs/virtiofsd > + * - vhost-user-gpio > + - Proxy gpio pins to host > + - See https://github.com/rust-vmm/vhost-device > + * - vhost-user-gpu > + - GPU driver > + - See contrib/vhost-user-gpu > + * - vhost-user-i2c > + - Proxy i2c devices to host > + - See https://github.com/rust-vmm/vhost-device > + * - vhost-user-input > + - Generic input driver > + - See contrib/vhost-user-input > + * - vhost-user-rng > + - Entropy driver > + - :ref:`vhost_user_rng` > + * - vhost-user-scmi > + - System Control and Management Interface > + - See https://github.com/rust-vmm/vhost-device > + * - vhost-user-snd > + - Audio device > + - See https://github.com/rust-vmm/vhost-device/staging > + * - vhost-user-scsi > + - SCSI based storage > + - See contrib/vhost-user-scsi > + * - vhost-user-vsock > + - Socket based communication > + - See https://github.com/rust-vmm/vhost-device > + > +The referenced *daemons* are not exhaustive, any conforming backend > +implementing the device and using the vhost-user protocol should work. > + > +vhost-user-device > +^^^^^^^^^^^^^^^^^ The distinction between "+vhost-user device" and "vhost-user-device" will be lost on all but the most astute readers. I propose to just removing this part for now. Developers can subclass vhost-user-device just as easily. > +The vhost-user-device is a generic development device intended for > +expert use while developing new backends. The user needs to specify > +all the required parameters including: > + > + - Device ``virtio-id`` > + - The ``num_vqs`` it needs and their ``vq_size`` > + - The ``config_size`` if needed > + > +.. note:: > + To prevent user confusion you cannot currently instantiate > + vhost-user-device without first patching out:: > + > + /* Reason: stop inexperienced users confusing themselves */ > + dc->user_creatable = false; > + > + in ``vhost-user-device.c`` and ``vhost-user-device-pci.c`` file and > + rebuilding. > + > vhost-user daemon > ================= > > -- > 2.39.2
diff --git a/docs/system/devices/vhost-user-rng.rst b/docs/system/devices/vhost-user-rng.rst index a145d4105c..ead1405326 100644 --- a/docs/system/devices/vhost-user-rng.rst +++ b/docs/system/devices/vhost-user-rng.rst @@ -1,3 +1,5 @@ +.. _vhost_user_rng: + QEMU vhost-user-rng - RNG emulation =================================== diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/vhost-user.rst index a80e95a48a..c6afc4836f 100644 --- a/docs/system/devices/vhost-user.rst +++ b/docs/system/devices/vhost-user.rst @@ -8,13 +8,81 @@ 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*. +Each device will have an virtio-mmio and virtio-pci variant. See your +platform details for what sort of virtio bus to use. + +.. list-table:: vhost-user devices + :widths: 20 20 60 + :header-rows: 1 + + * - Device + - Type + - Notes + * - vhost-user-blk + - Block storage + - See contrib/vhost-user-blk + * - vhost-user-fs + - File based storage driver + - See https://gitlab.com/virtio-fs/virtiofsd + * - vhost-user-gpio + - Proxy gpio pins to host + - See https://github.com/rust-vmm/vhost-device + * - vhost-user-gpu + - GPU driver + - See contrib/vhost-user-gpu + * - vhost-user-i2c + - Proxy i2c devices to host + - See https://github.com/rust-vmm/vhost-device + * - vhost-user-input + - Generic input driver + - See contrib/vhost-user-input + * - vhost-user-rng + - Entropy driver + - :ref:`vhost_user_rng` + * - vhost-user-scmi + - System Control and Management Interface + - See https://github.com/rust-vmm/vhost-device + * - vhost-user-snd + - Audio device + - See https://github.com/rust-vmm/vhost-device/staging + * - vhost-user-scsi + - SCSI based storage + - See contrib/vhost-user-scsi + * - vhost-user-vsock + - Socket based communication + - See https://github.com/rust-vmm/vhost-device + +The referenced *daemons* are not exhaustive, any conforming backend +implementing the device and using the vhost-user protocol should work. + +vhost-user-device +^^^^^^^^^^^^^^^^^ + +The vhost-user-device is a generic development device intended for +expert use while developing new backends. The user needs to specify +all the required parameters including: + + - Device ``virtio-id`` + - The ``num_vqs`` it needs and their ``vq_size`` + - The ``config_size`` if needed + +.. note:: + To prevent user confusion you cannot currently instantiate + vhost-user-device without first patching out:: + + /* Reason: stop inexperienced users confusing themselves */ + dc->user_creatable = false; + + in ``vhost-user-device.c`` and ``vhost-user-device-pci.c`` file and + rebuilding. + vhost-user daemon =================
Make it clear the vhost-user-device is intended for expert use only. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20231009095937.195728-7-alex.bennee@linaro.org> --- v5 - split vhost-user-device out of the table - sort the table alphabetically - add sound and scmi devices v6 - add note re vhost-user-device v7 - fix patching description --- docs/system/devices/vhost-user-rng.rst | 2 + docs/system/devices/vhost-user.rst | 70 +++++++++++++++++++++++++- 2 files changed, 71 insertions(+), 1 deletion(-)