From a9dacc80cbd84c8a1bc1e19e96a92a4fac18e51f Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 1 Jan 2011 11:48:59 +0000 Subject: [PATCH] Fixed bug 3149141, documentation improvements to the queues, updated pre-2.2.0 plan in todo.txt. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2562 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/include/chqueues.h | 78 ++++++++++++++++++++++++------------ readme.txt | 2 + todo.txt | 15 ++++++- 3 files changed, 68 insertions(+), 27 deletions(-) diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h index 80f206f5b..440c51f81 100644 --- a/os/kernel/include/chqueues.h +++ b/os/kernel/include/chqueues.h @@ -52,7 +52,7 @@ typedef void (*qnotify_t)(void); #define Q_FULL -4 /** - * @brief Generic I/O queue structure. + * @brief Type of a generic I/O queue structure. * @details This structure represents a generic Input or Output asymmetrical * queue. The queue is asymmetrical because one end is meant to be * accessed from a thread context, and thus can be blocking, the other @@ -73,27 +73,33 @@ typedef struct { /** * @brief Returns the queue's buffer size. * - * @iclass - */ -#define chQSizeI(q) ((q)->q_top - (q)->q_buffer) - -/** - * @brief Queue space. - * @details Returns the used space if used on an Input Queue and the empty - * space if used on an Output Queue. - * @note The returned value can be less than zero when there are waiting - * threads on the internal semaphore. + * @param[in] qp pointer to a @p GenericQueue structure. + * @return The buffer size. * * @iclass */ -#define chQSpaceI(q) chSemGetCounterI(&(q)->q_sem) +#define chQSizeI(qp) ((qp)->q_top - (qp)->q_buffer) + +/** + * @brief Queue space. + * @details Returns the used space if used on an input queue or the empty + * space if used on an output queue. + * @note The returned value can be less than zero when there are waiting + * threads on the internal semaphore. + * + * @param[in] qp pointer to a @p GenericQueue structure. + * @return The buffer space. + * + * @iclass + */ +#define chQSpaceI(qp) chSemGetCounterI(&(qp)->q_sem) /** * @extends GenericQueue * - * @brief Input queue structure. + * @brief Type of an input queue structure. * @details This structure represents a generic asymmetrical input queue. - * Writing in the queue is non-blocking and can be performed from + * Writing to the queue is non-blocking and can be performed from * interrupt handlers or from within a kernel lock zone (see * I-Locked and S-Locked states in @ref system_states). * Reading the queue can be a blocking operation and is supposed to @@ -102,18 +108,28 @@ typedef struct { typedef GenericQueue InputQueue; /** - * @brief Evaluates to @p TRUE if the specified Input Queue is empty. + * @brief Evaluates to @p TRUE if the specified input queue is empty. + * + * @param[in] iqp pointer to an @p InputQueue structure. + * @return The queue status. + * @retval FALSE The queue is not empty. + * @retval TRUE The queue is empty. * * @iclass */ -#define chIQIsEmptyI(q) ((bool_t)(chQSpaceI(q) <= 0)) +#define chIQIsEmptyI(iqp) ((bool_t)(chQSpaceI(iqp) <= 0)) /** - * @brief Evaluates to @p TRUE if the specified Input Queue is full. + * @brief Evaluates to @p TRUE if the specified input queue is full. + * + * @param[in] iqp pointer to an @p InputQueue structure. + * @return The queue status. + * @retval FALSE The queue is not full. + * @retval TRUE The queue is full. * * @iclass */ -#define chIQIsFullI(q) ((bool_t)(chQSpaceI(q) >= chQSizeI(q))) +#define chIQIsFullI(iqp) ((bool_t)(chQSpaceI(iqp) >= chQSizeI(iqp))) /** * @brief Input queue read. @@ -123,7 +139,7 @@ typedef GenericQueue InputQueue; * * @param[in] iqp pointer to an @p InputQueue structure * @return A byte value from the queue. - * @retval Q_RESET if the queue was reset. + * @retval Q_RESET If the queue has been reset. * * @api */ @@ -164,7 +180,7 @@ typedef GenericQueue InputQueue; /** * @extends GenericQueue * - * @brief Output queue structure. + * @brief Type of an output queue structure. * @details This structure represents a generic asymmetrical output queue. * Reading from the queue is non-blocking and can be performed from * interrupt handlers or from within a kernel lock zone (see @@ -175,14 +191,24 @@ typedef GenericQueue InputQueue; typedef GenericQueue OutputQueue; /** - * @brief Evaluates to @p TRUE if the specified Output Queue is empty. + * @brief Evaluates to @p TRUE if the specified output queue is empty. + * + * @param[in] oqp pointer to an @p OutputQueue structure. + * @return The queue status. + * @retval FALSE The queue is not empty. + * @retval TRUE The queue is empty. * * @iclass */ #define chOQIsEmptyI(q) ((bool_t)(chQSpaceI(q) >= chQSizeI(q))) /** - * @brief Evaluates to @p TRUE if the specified Output Queue is full. + * @brief Evaluates to @p TRUE if the specified output queue is full. + * + * @param[in] oqp pointer to an @p OutputQueue structure. + * @return The queue status. + * @retval FALSE The queue is not full. + * @retval TRUE The queue is full. * * @iclass */ @@ -198,7 +224,7 @@ typedef GenericQueue OutputQueue; * @param[in] b the byte value to be written in the queue * @return The operation status. * @retval Q_OK if the operation succeeded. - * @retval Q_RESET if the queue was reset. + * @retval Q_RESET if the queue has been reset. * * @api */ @@ -209,7 +235,7 @@ typedef GenericQueue OutputQueue; * @details This macro should be used when statically initializing an * output queue that is part of a bigger structure. * - * @param[in] name the name of the output queue variable. + * @param[in] name the name of the output queue variable * @param[in] buffer pointer to the queue buffer area * @param[in] size size of the queue buffer area * @param[in] onotify output notification callback pointer @@ -224,7 +250,7 @@ typedef GenericQueue OutputQueue; } /** - * @brief Static output queue initializer. + * @brief Static output queue initializer. * @details Statically initialized output queues require no explicit * initialization using @p chOQInit(). * @@ -234,7 +260,7 @@ typedef GenericQueue OutputQueue; * @param[in] onotify output notification callback pointer */ #define OUTPUTQUEUE_DECL(name, buffer, size, onotify) \ - InputQueue name = _OUTPUTQUEUE_DATA(name, buffer, size, onotify) + OutputQueue name = _OUTPUTQUEUE_DATA(name, buffer, size, onotify) #ifdef __cplusplus extern "C" { diff --git a/readme.txt b/readme.txt index 23066ebab..342f92189 100644 --- a/readme.txt +++ b/readme.txt @@ -65,6 +65,8 @@ ***************************************************************************** *** 2.1.7 *** +- FIX: Fixed error in output queues static initializer (bug 3149141) + (backported to 2.0.9). - FIX: Fixed extra notifications in input queues (bug 3148525)(backported to 2.0.9). - NEW: New ARM Cortex-Mx port for RVCT compiler (probably will not be diff --git a/todo.txt b/todo.txt index 3fa61906a..438dc6adf 100644 --- a/todo.txt +++ b/todo.txt @@ -59,9 +59,22 @@ N Evaluate if to add a synchronous API to the UART driver, eventually do so. and general solutions. X Support for more compilers (IAR, Keil, ARMCMx only initially). X Support for not just Makefiles (Ride7, Crossworks etc). -- Make thread functions return void. +? Make thread functions return void. - Introduce a "THREAD" function prefix in order to hide compiler-specific optimizations for thread functions. +- Move I/O queues out of the kernel into an new "oslib" category. +- Add an I/O buffers mechanism to the oslib category. +- Move MemStreams to the oslib category. +- Move iochannels and file interfaces to the oslib category. +? Evaluate moving mailboxes to the oslib category. +- Make the oslib category appear in the general documentation and the various + kernel reference manuals. +- IAR port for Cortex-Mx, add demos for all the supported families. +- Keil port for Cortex-Mx, add demos for all the supported families. +- Add an USB abstract device driver class. +- USB driver implementation for STM32F103/STM32F102. +- Add a Serial over USB generic device driver implementing a USB Communication + Device Class and offering a Serial-like interface to the applications. X Except for the above, bug fixing only until the 2.2.0 release. Within 2.3.x (hopefully)