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

.github/workflows/kernel-arm64-debug.config

@@ -1432,6 +1432,7 @@ CONFIG_SAMPLE_RUST_STACK_PROBING=m
 CONFIG_SAMPLE_RUST_SEMAPHORE=m
 CONFIG_SAMPLE_RUST_SEMAPHORE_C=m
 CONFIG_SAMPLE_RUST_RANDOM=m
+CONFIG_SAMPLE_RUST_SEQ_FILE=m
 
 #
 # arm64 Debugging

.github/workflows/kernel-arm64-release.config

@@ -1350,6 +1350,7 @@ CONFIG_SAMPLE_RUST_STACK_PROBING=m
 CONFIG_SAMPLE_RUST_SEMAPHORE=m
 CONFIG_SAMPLE_RUST_SEMAPHORE_C=m
 CONFIG_SAMPLE_RUST_RANDOM=m
+CONFIG_SAMPLE_RUST_SEQ_FILE=m
 
 #
 # arm64 Debugging

.github/workflows/kernel-ppc64le-debug.config

@@ -1492,6 +1492,7 @@ CONFIG_SAMPLE_RUST_STACK_PROBING=m
 CONFIG_SAMPLE_RUST_SEMAPHORE=m
 CONFIG_SAMPLE_RUST_SEMAPHORE_C=m
 CONFIG_SAMPLE_RUST_RANDOM=m
+CONFIG_SAMPLE_RUST_SEQ_FILE=m
 CONFIG_ARCH_HAS_DEVMEM_IS_ALLOWED=y
 # CONFIG_STRICT_DEVMEM is not set
 

.github/workflows/kernel-ppc64le-release.config

@@ -1454,6 +1454,7 @@ CONFIG_SAMPLE_RUST_STACK_PROBING=m
 CONFIG_SAMPLE_RUST_SEMAPHORE=m
 CONFIG_SAMPLE_RUST_SEMAPHORE_C=m
 CONFIG_SAMPLE_RUST_RANDOM=m
+CONFIG_SAMPLE_RUST_SEQ_FILE=m
 CONFIG_ARCH_HAS_DEVMEM_IS_ALLOWED=y
 # CONFIG_STRICT_DEVMEM is not set
 

.github/workflows/kernel-x86_64-debug.config

@@ -1444,6 +1444,7 @@ CONFIG_SAMPLE_RUST_STACK_PROBING=m
 CONFIG_SAMPLE_RUST_SEMAPHORE=m
 CONFIG_SAMPLE_RUST_SEMAPHORE_C=m
 CONFIG_SAMPLE_RUST_RANDOM=m
+CONFIG_SAMPLE_RUST_SEQ_FILE=m
 CONFIG_ARCH_HAS_DEVMEM_IS_ALLOWED=y
 # CONFIG_STRICT_DEVMEM is not set
 

rust/kernel/bindings_helper.h

@@ -4,7 +4,9 @@
 #include <linux/errname.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

@@ -62,7 +62,12 @@ pub mod module_param;
 mod build_assert;
 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,101 @@
+// 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},
+    ptr,
+};
+
+use crate::{
+    bindings, c_types,
+    seq_file::{SeqFileOperationsVTable, SeqOperations},
+    str::CStr,
+    types::PointerWrapper,
+    Error, Result,
+};
+
+/// 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 `T::into_pointer`.
+///
+/// [`proc_dir_entry`]: ../../../fs/proc/internal.h
+pub struct ProcDirEntry<T: PointerWrapper> {
+    proc_dir_entry: *mut bindings::proc_dir_entry,
+    data: *const c_types::c_void,
+    _wrapper: PhantomData<T>,
+}
+
+// SAFETY: The `proc_dir_entry` and `data` raw pointers aren't accessible.
+unsafe impl<T: PointerWrapper> Sync for ProcDirEntry<T> {}
+
+impl<T: PointerWrapper> Drop for ProcDirEntry<T> {
+    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 `T::into_pointer`.
+        unsafe { drop(T::from_pointer(self.data)) }
+    }
+}
+
+impl<T: PointerWrapper> ProcDirEntry<T> {
+    /// Create a seq_file entry in `/proc` containing data of type `S`.
+    ///
+    /// Corresponds to [`proc_create_seq_private`] on the C side.
+    ///
+    /// [`proc_create_seq_private`]: ../../../fs/proc/generic.c
+    pub fn new_seq_private<S>(name: &CStr, data: T) -> Result<Self>
+    where
+        S: SeqOperations<DataWrapper = T>,
+    {
+        let data = data.into_pointer();
+        let name = name.as_char_ptr();
+
+        // SAFETY: Calling a C function. The vtable for `S` expects a
+        // `S::DataWrapper = T` pointer in the data field of the associated
+        // `proc_dir_entry`.  `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(),
+                SeqFileOperationsVTable::<S>::build(),
+                0,
+                data as *mut c_types::c_void,
+            )
+        };
+        if proc_dir_entry.is_null() {
+            // SAFETY: `data` was created with a call to `T::into_pointer`.
+            drop(unsafe { T::from_pointer(data) });
+            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 `T::into_pointer`.
+            Ok(ProcDirEntry {
+                proc_dir_entry,
+                data,
+                _wrapper: PhantomData,
+            })
+        }
+    }
+}

