cpufreq.rs - source
Skip to main content kernel/ cpufreq.rs 1 // SPDX-License-Identifier: GPL-2.0 2 3 //! CPU frequency scaling. 4 //! 5 //! This module provides rust abstractions for interacting with the cpufreq subsystem. 6 //! 7 //! C header: [`include/linux/cpufreq.h`](srctree/include/linux/cpufreq.h) 8 //! 9 //! Reference: <https://docs.kernel.org/admin-guide/pm/cpufreq.html> 10 11 use crate ::{ 12 clk::Hertz , 13 cpu::CpuId , 14 cpumask , 15 device::{ Bound , Device }, 16 devres , 17 error::{ 18 code :: * , 19 from_result , 20 to_result , 21 Result , 22 VTABLE_DEFAULT_ERROR , // 23 }, 24 ffi::{ c_char , c_ulong }, 25 prelude :: * , 26 types::ForeignOwnable , 27 types::Opaque , 28 }; 29 30 #[cfg(CONFIG_COMMON_CLK)] 31 use crate ::clk::Clk ; 32 33 use core::{ 34 cell::UnsafeCell , 35 marker::PhantomData , 36 ops::{ Deref , DerefMut }, 37 pin::Pin , 38 ptr::{ 39 self , 40 NonNull , // 41 }, 42 }; 43 44 use macros::vtable ; 45 46 /// Maximum length of CPU frequency driver's name.
47 const CPUFREQ_NAME_LEN: usize = bindings::CPUFREQ_NAME_LEN as usize ; 48 49 /// Default transition latency value in nanoseconds. 50 pub const DEFAULT_TRANSITION_LATENCY_NS : u32 = bindings::CPUFREQ_DEFAULT_TRANSITION_LATENCY_NS; 51 52 /// CPU frequency driver flags. 53 pub mod flags { 54 /// Driver needs to update internal limits even if frequency remains unchanged. 55 pub const NEED_UPDATE_LIMITS : u16 = 1 << 0 ; 56 57 /// Platform where constants like `loops_per_jiffy` are unaffected by frequency changes.
58 pub const CONST_LOOPS : u16 = 1 << 1 ; 59 60 /// Register driver as a thermal cooling device automatically. 61 pub const IS_COOLING_DEV : u16 = 1 << 2 ; 62 63 /// Supports multiple clock domains with per-policy governors in `cpu/cpuN/cpufreq/`. 64 pub const HAVE_GOVERNOR_PER_POLICY : u16 = 1 << 3 ; 65 66 /// Allows post-change notifications outside of the `target()` routine. 67 pub const ASYNC_NOTIFICATION : u16 = 1 << 4 ; 68 69 /// Ensure CPU starts at a valid frequency from the driver's freq-table.
70 pub const NEED_INITIAL_FREQ_CHECK : u16 = 1 << 5 ; 71 72 /// Disallow governors with `dynamic_switching` capability. 73 pub const NO_AUTO_DYNAMIC_SWITCHING : u16 = 1 << 6 ; 74 } 75 76 /// Relations from the C code. 77 const CPUFREQ_RELATION_L: u32 = 0 ; 78 const CPUFREQ_RELATION_H: u32 = 1 ; 79 const CPUFREQ_RELATION_C: u32 = 2 ; 80 81 /// Can be used with any of the above values. 82 const CPUFREQ_RELATION_E: u32 = 1 << 2 ; 83 84 /// CPU frequency selection relations.
85 /// 86 /// CPU frequency selection relations, each optionally marked as "efficient". 87 #[derive( Copy , Clone , Debug , Eq , PartialEq )] 88 pub enum Relation { 89 /// Select the lowest frequency at or above target. 90 Low( bool ), 91 /// Select the highest frequency below or at target. 92 High( bool ), 93 /// Select the closest frequency to the target. 94 Close( bool ), 95 } 96 97 impl Relation { 98 // Construct from a C-compatible `u32` value.
99 fn new(val: u32 ) -> Result < Self > { 100 let efficient = val & CPUFREQ_RELATION_E != 0 ; 101 102 Ok ( match val & ! CPUFREQ_RELATION_E { 103 CPUFREQ_RELATION_L => Self :: Low ( efficient ), 104 CPUFREQ_RELATION_H => Self :: High ( efficient ), 105 CPUFREQ_RELATION_C => Self :: Close ( efficient ), 106 _ => return Err ( EINVAL ), 107 }) 108 } 109 } 110 111 impl From < Relation > for u32 { 112 // Convert to a C-compatible `u32` value.
113 fn from(rel: Relation ) -> Self { 114 let ( mut val, efficient) = match rel { 115 Relation:: Low (e) => ( CPUFREQ_RELATION_L , e ), 116 Relation:: High (e) => ( CPUFREQ_RELATION_H , e ), 117 Relation:: Close (e) => ( CPUFREQ_RELATION_C , e ), 118 }; 119 120 if efficient { 121 val |= CPUFREQ_RELATION_E ; 122 } 123 124 val 125 } 126 } 127 128 /// Policy data. 129 /// 130 /// Rust abstraction for the C `struct cpufreq_policy_data`.
131 /// 132 /// # Invariants 133 /// 134 /// A [`PolicyData`] instance always corresponds to a valid C `struct cpufreq_policy_data`. 135 /// 136 /// The callers must ensure that the `struct cpufreq_policy_data` is valid for access and remains 137 /// valid for the lifetime of the returned reference. 138 #[repr(transparent)] 139 pub struct PolicyData ( Opaque <bindings::cpufreq_policy_data>); 140 141 impl PolicyData { 142 /// Creates a mutable reference to an existing `struct cpufreq_policy_data` pointer.
143 /// 144 /// # Safety 145 /// 146 /// The caller must ensure that `ptr` is valid for writing and remains valid for the lifetime 147 /// of the returned reference. 148 #[inline] 149 pub unsafe fn from_raw_mut< 'a >(ptr: *mut bindings::cpufreq_policy_data) -> & 'a mut Self { 150 // SAFETY: Guaranteed by the safety requirements of the function. 151 // 152 // INVARIANT: The caller ensures that `ptr` is valid for writing and remains valid for the 153 // lifetime of the returned reference.
154 unsafe { &mut * ptr . cast () } 155 } 156 157 /// Returns a raw pointer to the underlying C `cpufreq_policy_data`. 158 #[inline] 159 pub fn as_raw( & self ) -> *mut bindings::cpufreq_policy_data { 160 let this: *const Self = self ; 161 this . cast_mut (). cast () 162 } 163 164 /// Wrapper for `cpufreq_generic_frequency_table_verify`. 165 #[inline] 166 pub fn generic_verify( & self ) -> Result { 167 // SAFETY: By the type invariant, the pointer stored in `self` is valid.
168 to_result ( unsafe { bindings::cpufreq_generic_frequency_table_verify( self . as_raw ()) }) 169 } 170 } 171 172 /// The frequency table index. 173 /// 174 /// Represents index with a frequency table. 175 /// 176 /// # Invariants 177 /// 178 /// The index must correspond to a valid entry in the [`Table`] it is used for. 179 #[derive( Copy , Clone , PartialEq , Eq , Debug )] 180 pub struct TableIndex ( usize ); 181 182 impl TableIndex { 183 /// Creates an instance of [`TableIndex`].
184 /// 185 /// # Safety 186 /// 187 /// The caller must ensure that `index` correspond to a valid entry in the [`Table`] it is used 188 /// for. 189 pub unsafe fn new(index: usize ) -> Self { 190 // INVARIANT: The caller ensures that `index` correspond to a valid entry in the [`Table`]. 191 Self ( index ) 192 } 193 } 194 195 impl From < TableIndex > for usize { 196 #[inline] 197 fn from(index: TableIndex ) -> Self { 198 index .
0 199 } 200 } 201 202 /// CPU frequency table. 203 /// 204 /// Rust abstraction for the C `struct cpufreq_frequency_table`. 205 /// 206 /// # Invariants 207 /// 208 /// A [`Table`] instance always corresponds to a valid C `struct cpufreq_frequency_table`. 209 /// 210 /// The callers must ensure that the `struct cpufreq_frequency_table` is valid for access and 211 /// remains valid for the lifetime of the returned reference.
212 /// 213 /// # Examples 214 /// 215 /// The following example demonstrates how to read a frequency value from [`Table`]. 216 /// 217 /// ``` 218 /// use kernel::cpufreq::{Policy, TableIndex}; 219 /// 220 /// fn show_freq(policy: &Policy) -> Result { 221 /// let table = policy.freq_table()?; 222 /// 223 /// // SAFETY: Index is a valid entry in the table. 224 /// let index = unsafe { TableIndex::new(0) }; 225 /// 226 /// pr_info!("The frequency at index 0 is: {:?}\n", table.freq(index)?); 227 /// pr_info!("The flags at index 0 is: {}\n", table.flags(index)); 228 /// pr_info!("The data at index 0 is: {}\n", table.data(index)); 229 /// Ok(()) 230 /// } 231 /// ``` 232 #[repr(transparent)] 233 pub struct Table ( Opaque <bindings::cpufreq_frequency_table>); 234 235 impl Table { 236 /// Creates a reference to an existing C `struct cpufreq_frequency_table` pointer.
237 /// 238 /// # Safety 239 /// 240 /// The caller must ensure that `ptr` is valid for reading and remains valid for the lifetime 241 /// of the returned reference. 242 #[inline] 243 pub unsafe fn from_raw< 'a >(ptr: *const bindings::cpufreq_frequency_table) -> & 'a Self { 244 // SAFETY: Guaranteed by the safety requirements of the function. 245 // 246 // INVARIANT: The caller ensures that `ptr` is valid for reading and remains valid for the 247 // lifetime of the returned refer
The rest of this page is on the live site.