Add ADC support for STM32F3 and STM32F0 devices (#7681)

* Add ADC support for STM32F3 and STM32F0 devices

* Add section about configration options available to the ARM ADC implementation

* Fix STM32 typo

3 files changed, 384 insertions, 1 deletions

diff --git a/docs/adc_driver.md b/docs/adc_driver.md
index 26e148addd..d808a82158 100644
--- a/docs/adc_driver.md
+++ b/docs/adc_driver.md
@@ -2,7 +2,7 @@
 
 QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md).
 
-This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V).
+This driver currently supports both AVR and a limited selection of ARM devices. On AVR devices, the values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). On supported ARM devices, there is more flexibility in control of operation through `#define`s, but by default the values returned are 12-bit integers (0-4095) mapped between 0V and VCC (usually 3.3V).
 
 ## Usage
 
@@ -20,6 +20,8 @@ Then place this include at the top of your code:
 
 ## Channels
 
+### AVR
+
 |Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
 |-------|-------------|-------------|---------|----------|
 |0      |`F0`         |`F0`         |`A0`     |`C0`      |
@@ -39,8 +41,84 @@ Then place this include at the top of your code:
 
 <sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
 
+### ARM
+
+Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
+
+Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
+
+|ADC|Channel|STM32F0XX|STM32F3XX|
+|---|-------|---------|---------|
+|1  |0      |`A0`     |         |
+|1  |1      |`A1`     |`A0`     |
+|1  |2      |`A2`     |`A1`     |
+|1  |3      |`A3`     |`A2`     |
+|1  |4      |`A4`     |`A3`     |
+|1  |5      |`A5`     |`F4`     |
+|1  |6      |`A6`     |`C0`     |
+|1  |7      |`A7`     |`C1`     |
+|1  |8      |`B0`     |`C2`     |
+|1  |9      |`B1`     |`C3`     |
+|1  |10     |`C0`     |`F2`     |
+|1  |11     |`C1`     |         |
+|1  |12     |`C2`     |         |
+|1  |13     |`C3`     |         |
+|1  |14     |`C4`     |         |
+|1  |15     |`C5`     |         |
+|1  |16     |         |         |
+|2  |1      |         |`A4`     |
+|2  |2      |         |`A5`     |
+|2  |3      |         |`A6`     |
+|2  |4      |         |`A7`     |
+|2  |5      |         |`C4`     |
+|2  |6      |         |`C0`     |
+|2  |7      |         |`C1`     |
+|2  |8      |         |`C2`     |
+|2  |9      |         |`C3`     |
+|2  |10     |         |`F2`     |
+|2  |11     |         |`C5`     |
+|2  |12     |         |`B2`     |
+|2  |13     |         |         |
+|2  |14     |         |         |
+|2  |15     |         |         |
+|2  |16     |         |         |
+|3  |1      |         |`B1`     |
+|3  |2      |         |`E9`     |
+|3  |3      |         |`E13`    |
+|3  |4      |         |         |
+|3  |5      |         |         |
+|3  |6      |         |`E8`     |
+|3  |7      |         |`D10`    |
+|3  |8      |         |`D11`    |
+|3  |9      |         |`D12`    |
+|3  |10     |         |`D13`    |
+|3  |11     |         |`D14`    |
+|3  |12     |         |`B0`     |
+|3  |13     |         |`E7`     |
+|3  |14     |         |`E10`    |
+|3  |15     |         |`E11`    |
+|3  |16     |         |`E12`    |
+|4  |1      |         |`E14`    |
+|4  |2      |         |`B12`    |
+|4  |3      |         |`B13`    |
+|4  |4      |         |`B14`    |
+|4  |5      |         |`B15`    |
+|4  |6      |         |`E8`     |
+|4  |7      |         |`D10`    |
+|4  |8      |         |`D11`    |
+|4  |9      |         |`D12`    |
+|4  |10     |         |`D13`    |
+|4  |11     |         |`D14`    |
+|4  |12     |         |`D8`     |
+|4  |13     |         |`D9`     |
+|4  |14     |         |         |
+|4  |15     |         |         |
+|4  |16     |         |         |
+
 ## Functions
 
+### AVR
+
 |Function                    |Description                                                                                                        |
 |----------------------------|-------------------------------------------------------------------------------------------------------------------|
 |`analogReference(mode)`     |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
