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