esp_hal/analog/adc/

esp32.rs

use core::{
    marker::PhantomData,
    sync::atomic::{AtomicBool, Ordering},
};

use super::{AdcCalScheme, AdcConfig, Attenuation, Error};
use crate::{
    peripherals::{ADC1, ADC2, SENS},
    private,
};

pub(super) const NUM_ATTENS: usize = 10;

mod calibration;
pub use self::calibration::*;

// ADC2 cannot be used with `radio` functionality on `esp32`, this global helps us to track it's
// state to prevent unexpected behaviour
static ADC2_IN_USE: AtomicBool = AtomicBool::new(false);

#[doc(hidden)]
/// Tries to "claim" `ADC2` peripheral and sets its status.
pub fn try_claim_adc2(_: private::Internal) -> Result<(), Error> {
    if ADC2_IN_USE.fetch_or(true, Ordering::Relaxed) {
        Err(Error::Adc2InUse)
    } else {
        Ok(())
    }
}

#[doc(hidden)]
/// Resets `ADC2` usage status to `Unused`.
pub fn release_adc2(_: private::Internal) {
    ADC2_IN_USE.store(false, Ordering::Relaxed);
}

/// The sampling/readout resolution of the ADC.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[allow(clippy::enum_variant_names, reason = "unit of measurement")]
pub enum Resolution {
    /// 9-bit resolution
    _9Bit,
    /// 10-bit resolution
    _10Bit,
    /// 11-bit resolution
    _11Bit,
    /// 12-bit resolution
    #[default]
    _12Bit,
}

#[doc(hidden)]
pub trait RegisterAccess {
    fn set_resolution(resolution: u8);

    fn set_attenuation(channel: usize, attenuation: u8);

    fn clear_dig_force();

    fn set_start_force();

    fn set_en_pad_force();

    fn set_en_pad(channel: u8);

    fn clear_start_sar();

    fn set_start_sar();

    fn read_done_sar() -> bool;

    fn read_data_sar() -> u16;

    fn instance_number() -> u8;
}

impl RegisterAccess for ADC1<'_> {
    fn set_resolution(resolution: u8) {
        SENS::regs()
            .sar_start_force()
            .modify(|_, w| unsafe { w.sar1_bit_width().bits(resolution) });
        SENS::regs()
            .sar_read_ctrl()
            .modify(|_, w| unsafe { w.sar1_sample_bit().bits(resolution) });
    }

    fn set_attenuation(channel: usize, attenuation: u8) {
        SENS::regs().sar_atten1().modify(|r, w| {
            let new_value = (r.bits() & !(0b11 << (channel * 2)))
                | (((attenuation & 0b11) as u32) << (channel * 2));

            unsafe { w.sar1_atten().bits(new_value) }
        });
    }

    fn clear_dig_force() {
        SENS::regs()
            .sar_read_ctrl()
            .modify(|_, w| w.sar1_dig_force().clear_bit());
    }

    fn set_start_force() {
        SENS::regs()
            .sar_meas_start1()
            .modify(|_, w| w.meas1_start_force().set_bit());
    }

    fn set_en_pad_force() {
        SENS::regs()
            .sar_meas_start1()
            .modify(|_, w| w.sar1_en_pad_force().set_bit());
    }

    fn set_en_pad(channel: u8) {
        SENS::regs()
            .sar_meas_start1()
            .modify(|_, w| unsafe { w.sar1_en_pad().bits(1 << channel) });
    }

    fn clear_start_sar() {
        SENS::regs()
            .sar_meas_start1()
            .modify(|_, w| w.meas1_start_sar().clear_bit());
    }

    fn set_start_sar() {
        SENS::regs()
            .sar_meas_start1()
            .modify(|_, w| w.meas1_start_sar().set_bit());
    }

    fn read_done_sar() -> bool {
        SENS::regs()
            .sar_meas_start1()
            .read()
            .meas1_done_sar()
            .bit_is_set()
    }

    fn read_data_sar() -> u16 {
        SENS::regs()
            .sar_meas_start1()
            .read()
            .meas1_data_sar()
            .bits()
    }

    fn instance_number() -> u8 {
        1
    }
}

