modetest

List connectors and their available modes for a specific driver

$ modetest -M [mgag200] -c

$ sudo modetest -M [mgag200] -s [connector_id]:[1600]x[1200]

modetest [OPTIONS]

-M <module>, --module=<module>
    Specifies the DRM driver module name to use (e.g., i915, amdgpu, nouveau). If not specified, modetest attempts to detect an active module.

-D <device>, --device=<device>
    Specifies the DRM device file path (e.g., /dev/dri/card0). Useful when multiple DRM devices are present.

-s <connector>, --size=<connector>
    When used alone (e.g., -s DP-1), lists available modes for the specified connector. When used with a resolution (e.g., -s DP-1@1920x1080p), attempts to set that mode on the connector. An optional 'p' suffix indicates preferred, 'r' for reduced blanking.

-P <plane-id>, --planes=<plane-id>
    Tests specific display planes, typically used for overlays, cursors, or dedicated video planes. This option can take complex arguments specifying source/destination rectangles and pixel formats.

-c <crtc-id>, --crtc=<crtc-id>
    Targets a specific CRTC (Cathode Ray Tube Controller) ID for operations, such as mode setting or property manipulation. CRTCs manage timing and synchronization for displays.

-f <format>, --format=<format>
    Specifies the pixel format for surfaces (e.g., XR24 for XRGB8888, BGRA888). Used with plane tests or buffer allocation.

-v, --verbose
    Increases the verbosity of the output, providing more detailed information about DRM objects and operations.

-h, --help
    Displays a help message with usage instructions and exits.

modetest is a command-line tool designed for testing and debugging the Kernel Mode Setting (KMS) functionality of Direct Rendering Manager (DRM) drivers. It allows users to query and manipulate display hardware directly through the kernel interface, independent of any desktop environment or display server. It can be used to list available connectors, CRTCs (Cathode Ray Tube Controllers), encoders, and planes, as well as to set display modes, test atomic commits, and display various test patterns or images.

This tool is invaluable for graphics driver developers, system integrators, and advanced users troubleshooting display-related issues or verifying display hardware capabilities on Linux.

Using modetest often requires root privileges or membership in the render or video user groups to access DRM devices. Running it on an actively used display can disrupt the current desktop environment (Xorg, Wayland), potentially leading to a blank screen or display corruption, as it directly manipulates the low-level display state. It's primarily a diagnostic tool for developers and advanced users.

Commonly, modetest is run with just the module name (e.g., sudo modetest -M i915) to enumerate all available DRM objects like connectors, encoders, CRTCs, and planes, along with their supported modes and properties. To test a specific mode, one might use sudo modetest -s DP-1@1920x1080p. Developers use it to test atomic commits for multi-plane setups or complex display configurations.

The output of modetest lists various DRM objects identified by unique IDs. Connectors represent physical display outputs (HDMI, DisplayPort, LVDS). CRTCs (Cathode Ray Tube Controllers) are responsible for generating scanout signals to display a buffer. Encoders convert CRTC signals to connector-specific formats. Planes are memory buffers that can be scanned out by CRTCs, including primary planes, overlay planes, and cursor planes. Understanding these components is key to interpreting modetest's detailed output.

modetest is an integral part of the libdrm project, the userspace library providing the API for interacting with the Linux kernel's Direct Rendering Manager (DRM). Its development gained prominence with the introduction of Kernel Mode Setting (KMS), which shifted the responsibility of display mode configuration from userspace applications (like the X server) into the kernel. This change enhanced stability, security, and performance of graphics on Linux.

modetest was created as a crucial utility to test, debug, and validate the KMS interface, enabling developers to directly interact with and verify display hardware capabilities and driver implementations.

lsmod(8), dmesg(1), lspci(8), xrandr(1)