diff options
Diffstat (limited to 'os/kernel/src/chevents.c')
| -rw-r--r-- | os/kernel/src/chevents.c | 73 |
1 files changed, 44 insertions, 29 deletions
diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c index 22739443f..aac3a22af 100644 --- a/os/kernel/src/chevents.c +++ b/os/kernel/src/chevents.c @@ -46,22 +46,27 @@ * Event Source will be signaled with an events mask.<br>
* An unlimited number of Event Sources can exists in a system and
* each thread can be listening on an unlimited number of
- * them.<br><br>
- * In order to use the Events APIs the @p CH_USE_EVENTS option must be
+ * them.
+ * @pre In order to use the Events APIs the @p CH_USE_EVENTS option must be
* enabled in @p chconf.h.
+ * @post Enabling events requires 1-4 (depending on the architecture)
+ * extra bytes in the @p Thread structure.
* @{
*/
#include "ch.h"
-#if CH_USE_EVENTS
+#if CH_USE_EVENTS || defined(__DOXYGEN__)
/**
* @brief Registers an Event Listener on an Event Source.
- * @note Multiple Event Listeners can specify the same bits to be pended.
+ * @details Once a thread has registered as listener on an event source it
+ * will be notified of all events broadcasted there.
+ * @note Multiple Event Listeners can specify the same bits to be ORed to
+ * different threads.
*
* @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
+ * @param[in] mask the mask of event flags to be ORed to the thread when
* the event source is broadcasted
*/
void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
@@ -110,7 +115,7 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) { * @param[in] mask the events to be cleared
* @return The pending events that were cleared.
*/
-eventmask_t chEvtClear(eventmask_t mask) {
+eventmask_t chEvtClearFlags(eventmask_t mask) {
eventmask_t m;
chSysLock();
@@ -123,13 +128,13 @@ 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 Adds (OR) 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
+ * @param[in] mask the event flags to be ORed
* @return The current pending events mask.
*/
-eventmask_t chEvtPend(eventmask_t mask) {
+eventmask_t chEvtAddFlags(eventmask_t mask) {
chSysLock();
@@ -140,10 +145,10 @@ eventmask_t chEvtPend(eventmask_t mask) { }
/**
- * @brief Pends a set of event flags on the specified @p Thread.
+ * @brief Adds (OR) 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] mask the event flags set to be ORed
*/
void chEvtSignal(Thread *tp, eventmask_t mask) {
@@ -156,10 +161,14 @@ void chEvtSignal(Thread *tp, eventmask_t mask) { }
/**
- * @brief Pends a set of event flags on the specified @p Thread.
+ * @brief Adds (OR) a set of event flags on the specified @p Thread.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel. Note that
+ * interrupt handlers always reschedule on exit so an explicit
+ * reschedule must not be performed in ISRs.
*
* @param[in] tp the thread to be signaled
- * @param[in] mask the event flags set to be pended
+ * @param[in] mask the event flags set to be ORed
*/
void chEvtSignalI(Thread *tp, eventmask_t mask) {
@@ -191,6 +200,10 @@ void chEvtBroadcast(EventSource *esp) { /**
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel. Note that
+ * interrupt handlers always reschedule on exit so an explicit
+ * reschedule must not be performed in ISRs.
*
* @param[in] esp pointer to the @p EventSource structure
*/
@@ -209,7 +222,7 @@ void chEvtBroadcastI(EventSource *esp) { /**
* @brief Invokes the event handlers associated to an event flags mask.
*
- * @param[in] mask mask of the events to be dispatched
+ * @param[in] mask mask of the event flags 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.
*/
@@ -242,8 +255,8 @@ void chEvtDispatch(const evhandler_t *handlers, eventmask_t mask) { * 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] mask mask of the event flags 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 mask) {
@@ -269,8 +282,8 @@ eventmask_t chEvtWaitOne(eventmask_t mask) { * @details The function waits for any event among those specified in
* @p mask to become pending then the events are cleared and returned.
*
- * @param[in] mask mask of the events that the function should wait for,
- * @p ALL_EVENTS enables all the events
+ * @param[in] mask mask of the event flags 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 mask) {
@@ -295,7 +308,8 @@ eventmask_t chEvtWaitAny(eventmask_t mask) { * @details The function waits for all the events specified in @p mask to
* become pending then the events are cleared and returned.
*
- * @param[in] mask mask of the event ids that the function should wait for
+ * @param[in] mask mask of the event flags that the function should wait
+ * for, @p ALL_EVENTS requires all the events
* @return The mask of the served and cleared events.
*/
eventmask_t chEvtWaitAll(eventmask_t mask) {
@@ -314,7 +328,7 @@ eventmask_t chEvtWaitAll(eventmask_t mask) { }
#endif /* CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT */
-#if CH_USE_EVENTS_TIMEOUT
+#if CH_USE_EVENTS_TIMEOUT || defined(__DOXYGEN__)
/**
* @brief Waits for exactly one of the specified events.
* @details The function waits for one event among those specified in
@@ -325,15 +339,15 @@ eventmask_t chEvtWaitAll(eventmask_t mask) { * 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] mask mask of the event flagss 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.
+ * @retval 0 if the operation has timed out.
*/
eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
@@ -362,15 +376,15 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) { * @p mask to become pending then the events are cleared and
* returned.
*
- * @param[in] mask mask of the events that the function should wait for,
- * @p ALL_EVENTS enables all the events
+ * @param[in] mask mask of the event flags 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.
+ * @retval 0 if the operation has timed out.
*/
eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
@@ -397,14 +411,15 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) { * @details The function waits for all the events specified in @p mask to
* become pending then the events are cleared and returned.
*
- * @param[in] mask mask of the event ids that the function should wait for
+ * @param[in] mask mask of the event flags that the function should wait
+ * for, @p ALL_EVENTS requires 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.
+ * @retval 0 if the operation has timed out.
*/
eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
|