From 055fea386e4994a35b758b94f948f9de1c8ba091 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 11 Dec 2014 15:12:21 +0000 Subject: Documentation related fixes. Documentation is buildable with Doxygen 1.8.8 now. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@7571 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/rt/include/chevents.h | 1 + os/rt/include/chmboxes.h | 6 +- os/rt/include/chmsg.h | 3 + os/rt/include/chmtx.h | 3 + os/rt/include/chschd.h | 252 +++++++++++++++++++++++++--------------------- os/rt/include/chsem.h | 7 ++ os/rt/include/chthreads.h | 5 + 7 files changed, 162 insertions(+), 115 deletions(-) (limited to 'os/rt/include') diff --git a/os/rt/include/chevents.h b/os/rt/include/chevents.h index 996cef31a..15511bfd8 100644 --- a/os/rt/include/chevents.h +++ b/os/rt/include/chevents.h @@ -218,6 +218,7 @@ static inline void chEvtRegister(event_source_t *esp, * @brief Verifies if there is at least one @p event_listener_t registered. * * @param[in] esp pointer to the @p event_source_t structure + * @return The event source status. * * @iclass */ diff --git a/os/rt/include/chmboxes.h b/os/rt/include/chmboxes.h index e6a0937b9..e93c14f3e 100644 --- a/os/rt/include/chmboxes.h +++ b/os/rt/include/chmboxes.h @@ -132,6 +132,7 @@ extern "C" { * @brief Returns the mailbox buffer size. * * @param[in] mbp the pointer to an initialized mailbox_t object + * @return The size of the mailbox. * * @iclass */ @@ -185,9 +186,12 @@ static inline cnt_t chMBGetUsedCountI(mailbox_t *mbp) { * to use @p chMBGetFullCountI() and then use this macro, all within * a lock state. * + * @param[in] mbp the pointer to an initialized mailbox_t object + * @return The next message in queue. + * * @iclass */ -static inline cnt_t chMBPeekI(mailbox_t *mbp) { +static inline msg_t chMBPeekI(mailbox_t *mbp) { chDbgCheckClassI(); diff --git a/os/rt/include/chmsg.h b/os/rt/include/chmsg.h index 7e935de99..d1f697477 100644 --- a/os/rt/include/chmsg.h +++ b/os/rt/include/chmsg.h @@ -72,6 +72,9 @@ extern "C" { /** * @brief Evaluates to @p true if the thread has pending messages. * + * @param[in] tp pointer to the thread + * @return The pending messages status. + * * @iclass */ static inline bool chMsgIsPendingI(thread_t *tp) { diff --git a/os/rt/include/chmtx.h b/os/rt/include/chmtx.h index ecfffae92..99eeb6f02 100644 --- a/os/rt/include/chmtx.h +++ b/os/rt/include/chmtx.h @@ -121,6 +121,9 @@ extern "C" { * @brief Returns @p true if the mutex queue contains at least a waiting * thread. * + * @param[out] mp pointer to a @p mutex_t structure + * @return The mutex queue status. + * * @deprecated * @sclass */ diff --git a/os/rt/include/chschd.h b/os/rt/include/chschd.h index f2deb3b92..3b17a417e 100644 --- a/os/rt/include/chschd.h +++ b/os/rt/include/chschd.h @@ -416,120 +416,136 @@ extern "C" { /* Module inline functions. */ /*===========================================================================*/ - /** - * @brief Threads list initialization. - * - * @notapi - */ - static inline void list_init(threads_list_t *tlp) { - - tlp->p_next = (thread_t *)tlp; - } - - /** - * @brief Evaluates to @p true if the specified threads list is empty. - * - * @notapi - */ - static inline bool list_isempty(threads_list_t *tlp) { - - return (bool)(tlp->p_next == (thread_t *)tlp); - } - - /** - * @brief Evaluates to @p true if the specified threads list is not empty. - * - * @notapi - */ - static inline bool list_notempty(threads_list_t *tlp) { - - return (bool)(tlp->p_next != (thread_t *)tlp); - } - - /** - * @brief Threads queue initialization. - * - * @notapi - */ - static inline void queue_init(threads_queue_t *tqp) { - - tqp->p_next = tqp->p_prev = (thread_t *)tqp; - } - - /** - * @brief Evaluates to @p true if the specified threads queue is empty. - * - * @notapi - */ - static inline bool queue_isempty(threads_queue_t *tqp) { - - return (bool)(tqp->p_next == (thread_t *)tqp); - } - - /** - * @brief Evaluates to @p true if the specified threads queue is not empty. - * - * @notapi - */ - static inline bool queue_notempty(threads_queue_t *tqp) { - - return (bool)(tqp->p_next != (thread_t *)tqp); - } - - /* If the performance code path has been chosen then all the following - functions are inlined into the various kernel modules.*/ - #if CH_CFG_OPTIMIZE_SPEED - static inline void list_insert(thread_t *tp, threads_list_t *tlp) { - - tp->p_next = tlp->p_next; - tlp->p_next = tp; - } - - static inline thread_t *list_remove(threads_list_t *tlp) { - - thread_t *tp = tlp->p_next; - tlp->p_next = tp->p_next; - return tp; - } - - static inline void queue_prio_insert(thread_t *tp, threads_queue_t *tqp) { - - thread_t *cp = (thread_t *)tqp; - do { - cp = cp->p_next; - } while ((cp != (thread_t *)tqp) && (cp->p_prio >= tp->p_prio)); - tp->p_next = cp; - tp->p_prev = cp->p_prev; - tp->p_prev->p_next = cp->p_prev = tp; - } - - static inline void queue_insert(thread_t *tp, threads_queue_t *tqp) { - - tp->p_next = (thread_t *)tqp; - tp->p_prev = tqp->p_prev; - tp->p_prev->p_next = tqp->p_prev = tp; - } - - static inline thread_t *queue_fifo_remove(threads_queue_t *tqp) { - thread_t *tp = tqp->p_next; - - (tqp->p_next = tp->p_next)->p_prev = (thread_t *)tqp; - return tp; - } - - static inline thread_t *queue_lifo_remove(threads_queue_t *tqp) { - thread_t *tp = tqp->p_prev; - - (tqp->p_prev = tp->p_prev)->p_next = (thread_t *)tqp; - return tp; - } - - static inline thread_t *queue_dequeue(thread_t *tp) { - - tp->p_prev->p_next = tp->p_next; - tp->p_next->p_prev = tp->p_prev; - return tp; - } +/** + * @brief Threads list initialization. + * + * @param[in] tlp pointer to the threads list object + * + * @notapi + */ +static inline void list_init(threads_list_t *tlp) { + + tlp->p_next = (thread_t *)tlp; +} + +/** + * @brief Evaluates to @p true if the specified threads list is empty. + * + * @param[in] tlp pointer to the threads list object + * @return The status of the list. + * + * @notapi + */ +static inline bool list_isempty(threads_list_t *tlp) { + + return (bool)(tlp->p_next == (thread_t *)tlp); +} + +/** + * @brief Evaluates to @p true if the specified threads list is not empty. + * + * @param[in] tlp pointer to the threads list object + * @return The status of the list. + * + * @notapi + */ +static inline bool list_notempty(threads_list_t *tlp) { + + return (bool)(tlp->p_next != (thread_t *)tlp); +} + +/** + * @brief Threads queue initialization. + * + * @param[in] tqp pointer to the threads queue object + * + * @notapi + */ +static inline void queue_init(threads_queue_t *tqp) { + + tqp->p_next = tqp->p_prev = (thread_t *)tqp; +} + +/** + * @brief Evaluates to @p true if the specified threads queue is empty. + * + * @param[in] tqp pointer to the threads queue object + * @return The status of the queue. + * + * @notapi + */ +static inline bool queue_isempty(threads_queue_t *tqp) { + + return (bool)(tqp->p_next == (thread_t *)tqp); +} + +/** + * @brief Evaluates to @p true if the specified threads queue is not empty. + * + * @param[in] tqp pointer to the threads queue object + * @return The status of the queue. + * + * @notapi + */ +static inline bool queue_notempty(threads_queue_t *tqp) { + + return (bool)(tqp->p_next != (thread_t *)tqp); +} + +/* If the performance code path has been chosen then all the following + functions are inlined into the various kernel modules.*/ +#if CH_CFG_OPTIMIZE_SPEED +static inline void list_insert(thread_t *tp, threads_list_t *tlp) { + + tp->p_next = tlp->p_next; + tlp->p_next = tp; +} + +static inline thread_t *list_remove(threads_list_t *tlp) { + + thread_t *tp = tlp->p_next; + tlp->p_next = tp->p_next; + return tp; +} + +static inline void queue_prio_insert(thread_t *tp, threads_queue_t *tqp) { + + thread_t *cp = (thread_t *)tqp; + do { + cp = cp->p_next; + } while ((cp != (thread_t *)tqp) && (cp->p_prio >= tp->p_prio)); + tp->p_next = cp; + tp->p_prev = cp->p_prev; + tp->p_prev->p_next = cp->p_prev = tp; +} + +static inline void queue_insert(thread_t *tp, threads_queue_t *tqp) { + + tp->p_next = (thread_t *)tqp; + tp->p_prev = tqp->p_prev; + tp->p_prev->p_next = tqp->p_prev = tp; +} + +static inline thread_t *queue_fifo_remove(threads_queue_t *tqp) { + thread_t *tp = tqp->p_next; + + (tqp->p_next = tp->p_next)->p_prev = (thread_t *)tqp; + return tp; +} + +static inline thread_t *queue_lifo_remove(threads_queue_t *tqp) { + thread_t *tp = tqp->p_prev; + + (tqp->p_prev = tp->p_prev)->p_next = (thread_t *)tqp; + return tp; +} + +static inline thread_t *queue_dequeue(thread_t *tp) { + + tp->p_prev->p_next = tp->p_next; + tp->p_next->p_prev = tp->p_prev; + return tp; +} #endif /* CH_CFG_OPTIMIZE_SPEED */ /** @@ -537,6 +553,10 @@ extern "C" { * @details This function returns @p true if there is a ready thread with * higher priority. * + * @return The priorities situation. + * @retval false if rescheduling is not necessary. + * @retval true if there is a ready thread at higher priority. + * * @iclass */ static inline bool chSchIsRescRequiredI(void) { @@ -551,6 +571,10 @@ static inline bool chSchIsRescRequiredI(void) { * @details This function returns @p true if there is a ready thread with * equal or higher priority. * + * @return The priorities situation. + * @retval false if yielding is not possible. + * @retval true if there is a ready thread at equal or higher priority. + * * @sclass */ static inline bool chSchCanYieldS(void) { diff --git a/os/rt/include/chsem.h b/os/rt/include/chsem.h index 4762da9df..51f9302a1 100644 --- a/os/rt/include/chsem.h +++ b/os/rt/include/chsem.h @@ -112,6 +112,8 @@ extern "C" { * @brief Decreases the semaphore counter. * @details This macro can be used when the counter is known to be positive. * + * @param[in] sp pointer to a @p semaphore_t structure + * * @iclass */ static inline void chSemFastWaitI(semaphore_t *sp) { @@ -126,6 +128,8 @@ static inline void chSemFastWaitI(semaphore_t *sp) { * @details This macro can be used when the counter is known to be not * negative. * + * @param[in] sp pointer to a @p semaphore_t structure + * * @iclass */ static inline void chSemFastSignalI(semaphore_t *sp) { @@ -138,6 +142,9 @@ static inline void chSemFastSignalI(semaphore_t *sp) { /** * @brief Returns the semaphore counter current value. * + * @param[in] sp pointer to a @p semaphore_t structure + * @return The semaphore counter value. + * * @iclass */ static inline cnt_t chSemGetCounterI(semaphore_t *sp) { diff --git a/os/rt/include/chthreads.h b/os/rt/include/chthreads.h index 4c23fbec2..24349000d 100644 --- a/os/rt/include/chthreads.h +++ b/os/rt/include/chthreads.h @@ -270,6 +270,8 @@ extern "C" { /** * @brief Returns a pointer to the current @p thread_t. * + * @return A pointer to the current thread. + * * @xclass */ static inline thread_t *chThdGetSelfX(void) { @@ -281,6 +283,8 @@ static inline thread_t *chThdGetSelfX(void) { * @brief Returns the current thread priority. * @note Can be invoked in any context. * + * @return The current thread priority. + * * @xclass */ static inline tprio_t chThdGetPriorityX(void) { @@ -294,6 +298,7 @@ static inline tprio_t chThdGetPriorityX(void) { * @p CH_DBG_THREADS_PROFILING configuration option is enabled. * * @param[in] tp pointer to the thread + * @return The number of consumed system ticks. * * @xclass */ -- cgit v1.2.3