doc: stm32: adc: upgrade common_v2 documentation

add register grouping, fixup comment have them pickedup by doxygen, align style and masks.

2 files changed, 96 insertions, 48 deletions

diff --git a/include/libopencm3/stm32/common/adc_common_v2.h b/include/libopencm3/stm32/common/adc_common_v2.h
index fe4095c8..d46bd496 100644
--- a/include/libopencm3/stm32/common/adc_common_v2.h
+++ b/include/libopencm3/stm32/common/adc_common_v2.h
@@ -36,138 +36,181 @@ specific memorymap.h header before including this header file.*/
 #define LIBOPENCM3_ADC_COMMON_V2_H
 
 /* ----- ADC registers  -----------------------------------------------------*/
-/* ADC interrupt and status register */
+/** ADC interrupt and status register */
 #define ADC_ISR(adc)		MMIO32((adc) + 0x00)
-/* Interrupt Enable Register */
+/** Interrupt Enable Register */
 #define ADC_IER(adc)		MMIO32((adc) + 0x04)
-/* Control Register */
+/** Control Register */
 #define ADC_CR(adc)		MMIO32((adc) + 0x08)
-/* Configuration Register 1 */
+/** Configuration Register 1 */
 #define ADC_CFGR1(adc)			MMIO32((adc) + 0x0C)
-/* Configuration Register 2 */
+/** Configuration Register 2 */
 #define ADC_CFGR2(adc)			MMIO32((adc) + 0x10)
-/* Sample Time Register 1 */
+/** Sample Time Register 1 */
 #define ADC_SMPR1(adc)			MMIO32((adc) + 0x14)
-/* Watchdog Threshold Register 1*/
+/** Watchdog Threshold Register 1*/
 #define ADC_TR1(adc)			MMIO32((adc) + 0x20)
-/* Regular Data Register */
+/** Regular Data Register */
 #define ADC_DR(adc)			MMIO32((adc) + 0x40)
 /* CALFACT for all but f0 :(*/
 
-/* ADC common (shared) registers */
+/** Common Configuration register */
 #define ADC_CCR(adc)		MMIO32((adc) + 0x300 + 0x8)
 
 /* --- Register values -------------------------------------------------------*/
 
 /* ADC_ISR Values -----------------------------------------------------------*/
+/** @defgroup adc_isr ISR ADC interrupt status register
+@{*/
 
-/* AWD1: Analog watchdog 1 flag */
+/** AWD1: Analog watchdog 1 flag */
 #define ADC_ISR_AWD1		(1 << 7)
+/** OVR: Overrun flag */
 #define ADC_ISR_OVR			(1 << 4)
+/** EOS: End of sequence conversions flag */
 #define ADC_ISR_EOS			(1 << 3)   // FIXME - move to single/multi here.
 #define ADC_ISR_EOSEQ			ADC_ISR_EOS /* TODO - keep only one? */
+/** EOS: End of regular conversion flag */
 #define ADC_ISR_EOC			(1 << 2)
+/** EOSMP: End of sampling flag */
 #define ADC_ISR_EOSMP			(1 << 1)
+/** ADRDY: Ready flag */
 #define ADC_ISR_ADRDY			(1 << 0)
 
+/**@}*/
+
 /* ADC_IER Values -----------------------------------------------------------*/
+/** @defgroup adc_ier IER ADC interrupt enable register
+@{*/
 
-/* AWD1IE: Analog watchdog 1 interrupt enable */
+/** AWD1IE: Analog watchdog 1 interrupt enable */
 #define ADC_IER_AWD1IE		(1 << 7)
-/* OVRIE: Overrun interrupt enable */
+/** OVRIE: Overrun interrupt enable */
 #define ADC_IER_OVRIE		(1 << 4)
-/* EOSIE: End of regular sequence of conversions interrupt enable */
+/** EOSIE: End of regular sequence of conversions interrupt enable */
 #define ADC_IER_EOSIE		(1 << 3)
 #define ADC_IER_EOSEQIE		ADC_IER_EOSIE /* TODO - keep only one? */
-/* EOCIE: End of regular conversion interrupt enable */
+/** EOCIE: End of regular conversion interrupt enable */
 #define ADC_IER_EOCIE		(1 << 2)
-/* EOSMPIE: End of sampling flag interrupt enable for regular conversions */
+/** EOSMPIE: End of sampling flag interrupt enable for regular conversions */
 #define ADC_IER_EOSMPIE		(1 << 1)
