TNeoKernel  v1.01
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_eventgrp.h
Go to the documentation of this file.
1 /*******************************************************************************
2  *
3  * TNeoKernel: real-time kernel initially based on TNKernel
4  *
5  * TNKernel: copyright © 2004, 2013 Yuri Tiomkin.
6  * PIC32-specific routines: copyright © 2013, 2014 Anders Montonen.
7  * TNeoKernel: copyright © 2014 Dmitry Frank.
8  *
9  * TNeoKernel was born as a thorough review and re-implementation of
10  * TNKernel. The new kernel has well-formed code, inherited bugs are fixed
11  * as well as new features being added, and it is tested carefully with
12  * unit-tests.
13  *
14  * API is changed somewhat, so it's not 100% compatible with TNKernel,
15  * hence the new name: TNeoKernel.
16  *
17  * Permission to use, copy, modify, and distribute this software in source
18  * and binary forms and its documentation for any purpose and without fee
19  * is hereby granted, provided that the above copyright notice appear
20  * in all copies and that both that copyright notice and this permission
21  * notice appear in supporting documentation.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE DMITRY FRANK AND CONTRIBUTORS "AS IS"
24  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DMITRY FRANK OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
33  * THE POSSIBILITY OF SUCH DAMAGE.
34  *
35  ******************************************************************************/
36 
37 /**
38  * \file
39  *
40  * Event group.
41  *
42  * An event group has an internal variable (of type `unsigned int`), which is
43  * interpreted as a bit pattern where each bit represents an event. An event
44  * group also has a wait queue for the tasks waiting on these events. A task
45  * may set specified bits when an event occurs and may clear specified bits
46  * when necessary.
47  *
48  * The tasks waiting for an event(s) are placed in the event group's wait
49  * queue. An event group is a very suitable synchronization object for cases
50  * where (for some reasons) one task has to wait for many tasks, or vice versa,
51  * many tasks have to wait for one task.
52  */
53 
54 #ifndef _TN_EVENTGRP_H
55 #define _TN_EVENTGRP_H
56 
57 /*******************************************************************************
58  * INCLUDED FILES
59  ******************************************************************************/
60 
61 #include "tn_list.h"
62 #include "tn_common.h"
63 
64 
65 
66 #ifdef __cplusplus
67 extern "C" { /*}*/
68 #endif
69 
70 /*******************************************************************************
71  * PUBLIC TYPES
72  ******************************************************************************/
73 
74 /**
75  * Events waiting mode: wait for all flags to be set or just for any of the
76  * specified flags to be set.
77  */
79  ///
80  /// Task waits for **any** of the event bits from the `wait_pattern`
81  /// to be set in the event group
83  ///
84  /// Task waits for **all** of the event bits from the `wait_pattern`
85  /// to be set in the event group
87 };
88 
89 /**
90  * Modify operation: set, clear or toggle. To be used in `tn_eventgrp_modify()`
91  * / `tn_eventgrp_imodify()` functions.
92  */
93 enum TN_EGrpOp {
94  ///
95  /// Set flags that are set in given `pattern` argument. Note that this
96  /// operation can lead to the context switch, since other high-priority
97  /// task(s) might wait for the event.
99  ///
100  /// Clear flags that are set in the given `pattern` argument.
101  /// This operation can **not** lead to the context switch,
102  /// since tasks can't wait for events to be cleared.
104  /// Toggle flags that are set in the given `pattern` argument. Note that this
105  /// operation can lead to the context switch, since other high-priority
106  /// task(s) might wait for the event that was just set (if any).
108 };
109 
110 /**
111  * Event group
112  */
113 struct TN_EventGrp {
114  struct TN_ListItem wait_queue; //!< task wait queue
115  unsigned int pattern; //!< current flags pattern
116  enum TN_ObjId id_event; //!< id for object validity verification
117 };
118 
119 /**
120  * EventGrp-specific fields related to waiting task,
121  * to be included in struct TN_Task.
122  */
124  ///
125  /// event wait pattern
127  ///
128  /// event wait mode: `AND` or `OR`
130  ///
131  /// pattern that caused task to finish waiting
133 };
134 
135 
136 
137 /*******************************************************************************
138  * GLOBAL VARIABLES
139  ******************************************************************************/
140 
141 /*******************************************************************************
142  * DEFINITIONS
143  ******************************************************************************/
144 
145 
146 
147 /*******************************************************************************
148  * PUBLIC FUNCTION PROTOTYPES
149  ******************************************************************************/
150 
151 /**
152  * Construct event group. `id_event` field should not contain `#TN_ID_EVENTGRP`,
153  * otherwise, `#TN_RC_WPARAM` is returned.
154  *
155  * $(TN_CALL_FROM_TASK)
156  * $(TN_CALL_FROM_ISR)
157  * $(TN_LEGEND_LINK)
158  *
159  * @param eventgrp
160  * Pointer to already allocated struct TN_EventGrp
161  * @param initial_pattern
162  * Initial events pattern.
163  *
164  * @return
165  * * `#TN_RC_OK` if event group was successfully created;
166  * * If `#TN_CHECK_PARAM` is non-zero, additional return code
167  * is available: `#TN_RC_WPARAM`.
168  */
170  struct TN_EventGrp *eventgrp,
171  unsigned int initial_pattern
172  );
173 
174 /**
175  * Destruct event group.
176  *
177  * All tasks that wait for the event(s) become runnable with `#TN_RC_DELETED`
178  * code returned.
179  *
180  * $(TN_CALL_FROM_TASK)
181  * $(TN_CAN_SWITCH_CONTEXT)
182  * $(TN_LEGEND_LINK)
183  *
184  * @param eventgrp Pointer to event groupt to be deleted.
185  *
186  * @return
187  * * `#TN_RC_OK` if event group was successfully deleted;
188  * * `#TN_RC_WCONTEXT` if called from wrong context;
189  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
190  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
191  */
192 enum TN_RCode tn_eventgrp_delete(struct TN_EventGrp *eventgrp);
193 
194 /**
195  * Wait for specified event(s) in the event group. If the specified event
196  * is already active, function returns `#TN_RC_OK` immediately. Otherwise,
197  * behavior depends on `timeout` value: refer to `#TN_Timeout`.
198  *
199  * $(TN_CALL_FROM_TASK)
200  * $(TN_CAN_SWITCH_CONTEXT)
201  * $(TN_CAN_SLEEP)
202  * $(TN_LEGEND_LINK)
203  *
204  * @param eventgrp
205  * Pointer to event group to wait events from
206  * @param wait_pattern
207  * Events bit pattern for which task should wait
208  * @param wait_mode
209  * Specifies whether task should wait for **all** the event bits from
210  * `wait_pattern` to be set, or for just **any** of them
211  * (see enum `#TN_EGrpWaitMode`)
212  * @param p_flags_pattern
213  * Pointer to the `unsigned int` variable in which actual event pattern
214  * that caused task to stop waiting will be stored.
215  * May be `NULL`.
216  * @param timeout
217  * refer to `#TN_Timeout`
218  *
219  * @return
220  * * `#TN_RC_OK` if specified event is active (so the task can check
221  * variable pointed to by `p_flags_pattern` if it wasn't `NULL`).
222  * * `#TN_RC_WCONTEXT` if called from wrong context;
223  * * Other possible return codes depend on `timeout` value,
224  * refer to `#TN_Timeout`
225  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
226  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
227  */
229  struct TN_EventGrp *eventgrp,
230  unsigned int wait_pattern,
231  enum TN_EGrpWaitMode wait_mode,
232  unsigned int *p_flags_pattern,
233  TN_Timeout timeout
234  );
235 
236 /**
237  * The same as `tn_eventgrp_wait()` with zero timeout.
238  *
239  * $(TN_CALL_FROM_TASK)
240  * $(TN_CAN_SWITCH_CONTEXT)
241  * $(TN_LEGEND_LINK)
242  */
244  struct TN_EventGrp *eventgrp,
245  unsigned int wait_pattern,
246  enum TN_EGrpWaitMode wait_mode,
247  unsigned int *p_flags_pattern
248  );
249 
250 /**
251  * The same as `tn_eventgrp_wait()` with zero timeout, but for using in the ISR.
252  *
253  * $(TN_CALL_FROM_ISR)
254  * $(TN_CAN_SWITCH_CONTEXT)
255  * $(TN_LEGEND_LINK)
256  */
258  struct TN_EventGrp *eventgrp,
259  unsigned int wait_pattern,
260  enum TN_EGrpWaitMode wait_mode,
261  unsigned int *p_flags_pattern
262  );
263 
264 /**
265  * Modify current events bit pattern in the event group. Behavior depends
266  * on the given `operation`: refer to `enum #TN_EGrpOp`
267  *
268  * $(TN_CALL_FROM_TASK)
269  * $(TN_CAN_SWITCH_CONTEXT)
270  * $(TN_LEGEND_LINK)
271  *
272  * @param eventgrp
273  * Pointer to event group to modify events in
274  * @param operation
275  * Actual operation to perform: set, clear or toggle.
276  * Refer to `enum #TN_EGrpOp`
277  * @param pattern
278  * Events pattern to be applied (depending on `operation` value)
279  *
280  * @return
281  * * `#TN_RC_OK` on success;
282  * * `#TN_RC_WCONTEXT` if called from wrong context;
283  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
284  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
285  */
287  struct TN_EventGrp *eventgrp,
288  enum TN_EGrpOp operation,
289  unsigned int pattern
290  );
291 
292 /**
293  * The same as `tn_eventgrp_modify()`, but for using in the ISR.
294  *
295  * $(TN_CALL_FROM_ISR)
296  * $(TN_CAN_SWITCH_CONTEXT)
297  * $(TN_LEGEND_LINK)
298  */
300  struct TN_EventGrp *eventgrp,
301  enum TN_EGrpOp operation,
302  unsigned int pattern
303  );
304 
305 
306 #ifdef __cplusplus
307 } /* extern "C" */
308 #endif
309 
310 #endif // _TN_EVENTGRP_H
311 
312 /*******************************************************************************
313  * end of file
314  ******************************************************************************/
315 
316 
Task waits for all of the event bits from the wait_pattern to be set in the event group...
Definition: tn_eventgrp.h:86
enum TN_EGrpWaitMode wait_mode
event wait mode: AND or OR
Definition: tn_eventgrp.h:129
enum TN_RCode tn_eventgrp_imodify(struct TN_EventGrp *eventgrp, enum TN_EGrpOp operation, unsigned int pattern)
The same as tn_eventgrp_modify(), but for using in the ISR.
unsigned int pattern
current flags pattern
Definition: tn_eventgrp.h:115
TN_EGrpOp
Modify operation: set, clear or toggle.
Definition: tn_eventgrp.h:93
Clear flags that are set in the given pattern argument.
Definition: tn_eventgrp.h:103
TN_RCode
Result code returned by kernel services.
Definition: tn_common.h:99
TN_ObjId
Magic number for object validity verification.
Definition: tn_common.h:87
enum TN_RCode tn_eventgrp_modify(struct TN_EventGrp *eventgrp, enum TN_EGrpOp operation, unsigned int pattern)
Modify current events bit pattern in the event group.
unsigned long TN_Timeout
The value representing maximum number of system ticks to wait.
Definition: tn_common.h:203
EventGrp-specific fields related to waiting task, to be included in struct TN_Task.
Definition: tn_eventgrp.h:123
enum TN_RCode tn_eventgrp_create(struct TN_EventGrp *eventgrp, unsigned int initial_pattern)
Construct event group.
TN_EGrpWaitMode
Events waiting mode: wait for all flags to be set or just for any of the specified flags to be set...
Definition: tn_eventgrp.h:78
Definitions used through the whole kernel.
int actual_pattern
pattern that caused task to finish waiting
Definition: tn_eventgrp.h:132
Toggle flags that are set in the given pattern argument.
Definition: tn_eventgrp.h:107
enum TN_RCode tn_eventgrp_wait(struct TN_EventGrp *eventgrp, unsigned int wait_pattern, enum TN_EGrpWaitMode wait_mode, unsigned int *p_flags_pattern, TN_Timeout timeout)
Wait for specified event(s) in the event group.
Task waits for any of the event bits from the wait_pattern to be set in the event group...
Definition: tn_eventgrp.h:82
enum TN_ObjId id_event
id for object validity verification
Definition: tn_eventgrp.h:116
enum TN_RCode tn_eventgrp_iwait_polling(struct TN_EventGrp *eventgrp, unsigned int wait_pattern, enum TN_EGrpWaitMode wait_mode, unsigned int *p_flags_pattern)
The same as tn_eventgrp_wait() with zero timeout, but for using in the ISR.
enum TN_RCode tn_eventgrp_delete(struct TN_EventGrp *eventgrp)
Destruct event group.
Event group.
Definition: tn_eventgrp.h:113
enum TN_RCode tn_eventgrp_wait_polling(struct TN_EventGrp *eventgrp, unsigned int wait_pattern, enum TN_EGrpWaitMode wait_mode, unsigned int *p_flags_pattern)
The same as tn_eventgrp_wait() with zero timeout.
int wait_pattern
event wait pattern
Definition: tn_eventgrp.h:126
Set flags that are set in given pattern argument.
Definition: tn_eventgrp.h:98
struct TN_ListItem wait_queue
task wait queue
Definition: tn_eventgrp.h:114