TNeoKernel  v1.02
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_tasks.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  * Various task services: create, sleep, wake up, terminate, etc.
41  *
42  */
43 
44 #ifndef _TN_TASKS_H
45 #define _TN_TASKS_H
46 
47 /*******************************************************************************
48  * INCLUDED FILES
49  ******************************************************************************/
50 
51 #include "tn_sys.h"
52 #include "tn_list.h"
53 #include "tn_common.h"
54 
55 #include "tn_eventgrp.h"
56 #include "tn_dqueue.h"
57 #include "tn_fmem.h"
58 #include "tn_timer.h"
59 
60 
61 
62 #ifdef __cplusplus
63 extern "C" { /*}*/
64 #endif
65 
66 /*******************************************************************************
67  * PUBLIC TYPES
68  ******************************************************************************/
69 
70 /**
71  * Task state
72  */
74  /// This state should never be publicly available.
75  /// It may be stored in task_state only temporarily,
76  /// while some system service is in progress.
78  ///
79  /// Task is ready to run (it doesn't mean that it is running at the moment)
81  ///
82  /// Task is waiting. The reason of waiting can be obtained from
83  /// `task_wait_reason` field of the `struct TN_Task`.
84  ///
85  /// @see `enum #TN_WaitReason`
86  TN_TASK_STATE_WAIT = (1 << 1),
87  ///
88  /// Task is suspended (by some other task)
90  ///
91  /// Task was previously waiting, and after this it was suspended
93  ///
94  /// Task isn't yet activated or it was terminated by `tn_task_terminate()`.
96 };
97 
98 
99 /**
100  * Task wait reason
101  */
103  ///
104  /// task isn't waiting for anything
106  ///
107  /// task has called `tn_task_sleep()`
109  ///
110  /// task waits to acquire a semaphore
111  /// @see tn_sem.h
113  ///
114  /// task waits for some event in the event group to be set
115  /// @see tn_eventgrp.h
117  ///
118  /// task wants to put some data to the data queue, and there's no space
119  /// in the queue.
120  /// @see tn_dqueue.h
122  ///
123  /// task wants to receive some data to the data queue, and there's no data
124  /// in the queue
125  /// @see tn_dqueue.h
127  ///
128  /// task wants to lock a mutex with priority ceiling
129  /// @see tn_mutex.h
131  ///
132  /// task wants to lock a mutex with priority inheritance
133  /// @see tn_mutex.h
135  ///
136  /// task wants to get memory block from memory pool, and there's no free
137  /// memory blocks
138  /// @see tn_fmem.h
140 };
141 
142 /**
143  * Options for `tn_task_create()`
144  */
146  ///
147  /// whether task should be activated right after it is created.
148  /// If this flag is not set, user must activate task manually by calling
149  /// `tn_task_activate()`.
151  ///
152  /// for internal kernel usage only: this option must be provided
153  /// when creating idle task
155 };
156 
157 /**
158  * Options for `tn_task_exit()`
159  */
161  ///
162  /// whether task should be deleted right after it is exited.
163  /// If this flag is not set, user must either delete it manually by
164  /// calling `tn_task_delete()` or re-activate it by calling
165  /// `tn_task_activate()`.
167 };
168 
169 
170 /**
171  * Task
172  */
173 struct TN_Task {
174  /// pointer to task's current stack pointer;
175  /// Note that this field **must** be a first field in the struct,
176  /// this fact is exploited by platform-specific routines.
177  unsigned int *task_stk;
178  ///
179  /// queue is used to include task in ready/wait lists
180  struct TN_ListItem task_queue;
181  //
182  // queue is used to include task in timer list
183  //struct TN_ListItem timer_queue;
184  ///
185  /// timer object to implement task waiting for timeout
186  struct TN_Timer timer;
187  ///
188  /// pointer to object's (semaphore, mutex, event, etc) wait list in which
189  /// task is included for waiting
190  struct TN_ListItem *pwait_queue;
191  ///
192  /// queue is used to include task in creation list
193  /// (currently, this list is used for statistics only)
194  struct TN_ListItem create_queue;
195 
196 #if TN_USE_MUTEXES
197  ///
198  /// list of all mutexes that are locked by task
199  struct TN_ListItem mutex_queue;
200 #if TN_MUTEX_DEADLOCK_DETECT
201  ///
202  /// list of other tasks involved in deadlock. This list is non-empty
203  /// only in emergency cases, and it is here to help you fix your bug
204  /// that led to deadlock.
205  ///
206  /// @see `#TN_MUTEX_DEADLOCK_DETECT`
207  struct TN_ListItem deadlock_list;
208 #endif
209 #endif
210 
211  /// base top of the stack for this task
213  ///
214  /// size of task's stack (in `sizeof(TN_UWord)`, not bytes)
216  ///
217  /// pointer to task's body function given to `tn_task_create()`
219  ///
220  /// pointer to task's parameter given to `tn_task_create()`
222  ///
223  /// base priority of the task (actual current priority may be higher than
224  /// base priority because of mutex)
226  ///
227  /// current task priority
228  int priority;
229  ///
230  /// id for object validity verification
232  ///
233  /// task state
235  ///
236  /// reason for waiting (relevant if only `task_state` is
237  /// $(TN_TASK_STATE_WAIT) or $(TN_TASK_STATE_WAITSUSP))
239  ///
240  /// waiting result code (reason why waiting finished)
242  //
243  // remaining time until timeout; may be `#TN_WAIT_INFINITE`.
244  //TN_Timeout tick_count;
245  ///
246  /// time slice counter
248 #if 0
249  ///
250  /// last operation result code, might be used if some service
251  /// does not return that code directly
252  int last_rc;
253 #endif
254  ///
255  /// subsystem-specific fields that are used while task waits for something.
256  /// Do note that these fields are grouped by union, so, they must not
257  /// interfere with each other. It's quite ok here because task can't wait
258  /// for different things.
259  union {
260  /// fields specific to tn_eventgrp.h
262  ///
263  /// fields specific to tn_dqueue.h
265  ///
266  /// fields specific to tn_fmem.h
268  } subsys_wait;
269 
270 #if TN_DEBUG
271  /// task name for debug purposes, user may want to set it by hand
272  const char *name;
273 #endif
274 
275  /// Internal flag used to optimize mutex priority algorithms.
276  /// For the comments on it, see file tn_mutex.c,
277  /// function `_mutex_do_unlock()`.
279 
280  /// Flag indicates that task waited for something
281  /// This flag is set automatially in `_tn_task_set_waiting()`
282  /// Must be cleared manually before calling any service that could sleep,
283  /// if the caller is interested in the relevant value of this flag.
284  unsigned waited : 1;
285 
286 
287 // Other implementation specific fields may be added below
288 
289 };
290 
291 
292 
293 /*******************************************************************************
294  * GLOBAL VARIABLES
295  ******************************************************************************/
296 
297 /*******************************************************************************
298  * DEFINITIONS
299  ******************************************************************************/
300 
301 /**
302  * Convenience macro for the definition of stack array. See
303  * `tn_task_create()` for the usage example.
304  *
305  * @param name
306  * C variable name of the array
307  * @param size
308  * size of the stack array in words (`#TN_UWord`), not in bytes.
309  */
310 #define TN_TASK_STACK_DEF(name, size) \
311  TN_ARCH_STK_ATTR_BEFORE \
312  TN_UWord name[ (size) ] \
313  TN_ARCH_STK_ATTR_AFTER
314 
315 
316 
317 /*******************************************************************************
318  * PUBLIC FUNCTION PROTOTYPES
319  ******************************************************************************/
320 
321 /**
322  * Construct task and probably start it (depends on options, see below).
323  * `id_task` member should not contain `#TN_ID_TASK`, otherwise,
324  * `#TN_RC_WPARAM` is returned.
325  *
326  * Usage example:
327  *
328  * \code{.c}
329  * #define MY_TASK_STACK_SIZE (TN_MIN_STACK_SIZE + 200)
330  * #define MY_TASK_PRIORITY 5
331  *
332  * struct TN_Task my_task;
333  *
334  * //-- define stack array, we use convenience macro TN_TASK_STACK_DEF()
335  * // for that
336  * TN_TASK_STACK_DEF(my_task_stack, MY_TASK_STACK_SIZE);
337  *
338  * void my_task_body(void *param)
339  * {
340  * //-- an endless loop
341  * for (;;){
342  * tn_task_sleep(1);
343  *
344  * //-- probably do something useful
345  * }
346  * }
347  * \endcode
348  *
349  *
350  *
351  * And then, somewhere from other task or from the callback
352  * `#TN_CBUserTaskCreate` given to `tn_sys_start()` :
353  * \code{.c}
354  * enum TN_RCode rc = tn_task_create(
355  * &my_task,
356  * my_task_body,
357  * MY_TASK_PRIORITY,
358  * my_task_stack,
359  * MY_TASK_STACK_SIZE,
360  * NULL, //-- parameter isn't used
361  * TN_TASK_CREATE_OPT_START //-- start task on creation
362  * );
363  *
364  * if (rc != TN_RC_OK){
365  * //-- handle error
366  * }
367  * \endcode
368  *
369  * $(TN_CALL_FROM_TASK)
370  * $(TN_LEGEND_LINK)
371  *
372  * @param task
373  * Ready-allocated `struct TN_Task` structure. `id_task` member should not
374  * contain `#TN_ID_TASK`, otherwise `#TN_RC_WPARAM` is returned.
375  * @param task_func
376  * Pointer to task body function.
377  * @param priority
378  * Priority for new task. **NOTE**: the lower value, the higher priority.
379  * Must be > `0` and < `(#TN_PRIORITIES_CNT - 1)`.
380  * @param task_stack_low_addr
381  * Pointer to the stack for task.
382  * User must either use the macro `TN_TASK_STACK_DEF()` for the definition
383  * of stack array, or allocate it manually as an array of `#TN_UWord` with
384  * `#TN_ARCH_STK_ATTR_BEFORE` and `#TN_ARCH_STK_ATTR_AFTER` macros.
385  * @param task_stack_size
386  * Size of task stack array, in words (`#TN_UWord`), not in bytes.
387  * @param param
388  * Parameter that is passed to `task_func`.
389  * @param opts
390  * Options for task creation, refer to `enum #TN_TaskCreateOpt`
391  *
392  * @return
393  * * `#TN_RC_OK` on success;
394  * * `#TN_RC_WCONTEXT` if called from wrong context;
395  * * `#TN_RC_WPARAM` if wrong params were given;
396  *
397  * @see `#TN_ARCH_STK_ATTR_BEFORE`
398  * @see `#TN_ARCH_STK_ATTR_AFTER`
399  */
401  struct TN_Task *task,
402  TN_TaskBody *task_func,
403  int priority,
404  TN_UWord *task_stack_low_addr,
405  int task_stack_size,
406  void *param,
407  enum TN_TaskCreateOpt opts
408  );
409 
410 
411 /**
412  * If the task is $(TN_TASK_STATE_RUNNABLE), it is moved to the
413  * $(TN_TASK_STATE_SUSPEND) state. If the task is in the $(TN_TASK_STATE_WAIT)
414  * state, it is moved to the $(TN_TASK_STATE_WAITSUSP) state. (waiting +
415  * suspended)
416  *
417  * $(TN_CALL_FROM_TASK)
418  * $(TN_CAN_SWITCH_CONTEXT)
419  * $(TN_LEGEND_LINK)
420  *
421  * @param task Task to suspend
422  *
423  * @return
424  * * `#TN_RC_OK` on success;
425  * * `#TN_RC_WCONTEXT` if called from wrong context;
426  * * `#TN_RC_WSTATE` if task is already suspended or dormant;
427  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
428  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
429  *
430  * @see `enum #TN_TaskState`
431  */
432 enum TN_RCode tn_task_suspend(struct TN_Task *task);
433 
434 /**
435  * Release task from $(TN_TASK_STATE_SUSPEND) state. If the given task is in
436  * the $(TN_TASK_STATE_SUSPEND) state, it is moved to $(TN_TASK_STATE_RUNNABLE)
437  * state; afterwards it has the lowest precedence among runnable tasks with the
438  * same priority. If the task is in $(TN_TASK_STATE_WAITSUSP) state, it is
439  * moved to $(TN_TASK_STATE_WAIT) state.
440  *
441  * $(TN_CALL_FROM_TASK)
442  * $(TN_CAN_SWITCH_CONTEXT)
443  * $(TN_LEGEND_LINK)
444  *
445  * @param task Task to release from suspended state
446  *
447  * @return
448  * * `#TN_RC_OK` on success;
449  * * `#TN_RC_WCONTEXT` if called from wrong context;
450  * * `#TN_RC_WSTATE` if task is not suspended;
451  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
452  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
453  *
454  * @see enum TN_TaskState
455  */
456 enum TN_RCode tn_task_resume(struct TN_Task *task);
457 
458 /**
459  * Put current task to sleep for at most timeout ticks. When the timeout
460  * expires and the task was not suspended during the sleep, it is switched to
461  * runnable state. If the timeout value is `#TN_WAIT_INFINITE` and the task was
462  * not suspended during the sleep, the task will sleep until another function
463  * call (like `tn_task_wakeup()` or similar) will make it runnable.
464  *
465  * $(TN_CALL_FROM_TASK)
466  * $(TN_CAN_SWITCH_CONTEXT)
467  * $(TN_CAN_SLEEP)
468  * $(TN_LEGEND_LINK)
469  *
470  * @param timeout
471  * Refer to `#TN_Timeout`
472  *
473  * @returns
474  * * `#TN_RC_TIMEOUT` if task has slept specified timeout;
475  * * `#TN_RC_OK` if task was woken up from other task by `tn_task_wakeup()`
476  * * `#TN_RC_FORCED` if task was released from wait forcibly by
477  * `tn_task_release_wait()`
478  * * `#TN_RC_WCONTEXT` if called from wrong context
479  *
480  * @see TN_Timeout
481  */
482 enum TN_RCode tn_task_sleep(TN_Timeout timeout);
483 
484 /**
485  * Wake up task from sleep.
486  *
487  * Task is woken up if only it sleeps because of call to `tn_task_sleep()`.
488  * If task sleeps for some another reason, task won't be woken up,
489  * and `tn_task_wakeup()` returns `#TN_RC_WSTATE`.
490  *
491  * After this call, `tn_task_sleep()` returns `#TN_RC_OK`.
492  *
493  * $(TN_CALL_FROM_TASK)
494  * $(TN_CAN_SWITCH_CONTEXT)
495  * $(TN_LEGEND_LINK)
496  *
497  * @param task sleeping task to wake up
498  *
499  * @return
500  * * `#TN_RC_OK` if successful
501  * * `#TN_RC_WSTATE` if task is not sleeping, or it is sleeping for
502  * some reason other than `tn_task_sleep()` call.
503  * * `#TN_RC_WCONTEXT` if called from wrong context;
504  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
505  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
506  *
507  */
508 enum TN_RCode tn_task_wakeup(struct TN_Task *task);
509 
510 /**
511  * The same as `tn_task_wakeup()` but for using in the ISR.
512  *
513  * $(TN_CALL_FROM_ISR)
514  * $(TN_CAN_SWITCH_CONTEXT)
515  * $(TN_LEGEND_LINK)
516  */
517 enum TN_RCode tn_task_iwakeup(struct TN_Task *task);
518 
519 /**
520  * Activate task that is in $(TN_TASK_STATE_DORMANT) state, that is, it was
521  * either just created by `tn_task_create()` without
522  * `#TN_TASK_CREATE_OPT_START` option, or terminated.
523  *
524  * Task is moved from $(TN_TASK_STATE_DORMANT) state to the
525  * $(TN_TASK_STATE_RUNNABLE) state.
526  *
527  * $(TN_CALL_FROM_TASK)
528  * $(TN_CAN_SWITCH_CONTEXT)
529  * $(TN_LEGEND_LINK)
530  *
531  * @param task dormant task to activate
532  *
533  * @return
534  * * `#TN_RC_OK` if successful
535  * * `#TN_RC_WSTATE` if task is not dormant
536  * * `#TN_RC_WCONTEXT` if called from wrong context;
537  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
538  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
539  *
540  * @see TN_TaskState
541  */
542 enum TN_RCode tn_task_activate(struct TN_Task *task);
543 
544 /**
545  * The same as `tn_task_activate()` but for using in the ISR.
546  *
547  * $(TN_CALL_FROM_ISR)
548  * $(TN_CAN_SWITCH_CONTEXT)
549  * $(TN_LEGEND_LINK)
550  */
551 enum TN_RCode tn_task_iactivate(struct TN_Task *task);
552 
553 /**
554  * Release task from $(TN_TASK_STATE_WAIT) state, independently of the reason
555  * of waiting.
556  *
557  * If task is in $(TN_TASK_STATE_WAIT) state, it is moved to
558  * $(TN_TASK_STATE_RUNNABLE) state. If task is in $(TN_TASK_STATE_WAITSUSP)
559  * state, it is moved to $(TN_TASK_STATE_SUSPEND) state.
560  *
561  * `#TN_RC_FORCED` is returned to the waiting task.
562  *
563  * $(TN_CALL_FROM_TASK)
564  * $(TN_CAN_SWITCH_CONTEXT)
565  * $(TN_LEGEND_LINK)
566  *
567  * \attention Usage of this function is discouraged, since the need for
568  * it indicates bad software design
569  *
570  * @param task task waiting for anything
571  *
572  * @return
573  * * `#TN_RC_OK` if successful
574  * * `#TN_RC_WSTATE` if task is not waiting for anything
575  * * `#TN_RC_WCONTEXT` if called from wrong context;
576  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
577  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
578  *
579  *
580  * @see TN_TaskState
581  */
582 enum TN_RCode tn_task_release_wait(struct TN_Task *task);
583 
584 /**
585  * The same as `tn_task_release_wait()` but for using in the ISR.
586  *
587  * $(TN_CALL_FROM_ISR)
588  * $(TN_CAN_SWITCH_CONTEXT)
589  * $(TN_LEGEND_LINK)
590  */
591 enum TN_RCode tn_task_irelease_wait(struct TN_Task *task);
592 
593 /**
594  * This function terminates the currently running task. The task is moved to
595  * the $(TN_TASK_STATE_DORMANT) state.
596  *
597  * After exiting, the task may be either deleted by the `tn_task_delete()`
598  * function call or reactivated by the `tn_task_activate()` /
599  * `tn_task_iactivate()` function call. In this case task starts execution from
600  * beginning (as after creation/activation). The task will have the lowest
601  * precedence among all tasks with the same priority in the
602  * $(TN_TASK_STATE_RUNNABLE) state.
603  *
604  * If this function is invoked with `#TN_TASK_EXIT_OPT_DELETE` option set, the
605  * task will be deleted after termination and cannot be reactivated (needs
606  * recreation).
607  *
608  * $(TN_CALL_FROM_TASK)
609  * $(TN_CAN_SWITCH_CONTEXT)
610  * $(TN_LEGEND_LINK)
611  *
612  * @return
613  * Returns if only called from wrong context. Normally, it never returns
614  * (since calling task becomes terminated)
615  *
616  * @see `#TN_TASK_EXIT_OPT_DELETE`
617  * @see `tn_task_delete()`
618  * @see `tn_task_activate()`
619  * @see `tn_task_iactivate()`
620  */
621 void tn_task_exit(enum TN_TaskExitOpt opts);
622 
623 
624 /**
625  * This function is similar to `tn_task_exit()` but it terminates any task
626  * other than currently running one.
627  *
628  * After task is terminated, the task may be either deleted by the
629  * `tn_task_delete()` function call or reactivated by the `tn_task_activate()`
630  * / `tn_task_iactivate()` function call. In this case task starts execution
631  * from beginning (as after creation/activation). The task will have the
632  * lowest precedence among all tasks with the same priority in the
633  * $(TN_TASK_STATE_RUNNABLE) state.
634  *
635  * $(TN_CALL_FROM_TASK)
636  * $(TN_CAN_SWITCH_CONTEXT)
637  * $(TN_LEGEND_LINK)
638  *
639  * @param task task to terminate
640  *
641  * @return
642  * * `#TN_RC_OK` if successful
643  * * `#TN_RC_WSTATE` if task is already dormant
644  * * `#TN_RC_WCONTEXT` if called from wrong context;
645  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
646  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
647  */
648 enum TN_RCode tn_task_terminate(struct TN_Task *task);
649 
650 /**
651  * This function deletes the task specified by the task. The task must be in
652  * the $(TN_TASK_STATE_DORMANT) state, otherwise `#TN_RC_WCONTEXT` will be
653  * returned.
654  *
655  * This function resets the `id_task` field in the task structure to 0 and
656  * removes the task from the system tasks list. The task can not be reactivated
657  * after this function call (the task must be recreated).
658  *
659  * $(TN_CALL_FROM_TASK)
660  * $(TN_LEGEND_LINK)
661  *
662  * @param task dormant task to delete
663  *
664  * @return
665  * * `#TN_RC_OK` if successful
666  * * `#TN_RC_WSTATE` if task is not dormant
667  * * `#TN_RC_WCONTEXT` if called from wrong context;
668  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
669  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
670  *
671  */
672 enum TN_RCode tn_task_delete(struct TN_Task *task);
673 
674 /**
675  * Get current state of the task; note that returned state is a bitmask,
676  * that is, states could be combined with each other.
677  *
678  * Currently, only $(TN_TASK_STATE_WAIT) and $(TN_TASK_STATE_SUSPEND) states
679  * are allowed to be set together. Nevertheless, it would be probably good
680  * idea to test individual bits in the returned value instead of plain
681  * comparing values.
682  *
683  * Note that if something goes wrong, variable pointed to by `p_state`
684  * isn't touched.
685  *
686  * $(TN_CALL_FROM_TASK)
687  * $(TN_LEGEND_LINK)
688  *
689  * @param task
690  * task to get state of
691  * @param p_state
692  * pointer to the location where to store state of the task
693  *
694  * @return state of the task
695  */
697  struct TN_Task *task,
698  enum TN_TaskState *p_state
699  );
700 
701 /**
702  * Set new priority for task.
703  * If priority is 0, then task's base_priority is set.
704  *
705  * $(TN_CALL_FROM_TASK)
706  * $(TN_LEGEND_LINK)
707  *
708  * \attention this function is obsolete and will probably be removed
709  */
710 enum TN_RCode tn_task_change_priority(struct TN_Task *task, int new_priority);
711 
712 
713 
714 #ifdef __cplusplus
715 } /* extern "C" */
716 #endif
717 
718 #endif // _TN_TASKS_H
719 
720 
721 /*******************************************************************************
722  * end of file
723  ******************************************************************************/
724 
725 
enum TN_RCode tn_task_activate(struct TN_Task *task)
Activate task that is in DORMANT state, that is, it was either just created by tn_task_create() witho...
TN_WaitReason
Task wait reason.
Definition: tn_tasks.h:102
task wants to lock a mutex with priority inheritance
Definition: tn_tasks.h:134
enum TN_RCode tn_task_release_wait(struct TN_Task *task)
Release task from WAIT state, independently of the reason of waiting.
enum TN_RCode tn_task_iwakeup(struct TN_Task *task)
The same as tn_task_wakeup() but for using in the ISR.
enum TN_RCode tn_task_terminate(struct TN_Task *task)
This function is similar to tn_task_exit() but it terminates any task other than currently running on...
Task is suspended (by some other task)
Definition: tn_tasks.h:89
enum TN_RCode tn_task_create(struct TN_Task *task, TN_TaskBody *task_func, int priority, TN_UWord *task_stack_low_addr, int task_stack_size, void *param, enum TN_TaskCreateOpt opts)
Construct task and probably start it (depends on options, see below).
Task.
Definition: tn_tasks.h:173
TN_RCode
Result code returned by kernel services.
Definition: tn_common.h:100
DQueue-specific fields related to waiting task, to be included in struct TN_Task. ...
Definition: tn_dqueue.h:115
TN_ObjId
Magic number for object validity verification.
Definition: tn_common.h:87
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_WaitReason task_wait_reason
reason for waiting (relevant if only task_state is WAIT or WAIT+SUSPEND)
Definition: tn_tasks.h:238
Task was previously waiting, and after this it was suspended.
Definition: tn_tasks.h:92
task wants to receive some data to the data queue, and there's no data in the queue ...
Definition: tn_tasks.h:126
Definitions used through the whole kernel.
enum TN_TaskState task_state
task state
Definition: tn_tasks.h:234
enum TN_RCode tn_task_delete(struct TN_Task *task)
This function deletes the task specified by the task.
Task is waiting.
Definition: tn_tasks.h:86
TN_TaskCreateOpt
Options for tn_task_create()
Definition: tn_tasks.h:145
struct TN_EGrpTaskWait eventgrp
fields specific to tn_eventgrp.h
Definition: tn_tasks.h:261
TN_UWord * base_stack_top
base top of the stack for this task
Definition: tn_tasks.h:212
int stack_size
size of task's stack (in sizeof(TN_UWord), not bytes)
Definition: tn_tasks.h:215
TN_TaskBody * task_func_addr
pointer to task's body function given to tn_task_create()
Definition: tn_tasks.h:218
int tslice_count
time slice counter
Definition: tn_tasks.h:247
enum TN_RCode tn_task_change_priority(struct TN_Task *task, int new_priority)
Set new priority for task.
struct TN_ListItem deadlock_list
list of other tasks involved in deadlock.
Definition: tn_tasks.h:207
Timer is a kernel object that is used to ask the kernel to call some user-provided function at a part...
enum TN_RCode tn_task_wakeup(struct TN_Task *task)
Wake up task from sleep.
TN_TaskState
Task state.
Definition: tn_tasks.h:73
This state should never be publicly available.
Definition: tn_tasks.h:77
Timer.
Definition: tn_timer.h:202
Fixed memory blocks pool.
enum TN_RCode tn_task_suspend(struct TN_Task *task)
If the task is RUNNABLE, it is moved to the SUSPEND state.
void tn_task_exit(enum TN_TaskExitOpt opts)
This function terminates the currently running task.
whether task should be deleted right after it is exited.
Definition: tn_tasks.h:166
enum TN_RCode tn_task_irelease_wait(struct TN_Task *task)
The same as tn_task_release_wait() but for using in the ISR.
enum TN_RCode tn_task_resume(struct TN_Task *task)
Release task from SUSPEND state.
int base_priority
base priority of the task (actual current priority may be higher than base priority because of mutex)...
Definition: tn_tasks.h:225
Event group.
Task isn't yet activated or it was terminated by tn_task_terminate().
Definition: tn_tasks.h:95
task has called tn_task_sleep()
Definition: tn_tasks.h:108
enum TN_ObjId id_task
id for object validity verification
Definition: tn_tasks.h:231
Task is ready to run (it doesn't mean that it is running at the moment)
Definition: tn_tasks.h:80
task wants to get memory block from memory pool, and there's no free memory blocks ...
Definition: tn_tasks.h:139
struct TN_DQueueTaskWait dqueue
fields specific to tn_dqueue.h
Definition: tn_tasks.h:264
unsigned waited
Flag indicates that task waited for something This flag is set automatially in _tn_task_set_waiting()...
Definition: tn_tasks.h:284
int priority
current task priority
Definition: tn_tasks.h:228
enum TN_RCode tn_task_iactivate(struct TN_Task *task)
The same as tn_task_activate() but for using in the ISR.
struct TN_ListItem * pwait_queue
pointer to object's (semaphore, mutex, event, etc) wait list in which task is included for waiting ...
Definition: tn_tasks.h:190
struct TN_ListItem task_queue
queue is used to include task in ready/wait lists
Definition: tn_tasks.h:180
for internal kernel usage only: this option must be provided when creating idle task ...
Definition: tn_tasks.h:154
task wants to lock a mutex with priority ceiling
Definition: tn_tasks.h:130
struct TN_FMemTaskWait fmem
fields specific to tn_fmem.h
Definition: tn_tasks.h:267
struct TN_Timer timer
timer object to implement task waiting for timeout
Definition: tn_tasks.h:186
Kernel system routines: system start, tick processing, time slice managing.
union TN_Task::@0 subsys_wait
subsystem-specific fields that are used while task waits for something.
task wants to put some data to the data queue, and there's no space in the queue. ...
Definition: tn_tasks.h:121
enum TN_RCode tn_task_state_get(struct TN_Task *task, enum TN_TaskState *p_state)
Get current state of the task; note that returned state is a bitmask, that is, states could be combin...
void( TN_TaskBody)(void *param)
Prototype for task body function.
Definition: tn_common.h:164
task waits to acquire a semaphore
Definition: tn_tasks.h:112
enum TN_RCode tn_task_sleep(TN_Timeout timeout)
Put current task to sleep for at most timeout ticks.
task isn't waiting for anything
Definition: tn_tasks.h:105
unsigned priority_already_updated
Internal flag used to optimize mutex priority algorithms.
Definition: tn_tasks.h:278
whether task should be activated right after it is created.
Definition: tn_tasks.h:150
void * task_func_param
pointer to task's parameter given to tn_task_create()
Definition: tn_tasks.h:221
FMem-specific fields related to waiting task, to be included in struct TN_Task.
Definition: tn_fmem.h:107
unsigned int TN_UWord
Unsigned integer type whose size is equal to the size of CPU register.
unsigned int * task_stk
pointer to task's current stack pointer; Note that this field must be a first field in the struct...
Definition: tn_tasks.h:177
task waits for some event in the event group to be set
Definition: tn_tasks.h:116
A data queue is a FIFO that stores pointer (of type void *) in each cell, called (in uITRON style) a ...
struct TN_ListItem create_queue
queue is used to include task in creation list (currently, this list is used for statistics only) ...
Definition: tn_tasks.h:194
TN_TaskExitOpt
Options for tn_task_exit()
Definition: tn_tasks.h:160
enum TN_RCode task_wait_rc
waiting result code (reason why waiting finished)
Definition: tn_tasks.h:241
struct TN_ListItem mutex_queue
list of all mutexes that are locked by task
Definition: tn_tasks.h:199