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

9 files changed, 149 insertions, 111 deletions

diff --git a/os/hal/platforms/LPC214x/hal_lld.c b/os/hal/platforms/LPC214x/hal_lld.c
index 1deac96fb..352f5c736 100644
--- a/os/hal/platforms/LPC214x/hal_lld.c
+++ b/os/hal/platforms/LPC214x/hal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/hal_lld.c

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

+ * @file    LPC214x/hal_lld.c

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

+ *

  * @addtogroup LPC214x_HAL

  * @{

  */

@@ -36,7 +37,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 =

@@ -75,7 +76,9 @@ static CH_IRQ_HANDLER(irq_handler) {
 /*===========================================================================*/

 

 /**

- * @brief Low level HAL driver initialization.

+ * @brief   Low level HAL driver initialization.

+ *

+ * @notapi

  */

 void hal_lld_init(void) {

 

@@ -85,8 +88,11 @@ void hal_lld_init(void) {
 }

 

 /**

- * @brief LPC214x clocks and PLL initialization.

- * @note All the involved constants come from the file @p board.h.

+ * @brief   LPC214x clocks and PLL initialization.

+ * @note    All the involved constants come from the file @p board.h.

+ * @note    This function must be invoked only after the system reset.

+ *

+ * @special

  */

 void lpc214x_clock_init(void) {

 

diff --git a/os/hal/platforms/LPC214x/hal_lld.h b/os/hal/platforms/LPC214x/hal_lld.h
index 0c231e4e5..4b88f13fc 100644
--- a/os/hal/platforms/LPC214x/hal_lld.h
+++ b/os/hal/platforms/LPC214x/hal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/hal_lld.h

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

+ * @file    LPC214x/hal_lld.h

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

+ *

  * @addtogroup LPC214x_HAL

  * @{

  */

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

 

 /**

- * @brief Default action for the non vectored IRQ handler, nothing.

+ * @brief   Default action for the non vectored IRQ handler, nothing.

  */

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

 #define LPC214x_NON_VECTORED_IRQ_HOOK()

diff --git a/os/hal/platforms/LPC214x/pal_lld.c b/os/hal/platforms/LPC214x/pal_lld.c
index bc563be28..9e145ed48 100644
--- a/os/hal/platforms/LPC214x/pal_lld.c
+++ b/os/hal/platforms/LPC214x/pal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/pal_lld.c

- * @brief LPC214x FIO low level driver code.

+ * @file    LPC214x/pal_lld.c

+ * @brief   LPC214x FIO low level driver code.

+ *

  * @addtogroup LPC214x_PAL

  * @{

  */

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

 

 /**

- * @brief LPC214x I/O ports configuration.

+ * @brief   LPC214x I/O ports configuration.

  * @details FIO units and PINSEL registers initialization.

  *

- * @param[in] config the LPC214x ports configuration

+ * @param[in] config    the LPC214x ports configuration

+ *

+ * @notapi

  */

 void _pal_lld_init(const PALConfig *config) {

 

@@ -76,20 +79,19 @@ 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 push pull output with

+ *          high state.

+ * @note    This function does not alter the @p PINSELx 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 push pull output with high

- *       state.

- * @note This function does not alter the @p PINSELx 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/LPC214x/pal_lld.h b/os/hal/platforms/LPC214x/pal_lld.h
index 4a0ca5106..f9e41b358 100644
--- a/os/hal/platforms/LPC214x/pal_lld.h
+++ b/os/hal/platforms/LPC214x/pal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/pal_lld.h

- * @brief LPC214x FIO low level driver header.

+ * @file    LPC214x/pal_lld.h

+ * @brief   LPC214x FIO low level driver header.

+ *

  * @addtogroup LPC214x_PAL

  * @{

  */

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

 

 /**

- * @brief FIO port setup info.

+ * @brief   FIO port setup info.

  */

 typedef struct {

   /** Initial value for FIO_PIN register.*/

@@ -52,7 +53,7 @@ typedef struct {
 } lpc214x_fio_setup_t;

 

 /**

- * @brief LPC214x FIO static initializer.

+ * @brief   LPC214x FIO 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

@@ -72,17 +73,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 32

 

 /**

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

+ * @brief   Whole port mask.

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

+ */

+#define PAL_WHOLE_PORT ((ioportmask_t)0xFFFFFFFF)

+

+/**

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

  */

 typedef uint32_t ioportmask_t;

 

 /**

- * @brief Port Identifier.

+ * @brief   Port Identifier.

  */

 typedef FIO * ioportid_t;

 

@@ -91,12 +98,12 @@ typedef FIO * ioportid_t;
 /*===========================================================================*/

 

 /**

- * @brief FIO port 0 identifier.

+ * @brief   FIO port 0 identifier.

  */

 #define IOPORT1        FIO0Base

 

 /**

- * @brief FIO port 1 identifier.

+ * @brief   FIO port 1 identifier.

  */

 #define IOPORT2        FIO1Base

 

@@ -106,91 +113,85 @@ typedef FIO * ioportid_t;
 /*===========================================================================*/

 

 /**

- * @brief FIO subsystem initialization.

+ * @brief   FIO subsystem initialization.

  * @details Enables the access through the fast registers.

  */

 #define pal_lld_init(config) _pal_lld_init(config)

 

 /**

- * @brief Reads an I/O port.

+ * @brief   Reads an I/O port.

  * @details This function is implemented by reading the FIO PIN 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)->FIO_PIN)

 

 /**

- * @brief Reads the output latch.

+ * @brief   Reads the output latch.

  * @details This function is implemented by reading the FIO SET 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)->FIO_SET)

 

 /**

- * @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 FIO PIN 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)->FIO_PIN = (bits))

 

 /**

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

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

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

  *          implementation has no side effects.

  *

- * @param[in] port the port identifier

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

+ * @param[in] port      the port identifier

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

  *

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

- *       code.

+ * @notapi

  */

 #define pal_lld_setport(port, bits) ((port)->FIO_SET = (bits))

 

 /**

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

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

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

  *          implementation has no side effects.

  *

- * @param[in] port the port identifier

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

+ * @param[in] port      the port identifier

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

  *

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

- *       code.

+ * @notapi

  */

 #define pal_lld_clearport(port, bits) ((port)->FIO_CLR = (bits))

 

 /**

- * @brief Writes a value on an I/O bus.

+ * @brief   Writes a value on an I/O bus.

  * @details This function is implemented by writing the FIO PIN and MASK

  *          registers, the implementation is not atomic because the multiple

  *          accesses.

  *

- * @param[in] port the port identifier

- * @param[in] mask the group mask, a logical AND is performed on the output

- *            data

- * @param[in] offset the group bit offset within the port

- * @param[in] bits the bits to be written. Values exceeding the group width

- *            are masked.

+ * @param[in] port      the port identifier

+ * @param[in] mask      the group mask, a logical AND is performed on the

+ *                      output data

+ * @param[in] offset    the group bit offset within the port

+ * @param[in] bits      the bits to be written. Values exceeding the group

+ *                      width are masked.

  *

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

- *       code.

+ * @notapi

  */

 #define pal_lld_writegroup(port, mask, offset, bits) {                  \

   (port)->FIO_MASK = ~((mask) << (offset));                             \

@@ -199,39 +200,40 @@ typedef FIO * ioportid_t;
 }

 

 /**

- * @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 push pull output with

+ *          high state.

+ * @note    This function does not alter the @p PINSELx 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 push pull output with high

- *       state.

- * @note This function does not alter the @p PINSELx 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)

 

 /**

- * @brief Writes a logical state on an output pad.

+ * @brief   Writes a logical state on an output pad.

  *

- * @param[in] port the port identifier

- * @param[in] pad the pad number within the port

- * @param[out] bit the logical value, the value must be @p 0 or @p 1

+ * @param[in] port      the port identifier

+ * @param[in] pad       the pad number within the port

+ * @param[in] bit       logical value, the value must be @p PAL_LOW or

+ *                      @p PAL_HIGH

  *

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

- *       code.

+ * @notapi

  */

 #define pal_lld_writepad(port, pad, bit) pal_lld_writegroup(port, 1, pad, bit)

 

 /**

- * @brief FIO port setup.

+ * @brief   FIO port setup.

  * @details This function programs the pins direction within a port.

+ *

+ * @notapi

  */

 #define pal_lld_lpc214x_set_direction(port, dir) {                      \

   (port)->FIO_DIR = (dir);                                              \

diff --git a/os/hal/platforms/LPC214x/serial_lld.c b/os/hal/platforms/LPC214x/serial_lld.c
index 87699aeb1..a1db8c537 100644
--- a/os/hal/platforms/LPC214x/serial_lld.c
+++ b/os/hal/platforms/LPC214x/serial_lld.c
@@ -227,6 +227,8 @@ static void notify2(void) {
 

 /**

  * @brief   UART0 IRQ handler.

+ *

+ * @isr

  */

 #if USE_LPC214x_UART0 || defined(__DOXYGEN__)

 CH_IRQ_HANDLER(UART0IrqHandler) {

@@ -242,6 +244,8 @@ CH_IRQ_HANDLER(UART0IrqHandler) {
 

 /**

  * @brief   UART1 IRQ handler.

+ *

+ * @isr

  */

 #if USE_LPC214x_UART1 || defined(__DOXYGEN__)

 CH_IRQ_HANDLER(UART1IrqHandler) {

@@ -261,6 +265,8 @@ CH_IRQ_HANDLER(UART1IrqHandler) {
 

 /**

  * @brief   Low level serial driver initialization.

+ *

+ * @notapi

  */

 void sd_lld_init(void) {

 

@@ -283,6 +289,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) {

 

@@ -312,6 +320,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/LPC214x/serial_lld.h b/os/hal/platforms/LPC214x/serial_lld.h
index a5cea7538..7b11cad38 100644
--- a/os/hal/platforms/LPC214x/serial_lld.h
+++ b/os/hal/platforms/LPC214x/serial_lld.h
@@ -121,7 +121,7 @@ typedef struct {
 } SerialConfig;

 

 /**

- * @brief @p SerialDriver specific data.

+ * @brief   @p SerialDriver specific data.

  */

 #define _serial_driver_data                                                 \

   _base_asynchronous_channel_data                                           \

diff --git a/os/hal/platforms/LPC214x/spi_lld.c b/os/hal/platforms/LPC214x/spi_lld.c
index 44c668db8..d829c3d62 100644
--- a/os/hal/platforms/LPC214x/spi_lld.c
+++ b/os/hal/platforms/LPC214x/spi_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/spi_lld.c

- * @brief LPC214x low level SPI driver code.

+ * @file    LPC214x/spi_lld.c

+ * @brief   LPC214x low level SPI driver code.

+ *

  * @addtogroup LPC214x_SPI

  * @{

  */

@@ -47,14 +48,13 @@ SPIDriver SPID1;
 /*===========================================================================*/

 

 /**

- * @brief Synchronous SSP transfer.

+ * @brief   Synchronous SSP transfer.

  *

  * @param[in] n         number of bytes to be exchanged

- *

  * @param[in] txbuf     the pointer to the transmit buffer or @p NULL

  * @param[out] rxbuf    the pointer to the receive buffer or @p NULL

  */

-void rw8(size_t n, const uint8_t *txbuf, uint8_t *rxbuf) {

+static void rw8(size_t n, const uint8_t *txbuf, uint8_t *rxbuf) {

   size_t ntx = n;

 

   while (n > 0) {

@@ -85,7 +85,9 @@ void rw8(size_t n, const uint8_t *txbuf, uint8_t *rxbuf) {
 /*===========================================================================*/

 

 /**

- * @brief Low level SPI driver initialization.

+ * @brief   Low level SPI driver initialization.

+ *

+ * @notapi

  */

 void spi_lld_init(void) {

 

@@ -95,9 +97,11 @@ void spi_lld_init(void) {
 }

 

 /**

- * @brief Configures and activates the SPI peripheral.

+ * @brief   Configures and activates the SPI peripheral.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @notapi

  */

 void spi_lld_start(SPIDriver *spip) {

 

@@ -116,9 +120,11 @@ void spi_lld_start(SPIDriver *spip) {
 }

 

 /**

- * @brief Deactivates the SPI peripheral.

+ * @brief   Deactivates the SPI peripheral.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @notapi

  */

 void spi_lld_stop(SPIDriver *spip) {

 

@@ -131,9 +137,11 @@ void spi_lld_stop(SPIDriver *spip) {
 }

 

 /**

- * @brief Asserts the slave select signal and prepares for transfers.

+ * @brief   Asserts the slave select signal and prepares for transfers.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @notapi

  */

 void spi_lld_select(SPIDriver *spip) {

 

@@ -141,10 +149,12 @@ void spi_lld_select(SPIDriver *spip) {
 }

 

 /**

- * @brief Deasserts the slave select signal.

+ * @brief   Deasserts the slave select signal.

  * @details The previously selected peripheral is unselected.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @notapi

  */

 void spi_lld_unselect(SPIDriver *spip) {

 

@@ -152,13 +162,15 @@ void spi_lld_unselect(SPIDriver *spip) {
 }

 

 /**

- * @brief Ignores data on the SPI bus.

+ * @brief   Ignores data on the SPI bus.

  * @details This function transmits a series of idle words on the SPI bus and

  *          ignores the received data. This function can be invoked even

  *          when a slave select signal has not been yet asserted.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to be ignored

+ *

+ * @notapi

  */

 void spi_lld_ignore(SPIDriver *spip, size_t n) {

 

@@ -167,16 +179,16 @@ void spi_lld_ignore(SPIDriver *spip, size_t n) {
 }

 

 /**

- * @brief Exchanges data on the SPI bus.

+ * @brief   Exchanges data on the SPI bus.

  * @details This function performs a simultaneous transmit/receive operation.

+ * @note    The buffers are organized as uint8_t arrays.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to be exchanged

  * @param[in] txbuf     the pointer to the transmit buffer

  * @param[out] rxbuf    the pointer to the receive buffer

  *

- * @note The buffers are organized as uint8_t arrays for data sizes below or

- *       equal to 8 bits else it is organized as uint16_t arrays.

+ * @notapi

  */

 void spi_lld_exchange(SPIDriver *spip, size_t n,

                       const void *txbuf, void *rxbuf) {

@@ -186,14 +198,14 @@ void spi_lld_exchange(SPIDriver *spip, size_t n,
 }

 

 /**

- * @brief Sends data ever the SPI bus.

+ * @brief   Sends data ever the SPI bus.

+ * @note    The buffers are organized as uint8_t arrays.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to send

  * @param[in] txbuf     the pointer to the transmit buffer

  *

- * @note The buffers are organized as uint8_t arrays for data sizes below or

- *       equal to 8 bits else it is organized as uint16_t arrays.

+ * @notapi

  */

 void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf) {

 

@@ -202,14 +214,14 @@ void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf) {
 }

 

 /**

- * @brief Receives data from the SPI bus.

+ * @brief   Receives data from the SPI bus.

+ * @note    The buffers are organized as uint8_t arrays.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to receive

  * @param[out] rxbuf    the pointer to the receive buffer

  *

- * @note The buffers are organized as uint8_t arrays for data sizes below or

- *       equal to 8 bits else it is organized as uint16_t arrays.

+ * @notapi

  */

 void spi_lld_receive(SPIDriver *spip, size_t n, void *rxbuf) {

 

diff --git a/os/hal/platforms/LPC214x/spi_lld.h b/os/hal/platforms/LPC214x/spi_lld.h
index cf6a06df4..d3d271cf0 100644
--- a/os/hal/platforms/LPC214x/spi_lld.h
+++ b/os/hal/platforms/LPC214x/spi_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file LPC214x/spi_lld.h

- * @brief LPC214x low level SPI driver header.

+ * @file    LPC214x/spi_lld.h

+ * @brief   LPC214x low level SPI driver header.

+ *

  * @addtogroup LPC214x_SPI

  * @{

  */

@@ -38,9 +39,9 @@
 /*===========================================================================*/

 

 /**

- * @brief SPI1 (SSP) driver enable switch.

+ * @brief   SPI1 (SSP) driver enable switch.

  * @details If set to @p TRUE the support for SPI0 is included.

- * @note The default is @p TRUE.

+ * @note    The default is @p TRUE.

  */

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

 #define USE_LPC214x_SPI1            TRUE

@@ -55,7 +56,7 @@
 /*===========================================================================*/

 

 /**

- * @brief Driver configuration structure.

+ * @brief   Driver configuration structure.

  */

 typedef struct {

   /**

@@ -81,7 +82,7 @@ typedef struct {
 } SPIConfig;

 

 /**

- * @brief Structure representing a SPI driver.

+ * @brief   Structure representing a SPI driver.

  */

 typedef struct {

   /**

diff --git a/os/hal/platforms/LPC214x/vic.c b/os/hal/platforms/LPC214x/vic.c
index c4e11231f..97dbf4851 100644
--- a/os/hal/platforms/LPC214x/vic.c
+++ b/os/hal/platforms/LPC214x/vic.c
@@ -30,6 +30,8 @@
 /**

  * @brief   VIC Initialization.

  * @note    Better reset everything in the VIC, it is a HUGE source of trouble.

+ *

+ * @notapi

  */

 void vic_init(void) {

   int i;

@@ -52,6 +54,8 @@ void vic_init(void) {
  * @param[in] handler   the pointer to the IRQ service routine

  * @param[in] vector    the vector number

  * @param[in] source    the IRQ source to be associated to the vector

+ *

+ * @api

  */

 void SetVICVector(void *handler, int vector, int source) {