doc: efm32: uart/usart provide common doxygen

Fix some direct includes, tag properly, include a stub file to pull in
shared header documentation and re-arrange some existing documentation
to make it present nicely.

8 files changed, 88 insertions, 52 deletions

diff --git a/include/libopencm3/efm32/common/uart_common.h b/include/libopencm3/efm32/common/uart_common.h
index b69617ba..58b65aac 100644
--- a/include/libopencm3/efm32/common/uart_common.h
+++ b/include/libopencm3/efm32/common/uart_common.h
@@ -1,3 +1,26 @@
+/** @addtogroup uart_defines
+ *
+ * @brief UART registers are mostly equivalent to USART registers.
+ *
+ * USART and UART registers are equivalent except [in UART registers]:
+ *
+ *  * USART_CTRL: SYNC, CSMA, SMSDELAY, SSSEARLY, CSINV, CPOL and CPHA
+ *	(Synchronous operation not available)
+ *  * USART_STATUS: MASTEREN (Synchronous operation not available)
+ *  * USART_CTRL: MSBF (transmission LSB first only)
+ *  * USART_CTRL: AUTOCS (chip-select not available)
+ *  * USART_CTRL: SCMODE (SmartCard mode not available)
+ *  * USART_FRAME: DATABITS (limited framesize. 8-9 databits only)
+ *  * USART_IRCTRL: IREN (IrDA not available)
+ *   (except DATABITS, all the above are 0)
+ *
+ * full text: (p495, "d0183_Rev1.10" EFM32LG-RM)
+ *  - "18.3 Functional Description",
+ *  - "18.4 Register Description"
+ *  - "18.5 Register Map"
+ *
+ * use USART macro's to manipulate UART registers.
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,31 +40,12 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_UART_H
-#define LIBOPENCM3_EFM32_UART_H
+#pragma once
 
-/**
- * USART and UART registers are equivalent except [in UART registers]:
- *
- *  USART_CTRL: SYNC, CSMA, SMSDELAY, SSSEARLY, CSINV, CPOL and CPHA [1]
- *  USART_STATUS: MASTEREN [1]
- *   [1] Synchronous operation not available.
- *  USART_CTRL: MSBF (transmission LSB first only)
- *  USART_CTRL: AUTOCS (chip-select not available)
- *  USART_CTRL: SCMODE (SmartCard mode not available)
- *  USART_FRAME: DATABITS (limited framsize. 8-9 databits only)
- *  USART_IRCTRL: IREN (IrDA not available)
- *   (except DATABITS, all the above are 0)
- *
- * full text: (p495, "d0183_Rev1.10" EFM32LG-RM)
- *  - "18.3 Functional Description",
- *  - "18.4 Register Description"
- *  - "18.5 Register Map"
- *
- * use USART macro's to manipulate UART registers.
- */
 #include <libopencm3/efm32/memorymap.h>
-#include <libopencm3/efm32/lg/usart.h>
+#include <libopencm3/efm32/usart.h>
+
+/**@{*/
 
 /* UART0 */
 #define UART0				UART0_BASE
@@ -97,4 +101,4 @@
 #define UART1_INPUT			USART_INPUT(UART1)
 #define UART1_I2SCTRL		USART_I2SCTRL(UART1)
 
-#endif
+/**@}*/
\ No newline at end of file
diff --git a/include/libopencm3/efm32/common/usart_common.h b/include/libopencm3/efm32/common/usart_common.h
index b3b3f54b..84f88004 100644
--- a/include/libopencm3/efm32/common/usart_common.h
+++ b/include/libopencm3/efm32/common/usart_common.h
@@ -1,3 +1,5 @@
+/** @addtogroup usart_defines
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,12 +19,13 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_USART_H
-#define LIBOPENCM3_EFM32_USART_H
+#pragma once
 
 #include <libopencm3/efm32/memorymap.h>
 #include <libopencm3/cm3/common.h>
 
+/**@{*/
+
 #define USART_CTRL(base)		MMIO32((base) + 0x000)
 #define USART_FRAME(base)		MMIO32((base) + 0x004)
 #define USART_TRIGCTRL(base)		MMIO32((base) + 0x008)