-/* ADRDYIE : ADC ready interrupt enable */
+/** ADRDYIE: ADC ready interrupt enable */
 #define ADC_IER_ADRDYIE		(1 << 0)
 
+/**@}*/
+
 /* ADC_CR Values -----------------------------------------------------------*/
+/** @defgroup adc_cr CR ADC control register
+@{*/
 
-/* ADCAL: ADC calibration */
+/** ADCAL: ADC calibration */
 #define ADC_CR_ADCAL		(1 << 31)
-/* ADSTP: ADC stop of regular conversion command */
+/** ADSTP: ADC stop of regular conversion command */
 #define ADC_CR_ADSTP		(1 << 4)
-/* ADSTART: ADC start of regular conversion */
+/** ADSTART: ADC start of regular conversion */
 #define ADC_CR_ADSTART		(1 << 2)
-/* ADDIS: ADC disable command */
+/** ADDIS: ADC disable command */
 #define ADC_CR_ADDIS		(1 << 1)
-/* ADEN: ADC enable control */
+/** ADEN: ADC enable control */
 #define ADC_CR_ADEN		(1 << 0)
 
+/**@}*/
+
 /* ADC_CFGR1 Values -----------------------------------------------------------*/
+/** @defgroup adc_cfgr1 CFGR1 ADC configuration register 1
+@{*/
 
-/* AWD1CH[4:0]: Analog watchdog 1 channel selection */
 #define ADC_CFGR1_AWD1CH_SHIFT		26
 #define ADC_CFGR1_AWD1CH			(0x1F << ADC_CFGR1_AWD1CH_SHIFT)
+/** AWD1CH: Analog watchdog 1 channel selection */
 #define ADC_CFGR1_AWD1CH_VAL(x)		((x) << ADC_CFGR1_AWD1CH_SHIFT)
 
-/* AWD1EN: Analog watchdog 1 enable on regular channels */
+/** AWD1EN: Analog watchdog 1 enable on regular channels */
 #define ADC_CFGR1_AWD1EN		(1 << 23)
-
-/* AWD1SGL: Enable the watchdog 1 on a single channel or on all channels */
+/** AWD1SGL: Enable the watchdog 1 on a single channel or on all channels */
 #define ADC_CFGR1_AWD1SGL		(1 << 22)
-
-/* DISCEN: Discontinuous mode for regular channels */
+/** DISCEN: Discontinuous mode for regular channels */
 #define ADC_CFGR1_DISCEN		(1 << 16)
-
-/* AUTDLY: Delayed conversion mode */
+/** AUTDLY: Delayed conversion mode */
 #define ADC_CFGR1_AUTDLY		(1 << 14)
-
-/* CONT: Single / continuous conversion mode for regular conversions */
+/** CONT: Single / continuous conversion mode for regular conversions */
 #define ADC_CFGR1_CONT		(1 << 13)
-
-/* OVRMOD: Overrun Mode */
+/** OVRMOD: Overrun Mode */
 #define ADC_CFGR1_OVRMOD		(1 << 12)
 
-/*
- * EXTEN[1:0]: External trigger enable and polarity selection for regular
- * channels
- */
+#define ADC_CFGR1_EXTEN_MASK		(0x3 << 10)
+/** @defgroup adc_cfgr1_exten EXTEN: External trigger enable and polarity selection for regular channels
+@{*/
 #define ADC_CFGR1_EXTEN_DISABLED		(0x0 << 10)
 #define ADC_CFGR1_EXTEN_RISING_EDGE	(0x1 << 10)
 #define ADC_CFGR1_EXTEN_FALLING_EDGE	(0x2 << 10)
 #define ADC_CFGR1_EXTEN_BOTH_EDGES	(0x3 << 10)
+/**@}*/
 
-#define ADC_CFGR1_EXTEN_MASK		(0x3 << 10)
-
-/* ALIGN: Data alignment */
+/** ALIGN: Data alignment */
 #define ADC_CFGR1_ALIGN		(1 << 5)
 
-/* RES[1:0]: Data resolution */
+#define ADC_CFGR1_RES_MASK	(0x3 << 3)
+/** @defgroup adc_cfgr1_res RES: Data resolution
+@{*/
 #define ADC_CFGR1_RES_12_BIT	(0x0 << 3)
 #define ADC_CFGR1_RES_10_BIT	(0x1 << 3)
 #define ADC_CFGR1_RES_8_BIT	(0x2 << 3)
 #define ADC_CFGR1_RES_6_BIT	(0x3 << 3)
