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/dox/hal_buffers.dox | 20 ++++++++++++++++++++ os/hal/dox/hal_queues.dox | 2 +- os/hal/dox/wdg.dox | 26 ++++++++++++++++++++++++++ os/hal/include/hal_buffers.h | 4 ++-- os/hal/include/uart.h | 1 + os/hal/ports/STM32/LLD/xWDGv1/wdg_lld.c | 2 +- os/hal/src/hal_buffers.c | 23 +++++++++++++++++++---- os/hal/src/uart.c | 4 +++- os/hal/templates/wdg_lld.c | 2 +- 9 files changed, 74 insertions(+), 10 deletions(-) create mode 100644 os/hal/dox/hal_buffers.dox create mode 100644 os/hal/dox/wdg.dox diff --git a/os/hal/dox/hal_buffers.dox b/os/hal/dox/hal_buffers.dox new file mode 100644 index 000000000..fca465572 --- /dev/null +++ b/os/hal/dox/hal_buffers.dox @@ -0,0 +1,20 @@ +/* + ChibiOS - Copyright (C) 2006..2015 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_BUFFERS I/O Buffers Queues + * @ingroup HAL_INNER_CODE + */ diff --git a/os/hal/dox/hal_queues.dox b/os/hal/dox/hal_queues.dox index f1e1f753c..9edfb47eb 100644 --- a/os/hal/dox/hal_queues.dox +++ b/os/hal/dox/hal_queues.dox @@ -15,6 +15,6 @@ */ /** - * @defgroup HAL_QUEUES I/O Queues + * @defgroup HAL_QUEUES I/O Bytes Queues * @ingroup HAL_INNER_CODE */ diff --git a/os/hal/dox/wdg.dox b/os/hal/dox/wdg.dox new file mode 100644 index 000000000..4ca070479 --- /dev/null +++ b/os/hal/dox/wdg.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2015 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup WDG WDG Driver + * @brief Watchdog Timer Abstraction Layer + * @details This module defines an abstract interface for a watchdog + * timer. + * @pre In order to use the WDG driver the @p HAL_USE_WDG option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/os/hal/include/hal_buffers.h b/os/hal/include/hal_buffers.h index f992046a9..7ce499215 100644 --- a/os/hal/include/hal_buffers.h +++ b/os/hal/include/hal_buffers.h @@ -205,8 +205,8 @@ typedef io_buffers_queue_t output_buffers_queue_t; * * @iclass */ -#define obqIsEmptyI(oqp) ((bool)(((obqp)->bwrptr == (obqp)->brdptr) && \ - ((obqp)->bcounter != 0U))) +#define obqIsEmptyI(obqp) ((bool)(((obqp)->bwrptr == (obqp)->brdptr) && \ + ((obqp)->bcounter != 0U))) /** * @brief Evaluates to @p true if the specified output buffers queue is full. diff --git a/os/hal/include/uart.h b/os/hal/include/uart.h index 43afcd7d9..2942636b4 100644 --- a/os/hal/include/uart.h +++ b/os/hal/include/uart.h @@ -268,6 +268,7 @@ typedef enum { * implementation only. * * @param[in] uartp pointer to the @p UARTDriver object + * @param[in] errors mask of errors to be reported * * @notapi */ diff --git a/os/hal/ports/STM32/LLD/xWDGv1/wdg_lld.c b/os/hal/ports/STM32/LLD/xWDGv1/wdg_lld.c index 6f3ce04ff..d3ff1600d 100644 --- a/os/hal/ports/STM32/LLD/xWDGv1/wdg_lld.c +++ b/os/hal/ports/STM32/LLD/xWDGv1/wdg_lld.c @@ -126,7 +126,7 @@ void wdg_lld_stop(WDGDriver *wdgp) { /** * @brief Reloads WDG's counter. * - * @param[in] idwgp pointer to the @p WDGDriver object + * @param[in] wdgp pointer to the @p WDGDriver object * * @notapi */ 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. diff --git a/os/hal/templates/wdg_lld.c b/os/hal/templates/wdg_lld.c index 4732928ac..c08bb0d20 100644 --- a/os/hal/templates/wdg_lld.c +++ b/os/hal/templates/wdg_lld.c @@ -88,7 +88,7 @@ void wdg_lld_stop(WDGDriver *wdgp) { /** * @brief Reloads WDG's counter. * - * @param[in] idwgp pointer to the @p WDGDriver object + * @param[in] wdgp pointer to the @p WDGDriver object * * @notapi */ -- cgit v1.2.3