seq_file.rs: Rust version of seq_operations

Adds a trait which allows Rust modules to implement the seq_operations
interface and use it to create a `/proc` file.

Signed-off-by: Adam Bratschi-Kaye <[email protected]>

Author: adamrk

rust/kernel/bindings_helper.h

@@ -3,7 +3,9 @@
 #include <linux/cdev.h>
 #include <linux/fs.h>
 #include <linux/module.h>
+#include <linux/proc_fs.h>
 #include <linux/random.h>
+#include <linux/seq_file.h>
 #include <linux/slab.h>
 #include <linux/sysctl.h>
 #include <linux/uaccess.h>

rust/kernel/lib.rs

@@ -53,7 +53,12 @@ pub mod module_param;
 
 pub mod prelude;
 pub mod print;
+
+#[cfg(CONFIG_PROC_FS)]
+pub mod proc_fs;
+
 pub mod random;
+pub mod seq_file;
 mod static_assert;
 pub mod sync;
 

rust/kernel/proc_fs.rs

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Type for defining `proc` files.
+//!
+//! This module allows Rust devices to create entries in `/proc` from a
+//! [`bindings::proc_ops`] vtable.
+//!
+//! C header: [`include/linux/proc_fs.h`](../../../include/linux/proc_fs.h)
+//!
+//! Reference: <https://www.kernel.org/doc/html/latest/filesystems/proc.html>
+
+use core::{
+    marker::{PhantomData, Sync},
+    ops::Deref,
+    ptr,
+};
+
+use crate::{bindings, c_types, file_operations::PointerWrapper, CStr, Error, KernelResult};
+
+/// An entry under `/proc` containing data of type `T`.
+///
+/// This is the Rust equivalent to [`proc_dir_entry`] on the C side.
+///
+/// # Invariants
+///
+/// The [`ProcDirEntry::proc_dir_entry`] is a valid pointer.
+/// [`ProcDirEntry::data`] points to the PDE data of
+/// [`ProcDirEntry::proc_dir_entry`].
+/// [`ProcDirEntry::data`] was created by a call to `W::into_pointer`.
+///
+/// [`proc_dir_entry`]: ../../../fs/proc/internal.h
+pub struct ProcDirEntry<T, W: PointerWrapper<T>> {
+    proc_dir_entry: *mut bindings::proc_dir_entry,
+    data: *const T,
+    _wrapper: PhantomData<W>,
+}
+
+// SAFETY: The `proc_dir_entry` and `data` raw pointers aren't accessible.
+unsafe impl<T, W: PointerWrapper<T>> Sync for ProcDirEntry<T, W> {}
+
+impl<T, W: PointerWrapper<T>> Drop for ProcDirEntry<T, W> {
+    fn drop(&mut self) {
+        // SAFETY: Calling a C function. `proc_dir_entry` is a valid pointer to
+        // a `bindings::proc_dir_entry` because it was created by a call to
+        // `proc_create_data` which only returns valid pointers.
+        unsafe {
+            bindings::proc_remove(self.proc_dir_entry);
+        }
+        // SAFETY: `self.data` was created by a call to `W::into_pointer`.
+        unsafe { drop(W::from_pointer(self.data)) }
+    }
+}
+
+/// Create a seq_file entry in `/proc` containing data of type `T`.
+///
+/// Corresponds to [`proc_create_seq_private`] on the C side.
+///
+/// [`proc_create_seq_private`]: ../../../fs/proc/generic.c
+pub(crate) fn proc_create_seq_private<T, W: PointerWrapper<T>>(
+    name: CStr<'static>,
+    seq_ops: &'static bindings::seq_operations,
+    data: W,
+) -> KernelResult<ProcDirEntry<T, W>> {
+    let data = data.into_pointer();
+    let name = name.deref().as_ptr() as *const u8 as *const c_types::c_char;
+
+    // SAFETY: Calling a C function. `name` is guaranteed to be null terminated
+    // because it is of type `CStr`.
+    let proc_dir_entry = unsafe {
+        bindings::proc_create_seq_private(
+            name,
+            0,
+            ptr::null_mut(),
+            seq_ops,
+            0,
+            data as *mut c_types::c_void,
+        )
+    };
+    if proc_dir_entry.is_null() {
+        Err(Error::ENOMEM)
+    } else {
+        // INVARIANT: `proc_dir_entry` is a valid pointer.
+        // The `data` points to the data stored in `proc_dir_entry`, and
+        // `data` was created by `W::into_pointer`.
+        Ok(ProcDirEntry {
+            proc_dir_entry,
+            data,
+            _wrapper: PhantomData,
+        })
+    }
+}

