[FIXME] Resurrected, shinier USART support.

FIXME:
- Test F1 support
- Solve problem of duplicated bytes being TXed unless delay is
  inserted after configuration but before first bytes are TXed.

Rip out nonportable bits from top-level interfaces. The USART register
maps are basically the same between F1 and F2, so leave these, but add
register bit definitions which had name changes to the libmaple header
to avoid needless repetition. There are also a few new bits in the F2
USART registers; add definitions for these in the F2 USART header. Add
Doxygen comments for all USART bit definitions.

Deprecate struct usart_dev's max_baud field. This is just bloat that
doesn't bring us much real benefit.

Add new series-specific USART files for F1 and F2:

- libmaple/stm32f[1,2]/usart.c
- libmaple/stm32f[1,2]/include/series/usart.h

These are standard series-specific files, providing register map base
pointers, defining devices, implementing nonportable routines, etc.

We need a portable way to configure the USART GPIOs. To this end, add
usart_async_gpio_cfg() to the top-level USART interface. This function
is implemented in new F1 and F2 USART backends to take the appropriate
action to configure the RX and TX pins for asynchronous full duplex
mode.

USART baud rate calculation is done differently on the different
series. Keep the usart_set_baud_rate() declaration in the top-level
USART header, but move the implementations into the series-specific
usart.c files.

In usart_set_baud_rate(), allow for deriving clock_speed automatically
by letting user tell us to figure out the peripheral clock speed by
mapping the device's rcc_clk_id onto an STM32_PCLK[1,2] value. This
preserves flexibility for users with non-default clock configurations,
but makes things easier on everyone else.

Add private USART files for portable private USART routines:

- libmaple/usart_private.h
- libmaple/usart_private.c

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 189 insertions, 40 deletions

