TNeoKernel  v1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Macros | Enumerations | Functions
tn_tasks.h File Reference

Detailed Description

Various task services: create, sleep, wake up, terminate, etc.

Definition in file tn_tasks.h.

Go to the source code of this file.

Data Structures

struct  TN_Task
 Task. More...
 

Macros

#define TN_TASK_STACK_DEF(name, size)
 Convenience macro for the definition of stack array. More...
 

Enumerations

enum  TN_TaskState {
  TN_TASK_STATE_NONE = 0, TN_TASK_STATE_RUNNABLE = (1 << 0), TN_TASK_STATE_WAIT = (1 << 1), TN_TASK_STATE_SUSPEND = (1 << 2),
  TN_TASK_STATE_WAITSUSP = (TN_TASK_STATE_WAIT | TN_TASK_STATE_SUSPEND), TN_TASK_STATE_DORMANT = (1 << 3)
}
 Task state. More...
 
enum  TN_WaitReason {
  TN_WAIT_REASON_NONE, TN_WAIT_REASON_SLEEP, TN_WAIT_REASON_SEM, TN_WAIT_REASON_EVENT,
  TN_WAIT_REASON_DQUE_WSEND, TN_WAIT_REASON_DQUE_WRECEIVE, TN_WAIT_REASON_MUTEX_C, TN_WAIT_REASON_MUTEX_I,
  TN_WAIT_REASON_WFIXMEM
}
 Task wait reason. More...
 
enum  TN_TaskCreateOpt { TN_TASK_CREATE_OPT_START = (1 << 0), TN_TASK_CREATE_OPT_IDLE = (1 << 1) }
 Options for tn_task_create() More...
 
enum  TN_TaskExitOpt { TN_TASK_EXIT_OPT_DELETE = (1 << 0) }
 Options for tn_task_exit() More...
 

Functions

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). More...
 
enum TN_RCode tn_task_suspend (struct TN_Task *task)
 If the task is RUNNABLE, it is moved to the SUSPEND state. More...
 
enum TN_RCode tn_task_resume (struct TN_Task *task)
 Release task from SUSPEND state. More...
 
enum TN_RCode tn_task_sleep (TN_Timeout timeout)
 Put current task to sleep for at most timeout ticks. More...
 
enum TN_RCode tn_task_wakeup (struct TN_Task *task)
 Wake up task from sleep. More...
 
enum TN_RCode tn_task_iwakeup (struct TN_Task *task)
 The same as tn_task_wakeup() but for using in the ISR. More...
 
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() without TN_TASK_CREATE_OPT_START option, or terminated. More...
 
enum TN_RCode tn_task_iactivate (struct TN_Task *task)
 The same as tn_task_activate() but for using in the ISR. More...
 
enum TN_RCode tn_task_release_wait (struct TN_Task *task)
 Release task from WAIT state, independently of the reason of waiting. More...
 
enum TN_RCode tn_task_irelease_wait (struct TN_Task *task)
 The same as tn_task_release_wait() but for using in the ISR. More...
 
void tn_task_exit (enum TN_TaskExitOpt opts)
 This function terminates the currently running task. More...
 
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 one. More...
 
enum TN_RCode tn_task_delete (struct TN_Task *task)
 This function deletes the task specified by the task. More...
 
enum TN_RCode tn_task_change_priority (struct TN_Task *task, int new_priority)
 Set new priority for task. More...
 

Macro Definition Documentation

#define TN_TASK_STACK_DEF (   name,
  size 
)
Value:
TN_UWord name[ (size) ] \
#define TN_ARCH_STK_ATTR_AFTER
Compiler-specific attribute that should be placed after declaration of array used for stack...
unsigned int TN_UWord
Unsigned integer type whose size is equal to the size of CPU register.

Convenience macro for the definition of stack array.

See tn_task_create() for the usage example.

Parameters
nameC variable name of the array
sizesize of the stack array in words (TN_UWord), not in bytes.

Definition at line 294 of file tn_tasks.h.

Enumeration Type Documentation

Task state.

Enumerator
TN_TASK_STATE_NONE 

This state should never be publicly available.

It may be stored in task_state only temporarily, while some system service is in progress.

TN_TASK_STATE_RUNNABLE 

