[PATCH 5/8] rust: debugfs: Support format hooks

Matthew Maurer
2025-04-29T23:16:05Z

Rather than always using Display, allow hooking arbitrary functions to
arbitrary files. Display technically has the expressiveness to do this,
but requires a new type be declared for every different way to render
things, which can be very clumsy.

Signed-off-by: Matthew Maurer <mmaurer@google.com>
---
rust/kernel/debugfs.rs | 125 ++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 124 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/debugfs.rs b/rust/kernel/debugfs.rs
index 6c7cf7e97741b98d2c0654d01fca3de0d8047e97..2faa59d2dae44ab708cb8fca0d23f06f73a95a3a 100644
--- a/rust/kernel/debugfs.rs
+++ b/rust/kernel/debugfs.rs
@@ -11,7 +11,8 @@
use crate::seq_print;
use crate::str::CStr;
use crate::types::{ARef, AlwaysRefCounted, Opaque};
-use core::fmt::Display;
+use core::fmt;
+use core::fmt::{Display, Formatter};
use core::marker::{PhantomData, PhantomPinned};
use core::mem::ManuallyDrop;
use core::ops::Deref;
@@ -127,6 +128,35 @@ pub fn display_file<T: Display + Sized>(
unsafe { self.display_file_raw(name, data) }
}

+ /// Create a file in a DebugFS directory with the provided name, and contents from invoking `f`
+ /// on the provided reference. `f` must be a function item or a non-capturing closure, or this
+ /// will fail to compile.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use core::sync::atomic::{AtomicU32, Ordering};
+ /// # use kernel::c_str;
+ /// # use kernel::debugfs::Dir;
+ /// let dir = Dir::new(c_str!("foo"), None)?;
+ /// static MY_ATOMIC: AtomicU32 = AtomicU32::new(3);
+ /// let file = dir.fmt_file(c_str!("bar"), &MY_ATOMIC, &|val, f| {
+ /// let out = val.load(Ordering::Relaxed);
+ /// write!(f, "{out:#010x}\n")
+ /// })?;
+ /// MY_ATOMIC.store(10, Ordering::Relaxed);
+ /// # Ok::<(), Error>(())
+ /// ```
+ pub fn fmt_file<T, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result>(
+ &self,
+ name: &CStr,
+ data: &'static T,
+ f: &'static F,
+ ) -> Result<ARef<Self>> {
+ // SAFETY: As `data` lives for the static lifetime, it outlives the file
+ unsafe { self.fmt_file_raw(name, data, f) }
+ }
+
/// Creates a DebugFS file backed by the display implementation of the provided pointer.
///
/// # Safety
@@ -162,6 +192,24 @@ unsafe fn display_file_raw<T: Display + Sized>(
// owning dentry from debugfs_create_dir, so we can wrap it in an ARef
Ok(unsafe { ARef::from_raw(ptr.cast()) })
}
+
+ /// Create a file in a DebugFS directory with the provided name, and contents from invoking the
+ /// fomatter on the attached data. The attached function must be a ZST, and will cause a
+ /// compilation error if it is not.
+ ///
+ /// # Safety
+ ///
+ /// `data` must outlive the resulting file's accessibility
+ unsafe fn fmt_file_raw<T, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result>(
+ &self,
+ name: &CStr,
+ data: &T,
+ f: &'static F,
+ ) -> Result<ARef<Self>> {
+ let data_adapted = FormatAdapter::new(data, f);
+ // SAFETY: data outlives the file's accessibility, so data_adapted does too
+ unsafe { self.display_file_raw(name, data_adapted) }
+ }
}

/// Implements `open` for `file_operations` via `single_open` to fill out a `seq_file`
@@ -373,6 +421,43 @@ pub fn dir(&self, name: &CStr) -> Result<Builder<'a>> {
// SAFETY: Since 'a is a builder lifetime, we can propagate our invariants
Ok(unsafe { Builder::new(dir) })
}
+
+ /// Create a file in a DebugFS directory with the provided name, and contents from invoking `f`
+ /// on the provided reference. `f` must be a function item or a non-capturing closure, or this
+ /// will fail to compile.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use kernel::{c_str, new_mutex};
+ /// # use kernel::debugfs::{Dir, Values};
+ /// let dir = Dir::new(c_str!("foo"), None)?;
+ /// let foo = KBox::pin_init(Values::attach(new_mutex!(0), dir), GFP_KERNEL)?;
+ /// foo.as_ref().build(|value, builder| {
+ /// builder.fmt_file(c_str!("bar"), value, &|val, f| {
+ /// write!(f, "Mutex read: {}", *val.lock())
+ /// })
+ /// })?;
+ /// *foo.lock() = 23;
+ /// # Ok::<(), Error>(())
+ /// ```
+ pub fn fmt_file<T, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result>(
+ &self,
+ name: &CStr,
+ data: &'a T,
+ f: &'static F,
+ ) -> Result<()> {
+ // We forget the reference because its reference count is implicitly "owned" by the root
+ // builder, which we know will use `debugfs_remove` to clean this up. If we release the
+ // file here, it will be immediately deleted.
+ // SAFETY:
+ // Because `Builder`'s invariant says that our lifetime is how long the directory will
+ // be available, and is equivariant, `'a` will outlive the base directory, which will be
+ // torn down by `debugfs_remove` to prevent access even if an extra refcount is held
+ // somewhere.
+ core::mem::forget(unsafe { self.fmt_file_raw(name, data, f) }?);
+ Ok(())
+ }
}

impl<'a> Deref for Builder<'a> {
@@ -381,3 +466,41 @@ fn deref(&self) -> &Self::Target {
&self.inner
}
}
+
+// INVARIANT: F is inhabited
+#[repr(transparent)]
+struct FormatAdapter<T, F> {
+ inner: T,
+ _formatter: PhantomData<F>,
+}
+
+impl<T, F> FormatAdapter<T, F> {
+ fn new<'a>(inner: &'a T, _f: &'static F) -> &'a Self {
+ // SAFETY: FormatAdapater is a repr(transparent) wrapper around T, so
+ // casting a reference is legal
+ // INVARIANT: We were passed a reference to F, so it is inhabited.
+ unsafe { core::mem::transmute(inner) }
+ }
+}
+
+impl<T, F: Fn(&T, &mut Formatter<'_>) -> fmt::Result + 'static> Display for FormatAdapter<T, F> {
+ fn fmt(&self, fmt: &mut Formatter<'_>) -> fmt::Result {
+ // SAFETY: FormatAdapter<_, F> can only be constructed if F is inhabited
+ let f: &F = unsafe { materialize_zst_fmt() };
+ f(&self.inner, fmt)
+ }
+}
+
+/// # Safety
+/// The caller asserts that F is inhabited
+unsafe fn materialize_zst_fmt<F>() -> &'static F {
+ // We don't have generic_const_exprs, and const items inside the function get promoted out and
+ // lose type variables, so we need to do the old-style assert to check for ZSTness
+ [(); 1][core::mem::size_of::<F>()];
+ let zst_dangle: NonNull<F> = NonNull::dangling();
+ // SAFETY:
+ // While the pointer is dangling, it is a dangling pointer to a ZST, based on the array
+ // assertion above. The type is also inhabited, by the caller's assertion. This means
+ // we can materialize it.
+ unsafe { zst_dangle.as_ref() }
+}

--
2.49.0.901.g37484f566f-goog