regulator.rs

  1// SPDX-License-Identifier: GPL-2.0
  2
  3//! Regulator abstractions, providing a standard kernel interface to control
  4//! voltage and current regulators.
  5//!
  6//! The intention is to allow systems to dynamically control regulator power
  7//! output in order to save power and prolong battery life. This applies to both
  8//! voltage regulators (where voltage output is controllable) and current sinks
  9//! (where current limit is controllable).
 10//!
 11//! C header: [`include/linux/regulator/consumer.h`](srctree/include/linux/regulator/consumer.h)
 12//!
 13//! Regulators are modeled in Rust with a collection of states. Each state may
 14//! enforce a given invariant, and they may convert between each other where applicable.
 15//!
 16//! See [Voltage and current regulator API](https://docs.kernel.org/driver-api/regulator.html)
 17//! for more information.
 18
 19use crate::{
 20    bindings,
 21    device::{Bound, Device},
 22    error::{from_err_ptr, to_result, Result},
 23    prelude::*,
 24};
 25
 26use core::{
 27    marker::PhantomData,
 28    mem::ManuallyDrop, //
 29};
 30
 31mod private {
 32    pub trait Sealed {}
 33
 34    impl Sealed for super::Enabled {}
 35    impl Sealed for super::Disabled {}
 36}
 37
 38/// A trait representing the different states a [`Regulator`] can be in.
 39pub trait RegulatorState: private::Sealed + 'static {
 40    /// Whether the regulator should be disabled when dropped.
 41    const DISABLE_ON_DROP: bool;
 42}
 43
 44/// A state where the [`Regulator`] is known to be enabled.
 45///
 46/// The `enable` reference count held by this state is decremented when it is
 47/// dropped.
 48pub struct Enabled;
 49
 50/// A state where this [`Regulator`] handle has not specifically asked for the
 51/// underlying regulator to be enabled. This means that this reference does not
 52/// own an `enable` reference count, but the regulator may still be on.
 53pub struct Disabled;
 54
 55impl RegulatorState for Enabled {
 56    const DISABLE_ON_DROP: bool = true;
 57}
 58
 59impl RegulatorState for Disabled {
 60    const DISABLE_ON_DROP: bool = false;
 61}
 62
 63/// A trait that abstracts the ability to check if a [`Regulator`] is enabled.
 64pub trait IsEnabled: RegulatorState {}
 65impl IsEnabled for Disabled {}
 66
 67/// An error that can occur when trying to convert a [`Regulator`] between states.
 68pub struct Error<State: RegulatorState> {
 69    /// The error that occurred.
 70    pub error: kernel::error::Error,
 71
 72    /// The regulator that caused the error, so that the operation may be retried.
 73    pub regulator: Regulator<State>,
 74}
 75/// Obtains and enables a [`devres`]-managed regulator for a device.
 76///
 77/// This calls [`regulator_disable()`] and [`regulator_put()`] automatically on
 78/// driver detach.
 79///
 80/// This API is identical to `devm_regulator_get_enable()`, and should be
 81/// preferred over the [`Regulator<T: RegulatorState>`] API if the caller only
 82/// cares about the regulator being enabled.
 83///
 84/// [`devres`]: https://docs.kernel.org/driver-api/driver-model/devres.html
 85/// [`regulator_disable()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_disable
 86/// [`regulator_put()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_put
 87pub fn devm_enable(dev: &Device<Bound>, name: &CStr) -> Result {
 88    // SAFETY: `dev` is a valid and bound device, while `name` is a valid C
 89    // string.
 90    to_result(unsafe { bindings::devm_regulator_get_enable(dev.as_raw(), name.as_char_ptr()) })
 91}
 92
 93/// Same as [`devm_enable`], but calls `devm_regulator_get_enable_optional`
 94/// instead.
 95///
 96/// This obtains and enables a [`devres`]-managed regulator for a device, but
 97/// does not print a message nor provides a dummy if the regulator is not found.
 98///
 99/// This calls [`regulator_disable()`] and [`regulator_put()`] automatically on
