Commit d4a5d397 authored by Matthew Maurer's avatar Matthew Maurer Committed by Danilo Krummrich
Browse files

samples: rust: Add scoped debugfs sample driver 



Adds a new sample driver `rust_scoped_debugfs` that demonstrates the
use of the scoped debugfs APIs.

The driver creates a `control` directory with two write-only files,
`create` and `remove`. Writing a name and a series of numbers to
`create` will create a new subdirectory under a `dynamic` directory.
This new subdirectory will contain files that expose the numbers as
atomic values.

Writing a name to `remove` will remove the corresponding subdirectory
from the `dynamic` directory.

This sample serves as an example of how to use the `debugfs::Scope`
and `debugfs::ScopedDir` APIs to create and manage debugfs entries
that are tied to the lifetime of a data structure.

Signed-off-by: default avatarMatthew Maurer <mmaurer@google.com>
Tested-by: default avatarDirk Behme <dirk.behme@de.bosch.com>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/20250904-debugfs-rust-v11-7-7d12a165685a@google.com


[ Rename "scoped_debugfs" -> "debugfs_scoped", fix up
  Result<(), Error> -> Result. - Danilo ]
Signed-off-by: default avatarDanilo Krummrich <dakr@kernel.org>
parent 5f094258

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -7497,6 +7497,7 @@ F: rust/kernel/driver.rs 
F:	rust/kernel/faux.rs

F:	rust/kernel/platform.rs

F:	samples/rust/rust_debugfs.rs

F:	samples/rust/rust_debugfs_scoped.rs

F:	samples/rust/rust_driver_platform.rs

F:	samples/rust/rust_driver_faux.rs
































samples/rust/Kconfig



+11
−0






























Original line number
Diff line number
Diff line







@@ -73,6 +73,17 @@ config SAMPLE_RUST_DEBUGFS

















	  If unsure, say N.



















config SAMPLE_RUST_DEBUGFS_SCOPED









	tristate "Scoped DebugFS Test Module"









	depends on DEBUG_FS









	help









	  This option builds the Rust Scoped DebugFS Test module sample.



















	  To compile this as a module, choose M here:









	  the module will be called rust_debugfs_scoped.



















	  If unsure, say N.



















config SAMPLE_RUST_DRIVER_PCI









	tristate "PCI Driver"









	depends on PCI
































samples/rust/Makefile



+1
−0






























Original line number
Diff line number
Diff line







@@ -5,6 +5,7 @@ obj-$(CONFIG_SAMPLE_RUST_MINIMAL)		+= rust_minimal.o







obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE)		+= rust_misc_device.o









obj-$(CONFIG_SAMPLE_RUST_PRINT)			+= rust_print.o









obj-$(CONFIG_SAMPLE_RUST_DEBUGFS)		+= rust_debugfs.o









obj-$(CONFIG_SAMPLE_RUST_DEBUGFS_SCOPED)	+= rust_debugfs_scoped.o









obj-$(CONFIG_SAMPLE_RUST_DMA)			+= rust_dma.o









obj-$(CONFIG_SAMPLE_RUST_DRIVER_PCI)		+= rust_driver_pci.o









obj-$(CONFIG_SAMPLE_RUST_DRIVER_PLATFORM)	+= rust_driver_platform.o
































samples/rust/rust_debugfs_scoped.rs
0 → 100644



+134
−0






























Original line number
Diff line number
Diff line









// SPDX-License-Identifier: GPL-2.0



















// Copyright (C) 2025 Google LLC.



















//! Sample DebugFS exporting platform driver that demonstrates the use of









//! `Scope::dir` to create a variety of files without the need to separately









//! track them all.



















use core::sync::atomic::AtomicUsize;









use kernel::debugfs::{Dir, Scope};









use kernel::prelude::*;









use kernel::sync::Mutex;









use kernel::{c_str, new_mutex, str::CString};



















