Struct Regulator

pub struct Regulator<State = Dynamic>
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(())
}

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

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.

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

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 Regulator<Dynamic>

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

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 enable(&mut self) -> Result

Increases the enabled reference count.

pub fn disable(&mut self) -> Result

Decreases the enabled reference count.

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.