rust: DebugFS Bindings

This allows Files to own their data, allowing DebugFS files to be managed in sync with the data that backs them. Because DebugFS files are intended to actually own data and provide access, Files still maintain the same lifecycle for provided data when CONFIG_DEBUG_FS is disabled.

Signed-off-by Matthew Maurer <[email protected]>

---
 rust/kernel/debugfs.rs | 149 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 117 insertions(+), 32 deletions(-)

rust/kernel/debugfs.rs +6 -5

index e5b6497d1deb67671d22ffd90cd5baa855bb9257..a1a84dd309216f455ae8fe3d3c0fd00f957f82a9 100644
@@ -5,12 +5,13 @@
 //!
 //! C header: [`include/linux/debugfs.h`](srctree/include/linux/debugfs.h)
 
-#[cfg(CONFIG_DEBUG_FS)]
-use crate::prelude::GFP_KERNEL;
+use crate::prelude::*;
 use crate::str::CStr;
 #[cfg(CONFIG_DEBUG_FS)]
 use crate::sync::Arc;
 use core::fmt::Display;
+use core::marker::PhantomPinned;
+use core::ops::Deref;
 
 #[cfg(CONFIG_DEBUG_FS)]
 mod display_file;

@@ -63,40 +64,78 @@ fn create(_name: &CStr, _parent: Option<&Dir>) -> Self {
     }
 
     #[cfg(CONFIG_DEBUG_FS)]