@@ -48,3 +126,28 @@ Then place this include at the top of your code:
 |`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4.                                   |
 |`pinToMux(pin)`             |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".   |
 |`adc_read(mux)`             |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information.        |
+
+### ARM
+
+Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.
+
+|Function                    |Description                                                                                                         |
+|----------------------------|--------------------------------------------------------------------------------------------------------------------|
+|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
+|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
+|`pinToMux(pin)`             |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".|
+|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.|
+
+## Configuration
+
+## ARM
+
+The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.
+
+|`#define`          |Type  |Default              |Description|
+|-------------------|------|---------------------|-----------|
+|ADC_CIRCULAR_BUFFER|`bool`|`false`              |If `TRUE`, then the implementation will use a circular buffer.|
+|ADC_NUM_CHANNELS   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
+|ADC_BUFFER_DEPTH   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
+|ADC_SAMPLING_RATE  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
+|ADC_RESOLUTION     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
diff --git a/drivers/arm/analog.c b/drivers/arm/analog.c
new file mode 100644
index 0000000000..57f649a81a
--- /dev/null
+++ b/drivers/arm/analog.c
@@ -0,0 +1,220 @@
+/* Copyright 2019 Drew Mills
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "analog.h"
+#include "quantum.h"
+
+
+/* User configurable ADC options */
+#ifndef ADC_CIRCULAR_BUFFER
+#define ADC_CIRCULAR_BUFFER FALSE
+#endif
+
+#ifndef ADC_NUM_CHANNELS
+#define ADC_NUM_CHANNELS 1
+#elif ADC_NUM_CHANNELS != 1
+#error "The ARM ADC implementation currently only supports reading one channel at a time."
+#endif
+
+#ifndef ADC_BUFFER_DEPTH
+#define ADC_BUFFER_DEPTH 2
+#endif
+
+// For more sampling rate options, look at hal_adc_lld.h in ChibiOS
+#ifndef ADC_SAMPLING_RATE
+#define ADC_SAMPLING_RATE ADC_SMPR_SMP_1P5
+#endif
+
+// Options are 12, 10, 8, and 6 bit.
+#ifndef ADC_RESOLUTION
+#define ADC_RESOLUTION ADC_CFGR1_RES_12BIT
+#endif
+
+
+
+static ADCConfig adcCfg = {};
+static adcsample_t sampleBuffer[ADC_NUM_CHANNELS * ADC_BUFFER_DEPTH];
+
+// Initialize to max number of ADCs, set to empty object to initialize all to false.
+#if defined(STM32F0XX)
+static bool adcInitialized[1] = {};
+#elif defined(STM32F3XX)
+static bool adcInitialized[4] = {};
+#else
+#error "adcInitialized has not been implemented for this ARM microcontroller."
+#endif
+
+
+
+static ADCConversionGroup adcConversionGroup = {
+    ADC_CIRCULAR_BUFFER,
+    (uint16_t)(ADC_NUM_CHANNELS),
+    NULL, // No end callback
+    NULL, // No error callback
+#if defined(STM32F0XX)
+    ADC_CFGR1_CONT | ADC_RESOLUTION,
+    ADC_TR(0, 0).
+    ADC_SAMPLING_RATE,
+    NULL, // Doesn't specify a default channel
+#elif defined(STM32F3XX)
+    ADC_CFGR_CONT | ADC_RESOLUTION,
+    ADC_TR(0, 4095),
+    {
+        ADC_SAMPLING_RATE,
+        ADC_SAMPLING_RATE,
+    },
+    {
+        0, // Doesn't specify a default channel
+        0,
+        0,
+        0,
+    },
+#endif
+};
+
+
+
+static inline ADCDriver* intToADCDriver(uint8_t adcInt) {
+
+    ADCDriver* target;
+
+    switch (adcInt) {
+        // clang-format off
+#if STM32_ADC_USE_ADC1
+        case 0: target = &ADCD1; break;
+#endif
+#if STM32_ADC_USE_ADC2
+        case 1: target = &ADCD2; break;
+#endif
+#if STM32_ADC_USE_ADC3
+        case 2: target = &ADCD3; break;
+#endif
+#if STM32_ADC_USE_ADC4
+        case 3: target = &ADCD4; break;
+#endif
+        default: target = NULL; break;
+        // clang-format on
+    }
+
+    return target;
+}
+
+static inline void manageAdcInitializationDriver(uint8_t adc, ADCDriver* adcDriver) {
+    if (!adcInitialized[adc]) {
+        adcStart(adcDriver, &adcCfg);
+        adcInitialized[adc] = true;
+    }
+}
+
+static inline void manageAdcInitialization(uint8_t adc) {
+    manageAdcInitializationDriver(adc, intToADCDriver(adc));
+}
+
+pin_and_adc pinToMux(pin_t pin) {
+    switch(pin) {
+        // clang-format off
+#if defined(STM32F0XX)
+        case A0:  return (pin_and_adc){ ADC_CHANNEL_IN0,  0 };
+        case A1:  return (pin_and_adc){ ADC_CHANNEL_IN1,  0 };
+        case A2:  return (pin_and_adc){ ADC_CHANNEL_IN2,  0 };
+        case A3:  return (pin_and_adc){ ADC_CHANNEL_IN3,  0 };
+        case A4:  return (pin_and_adc){ ADC_CHANNEL_IN4,  0 };
+        case A5:  return (pin_and_adc){ ADC_CHANNEL_IN5,  0 };
+        case A6:  return (pin_and_adc){ ADC_CHANNEL_IN6,  0 };
+        case A7:  return (pin_and_adc){ ADC_CHANNEL_IN7,  0 };
+        case B0:  return (pin_and_adc){ ADC_CHANNEL_IN8,  0 };
+        case B1:  return (pin_and_adc){ ADC_CHANNEL_IN9,  0 };
+        case C0:  return (pin_and_adc){ ADC_CHANNEL_IN10, 0 };
+        case C1:  return (pin_and_adc){ ADC_CHANNEL_IN11, 0 };
+        case C2:  return (pin_and_adc){ ADC_CHANNEL_IN12, 0 };
+        case C3:  return (pin_and_adc){ ADC_CHANNEL_IN13, 0 };
+        case C4:  return (pin_and_adc){ ADC_CHANNEL_IN14, 0 };
+        case C5:  return (pin_and_adc){ ADC_CHANNEL_IN15, 0 };
+#elif defined(STM32F3XX)
+        case A0:  return (pin_and_adc){ ADC_CHANNEL_IN1,  0 };
+        case A1:  return (pin_and_adc){ ADC_CHANNEL_IN2,  0 };
+        case A2:  return (pin_and_adc){ ADC_CHANNEL_IN3,  0 };
+        case A3:  return (pin_and_adc){ ADC_CHANNEL_IN4,  0 };
+        case A4:  return (pin_and_adc){ ADC_CHANNEL_IN1,  1 };
+        case A5:  return (pin_and_adc){ ADC_CHANNEL_IN2,  1 };
+        case A6:  return (pin_and_adc){ ADC_CHANNEL_IN3,  1 };
+        case A7:  return (pin_and_adc){ ADC_CHANNEL_IN4,  1 };
+        case B0:  return (pin_and_adc){ ADC_CHANNEL_IN12, 2 };
+        case B1:  return (pin_and_adc){ ADC_CHANNEL_IN1,  2 };
+        case B2:  return (pin_and_adc){ ADC_CHANNEL_IN12, 1 };
+        case B12: return (pin_and_adc){ ADC_CHANNEL_IN2,  3 };
+        case B13: return (pin_and_adc){ ADC_CHANNEL_IN3,  3 };
+        case B14: return (pin_and_adc){ ADC_CHANNEL_IN4,  3 };
+        case B15: return (pin_and_adc){ ADC_CHANNEL_IN5,  3 };
+        case C0:  return (pin_and_adc){ ADC_CHANNEL_IN6,  0 }; // Can also be ADC2
+        case C1:  return (pin_and_adc){ ADC_CHANNEL_IN7,  0 }; // Can also be ADC2
+        case C2:  return (pin_and_adc){ ADC_CHANNEL_IN8,  0 }; // Can also be ADC2
+        case C3:  return (pin_and_adc){ ADC_CHANNEL_IN9,  0 }; // Can also be ADC2
+        case C4:  return (pin_and_adc){ ADC_CHANNEL_IN5,  1 };
+        case C5:  return (pin_and_adc){ ADC_CHANNEL_IN11, 1 };
+        case D8:  return (pin_and_adc){ ADC_CHANNEL_IN12, 3 };
+        case D9:  return (pin_and_adc){ ADC_CHANNEL_IN13, 3 };
+        case D10: return (pin_and_adc){ ADC_CHANNEL_IN7,  2 }; // Can also be ADC4
+        case D11: return (pin_and_adc){ ADC_CHANNEL_IN8,  2 }; // Can also be ADC4
+        case D12: return (pin_and_adc){ ADC_CHANNEL_IN9,  2 }; // Can also be ADC4
+        case D13: return (pin_and_adc){ ADC_CHANNEL_IN10, 2 }; // Can also be ADC4
+        case D14: return (pin_and_adc){ ADC_CHANNEL_IN11, 2 }; // Can also be ADC4
+        case E7:  return (pin_and_adc){ ADC_CHANNEL_IN13, 2 };
+        case E8:  return (pin_and_adc){ ADC_CHANNEL_IN6,  2 }; // Can also be ADC4
+        case E9:  return (pin_and_adc){ ADC_CHANNEL_IN2,  2 };
+        case E10: return (pin_and_adc){ ADC_CHANNEL_IN14, 2 };
+        case E11: return (pin_and_adc){ ADC_CHANNEL_IN15, 2 };
+        case E12: return (pin_and_adc){ ADC_CHANNEL_IN16, 2 };
+        case E13: return (pin_and_adc){ ADC_CHANNEL_IN3,  2 };
+        case E14: return (pin_and_adc){ ADC_CHANNEL_IN1,  3 };
+        case E15: return (pin_and_adc){ ADC_CHANNEL_IN2,  3 };
+        case F2:  return (pin_and_adc){ ADC_CHANNEL_IN10, 0 }; // Can also be ADC2
+        case F4:  return (pin_and_adc){ ADC_CHANNEL_IN5,  0 };
+#else
+#error "An ADC pin-to-mux configuration has not been specified for this microcontroller."
+#endif
+        default:  return (pin_and_adc){ 0, 0 };
+        // clang-format on
+    }
+}
+
+adcsample_t analogReadPin(pin_t pin) {
+    return adc_read(pinToMux(pin));
+}
+
+adcsample_t analogReadPinAdc(pin_t pin, uint8_t adc) {
+    pin_and_adc target = pinToMux(pin);
+    target.adc = adc;
+    return adc_read(target);
+}
+
+adcsample_t adc_read(pin_and_adc mux) {
+#if defined(STM32F0XX)
+    adcConversionGroup.sqr = ADC_CHSELR_CHSEL1;
+#elif defined(STM32F3XX)
+    adcConversionGroup.sqr[0] = ADC_SQR1_SQ1_N(mux.pin);
+#else
+#error "adc_read has not been updated to support this ARM microcontroller."
+#endif
+
+    ADCDriver* targetDriver = intToADCDriver(mux.adc);
+    manageAdcInitializationDriver(mux.adc, targetDriver);
+
+    adcConvert(targetDriver, &adcConversionGroup, &sampleBuffer[0], ADC_BUFFER_DEPTH);
+    adcsample_t* result = sampleBuffer;
+
+    return *result;
+}
diff --git a/drivers/arm/analog.h b/drivers/arm/analog.h
new file mode 100644
index 0000000000..081d0c1e76
--- /dev/null
+++ b/drivers/arm/analog.h
@@ -0,0 +1,60 @@
+/* Copyright 2019 Drew Mills
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "quantum.h"
+#include "ch.h"
+#include <hal.h>
+
+
+#if !defined(STM32F0XX) && !defined(STM32F3XX)
+#error "Only STM23F0 and STM32F3 devices have ADC support in QMK at this time."
+#endif
+
+#if !HAL_USE_ADC
+#error "You need to set HAL_USE_ADC to TRUE in your halconf.h to use the ADC."
+#endif
+
+#if !STM32_ADC_USE_ADC1 && !STM32_ADC_USE_ADC2 && !STM32_ADC_USE_ADC3 && !STM32_ADC_USE_ADC4
+#error "You need to set one of the 'STM32_ADC_USE_ADCx' settings to TRUE in your mcuconf.h to use the ADC."
+#endif
+
+#if STM32_ADC_DUAL_MODE
+#error "STM32 ADC Dual Mode is not supported at this time."
+#endif
+
+#if STM32_ADCV3_OVERSAMPLING
+#error "STM32 ADCV3 Oversampling is not supported at this time."
+#endif
+
+
+
+typedef struct {
+    pin_t pin;
+    uint8_t adc;
+} pin_and_adc;
+#define PIN_AND_ADC(p,a) (pin_and_adc){p,a}
+
+
+// analogReference has been left un-defined for ARM devices.
+// void analogReference(uint8_t mode);
+
+adcsample_t analogReadPin(pin_t pin);
+adcsample_t analogReadPinAdc(pin_t pin, uint8_t adc);
+pin_and_adc pinToMux(pin_t pin);
+
+adcsample_t adc_read(pin_and_adc mux);