rust: add initial common clock framework bindings

This patch adds initial abstractions including:
  - `Clk` wrapper around `struct clk *`.
  - Binding of clk_get() method implemented
    as a method of `device::RawDevice` trait.
  - `EnableClk` that is an invariant of
    the `Clk` type that manages usage of
    the disable_unprepare() function.
  - Routines get_rate() and prepare_enable()
    implemented as methods of `Clk` type.

Signed-off-by: Maciej Falkowski <m.falkowski@samsung.com>

Author: Maciej Falkowski

rust/helpers.c

@@ -2,6 +2,7 @@
 
 #include <linux/bug.h>
 #include <linux/build_bug.h>
+#include <linux/clk.h>
 #include <linux/uaccess.h>
 #include <linux/sched/signal.h>
 #include <linux/gfp.h>
@@ -22,6 +23,18 @@ __noreturn void rust_helper_BUG(void)
 	BUG();
 }
 
+void rust_helper_clk_disable_unprepare(struct clk *clk)
+{
+	return clk_disable_unprepare(clk);
+}
+EXPORT_SYMBOL_GPL(rust_helper_clk_disable_unprepare);
+
+int rust_helper_clk_prepare_enable(struct clk *clk)
+{
+	return clk_prepare_enable(clk);
+}
+EXPORT_SYMBOL_GPL(rust_helper_clk_prepare_enable);
+
 unsigned long rust_helper_copy_from_user(void *to, const void __user *from, unsigned long n)
 {
 	return copy_from_user(to, from, n);

rust/kernel/bindings_helper.h

@@ -1,6 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 
 #include <linux/cdev.h>
+#include <linux/clk.h>
 #include <linux/errname.h>
 #include <linux/fs.h>
 #include <linux/module.h>

rust/kernel/clk.rs

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Common clock framework.
+//!
+//! C header: [`include/linux/clk.h`](../../../../include/linux/clk.h)
+
+use crate::{bindings, error::Result, to_result};
+use core::mem::ManuallyDrop;
+
+/// Represents `struct clk *`.
+///
+/// # Invariants
+///
+/// The pointer is valid.
+pub struct Clk(*mut bindings::clk);
+
+impl Clk {
+    /// Creates new clock structure from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The pointer must be valid.
+    pub unsafe fn new(clk: *mut bindings::clk) -> Self {
+        Self(clk)
+    }
+
+    /// Returns value of the rate field of `struct clk`.
+    pub fn get_rate(&self) -> usize {
+        // SAFETY: the pointer is valid by the type invariant.
+        unsafe { bindings::clk_get_rate(self.0) as usize }
+    }
+
+    /// Prepares and enables the underlying hardware clock.
+    ///
+    /// This function should not be called in atomic context.
+    pub fn prepare_enable(self) -> Result<EnabledClk> {
+        // SAFETY: the pointer is valid by the type invariant.
+        to_result(|| unsafe { bindings::clk_prepare_enable(self.0) })?;
+        Ok(EnabledClk(self))
+    }
+}
+
+impl Drop for Clk {
+    fn drop(&mut self) {
+        // SAFETY: the pointer is valid by the type invariant.
+        unsafe { bindings::clk_put(self.0) };
+    }
+}
+
+/// A clock variant that is prepared and enabled.
+pub struct EnabledClk(Clk);
+
+impl EnabledClk {
+    /// Returns value of the rate field of `struct clk`.
+    pub fn get_rate(&self) -> usize {
+        self.0.get_rate()
+    }
+
+    /// Disables and later unprepares the underlying hardware clock prematurely.
+    ///
+    /// This function should not be called in atomic context.
+    pub fn disable_unprepare(self) -> Clk {
+        let mut clk = ManuallyDrop::new(self);
+        // SAFETY: the pointer is valid by the type invariant.
+        unsafe { bindings::clk_disable_unprepare(clk.0 .0) };
+        core::mem::replace(&mut clk.0, Clk(core::ptr::null_mut()))
+    }
+}
+
+impl Drop for EnabledClk {
+    fn drop(&mut self) {
+        // SAFETY: the pointer is valid by the type invariant.
+        unsafe { bindings::clk_disable_unprepare(self.0 .0) };
+    }
+}

rust/kernel/device.rs

@@ -4,6 +4,9 @@
 //!
 //! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
 
+#[cfg(CONFIG_COMMON_CLK)]
+use crate::{clk::Clk, error::from_kernel_err_ptr};
+
 use crate::{
     bindings,
     revocable::{Revocable, RevocableGuard},
@@ -43,6 +46,24 @@ pub unsafe trait RawDevice {
         // by the compiler because of their lifetimes).
         unsafe { CStr::from_char_ptr(name) }
     }
+
+    /// Lookups a clock producer consumed by this device.
+    ///
+    /// Returns a managed reference to the clock producer.
+    #[cfg(CONFIG_COMMON_CLK)]
+    fn clk_get(&self, id: Option<&CStr>) -> Result<Clk> {
+        let id_ptr = match id {
+            Some(cstr) => cstr.as_char_ptr(),
+            None => core::ptr::null(),
+        };
+
+        // SAFETY: id_ptr is optional and may be either a valid pointer
+        // from the type invariant or NULL otherwise.
+        let clk_ptr = unsafe { from_kernel_err_ptr(bindings::clk_get(self.raw_device(), id_ptr)) }?;
+
+        // SAFETY: clock is initialized with valid pointer returned from `bindings::clk_get` call.
+        unsafe { Ok(Clk::new(clk_ptr)) }
+    }
 }
 
 /// A ref-counted device.
@@ -62,7 +83,7 @@ impl Device {
     ///
     /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count.
     pub unsafe fn new(ptr: *mut bindings::device) -> Self {
-        // SAFETY: By the safety requiments, ptr is valid and its refcounted will be incremented.
+        // SAFETY: By the safety requirements, ptr is valid and its refcounted will be incremented.
         unsafe { bindings::get_device(ptr) };
         // INVARIANT: The safety requirements satisfy all but one invariant, which is that `self`
         // owns a reference. This is satisfied by the call to `get_device` above.

rust/kernel/lib.rs

@@ -45,6 +45,8 @@ pub mod amba;
 pub mod buffer;
 pub mod c_types;
 pub mod chrdev;
+#[cfg(CONFIG_COMMON_CLK)]
+pub mod clk;
 pub mod cred;
 pub mod device;
 pub mod driver;