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

1 files changed, 88 insertions, 89 deletions

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) {