projects/linux·blob master · refs

1148 lines · 37.5 KiB

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 #[inline]
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 #[inline]
1052 unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
1053 // SAFETY: The safety requirements guarantee that the refcount is nonzero.
1054 unsafe { bindings::dev_pm_opp_put(obj.cast().as_ptr()) }
1055 }
1056}
1057
1058impl OPP {
1059 /// Creates an owned reference to a [`OPP`] from a valid pointer.
1060 ///
1061 /// The refcount is incremented by the C code and will be decremented by `dec_ref` when the
1062 /// [`ARef`] object is dropped.
1063 ///
1064 /// # Safety
1065 ///
1066 /// The caller must ensure that `ptr` is valid and the refcount of the [`OPP`] is incremented.
1067 /// The caller must also ensure that it doesn't explicitly drop the refcount of the [`OPP`], as
1068 /// the returned [`ARef`] object takes over the refcount increment on the underlying object and
1069 /// the same will be dropped along with it.
1070 pub unsafe fn from_raw_opp_owned(ptr: *mut bindings::dev_pm_opp) -> Result<ARef<Self>> {
1071 let ptr = ptr::NonNull::new(ptr).ok_or(ENODEV)?;
1072
1073 // SAFETY: The safety requirements guarantee the validity of the pointer.
1074 //
1075 // INVARIANT: The reference-count is decremented when [`OPP`] goes out of scope.
1076 Ok(unsafe { ARef::from_raw(ptr.cast()) })
1077 }
1078
1079 /// Creates a reference to a [`OPP`] from a valid pointer.
1080 ///
1081 /// The refcount is not updated by the Rust API unless the returned reference is converted to
1082 /// an [`ARef`] object.
1083 ///
1084 /// # Safety
1085 ///
1086 /// The caller must ensure that `ptr` is valid and remains valid for the duration of `'a`.
1087 #[inline]
1088 pub unsafe fn from_raw_opp<'a>(ptr: *mut bindings::dev_pm_opp) -> Result<&'a Self> {
1089 // SAFETY: The caller guarantees that the pointer is not dangling and stays valid for the
1090 // duration of 'a. The cast is okay because [`OPP`] is `repr(transparent)`.
1091 Ok(unsafe { &*ptr.cast() })
1092 }
1093
1094 #[inline]
1095 fn as_raw(&self) -> *mut bindings::dev_pm_opp {
1096 self.0.get()
1097 }
1098
1099 /// Returns the frequency of an [`OPP`].
1100 #[inline]
1101 pub fn freq(&self, index: Option<u32>) -> Hertz {
1102 let index = index.unwrap_or(0);
1103
1104 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1105 // use it.
1106 Hertz(unsafe { bindings::dev_pm_opp_get_freq_indexed(self.as_raw(), index) })
1107 }
1108
1109 /// Returns the voltage of an [`OPP`].
1110 #[inline]
1111 pub fn voltage(&self) -> MicroVolt {
1112 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1113 // use it.
1114 MicroVolt(unsafe { bindings::dev_pm_opp_get_voltage(self.as_raw()) })
1115 }
1116
1117 /// Returns the level of an [`OPP`].
1118 #[inline]
1119 pub fn level(&self) -> u32 {
1120 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1121 // use it.
1122 unsafe { bindings::dev_pm_opp_get_level(self.as_raw()) }
1123 }
1124
1125 /// Returns the power of an [`OPP`].
1126 #[inline]
1127 pub fn power(&self) -> MicroWatt {
1128 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1129 // use it.
1130 MicroWatt(unsafe { bindings::dev_pm_opp_get_power(self.as_raw()) })
1131 }
1132
1133 /// Returns the required pstate of an [`OPP`].
1134 #[inline]
1135 pub fn required_pstate(&self, index: u32) -> u32 {
1136 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1137 // use it.
1138 unsafe { bindings::dev_pm_opp_get_required_pstate(self.as_raw(), index) }
1139 }
1140
1141 /// Returns true if the [`OPP`] is turbo.
1142 #[inline]
1143 pub fn is_turbo(&self) -> bool {
1144 // SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe to
1145 // use it.
1146 unsafe { bindings::dev_pm_opp_is_turbo(self.as_raw()) }
1147 }
1148}