[RFC PATCH v2 12/18] rust: drm: framebuffer: add geometry accessors, refcounting and a byte-slice vmap

[Mike Lothian <mike@fireburn.co.uk>]

A driver that reads back a framebuffer's pixels (e.g. DisplayLink's evdi, whose
scanout is pulled by userspace via a GRABPIX ioctl rather than pushed to
hardware) needs three things the Framebuffer binding did not provide:

  - width()/height()/pitch() geometry accessors;

  - reference counting, so the framebuffer flipped in during an atomic commit can
    be held (ARef<Framebuffer>) and mapped later from an ioctl -- add
    AlwaysRefCounted backed by new drm_framebuffer_get()/put() helpers;

  - a way to read the mapping without unsafe in the driver -- add
    FramebufferVmap::as_bytes(), returning the plane-0 mapping as a &[u8] of
    height * pitch(0) bytes, valid for the guard's lifetime.

Signed-off-by: Mike Lothian <mike@fireburn.co.uk>
Assisted-by: Claude:claude-opus-4-8 [Claude-Code]
---
 rust/helpers/drm/drm.c             |  1 +
 rust/helpers/drm/framebuffer.c     | 13 +++++++
 rust/kernel/drm/kms/framebuffer.rs | 54 ++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 rust/helpers/drm/framebuffer.c

diff --git a/rust/helpers/drm/drm.c b/rust/helpers/drm/drm.c
index 5d700d75c0c9..24c531841ba1 100644
--- a/rust/helpers/drm/drm.c
+++ b/rust/helpers/drm/drm.c
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
 #include "atomic.c"
+#include "framebuffer.c"
 #include "gem.c"
 #include "vma_manager.c"
 #include "vblank.c"
diff --git a/rust/helpers/drm/framebuffer.c b/rust/helpers/drm/framebuffer.c
new file mode 100644
index 000000000000..280538ffb82c
--- /dev/null
+++ b/rust/helpers/drm/framebuffer.c
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <drm/drm_framebuffer.h>
+
+void rust_helper_drm_framebuffer_get(struct drm_framebuffer *fb)
+{
+	drm_framebuffer_get(fb);
+}
+
+void rust_helper_drm_framebuffer_put(struct drm_framebuffer *fb)
+{
+	drm_framebuffer_put(fb);
+}
diff --git a/rust/kernel/drm/kms/framebuffer.rs b/rust/kernel/drm/kms/framebuffer.rs
index 1ec6779ba7de..c7089b12d0d1 100644
--- a/rust/kernel/drm/kms/framebuffer.rs
+++ b/rust/kernel/drm/kms/framebuffer.rs
@@ -9,6 +9,7 @@
     drm::device::Device,
     error::{code::EINVAL, to_result},
     prelude::*,
+    sync::aref::AlwaysRefCounted,
     types::*,
 };
 use bindings;
@@ -46,6 +47,23 @@ fn raw_mode_obj(&self) -> *mut bindings::drm_mode_object {
 }
 
 // SAFETY: References to framebuffers are safe to be accessed from any thread
+// SAFETY: `struct drm_framebuffer` is refcounted via `drm_framebuffer_get()`/`drm_framebuffer_put()`,
+// which are the correct increment/decrement operations for it.
+unsafe impl<T: KmsDriver> AlwaysRefCounted for Framebuffer<T> {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The existence of a shared reference guarantees the refcount is non-zero.
+        unsafe { bindings::drm_framebuffer_get(self.as_raw()) };
+    }
+
+    #[inline]
+    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
+        // SAFETY: The safety requirements guarantee the refcount is non-zero; `Framebuffer<T>` has
+        // the same layout as `struct drm_framebuffer`.
+        unsafe { bindings::drm_framebuffer_put(obj.as_ptr().cast()) };
+    }
+}
+
 unsafe impl<T: KmsDriver> Send for Framebuffer<T> {}
 // SAFETY: References to framebuffers are safe to be accessed from any thread
 unsafe impl<T: KmsDriver> Sync for Framebuffer<T> {}
@@ -79,6 +97,30 @@ pub(crate) fn as_raw(&self) -> *mut bindings::drm_framebuffer {
         self.0.get()
     }
 
+    /// The framebuffer's width in pixels.
+    #[inline]
+    pub fn width(&self) -> u32 {
+        // SAFETY: `as_raw()` is a valid framebuffer; `width` is set at creation and immutable.
+        unsafe { (*self.as_raw()).width }
+    }
+
+    /// The framebuffer's height in pixels.
+    #[inline]
+    pub fn height(&self) -> u32 {
+        // SAFETY: `as_raw()` is a valid framebuffer; `height` is set at creation and immutable.
+        unsafe { (*self.as_raw()).height }
+    }
+
+    /// The byte stride (pitch) of colour plane `index`.
+    ///
+    /// A `drm_framebuffer` has at most four colour planes; `index` is masked into `0..=3`.
+    #[inline]
+    pub fn pitch(&self, index: usize) -> u32 {
+        // SAFETY: `pitches` has four elements; `index & 3` keeps the access in bounds. The pitches
+        // are set at creation and immutable.
+        unsafe { (*self.as_raw()).pitches[index & 3] }
+    }
+
     /// Map this framebuffer's plane-0 backing pages into the kernel address space for CPU
     /// access, for the duration of the returned guard.
     ///
@@ -123,6 +165,18 @@ pub fn as_ptr(&self) -> *const u8 {
         // SAFETY: set non-null in `Framebuffer::vmap`; `vaddr` is the active union member.
         (unsafe { self.map[0].__bindgen_anon_1.vaddr }) as *const u8
     }
+
+    /// Plane 0's mapped pixels as a byte slice.
+    ///
+    /// The slice covers `height * pitch(0)` bytes — the full extent of colour plane 0 — and is
+    /// valid for the guard's lifetime. This lets callers read the scanout buffer without `unsafe`.
+    #[inline]
+    pub fn as_bytes(&self) -> &[u8] {
+        let len = self.fb.height() as usize * self.fb.pitch(0) as usize;
+        // SAFETY: `drm_gem_fb_vmap` mapped colour plane 0 contiguously at `as_ptr()` for at least
+        // `height * pitch(0)` bytes, and the mapping is live for `self`'s lifetime.
+        unsafe { core::slice::from_raw_parts(self.as_ptr(), len) }
+    }
 }
 
 impl<'a, T: KmsDriver> Drop for FramebufferVmap<'a, T> {
-- 
2.55.0