drm/vkms: Add setup and testing information

.. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c

   :doc: vkms (Virtual Kernel Modesetting)

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.

To disable the driver, use ::

  sudo modprobe -r vkms

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 <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .

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

====