feat(adc): differential sampling support

boards/feather_m0/examples/adc.rs

@@ -48,6 +48,6 @@ fn main() -> ! {
     loop {
         let res = adc.read(&mut adc_pin);
         #[cfg(feature = "use_semihosting")]
-        cortex_m_semihosting::hprintln!("ADC value: {}", read).unwrap();
+        cortex_m_semihosting::hprintln!("ADC value: {}", res).unwrap();
     }
 }

hal/src/peripherals/adc/builder.rs

@@ -152,6 +152,10 @@ pub struct AdcBuilder {
     pub sample_clock_cycles: Option<u8>,
     pub accumulation: Accumulation,
     pub vref: Option<Reference>,
+    pub offset_compensation: Option<bool>,
+    pub reference_compensation: Option<bool>,
+    pub auto_left_adjust: Option<bool>,
+    pub auto_rail_to_rail: Option<bool>,
 }
 
 /// Version of [AdcBuilder] without any optional settings.
@@ -162,6 +166,10 @@ pub(crate) struct AdcSettings {
     pub sample_clock_cycles: u8,
     pub accumulation: Accumulation,
     pub vref: Reference,
+    pub offset_compensation: bool,
+    pub reference_compensation: bool,
+    pub auto_left_adjust: bool,
+    pub auto_rail_to_rail: bool,
 }
 
 impl AdcBuilder {
@@ -172,6 +180,10 @@ impl AdcBuilder {
             sample_clock_cycles: None,
             accumulation: accumulation_method,
             vref: None,
+            offset_compensation: None,
+            reference_compensation: None,
+            auto_left_adjust: None,
+            auto_rail_to_rail: None,
         }
     }
 
@@ -190,6 +202,10 @@ impl AdcBuilder {
             sample_clock_cycles: self.sample_clock_cycles.unwrap(),
             accumulation: self.accumulation,
             vref: self.vref.unwrap(),
+            offset_compensation: self.offset_compensation.unwrap_or(false),
+            reference_compensation: self.reference_compensation.unwrap_or(false),
+            auto_left_adjust: self.auto_left_adjust.unwrap_or(false),
+            auto_rail_to_rail: self.auto_rail_to_rail.unwrap_or(false),
         })
     }
 
@@ -244,6 +260,47 @@ impl AdcBuilder {
         Ok(adc_clk_freq / clocks_per_sample)
     }
 
+    /// Configure the ADC offset compensation
+    ///
+    /// ## Important
+    /// * Enabling offset compesation forces the clock cycles per sample to be 4
+    ///   GCLK cycles, any change to the cycles per sample via
+    ///   [`Self::with_clock_cycles_per_sample()`] will be ignored.
+    #[hal_cfg("adc-d5x")]
+    pub fn enable_offset_compensation(mut self, enable: bool) -> Self {
+        self.offset_compensation = Some(enable);
+        self
+    }
+
+    /// Configure the ADC reference compensation
+    pub fn enable_reference_compensation(mut self, enable: bool) -> Self {
+        self.reference_compensation = Some(enable);
+        self
+    }
+
+    /// Enables automatic left-adjustment when measuring differential inputs.
+    /// This allows use of the ADC summation or averaging hardware with
+    /// negative result values. Results are automatically right-shifted back
+    /// appropriately.
+    pub fn enable_auto_left_adjust(mut self, enable: bool) -> Self {
+        self.auto_left_adjust = Some(enable);
+        self
+    }
+
+    /// Automatically enables rail-to-rail operation when measuring a
+    /// differential input. This relaxes common-mode input requirements on
+    /// differential inputs and allows measurments closer to supply rails.
+    ///
+    /// ## Important
+    /// * Enabling auto rail-to-rail incurs a slight runtime performance hit as
+    ///   the CTRLA.R2R bit is enable-protected, meaning the ADC must be shut
+    ///   down and re-enabled to enable/disable rail-to-rail mode.
+    #[hal_cfg("adc-d5x")]
+    pub fn enable_auto_rail_to_rail(mut self, enable: bool) -> Self {
+        self.auto_rail_to_rail = Some(enable);
+        self
+    }
+
     /// Turn the builder into an ADC
     #[hal_cfg("adc-d5x")]
     #[inline]

