1 // SPDX-License-Identifier: GPL-2.0
5 //! C header: [`include/linux/clk.h`](srctree/include/linux/clk.h)
7 //! Reference: <https://docs.kernel.org/driver-api/clk.html>
11 /// The frequency unit.
13 /// Represents a frequency in hertz, wrapping a [`c_ulong`] value.
18 /// use kernel::clk::Hertz;
38     pub const fn from_khz(khz: c_ulong) -> Self {  in from_khz()
43     pub const fn from_mhz(mhz: c_ulong) -> Self {  in from_mhz()
48     pub const fn from_ghz(ghz: c_ulong) -> Self {  in from_ghz()
52     /// Get the frequency in hertz
53     pub const fn as_hz(&self) -> c_ulong {  in as_hz()
57     /// Get the frequency in kilohertz
58     pub const fn as_khz(&self) -> c_ulong {  in as_khz()
62     /// Get the frequency in megahertz
63     pub const fn as_mhz(&self) -> c_ulong {  in as_mhz()
67     /// Get the frequency in gigahertz
68     pub const fn as_ghz(&self) -> c_ulong {  in as_ghz()
74     fn from(freq: Hertz) -> Self {  in from()
90     /// A reference-counted clock.
92     /// Rust abstraction for the C [`struct clk`].
96     /// A [`Clk`] instance holds either a pointer to a valid [`struct clk`] created by the C
99     /// Instances of this type are reference-counted. Calling [`Clk::get`] ensures that the
100     /// allocation remains valid for the lifetime of the [`Clk`].
108     /// use kernel::clk::{Clk, Hertz};
112     /// fn configure_clk(dev: &Device) -> Result {
113     ///     let clk = Clk::get(dev, Some(c_str!("apb_clk")))?;
115     ///     clk.prepare_enable()?;
119     ///     if clk.rate() != expected_rate {
120     ///         clk.set_rate(expected_rate)?;
123     ///     clk.disable_unprepare();
128     /// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
130     pub struct Clk(*mut bindings::clk);  struct
132     impl Clk {  impl
133         /// Gets [`Clk`] corresponding to a [`Device`] and a connection id.
137         /// [`clk_get`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get
138         pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {  in get()
143             // INVARIANT: The reference-count is decremented when [`Clk`] goes out of scope.  in get()
149         /// Obtain the raw [`struct clk`] pointer.
151         pub fn as_raw(&self) -> *mut bindings::clk {  in as_raw()  argument
159         /// [`clk_enable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_enable
161         pub fn enable(&self) -> Result {  in enable()
171         /// [`clk_disable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_disable
183         /// [`clk_prepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_prepare
185         pub fn prepare(&self) -> Result {  in prepare()
195         /// [`clk_unprepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_unprepare
205         /// Equivalent to calling [`Clk::prepare`] followed by [`Clk::enable`].
207         pub fn prepare_enable(&self) -> Result {  in prepare_enable()
215         /// Equivalent to calling [`Clk::disable`] followed by [`Clk::unprepare`].
227         /// [`clk_get_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_rate
229         pub fn rate(&self) -> Hertz {  in rate()
239         /// [`clk_set_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_set_rate
241         pub fn set_rate(&self, rate: Hertz) -> Result {  in set_rate()
248     impl Drop for Clk {  implementation
255     /// A reference-counted optional clock.
257     /// A lightweight wrapper around an optional [`Clk`]. An [`OptionalClk`] represents a [`Clk`]
263     /// An [`OptionalClk`] instance encapsulates a [`Clk`] with either a valid [`struct clk`] or
266     /// Instances of this type are reference-counted. Calling [`OptionalClk::get`] ensures that the
276     /// use kernel::clk::{OptionalClk, Hertz};
280     /// fn configure_clk(dev: &Device) -> Result {
281     ///     let clk = OptionalClk::get(dev, Some(c_str!("apb_clk")))?;
283     ///     clk.prepare_enable()?;
287     ///     if clk.rate() != expected_rate {
288     ///         clk.set_rate(expected_rate)?;
291     ///     clk.disable_unprepare();
296     /// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html
297     pub struct OptionalClk(Clk);
305         /// https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_optional
306         pub fn get(dev: &Device, name: Option<&CStr>) -> Result<Self> {  in get()
311             // INVARIANT: The reference-count is decremented when [`OptionalClk`] goes out of  in get()
313             Ok(Self(Clk(from_err_ptr(unsafe {  in get()
319     // Make [`OptionalClk`] behave like [`Clk`].
321         type Target = Clk;
323         fn deref(&self) -> &Clk {  in deref()  argument