Add demo application.
[bertos.git] / kern / sem.c
1 /*!
2  * \file
3  * <!--
4  * Copyright 2001, 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 Semaphore based synchronization services.
10  *
11  * \version $Id$
12  *
13  * \author Bernardo Innocenti <bernie@develer.com>
14  */
15
16 /*#*
17  *#* $Log$
18  *#* Revision 1.11  2006/02/24 01:17:05  bernie
19  *#* Update for new emulator.
20  *#*
21  *#* Revision 1.10  2005/11/04 16:20:02  bernie
22  *#* Fix reference to README.devlib in header.
23  *#*
24  *#* Revision 1.9  2005/04/11 19:10:28  bernie
25  *#* Include top-level headers from cfg/ subdir.
26  *#*
27  *#* Revision 1.8  2005/01/22 04:20:42  bernie
28  *#* Add integrity checks.
29  *#*
30  *#* Revision 1.7  2004/11/28 23:20:25  bernie
31  *#* Remove obsolete INITLIST macro.
32  *#*
33  *#* Revision 1.6  2004/10/21 10:57:21  bernie
34  *#* Use proc_forbid()/proc_permit().
35  *#*
36  *#* Revision 1.5  2004/10/21 10:48:57  bernie
37  *#* sem_release(): Simplify (made by rasky on scfirm).
38  *#*
39  *#* Revision 1.4  2004/08/25 14:12:09  rasky
40  *#* Aggiornato il comment block dei log RCS
41  *#*
42  *#* Revision 1.3  2004/08/08 05:53:23  bernie
43  *#* Use DISABLE_IRQSAVE/ENABLE_IRQRESTORE; Cleanup documentation.
44  *#*
45  *#* Revision 1.2  2004/06/03 11:27:09  bernie
46  *#* Add dual-license information.
47  *#*
48  *#* Revision 1.1  2004/05/23 17:27:00  bernie
49  *#* Import kern/ subdirectory.
50  *#*/
51
52 #include "sem.h"
53 #include <kern/proc.h>
54 #include <kern/proc_p.h>
55 #include <kern/signal.h>
56 #include <cfg/debug.h>
57
58 INLINE void sem_verify(struct Semaphore *s)
59 {
60         LIST_ASSERT_VALID(&s->wait_queue);
61         ASSERT(s->nest_count >= 0);
62         ASSERT(s->nest_count < 128);   // heuristic max
63 }
64
65
66 /*!
67  * \brief Initialize a Semaphore structure.
68  */
69 void sem_init(struct Semaphore *s)
70 {
71         LIST_INIT(&s->wait_queue);
72         s->owner = NULL;
73         s->nest_count = 0;
74 }
75
76
77 /*!
78  * \brief Attempt to lock a semaphore without waiting.
79  *
80  * \return true in case of success, false if the semaphore
81  *         was already locked by someone else.
82  *
83  * \note   each call to sem_attempt() must be matched by a
84  *         call to sem_release().
85  *
86  * \see sem_obtain() sem_release()
87  */
88 bool sem_attempt(struct Semaphore *s)
89 {
90         bool result = false;
91
92         proc_forbid();
93         sem_verify(s);
94         if ((!s->owner) || (s->owner == CurrentProcess))
95         {
96                 s->owner = CurrentProcess;
97                 s->nest_count++;
98                 result = true;
99         }
100         proc_permit();
101
102         return result;
103 }
104
105
106 /*!
107  * \brief Lock a semaphore.
108  *
109  * If the semaphore is already owned by another process, the caller
110  * process will be enqueued into the waiting list and sleep until
111  * the semaphore is available.
112  *
113  * \note Each call to sem_obtain() must be matched by a
114  *       call to sem_release().
115  *
116  * \note This routine is optimized for highest speed in
117  *       the most common case: the semaphore is free or locked
118  *       by the calling process itself. Rearranging this code
119  *       is probably a bad idea.
120  *
121  * \sa sem_release() sem_attempt()
122  */
123 void sem_obtain(struct Semaphore *s)
124 {
125         proc_forbid();
126         sem_verify(s);
127
128         /* Is the semaphore already locked by another process? */
129         if (UNLIKELY(s->owner && (s->owner != CurrentProcess)))
130         {
131                 /* Append calling process to the wait queue */
132                 ADDTAIL(&s->wait_queue, (Node *)CurrentProcess);
133
134                 /*
135                  * We will wake up only when the current owner calls
136                  * sem_release(). Then, the semaphore will already
137                  * be locked for us.
138                  */
139                 proc_permit();
140                 proc_schedule();
141         }
142         else
143         {
144                 ASSERT(LIST_EMPTY(&s->wait_queue));
145
146                 /* The semaphore was free: lock it */
147                 s->owner = CurrentProcess;
148                 s->nest_count++;
149                 proc_permit();
150         }
151 }
152
153
154 /*!
155  * \brief Release a lock on a previously locked semaphore.
156  *
157  * If the nesting count of the semaphore reaches zero,
158  * the next process waiting for it will be awaken.
159  *
160  * \note This routine is optimized for highest speed in
161  *       the most common case: the semaphore has been locked just
162  *       once and nobody else was waiting for it. Rearranging
163  *       this code is probably a bad idea.
164  *
165  * \sa sem_obtain() sem_attempt()
166  */
167 void sem_release(struct Semaphore *s)
168 {
169         proc_forbid();
170         sem_verify(s);
171
172         ASSERT(s->owner == CurrentProcess);
173
174         /*
175          * Decrement nesting count and check if the semaphore
176          * has been fully unlocked.
177          */
178         if (--s->nest_count == 0)
179         {
180                 Process *proc;
181
182                 /* Disown semaphore */
183                 s->owner = NULL;
184
185                 /* Give semaphore to the first applicant, if any */
186                 if (UNLIKELY((proc = (Process *)list_remHead(&s->wait_queue))))
187                 {
188                         s->nest_count = 1;
189                         s->owner = proc;
190                         SCHED_ENQUEUE(proc);
191                 }
192         }
193
194         proc_permit();
195 }