Implement virtio-gpu 2D

[Mes0903]

This pull request implements a minimal VirtIO-GPU 2D device for semu. The device uses the VirtIO MMIO transport and provides DRM/KMS support for Linux to bind the virtio_gpu driver and expose /dev/dri/card0. The software backend supports 2D resource management, scanout updates, and cursor presentation through the SDL window backend.

When the SDL window grabs the pointer, press Ctrl+Alt+G to release the mouse cursor back to the host.

VirtIO-GPU

• Adds a VirtIO-GPU MMIO device.
• Implements the basic 2D command path:
  • display information and EDID queries
  • 2D resource creation and destruction
  • backing attachment and detachment
  • guest-to-host framebuffer transfer
  • scanout configuration and resource flushing
  • cursor set, move, and clear operations
• Adds a software 2D backend.
• Presents scanout and cursor updates through the SDL window backend.
• Adds a virtio-gpu CI smoke test that checks Linux driver binding,
  /dev/dri/card0, and the DirectFB2 DRM/KMS path.

Tested workloads

The implementation has been tested with:

• Linux virtio_gpu
• libdrm test tools such as modetest
• DirectFB2 using its DRM/KMS backend
• X11
• kmscube
• glmark2
• glxgears

Build and test

Install SDL2 development headers if they are not already present:

sudo apt install libsdl2-dev libsdl2-2.0-0

Build the emulator:

make

Run the virtio-gpu CI smoke test:

.ci/test-gpu.sh

To rebuild the default guest artifacts locally:

./scripts/build-image.sh --all

To build the DirectFB2 test tool disk used by the GPU smoke test:

./scripts/build-image.sh --directfb2-test

For the temporary X11-enabled test image used during review and CI testing:

./scripts/build-image.sh --x11 --directfb2-test

For a full manual GPU test run, build or download the kernel and tool disk, then launch semu with the tool disk as the guest root filesystem:

make semu minimal.dtb Image tool-ext4.img
./semu -k Image -c 1 -b minimal.dtb -d tool-ext4.img

Additional test scaffolding

This PR currently carries two DO NOT MERGE commits to make review and CI easier while the final guest artifact flow is being prepared:

• DO NOT MERGE: Add X11 image support for CI testing adds an optional X11-enabled Buildroot configuration. The normal rootfs.cpio and ext4.img stay on the default Buildroot configuration, while the heavier X11 payload is built into tool-ext4.img for development and CI coverage.
• DO NOT MERGE: Cache PR-built guest artifacts keeps PR-built Image/rootfs.cpio/tool-ext4.img artifacts cached by the live guest-input hash, then re-uploads them as the normal prebuilt-pr workflow artifact for downstream CI jobs. It also prevents restored PR artifacts from falling back to the upstream release download path before tool-ext4.img exists there.

These commits are test scaffolding only. They are expected to be dropped or replaced before merge and should not be treated as part of the final user-facing build flow. The temporary CI/cache/X11 adjustments are kept in DO NOT MERGE commits and are not intended to land in master.

Manual checks

Check DRM/KMS binding

Inside the guest:

ls -l /dev/dri/
modetest -M virtio_gpu

Run modetest

Use the connector ID reported by modetest -M virtio_gpu:

modetest -M virtio_gpu -s <connector-id>:1024x768

A test image should appear in the SDL window.

If you see Invalid argument, re-check the connector ID. If you see Permission denied or the DRM device is busy, stop the process that currently owns /dev/dri/card0:

ps | grep -E "Xorg|weston|kmscube|DirectFB"
kill <PID>

Run DirectFB2

If the DirectFB2 test payload is present in the guest disk:

. /root/local-env.sh
df_drivertest

Other DirectFB2 examples can also be run from the same environment, such as:

df_fire
df_matrix
df_window
df_input
df_layers

The installed DirectFB2 examples come from the upstream DirectFB-examples project and can be listed in the guest with:

ls /usr/local/bin/df_*

If X11 is running and owns /dev/dri/card0, stop Xorg first before running DirectFB2:

ps | grep Xorg
kill <PID>

