Improve support and docs for ADC driver (#7191)

* Improve support and docs for ADC driver

* Comment ADC channels

* Move to Makers and Modders section, and fix usage instructions

* Flesh out intro

* Superscript 328P note

* Fix pin_to_mux LUT

* Support USB64/1287 as well

* analogReadPin() defaults to 0V mux on invalid pin

* Update pinToMux() function documentation

* Dot

* Accept (some of) the `qmk cformat` changes

* Do clang-format properly

* More wording tweaks

* Link to encoder docs

1 files changed, 16 insertions, 21 deletions

diff --git a/drivers/avr/analog.h b/drivers/avr/analog.h
index 1b773d82c..058882450 100644
--- a/drivers/avr/analog.h
+++ b/drivers/avr/analog.h
@@ -14,45 +14,40 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef _analog_h_included__
-#define _analog_h_included__
+#pragma once
 
 #include <stdint.h>
+#include "quantum.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 void    analogReference(uint8_t mode);
 int16_t analogRead(uint8_t pin);
+
+int16_t analogReadPin(pin_t pin);
+uint8_t pinToMux(pin_t pin);
+
 int16_t adc_read(uint8_t mux);
 #ifdef __cplusplus
 }
 #endif
 
-#define ADC_REF_POWER (1 << REFS0)
-#define ADC_REF_INTERNAL ((1 << REFS1) | (1 << REFS0))
-#define ADC_REF_EXTERNAL (0)
+#define ADC_REF_EXTERNAL 0                          // AREF, Internal Vref turned off
+#define ADC_REF_POWER _BV(REFS0)                    // AVCC with external capacitor on AREF pin
+#define ADC_REF_INTERNAL (_BV(REFS1) | _BV(REFS0))  // Internal 2.56V Voltage Reference with external capacitor on AREF pin (1.1V for 328P)
 
 // These prescaler values are for high speed mode, ADHSM = 1
-#if F_CPU == 16000000L
-#    define ADC_PRESCALER ((1 << ADPS2) | (1 << ADPS1))
+#if F_CPU == 16000000L || F_CPU == 12000000L
+#    define ADC_PRESCALER (_BV(ADPS2) | _BV(ADPS1))  // /64
 #elif F_CPU == 8000000L
-#    define ADC_PRESCALER ((1 << ADPS2) | (1 << ADPS0))
+#    define ADC_PRESCALER (_BV(ADPS2) | _BV(ADPS0))  // /32
 #elif F_CPU == 4000000L
-#    define ADC_PRESCALER ((1 << ADPS2))
+#    define ADC_PRESCALER (_BV(ADPS2))  // /16
 #elif F_CPU == 2000000L
-#    define ADC_PRESCALER ((1 << ADPS1) | (1 << ADPS0))
+#    define ADC_PRESCALER (_BV(ADPS1) | _BV(ADPS0))  // /8
 #elif F_CPU == 1000000L
-#    define ADC_PRESCALER ((1 << ADPS1))
+#    define ADC_PRESCALER _BV(ADPS1)  // /4
 #else
-#    define ADC_PRESCALER ((1 << ADPS0))
-#endif
-
-// some avr-libc versions do not properly define ADHSM
-#if defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB1286__)
-#    if !defined(ADHSM)
-#        define ADHSM (7)
-#    endif
-#endif
-
+#    define ADC_PRESCALER _BV(ADPS0)  // /2
 #endif