torvalds/linux
3
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-03-29 02:37:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

rust: opp: Add abstractions for the OPP table

Browse Source 
Introduce Rust abstractions for `struct opp_table`, enabling access to
OPP tables from Rust.

Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
This commit is contained in:
Viresh Kumar
2023-12-18 11:15:13 +05:30
parent 8f835497b3
commit d52c7e868f
1 changed files with 486 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

487
rust/kernel/opp.rs
View File

@@ -10,8 +10,9 @@
use crate::{
clk::Hertz,
cpumask::{Cpumask, CpumaskVar},
device::Device,
error::{code::*, to_result, Result},
error::{code::*, from_err_ptr, to_result, Error, Result},
ffi::c_ulong,
types::{ARef, AlwaysRefCounted, Opaque},
};
@@ -171,6 +172,469 @@ impl Data {
}
}
/// [`OPP`] search options.
///
/// ## Examples
///
/// Defines how to search for an [`OPP`] in a [`Table`] relative to a frequency.
///
/// ```
/// use kernel::clk::Hertz;
/// use kernel::error::Result;
/// use kernel::opp::{OPP, SearchType, Table};
/// use kernel::types::ARef;
///
/// fn find_opp(table: &Table, freq: Hertz) -> Result<ARef<OPP>> {
/// let opp = table.opp_from_freq(freq, Some(true), None, SearchType::Exact)?;
///
/// pr_info!("OPP frequency is: {:?}\n", opp.freq(None));
/// pr_info!("OPP voltage is: {:?}\n", opp.voltage());
/// pr_info!("OPP level is: {}\n", opp.level());
/// pr_info!("OPP power is: {:?}\n", opp.power());
///
/// Ok(opp)
/// }
/// ```
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum SearchType {
/// Match the exact frequency.
Exact,
/// Find the highest frequency less than or equal to the given value.
Floor,
/// Find the lowest frequency greater than or equal to the given value.
Ceil,
}
/// A reference-counted OPP table.
///
/// Rust abstraction for the C `struct opp_table`.
///
/// # Invariants
///
/// The pointer stored in `Self` is non-null and valid for the lifetime of the [`Table`].
///
/// Instances of this type are reference-counted.
///
/// ## Examples
///
/// The following example demonstrates how to get OPP [`Table`] for a [`Cpumask`] and set its
/// frequency.
///
/// ```
/// use kernel::clk::Hertz;
/// use kernel::cpumask::Cpumask;
/// use kernel::device::Device;
/// use kernel::error::Result;
/// use kernel::opp::Table;
/// use kernel::types::ARef;
///
/// fn get_table(dev: &ARef<Device>, mask: &mut Cpumask, freq: Hertz) -> Result<Table> {
/// let mut opp_table = Table::from_of_cpumask(dev, mask)?;
///
/// if opp_table.opp_count()? == 0 {
/// return Err(EINVAL);
/// }
///
/// pr_info!("Max transition latency is: {} ns\n", opp_table.max_transition_latency_ns());
/// pr_info!("Suspend frequency is: {:?}\n", opp_table.suspend_freq());
///
/// opp_table.set_rate(freq)?;
/// Ok(opp_table)
/// }
/// ```
pub struct Table {
ptr: *mut bindings::opp_table,
dev: ARef<Device>,
#[allow(dead_code)]
em: bool,
#[allow(dead_code)]
of: bool,
cpus: Option<CpumaskVar>,
}
/// SAFETY: It is okay to send ownership of [`Table`] across thread boundaries.
unsafe impl Send for Table {}
/// SAFETY: It is okay to access [`Table`] through shared references from other threads because
/// we're either accessing properties that don't change or that are properly synchronised by C code.
unsafe impl Sync for Table {}
impl Table {
/// Creates a new reference-counted [`Table`] from a raw pointer.
///
/// # Safety
///
/// Callers must ensure that `ptr` is valid and non-null.
unsafe fn from_raw_table(ptr: *mut bindings::opp_table, dev: &ARef<Device>) -> Self {
// SAFETY: By the safety requirements, ptr is valid and its refcount will be incremented.
//
// INVARIANT: The reference-count is decremented when [`Table`] goes out of scope.
unsafe { bindings::dev_pm_opp_get_opp_table_ref(ptr) };
Self {
ptr,
dev: dev.clone(),
em: false,
of: false,
cpus: None,
}
}
/// Creates a new reference-counted [`Table`] instance for a [`Device`].
pub fn from_dev(dev: &Device) -> Result<Self> {
// SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
// requirements.
//
// INVARIANT: The reference-count is incremented by the C code and is decremented when
// [`Table`] goes out of scope.
let ptr = from_err_ptr(unsafe { bindings::dev_pm_opp_get_opp_table(dev.as_raw()) })?;
Ok(Self {
ptr,
dev: dev.into(),
em: false,
of: false,
cpus: None,
})
}
/// Creates a new reference-counted [`Table`] instance for a [`Device`] based on device tree
/// entries.
#[cfg(CONFIG_OF)]
pub fn from_of(dev: &ARef<Device>, index: i32) -> Result<Self> {
// SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
// requirements.
//
// INVARIANT: The reference-count is incremented by the C code and is decremented when
// [`Table`] goes out of scope.
to_result(unsafe { bindings::dev_pm_opp_of_add_table_indexed(dev.as_raw(), index) })?;
// Get the newly created [`Table`].
let mut table = Self::from_dev(dev)?;
table.of = true;
Ok(table)
}
/// Remove device tree based [`Table`].
#[cfg(CONFIG_OF)]
#[inline]
fn remove_of(&self) {
// SAFETY: The requirements are satisfied by the existence of the [`Device`] and its safety
// requirements. We took the reference from [`from_of`] earlier, it is safe to drop the
// same now.
unsafe { bindings::dev_pm_opp_of_remove_table(self.dev.as_raw()) };
}
/// Creates a new reference-counted [`Table`] instance for a [`Cpumask`] based on device tree
/// entries.
#[cfg(CONFIG_OF)]
pub fn from_of_cpumask(dev: &Device, cpumask: &mut Cpumask) -> Result<Self> {
// SAFETY: The cpumask is valid and the returned pointer will be owned by the [`Table`]
// instance.
//
// INVARIANT: The reference-count is incremented by the C code and is decremented when
// [`Table`] goes out of scope.
to_result(unsafe { bindings::dev_pm_opp_of_cpumask_add_table(cpumask.as_raw()) })?;
// Fetch the newly created table.
let mut table = Self::from_dev(dev)?;
table.cpus = Some(CpumaskVar::try_clone(cpumask)?);
Ok(table)
}
/// Remove device tree based [`Table`] for a [`Cpumask`].
#[cfg(CONFIG_OF)]
#[inline]
fn remove_of_cpumask(&self, cpumask: &Cpumask) {
// SAFETY: The cpumask is valid and we took the reference from [`from_of_cpumask`] earlier,
// it is safe to drop the same now.
unsafe { bindings::dev_pm_opp_of_cpumask_remove_table(cpumask.as_raw()) };
}
/// Returns the number of [`OPP`]s in the [`Table`].
pub fn opp_count(&self) -> Result<u32> {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
let ret = unsafe { bindings::dev_pm_opp_get_opp_count(self.dev.as_raw()) };
if ret < 0 {
Err(Error::from_errno(ret))
} else {
Ok(ret as u32)
}
}
/// Returns max clock latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
#[inline]
pub fn max_clock_latency_ns(&self) -> usize {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
unsafe { bindings::dev_pm_opp_get_max_clock_latency(self.dev.as_raw()) }
}
/// Returns max volt latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
#[inline]
pub fn max_volt_latency_ns(&self) -> usize {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
unsafe { bindings::dev_pm_opp_get_max_volt_latency(self.dev.as_raw()) }
}
/// Returns max transition latency (in nanoseconds) of the [`OPP`]s in the [`Table`].
#[inline]
pub fn max_transition_latency_ns(&self) -> usize {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
unsafe { bindings::dev_pm_opp_get_max_transition_latency(self.dev.as_raw()) }
}
/// Returns the suspend [`OPP`]'s frequency.
#[inline]
pub fn suspend_freq(&self) -> Hertz {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
Hertz(unsafe { bindings::dev_pm_opp_get_suspend_opp_freq(self.dev.as_raw()) })
}
/// Synchronizes regulators used by the [`Table`].
#[inline]
pub fn sync_regulators(&self) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_sync_regulators(self.dev.as_raw()) })
}
/// Gets sharing CPUs.
#[inline]
pub fn sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_get_sharing_cpus(dev.as_raw(), cpumask.as_raw()) })
}
/// Sets sharing CPUs.
pub fn set_sharing_cpus(&mut self, cpumask: &mut Cpumask) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe {
bindings::dev_pm_opp_set_sharing_cpus(self.dev.as_raw(), cpumask.as_raw())
})?;
if let Some(mask) = self.cpus.as_mut() {
// Update the cpumask as this will be used while removing the table.
cpumask.copy(mask);
}
Ok(())
}
/// Gets sharing CPUs from device tree.
#[cfg(CONFIG_OF)]
#[inline]
pub fn of_sharing_cpus(dev: &Device, cpumask: &mut Cpumask) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe {
bindings::dev_pm_opp_of_get_sharing_cpus(dev.as_raw(), cpumask.as_raw())
})
}
/// Updates the voltage value for an [`OPP`].
#[inline]
pub fn adjust_voltage(
&self,
freq: Hertz,
volt: MicroVolt,
volt_min: MicroVolt,
volt_max: MicroVolt,
) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe {
bindings::dev_pm_opp_adjust_voltage(
self.dev.as_raw(),
freq.into(),
volt.into(),
volt_min.into(),
volt_max.into(),
)
})
}
/// Configures device with [`OPP`] matching the frequency value.
#[inline]
pub fn set_rate(&self, freq: Hertz) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_set_rate(self.dev.as_raw(), freq.into()) })
}
/// Configures device with [`OPP`].
#[inline]
pub fn set_opp(&self, opp: &OPP) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_set_opp(self.dev.as_raw(), opp.as_raw()) })
}
/// Finds [`OPP`] based on frequency.
pub fn opp_from_freq(
&self,
freq: Hertz,
available: Option<bool>,
index: Option<u32>,
stype: SearchType,
) -> Result<ARef<OPP>> {
let raw_dev = self.dev.as_raw();
let index = index.unwrap_or(0);
let mut rate = freq.into();
let ptr = from_err_ptr(match stype {
SearchType::Exact => {
if let Some(available) = available {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and
// its safety requirements. The returned pointer will be owned by the new
// [`OPP`] instance.
unsafe {
bindings::dev_pm_opp_find_freq_exact_indexed(
raw_dev, rate, index, available,
)
}
} else {
return Err(EINVAL);
}
}
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Ceil => unsafe {
bindings::dev_pm_opp_find_freq_ceil_indexed(raw_dev, &mut rate, index)
},
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Floor => unsafe {
bindings::dev_pm_opp_find_freq_floor_indexed(raw_dev, &mut rate, index)
},
})?;
// SAFETY: The `ptr` is guaranteed by the C code to be valid.
unsafe { OPP::from_raw_opp_owned(ptr) }
}
/// Finds [`OPP`] based on level.
pub fn opp_from_level(&self, mut level: u32, stype: SearchType) -> Result<ARef<OPP>> {
let raw_dev = self.dev.as_raw();
let ptr = from_err_ptr(match stype {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Exact => unsafe { bindings::dev_pm_opp_find_level_exact(raw_dev, level) },
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Ceil => unsafe {
bindings::dev_pm_opp_find_level_ceil(raw_dev, &mut level)
},
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Floor => unsafe {
bindings::dev_pm_opp_find_level_floor(raw_dev, &mut level)
},
})?;
// SAFETY: The `ptr` is guaranteed by the C code to be valid.
unsafe { OPP::from_raw_opp_owned(ptr) }
}
/// Finds [`OPP`] based on bandwidth.
pub fn opp_from_bw(&self, mut bw: u32, index: i32, stype: SearchType) -> Result<ARef<OPP>> {
let raw_dev = self.dev.as_raw();
let ptr = from_err_ptr(match stype {
// The OPP core doesn't support this yet.
SearchType::Exact => return Err(EINVAL),
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Ceil => unsafe {
bindings::dev_pm_opp_find_bw_ceil(raw_dev, &mut bw, index)
},
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. The returned pointer will be owned by the new [`OPP`] instance.
SearchType::Floor => unsafe {
bindings::dev_pm_opp_find_bw_floor(raw_dev, &mut bw, index)
},
})?;
// SAFETY: The `ptr` is guaranteed by the C code to be valid.
unsafe { OPP::from_raw_opp_owned(ptr) }
}
/// Enables the [`OPP`].
#[inline]
pub fn enable_opp(&self, freq: Hertz) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_enable(self.dev.as_raw(), freq.into()) })
}
/// Disables the [`OPP`].
#[inline]
pub fn disable_opp(&self, freq: Hertz) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe { bindings::dev_pm_opp_disable(self.dev.as_raw(), freq.into()) })
}
/// Registers with the Energy model.
#[cfg(CONFIG_OF)]
pub fn of_register_em(&mut self, cpumask: &mut Cpumask) -> Result {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements.
to_result(unsafe {
bindings::dev_pm_opp_of_register_em(self.dev.as_raw(), cpumask.as_raw())
})?;
self.em = true;
Ok(())
}
/// Unregisters with the Energy model.
#[cfg(all(CONFIG_OF, CONFIG_ENERGY_MODEL))]
#[inline]
fn of_unregister_em(&self) {
// SAFETY: The requirements are satisfied by the existence of [`Device`] and its safety
// requirements. We registered with the EM framework earlier, it is safe to unregister now.
unsafe { bindings::em_dev_unregister_perf_domain(self.dev.as_raw()) };
}
}
impl Drop for Table {
fn drop(&mut self) {
// SAFETY: By the type invariants, we know that `self` owns a reference, so it is safe
// to relinquish it now.
unsafe { bindings::dev_pm_opp_put_opp_table(self.ptr) };
#[cfg(CONFIG_OF)]
{
#[cfg(CONFIG_ENERGY_MODEL)]
if self.em {
self.of_unregister_em();
}
if self.of {
self.remove_of();
} else if let Some(cpumask) = self.cpus.take() {
self.remove_of_cpumask(&cpumask);
}
}
}
}
/// A reference-counted Operating performance point (OPP).
///
/// Rust abstraction for the C `struct dev_pm_opp`.
@@ -184,6 +648,27 @@ impl Data {
/// represents a pointer that owns a reference count on the [`OPP`].
///
/// A reference to the [`OPP`], &[`OPP`], isn't refcounted by the Rust code.
///
/// ## Examples
///
/// The following example demonstrates how to get [`OPP`] corresponding to a frequency value and
/// configure the device with it.
///
/// ```
/// use kernel::clk::Hertz;
/// use kernel::error::Result;
/// use kernel::opp::{SearchType, Table};
///
/// fn configure_opp(table: &Table, freq: Hertz) -> Result {
/// let opp = table.opp_from_freq(freq, Some(true), None, SearchType::Exact)?;
///
/// if opp.freq(None) != freq {
/// return Err(EINVAL);
/// }
///
/// table.set_opp(&opp)
/// }
/// ```
#[repr(transparent)]
pub struct OPP(Opaque<bindings::dev_pm_opp>);