Task is ready to run (it doesn't mean that it is running at the moment)

TN_TASK_STATE_WAIT 

Task is waiting.

The reason of waiting can be obtained from task_wait_reason field of the struct TN_Task.

See also
enum TN_WaitReason
TN_TASK_STATE_SUSPEND 

Task is suspended (by some other task)

TN_TASK_STATE_WAITSUSP 

Task was previously waiting, and after this it was suspended.

TN_TASK_STATE_DORMANT 

Task isn't yet activated or it was terminated by tn_task_terminate().

Definition at line 72 of file tn_tasks.h.

Task wait reason.

Enumerator
TN_WAIT_REASON_NONE 

task isn't waiting for anything

TN_WAIT_REASON_SLEEP 

task has called tn_task_sleep()

TN_WAIT_REASON_SEM 

task waits to acquire a semaphore

See also
tn_sem.h
TN_WAIT_REASON_EVENT 

task waits for some event in the event group to be set

See also
tn_eventgrp.h
TN_WAIT_REASON_DQUE_WSEND 

task wants to put some data to the data queue, and there's no space in the queue.

See also
tn_dqueue.h
TN_WAIT_REASON_DQUE_WRECEIVE 

task wants to receive some data to the data queue, and there's no data in the queue

See also
tn_dqueue.h
TN_WAIT_REASON_MUTEX_C 

task wants to lock a mutex with priority ceiling

See also
tn_mutex.h
TN_WAIT_REASON_MUTEX_I 

task wants to lock a mutex with priority inheritance

See also
tn_mutex.h
TN_WAIT_REASON_WFIXMEM 

task wants to get memory block from memory pool, and there's no free memory blocks

See also
tn_fmem.h

Definition at line 101 of file tn_tasks.h.

Options for tn_task_create()

Enumerator
TN_TASK_CREATE_OPT_START 

whether task should be activated right after it is created.

If this flag is not set, user must activate task manually by calling tn_task_activate().

TN_TASK_CREATE_OPT_IDLE 

for internal kernel usage only: this option must be provided when creating idle task

Definition at line 144 of file tn_tasks.h.

Options for tn_task_exit()

Enumerator
TN_TASK_EXIT_OPT_DELETE 

whether task should be deleted right after it is exited.

If this flag is not set, user must either delete it manually by calling tn_task_delete() or re-activate it by calling tn_task_activate().

Definition at line 159 of file tn_tasks.h.

Function Documentation

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).

id_task member should not contain TN_ID_TASK, otherwise, TN_RC_WPARAM is returned.

Usage example:

#define MY_TASK_STACK_SIZE (TN_MIN_STACK_SIZE + 200)
#define MY_TASK_PRIORITY 5
struct TN_Task my_task;
//-- define stack array, we use convenience macro TN_TASK_STACK_DEF()
// for that
TN_TASK_STACK_DEF(my_task_stack, MY_TASK_STACK_SIZE);
void my_task_body(void *param)
{
//-- an endless loop
for (;;){
//-- probably do something useful
}
}

And then, somewhere from other task or from the callback TN_CBUserTaskCreate given to tn_sys_start() :

&my_task,
my_task_body,
MY_TASK_PRIORITY,
my_task_stack,
MY_TASK_STACK_SIZE,
NULL, //-- parameter isn't used
TN_TASK_CREATE_OPT_START //-- start task on creation
);
if (rc != TN_RC_OK){
//-- handle error
}
attr_call_task.png
(refer to Legend for details)

Parameters
taskReady-allocated struct TN_Task structure. id_task member should not contain TN_ID_TASK, otherwise TN_RC_WPARAM is returned.
task_funcPointer to task body function.
priorityPriority for new task. NOTE: the lower value, the higher priority. Must be > 0 and < (TN_PRIORITIES_CNT - 1).
task_stack_low_addrPointer to the stack for task. User must either use the macro TN_TASK_STACK_DEF() for the definition of stack array, or allocate it manually as an array of TN_UWord with TN_ARCH_STK_ATTR_BEFORE and TN_ARCH_STK_ATTR_AFTER macros.
task_stack_sizeSize of task stack array, in words (TN_UWord), not in bytes.
paramParameter that is passed to task_func.
optsOptions for task creation, refer to enum TN_TaskCreateOpt
Returns
See also
TN_ARCH_STK_ATTR_BEFORE
TN_ARCH_STK_ATTR_AFTER
enum TN_RCode tn_task_suspend ( struct TN_Task task)

If the task is RUNNABLE, it is moved to the SUSPEND state.

