rust: opp: Add abstractions for the OPP table (d52c7e86) · Commits · git / linux-net

rust/kernel/opp.rs

+486 −1

Original line number	Diff line number	Diff line
		@@ -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 @@ fn freq(&self) -> Hertz {
		}
		}

		/// [`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 @@ fn freq(&self) -> Hertz {
		/// 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>);