Detailed Description

Task Manager.

The Task module makes available a set of functions that manipulate task objects accessed through pointers of type Task_Handle. Tasks represent independent threads of control that conceptually execute functions in parallel within a single C program; in reality, concurrency is achieved by switching the processor from one task to another.

All tasks executing within a single program share a common set of global variables, accessed according to the standard rules of scope defined for C functions.

Each task is in one of five modes of execution at any point in time: running, ready, blocked, terminated, or inactive. By design, there is always one (and only one) task currently running, even if it is only the idle task managed internally by Task. The current task can be suspended from execution by calling certain Task functions, as well as functions provided by other modules like the Semaphore or Event Modules. The current task can also terminate its own execution. In either case, the processor is switched to the highest priority task that is ready to run.

You can assign numeric priorities to tasks. Tasks are readied for execution in strict priority order; tasks of the same priority are scheduled on a first-come, first-served basis. The priority of the currently running task is never lower than the priority of any ready task. Conversely, the running task is preempted and re-scheduled for execution whenever there exists some ready task of higher priority.

To use the Task module or to set any of the Task module configuration variables, the following must be added to the app.syscfg file:

const Task = scripting.addModule("/ti/sysbios/knl/Task");

Task Stacks

When you create a task, it is provided with its own run-time stack, used for storing local variables as well as for further nesting of function calls. Each stack must be large enough to handle normal subroutine calls and one task preemption context. A task preemption context is the context that gets saved when one task preempts another as a result of an interrupt thread readying a higher-priority task.

See the BIOS User's Guide for further discussions regarding task stack sizing.

Certain system configuration settings will result in task stacks needing to be large enough to absorb two interrupt contexts rather than just one. Setting the BIOS logsEnabled configuration parameter to 'true' or installing any Task hooks will have the side effect of allowing up to two interrupt contexts to be placed on a task stack.

Task Deletion

Any dynamically created task that is not in the Task_Mode_RUNNING state (ie not the currently running task) can be deleted using the Task_delete API.

Task_delete() removes the task from all internal queues and calls Memory_free() is used to free the task object and its stack. Memory_free() must acquire a lock to the memory before proceeding. If another task already holds a lock to the memory, then the thread performing the delete will be blocked until the memory is unlocked.

Note: Task_delete() should be called with extreme care. As mentioned above, the scope of Task_delete() is limited to freeing the Task object itself, freeing the task's stack memory if it was allocated at create time, and removing the task from any SYS/BIOS-internal state structures.

SYS/BIOS does not keep track of any resources the task may have acquired or used during its lifetime.

It is the application's responsibility to guarantee the integrity of a task's partnerships prior to deleting that task.

For example, if a task has obtained exclusive access to a resource, deleting that task will make the resource forever unavailable.

Task_delete() sets the referenced task handle to NULL. Any subsequent call to a Task instance API using that null task handle will behave unpredictably and will usually result in an application crash.

Assuming a task completely cleans up after itself prior to calling Task_exit() (or falling through the the bottom of the task function), it is then safest to use Task_delete() only when a task is in the 'Task_Mode_TERMINATED' state.

Delete hooks: You can specify application-wide Delete hook functions that run whenever a task is deleted. See the discussion of Hook Functions below for details.

Task_delete() constraints:

The task cannot be the currently executing task (Task_self()).
Task_delete cannot be called from a Swi or Hwi.
No check is performed to prevent Task_delete from being used on a statically-created object. If a program attempts to delete a task object that was created statically, the Memory_free() call will result in an assertion failure in its corresponding Heap manager, causing the application to exit.

Stack Alignment

Stack size parameters for both static and dynamic tasks are rounded up to the nearest integer multiple of a target-specific alignment requirement.

In the case of Task's which are created with a user-provided stack, both the base address and the stackSize are aligned. The base address is increased to the nearest aligned address. The stack size is decreased accordingly and then rounded down to the nearest integer multiple of the target-specific required alignment.

Hook Functions

Sets of hook functions can be specified for the Task module. Each set can contain these hook functions:

