We describe the Task kernel services in detail. The Task kernel services start and stop tasks and maintain information about task states.
KS_AbortTask ... 23 KS_CloseTask ... 25 KS_DefTaskEnvArg ... 27 KS_DefTaskName ...30 KS_DefTaskPriority ... 32 KS_DefTaskProp... 34 KS_DefTaskSema ... 36 KS_DefTickSlice... 38 KS_DisableTaskScheduler ... 40 KS_EnableTaskScheduler... 41 KS_ExecuteTask ...42 KS_GetTaskEnvArg ...44 KS_GetTaskClassProp...47 KS_GetTaskID ... 50 KS_GetTaskName ...51 KS_GetTaskPriority ... 53 KS_GetTaskProp... 54
KS_LookupTask ... 64 KS_OpenTask ... 66 XX_ResumeTask ... 68 KS_SleepTask... 70 KS_SuspendTask ... 71 KS_TerminateTask...72 KS_UseTask ... 74 KS_YieldTask... 76
KS_AbortTask
KS_AbortTask
Abort the execution of a task.
Synopsis
void KS_AbortTask (TASK task)Input
Description
The KS_AbortTask kernel service stops the specified task by blocking it from further operation. To start the task again, you must first terminate it with a call to KS_TerminateTask and then restart it with a call to KS_ExecuteTask.This service is similar to the KS_TerminateTask service except that it sets the status of the task to ABORTED_BLOCK instead of INACTIVE. Such an identification may be valuable when tracking down a task gone awry during system diagnostic operations.
A task number of zero (0) indicates a request to abort the Current Task. In all cases following abortion of the requester, the next highest priority ready task executes.
Warning: Other than the items mentioned above, tasks that are currently using kernel objects or have objects allocated to them are not cleaned up by the abort process. The
programmer must ensure that the task releases all such system elements to the system before aborting the task. For example, a dynamic task should not abort itself if the task’s stack has been dynamically allocated from a memory partition because it would be difficult to recover the memory used for the stack. Repeated occurrences of such an event would cause a memory leak that could lead to eventual system failure.
task The number of the task to abort.
KS_AbortTask
Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example
In Example 2-1, the Current Task aborts the TASKBX task and then terminates itself.Example 2-1. Abort Task and Terminate
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ktask.h" /* defines TASKBX */
KS_AbortTask (TASKBX); /* abort task TASKBX */
KS_TerminateTask (SELFTASK); /* now terminate self */
See Also
KS_TerminateTask, page 72KS_CloseTask
KS_CloseTask
End the use of a dynamic task.
Synopsis
KSRC KS_CloseTask (TASK task)Input
Description
The KS_CloseTask kernel service ends the Current Task’s use of the dynamic task specified in task. When closing the task, the kernel detaches the caller’s use of it. If the caller is the last user of the task, the kernel releases the closed task to the free pool of dynamic tasks for reuse. If there is at least one other task still referencing the task, the kernel does not release the task to the free pool but the service completes successfully.Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service was successful.
` RC_STATIC_OBJECT if the specified task is not dynamic.
` RC_OBJECT_NOT_INUSE if the specified task does not correspond to an active dynamic task.
` RC_OBJECT_INUSE if the Current Task’s use of the specified task is closed but the task remains open for use by other tasks.
Note: The KSRC value does not necessarily indicate an error condition. The calling task must interpret its meaning.
task The number of the task to close.
KS_CloseTask
Example
In Example 2-2, the Current Task waits on a signal from another task indicating that it is time to close an active dynamic task. The handle of the dynamic task is specified in dyntask. When the signal is received, the Current Task closes the associated task.Example 2-2. Close Task When Signaled
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
TASK dyntask; /* not SELFTASK (TASK)0 */
SEMA dynsema;
KS_TestSemaW (dynsema); /* wait for signal */
/* then close the task */
if (KS_CloseTask (dyntask) != RC_GOOD) {
...something is wrong. Deal with it }
...continue /* task closed successfully */
See Also
KS_OpenTask,page 66 KS_UseTask, page 74KS_DefTaskEnvArg
KS_DefTaskEnvArg
Define the environment arguments for a task.
Synopsis
void KS_DefTaskEnvArg (TASK task, const void *parg)Inputs
Description
The KS_DefTaskEnvArg kernel service establishes a pointer to a structure containing parameters that define the environment of the task specified in task. The RTXC Kernel places no restrictions on the size or content of the environment structure.The service requires a task number and a pointer, parg, to the environment arguments structure for the specified task.
Note: To use this service, you must enable the Environment Arguments attribute of the Task class during system
generation.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example
In Example 2-3 on page 28, the Current Task needs to spawn a dynamic task to operate on the port and channel specified by the port and chnl variables that were specified elsewhere. The dynamictask The number of the task being defined.
parg A pointer to the environment arguments structure for the task.
KS_DefTaskEnvArg
After defining the dynamic task’s properties, the Current Task defines the channel and port environment arguments in a structure and makes that structure known to the dynamic task. The Current Task then executes the dynamic task.
Example 2-3. Define Task Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kpart.h" /* Memory Partitions */
#define STKSIZE 256
#define DYNPRI 14
extern void taskA (void);
struct{
int port;
int channel;
} envargA; /* environment argument structure */
TASK dyntask;
TASKPROP tprop;
int port, chnl;
if (KS_OpenTask ((char *)0, &dyntask) != RC_GOOD) {
... Deal with problem with dynamic task allocation }
else {
/* allocate space for task’s stack */
tprop.stackbase = (char *)KS_AllocBlkW (BLK256, (PEVENT *)0);
/* define task properties */
tprop.taskentry = taskA;
tprop.stacksize = STKSIZE;
tprop.priority = DYNPRI;
KS_DefTaskProp (dyntask, &tprop);
/* define environment arguments */
envargA.port = port;
envargA.channel = chnl;
KS_DefTaskEnvArg (dyntask, &envargA);
/* start task */
KS_ExecuteTask (dyntask);
}
KS_DefTaskEnvArg
See Also
KS_DefTaskProp, page 34 KS_GetTaskEnvArg, page 44KS_DefTaskName
KS_DefTaskName
Define the name of a previously opened dynamic task.
Synopsis
KSRC KS_DefTaskName (TASK task, const char *pname)Inputs
Description
The KS_DefTaskName kernel service names or renames the dynamic task specified in task. The service uses the null-terminated string pointed to by pname for the task’s new name. The kernel only stores pname internally, which means that the same array cannot be used to build multiple dynamic task names. Static tasks cannot be named or renamed under program control.Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.
This service does not check for duplicate task names.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service completes successfully.
` RC_STATIC_OBJECT if the task being named is static.
` RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Task class is not enabled.
` RC_OBJECT_NOT_INUSE if the dynamic task being named is still in the free pool of dynamic tasks.
Error
This service may generate the following fatal error code:FE_ILLEGAL_TASK if the specified task ID is not valid.
task The number of the task being defined.
pname A pointer to a null-terminated name string.
KS_DefTaskName
Example
Example 2-4 assigns the name NewTask to the task specified in the dyntask variable so other users may reference it by name.Example 2-4. Define Task Name
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
TASK dyntask;
if (KS_DefTaskName (dyntask, "NewTask") != RC_GOOD) {
... Probably is a static task. Deal with it here.
}
... else the naming operation was successful. Continue
See Also
KS_OpenTask, page 66 KS_GetTaskName, page 51 KS_LookupTask, page 64 KS_UseTask, page 74KS_DefTaskPriority
KS_DefTaskPriority
Define a new priority for a task.
Synopsis
void KS_DefTaskPriority (TASK task, PRIORITY priority)Inputs
Description
The KS_DefTaskPriority kernel service defines or changes the priority of task. The new priority may be any legal priority, either higher or lower than the task’s current priority. Legal priority values are {1, 2, … 126}. Note that 0 is not a legal priority value.To increase the priority of a task, you must assign it a lower priority value. For example, a task with a priority of 1 has a higher priority than a task whose priority is 2. If the Current Task assigns itself a lower priority value (that is, it becomes a higher priority task), no context switch occurs. However, if the Current Task assigns itself a higher priority value, making it a lower priority task, a context switch does occur if there is another task in the Ready List that has a priority less than or equal to the Current Task’s assigned priority.
The Current Task may specify itself with a task value of zero (0).
If task is not the Current Task, a preemption occurs if the new priority of task is higher than that of the requesting task and task is in the Ready List.
If task is in one or more priority-ordered wait lists, its position in those lists may change to reflect its new priority.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
task The number of the task being defined.
priority The priority value for the task.
KS_DefTaskPriority
` FE_ILLEGAL_PRIORITY if the specified priority value is out of range.
Example
Example 2-5 changes the priority of the SERIALIN task from its current level to priority 3, and then changes the calling task to priority 6.Example 2-5. Define Task Priorities
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ktask.h" /* defines SERIALIN */
KS_DefTaskPriority (SERIALIN, 3); /* new priority = 3 */
KS_DefTaskPriority (SELFTASK, 6); /* new priority = 6 */
See Also
KS_ExecuteTask, page 42 KS_TerminateTask, page 72KS_DefTaskProp
KS_DefTaskProp
Define the properties of a task.
Synopsis
void KS_DefTaskProp (TASK task, const TASKPROP *ptaskprop)Inputs
Description
The KS_DefTaskProp kernel service defines the properties of the specified task by using the values contained in the TASKPROP structure pointed to by ptaskprop. If task is not in the inactive state, this function returns without making any changes to the properties of task. You may use this service on static or dynamically allocated tasks. It is typically used to define a static task during system startup or a dynamic task during runtime that has been previously allocated with the KS_OpenTask kernel service.Legal priority values are {1, 2, … 126}. (Note that 0 is not a legal priority value).
Example 2-6 shows the organization of the TASKPROP structure.
Example 2-6. Task Properties Structure typedef struct
{
void (*taskentry)(void); /* initial entry point address */
char *stackbase; /* initial stack base */
ksize_t stacksize; /* initial stack size */
PRIORITY priority; /* initial priority */
} TASKPROP;
Output
This service does not return a value.Error
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_ILLEGAL_PRIORITY if the specified priority is out of range.
task The number of the task being defined.
ptaskprop A pointer to a Task properties structure.
KS_DefTaskProp
` FE_NULL_TASKENTRY if the specified Task entry address is null.
` FE_NULL_STACKBASE if the specified Task stack base address is null.
` FE_ZERO_STACKSIZE if the specified Task stack size is zero.
Example
During system initialization, the startup code must create and initialize the Task object class and define the properties of all the static tasks before the start of multitasking operations, as illustrated in Example 2-7.Example 2-7. Define Task Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const KCLASSPROP taskclassprop;
extern const TASKPROP taskprop[];
KSRC ksrc;
int objnum;
if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) {
printf ("Task class initialization failed %d", ksrc);
return (ksrc);
}
for (objnum = 1; objnum <= taskclassprop.n_statics; objnum++) KS_DefTaskProp (objnum, &taskprop[objnum]);
See Also
KS_GetTaskProp, page 54 INIT_TaskClassProp, page 62 KS_OpenTask, page 66KS_DefTaskSema
KS_DefTaskSema
Associate a semaphore with the termination or abortion of a task.
Synopsis
void KS_DefTaskSema (TASK task, SEMA sema)Inputs
Description
The KS_DefTaskSema kernel service associates the semaphore specified in sema with the termination and abortion events of the specified task, when sema is to be used in a subsequent test using the KS_TestSema kernel service or one of its variants. The service signals the semaphore when task is terminated or aborted.Note: To use this service, you must enable the Semaphores attribute of the Task class during system generation.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example
In Example 2-8 on page 37, the Current Task has nothing to do until the TASKA task gets terminated or aborted. To synchronize with this event, the Current Task defines the GOSEMA semaphore for TASKA and then waits for that semaphore.task The number of the task with which to associate the semaphore.
sema The semaphore to associate with the task.
KS_DefTaskSema
Example 2-8. Define Task Termination Semaphore
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ktask.h" /* defines TASKA */
#include "ksema.h" /* defines GOSEMA */
KS_DefTaskSema (TASKA, GOSEMA);
KS_TestSemaW (GOSEMA);
... TASKA ended, begin processing now
See Also
KS_GetTaskSema, page 56 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaMW, page 115KS_DefTickSlice
KS_DefTickSlice
Define the tick-slice quantum for a task.
Synopsis
void KS_DefTickSlice (TASK task, TSLICE ticks)Inputs
Description
The KS_DefTickSlice kernel service defines the number of ticks the specified task is permitted to run before it is forced to yield under tick-sliced scheduling.The service requires a task number and a tick-slice quantum, ticks, as arguments. The tick quantum period is specified as a value of TSLICE type giving the number of clock ticks approximating the desired duration of the tick-slice quantum. A task number of zero (0) specifies the Current Task.
You can change the tick quantum at any time. If tick-slicing is not in operation for task (quantum = zero (0)) and ticks is non-zero, task immediately begins tick-sliced operation.
A ticks value of zero (0) causes task to cease tick-sliced operation immediately.
However, if tick slicing is already in effect, a new tick quantum does not take effect until the current tick quantum expires. If you must alter the quantum immediately, change the quantum to zero (0) and then to the desired value.
Note: To use this service, you must enable the Tick Slice attribute of the Task class during system generation.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
task The number of the task being defined.
ticks The number of clock ticks in the tick-slice quantum.
KS_DefTickSlice
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example
In Example 2-9, the Current Task begins tick-sliced operation with a tick quantum of 100 msec. After some period of tick-slicedoperation, the task ceases tick-sliced operation.
Example 2-9. Define Tick Slice
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kproject.h" /* defines CLKTICK */
/* define tick slice quantum as 100 ms */
KS_DefTickSlice (SELFTASK, (TSLICE)100/CLKTICK);
... Task now in tick-sliced operation /* turn off tick-sliced operation */
KS_DefTickSlice (SELFTASK, (TSLICE)0);
See Also
KS_GetTickSlice, page 60KS_DisableTaskScheduler
KS_DisableTaskScheduler
Disable the task scheduler to prevent task context switching.
Synopsis
void KS_DisableTaskScheduler (void)Inputs
This service has no inputs.Description
The KS_DisableTaskScheduler kernel service disables the kernel scheduler, which in turn prevents context switching between tasks. With context switching turned off, a task can execute without being preempted. Interrupts are not disabled, but a context switch does not occur. When an application makes nested calls toKS_DisableTaskScheduler, preemption does not resume until an equal number of KS_EnableTaskScheduler calls are made.
Output
This service does not return a value.Example
Example 2-10 executes a section of code without being preempted.Example 2-10. Disable Task Scheduler
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KS_DisableTaskScheduler (); /* prevent preemption */
...perform some function
/* allow context switch to occur now */
KS_EnableTaskScheduler ();
See Also
KS_EnableTaskScheduler, page 41KS_EnableTaskScheduler
KS_EnableTaskScheduler
Enable the scheduler to allow context switching between tasks.
Synopsis
void KS_EnableTaskScheduler (void)Inputs
This service has no inputs.Description
The KS_EnableTaskScheduler kernel service enables the RTXC/ms Scheduler, which in turn permits task context switching to occur. If the application makes nested calls toKS_DisableTaskScheduler, then it must make an equal number of calls to KS_EnableTaskScheduler before context switching (preemption) starts again.
The RTXC Kernel enables the scheduler by default during system initialization.
Output
This service does not return a value.Example
In Example 2-11, after performing some critical function with the scheduler disabled, the Current Task enables the scheduler.Example 2-11. Enable Task Scheduler
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KS_DisableTaskScheduler (); /* prevent preemption */
...perform some function
/* allow context switch to occur now */
KS_EnableTaskScheduler ();
See Also
KS_DisableTaskScheduler, page 40KS_ExecuteTask
KS_ExecuteTask
Execute a task.
Synopsis
KSRC KS_ExecuteTask (TASK task)Input
Description
The KS_ExecuteTask kernel service starts a specified task from its beginning address. The task must be in the INACTIVE state. If so, it is inserted into the Ready List with its program counter (PC) and stack pointer (SP) initialized to their starting values. The task’s starting address, initial priority, and stack pointer are specified during system generation or dynamically with theKS_DefTaskProp kernel service.
If task is of higher priority than the requesting (current) task, a context switch is performed and the new task runs. If task is of lower or equal priority, control is returned to the caller.
Warning: A task value of zero (0) indicates self-execution.
This is not advisable.
Output
This service returns a KSRC value as follows:` RC_GOOD if the task starts successfully.
` RC_TASK_NOT_INACTIVE if the specified task is in a state other than INACTIVE.
Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_TASK if the specified task ID is not valid.
` FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example
In Example 2-12 on page 43, the Current Task starts the SHUTDOWN static task from its starting address.task The number of the task to execute.
KS_ExecuteTask
Example 2-12. Execute Task
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "ktask.h" /* defines task SHUTDOWN */
/* execute SHUTDOWN task */
if (KS_ExecuteTask (SHUTDOWN) != RC_GOOD) {
...task is not started because it is not in INACTIVE state
}
...task successfully started executing
See Also
KS_TerminateTask, page 72KS_GetTaskEnvArg
KS_GetTaskEnvArg
Get the address of a task’s environment arguments.