| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20250505-debugfs-rust-v5-1-3e93ce7bb76e@google.com>
Date: Mon, 05 May 2025 23:51:34 +0000
From: Matthew Maurer <mmaurer@...gle.com>
To: Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>,
Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
"Björn Roy Baron" <bjorn3_gh@...tonmail.com>, Benno Lossin <benno.lossin@...ton.me>,
Andreas Hindborg <a.hindborg@...nel.org>, Alice Ryhl <aliceryhl@...gle.com>,
Trevor Gross <tmgross@...ch.edu>, Danilo Krummrich <dakr@...nel.org>,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael J. Wysocki" <rafael@...nel.org>,
Sami Tolvanen <samitolvanen@...gle.com>, Timur Tabi <ttabi@...dia.com>
Cc: linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org,
Matthew Maurer <mmaurer@...gle.com>
Subject: [PATCH v5 1/4] rust: debugfs: Bind DebugFS directory creation
Support creating DebugFS directories and subdirectories. Similar to the
original DebugFS API, errors are hidden.
By default, when a root directory handle leaves scope, it will be cleaned
up.
Subdirectories will by default persist until their root directory is
cleaned up, but can be converted into a root directory if a scoped
lifecycle is desired.
Signed-off-by: Matthew Maurer <mmaurer@...gle.com>
---
MAINTAINERS | 1 +
rust/bindings/bindings_helper.h | 1 +
rust/kernel/debugfs.rs | 139 ++++++++++++++++++++++++++++++++++++++++
rust/kernel/lib.rs | 1 +
4 files changed, 142 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 906881b6c5cb6ff743e13b251873b89138c69a1c..a3b835e427b083a4ddd690d9e7739851f0af47ae 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7271,6 +7271,7 @@ 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/device.rs
F: rust/kernel/device_id.rs
F: rust/kernel/devres.rs
diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 8a2add69e5d66d1c2ebed9d2c950380e61c48842..787f928467faabd02a7f3cf041378fac856c4f89 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -13,6 +13,7 @@
#include <linux/blkdev.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>
diff --git a/rust/kernel/debugfs.rs b/rust/kernel/debugfs.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ed1aba6d700d064dbfd7e923dbcbf80b9acf5361
--- /dev/null
+++ b/rust/kernel/debugfs.rs
@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: GPL-2.0
+// Copyright (C) 2025 Google LLC.
+
+//! DebugFS Abstraction
+//!
+//! C header: [`include/linux/debugfs.h`](srctree/include/linux/debugfs.h)
+
+use crate::str::CStr;
+use core::marker::PhantomData;
+
+/// Owning handle to a DebugFS entry.
+///
+/// # Invariants
+///
+/// The wrapped pointer will always be `NULL`, an error, or an owned DebugFS `dentry`.
+#[repr(transparent)]
+struct Entry<'a> {
+ #[cfg(CONFIG_DEBUG_FS)]
+ entry: *mut bindings::dentry,
+ // We need to be outlived by our parent, if they exist, but we don't actually need to be able
+ // to access the data.
+ _phantom: PhantomData<&'a Entry<'a>>,
+}
+
+// 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 native functions we re-export use interior locking, and the contents of the
+// struct are opaque to Rust.
+unsafe impl Sync for Entry<'_> {}
+
+impl<'a> Entry<'a> {
+ /// 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. If this is a child directory or file, `'a` must be less than the
+ /// lifetime of the parent directory.
+ #[cfg(CONFIG_DEBUG_FS)]
+ unsafe fn from_ptr(entry: *mut bindings::dentry) -> Self {
+ Self {
+ entry,
+ _phantom: PhantomData,
+ }
+ }
+
+ #[cfg(not(CONFIG_DEBUG_FS))]
+ fn new() -> Self {
+ Self {
+ _phantom: PhantomData,
+ }
+ }
+
+ /// 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, NUL, or a live DebugFS directory.
+ // If this function is ever needed with `not(CONFIG_DEBUG_FS)`, hardcode it to return
+ // `ERR_PTR(ENODEV)`.
+ #[cfg(CONFIG_DEBUG_FS)]
+ 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.
+ #[cfg(CONFIG_DEBUG_FS)]
+ unsafe {
+ bindings::debugfs_remove(self.as_ptr())
+ }
+ }
+}
+
+/// Owning handle to a DebugFS directory.
+///
+/// This directory will be cleaned up when the handle leaves scope.
+pub struct Dir<'a>(Entry<'a>);
+
+impl<'a> Dir<'a> {
+ /// Create a new directory in DebugFS. If `parent` is [`None`], it will be created at the root.
+ #[cfg(CONFIG_DEBUG_FS)]
+ fn create<'b>(name: &CStr, parent: Option<&'a Dir<'b>>) -> Self {
+ let parent_ptr = match parent {
+ Some(parent) => parent.0.as_ptr(),
+ None => core::ptr::null_mut(),
+ };
+ // SAFETY:
+ // * `name` argument points to a NUL-terminated string that lives across the call, by
+ // invariants of `&CStr`.
+ // * If `parent` is `None`, `parent` accepts null pointers to mean create at root.
+ // * If `parent` is `Some`, `parent` accepts live dentry debugfs pointers.
+ // so we can call `Self::from_ptr`.
+ let dir = unsafe { bindings::debugfs_create_dir(name.as_char_ptr(), parent_ptr) };
+
+ // SAFETY: `debugfs_create_dir` either returns an error code or a legal `dentry` pointer,
+ Self(unsafe { Entry::from_ptr(dir) })
+ }
+
+ #[cfg(not(CONFIG_DEBUG_FS))]
+ fn create<'b>(_name: &CStr, _parent: Option<&'a Dir<'b>>) -> Self {
+ Self(Entry::new())
+ }
+
+ /// Create a DebugFS subdirectory.
+ ///
+ /// Subdirectory handles cannot outlive the directory handle they were created from.
+ ///
+ /// # 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<'b>(&'b self, name: &CStr) -> Dir<'b> {
+ Dir::create(name, Some(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)
+ }
+}
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index c3762e80b314316b4b0cee3bfd9442f8f0510b91..86f6055b828d5f711578293d8916a517f2436977 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -45,6 +45,7 @@
#[doc(hidden)]
pub mod build_assert;
pub mod cred;
+pub mod debugfs;
pub mod device;
pub mod device_id;
pub mod devres;
--
2.49.0.967.g6a0df3ecc3-goog
Powered by blists - more mailing lists