impl RegisterAccess for ADC2<'_> {
    fn set_resolution(resolution: u8) {
        SENS::regs()
            .sar_start_force()
            .modify(|_, w| unsafe { w.sar2_bit_width().bits(resolution) });
        SENS::regs()
            .sar_read_ctrl2()
            .modify(|_, w| unsafe { w.sar2_sample_bit().bits(resolution) });
    }

    fn set_attenuation(channel: usize, attenuation: u8) {
        SENS::regs().sar_atten2().modify(|r, w| {
            let new_value = (r.bits() & !(0b11 << (channel * 2)))
                | (((attenuation & 0b11) as u32) << (channel * 2));

            unsafe { w.sar2_atten().bits(new_value) }
        });
    }

    fn clear_dig_force() {
        SENS::regs()
            .sar_read_ctrl2()
            .modify(|_, w| w.sar2_dig_force().clear_bit());
    }

    fn set_start_force() {
        SENS::regs()
            .sar_meas_start2()
            .modify(|_, w| w.meas2_start_force().set_bit());
    }

    fn set_en_pad_force() {
        SENS::regs()
            .sar_meas_start2()
            .modify(|_, w| w.sar2_en_pad_force().set_bit());
    }

    fn set_en_pad(channel: u8) {
        SENS::regs()
            .sar_meas_start2()
            .modify(|_, w| unsafe { w.sar2_en_pad().bits(1 << channel) });
    }

    fn clear_start_sar() {
        SENS::regs()
            .sar_meas_start2()
            .modify(|_, w| w.meas2_start_sar().clear_bit());
    }

    fn set_start_sar() {
        SENS::regs()
            .sar_meas_start2()
            .modify(|_, w| w.meas2_start_sar().set_bit());
    }

    fn read_done_sar() -> bool {
        SENS::regs()
            .sar_meas_start2()
            .read()
            .meas2_done_sar()
            .bit_is_set()
    }

    fn read_data_sar() -> u16 {
        SENS::regs()
            .sar_meas_start2()
            .read()
            .meas2_data_sar()
            .bits()
    }

    fn instance_number() -> u8 {
        2
    }
}

/// Analog-to-Digital Converter peripheral driver.
pub struct Adc<'d, ADC, Dm: crate::DriverMode> {
    _adc: ADC,
    attenuations: [Option<Attenuation>; NUM_ATTENS],
    active_channel: Option<u8>,
    resolution_bits: u8,
    // Set when this driver claimed ADC2, which it then releases on drop.
    adc2_claimed: bool,
    _phantom: PhantomData<(Dm, &'d mut ())>,
}

