Task

tasks (creation, control, delays) More...

Macros
#define	STK_SIZE(size)
	size of the task stack in stk_t units: the size in bytes (rounded up) with the guard area
#define	OS_TSK_STACK(stk, ...)
	define task stack
#define	static_TSK_STACK(stk, ...)
	static alias of OS_TSK_STACK()
#define	OS_WRK(tsk, prio, proc, size)
	define and initialize complete work area for task object
#define	static_WRK(tsk, prio, proc, size)
	static alias of OS_WRK()
#define	OS_TSK(tsk, prio, proc, ...)
	define and initialize complete work area for task object with default stack size
#define	static_TSK(tsk, prio, proc, ...)
	static alias of OS_TSK()
#define	OS_WRK_DEF(tsk, prio, size)
	define and initialize complete work area for task object
#define	static_WRK_DEF(tsk, prio, size)
	static alias of OS_WRK_DEF()
#define	OS_TSK_DEF(tsk, prio, ...)
	define and initialize complete work area for task object with default stack size
#define	static_TSK_DEF(tsk, prio, ...)
	static alias of OS_TSK_DEF()
#define	OS_WRK_START(tsk, prio, size)
	define, initialize and start complete work area for task object
#define	static_WRK_START(tsk, prio, size)
	static alias of OS_WRK_START()
#define	OS_TSK_START(tsk, prio, ...)
	define, initialize and start complete work area for task object with default stack size
#define	static_TSK_START(tsk, prio, ...)
	static alias of OS_TSK_START()
#define	WRK_INIT(prio, proc, size)
	create and initialize complete work area for task object
#define	WRK_CREATE(prio, proc, size)
	create and initialize complete work area for task object
#define	WRK_NEW   WRK_CREATE
	alias of WRK_CREATE()
#define	TSK_INIT(prio, proc, ...)
	create and initialize complete work area for task object with default stack size
#define	TSK_CREATE(prio, proc, ...)
	create and initialize complete work area for task object with default stack size
#define	TSK_NEW   TSK_CREATE
	alias of TSK_CREATE()
#define	SELF   ( System.cur )
	alias of tsk_this()

Functions
tsk_t *	tsk_this (void)
	return current task object
tsk_t *	cur_task (void)
	alias of tsk_this()
void	wrk_init (tsk_t *tsk, unsigned prio, fun_t *proc, stk_t *stack, size_t size)
	initialize complete work area for task object
void	tsk_init (tsk_t *tsk, unsigned prio, fun_t *proc, stk_t *stack, size_t size)
	initialize complete work area for task object and start the task, if proc != NULL
tsk_t *	wrk_create (unsigned prio, fun_t *proc, size_t size, bool detached, bool autostart)
	create and initialize complete work area for task object
tsk_t *	wrk_new (unsigned prio, fun_t *proc, size_t size, bool detached, bool autostart)
	alias of wrk_create()
tsk_t *	tsk_setup (unsigned prio, fun_a *proc, void *arg, size_t size)
	create and initialize complete work area for task object and start the task, if proc != NULL
tsk_t *	tsk_create (unsigned prio, fun_t *proc)
	create and initialize a new task object with default stack size and start the task, if proc != NULL
tsk_t *	tsk_new (unsigned prio, fun_t *proc)
	alias of tsk_create()
tsk_t *	tsk_detached (unsigned prio, fun_t *proc)
	create and initialize a new detached task object with default stack size and start the task, if proc != NULL
void	tsk_start (tsk_t *tsk)
	start previously defined/created/stopped task object
void	tsk_startFrom (tsk_t *tsk, fun_t *proc)
	start previously defined/created/stopped task object
void	tsk_startWith (tsk_t *tsk, fun_a *proc, void *arg)
	start previously defined/created/stopped task object
int	tsk_detach (tsk_t *tsk)
	detach given task
int	tsk_join (tsk_t *tsk)
	delay execution of current task until termination of given task
void	tsk_stop (void)
	stop the current task and remove it from READY queue
void	tsk_exit (void)
	alias of tsk_stop()
int	tsk_reset (tsk_t *tsk)
	reset the task object and remove it from READY/BLOCKED queue
int	tsk_kill (tsk_t *tsk)
	alias of tsk_reset()
int	tsk_destroy (tsk_t *tsk)
	reset the task object and free allocated resources
int	tsk_delete (tsk_t *tsk)
	alias of tsk_destroy()
