Documentation improvements, fixed a small error in the STM32 serial driver.

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

6 files changed, 100 insertions, 70 deletions

diff --git a/os/hal/platforms/MSP430/hal_lld.c b/os/hal/platforms/MSP430/hal_lld.c
index 490c0f505..6cbc0c2f1 100644
--- a/os/hal/platforms/MSP430/hal_lld.c
+++ b/os/hal/platforms/MSP430/hal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file MSP430/hal_lld.c

- * @brief MSP430 HAL subsystem low level driver source.

+ * @file    MSP430/hal_lld.c

+ * @brief   MSP430 HAL subsystem low level driver source.

+ *

  * @addtogroup MSP430_HAL

  * @{

  */

@@ -32,7 +33,7 @@
 /*===========================================================================*/

 

 /**

- * @brief PAL setup.

+ * @brief   PAL setup.

  * @details Digital I/O ports static configuration as defined in @p board.h.

  */

 const PALConfig pal_default_config =

@@ -74,7 +75,9 @@ const PALConfig pal_default_config =
 /*===========================================================================*/

 

 /**

- * @brief Low level HAL driver initialization.

+ * @brief   Low level HAL driver initialization.

+ *

+ * @notapi

  */

 void hal_lld_init(void) {

 

diff --git a/os/hal/platforms/MSP430/hal_lld.h b/os/hal/platforms/MSP430/hal_lld.h
index 9d730744c..681392645 100644
--- a/os/hal/platforms/MSP430/hal_lld.h
+++ b/os/hal/platforms/MSP430/hal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file MSP430/hal_lld.h

- * @brief MSP430 HAL subsystem low level driver header.

+ * @file    MSP430/hal_lld.h

+ * @brief   MSP430 HAL subsystem low level driver header.

+ *

  * @addtogroup MSP430_HAL

  * @{

  */

@@ -46,11 +47,11 @@
 /*===========================================================================*/

 

 /**

- * @brief Clock source.

+ * @brief   Clock source.

  * @details The clock source can be selected from:

- * - @p MSP430_CLOCK_SOURCE_XT2CLK.

- * - @p MSP430_CLOCK_SOURCE_DCOCLK.

- * .

+ *          - @p MSP430_CLOCK_SOURCE_XT2CLK.

+ *          - @p MSP430_CLOCK_SOURCE_DCOCLK.

+ *          .

  */

 #if !defined(MSP430_USE_CLOCK) || defined(__DOXYGEN__)

 #define MSP430_USE_CLOCK            MSP430_CLOCK_SOURCE_XT2CLK

diff --git a/os/hal/platforms/MSP430/pal_lld.c b/os/hal/platforms/MSP430/pal_lld.c
index 9a8cf5605..419b1ca82 100644
--- a/os/hal/platforms/MSP430/pal_lld.c
+++ b/os/hal/platforms/MSP430/pal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file MSP430/pal_lld.c

- * @brief MSP430 Digital I/O low level driver code.

+ * @file    MSP430/pal_lld.c

+ * @brief   MSP430 Digital I/O low level driver code.

+ *

  * @addtogroup MSP430_PAL

  * @{

  */

@@ -50,12 +51,13 @@
 /*===========================================================================*/

 

 /**

- * @brief MSP430 I/O ports configuration.

+ * @brief   MSP430 I/O ports configuration.

+ * @note    The @p PxIFG, @p PxIE and @p PxSEL registers are cleared. @p PxOUT

+ *          and @p PxDIR are configured as specified.

  *

  * @param[in] config the MSP430 ports configuration

  *

- * @note The @p PxIFG, @p PxIE and @p PxSEL registers are cleared. @p PxOUT

- *       and @p PxDIR are configured as specified.

+ * @notapi

  */

 void _pal_lld_init(const PALConfig *config) {

 

@@ -101,21 +103,20 @@ void _pal_lld_init(const PALConfig *config) {
 }

 

 /**

- * @brief Pads mode setup.

+ * @brief   Pads mode setup.

  * @details This function programs a pads group belonging to the same port

  *          with the specified mode.

+ * @note    @p PAL_MODE_UNCONNECTED is implemented as output as recommended by

+ *          the MSP430x1xx Family User's Guide. Unconnected pads are set to

+ *          high logic state by default.

+ * @note    This function does not alter the @p PxSEL registers. Alternate

+ *          functions setup must be handled by device-specific code.

  *

- * @param[in] port the port identifier

- * @param[in] mask the group mask

- * @param[in] mode the mode

+ * @param[in] port      the port identifier

+ * @param[in] mask      the group mask

+ * @param[in] mode      the mode

  *

- * @note This function is not meant to be invoked directly by the application

- *       code.

- * @note @p PAL_MODE_UNCONNECTED is implemented as output as recommended by

- *       the MSP430x1xx Family User's Guide. Unconnected pads are set to

- *       high logic state by default.

- * @note This function does not alter the @p PxSEL registers. Alternate

- *       functions setup must be handled by device-specific code.

+ * @notapi

  */

 void _pal_lld_setgroupmode(ioportid_t port,

                            ioportmask_t mask,

diff --git a/os/hal/platforms/MSP430/pal_lld.h b/os/hal/platforms/MSP430/pal_lld.h
index b1a12c924..e9b67bf18 100644
--- a/os/hal/platforms/MSP430/pal_lld.h
+++ b/os/hal/platforms/MSP430/pal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file MSP430/pal_lld.h

- * @brief MSP430 Digital I/O low level driver header.

+ * @file    MSP430/pal_lld.h

+ * @brief   MSP430 Digital I/O low level driver header.

+ *

  * @addtogroup MSP430_PAL

  * @{

  */

@@ -43,7 +44,7 @@
 /*===========================================================================*/

 

 /**

- * @brief Simplified MSP430 I/O port representation.

+ * @brief   Simplified MSP430 I/O port representation.

  * @details This structure represents the common part of all the MSP430 I/O

  *          ports.

  */

@@ -54,7 +55,7 @@ struct msp430_port_common {
 };

 

 /**

- * @brief Generic MSP430 I/O port.

+ * @brief   Generic MSP430 I/O port.

  */

 typedef union {

   struct msp430_port_common     iop_common;

@@ -63,7 +64,7 @@ typedef union {
 } msp430_ioport_t;

 

 /**

- * @brief Setup registers common to all the MSP430 ports.

+ * @brief   Setup registers common to all the MSP430 ports.

  */

 typedef struct  {

   ioregister_t  out;

@@ -71,7 +72,7 @@ typedef struct  {
 } msp430_dio_setup_t;

 

 /**

- * @brief MSP430 I/O ports static initializer.

+ * @brief   MSP430 I/O ports static initializer.

  * @details An instance of this structure must be passed to @p palInit() at

  *          system startup time in order to initialize the digital I/O

  *          subsystem. This represents only the initial setup, specific pads

@@ -117,23 +118,23 @@ typedef struct {
 } PALConfig;

 

 /**

- * @brief Width, in bits, of an I/O port.

+ * @brief   Width, in bits, of an I/O port.

  */

 #define PAL_IOPORTS_WIDTH 8

 

 /**

- * @brief Whole port mask.

- * @brief This macro specifies all the valid bits into a port.

+ * @brief   Whole port mask.

+ * @details This macro specifies all the valid bits into a port.

  */

 #define PAL_WHOLE_PORT ((ioportmask_t)0xFF)

 

 /**

- * @brief Digital I/O port sized unsigned type.

+ * @brief   Digital I/O port sized unsigned type.

  */

 typedef uint8_t ioportmask_t;

 

 /**

- * @brief Port Identifier.

+ * @brief   Port Identifier.

  * @details This type can be a scalar or some kind of pointer, do not make

  *          any assumption about it, use the provided macros when populating

  *          variables of this type.

@@ -145,7 +146,7 @@ typedef union msp430_ioport_t *ioportid_t;
 /*===========================================================================*/

 

 /**

- * @brief I/O port A identifier.

+ * @brief   I/O port A identifier.

  * @details This port identifier is mapped on the MSP430 port 1 (P1).

  */

 #if defined(__MSP430_HAS_PORT1__) ||                                    \

@@ -155,7 +156,7 @@ typedef union msp430_ioport_t *ioportid_t;
 #endif

 

 /**

- * @brief I/O port B identifier.

+ * @brief   I/O port B identifier.

  * @details This port identifier is mapped on the MSP430 port 2 (P2).

  */

 #if defined(__MSP430_HAS_PORT2__) ||                                    \

@@ -165,7 +166,7 @@ typedef union msp430_ioport_t *ioportid_t;
 #endif

 

 /**

- * @brief I/O port C identifier.

+ * @brief   I/O port C identifier.

  * @details This port identifier is mapped on the MSP430 port 3 (P3).

  */

 #if defined(__MSP430_HAS_PORT3__) ||                                    \

@@ -175,7 +176,7 @@ typedef union msp430_ioport_t *ioportid_t;
 #endif

 

 /**

- * @brief I/O port D identifier.

+ * @brief   I/O port D identifier.

  * @details This port identifier is mapped on the MSP430 port 4 (P4).

  */

 #if defined(__MSP430_HAS_PORT4__) ||                                    \

@@ -185,7 +186,7 @@ typedef union msp430_ioport_t *ioportid_t;
 #endif

 

 /**

- * @brief I/O port E identifier.

+ * @brief   I/O port E identifier.

  * @details This port identifier is mapped on the MSP430 port 5 (P5).

  */

 #if defined(__MSP430_HAS_PORT5__) ||                                    \

@@ -195,7 +196,7 @@ typedef union msp430_ioport_t *ioportid_t;
 #endif

 

 /**

- * @brief I/O port F identifier.

+ * @brief   I/O port F identifier.

  * @details This port identifier is mapped on the MSP430 port 6 (P6).

  */

 #if defined(__MSP430_HAS_PORT6__) ||                                    \

@@ -210,69 +211,67 @@ typedef union msp430_ioport_t *ioportid_t;
 /*===========================================================================*/

 

 /**

- * @brief Low level PAL subsystem initialization.

+ * @brief   Low level PAL subsystem initialization.

  * @details In MSP430 programs all the ports as input.

  *

  * @param[in] config the MSP430 ports configuration

+ *

+ * @notapi

  */

 #define pal_lld_init(config) _pal_lld_init(config)

 

 /**

- * @brief Reads the physical I/O port states.

+ * @brief   Reads the physical I/O port states.

  * @details This function is implemented by reading the PxIN register, the

  *          implementation has no side effects.

  *

- * @param[in] port the port identifier

- * @return The port bits.

+ * @param[in] port      the port identifier

+ * @return              The port bits.

  *

- * @note This function is not meant to be invoked directly by the application

- *       code.

+ * @notapi

  */

 #define pal_lld_readport(port) ((port)->iop_common.in.reg_p)

 

 /**

- * @brief Reads the output latch.

+ * @brief   Reads the output latch.

  * @details This function is implemented by reading the PxOUT register, the

  *          implementation has no side effects.

  *

- * @param[in] port the port identifier

- * @return The latched logical states.

+ * @param[in] port      the port identifier

+ * @return              The latched logical states.

  *

- * @note This function is not meant to be invoked directly by the application

- *       code.

+ * @notapi

  */

 #define pal_lld_readlatch(port) ((port)->iop_common.out.reg_p)

 

 /**

- * @brief Writes a bits mask on a I/O port.

+ * @brief   Writes a bits mask on a I/O port.

  * @details This function is implemented by writing the PxOUT register, the

  *          implementation has no side effects.

  *

- * @param[in] port the port identifier

- * @param[in] bits the bits to be written on the specified port

+ * @param[in] port      the port identifier

+ * @param[in] bits      the bits to be written on the specified port

  *

- * @note This function is not meant to be invoked directly by the application

- *       code.

+ * @notapi

  */

 #define pal_lld_writeport(port, bits) {                                 \

   (port)->iop_common.out.reg_p = (bits);                                \

 }

 

 /**

- * @brief Pads group mode setup.

+ * @brief   Pads group mode setup.

  * @details This function programs a pads group belonging to the same port

  *          with the specified mode.

+ * @note    @p PAL_MODE_UNCONNECTED is implemented as output as recommended by

+ *          the MSP430x1xx Family User's Guide.

+ * @note    This function does not alter the @p PxSEL registers. Alternate

+ *          functions setup must be handled by device-specific code.

  *

- * @param[in] port the port identifier

- * @param[in] mask the group mask

- * @param[in] mode the mode

+ * @param[in] port      the port identifier

+ * @param[in] mask      the group mask

+ * @param[in] mode      the mode

  *

- * @note This function is not meant to be invoked directly by the application

- *       code.

- * @note @p PAL_MODE_UNCONNECTED is implemented as output as recommended by

- *       the MSP430x1xx Family User's Guide.

- * @note This function does not alter the @p PxSEL registers. Alternate

- *       functions setup must be handled by device-specific code.

+ * @notapi

  */

 #define pal_lld_setgroupmode(port, mask, mode) \

   _pal_lld_setgroupmode(port, mask, mode)

diff --git a/os/hal/platforms/MSP430/serial_lld.c b/os/hal/platforms/MSP430/serial_lld.c
index 4ab12a872..25d3d06cd 100644
--- a/os/hal/platforms/MSP430/serial_lld.c
+++ b/os/hal/platforms/MSP430/serial_lld.c
@@ -169,6 +169,11 @@ static void usart1_deinit(void) {
 /*===========================================================================*/

 

 #if USE_MSP430_USART0 || defined(__DOXYGEN__)

+/**

+ * @brief   USART0 TX interrupt handler.

+ *

+ * @isr
+ */

 CH_IRQ_HANDLER(USART0TX_VECTOR) {

   msg_t b;

 

@@ -185,6 +190,11 @@ CH_IRQ_HANDLER(USART0TX_VECTOR) {
   CH_IRQ_EPILOGUE();

 }

 

+/**

+ * @brief   USART0 RX interrupt handler.

+ *

+ * @isr

+ */

 CH_IRQ_HANDLER(USART0RX_VECTOR) {

   uint8_t urctl;

 

@@ -201,6 +211,11 @@ CH_IRQ_HANDLER(USART0RX_VECTOR) {
 #endif /* USE_MSP430_USART0 */

 

 #if USE_MSP430_USART1 || defined(__DOXYGEN__)

+/**

+ * @brief   USART1 TX interrupt handler.

+ *

+ * @isr

+ */

 CH_IRQ_HANDLER(USART1TX_VECTOR) {

   msg_t b;

 

@@ -217,6 +232,11 @@ CH_IRQ_HANDLER(USART1TX_VECTOR) {
   CH_IRQ_EPILOGUE();

 }

 

+/**

+ * @brief   USART1 RX interrupt handler.

+ *

+ * @isr

+ */

 CH_IRQ_HANDLER(USART1RX_VECTOR) {

   uint8_t urctl;

 

@@ -238,6 +258,8 @@ CH_IRQ_HANDLER(USART1RX_VECTOR) {
 

 /**

  * @brief   Low level serial driver initialization.

+ *

+ * @notapi

  */

 void sd_lld_init(void) {

 

@@ -261,6 +283,8 @@ void sd_lld_init(void) {
  * @param[in] config    the architecture-dependent serial driver configuration.

  *                      If this parameter is set to @p NULL then a default

  *                      configuration is used.

+ *

+ * @notapi

  */

 void sd_lld_start(SerialDriver *sdp, const SerialConfig *config) {

 

@@ -287,6 +311,8 @@ void sd_lld_start(SerialDriver *sdp, const SerialConfig *config) {
  *          interrupt vector.

  *

  * @param[in] sdp       pointer to a @p SerialDriver object

+ *

+ * @notapi

  */

 void sd_lld_stop(SerialDriver *sdp) {

 

diff --git a/os/hal/platforms/MSP430/serial_lld.h b/os/hal/platforms/MSP430/serial_lld.h
index d19c9160d..b81333133 100644
--- a/os/hal/platforms/MSP430/serial_lld.h
+++ b/os/hal/platforms/MSP430/serial_lld.h
@@ -90,7 +90,7 @@ typedef struct {
 } SerialConfig;

 

 /**

- * @brief @p SerialDriver specific data.

+ * @brief   @p SerialDriver specific data.

  */

 #define _serial_driver_data                                                 \

   _base_asynchronous_channel_data                                           \