opp.rs - source
Skip to main content 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 11 use 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.
25 mod 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)] 84 pub use freq::FreqTable ; 85 86 use core::{ marker::PhantomData , ptr }; 87 88 use macros::vtable ; 89 90 /// Creates a null-terminated slice of pointers to [`CString`]s. 91 fn 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 )] 119 pub struct MicroVolt ( pub c_ulong ); 120 121 impl 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 )] 144 pub struct MicroWatt ( pub c_ulong ); 145 146 impl 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 /// ``` 175 pub struct Token { 176 dev: ARef < Device >, 177 freq: Hertz , 178 } 179 180 impl 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 193 impl 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)] 225 pub struct Data (bindings::dev_pm_opp_data); 226 227 impl 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
The rest of this page is on the live site.