Unverified Commit 2e0fd458 authored by Daniel Almeida's avatar Daniel Almeida Committed by Mark Brown
Browse files

rust: regulator: add devm_enable and devm_enable_optional 



A lot of drivers only care about enabling the regulator for as long as
the underlying Device is bound. This can be easily observed due to the
extensive use of `devm_regulator_get_enable` and
`devm_regulator_get_enable_optional` throughout the kernel.

Therefore, make this helper available in Rust. Also add an example
noting how it should be the default API unless the driver needs more
fine-grained control over the regulator.

Suggested-by: default avatarDanilo Krummrich <dakr@kernel.org>
Reviewed-by: default avatarBoqun Feng <boqun.feng@gmail.com>
Reviewed-by: default avatarDanilo Krummrich <dakr@kernel.org>
Reviewed-by: default avatarAlexandre Courbot <acourbot@nvidia.com>
Signed-off-by: default avatarDaniel Almeida <daniel.almeida@collabora.com>
Link: https://patch.msgid.link/20250910-regulator-remove-dynamic-v3-2-07af4dfa97cc@collabora.com


Signed-off-by: default avatarMark Brown <broonie@kernel.org>
parent b87ecbc5

rust/helpers/regulator.c

+10 −0
Original line number Diff line number Diff line
@@ -40,4 +40,14 @@ int rust_helper_regulator_is_enabled(struct regulator *regulator) 
	return regulator_is_enabled(regulator);

}



int rust_helper_devm_regulator_get_enable(struct device *dev, const char *id)

{

	return devm_regulator_get_enable(dev, id);

}



int rust_helper_devm_regulator_get_enable_optional(struct device *dev, const char *id)

{

	return devm_regulator_get_enable_optional(dev, id);

}



#endif

rust/kernel/regulator.rs

+59 −1
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ 


use crate::{

    bindings,

    device::Device,

    device::{Bound, Device},

    error::{from_err_ptr, to_result, Result},

    prelude::*,

};
@@ -69,6 +69,41 @@ pub struct Error<State: RegulatorState> { 
    /// The regulator that caused the error, so that the operation may be retried.

    pub regulator: Regulator<State>,

}

/// Obtains and enables a [`devres`]-managed regulator for a device.

///

/// This calls [`regulator_disable()`] and [`regulator_put()`] automatically on

/// driver detach.

///

/// This API is identical to `devm_regulator_get_enable()`, and should be

/// preferred over the [`Regulator<T: RegulatorState>`] API if the caller only

/// cares about the regulator being enabled.

///

/// [`devres`]: https://docs.kernel.org/driver-api/driver-model/devres.html

/// [`regulator_disable()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_disable

/// [`regulator_put()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_put

pub fn devm_enable(dev: &Device<Bound>, name: &CStr) -> Result {

    // SAFETY: `dev` is a valid and bound device, while `name` is a valid C

    // string.

    to_result(unsafe { bindings::devm_regulator_get_enable(dev.as_raw(), name.as_ptr()) })

}



/// Same as [`devm_enable`], but calls `devm_regulator_get_enable_optional`

/// instead.

///

/// This obtains and enables a [`devres`]-managed regulator for a device, but

/// does not print a message nor provides a dummy if the regulator is not found.

///

/// This calls [`regulator_disable()`] and [`regulator_put()`] automatically on

/// driver detach.

///

/// [`devres`]: https://docs.kernel.org/driver-api/driver-model/devres.html

/// [`regulator_disable()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_disable

/// [`regulator_put()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_put

pub fn devm_enable_optional(dev: &Device<Bound>, name: &CStr) -> Result {

    // SAFETY: `dev` is a valid and bound device, while `name` is a valid C

    // string.

    to_result(unsafe { bindings::devm_regulator_get_enable_optional(dev.as_raw(), name.as_ptr()) })

}



/// A `struct regulator` abstraction.

///
@@ -146,6 +181,29 @@ pub struct Error<State: RegulatorState> { 
/// }

/// ```

///

/// If a driver only cares about the regulator being on for as long it is bound

/// to a device, then it should use [`devm_enable`] or [`devm_enable_optional`].

/// This should be the default use-case unless more fine-grained control over

/// the regulator's state is required.

///

/// [`devm_enable`]: crate::regulator::devm_enable

/// [`devm_optional`]: crate::regulator::devm_enable_optional

///

/// ```

/// # use kernel::prelude::*;

/// # use kernel::c_str;

/// # use kernel::device::{Bound, Device};

/// # use kernel::regulator;

/// fn enable(dev: &Device<Bound>) -> Result {

///     // Obtain a reference to a (fictitious) regulator and enable it. This

///     // call only returns whether the operation succeeded.

///     regulator::devm_enable(dev, c_str!("vcc"))?;

///

///     // The regulator will be disabled and put when `dev` is unbound.

///     Ok(())

/// }

/// ```

///

/// ## Disabling a regulator

///

/// ```