[RFC PATCH v2 06/18] rust: drm: kms: add a Framebuffer::vmap() guard

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

Framebuffer::vmap() maps a framebuffer's plane-0 backing pages into the
kernel address space via drm_gem_fb_vmap()/vunmap(), returning an RAII
FramebufferVmap guard that unmaps on drop. Only single-CPU-visible-plane
framebuffers are supported (packed formats backed by GEM-shmem/CMA;
multi-plane YUV or an unmapped imported dma-buf return EINVAL). This is
the driver-side FbVmap guard the v1 series carried, moved into the layer
proper so every KMS driver gets it instead of hand-rolling the same
map/use/unmap dance.

Signed-off-by: Mike Lothian <mike@fireburn.co.uk>
Assisted-by: Claude:claude-sonnet-5 [Claude-Code]
---
 rust/kernel/drm/kms/framebuffer.rs | 67 +++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/drm/kms/framebuffer.rs b/rust/kernel/drm/kms/framebuffer.rs
index 54d0391388a9..1ec6779ba7de 100644
--- a/rust/kernel/drm/kms/framebuffer.rs
+++ b/rust/kernel/drm/kms/framebuffer.rs
@@ -5,7 +5,12 @@
 //! C header: [`include/drm/drm_framebuffer.h`](srctree/include/drm/drm_framebuffer.h)
 
 use super::{KmsDriver, ModeObject, Sealed};
-use crate::{drm::device::Device, types::*};
+use crate::{
+    drm::device::Device,
+    error::{code::EINVAL, to_result},
+    prelude::*,
+    types::*,
+};
 use bindings;
 use core::{marker::*, ptr};
 
@@ -67,4 +72,64 @@ pub(super) unsafe fn from_raw<'a>(ptr: *const bindings::drm_framebuffer) -> &'a
         // SAFETY: Our data layout is identical to drm_framebuffer
         unsafe { &*ptr.cast() }
     }
+
+    /// Return the raw `bindings::drm_framebuffer` for this framebuffer.
+    #[inline]
+    pub(crate) fn as_raw(&self) -> *mut bindings::drm_framebuffer {
+        self.0.get()
+    }
+
+    /// Map this framebuffer's plane-0 backing pages into the kernel address space for CPU
+    /// access, for the duration of the returned guard.
+    ///
+    /// Only framebuffers with a single, CPU-visible plane are supported (i.e. packed formats
+    /// backed by GEM-shmem/CMA memory, not multi-plane YUV or an IMPORTED dma-buf without a
+    /// CPU mapping); other cases return `EINVAL`.
+    pub fn vmap(&self) -> Result<FramebufferVmap<'_, T>> {
+        // SAFETY: `iosys_map` is POD (a pointer union plus a bool); all-zero is a valid
+        // "not mapped" value that `drm_gem_fb_vmap` overwrites for present planes.
+        let mut map: [bindings::iosys_map; 4] = unsafe { core::mem::zeroed() };
+        let mut data_map: [bindings::iosys_map; 4] = unsafe { core::mem::zeroed() };
+        // SAFETY: `self.as_raw()` is a valid, GEM-backed framebuffer for the lifetime of `self`.
+        to_result(unsafe {
+            bindings::drm_gem_fb_vmap(self.as_raw(), map.as_mut_ptr(), data_map.as_mut_ptr())
+        })?;
+        // SAFETY: `map[0]` was just filled in by `drm_gem_fb_vmap` above.
+        let vaddr = unsafe { map[0].__bindgen_anon_1.vaddr };
+        if vaddr.is_null() {
+            // SAFETY: balances the vmap just done, with the same `map`.
+            unsafe { bindings::drm_gem_fb_vunmap(self.as_raw(), map.as_mut_ptr()) };
+            return Err(EINVAL);
+        }
+        Ok(FramebufferVmap { fb: self, map, _p: PhantomData })
+    }
+}
+
+/// An RAII guard over a CPU mapping of a [`Framebuffer`]'s plane-0 backing pages, created by
+/// [`Framebuffer::vmap`].
+///
+/// The mapping is torn down when this guard is dropped, so an early return between mapping and
+/// use can never leak it.
+pub struct FramebufferVmap<'a, T: KmsDriver> {
+    fb: &'a Framebuffer<T>,
+    map: [bindings::iosys_map; 4],
+    _p: PhantomData<T>,
+}
+
+impl<'a, T: KmsDriver> FramebufferVmap<'a, T> {
+    /// Plane 0's CPU virtual base address (guaranteed non-null for the guard's lifetime).
+    #[inline]
+    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
+    }
+}
+
+impl<'a, T: KmsDriver> Drop for FramebufferVmap<'a, T> {
+    fn drop(&mut self) {
+        // SAFETY: `self.fb.as_raw()`/`self.map` are exactly the pair passed to
+        // `drm_gem_fb_vmap` in `Framebuffer::vmap`, and the mapping has not been released
+        // since.
+        unsafe { bindings::drm_gem_fb_vunmap(self.fb.as_raw(), self.map.as_mut_ptr()) };
+    }
 }
-- 
2.55.0