void	tsk_yield (void)
	yield system control to the next task with the same priority in READY queue
void	tsk_pass (void)
	alias of tsk_yield()
void	tsk_flip (fun_t *proc)
	restart current task with the new proc (task function)
void	tsk_setPrio (unsigned prio)
	set current task priority
void	tsk_prio (unsigned prio)
	alias of tsk_setPrio()
unsigned	tsk_getPrio (void)
	get current task priority
void	tsk_sleepFor (cnt_t delay)
	delay execution of current task for given duration of time
void	tsk_delay (cnt_t delay)
	alias of tsk_sleepFor()
void	tsk_sleepNext (cnt_t delay)
	delay execution of current task for given duration of time
void	tsk_sleepUntil (cnt_t time)
	delay execution of current task until given timepoint
void	tsk_sleep (void)
	delay indefinitely execution of current task
int	tsk_suspend (tsk_t *tsk)
	delay indefinitely execution of given task
int	tsk_resume (tsk_t *tsk)
	resume execution of given suspended task
int	tsk_resumeISR (tsk_t *tsk)
	ISR alias of tsk_resume().
void	tsk_give (tsk_t *tsk, unsigned signo)
	send given signal to the task
void	tsk_signal (tsk_t *tsk, unsigned signo)
	alias of tsk_give()
void	tsk_action (tsk_t *tsk, act_t *action)
	set given function as a signal handler
size_t	tsk_stackSpace (void)
	chack water mark of the stack of the current task

Detailed Description

tasks (creation, control, delays)

Macro Definition Documentation

STK_SIZE

#define STK_SIZE

(

size

)

Value:

ALIGNED_SIZE((size_t)( size ) + (OS_GUARD_SIZE), sizeof(stk_t))

size of the task stack in stk_t units: the size in bytes (rounded up) with the guard area

OS_TSK_STACK

#define OS_TSK_STACK	(		stk,
			... )

Value:

stk_t stk[ STK_SIZE( _VA_STK(__VA_ARGS__) ) ] __STKALIGN

define task stack

Parameters

stk	name of the stack (passed to the init function)
...	size: (optional) size of task stack (in bytes); default: OS_STACK_SIZE

static_TSK_STACK

#define static_TSK_STACK	(		stk,
			... )

Value:

static stk_t stk[ STK_SIZE( _VA_STK(__VA_ARGS__) ) ] __STKALIGN

static alias of OS_TSK_STACK()

OS_WRK

#define OS_WRK	(		tsk,
			prio,
			proc,
			size )

Value:

static stk_t tsk##__stk[STK_SIZE( size )] __STKALIGN; \
       tsk_t tsk[] = { _TSK_INIT( prio, proc, tsk##__stk, STK_OVER( size ) ) }

define and initialize complete work area for task object

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
size	size of task private stack (in bytes)

static_WRK

#define static_WRK	(		tsk,
			prio,
			proc,
			size )

Value:

static stk_t tsk##__stk[STK_SIZE( size )] __STKALIGN; \
static tsk_t tsk[] = { _TSK_INIT( prio, proc, tsk##__stk, STK_OVER( size ) ) }

static alias of OS_WRK()

OS_TSK

#define OS_TSK	(		tsk,
			prio,
			proc,
			... )

Value:

OS_WRK( tsk, prio, proc, _VA_STK(__VA_ARGS__) )

define and initialize complete work area for task object with default stack size

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
...	size: (optional) size of task private stack (in bytes); default: OS_STACK_SIZE

static_TSK

#define static_TSK	(		tsk,
			prio,
			proc,
			... )

Value:

static_WRK( tsk, prio, proc, _VA_STK(__VA_ARGS__) )

static alias of OS_TSK()

OS_WRK_DEF

#define OS_WRK_DEF	(		tsk,
			prio,
			size )

Value:

static void tsk##__fun( void );           \
    OS_WRK( tsk, prio, tsk##__fun, size ); \
static void tsk##__fun( void )

define and initialize complete work area for task object

     task proc (function body) must be defined immediately below

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
size	size of task private stack (in bytes)

static_WRK_DEF

#define static_WRK_DEF	(		tsk,
			prio,
			size )

Value:

static void tsk##__fun( void );           \
static_WRK( tsk, prio, tsk##__fun, size ); \
static void tsk##__fun( void )

static alias of OS_WRK_DEF()

OS_TSK_DEF

#define OS_TSK_DEF	(		tsk,
			prio,
			... )

