Linux DRM - Architecture and the Big Picture

Linux DRM - Architecture and the Big Picture

Reqruies

Kernel: Based on Linux v6.19 source
Library: libdrm 2.4.129

Introduction

Why DRM Was Needed

• fbdev (/dev/fb0): A straightforward method that mmaps a single chunk of display memory to directly write pixels. It lacks features such as 3D acceleration, multi-monitor support, and resolution changes.
• Direct hardware control by the X server: The X server ran with root privileges to directly access graphics card registers, configuring resolutions (modes) and sending 3D commands.

• For 3D applications to use the GPU directly, the kernel needed to arbitrate GPU access, but no such mechanism existed (concurrent GPU access by multiple processes caused mutual corruption).
• Because resolution configuration (mode setting) lived in user space, switching between console and X caused screen flickering, and controlling early boot splash screens was impossible.
• The requirement for the X server to run as root posed severe security vulnerabilities.

The Full Stack

Placement of DRM in the Linux Graphics Stack
Mermaid
flowchart TB
    subgraph US["User space"]
        APP["3D Apps / Games<br/>OpenGL · Vulkan"]
        COMP["Display Server<br/>Wayland compositor · Xorg"]
        MESA["Mesa<br/>user-mode GPU driver"]
        LIBDRM["libdrm"]
    end
    subgraph KS["Kernel space"]
        NR["/dev/dri/renderD128<br/>render node"]
        NC["/dev/dri/card0<br/>primary node"]
        CORE["DRM core<br/>drm_drv.c · drm_ioctl.c · drm_gem.c ..."]
        HELP["DRM helpers<br/>atomic · gem_shmem · gpu scheduler"]
        DRV["GPU / display driver<br/>i915 · amdgpu · v3d · vkms ..."]
    end
    HW["GPU + display controller + monitor"]
    APP --> MESA --> LIBDRM
    COMP --> LIBDRM
    LIBDRM -->|"ioctl · mmap"| NR
    LIBDRM -->|"ioctl · read"| NC
    NR --> CORE
    NC --> CORE
    CORE --> HELP --> DRV
    CORE --> DRV
    DRV --> HW

