git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@720 35acf78f-673a-0410-8e92-d51de3d6d3f4

demos/MSP430-MSP430x1611-GCC/board.c

@@ -82,7 +82,7 @@ void hwinit(void) {
   /*
    * Other subsystems.
    */
-  InitSerial();
+  msp430_serial_init();
 }
 
 CH_IRQ_HANDLER(TIMERA0_VECTOR) {

ports/ARMCM3/port.dox

@@ -106,7 +106,7 @@
 /** @} */
 
 /**
- * @defgroup ARMCM3_NVIC NVIC support
+ * @defgroup ARMCM3_NVIC NVIC Support
  * @{
  * @brief ARM Cortex-M3 NVIC support.
  *

ports/MSP430/msp430_serial.c

@@ -17,6 +17,13 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @file ports/MSP430/msp430_serial.c
+ * @brief MSP430 Serial driver code.
+ * @addtogroup MSP430_SERIAL
+ * @{
+ */
+
 #include <ch.h>
 #include <signal.h>
 
@@ -39,8 +46,11 @@ static void SetError(uint8_t urctl, FullDuplexDriver *com) {
   chSysUnlockFromIsr();
 }
 
-#ifdef USE_MSP430_USART0
+#if USE_MSP430_USART0 || defined(__DOXYGEN__)
+
+/** @brief USART0 serial driver identifier.*/
 FullDuplexDriver COM1;
+
 static uint8_t ib1[SERIAL_BUFFERS_SIZE];
 static uint8_t ob1[SERIAL_BUFFERS_SIZE];
 
@@ -88,9 +98,13 @@ static void OutNotify1(void) {
   }
 }
 
-/*
- * USART setup, must be invoked with interrupts disabled.
- * NOTE: Does not reset I/O queues.
+/**
+ * @brief USART0 setup.
+ * @details This function must be invoked with interrupts disabled.
+ * @param div The divider value as calculated by the @p UBR() macro.
+ * @param mod The value for the @p U0MCTL register.
+ * @param ctl The value for the @p U0CTL register.
+ * @note Does not reset the I/O queues.
  */
 void SetUSART0(uint16_t div, uint8_t mod, uint8_t ctl) {
 
@@ -111,8 +125,11 @@ void SetUSART0(uint16_t div, uint8_t mod, uint8_t ctl) {
 }
 #endif /* USE_MSP430_USART0 */
 
-#ifdef USE_MSP430_USART1
+#if USE_MSP430_USART1 || defined(__DOXYGEN__)
+
+/** @brief USART1 serial driver identifier.*/
 FullDuplexDriver COM2;
+
 static uint8_t ib2[SERIAL_BUFFERS_SIZE];
 static uint8_t ob2[SERIAL_BUFFERS_SIZE];
 
@@ -158,9 +175,13 @@ static void OutNotify2(void) {
   }
 }
 
-/*
- * 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 div The divider value as calculated by the @p UBR() macro.
+ * @param mod The value for the @p U1MCTL register.
+ * @param ctl The value for the @p U1CTL register.
+ * @note Does not reset the I/O queues.
  */
 void SetUSART1(uint16_t div, uint8_t mod, uint8_t ctl) {
 
@@ -181,16 +202,22 @@ void SetUSART1(uint16_t div, uint8_t mod, uint8_t ctl) {
 }
 #endif
 
-void InitSerial(void) {
+/**
+ * @brief Serial driver initialization.
+ * @note The serial ports are initialized at @p 38400-8-N-1 by default.
+ */
+void msp430_serial_init(void) {
 
   /* I/O queues setup.*/
-#ifdef USE_MSP430_USART0
+#if USE_MSP430_USART0
   chFDDInit(&COM1, ib1, sizeof ib1, NULL, ob1, sizeof ob1, OutNotify1);
   SetUSART0(UBR(38400), 0, CHAR);
 #endif
 
-#ifdef USE_MSP430_USART1
+#if USE_MSP430_USART1
   chFDDInit(&COM2, ib2, sizeof ib2, NULL, ob2, sizeof ob2, OutNotify2);
   SetUSART1(UBR(38400), 0, CHAR);
 #endif
 }
+
+/** @} */

ports/MSP430/msp430_serial.h

@@ -17,33 +17,64 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @file ports/MSP430/msp430_serial.h
+ * @brief MSP430 Serial driver macros and structures.
+ * @addtogroup MSP430_SERIAL
+ * @{
+ */
+
 #ifndef _MSP430_SERIAL_H_
 #define _MSP430_SERIAL_H_
 
-/*
- * Configuration parameter, you can change the depth of the queue buffers
- * depending on the requirements of your application.
+/**
+ * @brief Serial buffers size.
+ * @details Configuration parameter, you can change the depth of the queue
+ * buffers depending on the requirements of your application.
+ * @note The default is 32 bytes for both the transmission and receive buffers.
  */
+#ifndef SERIAL_BUFFERS_SIZE
 #define SERIAL_BUFFERS_SIZE 32
+#endif
 
-#define USE_MSP430_USART0
-//#define USE_MSP430_USART1
+/**
+ * @brief USART0 driver enable switch.
+ * @details If set to @p TRUE the support for USART0 is included.
+ * @note The default is @p TRUE.
+ */
+#if !defined(USE_MSP430_USART0) || defined(__DOXYGEN__)
+#define USE_MSP430_USART0 TRUE
+#endif
 
-/*
- * Macro for baud rate computation.
+/**
+ * @brief USART1 driver enable switch.
+ * @details If set to @p TRUE the support for USART1 is included.
+ * @note The default is @p FALSE.
+ */
+#if !defined(USE_MSP430_USART1) || defined(__DOXYGEN__)
+#define USE_MSP430_USART1 FALSE
+#endif
+
+/**
+ * @brief Macro for baud rate computation.
+ * @note Make sure the final baud rate is within tolerance.
  */
 #define UBR(b) (SMCLK / (b))
 
 #ifdef __cplusplus
 extern "C" {
 #endif
-  void InitSerial(void);
+  void msp430_serial_init(void);
   void SetUSART0(uint16_t div, uint8_t mod, uint8_t ctl);
   void SetUSART1(uint16_t div, uint8_t mod, uint8_t ctl);
 #ifdef __cplusplus
 }
 #endif
 
+/** @cond never*/
 extern FullDuplexDriver COM1, COM2;
+/** @endcond*/
 
 #endif /* _MSP430_SERIAL_H_ */
+
+/** @} */

ports/MSP430/port.dox

@@ -65,8 +65,16 @@
  * @brief MSP430 specific port code, structures and macros.
  *
  * @ingroup MSP430
- * @file ports/MSP430/chtypes.h Port types.
- * @file ports/MSP430/chcore.h Port related structures and macros.
- * @file ports/MSP430/chcore.c Port related code.
+ */
+/** @} */
+
+/**
+ * @defgroup MSP430_SERIAL USART Support
+ * @{
+ * @brief MSP430 USART support.
+ * @details The serial driver supports both the MSP430 USARTs in asynchronous
+ * mode.
+ *
+ * @ingroup MSP430_CORE
  */
 /** @} */