Value:

OS_WRK_DEF( tsk, prio, _VA_STK(__VA_ARGS__) )

define and initialize complete work area for task object with default stack size

     task proc (function body) must be defined immediately below

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
...	size: (optional) size of task private stack (in bytes); default: OS_STACK_SIZE

static_TSK_DEF

#define static_TSK_DEF	(		tsk,
			prio,
			... )

Value:

static_WRK_DEF( tsk, prio, _VA_STK(__VA_ARGS__) )

static alias of OS_TSK_DEF()

OS_WRK_START

#define OS_WRK_START	(		tsk,
			prio,
			size )

Value:

              static void tsk##__fun( void );                              \
                  OS_WRK( tsk, prio, tsk##__fun, size );                    \
__CONSTRUCTOR static void tsk##__run( void ) { sys_init(); tsk_start(tsk); } \
              static void tsk##__fun( void )

define, initialize and start complete work area for task object

     task proc (function body) must be defined immediately below

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
size	size of task private stack (in bytes)

Note

only available for compilers supporting the "constructor" function attribute or its equivalent

static_WRK_START

#define static_WRK_START	(		tsk,
			prio,
			size )

Value:

              static void tsk##__fun( void );                              \
              static_WRK( tsk, prio, tsk##__fun, size );                    \
__CONSTRUCTOR static void tsk##__run( void ) { sys_init(); tsk_start(tsk); } \
              static void tsk##__fun( void )

static alias of OS_WRK_START()

OS_TSK_START

#define OS_TSK_START	(		tsk,
			prio,
			... )

Value:

OS_WRK_START( tsk, prio, _VA_STK(__VA_ARGS__) )

define, initialize and start complete work area for task object with default stack size

     task proc (function body) must be defined immediately below

Parameters

tsk	name of a pointer to task object
prio	initial task priority (any unsigned int value)
...	size: (optional) size of task private stack (in bytes); default: OS_STACK_SIZE

Note

only available for compilers supporting the "constructor" function attribute or its equivalent

static_TSK_START

#define static_TSK_START	(		tsk,
			prio,
			... )

Value:

static_WRK_START( tsk, prio, _VA_STK(__VA_ARGS__) )

static alias of OS_TSK_START()

WRK_INIT

#define WRK_INIT	(		prio,
			proc,
			size )

Value:

_TSK_INIT( prio, proc, _TSK_STACK( size ), STK_OVER( size ) )

create and initialize complete work area for task object

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
size	size of task private stack (in bytes)

Returns

task object

Note

use only in 'C' code

WRK_CREATE

#define WRK_CREATE	(		prio,
			proc,
			size )

Value:

{ WRK_INIT  ( prio, proc, size ) }

create and initialize complete work area for task object

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
size	size of task private stack (in bytes)

Returns

task object as array (id)

Note

use only in 'C' code

TSK_INIT

#define TSK_INIT	(		prio,
			proc,
			... )

Value:

WRK_INIT( prio, proc, _VA_STK(__VA_ARGS__) )

create and initialize complete work area for task object with default stack size

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
...	size: (optional) size of task private stack (in bytes); default: OS_STACK_SIZE

Returns

task object

Note

use only in 'C' code

TSK_CREATE

#define TSK_CREATE	(		prio,
			proc,
			... )

Value:

WRK_CREATE( prio, proc, _VA_STK(__VA_ARGS__) )

create and initialize complete work area for task object with default stack size

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
...	size: (optional) size of task private stack (in bytes); default: OS_STACK_SIZE

Returns

task object as array (id)

Note

use only in 'C' code

Function Documentation

tsk_this()

tsk_t * tsk_this ( void )

inline

return current task object

Returns

current task object

Note

use only in thread mode

wrk_init()

void wrk_init	(	tsk_t *	tsk,
		unsigned	prio,
		fun_t *	proc,
		stk_t *	stack,
		size_t	size )

initialize complete work area for task object

     don't start the task

Parameters

tsk	pointer to task object
prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
stack	base of task's private stack storage
size	size of task private stack (in bytes)

Note

use only in thread mode

tsk_init()

void tsk_init	(	tsk_t *	tsk,
		unsigned	prio,
		fun_t *	proc,
		stk_t *	stack,
		size_t	size )

initialize complete work area for task object and start the task, if proc != NULL

Parameters

tsk	pointer to task object
prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
stack	base of task's private stack storage
size	size of task private stack (in bytes)

Note

use only in thread mode

wrk_create()

tsk_t * wrk_create	(	unsigned	prio,
		fun_t *	proc,
		size_t	size,
		bool	detached,
		bool	autostart )

create and initialize complete work area for task object

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop
size	size of task private stack (in bytes)
detached	create as detached?
autostart	specifies whether the task runs immediately after initialization

Returns

pointer to task object

Return values

NULL	object not created (not enough free memory)

Note

use only in thread mode

tsk_setup()

tsk_t * tsk_setup	(	unsigned	prio,
		fun_a *	proc,
		void *	arg,
		size_t	size )

create and initialize complete work area for task object and start the task, if proc != NULL

Parameters

prio	initial task priority (any unsigned int value)
proc	task initial procedure (initial task function with argument)
arg	task initial procedure argument
size	size of task private stack (in bytes)

Returns

pointer to task object

Return values

NULL	object not created (not enough free memory)

Note

use only in thread mode

tsk_startFrom and tsk_flip clear the argument

tsk_create()

tsk_t * tsk_create ( unsigned prio, fun_t * proc )

inline

create and initialize a new task object with default stack size and start the task, if proc != NULL

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop

Returns

pointer to task object

Return values

NULL	object not created (not enough free memory)

Note

use only in thread mode

tsk_detached()

tsk_t * tsk_detached ( unsigned prio, fun_t * proc )

inline

create and initialize a new detached task object with default stack size and start the task, if proc != NULL

Parameters

prio	initial task priority (any unsigned int value)
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop

Returns

pointer to task object

Return values

NULL	object not created (not enough free memory)

Note

use only in thread mode

tsk_start()

void tsk_start

(

tsk_t *

tsk

)

start previously defined/created/stopped task object

Parameters

tsk	pointer to task object

Note

use only in thread mode

tsk_startFrom()

void tsk_startFrom	(	tsk_t *	tsk,
		fun_t *	proc )

start previously defined/created/stopped task object

Parameters

tsk	pointer to task object
proc	task proc (initial task function) doesn't have to be noreturn-type it will be executed into an infinite system-implemented loop

Note

use only in thread mode

tsk_startWith()

void tsk_startWith	(	tsk_t *	tsk,
		fun_a *	proc,
		void *	arg )

start previously defined/created/stopped task object

Parameters

tsk	pointer to task object
proc	task initial procedure (initial task function with argument)
arg	task initial procedure argument

Note

use only in thread mode

tsk_startFrom and tsk_flip clear the argument

tsk_detach()

int tsk_detach

(

tsk_t *

tsk

)

detach given task

Parameters

tsk	pointer to task object

Return values

E_SUCCESS	given task was successfully detached
E_FAILURE	given task cannot be detached

Note

use only in thread mode

tsk_join()

int tsk_join

(

tsk_t *

tsk

)

delay execution of current task until termination of given task

Parameters

tsk	pointer to task object

Return values

E_SUCCESS	given task has stopped (stop / exit)
E_STOPPED	given task was reseted (reset / kill)
E_DELETED	given task was deleted (delete / destroy)
E_FAILURE	given task cannot be joined

Note

use only in thread mode

tsk_stop()

void tsk_stop

(

void

)

stop the current task and remove it from READY queue

     all mutexes held by the task are released (waiting tasks get E_STOPPED, robust mutex: next owner gets OWNERDEAD)

     detached task is destroyed, otherwise
     function doesn't destroy the stack storage,
     and all allocated resources will remain intact until
     joining, destroying or restarting the task

Note

use only in thread mode

tsk_reset()

int tsk_reset

(

tsk_t *

tsk

)

reset the task object and remove it from READY/BLOCKED queue

     all mutexes held by the task are released (waiting tasks get E_STOPPED, robust mutex: next owner gets OWNERDEAD)

     other objects held by the task (e.g. semaphores, read/write locks) are not released

Parameters

tsk	pointer to task object

Return values

E_SUCCESS	given task was already inactive or has been reseted
E_FAILURE	given task cannot be reseted

Note

use only in thread mode

readers waiting behind a writer stopped while waiting for a read/write lock are not released until the lock is given

tsk_destroy()

int tsk_destroy

(

tsk_t *

tsk

)

reset the task object and free allocated resources

     all mutexes held by the task are released (waiting tasks get E_STOPPED, robust mutex: next owner gets OWNERDEAD)

Parameters

tsk	pointer to task object

Return values

E_SUCCESS	given task has been destroyed
E_FAILURE	given task cannot be destroyed

Note

use only in thread mode

tsk_yield()

void tsk_yield

(

void

)

yield system control to the next task with the same priority in READY queue

     the current task goes to the end of its priority group (also when a higher priority task is ready)

Note

use only in thread mode

tsk_flip()

void tsk_flip

(

fun_t *

proc

)

restart current task with the new proc (task function)

     all mutexes held by the task are released (waiting tasks get E_STOPPED, robust mutex: next owner gets OWNERDEAD)

Parameters

proc	new task proc (task function)

Note

use only in thread mode

tsk_setPrio()

void tsk_setPrio

(

unsigned

prio

)

set current task priority

Parameters

prio	new task priority value

Note

use only in thread mode

tsk_getPrio()

unsigned tsk_getPrio

(

void

)

get current task priority

Returns

current task priority value

Note

use only in thread mode

tsk_sleepFor()

void tsk_sleepFor

(

cnt_t

delay

)

delay execution of current task for given duration of time

Parameters

delay

duration of time (maximum number of ticks to delay execution of current task) IMMEDIATE: don't delay execution of current task (cooperative mode: only give up the processor once) INFINITE: delay indefinitely execution of current task

Note

use only in thread mode

tsk_sleepNext()

void tsk_sleepNext

(

cnt_t

delay

)

delay execution of current task for given duration of time

     from the end of the previous countdown

Parameters

delay

duration of time (maximum number of ticks to delay execution of current task) IMMEDIATE: don't delay execution of current task (cooperative mode: only give up the processor once) INFINITE: delay indefinitely execution of current task

Note

use only in thread mode

tsk_sleepUntil()

void tsk_sleepUntil

(

cnt_t

time

)

delay execution of current task until given timepoint

Parameters

time	timepoint value past timepoint: don't delay execution of current task (cooperative mode: only give up the processor once)

Note

use only in thread mode

tsk_sleep()

void tsk_sleep ( void )

inline

delay indefinitely execution of current task

     execution of the task can be resumed

Note

use only in thread mode

tsk_suspend()

int tsk_suspend

(

tsk_t *

tsk

)

delay indefinitely execution of given task

     execution of the task can be resumed

Parameters

tsk	pointer to task object

Return values

E_SUCCESS	task was successfully suspended
E_FAILURE	task cannot be suspended

Note

use only in thread mode

tsk_resume()

int tsk_resume

(

tsk_t *

tsk

)

resume execution of given suspended task

     only suspended or indefinitely blocked tasks can be resumed

Parameters

tsk	pointer to suspended task object

Return values

E_SUCCESS	task was successfully resumed
E_FAILURE	task cannot be resumed

Note

can be used in both thread and handler mode (for blockable interrupts)

use ISR alias in blockable interrupt handlers

tsk_give()

void tsk_give	(	tsk_t *	tsk,
		unsigned	signo )

send given signal to the task

Parameters

tsk	pointer to the task object
signo	signal number

Note

use only in thread mode

the signal handler of a blocked task is called after the task is woken up (the task does not leave the blocked queue, so no wakeup can be lost)

the signal handler is called on the stack of the task; the stack must have room for an additional task context (and another one, if the handler calls blocking functions)

signals sent by the task to itself are handled immediately, also inside a critical section of the caller (the handler is called with unlocked interrupts); if such a handler is preempted and the task receives another signal, the handler is called again (nested), so it should be reentrant

tsk_action()

void tsk_action	(	tsk_t *	tsk,
		act_t *	action )

set given function as a signal handler

Parameters

tsk	pointer to the task object
action	signal handler

Note

use only in thread mode

the signal handler of a blocked task is called after the task is woken up (the task does not leave the blocked queue, so no wakeup can be lost)

the signal handler is called on the stack of the task; the stack must have room for an additional task context (and another one, if the handler calls blocking functions)

signals sent by the task to itself are handled immediately, also inside a critical section of the caller (the handler is called with unlocked interrupts); if such a handler is preempted and the task receives another signal, the handler is called again (nested), so it should be reentrant

tsk_stackSpace()

size_t tsk_stackSpace ( void )

inline

chack water mark of the stack of the current task

Returns

high water mark of the stack of the current task

Return values

0	DEBUG not defined