Merge pull request torvalds#276 from TheSven73/rust-for-linux-pdev-pr2

Simple Rust driver that touches real hardware: PR 2/6

Author: wedsonaf

arch/arm/boot/dts/bcm2835-rpi-zero-w-rust.dts

@@ -7,6 +7,7 @@
 
 use alloc::boxed::Box;
 use core::pin::Pin;
+use kernel::of::OfMatchTable;
 use kernel::prelude::*;
 use kernel::{cstr, platdev};
 
@@ -24,7 +25,13 @@ struct RngModule {
 
 impl KernelModule for RngModule {
     fn init() -> Result<Self> {
-        let pdev = platdev::Registration::new_pinned(cstr!("bcm2835-rng-rust"), &THIS_MODULE)?;
+        let of_match_tbl = OfMatchTable::new(&cstr!("brcm,bcm2835-rng"))?;
+
+        let pdev = platdev::Registration::new_pinned(
+            cstr!("bcm2835-rng-rust"),
+            Some(of_match_tbl),
+            &THIS_MODULE,
+        )?;
 
         Ok(RngModule { _pdev: pdev })
     }

arch/arm/boot/dts/bcm2836-rpi-2-b-rust.dts

@@ -14,6 +14,7 @@
 #include <linux/mm.h>
 #include <uapi/linux/android/binder.h>
 #include <linux/platform_device.h>
+#include <linux/of_platform.h>
 
 // `bindgen` gets confused at certain things
 const gfp_t BINDINGS_GFP_KERNEL = GFP_KERNEL;

drivers/char/hw_random/bcm2835_rng_rust.rs

@@ -63,6 +63,7 @@ pub mod sysctl;
 
 pub mod io_buffer;
 pub mod iov_iter;
+pub mod of;
 pub mod platdev;
 mod types;
 pub mod user_ptr;

rust/kernel/bindings_helper.h

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Devicetree and Open Firmware abstractions.
+//!
+//! C header: [`include/linux/of_*.h`](../../../../include/linux/of_*.h)
+
+use alloc::boxed::Box;
+
+use crate::{
+    bindings, c_types,
+    error::{Error, Result},
+    types::PointerWrapper,
+    CStr,
+};
+
+use core::mem::transmute;
+
+type InnerTable = Box<[bindings::of_device_id; 2]>;
+
+/// Wraps a kernel Open Firmware / devicetree match table.
+///
+/// Rust drivers may create this structure to match against devices
+/// described in the devicetree.
+///
+/// The ['PointerWrapper'] trait provides conversion to/from a raw pointer,
+/// suitable to be assigned to a `bindings::device_driver::of_match_table`.
+///
+/// # Invariants
+///
+/// The final array element is always filled with zeros (the default).
+pub struct OfMatchTable(InnerTable);
+
+impl OfMatchTable {
+    /// Creates a [`OfMatchTable`] from a single `compatible` string.
+    pub fn new(compatible: &CStr<'static>) -> Result<Self> {
+        let tbl: InnerTable = Box::try_new([
+            Self::new_of_device_id(compatible)?,
+            bindings::of_device_id::default(),
+        ])?;
+        // INVARIANTS: we allocated an array with `default()` as its final
+        // element, therefore that final element will be filled with zeros,
+        // and the invariant above will hold.
+        Ok(Self(tbl))
+    }
+
+    fn new_of_device_id(compatible: &CStr<'static>) -> Result<bindings::of_device_id> {
+        let mut buf = [0_u8; 128];
+        if compatible.len() > buf.len() {
+            return Err(Error::EINVAL);
+        }
+        buf.get_mut(..compatible.len())
+            .ok_or(Error::EINVAL)?
+            .copy_from_slice(compatible.as_bytes());
+        Ok(bindings::of_device_id {
+            // SAFETY: re-interpretation from [u8] to [c_types::c_char] of same length is always safe.
+            compatible: unsafe { transmute::<[u8; 128], [c_types::c_char; 128]>(buf) },
+            ..Default::default()
+        })
+    }
+}
+
+impl PointerWrapper for OfMatchTable {
+    fn into_pointer(self) -> *const c_types::c_void {
+        // Per the invariant above, the generated pointer points to an
+        // array of `bindings::of_device_id`, where the final element is
+        // filled with zeros (the sentinel). Therefore, it's suitable to
+        // be assigned to `bindings::device_driver::of_match_table`.
+        self.0.into_pointer()
+    }
+
+    unsafe fn from_pointer(p: *const c_types::c_void) -> Self {
+        Self(InnerTable::from_pointer(p))
+    }
+}

rust/kernel/lib.rs

@@ -9,7 +9,10 @@
 use crate::{
     bindings, c_types,
     error::{Error, Result},
-    pr_info, CStr,
+    of::OfMatchTable,
+    pr_info,
+    types::PointerWrapper,
+    CStr,
 };
 use alloc::boxed::Box;
 use core::{marker::PhantomPinned, pin::Pin};
@@ -18,6 +21,7 @@ use core::{marker::PhantomPinned, pin::Pin};
 #[derive(Default)]
 pub struct Registration {
     registered: bool,
+    of_table: Option<*const c_types::c_void>,
     pdrv: bindings::platform_driver,
     _pin: PhantomPinned,
 }
@@ -40,6 +44,7 @@ impl Registration {
     fn register(
         self: Pin<&mut Self>,
         name: CStr<'static>,
+        of_match_table: Option<OfMatchTable>,
         module: &'static crate::ThisModule,
     ) -> Result {
         // SAFETY: We must ensure that we never move out of `this`.
@@ -49,13 +54,22 @@ impl Registration {
             return Err(Error::EINVAL);
         }
         this.pdrv.driver.name = name.as_ptr() as *const c_types::c_char;
+        if let Some(tbl) = of_match_table {
+            let ptr = tbl.into_pointer();
+            this.of_table = Some(ptr);
+            this.pdrv.driver.of_match_table = ptr.cast();
+        }
         this.pdrv.probe = Some(probe_callback);
         this.pdrv.remove = Some(remove_callback);
         // SAFETY:
         //   - `this.pdrv` lives at least until the call to `platform_driver_unregister()` returns.
         //   - `name` pointer has static lifetime.
         //   - `module.0` lives at least as long as the module.
         //   - `probe()` and `remove()` are static functions.
+        //   - `of_match_table` is either:
+        //      - a raw pointer which lives until after the call to
+        //       `bindings::platform_driver_unregister()`, or
+        //      - null.
         let ret = unsafe { bindings::__platform_driver_register(&mut this.pdrv, module.0) };
         if ret < 0 {
             return Err(Error::from_kernel_errno(ret));
@@ -69,10 +83,11 @@ impl Registration {
     /// Returns a pinned heap-allocated representation of the registration.
     pub fn new_pinned(
         name: CStr<'static>,
+        of_match_tbl: Option<OfMatchTable>,
         module: &'static crate::ThisModule,
     ) -> Result<Pin<Box<Self>>> {
         let mut r = Pin::from(Box::try_new(Self::default())?);
-        r.as_mut().register(name, module)?;
+        r.as_mut().register(name, of_match_tbl, module)?;
         Ok(r)
     }
 }
@@ -85,5 +100,10 @@ impl Drop for Registration {
             // safe to call.
             unsafe { bindings::platform_driver_unregister(&mut self.pdrv) }
         }
+        if let Some(ptr) = self.of_table {
+            // SAFETY: `ptr` came from an `OfMatchTable`.
+            let tbl = unsafe { OfMatchTable::from_pointer(ptr) };
+            drop(tbl);
+        }
     }
 }