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

Detailed Description

Task

In TNeoKernel, a task is a branch of code that runs concurrently with other tasks from the programmer's point of view. Indeed, tasks are actually executed using processor time sharing. Each task can be considered to be an independed program, which executes in its own context (processor registers, stack pointer, etc.).

Actually, the term thread is more accurate than task, but the term task historically was used in TNKernel, so TNeoKernel keeps this convention.

When kernel decides that it's time to run another task, it performs context switch: current context (at least, values of all registers) gets saved to the preempted task's stack, pointer to currently running task is altered as well as stack pointer, and context gets restored from the stack of newly running task.

Task states

For list of task states and their description, refer to enum TN_TaskState.

Creating/starting tasks

Create task and delete task are two separate actions; although you can perform both of them in one step by passing TN_TASK_CREATE_OPT_START flag to the tn_task_create() function.

Stopping/deleting tasks

Stop task and delete task are two separate actions. If task was just stopped but not deleted, it can be just restarted again by calling tn_task_activate(). If task was deleted, it can't be just activated: it should be re-created by tn_task_create() first.

Task stops execution when:

Scheduling rules

TNeoKernel always runs the most privileged task in state RUNNABLE. In no circumstances can task run while there is at least one task is in the RUNNABLE state with higher priority. Task will run until:

Tasks with the same priority may be scheduled in round robin fashion by getting a predetermined time slice for each task with this priority. Time slice is set separately for each priority. By default, round robin is turned off for all priorities.

Idle task

TNeoKernel has one system task: an idle task, which has lowest priority. It is always in the state RUNNABLE, and it runs only when there are no other runnable tasks.

User can provide a callback function to be called from idle task, see TN_CBIdle. It is useful to bring the processor to some kind of real idle state, so that device draws less current.

Definition in file tn_tasks.h.

Go to the source code of this file.

Data Structures

struct  TN_Task
 Task. 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_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 combined with each other. More...
 
enum TN_RCode tn_task_change_priority (struct TN_Task *task, int new_priority)
 Set new priority for task. More...
 

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 141 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 170 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 213 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 228 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_STACK_ARR_DEF()
// for that
TN_STACK_ARR_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,
TN_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_STACK_ARR_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).

Please note that returning from task body function has the same effect as calling tn_task_exit(0).

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_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 combined with each other.

Currently, only WAIT and SUSPEND states are allowed to be set together. Nevertheless, it would be probably good idea to test individual bits in the returned value instead of plain comparing values.

Note that if something goes wrong, variable pointed to by p_state isn't touched.

attr_call_task.png
(refer to Legend for details)

Parameters
tasktask to get state of
p_statepointer to the location where to store state of the task
Returns
state of the task
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