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

1 files changed, 124 insertions, 123 deletions

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.<br>

+ *          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.<br>

- *       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.<br>

+ *          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.<br>

- *       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 */