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