Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399// SPDX-License-Identifier: GPL-2.0
//! Regulator abstractions, providing a standard kernel interface to control//! voltage and current regulators.//!//! The intention is to allow systems to dynamically control regulator power//! output in order to save power and prolong battery life. This applies to both//! voltage regulators (where voltage output is controllable) and current sinks//! (where current limit is controllable).//!//! C header: [`include/linux/regulator/consumer.h`](srctree/include/linux/regulator/consumer.h)//!//! Regulators are modeled in Rust with a collection of states. Each state may//! enforce a given invariant, and they may convert between each other where applicable.//!//! See [Voltage and current regulator API](https://docs.kernel.org/driver-api/regulator.html)//! for more information.
use crate::{ bindings, device::{Bound, Device}, error::{from_err_ptr, to_result, Result}, prelude::*,};
use core::{ marker::PhantomData, mem::ManuallyDrop, //};
mod private { pub trait Sealed {}
impl Sealed for super::Enabled {} impl Sealed for super::Disabled {}}
/// A trait representing the different states a [`Regulator`] can be in.pub trait RegulatorState: private::Sealed + 'static { /// Whether the regulator should be disabled when dropped. const DISABLE_ON_DROP: bool;}
/// A state where the [`Regulator`] is known to be enabled.////// The `enable` reference count held by this state is decremented when it is/// dropped.pub struct Enabled;
/// A state where this [`Regulator`] handle has not specifically asked for the/// underlying regulator to be enabled. This means that this reference does not/// own an `enable` reference count, but the regulator may still be on.pub struct Disabled;
impl RegulatorState for Enabled { const DISABLE_ON_DROP: bool = true;}
impl RegulatorState for Disabled { const DISABLE_ON_DROP: bool = false;}
/// A trait that abstracts the ability to check if a [`Regulator`] is enabled.pub trait IsEnabled: RegulatorState {}impl IsEnabled for Disabled {}
/// An error that can occur when trying to convert a [`Regulator`] between states.pub struct Error<State: RegulatorState> { /// The error that occurred. pub error: kernel::error::Error,
/// 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_putpub 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_char_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_putpub 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_char_ptr()) })}
/// A `struct regulator` abstraction.////// # Examples////// ## Enabling a regulator////// This example uses [`Regulator<Enabled>`], which is suitable for drivers that/// enable a regulator at probe time and leave them on until the device is/// removed or otherwise shutdown.////// These users can store [`Regulator<Enabled>`] directly in their driver's/// private data struct.////// ```/// # use kernel::prelude::*;/// # use kernel::device::Device;/// # use kernel::regulator::{Voltage, Regulator, Disabled, Enabled};/// fn enable(dev: &Device, min_voltage: Voltage, max_voltage: Voltage) -> Result {/// // Obtain a reference to a (fictitious) regulator./// let regulator: Regulator<Disabled> = Regulator::<Disabled>::get(dev, c"vcc")?;////// // The voltage can be set before enabling the regulator if needed, e.g.:/// regulator.set_voltage(min_voltage, max_voltage)?;////// // The same applies for `get_voltage()`, i.e.:/// let voltage: Voltage = regulator.get_voltage()?;////// // Enables the regulator, consuming the previous value./// ///// // From now on, the regulator is known to be enabled because of the type/// // `Enabled`./// ///// // If this operation fails, the `Error` will contain the regulator/// // reference, so that the operation may be retried./// let regulator: Regulator<Enabled> =/// regulator.try_into_enabled().map_err(|error| error.error)?;////// // The voltage can also be set after enabling the regulator, e.g.:/// regulator.set_voltage(min_voltage, max_voltage)?;////// // The same applies for `get_voltage()`, i.e.:/// let voltage: Voltage = regulator.get_voltage()?;////// // Dropping an enabled regulator will disable it. The refcount will be/// // decremented./// drop(regulator);////// // ...////// Ok(())/// }/// ```////// A more concise shortcut is available for enabling a regulator. This is/// equivalent to `regulator_get_enable()`:////// ```/// # use kernel::prelude::*;/// # use kernel::device::Device;/// # use kernel::regulator::{Voltage, Regulator, Enabled};/// fn enable(dev: &Device) -> Result {/// // Obtain a reference to a (fictitious) regulator and enable it./// let regulator: Regulator<Enabled> = Regulator::<Enabled>::get(dev, c"vcc")?;////// // Dropping an enabled regulator will disable it. The refcount will be/// // decremented./// drop(regulator);////// // ...////// Ok(())/// }/// ```////// 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::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"vcc")?;////// // The regulator will be disabled and put when `dev` is unbound./// Ok(())/// }/// ```////// ## Disabling a regulator////// ```/// # use kernel::prelude::*;/// # use kernel::device::Device;/// # use kernel::regulator::{Regulator, Enabled, Disabled};/// fn disable(dev: &Device, regulator: Regulator<Enabled>) -> Result {/// // We can also disable an enabled regulator without reliquinshing our/// // refcount:/// ///// // If this operation fails, the `Error` will contain the regulator/// // reference, so that the operation may be retried./// let regulator: Regulator<Disabled> =/// regulator.try_into_disabled().map_err(|error| error.error)?;////// // The refcount will be decremented when `regulator` is dropped./// drop(regulator);////// // ...////// Ok(())/// }/// ```////// # Invariants////// - `inner` is a pointer obtained from a successful call to/// [`regulator_get()`]. It is treated as an opaque token that may only be/// accessed using C API methods (e.g., it may be `NULL` if the C API returns/// `NULL`).////// [`regulator_get()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_getpub struct Regulator<State>where State: RegulatorState,{ inner: *mut bindings::regulator, _phantom: PhantomData<State>,}
impl<T: RegulatorState> Regulator<T> { /// Sets the voltage for the regulator. /// /// This can be used to ensure that the device powers up cleanly. pub fn set_voltage(&self, min_voltage: Voltage, max_voltage: Voltage) -> Result { // SAFETY: Safe as per the type invariants of `Regulator`. to_result(unsafe { bindings::regulator_set_voltage( self.inner, min_voltage.as_microvolts(), max_voltage.as_microvolts(), ) }) }
/// Gets the current voltage of the regulator. pub fn get_voltage(&self) -> Result<Voltage> { // SAFETY: Safe as per the type invariants of `Regulator`. let voltage = unsafe { bindings::regulator_get_voltage(self.inner) };
to_result(voltage).map(|()| Voltage::from_microvolts(voltage)) }
fn get_internal(dev: &Device, name: &CStr) -> Result<Regulator<T>> { let inner = // SAFETY: It is safe to call `regulator_get()`, on a device pointer // received from the C code. from_err_ptr(unsafe { bindings::regulator_get(dev.as_raw(), name.as_char_ptr()) })?;
// INVARIANT: `inner` is a pointer obtained from `regulator_get()`, and // the call was successful. Ok(Self { inner, _phantom: PhantomData, }) }
fn enable_internal(&self) -> Result { // SAFETY: Safe as per the type invariants of `Regulator`. to_result(unsafe { bindings::regulator_enable(self.inner) }) }
fn disable_internal(&self) -> Result { // SAFETY: Safe as per the type invariants of `Regulator`. to_result(unsafe { bindings::regulator_disable(self.inner) }) }}
impl Regulator<Disabled> { /// Obtains a [`Regulator`] instance from the system. pub fn get(dev: &Device, name: &CStr) -> Result<Self> { Regulator::get_internal(dev, name) }
/// Attempts to convert the regulator to an enabled state. pub fn try_into_enabled(self) -> Result<Regulator<Enabled>, Error<Disabled>> { // We will be transferring the ownership of our `regulator_get()` count to // `Regulator<Enabled>`. let regulator = ManuallyDrop::new(self);
regulator .enable_internal() .map(|()| Regulator { inner: regulator.inner, _phantom: PhantomData, }) .map_err(|error| Error { error, regulator: ManuallyDrop::into_inner(regulator), }) }}
impl Regulator<Enabled> { /// Obtains a [`Regulator`] instance from the system and enables it. /// /// This is equivalent to calling `regulator_get_enable()` in the C API. pub fn get(dev: &Device, name: &CStr) -> Result<Self> { Regulator::<Disabled>::get_internal(dev, name)? .try_into_enabled() .map_err(|error| error.error) }
/// Attempts to convert the regulator to a disabled state. pub fn try_into_disabled(self) -> Result<Regulator<Disabled>, Error<Enabled>> { // We will be transferring the ownership of our `regulator_get()` count // to `Regulator<Disabled>`. let regulator = ManuallyDrop::new(self);
regulator .disable_internal() .map(|()| Regulator { inner: regulator.inner, _phantom: PhantomData, }) .map_err(|error| Error { error, regulator: ManuallyDrop::into_inner(regulator), }) }}
impl<T: IsEnabled> Regulator<T> { /// Checks if the regulator is enabled. pub fn is_enabled(&self) -> bool { // SAFETY: Safe as per the type invariants of `Regulator`. unsafe { bindings::regulator_is_enabled(self.inner) != 0 } }}
impl<T: RegulatorState> Drop for Regulator<T> { fn drop(&mut self) { if T::DISABLE_ON_DROP { // SAFETY: By the type invariants, we know that `self` owns a // reference on the enabled refcount, so it is safe to relinquish it // now. unsafe { bindings::regulator_disable(self.inner) }; } // SAFETY: By the type invariants, we know that `self` owns a reference, // so it is safe to relinquish it now. unsafe { bindings::regulator_put(self.inner) }; }}
// SAFETY: It is safe to send a `Regulator<T>` across threads. In particular, a// Regulator<T> can be dropped from any thread.unsafe impl<T: RegulatorState> Send for Regulator<T> {}
// SAFETY: It is safe to send a &Regulator<T> across threads because the C side// handles its own locking.unsafe impl<T: RegulatorState> Sync for Regulator<T> {}
/// A voltage.////// This type represents a voltage value in microvolts.#[repr(transparent)]#[derive(Copy, Clone, PartialEq, Eq)]pub struct Voltage(i32);
impl Voltage { /// Creates a new `Voltage` from a value in microvolts. pub fn from_microvolts(uv: i32) -> Self { Self(uv) }
/// Returns the value of the voltage in microvolts as an [`i32`]. pub fn as_microvolts(self) -> i32 { self.0 }}