STRUCT DRM_FRAMEBUFFER(9)

💖 struct drm_framebuffer(9) 💖

okay so bestie, welcome to the Kernel API Manual — this is the page for struct drm_framebuffer(9), aka the frame buffer object that lowkey runs the whole modesetting vibe ✨. it’s giving “I hold pixels, refcounts, and main-character energy,” and honestly? iconic.

---

🌸 NAME 🌸

struct drm_framebuffer — frame buffer object 💅

---

✨ SYNOPSIS ✨

       struct drm_framebuffer {
           struct drm_device *dev;
           struct list_head head;
           struct drm_mode_object base;
           char comm[TASK_COMM_LEN];
           const struct drm_format_info *format;
           const struct drm_framebuffer_funcs *funcs;
           unsigned int pitches[DRM_FORMAT_MAX_PLANES];
           unsigned int offsets[DRM_FORMAT_MAX_PLANES];
           uint64_t modifier;
           unsigned int width;
           unsigned int height;
           int flags;
           unsigned int internal_flags;
           struct list_head filp_head;
           struct drm_gem_object *obj[DRM_FORMAT_MAX_PLANES];
        };

---

💅 Members 💅

• dev — the DRM device this framebuffer belongs to. home base 🏠
• head — sits on drm_mode_config.fb_list, and access is protected by drm_mode_config.fb_lock. 🔒
• base — the base modeset object structure, and it contains the reference count. that’s where the refcount lives, periodt 💅
• comm — the name of the process allocating the fb; it’s used for fb dumping. 🫶
• format — framebuffer format information. slay 💖
• funcs — the framebuffer vfunc table. 🎀
• pitches — line stride per buffer. for a userspace-created object, this is copied from drm_mode_fb_cmd2. ✨
• offsets — offset from buffer start to the actual pixel data, in bytes, per buffer. for a userspace-created object, this is copied from drm_mode_fb_cmd2. 💫

okay bestie, listen: this is a linear offset, and it does not take tiling or buffer layout per modifier into account. it’s meant to be used when the actual pixel data for this framebuffer plane starts at an offset, e.g. when multiple planes are allocated within the same backing storage buffer object. for tiled layouts this generally means its offsets must at least be tile-size aligned, but hardware often has stricter requirements. 😭 and do not use this to specify x/y pixel offsets into the buffer data (even for linear buffers). specifying an x/y pixel offset is instead done through the source rectangle in struct drm_plane_state. no cap.

• modifier — data layout modifier. this describes tiling, or also special layouts (like compression) of auxiliary buffers. for a userspace-created object, this is copied from drm_mode_fb_cmd2. 🌈
• width — logical width of the visible area of the framebuffer, in pixels. 📐
• height — logical height of the visible area of the framebuffer, in pixels. 📏
• flags — framebuffer flags like DRM_MODE_FB_INTERLACED or DRM_MODE_FB_MODIFIERS. 🚩
• internal_flags — framebuffer flags like DRM_FRAMEBUFFER_HAS_HANDLE_REF. 🔥
• filp_head — placed on drm_file.fbs, protected by drm_file.fbs_lock. 🔐
• obj — GEM objects backing the framebuffer, one per plane (optional). this is used by the GEM framebuffer helpers, see e.g. drm_gem_fb_create. 🧚

---

🌸 Description 🌸

so the fb is refcounted for the benefit of driver internals — for example, some hardware disables a CRTC/plane asynchronously, and scanout does not actually complete until the next vblank. so some cleanup (like releasing the reference(s) on the backing GEM bo(s)) should be deferred. in cases like this, the driver would like to hold a ref to the fb even though it has already been removed from userspace perspective. see drm_framebuffer_get and drm_framebuffer_put. 🫶

the refcount is stored inside the mode object base. and that’s the tea 💜

---

🦋 SEE ALSO 🦋

• Kernel file ./include/drm/drm_framebuffer.h struct
• drm_framebuffer_funcs(9)
• drm_framebuffer_get(9)
• drm_framebuffer_put(9)
• drm_framebuffer_read_refcount(9)
• drm_framebuffer_assign(9)
• struct drm_afbc_framebuffer(9)

---

source/version: ./include/drm • date: October 2026 • page: struct drm_framebuffer(9) in the Kernel API Manual — mwah 💋✨