VHOST-DEVICE-GPU(1)

💖 NAME 💖

okay bestie, meet vhost-device-gpu — it's a vhost-user backend for a VirtIO GPU device ✨

🌸 SYNOPSIS 🌸

vhost-device-gpu --socket-path <path> --gpu-mode <GPU_MODE>

🦋 DESCRIPTION 🦋

It's a virtio-gpu device, and it talks to everybody through the vhost-user protocol. That's the whole vibe 💅

✨ OPTIONS ✨

• -s, --socket-path <SOCKET> — the vhost-user Unix domain socket, aka where the magic little connection lives 🔌
• -g, --gpu-mode <GPU_MODE> — this one picks which backend implementation you're running with, so choose wisely bestie:
  • virglrenderer: the OpenGL implementation — note that it's been superseded by Virgl2 🙈
  • gfxstream: the Vulkan implementation (partial support only, so like… it's trying its best 🫶)
• -c, --capset <CAPSET> — a comma-separated list of the enabled capsets. The lineup:
  • virgl: OpenGL implementation, superseded by Virgl2 💀
  • virgl2: OpenGL implementation 👑
  • gfxstream-vulkan: Vulkan implementation (partial support only).

NOTE: Can only be used for 2D display output for now, no hardware acceleration yet.

• gfxstream-gles: OpenGL ES implementation (partial support only).

NOTE: Can only be used for 2D display output for now, no hardware acceleration yet.

• --use-egl <USE_EGL> — enables the backend to use EGL. Default: true. Possible values: true, false
• --use-glx <USE_GLX> — enables the backend to use GLX. Default: false. Possible values: true, false
• --use-gles <USE_GLES> — enables the backend to use GLES. Default: true. Possible values: true, false
• --use-surfaceless <USE_SURFACELESS> — turns on the surfaceless backend option. Default: true. Possible values: true, false
• -h, --help — prints help and usage info, for when you're lost (no shame, we've all been there) 🧚
• -V, --version — prints version info, slay ⭐

---

😭 LIMITATIONS 😭

bestie, sit down, we need to talk:

• This device links native libraries (because of the usage of Rutabaga) that are compiled with GNU libc. The CI is set up to not build this device for musl targets, periodt.
• It might be possible to build those libraries using musl and then build the GPU device, but honestly? That's untested. Nobody knows. Mystery behavior 🌈
• Currently, the only supported thing is sharing the display output to QEMU through a socket using the transfer_read operation (VIRTIO_GPU_CMD_TRANSFER_FROM_HOST_3D).
• Directly sharing display output resources using dmabuf is not yet supported. Not yet, babe.
• These features are not yet supported:
  • VIRTIO_GPU_CMD_RESOURCE_CREATE_BLOB
  • VIRTIO_GPU_CMD_SET_SCANOUT_BLOB
  • VIRTIO_GPU_CMD_RESOURCE_ASSIGN_UUID — these require rust-vmm/vhost#251, which in turn requires QEMU API stabilization. So we wait 🫠
• And because blob resources are not yet supported, some capsets are limited:
  • Venus (the Vulkan implementation in virglrenderer) support is unavailable 😭
  • gfxstream-vulkan and gfxstream-gles are exposed but can only be used for display output (no hardware acceleration yet).

---

🔥 FEATURES 🔥

The device leverages the rutabaga_gfx crate to provide rendering with virglrenderer and gfxstream. Iconic collaboration tbh 🤝

• Gfxstream support is compiled by default, but you can disable it by building without the gfxstream feature flag:

cargo build --no-default-features

• With Virglrenderer, Rutabaga translates OpenGL and Vulkan calls to an intermediate representation, which allows OpenGL acceleration on the host ✨
• With the gfxstream rendering mode, GLES and Vulkan calls are forwarded to the host with minimal modification 💫

---

🎀 EXAMPLES 🎀

Start the daemon on the host machine using either GPU mode:

1. Virglrenderer

2. Gfxstream (if the crate has been compiled with the gfxstream feature)

   host# vhost-device-gpu --socket-path /tmp/gpu.socket --gpu-mode virglrenderer

With QEMU, two device frontends can be used:

1. vhost-user-gpu-pci

2. vhost-user-vga (also implements VGA, allowing visibility of boot
   messages before GPU initialization)

By default, QEMU adds another VGA output. Disable it using -vga none.

🌟 Using vhost-user-gpu-pci

qemu-system-x86_64 \
  -chardev socket,id=vgpu,path=/tmp/gpu.socket \
  -device vhost-user-gpu-pci,chardev=vgpu,id=vgpu \
  -object memory-backend-memfd,share=on,id=mem0,size=4G \
  -machine q35,memory-backend=mem0,accel=kvm \
  -display gtk,gl=on,show-cursor=on \
  -vga none

💜 Using vhost-user-vga

qemu-system-x86_64 \
  -chardev socket,id=vgpu,path=/tmp/gpu.socket \
  -device vhost-user-vga,chardev=vgpu,id=vgpu \
  -object memory-backend-memfd,share=on,id=mem0,size=4G \
  -machine q35,memory-backend=mem0,accel=kvm \
  -display gtk,gl=on,show-cursor=on \
  -vga none

---

🌈 ENVIRONMENT 🌈

• RUST_LOG — the logging level, bestie. Set it to debug for maximum output, aka the full tea ☕

💀 BUGS 💀

See GitHub Issues: https://github.com/rust-vmm/vhost-device/issues

👑 AUTHORS 👑

• Dorinda Bassey dbassey@redhat.com
• Matej Hrica mhrica@redhat.com

🫶 SEE ALSO 🫶

• qemu(1)

---

okay that's the whole page, you're fully caught up 💖 this was Version 0.1.0 of vhost-device-gpu, straight out of rust-vmm/vhost-device — go forth and GPU, bestie, no cap ✨🎀🦋