rust-core/platdev: add of/devicetree matching support

Implement the bare minimum required so a Rust `platdev` can match
with devices described in the devicetree. Driver and device will
match if their `compatible` strings match. The Linux kernel will
instantiate one device per match.

Ideally, the of table should be const, and created at build time,
but we haven't figured out how to accomplish that yet.

Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>

Author: Sven Van Asbroeck

rust/kernel/bindings_helper.h

@@ -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;

rust/kernel/lib.rs

@@ -62,6 +62,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/of.rs

@@ -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/platdev.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);
+        }
     }
 }