From 4fe5103851f2290ea97a8db7de00045d06ccae77 Mon Sep 17 00:00:00 2001 From: Karl Palsson Date: Sun, 24 Jan 2021 22:08:20 +0000 Subject: [PATCH] stm32: dac: doxygenize the registers and values Not 100% complete, but far closer, mostly just tagging the existing information properly to get it included. --- .../libopencm3/stm32/common/dac_common_all.h | 93 ++++++++++++------- .../libopencm3/stm32/common/dac_common_v1.h | 7 +- .../libopencm3/stm32/common/dac_common_v2.h | 87 ++++++++++------- 3 files changed, 116 insertions(+), 71 deletions(-) diff --git a/include/libopencm3/stm32/common/dac_common_all.h b/include/libopencm3/stm32/common/dac_common_all.h index fc3ca40c..c93b9dbc 100644 --- a/include/libopencm3/stm32/common/dac_common_all.h +++ b/include/libopencm3/stm32/common/dac_common_all.h @@ -39,45 +39,46 @@ specific memorymap.h header before including this header file.*/ #ifndef LIBOPENCM3_DAC_COMMON_ALL_H #define LIBOPENCM3_DAC_COMMON_ALL_H -/* --- DAC registers ------------------------------------------------------- */ +/**@defgroup dac_registers DAC Registers + @{*/ -/* DAC control register (DAC_CR) */ +/** DAC control register (DAC_CR) */ #define DAC_CR(dac) MMIO32((dac) + 0x00) -/* DAC software trigger register (DAC_SWTRIGR) */ +/** DAC software trigger register (DAC_SWTRIGR) */ #define DAC_SWTRIGR(dac) MMIO32((dac) + 0x04) -/* DAC channel1 12-bit right-aligned data holding register (DAC_DHR12R1) */ +/** DAC channel1 12-bit right-aligned data holding register (DAC_DHR12R1) */ #define DAC_DHR12R1(dac) MMIO32((dac) + 0x08) -/* DAC channel1 12-bit left aligned data holding register (DAC_DHR12L1) */ +/** DAC channel1 12-bit left aligned data holding register (DAC_DHR12L1) */ #define DAC_DHR12L1(dac) MMIO32((dac) + 0x0C) -/* DAC channel1 8-bit right aligned data holding register (DAC_DHR8R1) */ +/** DAC channel1 8-bit right aligned data holding register (DAC_DHR8R1) */ #define DAC_DHR8R1(dac) MMIO32((dac) + 0x10) -/* DAC channel2 12-bit right aligned data holding register (DAC_DHR12R2) */ +/** DAC channel2 12-bit right aligned data holding register (DAC_DHR12R2) */ #define DAC_DHR12R2(dac) MMIO32((dac) + 0x14) -/* DAC channel2 12-bit left aligned data holding register (DAC_DHR12L2) */ +/** DAC channel2 12-bit left aligned data holding register (DAC_DHR12L2) */ #define DAC_DHR12L2(dac) MMIO32((dac) + 0x18) -/* DAC channel2 8-bit right-aligned data holding register (DAC_DHR8R2) */ +/** DAC channel2 8-bit right-aligned data holding register (DAC_DHR8R2) */ #define DAC_DHR8R2(dac) MMIO32((dac) + 0x1C) -/* Dual DAC 12-bit right-aligned data holding register (DAC_DHR12RD) */ +/** Dual DAC 12-bit right-aligned data holding register (DAC_DHR12RD) */ #define DAC_DHR12RD(dac) MMIO32((dac) + 0x20) -/* DUAL DAC 12-bit left aligned data holding register (DAC_DHR12LD) */ +/** DUAL DAC 12-bit left aligned data holding register (DAC_DHR12LD) */ #define DAC_DHR12LD(dac) MMIO32((dac) + 0x24) -/* DUAL DAC 8-bit right aligned data holding register (DAC_DHR8RD) */ +/** DUAL DAC 8-bit right aligned data holding register (DAC_DHR8RD) */ #define DAC_DHR8RD(dac) MMIO32((dac) + 0x28) -/* DAC channel1 data output register (DAC_DOR1) */ +/** DAC channel1 data output register (DAC_DOR1) */ #define DAC_DOR1(dac) MMIO32((dac) + 0x2C) -/* DAC channel2 data output register (DAC_DOR2) */ +/** DAC channel2 data output register (DAC_DOR2) */ #define DAC_DOR2(dac) MMIO32((dac) + 0x30) /** DAC status register. @@ -85,52 +86,63 @@ specific memorymap.h header before including this header file.*/ */ #define DAC_SR(dac) MMIO32((dac) + 0x34) -/* --- DAC_CR values ------------------------------------------------------- */ +/**@}*/ -/* DMAUDRIE2: DAC channel2 DMA underrun interrupt enable */ -/* doesn't exist in most members of the STM32F1 family */ +/** @defgroup dac_cr_values DAC_CR values + * @{ + */ + +/** DMAUDRIE2: DAC channel2 DMA underrun interrupt enable + * @note doesn't exist in most members of the STM32F1 family + */ #define DAC_CR_DMAUDRIE2 (1 << 29) -/* DMAEN2: DAC channel2 DMA enable */ +/** DMAEN2: DAC channel2 DMA enable */ #define DAC_CR_DMAEN2 (1 << 28) -/* MAMP2[3:0]: DAC channel2 mask/amplitude selector */ +/** MAMP2[3:0]: DAC channel2 mask/amplitude selector */ #define DAC_CR_MAMP2_SHIFT 24 -/* WAVE2[1:0]: DAC channel2 noise/triangle wave generation enable */ +/** WAVE2[1:0]: DAC channel2 noise/triangle wave generation enable */ #define DAC_CR_WAVE2_SHIFT 22 #define DAC_CR_WAVE2_MASK 0x3 -/* EN2: DAC channel2 enable */ +/** EN2: DAC channel2 enable */ #define DAC_CR_EN2 (1 << 16) -/* DMAUDRIE1: DAC channel1 DMA underrun interrupt enable */ -/* doesn't exist in most members of the STM32F1 family */ +/** DMAUDRIE1: DAC channel1 DMA underrun interrupt enable + * @note doesn't exist in most members of the STM32F1 family + */ #define DAC_CR_DMAUDRIE1 (1 << 13) -/* DMAEN1: DAC channel1 DMA enable */ +/** DMAEN1: DAC channel1 DMA enable */ #define DAC_CR_DMAEN1 (1 << 12) -/* MAMP1[3:0]: DAC channel1 mask/amplitude selector */ +/** MAMP1[3:0]: DAC channel1 mask/amplitude selector */ #define DAC_CR_MAMP1_SHIFT 8 -/* WAVEn[1:0]: DAC channel1 noise/triangle wave generation enable */ +/** WAVEn[1:0]: DAC channel1 noise/triangle wave generation enable */ #define DAC_CR_WAVE1_SHIFT 6 #define DAC_CR_WAVE1_MASK 0x3 -/* EN1: DAC channel1 enable */ +/** EN1: DAC channel1 enable */ #define DAC_CR_EN1 (1 << 0) +/**@}*/ - -/* --- DAC_SWTRIGR values -------------------------------------------------- */ - -/* SWTRIG2: DAC channel2 software trigger */ +/**@defgroup dac_swtrigr_values DAC_SWTRIGR Values + * @{ + */ +/** SWTRIG2: DAC channel2 software trigger */ #define DAC_SWTRIGR_SWTRIG2 (1 << 1) -/* SWTRIG1: DAC channel1 software trigger */ +/** SWTRIG1: DAC channel1 software trigger */ #define DAC_SWTRIGR_SWTRIG1 (1 << 0) +/**@}*/ +/**@defgroup dac_dhrxxx_values DAC_DHRxxx Values + * @{ + */ /* --- DAC_DHR12R1 values -------------------------------------------------- */ #define DAC_DHR12R1_DACC1DHR_SHIFT 0 #define DAC_DHR12R1_DACC1DHR_MASK 0xFFF @@ -180,8 +192,12 @@ specific memorymap.h header before including this header file.*/ #define DAC_DHR8RD_DACC2DHR_MSK 0xFF #define DAC_DHR8RD_DACC1DHR_SHIFT 0 #define DAC_DHR8RD_DACC1DHR_MSK 0xFF +/**@}*/ +/**@defgroup dac_dorx_values DAC_DORx Values + * @{ + */ /* --- DAC_DOR1 values ----------------------------------------------------- */ #define DAC_DOR1_DACC1DOR_SHIFT 0 #define DAC_DOR1_DACC1DOR_MSK 0xFFF @@ -191,20 +207,27 @@ specific memorymap.h header before including this header file.*/ #define DAC_DOR2_DACC2DOR_SHIFT 0 #define DAC_DOR2_DACC2DOR_MSK 0xFFF -/* --- DAC_SR values ------------------------------------------------------- */ +/**@}*/ +/**@defgroup dac_sr_values DAC_SR Values + * @{ + */ /** DAC channel 1 DMA underrun flag */ #define DAC_SR_DMAUDR1 (1 << 13) /** DAC channel 2 DMA underrun flag */ #define DAC_SR_DMAUDR2 (1 << 29) +/**@}*/ /* --- Function prototypes ------------------------------------------------- */ -/** DAC channel identifier */ +/** @defgroup dac_channel_id DAC Channel Identifier + * @{ + */ #define DAC_CHANNEL1 (1 << 0) #define DAC_CHANNEL2 (1 << 1) #define DAC_CHANNEL_BOTH (DAC_CHANNEL1 | DAC_CHANNEL2) +/**@}*/ /** DAC data size (8/12 bits), alignment (right/left) */ enum dac_align { @@ -213,7 +236,7 @@ enum dac_align { DAC_ALIGN_LEFT12, }; -/* DAC waveform generation options. */ +/** DAC waveform generation options. */ enum dac_wave { DAC_WAVE_DISABLE = 0, DAC_WAVE_NOISE = 1, diff --git a/include/libopencm3/stm32/common/dac_common_v1.h b/include/libopencm3/stm32/common/dac_common_v1.h index 38101fb0..c915a5c6 100644 --- a/include/libopencm3/stm32/common/dac_common_v1.h +++ b/include/libopencm3/stm32/common/dac_common_v1.h @@ -38,9 +38,11 @@ specific memorymap.h header before including this header file.*/ #include -/* --- DAC_CR values ------------------------------------------------------- */ +/**@addtogroup dac_cr_values + * @{ + */ -/* TSEL2[2:0]: DAC channel2 trigger selection */ +/** TSEL2[2:0]: DAC channel2 trigger selection */ #define DAC_CR_TSEL2_SHIFT 19 /** @defgroup dac_trig2_sel DAC Channel 2 Trigger Source Selection @ingroup dac_defines @@ -118,6 +120,7 @@ specific memorymap.h header before including this header file.*/ /* BOFF1: DAC channel1 output buffer disable */ #define DAC_CR_BOFF1 (1 << 1) +/**@}*/ /* --- Function prototypes ------------------------------------------------- */ diff --git a/include/libopencm3/stm32/common/dac_common_v2.h b/include/libopencm3/stm32/common/dac_common_v2.h index cc5453eb..ff3f95f1 100644 --- a/include/libopencm3/stm32/common/dac_common_v2.h +++ b/include/libopencm3/stm32/common/dac_common_v2.h @@ -38,38 +38,42 @@ specific memorymap.h header before including this header file.*/ #include -/* --- DAC registers ------------------------------------------------------- */ +/**@addtogroup dac_registers + @{*/ -/* DAC calibration control register (DAC_CCR) */ +/** DAC calibration control register (DAC_CCR) */ #define DAC_CCR(dac) MMIO32((dac) + 0x38) -/* DAC mode control register (DAC_MCR) */ +/** DAC mode control register (DAC_MCR) */ #define DAC_MCR(dac) MMIO32((dac) + 0x3C) -/* DAC channel1 sample and hold sample time register (DAC_SHSR1) */ +/** DAC channel1 sample and hold sample time register (DAC_SHSR1) */ #define DAC_SHSR1(dac) MMIO32((dac) + 0x40) -/* DAC channel2 sample and hold sample time register (DAC_SHSR2) */ +/** DAC channel2 sample and hold sample time register (DAC_SHSR2) */ #define DAC_SHSR2(dac) MMIO32((dac) + 0x44) -/* DAC sample and hold time register (DAC_SHHR) */ +/** DAC sample and hold time register (DAC_SHHR) */ #define DAC_SHHR(dac) MMIO32((dac) + 0x48) -/* DAC sample and hold refresh time register (DAC_SHRR) */ +/** DAC sample and hold refresh time register (DAC_SHRR) */ #define DAC_SHRR(dac) MMIO32((dac) + 0x4C) -/* DAC channel1 sawtooth register (DAC_STR1) */ +/** DAC channel1 sawtooth register (DAC_STR1) */ #define DAC_STR1(dac) MMIO32((dac) + 0x58) -/* DAC channel2 sawtooth register (DAC_STR2) */ +/** DAC channel2 sawtooth register (DAC_STR2) */ #define DAC_STR2(dac) MMIO32((dac) + 0x5C) -/* DAC sawtooth mode register (DAC_STMODR) */ +/** DAC sawtooth mode register (DAC_STMODR) */ #define DAC_STMODR(dac) MMIO32((dac) + 0x60) +/**@}*/ -/* --- DAC_CR values ------------------------------------------------------- */ +/**@addtogroup dac_cr_values + * @{ + */ -/* CEN2: DAC channel2 calibration enable */ +/** CEN2: DAC channel2 calibration enable */ #define DAC_CR_CEN2 (1 << 30) /* TSEL2[3:0]: DAC channel2 trigger selection */ @@ -162,19 +166,24 @@ specific memorymap.h header before including this header file.*/ #define DAC_CR_TSEL1_HR3 (0xF << DAC_CR_TSEL1_SHIFT) /**@}*/ -/* TEN1: DAC channel1 trigger enable */ +/** TEN1: DAC channel1 trigger enable */ #define DAC_CR_TEN1 (1 << 1) +/**@}*/ -/* --- DAC_SWTRIGR values -------------------------------------------------- */ - -/* SWTRIG2: DAC channel2 software trigger B */ +/** @addtogroup dac_swtrigr_values + * @{ + */ +/** SWTRIG2: DAC channel2 software trigger B */ #define DAC_SWTRIGR_SWTRIGB2 (1 << 17) -/* SWTRIG1: DAC channel1 software trigger B */ +/** SWTRIG1: DAC channel1 software trigger B */ #define DAC_SWTRIGR_SWTRIGB1 (1 << 16) +/**@}*/ - +/** @addtogroup dac_dorx_values + * @{ + */ /* --- DAC_DOR1 values ----------------------------------------------------- */ #define DAC_DOR1_DACC1DORB_SHIFT 16 #define DAC_DOR1_DACC1DORB_MASK 0xFFF @@ -183,41 +192,46 @@ specific memorymap.h header before including this header file.*/ /* --- DAC_DOR2 values ----------------------------------------------------- */ #define DAC_DOR2_DACC2DORB_SHIFT 16 #define DAC_DOR2_DACC2DORB_MASK 0xFFF +/**@}*/ -/* --- DAC_SR values ----------------------------------------------------- */ - -/* DAC channel2 busy writing sample time flag */ +/** @addtogroup dac_sr_values + * @{ + */ +/** DAC channel2 busy writing sample time flag */ #define DAC_SR_BWST2 (1 << 31) -/* DAC channel2 calibration offset status */ +/** DAC channel2 calibration offset status */ #define DAC_SR_CAL_FLAG2 (1 << 30) /** DAC channel2 DMA underrun flag */ #define DAC_SR_DMAUDR2 (1 << 29) -/* DAC channel2 output register status bit */ +/** DAC channel2 output register status bit */ #define DAC_SR_DORSTAT2 (1 << 28) -/* DAC channel2 ready status bit */ +/** DAC channel2 ready status bit */ #define DAC_SR_DAC2RDY (1 << 27) -/* DAC channel1 busy writing sample time flag */ +/** DAC channel1 busy writing sample time flag */ #define DAC_SR_BWST1 (1 << 15) -/* DAC channel1 calibration offset status */ +/** DAC channel1 calibration offset status */ #define DAC_SR_CAL_FLAG1 (1 << 14) /** DAC channel1 DMA underrun flag */ #define DAC_SR_DMAUDR1 (1 << 13) -/* DAC channel1 output register status bit */ +/** DAC channel1 output register status bit */ #define DAC_SR_DORSTAT1 (1 << 12) -/* DAC channel1 ready status bit */ +/** DAC channel1 ready status bit */ #define DAC_SR_DAC1RDY (1 << 11) +/**@}*/ -/* --- DAC_CCR values ----------------------------------------------------- */ +/**@defgroup dac_ccr_values DAC_CCR values + * @{ + */ /* DAC channel2 offset trimming value */ #define DAC_CCR_OTRIM2_SHIFT 16 #define DAC_CCR_OTRIM2_MASK 0x1F @@ -225,16 +239,20 @@ specific memorymap.h header before including this header file.*/ /* DAC channel1 offset trimming value */ #define DAC_CCR_OTRIM1_SHIFT 0 #define DAC_CCR_OTRIM1_MASK 0x1F +/**@}*/ /* --- DAC_MCR values ----------------------------------------------------- */ -/* Enable signed format for DAC channel2 */ +/**@defgroup dac_mcr_values DAC_MCR values + * @{ + */ +/** Enable signed format for DAC channel2 */ #define DAC_MCR_SINFORMAT2 (1 << 25) -/* DAC channel2 DMA double data mode */ +/** DAC channel2 DMA double data mode */ #define DAC_MCR_DMADOUBLE2 (1 << 24) -/* MODE2[2:0]: DAC channel2 mode */ +/** MODE2[2:0]: DAC channel2 mode */ #define DAC_MCR_MODE2_SHIFT 16 /** @defgroup dac_mode2_sel DAC Channel 2 Mode Selection @ingroup dac_defines @@ -277,10 +295,10 @@ specific memorymap.h header before including this header file.*/ #define DAC_MCR_HFSEL_AHB160 (0x2 << DAC_MCR_HFSEL_SHIFT) /**@}*/ -/* Enable signed format for DAC channel1 */ +/** Enable signed format for DAC channel1 */ #define DAC_MCR_SINFORMAT1 (1 << 9) -/* DAC channel1 DMA double data mode */ +/** DAC channel1 DMA double data mode */ #define DAC_MCR_DMADOUBLE1 (1 << 8) /* MODE1[2:0]: DAC channel1 mode */ @@ -310,6 +328,7 @@ specific memorymap.h header before including this header file.*/ #define DAC_MCR_MODE1_PERIPHERAL (0x1 << DAC_MCR_MODE1_SHIFT) #define DAC_MCR_MODE1_UNBUFFERED (0x2 << DAC_MCR_MODE1_SHIFT) #define DAC_MCR_MODE1_SAMPLEHOLD (0x4 << DAC_MCR_MODE1_SHIFT) +/**@}*/ /* --- DAC_SHSR1 values ----------------------------------------------------- */