rust/kernel/seq_file.rs

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Trait for defining `seq_file`s.
+//!
+//! This module allows Rust devices to implement [`struct seq_operations`] and
+//! and create a file under `/proc` based on that implementation.
+//!
+//! C header: [`include/linux/seq_file.h`](../../../include/linux/seq_file.h)
+//!
+//! Reference: <https://www.kernel.org/doc/html/latest/filesystems/seq_file.html>
+
+// Currently this module is only usable through proc_fs.
+#![cfg_attr(not(CONFIG_PROC_FS), allow(dead_code))]
+
+use alloc::boxed::Box;
+use core::{
+    iter::{Iterator, Peekable},
+    marker::PhantomData,
+    ptr,
+};
+
+use crate::{bindings, c_types, cstr, CStr};
+
+#[cfg(CONFIG_PROC_FS)]
+pub use proc::proc_create_seq;
+
+/// Rust equivalent of the [`seq_operations`] interface on the C side.
+///
+/// # Example
+///
+/// ```
+/// struct Data(&'static [String]);
+///
+/// impl seq_file::SeqOperations for Data {
+///     type Item = &'static String;
+///     type Iterator = core::slice::Iter<'static, String>;
+///
+///     fn start(arg: &Data) -> Option<Box<Peekable<Self::Iterator>>> {
+///         let iter = arg.0.iter();
+///         Box::try_new(iter.peekable()).ok()
+///     }
+///
+///     fn display(item: &Self::Item) -> &str {
+///         &item[..]
+///     }
+/// }
+/// ```
+///
+/// [`seq_operations`]: ../../../include/linux/seq_file.h
+pub trait SeqOperations {
+    /// Type produced on each iteration.
+    type Item;
+
+    /// Type created when the seq file is opened.
+    type Iterator: Iterator<Item = Self::Item>;
+
+    /// Called once each time the `seq_file` is opened.
+    fn start(arg: &Self) -> Option<Box<Peekable<Self::Iterator>>>;
+
+    /// How the item will be displayed to the reader.
+    fn display(item: &Self::Item) -> &str;
+}
+
+extern "C" fn stop_callback<T: SeqOperations>(
+    _m: *mut bindings::seq_file,
+    v: *mut c_types::c_void,
+) {
+    if !v.is_null() {
+        // SAFETY: `v` was created by a previous call to `next_callback` or
+        // `start_callback` and both functions return either a null pointer
+        // or pointer generated by `Box<Peekable<T::Iterator>>::into_raw`.
+        drop(unsafe { Box::from_raw(v as *mut Peekable<T::Iterator>) })
+    }
+}
+
+extern "C" fn next_callback<T: SeqOperations>(
+    _m: *mut bindings::seq_file,
+    v: *mut c_types::c_void,
+    pos: *mut bindings::loff_t,
+) -> *mut c_types::c_void {
+    if v.is_null() {
+        return ptr::null_mut();
+    }
+
+    // SAFETY: `v` was created by a previous call to `next_callback` or
+    // `start_callback` and both functions return either a null pointer
+    // or pointer generated by `Box<Peekable<T::Iterator>>::into_raw`.
+    // We already checked for he null pointer case above.
+    let mut iterator = unsafe { Box::from_raw(v as *mut Peekable<T::Iterator>) };
+
+    // SAFETY: The caller guarantees tha `pos` is a valid pointer to an
+    // `loff_t` and expects this function to mutate the value.
+    unsafe {
+        *pos += 1;
+    }
+
+    if iterator.next().is_none() {
+        return ptr::null_mut();
+    }
+
+    match iterator.peek() {
+        Some(_next) => Box::into_raw(iterator) as *mut c_types::c_void,
+        None => ptr::null_mut(),
+    }
+}
+
+extern "C" fn show_callback<T: SeqOperations>(
+    m: *mut bindings::seq_file,
+    v: *mut c_types::c_void,
+) -> c_types::c_int {
+    const FORMAT: CStr<'static> = cstr!("%.*s");
+    // SAFETY: `v` was created by a previous call to `next_callback` or
+    // `start_callback` and both functions return either a null pointer
+    // or pointer generated by `Box<Peekable<T::Iterator>>::into_raw`.
+    if let Some(iterator) = unsafe { (v as *mut Peekable<T::Iterator>).as_mut() } {
+        if let Some(item) = iterator.peek() {
+            let s = T::display(item);
+            // SAFETY: Calling a C function. `FORMAT` is null terminated because
+            // it comes from a `CStr`. `s` does not need to be null terminated
+            // because we are only printing the first `s.len()` bytes.
+            unsafe {
+                bindings::seq_printf(
+                    m,
+                    FORMAT.as_ptr() as *const c_types::c_char,
+                    s.len(),
+                    s.as_ptr() as *const u8 as *const c_types::c_char,
+                );
+            }
+        }
+    }
+    0
+}
+
+extern "C" fn start_callback<T: SeqOperations>(
+    m: *mut bindings::seq_file,
+    pos: *mut bindings::loff_t,
+) -> *mut c_types::c_void {
+    // SAFETY: This function will be called by opening a proc file generated
+    // from `proc_create_seq_private` on the C side with data of type `T`. That
+    // guarantees that that the proc_dir_entry data of the associated inode
+    // is a valid pointer to `T`.
+    let arg = unsafe { &*(bindings::PDE_DATA((*(*m).file).f_inode) as *const T) };
+    // SAFETY: The caller guarantees that `pos` points to a valid `loff_t`.
+    let pos = unsafe { *pos };
+    match T::start(arg) {
+        Some(mut wrapper) => {
+            for _ in 0..pos {
+                wrapper.next();
+            }
+            match wrapper.peek() {
+                Some(_next) => Box::into_raw(wrapper) as *mut c_types::c_void,
+                None => ptr::null_mut(),
+            }
+        }
+        None => ptr::null_mut(),
+    }
+}
+
+struct SeqFileOperationsVTable<T>(PhantomData<T>);
+
+impl<T: SeqOperations> SeqFileOperationsVTable<T> {
+    const VTABLE: bindings::seq_operations = bindings::seq_operations {
+        start: Some(start_callback::<T>),
+        stop: Some(stop_callback::<T>),
+        next: Some(next_callback::<T>),
+        show: Some(show_callback::<T>),
+    };
+
+    const fn build() -> &'static bindings::seq_operations {
+        &Self::VTABLE
+    }
+}
+
+#[cfg(CONFIG_PROC_FS)]
+mod proc {
+    use super::*;
+    use crate::{
+        file_operations::PointerWrapper,
+        proc_fs::{self, ProcDirEntry},
+        KernelResult,
+    };
+
+    /// Create an entry in `/proc` for a `seq_file`.
+    pub fn proc_create_seq<T: SeqOperations, W: PointerWrapper<T>>(
+        name: CStr<'static>,
+        data: W,
+    ) -> KernelResult<ProcDirEntry<T, W>> {
+        proc_fs::proc_create_seq_private(name, SeqFileOperationsVTable::<T>::build(), data)
+    }
+}

samples/rust/Kconfig

@@ -110,4 +110,15 @@ config SAMPLE_RUST_RANDOM
 
 	  If unsure, say N.
 
+config SAMPLE_RUST_SEQ_FILE
+	tristate "Seq file"
+	depends on PROC_FS
+	help
+	  This option builds the Rust seq_file sample.
+
+	  To compile this as a module, choose M here:
+	  the module will be called rust_seq_file.
+
+	  If unsure, say N.
+
 endif # SAMPLES_RUST

samples/rust/Makefile

@@ -10,3 +10,4 @@ obj-$(CONFIG_SAMPLE_RUST_STACK_PROBING)		+= rust_stack_probing.o
 obj-$(CONFIG_SAMPLE_RUST_SEMAPHORE)		+= rust_semaphore.o
 obj-$(CONFIG_SAMPLE_RUST_SEMAPHORE_C)		+= rust_semaphore_c.o
 obj-$(CONFIG_SAMPLE_RUST_RANDOM)		+= rust_random.o
+obj-$(CONFIG_SAMPLE_RUST_SEQ_FILE)		+= rust_seq_file.o