From 2891f7d645c4be187ac96ee4011207531d25c34a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 4 Oct 2010 17:16:18 +0000 Subject: 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 --- os/hal/src/adc.c | 20 +++++++++++++++++++ os/hal/src/can.c | 21 ++++++++++++++++++++ os/hal/src/hal.c | 2 ++ os/hal/src/i2c.c | 30 +++++++++++++++++++++++++---- os/hal/src/mac.c | 17 ++++++++++++++++- os/hal/src/mmc_spi.c | 54 +++++++++++++++++++++++++++++++++++++++++++--------- os/hal/src/pal.c | 6 ++++++ os/hal/src/pwm.c | 12 ++++++++++++ os/hal/src/serial.c | 16 ++++++++++++++++ os/hal/src/spi.c | 31 ++++++++++++++++++++++++++---- os/hal/src/uart.c | 24 +++++++++++++++++++++++ 11 files changed, 215 insertions(+), 18 deletions(-) (limited to 'os/hal/src') 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"); -- cgit v1.2.3