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