drm/vkms Virtual Kernel Modesetting

VKMS is a software-only model of a KMS driver that is useful for testing and for running X (or similar) on headless machines. VKMS aims to enable a virtual display with no need of a hardware display capability, releasing the GPU in DRM API tests.

Setup

The VKMS driver can be setup with the following steps:

To check if VKMS is loaded, run:

lsmod | grep vkms

This should list the VKMS driver. If no output is obtained, then you need to enable and/or load the VKMS driver. Ensure that the VKMS driver has been set as a loadable module in your kernel config file. Do:

make nconfig

Go to `Device Drivers> Graphics support`

Enable `Virtual KMS (EXPERIMENTAL)`

Compile and build the kernel for the changes to get reflected. Now, to load the driver, use:

sudo modprobe vkms

On running the lsmod command now, the VKMS driver will appear listed. You can also observe the driver being loaded in the dmesg logs.

The VKMS driver has optional features to simulate different kinds of hardware, which are exposed as module options. You can use the modinfo command to see the module options for vkms:

modinfo vkms

Module options are helpful when testing, and enabling modules can be done while loading vkms. For example, to load vkms with cursor enabled, use:

sudo modprobe vkms enable_cursor=1

To disable the driver, use

sudo modprobe -r vkms

Configuration With ConfigFS

VKMS is instrumented with support for configuration via ConfigFS.

With VKMS installed, you can mount ConfigFS at /config/ like so:

mkdir -p /config/
sudo mount -t configfs none /config

This allows you to configure multiple virtual devices. Note that the default device which can be enabled in the module params with:

modprobe vkms default_device=1

is immutable because we cannot pre-populate ConfigFS directories with normal files.

To set up a new device, create a new directory under the VKMS configfs directory:

mkdir /config/vkms/test

With your device created you'll find an new directory ready to be configured:

/config
`-- vkms
    `-- test
        |-- connectors
             `-- connected
        |-- crtcs
        |-- encoders
        |-- planes
        `-- enabled

Each directory you add within the connectors, crtcs, encoders, and planes directories will let you configure a new object of that type. Adding new objects will automatically create a set of default files and folders you can use to configure that object.

For instance, we can set up a two-output device like so:

DRM_PLANE_TYPE_PRIMARY=1
DRM_PLANE_TYPE_CURSOR=2
DRM_PLANE_TYPE_OVERLAY=0

mkdir /config/vkms/test/planes/primary
echo $DRM_PLANE_TYPE_PRIMARY > /config/vkms/test/planes/primary/type

mkdir /config/vkms/test/planes/other_primary
echo $DRM_PLANE_TYPE_PRIMARY > /config/vkms/test/planes/other_primary/type

mkdir /config/vkms/test/crtcs/crtc
mkdir /config/vkms/test/crtcs/crtc_other

mkdir /config/vkms/test/encoders/encoder
mkdir /config/vkms/test/encoders/encoder_other

mkdir /config/vkms/test/connectors/connector
mkdir /config/vkms/test/connectors/connector_other

You can see that specific attributes, such as .../<plane>/type, can be configured by writing into them. Associating objects together can be done via symlinks:

ln -s /config/vkms/test/encoders/encoder       /config/vkms/test/connectors/connector/possible_encoders
ln -s /config/vkms/test/encoders/encoder_other /config/vkms/test/connectors/connector_other/possible_encoders

ln -s /config/vkms/test/crtcs/crtc             /config/vkms/test/planes/primary/possible_crtcs/
ln -s /config/vkms/test/crtcs/crtc_other       /config/vkms/test/planes/other_primary/possible_crtcs/

ln -s /config/vkms/test/crtcs/crtc             /config/vkms/test/encoders/encoder/possible_crtcs/
ln -s /config/vkms/test/crtcs/crtc_other       /config/vkms/test/encoders/encoder_other/possible_crtcs/

Finally, to enable your configured device, just write 1 to the enabled file:

echo 1 > /config/vkms/test/enabled

By default no display is "connected" so to connect a connector you'll also have to write 1 to a connectors "connected" attribute:

echo 1 > /config/vkms/test/connectors/connector/connected

One can verify that this is worked using the modetest utility or the equivalent for your platform.

When you're done with the virtual device, you can clean up the device like so:

echo 0 > /config/vkms/test/enabled

