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_char, 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 c_char>> {
  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_char_ptr(), 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_names = self.clk_names.as_deref().map(to_c_str_array).transpose()?;
 447        let regulator_names = self
 448            .regulator_names
 449            .as_deref()
 450            .map(to_c_str_array)
 451            .transpose()?;
 452
 453        let set_config = || {
 454            let clk_names = clk_names.as_ref().map_or(ptr::null(), |c| c.as_ptr());
 455            let regulator_names = regulator_names.as_ref().map_or(ptr::null(), |c| c.as_ptr());
 456
 457            let prop_name = self
 458                .prop_name
 459                .as_ref()
 460                .map_or(ptr::null(), |p| p.as_char_ptr());
 461
 462            let (supported_hw, supported_hw_count) = self
 463                .supported_hw
 464                .as_ref()
 465                .map_or((ptr::null(), 0), |hw| (hw.as_ptr(), hw.len() as u32));
 466
 467            let (required_dev, required_dev_index) = self
 468                .required_dev
 469                .as_ref()
 470                .map_or((ptr::null_mut(), 0), |(dev, idx)| (dev.as_raw(), *idx));
 471
 472            let mut config = bindings::dev_pm_opp_config {
 473                clk_names,
 474                config_clks: if T::HAS_CONFIG_CLKS {
 475                    Some(Self::config_clks)
 476                } else {
 477                    None
 478                },
 479                prop_name,
 480                regulator_names,
 481                config_regulators: if T::HAS_CONFIG_REGULATORS {
 482                    Some(Self::config_regulators)
 483                } else {
 484                    None
 485                },
 486                supported_hw,
 487                supported_hw_count,
 488
 489                required_dev,
 490                required_dev_index,
 491            };
 492
 493            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 494            // requirements. The OPP core guarantees not to access fields of [`Config`] after this
 495            // call and so we don't need to save a copy of them for future use.
 496            let ret = unsafe { bindings::dev_pm_opp_set_config(dev.as_raw(), &mut config) };
 497
 498            to_result(ret).map(|()| ConfigToken(ret))
 499        };
 500
 501        // Ensure the closure does not accidentally drop owned data; if violated, the compiler
 502        // produces E0525 with e.g.:
 503        //
 504        // ```
 505        // closure is `FnOnce` because it moves the variable `clk_names` out of its environment
 506        // ```
 507        let _: &dyn Fn() -> _ = &set_config;
 508
 509        set_config()
 510    }
 511
 512    /// Config's clk callback.
 513    ///
 514    /// SAFETY: Called from C. Inputs must be valid pointers.
 515    extern "C" fn config_clks(
 516        dev: *mut bindings::device,
 517        opp_table: *mut bindings::opp_table,
 518        opp: *mut bindings::dev_pm_opp,
 519        _data: *mut c_void,
 520        scaling_down: bool,
 521    ) -> c_int {
 522        from_result(|| {
 523            // SAFETY: 'dev' is guaranteed by the C code to be valid.
 524            let dev = unsafe { Device::get_device(dev) };
 525            T::config_clks(
 526                &dev,
 527                // SAFETY: 'opp_table' is guaranteed by the C code to be valid.
 528                &unsafe { Table::from_raw_table(opp_table, &dev) },
 529                // SAFETY: 'opp' is guaranteed by the C code to be valid.
 530                unsafe { OPP::from_raw_opp(opp)? },
 531                scaling_down,
 532            )
 533            .map(|()| 0)
 534        })
 535    }
 536
 537    /// Config's regulator callback.
 538    ///
 539    /// SAFETY: Called from C. Inputs must be valid pointers.
 540    extern "C" fn config_regulators(
 541        dev: *mut bindings::device,
 542        old_opp: *mut bindings::dev_pm_opp,
 543        new_opp: *mut bindings::dev_pm_opp,
 544        regulators: *mut *mut bindings::regulator,
 545        count: c_uint,
 546    ) -> c_int {
 547        from_result(|| {
 548            // SAFETY: 'dev' is guaranteed by the C code to be valid.
 549            let dev = unsafe { Device::get_device(dev) };
 550            T::config_regulators(
 551                &dev,
 552                // SAFETY: 'old_opp' is guaranteed by the C code to be valid.
 553                unsafe { OPP::from_raw_opp(old_opp)? },
 554                // SAFETY: 'new_opp' is guaranteed by the C code to be valid.
 555                unsafe { OPP::from_raw_opp(new_opp)? },
 556                regulators,
 557                count,
 558            )
 559            .map(|()| 0)
 560        })
 561    }
 562}
 563
 564/// A reference-counted OPP table.
 565///
 566/// Rust abstraction for the C `struct opp_table`.
 567///
 568/// # Invariants
 569///
 570/// The pointer stored in `Self` is non-null and valid for the lifetime of the [`Table`].
 571///
 572/// Instances of this type are reference-counted.
 573///
 574/// # Examples
 575///
 576/// The following example demonstrates how to get OPP [`Table`] for a [`Cpumask`] and set its
 577/// frequency.
 578///
 579/// ```
 580/// # #![cfg(CONFIG_OF)]
 581/// use kernel::clk::Hertz;
 582/// use kernel::cpumask::Cpumask;
 583/// use kernel::device::Device;
 584/// use kernel::error::Result;
 585/// use kernel::opp::Table;
 586/// use kernel::sync::aref::ARef;
 587///
 588/// fn get_table(dev: &ARef<Device>, mask: &mut Cpumask, freq: Hertz) -> Result<Table> {
 589///     let mut opp_table = Table::from_of_cpumask(dev, mask)?;
 590///
 591///     if opp_table.opp_count()? == 0 {
 592///         return Err(EINVAL);
 593///     }
 594///
 595///     pr_info!("Max transition latency is: {} ns\n", opp_table.max_transition_latency_ns());
 596///     pr_info!("Suspend frequency is: {:?}\n", opp_table.suspend_freq());
 597///
 598///     opp_table.set_rate(freq)?;
 599///     Ok(opp_table)
 600/// }
 601/// ```
 602pub struct Table {
 603    ptr: *mut bindings::opp_table,
 604    dev: ARef<Device>,
 605    #[allow(dead_code)]
 606    em: bool,
 607    #[allow(dead_code)]
 608    of: bool,
 609    cpus: Option<CpumaskVar>,
 610}
 611
 612/// SAFETY: It is okay to send ownership of [`Table`] across thread boundaries.
 613unsafe impl Send for Table {}
 614
 615/// SAFETY: It is okay to access [`Table`] through shared references from other threads because
 616/// we're either accessing properties that don't change or that are properly synchronised by C code.
 617unsafe impl Sync for Table {}
 618
 619impl Table {
 620    /// Creates a new reference-counted [`Table`] from a raw pointer.
 621    ///
 622    /// # Safety
 623    ///
 624    /// Callers must ensure that `ptr` is valid and non-null.
 625    unsafe fn from_raw_table(ptr: *mut bindings::opp_table, dev: &ARef<Device>) -> Self {
 626        // SAFETY: By the safety requirements, ptr is valid and its refcount will be incremented.
 627        //
 628        // INVARIANT: The reference-count is decremented when [`Table`] goes out of scope.
 629        unsafe { bindings::dev_pm_opp_get_opp_table_ref(ptr) };
 630
 631        Self {
 632            ptr,
 633            dev: dev.clone(),
 634            em: false,
 635            of: false,
 636            cpus: None,
 637        }
 638    }
 639
 640    /// Creates a new reference-counted [`Table`] instance for a [`Device`].
 641    pub fn from_dev(dev: &Device) -> Result<Self> {
 642        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
 643        // requirements.
 644        //
 645        // INVARIANT: The reference-count is incremented by the C code and is decremented when
 646        // [`Table`] goes out of scope.
 647        let ptr = from_err_ptr(unsafe { bindings::dev_pm_opp_get_opp_table(dev.as_raw()) })?;
 648
 649        Ok(Self {
 650            ptr,
 651            dev: dev.into(),
 652            em: false,
 653            of: false,
 654            cpus: None,
 655        })
 656    }
 657
 658    /// Creates a new reference-counted [`Table`] instance for a [`Device`] based on device tree
 659    /// entries.
 660    #[cfg(CONFIG_OF)]
 661    pub fn from_of(dev: &ARef<Device>, index: i32) -> Result<Self> {
 662        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
 663        // requirements.
 664        //
 665        // INVARIANT: The reference-count is incremented by the C code and is decremented when
 666        // [`Table`] goes out of scope.
 667        to_result(unsafe { bindings::dev_pm_opp_of_add_table_indexed(dev.as_raw(), index) })?;
 668
 669        // Get the newly created [`Table`].
 670        let mut table = Self::from_dev(dev)?;
 671        table.of = true;
 672
 673        Ok(table)
 674    }
 675
 676    /// Remove device tree based [`Table`].
 677    #[cfg(CONFIG_OF)]
 678    #[inline]
 679    fn remove_of(&self) {
 680        // SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
 681        // requirements. We took the reference from [`from_of`] earlier, it is safe to drop the
 682        // same now.
 683        unsafe { bindings::dev_pm_opp_of_remove_table(self.dev.as_raw()) };
 684    }
 685
 686    /// Creates a new reference-counted [`Table`] instance for a [`Cpumask`] based on device tree
 687    /// entries.
 688    #[cfg(CONFIG_OF)]
 689    pub fn from_of_cpumask(dev: &Device, cpumask: &mut Cpumask) -> Result<Self> {
 690        // SAFETY: The cpumask is valid and the returned pointer will be owned by the [`Table`]
 691        // instance.
 692        //
 693        // INVARIANT: The reference-count is incremented by the C code and is decremented when
 694        // [`Table`] goes out of scope.
 695        to_result(unsafe { bindings::dev_pm_opp_of_cpumask_add_table(cpumask.as_raw()) })?;
 696
 697        // Fetch the newly created table.
 698        let mut table = Self::from_dev(dev)?;
 699        table.cpus = Some(CpumaskVar::try_clone(cpumask)?);
 700
 701        Ok(table)
 702    }
 703
 704    /// Remove device tree based [`Table`] for a [`Cpumask`].
 705    #[cfg(CONFIG_OF)]
 706    #[inline]
 707    fn remove_of_cpumask(&self, cpumask: &Cpumask) {
 708        // SAFETY: The cpumask is valid and we took the reference from [`from_of_cpumask`] earlier,
 709        // it is safe to drop the same now.
 710        unsafe { bindings::dev_pm_opp_of_cpumask_remove_table(cpumask.as_raw()) };
 711    }
 712
 713    /// Returns the number of [`OPP`]s in the [`Table`].
 714    pub fn opp_count(&self) -> Result<u32> {
 715        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 716        // requirements.
 717        let ret = unsafe { bindings::dev_pm_opp_get_opp_count(self.dev.as_raw()) };
 718
 719        to_result(ret).map(|()| ret as u32)
 720    }
 721
 722    /// Returns max clock latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
 723    #[inline]
 724    pub fn max_clock_latency_ns(&self) -> usize {
 725        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 726        // requirements.
 727        unsafe { bindings::dev_pm_opp_get_max_clock_latency(self.dev.as_raw()) }
 728    }
 729
 730    /// Returns max volt latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
 731    #[inline]
 732    pub fn max_volt_latency_ns(&self) -> usize {
 733        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 734        // requirements.
 735        unsafe { bindings::dev_pm_opp_get_max_volt_latency(self.dev.as_raw()) }
 736    }
 737
 738    /// Returns max transition latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
 739    #[inline]
 740    pub fn max_transition_latency_ns(&self) -> usize {
 741        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 742        // requirements.
 743        unsafe { bindings::dev_pm_opp_get_max_transition_latency(self.dev.as_raw()) }
 744    }
 745
 746    /// Returns the suspend [`OPP`]'s frequency.
 747    #[inline]
 748    pub fn suspend_freq(&self) -> Hertz {
 749        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 750        // requirements.
 751        Hertz(unsafe { bindings::dev_pm_opp_get_suspend_opp_freq(self.dev.as_raw()) })
 752    }
 753
 754    /// Synchronizes regulators used by the [`Table`].
 755    #[inline]
 756    pub fn sync_regulators(&self) -> Result {
 757        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 758        // requirements.
 759        to_result(unsafe { bindings::dev_pm_opp_sync_regulators(self.dev.as_raw()) })
 760    }
 761
 762    /// Gets sharing CPUs.
 763    #[inline]
 764    pub fn sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
 765        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 766        // requirements.
 767        to_result(unsafe { bindings::dev_pm_opp_get_sharing_cpus(dev.as_raw(), cpumask.as_raw()) })
 768    }
 769
 770    /// Sets sharing CPUs.
 771    pub fn set_sharing_cpus(&mut self, cpumask: &mut Cpumask) -> Result {
 772        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 773        // requirements.
 774        to_result(unsafe {
 775            bindings::dev_pm_opp_set_sharing_cpus(self.dev.as_raw(), cpumask.as_raw())
 776        })?;
 777
 778        if let Some(mask) = self.cpus.as_mut() {
 779            // Update the cpumask as this will be used while removing the table.
 780            cpumask.copy(mask);
 781        }
 782
 783        Ok(())
 784    }
 785
 786    /// Gets sharing CPUs from device tree.
 787    #[cfg(CONFIG_OF)]
 788    #[inline]
 789    pub fn of_sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
 790        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 791        // requirements.
 792        to_result(unsafe {
 793            bindings::dev_pm_opp_of_get_sharing_cpus(dev.as_raw(), cpumask.as_raw())
 794        })
 795    }
 796
 797    /// Updates the voltage value for an [`OPP`].
 798    #[inline]
 799    pub fn adjust_voltage(
 800        &self,
 801        freq: Hertz,
 802        volt: MicroVolt,
 803        volt_min: MicroVolt,
 804        volt_max: MicroVolt,
 805    ) -> Result {
 806        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 807        // requirements.
 808        to_result(unsafe {
 809            bindings::dev_pm_opp_adjust_voltage(
 810                self.dev.as_raw(),
 811                freq.into(),
 812                volt.into(),
 813                volt_min.into(),
 814                volt_max.into(),
 815            )
 816        })
 817    }
 818
 819    /// Creates [`FreqTable`] from [`Table`].
 820    #[cfg(CONFIG_CPU_FREQ)]
 821    #[inline]
 822    pub fn cpufreq_table(&mut self) -> Result<FreqTable> {
 823        FreqTable::new(self)
 824    }
 825
 826    /// Configures device with [`OPP`] matching the frequency value.
 827    #[inline]
 828    pub fn set_rate(&self, freq: Hertz) -> Result {
 829        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 830        // requirements.
 831        to_result(unsafe { bindings::dev_pm_opp_set_rate(self.dev.as_raw(), freq.into()) })
 832    }
 833
 834    /// Configures device with [`OPP`].
 835    #[inline]
 836    pub fn set_opp(&self, opp: &OPP) -> Result {
 837        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 838        // requirements.
 839        to_result(unsafe { bindings::dev_pm_opp_set_opp(self.dev.as_raw(), opp.as_raw()) })
 840    }
 841
 842    /// Finds [`OPP`] based on frequency.
 843    pub fn opp_from_freq(
 844        &self,
 845        freq: Hertz,
 846        available: Option<bool>,
 847        index: Option<u32>,
 848        stype: SearchType,
 849    ) -> Result<ARef<OPP>> {
 850        let raw_dev = self.dev.as_raw();
 851        let index = index.unwrap_or(0);
 852        let mut rate = freq.into();
 853
 854        let ptr = from_err_ptr(match stype {
 855            SearchType::Exact => {
 856                if let Some(available) = available {
 857                    // SAFETY: The requirements are satisfied by the existence of [`Device`] and
 858                    // its safety requirements. The returned pointer will be owned by the new
 859                    // [`OPP`] instance.
 860                    unsafe {
 861                        bindings::dev_pm_opp_find_freq_exact_indexed(
 862                            raw_dev, rate, index, available,
 863                        )
 864                    }
 865                } else {
 866                    return Err(EINVAL);
 867                }
 868            }
 869
 870            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 871            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 872            SearchType::Ceil => unsafe {
 873                bindings::dev_pm_opp_find_freq_ceil_indexed(raw_dev, &mut rate, index)
 874            },
 875
 876            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 877            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 878            SearchType::Floor => unsafe {
 879                bindings::dev_pm_opp_find_freq_floor_indexed(raw_dev, &mut rate, index)
 880            },
 881        })?;
 882
 883        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
 884        unsafe { OPP::from_raw_opp_owned(ptr) }
 885    }
 886
 887    /// Finds [`OPP`] based on level.
 888    pub fn opp_from_level(&self, mut level: u32, stype: SearchType) -> Result<ARef<OPP>> {
 889        let raw_dev = self.dev.as_raw();
 890
 891        let ptr = from_err_ptr(match stype {
 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::Exact => unsafe { bindings::dev_pm_opp_find_level_exact(raw_dev, level) },
 895
 896            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 897            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 898            SearchType::Ceil => unsafe {
 899                bindings::dev_pm_opp_find_level_ceil(raw_dev, &mut level)
 900            },
 901
 902            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 903            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 904            SearchType::Floor => unsafe {
 905                bindings::dev_pm_opp_find_level_floor(raw_dev, &mut level)
 906            },
 907        })?;
 908
 909        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
 910        unsafe { OPP::from_raw_opp_owned(ptr) }
 911    }
 912
 913    /// Finds [`OPP`] based on bandwidth.
 914    pub fn opp_from_bw(&self, mut bw: u32, index: i32, stype: SearchType) -> Result<ARef<OPP>> {
 915        let raw_dev = self.dev.as_raw();
 916
 917        let ptr = from_err_ptr(match stype {
 918            // The OPP core doesn't support this yet.
 919            SearchType::Exact => return Err(EINVAL),
 920
 921            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 922            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 923            SearchType::Ceil => unsafe {
 924                bindings::dev_pm_opp_find_bw_ceil(raw_dev, &mut bw, index)
 925            },
 926
 927            // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 928            // requirements. The returned pointer will be owned by the new [`OPP`] instance.
 929            SearchType::Floor => unsafe {
 930                bindings::dev_pm_opp_find_bw_floor(raw_dev, &mut bw, index)
 931            },
 932        })?;
 933
 934        // SAFETY: The `ptr` is guaranteed by the C code to be valid.
 935        unsafe { OPP::from_raw_opp_owned(ptr) }
 936    }
 937
 938    /// Enables the [`OPP`].
 939    #[inline]
 940    pub fn enable_opp(&self, freq: Hertz) -> Result {
 941        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 942        // requirements.
 943        to_result(unsafe { bindings::dev_pm_opp_enable(self.dev.as_raw(), freq.into()) })
 944    }
 945
 946    /// Disables the [`OPP`].
 947    #[inline]
 948    pub fn disable_opp(&self, freq: Hertz) -> Result {
 949        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 950        // requirements.
 951        to_result(unsafe { bindings::dev_pm_opp_disable(self.dev.as_raw(), freq.into()) })
 952    }
 953
 954    /// Registers with the Energy model.
 955    #[cfg(CONFIG_OF)]
 956    pub fn of_register_em(&mut self, cpumask: &mut Cpumask) -> Result {
 957        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 958        // requirements.
 959        to_result(unsafe {
 960            bindings::dev_pm_opp_of_register_em(self.dev.as_raw(), cpumask.as_raw())
 961        })?;
 962
 963        self.em = true;
 964        Ok(())
 965    }
 966
 967    /// Unregisters with the Energy model.
 968    #[cfg(all(CONFIG_OF, CONFIG_ENERGY_MODEL))]
 969    #[inline]
 970    fn of_unregister_em(&self) {
 971        // SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
 972        // requirements. We registered with the EM framework earlier, it is safe to unregister now.
 973        unsafe { bindings::em_dev_unregister_perf_domain(self.dev.as_raw()) };
 974    }
 975}
 976
 977impl Drop for Table {
 978    fn drop(&mut self) {
 979        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe
 980        // to relinquish it now.
 981        unsafe { bindings::dev_pm_opp_put_opp_table(self.ptr) };
 982
 983        #[cfg(CONFIG_OF)]
 984        {
 985            #[cfg(CONFIG_ENERGY_MODEL)]
 986            if self.em {
 987                self.of_unregister_em();
 988            }
 989
 990            if self.of {
 991                self.remove_of();
 992            } else if let Some(cpumask) = self.cpus.take() {
 993                self.remove_of_cpumask(&cpumask);
 994            }
 995        }
 996    }
 997}
 998
 999/// A reference-counted Operating performance point (OPP).
