Task Control Functions

Functions
POSEXTERN void POSCALL	posTaskYield (void)
POSEXTERN void POSCALL	posTaskSleep (UINT_t ticks)
POSEXTERN POSTASK_t POSCALL	posTaskCreate (POSTASKFUNC_t funcptr, void *funcarg, VAR_t priority, void *stackstart)
POSEXTERN void POSCALL	posInit (POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority, void *stackFirstTask, void *stackIdleTask)
POSEXTERN POSTASK_t POSCALL	posTaskCreate (POSTASKFUNC_t funcptr, void *funcarg, VAR_t priority, UINT_t stacksize)
POSEXTERN void POSCALL	posInit (POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority, UINT_t taskStackSize, UINT_t idleStackSize)
POSEXTERN POSTASK_t POSCALL	posTaskCreate (POSTASKFUNC_t funcptr, void *funcarg, VAR_t priority)
POSEXTERN void POSCALL	posInit (POSTASKFUNC_t firstfunc, void *funcarg, VAR_t priority)
POSEXTERN void POSCALL	posTaskExit (void)
POSEXTERN POSTASK_t POSCALL	posTaskGetCurrent (void)
POSEXTERN VAR_t POSCALL	posTaskUnused (POSTASK_t taskhandle)
POSEXTERN VAR_t POSCALL	posTaskSetPriority (POSTASK_t taskhandle, VAR_t priority)
POSEXTERN VAR_t POSCALL	posTaskGetPriority (POSTASK_t taskhandle)
POSEXTERN void POSCALL	posTaskSchedLock (void)
POSEXTERN void POSCALL	posTaskSchedUnlock (void)
POSEXTERN void *POSCALL	posTaskGetUserspace (void)
POSEXTERN POSIDLEFUNC_t POSCALL	posInstallIdleTaskHook (POSIDLEFUNC_t idlefunc)

Detailed Description

Function Documentation

posInit() [1/3]

POSEXTERN void POSCALL posInit	(	POSTASKFUNC_t	firstfunc,
		void *	funcarg,
		VAR_t	priority,
		void *	stackFirstTask,
		void *	stackIdleTask
	)

Operating System Initialization. This function initializes the operating system and starts the first tasks: The idle task and the first user task.

Parameters

firstfunc	pointer to the first task function that will run in the multitasking environment.
funcarg	optional argument passed to the first task.
priority	task priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.
stackFirstTask	pointer to the stack memory for the first task.
stackIdleTask	pointer to the stack memory for the idle task.

Note

POSCFG_TASKSTACKTYPE must be defined to 0 to have this format of the function compiled in.

posInit() [2/3]

POSEXTERN void POSCALL posInit	(	POSTASKFUNC_t	firstfunc,
		void *	funcarg,
		VAR_t	priority,
		UINT_t	taskStackSize,
		UINT_t	idleStackSize
	)

Operating System Initialization. This function initializes the operating system and starts the first tasks: The idle task and the first user task.

Parameters

firstfunc	pointer to the first task function that will run in the multitasking environment.
funcarg	optional argument passed to the first task.
priority	task priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.
taskStackSize	size of the stack memory for the first task.
idleStackSize	size of the stack memory for the idle task.

Note

POSCFG_TASKSTACKTYPE must be defined to 1 to have this format of the function compiled in.

posInit() [3/3]

POSEXTERN void POSCALL posInit	(	POSTASKFUNC_t	firstfunc,
		void *	funcarg,
		VAR_t	priority
	)

Operating System Initialization. This function initializes the operating system and starts the first tasks: The idle task and the first user task.

Parameters

firstfunc	pointer to the first task function that will run in the multitasking environment.
funcarg	optional argument passed to the first task.
priority	task priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.

Note

POSCFG_TASKSTACKTYPE must be defined to 2 to have this format of the function compiled in.

posInstallIdleTaskHook()

POSEXTERN POSIDLEFUNC_t POSCALL posInstallIdleTaskHook

(

POSIDLEFUNC_t

idlefunc

)

Task function. Install or remove an optional idle task hook function. The hook function is called every time the system is idle. It is possible to use this hook to implement your own idle task; in this case the function does not need to return to the system. You may insert a call to posTaskYield into your idle task loop to get a better task performance.

Parameters

idlefunc

function pointer to the new idle task handler. If this parameter is set to NULL, the idle task function hook is removed again.

Returns

This function may return a pointer to the last hook function set. If so (pointer is not NULL), the previous hook function should be called from within your idle task hook. This enables chaining of hook functions.

Note

POSCFG_FEATURE_IDLETASKHOOK must be defined to 1 to have this function compiled in.

posTaskCreate() [1/3]

POSEXTERN POSTASK_t POSCALL posTaskCreate	(	POSTASKFUNC_t	funcptr,
		void *	funcarg,
		VAR_t	priority,
		void *	stackstart
	)

Task function. Creates a new task. The stack memory is managed by the user.

Parameters

funcptr	pointer to the function that shall be executed by the new task.
funcarg	optional argument passed to function.
priority	task priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.
stackstart	pointer to the stack memory for the new task.

Returns

handle to the task. NULL is returned when the task could not be created.

Note

POSCFG_TASKSTACKTYPE must be defined to 0 to have this format of the function compiled in.

See also

posTaskExit

posTaskCreate() [2/3]

POSEXTERN POSTASK_t POSCALL posTaskCreate	(	POSTASKFUNC_t	funcptr,
		void *	funcarg,
		VAR_t	priority,
		UINT_t	stacksize
	)

