Commit 40ecc494 authored by Matthew Maurer's avatar Matthew Maurer Committed by Danilo Krummrich
Browse files

rust: debugfs: Add support for callback-based files 



Extends the `debugfs` API to support creating files with content
generated and updated by callbacks. This is done via the
`read_callback_file`, `write_callback_file`, and
`read_write_callback_file` methods.

These methods allow for more flexible file definition, either because
the type already has a `Writer` or `Reader` method that doesn't
do what you'd like, or because you cannot implement it (e.g. because
it's a type defined in another crate or a primitive type).

Signed-off-by: default avatarMatthew Maurer <mmaurer@google.com>
Tested-by: default avatarDirk Behme <dirk.behme@de.bosch.com>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/20250904-debugfs-rust-v11-4-7d12a165685a@google.com


[ Fix up Result<(), Error> -> Result. - Danilo ]
Signed-off-by: default avatarDanilo Krummrich <dakr@kernel.org>
parent 839dc1d1

rust/kernel/debugfs.rs

+89 −0
Original line number Diff line number Diff line
@@ -12,12 +12,16 @@ 
use crate::str::CStr;

#[cfg(CONFIG_DEBUG_FS)]

use crate::sync::Arc;

use crate::uaccess::UserSliceReader;

use core::fmt;

use core::marker::PhantomPinned;

use core::ops::Deref;



mod traits;

pub use traits::{Reader, Writer};



mod callback_adapters;

use callback_adapters::{FormatAdapter, NoWriter, WritableAdapter};

mod file_ops;

use file_ops::{FileOps, ReadFile, ReadWriteFile, WriteFile};

#[cfg(CONFIG_DEBUG_FS)]
@@ -143,6 +147,46 @@ pub fn read_only_file<'a, T, E: 'a>( 
        self.create_file(name, data, file_ops)

    }



    /// Creates a read-only file in this directory, with contents from a callback.

    ///

    /// `f` must be a function item or a non-capturing closure.

    /// This is statically asserted and not a safety requirement.

    ///

    /// # Examples

    ///

    /// ```

    /// # use core::sync::atomic::{AtomicU32, Ordering};

    /// # use kernel::c_str;

    /// # use kernel::debugfs::Dir;

    /// # use kernel::prelude::*;

    /// # let dir = Dir::new(c_str!("foo"));

    /// let file = KBox::pin_init(

    ///     dir.read_callback_file(c_str!("bar"),

    ///     AtomicU32::new(3),

    ///     &|val, f| {

    ///       let out = val.load(Ordering::Relaxed);

    ///       writeln!(f, "{out:#010x}")

    ///     }),

    ///     GFP_KERNEL)?;

    /// // Reading "foo/bar" will show "0x00000003".

    /// file.store(10, Ordering::Relaxed);

    /// // Reading "foo/bar" will now show "0x0000000a".

    /// # Ok::<(), Error>(())

    /// ```

    pub fn read_callback_file<'a, T, E: 'a, F>(

        &'a self,

        name: &'a CStr,

        data: impl PinInit<T, E> + 'a,

        _f: &'static F,

    ) -> impl PinInit<File<T>, E> + 'a

    where

        T: Send + Sync + 'static,

        F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync,

    {

        let file_ops = <FormatAdapter<T, F>>::FILE_OPS.adapt();

        self.create_file(name, data, file_ops)

    }



    /// Creates a read-write file in this directory.

    ///

    /// Reading the file uses the [`Writer`] implementation.
@@ -159,6 +203,31 @@ pub fn read_write_file<'a, T, E: 'a>( 
        self.create_file(name, data, file_ops)

    }



    /// Creates a read-write file in this directory, with logic from callbacks.

    ///

    /// Reading from the file is handled by `f`. Writing to the file is handled by `w`.

    ///

    /// `f` and `w` must be function items or non-capturing closures.

    /// This is statically asserted and not a safety requirement.

    pub fn read_write_callback_file<'a, T, E: 'a, F, W>(

        &'a self,

        name: &'a CStr,

        data: impl PinInit<T, E> + 'a,

        _f: &'static F,

        _w: &'static W,

    ) -> impl PinInit<File<T>, E> + 'a

    where

        T: Send + Sync + 'static,

        F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync,

        W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync,

    {

        let file_ops =

            <WritableAdapter<FormatAdapter<T, F>, W> as file_ops::ReadWriteFile<_>>::FILE_OPS

                .adapt()

                .adapt();

        self.create_file(name, data, file_ops)

    }



    /// Creates a write-only file in this directory.

    ///

    /// The file owns its backing data. Writing to the file uses the [`Reader`]
@@ -175,6 +244,26 @@ pub fn write_only_file<'a, T, E: 'a>( 
    {

        self.create_file(name, data, &T::FILE_OPS)

    }



    /// Creates a write-only file in this directory, with write logic from a callback.

    ///

    /// `w` must be a function item or a non-capturing closure.

    /// This is statically asserted and not a safety requirement.

    pub fn write_callback_file<'a, T, E: 'a, W>(

        &'a self,

        name: &'a CStr,

        data: impl PinInit<T, E> + 'a,

        _w: &'static W,

    ) -> impl PinInit<File<T>, E> + 'a

    where

        T: Send + Sync + 'static,

        W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync,

    {

        let file_ops = <WritableAdapter<NoWriter<T>, W> as WriteFile<_>>::FILE_OPS

            .adapt()

            .adapt();

        self.create_file(name, data, file_ops)

    }

}