-    fn create_file<T: Display + Sized + Sync>(&self, name: &CStr, data: &'static T) -> File {
-        let Some(parent) = &self.0 else {
-            return File {
+    /// Creates a DebugFS file which will own the data produced by the initializer provided in
+    /// `data`.
+    ///

Hi Matthew,

Quoted 40 lines · Matthew Maurer

This allows Files to own their data, allowing DebugFS files to be managed in sync with the data that backs them. Because DebugFS files are intended to actually own data and provide access, Files still maintain the same lifecycle for provided data when CONFIG_DEBUG_FS is disabled.

Signed-off-by Matthew Maurer <[email protected]>

---
 rust/kernel/debugfs.rs | 149 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 117 insertions(+), 32 deletions(-)

rust/kernel/debugfs.rs +6 -5

index e5b6497d1deb67671d22ffd90cd5baa855bb9257..a1a84dd309216f455ae8fe3d3c0fd00f957f82a9 100644
@@ -5,12 +5,13 @@
 //!
 //! C header: [`include/linux/debugfs.h`](srctree/include/linux/debugfs.h)
 
-#[cfg(CONFIG_DEBUG_FS)]
-use crate::prelude::GFP_KERNEL;
+use crate::prelude::*;
 use crate::str::CStr;
 #[cfg(CONFIG_DEBUG_FS)]
 use crate::sync::Arc;
 use core::fmt::Display;
+use core::marker::PhantomPinned;
+use core::ops::Deref;
 
 #[cfg(CONFIG_DEBUG_FS)]
 mod display_file;

@@ -63,40 +64,78 @@ fn create(_name: &CStr, _parent: Option<&Dir>) -> Self {
     }
 
     #[cfg(CONFIG_DEBUG_FS)]
-    fn create_file<T: Display + Sized + Sync>(&self, name: &CStr, data: &'static T) -> File {
-        let Some(parent) = &self.0 else {
-            return File {
+    /// Creates a DebugFS file which will own the data produced by the initializer provided in
+    /// `data`.
+    ///

rust/kernel/debugfs.rs fn create(_name: &CStr, _parent: Option<&Dir>) -> Self { · line 79

Quoted 10 lines

rust/kernel/debugfs.rs +10 -0

+    /// # Safety
+    ///
+    /// The provided vtable must be appropriate for implementing a seq_file if provided
+    /// with a private data pointer which provides shared access to a `T`.
+    unsafe fn create_file<'a, T: Sync, E, TI: PinInit<T, E>>(
+        &self,
+        name: &'a CStr,
+        data: TI,
+        vtable: &'static bindings::file_operations,
+    ) -> impl PinInit<File<T>, E> + use<'_, 'a, T, E, TI> {

Rebasing my test code from an older version of this series to this v9 (this is the most recent one?) here in rust/kernel/debugfs.rs and in samples/rust/rust_debugfs.rs I get errors for each place where 'use<...>' is used:

error[E0658]: precise captures on impl Trait are experimental
--> rust/kernel/debugfs.rs:81:37

   |
81 |     ) -> impl PinInit<File<T>, E> + use<'_, 'a, T, E, TI> {
   |                                     ^^^
   |

= note: see issue #123432
<https://github.com/rust-lang/rust/issues/123432> for more information
= help: add #![feature(precise_capturing)] to the crate attributes
to enable
= note: this compiler was built on 2024-09-04; consider upgrading it
if it is out of date

rustc is

rustc 1.81.0 (eeb90cda1 2024-09-04)

I tried to work around this by adding

rust/kernel/lib.rs +3 -0

@@ -36,6 +36,9 @@
 //
 // To be determined.
 #![feature(used_with_arg)]
+
+#![feature(precise_capturing)]
+
 

This seems to help for rust/kernel/debugfs.rs but not for samples/rust/rust_debugfs.rs.

Any hint?

Best regards

Dirk

The easy way to resolve this is to use rustc 1.82.0 or newer (you're only one revision behind!), but that's past the MSRV for the kernel at the moment of 1.79.0. I intend to send up a new patch today, so I suppose I'll need to put that behind a flag similar to RUSTC_HAS_DERIVE_COERCE_POINTEE.

Did you add #![feature(precise_capturing)] to samples/rust/rust_debugfs.rs as well? It is its own crate, so it has its own set of features.

samples/rust/rust_debugfs.rs new file +23 -0

+#[pin_data]
+struct Wrapper {
+    _dir: Dir,
+    #[pin]
+    _wrapped: File<File<RustDebugFs>>,
+}
+
+#[pin_data]
+struct RustDebugFs {
+    pdev: ARef<platform::Device>,
+    // As we only hold these for drop effect (to remove the directory/files) we have a leading
+    // underscore to indicate to the compiler that we don't expect to use this field directly.
+    _debugfs: Dir,
+    #[pin]
+    _compatible: File<CString>,
+    #[pin]
+    counter: File<File<AtomicUsize>>,
+    #[pin]
+    inner: File<Mutex<Inner>>,
+}
+
+#[derive(Debug)]
+struct Inner {

samples/rust/rust_debugfs.rs new file +19 -0

+kernel::acpi_device_table!(
+    ACPI_TABLE,
+    MODULE_ACPI_TABLE,
+    <Wrapper as platform::Driver>::IdInfo,
+    [(acpi::DeviceId::new(c_str!("LNUXDEBF")), ())]
+);
+
+impl platform::Driver for Wrapper {
+    type IdInfo = ();
+    const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = Some(&OF_TABLE);
+    const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = Some(&ACPI_TABLE);
+
+    fn probe(
+        pdev: &platform::Device<Core>,
+        _info: Option<&Self::IdInfo>,
+    ) -> Result<Pin<KBox<Self>>> {
+        KBox::try_pin_init(Wrapper::new(RustDebugFs::new(pdev)), GFP_KERNEL)
+    }
+}

Keep it simple, Create some driver private data in probe() and export a couple of fields of this driver private data through debugfs.

If you really want to showcase that those values can change, queue some work and modify the counter and / or the Inner type that is protected by a mutex.

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

Quoted 3 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Quoted 1 line

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

The problem is that the current abstractions only implement read(), but not write().

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

- Danilo

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

Quoted 6 lines

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

- Danilo

How do you feel about the Wrapper struct, intended to simulate the driver doing its actual job and show how that would look? Is that similarly verboten, even though there's a comment on it saying this isn't how one should do things?

Quoted 11 lines · Matthew Maurer

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 6 lines

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Absolutely, yes! I didn't mean to ask to add it now. :)

Quoted 3 lines

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

Quoted 5 lines

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

I'm not asking to do that. If the values don't change for now, because there's no write() yet, that's perfectly fine with me. :)

Quoted 6 lines

Quoted 6 lines

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

Quoted 6 lines

Quoted 1 line

- Danilo

How do you feel about the Wrapper struct, intended to simulate the driver doing its actual job and show how that would look? Is that similarly verboten, even though there's a comment on it saying this isn't how one should do things?

Yeah, let's not do that -- don't give people ideas. :)

Quoted 31 lines · Danilo Krummrich

Quoted 11 lines · Matthew Maurer

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 6 lines

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Absolutely, yes! I didn't mean to ask to add it now. :)

Quoted 8 lines

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

Quoted 2 lines

I'm not asking to do that. If the values don't change for now, because there's no write() yet, that's perfectly fine with me. :)

Potentially I misinterpreted Greg[1], I thought he wanted to see how mutation would work.
If we don't need mutation, I'm fine simplifying the driver to not have any mutation triggers and just export a few random things.

[1]: https://lore.kernel.org/all/2025070349-tricky-arguable-5362@gregkh/

Quoted 14 lines

Quoted 6 lines

Quoted 6 lines

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

Quoted 6 lines

Quoted 1 line

- Danilo

How do you feel about the Wrapper struct, intended to simulate the driver doing its actual job and show how that would look? Is that similarly verboten, even though there's a comment on it saying this isn't how one should do things?

Yeah, let's not do that -- don't give people ideas. :)

Quoted 35 lines · Matthew Maurer

Quoted 33 lines · Danilo Krummrich

Quoted 11 lines · Matthew Maurer

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 6 lines

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Absolutely, yes! I didn't mean to ask to add it now. :)

Quoted 8 lines

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

I'm not asking to do that. If the values don't change for now, because there's no write() yet, that's perfectly fine with me. :)

Quoted 4 lines

Potentially I misinterpreted Greg[1], I thought he wanted to see how mutation would work.
If we don't need mutation, I'm fine simplifying the driver to not have any mutation triggers and just export a few random things.

I mean, the most simple way would be to create the debugfs entries in probe() and mutate them - still in probe() - right afterwards once. I think we should do in any case. And AFAICT, this also covers [1].

Quoted 17 lines

[1]: https://lore.kernel.org/all/2025070349-tricky-arguable-5362@gregkh/

Quoted 14 lines

Quoted 6 lines

Quoted 6 lines

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

Quoted 6 lines

Quoted 1 line

- Danilo

How do you feel about the Wrapper struct, intended to simulate the driver doing its actual job and show how that would look? Is that similarly verboten, even though there's a comment on it saying this isn't how one should do things?

Yeah, let's not do that -- don't give people ideas. :)

Quoted 42 lines · Danilo Krummrich

Quoted 39 lines · Matthew Maurer

Quoted 25 lines · Danilo Krummrich

Quoted 11 lines · Matthew Maurer

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 6 lines

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Absolutely, yes! I didn't mean to ask to add it now. :)

Quoted 3 lines

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

Quoted 8 lines

Quoted 5 lines

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

I'm not asking to do that. If the values don't change for now, because there's no write() yet, that's perfectly fine with me. :)

Potentially I misinterpreted Greg[1], I thought he wanted to see how mutation would work.
If we don't need mutation, I'm fine simplifying the driver to not have any mutation triggers and just export a few random things.

Quoted 3 lines

I mean, the most simple way would be to create the debugfs entries in probe() and mutate them - still in probe() - right afterwards once. I think we should do in any case. And AFAICT, this also covers [1].

That's what I did with my InPlaceModule before and it evidently didn't count? I don't see how the constructor being probe rather than init would have been the issue - the only change that causes is calling KBox::pin_init on the value you would have returned.

Quoted 16 lines

Quoted 16 lines

[1]: https://lore.kernel.org/all/2025070349-tricky-arguable-5362@gregkh/

Quoted 14 lines

Quoted 6 lines

Quoted 6 lines

We really should not teach people to modify values by read() instead of write(). Also, without this workaround there shouldn't be a reason to export the exact same value twice, i.e. no need for File<File<AtomicUsize>>.

Quoted 6 lines

Quoted 1 line

- Danilo

How do you feel about the Wrapper struct, intended to simulate the driver doing its actual job and show how that would look? Is that similarly verboten, even though there's a comment on it saying this isn't how one should do things?

Yeah, let's not do that -- don't give people ideas. :)

Quoted 35 lines · Matthew Maurer

Quoted 33 lines · Danilo Krummrich

Quoted 11 lines · Matthew Maurer

Quoted 10 lines · Danilo Krummrich

Quoted 4 lines · Matthew Maurer

This series provides safe DebugFS bindings for Rust, with a sample module using them.

Example interaction with the sample driver:

I understand what you're trying to do here, i.e. showcase that values exported via debugfs can be altered.

Quoted 6 lines

Quoted 2 lines

The problem is that the current abstractions only implement read(), but not write().

I was trying to keep the initial bindings simple. Adding write is definitely something we could do, but I thought maybe that could be in a subsequent patch.

Absolutely, yes! I didn't mean to ask to add it now. :)

Quoted 8 lines

Quoted 2 lines

If you really want to showcase changing values, you can, for instance, create a workqueue inside the sample driver and modify the counter periodically.

This is supposed to be sample code, so ideally it should be as narrow as is reasonable in what subsystems it touches, no? If people would really prefer the sample schedule a ticking counter I can do that, but it already felt weird to be registering a platform driver in a debugfs sample.

I'm not asking to do that. If the values don't change for now, because there's no write() yet, that's perfectly fine with me. :)