If the task is in the WAIT state, it is moved to the WAIT+SUSPEND state. (waiting + suspended)

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
taskTask to suspend
Returns
See also
enum TN_TaskState
enum TN_RCode tn_task_resume ( struct TN_Task task)

Release task from SUSPEND state.

If the given task is in the SUSPEND state, it is moved to RUNNABLE state; afterwards it has the lowest precedence among runnable tasks with the same priority. If the task is in WAIT+SUSPEND state, it is moved to WAIT state.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
taskTask to release from suspended state
Returns
See also
enum TN_TaskState
enum TN_RCode tn_task_sleep ( TN_Timeout  timeout)

Put current task to sleep for at most timeout ticks.

When the timeout expires and the task was not suspended during the sleep, it is switched to runnable state. If the timeout value is TN_WAIT_INFINITE and the task was not suspended during the sleep, the task will sleep until another function call (like tn_task_wakeup() or similar) will make it runnable.

attr_call_task.png
attr_call_ct_sw.png
attr_timeout.png
(refer to Legend for details)

Parameters
timeoutRefer to TN_Timeout
Returns
See also
TN_Timeout
enum TN_RCode tn_task_wakeup ( struct TN_Task task)

Wake up task from sleep.

Task is woken up if only it sleeps because of call to tn_task_sleep(). If task sleeps for some another reason, task won't be woken up, and tn_task_wakeup() returns TN_RC_WSTATE.

After this call, tn_task_sleep() returns TN_RC_OK.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
tasksleeping task to wake up
Returns
enum TN_RCode tn_task_iwakeup ( struct TN_Task task)

The same as tn_task_wakeup() but for using in the ISR.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)

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() without TN_TASK_CREATE_OPT_START option, or terminated.

Task is moved from DORMANT state to the RUNNABLE state.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
taskdormant task to activate
Returns
See also
TN_TaskState
enum TN_RCode tn_task_iactivate ( struct TN_Task task)

The same as tn_task_activate() but for using in the ISR.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)

enum TN_RCode tn_task_release_wait ( struct TN_Task task)

Release task from WAIT state, independently of the reason of waiting.

If task is in WAIT state, it is moved to RUNNABLE state. If task is in WAIT+SUSPEND state, it is moved to SUSPEND state.

TN_RC_FORCED is returned to the waiting task.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Attention
Usage of this function is discouraged, since the need for it indicates bad software design
Parameters
tasktask waiting for anything
Returns
See also
TN_TaskState
enum TN_RCode tn_task_irelease_wait ( struct TN_Task task)

The same as tn_task_release_wait() but for using in the ISR.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)

void tn_task_exit ( enum TN_TaskExitOpt  opts)

This function terminates the currently running task.

The task is moved to the DORMANT state.

After exiting, the task may be either deleted by the tn_task_delete() function call or reactivated by the tn_task_activate() / tn_task_iactivate() function call. In this case task starts execution from beginning (as after creation/activation). The task will have the lowest precedence among all tasks with the same priority in the RUNNABLE state.

If this function is invoked with TN_TASK_EXIT_OPT_DELETE option set, the task will be deleted after termination and cannot be reactivated (needs recreation).

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Returns
Returns if only called from wrong context. Normally, it never returns (since calling task becomes terminated)
See also
TN_TASK_EXIT_OPT_DELETE
tn_task_delete()
tn_task_activate()
tn_task_iactivate()
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 one.

After task is terminated, the task may be either deleted by the tn_task_delete() function call or reactivated by the tn_task_activate() / tn_task_iactivate() function call. In this case task starts execution from beginning (as after creation/activation). The task will have the lowest precedence among all tasks with the same priority in the RUNNABLE state.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
tasktask to terminate
Returns
enum TN_RCode tn_task_delete ( struct TN_Task task)

This function deletes the task specified by the task.

The task must be in the DORMANT state, otherwise TN_RC_WCONTEXT will be returned.

This function resets the id_task field in the task structure to 0 and removes the task from the system tasks list. The task can not be reactivated after this function call (the task must be recreated).

attr_call_task.png
(refer to Legend for details)

Parameters
taskdormant task to delete
Returns
enum TN_RCode tn_task_change_priority ( struct TN_Task task,
int  new_priority 
)

Set new priority for task.

If priority is 0, then task's base_priority is set.

attr_call_task.png
(refer to Legend for details)

Attention
this function is obsolete and will probably be removed