| Message ID | 20231113190211.92412-3-leo.yan@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | virtio: Refactor vhost input stub | expand |
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 > >
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
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`
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