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

1 files changed, 55 insertions, 56 deletions

diff --git a/os/hal/platforms/AT91SAM7/pal_lld.h b/os/hal/platforms/AT91SAM7/pal_lld.h
index 607cc040c..07e17caff 100644
--- a/os/hal/platforms/AT91SAM7/pal_lld.h
+++ b/os/hal/platforms/AT91SAM7/pal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/pal_lld.h

- * @brief AT91SAM7 PIO low level driver header.

+ * @file    AT91SAM7/pal_lld.h

+ * @brief   AT91SAM7 PIO low level driver header.

+ *

  * @addtogroup AT91SAM7_PAL

  * @{

  */

@@ -40,7 +41,7 @@
 /*===========================================================================*/

 

 /**

- * @brief PIO port setup info.

+ * @brief   PIO port setup info.

  */

 typedef struct {

   /** Initial value for ODSR register (data).*/

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

 

 /**

- * @brief AT91SAM7 PIO static initializer.

+ * @brief   AT91SAM7 PIO 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

@@ -69,17 +70,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.

  * @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.

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

 

 /**

- * @brief PIO port A identifier.

+ * @brief   PIO port A identifier.

  */

 #define IOPORT1         AT91C_BASE_PIOA

 

 /**

- * @brief PIO port B identifier.

+ * @brief   PIO port B identifier.

  */

 #if (SAM7_PLATFORM == SAM7X128) || (SAM7_PLATFORM == SAM7X256) || \

     (SAM7_PLATFORM == SAM7X512) || defined(__DOXYGEN__)

@@ -109,96 +116,89 @@ typedef AT91PS_PIO ioportid_t;
 /*===========================================================================*/

 

 /**

- * @brief Low level PAL subsystem initialization.

+ * @brief   Low level PAL subsystem initialization.

  */

 #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 PIO_PDSR 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)->PIO_PDSR)

 

 /**

- * @brief Reads the output latch.

+ * @brief   Reads the output latch.

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

 

 /**

- * @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 PIO_ODSR 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

  *

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

- *       code.

+ * @notapi

  */

 #define pal_lld_writeport(port, bits) {                                 \

   (port)->PIO_ODSR = (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 PIO_SODR 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)->PIO_SODR = (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 PIO_CODR 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)->PIO_CODR = (bits);                                            \

 }

 

 /**

- * @brief Writes a group of bits.

+ * @brief   Writes a group of bits.

  * @details This function is implemented by writing the PIO_OWER, PIO_ODSR and

  *          PIO_OWDR registers, the implementation is not atomic because the

  *          multiple accesses.

  *

- * @param[in] port the port identifier

- * @param[in] mask the group mask

- * @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

+ * @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)->PIO_OWER = (mask) << (offset);                                \

@@ -207,31 +207,30 @@ typedef AT91PS_PIO 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.

  *

- * @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.

+ * @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)