Quoted 4 lines

Potentially I misinterpreted Greg[1], I thought he wanted to see how mutation would work.
If we don't need mutation, I'm fine simplifying the driver to not have any mutation triggers and just export a few random things.

I mean, the most simple way would be to create the debugfs entries in probe() and mutate them - still in probe() - right afterwards once. I think we should do in any case. And AFAICT, this also covers [1].

Quoted 1 line

[1]: https://lore.kernel.org/all/2025070349-tricky-arguable-5362@gregkh/

Ugh.

Yes we need write. And read, and custom file-ops, and the like as that's what debugfs is doing today for C code! We need this to be as simple as, or almost as simple as, what we have today in C or no one is going to use this stuff and go off and attempt to write their own mess.

While I would love to have something as simple as:

	void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, u8 *value);

like we do today. I understand that this makes all sorts of "assumptions" that Rust really doesn't like (i.e. lifetime of *value and the like), BUT we MUST have something like this for Rust users, as that's going to ensure that people actually use this api.

Look at an in-kernel function today, like ath9k_init_debug() that creates a metric-ton of debugfs files and binds them to different variables that are owned by a structure and more complex data structures and memory dumps and other random file interactions. We need, in Rust, a way to do everything that that function can do today, in a SIMPLE manner that reads just as easily as ath9k_init_debug() does.

