move TIMER_AFTER() and TIMER_BEFORE() macros in drv/timer.h

[bertos.git] / bertos / mware / event.h

diff --git a/bertos/mware/event.h b/bertos/mware/event.h
index e640105669490d7d7c25d8c5f731202ac5098f83..5bc94e9ef3b875ad6ce84654ec90867273271a2c 100644 (file)
--- a/bertos/mware/event.h
+++ b/bertos/mware/event.h
@@ -30,12 +30,15 @@
  * Copyright 1999, 2001, 2003 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
+ * \defgroup event_handling Event handling module
+ * \ingroup core
+ * \{
+ *
  * \brief Events handling
  *
  * This module implements a common system for executing
  * a user defined action calling a hook function.
  *
- *  NOTE: Generic completion events
  *
  *  Device drivers often need to wait the completion of some event, usually to
  *  allow the hardware to accomplish some asynchronous task.
@@ -64,7 +67,7 @@
  *  behaviour with or without the kernel.
  *
  *  Example usage (wait for a generic device driver initialization):
- *  \verbatim
+ *  \code
  *  static Event e;
  *
  *  static void irq_handler(void)
@@ -82,7 +85,7 @@
  *      // Wait for the completion of the event
  *      event_wait(&e);
  *  }
- *  \endverbatim
+ *  \endcode
  *
  * \author Bernie Innocenti <bernie@codewiz.org>
  */
@@ -106,7 +109,6 @@
        struct Process;
 #endif
 
-
 /// User defined callback type
 typedef void (*Hook)(void *);
 
@@ -121,6 +123,12 @@ typedef struct Event
                        struct Process *sig_proc;  /* Process to be signalled */
                        sigbit_t        sig_bit;   /* Signal to send */
                } Sig;
+
+               struct
+               {
+                       struct Process *sig_proc;  /* Process to be signalled */
+                       Signal          sig;       /* Signal structure */
+               } SigGen;
 #endif
                struct
                {
@@ -139,6 +147,7 @@ void event_hook_ignore(Event *event);
 void event_hook_signal(Event *event);
 void event_hook_softint(Event *event);
 void event_hook_generic(Event *event);
+void event_hook_generic_signal(Event *event);
 void event_hook_generic_timeout(Event *event);
 
 /** Initialize the event \a e as a no-op */
@@ -186,24 +195,22 @@ INLINE Event event_createSignal(struct Process *proc, sigbit_t bit)
 
 #endif
 
-/**
- * Prevent the compiler from optimizing access to the variable \a x, enforcing
- * a refetch from memory. This also forbid from reordering successing instances
- * of ACCESS_SAFE().
- *
- * TODO: move this to cfg/compiler.h
- */
-#define ACCESS_SAFE(x) (*(volatile typeof(x) *)&(x))
-
 #if defined(CONFIG_KERN_SIGNALS) && CONFIG_KERN_SIGNALS
 /** Initialize the generic sleepable event \a e */
-#define event_initGeneric(e) \
-       event_initSignal(e, proc_current(), SIG_SYSTEM5)
+#define event_initGeneric(e)                                   \
+       ((e)->action = event_hook_generic_signal,               \
+               (e)->Ev.SigGen.sig_proc = proc_current(),       \
+               (e)->Ev.SigGen.sig.wait = 0, (e)->Ev.SigGen.sig.recv = 0)
 #else
 #define event_initGeneric(e) \
        ((e)->action = event_hook_generic, (e)->Ev.Gen.completed = false)
 #endif
 
+/**
+ * Signal used to implement generic events.
+ */
+#define EVENT_GENERIC_SIGNAL   SIG_SYSTEM5
+
 /**
  * Create a generic sleepable event.
  *
@@ -218,12 +225,16 @@ INLINE Event event_createGeneric(void)
 
 /**
  * Wait the completion of event \a e.
+ *
+ * This function releases the CPU the application is configured to use
+ * the kernel, otherwise it's just a busy wait.
+ * \note It's forbidden to use this function inside irq handling functions.
  */
 INLINE void event_wait(Event *e)
 {
 #if defined(CONFIG_KERN_SIGNALS) && CONFIG_KERN_SIGNALS
        e->Ev.Sig.sig_proc = proc_current();
-       sig_wait(e->Ev.Sig.sig_bit);
+       sig_waitSignal(&e->Ev.SigGen.sig, EVENT_GENERIC_SIGNAL);
 #else
        while (ACCESS_SAFE(e->Ev.Gen.completed) == false)
                cpu_relax();
@@ -235,39 +246,47 @@ INLINE void event_wait(Event *e)
 #if CONFIG_TIMER_EVENTS
 #include <drv/timer.h> /* timer_clock() */
 
-/* TODO: move these macros to drv/timer.h */
-#define TIMER_AFTER(x, y) ((long)(y) - (long)(x) < 0)
-#define TIMER_BEFORE(x, y) TIMER_AFTER(y, x)
-
 /**
  * Wait the completion of event \a e or \a timeout elapses.
+ *
+ * \note It's forbidden to use this function inside irq handling functions.
  */
 INLINE bool event_waitTimeout(Event *e, ticks_t timeout)
 {
+       bool ret;
+
 #if defined(CONFIG_KERN_SIGNALS) && CONFIG_KERN_SIGNALS
        e->Ev.Sig.sig_proc = proc_current();
-       return (sig_waitTimeout(e->Ev.Sig.sig_bit, timeout) & SIG_TIMEOUT) ?
+       ret = (sig_waitTimeoutSignal(&e->Ev.SigGen.sig,
+                               EVENT_GENERIC_SIGNAL, timeout) & SIG_TIMEOUT) ?
                                false : true;
 #else
        ticks_t end = timer_clock() + timeout;
-       bool ret;
 
        while ((ACCESS_SAFE(e->Ev.Gen.completed) == false) ||
                        TIMER_AFTER(timer_clock(), end))
                cpu_relax();
        ret = e->Ev.Gen.completed;
        e->Ev.Gen.completed = false;
+#endif
        MEMORY_BARRIER;
-
        return ret;
-#endif
 }
 #endif /* CONFIG_TIMER_EVENTS */
 
-/** Trigger an event */
+/**
+ * Trigger an event.
+ *
+ * Execute the callback function associated with event \a e.
+ *
+ * This function can be used also in interrupt routines, but only if the
+ * event was created as a signal or generic event.
+ */
 INLINE void event_do(struct Event *e)
 {
        e->action(e);
 }
 
+/** \} */
+
 #endif /* KERN_EVENT_H */