hal/src/peripherals/adc/d11/channel.rs

@@ -0,0 +1,104 @@
+use core::marker::PhantomData;
+use atsamd_hal_macros::hal_cfg;
+use crate::{
+    adc::*,
+    pac::adc::inputctrl::{Muxposselect, Muxnegselect},
+    typelevel::Sealed,
+};
+
+macro_rules! channel {
+    (
+        $(
+            $CH:ident: ($($PMUX:path)?, $($NMUX:path)?) $(+ $MARKER:ident)*
+        ),+
+        $(,)?
+    ) => {
+        crate::paste::paste!{
+            $(
+                pub struct $CH<I: AdcInstance> {
+                    adc: PhantomData<I>,
+                }
+
+                impl<I: AdcInstance> Sealed for $CH<I> {}
+
+                $(
+                    impl<I: AdcInstance> PosChannel<I> for $CH<I> {
+                        const MUXVAL: Muxposselect = $PMUX;
+
+                        fn get_channel() -> Self {
+                            Self {
+                                adc: PhantomData
+                            }
+                        }
+                    }
+                )?
+                $(
+                    impl<I: AdcInstance> NegChannel<I> for $CH<I> {
+                        const MUXVAL: Muxnegselect = $NMUX;
+
+                        fn get_channel() -> Self {
+                            Self {
+                                adc: PhantomData
+                            }
+                        }
+                    }
+                )?
+                $(
+                    impl<I: AdcInstance> $MARKER<I> for $CH<I> {}
+                )*
+            )+
+        }
+    };
+}
+
+#[hal_cfg("adc-d21")]
+channel! {
+    AIN0: (Muxposselect::Pin0, Muxnegselect::Pin0),
+    AIN1: (Muxposselect::Pin1, Muxnegselect::Pin1),
+    AIN2: (Muxposselect::Pin2, Muxnegselect::Pin2),
+    AIN3: (Muxposselect::Pin3, Muxnegselect::Pin3),
+    AIN4: (Muxposselect::Pin4, Muxnegselect::Pin4),
+    AIN5: (Muxposselect::Pin5, Muxnegselect::Pin5),
+    AIN6: (Muxposselect::Pin6, Muxnegselect::Pin6),
+    AIN7: (Muxposselect::Pin7, Muxnegselect::Pin7),
+    AIN8: (Muxposselect::Pin8, ),
+    AIN9: (Muxposselect::Pin9, ),
+    AIN10: (Muxposselect::Pin10, ),
+    AIN11: (Muxposselect::Pin11, ),
+    AIN12: (Muxposselect::Pin12, ),
+    AIN13: (Muxposselect::Pin13, ),
+    AIN14: (Muxposselect::Pin14, ),
+    AIN15: (Muxposselect::Pin15, ),
+    AIN16: (Muxposselect::Pin15, ),
+    AIN17: (Muxposselect::Pin15, ),
+    AIN18: (Muxposselect::Pin15, ),
+    AIN19: (Muxposselect::Pin15, ),
+    TEMP: (Muxposselect::Temp, ),
+    SCALEDCOREVCC: (Muxposselect::Scaledcorevcc, ) + CpuVoltageSource,
+    SCALEDIOVCC: (Muxposselect::Scalediovcc, ) + CpuVoltageSource,
+    BANDGAP: (Muxposselect::Bandgap, ) + CpuVoltageSource,
+    DAC: (Muxposselect::Dac, ),
+    GND: (, Muxnegselect::Gnd),
+    IOGND: (, Muxnegselect::Iognd),
+}
+
+#[hal_cfg("adc-d11")]
+channel! {
+    AIN0: (Muxposselect::Pin0, Muxnegselect::Pin0),
+    AIN1: (Muxposselect::Pin1, Muxnegselect::Pin1),
+    AIN2: (Muxposselect::Pin2, Muxnegselect::Pin2),
+    AIN3: (Muxposselect::Pin3, Muxnegselect::Pin3),
+    AIN4: (Muxposselect::Pin4, Muxnegselect::Pin4),
+    AIN5: (Muxposselect::Pin5, Muxnegselect::Pin5),
+    AIN6: (Muxposselect::Pin6, Muxnegselect::Pin6),
+    AIN7: (Muxposselect::Pin7, Muxnegselect::Pin7),
+    AIN8: (Muxposselect::Pin8, ),
+    AIN9: (Muxposselect::Pin9, ),
+    TEMP: (Muxposselect::Temp, ),
+    SCALEDCOREVCC: (Muxposselect::Scaledcorevcc, ) + CpuVoltageSource,
+    SCALEDIOVCC: (Muxposselect::Scalediovcc, ) + CpuVoltageSource,
+    BANDGAP: (Muxposselect::Bandgap, ) + CpuVoltageSource,
+    DAC: (Muxposselect::Dac, ),
+    GND: (, Muxnegselect::Gnd),
+    IOGND: (, Muxnegselect::Iognd),
+}

