xref: /linux/rust/kernel/debugfs/file_ops.rs (revision 486b257357c23743d9729ea715136d105fff461e)
1 // SPDX-License-Identifier: GPL-2.0
2 // Copyright (C) 2025 Google LLC.
3 
4 use super::{
5     BinaryReader,
6     BinaryWriter,
7     Reader,
8     Writer, //
9 };
10 
11 use crate::{
12     debugfs::callback_adapters::Adapter,
13     fmt,
14     fs::file,
15     prelude::*,
16     seq_file::SeqFile,
17     seq_print,
18     uaccess::UserSlice, //
19 };
20 
21 use core::marker::PhantomData;
22 
23 /// # Invariant
24 ///
25 /// `FileOps<T>` will always contain an `operations` which is safe to use for a file backed
26 /// off an inode which has a pointer to a `T` in its private data that is safe to convert
27 /// into a reference.
28 pub(super) struct FileOps<T> {
29     #[cfg(CONFIG_DEBUG_FS)]
30     operations: &'static bindings::file_operations,
31     #[cfg(CONFIG_DEBUG_FS)]
32     mode: u16,
33     _phantom: PhantomData<T>,
34 }
35 
36 impl<T> FileOps<T> {
37     /// # Safety
38     ///
39     /// The caller asserts that the provided `operations` is safe to use for a file whose
40     /// inode has a pointer to `T` in its private data that is safe to convert into a reference.
41     const unsafe fn new(operations: &'static bindings::file_operations, mode: u16) -> Self {
42         Self {
43             #[cfg(CONFIG_DEBUG_FS)]
44             operations,
45             #[cfg(CONFIG_DEBUG_FS)]
46             mode,
47             _phantom: PhantomData,
48         }
49     }
50 
51     #[cfg(CONFIG_DEBUG_FS)]
52     pub(crate) const fn mode(&self) -> u16 {
53         self.mode
54     }
55 }
56 
57 impl<T: Adapter> FileOps<T> {
58     pub(super) const fn adapt(&self) -> &FileOps<T::Inner> {
59         // SAFETY: `Adapter` asserts that `T` can be legally cast to `T::Inner`.
60         unsafe { core::mem::transmute(self) }
61     }
62 }
63 
64 #[cfg(CONFIG_DEBUG_FS)]
65 impl<T> FileOps<T> {
66     /// Returns a `'static` reference to the inner `file_operations`.
67     #[inline]
68     pub(crate) fn fops(&self) -> &'static bindings::file_operations {
69         self.operations
70     }
71 }
72 
73 struct WriterAdapter<T>(T);
74 
75 impl<'a, T: Writer> fmt::Display for WriterAdapter<&'a T> {
76     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77         self.0.write(f)
78     }
79 }
80 
81 /// Implements `open` for `file_operations` via `single_open` to fill out a `seq_file`.
82 ///
83 /// # Safety
84 ///
85 /// * `inode`'s private pointer must point to a value of type `T` which will outlive the `inode`
86 ///   and will not have any unique references alias it during the call.
87 /// * `file` must point to a live, not-yet-initialized file object.
88 unsafe extern "C" fn writer_open<T: Writer + Sync>(
89     inode: *mut bindings::inode,
90     file: *mut bindings::file,
91 ) -> c_int {
92     // SAFETY: The caller ensures that `inode` is a valid pointer.
93     let data = unsafe { (*inode).i_private };
94     // SAFETY:
95     // * `file` is acceptable by caller precondition.
96     // * `print_act` will be called on a `seq_file` with private data set to the third argument,
97     //   so we meet its safety requirements.
98     // * The `data` pointer passed in the third argument is a valid `T` pointer that outlives
99     //   this call by caller preconditions.
100     unsafe { bindings::single_open(file, Some(writer_act::<T>), data) }
101 }
102 
103 /// Prints private data stashed in a seq_file to that seq file.
104 ///
105 /// # Safety
106 ///
107 /// `seq` must point to a live `seq_file` whose private data is a valid pointer to a `T` which may
108 /// not have any unique references alias it during the call.
109 unsafe extern "C" fn writer_act<T: Writer + Sync>(
110     seq: *mut bindings::seq_file,
111     _: *mut c_void,
112 ) -> c_int {
113     // SAFETY: By caller precondition, this pointer is valid pointer to a `T`, and
114     // there are not and will not be any unique references until we are done.
115     let data = unsafe { &*((*seq).private.cast::<T>()) };
116     // SAFETY: By caller precondition, `seq_file` points to a live `seq_file`, so we can lift
117     // it.
118     let seq_file = unsafe { SeqFile::from_raw(seq) };
119     seq_print!(seq_file, "{}", WriterAdapter(data));
120     0
121 }
122 
123 // Work around lack of generic const items.
124 pub(crate) trait ReadFile<T> {
125     const FILE_OPS: FileOps<T>;
126 }
127 
128 impl<T: Writer + Sync> ReadFile<T> for T {
129     const FILE_OPS: FileOps<T> = {
130         let operations = &bindings::file_operations {
131             read: Some(bindings::seq_read),
132             llseek: Some(bindings::seq_lseek),
133             release: Some(bindings::single_release),
134             open: Some(writer_open::<Self>),
135             ..pin_init::zeroed()
136         };
137         // SAFETY: `operations` is all stock `seq_file` implementations except for `writer_open`.
138         // `open`'s only requirement beyond what is provided to all open functions is that the
139         // inode's data pointer must point to a `T` that will outlive it, which matches the
140         // `FileOps` requirements.
141         unsafe { FileOps::new(operations, 0o400) }
142     };
143 }
144 
145 fn read<T: Reader + Sync>(data: &T, buf: *const c_char, count: usize) -> isize {
146     let mut reader = UserSlice::new(UserPtr::from_ptr(buf as *mut c_void), count).reader();
147 
148     if let Err(e) = data.read_from_slice(&mut reader) {
149         return e.to_errno() as isize;
150     }
151 
152     count as isize
153 }
154 
155 /// # Safety
156 ///
157 /// `file` must be a valid pointer to a `file` struct.
158 /// The `private_data` of the file must contain a valid pointer to a `seq_file` whose
159 /// `private` data in turn points to a `T` that implements `Reader`.
160 /// `buf` must be a valid user-space buffer.
161 pub(crate) unsafe extern "C" fn write<T: Reader + Sync>(
162     file: *mut bindings::file,
163     buf: *const c_char,
164     count: usize,
165     _ppos: *mut bindings::loff_t,
166 ) -> isize {
167     // SAFETY: The file was opened with `single_open`, which sets `private_data` to a `seq_file`.
168     let seq = unsafe { &mut *((*file).private_data.cast::<bindings::seq_file>()) };
169     // SAFETY: By caller precondition, this pointer is live and points to a value of type `T`.
170     let data = unsafe { &*(seq.private as *const T) };
171     read(data, buf, count)
172 }
173 
174 // A trait to get the file operations for a type.
175 pub(crate) trait ReadWriteFile<T> {
176     const FILE_OPS: FileOps<T>;
177 }
178 
179 impl<T: Writer + Reader + Sync> ReadWriteFile<T> for T {
180     const FILE_OPS: FileOps<T> = {
181         let operations = &bindings::file_operations {
182             open: Some(writer_open::<T>),
183             read: Some(bindings::seq_read),
184             write: Some(write::<T>),
185             llseek: Some(bindings::seq_lseek),
186             release: Some(bindings::single_release),
187             ..pin_init::zeroed()
188         };
189         // SAFETY: `operations` is all stock `seq_file` implementations except for `writer_open`
190         // and `write`.
191         // `writer_open`'s only requirement beyond what is provided to all open functions is that
192         // the inode's data pointer must point to a `T` that will outlive it, which matches the
193         // `FileOps` requirements.
194         // `write` only requires that the file's private data pointer points to `seq_file`
195         // which points to a `T` that will outlive it, which matches what `writer_open`
196         // provides.
197         unsafe { FileOps::new(operations, 0o600) }
198     };
199 }
200 
201 /// # Safety
202 ///
203 /// `inode` must be a valid pointer to an `inode` struct.
204 /// `file` must be a valid pointer to a `file` struct.
205 unsafe extern "C" fn write_only_open(
206     inode: *mut bindings::inode,
207     file: *mut bindings::file,
208 ) -> c_int {
209     // SAFETY: The caller ensures that `inode` and `file` are valid pointers.
210     unsafe { (*file).private_data = (*inode).i_private };
211     0
212 }
213 
214 /// # Safety
215 ///
216 /// * `file` must be a valid pointer to a `file` struct.
217 /// * The `private_data` of the file must contain a valid pointer to a `T` that implements
218 ///   `Reader`.
219 /// * `buf` must be a valid user-space buffer.
220 pub(crate) unsafe extern "C" fn write_only_write<T: Reader + Sync>(
221     file: *mut bindings::file,
222     buf: *const c_char,
223     count: usize,
224     _ppos: *mut bindings::loff_t,
225 ) -> isize {
226     // SAFETY: The caller ensures that `file` is a valid pointer and that `private_data` holds a
227     // valid pointer to `T`.
228     let data = unsafe { &*((*file).private_data as *const T) };
229     read(data, buf, count)
230 }
231 
232 pub(crate) trait WriteFile<T> {
233     const FILE_OPS: FileOps<T>;
234 }
235 
236 impl<T: Reader + Sync> WriteFile<T> for T {
237     const FILE_OPS: FileOps<T> = {
238         let operations = &bindings::file_operations {
239             open: Some(write_only_open),
240             write: Some(write_only_write::<T>),
241             llseek: Some(bindings::noop_llseek),
242             ..pin_init::zeroed()
243         };
244         // SAFETY:
245         // * `write_only_open` populates the file private data with the inode private data
246         // * `write_only_write`'s only requirement is that the private data of the file point to
247         //   a `T` and be legal to convert to a shared reference, which `write_only_open`
248         //   satisfies.
249         unsafe { FileOps::new(operations, 0o200) }
250     };
251 }
252 
253 extern "C" fn blob_read<T: BinaryWriter>(
254     file: *mut bindings::file,
255     buf: *mut c_char,
256     count: usize,
257     ppos: *mut bindings::loff_t,
258 ) -> isize {
259     // SAFETY:
260     // - `file` is a valid pointer to a `struct file`.
261     // - The type invariant of `FileOps` guarantees that `private_data` points to a valid `T`.
262     let this = unsafe { &*((*file).private_data.cast::<T>()) };
263 
264     // SAFETY:
265     // - `ppos` is a valid `file::Offset` pointer.
266     // - We have exclusive access to `ppos`.
267     let pos: &mut file::Offset = unsafe { &mut *ppos };
268 
269     let mut writer = UserSlice::new(UserPtr::from_ptr(buf.cast()), count).writer();
270 
271     let ret = || -> Result<isize> {
272         let written = this.write_to_slice(&mut writer, pos)?;
273 
274         Ok(written.try_into()?)
275     }();
276 
277     match ret {
278         Ok(n) => n,
279         Err(e) => e.to_errno() as isize,
280     }
281 }
282 
283 /// Representation of [`FileOps`] for read only binary files.
284 pub(crate) trait BinaryReadFile<T> {
285     const FILE_OPS: FileOps<T>;
286 }
287 
288 impl<T: BinaryWriter + Sync> BinaryReadFile<T> for T {
289     const FILE_OPS: FileOps<T> = {
290         let operations = &bindings::file_operations {
291             read: Some(blob_read::<T>),
292             llseek: Some(bindings::default_llseek),
293             open: Some(bindings::simple_open),
294             ..pin_init::zeroed()
295         };
296 
297         // SAFETY:
298         // - The private data of `struct inode` does always contain a pointer to a valid `T`.
299         // - `simple_open()` stores the `struct inode`'s private data in the private data of the
300         //   corresponding `struct file`.
301         // - `blob_read()` re-creates a reference to `T` from the `struct file`'s private data.
302         // - `default_llseek()` does not access the `struct file`'s private data.
303         unsafe { FileOps::new(operations, 0o400) }
304     };
305 }
306 
307 extern "C" fn blob_write<T: BinaryReader>(
308     file: *mut bindings::file,
309     buf: *const c_char,
310     count: usize,
311     ppos: *mut bindings::loff_t,
312 ) -> isize {
313     // SAFETY:
314     // - `file` is a valid pointer to a `struct file`.
315     // - The type invariant of `FileOps` guarantees that `private_data` points to a valid `T`.
316     let this = unsafe { &*((*file).private_data.cast::<T>()) };
317 
318     // SAFETY:
319     // - `ppos` is a valid `file::Offset` pointer.
320     // - We have exclusive access to `ppos`.
321     let pos: &mut file::Offset = unsafe { &mut *ppos };
322 
323     let mut reader = UserSlice::new(UserPtr::from_ptr(buf.cast_mut().cast()), count).reader();
324 
325     let ret = || -> Result<isize> {
326         let read = this.read_from_slice(&mut reader, pos)?;
327 
328         Ok(read.try_into()?)
329     }();
330 
331     match ret {
332         Ok(n) => n,
333         Err(e) => e.to_errno() as isize,
334     }
335 }
336 
337 /// Representation of [`FileOps`] for write only binary files.
338 pub(crate) trait BinaryWriteFile<T> {
339     const FILE_OPS: FileOps<T>;
340 }
341 
342 impl<T: BinaryReader + Sync> BinaryWriteFile<T> for T {
343     const FILE_OPS: FileOps<T> = {
344         let operations = &bindings::file_operations {
345             write: Some(blob_write::<T>),
346             llseek: Some(bindings::default_llseek),
347             open: Some(bindings::simple_open),
348             ..pin_init::zeroed()
349         };
350 
351         // SAFETY:
352         // - The private data of `struct inode` does always contain a pointer to a valid `T`.
353         // - `simple_open()` stores the `struct inode`'s private data in the private data of the
354         //   corresponding `struct file`.
355         // - `blob_write()` re-creates a reference to `T` from the `struct file`'s private data.
356         // - `default_llseek()` does not access the `struct file`'s private data.
357         unsafe { FileOps::new(operations, 0o200) }
358     };
359 }
360 
361 /// Representation of [`FileOps`] for read/write binary files.
362 pub(crate) trait BinaryReadWriteFile<T> {
363     const FILE_OPS: FileOps<T>;
364 }
365 
366 impl<T: BinaryWriter + BinaryReader + Sync> BinaryReadWriteFile<T> for T {
367     const FILE_OPS: FileOps<T> = {
368         let operations = &bindings::file_operations {
369             read: Some(blob_read::<T>),
370             write: Some(blob_write::<T>),
371             llseek: Some(bindings::default_llseek),
372             open: Some(bindings::simple_open),
373             ..pin_init::zeroed()
374         };
375 
376         // SAFETY:
377         // - The private data of `struct inode` does always contain a pointer to a valid `T`.
378         // - `simple_open()` stores the `struct inode`'s private data in the private data of the
379         //   corresponding `struct file`.
380         // - `blob_read()` re-creates a reference to `T` from the `struct file`'s private data.
381         // - `blob_write()` re-creates a reference to `T` from the `struct file`'s private data.
382         // - `default_llseek()` does not access the `struct file`'s private data.
383         unsafe { FileOps::new(operations, 0o600) }
384     };
385 }
386