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

source code of linux/rust/kernel/opp.rs

Morty Proxy This is a proxified and sanitized view of the page, visit original site.