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

11 files changed, 259 insertions, 183 deletions

diff --git a/os/hal/platforms/AT91SAM7/at91sam7_mii.c b/os/hal/platforms/AT91SAM7/at91sam7_mii.c
index 8a79082c5..2f1665847 100644
--- a/os/hal/platforms/AT91SAM7/at91sam7_mii.c
+++ b/os/hal/platforms/AT91SAM7/at91sam7_mii.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/at91sam7_mii.c

- * @brief AT91SAM7 low level MII driver code.

+ * @file    AT91SAM7/at91sam7_mii.c

+ * @brief   AT91SAM7 low level MII driver code.

+ *

  * @addtogroup AT91SAM7_MII

  * @{

  */

@@ -51,16 +52,20 @@
 /*===========================================================================*/

 

 /**

- * @brief Low level MII driver initialization.

+ * @brief   Low level MII driver initialization.

+ *

+ * @notapi

  */

 void miiInit(void) {

 

 }

 

 /**

- * @brief Resets a PHY device.

+ * @brief   Resets a PHY device.

+ *

+ * @param[in] macp      pointer to the @p MACDriver object

  *

- * @param[in] macp pointer to the @p MACDriver object

+ * @notapi

  */

 void miiReset(MACDriver *macp) {

 

@@ -94,11 +99,13 @@ void miiReset(MACDriver *macp) {
 }

 

 /**

- * @brief Reads a PHY register through the MII interface.

+ * @brief   Reads a PHY register through the MII interface.

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @param addr the register address

- * @return The register value.

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @param[in] addr      the register address

+ * @return              The register value.

+ *

+ * @notapi

  */

 phyreg_t miiGet(MACDriver *macp, phyaddr_t addr) {

 

@@ -114,11 +121,13 @@ phyreg_t miiGet(MACDriver *macp, phyaddr_t addr) {
 }

 

 /**

- * @brief Writes a PHY register through the MII interface.

+ * @brief   Writes a PHY register through the MII interface.

+ *

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @param[in] addr      the register address

+ * @param[in] value     the new register value

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @param addr the register address

- * @param value the new register value

+ * @notapi

  */

 void miiPut(MACDriver *macp, phyaddr_t addr, phyreg_t value) {

 

diff --git a/os/hal/platforms/AT91SAM7/at91sam7_mii.h b/os/hal/platforms/AT91SAM7/at91sam7_mii.h
index 8d98d41b0..a02ca90c9 100644
--- a/os/hal/platforms/AT91SAM7/at91sam7_mii.h
+++ b/os/hal/platforms/AT91SAM7/at91sam7_mii.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/at91sam7_mii.h

- * @brief AT91SAM7 low level MII driver header.

+ * @file    AT91SAM7/at91sam7_mii.h

+ * @brief   AT91SAM7 low level MII driver header.

+ *

  * @addtogroup AT91SAM7_MII

  * @{

  */

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

 

 /**

- * @brief PHY manufacturer and model.

+ * @brief   PHY manufacturer and model.

  */

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

 #define PHY_HARDWARE            PHY_MICREL_KS8721

@@ -52,7 +53,7 @@
 /*===========================================================================*/

 

 /**

- * @brief Pins latched by the PHY at reset.

+ * @brief   Pins latched by the PHY at reset.

  */

 #if PHY_HARDWARE == PHY_MICREL_KS8721

 #define PHY_ADDRESS             1

@@ -78,12 +79,12 @@
 /*===========================================================================*/

 

 /**

- * @brief Type of a PHY register value.

+ * @brief   Type of a PHY register value.

  */

 typedef uint16_t phyreg_t;

 

 /**

- * @brief Type of a PHY register address.

+ * @brief   Type of a PHY register address.

  */

 typedef uint8_t phyaddr_t;

 

diff --git a/os/hal/platforms/AT91SAM7/hal_lld.c b/os/hal/platforms/AT91SAM7/hal_lld.c
index 370b7cad5..4f2845411 100644
--- a/os/hal/platforms/AT91SAM7/hal_lld.c
+++ b/os/hal/platforms/AT91SAM7/hal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/hal_lld.c

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

+ * @file    AT91SAM7/hal_lld.c

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

+ *

  * @addtogroup AT91SAM7_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 =

@@ -72,7 +73,9 @@ static CH_IRQ_HANDLER(spurious_handler) {
 /*===========================================================================*/

 

 /**

- * @brief Low level HAL driver initialization.

+ * @brief   Low level HAL driver initialization.

+ *

+ * @notapi

  */

 void hal_lld_init(void) {

   unsigned i;

@@ -93,8 +96,11 @@ void hal_lld_init(void) {
 }

 

 /**

- * @brief AT91SAM7 clocks and PLL initialization.

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

+ * @brief   AT91SAM7 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 at91sam7_clock_init(void) {

 

diff --git a/os/hal/platforms/AT91SAM7/hal_lld.h b/os/hal/platforms/AT91SAM7/hal_lld.h
index e1a8fa2f8..d75fc8317 100644
--- a/os/hal/platforms/AT91SAM7/hal_lld.h
+++ b/os/hal/platforms/AT91SAM7/hal_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/hal_lld.h

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

+ * @file    AT91SAM7/hal_lld.h

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

+ *

  * @addtogroup AT91SAM7_HAL

  * @{

  */

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

 

 /**

- * @brief Default action for the spurious handler, nothing.

+ * @brief   Default action for the spurious handler, nothing.

  */

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

 #define AT91SAM7_SPURIOUS_HANDLER_HOOK()

 #endif

 

 /**

- * @brief Default divider for the USB clock - half the PLL clock.

+ * @brief   Default divider for the USB clock - half the PLL clock.

  */

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

 #define AT91SAM7_USBDIV AT91C_CKGR_USBDIV_1

diff --git a/os/hal/platforms/AT91SAM7/mac_lld.c b/os/hal/platforms/AT91SAM7/mac_lld.c
index 248202b05..0a03d192a 100644
--- a/os/hal/platforms/AT91SAM7/mac_lld.c
+++ b/os/hal/platforms/AT91SAM7/mac_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/mac_lld.c

- * @brief AT91SAM7 low level MAC driver code.

+ * @file    AT91SAM7/mac_lld.c

+ * @brief   AT91SAM7 low level MAC driver code.

+ *

  * @addtogroup AT91SAM7_MAC

  * @{

  */

@@ -53,7 +54,7 @@
 /*===========================================================================*/

 

 /**

- * @brief Ethernet driver 1.

+ * @brief   Ethernet driver 1.

  */

 MACDriver ETH1;

 

@@ -83,7 +84,7 @@ static uint8_t tb[EMAC_TRANSMIT_DESCRIPTORS * EMAC_TRANSMIT_BUFFERS_SIZE]
 /*===========================================================================*/

 

 /**

- * @brief IRQ handler.

+ * @brief   IRQ handler.

  */

 /** @cond never*/

 __attribute__((noinline))

@@ -120,8 +121,9 @@ static void serve_interrupt(void) {
 }

 

 /**

- * @brief Cleans an incomplete frame.

- * @param from the start position of the incomplete frame

+ * @brief   Cleans an incomplete frame.

+ *

+ * @param[in] from      the start position of the incomplete frame

  */

 static void cleanup(EMACDescriptor *from) {

 

@@ -137,7 +139,9 @@ static void cleanup(EMACDescriptor *from) {
 /*===========================================================================*/

 

 /**

- * @brief EMAC IRQ veneer handler.

+ * @brief   EMAC IRQ handler.

+ *

+ * @isr

  */

 CH_IRQ_HANDLER(irq_handler) {

 

@@ -153,7 +157,9 @@ CH_IRQ_HANDLER(irq_handler) {
 /*===========================================================================*/

 

 /**

- * @brief Low level MAC initialization.

+ * @brief   Low level MAC initialization.

+ *

+ * @notapi

  */

 void mac_lld_init(void) {

   unsigned i;

@@ -228,13 +234,15 @@ void mac_lld_init(void) {
 }

 

 /**

- * @brief Low level MAC address setup.

+ * @brief   Low level MAC address setup.

+ *

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @param[in] p         pointer to a six bytes buffer containing the MAC

+ *                      address. If this parameter is set to @p NULL then

+ *                      a system default MAC is used. The MAC address must

+ *                      be aligned with the most significant byte first.

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @param[in] p pointer to a six bytes buffer containing the MAC address. If

- *            this parameter is set to @p NULL then a system default MAC is

- *            used. The MAC address must be aligned with the most significant

- *            byte first.

+ * @notapi

  */

 void mac_lld_set_address(MACDriver *macp, const uint8_t *p) {

 

@@ -245,15 +253,17 @@ void mac_lld_set_address(MACDriver *macp, const uint8_t *p) {
 }

 

 /**

- * @brief Returns a transmission descriptor.

+ * @brief   Returns a transmission descriptor.

  * @details One of the available transmission descriptors is locked and

  *          returned.

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @param[out] tdp pointer to a @p MACTransmitDescriptor structure

- * @return The operation status.

- * @retval RDY_OK the descriptor was obtained.

- * @retval RDY_TIMEOUT descriptor not available.

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @param[out] tdp      pointer to a @p MACTransmitDescriptor structure

+ * @return              The operation status.

+ * @retval RDY_OK       the descriptor has been obtained.

+ * @retval RDY_TIMEOUT  descriptor not available.

+ *

+ * @notapi

  */

 msg_t max_lld_get_transmit_descriptor(MACDriver *macp,

                                       MACTransmitDescriptor *tdp) {

@@ -288,14 +298,18 @@ msg_t max_lld_get_transmit_descriptor(MACDriver *macp,
 }

 

 /**

- * @brief Writes to a transmit descriptor's stream.

+ * @brief   Writes to a transmit descriptor's stream.

  *

- * @param[in] tdp pointer to a @p MACTransmitDescriptor structure

- * @param[in] buf pointer to the buffer cointaining the data to be written

- * @param[in] size number of bytes to be written

- * @return The number of bytes written into the descriptor's stream, this

- *         value can be less than the amount specified in the parameter

- *         @p size if the maximum frame size is reached.

+ * @param[in] tdp       pointer to a @p MACTransmitDescriptor structure

+ * @param[in] buf       pointer to the buffer cointaining the data to be

+ *                      written

+ * @param[in] size      number of bytes to be written

+ * @return              The number of bytes written into the descriptor's

+ *                      stream, this value can be less than the amount

+ *                      specified in the parameter @p size if the maximum

+ *                      frame size is reached.

+ *

+ * @notapi

  */

 size_t mac_lld_write_transmit_descriptor(MACTransmitDescriptor *tdp,

                                          uint8_t *buf,

@@ -313,10 +327,12 @@ size_t mac_lld_write_transmit_descriptor(MACTransmitDescriptor *tdp,
 }

 

 /**

- * @brief Releases a transmit descriptor and starts the transmission of the

- *        enqueued data as a single frame.

+ * @brief   Releases a transmit descriptor and starts the transmission of the

+ *          enqueued data as a single frame.

+ *

+ * @param[in] tdp       the pointer to the @p MACTransmitDescriptor structure

  *

- * @param[in] tdp the pointer to the @p MACTransmitDescriptor structure

+ * @notapi

  */

 void mac_lld_release_transmit_descriptor(MACTransmitDescriptor *tdp) {

 

@@ -329,13 +345,15 @@ void mac_lld_release_transmit_descriptor(MACTransmitDescriptor *tdp) {
 }

 

 /**

- * @brief Returns a receive descriptor.

+ * @brief   Returns a receive descriptor.

+ *

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @param[out] rdp      pointer to a @p MACReceiveDescriptor structure

+ * @return              The operation status.

+ * @retval RDY_OK       the descriptor has been obtained.

+ * @retval RDY_TIMEOUT  descriptor not available.

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @param[out] rdp pointer to a @p MACReceiveDescriptor structure

- * @return The operation status.

- * @retval RDY_OK the descriptor was obtained.

- * @retval RDY_TIMEOUT descriptor not available.

+ * @notapi

  */

 msg_t max_lld_get_receive_descriptor(MACDriver *macp,

                                      MACReceiveDescriptor *rdp) {

@@ -402,14 +420,17 @@ restart:
 }

 

 /**

- * @brief Reads from a receive descriptor's stream.

+ * @brief   Reads from a receive descriptor's stream.

  *

- * @param[in] rdp pointer to a @p MACReceiveDescriptor structure

- * @param[in] buf pointer to the buffer that will receive the read data

- * @param[in] size number of bytes to be read

- * @return The number of bytes read from the descriptor's stream, this

- *         value can be less than the amount specified in the parameter

- *         @p size if there are no more bytes to read.

+ * @param[in] rdp       pointer to a @p MACReceiveDescriptor structure

+ * @param[in] buf       pointer to the buffer that will receive the read data

+ * @param[in] size      number of bytes to be read

+ * @return              The number of bytes read from the descriptor's

+ *                      stream, this value can be less than the amount

+ *                      specified in the parameter @p size if there are

+ *                      no more bytes to read.

+ *

+ * @notapi

  */

 size_t mac_lld_read_receive_descriptor(MACReceiveDescriptor *rdp,

                                          uint8_t *buf,

@@ -434,11 +455,13 @@ size_t mac_lld_read_receive_descriptor(MACReceiveDescriptor *rdp,
 }

 

 /**

- * @brief Releases a receive descriptor.

+ * @brief   Releases a receive descriptor.

  * @details The descriptor and its buffer are made available for more incoming

  *          frames.

  *

- * @param[in] rdp the pointer to the @p MACReceiveDescriptor structure

+ * @param[in] rdp       the pointer to the @p MACReceiveDescriptor structure

+ *

+ * @notapi

  */

 void mac_lld_release_receive_descriptor(MACReceiveDescriptor *rdp) {

   bool_t done;

@@ -464,12 +487,14 @@ void mac_lld_release_receive_descriptor(MACReceiveDescriptor *rdp) {
 }

 

 /**

- * @brief Updates and returns the link status.

+ * @brief   Updates and returns the link status.

+ *

+ * @param[in] macp      pointer to the @p MACDriver object

+ * @return              The link status.

+ * @retval TRUE         if the link is active.

+ * @retval FALSE        if the link is down.

  *

- * @param[in] macp pointer to the @p MACDriver object

- * @return The link status.

- * @retval TRUE if the link is active.

- * @retval FALSE if the link is down.

+ * @notapi

  */

 bool_t mac_lld_poll_link_status(MACDriver *macp) {

   uint32_t ncfgr, bmsr, bmcr, lpa;

diff --git a/os/hal/platforms/AT91SAM7/mac_lld.h b/os/hal/platforms/AT91SAM7/mac_lld.h
index c98afc0f8..ff8638d75 100644
--- a/os/hal/platforms/AT91SAM7/mac_lld.h
+++ b/os/hal/platforms/AT91SAM7/mac_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/mac_lld.h

- * @brief AT91SAM7 low level MAC driver header.

+ * @file    AT91SAM7/mac_lld.h

+ * @brief   AT91SAM7 low level MAC driver header.

+ *

  * @addtogroup AT91SAM7_MAC

  * @{

  */

@@ -81,28 +82,28 @@
 /*===========================================================================*/

 

 /**

- * @brief Number of available transmit buffers.

+ * @brief   Number of available transmit buffers.

  */

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

 #define MAC_TRANSMIT_BUFFERS        2

 #endif

 

 /**

- * @brief Number of available receive buffers.

+ * @brief   Number of available receive buffers.

  */

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

 #define MAC_RECEIVE_BUFFERS         2

 #endif

 

 /**

- * @brief Maximum supported frame size.

+ * @brief   Maximum supported frame size.

  */

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

 #define MAC_BUFFERS_SIZE            1518

 #endif

 

 /**

- * @brief Interrupt priority level for the EMAC device.

+ * @brief   Interrupt priority level for the EMAC device.

  */

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

 #define EMAC_INTERRUPT_PRIORITY     (AT91C_AIC_PRIOR_HIGHEST - 3)

@@ -117,8 +118,8 @@
 /*===========================================================================*/

 

 /**

- * @brief Structure representing a buffer physical descriptor.

- * @note It represents both descriptor types.

+ * @brief   Structure representing a buffer physical descriptor.

+ * @note    It represents both descriptor types.

  */

 typedef struct {

   uint32_t              w1;

@@ -126,7 +127,7 @@ typedef struct {
 } EMACDescriptor;

 

 /**

- * @brief Structure representing a MAC driver.

+ * @brief   Structure representing a MAC driver.

  */

 typedef struct {

   Semaphore             md_tdsem;       /**< Transmit semaphore.        */

@@ -138,7 +139,7 @@ typedef struct {
 } MACDriver;

 

 /**

- * @brief Structure representing a transmit descriptor.

+ * @brief   Structure representing a transmit descriptor.

  */

 typedef struct {

   size_t                td_offset;      /**< Current write offset.      */

@@ -149,7 +150,7 @@ typedef struct {
 } MACTransmitDescriptor;

 

 /**

- * @brief Structure representing a receive descriptor.

+ * @brief   Structure representing a receive descriptor.

  */

 typedef struct {

   size_t                rd_offset;      /**< Current read offset.       */

diff --git a/os/hal/platforms/AT91SAM7/pal_lld.c b/os/hal/platforms/AT91SAM7/pal_lld.c
index 3ea061f07..6545be0e6 100644
--- a/os/hal/platforms/AT91SAM7/pal_lld.c
+++ b/os/hal/platforms/AT91SAM7/pal_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/pal_lld.c

- * @brief AT91SAM7 PIO low level driver code.

+ * @file    AT91SAM7/pal_lld.c

+ * @brief   AT91SAM7 PIO low level driver code.

+ *

  * @addtogroup AT91SAM7_PAL

  * @{

  */

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

 

 /**

- * @brief AT91SAM7 I/O ports configuration.

+ * @brief   AT91SAM7 I/O ports configuration.

  * @details PIO registers initialization.

  *

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

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

+ *

+ * @notapi

  */

 void _pal_lld_init(const PALConfig *config) {

 

@@ -99,20 +102,21 @@ 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    This function is not meant to be invoked directly from the

+ *          application code.

+ * @note    @p PAL_MODE_RESET is implemented as input with pull-up.

+ * @note    @p PAL_MODE_UNCONNECTED is implemented as push pull output with

+ *          high state.

+ * @note    @p PAL_MODE_OUTPUT_OPENDRAIN also enables the pull-up resistor.

  *

- * @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_RESET is implemented as input with pull-up.

- * @note @p PAL_MODE_UNCONNECTED is implemented as push pull output with high

- *       state.

- * @note @p PAL_MODE_OUTPUT_OPENDRAIN also enables the pull-up resistor.

+ * @notapi

  */

 void _pal_lld_setgroupmode(ioportid_t port,

                            ioportmask_t mask,

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)

 

diff --git a/os/hal/platforms/AT91SAM7/serial_lld.c b/os/hal/platforms/AT91SAM7/serial_lld.c
index 39e6540d4..47de0a0e6 100644
--- a/os/hal/platforms/AT91SAM7/serial_lld.c
+++ b/os/hal/platforms/AT91SAM7/serial_lld.c
@@ -219,6 +219,11 @@ static void notify3(void) {
 /*===========================================================================*/

 

 #if USE_SAM7_USART0 || defined(__DOXYGEN__)

+/**

+ * @brief   USART0 interrupt handler.

+ *

+ * @isr
+ */

 CH_IRQ_HANDLER(USART0IrqHandler) {

 

   CH_IRQ_PROLOGUE();

@@ -229,6 +234,11 @@ CH_IRQ_HANDLER(USART0IrqHandler) {
 #endif

 

 #if USE_SAM7_USART1 || defined(__DOXYGEN__)

+/**

+ * @brief   USART1 interrupt handler.

+ *

+ * @isr

+ */

 CH_IRQ_HANDLER(USART1IrqHandler) {

 

   CH_IRQ_PROLOGUE();

@@ -247,6 +257,8 @@ CH_IRQ_HANDLER(USART1IrqHandler) {
 

 /**

  * @brief   Low level serial driver initialization.

+ *

+ * @notapi

  */

 void sd_lld_init(void) {

 

@@ -291,6 +303,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) {

 

@@ -325,6 +339,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/AT91SAM7/spi_lld.c b/os/hal/platforms/AT91SAM7/spi_lld.c
index 2353b76cb..d614aabb5 100644
--- a/os/hal/platforms/AT91SAM7/spi_lld.c
+++ b/os/hal/platforms/AT91SAM7/spi_lld.c
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/spi_lld.c

- * @brief AT91SAM7 low level SPI driver code.

+ * @file    AT91SAM7/spi_lld.c

+ * @brief   AT91SAM7 low level SPI driver code.

+ *

  * @addtogroup AT91SAM7_SPI

  * @{

  */

@@ -47,7 +48,7 @@ SPIDriver SPID;
 /*===========================================================================*/

 

 /**

- * @brief Synchronous SPI transfer.

+ * @brief   Synchronous SPI transfer.

  *

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

  *

@@ -85,7 +86,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 +98,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) {

 

@@ -120,9 +125,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) {

 

@@ -135,9 +142,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) {

 

@@ -145,10 +154,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) {

 

@@ -156,13 +167,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) {

 

@@ -171,16 +184,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) {

@@ -190,14 +203,14 @@ void spi_lld_exchange(SPIDriver *spip, size_t n,
 }

 

 /**

- * @brief Sends data over the SPI bus.

+ * @brief   Sends data over 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) {

 

@@ -206,14 +219,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/AT91SAM7/spi_lld.h b/os/hal/platforms/AT91SAM7/spi_lld.h
index 529b284d2..4c5ed4388 100644
--- a/os/hal/platforms/AT91SAM7/spi_lld.h
+++ b/os/hal/platforms/AT91SAM7/spi_lld.h
@@ -18,8 +18,9 @@
 */

 

 /**

- * @file AT91SAM7/spi_lld.h

- * @brief AT91SAM7 low level SPI driver header.

+ * @file    AT91SAM7/spi_lld.h

+ * @brief   AT91SAM7 low level SPI driver header.

+ *

  * @addtogroup AT91SAM7_SPI

  * @{

  */

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

 

 /**

- * @brief SPI driver enable switch.

+ * @brief   SPI 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_AT91SAM7_SPI) || defined(__DOXYGEN__)

 #define USE_AT91SAM7_SPI            TRUE

@@ -63,7 +64,7 @@
 /*===========================================================================*/

 

 /**

- * @brief Driver configuration structure.

+ * @brief   Driver configuration structure.

  */

 typedef struct {

   /**