rm /config/vkms/test/connectors/connector/possible_encoders/encoder
rm /config/vkms/test/encoders/encoder/possible_crtcs/crtc
rm /config/vkms/test/planes/primary/possible_crtcs/crtc
rm /config/vkms/test/planes/cursor/possible_crtcs/crtc
rm /config/vkms/test/planes/overlay/possible_crtcs/crtc
rm /config/vkms/test/planes/overlay/possible_crtcs/crtc_other
rm /config/vkms/test/planes/other_primary/possible_crtcs/crtc_other

rmdir /config/vkms/test/planes/primary
rmdir /config/vkms/test/planes/other_primary
rmdir /config/vkms/test/planes/cursor
rmdir /config/vkms/test/planes/overlay
rmdir /config/vkms/test/crtcs/crtc
rmdir /config/vkms/test/crtcs/crtc_other
rmdir /config/vkms/test/encoders/encoder
rmdir /config/vkms/test/encoders/encoder_other
rmdir /config/vkms/test/connectors/connector
rmdir /config/vkms/test/connectors/connector_other

rmdir /config/vkms/test

Testing With IGT

The IGT GPU Tools is a test suite used specifically for debugging and development of the DRM drivers. The IGT Tools can be installed from here .

The tests need to be run without a compositor, so you need to switch to text only mode. You can do this by:

sudo systemctl isolate multi-user.target

To return to graphical mode, do:

sudo systemctl isolate graphical.target

Once you are in text only mode, you can run tests using the --device switch or IGT_DEVICE variable to specify the device filter for the driver we want to test. IGT_DEVICE can also be used with the run-test.sh script to run the tests for a specific driver:

sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>

For example, to test the functionality of the writeback library, we can run the kms_writeback test:

sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback

You can also run subtests if you do not want to run the entire test:

sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip

TODO

If you want to do any of the items listed below, please share your interest with VKMS maintainers.

IGT better support

Debugging:

  • kms_plane: some test cases are failing due to timeout on capturing CRC;

Virtual hardware (vblank-less) mode:

  • VKMS already has support for vblanks simulated via hrtimers, which can be tested with kms_flip test; in some way, we can say that VKMS already mimics the real hardware vblank. However, we also have virtual hardware that does not support vblank interrupt and completes page_flip events right away; in this case, compositor developers may end up creating a busy loop on virtual hardware. It would be useful to support Virtual Hardware behavior in VKMS because this can help compositor developers to test their features in multiple scenarios.

Add Plane Features

There's lots of plane features we could add support for:

  • Add background color KMS property[Good to get started].

  • Scaling.

  • Additional buffer formats, especially YUV formats for video like NV12. Low/high bpp RGB formats would also be interesting.

  • Async updates (currently only possible on cursor plane using the legacy cursor api).

For all of these, we also want to review the igt test coverage and make sure all relevant igt testcases work on vkms. They are good options for internship project.

Runtime Configuration

We want to be able to manipulate vkms instances without having to reload the module. Such configuration can be added as extensions to vkms's ConfigFS support. Use-cases:

  • Hotremove connectors on the fly (to be able to test DP MST handling of compositors).

  • Change output configuration: Plug/unplug screens, change EDID, allow changing the refresh rate.

Writeback support

  • The writeback and CRC capture operations share the use of composer_enabled boolean to ensure vblanks. Probably, when these operations work together, composer_enabled needs to refcounting the composer state to proper work. [Good to get started]

  • Add support for cloned writeback outputs and related test cases using a cloned output in the IGT kms_writeback.

  • As a v4l device. This is useful for debugging compositors on special vkms configurations, so that developers see what's really going on.

Output Features

  • Variable refresh rate/freesync support. This probably needs prime buffer sharing support, so that we can use vgem fences to simulate rendering in testing. Also needs support to specify the EDID.

  • Add support for link status, so that compositors can validate their runtime fallbacks when e.g. a Display Port link goes bad.

CRC API Improvements

  • Optimize CRC computation compute_crc() and plane blending blend()

Atomic Check using eBPF

Atomic drivers have lots of restrictions which are not exposed to userspace in any explicit form through e.g. possible property values. Userspace can only inquiry about these limits through the atomic IOCTL, possibly using the TEST_ONLY flag. Trying to add configurable code for all these limits, to allow compositors to be tested against them, would be rather futile exercise. Instead we could add support for eBPF to validate any kind of atomic state, and implement a library of different restrictions.

This needs a bunch of features (plane compositing, multiple outputs, ...) enabled already to make sense.