From 2d1277e1fae9552d11499a1573ecad39d0147d99 Mon Sep 17 00:00:00 2001 From: Karl Palsson Date: Tue, 25 Jun 2019 12:06:47 +0000 Subject: [PATCH] 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 | 52 ++++++++++--------- .../libopencm3/efm32/common/usart_common.h | 10 ++-- include/libopencm3/efm32/ezr32wg/uart.h | 13 +++-- include/libopencm3/efm32/ezr32wg/usart.h | 13 +++-- include/libopencm3/efm32/lg/uart.h | 13 +++-- include/libopencm3/efm32/lg/usart.h | 13 +++-- include/libopencm3/efm32/wg/uart.h | 13 +++-- include/libopencm3/efm32/wg/usart.h | 13 +++-- lib/efm32/common/usart_common.c | 18 +++++++ lib/efm32/ezr32wg/Makefile | 1 + lib/efm32/lg/Makefile | 1 + lib/efm32/wg/Makefile | 1 + 12 files changed, 109 insertions(+), 52 deletions(-) create mode 100644 lib/efm32/common/usart_common.c 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 . */ -#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 -#include +#include + +/**@{*/ /* 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 . */ -#ifndef LIBOPENCM3_EFM32_USART_H -#define LIBOPENCM3_EFM32_USART_H +#pragma once #include #include +/**@{*/ + #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 Defined Constants and Types for the UART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_EZR32WG_UART_H -#define LIBOPENCM3_EFM32_EZR32WG_UART_H +#pragma once #include - -#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 Defined Constants and Types for the USART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_EZR32WG_USART_H -#define LIBOPENCM3_EFM32_EZR32WG_USART_H +#pragma once #include - -#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 Defined Constants and Types for the UART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_LG_UART_H -#define LIBOPENCM3_EFM32_LG_UART_H +#pragma once #include - -#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 Defined Constants and Types for the USART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_LG_USART_H -#define LIBOPENCM3_EFM32_LG_USART_H +#pragma once #include - -#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 Defined Constants and Types for the UART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_WG_UART_H -#define LIBOPENCM3_EFM32_WG_UART_H +#pragma once #include - -#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 Defined Constants and Types for the USART module + * + * @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 . */ -#ifndef LIBOPENCM3_EFM32_WG_USART_H -#define LIBOPENCM3_EFM32_WG_USART_H +#pragma once #include - -#endif diff --git a/lib/efm32/common/usart_common.c b/lib/efm32/common/usart_common.c new file mode 100644 index 00000000..ef49f42c --- /dev/null +++ b/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. + * + * NO 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 +#include + +/**@{*/ + +/**@}*/ + diff --git a/lib/efm32/ezr32wg/Makefile b/lib/efm32/ezr32wg/Makefile index 78ee2db1..28026b8c 100644 --- a/lib/efm32/ezr32wg/Makefile +++ b/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 diff --git a/lib/efm32/lg/Makefile b/lib/efm32/lg/Makefile index cf1e5bc9..da0ef81d 100644 --- a/lib/efm32/lg/Makefile +++ b/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 diff --git a/lib/efm32/wg/Makefile b/lib/efm32/wg/Makefile index ef4b264f..0df4b0b6 100644 --- a/lib/efm32/wg/Makefile +++ b/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