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,6 +53,7 @@ pub mod module_param;
 pub mod prelude;
 pub mod print;
 pub mod random;
+pub mod seq_file;
 mod static_assert;
 pub mod sync;
 

rust/kernel/seq_file.rs

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Trait for defining `seq_file`s under `/proc`.
+//!
+//! 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)
+//! C header: [`include/linux/proc_fs.h`](../../../include/linux/proc_fs.h)
+//!
+//! Reference: <https://www.kernel.org/doc/html/latest/filesystems/seq_file.html>
+
+use alloc::{boxed::Box, string::ToString};
+use core::{
+    fmt::Display,
+    iter::{Iterator, Peekable},
+    marker::{PhantomData, PhantomPinned},
+    ops::Deref,
+    pin::Pin,
+    ptr,
+};
+
+use crate::{bindings, c_types, CStr, KernelResult};
+
+/// Rust equivalent of the [`seq_operations`] interface on the C side.
+///
+/// # Example
+///
+/// ```
+/// struct Data(&'static [u32]);
+///
+/// impl seq_file::SeqOperations for Data {
+///     type Item = &'static u32;
+///     type Iterator = core::slice::Iter<'static, u32>;
+///
+///     fn start(arg: &Data) -> Option<Box<Peekable<Self::Iterator>>> {
+///         let iter = arg.0.iter();
+///         Box::try_new(iter.peekable()).ok()
+///     }
+/// }
+/// ```
+///
+/// [`seq_operations`]: ../../../include/linux/seq_file.h
+pub trait SeqOperations {
+    /// Type produced on each iteration.
+    type Item: Display;
+
+    /// 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>>>;
+}
+
+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`.
+        let _iterator = 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`.
+    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;
+    }
+
+    match iterator.as_mut().next() {
+        Some(_seen) => 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 {
+    // 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`.
+    let iterator = unsafe { (v as *mut Peekable<T::Iterator>).as_mut() };
+    if let Some(iterator) = iterator {
+        let s = match iterator.peek() {
+            // TODO: Replace with fallible `to_string` when available.
+            Some(item) => item.to_string() + "\0",
+            None => "\0".to_string(),
+        };
+        // SAFETY: Calling a C function. `s` is guaranteed to be null terminated
+        // because we explicitly constructed it just above.
+        unsafe {
+            bindings::seq_puts(m, 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
+    // by a call to `proc_create::<T>`, so `m` can be converted using
+    // `SeqFile<T>`.
+    let arg = unsafe { &*SeqFile::<T>::convert(m) };
+    // 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.as_mut().next();
+            }
+            Box::into_raw(wrapper) as *mut c_types::c_void
+        }
+        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>),
+    };
+}
+
+/// A `seq_file` referencing data of type `T`.
+pub struct SeqFile<T> {
+    seq_ops: bindings::seq_operations,
+    _pin: PhantomPinned,
+    dir_entry: *mut bindings::proc_dir_entry,
+    context: T,
+}
+
+impl<T> Drop for SeqFile<T> {
+    fn drop(&mut self) {
+        if !self.dir_entry.is_null() {
+            // SAFETY: Calling a C function. `dir_entry` is a valid pointer to a
+            // `proc_dir_entry` because if it is not null it was created by a
+            // call to `bindings::proc_create_seq_private`.
+            unsafe {
+                bindings::proc_remove(self.dir_entry);
+            }
+        }
+    }
+}
+
+impl<T> SeqFile<T> {
+    fn new(seq_ops: bindings::seq_operations, context: T) -> KernelResult<Box<Self>> {
+        Ok(Box::try_new(SeqFile {
+            seq_ops,
+            _pin: PhantomPinned,
+            dir_entry: ptr::null_mut::<bindings::proc_dir_entry>(),
+            context,
+        })?)
+    }
+
+    /// Retrieve the [`SeqFile::context`] associated with a [`bindings::seq_file`].
+    ///
+    /// # Safety
+    ///
+    /// `m` must have been created from a proc file generated by calling
+    /// `proc_create::<T>`.
+    unsafe fn convert(m: *mut bindings::seq_file) -> *const T {
+        let reg = crate::container_of!((*m).op, Self, seq_ops);
+        &(*reg).context
+    }
+}
+
+// SAFETY: The fields of `SeqFile` that are not `Sync` are `dir_entry` and
+// potentially `context`, but `SeqFile` provides no access to these fields.
+unsafe impl<T> Sync for SeqFile<T> {}
+
+/// Create a `/proc` file.
+///
+/// The returned value must not be dropped until the module is unloaded.
+pub fn proc_create<T: SeqOperations + Sync>(
+    name: CStr<'static>,
+    context: T,
+) -> KernelResult<Pin<Box<SeqFile<T>>>> {
+    let mut reg = SeqFile::new(SeqFileOperationsVTable::<T>::VTABLE, context)?;
+
+    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 dir_entry = unsafe {
+        bindings::proc_create_seq_private(
+            name,
+            0,
+            ptr::null_mut(),
+            &reg.seq_ops,
+            0,
+            ptr::null_mut(),
+        )
+    };
+    reg.dir_entry = dir_entry;
+    let reg = Pin::from(reg);
+    Ok(reg)
+}

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