STRUCT DRM_MODE_CONFIG_FUNCS(9)

📦 version 7.3.1, in nixpkgs unstable

💅 NAME ✨

struct drm_mode_config_funcs — the basic driver-provided mode setting functions, aka the little bundle of function pointers where your driver hands over its whole "how do I do modesetting" personality 🎀

(this is out of the Kernel API Manual, bestie, that's the vibe we're in 👑)

🦋 SYNOPSIS 🦋

okay so picture the struct. It's giving "eight function pointers, all driver-supplied, all doing a specific little job." Look at her 💖

struct drm_mode_config_funcs {
    struct drm_framebuffer *(*fb_create)(struct drm_device *dev, struct
drm_file *file_priv, const struct drm_format_info *info, const struct
drm_mode_fb_cmd2 *mode_cmd);
    const struct drm_format_info *(*get_format_info)(u32 pixel_format,
u64 modifier);
    enum drm_mode_status (*mode_valid)(struct drm_device *dev, const
struct drm_display_mode *mode);
    int (*atomic_check)(struct drm_device *dev, struct drm_atomic_commit
*state);
    int (*atomic_commit)(struct drm_device *dev, struct
drm_atomic_commit *state, bool nonblock);
    struct drm_atomic_commit *(*atomic_state_alloc)(struct drm_device
*dev);
    void (*atomic_state_clear)(struct drm_atomic_commit *state);
    void (*atomic_state_free)(struct drm_atomic_commit *state);
 };

so we've got fb_create, get_format_info, mode_valid, atomic_check, atomic_commit, atomic_state_alloc, atomic_state_clear and atomic_state_free — eight icons, one struct, no filler 💅

like, write them down, screenshot them, put them in your notes app, whatever. We do not skip members in this house 🙈

bestie we are SO not done, the actual breakdown of what each of these is for is coming in the next part, so don't go anywhere 🌸🫶

✨ Members ✨

🦋 fb_create 🦋

okay so bestie, fb_create is the “make me a new framebuffer object” hook. The core does basic checks on the requested metadata, but most of that is left to the driver. See struct drm_mode_fb_cmd2 for the deets.

To validate the pixel format and modifier, drivers can use drm_any_plane_has_format to make sure at least one plane supports the requested values. Note that the driver must first determine the actual modifier used if the request doesn’t have it specified, ie. when (mode_cmd->flags & DRM_MODE_FB_MODIFIERS) == 0.

IMPORTANT: These implied modifiers for legacy userspace must be stored in struct drm_framebuffer, including all relevant metadata like drm_framebuffer.pitches and drm_framebuffer.offsets if the modifier enables additional planes beyond the fourcc pixel format code. This is required by the GETFB2 ioctl, iykyk.

If the parameters are deemed valid and the backing storage objects in the underlying memory manager all exist, then the driver allocates a new drm_framebuffer structure, subclassed to contain driver-specific information (like the internal native buffer object references). It also needs to fill out all relevant metadata, which should be done by calling drm_helper_mode_fill_fb_struct.

The initialization is finalized by calling drm_framebuffer_init, which registers the framebuffer and makes it accessible to other threads. slay.

💥 RETURNS 💥

A new framebuffer with an initial reference count of 1 or a negative error code encoded with ERR_PTR.

🎀 get_format_info 🎀

Allows a driver to return custom format information for special fb layouts (eg. ones with auxiliary compression control planes). it’s giving “special little layout needs special little format info.”

💥 RETURNS 💥

The format information specific to the given fb metadata, or NULL if none is found.

🌸 mode_valid 🌸

Device-specific validation of display modes. Can be used to reject modes that can never be supported. Only device-wide constraints can be checked here. crtc/encoder/bridge/connector-specific constraints should be checked in the .mode_valid hook for each specific object. vibe check: this hook is for the whole device, not the individual little guys.

🔥 atomic_check 🔥

the way that this is the only hook to validate an atomic modeset update… main character energy, honestly. This function must reject any modeset and state changes which the hardware or driver doesn’t support. This includes but is of course not limited to:

  • Checking that the modes, framebuffers, scaling and placement requirements and so on are within the limits of the hardware.
  • Checking that any hidden shared resources are not oversubscribed. This can be shared PLLs, shared lanes, overall memory bandwidth, display fifo space (where shared between planes or maybe even CRTCs).
  • Checking that virtualized resources exported to userspace are not oversubscribed. For various reasons it can make sense to expose more planes, crtcs or encoders than which are physically there. One example is dual-pipe operations (which generally should be hidden from userspace if when lockstepped in hardware, exposed otherwise), where a plane might need 1 hardware plane (if it’s just on one pipe), 2 hardware planes (when it spans both pipes) or maybe even shared a hardware plane with a 2nd plane (if there’s a compatible plane requested on the area handled by the other pipe).
  • Check that any transitional state is possible and that if requested, the update can indeed be done in the vblank period without temporarily disabling some functions.
  • Check any other constraints the driver or hardware might have.
  • This callback also needs to correctly fill out the drm_crtc_state in this update to make sure that drm_atomic_crtc_needs_modeset reflects the nature of the possible update and returns true if and only if the update cannot be applied without tearing within one vblank on that CRTC. The core uses that information to reject updates which require a full modeset (i.e. blanking the screen, or at least pausing updates for a substantial amount of time) if userspace has disallowed that in its request.
  • The driver also does not need to repeat basic input validation like done for the corresponding legacy entry points. The core does that before calling this hook. so you can lowkey chill on that part.

See the documentation of atomic_commit for an exhaustive list of error conditions which don’t have to be checked at in this callback.

See the documentation for struct drm_atomic_commit for how exactly an atomic modeset update is described.