Register: A function called before any statically created tasks are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
Create: A function that is called when a task is created. This includes tasks that are created statically and those created dynamically using Task_create or Task_construct. For statically created tasks, create hook is called before main() and before interrupts are enabled. For dynamically created or constructed tasks, create hook is called in the same context the task is created or constructed in i.e. if a task is created in main(), the create hook is called in main context and if the task is created within another task, it is called in task context. The create hook is called outside of a Task_disable/enable block and before the task has been added to the ready list.
Ready: A function that is called when a task becomes ready to run. The ready hook is called in the context of the thread unblocking a task and therefore it can be called in Hwi, Swi or Task context. If a Swi or Hwi posts a semaphore that unblocks a task, the ready hook would be called in the Swi or Hwi's context. The ready hook is called from within a Task_disable/enable block with interrupts enabled.
Switch: A function that is called just before a task switch occurs. The 'prev' and 'next' task handles are passed to the switch hook. 'prev' is set to NULL for the initial task switch that occurs during SYS/BIOS startup. The switch hook is called from within a Task_disable/enable block with interrupts enabled, in the context of the task being switched from (ie: the prev task).
Exit: A function that is called when a task exits using Task_exit. It is called in the exiting task's context. The exit hook is passed the handle of the exiting task. The exit hook is called outside of a Task_disable/enable block and before the task has been removed from the kernel lists.
Delete: A function that is called when any task is deleted at run-time with Task_delete. The delete hook is called in idle task context if Task_deleteTerminatedTasks is set to true. Otherwise, it is called in the context of the task that is deleting another task. The delete hook is called outside of a Task_disable/enable block.

Hook functions can only be configured statically.

If you define more than one set of hook functions, all the functions of a particular type will be run when a Task triggers that type of hook.

To add a Task hook or set of Task hooks, the following syntax is used in the app.syscfg file:

const Task = scripting.addModule("/ti/sysbios/knl/Task");
Task.taskHooks.create(1);
Task.taskHooks[0].registerFxn = "myRegisterFxn";
Task.taskHooks[0].createFxn   = "myCreateFxn";
Task.taskHooks[0].readyFxn    = "myReadyFxn";
Task.taskHooks[0].switchFxn   = "mySwitchFxn";
Task.taskHooks[0].exitFxn     = "myExitFxn";
Task.taskHooks[0].deleteFxn   = "myDeleteFxn";

Leaving a subset of the hook functions undefined is ok.

Warning: Configuring ANY Task hook function will have the side effect of allowing up to two interrupt contexts beings saved on a task stack. Be careful to size your task stacks accordingly.

Register Function

The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Task_setHookContext and Task_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Task_setHookContext or Task_getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.

void myRegisterFxn(int id);

Create and Delete Functions

The create and delete functions are called whenever a Task is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).

void myCreateFxn(Task_Handle task, Error_Block *eb);

void myDeleteFxn(Task_Handle task);

Switch Function

If a switch function is specified, it is invoked just before the new task is switched to. The switch function is called with interrupts enabled.

This function can be used to save/restore additional task context (for example, external hardware registers), to check for task stack overflow, to monitor the time used by each task, etc.

void mySwitchFxn(Task_Handle prev, Task_Handle next);

To properly handle the switch to the first task your switchFxn should check for "prev == NULL" before using prev:

void mySwitchFxn(Task_Handle prev, Task_Handle next)
{
    if (prev != NULL) {
        ...
    }
    ...
}

Ready Function

If a ready function is specified, it is invoked whenever a task is made ready to run. The ready function is called with interrupts enabled (unless called at boot time or from main()).

void myReadyFxn(Task_Handle task);

Exit Function

If an exit function is specified, it is invoked when a task exits (via call to Task_exit() or when a task returns from its' main function). The Exit Function is called with interrupts enabled.

void myExitFxn(Task_Handle task);

Calling Context

Function	Hwi	Swi	Task	Main	Startup
create	N	N	Y	Y	N
disable	Y	Y	Y	Y	N
exit	N	N	Y	N	N
getIdleTask	Y	Y	Y	Y	N
Params_init	Y	Y	Y	Y	Y
restore	Y	Y	Y	Y	N
self	Y	Y	Y	Y	N
sleep	N	N	Y	N	N
yield	Y	Y	Y	N	N
construct	N	N	Y	Y	N
delete	N	N	Y	Y	N
destruct	N	N	Y	Y	N
getEnv	Y	Y	Y	Y	N
getHookContext	Y	Y	Y	Y	N
getMode	Y	Y	Y	Y	N
getPri	Y	Y	Y	Y	N
getFunc	Y	Y	Y	Y	N
setEnv	Y	Y	Y	Y	N
setHookContext	Y	Y	Y	Y	N
setPri	Y	Y	Y	N	N
stat	Y	Y	Y	Y	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. after Task_init() has been called). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. before Task_init() has been called).

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Clock.h>
#include <ti/sysbios/runtime/Error.h>
#include <ti/sysbios/runtime/IHeap.h>

Include dependency graph for Task.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Task_Stat

struct	Task_HookSet

struct	Task_Hook

struct	Task_Params

Macros
#define	Task_A_badPriority "invalid priority"
	Asserted in Task_create. More...

#define	Task_A_badTaskState "cannot delete a task in RUNNING state"
	Asserted in Task_delete. More...

