STRUCT DRM_PRIVATE_OBJ(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct drm_private_obj(9)

okay so this is a page from the Kernel API Manual and honestly bestie, it's giving "driver private atomic object" realness ✨ — like the glow-up base struct that your driver's own private state sits on top of. Let's get into it 🫶

🌸 NAME 🌸

struct drm_private_obj — the base struct for a driver private atomic object. no cap, that's literally what it is 💅

✨ SYNOPSIS ✨

struct drm_private_obj {
    struct drm_device *dev;
    struct list_head head;
    struct drm_modeset_lock lock;
    struct drm_private_state *state;
    const struct drm_private_state_funcs *funcs;
 };

🎀 Members 🎀

  • dev — the parent DRM device. the whole fam, basically 💖
  • head — list entry used to attach a private object to a drm_device (it gets queued to drm_mode_config.privobj_list). lowkey it's how your object gets found in the group chat 📋
  • lock — modeset lock that protects the state object. keep it safe bestie 🔒
  • state — the current atomic state for this driver private object. this is the main character state state ✨
  • funcs — functions to manipulate the state of this driver private object, see drm_private_state_funcs. the little helper squad 🧚

🦋 Description 🦋

A driver private object is initialized by calling drm_atomic_private_obj_init and cleaned up by calling drm_atomic_private_obj_fini. that's the whole life cycle, birth and fini, iconic 😌

Currently it only tracks the state update functions and the opaque driver private state itself, but in the future it might also track which drm_modeset_lock is required to duplicate and update this object's state. so like, watch this space 👀

All private objects must be initialized before the DRM device they are attached to is registered to the DRM subsystem (that's the call to drm_dev_register), and they should stay around until this DRM device is unregistered (the call to drm_dev_unregister). In other words — and say it with me — private objects' lifetime is tied to the DRM device lifetime 🔗. This implies that:

  1. all calls to drm_atomic_private_obj_init must be done before calling drm_dev_register
  2. all calls to drm_atomic_private_obj_fini must be done after calling drm_dev_unregister

If that private object is used to store a state shared by multiple CRTCs, proper care must be taken to ensure that non-blocking commits are properly ordered, to avoid a use-after-free issue 💀 fr fr, this part is not a vibe.

Indeed — assuming a sequence of two non-blocking drm_atomic_commit on two different drm_crtc using different drm_plane and drm_connector, so with no resources shared, there's no guarantee on which commit is going to happen first. However, the second drm_atomic_commit will consider the first drm_private_obj its old state, and will be in charge of freeing it whenever the second drm_atomic_commit is done.

If the first drm_atomic_commit happens after it, it will consider its drm_private_obj the new state and will be likely to access it — resulting in an access to a freed memory region 😭 so yeah. that's the bad ending.

Drivers should store (and get a reference to) the drm_crtc_commit structure in our private state in drm_mode_config_helper_funcs.atomic_commit_setup, and then wait for that commit to complete as the first step of drm_mode_config_helper_funcs.atomic_commit_tail, similar to drm_atomic_helper_wait_for_dependencies. 🔥 do this, bestie, please.

🌈 SEE ALSO 🌈

that's the whole thing bestie, go forth and manage your private objects responsibly 💜

source: ./include/drm · dated October 2026 · struct drm_private_obj(9) — mwah, catch you in the next manpage 🎀💖

📦 where this page comes from