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
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 \
+ ...
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.1Hi 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
Hi Marc-André, + Mathieu for vhost RNG stuff. On Tue, Nov 14, 2023 at 01:54:50PM +0400, Marc-André Lureau wrote: > Hi > > On Mon, Nov 13, 2023 at 11:04 PM Leo Yan <leo.yan@linaro.org> wrote: [...] > > @@ -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 Will update the toctree in next version. [...] > > +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. Yeah, I copied from vhost-user-rng.rst. To be easier for our life, I will firstly fix this patch for this part, later we can consider to update vhost-user-rng.rst in a separate patch. Looped in Mathieu to be awared. > 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. I will update the doc as: "The QEMU invocation needs to create a chardev socket to communicate with the backend daemon and access the VirtIO queues with the guest over the :ref:`_shared_memory_object`." Thanks, Leo
© 2016 - 2024 Red Hat, Inc.