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.

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
+#pragma once
-#define LIBOPENCM3_EFM32_UART_H
 
-/**
- * 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
+/**@}*/

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
+#pragma once
-#define LIBOPENCM3_EFM32_USART_H
 
 #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
+/**@}*/
-

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
+#pragma once
-#define LIBOPENCM3_EFM32_EZR32WG_UART_H
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif

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
+#pragma once
-#define LIBOPENCM3_EFM32_EZR32WG_USART_H
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif

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
+#pragma once
-#define LIBOPENCM3_EFM32_LG_UART_H
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif

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
+#pragma once
-#define LIBOPENCM3_EFM32_LG_USART_H
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif

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
+#pragma once
-#define LIBOPENCM3_EFM32_WG_UART_H
 
 #include <libopencm3/efm32/common/uart_common.h>
-
-#endif

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
+#pragma once
-#define LIBOPENCM3_EFM32_WG_USART_H
 
 #include <libopencm3/efm32/common/usart_common.h>
-
-#endif

lib/efm32/common/usart_common.c

@@ -0,0 +1,18 @@
+/** @addtogroup usart_file UART/USART peripheral API
+ * @ingroup peripheral_apis
+ * @brief UART/USART helper functions.
+ *
+ * <b>NO</b> helper functions exist. Only header definitions are available.
+ * Delete these lines if/when you add actual helper APIs.
+ * @sa usart_defines
+ * @sa uart_defines
+ * @copyright See @ref lgpl_license
+ */
+
+#include <libopencm3/efm32/uart.h>
+#include <libopencm3/efm32/usart.h>
+
+/**@{*/
+
+/**@}*/
+

lib/efm32/ezr32wg/Makefile

@@ -52,6 +52,7 @@ OBJS += prs_common.o
 OBJS += rmu_common.o
 OBJS += rtc_common.o
 OBJS += timer_common.o
+OBJS += usart_common.o
 OBJS += wdog_common.o
 
 OBJS += usb.o usb_control.o usb_standard.o usb_msc.o

lib/efm32/lg/Makefile

@@ -52,6 +52,7 @@ OBJS += prs_common.o
 OBJS += rmu_common.o
 OBJS += rtc_common.o
 OBJS += timer_common.o
+OBJS += usart_common.o
 OBJS += wdog_common.o
 
 OBJS += usb.o usb_control.o usb_standard.o usb_msc.o

lib/efm32/wg/Makefile

@@ -52,6 +52,7 @@ OBJS += prs_common.o
 OBJS += rmu_common.o
 OBJS += rtc_common.o
 OBJS += timer_common.o
+OBJS += usart_common.o
 OBJS += wdog_common.o
 
 OBJS += usb.o usb_control.o usb_standard.o usb_msc.o