Task function. Creates a new task. The stack memory is managed by the achitecture specific portion of the operating system, the size can be set by the user.

Parameters

funcptr	pointer to the function that shall be executed by the new task.
funcarg	optional argument passed to function.
priority	task priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.
stacksize	size of the stack memory. This parameter is passed to the architecture specific portion of the operating system.

Returns

handle to the task. NULL is returned when the task could not be created.

Note

POSCFG_TASKSTACKTYPE must be defined to 1 to have this format of the function compiled in.

See also

posTaskExit

posTaskCreate() [3/3]

POSEXTERN POSTASK_t POSCALL posTaskCreate	(	POSTASKFUNC_t	funcptr,
		void *	funcarg,
		VAR_t	priority
	)

Task function. Creates a new task. The stack memory is fixed, its size is set by the architecture specific portion of the operating system.

Parameters

funcptr	pointer to the function that shall be executed by the new task.
funcarg	optional argument passed to function.
priority	task priority. Must be in the range 0.. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.

Returns

handle to the task. NULL is returned when the task could not be created.

Note

POSCFG_TASKSTACKTYPE must be defined to 2 to have this format of the function compiled in.

See also

posTaskExit

posTaskExit()

POSEXTERN void POSCALL posTaskExit

(

void

)

Task function. Terminate execution of a task.

Note

POSCFG_FEATURE_EXIT must be defined to 1 to have this function compiled in.

See also

posTaskCreate

posTaskGetCurrent()

POSEXTERN POSTASK_t POSCALL posTaskGetCurrent

(

void

)

Task function. Get the handle to the currently running task.

Returns

the task handle.

Note

POSCFG_FEATURE_GETTASK must be defined to 1 to have this function compiled in.

See also

posTaskCreate, posTaskSetPriority

posTaskGetPriority()

POSEXTERN VAR_t POSCALL posTaskGetPriority

(

POSTASK_t

taskhandle

)

Task function. Get the priority of a task.

Parameters

taskhandle

handle to the task.

Returns

the priority of the task. A negative value is returned on error.

Note

POSCFG_FEATURE_GETPRIORITY must be defined to 1 to have this function compiled in.

See also

posTaskSetPriority, posTaskGetCurrent, posTaskCreate

posTaskGetUserspace()

POSEXTERN void* POSCALL posTaskGetUserspace

(

void

)

Task function. Returns a pointer to the user memory in the current task control block.

Note

POSCFG_TASKCB_USERSPACE must be defined to a nonzero value to have this function compiled in. POSCFG_TASKCB_USERSPACE is also used to set the size of the user memory (in bytes).

Returns

pointer to user memory space.

posTaskSchedLock()

POSEXTERN void POSCALL posTaskSchedLock

(

void

)

Task function. Locks the scheduler. When this function is called, no task switches will be done any more, until the counterpart function posTaskSchedUnlock is called. This function is usefull for short critical sections that require exclusive access to variables. Note that interrupts still remain enabled.

Note

POSCFG_FEATURE_INHIBITSCHED must be defined to 1 to have this function compiled in.

See also

posTaskSchedUnlock

posTaskSchedUnlock()

POSEXTERN void POSCALL posTaskSchedUnlock

(

void

)

Task function. Unlocks the scheduler. This function is called to leave a critical section. If a context switch request is pending, the context switch will happen directly after calling this function.

Note

POSCFG_FEATURE_INHIBITSCHED must be defined to 1 to have this function compiled in.

See also

posTaskSchedLock

posTaskSetPriority()

POSEXTERN VAR_t POSCALL posTaskSetPriority	(	POSTASK_t	taskhandle,
		VAR_t	priority
	)

Task function. Change the priority of a task. Note that in a non-roundrobin scheduling environment every priority level can only exist once.

Parameters

taskhandle	handle to the task.
priority	new priority. Must be in the range 0 .. POSCFG_MAX_PRIO_LEVEL - 1. The higher the number, the higher the priority.

Returns

zero on success.

Note

POSCFG_FEATURE_SETPRIORITY must be defined to 1 to have this function compiled in.

See also

posTaskGetPriority, posTaskGetCurrent, posTaskCreate

posTaskSleep()

POSEXTERN void POSCALL posTaskSleep

(

UINT_t

ticks

)

Task function. Delay task execution for a couple of timer ticks.

Parameters

ticks

delay time in timer ticks (see HZ define and MS macro)

Note

POSCFG_FEATURE_SLEEP must be defined to 1 to have this function compiled in.
It is not guaranteed that the task will proceed execution exactly when the time has elapsed. A higher priorized task or a task having the same priority may steal the processing time. Sleeping a very short time is inaccurate.

See also

posTaskYield, HZ, MS

posTaskUnused()

POSEXTERN VAR_t POSCALL posTaskUnused

(

POSTASK_t

taskhandle

)

Task function. Tests if a task is yet in use by the operating system. This function can be used to test if a task has been fully terminated (and the stack memory is no more in use).

Parameters

taskhandle

handle to the task.

Returns

1 (=true) when the task is unused. If the task is still in use, zero is returned. A negative value is returned on error.

Note

POSCFG_FEATURE_TASKUNUSED must be defined to 1 to have this function compiled in.

See also

posTaskCreate, posTaskExit

posTaskYield()

POSEXTERN void POSCALL posTaskYield

(

void

)

Task function. This function can be called to give off processing time so other tasks ready to run will be scheduled (= cooparative multitasking).

Note

POSCFG_FEATURE_YIELD must be defined to 1 to have this function compiled in.

See also

posTaskSleep