module! {









    type: RustScopedDebugFs,









    name: "rust_debugfs_scoped",









    authors: ["Matthew Maurer"],









    description: "Rust Scoped DebugFS usage sample",









    license: "GPL",









}



















fn remove_file_write(









    mod_data: &ModuleData,









    reader: &mut kernel::uaccess::UserSliceReader,









) -> Result {









    let mut buf = [0u8; 128];









    if reader.len() >= buf.len() {









        return Err(EINVAL);









    }









    let n = reader.len();









    reader.read_slice(&mut buf[..n])?;



















    let s = core::str::from_utf8(&buf[..n]).map_err(|_| EINVAL)?.trim();









    let nul_idx = s.len();









    buf[nul_idx] = 0;









    let to_remove = CStr::from_bytes_with_nul(&buf[..nul_idx + 1]).map_err(|_| EINVAL)?;









    mod_data









        .devices









        .lock()









        .retain(|device| device.name.as_bytes() != to_remove.as_bytes());









    Ok(())









}



















fn create_file_write(









    mod_data: &ModuleData,









    reader: &mut kernel::uaccess::UserSliceReader,









) -> Result {









    let mut buf = [0u8; 128];









    if reader.len() > buf.len() {









        return Err(EINVAL);









    }









    let n = reader.len();









    reader.read_slice(&mut buf[..n])?;



















    let mut nums = KVec::new();



















    let s = core::str::from_utf8(&buf[..n]).map_err(|_| EINVAL)?.trim();









    let mut items = s.split_whitespace();









    let name_str = items.next().ok_or(EINVAL)?;









    let name = CString::try_from_fmt(fmt!("{name_str}"))?;









    let file_name = CString::try_from_fmt(fmt!("{name_str}"))?;









    for sub in items {









        nums.push(









            AtomicUsize::new(sub.parse().map_err(|_| EINVAL)?),









            GFP_KERNEL,









        )?;









    }



















    let scope = KBox::pin_init(









        mod_data









            .device_dir









            .scope(DeviceData { name, nums }, &file_name, |dev_data, dir| {









                for (idx, val) in dev_data.nums.iter().enumerate() {









                    let Ok(name) = CString::try_from_fmt(fmt!("{idx}")) else {









                        return;









                    };









                    dir.read_write_file(&name, val);









                }









            }),









        GFP_KERNEL,









    )?;









    (*mod_data.devices.lock()).push(scope, GFP_KERNEL)?;



















    Ok(())









}



















struct RustScopedDebugFs {









    _data: Pin<KBox<Scope<ModuleData>>>,









}



















#[pin_data]









struct ModuleData {









    device_dir: Dir,









    #[pin]









    devices: Mutex<KVec<Pin<KBox<Scope<DeviceData>>>>>,









}



















impl ModuleData {









    fn init(device_dir: Dir) -> impl PinInit<Self> {









        pin_init! {









            Self {









                device_dir: device_dir,









                devices <- new_mutex!(KVec::new())









            }









        }









    }









}



















struct DeviceData {









    name: CString,









    nums: KVec<AtomicUsize>,









}



















fn init_control(base_dir: &Dir, dyn_dirs: Dir) -> impl PinInit<Scope<ModuleData>> + '_ {









    base_dir.scope(









        ModuleData::init(dyn_dirs),









        c_str!("control"),









        |data, dir| {









            dir.write_only_callback_file(c_str!("create"), data, &create_file_write);









            dir.write_only_callback_file(c_str!("remove"), data, &remove_file_write);









        },









    )









}



















impl kernel::Module for RustScopedDebugFs {









    fn init(_module: &'static kernel::ThisModule) -> Result<Self> {









        let base_dir = Dir::new(c_str!("rust_scoped_debugfs"));









        let dyn_dirs = base_dir.subdir(c_str!("dynamic"));









        Ok(Self {









            _data: KBox::pin_init(init_control(&base_dir, dyn_dirs), GFP_KERNEL)?,









        })









    }









}