Direct Rendering Manager (DRM)

Relevant source files

The following files were used as context for generating this wiki page:

• drivers/gpu/drm/drm_drv.c
• Documentation/gpu/introduction.rst
• Documentation/gpu/drm-internals.rst
• Documentation/gpu/drm-uapi.rst
• Documentation/gpu/drm-kms-helpers.rst
• Documentation/gpu/automated_testing.rst

The Direct Rendering Manager (DRM) is a Linux kernel subsystem responsible for supporting complex graphics devices, particularly those with programmable pipelines for 3D graphics acceleration. It provides a uniform interface to applications and simplifies common driver tasks such as memory management, interrupt handling, and Direct Memory Access (DMA).
Sources: Documentation/gpu/introduction.rst:4-9

DRM acts as the primary layer for graphics drivers to interface with the kernel. It includes specialized components like the Translation Table Manager (TTM) for memory, output configuration, mode setting, and vblank internals.
Sources: Documentation/gpu/introduction.rst:11-14

Core Architecture and Services

The DRM core provides multiple services to graphics drivers through the drm.ko module. Drivers register with the core by providing a struct drm_driver and calling drm_dev_alloc() and drm_dev_register().
Sources: Documentation/gpu/drm-internals.rst:26-31

Key Services

• Memory Management: Supports GEM (Graphics Execution Manager) and TTM.
• Mode Setting (KMS): Manages output configurations, CRTCs, and planes.
• Vblank Handling: Manages vertical blanking interrupts and events.
• Command Submission: Fencing and DMA services for hardware execution.
  Sources: Documentation/gpu/drm-internals.rst:14-19

The following diagram illustrates the relationship between user applications, the DRM core, and specific hardware drivers:

The DRM stack allows applications to communicate with hardware through a structured set of IOCTLs and memory managers.
Sources: Documentation/gpu/introduction.rst:4-15, Documentation/gpu/drm-uapi.rst:6-10

Device Nodes and Userland Interfaces

DRM exposes several character-device nodes in /dev/dri/ to user-space applications. Each node type grants different levels of access and serves specific roles.
Sources: Documentation/gpu/drm-uapi.rst:133-138

Node Types

Node Name	Device Path	Purpose
Primary Node	/dev/dri/cardX	Provides legacy operations, modesetting, and requires authentication for unprivileged clients.
Render Node	/dev/dri/renderDX	Provides non-global rendering commands for offscreen rendering and GPGPU; does not require a DRM-Master.
Control Node	/dev/dri/controlDX	Reserved for future KMS control interfaces; currently unused.
Sources: Documentation/gpu/drm-uapi.rst:135-155

Userland Interface Flow

When a user-space client opens a DRM device, the following flow occurs depending on the node type:

Render nodes simplify access for GPGPU tasks by removing the requirement for a central display compositor to authenticate clients.
Sources: Documentation/gpu/drm-uapi.rst:157-170

Kernel Mode Setting (KMS)

KMS allows the kernel to set the display mode, including resolution, color depth, and refresh rate. It separates the display pipeline into discrete objects: CRTCs, Planes, Encoders, and Connectors.
Sources: Documentation/gpu/drm-kms-helpers.rst:4-9

KMS Object Indexing

CRTCs possess both a unique object ID and a densely packed index. The index is used in bitmasks, such as the possible_crtcs member of struct drm_mode_get_plane. The DRM_IOCTL_MODE_GETRESOURCES call returns an array of CRTC IDs; the index represents the CRTC's position in that array.
Sources: Documentation/gpu/drm-uapi.rst:370-377

Helper Libraries

DRM uses a modular approach with helper libraries that drivers can combine:

• Atomic Helpers: Implement atomic modeset commits, allowing multiple property changes in a single operation.
• Bridge Helpers: Manage encoder and transcoder IP blocks.
• Panel Helpers: Handle display panel logic and timings.
  Sources: Documentation/gpu/drm-kms-helpers.rst:14-25

Device Reset and Wedging

When a GPU hang is detected, the kernel attempts to reset the device. If recovery fails, the device is declared "wedged."
Sources: Documentation/gpu/drm-uapi.rst:248-251

Reset Propagation

The Kernel Mode Driver (KMD) checks for hangs and performs resets. It uses the dma_fence object to propagate error codes to user-space. The dma_fence_set_error() function attaches codes like ENODEV to fences before signaling them.
Sources: Documentation/gpu/drm-uapi.rst:256-262

Recovery Methods

Drivers use the drm_dev_wedged_event() to notify userspace via a uevent. The WEDGED= environment variable specifies the suggested recovery method.
Sources: Documentation/gpu/drm-uapi.rst:309-315

Recovery Method	Action Required
none	Telemetry collection only (debug logs).
rebind	Unbind and then bind the driver to the device.
bus-reset	Perform a full bus reset/re-enumeration and rebind.
unknown	Consumer policy defined by userspace.
Sources: Documentation/gpu/drm-uapi.rst:328-336

Automated Testing

The DRM subsystem utilizes GitLab CI for regression testing. The infrastructure is shared with the Mesa project.
Sources: Documentation/gpu/automated_testing.rst:4-9

CI Components

• IGT (igt-gpu-tools): The primary test suite for DRM drivers.
• VKMS: A software-only model of a KMS driver used for testing without hardware.
• Test Lists: Configuration files like testlist.txt define which IGT tests run on specific hardware.
  Sources: Documentation/gpu/automated_testing.rst:21-35, Documentation/gpu/drm-uapi.rst:489-493

Summary

The Direct Rendering Manager provides a robust framework for Linux graphics, handling the complexity of modern GPU hardware while offering a stable UAPI for applications. Through its modular design using KMS helpers and standardized memory management, it supports a wide variety of display and compute tasks while integrating with automated CI tools for stability.
Sources: Documentation/gpu/introduction.rst:4-14, Documentation/gpu/drm-kms-helpers.rst:4-10