1000///
1001/// Rust abstraction for the C `struct dev_pm_opp`.
1002///
1003/// # Invariants
1004///
1005/// The pointer stored in `Self` is non-null and valid for the lifetime of the [`OPP`].
1006///
1007/// Instances of this type are reference-counted. The reference count is incremented by the
1008/// `dev_pm_opp_get` function and decremented by `dev_pm_opp_put`. The Rust type `ARef<OPP>`
1009/// represents a pointer that owns a reference count on the [`OPP`].
1010///
1011/// A reference to the [`OPP`], &[`OPP`], isn't refcounted by the Rust code.
1012///
1013/// # Examples
1014///
1015/// The following example demonstrates how to get [`OPP`] corresponding to a frequency value and
1016/// configure the device with it.
1017///
1018/// ```
1019/// use kernel::clk::Hertz;
1020/// use kernel::error::Result;
1021/// use kernel::opp::{SearchType, Table};
1022///
1023/// fn configure_opp(table: &Table, freq: Hertz) -> Result {
1024///     let opp = table.opp_from_freq(freq, Some(true), None, SearchType::Exact)?;
1025///
1026///     if opp.freq(None) != freq {
1027///         return Err(EINVAL);
1028///     }
1029///
1030///     table.set_opp(&opp)
1031/// }
1032/// ```
1033#[repr(transparent)]
1034pub struct OPP(Opaque<bindings::dev_pm_opp>);
1035
1036/// SAFETY: It is okay to send the ownership of [`OPP`] across thread boundaries.
1037unsafe impl Send for OPP {}
1038
1039/// SAFETY: It is okay to access [`OPP`] through shared references from other threads because we're
1040/// either accessing properties that don't change or that are properly synchronised by C code.
1041unsafe impl Sync for OPP {}
1042
1043/// SAFETY: The type invariants guarantee that [`OPP`] is always refcounted.
1044unsafe impl AlwaysRefCounted for OPP {
1045    fn inc_ref(&self) {
1046        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
1047        unsafe { bindings::dev_pm_opp_get(self.0.get()) };
1048    }
1049
1050    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
1051        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
1052        unsafe { bindings::dev_pm_opp_put(obj.cast().as_ptr()) }
1053    }
1054}
1055
1056impl OPP {
1057    /// Creates an owned reference to a [`OPP`] from a valid pointer.
1058    ///
1059    /// The refcount is incremented by the C code and will be decremented by `dec_ref` when the
1060    /// [`ARef`] object is dropped.
1061    ///
1062    /// # Safety
1063    ///
1064    /// The caller must ensure that `ptr` is valid and the refcount of the [`OPP`] is incremented.
1065    /// The caller must also ensure that it doesn't explicitly drop the refcount of the [`OPP`], as
1066    /// the returned [`ARef`] object takes over the refcount increment on the underlying object and
1067    /// the same will be dropped along with it.
1068    pub unsafe fn from_raw_opp_owned(ptr: *mut bindings::dev_pm_opp) -> Result<ARef<Self>> {
1069        let ptr = ptr::NonNull::new(ptr).ok_or(ENODEV)?;
1070
1071        // SAFETY: The safety requirements guarantee the validity of the pointer.
1072        //
1073        // INVARIANT: The reference-count is decremented when [`OPP`] goes out of scope.
1074        Ok(unsafe { ARef::from_raw(ptr.cast()) })
1075    }
1076
1077    /// Creates a reference to a [`OPP`] from a valid pointer.
1078    ///
1079    /// The refcount is not updated by the Rust API unless the returned reference is converted to
1080    /// an [`ARef`] object.
1081    ///
1082    /// # Safety
1083    ///
1084    /// The caller must ensure that `ptr` is valid and remains valid for the duration of `'a`.
1085    #[inline]
1086    pub unsafe fn from_raw_opp<'a>(ptr: *mut bindings::dev_pm_opp) -> Result<&'a Self> {
1087        // SAFETY: The caller guarantees that the pointer is not dangling and stays valid for the
1088        // duration of 'a. The cast is okay because [`OPP`] is `repr(transparent)`.
1089        Ok(unsafe { &*ptr.cast() })
1090    }
1091
1092    #[inline]
1093    fn as_raw(&self) -> *mut bindings::dev_pm_opp {
1094        self.0.get()
1095    }
1096
1097    /// Returns the frequency of an [`OPP`].
1098    pub fn freq(&self, index: Option<u32>) -> Hertz {
1099        let index = index.unwrap_or(0);
1100
1101        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1102        // use it.
1103        Hertz(unsafe { bindings::dev_pm_opp_get_freq_indexed(self.as_raw(), index) })
1104    }
1105
1106    /// Returns the voltage of an [`OPP`].
1107    #[inline]
1108    pub fn voltage(&self) -> MicroVolt {
1109        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1110        // use it.
1111        MicroVolt(unsafe { bindings::dev_pm_opp_get_voltage(self.as_raw()) })
1112    }
1113
1114    /// Returns the level of an [`OPP`].
1115    #[inline]
1116    pub fn level(&self) -> u32 {
1117        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1118        // use it.
1119        unsafe { bindings::dev_pm_opp_get_level(self.as_raw()) }
1120    }
1121
1122    /// Returns the power of an [`OPP`].
1123    #[inline]
1124    pub fn power(&self) -> MicroWatt {
1125        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1126        // use it.
1127        MicroWatt(unsafe { bindings::dev_pm_opp_get_power(self.as_raw()) })
1128    }
1129
1130    /// Returns the required pstate of an [`OPP`].
1131    #[inline]
1132    pub fn required_pstate(&self, index: u32) -> u32 {
1133        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1134        // use it.
1135        unsafe { bindings::dev_pm_opp_get_required_pstate(self.as_raw(), index) }
1136    }
1137
1138    /// Returns true if the [`OPP`] is turbo.
1139    #[inline]
1140    pub fn is_turbo(&self) -> bool {
1141        // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1142        // use it.
1143        unsafe { bindings::dev_pm_opp_is_turbo(self.as_raw()) }
1144    }
1145}