X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=kern%2Fsignal.c;h=513efc28795f43ed1af1719dcba080b6e5f8d98c;hb=58298d38ce938cac4cae47b3647cc7787b04e392;hp=62cfd74c1a9425d3c861a7bd290174817f0f8576;hpb=a8ed288597f0fac2f01347a80ed781964d09b663;p=bertos.git

diff --git a/kern/signal.c b/kern/signal.c
index 62cfd74c..513efc28 100755
--- a/kern/signal.c
+++ b/kern/signal.c
@@ -2,15 +2,62 @@
  * \file
  * <!--
  * Copyright 2004 Develer S.r.l. (http://www.develer.com/)
- * Copyright 1999,2000,2001 Bernardo Innocenti <bernie@develer.com>
+ * Copyright 1999, 2000, 2001 Bernardo Innocenti <bernie@develer.com>
  * This file is part of DevLib - See devlib/README for information.
  * -->
  *
  * \brief IPC signals implementation.
  *
- * Each process can wait for just one signal.
- * Multiple processes can wait for the same signal. In this
- * case, each signal will wake-up one of them.
+ * Signals are a low-level IPC primitive.  A process receives a signal
+ * when some external event has happened.  Like interrupt requests,
+ * signals do not carry any additional information.  If processing a
+ * specific event requires additional data, the process must obtain it
+ * through some other mechanism.
+ *
+ * Despite the name, one shouldn't confuse these signals with POSIX
+ * signals.  POSIX signals are usually executed synchronously, like
+ * software interrupts.
+ *
+ * In this implementation, each process has a limited set of signal
+ * bits (usually 32) and can wait for multiple signals at the same
+ * time using sig_wait().  Signals can also be polled using sig_check(),
+ * but a process spinning on its signals usually defeats their purpose
+ * of providing a multitasking-friendly infrastructure for event-driven
+ * applications.
+ *
+ * Signals are like flags: they are either active or inactive.  After an
+ * external event has delivered a particular signal, it remains raised until
+ * the process acknowledges it using either sig_wait() or sig_check().
+ * Counting signals is not a reliable way to count how many times a
+ * particular event has occurred, because the same signal may be
+ * delivered twice before the process can notice.
+ *
+ * Any execution context, including an interrupt handler, can deliver
+ * a signal to a process using sig_signal().  Multiple distinct signals
+ * may be delivered at once with a single invocation of sig_signal(),
+ * although this is rarely useful.
+ *
+ * There's no hardcoded mapping of specific events to signal bits.
+ * The meaning of a particular signal bit is defined by an agreement
+ * between the delivering entity and the receiving process.
+ * For instance, a terminal driver may be written to deliver
+ * a signal bit called SIG_INT when it reads the CTRL-C sequence
+ * from the keyboard, and a process may react to it by quitting.
+ *
+ * The SIG_SINGLE bit is reserved for a special purpose (this is
+ * more a suggestion than a constraint).  When a process wants
+ * wait for a single event on the fly, it needs not allocate a
+ * free signal from its pool.  Instead, SIG_SINGLE can be used
+ *
+ * The "event" module is a higher-level interface that can optionally
+ * deliver signals to processes.  Messages provide even higher-level
+ * IPC services built on signals.  Semaphore arbitration is also
+ * implemented using signals.
+ *
+ * Signals are very low overhead.  Using them exclusively to wait
+ * for multiple asynchronous events results in very simple dispatch
+ * logic with low processor and resource usage.
+ *
  *
  * \version $Id$
  *
@@ -19,6 +66,12 @@
 
 /*
  * $Log$
+ * Revision 1.6  2004/08/14 19:37:57  rasky
+ * Merge da SC: macros.h, pool.h, BIT_CHANGE, nome dei processi, etc.
+ *
+ * Revision 1.5  2004/08/04 21:50:33  bernie
+ * Add extensive documentation.
+ *
  * Revision 1.4  2004/07/30 14:30:27  rasky
  * Resa la sig_signal interrupt safe (con il nuovo scheduler IRQ-safe)
  * Rimossa event_doIntr (ora inutile) e semplificata la logica delle macro con funzioni inline
@@ -39,6 +92,7 @@
 #include "proc.h"
 #include "proc_p.h"
 #include "hw.h"
+#include <drv/kdebug.h>
 
 // FIXME
 #if CONFIG_KERN_SIGNALS
@@ -77,6 +131,10 @@ sigset_t sig_wait(sigset_t sigs)
 		/* go to sleep and proc_schedule() another process */
 		CurrentProcess->sig_wait = sigs;
 		proc_schedule();
+
+		/* When we come back here, a signal must be arrived */
+		ASSERT(!CurrentProcess->sig_wait);
+		ASSERT(CurrentProcess->sig_recv);
 	}
 
 	/* Signals found: clear them and return */