rust: add SPI API

This add support for the SPI API for Rust modules.
Features:
- Register/Unregister
- Probe, Remove and Shutdown
- write_then_read, write, read

Co-developed-by: Martin Schmidt <[email protected]>
Signed-off-by: Martin Schmidt <[email protected]>
Co-developed-by: Arthur Cohen <[email protected]>
Signed-off-by: Arthur Cohen <[email protected]>
Signed-off-by: Esteban Blanc <[email protected]>

Author: Skallwar

rust/bindings/bindings_helper.h

@@ -11,6 +11,7 @@
 #include <linux/refcount.h>
 #include <linux/wait.h>
 #include <linux/sched.h>
+#include <linux/spi/spi.h>
 
 /* `bindgen` gets confused at certain things. */
 const gfp_t BINDINGS_GFP_KERNEL = GFP_KERNEL;

rust/kernel/lib.rs

@@ -52,6 +52,9 @@ pub use uapi;
 #[doc(hidden)]
 pub use build_error::build_error;
 
+#[cfg(CONFIG_SPI)]
+pub mod spi;
+
 /// Prefix to appear before log messages printed from within the `kernel` crate.
 const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
 

rust/kernel/spi.rs

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! This module provides safer and higher level abstraction over the kernel's SPI types
+//! and functions.
+//!
+//! C header: [`include/linux/spi/spi.h`](../../../../include/linux/spi/spi.h)
+
+use crate::bindings;
+use crate::error::{code::*, from_result, Error, Result};
+use crate::str::CStr;
+use alloc::boxed::Box;
+use core::marker::PhantomData;
+use core::pin::Pin;
+use macros::vtable;
+
+/// Wrapper struct around the kernel's `spi_device`.
+#[derive(Clone, Copy)]
+pub struct SpiDevice(*mut bindings::spi_device);
+
+impl SpiDevice {
+    /// Create an [`SpiDevice`] from a mutable spi_device raw pointer. This function is unsafe
+    /// as the pointer might be invalid.
+    ///
+    /// The pointer must be valid. This can be achieved by calling `to_ptr` on a previously
+    /// constructed, safe `SpiDevice` instance, or by making sure that the pointer points
+    /// to valid memory.
+    ///
+    /// You probably do not want to use this abstraction directly. It is mainly used
+    /// by this abstraction to wrap valid pointers given by the Kernel to the different
+    /// SPI methods: `probe`, `remove` and `shutdown`.
+    pub unsafe fn from_ptr(dev: *mut bindings::spi_device) -> Self {
+        SpiDevice(dev)
+    }
+
+    /// Access the raw pointer from an [`SpiDevice`] instance.
+    pub fn to_ptr(&mut self) -> *mut bindings::spi_device {
+        self.0
+    }
+}
+
+/// Corresponds to the kernel's spi_driver's methods. Implement this trait on a type to
+/// express the need of a custom probe, remove or shutdown function for your SPI driver.
+#[vtable]
+pub trait SpiMethods {
+    /// Corresponds to the kernel's `spi_driver`'s `probe` method field.
+    fn probe(_spi_dev: &mut SpiDevice) -> Result<i32> {
+        unreachable!("There should be a NULL in the probe filed of spi_driver's");
+    }
+
+    /// Corresponds to the kernel's `spi_driver`'s `remove` method field.
+    fn remove(_spi_dev: &mut SpiDevice) {
+        unreachable!("There should be a NULL in the remove filed of spi_driver's");
+    }
+
+    /// Corresponds to the kernel's `spi_driver`'s `shutdown` method field.
+    fn shutdown(_spi_dev: &mut SpiDevice) {
+        unreachable!("There should be a NULL in the shutdown filed of spi_driver's");
+    }
+}
+
+/// Registration of an SPI driver.
+pub struct DriverRegistration<T: SpiMethods> {
+    this_module: &'static crate::ThisModule,
+    registered: bool,
+    name: &'static CStr,
+    spi_driver: bindings::spi_driver,
+    _p: PhantomData<T>,
+}
+
+impl<T: SpiMethods> DriverRegistration<T> {
+    fn new(this_module: &'static crate::ThisModule, name: &'static CStr) -> Self {
+        DriverRegistration {
+            this_module,
+            name,
+            registered: false,
+            spi_driver: bindings::spi_driver::default(),
+            _p: PhantomData,
+        }
+    }
+
+    /// Create a new `DriverRegistration` and register it. This is equivalent to creating
+    /// a static `spi_driver` and then calling `spi_driver_register` on it in C.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let spi_driver =
+    ///     spi::DriverRegistration::new_pinned::<MySpiMethods>(&THIS_MODULE, cstr!("my_driver_name"))?;
+    /// ```
+    pub fn new_pinned(
+        this_module: &'static crate::ThisModule,
+        name: &'static CStr,
+    ) -> Result<Pin<Box<Self>>> {
+        let mut registration = Pin::from(Box::try_new(Self::new(this_module, name))?);
+
+        registration.as_mut().register()?;
+
+        Ok(registration)
+    }
+
+    /// Register a [`DriverRegistration`]. This is equivalent to calling `spi_driver_register`
+    /// on your `spi_driver` in C, without creating it first.
+    fn register(self: Pin<&mut Self>) -> Result {
+        // SAFETY: We do not move out of the reference we get, and are only registering
+        // `this` once over the course of the module, since we check that the `registered`
+        // field was not already set to true.
+        let this = unsafe { self.get_unchecked_mut() };
+        if this.registered {
+            return Err(EINVAL);
+        }
+
+        let mut spi_driver = this.spi_driver;
+
+        if T::HAS_PROBE {
+            spi_driver.probe = Some(probe_callback::<T>);
+        }
+        if T::HAS_REMOVE {
+            spi_driver.remove = Some(remove_callback::<T>);
+        }
+        if T::HAS_SHUTDOWN {
+            spi_driver.remove = Some(shutdown_callback::<T>);
+        }
+
+        spi_driver.driver.name = this.name.as_ptr() as *const core::ffi::c_char;
+
+        // SAFETY: Since we are using a pinned `self`, we can register the driver safely as
+        // if we were using a static instance. The kernel will access this driver over the
+        // entire lifespan of a module and therefore needs a pointer valid for the entirety
+        // of this lifetime.
+        let res =
+            unsafe { bindings::__spi_register_driver(this.this_module.0, &mut this.spi_driver) };
+
+        if res != 0 {
+            return Err(Error::from_errno(res));
+        }
+
+        this.registered = true;
+
+        Ok(())
+    }
+}
+
+impl<T: SpiMethods> Drop for DriverRegistration<T> {
+    fn drop(&mut self) {
+        // SAFETY: We are simply unregistering an `spi_driver` that we know to be valid.
+        // [`DriverRegistration`] instances can only be created by being registered at the
+        // same time, so we are sure that we'll never unregister an unregistered `spi_driver`.
+        unsafe { bindings::driver_unregister(&mut self.spi_driver.driver) }
+    }
+}
+
+unsafe extern "C" fn probe_callback<T: SpiMethods>(
+    spi: *mut bindings::spi_device,
+) -> core::ffi::c_int {
+    from_result(|| Ok(T::probe(&mut SpiDevice(spi))?))
+}
+
+unsafe extern "C" fn remove_callback<T: SpiMethods>(spi: *mut bindings::spi_device) {
+    T::remove(&mut SpiDevice(spi));
+}
+
+unsafe extern "C" fn shutdown_callback<T: SpiMethods>(spi: *mut bindings::spi_device) {
+    T::shutdown(&mut SpiDevice(spi));
+}
+
+// SAFETY: The only method is `register()`, which requires a (pinned) mutable `Registration`, so it
+// is safe to pass `&Registration` to multiple threads because it offers no interior mutability.
+unsafe impl<T: SpiMethods> Sync for DriverRegistration<T> {}
+
+// SAFETY: All functions work from any thread.
+unsafe impl<T: SpiMethods> Send for DriverRegistration<T> {}
+
+/// High level abstraction over the kernel's SPI functions such as `spi_write_then_read`.
+// TODO this should be a mod, right?
+pub struct Spi;
+
+impl Spi {
+    /// Corresponds to the kernel's `spi_write_then_read`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let to_write = "rust-for-linux".as_bytes();
+    /// let mut to_receive = [0u8; 10]; // let's receive 10 bytes back
+    ///
+    /// // `spi_device` was previously provided by the kernel in that case
+    /// let transfer_result = Spi::write_then_read(spi_device, &to_write, &mut to_receive);
+    /// ```
+    pub fn write_then_read(dev: &mut SpiDevice, tx_buf: &[u8], rx_buf: &mut [u8]) -> Result {
+        // SAFETY: The `dev` argument must uphold the safety guarantees made when creating
+        // the [`SpiDevice`] instance. It should therefore point to a valid `spi_device`
+        // and valid memory. We also know that a rust slice will always contain a proper
+        // size and that it is safe to use as is. Converting from a Rust pointer to a
+        // generic C `void*` pointer is normal, and does not pose size issues on the
+        // kernel's side, which will use the given Transfer Receive sizes as bytes.
+        let res = unsafe {
+            bindings::spi_write_then_read(
+                dev.to_ptr(),
+                tx_buf.as_ptr() as *const core::ffi::c_void,
+                tx_buf.len() as core::ffi::c_uint,
+                rx_buf.as_mut_ptr() as *mut core::ffi::c_void,
+                rx_buf.len() as core::ffi::c_uint,
+            )
+        };
+
+        match res {
+            0 => Ok(()),                        // 0 indicates a valid transfer,
+            err => Err(Error::from_errno(err)), // A negative number indicates an error
+        }
+    }
+
+    /// Corresponds to the kernel's `spi_write`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let to_write = "rust-for-linux".as_bytes();
+    ///
+    /// // `spi_device` was previously provided by the kernel in that case
+    /// let write_result = Spi::write(spi_device, &to_write);
+    /// ```
+    pub fn write(dev: &mut SpiDevice, tx_buf: &[u8]) -> Result {
+        Spi::write_then_read(dev, tx_buf, &mut [0u8; 0])
+    }
+
+    /// Corresponds to the kernel's `spi_read`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut to_receive = [0u8; 10]; // let's receive 10 bytes
+    ///
+    /// // `spi_device` was previously provided by the kernel in that case
+    /// let transfer_result = Spi::read(spi_device, &mut to_receive);
+    /// ```
+    pub fn read(dev: &mut SpiDevice, rx_buf: &mut [u8]) -> Result {
+        Spi::write_then_read(dev, &[0u8; 0], rx_buf)
+    }
+}