@@ -508,5 +511,4 @@
 #define USART2_INPUT			USART_INPUT(USART2)
 #define USART2_I2SCTRL			USART_I2SCTRL(USART2)
 
-#endif
-
+/**@}*/
\ No newline at end of file
diff --git a/include/libopencm3/efm32/ezr32wg/uart.h b/include/libopencm3/efm32/ezr32wg/uart.h
index a012581b..6f4bf3e7 100644
--- a/include/libopencm3/efm32/ezr32wg/uart.h
+++ b/include/libopencm3/efm32/ezr32wg/uart.h
@@ -1,3 +1,11 @@
+/** @defgroup uart_defines UART Defines
+ *
+ * @brief <b>Defined Constants and Types for the UART module</b>
+ *
+ * @ingroup EZR32WG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_EZR32WG_UART_H
-#define LIBOPENCM3_EFM32_EZR32WG_UART_H
+#pragma once
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif
diff --git a/include/libopencm3/efm32/ezr32wg/usart.h b/include/libopencm3/efm32/ezr32wg/usart.h
index 07a80415..5db0aae2 100644
--- a/include/libopencm3/efm32/ezr32wg/usart.h
+++ b/include/libopencm3/efm32/ezr32wg/usart.h
@@ -1,3 +1,11 @@
+/** @defgroup usart_defines USART Defines
+ *
+ * @brief <b>Defined Constants and Types for the USART module</b>
+ *
+ * @ingroup EZR32WG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_EZR32WG_USART_H
-#define LIBOPENCM3_EFM32_EZR32WG_USART_H
+#pragma once
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif
diff --git a/include/libopencm3/efm32/lg/uart.h b/include/libopencm3/efm32/lg/uart.h
index 86b493fd..301a0754 100644
--- a/include/libopencm3/efm32/lg/uart.h
+++ b/include/libopencm3/efm32/lg/uart.h
@@ -1,3 +1,11 @@
+/** @defgroup uart_defines UART Defines
+ *
+ * @brief <b>Defined Constants and Types for the UART module</b>
+ *
+ * @ingroup EFM32LG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_LG_UART_H
-#define LIBOPENCM3_EFM32_LG_UART_H
+#pragma once
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif
diff --git a/include/libopencm3/efm32/lg/usart.h b/include/libopencm3/efm32/lg/usart.h
index 41c1ec1a..0a0a5254 100644
--- a/include/libopencm3/efm32/lg/usart.h
+++ b/include/libopencm3/efm32/lg/usart.h
@@ -1,3 +1,11 @@
+/** @defgroup usart_defines USART Defines
+ *
+ * @brief <b>Defined Constants and Types for the USART module</b>
+ *
+ * @ingroup EFM32LG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_LG_USART_H
-#define LIBOPENCM3_EFM32_LG_USART_H
+#pragma once
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif
diff --git a/include/libopencm3/efm32/wg/uart.h b/include/libopencm3/efm32/wg/uart.h
index 52c79f7b..b79d8c89 100644
--- a/include/libopencm3/efm32/wg/uart.h
+++ b/include/libopencm3/efm32/wg/uart.h
@@ -1,3 +1,11 @@
+/** @defgroup uart_defines UART Defines
+ *
+ * @brief <b>Defined Constants and Types for the UART module</b>
+ *
+ * @ingroup EFM32WG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_WG_UART_H
-#define LIBOPENCM3_EFM32_WG_UART_H
+#pragma once
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif
diff --git a/include/libopencm3/efm32/wg/usart.h b/include/libopencm3/efm32/wg/usart.h
index 149842d7..edba183d 100644
--- a/include/libopencm3/efm32/wg/usart.h
+++ b/include/libopencm3/efm32/wg/usart.h
@@ -1,3 +1,11 @@
+/** @defgroup usart_defines USART Defines
+ *
+ * @brief <b>Defined Constants and Types for the USART module</b>
+ *
+ * @ingroup EFM32WG_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,9 +25,6 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LIBOPENCM3_EFM32_WG_USART_H
-#define LIBOPENCM3_EFM32_WG_USART_H
+#pragma once
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif