utask.h File Reference

#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	utask
	Structure describing single task. More...
Defines
#define	UTASK_VER_STR   "0.3.3"
	defines utask version string
#define	UTASK_VER_MAJOR   0
	major version
#define	UTASK_VER_MINOR   3
	minor version
#define	UTASK_VER_REV   3
	revision
#define	UTASK_SIMPLE_ADD
	enables simplified utask_add (for fixed number of tasks)
#define	UTASK_EXIT
	enables utask_exit for ending tasks
#define	UTASK_STATS
	enables task finding and counting
#define	UTASK_SUSPEND_RESUME
	enables utask_suspend and utask_resume functions
#define	UTASK_NAME
	emables task names
#define	UTASK_TID
	enables task indentifiers (tids)
#define	UTASK_ARG
	enables arg field in utask type
#define	UTASK_SEM
	enables semaphores
#define	UTASK_SEM_CHANGE
	enables waiting for specific semaphore values (without only for 0 and non zero)
#define	UTASK_DATA   1
	enables data field in utask type (for free use)
#define	UTASKS   10
	defines how many tasks can be run in one time
#define	UTASK_PACKED_STRUCT
	enables structure packing
#define	UTASK_CHECK_MCU_SLEEP
	enables putting device to sleep
#define	UTASK_SLEEP_MAX   0xFFFFFFFF
#define	UTS_NONE   0
	unsused
#define	UTS_SUSP   1
	suspended
#define	UTS_READY   2
	ready for execution
#define	UTS_SLEEP   3
	asleep
#define	UTS_WAIT_E   4
	waiting for semaphore == val (val set in function)
#define	UTS_WAIT_NE   5
	waiting for semaphore != val (val set in function)
Typedefs
typedef uint32_t	utask_timer_t
	This typedef defines size of utask_t->sleep timer member.
typedef uint32_t	utask_state_t
	This typedef defines size of utask_t->state and utask_t->istate member.
typedef uint32_t	utask_sem_t
	This typedef defines size of utask_t->sem member.
typedef uint32_t	utask_data_t
	This typedef defines size of utask_t->data member.
typedef struct utask	utask_t
typedef void(*	utask_fun )(utask_t *t)
	task function typedef
Functions
void	utask_init (void)
	Intializes internal variables. Must be run before all other utask functions.
void	utask_schedule (void)
	Scheduling function, must be called forever.
void	utask_sleep_process (void)
	Timekeeping function, should be called from ISR.
utask_t *	utask_add (utask_fun fun)
	Add new task with function function for execution.
utask_t *	utask_add_name (utask_fun fun, const char *name)
	Add new task with function function and name name for execution.
void	utask_exit (utask_t *t)
	Terminate task t.
void	utask_sleep (utask_t *t, utask_timer_t ticks)
	Sleep task t for ticks ticks of clock.
void	utask_suspend (utask_t *t)
	Suspend task exectuion.
void	utask_resume (utask_t *t)
	Resume task t.
void	utask_wait_zero (utask_t *t, utask_sem_t *sem, utask_timer_t timeout)
	Wait for the semaphore sem to be cleared with timeout ticks of timeout.
void	utask_wait_nzero (utask_t *t, utask_sem_t *sem, utask_timer_t timeout)
	Wait for the semahore sem to be set with timeout ticks of timeout.
void	utask_wait_eq (utask_t *t, utask_sem_t *sem, utask_sem_t sem_val, utask_timer_t timeout)
	Wait for the semaphore sem value to be set to sem_value with timeout ticks of timeout.
void	utask_wait_neq (utask_t *t, utask_sem_t *sem, utask_sem_t sem_val, utask_timer_t timeout)
	Wait for the semaphore sem value to be changed from sem_value with timeout ticks of timeout.
utask_data_t	utask_get_free_slots (void)
	Returns free task slots.
utask_data_t	utask_get_task_cnt (utask_fun fun)
	Function returns number of tasks executing fun function.
utask_t *	utask_get_by_tid (utask_data_t tid)
	Returns task structure pointer by task id.
Variables
void(*	utask_put_mcu_to_sleep )(utask_data_t d)

---

Detailed Description

Authors:

B.Bielawski - InventLab, Marcin Zapolski - InventLab

Date:

2010.02.28

---

Function Documentation

utask_t* utask_add

(

utask_fun

fun

)

Add new task with function function for execution. Can be one of two versions:

