Linux DRM Atomic KMS: Plane State, Test Commits, and Page Flips

Linux Kernel Mode Setting (KMS) represents display hardware as connectors, encoders, CRTCs, planes, and framebuffers. Atomic modesetting treats a proposed change across these objects as one state transaction. The driver validates whether the combined state can be programmed, then commits it subject to synchronization and hardware constraints. This differs from changing a connector, plane, or mode independently and hoping the rest of the display pipeline remains compatible.

An atomic commit that returns success means the kernel accepted or queued the requested state according to the API. It does not prove that the monitor displayed the expected pixels, that a compositor presented the correct frame, or that a physical connector is reliable. Diagnose object state, commit completion, hotplug, synchronization, and output separately.

Map the KMS object graph

A connector represents an output endpoint such as a display port or panel connection. An encoder routes a display signal, a CRTC generates a scanout stream, and planes contribute framebuffer layers to that stream. A framebuffer describes memory and pixel layout; it is not the buffer contents themselves. Hardware may expose multiple planes and impose format, scaling, rotation, bandwidth, or routing restrictions.

Inspect devices and kernel logs before using a display-setting tool:

ls -l /dev/dri/
ls -l /sys/class/drm/
journalctl -k -b --no-pager

The card index is not a stable physical identity when systems have multiple GPUs. Correlate it with the PCI or platform device path and driver. The connector status file reports a kernel view of connection state, not proof that the entire cable path or monitor is healthy.

Userspace normally discovers object IDs and properties through DRM ioctls, then builds an atomic request. IDs can change after driver reload or device recreation. Applications should enumerate current resources instead of persisting object IDs as configuration.

Build and test the complete state

An atomic request contains changes to one or more object properties. The kernel validates the proposed state across affected planes, CRTCs, and connectors. A TEST_ONLY commit asks the driver to check whether the configuration is possible without applying it. That is valuable for compositor planning, but success does not guarantee the real commit will later succeed if hotplug, memory, device state, or another commit changes between test and apply.

The request must satisfy hardware constraints. A plane’s source rectangle and destination rectangle, pixel format, modifier, rotation, scaling, z-position, and CRTC assignment may be jointly limited. A framebuffer may be valid for rendering but unsupported for scanout on a particular plane. Device-specific modifiers describe memory layout and cannot be replaced with a guessed linear interpretation.

When a request fails, preserve the property values and errno. An invalid argument can indicate unsupported combination; busy or retry-style outcomes can reflect concurrent state changes or synchronization; allocation failures can appear separately. Do not reduce every failure to “mode unsupported.” Try a minimal state on a test display, then add one plane or property at a time.

Atomicity does not mean instantaneous pixels

Atomic means a coordinated state transition as defined by the driver and KMS API, typically synchronized to a display update boundary where possible. It does not mean all pixels change at one physical instant or that every hardware feature is double-buffered. Some modesets require disabling and re-enabling a pipeline; a nonblocking commit can return before the hardware transition completes.

Page-flip or atomic completion events allow userspace to learn that a commit reached its completion point. The event is not a monitor acknowledgment. A compositor should retain the framebuffer and associated resources until the commit no longer uses them. Releasing memory immediately after queueing a nonblocking commit can cause use-after-free in userspace or invalid display memory if ownership rules are violated.

Explicit or implicit synchronization fences coordinate rendering with scanout. If a producer has not finished writing a framebuffer, the display can show stale or torn content unless synchronization is correct. A successful commit that waits on a fence may complete later than expected. Track fence dependencies and event timestamps rather than assuming rendering completion equals scanout start.

Hotplug, mode changes, and rollback

Connector state can change during a commit. A monitor unplug, display link retraining, GPU reset, suspend, or dock transition can invalidate the resource graph. Userspace should handle hotplug notifications, re-enumerate connectors and modes, and reject stale object IDs. Do not blindly replay an old atomic request after topology changes.

A modeset changes more than a framebuffer. It may alter timing, clocks, link rate, color format, and hardware routing. Drivers can reject a mode because of bandwidth or shared resources even if each connector supports it individually. A test-only commit is useful before switching, but the application still needs a rollback path if the real commit fails or the display goes blank.

For remote systems, keep a recovery path that does not depend on the display being active. A failed modeset can leave a headless service running while local console access disappears. Do not apply experimental KMS state over the only remote administration channel without an automatic rollback and out-of-band console.

Observe the actual pipeline

Tools such as drm_info or modetest can list objects and properties when installed and when permissions allow. Their options and output depend on versions and drivers. Collect the object graph, modes, plane formats, modifier support, property values, driver, kernel, connector status, and commit error. Avoid changing modes during inventory.

Correlate DRM logs with compositor logs, application frame timing, GPU reset messages, and monitor link behavior. A blank panel may originate from backlight or panel power sequencing, not the KMS plane update. A visual artifact can originate in rendering, synchronization, memory layout, or cable transport. Screenshot capture may use a different path than direct scanout and does not prove the physical display link is correct.

Record whether the compositor uses direct scanout, overlays, color-management properties, or a fallback composition path. When possible, reproduce with a minimal atomic test that uses a known-good framebuffer and one connector. A test application should not compete with the compositor for the same display resources.

Color properties, gamma or degamma lookup tables, content-protection state, and color pipeline blocks can be part of the atomic state on capable hardware. A display can commit successfully while its output differs because the application selected a different color encoding, range, or transfer function. Compare the pixel format and color properties with the monitor’s reported mode and the application’s render target rather than treating every washed-out or clipped image as a plane-placement bug.

Atomic state also interacts with bandwidth and shared resources. Two individually valid CRTCs may not be active simultaneously if their combined clocks, memory bandwidth, or shared PLL requirements exceed the device’s limits. Driver validation can reject the combined state even when a test-only commit passed earlier. Keep a minimal known-good configuration, then add outputs and planes one at a time to find the boundary.

When a nonblocking commit is queued, userspace needs to match its completion event to the request and retain referenced objects until the completion rule permits reuse. A lost event or compositor crash should not cause the application to free a buffer merely because a timeout elapsed. Re-query current state, handle device reset, and avoid reusing resources until ownership is established. Capture event timestamps and commit IDs where supported so delayed presentation is distinguishable from a failed modeset.

Acceptance criteria

A reliable display transition enumerates current resources, checks a test-only state where useful, commits a fully specified state, waits for completion, and retains buffers until safe release. It handles hotplug and reset by rebuilding object state, reports precise errno and property context, and can roll back without losing remote access.

Test the target GPU, connector, monitor, kernel, format, modifier, multi-plane composition, suspend/resume, and unplug/replug. Measure commit-to-event latency and visible output separately. Atomic KMS is a transaction over display hardware state; its operational value comes from validating that entire transaction instead of issuing a sequence of partially applied changes.

Related:

Sources: