From f17db1931e95f5ebb42f557b6eead2bf1320db5a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 6 Feb 2010 10:55:53 +0000 Subject: Reformatted doxygen tags into the kernel sources to make them more readable. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1567 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/src/chqueues.c | 177 +++++++++++++++++++++++------------------------ 1 file changed, 88 insertions(+), 89 deletions(-) (limited to 'os/kernel/src/chqueues.c') diff --git a/os/kernel/src/chqueues.c b/os/kernel/src/chqueues.c index 6a951f223..50f1f2401 100644 --- a/os/kernel/src/chqueues.c +++ b/os/kernel/src/chqueues.c @@ -18,8 +18,9 @@ */ /** - * @file chqueues.c - * @brief I/O Queues code. + * @file chqueues.c + * @brief I/O Queues code. + * * @addtogroup io_queues * @{ */ @@ -29,18 +30,17 @@ #if CH_USE_QUEUES /** - * @brief Initializes an input queue. + * @brief Initializes an input queue. * @details A Semaphore is internally initialized and works as a counter of * the bytes contained in the queue. + * @note The callback is invoked from within the S-Locked system state, + * see @ref system_states. * - * @param[out] iqp pointer to an @p InputQueue structure - * @param[in] bp pointer to a memory area allocated as queue buffer - * @param[in] size size of the queue buffer - * @param[in] infy pointer to a callback function that is invoked when - * data is read from the queue. The value can be @p NULL. - * - * @note The callback is invoked from within the S-Locked system state, - * see @ref system_states. + * @param[out] iqp pointer to an @p InputQueue structure + * @param[in] bp pointer to a memory area allocated as queue buffer + * @param[in] size size of the queue buffer + * @param[in] infy pointer to a callback function that is invoked when + * data is read from the queue. The value can be @p NULL. */ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) { @@ -51,13 +51,13 @@ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) { } /** - * @brief Resets an input queue. + * @brief Resets an input queue. * @details All the data in the input queue is erased and lost, any waiting * thread is resumed with status @p Q_RESET. - * @note A reset operation can be used by a low level driver in order to obtain - * immediate attention from the high level layers. + * @note A reset operation can be used by a low level driver in order to + * obtain immediate attention from the high level layers. * - * @param[in] iqp pointer to an @p InputQueue structure + * @param[in] iqp pointer to an @p InputQueue structure */ void chIQResetI(InputQueue *iqp) { @@ -66,14 +66,15 @@ void chIQResetI(InputQueue *iqp) { } /** - * @brief Input queue write. + * @brief Input queue write. * @details A byte value is written into the low end of an input queue. * - * @param[in] iqp pointer to an @p InputQueue structure - * @param[in] b the byte value to be written in the queue - * @return The operation status, it can be one of: - * @retval Q_OK if the operation has been completed with success. - * @retval Q_FULL if the queue is full and the operation cannot be completed. + * @param[in] iqp pointer to an @p InputQueue structure + * @param[in] b the byte value to be written in the queue + * @return The operation status, it can be one of: + * @retval Q_OK if the operation has been completed with success. + * @retval Q_FULL if the queue is full and the operation cannot be + * completed. */ msg_t chIQPutI(InputQueue *iqp, uint8_t b) { @@ -88,20 +89,20 @@ msg_t chIQPutI(InputQueue *iqp, uint8_t b) { } /** - * @brief Input queue read with timeout. + * @brief Input queue read with timeout. * @details This function reads a byte value from an input queue. If the queue * is empty then the calling thread is suspended until a byte arrives * in the queue or a timeout occurs. * - * @param[in] iqp pointer to an @p InputQueue structure - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return A byte value from the queue or: - * @retval Q_TIMEOUT if the specified time expired. - * @retval Q_RESET if the queue was reset. + * @param[in] iqp pointer to an @p InputQueue structure + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return A byte value from the queue or: + * @retval Q_TIMEOUT if the specified time expired. + * @retval Q_RESET if the queue was reset. */ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) { uint8_t b; @@ -124,25 +125,25 @@ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) { } /** - * @brief Input queue read with timeout. + * @brief Input queue read with timeout. * @details The function reads data from an input queue into a buffer. The * operation completes when the specified amount of data has been * transferred or after the specified timeout or if the queue has * been reset. - * @note The function is not atomic, if you need atomicity it is suggested - * to use a semaphore or a mutex for mutual exclusion. - * @note The queue callback is invoked before entering a sleep state and at - * the end of the transfer. + * @note The function is not atomic, if you need atomicity it is suggested + * to use a semaphore or a mutex for mutual exclusion. + * @note The queue callback is invoked before entering a sleep state and at + * the end of the transfer. * - * @param[in] iqp pointer to an @p InputQueue structure - * @param[out] bp pointer to the data buffer - * @param[in] n the maximum amount of data to be transferred - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return The number of bytes effectively transferred. + * @param[in] iqp pointer to an @p InputQueue structure + * @param[out] bp pointer to the data buffer + * @param[in] n the maximum amount of data to be transferred + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return The number of bytes effectively transferred. */ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp, size_t n, systime_t time) { @@ -180,18 +181,17 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp, } /** - * @brief Initializes an output queue. + * @brief Initializes an output queue. * @details A Semaphore is internally initialized and works as a counter of * the free bytes in the queue. + * @note The callback is invoked from within the S-Locked system state, + * see @ref system_states. * - * @param[out] oqp pointer to an @p OutputQueue structure - * @param[in] bp pointer to a memory area allocated as queue buffer - * @param[in] size size of the queue buffer - * @param[in] onfy pointer to a callback function that is invoked when - * data is written to the queue. The value can be @p NULL. - * - * @note The callback is invoked from within the S-Locked system state, - * see @ref system_states. + * @param[out] oqp pointer to an @p OutputQueue structure + * @param[in] bp pointer to a memory area allocated as queue buffer + * @param[in] size size of the queue buffer + * @param[in] onfy pointer to a callback function that is invoked when + * data is written to the queue. The value can be @p NULL. */ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) { @@ -202,14 +202,13 @@ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) { } /** - * @brief Resets an output queue. + * @brief Resets an output queue. * @details All the data in the output queue is erased and lost, any waiting * thread is resumed with status @p Q_RESET. + * @note A reset operation can be used by a low level driver in order to + * obtain immediate attention from the high level layers. * - * @param[in] oqp pointer to an @p OutputQueue structure - * - * @note A reset operation can be used by a low level driver in order to obtain - * immediate attention from the high level layers. + * @param[in] oqp pointer to an @p OutputQueue structure */ void chOQResetI(OutputQueue *oqp) { @@ -218,22 +217,22 @@ void chOQResetI(OutputQueue *oqp) { } /** - * @brief Output queue write with timeout. + * @brief Output queue write with timeout. * @details This function writes a byte value to an output queue. If the queue * is full then the calling thread is suspended until there is space * in the queue or a timeout occurs. * - * @param[in] oqp pointer to an @p OutputQueue structure - * @param[in] b the byte value to be written in the queue - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return The operation status: - * @retval Q_OK if the operation succeeded. - * @retval Q_TIMEOUT if the specified time expired. - * @retval Q_RESET if the queue was reset. + * @param[in] oqp pointer to an @p OutputQueue structure + * @param[in] b the byte value to be written in the queue + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return The operation status: + * @retval Q_OK if the operation succeeded. + * @retval Q_TIMEOUT if the specified time expired. + * @retval Q_RESET if the queue was reset. */ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) { msg_t msg; @@ -255,12 +254,12 @@ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) { } /** - * @brief Output queue read. + * @brief Output queue read. * @details A byte value is read from the low end of an output queue. * - * @param[in] oqp pointer to an @p OutputQueue structure - * @return The byte value from the queue or: - * @retval Q_EMPTY if the queue is empty. + * @param[in] oqp pointer to an @p OutputQueue structure + * @return The byte value from the queue or: + * @retval Q_EMPTY if the queue is empty. */ msg_t chOQGetI(OutputQueue *oqp) { uint8_t b; @@ -276,25 +275,25 @@ msg_t chOQGetI(OutputQueue *oqp) { } /** - * @brief Output queue write with timeout. + * @brief Output queue write with timeout. * @details The function writes data from a buffer to an output queue. The * operation completes when the specified amount of data has been * transferred or after the specified timeout or if the queue has * been reset. - * @note The function is not atomic, if you need atomicity it is suggested - * to use a semaphore or a mutex for mutual exclusion. - * @note The queue callback is invoked before entering a sleep state and at - * the end of the transfer. + * @note The function is not atomic, if you need atomicity it is suggested + * to use a semaphore or a mutex for mutual exclusion. + * @note The queue callback is invoked before entering a sleep state and at + * the end of the transfer. * - * @param[in] oqp pointer to an @p OutputQueue structure - * @param[out] bp pointer to the data buffer - * @param[in] n the maximum amount of data to be transferred - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @return The number of bytes effectively transferred. + * @param[in] oqp pointer to an @p OutputQueue structure + * @param[out] bp pointer to the data buffer + * @param[in] n the maximum amount of data to be transferred + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @return The number of bytes effectively transferred. */ size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp, size_t n, systime_t time) { -- cgit v1.2.3