Re: [PATCH V9 11/17] rust: opp: Add abstractions for the OPP table

[Yury Norov <yury.norov@gmail.com>]

On Fri, Apr 11, 2025 at 04:25:10PM +0530, Viresh Kumar wrote:
> Introduce Rust abstractions for `struct opp_table`, enabling access to
> OPP tables from Rust.
> 
> Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
> ---
>  rust/kernel/opp.rs | 495 ++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 494 insertions(+), 1 deletion(-)
> 
> diff --git a/rust/kernel/opp.rs b/rust/kernel/opp.rs
> index e4780b41664f..e074009e4b7a 100644
> --- a/rust/kernel/opp.rs
> +++ b/rust/kernel/opp.rs
> @@ -11,8 +11,9 @@
>  use crate::{
>      bindings,
>      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},
>  };
> @@ -172,6 +173,477 @@ 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>,
> +    em: bool,
> +    of: bool,
> +    cpumask_box: Option<CpumaskVar>,

The other fields have short names. Maybe just 'cpus' instead of
cpumask_box? If you want to put the type of variable into the name, it
should be a cpumask_var.

> +}