rust: debugfs: Add initial support for directories (7f201ca1) · Commits · git / linux-net

MAINTAINERS

+2 −0

Original line number	Diff line number	Diff line
		@@ -7487,6 +7487,8 @@ F: include/linux/kobj*
		F: include/linux/property.h
		F: include/linux/sysfs.h
		F: lib/kobj*
		F: rust/kernel/debugfs.rs
		F: rust/kernel/debugfs/
		F: rust/kernel/device.rs
		F: rust/kernel/device/
		F: rust/kernel/device_id.rs

rust/bindings/bindings_helper.h

+1 −0

Original line number	Diff line number	Diff line
		@@ -46,6 +46,7 @@
		#include <linux/cpufreq.h>
		#include <linux/cpumask.h>
		#include <linux/cred.h>
		#include <linux/debugfs.h>
		#include <linux/device/faux.h>
		#include <linux/dma-mapping.h>
		#include <linux/errname.h>

rust/kernel/debugfs.rs

0 → 100644

+82 −0

Original line number	Diff line number	Diff line
		// SPDX-License-Identifier: GPL-2.0
		// Copyright (C) 2025 Google LLC.

		//! DebugFS Abstraction
		//!
		//! C header: [`include/linux/debugfs.h`](srctree/include/linux/debugfs.h)

		// When DebugFS is disabled, many parameters are dead. Linting for this isn't helpful.
		#![cfg_attr(not(CONFIG_DEBUG_FS), allow(unused_variables))]

		#[cfg(CONFIG_DEBUG_FS)]
		use crate::prelude::*;
		use crate::str::CStr;
		#[cfg(CONFIG_DEBUG_FS)]
		use crate::sync::Arc;

		#[cfg(CONFIG_DEBUG_FS)]
		mod entry;
		#[cfg(CONFIG_DEBUG_FS)]
		use entry::Entry;

		/// Owning handle to a DebugFS directory.
		///
		/// The directory in the filesystem represented by [`Dir`] will be removed when handle has been
		/// dropped and all children have been removed.
		// If we have a parent, we hold a reference to it in the `Entry`. This prevents the `dentry`
		// we point to from being cleaned up if our parent `Dir`/`Entry` is dropped before us.
		//
		// The `None` option indicates that the `Arc` could not be allocated, so our children would not be
		// able to refer to us. In this case, we need to silently fail. All future child directories/files
		// will silently fail as well.
		#[derive(Clone)]
		pub struct Dir(#[cfg(CONFIG_DEBUG_FS)] Option<Arc<Entry>>);

		impl Dir {
		/// Create a new directory in DebugFS. If `parent` is [`None`], it will be created at the root.
		fn create(name: &CStr, parent: Option<&Dir>) -> Self {
		#[cfg(CONFIG_DEBUG_FS)]
		{
		let parent_entry = match parent {
		// If the parent couldn't be allocated, just early-return
		Some(Dir(None)) => return Self(None),
		Some(Dir(Some(entry))) => Some(entry.clone()),
		None => None,
		};
		Self(
		// If Arc creation fails, the `Entry` will be dropped, so the directory will be
		// cleaned up.
		Arc::new(Entry::dynamic_dir(name, parent_entry), GFP_KERNEL).ok(),
		)
		}
		#[cfg(not(CONFIG_DEBUG_FS))]
		Self()
		}

		/// Create a new directory in DebugFS at the root.
		///
		/// # Examples
		///
		/// ```
		/// # use kernel::c_str;
		/// # use kernel::debugfs::Dir;
		/// let debugfs = Dir::new(c_str!("parent"));
		/// ```
		pub fn new(name: &CStr) -> Self {
		Dir::create(name, None)
		}

		/// Creates a subdirectory within this directory.
		///
		/// # Examples
		///
		/// ```
		/// # use kernel::c_str;
		/// # use kernel::debugfs::Dir;
		/// let parent = Dir::new(c_str!("parent"));
		/// let child = parent.subdir(c_str!("child"));
		/// ```
		pub fn subdir(&self, name: &CStr) -> Self {
		Dir::create(name, Some(self))
		}
		}

rust/kernel/debugfs/entry.rs

0 → 100644

+61 −0

Original line number	Diff line number	Diff line
		// SPDX-License-Identifier: GPL-2.0
		// Copyright (C) 2025 Google LLC.

		use crate::str::CStr;
		use crate::sync::Arc;

		/// Owning handle to a DebugFS entry.
		///
		/// # Invariants
		///
		/// The wrapped pointer will always be `NULL`, an error, or an owned DebugFS `dentry`.
		pub(crate) struct Entry {
		entry: *mut bindings::dentry,
		// If we were created with an owning parent, this is the keep-alive
		_parent: Option<Arc<Entry>>,
		}

		// SAFETY: [`Entry`] is just a `dentry` under the hood, which the API promises can be transferred
		// between threads.
		unsafe impl Send for Entry {}

		// SAFETY: All the C functions we call on the `dentry` pointer are threadsafe.
		unsafe impl Sync for Entry {}

		impl Entry {
		pub(crate) fn dynamic_dir(name: &CStr, parent: Option<Arc<Self>>) -> Self {
		let parent_ptr = match &parent {
		Some(entry) => entry.as_ptr(),
		None => core::ptr::null_mut(),
		};
		// SAFETY: The invariants of this function's arguments ensure the safety of this call.
		// * `name` is a valid C string by the invariants of `&CStr`.
		// * `parent_ptr` is either `NULL` (if `parent` is `None`), or a pointer to a valid
		// `dentry` by our invariant. `debugfs_create_dir` handles `NULL` pointers correctly.
		let entry = unsafe { bindings::debugfs_create_dir(name.as_char_ptr(), parent_ptr) };

		Entry {
		entry,
		_parent: parent,
		}
		}

		/// Returns the pointer representation of the DebugFS directory.
		///
		/// # Guarantees
		///
		/// Due to the type invariant, the value returned from this function will always be an error
		/// code, NULL, or a live DebugFS directory. If it is live, it will remain live at least as
		/// long as this entry lives.
		pub(crate) fn as_ptr(&self) -> *mut bindings::dentry {
		self.entry
		}
		}

		impl Drop for Entry {
		fn drop(&mut self) {
		// SAFETY: `debugfs_remove` can take `NULL`, error values, and legal DebugFS dentries.
		// `as_ptr` guarantees that the pointer is of this form.
		unsafe { bindings::debugfs_remove(self.as_ptr()) }
		}
		}

rust/kernel/lib.rs

+1 −0

Original line number	Diff line number	Diff line
		@@ -76,6 +76,7 @@
		pub mod cpufreq;
		pub mod cpumask;
		pub mod cred;
		pub mod debugfs;
		pub mod device;
		pub mod device_id;
		pub mod devres;