#define	Task_A_badThreadType "cannot create/delete a task from a Hwi or Swi thread"
	Asserted in Task_create and Task_delete. More...

#define	Task_A_badTimeout "cannot sleep forever"
	Asserted in Task_sleep. More...

#define	Task_A_noPendElem "not enough info to delete BLOCKED task"
	Asserted in Task_delete. More...

#define	Task_A_sleepTaskDisabled "cannot call Task_sleep when the scheduler is disabled"
	Asserted in Task_sleep. More...

#define	Task_A_taskDisabled "cannot create a task when tasking is disabled"
	Asserted in Task_create. More...

#define	Task_E_stackOverflow "task 0x%x stack overflow"
	Error raised when a stack overflow (or corruption) is detected. More...

#define	Task_E_spOutOfBounds "task 0x%x stack error, SP = 0x%x"
	Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack. More...

#define	Task_E_deleteNotAllowed "delete not allowed task 0x%x"
	Task_delete error. More...

Typedefs
typedef enum Task_Mode	Task_Mode
	Task execution modes. More...

typedef void(*	Task_FuncPtr) (uintptr_t arg1, uintptr_t arg2)
	Task function type definition. More...

typedef struct Task_Struct	Task_Struct

typedef struct Task_Struct	Task_Object

typedef struct Task_Struct *	Task_Handle

typedef struct Task_Struct *	Task_Instance

typedef struct Task_Stat	Task_Stat
	Task Status Buffer. More...

typedef struct Task_HookSet	Task_HookSet
	Task hook set type definition. More...

typedef struct Task_Params	Task_Params

Enumerations
enum	Task_Mode { Task_Mode_RUNNING, Task_Mode_READY, Task_Mode_BLOCKED, Task_Mode_TERMINATED, Task_Mode_INACTIVE }
	Task execution modes. More...

Functions
Task_Handle	Task_create (Task_FuncPtr fxn, const Task_Params prms, Error_Block eb)
	Create a Task. More...

Task_Handle	Task_construct (Task_Struct obj, Task_FuncPtr fxn, const Task_Params prms, Error_Block *eb)
	Construct a task. More...

void	Task_delete (Task_Handle *task)
	Delete a task. More...

void	Task_destruct (Task_Struct *obj)
	Destruct a task. More...

unsigned int	Task_disable (void)
	Disable the task scheduler. More...

void	Task_restore (unsigned int key)
	Restore Task scheduling state. More...

Task_Handle	Task_self (void)
	Returns a handle to the currently executing Task object. More...

void	Task_checkStacks (Task_Handle oldTask, Task_Handle newTask)
	Check for stack overflow. More...

void	Task_exit (void)
	Terminate execution of the current task. More...

void	Task_sleep (uint32_t nticks)
	Delay execution of the current task. More...

void	Task_yield (void)
	Yield processor to equal priority task. More...

Task_Handle	Task_getIdleTask (void)
	returns a handle to the idle task object (for core 0) More...

void *	Task_getEnv (Task_Handle task)
	Get task environment pointer. More...

Task_FuncPtr	Task_getFunc (Task_Handle task, uintptr_t arg0, uintptr_t arg1)
	Get Task function and arguments. More...

void *	Task_getHookContext (Task_Handle task, int id)
	Get hook set's context for a task. More...

char *	Task_getName (Task_Handle task)
	Get task name. More...

int	Task_getPri (Task_Handle task)
	Get task priority. More...

void	Task_setEnv (Task_Handle task, void *env)
	Set task environment. More...

void	Task_setHookContext (Task_Handle task, int id, void *hookContext)
	Set hook instance's context for a task. More...

int	Task_setPri (Task_Handle task, int newpri)
	Set a task's priority. More...

void	Task_stat (Task_Handle task, Task_Stat *statbuf)
	Retrieve the status of a task. More...

Task_Mode	Task_getMode (Task_Handle task)
	Retrieve the Task_Mode of a task. More...

void	Task_block (Task_Handle task)
	Block a task. More...

void	Task_Params_init (Task_Params *prms)
	Initialize the Task_Params structure with default values. More...

Task_Handle	Task_Object_first (void)
	return handle of the first task on task list More...

Task_Handle	Task_Object_next (Task_Handle task)
	return handle of the next task on task list More...

Variables
const unsigned int	Task_numPriorities
	Number of Task priorities supported. Default is 16. More...

const size_t	Task_defaultStackSize
	Default stack size (in MAUs) used for all tasks. More...

const Task_AllBlockedFuncPtr	Task_allBlockedFunc
	Function to call while all tasks are blocked. More...

const bool	Task_initStackFlag
	Initialize stack with known value for stack checking at runtime (see Task_checkStackFlag). More...

const bool	Task_checkStackFlag
	Check 'from' and 'to' task stacks before task context switch. More...

Macro Definition Documentation

§ Task_A_badPriority

#define Task_A_badPriority "invalid priority"

Asserted in Task_create.

§ Task_A_badTaskState

#define Task_A_badTaskState "cannot delete a task in RUNNING state"

Asserted in Task_delete.

§ Task_A_badThreadType

#define Task_A_badThreadType "cannot create/delete a task from a Hwi or Swi thread"

Asserted in Task_create and Task_delete.

§ Task_A_badTimeout

#define Task_A_badTimeout "cannot sleep forever"

Asserted in Task_sleep.

§ Task_A_noPendElem

#define Task_A_noPendElem "not enough info to delete BLOCKED task"

Asserted in Task_delete.

§ Task_A_sleepTaskDisabled

#define Task_A_sleepTaskDisabled "cannot call Task_sleep when the scheduler is disabled"

Asserted in Task_sleep.

§ Task_A_taskDisabled

#define Task_A_taskDisabled "cannot create a task when tasking is disabled"

Asserted in Task_create.

§ Task_E_stackOverflow

#define Task_E_stackOverflow "task 0x%x stack overflow"

Error raised when a stack overflow (or corruption) is detected.

This error is raised by kernel's stack checking function. This function checks the stacks before every task switch to make sure that reserved word at top of stack has not been modified.

The stack checking logic is enabled by the Task_initStackFlag and Task_checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stacks.

§ Task_E_spOutOfBounds

#define Task_E_spOutOfBounds "task 0x%x stack error, SP = 0x%x"

Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack.

This error is raised by kernel's stack checking function. This function checks the SPs before every task switch to make sure they point within the task's stack.

The stack checking logic is enabled by the Task_initStackFlag and Task_checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stack pointers.

§ Task_E_deleteNotAllowed

#define Task_E_deleteNotAllowed "delete not allowed task 0x%x"

Task_delete error.

This error raised when a Task_delete is called when the Task.deleteTerminated configuration parameter is set to 'true' and the task is in the terminated state. When Task.deleteTerminated is 'true', the idle task will delete terminated tasks.

Typedef Documentation

§ Task_Mode

typedef enum Task_Mode Task_Mode

Task execution modes.

These enumerations are the range of modes or states that a task can be in. A task's current mode can be gotten using Task_stat.

§ Task_FuncPtr

typedef void(* Task_FuncPtr) (uintptr_t arg1, uintptr_t arg2)

Task function type definition.

§ Task_Struct

typedef struct Task_Struct Task_Struct

§ Task_Object

typedef struct Task_Struct Task_Object

§ Task_Handle

typedef struct Task_Struct* Task_Handle

§ Task_Instance

typedef struct Task_Struct* Task_Instance

§ Task_Stat

typedef struct Task_Stat Task_Stat

Task Status Buffer.

Passed to and filled in by Task_stat;

§ Task_HookSet

typedef struct Task_HookSet Task_HookSet

Task hook set type definition.

Sets of hook functions can be specified for the Task module. See Hook Functions for details.

§ Task_Params

typedef struct Task_Params Task_Params

Enumeration Type Documentation

§ Task_Mode

enum Task_Mode

Task execution modes.

These enumerations are the range of modes or states that a task can be in. A task's current mode can be gotten using Task_stat.

Enumerator
Task_Mode_RUNNING
Task_Mode_READY
Task_Mode_BLOCKED
Task_Mode_TERMINATED
Task_Mode_INACTIVE	Task is on inactive task list.

Function Documentation

§ Task_create()

Task_Handle Task_create	(	Task_FuncPtr	fxn,
		const Task_Params *	prms,
		Error_Block *	eb
	)

Create a Task.

Task_create creates a new task object. If successful, Task_create returns the handle of the new task object. If unsuccessful, Task_create returns NULL unless it aborts.

The fxn parameter uses the Task_FuncPtr type to pass a pointer to the function the Task object should run. For example, if myFxn is a function in your program, your C code can create a Task object to call that function as follows:

Task_Params taskParams;
// Create task with priority 15
Task_Params_init(&taskParams);
taskParams.stackSize = 512;
taskParams.priority = 15;
Task_create((Task_FuncPtr)myFxn, &taskParams, &eb);

The following statements statically create a task in the configuration file:

var params = new Task.Params;
params.name = "tsk0";
params.arg0 = 1;
params.arg1 = 2;
params.priority = 1;
Task.create('&tsk0_func', params);

If NULL is passed instead of a pointer to an actual Task_Params struct, a default set of parameters is used. The "eb" is an error block that you can use to handle errors that may occur during Task object creation.

The newly created task is placed in Task_Mode_READY mode, and is scheduled to begin concurrent execution of the following function call:

(*fxn)(arg1, arg2);

As a result of being made ready to run, the task runs any application-wide Ready functions that have been specified.

Task_exit is automatically called if and when the task returns from fxn.

Create Hook Functions

You can specify application-wide Create hook functions in your config file that run whenever a task is created. This includes tasks that are created statically and those created dynamically using Task_create.

For Task objects created statically, Create functions are called during the Task module initialization phase of the program startup process prior to main().

For Task objects created dynamically, Create functions are called after the task handle has been initialized but before the task has been placed on its ready queue.

Any SYS/BIOS function can be called from Create functions. SYS/BIOS passes the task handle of the task being created to each of the Create functions.

All Create function declarations should be similar to this:

void myCreateFxn(Task_Handle task);

Precondition

The fxn parameter and the name attribute cannot be NULL.
The priority attribute must be less than or equal to (Task_numPriorities - 1) and greater than or equal to one (1) (priority 0 is owned by the Idle task).
The priority can be set to -1 for tasks that will not execute until another task changes the priority to a positive value.
The stackHeap attribute must identify a valid memory Heap.

Parameters

fxn	Task function
prms	optional create parameters (NULL for defaults)
eb	error block

Return values

Task	handle (NULL on failure)

§ Task_construct()

Task_Handle Task_construct	(	Task_Struct *	obj,
		Task_FuncPtr	fxn,
		const Task_Params *	prms,
		Error_Block *	eb
	)

Construct a task.

Task_construct is equivalent to Task_create except that the Task_Struct is pre-allocated. See Task_create() for a description of this API.

Parameters

obj	pointer to a Task object
fxn	Task function
prms	optional create parameters (NULL for defaults)
eb	error block

Return values

Task	handle (NULL on failure)

§ Task_delete()

void Task_delete ( Task_Handle * task )

Delete a task.

Task_delete deletes a Task object. Note that Task_delete takes a pointer to a Task_Handle which enables Task_delete to set the Task handle to NULL.

Parameters

task	pointer to Task handle

§ Task_destruct()

void Task_destruct ( Task_Struct * obj )

Destruct a task.

Task_destruct destructs a Task object.

Parameters

obj	pointer to Task object

§ Task_disable()

unsigned int Task_disable ( void )

Disable the task scheduler.

Task_disable and Task_restore control Task scheduling. Task_disable disables all other Tasks from running until Task_restore is called. Hardware and Software interrupts can still run.

Task_disable and Task_restore allow you to ensure that statements that must be performed together during critical processing are not preempted by other Tasks.

The value of the key returned is opaque to applications and is meant to be passed to Task_restore().

In the following example, the critical section is not preempted by any Tasks.

key = Task_disable();
    `critical section`
Task_restore(key);

You can also use Task_disable and Task_restore to create several Tasks and allow them to be invoked in priority order.

Task_disable calls can be nested.

Precondition: Do not call any function that can cause the current task to block within a Task_disable/Task_restore block. For example, Semaphore_pend (if timeout is non-zero), Task_sleep, Task_yield, and Memory_alloc can all cause blocking.

Return values

key	for use with Task_restore

§ Task_restore()

void Task_restore ( unsigned int key )

Restore Task scheduling state.

Task_disable and Task_restore control Task scheduling Task_disable disables all other Tasks from running until Task_restore is called. Hardware and Software interrupts can still run.

Task_disable and Task_restore allow you to ensure that statements that must be performed together during critical processing are not preempted.

In the following example, the critical section is not preempted by any Tasks.

key = Task_disable();
    `critical section`
Task_restore(key);

You can also use Task_disable and Task_restore to create several Tasks and allow them to be performed in priority order.

Task_disable calls can be nested.

Task_restore returns with interrupts enabled if the key unlocks the scheduler

Precondition: Do not call any function that can cause the current task to block within a Task_disable/Task_restore block. For example, Semaphore_pend (if timeout is non-zero), Task_sleep, Task_yield, and Memory_alloc can all cause blocking.

Task_restore internally calls Hwi_enable() if the key passed to it results in the unlocking of the Task scheduler (ie if this is root Task_disable/Task_restore pair).

Parameters

key	key to restore previous Task scheduler state

§ Task_self()

Task_Handle Task_self ( void )

Returns a handle to the currently executing Task object.

Task_self returns the object handle for the currently executing task. This function is useful when inspecting the object or when the current task changes its own priority through Task_setPri.

No task switch occurs when calling Task_self.

Task_self will return NULL until Tasking is initiated at the end of BIOS_start().

Return values

address of currently executing task object

§ Task_checkStacks()

void Task_checkStacks	(	Task_Handle	oldTask,
		Task_Handle	newTask
	)