Drivers using the atomic helpers can implement this hook using drm_atomic_helper_check, or one of the exported sub-functions of it.

💥 RETURNS 💥

0 on success or one of the below negative error codes:

  • -EINVAL, if any of the above constraints are violated.
  • -EDEADLK, when returned from an attempt to acquire an additional drm_modeset_lock through drm_modeset_lock.
  • -ENOMEM, if allocating additional state sub-structures failed due to lack of memory.
  • -EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted. This can either be due to a pending signal, or because the driver needs to completely bail out to recover from an exceptional situation like a GPU hang. From a userspace point, all errors are treated equally.

🫶 atomic_commit 🫶

This is the only hook to commit an atomic modeset update. The core guarantees that atomic_check has been called successfully before calling this function, and that nothing has been changed in the interim. no sneaky little changes in between, bestie.

See the documentation for struct drm_atomic_commit for how exactly an atomic modeset update is described.

Drivers using the atomic helpers can implement this hook using drm_atomic_helper_commit, or one of the exported sub-functions of it.

Nonblocking commits (as indicated with the nonblock parameter) must do any preparatory work which might result in an unsuccessful commit in the context of this callback. The only exceptions are hardware errors resulting in -EIO. But even in that case the driver must ensure that the display pipe is at least running, to avoid compositors crashing when pageflips don’t work. Anything else, specifically committing the update to the hardware, should be done without blocking the caller. For updates which do not require a modeset this must be guaranteed. fr fr, do not block the caller.

The driver must wait for any pending rendering to the new framebuffers to complete before executing the flip. It should also wait for any pending rendering from other drivers if the underlying buffer is a shared dma-buf. Nonblocking commits must not wait for rendering in the context of this callback.

An application can request to be notified when the atomic commit has completed. These events are per-CRTC and can be distinguished by the CRTC index supplied in drm_event to userspace.

The drm core will supply a struct drm_event in each CRTC’s drm_crtc_state.event. See the documentation for drm_crtc_state.event for more details about the precise semantics of this event.

NOTE: Drivers are not allowed to shut down any display pipe successfully enabled through an atomic commit on their own. Doing so can result in compositors crashing if a page flip is suddenly rejected because the pipe is off. literally do not do this.

💥 RETURNS 💥

0 on success or one of the below negative error codes:

  • -EBUSY, if a nonblocking update is requested and there is an earlier update pending. Drivers are allowed to support a queue of outstanding updates, but currently no driver supports that. Note that drivers must wait for preceding updates to complete if a synchronous update is requested, they are not allowed to fail the commit in that case.
  • -ENOMEM, if the driver failed to allocate memory. Specifically this can happen when trying to pin framebuffers, which must only be done when committing the state.
  • -ENOSPC, as a refinement of the more generic -ENOMEM to indicate that the driver has run out of vram, iommu space or similar GPU address space needed for framebuffer.
  • -EIO, if the hardware completely died.
  • -EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted. This can either be due to a pending signal, or because the driver needs to completely bail out to recover from an exceptional situation like a GPU hang. From a userspace point of view all errors are treated equally.

This list is exhaustive. Specifically this hook is not allowed to return -EINVAL (any invalid requests should be caught in atomic_check) or -EDEADLK (this function must not acquire additional modeset locks). periodt, that’s the whole list.

💜 atomic_state_alloc 💜

This optional hook can be used by drivers that want to subclass struct drm_atomic_commit to be able to track their own driver-private global state easily. If this hook is implemented, drivers must also implement atomic_state_clear and atomic_state_free. all three or none, bestie — no half-finished little trio.

Subclassing of drm_atomic_commit is deprecated in favour of using drm_private_state and drm_private_obj.

💥 RETURNS 💥

A new drm_atomic_commit on success or NULL on failure.

🦋 atomic_state_clear 🦋

This hook must clear any driver private state duplicated into the passed-in drm_atomic_commit. This hook is called when the caller encountered a drm_modeset_lock deadlock and needs to drop all already acquired locks as part of the deadlock avoidance dance implemented in drm_modeset_backoff. the deadlock avoidance dance… iconic behavior, honestly.

Any duplicated state must be invalidated since a concurrent atomic update might change it, and the drm atomic interfaces always apply updates as relative changes to the current state.

Drivers that implement this must call drm_atomic_commit_default_clear to clear common state.

Subclassing of drm_atomic_commit is deprecated in favour of using drm_private_state and drm_private_obj.

🌈 atomic_state_free 🌈

This hook needs driver private resources and the drm_atomic_commit itself. Note that the core first calls drm_atomic_commit_clear to avoid code duplicate between the clear and free hooks.

Drivers that implement this must call drm_atomic_commit_default_release to release common resources.

Subclassing of drm_atomic_commit is deprecated in favour of using drm_private_state and drm_private_obj.

🌟 Description 🌟

Some global (i.e. not per-CRTC, connector, etc) mode setting functions that involve drivers. big-picture driver mode-setting stuff, not the little per-object vibes.

🔗 SEE ALSO

ok bestie you made it to the end, so here's where you go next when you're done here 💅

  • Kernel file ./include/drm/drm_mode_config.h — that's literally the header this whole page comes from, go read it, it's right there ✨
  • struct drm_mode_config(9) — the struct that actually holds all these funcs, like the main character whose friends we've been discussing 🫶
  • drm_mode_config_init(9) — the init function, the "set everything up before you touch anything" one, lowkey the most important call in this whole saga 👑

and that's a wrap on struct drm_m...config_funcs(9), no cap 🎀 this page lives in the ./include/drm corner of the kernel tree, and the copy you're reading is dated October 2026 ⭐ go forth, configure your mode config, and slay 💖🦋🌸

📦 where this page comes from