Add support for new driver in IGT¶

Here is a detailed procedure to support a new driver in IGT, using Intel's "XE" driver as an example.

Detect the Driver¶

Add support in IGT lib to detect the driver, so that IGT will recognize the driver. The device name should match with the DRIVER_NAME configured in the Linux Kernel Module.

Example: drm/xe/kernel/-/blob/drm-xe-next/drivers/gpu/drm/xe/xe_drv.h#L11

KMD Changes:¶

#define DRIVER_NAME     "xe"

#define DRIVER_DESC     "Intel Xe Graphics"

#define DRIVER_DATE     "20201103"

IGT Changes:¶

diff --git a/lib/drmtest.c b/lib/drmtest.c

index 8e2d1ac50b..0ceab10389 100644

--- a/lib/drmtest.c

+++ b/lib/drmtest.c

@@ -189,6 +189,7 @@  static const struct module {

    { DRIVER_V3D, "v3d" },

    { DRIVER_VC4, "vc4" },

    { DRIVER_VGEM, "vgem" },

+   { DRIVER_XE, "xe" },

    {}

 };



@@ -547,6 +548,8 @@  static const char *chipset_to_str(int chipset)

        return "panfrost";

    case DRIVER_MSM:

        return "msm";

+   case DRIVER_XE:

+       return "xe";

    case DRIVER_ANY:

        return "any";

    default:

diff --git a/lib/drmtest.h b/lib/drmtest.h

index b5debd44b3..448ac03b49 100644

--- a/lib/drmtest.h

+++ b/lib/drmtest.h

@@ -51,6 +51,7 @@

 #define DRIVER_V3D (1 << 4)

 #define DRIVER_PANFROST    (1 << 5)

 #define DRIVER_MSM (1 << 6)

+#define DRIVER_XE  (1 << 7)

With the above changes, the simple IGT snippet int fd = drm_open_driver_master(DRIVER_XE); can open the "XE" driver.

UAPI Changes to Support Driver-Specific IOCTLs¶

Import UAPI headers: https://gitlab.freedesktop.org/drm/igt-gpu-tools#includedrm-uapi

Develop IGT Helpers¶

Now we can develop driver-specific IGT helpers based on DRM_IOCTL_VERSION.

Example:

+++ b/lib/drmtest.c

@@ -139,6 +139,16 @@  bool is_vc4_device(int fd)

    return __is_device(fd, "vc4");

 }



+bool is_xe_device(int fd)

+{

+   return __is_device(fd, "xe");

+}



+++ b/lib/intel_chipset.c

@@ -125,22 +163,18 @@  intel_get_pci_device(void)

 uint32_t

 intel_get_drm_devid(int fd)

 {



+   if (is_xe_device(fd))

+       return __xe_get_drm_devid(fd);

+   else

+       return __i915_get_drm_devid(fd);

}

Porting All Display IGTs to Support XE Driver¶

The task of porting all display-specific IGTs to support the XE driver is significant and critical. This process involves several steps.

Understanding the Current IGTs¶

The existing codebase must be thoroughly understood. This involves reviewing the code for all display IGTs, understanding their functionality, and identifying any potential issues that may arise when porting to the XE driver.

Understanding the XE Driver¶

The XE driver's specifications and capabilities must be understood. This will allow for the identification of any features that the IGTs can take advantage of, as well as any limitations that must be worked around.

Mapping the IGTs to the XE Driver¶

Once we understand both the IGTs and the XE driver, we can start mapping the functionality of the IGTs to the XE driver. This involves identifying which tests can be supported by the XE driver, which ones need to be modified, and which ones cannot be supported.

Modifying IGT Libraries¶

Start modifying the IGT libraries to support the XE driver and try to make the APIs as unified (to support both i915 and XE). To achieve this, collaborate and contribute with the core-mm and other development teams.

Notable contributions by Bhanu:

• Add IGT helpers to check for the XE driver
• Add an interface to query dev_id
• Get and cache the XE_config at driver opening level and uncache at driver closing level
• Support to create a BO for display framebuffers
• Add rendercopy support for display tests
• Add tiling support for XE
• API support to get the pipe index

Modifying the IGTs¶

Based on the mapping, we can start modifying the IGTs to support the XE driver. This could involve changing the code, adding new lib helpers, adding new tests, or removing unsupported tests. This process involves the following steps:

• Modify test initialization code to open the XE driver instead of Intel where applicable
• Update any Intel-specific code/defines in the tests to use equivalent XE APIs
• Ensure all relevant XE driver features are properly exercised by the tests. Add any missing test coverage
• Update documentation like man pages, comments, etc. to cover XE driver usage

Testing the Ported IGTs¶

After the IGTs have been modified, they need to be tested to ensure they work correctly with the XE driver. This involves running the tests, analyzing the results, and fixing any issues that are identified.

Test-Plan Documentation¶

With the addition of the Xe driver, a new way to document tests was added. It is based on special comment-like annotation inside the C code. We need to update each and every IGT with this new style of documentation.