// 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))] use crate::prelude::*;use crate::str::CStr;#[cfg(CONFIG_DEBUG_FS)]use crate::sync::Arc;use crate::uaccess::UserSliceReader;use core::fmt;use core::marker::PhantomData;use core::marker::PhantomPinned;#[cfg(CONFIG_DEBUG_FS)]use core::mem::ManuallyDrop;use core::ops::Deref; mod traits;pub use traits::{Reader, Writer}; mod callback_adapters;use callback_adapters::{FormatAdapter, NoWriter, WritableAdapter};mod file_ops;use file_ops::{FileOps, ReadFile, ReadWriteFile, WriteFile};#[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<'static>>>); 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() } /// Creates a DebugFS file which will own the data produced by the initializer provided in /// `data`. fn create_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, file_ops: &'static FileOps<T>, ) -> impl PinInit<File<T>, E> + 'a where T: Sync + 'static, { let scope = Scope::<T>::new(data, move |data| { #[cfg(CONFIG_DEBUG_FS)] if let Some(parent) = &self.0 { // SAFETY: Because data derives from a scope, and our entry will be dropped before // the data is dropped, it is guaranteed to outlive the entry we return. unsafe { Entry::dynamic_file(name, parent.clone(), data, file_ops) } } else { Entry::empty() } }); try_pin_init! { File { scope <- scope } ? E } } /// 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)) } /// Creates a read-only file in this directory. /// /// The file's contents are produced by invoking [`Writer::write`] on the value initialized by /// `data`. /// /// # Examples /// /// ``` /// # use kernel::c_str; /// # use kernel::debugfs::Dir; /// # use kernel::prelude::*; /// # let dir = Dir::new(c_str!("my_debugfs_dir")); /// let file = KBox::pin_init(dir.read_only_file(c_str!("foo"), 200), GFP_KERNEL)?; /// // "my_debugfs_dir/foo" now contains the number 200. /// // The file is removed when `file` is dropped. /// # Ok::<(), Error>(()) /// ``` pub fn read_only_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Writer + Send + Sync + 'static, { let file_ops = &<T as ReadFile<_>>::FILE_OPS; self.create_file(name, data, file_ops) } /// Creates a read-only file in this directory, with contents from a callback. /// /// `f` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. /// /// # Examples /// /// ``` /// # use core::sync::atomic::{AtomicU32, Ordering}; /// # use kernel::c_str; /// # use kernel::debugfs::Dir; /// # use kernel::prelude::*; /// # let dir = Dir::new(c_str!("foo")); /// let file = KBox::pin_init( /// dir.read_callback_file(c_str!("bar"), /// AtomicU32::new(3), /// &|val, f| { /// let out = val.load(Ordering::Relaxed); /// writeln!(f, "{out:#010x}") /// }), /// GFP_KERNEL)?; /// // Reading "foo/bar" will show "0x00000003". /// file.store(10, Ordering::Relaxed); /// // Reading "foo/bar" will now show "0x0000000a". /// # Ok::<(), Error>(()) /// ``` pub fn read_callback_file<'a, T, E: 'a, F>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _f: &'static F, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, { let file_ops = <FormatAdapter<T, F>>::FILE_OPS.adapt(); self.create_file(name, data, file_ops) } /// Creates a read-write file in this directory. /// /// Reading the file uses the [`Writer`] implementation. /// Writing to the file uses the [`Reader`] implementation. pub fn read_write_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Writer + Reader + Send + Sync + 'static, { let file_ops = &<T as ReadWriteFile<_>>::FILE_OPS; self.create_file(name, data, file_ops) } /// Creates a read-write file in this directory, with logic from callbacks. /// /// Reading from the file is handled by `f`. Writing to the file is handled by `w`. /// /// `f` and `w` must be function items or non-capturing closures. /// This is statically asserted and not a safety requirement. pub fn read_write_callback_file<'a, T, E: 'a, F, W>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _f: &'static F, _w: &'static W, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync, { let file_ops = <WritableAdapter<FormatAdapter<T, F>, W> as file_ops::ReadWriteFile<_>>::FILE_OPS .adapt() .adapt(); self.create_file(name, data, file_ops) } /// Creates a write-only file in this directory. /// /// The file owns its backing data. Writing to the file uses the [`Reader`] /// implementation. /// /// The file is removed when the returned [`File`] is dropped. pub fn write_only_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Reader + Send + Sync + 'static, { self.create_file(name, data, &T::FILE_OPS) } /// Creates a write-only file in this directory, with write logic from a callback. /// /// `w` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. pub fn write_callback_file<'a, T, E: 'a, W>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _w: &'static W, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync, { let file_ops = <WritableAdapter<NoWriter<T>, W> as WriteFile<_>>::FILE_OPS .adapt() .adapt(); self.create_file(name, data, file_ops) } // While this function is safe, it is intentionally not public because it's a bit of a // footgun. // // Unless you also extract the `entry` later and schedule it for `Drop` at the appropriate // time, a `ScopedDir` with a `Dir` parent will never be deleted. fn scoped_dir<'data>(&self, name: &CStr) -> ScopedDir<'data, 'static> { #[cfg(CONFIG_DEBUG_FS)] { let parent_entry = match &self.0 { None => return ScopedDir::empty(), Some(entry) => entry.clone(), }; ScopedDir { entry: ManuallyDrop::new(Entry::dynamic_dir(name, Some(parent_entry))), _phantom: PhantomData, } } #[cfg(not(CONFIG_DEBUG_FS))] ScopedDir::empty() } /// Creates a new scope, which is a directory associated with some data `T`. /// /// The created directory will be a subdirectory of `self`. The `init` closure is called to /// populate the directory with files and subdirectories. These files can reference the data /// stored in the scope. /// /// The entire directory tree created within the scope will be removed when the returned /// `Scope` handle is dropped. pub fn scope<'a, T: 'a, E: 'a, F>( &'a self, data: impl PinInit<T, E> + 'a, name: &'a CStr, init: F, ) -> impl PinInit<Scope<T>, E> + 'a where F: for<'data, 'dir> FnOnce(&'data T, &'dir ScopedDir<'data, 'dir>) + 'a, { Scope::new(data, |data| { let scoped = self.scoped_dir(name); init(data, &scoped); scoped.into_entry() }) }} #[pin_data]/// Handle to a DebugFS scope, which ensures that attached `data` will outlive the DebugFS entry/// without moving.////// This is internally used to back [`File`], and used in the API to represent the attachment/// of a directory lifetime to a data structure which may be jointly accessed by a number of/// different files.////// When dropped, a `Scope` will remove all directories and files in the filesystem backed by the/// attached data structure prior to releasing the attached data.pub struct Scope<T> { // This order is load-bearing for drops - `_entry` must be dropped before `data`. #[cfg(CONFIG_DEBUG_FS)] _entry: Entry<'static>, #[pin] data: T, // Even if `T` is `Unpin`, we still can't allow it to be moved. #[pin] _pin: PhantomPinned,} #[pin_data]/// Handle to a DebugFS file, owning its backing data.////// When dropped, the DebugFS file will be removed and the attached data will be dropped.pub struct File<T> { #[pin] scope: Scope<T>,} #[cfg(not(CONFIG_DEBUG_FS))]impl<'b, T: 'b> Scope<T> { fn new<E: 'b, F>(data: impl PinInit<T, E> + 'b, init: F) -> impl PinInit<Self, E> + 'b where F: for<'a> FnOnce(&'a T) + 'b, { try_pin_init! { Self { data <- data, _pin: PhantomPinned } ? E } .pin_chain(|scope| { init(&scope.data); Ok(()) }) }} #[cfg(CONFIG_DEBUG_FS)]impl<'b, T: 'b> Scope<T> { fn entry_mut(self: Pin<&mut Self>) -> &mut Entry<'static> { // SAFETY: _entry is not structurally pinned. unsafe { &mut Pin::into_inner_unchecked(self)._entry } } fn new<E: 'b, F>(data: impl PinInit<T, E> + 'b, init: F) -> impl PinInit<Self, E> + 'b where F: for<'a> FnOnce(&'a T) -> Entry<'static> + 'b, { try_pin_init! { Self { _entry: Entry::empty(), data <- data, _pin: PhantomPinned } ? E } .pin_chain(|scope| { *scope.entry_mut() = init(&scope.data); Ok(()) }) }} impl<'a, T: 'a> Scope<T> { /// Creates a new scope, which is a directory at the root of the debugfs filesystem, /// associated with some data `T`. /// /// The `init` closure is called to populate the directory with files and subdirectories. These /// files can reference the data stored in the scope. /// /// The entire directory tree created within the scope will be removed when the returned /// `Scope` handle is dropped. pub fn dir<E: 'a, F>( data: impl PinInit<T, E> + 'a, name: &'a CStr, init: F, ) -> impl PinInit<Self, E> + 'a where F: for<'data, 'dir> FnOnce(&'data T, &'dir ScopedDir<'data, 'dir>) + 'a, { Scope::new(data, |data| { let scoped = ScopedDir::new(name); init(data, &scoped); scoped.into_entry() }) }} impl<T> Deref for Scope<T> { type Target = T; fn deref(&self) -> &T { &self.data }} impl<T> Deref for File<T> { type Target = T; fn deref(&self) -> &T { &self.scope }} /// A handle to a directory which will live at most `'dir`, accessing data that will live for at/// least `'data`.////// Dropping a ScopedDir will not delete or clean it up, this is expected to occur through dropping/// the `Scope` that created it.pub struct ScopedDir<'data, 'dir> { #[cfg(CONFIG_DEBUG_FS)] entry: ManuallyDrop<Entry<'dir>>, _phantom: PhantomData<fn(&'data ()) -> &'dir ()>,} impl<'data, 'dir> ScopedDir<'data, 'dir> { /// Creates a subdirectory inside this `ScopedDir`. /// /// The returned directory handle cannot outlive this one. pub fn dir<'dir2>(&'dir2 self, name: &CStr) -> ScopedDir<'data, 'dir2> { #[cfg(not(CONFIG_DEBUG_FS))] let _ = name; ScopedDir { #[cfg(CONFIG_DEBUG_FS)] entry: ManuallyDrop::new(Entry::dir(name, Some(&*self.entry))), _phantom: PhantomData, } } fn create_file<T: Sync>(&self, name: &CStr, data: &'data T, vtable: &'static FileOps<T>) { #[cfg(CONFIG_DEBUG_FS)] core::mem::forget(Entry::file(name, &self.entry, data, vtable)); } /// Creates a read-only file in this directory. /// /// The file's contents are produced by invoking [`Writer::write`]. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_only_file<T: Writer + Send + Sync + 'static>(&self, name: &CStr, data: &'data T) { self.create_file(name, data, &T::FILE_OPS) } /// Creates a read-only file in this directory, with contents from a callback. /// /// The file contents are generated by calling `f` with `data`. /// /// /// `f` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_callback_file<T, F>(&self, name: &CStr, data: &'data T, _f: &'static F) where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, { let vtable = <FormatAdapter<T, F> as ReadFile<_>>::FILE_OPS.adapt(); self.create_file(name, data, vtable) } /// Creates a read-write file in this directory. /// /// Reading the file uses the [`Writer`] implementation on `data`. Writing to the file uses /// the [`Reader`] implementation on `data`. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_write_file<T: Writer + Reader + Send + Sync + 'static>( &self,Lines 1–500 of 594. Load more
// 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))] use crate::prelude::*; use crate::str::CStr; #[cfg(CONFIG_DEBUG_FS)] use crate::sync::Arc; use crate::uaccess::UserSliceReader; use core::fmt; use core::marker::PhantomData; use core::marker::PhantomPinned; #[cfg(CONFIG_DEBUG_FS)] use core::mem::ManuallyDrop; use core::ops::Deref; mod traits; pub use traits::{Reader, Writer}; mod callback_adapters; use callback_adapters::{FormatAdapter, NoWriter, WritableAdapter}; mod file_ops; use file_ops::{FileOps, ReadFile, ReadWriteFile, WriteFile}; #[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<'static>>>); 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() } /// Creates a DebugFS file which will own the data produced by the initializer provided in /// `data`. fn create_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, file_ops: &'static FileOps<T>, ) -> impl PinInit<File<T>, E> + 'a where T: Sync + 'static, { let scope = Scope::<T>::new(data, move |data| { #[cfg(CONFIG_DEBUG_FS)] if let Some(parent) = &self.0 { // SAFETY: Because data derives from a scope, and our entry will be dropped before // the data is dropped, it is guaranteed to outlive the entry we return. unsafe { Entry::dynamic_file(name, parent.clone(), data, file_ops) } } else { Entry::empty() } }); try_pin_init! { File { scope <- scope } ? E } } /// 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)) } /// Creates a read-only file in this directory. /// /// The file's contents are produced by invoking [`Writer::write`] on the value initialized by /// `data`. /// /// # Examples /// /// ``` /// # use kernel::c_str; /// # use kernel::debugfs::Dir; /// # use kernel::prelude::*; /// # let dir = Dir::new(c_str!("my_debugfs_dir")); /// let file = KBox::pin_init(dir.read_only_file(c_str!("foo"), 200), GFP_KERNEL)?; /// // "my_debugfs_dir/foo" now contains the number 200. /// // The file is removed when `file` is dropped. /// # Ok::<(), Error>(()) /// ``` pub fn read_only_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Writer + Send + Sync + 'static, { let file_ops = &<T as ReadFile<_>>::FILE_OPS; self.create_file(name, data, file_ops) } /// Creates a read-only file in this directory, with contents from a callback. /// /// `f` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. /// /// # Examples /// /// ``` /// # use core::sync::atomic::{AtomicU32, Ordering}; /// # use kernel::c_str; /// # use kernel::debugfs::Dir; /// # use kernel::prelude::*; /// # let dir = Dir::new(c_str!("foo")); /// let file = KBox::pin_init( /// dir.read_callback_file(c_str!("bar"), /// AtomicU32::new(3), /// &|val, f| { /// let out = val.load(Ordering::Relaxed); /// writeln!(f, "{out:#010x}") /// }), /// GFP_KERNEL)?; /// // Reading "foo/bar" will show "0x00000003". /// file.store(10, Ordering::Relaxed); /// // Reading "foo/bar" will now show "0x0000000a". /// # Ok::<(), Error>(()) /// ``` pub fn read_callback_file<'a, T, E: 'a, F>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _f: &'static F, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, { let file_ops = <FormatAdapter<T, F>>::FILE_OPS.adapt(); self.create_file(name, data, file_ops) } /// Creates a read-write file in this directory. /// /// Reading the file uses the [`Writer`] implementation. /// Writing to the file uses the [`Reader`] implementation. pub fn read_write_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Writer + Reader + Send + Sync + 'static, { let file_ops = &<T as ReadWriteFile<_>>::FILE_OPS; self.create_file(name, data, file_ops) } /// Creates a read-write file in this directory, with logic from callbacks. /// /// Reading from the file is handled by `f`. Writing to the file is handled by `w`. /// /// `f` and `w` must be function items or non-capturing closures. /// This is statically asserted and not a safety requirement. pub fn read_write_callback_file<'a, T, E: 'a, F, W>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _f: &'static F, _w: &'static W, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync, { let file_ops = <WritableAdapter<FormatAdapter<T, F>, W> as file_ops::ReadWriteFile<_>>::FILE_OPS .adapt() .adapt(); self.create_file(name, data, file_ops) } /// Creates a write-only file in this directory. /// /// The file owns its backing data. Writing to the file uses the [`Reader`] /// implementation. /// /// The file is removed when the returned [`File`] is dropped. pub fn write_only_file<'a, T, E: 'a>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, ) -> impl PinInit<File<T>, E> + 'a where T: Reader + Send + Sync + 'static, { self.create_file(name, data, &T::FILE_OPS) } /// Creates a write-only file in this directory, with write logic from a callback. /// /// `w` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. pub fn write_callback_file<'a, T, E: 'a, W>( &'a self, name: &'a CStr, data: impl PinInit<T, E> + 'a, _w: &'static W, ) -> impl PinInit<File<T>, E> + 'a where T: Send + Sync + 'static, W: Fn(&T, &mut UserSliceReader) -> Result + Send + Sync, { let file_ops = <WritableAdapter<NoWriter<T>, W> as WriteFile<_>>::FILE_OPS .adapt() .adapt(); self.create_file(name, data, file_ops) } // While this function is safe, it is intentionally not public because it's a bit of a // footgun. // // Unless you also extract the `entry` later and schedule it for `Drop` at the appropriate // time, a `ScopedDir` with a `Dir` parent will never be deleted. fn scoped_dir<'data>(&self, name: &CStr) -> ScopedDir<'data, 'static> { #[cfg(CONFIG_DEBUG_FS)] { let parent_entry = match &self.0 { None => return ScopedDir::empty(), Some(entry) => entry.clone(), }; ScopedDir { entry: ManuallyDrop::new(Entry::dynamic_dir(name, Some(parent_entry))), _phantom: PhantomData, } } #[cfg(not(CONFIG_DEBUG_FS))] ScopedDir::empty() } /// Creates a new scope, which is a directory associated with some data `T`. /// /// The created directory will be a subdirectory of `self`. The `init` closure is called to /// populate the directory with files and subdirectories. These files can reference the data /// stored in the scope. /// /// The entire directory tree created within the scope will be removed when the returned /// `Scope` handle is dropped. pub fn scope<'a, T: 'a, E: 'a, F>( &'a self, data: impl PinInit<T, E> + 'a, name: &'a CStr, init: F, ) -> impl PinInit<Scope<T>, E> + 'a where F: for<'data, 'dir> FnOnce(&'data T, &'dir ScopedDir<'data, 'dir>) + 'a, { Scope::new(data, |data| { let scoped = self.scoped_dir(name); init(data, &scoped); scoped.into_entry() }) } } #[pin_data] /// Handle to a DebugFS scope, which ensures that attached `data` will outlive the DebugFS entry /// without moving. /// /// This is internally used to back [`File`], and used in the API to represent the attachment /// of a directory lifetime to a data structure which may be jointly accessed by a number of /// different files. /// /// When dropped, a `Scope` will remove all directories and files in the filesystem backed by the /// attached data structure prior to releasing the attached data. pub struct Scope<T> { // This order is load-bearing for drops - `_entry` must be dropped before `data`. #[cfg(CONFIG_DEBUG_FS)] _entry: Entry<'static>, #[pin] data: T, // Even if `T` is `Unpin`, we still can't allow it to be moved. #[pin] _pin: PhantomPinned, } #[pin_data] /// Handle to a DebugFS file, owning its backing data. /// /// When dropped, the DebugFS file will be removed and the attached data will be dropped. pub struct File<T> { #[pin] scope: Scope<T>, } #[cfg(not(CONFIG_DEBUG_FS))] impl<'b, T: 'b> Scope<T> { fn new<E: 'b, F>(data: impl PinInit<T, E> + 'b, init: F) -> impl PinInit<Self, E> + 'b where F: for<'a> FnOnce(&'a T) + 'b, { try_pin_init! { Self { data <- data, _pin: PhantomPinned } ? E } .pin_chain(|scope| { init(&scope.data); Ok(()) }) } } #[cfg(CONFIG_DEBUG_FS)] impl<'b, T: 'b> Scope<T> { fn entry_mut(self: Pin<&mut Self>) -> &mut Entry<'static> { // SAFETY: _entry is not structurally pinned. unsafe { &mut Pin::into_inner_unchecked(self)._entry } } fn new<E: 'b, F>(data: impl PinInit<T, E> + 'b, init: F) -> impl PinInit<Self, E> + 'b where F: for<'a> FnOnce(&'a T) -> Entry<'static> + 'b, { try_pin_init! { Self { _entry: Entry::empty(), data <- data, _pin: PhantomPinned } ? E } .pin_chain(|scope| { *scope.entry_mut() = init(&scope.data); Ok(()) }) } } impl<'a, T: 'a> Scope<T> { /// Creates a new scope, which is a directory at the root of the debugfs filesystem, /// associated with some data `T`. /// /// The `init` closure is called to populate the directory with files and subdirectories. These /// files can reference the data stored in the scope. /// /// The entire directory tree created within the scope will be removed when the returned /// `Scope` handle is dropped. pub fn dir<E: 'a, F>( data: impl PinInit<T, E> + 'a, name: &'a CStr, init: F, ) -> impl PinInit<Self, E> + 'a where F: for<'data, 'dir> FnOnce(&'data T, &'dir ScopedDir<'data, 'dir>) + 'a, { Scope::new(data, |data| { let scoped = ScopedDir::new(name); init(data, &scoped); scoped.into_entry() }) } } impl<T> Deref for Scope<T> { type Target = T; fn deref(&self) -> &T { &self.data } } impl<T> Deref for File<T> { type Target = T; fn deref(&self) -> &T { &self.scope } } /// A handle to a directory which will live at most `'dir`, accessing data that will live for at /// least `'data`. /// /// Dropping a ScopedDir will not delete or clean it up, this is expected to occur through dropping /// the `Scope` that created it. pub struct ScopedDir<'data, 'dir> { #[cfg(CONFIG_DEBUG_FS)] entry: ManuallyDrop<Entry<'dir>>, _phantom: PhantomData<fn(&'data ()) -> &'dir ()>, } impl<'data, 'dir> ScopedDir<'data, 'dir> { /// Creates a subdirectory inside this `ScopedDir`. /// /// The returned directory handle cannot outlive this one. pub fn dir<'dir2>(&'dir2 self, name: &CStr) -> ScopedDir<'data, 'dir2> { #[cfg(not(CONFIG_DEBUG_FS))] let _ = name; ScopedDir { #[cfg(CONFIG_DEBUG_FS)] entry: ManuallyDrop::new(Entry::dir(name, Some(&*self.entry))), _phantom: PhantomData, } } fn create_file<T: Sync>(&self, name: &CStr, data: &'data T, vtable: &'static FileOps<T>) { #[cfg(CONFIG_DEBUG_FS)] core::mem::forget(Entry::file(name, &self.entry, data, vtable)); } /// Creates a read-only file in this directory. /// /// The file's contents are produced by invoking [`Writer::write`]. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_only_file<T: Writer + Send + Sync + 'static>(&self, name: &CStr, data: &'data T) { self.create_file(name, data, &T::FILE_OPS) } /// Creates a read-only file in this directory, with contents from a callback. /// /// The file contents are generated by calling `f` with `data`. /// /// /// `f` must be a function item or a non-capturing closure. /// This is statically asserted and not a safety requirement. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_callback_file<T, F>(&self, name: &CStr, data: &'data T, _f: &'static F) where T: Send + Sync + 'static, F: Fn(&T, &mut fmt::Formatter<'_>) -> fmt::Result + Send + Sync, { let vtable = <FormatAdapter<T, F> as ReadFile<_>>::FILE_OPS.adapt(); self.create_file(name, data, vtable) } /// Creates a read-write file in this directory. /// /// Reading the file uses the [`Writer`] implementation on `data`. Writing to the file uses /// the [`Reader`] implementation on `data`. /// /// This function does not produce an owning handle to the file. The created /// file is removed when the [`Scope`] that this directory belongs /// to is dropped. pub fn read_write_file<T: Writer + Reader + Send + Sync + 'static>( &self,