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