From f17db1931e95f5ebb42f557b6eead2bf1320db5a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 6 Feb 2010 10:55:53 +0000 Subject: 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 --- os/kernel/src/chevents.c | 247 ++++++++++++++++++++++++----------------------- 1 file changed, 124 insertions(+), 123 deletions(-) (limited to 'os/kernel/src/chevents.c') diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c index 9da61adaf..310f04212 100644 --- a/os/kernel/src/chevents.c +++ b/os/kernel/src/chevents.c @@ -18,8 +18,9 @@ */ /** - * @file chevents.c - * @brief Events code. + * @file chevents.c + * @brief Events code. + * * @addtogroup events * @{ */ @@ -27,15 +28,15 @@ #if CH_USE_EVENTS /** - * @brief Registers an Event Listener on an Event Source. + * @brief Registers an Event Listener on an Event Source. + * @note Multiple Event Listeners can specify the same bits to be pended. * - * @param[in] esp pointer to the @p EventSource structure - * @param[in] elp pointer to the @p EventListener structure - * @param[in] emask the mask of event flags to be pended to the thread when the - * event source is broadcasted - * @note Multiple Event Listeners can specify the same bits to be pended. + * @param[in] esp pointer to the @p EventSource structure + * @param[in] elp pointer to the @p EventListener structure + * @param[in] mask the mask of event flags to be pended to the thread when + * the event source is broadcasted */ -void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask) { +void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) { chDbgCheck((esp != NULL) && (elp != NULL), "chEvtRegisterMask"); @@ -43,20 +44,20 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask) elp->el_next = esp->es_next; esp->es_next = elp; elp->el_listener = currp; - elp->el_mask = emask; + elp->el_mask = mask; chSysUnlock(); } /** - * @brief Unregisters an Event Listener from its Event Source. + * @brief Unregisters an Event Listener from its Event Source. + * @note If the event listener is not registered on the specified event + * source then the function does nothing. + * @note For optimal performance it is better to perform the unregister + * operations in inverse order of the register operations (elements + * are found on top of the list). * - * @param[in] esp pointer to the @p EventSource structure - * @param[in] elp pointer to the @p EventListener structure - * @note If the event listener is not registered on the specified event source - * then the function does nothing. - * @note For optimal performance it is better to perform the unregister - * operations in inverse order of the register operations (elements are - * found on top of the list). + * @param[in] esp pointer to the @p EventSource structure + * @param[in] elp pointer to the @p EventListener structure */ void chEvtUnregister(EventSource *esp, EventListener *elp) { EventListener *p; @@ -76,10 +77,10 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) { } /** - * @brief Clears the pending events specified in the mask. + * @brief Clears the pending events specified in the mask. * - * @param[in] mask the events to be cleared - * @return The pending events that were cleared. + * @param[in] mask the events to be cleared + * @return The pending events that were cleared. */ eventmask_t chEvtClear(eventmask_t mask) { eventmask_t m; @@ -94,11 +95,11 @@ eventmask_t chEvtClear(eventmask_t mask) { } /** - * @brief Pends a set of event flags on the current thread, this is @b much - * faster than using @p chEvtBroadcast() or @p chEvtSignal(). + * @brief Pends a set of event flags on the current thread, this is @b much + * faster than using @p chEvtBroadcast() or @p chEvtSignal(). * - * @param[in] mask the events to be pended - * @return The current pending events mask. + * @param[in] mask the events to be pended + * @return The current pending events mask. */ eventmask_t chEvtPend(eventmask_t mask) { @@ -111,10 +112,10 @@ eventmask_t chEvtPend(eventmask_t mask) { } /** - * @brief Pends a set of event flags on the specified @p Thread. + * @brief Pends a set of event flags on the specified @p Thread. * - * @param[in] tp the thread to be signaled - * @param[in] mask the event flags set to be pended + * @param[in] tp the thread to be signaled + * @param[in] mask the event flags set to be pended */ void chEvtSignal(Thread *tp, eventmask_t mask) { @@ -126,10 +127,10 @@ void chEvtSignal(Thread *tp, eventmask_t mask) { } /** - * @brief Pends a set of event flags on the specified @p Thread. + * @brief Pends a set of event flags on the specified @p Thread. * - * @param[in] tp the thread to be signaled - * @param[in] mask the event flags set to be pended + * @param[in] tp the thread to be signaled + * @param[in] mask the event flags set to be pended */ void chEvtSignalI(Thread *tp, eventmask_t mask) { @@ -145,10 +146,10 @@ void chEvtSignalI(Thread *tp, eventmask_t mask) { } /** - * @brief Signals all the Event Listeners registered on the specified Event - * Source. + * @brief Signals all the Event Listeners registered on the specified Event + * Source. * - * @param[in] esp pointer to the @p EventSource structure + * @param[in] esp pointer to the @p EventSource structure */ void chEvtBroadcast(EventSource *esp) { @@ -159,10 +160,10 @@ void chEvtBroadcast(EventSource *esp) { } /** - * @brief Signals all the Event Listeners registered on the specified Event - * Source. + * @brief Signals all the Event Listeners registered on the specified Event + * Source. * - * @param[in] esp pointer to the @p EventSource structure + * @param[in] esp pointer to the @p EventSource structure */ void chEvtBroadcastI(EventSource *esp) { EventListener *elp; @@ -177,11 +178,11 @@ void chEvtBroadcastI(EventSource *esp) { } /** - * @brief Invokes the event handlers associated to an event flags mask. + * @brief Invokes the event handlers associated to an event flags mask. * - * @param[in] mask mask of the events to be dispatched - * @param[in] handlers an array of @p evhandler_t. The array must have size - * equal to the number of bits in eventmask_t. + * @param[in] mask mask of the events to be dispatched + * @param[in] handlers an array of @p evhandler_t. The array must have size + * equal to the number of bits in eventmask_t. */ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) { eventid_t eid; @@ -203,29 +204,29 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) { #if CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT || defined(__DOXYGEN__) /** - * @brief Waits for exactly one of the specified events. + * @brief Waits for exactly one of the specified events. * @details The function waits for one event among those specified in - * @p ewmask to become pending then the event is cleared and returned. + * @p mask to become pending then the event is cleared and returned. + * @note One and only one event is served in the function, the one with the + * lowest event id. The function is meant to be invoked into a loop in + * order to serve all the pending events.
+ * This means that Event Listeners with a lower event identifier have + * an higher priority. * - * @param[in] ewmask mask of the events that the function should wait for, - * @p ALL_EVENTS enables all the events - * @return The mask of the lowest id served and cleared event. - * @note One and only one event is served in the function, the one with the - * lowest event id. The function is meant to be invoked into a loop in - * order to serve all the pending events.
- * This means that Event Listeners with a lower event identifier have - * an higher priority. + * @param[in] mask mask of the events that the function should wait for, + * @p ALL_EVENTS enables all the events + * @return The mask of the lowest id served and cleared event. */ -eventmask_t chEvtWaitOne(eventmask_t ewmask) { +eventmask_t chEvtWaitOne(eventmask_t mask) { Thread *ctp = currp; eventmask_t m; chSysLock(); - if ((m = (ctp->p_epending & ewmask)) == 0) { - ctp->p_u.ewmask = ewmask; + if ((m = (ctp->p_epending & mask)) == 0) { + ctp->p_u.ewmask = mask; chSchGoSleepS(THD_STATE_WTOREVT); - m = ctp->p_epending & ewmask; + m = ctp->p_epending & mask; } m &= -m; ctp->p_epending &= ~m; @@ -235,24 +236,24 @@ eventmask_t chEvtWaitOne(eventmask_t ewmask) { } /** - * @brief Waits for any of the specified events. + * @brief Waits for any of the specified events. * @details The function waits for any event among those specified in - * @p ewmask to become pending then the events are cleared and returned. + * @p mask to become pending then the events are cleared and returned. * - * @param[in] ewmask mask of the events that the function should wait for, - * @p ALL_EVENTS enables all the events - * @return The mask of the served and cleared events. + * @param[in] mask mask of the events that the function should wait for, + * @p ALL_EVENTS enables all the events + * @return The mask of the served and cleared events. */ -eventmask_t chEvtWaitAny(eventmask_t ewmask) { +eventmask_t chEvtWaitAny(eventmask_t mask) { Thread *ctp = currp; eventmask_t m; chSysLock(); - if ((m = (ctp->p_epending & ewmask)) == 0) { - ctp->p_u.ewmask = ewmask; + if ((m = (ctp->p_epending & mask)) == 0) { + ctp->p_u.ewmask = mask; chSchGoSleepS(THD_STATE_WTOREVT); - m = ctp->p_epending & ewmask; + m = ctp->p_epending & mask; } ctp->p_epending &= ~m; @@ -261,63 +262,63 @@ eventmask_t chEvtWaitAny(eventmask_t ewmask) { } /** - * @brief Waits for all the specified events. - * @details The function waits for all the events specified in @p ewmask to + * @brief Waits for all the specified events. + * @details The function waits for all the events specified in @p mask to * become pending then the events are cleared and returned. * - * @param[in] ewmask mask of the event ids that the function should wait for - * @return The mask of the served and cleared events. + * @param[in] mask mask of the event ids that the function should wait for + * @return The mask of the served and cleared events. */ -eventmask_t chEvtWaitAll(eventmask_t ewmask) { +eventmask_t chEvtWaitAll(eventmask_t mask) { Thread *ctp = currp; chSysLock(); - if ((ctp->p_epending & ewmask) != ewmask) { - ctp->p_u.ewmask = ewmask; + if ((ctp->p_epending & mask) != mask) { + ctp->p_u.ewmask = mask; chSchGoSleepS(THD_STATE_WTANDEVT); } - ctp->p_epending &= ~ewmask; + ctp->p_epending &= ~mask; chSysUnlock(); - return ewmask; + return mask; } #endif /* CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT */ #if CH_USE_EVENTS_TIMEOUT /** - * @brief Waits for exactly one of the specified events. + * @brief Waits for exactly one of the specified events. * @details The function waits for one event among those specified in - * @p ewmask to become pending then the event is cleared and returned. + * @p mask to become pending then the event is cleared and returned. + * @note One and only one event is served in the function, the one with the + * lowest event id. The function is meant to be invoked into a loop in + * order to serve all the pending events.
+ * This means that Event Listeners with a lower event identifier have + * an higher priority. * - * @param[in] ewmask mask of the events that the function should wait for, - * @p ALL_EVENTS enables all the events - * @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 mask of the lowest id served and cleared event. - * @retval 0 if the specified timeout expired. - * @note One and only one event is served in the function, the one with the - * lowest event id. The function is meant to be invoked into a loop in - * order to serve all the pending events.
- * This means that Event Listeners with a lower event identifier have - * an higher priority. + * @param[in] mask mask of the events that the function should wait for, + * @p ALL_EVENTS enables all the events + * @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 mask of the lowest id served and cleared event. + * @retval 0 if the specified timeout expired. */ -eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) { +eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) { Thread *ctp = currp; eventmask_t m; chSysLock(); - if ((m = (ctp->p_epending & ewmask)) == 0) { + if ((m = (ctp->p_epending & mask)) == 0) { if (TIME_IMMEDIATE == time) return (eventmask_t)0; - ctp->p_u.ewmask = ewmask; + ctp->p_u.ewmask = mask; if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK) return (eventmask_t)0; - m = ctp->p_epending & ewmask; + m = ctp->p_epending & mask; } m &= -m; ctp->p_epending &= ~m; @@ -327,34 +328,34 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) { } /** - * @brief Waits for any of the specified events. + * @brief Waits for any of the specified events. * @details The function waits for any event among those specified in - * @p ewmask to become pending then the events are cleared and + * @p mask to become pending then the events are cleared and * returned. * - * @param[in] ewmask mask of the events that the function should wait for, - * @p ALL_EVENTS enables all the events - * @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 mask of the served and cleared events. - * @retval 0 if the specified timeout expired. + * @param[in] mask mask of the events that the function should wait for, + * @p ALL_EVENTS enables all the events + * @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 mask of the served and cleared events. + * @retval 0 if the specified timeout expired. */ -eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) { +eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) { Thread *ctp = currp; eventmask_t m; chSysLock(); - if ((m = (ctp->p_epending & ewmask)) == 0) { + if ((m = (ctp->p_epending & mask)) == 0) { if (TIME_IMMEDIATE == time) return (eventmask_t)0; - ctp->p_u.ewmask = ewmask; + ctp->p_u.ewmask = mask; if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK) return (eventmask_t)0; - m = ctp->p_epending & ewmask; + m = ctp->p_epending & mask; } ctp->p_epending &= ~m; @@ -363,35 +364,35 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) { } /** - * @brief Waits for all the specified events. - * @details The function waits for all the events specified in @p ewmask to + * @brief Waits for all the specified events. + * @details The function waits for all the events specified in @p mask to * become pending then the events are cleared and returned. * - * @param[in] ewmask mask of the event ids that the function should wait for - * @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 mask of the served and cleared events. - * @retval 0 if the specified timeout expired. + * @param[in] mask mask of the event ids that the function should wait for + * @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 mask of the served and cleared events. + * @retval 0 if the specified timeout expired. */ -eventmask_t chEvtWaitAllTimeout(eventmask_t ewmask, systime_t time) { +eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) { Thread *ctp = currp; chSysLock(); - if ((ctp->p_epending & ewmask) != ewmask) { + if ((ctp->p_epending & mask) != mask) { if (TIME_IMMEDIATE == time) return (eventmask_t)0; - ctp->p_u.ewmask = ewmask; + ctp->p_u.ewmask = mask; if (chSchGoSleepTimeoutS(THD_STATE_WTANDEVT, time) < RDY_OK) return (eventmask_t)0; } - ctp->p_epending &= ~ewmask; + ctp->p_epending &= ~mask; chSysUnlock(); - return ewmask; + return mask; } #endif /* CH_USE_EVENTS_TIMEOUT */ -- cgit v1.2.3