rust/kernel/clk.rs - linux - Git at Google

 // SPDX-License-Identifier: GPL-2.0

 //! Clock abstractions.
 //!
 //! C header: [`include/linux/clk.h`](srctree/include/linux/clk.h)
 //!
 //! Reference: <https://docs.kernel.org/driver-api/clk.html>

 use crate::ffi::c_ulong;

 /// The frequency unit.
 ///
 /// Represents a frequency in hertz, wrapping a [`c_ulong`] value.
 ///
 /// # Examples
 ///
 /// ```
 /// use kernel::clk::Hertz;
 ///
 /// let hz = 1_000_000_000;
 /// let rate = Hertz(hz);
 ///
 /// assert_eq!(rate.as_hz(), hz);
 /// assert_eq!(rate, Hertz(hz));
 /// assert_eq!(rate, Hertz::from_khz(hz / 1_000));
 /// assert_eq!(rate, Hertz::from_mhz(hz / 1_000_000));
 /// assert_eq!(rate, Hertz::from_ghz(hz / 1_000_000_000));
 /// ```
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct Hertz(pub c_ulong);

 impl Hertz {
     const KHZ_TO_HZ: c_ulong = 1_000;
     const MHZ_TO_HZ: c_ulong = 1_000_000;
     const GHZ_TO_HZ: c_ulong = 1_000_000_000;

     /// Create a new instance from kilohertz (kHz)
     pub const fn from_khz(khz: c_ulong) -> Self {
         Self(khz * Self::KHZ_TO_HZ)
     }

     /// Create a new instance from megahertz (MHz)
     pub const fn from_mhz(mhz: c_ulong) -> Self {
         Self(mhz * Self::MHZ_TO_HZ)
     }

     /// Create a new instance from gigahertz (GHz)
     pub const fn from_ghz(ghz: c_ulong) -> Self {
         Self(ghz * Self::GHZ_TO_HZ)
     }

     /// Get the frequency in hertz
     pub const fn as_hz(&self) -> c_ulong {
         self.0
     }

     /// Get the frequency in kilohertz
     pub const fn as_khz(&self) -> c_ulong {
         self.0 / Self::KHZ_TO_HZ
     }

     /// Get the frequency in megahertz
     pub const fn as_mhz(&self) -> c_ulong {
         self.0 / Self::MHZ_TO_HZ
     }

     /// Get the frequency in gigahertz
     pub const fn as_ghz(&self) -> c_ulong {
         self.0 / Self::GHZ_TO_HZ
     }
 }

 impl From<Hertz> for c_ulong {
     fn from(freq: Hertz) -> Self {
         freq.0
     }
 }

 #[cfg(CONFIG_COMMON_CLK)]
 mod common_clk {
     use super::Hertz;
     use crate::{
         device::Device,
         error::{from_err_ptr, to_result, Result},
         prelude::*,
     };

     use core::{ops::Deref, ptr};

     /// A reference-counted clock.
     ///
     /// Rust abstraction for the C [`struct clk`].
     ///
     /// # Invariants
     ///
     /// A [`Clk`] instance holds either a pointer to a valid [`struct clk`] created by the C
     /// portion of the kernel or a NULL pointer.
     ///
     /// Instances of this type are reference-counted. Calling [`Clk::get`] ensures that the
     /// allocation remains valid for the lifetime of the [`Clk`].
     ///
     /// # Examples
     ///
     /// The following example demonstrates how to obtain and configure a clock for a device.
     ///
     /// ```
     /// use kernel::c_str;
     /// use kernel::clk::{Clk, Hertz};
     /// use kernel::device::Device;
     /// use kernel::error::Result;
     ///
     /// fn configure_clk(dev: &Device) -> Result {
     ///     let clk = Clk::get(dev, Some(c_str!("apb_clk")))?;
     ///
     ///     clk.prepare_enable()?;
     ///
     ///     let expected_rate = Hertz::from_ghz(1);
     ///
     ///     if clk.rate() != expected_rate {
     ///         clk.set_rate(expected_rate)?;
     ///     }
     ///
     ///     clk.disable_unprepare();
     ///     Ok(())
     /// }
     /// ```
     ///
     /// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
     #[repr(transparent)]
     pub struct Clk(*mut bindings::clk);

     impl Clk {
         /// Gets [`Clk`] corresponding to a [`Device`] and a connection id.
         ///
         /// Equivalent to the kernel's [`clk_get`] API.
         ///
         /// [`clk_get`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get
         pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {
             let con_id = name.map_or(ptr::null(), |n| n.as_ptr());

             // SAFETY: It is safe to call [`clk_get`] for a valid device pointer.
             //
             // INVARIANT: The reference-count is decremented when [`Clk`] goes out of scope.
             Ok(Self(from_err_ptr(unsafe {
                 bindings::clk_get(dev.as_raw(), con_id)
             })?))
         }

         /// Obtain the raw [`struct clk`] pointer.
         #[inline]
         pub fn as_raw(&self) -> *mut bindings::clk {
             self.0
         }

         /// Enable the clock.
         ///
         /// Equivalent to the kernel's [`clk_enable`] API.
         ///
         /// [`clk_enable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_enable
         #[inline]
         pub fn enable(&self) -> Result {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_enable`].
             to_result(unsafe { bindings::clk_enable(self.as_raw()) })
         }

         /// Disable the clock.
         ///
         /// Equivalent to the kernel's [`clk_disable`] API.
         ///
         /// [`clk_disable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_disable
         #[inline]
         pub fn disable(&self) {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_disable`].
             unsafe { bindings::clk_disable(self.as_raw()) };
         }

         /// Prepare the clock.
         ///
         /// Equivalent to the kernel's [`clk_prepare`] API.
         ///
         /// [`clk_prepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_prepare
         #[inline]
         pub fn prepare(&self) -> Result {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_prepare`].
             to_result(unsafe { bindings::clk_prepare(self.as_raw()) })
         }

         /// Unprepare the clock.
         ///
         /// Equivalent to the kernel's [`clk_unprepare`] API.
         ///
         /// [`clk_unprepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_unprepare
         #[inline]
         pub fn unprepare(&self) {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_unprepare`].
             unsafe { bindings::clk_unprepare(self.as_raw()) };
         }

         /// Prepare and enable the clock.
         ///
         /// Equivalent to calling [`Clk::prepare`] followed by [`Clk::enable`].
         #[inline]
         pub fn prepare_enable(&self) -> Result {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_prepare_enable`].
             to_result(unsafe { bindings::clk_prepare_enable(self.as_raw()) })
         }

         /// Disable and unprepare the clock.
         ///
         /// Equivalent to calling [`Clk::disable`] followed by [`Clk::unprepare`].
         #[inline]
         pub fn disable_unprepare(&self) {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_disable_unprepare`].
             unsafe { bindings::clk_disable_unprepare(self.as_raw()) };
         }

         /// Get clock's rate.
         ///
         /// Equivalent to the kernel's [`clk_get_rate`] API.
         ///
         /// [`clk_get_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_rate
         #[inline]
         pub fn rate(&self) -> Hertz {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_get_rate`].
             Hertz(unsafe { bindings::clk_get_rate(self.as_raw()) })
         }

         /// Set clock's rate.
         ///
         /// Equivalent to the kernel's [`clk_set_rate`] API.
         ///
         /// [`clk_set_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_set_rate
         #[inline]
         pub fn set_rate(&self, rate: Hertz) -> Result {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for
             // [`clk_set_rate`].
             to_result(unsafe { bindings::clk_set_rate(self.as_raw(), rate.as_hz()) })
         }
     }

     impl Drop for Clk {
         fn drop(&mut self) {
             // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_put`].
             unsafe { bindings::clk_put(self.as_raw()) };
         }
     }

     /// A reference-counted optional clock.
     ///
     /// A lightweight wrapper around an optional [`Clk`]. An [`OptionalClk`] represents a [`Clk`]
     /// that a driver can function without but may improve performance or enable additional
     /// features when available.
     ///
     /// # Invariants
     ///
     /// An [`OptionalClk`] instance encapsulates a [`Clk`] with either a valid [`struct clk`] or
     /// `NULL` pointer.
     ///
     /// Instances of this type are reference-counted. Calling [`OptionalClk::get`] ensures that the
     /// allocation remains valid for the lifetime of the [`OptionalClk`].
     ///
     /// # Examples
     ///
     /// The following example demonstrates how to obtain and configure an optional clock for a
     /// device. The code functions correctly whether or not the clock is available.
     ///
     /// ```
     /// use kernel::c_str;
     /// use kernel::clk::{OptionalClk, Hertz};
     /// use kernel::device::Device;
     /// use kernel::error::Result;
     ///
     /// fn configure_clk(dev: &Device) -> Result {
     ///     let clk = OptionalClk::get(dev, Some(c_str!("apb_clk")))?;
     ///
     ///     clk.prepare_enable()?;
     ///
     ///     let expected_rate = Hertz::from_ghz(1);
     ///
     ///     if clk.rate() != expected_rate {
     ///         clk.set_rate(expected_rate)?;
     ///     }
     ///
     ///     clk.disable_unprepare();
     ///     Ok(())
     /// }
     /// ```
     ///
     /// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
     pub struct OptionalClk(Clk);

     impl OptionalClk {
         /// Gets [`OptionalClk`] corresponding to a [`Device`] and a connection id.
         ///
         /// Equivalent to the kernel's [`clk_get_optional`] API.
         ///
         /// [`clk_get_optional`]:
         /// https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_optional
         pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {
             let con_id = name.map_or(ptr::null(), |n| n.as_ptr());

             // SAFETY: It is safe to call [`clk_get_optional`] for a valid device pointer.
             //
             // INVARIANT: The reference-count is decremented when [`OptionalClk`] goes out of
             // scope.
             Ok(Self(Clk(from_err_ptr(unsafe {
                 bindings::clk_get_optional(dev.as_raw(), con_id)
             })?)))
         }
     }

     // Make [`OptionalClk`] behave like [`Clk`].
     impl Deref for OptionalClk {
         type Target = Clk;

         fn deref(&self) -> &Clk {
             &self.0
         }
     }
 }

 #[cfg(CONFIG_COMMON_CLK)]
 pub use common_clk::*;
	// SPDX-License-Identifier: GPL-2.0

	//! Clock abstractions.
	//!
	//! C header: [`include/linux/clk.h`](srctree/include/linux/clk.h)
	//!
	//! Reference: <https://docs.kernel.org/driver-api/clk.html>

	use crate::ffi::c_ulong;

	/// The frequency unit.
	///
	/// Represents a frequency in hertz, wrapping a [`c_ulong`] value.
	///
	/// # Examples
	///
	/// ```
	/// use kernel::clk::Hertz;
	///
	/// let hz = 1_000_000_000;
	/// let rate = Hertz(hz);
	///
	/// assert_eq!(rate.as_hz(), hz);
	/// assert_eq!(rate, Hertz(hz));
	/// assert_eq!(rate, Hertz::from_khz(hz / 1_000));
	/// assert_eq!(rate, Hertz::from_mhz(hz / 1_000_000));
	/// assert_eq!(rate, Hertz::from_ghz(hz / 1_000_000_000));
	/// ```
	#[derive(Copy, Clone, PartialEq, Eq, Debug)]
	pub struct Hertz(pub c_ulong);

	impl Hertz {
	const KHZ_TO_HZ: c_ulong = 1_000;
	const MHZ_TO_HZ: c_ulong = 1_000_000;
	const GHZ_TO_HZ: c_ulong = 1_000_000_000;

	/// Create a new instance from kilohertz (kHz)
	pub const fn from_khz(khz: c_ulong) -> Self {
	Self(khz * Self::KHZ_TO_HZ)
	}

	/// Create a new instance from megahertz (MHz)
	pub const fn from_mhz(mhz: c_ulong) -> Self {
	Self(mhz * Self::MHZ_TO_HZ)
	}

	/// Create a new instance from gigahertz (GHz)
	pub const fn from_ghz(ghz: c_ulong) -> Self {
	Self(ghz * Self::GHZ_TO_HZ)
	}

	/// Get the frequency in hertz
	pub const fn as_hz(&self) -> c_ulong {
	self.0
	}

	/// Get the frequency in kilohertz
	pub const fn as_khz(&self) -> c_ulong {
	self.0 / Self::KHZ_TO_HZ
	}

	/// Get the frequency in megahertz
	pub const fn as_mhz(&self) -> c_ulong {
	self.0 / Self::MHZ_TO_HZ
	}

	/// Get the frequency in gigahertz
	pub const fn as_ghz(&self) -> c_ulong {
	self.0 / Self::GHZ_TO_HZ
	}
	}

	impl From<Hertz> for c_ulong {
	fn from(freq: Hertz) -> Self {
	freq.0
	}
	}

	#[cfg(CONFIG_COMMON_CLK)]
	mod common_clk {
	use super::Hertz;
	use crate::{
	device::Device,
	error::{from_err_ptr, to_result, Result},
	prelude::*,
	};

	use core::{ops::Deref, ptr};

	/// A reference-counted clock.
	///
	/// Rust abstraction for the C [`struct clk`].
	///
	/// # Invariants
	///
	/// A [`Clk`] instance holds either a pointer to a valid [`struct clk`] created by the C
	/// portion of the kernel or a NULL pointer.
	///
	/// Instances of this type are reference-counted. Calling [`Clk::get`] ensures that the
	/// allocation remains valid for the lifetime of the [`Clk`].
	///
	/// # Examples
	///
	/// The following example demonstrates how to obtain and configure a clock for a device.
	///
	/// ```
	/// use kernel::c_str;
	/// use kernel::clk::{Clk, Hertz};
	/// use kernel::device::Device;
	/// use kernel::error::Result;
	///
	/// fn configure_clk(dev: &Device) -> Result {
	/// let clk = Clk::get(dev, Some(c_str!("apb_clk")))?;
	///
	/// clk.prepare_enable()?;
	///
	/// let expected_rate = Hertz::from_ghz(1);
	///
	/// if clk.rate() != expected_rate {
	/// clk.set_rate(expected_rate)?;
	/// }
	///
	/// clk.disable_unprepare();
	/// Ok(())
	/// }
	/// ```
	///
	/// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
	#[repr(transparent)]
	pub struct Clk(*mut bindings::clk);

	impl Clk {
	/// Gets [`Clk`] corresponding to a [`Device`] and a connection id.
	///
	/// Equivalent to the kernel's [`clk_get`] API.
	///
	/// [`clk_get`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get
	pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {
	let con_id = name.map_or(ptr::null(), \|n\| n.as_ptr());

	// SAFETY: It is safe to call [`clk_get`] for a valid device pointer.
	//
	// INVARIANT: The reference-count is decremented when [`Clk`] goes out of scope.
	Ok(Self(from_err_ptr(unsafe {
	bindings::clk_get(dev.as_raw(), con_id)
	})?))
	}

	/// Obtain the raw [`struct clk`] pointer.
	#[inline]
	pub fn as_raw(&self) -> *mut bindings::clk {
	self.0
	}

	/// Enable the clock.
	///
	/// Equivalent to the kernel's [`clk_enable`] API.
	///
	/// [`clk_enable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_enable
	#[inline]
	pub fn enable(&self) -> Result {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_enable`].
	to_result(unsafe { bindings::clk_enable(self.as_raw()) })
	}

	/// Disable the clock.
	///
	/// Equivalent to the kernel's [`clk_disable`] API.
	///
	/// [`clk_disable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_disable
	#[inline]
	pub fn disable(&self) {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_disable`].
	unsafe { bindings::clk_disable(self.as_raw()) };
	}

	/// Prepare the clock.
	///
	/// Equivalent to the kernel's [`clk_prepare`] API.
	///
	/// [`clk_prepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_prepare
	#[inline]
	pub fn prepare(&self) -> Result {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_prepare`].
	to_result(unsafe { bindings::clk_prepare(self.as_raw()) })
	}

	/// Unprepare the clock.
	///
	/// Equivalent to the kernel's [`clk_unprepare`] API.
	///
	/// [`clk_unprepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_unprepare
	#[inline]
	pub fn unprepare(&self) {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_unprepare`].
	unsafe { bindings::clk_unprepare(self.as_raw()) };
	}

	/// Prepare and enable the clock.
	///
	/// Equivalent to calling [`Clk::prepare`] followed by [`Clk::enable`].
	#[inline]
	pub fn prepare_enable(&self) -> Result {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_prepare_enable`].
	to_result(unsafe { bindings::clk_prepare_enable(self.as_raw()) })
	}

	/// Disable and unprepare the clock.
	///
	/// Equivalent to calling [`Clk::disable`] followed by [`Clk::unprepare`].
	#[inline]
	pub fn disable_unprepare(&self) {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_disable_unprepare`].
	unsafe { bindings::clk_disable_unprepare(self.as_raw()) };
	}

	/// Get clock's rate.
	///
	/// Equivalent to the kernel's [`clk_get_rate`] API.
	///
	/// [`clk_get_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_rate
	#[inline]
	pub fn rate(&self) -> Hertz {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_get_rate`].
	Hertz(unsafe { bindings::clk_get_rate(self.as_raw()) })
	}

	/// Set clock's rate.
	///
	/// Equivalent to the kernel's [`clk_set_rate`] API.
	///
	/// [`clk_set_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_set_rate
	#[inline]
	pub fn set_rate(&self, rate: Hertz) -> Result {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for
	// [`clk_set_rate`].
	to_result(unsafe { bindings::clk_set_rate(self.as_raw(), rate.as_hz()) })
	}
	}

	impl Drop for Clk {
	fn drop(&mut self) {
	// SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_put`].
	unsafe { bindings::clk_put(self.as_raw()) };
	}
	}

	/// A reference-counted optional clock.
	///
	/// A lightweight wrapper around an optional [`Clk`]. An [`OptionalClk`] represents a [`Clk`]
	/// that a driver can function without but may improve performance or enable additional
	/// features when available.
	///
	/// # Invariants
	///
	/// An [`OptionalClk`] instance encapsulates a [`Clk`] with either a valid [`struct clk`] or
	/// `NULL` pointer.
	///
	/// Instances of this type are reference-counted. Calling [`OptionalClk::get`] ensures that the
	/// allocation remains valid for the lifetime of the [`OptionalClk`].
	///
	/// # Examples
	///
	/// The following example demonstrates how to obtain and configure an optional clock for a
	/// device. The code functions correctly whether or not the clock is available.
	///
	/// ```
	/// use kernel::c_str;
	/// use kernel::clk::{OptionalClk, Hertz};
	/// use kernel::device::Device;
	/// use kernel::error::Result;
	///
	/// fn configure_clk(dev: &Device) -> Result {
	/// let clk = OptionalClk::get(dev, Some(c_str!("apb_clk")))?;
	///
	/// clk.prepare_enable()?;
	///
	/// let expected_rate = Hertz::from_ghz(1);
	///
	/// if clk.rate() != expected_rate {
	/// clk.set_rate(expected_rate)?;
	/// }
	///
	/// clk.disable_unprepare();
	/// Ok(())
	/// }
	/// ```
	///
	/// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
	pub struct OptionalClk(Clk);

	impl OptionalClk {
	/// Gets [`OptionalClk`] corresponding to a [`Device`] and a connection id.
	///
	/// Equivalent to the kernel's [`clk_get_optional`] API.
	///
	/// [`clk_get_optional`]:
	/// https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_optional
	pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {
	let con_id = name.map_or(ptr::null(), \|n\| n.as_ptr());

	// SAFETY: It is safe to call [`clk_get_optional`] for a valid device pointer.
	//
	// INVARIANT: The reference-count is decremented when [`OptionalClk`] goes out of
	// scope.
	Ok(Self(Clk(from_err_ptr(unsafe {
	bindings::clk_get_optional(dev.as_raw(), con_id)
	})?)))
	}
	}

	// Make [`OptionalClk`] behave like [`Clk`].
	impl Deref for OptionalClk {
	type Target = Clk;

	fn deref(&self) -> &Clk {
	&self.0
	}
	}
	}

	#[cfg(CONFIG_COMMON_CLK)]
	pub use common_clk::*;