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,197 @@
+// 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 {
+///     contents: Vec<u32>,
+/// }
+///
+/// impl SeqOperations for Data {
+///     type Item = u32;
+///     type Iterator = alloc::vec::IntoIter<u32>;
+///
+///     fn start(arg: &self) -> Option<Box<Peekable<Self::Iterator>>> {
+///         Box::try_new(arg.contents.clone().into_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() {
+        // 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`.
+        //
+        // The caller guarantees tha `pos` is a valid pointer to an
+        // `loff_t` and expects this function to mutate the value.
+        let mut iterator = unsafe {
+            *pos += 1;
+            Box::from_raw(v as *mut Peekable<T::Iterator>)
+        };
+        match iterator.as_mut().next() {
+            Some(_seen) => Box::into_raw(iterator) as *mut c_types::c_void,
+            None => ptr::null_mut(),
+        }
+    } else {
+        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,
+    context: T,
+}
+
+impl<T> SeqFile<T> {
+    fn new_pinned(seq_ops: bindings::seq_operations, context: T) -> KernelResult<Pin<Box<Self>>> {
+        Ok(Pin::from(Box::try_new(SeqFile {
+            seq_ops,
+            _pin: PhantomPinned,
+            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
+    }
+}
+
+/// 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 reg = SeqFile::new_pinned(SeqFileOperationsVTable::<T>::VTABLE, context)?;
+    // SAFETY: Calling a C function. `name` is guaranteed to be null terminated
+    // because it is of type `CStr`.
+    unsafe {
+        let _dir_entry = bindings::proc_create_seq_private(
+            name.deref().as_ptr() as *const u8 as *const c_types::c_char,
+            0,
+            ptr::null_mut(),
+            &reg.seq_ops,
+            0,
+            ptr::null_mut(),
+        );
+        Ok(reg)
+    }
+}

samples/rust/Kconfig

@@ -110,4 +110,14 @@ config SAMPLE_RUST_RANDOM
 
 	  If unsure, say N.
 
+config SAMPLE_RUST_SEQ_FILE
+	tristate "Seq file"
+	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

samples/rust/rust_seq_file.rs

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Example of using a [`seq_file`] in Rust.
+//!
+//! 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>
+
+#![no_std]
+#![feature(allocator_api, global_asm, try_reserve)]
+
+use alloc::{boxed::Box, sync::Arc};
+use core::{
+    convert::TryInto,
+    fmt::Write,
+    iter::{repeat, Peekable, Repeat, Take},
+    pin::Pin,
+};
+use kernel::{
+    cstr,
+    file_operations::{File, FileOpener, FileOperations},
+    io_buffer::IoBufferWriter,
+    miscdev, mutex_init, seq_file,
+    sync::Mutex,
+};
+
+use kernel::prelude::*;
+
+module! {
+    type: RustSeqFileDev,
+    name: b"rust_seq_file",
+    author: b"Adam Bratschi-Kaye",
+    description: b"Rust sample using a seq_file",
+    license: b"GPL v2",
+    params: {
+    },
+}
+
+#[derive(Clone)]
+struct SharedState(Arc<Mutex<u32>>);
+
+impl SharedState {
+    fn try_new() -> KernelResult<Self> {
+        let state = Arc::try_new(
+            // SAFETY: `mutex_init!` is called below.
+            unsafe { Mutex::new(0) },
+        )?;
+        // SAFETY: Mutex is pinned behind `Arc`.
+        let pin_state = unsafe { Pin::new_unchecked(state.as_ref()) };
+        mutex_init!(pin_state, "SharedState::0");
+        Ok(SharedState(state))
+    }
+}
+
+impl seq_file::SeqOperations for SharedState {
+    type Item = String;
+    type Iterator = Take<Repeat<String>>;
+
+    fn start(arg: &SharedState) -> Option<Box<Peekable<Self::Iterator>>> {
+        let count = arg.0.lock();
+        let mut message = String::new();
+
+        let template = "rust_seq_file: device opened this many times: ";
+        message.try_reserve_exact(template.len() + 4).ok()?;
+        // NO PANIC: We reserved space for `template` above.
+        message.push_str(template);
+        if *count < 1000 {
+            // NO PANIC: There are 4 characters remaining in the string which
+            // leaves space for a 3 digit number and the newline.
+            write!(&mut message, "{}\n", *count).ok()?;
+        }
+
+        Box::try_new(repeat(message).take((*count).try_into().ok()?).peekable()).ok()
+    }
+}
+
+impl FileOpener<SharedState> for SharedState {
+    fn open(ctx: &SharedState) -> KernelResult<Self::Wrapper> {
+        pr_info!("rust seq_file was opened!\n");
+        Ok(Box::try_new(ctx.clone())?)
+    }
+}
+
+impl FileOperations for SharedState {
+    type Wrapper = Box<Self>;
+
+    kernel::declare_file_operations!(read);
+
+    fn read<T: IoBufferWriter>(&self, _: &File, data: &mut T, offset: u64) -> KernelResult<usize> {
+        let message = b"incremented read count\n";
+        if offset != 0 {
+            return Ok(0);
+        }
+
+        {
+            let mut count = self.0.lock();
+            *count += 1;
+        }
+
+        data.write_slice(message)?;
+        Ok(message.len())
+    }
+}
+
+struct RustSeqFileDev {
+    _seq: Pin<Box<seq_file::SeqFile<SharedState>>>,
+    _dev: Pin<Box<miscdev::Registration<SharedState>>>,
+}
+
+impl KernelModule for RustSeqFileDev {
+    fn init() -> KernelResult<Self> {
+        pr_info!("Rust seq_file sample (init)\n");
+
+        let state = SharedState::try_new()?;
+
+        let seq_file =
+            kernel::seq_file::proc_create::<SharedState>(cstr!("rust_seq_file"), state.clone())?;
+
+        let dev_reg =
+            miscdev::Registration::new_pinned::<SharedState>(cstr!("rust_seq_file"), None, state)?;
+
+        let dev = RustSeqFileDev {
+            _seq: seq_file,
+            _dev: dev_reg,
+        };
+
+        Ok(dev)
+    }
+}
+
+impl Drop for RustSeqFileDev {
+    fn drop(&mut self) {
+        pr_info!("Rust seq_file sample (exit)\n");
+    }
+}