100/// driver detach.
101///
102/// [`devres`]: https://docs.kernel.org/driver-api/driver-model/devres.html
103/// [`regulator_disable()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_disable
104/// [`regulator_put()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_put
105pub fn devm_enable_optional(dev: &Device<Bound>, name: &CStr) -> Result {
106    // SAFETY: `dev` is a valid and bound device, while `name` is a valid C
107    // string.
108    to_result(unsafe {
109        bindings::devm_regulator_get_enable_optional(dev.as_raw(), name.as_char_ptr())
110    })
111}
112
113/// A `struct regulator` abstraction.
114///
115/// # Examples
116///
117/// ## Enabling a regulator
118///
119/// This example uses [`Regulator<Enabled>`], which is suitable for drivers that
120/// enable a regulator at probe time and leave them on until the device is
121/// removed or otherwise shutdown.
122///
123/// These users can store [`Regulator<Enabled>`] directly in their driver's
124/// private data struct.
125///
126/// ```
127/// # use kernel::prelude::*;
128/// # use kernel::c_str;
129/// # use kernel::device::Device;
130/// # use kernel::regulator::{Voltage, Regulator, Disabled, Enabled};
131/// fn enable(dev: &Device, min_voltage: Voltage, max_voltage: Voltage) -> Result {
132///     // Obtain a reference to a (fictitious) regulator.
133///     let regulator: Regulator<Disabled> = Regulator::<Disabled>::get(dev, c_str!("vcc"))?;
134///
135///     // The voltage can be set before enabling the regulator if needed, e.g.:
136///     regulator.set_voltage(min_voltage, max_voltage)?;
137///
138///     // The same applies for `get_voltage()`, i.e.:
139///     let voltage: Voltage = regulator.get_voltage()?;
140///
141///     // Enables the regulator, consuming the previous value.
142///     //
143///     // From now on, the regulator is known to be enabled because of the type
144///     // `Enabled`.
145///     //
146///     // If this operation fails, the `Error` will contain the regulator
147///     // reference, so that the operation may be retried.
148///     let regulator: Regulator<Enabled> =
149///         regulator.try_into_enabled().map_err(|error| error.error)?;
150///
151///     // The voltage can also be set after enabling the regulator, e.g.:
152///     regulator.set_voltage(min_voltage, max_voltage)?;
153///
154///     // The same applies for `get_voltage()`, i.e.:
155///     let voltage: Voltage = regulator.get_voltage()?;
156///
157///     // Dropping an enabled regulator will disable it. The refcount will be
158///     // decremented.
159///     drop(regulator);
160///
161///     // ...
162///
163///     Ok(())
164/// }
165/// ```
166///
167/// A more concise shortcut is available for enabling a regulator. This is
168/// equivalent to `regulator_get_enable()`:
169///
170/// ```
171/// # use kernel::prelude::*;
172/// # use kernel::c_str;
173/// # use kernel::device::Device;
174/// # use kernel::regulator::{Voltage, Regulator, Enabled};
175/// fn enable(dev: &Device) -> Result {
176///     // Obtain a reference to a (fictitious) regulator and enable it.
177///     let regulator: Regulator<Enabled> = Regulator::<Enabled>::get(dev, c_str!("vcc"))?;
178///
179///     // Dropping an enabled regulator will disable it. The refcount will be
180///     // decremented.
181///     drop(regulator);
182///
183///     // ...
184///
185///     Ok(())
186/// }
187/// ```
188///
189/// If a driver only cares about the regulator being on for as long it is bound
190/// to a device, then it should use [`devm_enable`] or [`devm_enable_optional`].
191/// This should be the default use-case unless more fine-grained control over
192/// the regulator's state is required.
193///
194/// [`devm_enable`]: crate::regulator::devm_enable
195/// [`devm_optional`]: crate::regulator::devm_enable_optional
196///
197/// ```
198/// # use kernel::prelude::*;
199/// # use kernel::c_str;
200/// # use kernel::device::{Bound, Device};
201/// # use kernel::regulator;
202/// fn enable(dev: &Device<Bound>) -> Result {
203///     // Obtain a reference to a (fictitious) regulator and enable it. This
204///     // call only returns whether the operation succeeded.
205///     regulator::devm_enable(dev, c_str!("vcc"))?;
206///
207///     // The regulator will be disabled and put when `dev` is unbound.
208///     Ok(())
209/// }
210/// ```
211///
212/// ## Disabling a regulator
213///
214/// ```
215/// # use kernel::prelude::*;
216/// # use kernel::device::Device;
217/// # use kernel::regulator::{Regulator, Enabled, Disabled};
218/// fn disable(dev: &Device, regulator: Regulator<Enabled>) -> Result {
219///     // We can also disable an enabled regulator without reliquinshing our
220///     // refcount:
221///     //
222///     // If this operation fails, the `Error` will contain the regulator
223///     // reference, so that the operation may be retried.
224///     let regulator: Regulator<Disabled> =
225///         regulator.try_into_disabled().map_err(|error| error.error)?;
226///
227///     // The refcount will be decremented when `regulator` is dropped.
228///     drop(regulator);
229///
230///     // ...
231///
232///     Ok(())
233/// }
234/// ```
235///
236/// # Invariants
237///
238/// - `inner` is a pointer obtained from a successful call to
239///   [`regulator_get()`]. It is treated as an opaque token that may only be
240///   accessed using C API methods (e.g., it may be `NULL` if the C API returns
241///   `NULL`).
242///
243/// [`regulator_get()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_get
244pub struct Regulator<State>
245where
246    State: RegulatorState,
247{
248    inner: *mut bindings::regulator,
249    _phantom: PhantomData<State>,
250}
251
252impl<T: RegulatorState> Regulator<T> {
253    /// Sets the voltage for the regulator.
254    ///
255    /// This can be used to ensure that the device powers up cleanly.
256    pub fn set_voltage(&self, min_voltage: Voltage, max_voltage: Voltage) -> Result {
257        // SAFETY: Safe as per the type invariants of `Regulator`.
258        to_result(unsafe {
259            bindings::regulator_set_voltage(
260                self.inner,
261                min_voltage.as_microvolts(),
262                max_voltage.as_microvolts(),
263            )
264        })
265    }
266
267    /// Gets the current voltage of the regulator.
268    pub fn get_voltage(&self) -> Result<Voltage> {
269        // SAFETY: Safe as per the type invariants of `Regulator`.
270        let voltage = unsafe { bindings::regulator_get_voltage(self.inner) };
271
272        to_result(voltage).map(|()| Voltage::from_microvolts(voltage))
273    }
274
275    fn get_internal(dev: &Device, name: &CStr) -> Result<Regulator<T>> {
276        let inner =
277            // SAFETY: It is safe to call `regulator_get()`, on a device pointer
278            // received from the C code.
279            from_err_ptr(unsafe { bindings::regulator_get(dev.as_raw(), name.as_char_ptr()) })?;
280
281        // INVARIANT: `inner` is a pointer obtained from `regulator_get()`, and
282        // the call was successful.
283        Ok(Self {
284            inner,
285            _phantom: PhantomData,
286        })
287    }
288
289    fn enable_internal(&self) -> Result {
290        // SAFETY: Safe as per the type invariants of `Regulator`.
291        to_result(unsafe { bindings::regulator_enable(self.inner) })
292    }
293
294    fn disable_internal(&self) -> Result {
295        // SAFETY: Safe as per the type invariants of `Regulator`.
296        to_result(unsafe { bindings::regulator_disable(self.inner) })
297    }
298}
299
300impl Regulator<Disabled> {
301    /// Obtains a [`Regulator`] instance from the system.
302    pub fn get(dev: &Device, name: &CStr) -> Result<Self> {
303        Regulator::get_internal(dev, name)
304    }
305
306    /// Attempts to convert the regulator to an enabled state.
307    pub fn try_into_enabled(self) -> Result<Regulator<Enabled>, Error<Disabled>> {
308        // We will be transferring the ownership of our `regulator_get()` count to
309        // `Regulator<Enabled>`.
310        let regulator = ManuallyDrop::new(self);
311
312        regulator
313            .enable_internal()
314            .map(|()| Regulator {
315                inner: regulator.inner,
316                _phantom: PhantomData,
317            })
318            .map_err(|error| Error {
319                error,
320                regulator: ManuallyDrop::into_inner(regulator),
321            })
322    }
323}
324
325impl Regulator<Enabled> {
326    /// Obtains a [`Regulator`] instance from the system and enables it.
327    ///
328    /// This is equivalent to calling `regulator_get_enable()` in the C API.
329    pub fn get(dev: &Device, name: &CStr) -> Result<Self> {
330        Regulator::<Disabled>::get_internal(dev, name)?
331            .try_into_enabled()
332            .map_err(|error| error.error)
333    }
334
335    /// Attempts to convert the regulator to a disabled state.
336    pub fn try_into_disabled(self) -> Result<Regulator<Disabled>, Error<Enabled>> {
337        // We will be transferring the ownership of our `regulator_get()` count
338        // to `Regulator<Disabled>`.
339        let regulator = ManuallyDrop::new(self);
340
341        regulator
342            .disable_internal()
343            .map(|()| Regulator {
344                inner: regulator.inner,
345                _phantom: PhantomData,
346            })
347            .map_err(|error| Error {
348                error,
349                regulator: ManuallyDrop::into_inner(regulator),
350            })
351    }
352}
353
354impl<T: IsEnabled> Regulator<T> {
355    /// Checks if the regulator is enabled.
356    pub fn is_enabled(&self) -> bool {
357        // SAFETY: Safe as per the type invariants of `Regulator`.
358        unsafe { bindings::regulator_is_enabled(self.inner) != 0 }
359    }
360}
361
362impl<T: RegulatorState> Drop for Regulator<T> {
363    fn drop(&mut self) {
364        if T::DISABLE_ON_DROP {
365            // SAFETY: By the type invariants, we know that `self` owns a
366            // reference on the enabled refcount, so it is safe to relinquish it
367            // now.
368            unsafe { bindings::regulator_disable(self.inner) };
369        }
370        // SAFETY: By the type invariants, we know that `self` owns a reference,
371        // so it is safe to relinquish it now.
372        unsafe { bindings::regulator_put(self.inner) };
373    }
374}
375
376// SAFETY: It is safe to send a `Regulator<T>` across threads. In particular, a
377// Regulator<T> can be dropped from any thread.
378unsafe impl<T: RegulatorState> Send for Regulator<T> {}
379
380// SAFETY: It is safe to send a &Regulator<T> across threads because the C side
381// handles its own locking.
382unsafe impl<T: RegulatorState> Sync for Regulator<T> {}
383
384/// A voltage.
385///
386/// This type represents a voltage value in microvolts.
387#[repr(transparent)]
388#[derive(Copy, Clone, PartialEq, Eq)]
389pub struct Voltage(i32);
390
391impl Voltage {
392    /// Creates a new `Voltage` from a value in microvolts.
393    pub fn from_microvolts(uv: i32) -> Self {
394        Self(uv)
395    }
396
397    /// Returns the value of the voltage in microvolts as an [`i32`].
398    pub fn as_microvolts(self) -> i32 {
399        self.0
400    }
401}