hal/src/peripherals/adc/d11/mod.rs

@@ -1,16 +1,20 @@
 use super::{
     ADC_SETTINGS_INTERNAL_READ, ADC_SETTINGS_INTERNAL_READ_D21_TEMP, Accumulation, Adc,
-    AdcInstance, AdcSettings, CpuVoltageSource, Error, Flags, PrimaryAdc, SampleCount,
+    AdcInstance, AdcSettings, Error, Flags, PrimaryAdc, SampleCount, SampleMode, TEMP, GND,
+    CpuVoltageSource, PosChannel, NegChannel,
 };
 
+use atsamd_hal_macros::{hal_macro_helper};
+
 #[cfg(feature = "async")]
 use super::{FutureAdc, async_api};
 
 use crate::{calibration, pac};
 use pac::Peripherals;
 use pac::Sysctrl;
-use pac::adc::inputctrl::Gainselect;
+use pac::adc::inputctrl::{Gainselect, Muxposselect};
 pub mod pin;
+pub mod channel;
 
 /// Wrapper around the ADC instance
 pub struct Adc0 {
@@ -76,10 +80,9 @@ impl<I: AdcInstance> Adc<I> {
             .sampctrl()
             .modify(|_, w| unsafe { w.samplen().bits(cfg.sample_clock_cycles.saturating_sub(1)) }); // sample length
         self.sync();
-        self.adc.inputctrl().modify(|_, w| {
-            w.muxneg().gnd();
-            w.gain().variant(Gainselect::Div2)
-        }); // No negative input (internal gnd)
+        self.adc
+            .inputctrl()
+            .modify(|_, w| w.gain().variant(Gainselect::Div2));
         self.sync();
         let (sample_cnt, adjres) = match cfg.accumulation {
             // 1 sample to be used as is
@@ -100,6 +103,8 @@ impl<I: AdcInstance> Adc<I> {
         self.sync();
         self.set_reference(cfg.vref);
         self.sync();
+        self.adc.refctrl().modify(|_, w| w.refcomp().bit(cfg.reference_compensation));
+        self.sync();
         self.adc.ctrla().modify(|_, w| w.enable().set_bit());
         self.sync();
         self.cfg = cfg;
@@ -196,16 +201,62 @@ impl<I: AdcInstance> Adc<I> {
     }
 
     #[inline]
-    pub(super) fn mux(&mut self, ch: u8) {
+    pub(super) fn mux(
+        &mut self,
+        pos_ch: pac::adc::inputctrl::Muxposselect,
+        neg_ch: pac::adc::inputctrl::Muxnegselect,
+    ) {
         self.adc.inputctrl().modify(|r, w| {
-            if r.muxpos().bits() != ch {
+            if (r.muxpos().bits() != pos_ch.into()) || (r.muxneg().bits() != neg_ch.into()) {
                 self.discard = true;
             }
-            unsafe { w.muxpos().bits(ch) }
+
+            // Safe as pos_ch and neg_ch are derived from Muxposselect and Muxnegselect PAC enums
+            unsafe {
+                w.muxpos().bits(pos_ch.into());
+                w.muxpos().bits(neg_ch.into())
+            }
         });
         self.sync()
     }
 
+
+    /// Sets the sample mode and various ADC settings based on sample mode & the user supplied
+    /// [`AdcSettings`].
+    ///
+    /// ## Important
+    /// * (For D11) The ADC is automatically powered down before modifying the the enable-protected
+    ///   CTRLB.DIFFMODE and CTRLB.LEFTADJ bits, then turned back on.
+    #[inline]
+    #[hal_macro_helper]
+    pub(super) fn set_sample_mode(&mut self, sample_mode: SampleMode) {
+        // Disable the ADC if chip is SAMD11 family
+        // SAMD11 datasheet section 31.8.5 states that the ADC must be disabled to modify
+        // the DIFFMODE and LEFTADJ bits.
+        #[hal_cfg("adc-d11")]
+        self.power_down();
+
+        self.adc.ctrlb().modify(|_, w| {
+            match sample_mode {
+                SampleMode::SingleEnded => w.diffmode().clear_bit(),
+                SampleMode::Differential => w.diffmode().set_bit(),
+            };
+
+            if self.cfg.auto_left_adjust {
+                match sample_mode {
+                    SampleMode::SingleEnded => w.leftadj().clear_bit(),
+                    SampleMode::Differential => w.leftadj().set_bit(),
+                };
+            }
+            w
+        });
+        self.sync();
+
+        // Re-enable the ADC if chip is SAMD11 family
+        #[hal_cfg("adc-d11")]
+        self.power_up();
+    }
+
     #[inline]
     fn cpu_raw_to_temp(&self, reading: u16) -> f32 {
         // Source:
@@ -252,7 +303,11 @@ impl<I: AdcInstance + PrimaryAdc> Adc<I> {
             // Settings
             adc.adc.inputctrl().modify(|_, w| w.gain()._1x());
             adc.discard = true;
-            let res = adc.read_channel(0x18);
+            let res = adc.read_channel(
+                TEMP::get_channel(),
+                GND::get_channel(),
+                SampleMode::SingleEnded
+            );
             // Set gain back to normal
             adc.adc.inputctrl().modify(|_, w| w.gain().div2());
             adc.discard = true;
@@ -265,11 +320,11 @@ impl<I: AdcInstance + PrimaryAdc> Adc<I> {
     }
 
     #[inline]
-    pub fn read_cpu_voltage(&mut self, src: CpuVoltageSource) -> u16 {
+    pub fn read_cpu_voltage<C: CpuVoltageSource<I>>(&mut self, src: C) -> u16 {
         let voltage = self.with_specific_settings(ADC_SETTINGS_INTERNAL_READ, |adc| {
-            let res = adc.read_channel(src as u8);
+            let res = adc.read_channel(src, GND::get_channel(), SampleMode::SingleEnded);
             let mut res_f = adc.reading_to_f32(res) * 3.3;
-            if CpuVoltageSource::Bandgap != src {
+            if C::MUXVAL != Muxposselect::Bandgap {
                 res_f *= 4.0;
             }
             res_f
@@ -293,7 +348,11 @@ where
         self.inner.adc.inputctrl().modify(|_, w| w.gain()._1x());
         self.inner.discard = true;
 
-        let res = self.read_channel(0x18).await;
+        let res = self.read_channel(
+            TEMP::get_channel(),
+            GND::get_channel(),
+            SampleMode::SingleEnded
+        ).await;
 
         self.inner.adc.inputctrl().modify(|_, w| w.gain().div2());
         self.inner.configure(old_adc_settings);
@@ -305,13 +364,13 @@ where
     }
 
     /// Reads a CPU voltage source. Value returned is in millivolts (mV)
-    pub async fn read_cpu_voltage(&mut self, src: CpuVoltageSource) -> u16 {
+    pub async fn read_cpu_voltage<C: CpuVoltageSource<I>>(&mut self, src: C) -> u16 {
         let old_adc_settings = self.inner.cfg;
         self.inner.configure(ADC_SETTINGS_INTERNAL_READ);
 
-        let res = self.read_channel(src as u8).await;
+        let res = self.read_channel(src, GND::get_channel(), SampleMode::SingleEnded).await;
         let mut voltage = self.inner.reading_to_f32(res) * 3.3;
-        if CpuVoltageSource::Bandgap != src {
+        if C::MUXVAL != Muxposselect::Bandgap {
             voltage *= 4.0;
         }