Check for stack overflow.

This function is usually called by the Task_HookSet switchFxn to make sure task stacks are valid before performing the context switch.

If a stack overflow is detected on either the oldTask or the newTask, a Task_E_stackOverflow error is raised and the system exited.

In order to work properly, Task_checkStacks requires that the Task_initStackFlag set to true, which it is by default.

You can call Task_checkStacks directly from your application. For example, you can check the current task's stack integrity at any time with a call like the following:

Task_checkStacks(Task_self(), Task_self());

Parameters

oldTask	leaving Task Object void *
newTask	entering Task Object void *

§ Task_exit()

void Task_exit ( void )

Terminate execution of the current task.

Task_exit terminates execution of the current task, changing its mode from Task_Mode_RUNNING to Task_Mode_TERMINATED. If all tasks have been terminated, or if all remaining tasks have their vitalTaskFlag attribute set to false, then SYS/BIOS terminates the program as a whole by calling the function System_exit with a status code of 0.

Task_exit is automatically called whenever a task returns from its top-level function.

Exit Hooks (see exitFxn in Task_HookSet) can be used to provide functions that run whenever a task is terminated. The exitFxn Hooks are called before the task has been blocked and marked Task_Mode_TERMINATED. See Hook Functions for more information.

Any SYS/BIOS function can be called from an Exit Hook function.

Calling Task_self within an Exit function returns the task being exited. Your Exit function declaration should be similar to the following:

void myExitFxn(void);

A task switch occurs when calling Task_exit unless the program as a whole is terminated

Precondition: Task_exit cannot be called from a Swi or Hwi.

Task_exit cannot be called from the program's main() function.

§ Task_sleep()

void Task_sleep ( uint32_t nticks )

Delay execution of the current task.

Task_sleep changes the current task's mode from Task_Mode_RUNNING to Task_Mode_BLOCKED, and delays its execution for nticks increments of the "system clock". The actual time delayed can be up to 1 system clock tick less than nticks due to granularity in system timekeeping and the time elapsed per tick is determined by Clock_tickPeriod.

After the specified period of time has elapsed, the task reverts to the Task_Mode_READY mode and is scheduled for execution.

A task switch always occurs when calling Task_sleep if nticks > 0.

Precondition: Task_sleep cannot be called from a Swi or Hwi, or within a Task_disable / Task_restore block.

Task_sleep cannot be called from the program's main() function.

Task_sleep should not be called from within an Idle function. Doing so prevents analysis tools from gathering run-time information.

nticks cannot be BIOS_WAIT_FOREVER.

Parameters

nticks number of system clock ticks to sleep

§ Task_yield()

void Task_yield ( void )

Yield processor to equal priority task.

Task_yield yields the processor to another task of equal priority.

A task switch occurs when you call Task_yield if there is an equal priority task ready to run.

Tasks of higher priority preempt the currently running task without the need for a call to Task_yield. If only lower-priority tasks are ready to run when you call Task_yield, the current task continues to run. Control does not pass to a lower-priority task.

Precondition: When called within an Hwi, the code sequence calling Task_yield must be invoked by the Hwi dispatcher.

Task_yield cannot be called from the program's main() function.

§ Task_getIdleTask()

Task_Handle Task_getIdleTask ( void )

returns a handle to the idle task object (for core 0)

§ Task_getEnv()

void* Task_getEnv ( Task_Handle task )

Get task environment pointer.

Task_getEnv returns the environment pointer of the specified task. The environment pointer references an arbitrary application-defined data structure.

If your program uses multiple hook sets, Task_getHookContext allows you to get environment pointers you have set for a particular hook set and Task object combination.

Parameters

task	Task handle

Return values

task	environment pointer

§ Task_getFunc()

Task_FuncPtr Task_getFunc	(	Task_Handle	task,
		uintptr_t *	arg0,
		uintptr_t *	arg1
	)

Get Task function and arguments.

If either arg0 or arg1 is NULL, then the corresponding argument is not returned.

Parameters

arg0	pointer for returning Task's first function argument
arg1	pointer for returning Task's second function argument
task	Task handle

Return values

Task function

§ Task_getHookContext()

void* Task_getHookContext	(	Task_Handle	task,
		int	id
	)

Get hook set's context for a task.

For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.

void * pEnv;
Task_Handle myTask;
int myHookSetId1;
pEnv = Task_getHookContext(task, myHookSetId1);
System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
              (ULong)pEnv, (ULong)Timestamp_get32());
Task_setHookContext(task, myHookSetId1, (void *)0xc0de1);

See Hook Functions for more details.

Parameters

task	Task handle
id	hook set ID

Return values

hook	set context for task

§ Task_getName()

char* Task_getName ( Task_Handle task )

Get task name.

Task_getName returns the name of the referenced task.

Parameters

task	Task handle

Return values

task name

§ Task_getPri()

int Task_getPri ( Task_Handle task )

Get task priority.

Task_getPri returns the priority of the referenced task.

Parameters

task	Task handle

Return values

task priority

§ Task_setEnv()

void Task_setEnv	(	Task_Handle	task,
		void *	env
	)

Set task environment.

Task_setEnv sets the task environment pointer to env. The environment pointer references an arbitrary application-defined data structure.

If your program uses multiple hook sets, Task_setHookContext allows you to set environment pointers for any hook set and Task object combination.

Parameters

task	Task handle
env	task environment pointer

§ Task_setHookContext()

void Task_setHookContext	(	Task_Handle	task,
		int	id,
		void *	hookContext
	)

Set hook instance's context for a task.

For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.

void * pEnv;
Task_Handle myTask;
int myHookSetId1;
pEnv = Task_getHookContext(task, myHookSetId1);
System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
              (ULong)pEnv, (ULong)Timestamp_get32());
Task_setHookContext(task, myHookSetId1, (void *)0xc0de1);

See Hook Functions for more details.

Parameters

task	Task handle
id	hook set ID
hookContext	value to write to context

§ Task_setPri()

int Task_setPri	(	Task_Handle	task,
		int	newpri
	)

Set a task's priority.

Task_setpri sets the execution priority of task to newpri, and returns that task's old priority value. Raising or lowering a task's priority does not necessarily force preemption and re-scheduling of the caller: tasks in the Task_Mode_BLOCKED mode remain suspended despite a change in priority; and tasks in the Task_Mode_READY mode gain control only if their new priority is greater than that of the currently executing task.

newpri should be set to a value greater than or equal to 1 and less than or equal to (Task_numPriorities - 1). newpri can also be set to -1 which puts the the task into the INACTIVE state and the task will not run until its priority is raised at a later time by another task. Priority 0 is reserved for the idle task. If newpri equals (Task_numPriorities - 1), execution of the task effectively locks out all other program activity, except for the handling of interrupts.

The current task can change its own priority (and possibly preempt its execution) by passing the output of Task_self as the value of the task parameter.

A context switch occurs when calling Task_setpri if a currently running task priority is set lower than the priority of another currently ready task, or if another ready task is made to have a higher priority than the currently running task.

Task_setpri can be used for mutual exclusion.

If a task's new priority is different than its previous priority, then its relative placement in its new ready task priority queue can be different than the one it was removed from. This can effect the relative order in which it becomes the running task.

The effected task is placed at the head of its new priority queue if it is the currently running task. Otherwise it is placed at at the end of its new task priority queue.

Precondition: newpri must be a value between 1 and (Task_numPriorities - 1) or -1.

The task cannot be in the Task_Mode_TERMINATED mode.

The new priority should not be zero (0). This priority level is reserved for the Idle task.

Parameters

task	Task handle
newpri	task's new priority

Return values

task's old priority

§ Task_stat()

void Task_stat	(	Task_Handle	task,
		Task_Stat *	statbuf
	)

Retrieve the status of a task.

Task_stat retrieves attribute values and status information about a task.

Status information is returned through statbuf, which references a structure of type Task_Stat.

When a task is preempted by a software or hardware interrupt, the task execution mode returned for that task by Task_stat is still Task_Mode_RUNNING because the task runs when the preemption ends.

The current task can inquire about itself by passing the output of Task_self as the first argument to Task_stat. However, the task stack pointer (sp) in the Task_Stat structure is the value from the previous context switch.

Task_stat has a non-deterministic execution time. As such, it is not recommended to call this API from Swis or Hwis.

Precondition: statbuf cannot be NULL;

Parameters

task	Task handle
statbuf	pointer to task status structure

§ Task_getMode()

Task_Mode Task_getMode ( Task_Handle task )

Retrieve the Task_Mode of a task.

Parameters

task	Task handle

§ Task_block()

void Task_block ( Task_Handle task )

Block a task.

Remove a task from its ready list. The effect of this API is manifest the next time the internal Task scheduler is invoked. This can be done directly by embedding the call within a Task_disable/Task_restore block. Otherwise, the effect will be manifest as a result of processing the next dispatched interrupt, or by posting a Swi, or by falling through the task function.

Precondition: If called from within a Hwi or a Swi, or main(), there is no need to embed the call within a Task_disable/Task_restore block.

Parameters

task	Task handle

§ Task_Params_init()

void Task_Params_init ( Task_Params * prms )

Initialize the Task_Params structure with default values.

Task_Params_init initializes the Task_Params structure with default values. Task_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

