Re: [PATCH v2 2/4] docs/system: Add vhost-user-input documentation

[Marc-André Lureau]

Hi

On Mon, Nov 13, 2023 at 11:04 PM Leo Yan <leo.yan@linaro.org> wrote:
>
> This adds basic documentation for vhost-user-input.
>
> Signed-off-by: Leo Yan <leo.yan@linaro.org>
> ---
>  MAINTAINERS                              |  1 +
>  docs/system/devices/vhost-user-input.rst | 44 ++++++++++++++++++++++++
>  docs/system/devices/vhost-user.rst       |  2 +-
>  3 files changed, 46 insertions(+), 1 deletion(-)
>  create mode 100644 docs/system/devices/vhost-user-input.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 86c649784e..ef72c6d512 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2233,6 +2233,7 @@ L: virtio-fs@redhat.com
>  virtio-input
>  M: Gerd Hoffmann <kraxel@redhat.com>
>  S: Odd Fixes
> +F: docs/system/devices/vhost-user-input.rst
>  F: hw/input/vhost-user-input.c
>  F: hw/input/virtio-input*.c
>  F: include/hw/virtio/virtio-input.h
> diff --git a/docs/system/devices/vhost-user-input.rst 
> b/docs/system/devices/vhost-user-input.rst

You need to include the file in the toctree, in docs/system/device-emulation.rst

> new file mode 100644
> index 0000000000..4ff9dd4b27
> --- /dev/null
> +++ b/docs/system/devices/vhost-user-input.rst
> @@ -0,0 +1,44 @@
> +.. _vhost_user_input:
> +
> +QEMU vhost-user-input - Input emulation
> +=======================================
> +
> +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 daemon
> +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=input.sock      \
> +      --evdev-path=/dev/input/event17
> +
> +The QEMU invocation needs to create a chardev socket to communicate with the
> +backend daemon and share memory with the guest over a memfd.
> +
> +::
> +
> +  host# qemu-system                                                          
>   \
> +      -chardev socket,path=/tmp/input.sock,id=mouse0                         
>   \
> +      -device vhost-user-input-pci,chardev=mouse0                            
>   \
> +      -m 4096                                                                
>   \
> +      -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on  
>   \
> +      -numa node,memdev=mem


Well, this is not a memfd. This is taken from vhost-user-rng.rst, and
should probably be adjusted there too.

It needs shared memory, memory-backend-file can provide it and is
generally more available than memfd, although memfd should be
preferred as it offers some extra security guarantees. There is
already some explanations in vhost-user.rst, maybe we should just add
extra links.

> +      ...
> diff --git a/docs/system/devices/vhost-user.rst 
> b/docs/system/devices/vhost-user.rst
> index c6afc4836f..75b40f08c6 100644
> --- a/docs/system/devices/vhost-user.rst
> +++ b/docs/system/devices/vhost-user.rst
> @@ -42,7 +42,7 @@ platform details for what sort of virtio bus to use.
>      - See https://github.com/rust-vmm/vhost-device
>    * - vhost-user-input
>      - Generic input driver
> -    - See contrib/vhost-user-input
> +    - :ref:`vhost_user_input`
>    * - vhost-user-rng
>      - Entropy driver
>      - :ref:`vhost_user_rng`
> --
> 2.34.1
>
>


-- 
Marc-André Lureau