Speaker
Description
Problem Statement
Today, when an atomic commit fails, userspace typically receives only a generic error such as -EINVAL, with no indication of the underlying cause. As a result, compositors cannot determine why the commit failed or apply appropriate corrective actions. A common example is a bandwidth-related failure, where the requested bpc exceeds the available link bandwidth. Since the failure reason is not propagated to userspace, the compositor must rely on kernel logs to diagnose the issue and infer that the bpc should be reduced before retrying the atomic commit.
Solution
The goal is to provide compositors with sufficient information to understand why an atomic commit failed and enable targeted fallback mechanisms. In the bandwidth example above, the kernel reports the reason for the failure, allowing the compositor to identify the bandwidth limitation, reduce the bpc accordingly, and retry the atomic commit with a more suitable configuration.
The proposed DRM/KMS UAPI for atomic commit failure reporting repurposes the reserved u64 field in struct drm_mode_atomic, passed as part of the atomic_commit ioctl, to return detailed failure information to userspace. As part of the compositor implementation, this information is decoded to identify the specific reason for an atomic commit failure. Based on the reported failure, the compositor will implement targeted fallback logic and intelligently retry the atomic commit with a more suitable configuration wherever possible.
Atomic Commit Failure Codes Reported by Kernel
The current implementation defines the following common atomic commit failure codes, with the flexibility to extend the list as new failure scenarios are identified.
• DRM_MODE_ATOMIC_UNSPECIFIED_ERROR – Generic error when no specific failure reason is available.
• DRM_MODE_ATOMIC_INVALID_API_USAGE – The atomic commit failed due to invalid use of the DRM atomic API (e.g., missing atomic capability, invalid flags, or incompatible options).
• DRM_MODE_ATOMIC_NEED_FULL_MODESET – The requested update requires a full modeset.
• DRM_MODE_ATOMIC_ASYNC_PROP_CHANGED – A property was modified during an asynchronous page flip.
• DRM_MODE_ATOMIC_SCANOUT_BW – The requested display configuration exceeds the available scanout bandwidth (e.g., resolution, refresh rate, or color depth).
• DRM_MODE_ATOMIC_CONNECTOR_BW – The requested configuration exceeds the available bandwidth of the display connector or link.
• DRM_MODE_ATOMIC_PIPE_BW – The display pipeline cannot support the requested configuration due to pipe or scaler limitations.
• DRM_MODE_ATOMIC_MEMORY_DOMAIN – The requested configuration exceeds memory or bandwidth constraints not covered by the other bandwidth-related errors.
• DRM_MODE_ATOMIC_SPEC_VIOLATION – The requested configuration violates a hardware-specific capability or specification limitation.
References
2025 Display Next Hackfest https://hackmd.io/f3bDn3kyRUalLn4LbMfCVQ#Commit-Failure-Feedback
Kernel https://patchwork.freedesktop.org/series/152275/
Mutter https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/5022
IGT https://patchwork.freedesktop.org/series/153330/
Libdrm https://gitlab.freedesktop.org/mesa/libdrm/-/merge_requests/450
KWIN https://invent.kde.org/plasma/kwin/-/merge_requests/8991
| GSoC, EVoC or Outreachy | No |
|---|---|
| Code of Conduct | Yes |
| In-person or virtual presentation | Virtual |
