Add demo application.
[bertos.git] / kern / signal.c
1 /*!
2  * \file
3  * <!--
4  * Copyright 2004 Develer S.r.l. (http://www.develer.com/)
5  * Copyright 1999, 2000, 2001 Bernardo Innocenti <bernie@develer.com>
6  * This file is part of DevLib - See README.devlib for information.
7  * -->
8  *
9  * \brief IPC signals implementation.
10  *
11  * Signals are a low-level IPC primitive.  A process receives a signal
12  * when some external event has happened.  Like interrupt requests,
13  * signals do not carry any additional information.  If processing a
14  * specific event requires additional data, the process must obtain it
15  * through some other mechanism.
16  *
17  * Despite the name, one shouldn't confuse these signals with POSIX
18  * signals.  POSIX signals are usually executed synchronously, like
19  * software interrupts.
20  *
21  * In this implementation, each process has a limited set of signal
22  * bits (usually 32) and can wait for multiple signals at the same
23  * time using sig_wait().  Signals can also be polled using sig_check(),
24  * but a process spinning on its signals usually defeats their purpose
25  * of providing a multitasking-friendly infrastructure for event-driven
26  * applications.
27  *
28  * Signals are like flags: they are either active or inactive.  After an
29  * external event has delivered a particular signal, it remains raised until
30  * the process acknowledges it using either sig_wait() or sig_check().
31  * Counting signals is not a reliable way to count how many times a
32  * particular event has occurred, because the same signal may be
33  * delivered twice before the process can notice.
34  *
35  * Any execution context, including an interrupt handler, can deliver
36  * a signal to a process using sig_signal().  Multiple distinct signals
37  * may be delivered at once with a single invocation of sig_signal(),
38  * although this is rarely useful.
39  *
40  * There's no hardcoded mapping of specific events to signal bits.
41  * The meaning of a particular signal bit is defined by an agreement
42  * between the delivering entity and the receiving process.
43  * For instance, a terminal driver may be written to deliver
44  * a signal bit called SIG_INT when it reads the CTRL-C sequence
45  * from the keyboard, and a process may react to it by quitting.
46  *
47  * The SIG_SINGLE bit is reserved for a special purpose (this is
48  * more a suggestion than a constraint).  When a process wants
49  * wait for a single event on the fly, it needs not allocate a
50  * free signal from its pool.  Instead, SIG_SINGLE can be used
51  *
52  * The "event" module is a higher-level interface that can optionally
53  * deliver signals to processes.  Messages provide even higher-level
54  * IPC services built on signals.  Semaphore arbitration is also
55  * implemented using signals.
56  *
57  * Signals are very low overhead.  Using them exclusively to wait
58  * for multiple asynchronous events results in very simple dispatch
59  * logic with low processor and resource usage.
60  *
61  *
62  * \version $Id$
63  *
64  * \author Bernardo Innocenti <bernie@develer.com>
65  */
66
67 /*#*
68  *#* $Log$
69  *#* Revision 1.13  2006/02/24 01:17:05  bernie
70  *#* Update for new emulator.
71  *#*
72  *#* Revision 1.12  2005/11/04 16:20:02  bernie
73  *#* Fix reference to README.devlib in header.
74  *#*
75  *#* Revision 1.11  2005/04/11 19:10:28  bernie
76  *#* Include top-level headers from cfg/ subdir.
77  *#*
78  *#* Revision 1.10  2004/12/13 12:07:06  bernie
79  *#* DISABLE_IRQSAVE/ENABLE_IRQRESTORE: Convert to IRQ_SAVE_DISABLE/IRQ_RESTORE.
80  *#*
81  *#* Revision 1.9  2004/12/08 08:57:35  bernie
82  *#* Rename sigset_t to sigmask_t.
83  *#*
84  *#* Revision 1.8  2004/09/14 21:06:44  bernie
85  *#* Use debug.h instead of kdebug.h.
86  *#*
87  *#* Revision 1.7  2004/08/25 14:12:09  rasky
88  *#* Aggiornato il comment block dei log RCS
89  *#*
90  *#* Revision 1.6  2004/08/14 19:37:57  rasky
91  *#* Merge da SC: macros.h, pool.h, BIT_CHANGE, nome dei processi, etc.
92  *#*
93  *#* Revision 1.5  2004/08/04 21:50:33  bernie
94  *#* Add extensive documentation.
95  *#*
96  *#* Revision 1.4  2004/07/30 14:30:27  rasky
97  *#* Resa la sig_signal interrupt safe (con il nuovo scheduler IRQ-safe)
98  *#* Rimossa event_doIntr (ora inutile) e semplificata la logica delle macro con funzioni inline
99  *#*
100  *#* Revision 1.3  2004/07/30 14:24:16  rasky
101  *#* Task switching con salvataggio perfetto stato di interrupt (SR)
102  *#* Kernel monitor per dump informazioni su stack dei processi
103  *#*
104  *#* Revision 1.2  2004/06/03 11:27:09  bernie
105  *#* Add dual-license information.
106  *#*
107  *#* Revision 1.1  2004/05/23 17:27:00  bernie
108  *#* Import kern/ subdirectory.
109  *#*
110  *#*/
111
112 #include "signal.h"
113
114 #include <kern/proc.h>
115 #include <kern/proc_p.h>
116 #include <cfg/debug.h>
117
118 #if CONFIG_KERN_SIGNALS
119
120 /*!
121  * Check if any of the signals in \a sigs has occurred and clear them.
122  * Return the signals that have occurred.
123  */
124 sigmask_t sig_check(sigmask_t sigs)
125 {
126         sigmask_t result;
127         cpuflags_t flags;
128
129         IRQ_SAVE_DISABLE(flags);
130         result = CurrentProcess->sig_recv & sigs;
131         CurrentProcess->sig_recv &= ~sigs;
132         IRQ_RESTORE(flags);
133
134         return result;
135 }
136
137
138 /*!
139  * Sleep until any of the signals in \a sigs occurs.
140  * Return the signal(s) that have awaked the process.
141  */
142 sigmask_t sig_wait(sigmask_t sigs)
143 {
144         sigmask_t result;
145         cpuflags_t flags;
146
147         IRQ_SAVE_DISABLE(flags);
148
149         /* Loop until we get at least one of the signals */
150         while (!(result = CurrentProcess->sig_recv & sigs))
151         {
152                 /* go to sleep and proc_schedule() another process */
153                 CurrentProcess->sig_wait = sigs;
154                 proc_schedule();
155
156                 /* When we come back here, a signal must be arrived */
157                 ASSERT(!CurrentProcess->sig_wait);
158                 ASSERT(CurrentProcess->sig_recv);
159         }
160
161         /* Signals found: clear them and return */
162         CurrentProcess->sig_recv &= ~sigs;
163
164         IRQ_RESTORE(flags);
165         return result;
166 }
167
168
169 /*!
170  * Send the signals \a sigs to the process \a proc.
171  * The process will be awaken if it was waiting for any of them.
172  *
173  * \note This call is interrupt safe.
174  */
175 void sig_signal(Process *proc, sigmask_t sigs)
176 {
177         cpuflags_t flags;
178         IRQ_SAVE_DISABLE(flags);
179
180         /* Set the signals */
181         proc->sig_recv |= sigs;
182
183         /* Check if process needs to be awaken */
184         if (proc->sig_recv & proc->sig_wait)
185         {
186                 /* Wake up process and enqueue in ready list */
187                 proc->sig_wait = 0;
188                 SCHED_ENQUEUE(proc);
189         }
190
191         IRQ_RESTORE(flags);
192 }
193
194 #endif /* CONFIG_KERN_SIGNALS */
195