diff --git a/libmaple/include/libmaple/usart.h b/libmaple/include/libmaple/usart.h
index f9bdb8b..42f9576 100644
--- a/libmaple/include/libmaple/usart.h
+++ b/libmaple/include/libmaple/usart.h
@@ -43,9 +43,10 @@ extern "C"{
 #include <libmaple/rcc.h>
 #include <libmaple/nvic.h>
 #include <libmaple/ring_buffer.h>
+#include <series/usart.h>
 
 /*
- * Register maps and devices
+ * Register map (common across supported STM32 series).
  */
 
 /** USART register map type */
@@ -59,169 +60,315 @@ typedef struct usart_reg_map {
     __io uint32 GTPR;           /**< Guard time and prescaler register */
 } usart_reg_map;
 
-/** USART1 register map base pointer */
-#define USART1_BASE                     ((struct usart_reg_map*)0x40013800)
-/** USART2 register map base pointer */
-#define USART2_BASE                     ((struct usart_reg_map*)0x40004400)
-/** USART3 register map base pointer */
-#define USART3_BASE                     ((struct usart_reg_map*)0x40004800)
-#ifdef STM32_HIGH_DENSITY
-/** UART4 register map base pointer */
-#define UART4_BASE                      ((struct usart_reg_map*)0x40004C00)
-/** UART5 register map base pointer */
-#define UART5_BASE                      ((struct usart_reg_map*)0x40005000)
-#endif
-
 /*
  * Register bit definitions
  */
 
 /* Status register */
 
+/** Clear to send bit */
 #define USART_SR_CTS_BIT                9
+/** Line break detection bit */
 #define USART_SR_LBD_BIT                8
+/** Transmit data register empty bit */
 #define USART_SR_TXE_BIT                7
+/** Transmission complete bit */
 #define USART_SR_TC_BIT                 6
+/** Read data register not empty bit */
 #define USART_SR_RXNE_BIT               5
+/** IDLE line detected bit */
 #define USART_SR_IDLE_BIT               4
+/** Overrun error bit */
 #define USART_SR_ORE_BIT                3
+/** Noise error bit */
 #define USART_SR_NE_BIT                 2
+/**
+ * @brief Synonym for USART_SR_NE_BIT.
+ *
+ * Some series (e.g. STM32F2) use "NF" for "noise flag" instead of the
+ * original "NE" for "noise error". The meaning of the bit is
+ * unchanged, but the NF flag can be disabled when the line is
+ * noise-free.
+ *
+ * @see USART_SR_NE_BIT
+ */
+#define USART_SR_NF_BIT                 USART_SR_NE_BIT
+/** Framing error bit */
 #define USART_SR_FE_BIT                 1
+/** Parity error bit */
 #define USART_SR_PE_BIT                 0
 
+/** Clear to send mask */
 #define USART_SR_CTS                    BIT(USART_SR_CTS_BIT)
+/** Line break detected mask */
 #define USART_SR_LBD                    BIT(USART_SR_LBD_BIT)
+/** Transmit data register empty mask */
 #define USART_SR_TXE                    BIT(USART_SR_TXE_BIT)
+/** Transmission complete mask */
 #define USART_SR_TC                     BIT(USART_SR_TC_BIT)
+/** Read data register not empty mask */
 #define USART_SR_RXNE                   BIT(USART_SR_RXNE_BIT)
+/** IDLE line detected mask */
 #define USART_SR_IDLE                   BIT(USART_SR_IDLE_BIT)
+/** Overrun error mask */
 #define USART_SR_ORE                    BIT(USART_SR_ORE_BIT)
+/** Noise error mask */
 #define USART_SR_NE                     BIT(USART_SR_NE_BIT)
+/**
+ * @brief Synonym for USART_SR_NE.
+ * @see USART_SR_NF_BIT
+ */
+#define USART_SR_NF                     USART_SR_NE
+/** Framing error mask */
 #define USART_SR_FE                     BIT(USART_SR_FE_BIT)
+/** Parity error mask */
 #define USART_SR_PE                     BIT(USART_SR_PE_BIT)
 
 /* Data register */
 
+/** Data register data value mask */
 #define USART_DR_DR                     0xFF
 
 /* Baud rate register */
 
+/** Mantissa of USARTDIV mask */
 #define USART_BRR_DIV_MANTISSA          (0xFFF << 4)
+/** Fraction of USARTDIV mask */
 #define USART_BRR_DIV_FRACTION          0xF
 
 /* Control register 1 */
 
+/** USART enable bit */
 #define USART_CR1_UE_BIT                13
+/** Word length bit */
 #define USART_CR1_M_BIT                 12
+/** Wakeup method bit */
 #define USART_CR1_WAKE_BIT              11
+/** Parity control enable bit */
 #define USART_CR1_PCE_BIT               10
+/** Parity selection bit */
 #define USART_CR1_PS_BIT                9
+/** Parity error interrupt enable bit */
 #define USART_CR1_PEIE_BIT              8
+/** Transmit data regsiter not empty interrupt enable bit */
 #define USART_CR1_TXEIE_BIT             7
+/** Transmission complete interrupt enable bit */
 #define USART_CR1_TCIE_BIT              6
+/** RXNE interrupt enable bit */
 #define USART_CR1_RXNEIE_BIT            5
+/** IDLE interrupt enable bit */
 #define USART_CR1_IDLEIE_BIT            4
+/** Transmitter enable bit */
 #define USART_CR1_TE_BIT                3
+/** Receiver enable bit */
 #define USART_CR1_RE_BIT                2
+/** Receiver wakeup bit */
 #define USART_CR1_RWU_BIT               1
+/** Send break bit */
 #define USART_CR1_SBK_BIT               0
 
+/** USART enable mask */
 #define USART_CR1_UE                    BIT(USART_CR1_UE_BIT)
+/** Word length mask */
 #define USART_CR1_M                     BIT(USART_CR1_M_BIT)
+/** Word length: 1 start bit, 8 data bits, n stop bit */
+#define USART_CR1_M_8N1                 (0 << USART_CR1_M_BIT)
+/** Word length: 1 start bit, 9 data bits, n stop bit */
+#define USART_CR1_M_9N1                 (1 << USART_CR1_M_BIT)
+/** Wakeup method mask */
 #define USART_CR1_WAKE                  BIT(USART_CR1_WAKE_BIT)
+/** Wakeup on idle line */
 #define USART_CR1_WAKE_IDLE             (0 << USART_CR1_WAKE_BIT)
+/** Wakeup on address mark */
 #define USART_CR1_WAKE_ADDR             (1 << USART_CR1_WAKE_BIT)
+/** Parity control enable mask */
 #define USART_CR1_PCE                   BIT(USART_CR1_PCE_BIT)
+/** Parity selection mask */
 #define USART_CR1_PS                    BIT(USART_CR1_PS_BIT)
+/** Parity selection: even parity */
 #define USART_CR1_PS_EVEN               (0 << USART_CR1_PS_BIT)
+/** Parity selection: odd parity */
 #define USART_CR1_PS_ODD                (1 << USART_CR1_PS_BIT)
+/** Parity error interrupt enable mask */
 #define USART_CR1_PEIE                  BIT(USART_CR1_PEIE_BIT)
+/** Transmit data register empty interrupt enable mask */
 #define USART_CR1_TXEIE                 BIT(USART_CR1_TXEIE_BIT)
+/** Transmission complete interrupt enable mask */
 #define USART_CR1_TCIE                  BIT(USART_CR1_TCIE_BIT)
+/** RXNE interrupt enable mask */
 #define USART_CR1_RXNEIE                BIT(USART_CR1_RXNEIE_BIT)
+/** IDLE line interrupt enable mask */
 #define USART_CR1_IDLEIE                BIT(USART_CR1_IDLEIE_BIT)
+/** Transmitter enable mask */
 #define USART_CR1_TE                    BIT(USART_CR1_TE_BIT)
+/** Receiver enable mask */
 #define USART_CR1_RE                    BIT(USART_CR1_RE_BIT)
+/** Receiver wakeup mask */
 #define USART_CR1_RWU                   BIT(USART_CR1_RWU_BIT)
+/** Receiver wakeup: receiver in active mode */
 #define USART_CR1_RWU_ACTIVE            (0 << USART_CR1_RWU_BIT)
+/** Receiver wakeup: receiver in mute mode */
 #define USART_CR1_RWU_MUTE              (1 << USART_CR1_RWU_BIT)
+/** Send break */
 #define USART_CR1_SBK                   BIT(USART_CR1_SBK_BIT)
 
 /* Control register 2 */
 
+/** LIN mode enable bit */
 #define USART_CR2_LINEN_BIT             14
+/** Clock enable bit */
 #define USART_CR2_CLKEN_BIT             11
+/** Clock polarity bit */
 #define USART_CR2_CPOL_BIT              10
+/** Clock phase bit */
 #define USART_CR2_CPHA_BIT              9
+/** Last bit clock pulse bit */
 #define USART_CR2_LBCL_BIT              8
+/** LIN break detection interrupt enable bit */
 #define USART_CR2_LBDIE_BIT             6
+/** LIN break detection length bit */
 #define USART_CR2_LBDL_BIT              5
 
+/** LIN mode enable mask */
 #define USART_CR2_LINEN                 BIT(USART_CR2_LINEN_BIT)
+/** STOP bits mask */
 #define USART_CR2_STOP                  (0x3 << 12)
+/** STOP bits: 1 stop bit */
 #define USART_CR2_STOP_BITS_1           (0x0 << 12)
-/* Not on UART4, UART5 */
+/**
+ * @brief STOP bits: 0.5 stop bits
+ * Not available  on UART4, UART5. */
 #define USART_CR2_STOP_BITS_POINT_5     (0x1 << 12)
-/* Not on UART4, UART5 */
-#define USART_CR2_STOP_BITS_1_POINT_5   (0x3 << 12)
+/** STOP bits: 2 stop bits */
 #define USART_CR2_STOP_BITS_2           (0x2 << 12)
+/**
+ * @brief STOP bits: 1.5 stop bits
+ * Not available  on UART4, UART5. */
+#define USART_CR2_STOP_BITS_1_POINT_5   (0x3 << 12)
+/**
+ * @brief Clock enable.
+ * Not available on UART4, UART5 */
 #define USART_CR2_CLKEN                 BIT(USART_CR2_CLKEN_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Clock polarity mask.
+ * Not available on UART4, UART5 */
 #define USART_CR2_CPOL                  BIT(USART_CR2_CPOL_BIT)
+/** Clock polarity: low */
 #define USART_CR2_CPOL_LOW              (0x0 << USART_CR2_CLKEN_BIT)
+/** Clock polarity: high */
 #define USART_CR2_CPOL_HIGH             (0x1 << USART_CR2_CLKEN_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Clock phase mask.
+ * Not available on UART4, UART5 */
 #define USART_CR2_CPHA                  BIT(USART_CR2_CPHA_BIT)
+/**
+ * @brief Clock phase: first
+ * First clock transition is the first data capture edge. */
 #define USART_CR2_CPHA_FIRST            (0x0 << USART_CR2_CPHA_BIT)
+/**
+ * @brief Clock phase: second
+ * Second clock transition is the first data capture edge. */
 #define USART_CR2_CPHA_SECOND           (0x1 << USART_CR2_CPHA_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Last bit clock pulse mask.
+ *
+ * When set, the last bit transmitted causes a clock pulse in
+ * synchronous mode.
+ *
+ * Not available on UART4, UART5 */
 #define USART_CR2_LBCL                  BIT(USART_CR2_LBCL_BIT)
+/** LIN break detection interrupt enable mask. */
 #define USART_CR2_LBDIE                 BIT(USART_CR2_LBDIE_BIT)
+/** LIN break detection length. */
 #define USART_CR2_LBDL                  BIT(USART_CR2_LBDL_BIT)
+/** LIN break detection length: 10 bits */
 #define USART_CR2_LBDL_10_BIT           (0 << USART_CR2_LBDL_BIT)
+/** LIN break detection length: 11 bits */
 #define USART_CR2_LBDL_11_BIT           (1 << USART_CR2_LBDL_BIT)
+/**
+ * @brief Address of the USART node
+ * This is useful during multiprocessor communication. */
 #define USART_CR2_ADD                   0xF
 
 /* Control register 3 */
 
+/** Clear to send interrupt enable bit */
 #define USART_CR3_CTSIE_BIT             10
+/** Clear to send enable bit */
 #define USART_CR3_CTSE_BIT              9
+/** Ready to send enable bit */
 #define USART_CR3_RTSE_BIT              8
+/** DMA enable transmitter bit */
 #define USART_CR3_DMAT_BIT              7
+/** DMA enable receiver bit */
 #define USART_CR3_DMAR_BIT              6
+/** Smartcard mode enable bit */
 #define USART_CR3_SCEN_BIT              5
+/** Smartcard NACK enable bit */
 #define USART_CR3_NACK_BIT              4
+/** Half-duplex selection bit */
 #define USART_CR3_HDSEL_BIT             3
+/** IrDA low power bit */
 #define USART_CR3_IRLP_BIT              2
+/** IrDA mode enable bit */
 #define USART_CR3_IREN_BIT              1
+/** Error interrupt enable bit */
 #define USART_CR3_EIE_BIT               0
 
-/* Not on UART4, UART5 */
+/**
+ * @brief Clear to send interrupt enable
+ * Not available on UART4, UART5. */
 #define USART_CR3_CTSIE                 BIT(USART_CR3_CTSIE_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Clear to send enable
+ * Not available on UART4, UART5. */
 #define USART_CR3_CTSE                  BIT(USART_CR3_CTSE_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Ready to send enable
+ * Not available on UART4, UART5. */
 #define USART_CR3_RTSE                  BIT(USART_CR3_RTSE_BIT)
-/* Not on UART5 */
+/**
+ * @brief DMA enable transmitter
+ * Not available on UART5. */
 #define USART_CR3_DMAT                  BIT(USART_CR3_DMAT_BIT)
-/* Not on UART5 */
+/**
+ * @brief DMA enable receiver
+ * Not available on UART5. */
 #define USART_CR3_DMAR                  BIT(USART_CR3_DMAR_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Smartcard mode enable
+ * Not available on UART4, UART5. */
 #define USART_CR3_SCEN                  BIT(USART_CR3_SCEN_BIT)
-/* Not on UART4, UART5 */
+/**
+ * @brief Smartcard NACK enable
+ * Not available on UART4, UART5. */
 #define USART_CR3_NACK                  BIT(USART_CR3_NACK_BIT)
+/**
+ * @brief Half-duplex selection
+ * When set, single-wire half duplex mode is selected.
+ */
 #define USART_CR3_HDSEL                 BIT(USART_CR3_HDSEL_BIT)
+/** IrDA low power mode */
 #define USART_CR3_IRLP                  BIT(USART_CR3_IRLP_BIT)
-#define USART_CR3_IRLP_NORMAL           (0 << USART_CR3_IRLP_BIT)
-#define USART_CR3_IRLP_LOW_POWER        (1 << USART_CR3_IRLP_BIT)
+/** IrDA mode: normal */
+#define USART_CR3_IRLP_NORMAL           (0U << USART_CR3_IRLP_BIT)
+/** IrDA mode: low power */
+#define USART_CR3_IRLP_LOW_POWER        (1U << USART_CR3_IRLP_BIT)
+/** IrDA mode enable */
 #define USART_CR3_IREN                  BIT(USART_CR3_IREN_BIT)
+/** Error interrupt enable */
 #define USART_CR3_EIE                   BIT(USART_CR3_EIE_BIT)
 
 /* Guard time and prescaler register */
 
-/* Not on UART4, UART5 */
+/**
+ * @brief Guard time value mask
+ * Used in Smartcard mode. Not available on UART4, UART5. */
 #define USART_GTPR_GT                   (0xFF << 8)
-/* Not on UART4, UART5 */
+/**
+ * @brief Prescaler value mask
+ * Restrictions on this value apply, depending on the USART mode. Not
+ * available on UART4, UART5. */
 #define USART_GTPR_PSC                  0xFF
 
 /*
@@ -236,7 +383,8 @@ typedef struct usart_reg_map {
 typedef struct usart_dev {
     usart_reg_map *regs;             /**< Register map */
     ring_buffer *rb;                 /**< RX ring buffer */
-    uint32 max_baud;                 /**< Maximum baud */
+    uint32 max_baud;                 /**< @brief Deprecated.
+                                      * Maximum baud rate. */
     uint8 rx_buf[USART_RX_BUF_SIZE]; /**< @brief Deprecated.
                                       * Actual RX buffer used by rb.
                                       * This field will be removed in
@@ -245,16 +393,17 @@ typedef struct usart_dev {
     nvic_irq_num irq_num;            /**< USART NVIC interrupt */
 } usart_dev;
 
-extern usart_dev *USART1;
-extern usart_dev *USART2;
-extern usart_dev *USART3;
-#ifdef STM32_HIGH_DENSITY
-extern usart_dev *UART4;
-extern usart_dev *UART5;
-#endif
-
 void usart_init(usart_dev *dev);
+
+struct gpio_dev;                /* forward declaration */
+void usart_async_gpio_cfg(usart_dev *udev,
+                          struct gpio_dev *rx_dev, uint8 rx,
+                          struct gpio_dev *tx_dev, uint8 tx,
+                          unsigned flags);
+
+#define USART_USE_PCLK 0
 void usart_set_baud_rate(usart_dev *dev, uint32 clock_speed, uint32 baud);
+
 void usart_enable(usart_dev *dev);
 void usart_disable(usart_dev *dev);
 void usart_foreach(void (*fn)(usart_dev *dev));