VxWorks Reference Manual : Libraries
taskLib - task management library
taskSpawn( ) - spawn a task
taskInit( ) - initialize a task with a stack at a specified address
taskActivate( ) - activate a task that has been initialized
exit( ) - exit a task (ANSI)
taskDelete( ) - delete a task
taskDeleteForce( ) - delete a task without restriction
taskSuspend( ) - suspend a task
taskResume( ) - resume a task
taskRestart( ) - restart a task
taskPrioritySet( ) - change the priority of a task
taskPriorityGet( ) - examine the priority of a task
taskLock( ) - disable task rescheduling
taskUnlock( ) - enable task rescheduling
taskSafe( ) - make the calling task safe from deletion
taskUnsafe( ) - make the calling task unsafe from deletion
taskDelay( ) - delay a task from executing
taskIdSelf( ) - get the task ID of a running task
taskIdVerify( ) - verify the existence of a task
taskTcb( ) - get the task control block for a task ID
This library provides the interface to the VxWorks task management facilities. Task control services are provided by the VxWorks kernel, which is comprised of kernelLib, taskLib, semLib, tickLib, msgQLib, and wdLib. Programmatic access to task information and debugging features is provided by taskInfo. Higher-level task information display routines are provided by taskShow.
Tasks are created with the general-purpose routine taskSpawn( ). Task creation consists of the following: allocation of memory for the stack and task control block (WIND_TCB), initialization of the WIND_TCB, and activation of the WIND_TCB. Special needs may require the use of the lower-level routines taskInit( ) and taskActivate( ), which are the underlying primitives of taskSpawn( ).
Tasks in VxWorks execute in the most privileged state of the underlying architecture. In a shared address space, processor privilege offers no protection advantages and actually hinders performance.
There is no limit to the number of tasks created in VxWorks, as long as sufficient memory is available to satisfy allocation requirements.
The routine sp( ) is provided in usrLib as a convenient abbreviation for spawning tasks. It calls taskSpawn( ) with default parameters.
If a task exits its "main" routine, specified during task creation, the kernel implicitly calls exit( ) to delete the task. Tasks can be explicitly deleted with the taskDelete( ) or exit( ) routine.
Task deletion must be handled with extreme care, due to the inherent difficulties of resource reclamation. Deleting a task that owns a critical resource can cripple the system, since the resource may no longer be available. Simply returning a resource to an available state is not a viable solution, since the system can make no assumption as to the state of a particular resource at the time a task is deleted.
The solution to the task deletion problem lies in deletion protection, rather than overly complex deletion facilities. Tasks may be protected from unexpected deletion using taskSafe( ) and taskUnsafe( ). While a task is safe from deletion, deleters will block until it is safe to proceed. Also, a task can protect itself from deletion by taking a mutual-exclusion semaphore created with the SEM_DELETE_SAFE option, which enables an implicit taskSafe( ) with each semTake( ), and a taskUnsafe( ) with each semGive( ) (see semMLib for more information). Many VxWorks system resources are protected in this manner, and application designers may wish to consider this facility where dynamic task deletion is a possibility.
The sigLib facility may also be used to allow a task to execute clean-up code before actually expiring.
Tasks are manipulated by means of an ID that is returned when a task is created. VxWorks uses the convention that specifying a task ID of NULL in a task control function signifies the calling task.
The following routines control task state: taskResume( ), taskSuspend( ), taskDelay( ), taskRestart( ), taskPrioritySet( ), and taskRegsSet( ).
VxWorks schedules tasks on the basis of priority. Tasks may have priorities ranging from 0, the highest priority, to 255, the lowest priority. The priority of a task in VxWorks is dynamic, and an existing task's priority can be changed using taskPrioritySet( ).
taskLib.h
taskLib, taskInfo, taskShow, taskHookLib, taskVarLib, semLib, semMLib, kernelLib, VxWorks Programmer's Guide: Basic OS
taskSpawn( ) - spawn a task
int taskSpawn ( char * name, /* name of new task (stored at pStackBase) */ int priority, /* priority of new task */ int options, /* task option word */ int stackSize, /* size (bytes) of stack needed plus name */ FUNCPTR entryPt, /* entry point of new task */ int arg1, /* 1st of 10 req'd task args to pass to func */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9, int arg10 )
This routine creates and activates a new task with a specified priority and options and returns a system-assigned ID. See taskInit( ) and taskActivate( ) for the building blocks of this routine.
A task may be assigned a name as a debugging aid. This name will appear in displays generated by various system information facilities such as i( ). The name may be of arbitrary length and content, but the current VxWorks convention is to limit task names to ten characters and prefix them with a "t". If name is specified as NULL, an ASCII name will be assigned to the task of the form "tn" where n is an integer which increments as new tasks are spawned.
The only resource allocated to a spawned task is a stack of a specified size stackSize, which is allocated from the system memory partition. Stack size should be an even integer. A task control block (TCB) is carved from the stack, as well as any memory required by the task name. The remaining memory is the task's stack and every byte is filled with the value 0xEE for the checkStack( ) facility. See the manual entry for checkStack( ) for stack-size checking aids.
The entry address entryPt is the address of the "main" routine of the task. The routine will be called once the C environment has been set up. The specified routine will be called with the ten given arguments. Should the specified main routine return, a call to exit( ) will automatically be made.
Note that ten (and only ten) arguments must be passed for the spawned function.
Bits in the options argument may be set to run with the following modes:
- VX_FP_TASK (0x0008)
- execute with floating-point coprocessor support.
- VX_PRIVATE_ENV (0x0080)
- include private environment support (see envLib).
- VX_NO_STACK_FILL (0x0100)
- do not fill the stack for use by checkStack( ).
- VX_UNBREAKABLE (0x0002)
- do not allow breakpoint debugging.
See the definitions in taskLib.h.
The task ID, or ERROR if memory is insufficient or the task cannot be created.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,
S_smObjLib_NOT_INITIALIZED, S_memLib_NOT_ENOUGH_MEMORY,
S_memLib_BLOCK_ERROR
taskLib, taskInit( ), taskActivate( ), sp( ), VxWorks Programmer's Guide: Basic OS
VARARGS5
taskInit( ) - initialize a task with a stack at a specified address
STATUS taskInit ( WIND_TCB * pTcb, /* address of new task's TCB */ char * name, /* name of new task (stored at pStackBase) */ int priority, /* priority of new task */ int options, /* task option word */ char * pStackBase, /* base of new task's stack */ int stackSize, /* size (bytes) of stack needed */ FUNCPTR entryPt, /* entry point of new task */ int arg1, /* first of ten task args to pass to func */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9, int arg10 )
This routine initializes user-specified regions of memory for a task stack and control block instead of allocating them from memory as taskSpawn( ) does. This routine will utilize the specified pointers to the WIND_TCB and stack as the components of the task. This allows, for example, the initialization of a static WIND_TCB variable. It also allows for special stack positioning as a debugging aid.
As in taskSpawn( ), a task may be given a name. While taskSpawn( ) automatically names unnamed tasks, taskInit( ) permits the existence of tasks without names. The task ID required by other task routines is simply the address pTcb, cast to an integer.
Note that the task stack may grow up or down from pStackBase, depending on the target architecture.
Other arguments are the same as in taskSpawn( ). Unlike taskSpawn( ), taskInit( ) does not activate the task. This must be done by calling taskActivate( ) after calling taskInit( ).
Normally, tasks should be started using taskSpawn( ) rather than taskInit( ), except when additional control is required for task memory allocation or a separate task activation is desired.
OK, or ERROR if the task cannot be initialized.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR
taskLib, taskActivate( ), taskSpawn( )
VARARGS7
taskActivate( ) - activate a task that has been initialized
STATUS taskActivate ( int tid /* task ID of task to activate */ )
This routine activates tasks created by taskInit( ). Without activation, a task is ineligible for CPU allocation by the scheduler.
The tid (task ID) argument is simply the address of the WIND_TCB for the task (the taskInit( ) pTcb argument), cast to an integer:
tid = (int) pTcb;The taskSpawn( ) routine is built from taskActivate( ) and taskInit( ). Tasks created by taskSpawn( ) do not require explicit task activation.
OK, or ERROR if the task cannot be activated.
exit( ) - exit a task (ANSI)
void exit ( int code /* code stored in TCB for delete hooks */ )
This routine is called by a task to cease to exist as a task. It is called implicitly when the "main" routine of a spawned task is exited. The code parameter will be stored in the WIND_TCB for possible use by the delete hooks, or post-mortem debugging.
N/A
taskLib, taskDelete( ), American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdlib.h), VxWorks Programmer's Guide: Basic OS
taskDelete( ) - delete a task
STATUS taskDelete ( int tid /* task ID of task to delete */ )
This routine causes a specified task to cease to exist and deallocates the stack and WIND_TCB memory resources. Upon deletion, all routines specified by taskDeleteHookAdd( ) will be called in the context of the deleting task. This routine is the companion routine to taskSpawn( ).
OK, or ERROR if the task cannot be deleted.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_DELETED
S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_ID_ERROR
taskLib, excLib, taskDeleteHookAdd( ), taskSpawn( ), VxWorks Programmer's Guide: Basic OS
taskDeleteForce( ) - delete a task without restriction
STATUS taskDeleteForce ( int tid /* task ID of task to delete */ )
This routine deletes a task even if the task is protected from deletion. It is similar to taskDelete( ). Upon deletion, all routines specified by taskDeleteHookAdd( ) will be called in the context of the deleting task.
This routine is intended as a debugging aid, and is generally inappropriate for applications. Disregarding a task's deletion protection could leave the the system in an unstable state or lead to system deadlock.
The system does not protect against simultaneous taskDeleteForce( ) calls. Such a situation could leave the system in an unstable state.
OK, or ERROR if the task cannot be deleted.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_DELETED,
S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_ID_ERROR
taskLib, taskDeleteHookAdd( ), taskDelete( )
taskSuspend( ) - suspend a task
STATUS taskSuspend ( int tid /* task ID of task to suspend */ )
This routine suspends a specified task. A task ID of zero results in the suspension of the calling task. Suspension is additive, thus tasks can be delayed and suspended, or pended and suspended. Suspended, delayed tasks whose delays expire remain suspended. Likewise, suspended, pended tasks that unblock remain suspended only.
Care should be taken with asynchronous use of this facility. The specified task is suspended regardless of its current state. The task could, for instance, have mutual exclusion to some system resource, such as the network * or system memory partition. If suspended during such a time, the facilities engaged are unavailable, and the situation often ends in deadlock.
This routine is the basis of the debugging and exception handling packages. However, as a synchronization mechanism, this facility should be rejected in favor of the more general semaphore facility.
OK, or ERROR if the task cannot be suspended.
S_objLib_OBJ_ID_ERROR
taskResume( ) - resume a task
STATUS taskResume ( int tid /* task ID of task to resume */ )
This routine resumes a specified task. Suspension is cleared, and the task operates in the remaining state.
OK, or ERROR if the task cannot be resumed.
S_objLib_OBJ_ID_ERROR
taskRestart( ) - restart a task
STATUS taskRestart ( int tid /* task ID of task to restart */ )
This routine "restarts" a task. The task is first terminated, and then reinitialized with the same ID, priority, options, original entry point, stack size, and parameters it had when it was terminated. Self-restarting of a calling task is performed by the exception task. The shell utilizes this routine to restart itself when aborted.
If the task has modified any of its start-up parameters, the restarted task will start with the changed values.
OK, or ERROR if the task ID is invalid or the task could not be restarted.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_DELETED,
S_objLib_OBJ_UNAVAILABLE, S_objLib_OBJ_ID_ERROR,
S_smObjLib_NOT_INITIALIZED, S_memLib_NOT_ENOUGH_MEMORY,
S_memLib_BLOCK_ERROR
taskPrioritySet( ) - change the priority of a task
STATUS taskPrioritySet ( int tid, /* task ID */ int newPriority /* new priority */ )
This routine changes a task's priority to a specified priority. Priorities range from 0, the highest priority, to 255, the lowest priority.
OK, or ERROR if the task ID is invalid.
S_taskLib_ILLEGAL_PRIORITY, S_objLib_OBJ_ID_ERROR
taskPriorityGet( ) - examine the priority of a task
STATUS taskPriorityGet ( int tid, /* task ID */ int * pPriority /* return priority here */ )
This routine determines the current priority of a specified task. The current priority is copied to the integer pointed to by pPriority.
OK, or ERROR if the task ID is invalid.
S_objLib_OBJ_ID_ERROR
taskLock( ) - disable task rescheduling
STATUS taskLock (void)
This routine disables task context switching. The task that calls this routine will be the only task that is allowed to execute, unless the task explicitly gives up the CPU by making itself no longer ready. Typically this call is paired with taskUnlock( ); together they surround a critical section of code. These preemption locks are implemented with a counting variable that allows nested preemption locks. Preemption will not be unlocked until taskUnlock( ) has been called as many times as taskLock( ).
This routine does not lock out interrupts; use intLock( ) to lock out interrupts.
A taskLock( ) is preferable to intLock( ) as a means of mutual exclusion, because interrupt lock-outs add interrupt latency to the system.
A semTake( ) is preferable to taskLock( ) as a means of mutual exclusion, because preemption lock-outs add preemptive latency to the system.
The taskLock( ) routine is not callable from interrupt service routines.
OK or ERROR.
S_objLib_OBJ_ID_ERROR, S_intLib_NOT_ISR_CALLABLE
taskLib, taskUnlock( ), intLock( ), taskSafe( ), semTake( )
taskUnlock( ) - enable task rescheduling
STATUS taskUnlock (void)
This routine decrements the preemption lock count. Typically this call is paired with taskLock( ) and concludes a critical section of code. Preemption will not be unlocked until taskUnlock( ) has been called as many times as taskLock( ). When the lock count is decremented to zero, any tasks that were eligible to preempt the current task will execute.
The taskUnlock( ) routine is not callable from interrupt service routines.
OK or ERROR.
S_intLib_NOT_ISR_CALLABLE
taskSafe( ) - make the calling task safe from deletion
STATUS taskSafe (void)
This routine protects the calling task from deletion. Tasks that attempt to delete a protected task will block until the task is made unsafe, using taskUnsafe( ). When a task becomes unsafe, the deleter will be unblocked and allowed to delete the task.
The taskSafe( ) primitive utilizes a count to keep track of nested calls for task protection. When nesting occurs, the task becomes unsafe only after the outermost taskUnsafe( ) is executed.
OK.
taskLib, taskUnsafe( ), VxWorks Programmer's Guide: Basic OS
taskUnsafe( ) - make the calling task unsafe from deletion
STATUS taskUnsafe (void)
This routine removes the calling task's protection from deletion. Tasks that attempt to delete a protected task will block until the task is unsafe. When a task becomes unsafe, the deleter will be unblocked and allowed to delete the task.
The taskUnsafe( ) primitive utilizes a count to keep track of nested calls for task protection. When nesting occurs, the task becomes unsafe only after the outermost taskUnsafe( ) is executed.
OK.
taskLib, taskSafe( ), VxWorks Programmer's Guide: Basic OS
taskDelay( ) - delay a task from executing
STATUS taskDelay ( int ticks /* number of ticks to delay task */ )
This routine causes the calling task to relinquish the CPU for the duration specified (in ticks). This is commonly referred to as manual rescheduling, but it is also useful when waiting for some external condition that does not have an interrupt associated with it.
If the calling task receives a signal that is not being blocked or ignored, taskDelay( ) returns ERROR and sets errno to EINTR after the signal handler is run.
OK, or ERROR if called from interrupt level or if the calling task receives a signal that is not blocked or ignored.
S_intLib_NOT_ISR_CALLABLE, EINTR
taskIdSelf( ) - get the task ID of a running task
int taskIdSelf (void)
This routine gets the task ID of the calling task. The task ID will be invalid if called at interrupt level.
The task ID of the calling task.
taskIdVerify( ) - verify the existence of a task
STATUS taskIdVerify ( int tid /* task ID */ )
This routine verifies the existence of a specified task by validating the specified ID as a task ID.
OK, or ERROR if the task ID is invalid.
S_objLib_OBJ_ID_ERROR
taskTcb( ) - get the task control block for a task ID
WIND_TCB *taskTcb ( int tid /* task ID */ )
This routine returns a pointer to the task control block (WIND_TCB) for a specified task. Although all task state information is contained in the TCB, users must not modify it directly. To change registers, for instance, use taskRegsSet( ) and taskRegsGet( ).
A pointer to a WIND_TCB, or NULL if the task ID is invalid.
S_objLib_OBJ_ID_ERROR