TNeoKernel  v1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_sem.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  * A semaphore: an object to provide signaling mechanism.
41  *
42  * There is a lot of confusion about differences between semaphores and
43  * mutexes, so, it's quite recommended to read small article by Michael Barr:
44  * [Mutexes and Semaphores Demystified](http://goo.gl/YprPBW).
45  *
46  * Very short:
47  *
48  * While mutex is seemingly similar to a semaphore with maximum count of `1`
49  * (the so-called binary semaphore), their usage is very different: the purpose
50  * of mutex is to protect shared resource. A locked mutex is "owned" by the
51  * task that locked it, and only the same task may unlock it. This ownership
52  * allows to implement algorithms to prevent priority inversion. So, mutex is
53  * a *locking mechanism*.
54  *
55  * Semaphore, on the other hand, is *signaling mechanism*. It's quite legal and
56  * encouraged for semaphore to be acquired in the task A, and then signaled
57  * from task B or even from ISR. It may be used in situations like "producer
58  * and consumer", etc.
59  *
60  * In addition to the article mentioned above, you may want to look at the
61  * [related question on stackoverflow.com](http://goo.gl/ZBReHK).
62  *
63  */
64 
65 #ifndef _TN_SEM_H
66 #define _TN_SEM_H
67 
68 /*******************************************************************************
69  * INCLUDED FILES
70  ******************************************************************************/
71 
72 #include "tn_list.h"
73 #include "tn_common.h"
74 
75 
76 
77 #ifdef __cplusplus
78 extern "C" { /*}*/
79 #endif
80 
81 /*******************************************************************************
82  * PUBLIC TYPES
83  ******************************************************************************/
84 
85 /**
86  * Semaphore
87  */
88 struct TN_Sem {
89  ///
90  /// List of tasks that wait to acquire a semaphore
91  struct TN_ListItem wait_queue;
92  ///
93  /// Current semaphore counter value
94  int count;
95  ///
96  /// Max value of `count`
97  int max_count;
98  ///
99  /// id for object validity verification
100  enum TN_ObjId id_sem;
101 };
102 
103 
104 /*******************************************************************************
105  * GLOBAL VARIABLES
106  ******************************************************************************/
107 
108 /*******************************************************************************
109  * DEFINITIONS
110  ******************************************************************************/
111 
112 /*******************************************************************************
113  * PUBLIC FUNCTION PROTOTYPES
114  ******************************************************************************/
115 
116 /**
117  * Construct the semaphore. `id_sem` field should not contain
118  * `#TN_ID_SEMAPHORE`, otherwise, `#TN_RC_WPARAM` is returned.
119  *
120  * $(TN_CALL_FROM_TASK)
121  * $(TN_CALL_FROM_ISR)
122  * $(TN_LEGEND_LINK)
123  *
124  * @param sem
125  * Pointer to already allocated `struct TN_Sem`
126  * @param start_count
127  * Initial counter value, typically it is equal to `max_count`
128  * @param max_count
129  * Maximum counter value.
130  *
131  * @return
132  * * `#TN_RC_OK` if semaphore was successfully created;
133  * * If `#TN_CHECK_PARAM` is non-zero, additional return code
134  * is available: `#TN_RC_WPARAM`.
135  */
136 enum TN_RCode tn_sem_create(
137  struct TN_Sem *sem,
138  int start_count,
139  int max_count
140  );
141 
142 /**
143  * Destruct the semaphore.
144  *
145  * All tasks that wait for acquire the semaphore become runnable with
146  * `#TN_RC_DELETED` code returned.
147  *
148  * $(TN_CALL_FROM_TASK)
149  * $(TN_CAN_SWITCH_CONTEXT)
150  * $(TN_LEGEND_LINK)
151  *
152  * @param sem semaphore to destruct
153  *
154  * @return
155  * * `#TN_RC_OK` if semaphore was successfully deleted;
156  * * `#TN_RC_WCONTEXT` if called from wrong context;
157  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
158  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
159  */
160 enum TN_RCode tn_sem_delete(struct TN_Sem *sem);
161 
162 /**
163  * Signal the semaphore.
164  *
165  * If current semaphore counter (`count`) is less than `max_count`,
166  * counter is incremented by one; otherwise, `#TN_RC_OVERFLOW` is returned.
167  *
168  * If wait queue is not empty, the first task from the queue acquires the
169  * semaphore.
170  *
171  * $(TN_CALL_FROM_TASK)
172  * $(TN_CAN_SWITCH_CONTEXT)
173  * $(TN_LEGEND_LINK)
174  *
175  * @param sem semaphore to signal
176  *
177  * @return
178  * * `#TN_RC_OK` if successful
179  * * `#TN_RC_WCONTEXT` if called from wrong context;
180  * * `#TN_RC_OVERFLOW` if `count` is already at maximum value (`max_count`)
181  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
182  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
183  */
184 enum TN_RCode tn_sem_signal(struct TN_Sem *sem);
185 
186 /**
187  * The same as `tn_sem_signal()` but for using in the ISR.
188  *
189  * $(TN_CALL_FROM_ISR)
190  * $(TN_CAN_SWITCH_CONTEXT)
191  * $(TN_LEGEND_LINK)
192  *
193  */
194 enum TN_RCode tn_sem_isignal(struct TN_Sem *sem);
195 
196 /**
197  * Acquire the semaphore.
198  *
199  * If the current semaphore counter (`count`) is non-zero, it is decremented
200  * and `#TN_RC_OK` is returned. Otherwise, behavior depends on `timeout` value:
201  * refer to `#TN_Timeout`.
202  *
203  * $(TN_CALL_FROM_TASK)
204  * $(TN_CAN_SWITCH_CONTEXT)
205  * $(TN_CAN_SLEEP)
206  * $(TN_LEGEND_LINK)
207  *
208  * @param sem semaphore to acquire
209  * @param timeout refer to `#TN_Timeout`
210  *
211  * @return
212  * * `#TN_RC_OK` if semaphore was successfully acquired
213  * * Other possible return codes depend on `timeout` value,
214  * refer to `#TN_Timeout`
215  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
216  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
217  */
218 enum TN_RCode tn_sem_acquire(struct TN_Sem *sem, TN_Timeout timeout);
219 
220 /**
221  * The same as `tn_sem_acquire()` with zero timeout.
222  *
223  * $(TN_CALL_FROM_TASK)
224  * $(TN_CAN_SWITCH_CONTEXT)
225  * $(TN_LEGEND_LINK)
226  */
227 enum TN_RCode tn_sem_acquire_polling(struct TN_Sem *sem);
228 
229 /**
230  * The same as `tn_sem_acquire()` with zero timeout, but for using in the ISR.
231  *
232  * $(TN_CALL_FROM_ISR)
233  * $(TN_CAN_SWITCH_CONTEXT)
234  * $(TN_LEGEND_LINK)
235  */
236 enum TN_RCode tn_sem_iacquire_polling(struct TN_Sem *sem);
237 
238 
239 #ifdef __cplusplus
240 } /* extern "C" */
241 #endif
242 
243 #endif // _TN_SEM_H
244 
245 /*******************************************************************************
246  * end of file
247  ******************************************************************************/
248 
249 
TN_Sem
Semaphore.
Definition: tn_sem.h:88
TN_RCode
TN_RCode
Result code returned by kernel services.
Definition: tn_common.h:99
TN_ObjId
TN_ObjId
Magic number for object validity verification.
Definition: tn_common.h:87
TN_Timeout
unsigned long TN_Timeout
The value representing maximum number of system ticks to wait.
Definition: tn_common.h:203
tn_sem_signal
enum TN_RCode tn_sem_signal(struct TN_Sem *sem)
Signal the semaphore.
tn_sem_acquire_polling
enum TN_RCode tn_sem_acquire_polling(struct TN_Sem *sem)
The same as tn_sem_acquire() with zero timeout.
tn_common.h
Definitions used through the whole kernel.
tn_sem_acquire
enum TN_RCode tn_sem_acquire(struct TN_Sem *sem, TN_Timeout timeout)
Acquire the semaphore.
TN_Sem::wait_queue
struct TN_ListItem wait_queue
List of tasks that wait to acquire a semaphore.
Definition: tn_sem.h:91
TN_Sem::id_sem
enum TN_ObjId id_sem
id for object validity verification
Definition: tn_sem.h:100
tn_sem_iacquire_polling
enum TN_RCode tn_sem_iacquire_polling(struct TN_Sem *sem)
The same as tn_sem_acquire() with zero timeout, but for using in the ISR.
tn_sem_delete
enum TN_RCode tn_sem_delete(struct TN_Sem *sem)
Destruct the semaphore.
tn_sem_isignal
enum TN_RCode tn_sem_isignal(struct TN_Sem *sem)
The same as tn_sem_signal() but for using in the ISR.
tn_sem_create
enum TN_RCode tn_sem_create(struct TN_Sem *sem, int start_count, int max_count)
Construct the semaphore.
TN_Sem::count
int count
Current semaphore counter value.
Definition: tn_sem.h:94
TN_Sem::max_count
int max_count
Max value of count
Definition: tn_sem.h:97
Generated on Thu Oct 2 2014 03:07:03 for TNeoKernel by   doxygen 1.8.8