From 1a7524add7dabf81895a6e6cb170c2b417da4c18 Mon Sep 17 00:00:00 2001 From: Giovanni Di Sirio Date: Sun, 3 Jan 2016 10:53:23 +0000 Subject: Documentation-related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@8672 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/src/hal_buffers.c | 23 +++++++++++++++++++---- os/hal/src/uart.c | 4 +++- 2 files changed, 22 insertions(+), 5 deletions(-) (limited to 'os/hal/src') diff --git a/os/hal/src/hal_buffers.c b/os/hal/src/hal_buffers.c index 2dae9771e..a01de2793 100644 --- a/os/hal/src/hal_buffers.c +++ b/os/hal/src/hal_buffers.c @@ -19,6 +19,20 @@ * @brief I/O Buffers code. * * @addtogroup HAL_BUFFERS + * @details Buffers Queues are used when there is the need to exchange + * fixed-length data buffers between ISRs and threads. + * On the ISR side data can be exchanged only using buffers, + * on the thread side data can be exchanged both using buffers and/or + * using an emulation of regular byte queues. + * There are several kind of buffers queues:
+ * - Input queue, unidirectional queue where the writer is the + * ISR side and the reader is the thread side. + * - Output queue, unidirectional queue where the writer is the + * ISR side and the reader is the thread side. + * - Full duplex queue, bidirectional queue. Full duplex queues + * are implemented by pairing an input queue and an output queue + * together. + * . * @{ */ @@ -155,7 +169,7 @@ void ibqPostFullBufferI(input_buffers_queue_t *ibqp, size_t size) { * @brief Gets the next filled buffer from the queue. * @note The function always acquires the same buffer if called repeatedly. * @post After calling the function the fields @p ptr and @p top are set - * at beginning and end of the buffer data or @NULL if the queue + * at beginning and end of the buffer data or @p NULL if the queue * is empty. * * @param[in] ibqp pointer to the @p input_buffers_queue_t object @@ -186,7 +200,7 @@ msg_t ibqGetFullBufferTimeout(input_buffers_queue_t *ibqp, * @brief Gets the next filled buffer from the queue. * @note The function always acquires the same buffer if called repeatedly. * @post After calling the function the fields @p ptr and @p top are set - * at beginning and end of the buffer data or @NULL if the queue + * at beginning and end of the buffer data or @p NULL if the queue * is empty. * * @param[in] ibqp pointer to the @p input_buffers_queue_t object @@ -525,7 +539,7 @@ void obqReleaseEmptyBufferI(output_buffers_queue_t *obqp) { * @brief Gets the next empty buffer from the queue. * @note The function always acquires the same buffer if called repeatedly. * @post After calling the function the fields @p ptr and @p top are set - * at beginning and end of the buffer data or @NULL if the queue + * at beginning and end of the buffer data or @p NULL if the queue * is empty. * * @param[in] obqp pointer to the @p output_buffers_queue_t object @@ -556,7 +570,7 @@ msg_t obqGetEmptyBufferTimeout(output_buffers_queue_t *obqp, * @brief Gets the next empty buffer from the queue. * @note The function always acquires the same buffer if called repeatedly. * @post After calling the function the fields @p ptr and @p top are set - * at beginning and end of the buffer data or @NULL if the queue + * at beginning and end of the buffer data or @p NULL if the queue * is empty. * * @param[in] obqp pointer to the @p output_buffers_queue_t object @@ -650,6 +664,7 @@ void obqPostFullBufferS(output_buffers_queue_t *obqp, size_t size) { * new buffer is freed in the queue or a timeout occurs. * * @param[in] obqp pointer to the @p output_buffers_queue_t object + * @param[in] b byte value to be transferred * @param[in] timeout the number of ticks before the operation timeouts, * the following special values are allowed: * - @a TIME_IMMEDIATE immediate timeout. diff --git a/os/hal/src/uart.c b/os/hal/src/uart.c index f521412ec..96f2bed5f 100644 --- a/os/hal/src/uart.c +++ b/os/hal/src/uart.c @@ -320,7 +320,7 @@ size_t uartStopReceive(UARTDriver *uartp) { * @note Stopping a receive operation also suppresses the receive callbacks. * @note This function has to be invoked from a lock zone. * - * @param[in] uartp pointer to the @p UARTDriver object + * @param[in] uartp pointer to the @p UARTDriver object * * @return The number of data frames not received by the * stopped receive operation. @@ -354,6 +354,7 @@ size_t uartStopReceiveI(UARTDriver *uartp) { * @param[in,out] np number of data frames to transmit, on exit the number * of frames actually transmitted * @param[in] txbuf the pointer to the transmit buffer + * @param[in] time operation timeout * @return The operation status. * @retval MSG_OK if the operation completed successfully. * @retval MSG_TIMEOUT if the operation timed out. @@ -396,6 +397,7 @@ msg_t uartSendTimeout(UARTDriver *uartp, size_t *np, * @param[in,out] np number of data frames to transmit, on exit the number * of frames actually transmitted * @param[in] txbuf the pointer to the transmit buffer + * @param[in] time operation timeout * @return The operation status. * @retval MSG_OK if the operation completed successfully. * @retval MSG_TIMEOUT if the operation timed out. -- cgit v1.2.3