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

[lyude]

We have VMap at home already, please (with your eyes) search the rest
of the kernel for it. The work for this was pushed to drm-rust-next
recently.

On Fri, 2026-07-03 at 04:00 +0100, Mike Lothian wrote:
> 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@xxxxxxxxxxxxxx>
> 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()) };
> +    }
>  }