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
+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
 =================
 
-- 
2.39.2

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