|
| 1 | +// SPDX-License-Identifier: GPL-2.0 |
| 2 | + |
| 3 | +//! Rust implementation of `debugfs`. |
| 4 | +//! |
| 5 | +//! This module allows Rust kernel modules to create directories and files in |
| 6 | +//! `/debugfs`. |
| 7 | +//! |
| 8 | +//! C header: [`include/linux/debugfs.h`](../../../include/linux/debugfs.h) |
| 9 | +//! |
| 10 | +//! Reference: <https://www.kernel.org/doc/html/latest/filesystems/debugfs.html> |
| 11 | +
|
| 12 | +use alloc::boxed::Box; |
| 13 | +use core::{ |
| 14 | + any::Any, |
| 15 | + marker::{PhantomData, Sync}, |
| 16 | + ptr, |
| 17 | +}; |
| 18 | + |
| 19 | +use crate::{ |
| 20 | + bindings::{self, debugfs_remove_with_callback}, |
| 21 | + error, |
| 22 | + file::{OpenAdapter, Operations, OperationsVtable}, |
| 23 | + str::CStr, |
| 24 | + types::PointerWrapper, |
| 25 | + Result, |
| 26 | +}; |
| 27 | + |
| 28 | +/// An `dentry` for a directory in debugfs. |
| 29 | +pub struct DebugFsDirectory { |
| 30 | + dentry: *mut bindings::dentry, |
| 31 | + has_parent: bool, |
| 32 | +} |
| 33 | + |
| 34 | +// SAFETY: There are no public functions that take a shared [`DebugFsDirectory`] |
| 35 | +// reference and all its fields are private so a thread can't actually do |
| 36 | +// anything with a `&DebugFsDirectory`. This makes it is safe to share across |
| 37 | +// threads. |
| 38 | +unsafe impl Sync for DebugFsDirectory {} |
| 39 | + |
| 40 | +impl DebugFsDirectory { |
| 41 | + /// Create a new directory in `debugfs` under `parent`. If `parent` is |
| 42 | + /// `None`, it will be created at the `debugfs` root. The directory will be |
| 43 | + /// recursively removed on drop. |
| 44 | + pub fn create(name: &CStr, parent: Option<&mut DebugFsDirectory>) -> Result<Self> { |
| 45 | + let name = name.as_char_ptr(); |
| 46 | + let has_parent = parent.is_some(); |
| 47 | + let parent_ptr = parent.map(|p| p.dentry).unwrap_or_else(ptr::null_mut); |
| 48 | + // SAFETY: Calling a C function. `name` is a valid null-terminated |
| 49 | + // string because it came from a [`CStr`] and `parent` is either null or |
| 50 | + // valid because it came from a [`DebugFsDirectory`]. |
| 51 | + let dentry = |
| 52 | + error::from_kernel_err_ptr(unsafe { bindings::debugfs_create_dir(name, parent_ptr) })?; |
| 53 | + Ok(DebugFsDirectory { dentry, has_parent }) |
| 54 | + } |
| 55 | +} |
| 56 | + |
| 57 | +impl Drop for DebugFsDirectory { |
| 58 | + fn drop(&mut self) { |
| 59 | + // If this entry has a parent, we don't need to worry about removal |
| 60 | + // because the parent will remove its children when dropped. Otherwise |
| 61 | + // we need to clean up. |
| 62 | + if !self.has_parent { |
| 63 | + // SAFETY: Calling a C function. `dentry` must have been created by |
| 64 | + // a call to `DebugFsDirectory::create` which always returns a |
| 65 | + // valid `dentry`. There is no parent, so the |
| 66 | + // `dentry` couldn't have been removed and must still be valid. |
| 67 | + // |
| 68 | + // This `dentry` and every `dentry` in it was created with either |
| 69 | + // `DebugFsDirectory::create` or `DebugFsFile::create`. Both |
| 70 | + // functions guarantee that the created `dentry` has a valide |
| 71 | + // `inode` and the `inode`'s `i_private` field will be either null |
| 72 | + // or come from calling `PointerWrapper::into_pointer` on a |
| 73 | + // `Box<Box<dyn Any>>`. They both only create dentry's in debugfs. |
| 74 | + // This makes it safe to call `remove_rust_dentry` on each `dentry` |
| 75 | + // in `self.dentry`. |
| 76 | + unsafe { debugfs_remove_with_callback(self.dentry, Some(remove_rust_dentry)) }; |
| 77 | + } |
| 78 | + } |
| 79 | +} |
| 80 | + |
| 81 | +/// A `dentry` for a file in debugfs with a `T` stored in `i_private`. |
| 82 | +pub struct DebugFsFile<T> { |
| 83 | + dentry: Option<*mut bindings::dentry>, |
| 84 | + _t: PhantomData<T>, |
| 85 | +} |
| 86 | + |
| 87 | +// SAFETY: There are no public methods available on [`DebugFsFile`] so a thread |
| 88 | +// can't actually do anything with a `&DebugFsFile`. This makes it is safe to |
| 89 | +// share across threads. |
| 90 | +unsafe impl<T> Sync for DebugFsFile<T> {} |
| 91 | + |
| 92 | +impl<T: Any> DebugFsFile<T> { |
| 93 | + /// Create a file in the `debugfs` directory under `parent`. If `parent` is |
| 94 | + /// `None` then the file will be created at the root of the `debugfs` |
| 95 | + /// directory. |
| 96 | + /// |
| 97 | + /// # Safety |
| 98 | + /// |
| 99 | + /// `fops` must be valid when opening an `inode` with a `Box<Box<dyn |
| 100 | + /// Any>>::into_pointer` that can be downcast to `T` stored in `i_private`. |
| 101 | + #[allow(dead_code)] // Remove when a caller is implemented. |
| 102 | + pub(crate) unsafe fn create( |
| 103 | + name: &CStr, |
| 104 | + parent: Option<&mut DebugFsDirectory>, |
| 105 | + data: T, |
| 106 | + fops: &'static bindings::file_operations, |
| 107 | + ) -> Result<DebugFsFile<T>> { |
| 108 | + let has_parent = parent.is_some(); |
| 109 | + let name = name.as_char_ptr(); |
| 110 | + let boxed1: Box<dyn Any> = Box::try_new(data)?; |
| 111 | + let boxed2 = Box::try_new(boxed1)?; |
| 112 | + let data = PointerWrapper::into_pointer(boxed2) as *mut _; |
| 113 | + let parent = parent.map(|p| p.dentry).unwrap_or_else(ptr::null_mut); |
| 114 | + // SAFETY: Calling a C function. `name` will be a valid null-terminated |
| 115 | + // string because it came from a [`CStr`]. The caller guarantees that |
| 116 | + // `fops` is valid for an inode with a `Box<Box<dyn Any>>::into_pointer` |
| 117 | + // that can be downcast to `T` stored in `i_private`. |
| 118 | + let dentry_ptr = error::from_kernel_err_ptr(unsafe { |
| 119 | + bindings::debugfs_create_file(name, 0, parent, data, fops) |
| 120 | + }); |
| 121 | + match dentry_ptr { |
| 122 | + Err(err) => { |
| 123 | + // SAFETY: `data` was created by calling |
| 124 | + // `PointerWrapper::into_pointer` on a `Box<Box<dyn Any>>` just |
| 125 | + // above. |
| 126 | + let _: Box<Box<dyn Any>> = unsafe { PointerWrapper::from_pointer(data) }; |
| 127 | + Err(err) |
| 128 | + } |
| 129 | + Ok(dentry) => Ok(DebugFsFile { |
| 130 | + dentry: if has_parent { None } else { Some(dentry) }, |
| 131 | + _t: PhantomData, |
| 132 | + }), |
| 133 | + } |
| 134 | + } |
| 135 | +} |
| 136 | + |
| 137 | +impl<T> Drop for DebugFsFile<T> { |
| 138 | + fn drop(&mut self) { |
| 139 | + // If there is no dentry then this file has a parent `DebugFsDirectory` |
| 140 | + // which is responsible for removal. |
| 141 | + if let Some(dentry) = self.dentry { |
| 142 | + // SAFETY: Calling a C function. `dentry` must have been created by |
| 143 | + // a call to [`DebugFsFile::create`] which always returns a valid |
| 144 | + // `dentry`. Since there is no parent that can remove the `dentry` |
| 145 | + // it must still exist. |
| 146 | + // |
| 147 | + // A `DebugFsFile` is created by calling `debugfs_create_file` |
| 148 | + // (which always creates a valid `dentry` in debugfs with a valid |
| 149 | + // `d_inode` field) and passing in a pointer coming from a |
| 150 | + // `Box<Box<dyn Any>>` which gets put in the `inode`'s `i_private` |
| 151 | + // field. This is sufficient for `remove_rust_dentry` to be safely |
| 152 | + // called on the `dentry`. |
| 153 | + unsafe { debugfs_remove_with_callback(dentry, Some(remove_rust_dentry)) }; |
| 154 | + } |
| 155 | + } |
| 156 | +} |
| 157 | + |
| 158 | +/// # Safety |
| 159 | +/// `dentry` must be a valid `bindings::dentry` with a valid `d_inode` field. In |
| 160 | +/// addition, the `i_private` field of `d_inode` must be either a null pointer |
| 161 | +/// or one created by calling `PointerWrapper::into_pointer` on a `Box<Box<dyn |
| 162 | +/// Any>>`. |
| 163 | +unsafe extern "C" fn drop_i_private(dentry: *mut bindings::dentry) { |
| 164 | + // SAFETY: Caller guarantees that `dentry->d_inode` can be dereferenced. |
| 165 | + let i_private = unsafe { (*(*dentry).d_inode).i_private }; |
| 166 | + // SAFETY: Caller guarantees that `dentry->d_inode->i_private` is either |
| 167 | + // null, or generated by calling `PointerWrapper::into_pointer` on a |
| 168 | + // `Box<Box<dyn Any>>`. |
| 169 | + if !i_private.is_null() { |
| 170 | + let _: Box<Box<dyn Any>> = unsafe { PointerWrapper::from_pointer(i_private) }; |
| 171 | + } |
| 172 | +} |
| 173 | + |
| 174 | +/// # Safety |
| 175 | +/// `dentry` must be in debugfs and satify all the requirements for |
| 176 | +/// `drop_i_private` to be safely called on it. |
| 177 | +unsafe extern "C" fn remove_rust_dentry(dentry: *mut bindings::dentry) { |
| 178 | + // SAFETY: The caller is responsible for ensuring that `drop_i_private` can |
| 179 | + // be called on `dentry` and that the dentry is in debugfs. |
| 180 | + unsafe { bindings::debugfs_remove_one_with_callback(dentry, Some(drop_i_private)) } |
| 181 | +} |
| 182 | + |
| 183 | +impl<T: Any + Sync> OpenAdapter<T> for DebugFsFile<T> { |
| 184 | + unsafe fn convert(inode: *mut bindings::inode, _file: *mut bindings::file) -> *const T { |
| 185 | + let data: &dyn Any = |
| 186 | + unsafe { <Box<Box<dyn Any>> as PointerWrapper>::borrow((*inode).i_private) }.as_ref(); |
| 187 | + let open_data: &T = match data.downcast_ref() { |
| 188 | + Some(data) => data, |
| 189 | + None => panic!(), |
| 190 | + }; |
| 191 | + open_data |
| 192 | + } |
| 193 | +} |
| 194 | + |
| 195 | +/// TODOABK |
| 196 | +pub fn debugfs_create<T: Operations>( |
| 197 | + name: &CStr, |
| 198 | + parent: Option<&mut DebugFsDirectory>, |
| 199 | + data: T::OpenData, |
| 200 | +) -> Result<DebugFsFile<T::OpenData>> |
| 201 | +where |
| 202 | + T::OpenData: 'static, |
| 203 | +{ |
| 204 | + // TODOABK |
| 205 | + unsafe { |
| 206 | + DebugFsFile::create( |
| 207 | + name, |
| 208 | + parent, |
| 209 | + data, |
| 210 | + OperationsVtable::<DebugFsFile<T::OpenData>, T>::build(), |
| 211 | + ) |
| 212 | + } |
| 213 | +} |
0 commit comments