So no "we will add write support later" stuff, sorry, real drivers require write support in debugfs.

Quoted 6 lines · Greg Kroah-Hartman

Ugh.

Yes we need write. And read, and custom file-ops, and the like as that's what debugfs is doing today for C code! We need this to be as simple as, or almost as simple as, what we have today in C or no one is going to use this stuff and go off and attempt to write their own mess.

I agree, we really want the helpers you're referring to below. I think we discussed this in previous iterations already.

Quoted 6 lines

While I would love to have something as simple as:

	void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, u8 *value);

like we do today. I understand that this makes all sorts of "assumptions" that Rust really doesn't like (i.e. lifetime of *value and the like), BUT we MUST have something like this for Rust users, as that's going to ensure that people actually use this api.

I think it can be as simple as

	void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, u8 *value);

in Rust as well. Declaring this in a structure looks like this.

	struct Data {
	   counter: File<u8>,
	}

Given that we have some Dir instance, this can be as simple as:

	dir.create_file_u8(...);

Which uses default callbacks for read(), write(), etc.

Quoted 6 lines

Look at an in-kernel function today, like ath9k_init_debug() that creates a metric-ton of debugfs files and binds them to different variables that are owned by a structure and more complex data structures and memory dumps and other random file interactions. We need, in Rust, a way to do everything that that function can do today, in a SIMPLE manner that reads just as easily as ath9k_init_debug() does.

That's possible with the current design and code, it misses the helpers, such as create_file_u8() above, to reduce the boilerplate though. With that, it should look pretty similar.

Quoted 41 lines · Danilo Krummrich

Quoted 6 lines · Greg Kroah-Hartman

Ugh.

Yes we need write. And read, and custom file-ops, and the like as that's what debugfs is doing today for C code! We need this to be as simple as, or almost as simple as, what we have today in C or no one is going to use this stuff and go off and attempt to write their own mess.

I agree, we really want the helpers you're referring to below. I think we discussed this in previous iterations already.

Quoted 6 lines

While I would love to have something as simple as:

	void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, u8 *value);

like we do today. I understand that this makes all sorts of "assumptions" that Rust really doesn't like (i.e. lifetime of *value and the like), BUT we MUST have something like this for Rust users, as that's going to ensure that people actually use this api.

I think it can be as simple as

	void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, u8 *value);

in Rust as well. Declaring this in a structure looks like this.

	struct Data {
	   counter: File<u8>,
	}

Given that we have some Dir instance, this can be as simple as:

	dir.create_file_u8(...);

Which uses default callbacks for read(), write(), etc.

Quoted 6 lines

Look at an in-kernel function today, like ath9k_init_debug() that creates a metric-ton of debugfs files and binds them to different variables that are owned by a structure and more complex data structures and memory dumps and other random file interactions. We need, in Rust, a way to do everything that that function can do today, in a SIMPLE manner that reads just as easily as ath9k_init_debug() does.

Quoted 3 lines

That's possible with the current design and code, it misses the helpers, such as create_file_u8() above, to reduce the boilerplate though. With that, it should look pretty similar.

Can't you just implement the traits directly on u8 and then just call create_file?