rust/kernel/regulator.rs - linux - Git at Google

 // 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::Device,
     error::{from_err_ptr, to_result, Result},
     prelude::*,
 };

 use core::{marker::PhantomData, mem::ManuallyDrop, ptr::NonNull};

 mod private {
     pub trait Sealed {}

     impl Sealed for super::Enabled {}
     impl Sealed for super::Disabled {}
     impl Sealed for super::Dynamic {}
 }

 /// 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;

 /// A state that models the C API. The [`Regulator`] can be either enabled or
 /// disabled, and the user is in control of the reference count. This is also
 /// the default state.
 ///
 /// Use [`Regulator::is_enabled`] to check the regulator's current state.
 pub struct Dynamic;

 impl RegulatorState for Enabled {
     const DISABLE_ON_DROP: bool = true;
 }

 impl RegulatorState for Disabled {
     const DISABLE_ON_DROP: bool = false;
 }

 impl RegulatorState for Dynamic {
     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 {}
 impl IsEnabled for Dynamic {}

 /// 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>,
 }

 /// 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::c_str;
 /// # 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_str!("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::c_str;
 /// # 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_str!("vcc"))?;
 ///
 ///     // Dropping an enabled regulator will disable it. The refcount will be
 ///     // decremented.
 ///     drop(regulator);
 ///
 ///     // ...
 ///
 ///     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(())
 /// }
 /// ```
 ///
 /// ## Using [`Regulator<Dynamic>`]
 ///
 /// This example mimics the behavior of the C API, where the user is in
 /// control of the enabled reference count. This is useful for drivers that
 /// might call enable and disable to manage the `enable` reference count at
 /// runtime, perhaps as a result of `open()` and `close()` calls or whatever
 /// other driver-specific or subsystem-specific hooks.
 ///
 /// ```
 /// # use kernel::prelude::*;
 /// # use kernel::c_str;
 /// # use kernel::device::Device;
 /// # use kernel::regulator::{Regulator, Dynamic};
 /// struct PrivateData {
 ///     regulator: Regulator<Dynamic>,
 /// }
 ///
 /// // A fictictious probe function that obtains a regulator and sets it up.
 /// fn probe(dev: &Device) -> Result<PrivateData> {
 ///     // Obtain a reference to a (fictitious) regulator.
 ///     let mut regulator = Regulator::<Dynamic>::get(dev, c_str!("vcc"))?;
 ///
 ///     Ok(PrivateData { regulator })
 /// }
 ///
 /// // A fictictious function that indicates that the device is going to be used.
 /// fn open(dev: &Device, data: &mut PrivateData) -> Result {
 ///     // Increase the `enabled` reference count.
 ///     data.regulator.enable()?;
 ///
 ///     Ok(())
 /// }
 ///
 /// fn close(dev: &Device, data: &mut PrivateData) -> Result {
 ///     // Decrease the `enabled` reference count.
 ///     data.regulator.disable()?;
 ///
 ///     Ok(())
 /// }
 ///
 /// fn remove(dev: &Device, data: PrivateData) -> Result {
 ///     // `PrivateData` is dropped here, which will drop the
 ///     // `Regulator<Dynamic>` in turn.
 ///     //
 ///     // The reference that was obtained by `regulator_get()` will be
 ///     // released, but it is up to the user to make sure that the number of calls
 ///     // to `enable()` and `disabled()` are balanced before this point.
 ///     Ok(())
 /// }
 /// ```
 ///
 /// # Invariants
 ///
 /// - `inner` is a non-null wrapper over a pointer to a `struct
 ///   regulator` obtained from [`regulator_get()`].
 ///
 /// [`regulator_get()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_get
 pub struct Regulator<State = Dynamic>
 where
     State: RegulatorState,
 {
     inner: NonNull<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.as_ptr(),
                 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.as_ptr()) };
         if voltage < 0 {
             Err(kernel::error::Error::from_errno(voltage))
         } else {
             Ok(Voltage::from_microvolts(voltage))
         }
     }

     fn get_internal(dev: &Device, name: &CStr) -> Result<Regulator<T>> {
         // SAFETY: It is safe to call `regulator_get()`, on a device pointer
         // received from the C code.
         let inner = from_err_ptr(unsafe { bindings::regulator_get(dev.as_raw(), name.as_ptr()) })?;

         // SAFETY: We can safely trust `inner` to be a pointer to a valid
         // regulator if `ERR_PTR` was not returned.
         let inner = unsafe { NonNull::new_unchecked(inner) };

         Ok(Self {
             inner,
             _phantom: PhantomData,
         })
     }

     fn enable_internal(&mut self) -> Result {
         // SAFETY: Safe as per the type invariants of `Regulator`.
         to_result(unsafe { bindings::regulator_enable(self.inner.as_ptr()) })
     }

     fn disable_internal(&mut self) -> Result {
         // SAFETY: Safe as per the type invariants of `Regulator`.
         to_result(unsafe { bindings::regulator_disable(self.inner.as_ptr()) })
     }
 }

 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 mut 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 mut 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 Regulator<Dynamic> {
     /// Obtains a [`Regulator`] instance from the system. The current state of
     /// the regulator is unknown and it is up to the user to manage the enabled
     /// reference count.
     ///
     /// This closely mimics the behavior of the C API and can be used to
     /// dynamically manage the enabled reference count at runtime.
     pub fn get(dev: &Device, name: &CStr) -> Result<Self> {
         Regulator::get_internal(dev, name)
     }

     /// Increases the `enabled` reference count.
     pub fn enable(&mut self) -> Result {
         self.enable_internal()
     }

     /// Decreases the `enabled` reference count.
     pub fn disable(&mut self) -> Result {
         self.disable_internal()
     }
 }

 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.as_ptr()) != 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.as_ptr()) };
         }
         // 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.as_ptr()) };
     }
 }

 /// 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
     }
 }
	// 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::Device,
	error::{from_err_ptr, to_result, Result},
	prelude::*,
	};

	use core::{marker::PhantomData, mem::ManuallyDrop, ptr::NonNull};

	mod private {
	pub trait Sealed {}

	impl Sealed for super::Enabled {}
	impl Sealed for super::Disabled {}
	impl Sealed for super::Dynamic {}
	}

	/// 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;

	/// A state that models the C API. The [`Regulator`] can be either enabled or
	/// disabled, and the user is in control of the reference count. This is also
	/// the default state.
	///
	/// Use [`Regulator::is_enabled`] to check the regulator's current state.
	pub struct Dynamic;

	impl RegulatorState for Enabled {
	const DISABLE_ON_DROP: bool = true;
	}

	impl RegulatorState for Disabled {
	const DISABLE_ON_DROP: bool = false;
	}

	impl RegulatorState for Dynamic {
	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 {}
	impl IsEnabled for Dynamic {}

	/// 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>,
	}

	/// 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::c_str;
	/// # 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_str!("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::c_str;
	/// # 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_str!("vcc"))?;
	///
	/// // Dropping an enabled regulator will disable it. The refcount will be
	/// // decremented.
	/// drop(regulator);
	///
	/// // ...
	///
	/// 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(())
	/// }
	/// ```
	///
	/// ## Using [`Regulator<Dynamic>`]
	///
	/// This example mimics the behavior of the C API, where the user is in
	/// control of the enabled reference count. This is useful for drivers that
	/// might call enable and disable to manage the `enable` reference count at
	/// runtime, perhaps as a result of `open()` and `close()` calls or whatever
	/// other driver-specific or subsystem-specific hooks.
	///
	/// ```
	/// # use kernel::prelude::*;
	/// # use kernel::c_str;
	/// # use kernel::device::Device;
	/// # use kernel::regulator::{Regulator, Dynamic};
	/// struct PrivateData {
	/// regulator: Regulator<Dynamic>,
	/// }
	///
	/// // A fictictious probe function that obtains a regulator and sets it up.
	/// fn probe(dev: &Device) -> Result<PrivateData> {
	/// // Obtain a reference to a (fictitious) regulator.
	/// let mut regulator = Regulator::<Dynamic>::get(dev, c_str!("vcc"))?;
	///
	/// Ok(PrivateData { regulator })
	/// }
	///
	/// // A fictictious function that indicates that the device is going to be used.
	/// fn open(dev: &Device, data: &mut PrivateData) -> Result {
	/// // Increase the `enabled` reference count.
	/// data.regulator.enable()?;
	///
	/// Ok(())
	/// }
	///
	/// fn close(dev: &Device, data: &mut PrivateData) -> Result {
	/// // Decrease the `enabled` reference count.
	/// data.regulator.disable()?;
	///
	/// Ok(())
	/// }
	///
	/// fn remove(dev: &Device, data: PrivateData) -> Result {
	/// // `PrivateData` is dropped here, which will drop the
	/// // `Regulator<Dynamic>` in turn.
	/// //
	/// // The reference that was obtained by `regulator_get()` will be
	/// // released, but it is up to the user to make sure that the number of calls
	/// // to `enable()` and `disabled()` are balanced before this point.
	/// Ok(())
	/// }
	/// ```
	///
	/// # Invariants
	///
	/// - `inner` is a non-null wrapper over a pointer to a `struct
	/// regulator` obtained from [`regulator_get()`].
	///
	/// [`regulator_get()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_get
	pub struct Regulator<State = Dynamic>
	where
	State: RegulatorState,
	{
	inner: NonNull<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.as_ptr(),
	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.as_ptr()) };
	if voltage < 0 {
	Err(kernel::error::Error::from_errno(voltage))
	} else {
	Ok(Voltage::from_microvolts(voltage))
	}
	}

	fn get_internal(dev: &Device, name: &CStr) -> Result<Regulator<T>> {
	// SAFETY: It is safe to call `regulator_get()`, on a device pointer
	// received from the C code.
	let inner = from_err_ptr(unsafe { bindings::regulator_get(dev.as_raw(), name.as_ptr()) })?;

	// SAFETY: We can safely trust `inner` to be a pointer to a valid
	// regulator if `ERR_PTR` was not returned.
	let inner = unsafe { NonNull::new_unchecked(inner) };

	Ok(Self {
	inner,
	_phantom: PhantomData,
	})
	}

	fn enable_internal(&mut self) -> Result {
	// SAFETY: Safe as per the type invariants of `Regulator`.
	to_result(unsafe { bindings::regulator_enable(self.inner.as_ptr()) })
	}

	fn disable_internal(&mut self) -> Result {
	// SAFETY: Safe as per the type invariants of `Regulator`.
	to_result(unsafe { bindings::regulator_disable(self.inner.as_ptr()) })
	}
	}

	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 mut 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 mut 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 Regulator<Dynamic> {
	/// Obtains a [`Regulator`] instance from the system. The current state of
	/// the regulator is unknown and it is up to the user to manage the enabled
	/// reference count.
	///
	/// This closely mimics the behavior of the C API and can be used to
	/// dynamically manage the enabled reference count at runtime.
	pub fn get(dev: &Device, name: &CStr) -> Result<Self> {
	Regulator::get_internal(dev, name)
	}

	/// Increases the `enabled` reference count.
	pub fn enable(&mut self) -> Result {
	self.enable_internal()
	}

	/// Decreases the `enabled` reference count.
	pub fn disable(&mut self) -> Result {
	self.disable_internal()
	}
	}

	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.as_ptr()) != 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.as_ptr()) };
	}
	// 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.as_ptr()) };
	}
	}

	/// 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
	}
	}