• simple version allowing adding tasks only before first call to utask_schedule(), enabled when UTASK_SIMPLE_ADD is defined.
• version allowing spawning new task any time - when UTASK_SIMPLE_ADD is undefined.

After add is called following structure members are set to as follows:

• state is set to UTS_READY and task will be executed as soon as possible,
• istate is set to zero,
• sleep is set to zero,
• arg (if enabled) is set to zero,
• tid (if enabled) is last task's id + 1,
• not mentioned members are in undefined state.

Parameters:

fun	pointer to function to be executed

Returns:

pointer to task structure describing task of NULL in case of error

utask_t* utask_add_name	(	utask_fun	fun,
		const char *	name
	)

Add new task with function function and name name for execution. This is simple wrapper. See utask_add() for details.

Parameters:

fun	pointer to function to be executed
name	name of the task

Returns:

pointer to task structure describing task of NULL in case of error

void utask_exit

(

utask_t *

t

)

Ends task t. utask_exit() can terminate other tasks. Do not reference t after it has been freed with utask_exit().

Parameters:

t	pointer to utask structure

utask_t* utask_get_by_tid

(

utask_data_t

tid

)

Returns task structure pointer by task id.

Parameters:

tid

task id

Returns:

pointer to the task structure or NULL if not found

utask_data_t utask_get_free_slots

(

void

)

Returns free task slots.

Returns:

free task slots

utask_data_t utask_get_task_cnt

(

utask_fun

fun

)

Function returns number of tasks executing fun function.

Parameters:

fun

function

Returns:

numbers of tasks executing fun function.

void utask_init

(

void

)

Intializes internal variables. Must be run before all other utask functions.

Returns:

nothing

void utask_resume

(

utask_t *

t

)

Resume task t. It works on both on tasks put to sleep and suspended.

Parameters:

t	pointer to utask structure

void utask_schedule

(

void

)

Scheduling function, must be called forever (e.g. in main() in while(1) {} loop) or utask will not work!

Returns:

nothing

void utask_sleep	(	utask_t *	t,
		utask_timer_t	ticks
	)

Sleep task t for ticks ticks of clock. This function can put to sleep another task.

Parameters:

t	pointer to utask structure
ticks	number of ticks of clock for task to sleep

void utask_sleep_process

(

void

)

Function decreasing tasks' sleep timers. Must be called periodically (e.g. from timer ISR) or utask_sleep() and utask_wait_*() will not work properly! Calling frequency selects timeout tick resolution. Calling this function at 1kHz rate gives you tick equal to 1 ms. Call this function as often (or as rarely) as you need.

Returns:

nothing

void utask_suspend

(

utask_t *

t

)

Suspend task exectuion. This function can suspend another task.

Parameters:

t	pointer to utask structure

void utask_wait_eq	(	utask_t *	t,
		utask_sem_t *	sem,
		utask_sem_t	sem_val,
		utask_timer_t	timeout
	)

Wait for the semaphore sem value to be set to sem_value with timeout ticks of timeout. If contidion was met t->sleep != 0.

Parameters:

t	pointer to utask structure
sem	pointer to semaphore
sem_val	value waited for
timeout	waiting timeout

Returns:

nothing

void utask_wait_neq	(	utask_t *	t,
		utask_sem_t *	sem,
		utask_sem_t	sem_val,
		utask_timer_t	timeout
	)

Wait for the semaphore sem value to be changed from sem_value with timeout ticks of timeout. If contidion was met t->sleep != 0.

Parameters:

t	pointer to utask structure
sem	pointer to semaphore
sem_val	value waited for
timeout	waiting timeout

Returns:

nothing

void utask_wait_nzero	(	utask_t *	t,
		utask_sem_t *	sem,
		utask_timer_t	timeout
	)

Wait for the semahore sem to be set with timeout ticks of timeout. If condition was met t->sleep != 0.

Parameters:

t	pointer to utask structure
sem	pointer to semaphore
timeout	waiting timeout

Returns:

nothing

Examples:

utask_example_4.c.

void utask_wait_zero	(	utask_t *	t,
		utask_sem_t *	sem,
		utask_timer_t	timeout
	)

Wait for the semahore sem to be cleared with timeout ticks of timeout. If condition was met t->sleep != 0.

Parameters:

t	pointer to utask structure
sem	pointer to semaphore
timeout	waiting timeout

Examples:

utask_example_3.c.