kernel/
opp.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Operating performance points.
4//!
5//! This module provides rust abstractions for interacting with the OPP subsystem.
6//!
7//! C header: [`include/linux/pm_opp.h`](srctree/include/linux/pm_opp.h)
8//!
9//! Reference: <https://docs.kernel.org/power/opp.html>
10
11use crate::{
12    clk::Hertz,
13    cpumask::{Cpumask, CpumaskVar},
14    device::Device,
15    error::{code::*, from_err_ptr, from_result, to_result, Result, VTABLE_DEFAULT_ERROR},
16    ffi::c_ulong,
17    prelude::*,
18    str::CString,
19    sync::aref::{ARef, AlwaysRefCounted},
20    types::Opaque,
21};
22
23#[cfg(CONFIG_CPU_FREQ)]
24/// Frequency table implementation.
25mod freq {
26    use super::*;
27    use crate::cpufreq;
28    use core::ops::Deref;
29
30    /// OPP frequency table.
31    ///
32    /// A [`cpufreq::Table`] created from [`Table`].
33    pub struct FreqTable {
34        dev: ARef<Device>,
35        ptr: *mut bindings::cpufreq_frequency_table,
36    }
37
38    impl FreqTable {
39        /// Creates a new instance of [`FreqTable`] from [`Table`].
40        pub(crate) fn new(table: &Table) -> Result<Self> {
41            let mut ptr: *mut bindings::cpufreq_frequency_table = ptr::null_mut();
42
43            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
44            // requirements.
45            to_result(unsafe {
46                bindings::dev_pm_opp_init_cpufreq_table(table.dev.as_raw(), &mut ptr)
47            })?;
48
49            Ok(Self {
50                dev: table.dev.clone(),
51                ptr,
52            })
53        }
54
55        /// Returns a reference to the underlying [`cpufreq::Table`].
56        #[inline]
57        fn table(&self) -> &cpufreq::Table {
58            // SAFETY: The `ptr` is guaranteed by the C code to be valid.
59            unsafe { cpufreq::Table::from_raw(self.ptr) }
60        }
61    }
62
63    impl Deref for FreqTable {
64        type Target = cpufreq::Table;
65
66        #[inline]
67        fn deref(&self) -> &Self::Target {
68            self.table()
69        }
70    }
71
72    impl Drop for FreqTable {
73        fn drop(&mut self) {
74            // SAFETY: The pointer was created via `dev_pm_opp_init_cpufreq_table`, and is only
75            // freed here.
76            unsafe {
77                bindings::dev_pm_opp_free_cpufreq_table(self.dev.as_raw(), &mut self.as_raw())
78            };
79        }
80    }
81}
82
83#[cfg(CONFIG_CPU_FREQ)]
84pub use freq::FreqTable;
85
86use core::{marker::PhantomData, ptr};
87
88use macros::vtable;
89
90/// Creates a null-terminated slice of pointers to [`Cstring`]s.
91fn to_c_str_array(names: &[CString]) -> Result<KVec<*const u8>> {
92    // Allocated a null-terminated vector of pointers.
93    let mut list = KVec::with_capacity(names.len() + 1, GFP_KERNEL)?;
94
95    for name in names.iter() {
96        list.push(name.as_ptr().cast(), GFP_KERNEL)?;
97    }
98
99    list.push(ptr::null(), GFP_KERNEL)?;
100    Ok(list)
101}
102
103/// The voltage unit.
104///
105/// Represents voltage in microvolts, wrapping a [`c_ulong`] value.
106///
107/// # Examples
108///
109/// ```
110/// use kernel::opp::MicroVolt;
111///
112/// let raw = 90500;
113/// let volt = MicroVolt(raw);
114///
115/// assert_eq!(usize::from(volt), raw);
116/// assert_eq!(volt, MicroVolt(raw));
117/// ```
118#[derive(Copy, Clone, PartialEq, Eq, Debug)]
119pub struct MicroVolt(pub c_ulong);
120
121impl From<MicroVolt> for c_ulong {
122    #[inline]
123    fn from(volt: MicroVolt) -> Self {
124        volt.0
125    }
126}
127
128/// The power unit.
129///
130/// Represents power in microwatts, wrapping a [`c_ulong`] value.
131///
132/// # Examples
133///
134/// ```
135/// use kernel::opp::MicroWatt;
136///
137/// let raw = 1000000;
138/// let power = MicroWatt(raw);
139///
140/// assert_eq!(usize::from(power), raw);
141/// assert_eq!(power, MicroWatt(raw));
142/// ```
143#[derive(Copy, Clone, PartialEq, Eq, Debug)]
144pub struct MicroWatt(pub c_ulong);
145
146impl From<MicroWatt> for c_ulong {
147    #[inline]
148    fn from(power: MicroWatt) -> Self {
149        power.0
150    }
151}
152
153/// Handle for a dynamically created [`OPP`].
154///
155/// The associated [`OPP`] is automatically removed when the [`Token`] is dropped.
156///
157/// # Examples
158///
159/// The following example demonstrates how to create an [`OPP`] dynamically.
160///
161/// ```
162/// use kernel::clk::Hertz;
163/// use kernel::device::Device;
164/// use kernel::error::Result;
165/// use kernel::opp::{Data, MicroVolt, Token};
166/// use kernel::sync::aref::ARef;
167///
168/// fn create_opp(dev: &ARef<Device>, freq: Hertz, volt: MicroVolt, level: u32) -> Result<Token> {
169///     let data = Data::new(freq, volt, level, false);
170///
171///     // OPP is removed once token goes out of scope.
172///     data.add_opp(dev)
173/// }
174/// ```
175pub struct Token {
176    dev: ARef<Device>,
177    freq: Hertz,
178}
179
180impl Token {
181    /// Dynamically adds an [`OPP`] and returns a [`Token`] that removes it on drop.
182    fn new(dev: &ARef<Device>, mut data: Data) -> Result<Self> {
183        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
184        // requirements.
185        to_result(unsafe { bindings::dev_pm_opp_add_dynamic(dev.as_raw(), &mut data.0) })?;
186        Ok(Self {
187            dev: dev.clone(),
188            freq: data.freq(),
189        })
190    }
191}
192
193impl Drop for Token {
194    fn drop(&mut self) {
195        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
196        // requirements.
197        unsafe { bindings::dev_pm_opp_remove(self.dev.as_raw(), self.freq.into()) };
198    }
199}
200
201/// OPP data.
202///
203/// Rust abstraction for the C `struct dev_pm_opp_data`, used to define operating performance
204/// points (OPPs) dynamically.
205///
206/// # Examples
207///
208/// The following example demonstrates how to create an [`OPP`] with [`Data`].
209///
210/// ```
211/// use kernel::clk::Hertz;
212/// use kernel::device::Device;
213/// use kernel::error::Result;
214/// use kernel::opp::{Data, MicroVolt, Token};
215/// use kernel::sync::aref::ARef;
216///
217/// fn create_opp(dev: &ARef<Device>, freq: Hertz, volt: MicroVolt, level: u32) -> Result<Token> {
218///     let data = Data::new(freq, volt, level, false);
219///
220///     // OPP is removed once token goes out of scope.
221///     data.add_opp(dev)
222/// }
223/// ```
224#[repr(transparent)]
225pub struct Data(bindings::dev_pm_opp_data);
226
227impl Data {
228    /// Creates a new instance of [`Data`].
229    ///
230    /// This can be used to define a dynamic OPP to be added to a device.
231    pub fn new(freq: Hertz, volt: MicroVolt, level: u32, turbo: bool) -> Self {
232        Self(bindings::dev_pm_opp_data {
233            turbo,
234            freq: freq.into(),
235            u_volt: volt.into(),
236            level,
237        })
238    }
239
240    /// Adds an [`OPP`] dynamically.
241    ///
242    /// Returns a [`Token`] that ensures the OPP is automatically removed
243    /// when it goes out of scope.
244    #[inline]
245    pub fn add_opp(self, dev: &ARef<Device>) -> Result<Token> {
246        Token::new(dev, self)
247    }
248
249    /// Returns the frequency associated with this OPP data.
250    #[inline]
251    fn freq(&self) -> Hertz {
252        Hertz(self.0.freq)
253    }
254}
255
256/// [`OPP`] search options.
257///
258/// # Examples
259///
260/// Defines how to search for an [`OPP`] in a [`Table`] relative to a frequency.
261///
262/// ```
263/// use kernel::clk::Hertz;
264/// use kernel::error::Result;
265/// use kernel::opp::{OPP, SearchType, Table};
266/// use kernel::sync::aref::ARef;
267///
268/// fn find_opp(table: &Table, freq: Hertz) -> Result<ARef<OPP>> {
269///     let opp = table.opp_from_freq(freq, Some(true), None, SearchType::Exact)?;
270///
271///     pr_info!("OPP frequency is: {:?}\n", opp.freq(None));
272///     pr_info!("OPP voltage is: {:?}\n", opp.voltage());
273///     pr_info!("OPP level is: {}\n", opp.level());
274///     pr_info!("OPP power is: {:?}\n", opp.power());
275///
276///     Ok(opp)
277/// }
278/// ```
279#[derive(Copy, Clone, Debug, Eq, PartialEq)]
280pub enum SearchType {
281    /// Match the exact frequency.
282    Exact,
283    /// Find the highest frequency less than or equal to the given value.
284    Floor,
285    /// Find the lowest frequency greater than or equal to the given value.
286    Ceil,
287}
288
289/// OPP configuration callbacks.
290///
291/// Implement this trait to customize OPP clock and regulator setup for your device.
292#[vtable]
293pub trait ConfigOps {
294    /// This is typically used to scale clocks when transitioning between OPPs.
295    #[inline]
296    fn config_clks(_dev: &Device, _table: &Table, _opp: &OPP, _scaling_down: bool) -> Result {
297        build_error!(VTABLE_DEFAULT_ERROR)
298    }
299
300    /// This provides access to the old and new OPPs, allowing for safe regulator adjustments.
301    #[inline]
302    fn config_regulators(
303        _dev: &Device,
304        _opp_old: &OPP,
305        _opp_new: &OPP,
306        _data: *mut *mut bindings::regulator,
307        _count: u32,
308    ) -> Result {
309        build_error!(VTABLE_DEFAULT_ERROR)
310    }
311}
312
313/// OPP configuration token.
314///
315/// Returned by the OPP core when configuration is applied to a [`Device`]. The associated
316/// configuration is automatically cleared when the token is dropped.
317pub struct ConfigToken(i32);
318
319impl Drop for ConfigToken {
320    fn drop(&mut self) {
321        // SAFETY: This is the same token value returned by the C code via `dev_pm_opp_set_config`.
322        unsafe { bindings::dev_pm_opp_clear_config(self.0) };
323    }
324}
325
326/// OPP configurations.
327///
328/// Rust abstraction for the C `struct dev_pm_opp_config`.
329///
330/// # Examples
331///
332/// The following example demonstrates how to set OPP property-name configuration for a [`Device`].
333///
334/// ```
335/// use kernel::device::Device;
336/// use kernel::error::Result;
337/// use kernel::opp::{Config, ConfigOps, ConfigToken};
338/// use kernel::str::CString;
339/// use kernel::sync::aref::ARef;
340/// use kernel::macros::vtable;
341///
342/// #[derive(Default)]
343/// struct Driver;
344///
345/// #[vtable]
346/// impl ConfigOps for Driver {}
347///
348/// fn configure(dev: &ARef<Device>) -> Result<ConfigToken> {
349///     let name = CString::try_from_fmt(fmt!("slow"))?;
350///
351///     // The OPP configuration is cleared once the [`ConfigToken`] goes out of scope.
352///     Config::<Driver>::new()
353///         .set_prop_name(name)?
354///         .set(dev)
355/// }
356/// ```
357#[derive(Default)]
358pub struct Config<T: ConfigOps>
359where
360    T: Default,
361{
362    clk_names: Option<KVec<CString>>,
363    prop_name: Option<CString>,
364    regulator_names: Option<KVec<CString>>,
365    supported_hw: Option<KVec<u32>>,
366
367    // Tuple containing (required device, index)
368    required_dev: Option<(ARef<Device>, u32)>,
369    _data: PhantomData<T>,
370}
371
372impl<T: ConfigOps + Default> Config<T> {
373    /// Creates a new instance of [`Config`].
374    #[inline]
375    pub fn new() -> Self {
376        Self::default()
377    }
378
379    /// Initializes clock names.
380    pub fn set_clk_names(mut self, names: KVec<CString>) -> Result<Self> {
381        if self.clk_names.is_some() {
382            return Err(EBUSY);
383        }
384
385        if names.is_empty() {
386            return Err(EINVAL);
387        }
388
389        self.clk_names = Some(names);
390        Ok(self)
391    }
392
393    /// Initializes property name.
394    pub fn set_prop_name(mut self, name: CString) -> Result<Self> {
395        if self.prop_name.is_some() {
396            return Err(EBUSY);
397        }
398
399        self.prop_name = Some(name);
400        Ok(self)
401    }
402
403    /// Initializes regulator names.
404    pub fn set_regulator_names(mut self, names: KVec<CString>) -> Result<Self> {
405        if self.regulator_names.is_some() {
406            return Err(EBUSY);
407        }
408
409        if names.is_empty() {
410            return Err(EINVAL);
411        }
412
413        self.regulator_names = Some(names);
414
415        Ok(self)
416    }
417
418    /// Initializes required devices.
419    pub fn set_required_dev(mut self, dev: ARef<Device>, index: u32) -> Result<Self> {
420        if self.required_dev.is_some() {
421            return Err(EBUSY);
422        }
423
424        self.required_dev = Some((dev, index));
425        Ok(self)
426    }
427
428    /// Initializes supported hardware.
429    pub fn set_supported_hw(mut self, hw: KVec<u32>) -> Result<Self> {
430        if self.supported_hw.is_some() {
431            return Err(EBUSY);
432        }
433
434        if hw.is_empty() {
435            return Err(EINVAL);
436        }
437
438        self.supported_hw = Some(hw);
439        Ok(self)
440    }
441
442    /// Sets the configuration with the OPP core.
443    ///
444    /// The returned [`ConfigToken`] will remove the configuration when dropped.
445    pub fn set(self, dev: &Device) -> Result<ConfigToken> {
446        let (_clk_list, clk_names) = match &self.clk_names {
447            Some(x) => {
448                let list = to_c_str_array(x)?;
449                let ptr = list.as_ptr();
450                (Some(list), ptr)
451            }
452            None => (None, ptr::null()),
453        };
454
455        let (_regulator_list, regulator_names) = match &self.regulator_names {
456            Some(x) => {
457                let list = to_c_str_array(x)?;
458                let ptr = list.as_ptr();
459                (Some(list), ptr)
460            }
461            None => (None, ptr::null()),
462        };
463
464        let prop_name = self
465            .prop_name
466            .as_ref()
467            .map_or(ptr::null(), |p| p.as_char_ptr());
468
469        let (supported_hw, supported_hw_count) = self
470            .supported_hw
471            .as_ref()
472            .map_or((ptr::null(), 0), |hw| (hw.as_ptr(), hw.len() as u32));
473
474        let (required_dev, required_dev_index) = self
475            .required_dev
476            .as_ref()
477            .map_or((ptr::null_mut(), 0), |(dev, idx)| (dev.as_raw(), *idx));
478
479        let mut config = bindings::dev_pm_opp_config {
480            clk_names,
481            config_clks: if T::HAS_CONFIG_CLKS {
482                Some(Self::config_clks)
483            } else {
484                None
485            },
486            prop_name,
487            regulator_names,
488            config_regulators: if T::HAS_CONFIG_REGULATORS {
489                Some(Self::config_regulators)
490            } else {
491                None
492            },
493            supported_hw,
494            supported_hw_count,
495
496            required_dev,
497            required_dev_index,
498        };
499
500        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
501        // requirements. The OPP core guarantees not to access fields of [`Config`] after this call
502        // and so we don't need to save a copy of them for future use.
503        let ret = unsafe { bindings::dev_pm_opp_set_config(dev.as_raw(), &mut config) };
504
505        to_result(ret).map(|()| ConfigToken(ret))
506    }
507
508    /// Config's clk callback.
509    ///
510    /// SAFETY: Called from C. Inputs must be valid pointers.
511    extern "C" fn config_clks(
512        dev: *mut bindings::device,
513        opp_table: *mut bindings::opp_table,
514        opp: *mut bindings::dev_pm_opp,
515        _data: *mut c_void,
516        scaling_down: bool,
517    ) -> c_int {
518        from_result(|| {
519            // SAFETY: 'dev' is guaranteed by the C code to be valid.
520            let dev = unsafe { Device::get_device(dev) };
521            T::config_clks(
522                &dev,
523                // SAFETY: 'opp_table' is guaranteed by the C code to be valid.
524                &unsafe { Table::from_raw_table(opp_table, &dev) },
525                // SAFETY: 'opp' is guaranteed by the C code to be valid.
526                unsafe { OPP::from_raw_opp(opp)? },
527                scaling_down,
528            )
529            .map(|()| 0)
530        })
531    }
532
533    /// Config's regulator callback.
534    ///
535    /// SAFETY: Called from C. Inputs must be valid pointers.
536    extern "C" fn config_regulators(
537        dev: *mut bindings::device,
538        old_opp: *mut bindings::dev_pm_opp,
539        new_opp: *mut bindings::dev_pm_opp,
540        regulators: *mut *mut bindings::regulator,
541        count: c_uint,
542    ) -> c_int {
543        from_result(|| {
544            // SAFETY: 'dev' is guaranteed by the C code to be valid.
545            let dev = unsafe { Device::get_device(dev) };
546            T::config_regulators(
547                &dev,
548                // SAFETY: 'old_opp' is guaranteed by the C code to be valid.
549                unsafe { OPP::from_raw_opp(old_opp)? },
550                // SAFETY: 'new_opp' is guaranteed by the C code to be valid.
551                unsafe { OPP::from_raw_opp(new_opp)? },
552                regulators,
553                count,
554            )
555            .map(|()| 0)
556        })
557    }
558}
559
560/// A reference-counted OPP table.
561///
562/// Rust abstraction for the C `struct opp_table`.
563///
564/// # Invariants
565///
566/// The pointer stored in `Self` is non-null and valid for the lifetime of the [`Table`].
567///
568/// Instances of this type are reference-counted.
569///
570/// # Examples
571///
572/// The following example demonstrates how to get OPP [`Table`] for a [`Cpumask`] and set its
573/// frequency.
574///
575/// ```
576/// # #![cfg(CONFIG_OF)]
577/// use kernel::clk::Hertz;
578/// use kernel::cpumask::Cpumask;
579/// use kernel::device::Device;
580/// use kernel::error::Result;
581/// use kernel::opp::Table;
582/// use kernel::sync::aref::ARef;
583///
584/// fn get_table(dev: &ARef<Device>, mask: &mut Cpumask, freq: Hertz) -> Result<Table> {
585///     let mut opp_table = Table::from_of_cpumask(dev, mask)?;
586///
587///     if opp_table.opp_count()? == 0 {
588///         return Err(EINVAL);
589///     }
590///
591///     pr_info!("Max transition latency is: {} ns\n", opp_table.max_transition_latency_ns());
592///     pr_info!("Suspend frequency is: {:?}\n", opp_table.suspend_freq());
593///
594///     opp_table.set_rate(freq)?;
595///     Ok(opp_table)
596/// }
597/// ```
598pub struct Table {
599    ptr: *mut bindings::opp_table,
600    dev: ARef<Device>,
601    #[allow(dead_code)]
602    em: bool,
603    #[allow(dead_code)]
604    of: bool,
605    cpus: Option<CpumaskVar>,
606}
607
608/// SAFETY: It is okay to send ownership of [`Table`] across thread boundaries.
609unsafe impl Send for Table {}
610
611/// SAFETY: It is okay to access [`Table`] through shared references from other threads because
612/// we're either accessing properties that don't change or that are properly synchronised by C code.
613unsafe impl Sync for Table {}
614
615impl Table {
616    /// Creates a new reference-counted [`Table`] from a raw pointer.
617    ///
618    /// # Safety
619    ///
620    /// Callers must ensure that `ptr` is valid and non-null.
621    unsafe fn from_raw_table(ptr: *mut bindings::opp_table, dev: &ARef<Device>) -> Self {
622        // SAFETY: By the safety requirements, ptr is valid and its refcount will be incremented.
623        //
624        // INVARIANT: The reference-count is decremented when [`Table`] goes out of scope.
625        unsafe { bindings::dev_pm_opp_get_opp_table_ref(ptr) };
626
627        Self {
628            ptr,
629            dev: dev.clone(),
630            em: false,
631            of: false,
632            cpus: None,
633        }
634    }
635
636    /// Creates a new reference-counted [`Table`] instance for a [`Device`].
637    pub fn from_dev(dev: &Device) -> Result<Self> {
638        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
639        // requirements.
640        //
641        // INVARIANT: The reference-count is incremented by the C code and is decremented when
642        // [`Table`] goes out of scope.
643        let ptr = from_err_ptr(unsafe { bindings::dev_pm_opp_get_opp_table(dev.as_raw()) })?;
644
645        Ok(Self {
646            ptr,
647            dev: dev.into(),
648            em: false,
649            of: false,
650            cpus: None,
651        })
652    }
653
654    /// Creates a new reference-counted [`Table`] instance for a [`Device`] based on device tree
655    /// entries.
656    #[cfg(CONFIG_OF)]
657    pub fn from_of(dev: &ARef<Device>, index: i32) -> Result<Self> {
658        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
659        // requirements.
660        //
661        // INVARIANT: The reference-count is incremented by the C code and is decremented when
662        // [`Table`] goes out of scope.
663        to_result(unsafe { bindings::dev_pm_opp_of_add_table_indexed(dev.as_raw(), index) })?;
664
665        // Get the newly created [`Table`].
666        let mut table = Self::from_dev(dev)?;
667        table.of = true;
668
669        Ok(table)
670    }
671
672    /// Remove device tree based [`Table`].
673    #[cfg(CONFIG_OF)]
674    #[inline]
675    fn remove_of(&self) {
676        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
677        // requirements. We took the reference from [`from_of`] earlier, it is safe to drop the
678        // same now.
679        unsafe { bindings::dev_pm_opp_of_remove_table(self.dev.as_raw()) };
680    }
681
682    /// Creates a new reference-counted [`Table`] instance for a [`Cpumask`] based on device tree
683    /// entries.
684    #[cfg(CONFIG_OF)]
685    pub fn from_of_cpumask(dev: &Device, cpumask: &mut Cpumask) -> Result<Self> {
686        // SAFETY: The cpumask is valid and the returned pointer will be owned by the [`Table`]
687        // instance.
688        //
689        // INVARIANT: The reference-count is incremented by the C code and is decremented when
690        // [`Table`] goes out of scope.
691        to_result(unsafe { bindings::dev_pm_opp_of_cpumask_add_table(cpumask.as_raw()) })?;
692
693        // Fetch the newly created table.
694        let mut table = Self::from_dev(dev)?;
695        table.cpus = Some(CpumaskVar::try_clone(cpumask)?);
696
697        Ok(table)
698    }
699
700    /// Remove device tree based [`Table`] for a [`Cpumask`].
701    #[cfg(CONFIG_OF)]
702    #[inline]
703    fn remove_of_cpumask(&self, cpumask: &Cpumask) {
704        // SAFETY: The cpumask is valid and we took the reference from [`from_of_cpumask`] earlier,
705        // it is safe to drop the same now.
706        unsafe { bindings::dev_pm_opp_of_cpumask_remove_table(cpumask.as_raw()) };
707    }
708
709    /// Returns the number of [`OPP`]s in the [`Table`].
710    pub fn opp_count(&self) -> Result<u32> {
711        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
712        // requirements.
713        let ret = unsafe { bindings::dev_pm_opp_get_opp_count(self.dev.as_raw()) };
714
715        to_result(ret).map(|()| ret as u32)
716    }
717
718    /// Returns max clock latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
719    #[inline]
720    pub fn max_clock_latency_ns(&self) -> usize {
721        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
722        // requirements.
723        unsafe { bindings::dev_pm_opp_get_max_clock_latency(self.dev.as_raw()) }
724    }
725
726    /// Returns max volt latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
727    #[inline]
728    pub fn max_volt_latency_ns(&self) -> usize {
729        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
730        // requirements.
731        unsafe { bindings::dev_pm_opp_get_max_volt_latency(self.dev.as_raw()) }
732    }
733
734    /// Returns max transition latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
735    #[inline]
736    pub fn max_transition_latency_ns(&self) -> usize {
737        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
738        // requirements.
739        unsafe { bindings::dev_pm_opp_get_max_transition_latency(self.dev.as_raw()) }
740    }
741
742    /// Returns the suspend [`OPP`]'s frequency.
743    #[inline]
744    pub fn suspend_freq(&self) -> Hertz {
745        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
746        // requirements.
747        Hertz(unsafe { bindings::dev_pm_opp_get_suspend_opp_freq(self.dev.as_raw()) })
748    }
749
750    /// Synchronizes regulators used by the [`Table`].
751    #[inline]
752    pub fn sync_regulators(&self) -> Result {
753        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
754        // requirements.
755        to_result(unsafe { bindings::dev_pm_opp_sync_regulators(self.dev.as_raw()) })
756    }
757
758    /// Gets sharing CPUs.
759    #[inline]
760    pub fn sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
761        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
762        // requirements.
763        to_result(unsafe { bindings::dev_pm_opp_get_sharing_cpus(dev.as_raw(), cpumask.as_raw()) })
764    }
765
766    /// Sets sharing CPUs.
767    pub fn set_sharing_cpus(&mut self, cpumask: &mut Cpumask) -> Result {
768        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
769        // requirements.
770        to_result(unsafe {
771            bindings::dev_pm_opp_set_sharing_cpus(self.dev.as_raw(), cpumask.as_raw())
772        })?;
773
774        if let Some(mask) = self.cpus.as_mut() {
775            // Update the cpumask as this will be used while removing the table.
776            cpumask.copy(mask);
777        }
778
779        Ok(())
780    }
781
782    /// Gets sharing CPUs from device tree.
783    #[cfg(CONFIG_OF)]
784    #[inline]
785    pub fn of_sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
786        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
787        // requirements.
788        to_result(unsafe {
789            bindings::dev_pm_opp_of_get_sharing_cpus(dev.as_raw(), cpumask.as_raw())
790        })
791    }
792
793    /// Updates the voltage value for an [`OPP`].
794    #[inline]
795    pub fn adjust_voltage(
796        &self,
797        freq: Hertz,
798        volt: MicroVolt,
799        volt_min: MicroVolt,
800        volt_max: MicroVolt,
801    ) -> Result {
802        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
803        // requirements.
804        to_result(unsafe {
805            bindings::dev_pm_opp_adjust_voltage(
806                self.dev.as_raw(),
807                freq.into(),
808                volt.into(),
809                volt_min.into(),
810                volt_max.into(),
811            )
812        })
813    }
814
815    /// Creates [`FreqTable`] from [`Table`].
816    #[cfg(CONFIG_CPU_FREQ)]
817    #[inline]
818    pub fn cpufreq_table(&mut self) -> Result<FreqTable> {
819        FreqTable::new(self)
820    }
821
822    /// Configures device with [`OPP`] matching the frequency value.
823    #[inline]
824    pub fn set_rate(&self, freq: Hertz) -> Result {
825        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
826        // requirements.
827        to_result(unsafe { bindings::dev_pm_opp_set_rate(self.dev.as_raw(), freq.into()) })
828    }
829
830    /// Configures device with [`OPP`].
831    #[inline]
832    pub fn set_opp(&self, opp: &OPP) -> Result {
833        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
834        // requirements.
835        to_result(unsafe { bindings::dev_pm_opp_set_opp(self.dev.as_raw(), opp.as_raw()) })
836    }
837
838    /// Finds [`OPP`] based on frequency.
839    pub fn opp_from_freq(
840        &self,
841        freq: Hertz,
842        available: Option<bool>,
843        index: Option<u32>,
844        stype: SearchType,
845    ) -> Result<ARef<OPP>> {
846        let raw_dev = self.dev.as_raw();
847        let index = index.unwrap_or(0);
848        let mut rate = freq.into();
849
850        let ptr = from_err_ptr(match stype {
851            SearchType::Exact => {
852                if let Some(available) = available {
853                    // SAFETY: The requirements are satisfied by the existence of [`Device`] and
854                    // its safety requirements. The returned pointer will be owned by the new
855                    // [`OPP`] instance.
856                    unsafe {
857                        bindings::dev_pm_opp_find_freq_exact_indexed(
858                            raw_dev, rate, index, available,
859                        )
860                    }
861                } else {
862                    return Err(EINVAL);
863                }
864            }
865
866            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
867            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
868            SearchType::Ceil => unsafe {
869                bindings::dev_pm_opp_find_freq_ceil_indexed(raw_dev, &mut rate, index)
870            },
871
872            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
873            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
874            SearchType::Floor => unsafe {
875                bindings::dev_pm_opp_find_freq_floor_indexed(raw_dev, &mut rate, index)
876            },
877        })?;
878
879        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
880        unsafe { OPP::from_raw_opp_owned(ptr) }
881    }
882
883    /// Finds [`OPP`] based on level.
884    pub fn opp_from_level(&self, mut level: u32, stype: SearchType) -> Result<ARef<OPP>> {
885        let raw_dev = self.dev.as_raw();
886
887        let ptr = from_err_ptr(match stype {
888            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
889            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
890            SearchType::Exact => unsafe { bindings::dev_pm_opp_find_level_exact(raw_dev, level) },
891
892            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
893            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
894            SearchType::Ceil => unsafe {
895                bindings::dev_pm_opp_find_level_ceil(raw_dev, &mut level)
896            },
897
898            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
899            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
900            SearchType::Floor => unsafe {
901                bindings::dev_pm_opp_find_level_floor(raw_dev, &mut level)
902            },
903        })?;
904
905        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
906        unsafe { OPP::from_raw_opp_owned(ptr) }
907    }
908
909    /// Finds [`OPP`] based on bandwidth.
910    pub fn opp_from_bw(&self, mut bw: u32, index: i32, stype: SearchType) -> Result<ARef<OPP>> {
911        let raw_dev = self.dev.as_raw();
912
913        let ptr = from_err_ptr(match stype {
914            // The OPP core doesn't support this yet.
915            SearchType::Exact => return Err(EINVAL),
916
917            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
918            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
919            SearchType::Ceil => unsafe {
920                bindings::dev_pm_opp_find_bw_ceil(raw_dev, &mut bw, index)
921            },
922
923            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
924            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
925            SearchType::Floor => unsafe {
926                bindings::dev_pm_opp_find_bw_floor(raw_dev, &mut bw, index)
927            },
928        })?;
929
930        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
931        unsafe { OPP::from_raw_opp_owned(ptr) }
932    }
933
934    /// Enables the [`OPP`].
935    #[inline]
936    pub fn enable_opp(&self, freq: Hertz) -> Result {
937        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
938        // requirements.
939        to_result(unsafe { bindings::dev_pm_opp_enable(self.dev.as_raw(), freq.into()) })
940    }
941
942    /// Disables the [`OPP`].
943    #[inline]
944    pub fn disable_opp(&self, freq: Hertz) -> Result {
945        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
946        // requirements.
947        to_result(unsafe { bindings::dev_pm_opp_disable(self.dev.as_raw(), freq.into()) })
948    }
949
950    /// Registers with the Energy model.
951    #[cfg(CONFIG_OF)]
952    pub fn of_register_em(&mut self, cpumask: &mut Cpumask) -> Result {
953        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
954        // requirements.
955        to_result(unsafe {
956            bindings::dev_pm_opp_of_register_em(self.dev.as_raw(), cpumask.as_raw())
957        })?;
958
959        self.em = true;
960        Ok(())
961    }
962
963    /// Unregisters with the Energy model.
964    #[cfg(all(CONFIG_OF, CONFIG_ENERGY_MODEL))]
965    #[inline]
966    fn of_unregister_em(&self) {
967        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
968        // requirements. We registered with the EM framework earlier, it is safe to unregister now.
969        unsafe { bindings::em_dev_unregister_perf_domain(self.dev.as_raw()) };
970    }
971}
972
973impl Drop for Table {
974    fn drop(&mut self) {
975        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe
976        // to relinquish it now.
977        unsafe { bindings::dev_pm_opp_put_opp_table(self.ptr) };
978
979        #[cfg(CONFIG_OF)]
980        {
981            #[cfg(CONFIG_ENERGY_MODEL)]
982            if self.em {
983                self.of_unregister_em();
984            }
985
986            if self.of {
987                self.remove_of();
988            } else if let Some(cpumask) = self.cpus.take() {
989                self.remove_of_cpumask(&cpumask);
990            }
991        }
992    }
993}
994
995/// A reference-counted Operating performance point (OPP).
996///
997/// Rust abstraction for the C `struct dev_pm_opp`.
998///
999/// # Invariants
1000///
1001/// The pointer stored in `Self` is non-null and valid for the lifetime of the [`OPP`].
1002///
1003/// Instances of this type are reference-counted. The reference count is incremented by the
1004/// `dev_pm_opp_get` function and decremented by `dev_pm_opp_put`. The Rust type `ARef<OPP>`
1005/// represents a pointer that owns a reference count on the [`OPP`].
1006///
1007/// A reference to the [`OPP`], &[`OPP`], isn't refcounted by the Rust code.
1008///
1009/// # Examples
1010///
1011/// The following example demonstrates how to get [`OPP`] corresponding to a frequency value and
1012/// configure the device with it.
1013///
1014/// ```
1015/// use kernel::clk::Hertz;
1016/// use kernel::error::Result;
1017/// use kernel::opp::{SearchType, Table};
1018///
1019/// fn configure_opp(table: &Table, freq: Hertz) -> Result {
1020///     let opp = table.opp_from_freq(freq, Some(true), None, SearchType::Exact)?;
1021///
1022///     if opp.freq(None) != freq {
1023///         return Err(EINVAL);
1024///     }
1025///
1026///     table.set_opp(&opp)
1027/// }
1028/// ```
1029#[repr(transparent)]
1030pub struct OPP(Opaque<bindings::dev_pm_opp>);
1031
1032/// SAFETY: It is okay to send the ownership of [`OPP`] across thread boundaries.
1033unsafe impl Send for OPP {}
1034
1035/// SAFETY: It is okay to access [`OPP`] through shared references from other threads because we're
1036/// either accessing properties that don't change or that are properly synchronised by C code.
1037unsafe impl Sync for OPP {}
1038
1039/// SAFETY: The type invariants guarantee that [`OPP`] is always refcounted.
1040unsafe impl AlwaysRefCounted for OPP {
1041    fn inc_ref(&self) {
1042        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
1043        unsafe { bindings::dev_pm_opp_get(self.0.get()) };
1044    }
1045
1046    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
1047        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
1048        unsafe { bindings::dev_pm_opp_put(obj.cast().as_ptr()) }
1049    }
1050}
1051
1052impl OPP {
1053    /// Creates an owned reference to a [`OPP`] from a valid pointer.
1054    ///
1055    /// The refcount is incremented by the C code and will be decremented by `dec_ref` when the
1056    /// [`ARef`] object is dropped.
1057    ///
1058    /// # Safety
1059    ///
1060    /// The caller must ensure that `ptr` is valid and the refcount of the [`OPP`] is incremented.
1061    /// The caller must also ensure that it doesn't explicitly drop the refcount of the [`OPP`], as
1062    /// the returned [`ARef`] object takes over the refcount increment on the underlying object and
1063    /// the same will be dropped along with it.
1064    pub unsafe fn from_raw_opp_owned(ptr: *mut bindings::dev_pm_opp) -> Result<ARef<Self>> {
1065        let ptr = ptr::NonNull::new(ptr).ok_or(ENODEV)?;
1066
1067        // SAFETY: The safety requirements guarantee the validity of the pointer.
1068        //
1069        // INVARIANT: The reference-count is decremented when [`OPP`] goes out of scope.
1070        Ok(unsafe { ARef::from_raw(ptr.cast()) })
1071    }
1072
1073    /// Creates a reference to a [`OPP`] from a valid pointer.
1074    ///
1075    /// The refcount is not updated by the Rust API unless the returned reference is converted to
1076    /// an [`ARef`] object.
1077    ///
1078    /// # Safety
1079    ///
1080    /// The caller must ensure that `ptr` is valid and remains valid for the duration of `'a`.
1081    #[inline]
1082    pub unsafe fn from_raw_opp<'a>(ptr: *mut bindings::dev_pm_opp) -> Result<&'a Self> {
1083        // SAFETY: The caller guarantees that the pointer is not dangling and stays valid for the
1084        // duration of 'a. The cast is okay because [`OPP`] is `repr(transparent)`.
1085        Ok(unsafe { &*ptr.cast() })
1086    }
1087
1088    #[inline]
1089    fn as_raw(&self) -> *mut bindings::dev_pm_opp {
1090        self.0.get()
1091    }
1092
1093    /// Returns the frequency of an [`OPP`].
1094    pub fn freq(&self, index: Option<u32>) -> Hertz {
1095        let index = index.unwrap_or(0);
1096
1097        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1098        // use it.
1099        Hertz(unsafe { bindings::dev_pm_opp_get_freq_indexed(self.as_raw(), index) })
1100    }
1101
1102    /// Returns the voltage of an [`OPP`].
1103    #[inline]
1104    pub fn voltage(&self) -> MicroVolt {
1105        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1106        // use it.
1107        MicroVolt(unsafe { bindings::dev_pm_opp_get_voltage(self.as_raw()) })
1108    }
1109
1110    /// Returns the level of an [`OPP`].
1111    #[inline]
1112    pub fn level(&self) -> u32 {
1113        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1114        // use it.
1115        unsafe { bindings::dev_pm_opp_get_level(self.as_raw()) }
1116    }
1117
1118    /// Returns the power of an [`OPP`].
1119    #[inline]
1120    pub fn power(&self) -> MicroWatt {
1121        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1122        // use it.
1123        MicroWatt(unsafe { bindings::dev_pm_opp_get_power(self.as_raw()) })
1124    }
1125
1126    /// Returns the required pstate of an [`OPP`].
1127    #[inline]
1128    pub fn required_pstate(&self, index: u32) -> u32 {
1129        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1130        // use it.
1131        unsafe { bindings::dev_pm_opp_get_required_pstate(self.as_raw(), index) }
1132    }
1133
1134    /// Returns true if the [`OPP`] is turbo.
1135    #[inline]
1136    pub fn is_turbo(&self) -> bool {
1137        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1138        // use it.
1139        unsafe { bindings::dev_pm_opp_is_turbo(self.as_raw()) }
1140    }
1141}