[PATCH 01/12] docs: Add a vhost-virtio-video rst file

[Albert Esteve <aesteve@redhat.com>]

From: Peter Griffin <peter.griffin@linaro.org>

Add rst file with a brief description of the
daemon and a cheat sheet of commands.

Signed-off-by: Peter Griffin <peter.griffin@linaro.org>
Signed-off-by: Albert Esteve <aesteve@redhat.com>
---
 docs/system/devices/vhost-user-video.rst | 124 +++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 docs/system/devices/vhost-user-video.rst

diff --git a/docs/system/devices/vhost-user-video.rst b/docs/system/devices/vhost-user-video.rst
new file mode 100644
index 0000000000..ff0a8fe5c7
--- /dev/null
+++ b/docs/system/devices/vhost-user-video.rst
@@ -0,0 +1,124 @@
+=====================
+QEMU vhost-user-video
+=====================
+
+Overview
+--------
+
+This vmm translates from virtio-video v3 protocol and writes
+to a v4l2 mem2mem stateful decoder/encoder device [1]. v3 was
+chosen as that is what the virtio-video Linux frontend driver
+currently implements.
+
+The primary goal so far is to enable development of virtio-video
+frontend driver using purely open source software. Using vicodec
+v4l2 stateful decoder on the host for testing then allows a pure
+virtual environment for development and testing.
+
+Currently the vmm only supports v4l2 stateful devices, and the
+intention is it will be used with Arm SoCs that implement stateful
+decode/encode devices such as Qcom Venus, RPi, MediaTek etc.
+
+A Qemu + vicodec setup for virtio-video should also allow for
+CI systems like kernelci, lkft to test the virtio-video interface
+easily.
+
+Currently support for VAAPI or decoding via libavcodec or similar
+libraries is not implemented, but this could be added in the future.
+
+Some example commands are provided below on how to run the daemon
+and achieve a video decode using vicodec and a link to some test
+content.
+
+[1] https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/dev-decoder.html
+
+[2] https://lwn.net/Articles/760650/
+
+Examples
+--------
+
+Guest Linux kernel modules:
+
+::
+
+    CONFIG_MEDIA_SUPPORT=y
+    CONFIG_MEDIA_TEST_SUPPORT=y
+    CONFIG_V4L_TEST_DRIVERS=y
+    CONFIG_VIRTIO_VIDEO=y
+    CONFIG_GDB_SCRIPTS=y
+    CONFIG_DRM_VIRTIO_GPU=y
+
+Host kernel modules:
+
+::
+
+    CONFIG_MEDIA_SUPPORT=y
+    CONFIG_MEDIA_TEST_SUPPORT=y
+    CONFIG_V4L_TEST_DRIVERS=y
+    CONFIG_VIDEO_VICODEC=y
+
+Note: Vicodec has been recently included in the Fedora kernel releases,
+but it is not yet set on the default Debian kernel.
+
+The daemon should be started first (video3 typically is the stateful video):
+
+::
+
+    host# vhost-user-video --socket-path=/tmp/video.sock --v4l2-device=/dev/video3
+
+The QEMU invocation needs to create a chardev socket the device can
+use to communicate as well as share the guests memory over a memfd.
+
+::
+
+    host# qemu-system								\
+        -device vhost-user-video-pci,chardev=video,id=video                     \
+        -chardev socket,path=/tmp//video.sock,id=video                          \
+        -m 4096 		        					\
+        -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on	\
+        -numa node,memdev=mem							\
+        ...
+
+After booting, the device should be available at /dev/video0:
+
+::
+
+    guest# v4l2-ctl -d/dev/video0 --info
+    Driver Info:
+            Driver name      : virtio-video
+            Card type        : 
+            Bus info         : virtio:stateful-decoder
+            Driver version   : 6.1.0
+            Capabilities     : 0x84204000
+                    Video Memory-to-Memory Multiplanar
+                    Streaming
+                    Extended Pix Format
+                    Device Capabilities
+            Device Caps      : 0x04204000
+                    Video Memory-to-Memory Multiplanar
+                    Streaming
+                    Extended Pix Format
+
+Example v4l2-ctl decode command:
+
+::
+
+    guest# wget https://people.linaro.org/~peter.griffin/jelly_640_480-420P.fwht
+    guest# v4l2-ctl -d0 -x width=640,height=480 -v width=640,height=480,pixelformat=YU12 \
+        --stream-mmap --stream-out-mmap --stream-from jelly_640_480-420P.fwht            \
+        --stream-to out-jelly-640-480.YU12
+
+Play the raw decoded video with ffplay or mplayer
+
+::
+
+    guest# ffplay -loglevel warning -v info -f rawvideo -pixel_format yuv420p \
+        -video_size "640x480" ./out-jelly-640-480.YU12
+    guest# mplayer -demuxer rawvideo -rawvideo \
+        format=i420:w=640:h=480:fps=25 out-jelly-640-480.YU12
+
+Enable v4l2 debug in virtio-video driver
+
+::
+
+    # echo 0x1f > /sys/class/video4linux/videoX/dev_debug
-- 
2.39.2