• Applications draw using OpenGL/Vulkan. Mesa, which implements these APIs, generates GPU-specific commands (shaders, state setup). This part is called the user-mode driver (UMD).
• libdrm is a thin C library wrapping ioctl(). In other words, user space communicates with DRM solely by opening /dev/dri/* files and issuing ioctl, mmap, and read.
• The kernel side is divided into the common DRM core, helpers shared across various drivers, and hardware-specific drivers.

Two Jobs of DRM

Device Nodes: /dev/dri and sysfs

Verifying DRM Device Nodes
shell

• The major number is 226 and the name is drm. This value is registered by the kernel during boot (verified in the code below).
• card0 has minor number 0, while renderD128 has 128. This indicates that minor number ranges vary depending on the node type.
• Connectors also appear in sysfs, such as card0-DP-1 and card0-HDMI-A-1.

drivers/gpu/drm/drm_drv.c - #define DRM_MINOR_LIMIT (L136-139)
c

Source drivers/gpu/drm/drm_drv.c L136-L139 (Linux v6.19)

include/drm/drm_file.h - enum drm_minor_type (L61-66)
c

Source include/drm/drm_file.h L61-L66 (Linux v6.19)

• Primary (DRM_MINOR_PRIMARY = 0) spans minor numbers 0–63, while render (DRM_MINOR_RENDER = 2) begins at 64 * 2 = 128. The 226, 128 in the ls output above reflects this exact calculation.
• The name is assigned in drm_sysfs_minor_alloc().

drivers/gpu/drm/drm_sysfs.c - drm_sysfs_minor_alloc() (L551-591)
c

Source drivers/gpu/drm/drm_sysfs.c L551-L591 (Linux v6.19)

How card0 Differs from renderD128

include/drm/drm_ioctl.h - enum drm_ioctl_flags (L80-122)
c

Source include/drm/drm_ioctl.h L80-L122 (Linux v6.19)

drivers/gpu/drm/drm_ioctl.c - drm_ioctl_permit() (L599-621)
c

Source drivers/gpu/drm/drm_ioctl.c L599-L621 (Linux v6.19)

• An ioctl flagged with DRM_MASTER can only be invoked by the current master. A prime example is DRM_IOCTL_MODE_ATOMIC.
• Render nodes (drm_is_render_client) can only execute ioctls where DRM_RENDER_ALLOW is explicitly designated. Hence, while DRM_IOCTL_VERSION and DRM_IOCTL_PRIME_HANDLE_TO_FD work on render nodes, DRM_IOCTL_MODE_CREATE_DUMB has flags set to 0 and is rejected on render nodes.

drivers/gpu/drm/drm_auth.c - drm_master_open() (L317-335)
c

Source drivers/gpu/drm/drm_auth.c L317-L335 (Linux v6.19)

Struct Relationships Inside DRM Core

Relationships between drm_driver · drm_device · drm_minor · drm_file
Mermaid
flowchart TB
    DRIVER["struct drm_driver<br/>const template defined by driver<br/>name · driver_features · fops · ioctls · dumb_create ..."]
    DEV["struct drm_device<br/>instance of 1 physical device<br/>filelist · mode_config · vblank ..."]
    PRI["drm_minor : primary<br/>card0 · 226:0"]
    REN["drm_minor : render<br/>renderD128 · 226:128"]
    F1["drm_file<br/>Process A's open()"]
    F2["drm_file<br/>Process B's open()"]
    PF["Per-open state<br/>object_idr : GEM handle table · fbs : created framebuffers<br/>event_list : event queue · master · atomic settings"]
    DRIVER -->|"dev->driver"| DEV
    DEV --> PRI
    DEV --> REN
    PRI --> F1
    REN --> F2
    F1 --- PF

drm_driver: The Template Drivers Fill In

include/drm/drm_drv.h - struct drm_driver (L181-434)
c

Source include/drm/drm_drv.h L181-L434 (Linux v6.19)

• driver_features: Bit flags such as DRIVER_GEM, DRIVER_MODESET, DRIVER_RENDER, and DRIVER_ATOMIC. The DRM core inspects this value to decide which features to activate (for instance, DRIVER_RENDER must be present to instantiate a render node).
• fops: The file_operations for /dev/dri/cardN. Most drivers use a standard macro for this (seen below).
• ioctls, num_ioctls: Driver-specific ioctl table. The number range is 0x40 through 0xA0 (DRM_COMMAND_BASE to DRM_COMMAND_END).
• dumb_create, gem_prime_import_sg_table, etc.: Driver callbacks invoked by the core. The core handles common tasks and delegates hardware-dependent behavior to these callbacks. This pattern permeates all of DRM.

include/drm/drm_drv.h - enum drm_driver_feature (L57-170)
c

Source include/drm/drm_drv.h L57-L170 (Linux v6.19)

drm_file: One per open()

include/drm/drm_file.h - struct drm_file (L164-420)
c

Source include/drm/drm_file.h L164-L420 (Linux v6.19)

• object_idr: A table mapping user-visible GEM handles to kernel objects. This implies handles are isolated per fd (drm_file).
• event_list, pending_event_list: Queues buffering events such as page flip completion. User space retrieves them by calling read() on this fd.
• atomic, universal_planes: Client capabilities enabled via drmSetClientCap(). Atomic ioctls require these to be turned on.
• master, is_master: Indicate whether this file holds display control authority.

Source Tree Map

Code Locations

Summary

• DRM is a subsystem through which the kernel arbitrates rendering (GPU) and display (KMS); user space interfaces with it solely via ioctl, mmap, and read on /dev/dri/*.
• Device nodes use major number 226 and include primary (card) and render (renderD) nodes, with permission distinctions enforced through ioctl flags (DRM_MASTER, DRM_RENDER_ALLOW).
• The hierarchy is structured as drm_driver (template) → drm_device (device) → drm_minor (node) → drm_file (open), with the core handling common tasks and delegating hardware-specific routines to driver callbacks.