Run kmscube

If the test image includes kmscube, stop X11 first if it is running, then run:

kmscube

Run X11 workloads

If using the temporary X11-enabled test image from the DO NOT MERGE scaffolding, start X11 inside the guest:

startx

After X11 is running, launch the test programs from the guest:

glmark2
glxgears

[jserv]

Rebase latest 'master' branch, as deployment and build system are refined.

[Mes0903]

@jserv Since master now rebuilds PR prebuilts from source and publishes only Image/rootfs.cpio, should the DirectFB2 GPU test program become part of the normal Buildroot rootfs, or should test-gpu build/inject a separate GPU-only ext4 image during CI?

[jserv]

Since master now rebuilds PR prebuilts from source and publishes only Image/rootfs.cpio, should the DirectFB2 GPU test program become part of the normal Buildroot rootfs, or should test-gpu build/inject a separate GPU-only ext4 image during CI?

Both are doable. You can even propose alternatives. The only consideration is to minimize kernel/rootfs images when possible.

[Mes0903]

I decided to keep the normal kernel/rootfs path small and keep the GPU test payload out of the default Buildroot rootfs.

The current direction is to keep rootfs.cpio and the default ext4.img built from the normal Buildroot config, then build a separate tool-ext4.img only for GPU-oriented CI tests. test-gpu.sh boots that tool disk directly when it needs the DirectFB2 test programs. This keeps the default boot artifacts small, while still letting CI exercise the DRM/KMS path end to end.

For the temporary X11/glxgears validation, the DO NOT MERGE commit extends that same tool-image path with --x11; it does not put X11 into the normal rootfs. That part is only for PR testing and should not go into the mainline series.

[Mes0903]

I also made a few CI-only adjustments after testing the PR prebuilt path.

The PR prebuilt job now caches the generated guest artifacts by the live guest-input hash. When the PR changes Buildroot/Linux/rootfs inputs, the first run still rebuilds Image/rootfs.cpio/tool-ext4.img from source, but later pushes with the same guest inputs can restore those files from cache instead of running Buildroot again.

I also kept the downstream jobs artifact-based: pr-prebuilt-build still uploads Image/rootfs.cpio/tool-ext4.img as prebuilt-pr, so the Linux/macOS test jobs do not need to know whether the files came from a fresh build or from cache.

One related Makefile issue showed up during CI: external artifacts depended on prebuilt.sha1 as a normal prerequisite, and prebuilt.sha1 is refreshed via FORCE. That made make check treat already-restored PR artifacts as stale and try to download tool-ext4.img.bz2 from the upstream release, where it does not exist yet. I changed that dependency to order-only, so the manifest is still available when an artifact has to be downloaded, but existing PR-built artifacts are not redownloaded just because the manifest was refreshed.

Finally, test-gpu.sh now checks whether Image/rootfs.cpio/tool-ext4.img are already present before invoking make for them. This lets the workflow artifact path work correctly and avoids accidentally falling back to the release download path.

All of these CI adjustments are currently kept in DO NOT MERGE commits, so they are only for validating this PR and are not intended to land in master.

[Mes0903]

For convenience when manually testing the PR, I have also uploaded the prebuilt files to my own blob branch: https://github.com/Mes0903/semu/tree/blob

[jserv]

Is local-env.sh required?

[Mes0903]

It depends on how we want users to invoke the test tools. local-env.sh is the guest-side environment hook for tools that are overlaid through the shared test-tools.img. Now it adds /usr/local/bin to PATH and /usr/local/lib to LD_LIBRARY_PATH.

The idea is that the default rootfs stays small, while optional test tools are collected in the same test-tools.img. When we add a new test tool later, the image build should stage that tool into test-tools.img, and local-env.sh should be updated if that tool needs an additional binary or library search path.

With that convention, after booting the VM the user only needs to source /root/local-env.sh once, instead of typing full paths such as /usr/local/bin/df_* for the overlaid tools.

[shengwen-tw]

Aside from the CI/test change which I’m not familiar enough, the implementation looks legitimate to me.