§ Task_Object_first()

Task_Handle Task_Object_first ( void )

return handle of the first task on task list

Return the handle of the first task on the create/construct list. NULL if no Tasks have been created or constructed.

Return values

Task handle

§ Task_Object_next()

Task_Handle Task_Object_next ( Task_Handle task )

return handle of the next task on task list

Return the handle of the next task on the create/construct list. NULL if no more Tasks are on the list.

Parameters

task	Task handle

Return values

Task handle

Variable Documentation

§ Task_numPriorities

const unsigned int Task_numPriorities

Number of Task priorities supported. Default is 16.

The maximum number of priorities supported is target specific and depends on the number of bits in a unsigned int data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For C28x devices, the maximum number of priorities is 16.

Task.numPriorities = 16;

§ Task_defaultStackSize

const size_t Task_defaultStackSize

Default stack size (in MAUs) used for all tasks.

Default is provided by the ti/sysbios/family/Settings.js file.

Task.defaultStackSize = 1024;

§ Task_allBlockedFunc

const Task_AllBlockedFuncPtr Task_allBlockedFunc

Function to call while all tasks are blocked.

This function will be called repeatedly while no tasks are ready to run.

Ordinarily (in applications that have tasks ready to run at startup), the function will run in the context of the last task to block.

In an application where there are no tasks ready to run when BIOS_start() is called, the allBlockedFunc function is called within the BIOS_start() thread which runs on the system/ISR stack.

By default, allBlockedFunc is initialized to point to an internal function that simply returns.

By adding the following lines to the config script, the Idle functions will run whenever all tasks are blocked:

Task.enableIdleTask = false;

Task.allBlockedFunc = "ti_sysbios_knl_Idle_run";

See also: Task_enableIdleTask

Precondition: The configured allBlockedFunc is designed to be called repeatedly. It must return in order for the task scheduler to check if all tasks are STILL blocked and if not, run the highest priority task currently ready to run.

The configured allBlockedFunc function is called with interrupts disabled. If your function must run with interrupts enabled, surround the body of your code with Hwi_enable()/Hwi_restore() function calls per the following example:

void yourFunc() {
    unsigned int hwiKey;
    hwiKey = Hwi_enable();
    ...         // your code here
    Hwi_restore(hwiKey);
}

§ Task_initStackFlag

const bool Task_initStackFlag

Initialize stack with known value for stack checking at runtime (see Task_checkStackFlag).

This is also useful for inspection of stack in debugger or core dump utilities. Default is true.

Task.initStackFlag = true/false;

§ Task_checkStackFlag

const bool Task_checkStackFlag

Check 'from' and 'to' task stacks before task context switch.

The check consists of testing the top of stack value against its initial value (see configuration parameter Task.initStackFlag). If it is no longer at this value, the assumption is that the task has overrun its stack. If the test fails, then the Task_E_stackOverflow error is raised.

Default is true.

To enable or disable full stack checking, you should set both this flag and the Hwi.checkStackFlag configuration parameter.

Task.checkStackFlag = true/false;

Note: Enabling stack checking will add some interrupt latency because the checks are made within the Task scheduler while interrupts are disabled.

Detailed Description

Task Stacks

Task Deletion

Stack Alignment

Calling Context

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ Task_A_badPriority

§ Task_A_badTaskState

§ Task_A_badThreadType

§ Task_A_badTimeout

§ Task_A_noPendElem

§ Task_A_sleepTaskDisabled

§ Task_A_taskDisabled

§ Task_E_stackOverflow

§ Task_E_spOutOfBounds

§ Task_E_deleteNotAllowed

Typedef Documentation

§ Task_Mode

§ Task_FuncPtr

§ Task_Struct

§ Task_Object

§ Task_Handle

§ Task_Instance

§ Task_Stat

§ Task_HookSet

§ Task_Params

Enumeration Type Documentation

§ Task_Mode

Function Documentation

§ Task_create()

§ Task_construct()

§ Task_delete()

§ Task_destruct()

§ Task_disable()

§ Task_restore()

§ Task_self()

§ Task_checkStacks()

§ Task_exit()

§ Task_sleep()

§ Task_yield()

§ Task_getIdleTask()

§ Task_getEnv()

§ Task_getFunc()

§ Task_getHookContext()

§ Task_getName()

§ Task_getPri()

§ Task_setEnv()

§ Task_setHookContext()

§ Task_setPri()

§ Task_stat()

§ Task_getMode()

§ Task_block()

§ Task_Params_init()

§ Task_Object_first()

§ Task_Object_next()

Variable Documentation

§ Task_numPriorities

§ Task_defaultStackSize

§ Task_allBlockedFunc

§ Task_initStackFlag

§ Task_checkStackFlag