From: Peter Griffin <peter.grif...@linaro.org> Add rst file with a brief description of the daemon and a cheat sheet of commands.
Signed-off-by: Peter Griffin <peter.grif...@linaro.org> Signed-off-by: Albert Esteve <aest...@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