-#define ADC_CFGR1_RES_MASK	(0x3 << 3)
+/**@}*/
 
-/* DMACFG: Direct memory access configuration */
+/** DMACFG: Direct memory access configuration */
 #define ADC_CFGR1_DMACFG		(1 << 1)
 
-/* DMAEN: Direct memory access enable */
+/** DMAEN: Direct memory access enable */
 #define ADC_CFGR1_DMAEN		(1 << 0)
 
+/**@}*/
+
+/* ADC_SMPR Values -----------------------------------------------------------*/
+/** @defgroup adc_smpr SMPR ADC sample time register
+@{*/
+
+/**@}*/
+
+/* ADC_CFGR2 Values -----------------------------------------------------------*/
+/** @defgroup adc_cfgr2 CFGR2 ADC configuration register 2
+@{*/
+
+/**@}*/
+
 /* ADC_TR1 Values ------------------------------------------------------------*/
+/** @defgroup adc_tr1 TR1 ADC watchdog threshold register 1
+@{*/
 
 #define ADC_TR1_LT_SHIFT		0
+#define ADC_TR1_LT_MASK			0xFFF
 #define ADC_TR1_LT			(0xFFF << ADC_TR1_LT_SHIFT)
+/** TR1_LT: analog watchdog 1 threshold low */
 #define ADC_TR1_LT_VAL(x)		((x) << ADC_TR1_LT_SHIFT)
 
 #define ADC_TR1_HT_SHIFT		16
+#define ADC_TR1_HT_MASK			0xFFF
 #define ADC_TR1_HT			(0xFFF << ADC_TR1_HT_SHIFT)
+/** TR1_HT: analog watchdog 1 threshold high */
 #define ADC_TR1_HT_VAL(x)		((x) << ADC_TR1_HT_SHIFT)
 
-
+/**@}*/
 
 /* ADC_CCR Values -----------------------------------------------------------*/
+/** @defgroup adc_ccr CCR ADC common configuration register
+@{*/
+
+/** VBATEN: Enable VBAT Channel */
 #define ADC_CCR_VBATEN			(1 << 24)
+
+/** TSEN: Enable Temperature Sensor */
 #define ADC_CCR_TSEN			(1 << 23)
+
+/** VREFEN: Enable internal Voltage Reference */
 #define ADC_CCR_VREFEN			(1 << 22)
 
+/**@}*/
 
 /* --- Function prototypes ------------------------------------------------- */
 
diff --git a/include/libopencm3/stm32/common/adc_common_v2_single.h b/include/libopencm3/stm32/common/adc_common_v2_single.h
index 1d6729d1..d2db6dce 100644
--- a/include/libopencm3/stm32/common/adc_common_v2_single.h
+++ b/include/libopencm3/stm32/common/adc_common_v2_single.h
@@ -48,22 +48,27 @@ specific memorymap.h header before including this header file.*/
 
 /* ----- ADC registers values -----------------------------------------------*/
 /* ADC_CFGR1 values */
+/** @addtogroup adc_cfgr1
+@{*/
 /** Wait conversion mode */
 #define ADC_CFGR1_WAIT		(1<<14)
 /** Auto off mode */
 #define ADC_CFGR1_AUTOFF		(1 << 15)
 
-/* EXTSEL[2:0]: External trigger selection for regular group */
 #define ADC_CFGR1_EXTSEL_SHIFT		6
 #define ADC_CFGR1_EXTSEL		(0x7 << ADC_CFGR1_EXTSEL_SHIFT)
+/** EXTSEL[2:0]: External trigger selection for regular group */
 #define ADC_CFGR1_EXTSEL_VAL(x)		((x) << ADC_CFGR1_EXTSEL_SHIFT)
 
+/** SCANDIR: Scan Sequence Direction: Upwards Scan (0), Downwards(1) */
 #define ADC_CFGR1_SCANDIR		(1 << 2)
+/**@}*/
 
 /* ADC_CHSELR Values --------------------------------------------------------*/
-
+/** @addtogroup adc_chselr
+@{*/
 #define ADC_CHSELR_CHSEL(x)		(1 << (x))
-
+/**@}*/
 
 /* --- Function prototypes ------------------------------------------------- */