rust/kernel/seq_file.rs

@@ -0,0 +1,196 @@
+// 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(CONFIG_PROC_FS)]
+
+use core::{
+    iter::{Iterator, Peekable},
+    marker::PhantomData,
+    mem,
+    ops::{Deref, DerefMut},
+    ptr,
+};
+
+use crate::{bindings, c_str, c_types, str::CStr, types::PointerWrapper, Result};
+
+/// Rust equivalent of the [`seq_operations`] interface on the C side.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// #![feature(allocator_api)]
+///
+/// use core::iter::Peekable;
+/// use kernel::{Error, Result, seq_file};
+///
+/// struct Data(&'static [String]);
+///
+/// impl seq_file::SeqOperations for Data {
+///     type Item = &'static String;
+///     type Iterator = core::slice::Iter<'static, String>;
+///     type DataWrapper = Box<Self>;
+///     type IteratorWrapper = Box<Peekable<Self::Iterator>>;
+///
+///     fn start(&self) -> Result<Self::IteratorWrapper> {
+///         let iter = self.0.iter();
+///         Box::try_new(iter.peekable()).map_err(|_| Error::ENOMEM)
+///     }
+///
+///     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>;
+
+    /// Wrapper used to store a pointer to `Self` on the C side.
+    type DataWrapper: PointerWrapper + Deref<Target = Self>;
+
+    /// Wrapper used to store a pointer to the iterator on the C side.
+    type IteratorWrapper: PointerWrapper + DerefMut<Target = Peekable<Self::Iterator>>;
+
+    /// Called once each time the `seq_file` is opened.
+    fn start(&self) -> Result<Self::IteratorWrapper>;
+
+    /// 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 `T::IteratorWrapper::into_pointer`.
+        drop(unsafe { T::IteratorWrapper::from_pointer(v) })
+    }
+}
+
+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 `T::IteratorWrapper::into_pointer`.
+    // We already checked for he null pointer case above.
+    let mut iterator = unsafe { T::IteratorWrapper::from_pointer(v) };
+
+    // 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) => T::IteratorWrapper::into_pointer(iterator) as *mut _,
+        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 = c_str!("%.*s");
+    if v.is_null() {
+        return 0;
+    }
+    // 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 `T::IteratorWrapper::into_pointer`. We
+    // checked for null pointers above. The iterator is forgotten below
+    // so the pointer on the C side stays valid.
+    let mut iterator = unsafe { T::IteratorWrapper::from_pointer(v) };
+    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_char_ptr(),
+                s.len(),
+                s.as_ptr() as *const u8 as *const c_types::c_char,
+            );
+        }
+    }
+    // Need to forget the iterator because the C side is still using a
+    // reference to it.
+    mem::forget(iterator);
+    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 created via
+    // `T::DataWrapper::into_pointer`. We don't move the data in the wrapper
+    // so the pointer will remain valid for later calls.
+    let data_wrapper =
+        unsafe { T::DataWrapper::from_pointer(bindings::PDE_DATA((*(*m).file).f_inode)) };
+    let iterator = data_wrapper.start().ok();
+    // Data is still used in the `proc_dir_entry`.
+    mem::forget(data_wrapper);
+    // SAFETY: The caller guarantees that `pos` points to a valid `loff_t`.
+    let pos = unsafe { *pos };
+    match iterator {
+        Some(mut wrapper) => {
+            for _ in 0..pos {
+                if wrapper.next().is_none() {
+                    return ptr::null_mut();
+                }
+            }
+            match wrapper.peek() {
+                Some(_next) => T::IteratorWrapper::into_pointer(wrapper) as *mut _,
+                None => ptr::null_mut(),
+            }
+        }
+        None => ptr::null_mut(),
+    }
+}
+
+pub(crate) 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>),
+    };
+
+    pub(crate) const fn build() -> &'static bindings::seq_operations {
+        &Self::VTABLE
+    }
+}

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