Detailed Description

Task

In TNeo, 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 TNeo 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 start 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:

it calls tn_task_exit();
it returns from its task body function (it is the equivalent to tn_task_exit(0))
some other task calls tn_task_terminate() passing appropriate pointer to struct TN_Task.

Scheduling rules

TNeo 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:

It becomes non-runnable (say, it may wait for something, etc)
Some other task with higher priority becomes runnable.

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

TNeo 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_TaskTiming
	Timing structure that is managed by profiler and can be read by `tn_task_profiler_timing_get()` function. More...

struct	_TN_TaskProfiler
	Internal kernel structure for profiling data of task. More...

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, TN_WAIT_REASONS_CNT }
	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_create_wname (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, const char *name)
	The same as `tn_task_create()` but with additional argument `name`, which could be very useful for debug.

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_TickCnt 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_profiler_timing_get (const struct TN_Task task, struct TN_TaskTiming tgt)
	Read profiler timing data of the task. More...

enum TN_RCode	tn_task_change_priority (struct TN_Task *task, int new_priority)
	Set new priority for task. More...

Enumeration Type Documentation

◆ TN_TaskState

enum TN_TaskState

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.

◆ TN_WaitReason

enum TN_WaitReason

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
TN_WAIT_REASONS_CNT	Wait reasons count.

Definition at line 173 of file tn_tasks.h.

◆ TN_TaskCreateOpt

enum TN_TaskCreateOpt

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 221 of file tn_tasks.h.

◆ TN_TaskExitOpt

enum TN_TaskExitOpt

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 236 of file tn_tasks.h.

Function Documentation

◆ tn_task_create()

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 (;;){
      tn_task_sleep(1);
      //-- probably do something useful
   }
}

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

enum TN_RCode rc = tn_task_create(
      &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
}

(refer to Legend for details)

Parameters

task	Ready-allocated `struct TN_Task` structure. `id_task` member should not contain `TN_ID_TASK`, otherwise `TN_RC_WPARAM` is returned.
task_func	Pointer to task body function.
priority	Priority for new task. NOTE: the lower value, the higher priority. Must be > `0` and < `(TN_PRIORITIES_CNT - 1)`.
task_stack_low_addr	Pointer 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_size	Size of task stack array, in words (`TN_UWord`), not in bytes.
param	Parameter that is passed to `task_func`.
opts	Options for task creation, refer to `enum TN_TaskCreateOpt`

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context;
TN_RC_WPARAM if wrong params were given;

See also: tn_task_create_wname(); TN_ARCH_STK_ATTR_BEFORE; TN_ARCH_STK_ATTR_AFTER

◆ tn_task_suspend()

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)

(refer to Legend for details)

Parameters

task	Task to suspend

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context;
TN_RC_WSTATE if task is already suspended or dormant;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

See also: enum TN_TaskState

◆ tn_task_resume()

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.

(refer to Legend for details)

Parameters

task	Task to release from suspended state

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context;
TN_RC_WSTATE if task is not suspended;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

See also: enum TN_TaskState

◆ tn_task_sleep()

enum TN_RCode tn_task_sleep ( TN_TickCnt 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.

(refer to Legend for details)

Parameters

timeout Refer to TN_TickCnt

Returns

TN_RC_TIMEOUT if task has slept specified timeout;
TN_RC_OK if task was woken up from other task by tn_task_wakeup()
TN_RC_FORCED if task was released from wait forcibly by tn_task_release_wait()
TN_RC_WCONTEXT if called from wrong context

See also: TN_TickCnt

◆ tn_task_wakeup()

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.

(refer to Legend for details)

Parameters

task	sleeping task to wake up

Returns

TN_RC_OK if successful
TN_RC_WSTATE if task is not sleeping, or it is sleeping for some reason other than tn_task_sleep() call.
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ tn_task_iwakeup()

enum TN_RCode tn_task_iwakeup ( struct TN_Task * task )

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

(refer to Legend for details)

◆ tn_task_activate()

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.

(refer to Legend for details)

Parameters

task	dormant task to activate

Returns

TN_RC_OK if successful
TN_RC_WSTATE if task is not dormant
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

See also: TN_TaskState

◆ tn_task_iactivate()

enum TN_RCode tn_task_iactivate ( struct TN_Task * task )

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

(refer to Legend for details)

◆ tn_task_release_wait()

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.

(refer to Legend for details)

Attention: Usage of this function is discouraged, since the need for it indicates bad software design

Parameters

task	task waiting for anything

Returns

TN_RC_OK if successful
TN_RC_WSTATE if task is not waiting for anything
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

See also: TN_TaskState

◆ tn_task_irelease_wait()

enum TN_RCode tn_task_irelease_wait ( struct TN_Task * task )

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

(refer to Legend for details)

◆ tn_task_exit()

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

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

◆ tn_task_terminate()

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.

(refer to Legend for details)

Parameters

task	task to terminate

Returns

TN_RC_OK if successful
TN_RC_WSTATE if task is already dormant
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ tn_task_delete()

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

(refer to Legend for details)

Parameters

task	dormant task to delete

Returns

TN_RC_OK if successful
TN_RC_WSTATE if task is not dormant
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ tn_task_state_get()

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.

(refer to Legend for details)

Parameters

task	task to get state of
p_state	pointer to the location where to store state of the task

Returns: state of the task

◆ tn_task_profiler_timing_get()

enum TN_RCode tn_task_profiler_timing_get	(	const struct TN_Task *	task,
		struct TN_TaskTiming *	tgt
	)

Read profiler timing data of the task.

See struct TN_TaskTiming for details on timing data.

(refer to Legend for details)

Parameters

task	Task to get timing data of
tgt	Target structure to fill with data, should be allocated by caller

◆ tn_task_change_priority()

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.

(refer to Legend for details)

Attention: this function is obsolete and will probably be removed

Detailed Description

Task

Task states

Creating/starting tasks

Stopping/deleting tasks

Scheduling rules

Idle task

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ TN_TaskState

◆ TN_WaitReason

◆ TN_TaskCreateOpt

◆ TN_TaskExitOpt

Function Documentation

◆ tn_task_create()

◆ tn_task_suspend()

◆ tn_task_resume()

◆ tn_task_sleep()

◆ tn_task_wakeup()

◆ tn_task_iwakeup()

◆ tn_task_activate()

◆ tn_task_iactivate()

◆ tn_task_release_wait()

◆ tn_task_irelease_wait()

◆ tn_task_exit()

◆ tn_task_terminate()

◆ tn_task_delete()

◆ tn_task_state_get()

◆ tn_task_profiler_timing_get()

◆ tn_task_change_priority()