#[pin_data]

rust/kernel/debugfs/callback_adapters.rs

0 → 100644
+122 −0
Original line number Diff line number Diff line 
// SPDX-License-Identifier: GPL-2.0

// Copyright (C) 2025 Google LLC.



//! Adapters which allow the user to supply a write or read implementation as a value rather

//! than a trait implementation. If provided, it will override the trait implementation.



use super::{Reader, Writer};

use crate::prelude::*;

use crate::uaccess::UserSliceReader;

use core::fmt;

use core::fmt::Formatter;

use core::marker::PhantomData;

use core::ops::Deref;



/// # Safety

///

/// To implement this trait, it must be safe to cast a `&Self` to a `&Inner`.

/// It is intended for use in unstacking adapters out of `FileOps` backings.

pub(crate) unsafe trait Adapter {

    type Inner;

}



/// Adapter to implement `Reader` via a callback with the same representation as `T`.

///

/// * Layer it on top of `WriterAdapter` if you want to add a custom callback for `write`.

/// * Layer it on top of `NoWriter` to pass through any support present on the underlying type.

///

/// # Invariants

///

/// If an instance for `WritableAdapter<_, W>` is constructed, `W` is inhabited.

#[repr(transparent)]

pub(crate) struct WritableAdapter<D, W> {

    inner: D,

    _writer: PhantomData<W>,

}



// SAFETY: Stripping off the adapter only removes constraints

unsafe impl<D, W> Adapter for WritableAdapter<D, W> {

    type Inner = D;

}



impl<D: Writer, W> Writer for WritableAdapter<D, W> {

    fn write(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {

        self.inner.write(fmt)

    }

}



impl<D: Deref, W> Reader for WritableAdapter<D, W>

where

    W: Fn(&D::Target, &mut UserSliceReader) -> Result + Send + Sync + 'static,

{

    fn read_from_slice(&self, reader: &mut UserSliceReader) -> Result {

        // SAFETY: WritableAdapter<_, W> can only be constructed if W is inhabited

        let w: &W = unsafe { materialize_zst() };

        w(self.inner.deref(), reader)

    }

}



/// Adapter to implement `Writer` via a callback with the same representation as `T`.

///

/// # Invariants

///

/// If an instance for `FormatAdapter<_, F>` is constructed, `F` is inhabited.

#[repr(transparent)]

pub(crate) struct FormatAdapter<D, F> {

    inner: D,

    _formatter: PhantomData<F>,

}



impl<D, F> Deref for FormatAdapter<D, F> {

    type Target = D;

    fn deref(&self) -> &D {

        &self.inner

    }

}



impl<D, F> Writer for FormatAdapter<D, F>

where

    F: Fn(&D, &mut Formatter<'_>) -> fmt::Result + 'static,

{

    fn write(&self, fmt: &mut Formatter<'_>) -> fmt::Result {

        // SAFETY: FormatAdapter<_, F> can only be constructed if F is inhabited

        let f: &F = unsafe { materialize_zst() };

        f(&self.inner, fmt)

    }

}



// SAFETY: Stripping off the adapter only removes constraints

unsafe impl<D, F> Adapter for FormatAdapter<D, F> {

    type Inner = D;

}



#[repr(transparent)]

pub(crate) struct NoWriter<D> {

    inner: D,

}



// SAFETY: Stripping off the adapter only removes constraints

unsafe impl<D> Adapter for NoWriter<D> {

    type Inner = D;

}



impl<D> Deref for NoWriter<D> {

    type Target = D;

    fn deref(&self) -> &D {

        &self.inner

    }

}



/// For types with a unique value, produce a static reference to it.

///

/// # Safety

///

/// The caller asserts that F is inhabited

unsafe fn materialize_zst<F>() -> &'static F {

    const { assert!(core::mem::size_of::<F>() == 0) };

    let zst_dangle: core::ptr::NonNull<F> = core::ptr::NonNull::dangling();

    // SAFETY: While the pointer is dangling, it is a dangling pointer to a ZST, based on the

    // assertion above. The type is also inhabited, by the caller's assertion. This means

    // we can materialize it.

    unsafe { zst_dangle.as_ref() }

}

rust/kernel/debugfs/file_ops.rs

+8 −0
Original line number Diff line number Diff line
@@ -2,6 +2,7 @@ 
// Copyright (C) 2025 Google LLC.



use super::{Reader, Writer};

use crate::debugfs::callback_adapters::Adapter;

use crate::prelude::*;

use crate::seq_file::SeqFile;

use crate::seq_print;
@@ -46,6 +47,13 @@ pub(crate) const fn mode(&self) -> u16 { 
    }

}



impl<T: Adapter> FileOps<T> {

    pub(super) const fn adapt(&self) -> &FileOps<T::Inner> {

        // SAFETY: `Adapter` asserts that `T` can be legally cast to `T::Inner`.

        unsafe { core::mem::transmute(self) }

    }

}



#[cfg(CONFIG_DEBUG_FS)]

impl<T> Deref for FileOps<T> {

    type Target = bindings::file_operations;