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, 215 insertions, 18 deletions

diff --git a/os/hal/src/adc.c b/os/hal/src/adc.c
index df8b05fd5..4983199ce 100644
--- a/os/hal/src/adc.c
+++ b/os/hal/src/adc.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   ADC Driver initialization.

+ *

+ * @init

  */

 void adcInit(void) {

 

@@ -58,6 +60,8 @@ void adcInit(void) {
  * @brief   Initializes the standard part of a @p ADCDriver structure.

  *

  * @param[in] adcp      pointer to the @p ADCDriver object

+ *

+ * @init

  */

 void adcObjectInit(ADCDriver *adcp) {

 

@@ -77,6 +81,8 @@ void adcObjectInit(ADCDriver *adcp) {
  *

  * @param[in] adcp      pointer to the @p ADCDriver object

  * @param[in] config    pointer to the @p ADCConfig object

+ *

+ * @api

  */

 void adcStart(ADCDriver *adcp, const ADCConfig *config) {

 

@@ -96,6 +102,8 @@ void adcStart(ADCDriver *adcp, const ADCConfig *config) {
  * @brief   Deactivates the ADC peripheral.

  *

  * @param[in] adcp      pointer to the @p ADCDriver object

+ *

+ * @api

  */

 void adcStop(ADCDriver *adcp) {

 

@@ -139,6 +147,8 @@ void adcStop(ADCDriver *adcp) {
  * @return              The operation status.

  * @retval FALSE        the conversion has been started.

  * @retval TRUE         the driver is busy, conversion not started.

+ *

+ * @api

  */

 bool_t adcStartConversion(ADCDriver *adcp,

                           const ADCConversionGroup *grpp,

@@ -182,6 +192,8 @@ bool_t adcStartConversion(ADCDriver *adcp,
  * @return              The operation status.

  * @retval FALSE        the conversion has been started.

  * @retval TRUE         the driver is busy, conversion not started.

+ *

+ * @iclass

  */

 bool_t adcStartConversionI(ADCDriver *adcp,

                            const ADCConversionGroup *grpp,

@@ -216,6 +228,8 @@ bool_t adcStartConversionI(ADCDriver *adcp,
  *          being processed then the function does nothing.

  *

  * @param[in] adcp      pointer to the @p ADCDriver object

+ *

+ * @api

  */

 void adcStopConversion(ADCDriver *adcp) {

 

@@ -248,6 +262,8 @@ void adcStopConversion(ADCDriver *adcp) {
  *          being processed then the function does nothing.

  *

  * @param[in] adcp      pointer to the @p ADCDriver object

+ *

+ * @iclass

  */

 void adcStopConversionI(ADCDriver *adcp) {

 

@@ -275,6 +291,8 @@ void adcStopConversionI(ADCDriver *adcp) {
  * @brief   Waits for completion.

  * @details If the conversion is not completed or not yet started then the

  *          invoking thread waits for a conversion completion event.

+ * @pre     In order to use this function the option @p ADC_USE_WAIT must be

+ *          enabled.

  *

  * @param[in] adcp      pointer to the @p ADCDriver object

  * @param[in] timeout   the number of ticks before the operation timeouts,

@@ -285,6 +303,8 @@ void adcStopConversionI(ADCDriver *adcp) {
  * @return              The operation result.

  * @retval RDY_OK       conversion finished.

  * @retval RDY_TIMEOUT  conversion not finished within the specified time.

+ *

+ * @init

  */

 msg_t adcWaitConversion(ADCDriver *adcp, systime_t timeout) {

 

diff --git a/os/hal/src/can.c b/os/hal/src/can.c
index 7bb91173f..a1fb237f3 100644
--- a/os/hal/src/can.c
+++ b/os/hal/src/can.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   CAN Driver initialization.

+ *

+ * @init

  */

 void canInit(void) {

 

@@ -58,6 +60,8 @@ void canInit(void) {
  * @brief   Initializes the standard part of a @p CANDriver structure.

  *

  * @param[in] canp      pointer to the @p CANDriver object

+ *

+ * @init

  */

 void canObjectInit(CANDriver *canp) {

 

@@ -80,6 +84,8 @@ void canObjectInit(CANDriver *canp) {
  *

  * @param[in] canp      pointer to the @p CANDriver object

  * @param[in] config    pointer to the @p CANConfig object

+ *

+ * @api

  */

 void canStart(CANDriver *canp, const CANConfig *config) {

 

@@ -105,6 +111,8 @@ void canStart(CANDriver *canp, const CANConfig *config) {
  * @brief   Deactivates the CAN peripheral.

  *

  * @param[in] canp      pointer to the @p CANDriver object

+ *

+ * @api

  */

 void canStop(CANDriver *canp) {

 

@@ -140,6 +148,8 @@ void canStop(CANDriver *canp) {
  * @retval RDY_OK       the frame has been queued for transmission.

  * @retval RDY_TIMEOUT  operation not finished within the specified time.

  * @retval RDY_RESET    driver stopped while waiting.

+ *

+ * @api

  */

 msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) {

 

@@ -181,6 +191,8 @@ msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) {
  *                      frame not immediately available if invoked using

  *                      @p TIME_IMMEDIATE.

  * @retval RDY_RESET    driver stopped while waiting.

+ *

+ * @api

  */

 msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) {

 

@@ -207,6 +219,8 @@ msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) {
  *

  * @param[in] canp      pointer to the @p CANDriver object

  * @return              The status flags mask.

+ *

+ * @api

  */

 canstatus_t canGetAndClearFlags(CANDriver *canp) {

   canstatus_t status;

@@ -221,8 +235,15 @@ canstatus_t canGetAndClearFlags(CANDriver *canp) {
 #if CAN_USE_SLEEP_MODE || defined(__DOXYGEN__)

 /**

  * @brief   Enters the sleep mode.

+ * @details This function puts the CAN driver in sleep mode and broadcasts

+ *          the @p cd_sleep_event event source.

+ * @pre     In order to use this function the option @p CAN_USE_SLEEP_MODE must

+ *          be enabled and the @p CAN_SUPPORTS_SLEEP mode must be supported

+ *          by the low level driver.

  *

  * @param[in] canp      pointer to the @p CANDriver object

+ *

+ * @api

  */

 void canSleep(CANDriver *canp) {

 

diff --git a/os/hal/src/hal.c b/os/hal/src/hal.c
index 156e75ea9..c0e3d2c28 100644
--- a/os/hal/src/hal.c
+++ b/os/hal/src/hal.c
@@ -46,6 +46,8 @@
 

 /**

  * @brief   HAL initialization.

+ *

+ * @init

  */

 void halInit(void) {

 

diff --git a/os/hal/src/i2c.c b/os/hal/src/i2c.c
index cc48c4147..1a55f53cd 100644
--- a/os/hal/src/i2c.c
+++ b/os/hal/src/i2c.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   I2C Driver initialization.

+ *

+ * @init

  */

 void i2cInit(void) {

 

@@ -58,6 +60,8 @@ void i2cInit(void) {
  * @brief   Initializes the standard part of a @p I2CDriver structure.

  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

+ *

+ * @init

  */

 void i2cObjectInit(I2CDriver *i2cp) {

 

@@ -70,6 +74,8 @@ void i2cObjectInit(I2CDriver *i2cp) {
  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

  * @param[in] config    pointer to the @p I2CConfig object

+ *

+ * @api

  */

 void i2cStart(I2CDriver *i2cp, const I2CConfig *config) {

 

@@ -89,6 +95,8 @@ void i2cStart(I2CDriver *i2cp, const I2CConfig *config) {
  * @brief   Deactivates the I2C peripheral.

  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

+ *

+ * @api

  */

 void i2cStop(I2CDriver *i2cp) {

 

@@ -111,6 +119,8 @@ void i2cStop(I2CDriver *i2cp) {
  * @param[in] i2cp      pointer to the @p I2CDriver object

  * @param[in] header    transaction header

  * @param[in] callback  operation complete callback

+ *

+ * @iclass

  */

 void i2cMasterStartI(I2CDriver *i2cp,

                      uint16_t header,

@@ -129,6 +139,8 @@ void i2cMasterStartI(I2CDriver *i2cp,
  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

  * @param[in] callback  operation complete callback

+ *

+ * @iclass

  */

 void i2cMasterStopI(I2CDriver *i2cp, i2ccallback_t callback) {

 

@@ -147,6 +159,8 @@ void i2cMasterStopI(I2CDriver *i2cp, i2ccallback_t callback) {
  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

  * @param[in] callback  operation complete callback

+ *

+ * @iclass

  */

 void i2cMasterRestartI(I2CDriver *i2cp, i2ccallback_t callback) {

 

@@ -165,6 +179,8 @@ void i2cMasterRestartI(I2CDriver *i2cp, i2ccallback_t callback) {
  * @param[in] n         number of bytes to be transmitted

  * @param[in] txbuf     transmit data buffer pointer

  * @param[in] callback  operation complete callback

+ *

+ * @iclass

  */

 void i2cMasterTransmitI(I2CDriver *i2cp, size_t n, const uint8_t *txbuf,

                         i2ccallback_t callback) {

@@ -185,6 +201,8 @@ void i2cMasterTransmitI(I2CDriver *i2cp, size_t n, const uint8_t *txbuf,
  * @param[in] n         number of bytes to be transmitted

  * @param[in] rxbuf     receive data buffer pointer

  * @param[in] callback  operation complete callback

+ *

+ * @iclass

  */

 void i2cMasterReceiveI(I2CDriver *i2cp, size_t n, uint8_t *rxbuf,

                        i2ccallback_t callback) {

@@ -203,11 +221,13 @@ void i2cMasterReceiveI(I2CDriver *i2cp, size_t n, uint8_t *rxbuf,
  * @brief   Gains exclusive access to the I2C bus.

  * @details This function tries to gain ownership to the I2C bus, if the bus

  *          is already being used then the invoking thread is queued.

- * @note    This function is only available when the @p I2C_USE_MUTUAL_EXCLUSION

- *          option is set to @p TRUE.

+ * @pre     In order to use this function the option @p I2C_USE_MUTUAL_EXCLUSION

+ *          must be enabled.

  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

  *

+ * @api

+ *

  */

 void i2cAcquireBus(I2CDriver *i2cp) {

 

@@ -222,10 +242,12 @@ void i2cAcquireBus(I2CDriver *i2cp) {
 

 /**

  * @brief   Releases exclusive access to the I2C bus.

- * @note    This function is only available when the @p I2C_USE_MUTUAL_EXCLUSION

- *          option is set to @p TRUE.

+ * @pre     In order to use this function the option @p I2C_USE_MUTUAL_EXCLUSION

+ *          must be enabled.

  *

  * @param[in] i2cp      pointer to the @p I2CDriver object

+ *

+ * @api

  */

 void i2cReleaseBus(I2CDriver *i2cp) {

 

diff --git a/os/hal/src/mac.c b/os/hal/src/mac.c
index a079556fe..62340dc31 100644
--- a/os/hal/src/mac.c
+++ b/os/hal/src/mac.c
@@ -52,6 +52,8 @@
 

 /**

  * @brief   MAC Driver initialization.

+ *

+ * @init

  */

 void macInit(void) {

 

@@ -62,6 +64,8 @@ void macInit(void) {
  * @brief   Initialize the standard part of a @p MACDriver structure.

  *

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

+ *

+ * @init

  */

 void macObjectInit(MACDriver *macp) {

 

@@ -74,7 +78,7 @@ void macObjectInit(MACDriver *macp) {
 

 /**

  * @brief   MAC address setup.

- * @note    This function must be invoked only with the driver in the stopped

+ * @pre     This function must be invoked with the driver in the stopped

  *          state. If invoked on an active interface then it is ignored.

  *

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

@@ -82,6 +86,7 @@ void macObjectInit(MACDriver *macp) {
  *                      address. If this parameter is set to @p NULL then MAC

  *                      a system default is used.

  *

+ * @api

  */

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

 

@@ -104,6 +109,8 @@ void macSetAddress(MACDriver *macp, const uint8_t *p) {
  * @return              The operation status.

  * @retval RDY_OK       the descriptor was obtained.

  * @retval RDY_TIMEOUT  the operation timed out, descriptor not initialized.

+ *

+ * @api

  */

 msg_t macWaitTransmitDescriptor(MACDriver *macp,

                                 MACTransmitDescriptor *tdp,

@@ -128,6 +135,8 @@ msg_t macWaitTransmitDescriptor(MACDriver *macp,
  *          enqueued data as a single frame.

  *

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

+ *

+ * @api

  */

 void macReleaseTransmitDescriptor(MACTransmitDescriptor *tdp) {

 

@@ -150,6 +159,8 @@ void macReleaseTransmitDescriptor(MACTransmitDescriptor *tdp) {
  * @return              The operation status.

  * @retval RDY_OK       the descriptor was obtained.

  * @retval RDY_TIMEOUT  the operation timed out, descriptor not initialized.

+ *

+ * @api

  */

 msg_t macWaitReceiveDescriptor(MACDriver *macp,

                                MACReceiveDescriptor *rdp,

@@ -175,6 +186,8 @@ msg_t macWaitReceiveDescriptor(MACDriver *macp,
  *          frames.

  *

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

+ *

+ * @api

  */

 void macReleaseReceiveDescriptor(MACReceiveDescriptor *rdp) {

 

@@ -188,6 +201,8 @@ void macReleaseReceiveDescriptor(MACReceiveDescriptor *rdp) {
  * @return              The link status.

  * @retval TRUE         if the link is active.

  * @retval FALSE        if the link is down.

+ *

+ * @api

  */

 bool_t macPollLinkStatus(MACDriver *macp) {

 

diff --git a/os/hal/src/mmc_spi.c b/os/hal/src/mmc_spi.c
index e5070de02..49f75c3cc 100644
--- a/os/hal/src/mmc_spi.c
+++ b/os/hal/src/mmc_spi.c
@@ -46,8 +46,10 @@
  * @brief   Inserion monitor timer callback function.

  *

  * @param[in] p         pointer to the @p MMCDriver object

+ *

+ * @notapi

  */

-void tmrfunc(void *p) {

+static void tmrfunc(void *p) {

   MMCDriver *mmcp = p;

 

   if (mmcp->mmc_cnt > 0) {

@@ -74,6 +76,8 @@ void tmrfunc(void *p) {
  * @brief   Waits an idle condition.

  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

+ *

+ * @notapi

  */

 static void wait(MMCDriver *mmcp) {

   int i;

@@ -102,6 +106,8 @@ static void wait(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param cmd[in]       the command id

  * @param arg[in]       the command argument

+ *

+ * @notapi

  */

 static void send_hdr(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) {

   uint8_t buf[6];

@@ -124,6 +130,8 @@ static void send_hdr(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The response as an @p uint8_t value.

  * @retval 0xFF         timed out.

+ *

+ * @notapi

  */

 static uint8_t recvr1(MMCDriver *mmcp) {

   int i;

@@ -145,6 +153,8 @@ static uint8_t recvr1(MMCDriver *mmcp) {
  * @param arg[in]       the command argument

  * @return              The response as an @p uint8_t value.

  * @retval 0xFF         timed out.

+ *

+ * @notapi

  */

 static uint8_t send_command(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) {

   uint8_t r1;

@@ -160,6 +170,8 @@ static uint8_t send_command(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) {
  * @brief   Waits that the card reaches an idle state.

  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

+ *

+ * @notapi

  */

 static void sync(MMCDriver *mmcp) {

   uint8_t buf[1];

@@ -182,6 +194,8 @@ static void sync(MMCDriver *mmcp) {
 

 /**

  * @brief   MMC over SPI driver initialization.

+ *

+ * @init

  */

 void mmcInit(void) {

 

@@ -198,6 +212,8 @@ void mmcInit(void) {
  *                          setting

  * @param[in] is_inserted   function that returns the card insertion sensor

  *                          status

+ *

+ * @init

  */

 void mmcObjectInit(MMCDriver *mmcp, SPIDriver *spip,

                    const SPIConfig *lscfg, const SPIConfig *hscfg,

@@ -219,6 +235,8 @@ void mmcObjectInit(MMCDriver *mmcp, SPIDriver *spip,
  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param[in] config    pointer to the @p MMCConfig object

+ *

+ * @api

  */

 void mmcStart(MMCDriver *mmcp, const MMCConfig *config) {

 

@@ -237,6 +255,8 @@ void mmcStart(MMCDriver *mmcp, const MMCConfig *config) {
  * @brief   Disables the MMC peripheral.

  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

+ *

+ * @api

  */

 void mmcStop(MMCDriver *mmcp) {

 

@@ -266,9 +286,11 @@ void mmcStop(MMCDriver *mmcp) {
  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The operation status.

- * @retval FALSE        the operation was successful and the driver is now

+ * @retval FALSE        the operation succeeded and the driver is now

  *                      in the @p MMC_READY state.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcConnect(MMCDriver *mmcp) {

   unsigned i;

@@ -338,9 +360,11 @@ bool_t mmcConnect(MMCDriver *mmcp) {
  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The operation status.

- * @retval FALSE        the operation was successful and the driver is now

+ * @retval FALSE        the operation succeeded and the driver is now

  *                      in the @p MMC_INSERTED state.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcDisconnect(MMCDriver *mmcp) {

   bool_t status;

@@ -374,8 +398,10 @@ bool_t mmcDisconnect(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param[in] startblk  first block to read

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcStartSequentialRead(MMCDriver *mmcp, uint32_t startblk) {

 

@@ -409,8 +435,10 @@ bool_t mmcStartSequentialRead(MMCDriver *mmcp, uint32_t startblk) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param[out] buffer   pointer to the read buffer

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcSequentialRead(MMCDriver *mmcp, uint8_t *buffer) {

   int i;

@@ -447,8 +475,10 @@ bool_t mmcSequentialRead(MMCDriver *mmcp, uint8_t *buffer) {
  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcStopSequentialRead(MMCDriver *mmcp) {

   static const uint8_t stopcmd[] = {0x40 | MMC_CMDSTOP, 0, 0, 0, 0, 1, 0xFF};

@@ -483,8 +513,10 @@ bool_t mmcStopSequentialRead(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param[in] startblk  first block to write

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcStartSequentialWrite(MMCDriver *mmcp, uint32_t startblk) {

 

@@ -518,8 +550,10 @@ bool_t mmcStartSequentialWrite(MMCDriver *mmcp, uint32_t startblk) {
  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @param[out] buffer   pointer to the write buffer

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcSequentialWrite(MMCDriver *mmcp, const uint8_t *buffer) {

   static const uint8_t start[] = {0xFF, 0xFC};

@@ -557,8 +591,10 @@ bool_t mmcSequentialWrite(MMCDriver *mmcp, const uint8_t *buffer) {
  *

  * @param[in] mmcp      pointer to the @p MMCDriver object

  * @return              The operation status.

- * @retval FALSE        the operation was successful.

+ * @retval FALSE        the operation succeeded.

  * @retval TRUE         the operation failed.

+ *

+ * @api

  */

 bool_t mmcStopSequentialWrite(MMCDriver *mmcp) {

   static const uint8_t stop[] = {0xFD, 0xFF};

diff --git a/os/hal/src/pal.c b/os/hal/src/pal.c
index eef5c32ff..824ebae0d 100644
--- a/os/hal/src/pal.c
+++ b/os/hal/src/pal.c
@@ -58,6 +58,8 @@
  *

  * @param[in] bus       the I/O bus, pointer to a @p IOBus structure

  * @return              The bus logical states.

+ *

+ * @api

  */

 ioportmask_t palReadBus(IOBus *bus) {

 

@@ -81,6 +83,8 @@ ioportmask_t palReadBus(IOBus *bus) {
  * @param[in] bits      the bits to be written on the I/O bus. Values exceeding

  *                      the bus width are masked so most significant bits are

  *                      lost.

+ *

+ * @api

  */

 void palWriteBus(IOBus *bus, ioportmask_t bits) {

 

@@ -102,6 +106,8 @@ void palWriteBus(IOBus *bus, ioportmask_t bits) {
  *

  * @param[in] bus       the I/O bus, pointer to a @p IOBus structure

  * @param[in] mode      the mode

+ *

+ * @api

  */

 void palSetBusMode(IOBus *bus, uint_fast8_t mode) {

 

diff --git a/os/hal/src/pwm.c b/os/hal/src/pwm.c
index 4b797da0c..f4af775e3 100644
--- a/os/hal/src/pwm.c
+++ b/os/hal/src/pwm.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   PWM Driver initialization.

+ *

+ * @init

  */

 void pwmInit(void) {

 

@@ -58,6 +60,8 @@ void pwmInit(void) {
  * @brief   Initializes the standard part of a @p PWMDriver structure.

  *

  * @param[in] pwmp      pointer to a @p PWMDriver object

+ *

+ * @init

  */

 void pwmObjectInit(PWMDriver *pwmp) {

 

@@ -70,6 +74,8 @@ void pwmObjectInit(PWMDriver *pwmp) {
  *

  * @param[in] pwmp      pointer to a @p PWMDriver object

  * @param[in] config    pointer to a @p PWMConfig object

+ *

+ * @api

  */

 void pwmStart(PWMDriver *pwmp, const PWMConfig *config) {

 

@@ -89,6 +95,8 @@ void pwmStart(PWMDriver *pwmp, const PWMConfig *config) {
  * @brief   Deactivates the PWM peripheral.

  *

  * @param[in] pwmp      pointer to a @p PWMDriver object

+ *

+ * @api

  */

 void pwmStop(PWMDriver *pwmp) {

 

@@ -110,6 +118,8 @@ void pwmStop(PWMDriver *pwmp) {
  * @param[in] pwmp      pointer to a @p PWMDriver object

  * @param[in] channel   PWM channel identifier

  * @param[in] width     PWM pulse width as clock pulses number

+ *

+ * @api

  */

 void pwmEnableChannel(PWMDriver *pwmp,

                       pwmchannel_t channel,

@@ -132,6 +142,8 @@ void pwmEnableChannel(PWMDriver *pwmp,
  *

  * @param[in] pwmp      pointer to a @p PWMDriver object

  * @param[in] channel   PWM channel identifier

+ *

+ * @api

  */

 void pwmDisableChannel(PWMDriver *pwmp, pwmchannel_t channel) {

 

diff --git a/os/hal/src/serial.c b/os/hal/src/serial.c
index 48518e66c..6c47d7fc3 100644
--- a/os/hal/src/serial.c
+++ b/os/hal/src/serial.c
@@ -99,6 +99,8 @@ static const struct SerialDriverVMT vmt = {
 

 /**

  * @brief   Serial Driver initialization.

+ *

+ * @init

  */

 void sdInit(void) {

 

@@ -117,6 +119,8 @@ void sdInit(void) {
  * @param[in] onotify   pointer to a callback function that is invoked when

  *                      some data is written in the Queue. The value can be

  *                      @p NULL.

+ *

+ * @init

  */

 void sdObjectInit(SerialDriver *sdp, qnotify_t inotify, qnotify_t onotify) {

 

@@ -137,6 +141,8 @@ void sdObjectInit(SerialDriver *sdp, qnotify_t inotify, qnotify_t onotify) {
  * @param[in] config    the architecture-dependent serial driver configuration.

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

  *                      configuration is used.

+ *

+ * @api

  */

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

 

@@ -157,6 +163,8 @@ void sdStart(SerialDriver *sdp, const SerialConfig *config) {
  *          the message @p Q_RESET.

  *

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

+ *

+ * @api

  */

 void sdStop(SerialDriver *sdp) {

 

@@ -187,6 +195,8 @@ void sdStop(SerialDriver *sdp) {
  *

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

  * @param[in] b         the byte to be written in the driver's Input Queue

+ *

+ * @iclass

  */

 void sdIncomingDataI(SerialDriver *sdp, uint8_t b) {

 

@@ -210,6 +220,8 @@ void sdIncomingDataI(SerialDriver *sdp, uint8_t b) {
  * @return              The byte value read from the driver's output queue.

  * @retval Q_EMPTY      if the queue is empty (the lower driver usually

  *                      disables the interrupt source when this happens).

+ *

+ * @iclass

  */

 msg_t sdRequestDataI(SerialDriver *sdp) {

   msg_t  b;

@@ -229,6 +241,8 @@ msg_t sdRequestDataI(SerialDriver *sdp) {
  *

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

  * @param[in] mask      condition flags to be added to the mask

+ *

+ * @iclass

  */

 void sdAddFlagsI(SerialDriver *sdp, sdflags_t mask) {

 

@@ -244,6 +258,8 @@ void sdAddFlagsI(SerialDriver *sdp, sdflags_t mask) {
  * @param[in] sdp       pointer to a @p SerialDriver structure

  * @return              The condition flags modified since last time this

  *                      function was invoked.

+ *

+ * @api

  */

 sdflags_t sdGetAndClearFlags(SerialDriver *sdp) {

   sdflags_t mask;

diff --git a/os/hal/src/spi.c b/os/hal/src/spi.c
index 29e69a283..85cb941e6 100644
--- a/os/hal/src/spi.c
+++ b/os/hal/src/spi.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   SPI Driver initialization.

+ *

+ * @init

  */

 void spiInit(void) {

 

@@ -58,6 +60,8 @@ void spiInit(void) {
  * @brief   Initializes the standard part of a @p SPIDriver structure.

  *

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

+ *

+ * @init

  */

 void spiObjectInit(SPIDriver *spip) {

 

@@ -75,6 +79,8 @@ void spiObjectInit(SPIDriver *spip) {
  *

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

  * @param[in] config    pointer to the @p SPIConfig object

+ *

+ * @api

  */

 void spiStart(SPIDriver *spip, const SPIConfig *config) {

 

@@ -94,6 +100,8 @@ void spiStart(SPIDriver *spip, const SPIConfig *config) {
  * @brief Deactivates the SPI peripheral.

  *

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

+ *

+ * @api

  */

 void spiStop(SPIDriver *spip) {

 

@@ -112,6 +120,8 @@ void spiStop(SPIDriver *spip) {
  * @brief   Asserts the slave select signal and prepares for transfers.

  *

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

+ *

+ * @api

  */

 void spiSelect(SPIDriver *spip) {

 

@@ -132,6 +142,8 @@ void spiSelect(SPIDriver *spip) {
  * @details The previously selected peripheral is unselected.

  *

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

+ *

+ * @api

  */

 void spiUnselect(SPIDriver *spip) {

 

@@ -155,6 +167,8 @@ void spiUnselect(SPIDriver *spip) {
  *

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

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

+ *

+ * @api

  */

 void spiIgnore(SPIDriver *spip, size_t n) {

 

@@ -176,6 +190,8 @@ void spiIgnore(SPIDriver *spip, size_t n) {
  * @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

+ *

+ * @api

  */

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

 

@@ -196,6 +212,8 @@ void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) {
  * @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

+ *

+ * @api

  */

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

 

@@ -216,6 +234,8 @@ void spiSend(SPIDriver *spip, size_t n, const void *txbuf) {
  * @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

+ *

+ * @api

  */

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

 

@@ -233,11 +253,12 @@ void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) {
  * @brief   Gains exclusive access to the SPI bus.

  * @details This function tries to gain ownership to the SPI bus, if the bus

  *          is already being used then the invoking thread is queued.

- * @note    This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION

- *          option is set to @p TRUE.

+ * @pre     In order to use this function the option @p SPI_USE_MUTUAL_EXCLUSION

+ *          must be enabled.

  *

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

  *

+ * @api

  */

 void spiAcquireBus(SPIDriver *spip) {

 

@@ -252,10 +273,12 @@ void spiAcquireBus(SPIDriver *spip) {
 

 /**

  * @brief   Releases exclusive access to the SPI bus.

- * @note    This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION

- *          option is set to @p TRUE.

+ * @pre     In order to use this function the option @p SPI_USE_MUTUAL_EXCLUSION

+ *          must be enabled.

  *

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

+ *

+ * @api

  */

 void spiReleaseBus(SPIDriver *spip) {

 

diff --git a/os/hal/src/uart.c b/os/hal/src/uart.c
index 097bd364b..e984655d4 100644
--- a/os/hal/src/uart.c
+++ b/os/hal/src/uart.c
@@ -48,6 +48,8 @@
 

 /**

  * @brief   UART Driver initialization.

+ *

+ * @init

  */

 void uartInit(void) {

 

@@ -58,6 +60,8 @@ void uartInit(void) {
  * @brief   Initializes the standard part of a @p UARTDriver structure.

  *

  * @param[in] uartp     pointer to the @p UARTDriver object

+ *

+ * @init

  */

 void uartObjectInit(UARTDriver *uartp) {

 

@@ -72,6 +76,8 @@ void uartObjectInit(UARTDriver *uartp) {
  *

  * @param[in] uartp     pointer to the @p UARTDriver object

  * @param[in] config    pointer to the @p UARTConfig object

+ *

+ * @api

  */

 void uartStart(UARTDriver *uartp, const UARTConfig *config) {

 

@@ -93,6 +99,8 @@ void uartStart(UARTDriver *uartp, const UARTConfig *config) {
  * @brief   Deactivates the UART peripheral.

  *

  * @param[in] uartp     pointer to the @p UARTDriver object

+ *

+ * @api

  */

 void uartStop(UARTDriver *uartp) {

 

@@ -119,6 +127,8 @@ void uartStop(UARTDriver *uartp) {
  * @param[in] uartp     pointer to the @p UARTDriver object

  * @param[in] n         number of data frames to send

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

+ *

+ * @api

  */

 void uartStartSend(UARTDriver *uartp, size_t n, const void *txbuf) {

 

@@ -145,6 +155,8 @@ void uartStartSend(UARTDriver *uartp, size_t n, const void *txbuf) {
  * @param[in] uartp     pointer to the @p UARTDriver object

  * @param[in] n         number of data frames to send

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

+ *

+ * @iclass

  */

 void uartStartSendI(UARTDriver *uartp, size_t n, const void *txbuf) {

 

@@ -168,6 +180,8 @@ void uartStartSendI(UARTDriver *uartp, size_t n, const void *txbuf) {
  * @return              The number of data frames not transmitted by the

  *                      stopped transmit operation.

  * @retval 0            There was no transmit operation in progress.

+ *

+ * @api

  */

 size_t uartStopSend(UARTDriver *uartp) {

   size_t n;

@@ -199,6 +213,8 @@ size_t uartStopSend(UARTDriver *uartp) {
  * @return              The number of data frames not transmitted by the

  *                      stopped transmit operation.

  * @retval 0            There was no transmit operation in progress.

+ *

+ * @iclass

  */

 size_t uartStopSendI(UARTDriver *uartp) {

 

@@ -224,6 +240,8 @@ size_t uartStopSendI(UARTDriver *uartp) {
  * @param[in] uartp     pointer to the @p UARTDriver object

  * @param[in] n         number of data frames to send

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

+ *

+ * @api

  */

 void uartStartReceive(UARTDriver *uartp, size_t n, void *rxbuf) {

 

@@ -250,6 +268,8 @@ void uartStartReceive(UARTDriver *uartp, size_t n, void *rxbuf) {
  * @param[in] uartp     pointer to the @p UARTDriver object

  * @param[in] n         number of data frames to send

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

+ *

+ * @iclass

  */

 void uartStartReceiveI(UARTDriver *uartp, size_t n, void *rxbuf) {

 

@@ -274,6 +294,8 @@ void uartStartReceiveI(UARTDriver *uartp, size_t n, void *rxbuf) {
  * @return              The number of data frames not received by the

  *                      stopped receive operation.

  * @retval 0            There was no receive operation in progress.

+ *

+ * @api

  */

 size_t uartStopReceive(UARTDriver *uartp) {

   size_t n;

@@ -305,6 +327,8 @@ size_t uartStopReceive(UARTDriver *uartp) {
  * @return              The number of data frames not received by the

  *                      stopped receive operation.

  * @retval 0            There was no receive operation in progress.

+ *

+ * @iclass

  */

 size_t uartStopReceiveI(UARTDriver *uartp) {

   chDbgCheck(uartp != NULL, "uartStopReceiveI");