diff --git a/rust/kernel/regulator.rs b/rust/kernel/regulator.rs index 338fc653c32b..0baf763a098e 100644 --- a/rust/kernel/regulator.rs +++ b/rust/kernel/regulator.rs @@ -13,7 +13,7 @@ //! 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") +//! See [Voltage and current regulator API](https://docs.kernel.org/driver-api/regulator.html) //! for more information. use crate::{ @@ -72,6 +72,7 @@ impl IsEnabled for Dynamic {} pub struct Error { /// 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, } @@ -80,7 +81,7 @@ pub struct Error { /// /// # Examples /// -/// Enabling a regulator: +/// ## Enabling a regulator /// /// This example uses [`Regulator`], which is suitable for drivers that /// enable a regulator at probe time and leave them on until the device is @@ -95,37 +96,40 @@ pub struct Error { /// # use kernel::device::Device; /// # use kernel::regulator::{Microvolt, Regulator, Disabled, Enabled}; /// fn enable(dev: &Device, min_uv: Microvolt, max_uv: Microvolt) -> Result { -/// // Obtain a reference to a (fictitious) regulator. -/// let regulator: Regulator = Regulator::::get(dev, c_str!("vcc"))?; -/// -/// // The voltage can be set before enabling the regulator if needed, e.g.: -/// regulator.set_voltage(min_uv, max_uv)?; -/// -/// // The same applies for `get_voltage()`, i.e.: -/// let voltage: Microvolt = 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 = 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_uv, max_uv)?; -/// -/// // The same applies for `get_voltage()`, i.e.: -/// let voltage: Microvolt = regulator.get_voltage()?; -/// -/// // Dropping an enabled regulator will disable it. The refcount will be -/// // decremented. -/// drop(regulator); -/// // ... -/// # Ok::<(), Error>(()) +/// // Obtain a reference to a (fictitious) regulator. +/// let regulator: Regulator = Regulator::::get(dev, c_str!("vcc"))?; +/// +/// // The voltage can be set before enabling the regulator if needed, e.g.: +/// regulator.set_voltage(min_uv, max_uv)?; +/// +/// // The same applies for `get_voltage()`, i.e.: +/// let voltage: Microvolt = 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 = +/// 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_uv, max_uv)?; +/// +/// // The same applies for `get_voltage()`, i.e.: +/// let voltage: Microvolt = 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()`: @@ -136,40 +140,44 @@ pub struct Error { /// # use kernel::device::Device; /// # use kernel::regulator::{Microvolt, Regulator, Enabled}; /// fn enable(dev: &Device, min_uv: Microvolt, max_uv: Microvolt) -> Result { -/// // Obtain a reference to a (fictitious) regulator and enable it. -/// let regulator: Regulator = Regulator::::get(dev, c_str!("vcc"))?; -/// -/// // Dropping an enabled regulator will disable it. The refcount will be -/// // decremented. -/// drop(regulator); -/// // ... -/// # Ok::<(), Error>(()) +/// // Obtain a reference to a (fictitious) regulator and enable it. +/// let regulator: Regulator = Regulator::::get(dev, c_str!("vcc"))?; +/// +/// // Dropping an enabled regulator will disable it. The refcount will be +/// // decremented. +/// drop(regulator); +/// +/// // ... +/// +/// Ok(()) /// } /// ``` /// -/// Disabling a regulator: +/// ## Disabling a regulator /// -///``` +/// ``` /// # use kernel::prelude::*; /// # use kernel::device::Device; /// # use kernel::regulator::{Regulator, Enabled, Disabled}; /// fn disable(dev: &Device, regulator: Regulator) -> 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 = regulator.try_into_disabled().map_err(|error| error.error)?; -/// -/// // The refcount will be decremented when `regulator` is dropped. -/// drop(regulator); -/// // ... -/// # Ok::<(), Error>(()) +/// // 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 = +/// regulator.try_into_disabled().map_err(|error| error.error)?; +/// +/// // The refcount will be decremented when `regulator` is dropped. +/// drop(regulator); +/// +/// // ... +/// +/// Ok(()) /// } /// ``` /// -/// -/// Using `Regulator`: +/// ## Using [`Regulator`] /// /// 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 @@ -182,33 +190,33 @@ pub struct Error { /// # use kernel::c_str; /// # use kernel::device::Device; /// # use kernel::regulator::{Regulator, Dynamic}; -/// /// struct PrivateData { /// regulator: Regulator, /// } /// /// // A fictictious probe function that obtains a regulator and sets it up. /// fn probe(dev: &Device, data: &mut PrivateData) -> Result { -/// // Obtain a reference to a (fictitious) regulator. -/// let mut regulator = Regulator::::get(dev, c_str!("vcc"))?; -/// // Enable the regulator. The type is still `Regulator`. -/// regulator.enable()?; -/// -/// Ok(PrivateData { -/// regulator, -/// }) +/// // Obtain a reference to a (fictitious) regulator. +/// let mut regulator = Regulator::::get(dev, c_str!("vcc"))?; +/// +/// // Enable the regulator. The type is still `Regulator`. +/// regulator.enable()?; +/// +/// 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()?; +/// // Decrease the `enabled` reference count. +/// data.regulator.disable()?; +/// /// Ok(()) /// } /// @@ -221,13 +229,14 @@ pub struct Error { /// // 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()`](https://docs.kernel.org/driver-api/regulator.html#c.regulator_get). +/// regulator` obtained from [`regulator_get()`]. +/// +/// [`regulator_get()`]: https://docs.kernel.org/driver-api/regulator.html#c.regulator_get pub struct Regulator where State: RegulatorState + 'static, @@ -379,7 +388,7 @@ fn drop(&mut self) { /// A voltage in microvolts. /// /// The explicit type is used to avoid confusion with other multiples of the -/// volt, which can be desastrous. +/// volt, which can be disastrous. #[repr(transparent)] #[derive(Copy, Clone, PartialEq, Eq)] pub struct Microvolt(pub i32);