Struct Regulator

pub struct Regulator<State>
where
    State: RegulatorState,
{ /* private fields */ }

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.

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():

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(())
}

If a driver only cares about the regulator being on for as long it is bound to a device, then it should use devm_enable or devm_enable_optional. This should be the default use-case unless more fine-grained control over the regulator’s state is required.

fn enable(dev: &Device<Bound>) -> Result {
    // Obtain a reference to a (fictitious) regulator and enable it. This
    // call only returns whether the operation succeeded.
    regulator::devm_enable(dev, c_str!("vcc"))?;

    // The regulator will be disabled and put when `dev` is unbound.
    Ok(())
}

Disabling a regulator

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(())
}

Invariants

• inner is a non-null wrapper over a pointer to a struct regulator obtained from regulator_get().

Implementations

impl<T: RegulatorState> Regulator<T>

pub fn set_voltage(&self, min_voltage: Voltage, max_voltage: Voltage) -> Result

Sets the voltage for the regulator.

This can be used to ensure that the device powers up cleanly.

pub fn get_voltage(&self) -> Result<Voltage>

Gets the current voltage of the regulator.

impl Regulator<Disabled>

pub fn get(dev: &Device, name: &CStr) -> Result<Self>

Obtains a Regulator instance from the system.

pub fn try_into_enabled(self) -> Result<Regulator<Enabled>, Error<Disabled>>

Attempts to convert the regulator to an enabled state.

impl Regulator<Enabled>

pub fn get(dev: &Device, name: &CStr) -> Result<Self>

Obtains a Regulator instance from the system and enables it.

This is equivalent to calling regulator_get_enable() in the C API.

pub fn try_into_disabled(self) -> Result<Regulator<Disabled>, Error<Enabled>>

Attempts to convert the regulator to a disabled state.

impl<T: IsEnabled> Regulator<T>

pub fn is_enabled(&self) -> bool

Checks if the regulator is enabled.

Trait Implementations

impl<T: RegulatorState> Drop for Regulator<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: RegulatorState> Send for Regulator<T>

impl<T: RegulatorState> Sync for Regulator<T>