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}