TNeoKernel  v1.02
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_sys.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  * Kernel system routines: system start, tick processing, time slice managing.
41  *
42  */
43 
44 #ifndef _TN_SYS_H
45 #define _TN_SYS_H
46 
47 
48 
49 /*******************************************************************************
50  * INCLUDED FILES
51  ******************************************************************************/
52 
53 #include "tn_list.h"
54 #include "../arch/tn_arch.h"
55 
56 
57 
58 
59 #ifdef __cplusplus
60 extern "C" { /*}*/
61 #endif
62 
63 /*******************************************************************************
64  * EXTERNAL TYPES
65  ******************************************************************************/
66 
67 struct TN_Task;
68 struct TN_Mutex;
69 
70 
71 
72 /*******************************************************************************
73  * DEFINITIONS
74  ******************************************************************************/
75 
76 
77 /*******************************************************************************
78  * PUBLIC TYPES
79  ******************************************************************************/
80 
81 /**
82  * System state flags
83  */
85  ///
86  /// system is running
88  ///
89  /// deadlock is active
90  /// Note: this feature works if only `#TN_MUTEX_DEADLOCK_DETECT` is non-zero.
91  /// @see `#TN_MUTEX_DEADLOCK_DETECT`
93 };
94 
95 /**
96  * System context
97  *
98  * @see `tn_sys_context_get()`
99  */
101  ///
102  /// None: this code is possible if only system is not running
103  /// (flag (`#TN_STATE_FLAG__SYS_RUNNING` is not set in the `tn_sys_state`))
105  ///
106  /// Task context
108  ///
109  /// ISR context
111 };
112 
113 /**
114  * User-provided callback function that is called directly from
115  * `tn_sys_start()` as a part of system startup routine; it should merely
116  * create at least one (and typically just one) user's task, which should
117  * perform all the rest application initialization.
118  *
119  * When `TN_CBUserTaskCreate()` returned, the kernel performs first context
120  * switch to the task with highest priority. If there are several tasks with
121  * highest priority, context is switched to the first created one.
122  *
123  * Refer to the section \ref starting_the_kernel for details about system
124  * startup process on the whole.
125  *
126  * **Note:** Although you're able to create more than one task here, it's
127  * usually not so good idea, because many things typically should be done at
128  * startup before tasks can go on with their job: we need to initialize various
129  * on-board peripherals (displays, flash memory chips, or whatever) as well as
130  * initialize software modules used by application. So, if many tasks are
131  * created here, you have to provide some synchronization object so that tasks
132  * will wait until all the initialization is done.
133  *
134  * It's usually easier to maintain if we create just one task here, which
135  * firstly performs all the necessary initialization, **then** creates the rest
136  * of your tasks, and eventually gets to its primary job (the job for which
137  * task was created at all). For the usage example, refer to the page \ref
138  * starting_the_kernel.
139  *
140  * \attention
141  * * The only system service is allowed to call in this function is
142  * `tn_task_create()`.
143  *
144  * @see `tn_sys_start()`
145  */
146 typedef void (TN_CBUserTaskCreate)(void);
147 
148 /**
149  * User-provided callback function that is called repeatedly from the idle task
150  * loop. Make sure that idle task has enough stack space to call this function.
151  *
152  * \attention
153  * * It is illegal to sleep here, because idle task (from which this
154  * function is called) should always be runnable, by design. If `#TN_DEBUG`
155  * option is set, then sleeping in idle task is checked, so if you try to
156  * sleep here, `_TN_FATAL_ERROR()` macro will be called.
157  *
158  *
159  * @see `tn_sys_start()`
160  */
161 typedef void (TN_CBIdle)(void);
162 
163 /**
164  * User-provided callback function that is called whenever
165  * deadlock becomes active or inactive.
166  * Note: this feature works if only `#TN_MUTEX_DEADLOCK_DETECT` is non-zero.
167  *
168  * @param active if `TRUE`, deadlock becomes active, otherwise it becomes
169  * inactive (say, if task stopped waiting for mutex
170  * because of timeout)
171  * @param mutex mutex that is involved in deadlock. You may find out other
172  * mutexes involved by means of `mutex->deadlock_list`.
173  * @param task task that is involved in deadlock. You may find out other
174  * tasks involved by means of `task->deadlock_list`.
175  */
176 typedef void (TN_CBDeadlock)(
177  BOOL active,
178  struct TN_Mutex *mutex,
179  struct TN_Task *task
180  );
181 
182 
183 
184 
185 /*******************************************************************************
186  * DEFINITIONS
187  ******************************************************************************/
188 
189 /**
190  * Value to pass to `tn_sys_tslice_set()` to turn round-robin off.
191  */
192 #define TN_NO_TIME_SLICE 0
193 
194 /**
195  * Max value of time slice
196  */
197 #define TN_MAX_TIME_SLICE 0xFFFE
198 
199 
200 
201 
202 /*******************************************************************************
203  * PUBLIC FUNCTION PROTOTYPES
204  ******************************************************************************/
205 
206 /**
207  * Initial TNeoKernel system start function, never returns. Typically called
208  * from main().
209  *
210  * Refer to the \ref starting_the_kernel "Starting the kernel" section for the
211  * usage example and additional comments.
212  *
213  * $(TN_CALL_FROM_MAIN)
214  * $(TN_LEGEND_LINK)
215  *
216  * @param idle_task_stack
217  * Pointer to array for idle task stack.
218  * User must either use the macro `TN_TASK_STACK_DEF()` for the definition
219  * of stack array, or allocate it manually as an array of `#TN_UWord` with
220  * `#TN_ARCH_STK_ATTR_BEFORE` and `#TN_ARCH_STK_ATTR_AFTER` macros.
221  * @param idle_task_stack_size
222  * Size of idle task stack, in words (`#TN_UWord`)
223  * @param int_stack
224  * Pointer to array for interrupt stack.
225  * User must either use the macro `TN_TASK_STACK_DEF()` for the definition
226  * of stack array, or allocate it manually as an array of `#TN_UWord` with
227  * `#TN_ARCH_STK_ATTR_BEFORE` and `#TN_ARCH_STK_ATTR_AFTER` macros.
228  * @param int_stack_size
229  * Size of interrupt stack, in words (`#TN_UWord`)
230  * @param cb_user_task_create
231  * Callback function that should create initial user's task, see
232  * `#TN_CBUserTaskCreate` for details.
233  * @param cb_idle
234  * Callback function repeatedly called from idle task, see `#TN_CBIdle` for
235  * details.
236  */
237 void tn_sys_start(
238  TN_UWord *idle_task_stack,
239  unsigned int idle_task_stack_size,
240  TN_UWord *int_stack,
241  unsigned int int_stack_size,
242  TN_CBUserTaskCreate *cb_user_task_create,
243  TN_CBIdle *cb_idle
244  );
245 
246 /**
247  * Process system tick; should be called periodically, typically
248  * from some kind of timer ISR.
249  *
250  * The period of this timer is determined by user
251  * (typically 1 ms, but user is free to set different value)
252  *
253  * Among other things, expired \ref tn_timer.h "timers" are fired from this
254  * function.
255  *
256  * For further information, refer to \ref quick_guide "Quick guide".
257  *
258  * $(TN_CALL_FROM_ISR)
259  * $(TN_CAN_SWITCH_CONTEXT)
260  * $(TN_LEGEND_LINK)
261  *
262  * @return
263  * * `#TN_RC_OK` on success;
264  * * `#TN_RC_WCONTEXT` if called from wrong context.
265  */
267 
268 /**
269  * Set time slice ticks value for specified priority (see \ref round_robin).
270  *
271  * $(TN_CALL_FROM_TASK)
272  * $(TN_LEGEND_LINK)
273  *
274  * @param priority
275  * Priority of tasks for which time slice value should be set
276  * @param ticks
277  * Time slice value, in ticks. Set to `#TN_NO_TIME_SLICE` for no round-robin
278  * scheduling for given priority (it's default value). Value can't be
279  * higher than `#TN_MAX_TIME_SLICE`.
280  *
281  * @return
282  * * `#TN_RC_OK` on success;
283  * * `#TN_RC_WCONTEXT` if called from wrong context;
284  * * `#TN_RC_WPARAM` if given `priority` or `ticks` are invalid.
285  */
286 enum TN_RCode tn_sys_tslice_set(int priority, int ticks);
287 
288 /**
289  * Get current system ticks count.
290  *
291  * $(TN_CALL_FROM_TASK)
292  * $(TN_CALL_FROM_ISR)
293  * $(TN_LEGEND_LINK)
294  *
295  * @return
296  * Current system ticks count.
297  */
298 unsigned int tn_sys_time_get(void);
299 
300 
301 /**
302  * Set callback function that should be called whenever deadlock occurs or
303  * becomes inactive (say, if one of tasks involved in the deadlock was released
304  * from wait because of timeout)
305  *
306  * $(TN_CALL_FROM_MAIN)
307  * $(TN_LEGEND_LINK)
308  *
309  * **Note:** this function should be called before `tn_sys_start()`
310  *
311  * @param cb
312  * Pointer to user-provided callback function.
313  *
314  * @see `#TN_MUTEX_DEADLOCK_DETECT`
315  * @see `#TN_CBDeadlock` for callback function prototype
316  */
318 
319 /**
320  * Returns current system state flags
321  *
322  * $(TN_CALL_FROM_TASK)
323  * $(TN_CALL_FROM_ISR)
324  * $(TN_LEGEND_LINK)
325  */
327 
328 /**
329  * Returns system context: task or ISR.
330  *
331  * $(TN_CALL_FROM_TASK)
332  * $(TN_CALL_FROM_ISR)
333  * $(TN_CALL_FROM_MAIN)
334  * $(TN_LEGEND_LINK)
335  *
336  * @see `enum #TN_Context`
337  */
338 enum TN_Context tn_sys_context_get(void);
339 
340 /**
341  * Returns whether current system context is `#TN_CONTEXT_TASK`
342  *
343  * $(TN_CALL_FROM_TASK)
344  * $(TN_CALL_FROM_ISR)
345  * $(TN_CALL_FROM_MAIN)
346  * $(TN_LEGEND_LINK)
347  *
348  * @return `TRUE` if current system context is `#TN_CONTEXT_TASK`,
349  * `FALSE` otherwise.
350  *
351  * @see `tn_sys_context_get()`
352  * @see `enum #TN_Context`
353  */
354 static inline BOOL tn_is_task_context(void)
355 {
356  return (tn_sys_context_get() == TN_CONTEXT_TASK);
357 }
358 
359 /**
360  * Returns whether current system context is `#TN_CONTEXT_ISR`
361  *
362  * $(TN_CALL_FROM_TASK)
363  * $(TN_CALL_FROM_ISR)
364  * $(TN_CALL_FROM_MAIN)
365  * $(TN_LEGEND_LINK)
366  *
367  * @return `TRUE` if current system context is `#TN_CONTEXT_ISR`,
368  * `FALSE` otherwise.
369  *
370  * @see `tn_sys_context_get()`
371  * @see `enum #TN_Context`
372  */
373 static inline BOOL tn_is_isr_context(void)
374 {
375  return (tn_sys_context_get() == TN_CONTEXT_ISR);
376 }
377 
378 /**
379  * Returns pointer to the currently running task.
380  *
381  * $(TN_CALL_FROM_TASK)
382  * $(TN_CALL_FROM_ISR)
383  * $(TN_LEGEND_LINK)
384  */
385 struct TN_Task *tn_cur_task_get(void);
386 
387 /**
388  * Returns pointer to the body function of the currently running task.
389  *
390  * $(TN_CALL_FROM_TASK)
391  * $(TN_CALL_FROM_ISR)
392  * $(TN_LEGEND_LINK)
393  */
395 
396 #ifdef __cplusplus
397 } /* extern "C" */
398 #endif
399 
400 #endif // _TN_SYS_H
401 
Mutex.
Definition: tn_mutex.h:122
TN_Context
System context.
Definition: tn_sys.h:100
#define BOOL
boolean type definition
Definition: tn_common.h:222
deadlock is active Note: this feature works if only TN_MUTEX_DEADLOCK_DETECT is non-zero.
Definition: tn_sys.h:92
Task.
Definition: tn_tasks.h:173
TN_RCode
Result code returned by kernel services.
Definition: tn_common.h:100
None: this code is possible if only system is not running (flag (TN_STATE_FLAG__SYS_RUNNING is not se...
Definition: tn_sys.h:104
TN_TaskBody * tn_cur_task_body_get(void)
Returns pointer to the body function of the currently running task.
system is running
Definition: tn_sys.h:87
void tn_callback_deadlock_set(TN_CBDeadlock *cb)
Set callback function that should be called whenever deadlock occurs or becomes inactive (say...
void tn_sys_start(TN_UWord *idle_task_stack, unsigned int idle_task_stack_size, TN_UWord *int_stack, unsigned int int_stack_size, TN_CBUserTaskCreate *cb_user_task_create, TN_CBIdle *cb_idle)
Initial TNeoKernel system start function, never returns.
void( TN_CBDeadlock)(BOOL active, struct TN_Mutex *mutex, struct TN_Task *task)
User-provided callback function that is called whenever deadlock becomes active or inactive...
Definition: tn_sys.h:176
static BOOL tn_is_task_context(void)
Returns whether current system context is TN_CONTEXT_TASK
Definition: tn_sys.h:354
enum TN_StateFlag tn_sys_state_flags_get(void)
Returns current system state flags.
void( TN_CBUserTaskCreate)(void)
User-provided callback function that is called directly from tn_sys_start() as a part of system start...
Definition: tn_sys.h:146
enum TN_Context tn_sys_context_get(void)
Returns system context: task or ISR.
int priority
current task priority
Definition: tn_tasks.h:228
enum TN_RCode tn_tick_int_processing(void)
Process system tick; should be called periodically, typically from some kind of timer ISR...
struct TN_Task * tn_cur_task_get(void)
Returns pointer to the currently running task.
Task context.
Definition: tn_sys.h:107
static BOOL tn_is_isr_context(void)
Returns whether current system context is TN_CONTEXT_ISR
Definition: tn_sys.h:373
void( TN_CBIdle)(void)
User-provided callback function that is called repeatedly from the idle task loop.
Definition: tn_sys.h:161
enum TN_RCode tn_sys_tslice_set(int priority, int ticks)
Set time slice ticks value for specified priority (see Round-robin scheduling).
void( TN_TaskBody)(void *param)
Prototype for task body function.
Definition: tn_common.h:164
unsigned int tn_sys_time_get(void)
Get current system ticks count.
unsigned int TN_UWord
Unsigned integer type whose size is equal to the size of CPU register.
TN_StateFlag
System state flags.
Definition: tn_sys.h:84
ISR context.
Definition: tn_sys.h:110