Allows creation of files for references that live forever and lack
metadata through the `Display` implementation.
The reference must live forever because we do not have a maximum
lifetime for the file we are creating.
The `Display` implementation is used because `seq_printf` needs to route
through `%pA`, which in turn routes through Arguments. A more generic
API is provided later in the series, implemented in terms of this one.
Signed-off-by: Matthew Maurer <mmaurer@google.com>
---
rust/kernel/debugfs.rs | 132 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 132 insertions(+)
diff --git a/rust/kernel/debugfs.rs b/rust/kernel/debugfs.rs
index ed1aba6d700d064dbfd7e923dbcbf80b9acf5361..4a138717bd0fdb320033d07446a192c9f520a17b 100644
--- a/rust/kernel/debugfs.rs
+++ b/rust/kernel/debugfs.rs
@@ -6,6 +6,7 @@
//! C header: [`include/linux/debugfs.h`](srctree/include/linux/debugfs.h)
use crate::str::CStr;
+use core::fmt::Display;
use core::marker::PhantomData;
/// Owning handle to a DebugFS entry.
@@ -46,6 +47,19 @@ unsafe fn from_ptr(entry: *mut bindings::dentry) -> Self {
}
}
+ /// Constructs a new DebugFS [`Entry`] from the underlying pointer.
+ ///
+ /// # Safety
+ ///
+ /// The pointer must either be an error code, `NULL`, or represent a transfer of ownership of a
+ /// live DebugFS directory.
+ #[cfg(not(CONFIG_DEBUG_FS))]
+ unsafe fn from_ptr(_entry: *mut bindings::dentry) -> Self {
+ Self {
+ _phantom: PhantomData,
+ }
+ }
+
#[cfg(not(CONFIG_DEBUG_FS))]
fn new() -> Self {
Self {
@@ -124,6 +138,57 @@ pub fn subdir<'b>(&'b self, name: &CStr) -> Dir<'b> {
Dir::create(name, Some(self))
}
+ /// Create a file in a DebugFS directory with the provided name, and contents from invoking
+ /// [`Display::fmt`] on the provided reference.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// # use kernel::c_str;
+ /// # use kernel::debugfs::Dir;
+ /// let dir = Dir::new(c_str!("my_debugfs_dir"));
+ /// dir.display_file(c_str!("foo"), &200);
+ /// // "my_debugfs_dir/foo" now contains the number 200.
+ /// ```
+ pub fn display_file<'b, T: Display + Sized>(
+ &'b self,
+ name: &CStr,
+ data: &'static T,
+ ) -> File<'b> {
+ // SAFETY:
+ // * `name` is a NUL-terminated C string, living across the call, by `CStr` invariant.
+ // * `parent` is a live `dentry` since we have a reference to it.
+ // * `vtable` is all stock `seq_file` implementations except for `open`.
+ // `open`'s only requirement beyond what is provided to all open functions is that the
+ // inode's data pointer must point to a `T` that will outlive it, which we know because
+ // we have a static reference.
+ #[cfg(CONFIG_DEBUG_FS)]
+ let ptr = unsafe {
+ bindings::debugfs_create_file_full(
+ name.as_char_ptr(),
+ 0o444,
+ self.0.as_ptr(),
+ data as *const _ as *mut _,
+ core::ptr::null(),
+ &<T as DisplayFile>::VTABLE,
+ )
+ };
+
+ #[cfg(not(CONFIG_DEBUG_FS))]
+ let ptr = {
+ // Mark parameters used
+ let (_, _) = (name, data);
+ crate::error::code::ENODEV.to_ptr()
+ };
+
+ // SAFETY: `debugfs_create_file_full` either returns an error code or a legal
+ // dentry pointer, and without `CONFIG_DEBUGFS` we return an error pointer, so
+ // `Entry::from_ptr` is safe to call here.
+ let entry = unsafe { Entry::from_ptr(ptr) };
+
+ File(entry)
+ }
+
/// Create a new directory in DebugFS at the root.
///
/// # Examples
@@ -137,3 +202,70 @@ pub fn new(name: &CStr) -> Self {
Dir::create(name, None)
}
}
+/// Handle to a DebugFS file.
+#[repr(transparent)]
+pub struct File<'a>(Entry<'a>);
+
+#[cfg(CONFIG_DEBUG_FS)]
+mod helpers {
+ use crate::seq_file::SeqFile;
+ use crate::seq_print;
+ use core::fmt::Display;
+
+ /// Implements `open` for `file_operations` via `single_open` to fill out a `seq_file`.
+ ///
+ /// # Safety
+ ///
+ /// * `inode`'s private pointer must point to a value of type `T` which will outlive the `inode`
+ /// and will not be mutated during this call.
+ /// * `file` must point to a live, not-yet-initialized file object.
+ pub(crate) unsafe extern "C" fn display_open<T: Display>(
+ inode: *mut bindings::inode,
+ file: *mut bindings::file,
+ ) -> i32 {
+ // SAFETY:
+ // * `file` is acceptable by caller precondition.
+ // * `print_act` will be called on a `seq_file` with private data set to the third argument,
+ // so we meet its safety requirements.
+ // * The `data` pointer passed in the third argument is a valid `T` pointer that outlives
+ // this call by caller preconditions.
+ unsafe { bindings::single_open(file, Some(display_act::<T>), (*inode).i_private) }
+ }
+
+ /// Prints private data stashed in a seq_file to that seq file.
+ ///
+ /// # Safety
+ ///
+ /// `seq` must point to a live `seq_file` whose private data is a live pointer to a `T` which is
+ /// not being mutated.
+ pub(crate) unsafe extern "C" fn display_act<T: Display>(
+ seq: *mut bindings::seq_file,
+ _: *mut core::ffi::c_void,
+ ) -> i32 {
+ // SAFETY: By caller precondition, this pointer is live, points to a value of type `T`, and
+ // is not being mutated.
+ let data = unsafe { &*((*seq).private as *mut T) };
+ // SAFETY: By caller precondition, `seq_file` points to a live `seq_file`, so we can lift
+ // it.
+ let seq_file = unsafe { SeqFile::from_raw(seq) };
+ seq_print!(seq_file, "{}", data);
+ 0
+ }
+
+ // Work around lack of generic const items.
+ pub(crate) trait DisplayFile: Display + Sized {
+ const VTABLE: bindings::file_operations = bindings::file_operations {
+ read: Some(bindings::seq_read),
+ llseek: Some(bindings::seq_lseek),
+ release: Some(bindings::single_release),
+ open: Some(display_open::<Self> as _),
+ // SAFETY: `file_operations` supports zeroes in all fields.
+ ..unsafe { core::mem::zeroed() }
+ };
+ }
+
+ impl<T: Display + Sized> DisplayFile for T {}
+}
+
+#[cfg(CONFIG_DEBUG_FS)]
+use helpers::*;
--
2.49.0.967.g6a0df3ecc3-googOn Tue May 6, 2025 at 1:51 AM CEST, Matthew Maurer wrote:
> diff --git a/rust/kernel/debugfs.rs b/rust/kernel/debugfs.rs
> index ed1aba6d700d064dbfd7e923dbcbf80b9acf5361..4a138717bd0fdb320033d07446a192c9f520a17b 100644
> --- a/rust/kernel/debugfs.rs
> +++ b/rust/kernel/debugfs.rs
> @@ -46,6 +47,19 @@ unsafe fn from_ptr(entry: *mut bindings::dentry) -> Self {
> }
> }
>
> + /// Constructs a new DebugFS [`Entry`] from the underlying pointer.
> + ///
> + /// # Safety
> + ///
> + /// The pointer must either be an error code, `NULL`, or represent a transfer of ownership of a
> + /// live DebugFS directory.
> + #[cfg(not(CONFIG_DEBUG_FS))]
> + unsafe fn from_ptr(_entry: *mut bindings::dentry) -> Self {
> + Self {
Why duplicate this function and not just do this to the existing
function?:
unsafe fn from_ptr(entry: *mut bindings::dentry) -> Self {
#[cfg(not(CONFIG_DEBUG_FS))]
let _ = entry;
Self {
#[cfg(CONFIG_DEBUG_FS)]
entry,
_phantom: PhantomData,
}
}
> + _phantom: PhantomData,
> + }
> + }
> +
> #[cfg(not(CONFIG_DEBUG_FS))]
> fn new() -> Self {
> Self {
> @@ -124,6 +138,57 @@ pub fn subdir<'b>(&'b self, name: &CStr) -> Dir<'b> {
> Dir::create(name, Some(self))
> }
>
> + /// Create a file in a DebugFS directory with the provided name, and contents from invoking
> + /// [`Display::fmt`] on the provided reference.
> + ///
> + /// # Examples
> + ///
> + /// ```
> + /// # use kernel::c_str;
> + /// # use kernel::debugfs::Dir;
> + /// let dir = Dir::new(c_str!("my_debugfs_dir"));
> + /// dir.display_file(c_str!("foo"), &200);
> + /// // "my_debugfs_dir/foo" now contains the number 200.
> + /// ```
> + pub fn display_file<'b, T: Display + Sized>(
> + &'b self,
> + name: &CStr,
> + data: &'static T,
> + ) -> File<'b> {
> + // SAFETY:
> + // * `name` is a NUL-terminated C string, living across the call, by `CStr` invariant.
> + // * `parent` is a live `dentry` since we have a reference to it.
> + // * `vtable` is all stock `seq_file` implementations except for `open`.
> + // `open`'s only requirement beyond what is provided to all open functions is that the
> + // inode's data pointer must point to a `T` that will outlive it, which we know because
> + // we have a static reference.
> + #[cfg(CONFIG_DEBUG_FS)]
> + let ptr = unsafe {
> + bindings::debugfs_create_file_full(
> + name.as_char_ptr(),
> + 0o444,
> + self.0.as_ptr(),
> + data as *const _ as *mut _,
> + core::ptr::null(),
> + &<T as DisplayFile>::VTABLE,
> + )
> + };
> +
> + #[cfg(not(CONFIG_DEBUG_FS))]
> + let ptr = {
> + // Mark parameters used
> + let (_, _) = (name, data);
`let _ = (name, data);` should be sufficient.
> + crate::error::code::ENODEV.to_ptr()
> + };
> +
> + // SAFETY: `debugfs_create_file_full` either returns an error code or a legal
> + // dentry pointer, and without `CONFIG_DEBUGFS` we return an error pointer, so
> + // `Entry::from_ptr` is safe to call here.
> + let entry = unsafe { Entry::from_ptr(ptr) };
> +
> + File(entry)
> + }
> +
> /// Create a new directory in DebugFS at the root.
> ///
> /// # Examples
> @@ -137,3 +202,70 @@ pub fn new(name: &CStr) -> Self {
> Dir::create(name, None)
> }
> }
> +/// Handle to a DebugFS file.
> +#[repr(transparent)]
> +pub struct File<'a>(Entry<'a>);
> +
> +#[cfg(CONFIG_DEBUG_FS)]
> +mod helpers {
> + use crate::seq_file::SeqFile;
> + use crate::seq_print;
> + use core::fmt::Display;
> +
> + /// Implements `open` for `file_operations` via `single_open` to fill out a `seq_file`.
> + ///
> + /// # Safety
> + ///
> + /// * `inode`'s private pointer must point to a value of type `T` which will outlive the `inode`
> + /// and will not be mutated during this call.
> + /// * `file` must point to a live, not-yet-initialized file object.
> + pub(crate) unsafe extern "C" fn display_open<T: Display>(
Why do these functions need to be pub?
---
Cheers,
Benno
> + inode: *mut bindings::inode,
> + file: *mut bindings::file,
> + ) -> i32 {
> + // SAFETY:
> + // * `file` is acceptable by caller precondition.
> + // * `print_act` will be called on a `seq_file` with private data set to the third argument,
> + // so we meet its safety requirements.
> + // * The `data` pointer passed in the third argument is a valid `T` pointer that outlives
> + // this call by caller preconditions.
> + unsafe { bindings::single_open(file, Some(display_act::<T>), (*inode).i_private) }
> + }
On Mon, 2025-05-05 at 23:51 +0000, Matthew Maurer wrote:
> + pub(crate) unsafe extern "C" fn display_act<T: Display>(
> + seq: *mut bindings::seq_file,
> + _: *mut core::ffi::c_void,
> + ) -> i32 {
> + // SAFETY: By caller precondition, this pointer is live, points to a value of type `T`,
> and
> + // is not being mutated.
> + let data = unsafe { &*((*seq).private as *mut T) };
> + // SAFETY: By caller precondition, `seq_file` points to a live `seq_file`, so we can lift
> + // it.
> + let seq_file = unsafe { SeqFile::from_raw(seq) };
> + seq_print!(seq_file, "{}", data);
Doesn't this restrict T to data types that are supported by "{}"? So, for example, T cannot be a
Vec, correct?
For nova-core, we need to be able to "print" an array of bytes as-is. Specifically, a DMA buffer
that just contains binary data. But by using seq_print!, aren't we forcing T to contain only
printable characters?
On Tue, May 6, 2025 at 1:51 AM Matthew Maurer <mmaurer@google.com> wrote: > > Allows creation of files for references that live forever and lack > metadata through the `Display` implementation. > > The reference must live forever because we do not have a maximum > lifetime for the file we are creating. > > The `Display` implementation is used because `seq_printf` needs to route > through `%pA`, which in turn routes through Arguments. A more generic > API is provided later in the series, implemented in terms of this one. > > Signed-off-by: Matthew Maurer <mmaurer@google.com> I believe it should be possible to bind owned data to a `File` using a signature like this: fn create_file<T>(&self, name: &CStr, data: impl PinInit<T>) -> impl PinInit<FileWithData<T>>
On Mon, 2025-05-05 at 23:51 +0000, Matthew Maurer wrote:
> + /// Create a file in a DebugFS directory with the provided name, and contents from invoking
> + /// [`Display::fmt`] on the provided reference.
Is there a typo in this sentence? I can't quite parse it.
> + pub fn display_file<'b, T: Display + Sized>(
> + &'b self,
> + name: &CStr,
> + data: &'static T,
> + ) -> File<'b> {
> + // SAFETY:
> + // * `name` is a NUL-terminated C string, living across the call, by `CStr` invariant.
> + // * `parent` is a live `dentry` since we have a reference to it.
> + // * `vtable` is all stock `seq_file` implementations except for `open`.
> + // `open`'s only requirement beyond what is provided to all open functions is that the
> + // inode's data pointer must point to a `T` that will outlive it, which we know because
> + // we have a static reference.
> + #[cfg(CONFIG_DEBUG_FS)]
> + let ptr = unsafe {
> + bindings::debugfs_create_file_full(
> + name.as_char_ptr(),
> + 0o444,
Can you make the mode a parameter? I get that you're not supporting writing yet, but there should
be a choice as to whether it's 0o444, 0o440, or 0o400.
Also, maybe use S_IRUSR, S_IRGRP, and S_IROTH?
On Mon, 2025-05-05 at 23:51 +0000, Matthew Maurer wrote:
> + /// Constructs a new DebugFS [`Entry`] from the underlying pointer.
> + ///
> + /// # Safety
> + ///
> + /// The pointer must either be an error code, `NULL`, or represent a transfer of ownership of
> a
> + /// live DebugFS directory.
> + #[cfg(not(CONFIG_DEBUG_FS))]
> + unsafe fn from_ptr(_entry: *mut bindings::dentry) -> Self {
> + Self {
> + _phantom: PhantomData,
> + }
> + }
> +
Does this diff belong in patch 1/4? That would explain my confusion.
© 2016 - 2025 Red Hat, Inc.