impl<'d, ADCX> Adc<'d, ADCX, crate::Blocking>
where
    ADCX: RegisterAccess + 'd,
{
    /// Configures a given ADC instance using the provided configuration, and
    /// initializes the ADC for use.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Adc2InUse`] if `ADC2` is already in use by the radio.
    /// `ADC2` cannot be used simultaneously with `radio` functionalities.
    /// The handle is consumed even on failure; pass a reborrowed handle to retry later.
    pub fn new(adc_instance: ADCX, config: AdcConfig<ADCX>) -> Result<Self, Error> {
        // Claim ADC2 for exclusive use; the driver releases it on drop.
        let adc2_claimed = if ADCX::instance_number() == 2 {
            if try_claim_adc2(private::Internal).is_err() {
                return Err(Error::Adc2InUse);
            }
            true
        } else {
            false
        };

        let sensors = SENS::regs();

        // Set reading and sampling resolution
        ADCX::set_resolution(config.resolution as u8);

        // Set attenuation for pins
        let attenuations = config.attenuations;

        for (channel, attenuation) in attenuations.iter().enumerate() {
            if let Some(attenuation) = attenuation {
                ADCX::set_attenuation(channel, *attenuation as u8);
            }
        }

        // Set controller to RTC
        ADCX::clear_dig_force();
        ADCX::set_start_force();
        ADCX::set_en_pad_force();
        sensors.sar_touch_ctrl1().modify(|_, w| {
            w.xpd_hall_force().set_bit();
            w.hall_phase_force().set_bit()
        });

        sensors.sar_meas_wait2().modify(|_, w| unsafe {
            // Set power to SW power on
            w.force_xpd_sar().bits(0b11);
            // disable AMP
            w.force_xpd_amp().bits(0b10)
        });
        sensors.sar_meas_ctrl().modify(|_, w| unsafe {
            w.amp_rst_fb_fsm().bits(0);
            w.amp_short_ref_fsm().bits(0);
            w.amp_short_ref_gnd_fsm().bits(0)
        });
        sensors.sar_meas_wait1().modify(|_, w| unsafe {
            w.sar_amp_wait1().bits(1);
            w.sar_amp_wait2().bits(1)
        });
        sensors
            .sar_meas_wait2()
            .modify(|_, w| unsafe { w.sar_amp_wait3().bits(1) });

        // Do *not* invert the output
        // NOTE: This seems backwards, but was verified experimentally.
        sensors
            .sar_read_ctrl()
            .modify(|_, w| w.sar1_data_inv().set_bit());
        sensors
            .sar_read_ctrl2()
            .modify(|_, w| w.sar2_data_inv().set_bit());

        Ok(Adc {
            _adc: adc_instance,
            attenuations: config.attenuations,
            active_channel: None,
            resolution_bits: match config.resolution {
                Resolution::_9Bit => 9,
                Resolution::_10Bit => 10,
                Resolution::_11Bit => 11,
                Resolution::_12Bit => 12,
            },
            adc2_claimed,
            _phantom: PhantomData,
        })
    }

    /// Requests that the ADC begin a conversion on the specified pin.
    ///
    /// Takes an [`AdcPin`](super::AdcPin) reference, as it is
    /// expected that the ADC will be able to sample whatever channel
    /// underlies the pin.
    ///
    /// # Errors
    ///
    /// Returns [`Error::ChannelNotConfigured`] if the channel was not configured in
    /// [`AdcConfig`].
    pub fn read_oneshot<PIN, CS>(
        &mut self,
        pin: &mut super::AdcPin<PIN, ADCX, CS>,
    ) -> nb::Result<u16, Error>
    where
        PIN: super::AdcChannel,
        CS: AdcCalScheme<ADCX>,
    {
        let channel = pin.pin.adc_channel();
        if self.attenuations[channel as usize].is_none() {
            return Err(nb::Error::Other(Error::ChannelNotConfigured(channel)));
        }

        if let Some(active_channel) = self.active_channel {
            // There is conversion in progress:
            // - if it's for a different channel try again later
            // - if it's for the given channel, go ahead and check progress
            if active_channel != pin.pin.adc_channel() {
                return Err(nb::Error::WouldBlock);
            }
        } else {
            // If no conversions are in progress, start a new one for given channel
            self.active_channel = Some(pin.pin.adc_channel());

            ADCX::set_en_pad(pin.pin.adc_channel());

            ADCX::clear_start_sar();
            ADCX::set_start_sar();
        }

        // Wait for ADC to finish conversion
        let conversion_finished = ADCX::read_done_sar();
        if !conversion_finished {
            return Err(nb::Error::WouldBlock);
        }

        // Get converted value and scale to 12 bits
        let mut converted_value = ADCX::read_data_sar() as u32;
        converted_value <<= 12 - self.resolution_bits;
        if converted_value > 4095 {
            converted_value = 4095;
        }

        // Mark that no conversions are currently in progress
        self.active_channel = None;

        Ok(pin.cal_scheme.adc_val(converted_value as u16))
    }
}

impl<ADC, Dm: crate::DriverMode> Drop for Adc<'_, ADC, Dm> {
    fn drop(&mut self) {
        if self.adc2_claimed {
            release_adc2(private::Internal);
        }
    }
}