First version
[3rdparty/ote_partner/tlk.git] / kernel / event.c
1 /*
2  * Copyright (c) 2008-2009 Travis Geiselbrecht
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files
6  * (the "Software"), to deal in the Software without restriction,
7  * including without limitation the rights to use, copy, modify, merge,
8  * publish, distribute, sublicense, and/or sell copies of the Software,
9  * and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be
13  * included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22  */
23
24 /**
25  * @file
26  * @brief  Event wait and signal functions for threads.
27  * @defgroup event Events
28  *
29  * An event is a subclass of a wait queue.
30  *
31  * Threads wait for events, with optional timeouts.
32  *
33  * Events are "signaled", releasing waiting threads to continue.
34  * Signals may be one-shot signals (EVENT_FLAG_AUTOUNSIGNAL), in which
35  * case one signal releases only one thread, at which point it is
36  * automatically cleared. Otherwise, signals release all waiting threads
37  * to continue immediately until the signal is manually cleared with
38  * event_unsignal().
39  *
40  * @{
41  */
42
43 #include <debug.h>
44 #include <assert.h>
45 #include <err.h>
46 #include <kernel/event.h>
47
48 #if DEBUGLEVEL > 1
49 #define EVENT_CHECK 1
50 #endif
51
52 /**
53  * @brief  Initialize an event object
54  *
55  * @param e        Event object to initialize
56  * @param initial  Initial value for "signaled" state
57  * @param flags    0 or EVENT_FLAG_AUTOUNSIGNAL
58  */
59 void event_init(event_t *e, bool initial, uint flags)
60 {
61 #if EVENT_CHECK
62 //      ASSERT(e->magic != EVENT_MAGIC);
63 #endif
64
65         e->magic = EVENT_MAGIC;
66         e->signalled = initial;
67         e->flags = flags;
68         wait_queue_init(&e->wait);
69 }
70
71 /**
72  * @brief  Destroy an event object.
73  *
74  * Event's resources are freed and it may no longer be
75  * used until event_init() is called again.  Any threads
76  * still waiting on the event will be resumed.
77  *
78  * @param e        Event object to initialize
79  */
80 void event_destroy(event_t *e)
81 {
82         enter_critical_section();
83
84 #if EVENT_CHECK
85         ASSERT(e->magic == EVENT_MAGIC);
86 #endif
87
88         e->magic = 0;
89         e->signalled = false;
90         e->flags = 0;
91         wait_queue_destroy(&e->wait, true);
92
93         exit_critical_section();
94 }
95
96 /**
97  * @brief  Wait for event to be signaled
98  *
99  * If the event has already been signaled, this function
100  * returns immediately.  Otherwise, the current thread
101  * goes to sleep until the event object is signaled,
102  * the timeout is reached, or the event object is destroyed
103  * by another thread.
104  *
105  * @param e        Event object
106  * @param timeout  Timeout value, in ms
107  *
108  * @return  0 on success, ERR_TIMED_OUT on timeout,
109  *         other values on other errors.
110  */
111 status_t event_wait_timeout(event_t *e, lk_time_t timeout)
112 {
113         status_t ret = NO_ERROR;
114
115         enter_critical_section();
116
117 #if EVENT_CHECK
118         ASSERT(e->magic == EVENT_MAGIC);
119 #endif
120
121         if (e->signalled) {
122                 /* signalled, we're going to fall through */
123                 if (e->flags & EVENT_FLAG_AUTOUNSIGNAL) {
124                         /* autounsignal flag lets one thread fall through before unsignalling */
125                         e->signalled = false;
126                 }
127         } else {
128                 /* unsignalled, block here */
129                 ret = wait_queue_block(&e->wait, timeout);
130                 if (ret < 0)
131                         goto err;
132         }
133
134 err:
135         exit_critical_section();
136
137         return ret;
138 }
139
140 /**
141  * @brief  Same as event_wait_timeout(), but without a timeout.
142  */
143 status_t event_wait(event_t *e)
144 {
145         return event_wait_timeout(e, INFINITE_TIME);
146 }
147
148 /**
149  * @brief  Signal an event
150  *
151  * Signals an event.  If EVENT_FLAG_AUTOUNSIGNAL is set in the event
152  * object's flags, only one waiting thread is allowed to proceed.  Otherwise,
153  * all waiting threads are allowed to proceed until such time as
154  * event_unsignal() is called.
155  *
156  * @param e               Event object
157  * @param reschedule  If true, waiting thread(s) are executed immediately,
158  *                    and the current thread resumes only after the
159  *                    waiting threads have been satisfied. If false,
160  *                    waiting threads are placed at the end of the run
161  *                    queue.
162  *
163  * @return  Returns NO_ERROR on success.
164  */
165 status_t event_signal(event_t *e, bool reschedule)
166 {
167         enter_critical_section();
168
169 #if EVENT_CHECK
170         ASSERT(e->magic == EVENT_MAGIC);
171 #endif
172
173         if (!e->signalled) {
174                 if (e->flags & EVENT_FLAG_AUTOUNSIGNAL) {
175                         /* try to release one thread and leave unsignalled if successful */
176                         if (wait_queue_wake_one(&e->wait, reschedule, NO_ERROR) <= 0) {
177                                 /*
178                                  * if we didn't actually find a thread to wake up, go to
179                                  * signalled state and let the next call to event_wait
180                                  * unsignal the event.
181                                  */
182                                 e->signalled = true;
183                         }
184                 } else {
185                         /* release all threads and remain signalled */
186                         e->signalled = true;
187                         wait_queue_wake_all(&e->wait, reschedule, NO_ERROR);
188                 }
189         }
190
191         exit_critical_section();
192
193         return NO_ERROR;
194 }
195
196 /**
197  * @brief  Clear the "signaled" property of an event
198  *
199  * Used mainly for event objects without the EVENT_FLAG_AUTOUNSIGNAL
200  * flag.  Once this function is called, threads that call event_wait()
201  * functions will once again need to wait until the event object
202  * is signaled.
203  *
204  * @param e  Event object
205  *
206  * @return  Returns NO_ERROR on success.
207  */
208 status_t event_unsignal(event_t *e)
209 {
210         enter_critical_section();
211
212 #if EVENT_CHECK
213         ASSERT(e->magic == EVENT_MAGIC);
214 #endif
215
216         e->signalled = false;
217
218         exit_critical_section();
219
220         return NO_ERROR;
221 }
222