1 files changed, 67 insertions, 37 deletions

diff --git a/ports/ARMCM3-STM32F103/stm32_serial.c b/ports/ARMCM3-STM32F103/stm32_serial.c
index 725fe3480..9d0534b04 100644
--- a/ports/ARMCM3-STM32F103/stm32_serial.c
+++ b/ports/ARMCM3-STM32F103/stm32_serial.c
@@ -17,6 +17,13 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @file ports/ARMCM3-STM32F103/stm32_serial.c
+ * @brief STM32F103 Serial driver code.
+ * @addtogroup STM32F103_SERIAL
+ * @{
+ */
+
 #include <ch.h>
 
 #include "board.h"
@@ -24,26 +31,35 @@
 #include "stm32_serial.h"
 #include "stm32lib/stm32f10x_nvic.h"
 
-#define USART_BITRATE (38400)
-
-#ifdef USE_USART1
+#if USE_STM32_USART1 || defined(__DOXYGEN__)
+/** @brief USART1 serial driver identifier.*/
 FullDuplexDriver COM1;
+
 static uint8_t ib1[SERIAL_BUFFERS_SIZE];
 static uint8_t ob1[SERIAL_BUFFERS_SIZE];
 #endif
 
-#ifdef USE_USART2
+#if USE_STM32_USART2 || defined(__DOXYGEN__)
+/** @brief USART2 serial driver identifier.*/
 FullDuplexDriver COM2;
+
 static uint8_t ib2[SERIAL_BUFFERS_SIZE];
 static uint8_t ob2[SERIAL_BUFFERS_SIZE];
 #endif
 
-#ifdef USE_USART3
+#if USE_STM32_USART3 || defined(__DOXYGEN__)
+/** @brief USART3 serial driver identifier.*/
 FullDuplexDriver COM3;
+
 static uint8_t ib3[SERIAL_BUFFERS_SIZE];
 static uint8_t ob3[SERIAL_BUFFERS_SIZE];
 #endif
 
+/**
+ * @brief Error handling routine.
+ * @param[in] sr USART SR register value
+ * @param[in] com communication channel associated to the USART
+ */
 static void SetError(uint16_t sr, FullDuplexDriver *com) {
   dflags_t sts = 0;
 
@@ -60,6 +76,11 @@ static void SetError(uint16_t sr, FullDuplexDriver *com) {
   chSysUnlockFromIsr();
 }
 
+/**
+ * @brief Common IRQ handler.
+ * @param[in] u pointer to an USART I/O block
+ * @param[in] com communication channel associated to the USART
+ */
 static void ServeInterrupt(USART_TypeDef *u, FullDuplexDriver *com) {
   uint16_t sr = u->SR;
 
@@ -81,9 +102,9 @@ static void ServeInterrupt(USART_TypeDef *u, FullDuplexDriver *com) {
   }
 }
 
-#ifdef USE_USART1
-/*
- * USART1 IRQ service routine.
+#if USE_STM32_USART1 || defined(__DOXYGEN__)
+/**
+ * @brief USART1 IRQ service routine.
  */
 CH_IRQ_HANDLER(VectorD4) {
 
@@ -94,9 +115,8 @@ CH_IRQ_HANDLER(VectorD4) {
   CH_IRQ_EPILOGUE();
 }
 
-/*
- * Invoked by the high driver when one or more bytes are inserted in the
- * output queue.
+/**
+ * @brief Output queue insertion notification from the high driver.
  */
 static void OutNotify1(void) {
 
@@ -104,9 +124,9 @@ static void OutNotify1(void) {
 }
 #endif
 
-#ifdef USE_USART2
-/*
- * USART2 IRQ service routine.
+#if USE_STM32_USART2 || defined(__DOXYGEN__)
+/**
+ * @brief USART2 IRQ service routine.
  */
 CH_IRQ_HANDLER(VectorD8) {
 
@@ -117,9 +137,8 @@ CH_IRQ_HANDLER(VectorD8) {
   CH_IRQ_EPILOGUE();
 }
 
-/*
- * Invoked by the high driver when one or more bytes are inserted in the
- * output queue.
+/**
+ * @brief Output queue insertion notification from the high driver.
  */
 static void OutNotify2(void) {
 
@@ -127,9 +146,9 @@ static void OutNotify2(void) {
 }
 #endif
 
-#ifdef USE_USART3
-/*
- * USART3 IRQ service routine.
+#if USE_STM32_USART3 || defined(__DOXYGEN__)
+/**
+ * @brief USART3 IRQ service routine.
  */
 CH_IRQ_HANDLER(VectorDC) {
 
@@ -140,9 +159,8 @@ CH_IRQ_HANDLER(VectorDC) {
   CH_IRQ_EPILOGUE();
 }
 
-/*
- * Invoked by the high driver when one or more bytes are inserted in the
- * output queue.
+/**
+ * @brief Output queue insertion notification from the high driver.
  */
 static void OutNotify3(void) {
 
@@ -150,9 +168,15 @@ static void OutNotify3(void) {
 }
 #endif
 
-/*
- * USART setup, must be invoked with interrupts disabled.
- * NOTE: Does not reset I/O queues.
+/**
+ * @brief USART1 setup.
+ * @details This function must be invoked with interrupts disabled.
+ * @param[in] u pointer to an USART I/O block
+ * @param[in] speed serial port speed in bits per second
+ * @param[in] cr1 the value for the @p CR1 register
+ * @param[in] cr2 the value for the @p CR2 register
+ * @param[in] cr3 the value for the @p CR3 register
+ * @note Does not reset the I/O queues.
  */
 void SetUSART(USART_TypeDef *u, uint32_t speed, uint16_t cr1,
               uint16_t cr2, uint16_t cr3) {
@@ -173,34 +197,40 @@ void SetUSART(USART_TypeDef *u, uint32_t speed, uint16_t cr1,
   u->CR3 = cr3 | CR3_EIE;
 }
 
-/*
- * Serial subsystem initialization.
- * NOTE: Handshake pins are not switched to their function because they may have
- *       another use. Enable them externally if needed.
+/**
+ * @brief Serial driver initialization.
+ * @param[in] prio1 priority to be assigned to the USART1 IRQ
+ * @param[in] prio2 priority to be assigned to the USART2 IRQ
+ * @param[in] prio3 priority to be assigned to the USART3 IRQ
+ * @note Handshake pads are not enabled inside this function because they
+ *       may have another use, enable them externally if needed.
+ *       RX and TX pads are handled inside.
  */
-void InitSerial(uint32_t prio1, uint32_t prio2, uint32_t prio3) {
+void stm32_serial_init(uint32_t prio1, uint32_t prio2, uint32_t prio3) {
 
-#ifdef USE_USART1
+#if USE_STM32_USART1
   chFDDInit(&COM1, ib1, sizeof ib1, NULL, ob1, sizeof ob1, OutNotify1);
   RCC->APB2ENR |= 0x00004000;
-  SetUSART(USART1, USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
+  SetUSART(USART1, STM32_USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
   GPIOA->CRH = (GPIOA->CRH & 0xFFFFF00F) | 0x000004B0;
   NVICEnableVector(USART1_IRQChannel, prio1);
 #endif
 
-#ifdef USE_USART2
+#if USE_STM32_USART2
   chFDDInit(&COM2, ib2, sizeof ib2, NULL, ob2, sizeof ob2, OutNotify2);
   RCC->APB1ENR |= 0x00020000;
-  SetUSART(USART2, USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
+  SetUSART(USART2, STM32_USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
   GPIOA->CRL = (GPIOA->CRL & 0xFFFF00FF) | 0x00004B00;
   NVICEnableVector(USART2_IRQChannel, prio2);
 #endif
 
-#ifdef USE_USART3
+#if USE_STM32_USART3
   chFDDInit(&COM3, ib3, sizeof ib3, NULL, ob3, sizeof ob3, OutNotify3);
   RCC->APB1ENR |= 0x00040000;
-  SetUSART(USART3, USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
+  SetUSART(USART3, STM32_USART_BITRATE, 0, CR2_STOP1_BITS | CR2_LINEN, 0);
   GPIOB->CRH = (GPIOB->CRH & 0xFFFF00FF) | 0x00004B00;
   NVICEnableVector(USART3_IRQChannel, prio3);
 #endif
 }
+
+/** @} */