CHAPTER 3 TASK MANAGEMENT FUNCTIONS

This chapter describes the task management functions performed by the RI850V4.

3.1 Outline

The task management functions provided by the RI850V4 include a function to reference task statuses such as priorities and detailed task information, in addition to a function to manipulate task statuses such as generation, activation and termination of tasks.

3.2 Tasks

A task is processing program that is not executed unless it is explicitly manipulated via service calls provided by the RI850V4, unlike other processing programs (cyclic handler and interrupt handler), and is called from the scheduler.

The RI850V4 manages the states in which each task may enter and tasks themselves, by using management objects (task management blocks) corresponding to tasks one-to-one.

Note The execution environment information required for a task's execution is called "task context". During task execution switching, the task context of the task currently under execution by the RI850V4 is saved and the task context of the next task to be executed is loaded.

3.2.1 Task state

Tasks enter various states according to the acquisition status for the OS resources required for task execution and the occurrence/non-occurrence of various events. In this process, the current state of each task must be checked and managed by the RI850V4.

The RI850V4 classifies task states into the following six types.

Figure 3-1 Task State

1 ) DORMANT state

State of a task that is not active, or the state entered by a task when processing has ended.
A task in the DORMANT state, while being under management of the RI850V4, is not subject to RI850V4 scheduling.

2 ) READY state

State of a task for which the preparations required for processing execution have been completed, but since another task with a higher priority level or a task with the same priority level is currently being processed, the task is waiting to be given the CPU's use right.

3 ) RUNNING state

State of a task that has acquired the CPU use right and is currently being processed.
Only one task can be in the running state at one time in the entire system.

4 ) WAITING state

State in which processing execution has been suspended because conditions required for execution are not satisfied.
Resumption of processing from the WAITING state starts from the point where the processing execution was suspended. The value of information required for resumption (such as task context) immediately before suspension is therefore restored.
In the RI850V4, the WAITING state is classified into the following ten types according to their required conditions and managed.

Table 3-1 WAITING State


WAITING State	Description
Sleeping state	A task enters this state if the counter for the task (registering the number of times the wakeup request has been issued) indicates 0x0 upon the issue of slp_tsk or tslp_tsk.
Delayed state	A task enters this state upon the issue of a dly_tsk.
WAITING state for a semaphore resource	A task enters this state if it cannot acquire a resource from the relevant semaphore upon the issue of wai_sem or twai_sem.
WAITING state for an eventflag	A task enters this state if a relevant eventflag does not satisfy a predetermined condition upon the issue of wai_flg or twai_flg.
Sending WAITING state for a data queue	A task enters this state if cannot send a data to the relevant data queue upon the issue of snd_dtq or tsnd_dtq.
Receiving WAITING state for a data queue	A task enters this state if cannot receive a data from the relevant data queue upon the issue of rcv_dtq or trcv_dtq.
Receiving WAITING state for a mailbox	A task enters this state if cannot receive a message from the relevant mailbox upon the issue of rcv_mbx or trcv_mbx.
WAITING state for a mutex	A task enters this state if cannot lock the relevant mutex upon the issue of loc_mtx or tloc_mtx.
WAITING state for a fixed-sized memory block	A task enters this state if it cannot acquire a fixed-sized memory block from the relevant fixed-sized memory pool upon the issue of get_mpf or tget_mpf.
WAITING state for a variable-sized memory block	A task enters this state if it cannot acquire a variable-sized memory block from the relevant variable-sized memory pool upon the issue of get_mpl or tget_mpl.

5 ) SUSPENDED state

State in which processing execution has been suspended forcibly.
Resumption of processing from the SUSPENDED state starts from the point where the processing execution was suspended. The value of information required for resumption (such as task context) immediately before suspension is therefore restored.

6 ) WAITING-SUSPENDED state

State in which the WAITING and SUSPENDED states are combined.
A task enters the SUSPENDED state when the WAITING state is cancelled, or enters the WAITING state when the SUSPENDED state is cancelled.

3.2.2 Task priority

A priority level that determines the order in which that task will be processed in relation to the other tasks is assigned to each task.

As a result, in the RI850V4, the task that has the highest priority level of all the tasks that have entered an executable state (RUNNING state or READY state) is selected and given the CPU use right.

In the RI850V4, the following two types of priorities are used for management purposes.

- Initial priority
Priority set when a task is created.
Therefore, the priority level of a task (priority level referenced by the scheduler) immediately after it moves from the DORMANT state to the READY state is the initial priority.

- Current priority
Priority referenced by the RI850V4 when it performs a manipulation (task scheduling, queuing tasks to a wait queue in the order of priority, or priority level inheritance) when a task is activated.

Note 1 In the RI850V4, a task having a smaller priority number is given a higher priority.

Note 2 The priority range that can be specified in a system can be defined in Basic information (Maximum priority: maxtpri) when creating a system configuration file.

3.2.3 Basic form of tasks

When coding a task, use a void function with one VP_INT argument (any function name is fine).

The extended information specified with Task information, or the start code specified when sta_tsk or ista_tsk is issued, is set for the exinf argument.

The following shows the basic form of tasks in C.


#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ......... ext_tsk (); /Terminate invoking task/ }

Note 1 If a task moves from the DORMANT state to the READY state by issuing sta_tsk or ista_tsk, the start code specified when issuing sta_tsk or ista_tsk is set to the exinf argument.

Note 2 When the return instruction is issued in a task, the same processing as ext_tsk is performed.

Note 3 For details about the extended information, refer to "3.4 Activate Task".

3.2.4 Internal processing of task

In the RI850V4, original dispatch processing (task scheduling) is executed during task switching.

Therefore, note the following points when coding tasks.

- Coding method
Code tasks using C or assembly language.
When coding in C, they can be coded in the same manner as ordinary functions coded.
When coding in assembly language, code them according to the calling rules prescribed in the compiler used.

- Stack switching
When switching tasks, the RI850V4 performs switching to the task specified in Task information.

- Service call issue
Service calls that can be issued in tasks are limited to the service calls that can be issued from tasks.

Note For details on the valid issue range of each service call, refer to Table 16-1 to Table 16-12.

- Acceptance of EI level maskable interrupts
When a task is activated, the RI850V4 sets the interrupt acceptance status according to the settings in the Attribute: tskatr (such as the description language and initial state after activation) by manipulating the PMn bits in the priority mask register (PMR) and the ID bit in the program status word (PSW).

3.3 Create Task

In the RI850V4, the method of creating a task is limited to "static creation".

Tasks therefore cannot be created dynamically using a method such as issuing a service call from a processing program.

Static task creation means defining of tasks using static API "CRE_TSK" in the system configuration file.

For details about the static API "CRE_TSK", refer to "17.5.1 Task information".

3.4 Activate Task

The RI850V4 provides two types of interfaces for task activation: queuing an activation request queuing and not queuing an activation request.

In the RI850V4, extended information specified in Task information during configuration and the value specified for the second parameter stacd when service call sta_tsk or ista_tsk is issued are called "extended information".

3.4.1 Queuing an activation request

A task (queuing an activation request) is activated by issuing the following service call from the processing program.

- act_tsk, iact_tsk
These service calls move a task specified by parameter tskid from the DORMANT state to the READY state.
As a result, the target task is queued at the end on the ready queue corresponding to the initial priority and becomes subject to scheduling by the RI850V4.
If the target task has been moved to a state other than the DORMANT state when this service call is issued, this service call does not move the state but increments the activation request counter (by added 0x1 to the wakeup request counter).
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System infromation header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ ......... ......... act_tsk (tskid); /Activate task (queues an activation request)/ ......... ......... }

 #include    <kernel.h>          /*Standard header file definition*/

 #include    <kernel_id.h>       /*System infromation header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;          /*Declares and initializes variable*/

     .........

     .........

     act_tsk (tskid);            /*Activate task (queues an activation request)*/

     .........

     .........

Note 1 The activation request counter managed by the RI850V4 is configured in 7-bit widths. If the number of activation requests exceeds the maximum count value 127 as a result of issuing this service call, the counter manipulation processing is therefore not performed but "E_QOVR" is returned.

Note 2 Extended information specified in Task information is passed to the task activated by issuing these service calls.

3.4.2 Not queuing an activation request

A task (not queuing an activation request) is activated by issuing the following service call from the processing program.

- sta_tsk, ista_tsk
These service calls move a task specified by parameter tskid from the DORMANT state to the READY state.
As a result, the target task is queued at the end on the ready queue corresponding to the initial priority and becomes subject to scheduling by the RI850V4.
This service call does not perform queuing of activation requests. If the target task is in a state other than the DORMANT state, the status manipulation processing for the target task is therefore not performed but "E_OBJ" is returned.
Specify for parameter stacd the extended information transferred to the target task.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ VP_INT stacd = 123; /Declares and initializes variable/ ......... ......... sta_tsk (tskid, stacd); /Activate task (does not queue an activation / /request)/ ......... ......... }

 #include    <kernel.h>          /*Standard header file definition*/

 #include    <kernel_id.h>       /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;          /*Declares and initializes variable*/

     VP_INT  stacd = 123;        /*Declares and initializes variable*/

     .........

     .........

     sta_tsk (tskid, stacd);     /*Activate task (does not queue an activation */

                                 /*request)*/

     .........

     .........

3.5 Cancel Task Activation Requests

An activation request is cancelled by issuing the following service call from the processing program.

- can_act, ican_act
This service call cancels all of the activation requests queued to the task specified by parameter tskid (sets the activation request counter to 0x0).
When this service call is terminated normally, the number of cancelled activation requests is returned.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ER_UINT ercd; /Declares variable/ ID tskid = 8; /Declares and initializes variable/ ......... ......... ercd = can_act (tskid); /Cancel task activation requests/ if (ercd >= 0x0) { ......... /Normal termination processing/ ......... } ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ER_UINT ercd;                   /*Declares variable*/

     ID      tskid = 8;              /*Declares and initializes variable*/

     .........

     .........

     ercd = can_act (tskid);         /*Cancel task activation requests*/

     if (ercd >= 0x0) {

            .........                /*Normal termination processing*/

            .........

     .........

     .........

Note This service call does not perform status manipulation processing but performs the setting of activation request counter. Therefore, the task does not move from a state such as the READY state to the DORMANT state.

3.6 Terminate Task

3.6.1 Terminate invoking task

An invoking task is terminated by issuing the following service call from the processing program.

- ext_tsk
This service call moves an invoking task from the RUNNING state to the DORMANT state.
As a result, the invoking task is unlinked from the ready queue and excluded from the RI850V4 scheduling subject.
If an activation request has been queued to the invoking task (the activation request counter is not set to 0x0) when this service call is issued, this service call moves the task from the RUNNING state to the DORMANT state, decrements the wakeup request counter (by subtracting 0x1 from the wakeup request counter), and then moves the task from the DORMANT state to the READY state.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ......... ......... ext_tsk (); /Terminate invoking task/ }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     .........

     .........

     ext_tsk ();                     /*Terminate invoking task*/

Note 1 When moving a task from the RUNNING state to the DORMANT state, this service call initializes the following information to values that are set during task creation.

- Priority (current priority)

- Wakeup request count

- Suspension count

- Interrupt status

If an invoking task has locked a mutex, the locked state is released at the same time (processing equivalent to unl_mtx).

Note 2 When the return instruction is issued in a task, the same processing as ext_tsk is performed.

3.6.2 Terminate task

Other tasks are forcibly terminated by issuing the following service call from the processing program.

- ter_tsk
This service call forcibly moves a task specified by parameter tskid to the DORMANT state.
As a result, the target task is excluded from the RI850V4 scheduling subject.
If an activation request has been queued to the target task (the activation request counter is not set to 0x0) when this service call is issued, this service call moves the task to the DORMANT state, decrements the wakeup request counter (by subtracting 0x1 from the wakeup request counter), and then moves the task from the DORMANT state to the READY state.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ ......... ......... ter_tsk (tskid); /Terminate task/ ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;              /*Declares and initializes variable*/

     .........

     .........

     ter_tsk (tskid);                /*Terminate task*/

     .........

     .........

Note When moving a task to the DORMANT state, this service call initializes the following information to values that are set during task creation.

- Priority (current priority)

- Wakeup request count

- Suspension count

- Interrupt status

If the target task has locked a mutex, the locked state is released at the same time (processing equivalent to unl_mtx).

3.7 Change Task Priority

The priority is changed by issuing the following service call from the processing program.

- chg_pri, ichg_pri
These service calls change the priority of the task specified by parameter tskid (current priority) to a value specified by parameter tskpri.
If the target task is in the RUNNING or READY state after this service call is issued, this service call re-queues the task at the end of the ready queue corresponding to the priority specified by parameter tskpri, following priority change processing.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ PRI tskpri = 9; /Declares and initializes variable/ ......... ......... chg_pri (tskid, tskpri); /Change task priority/ ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;              /*Declares and initializes variable*/

     PRI     tskpri = 9;             /*Declares and initializes variable*/

     .........

     .........

     chg_pri (tskid, tskpri);        /*Change task priority*/

     .........

     .........

Note When the target task is queued to a wait queue in the order of priority, the wait order may change due to issue of this service call.

Example When three tasks (task A: priority level 10, task B: priority level 11, task C: priority level 12) are queued to the semaphore wait queue in the order of priority, and the priority level of task B is changed from 11 to 9, the wait order will be changed as follows.

3.8 Reference Task Priority

A task priority is referenced by issuing the following service call from the processing program.

- get_pri, iget_pri
Stores current priority of the task specified by parameter tskid in the area specified by parameter p_tskpri.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ PRI p_tskpri; /Declares variable/ ......... ......... get_pri (tskid, &p_tskpri); /Reference task priority/ ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;              /*Declares and initializes variable*/

     PRI     p_tskpri;               /*Declares variable*/

     .........

     .........

     get_pri (tskid, &p_tskpri);     /*Reference task priority*/

     .........

     .........

3.9 Reference Task State

3.9.1 Reference task state

A task status is referenced by issuing the following service call from the processing program.

- ref_tsk, iref_tsk
Stores task state packet (current state, current priority, etc.) of the task specified by parameter tskid in the area specified by parameter pk_rtsk.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ T_RTSK pk_rtsk; /Declares data structure/ STAT tskstat; /Declares variable/ PRI tskpri; /Declares variable/ STAT tskwait; /Declares variable/ ID wobjid; /Declares variable/ TMO lefttmo; /Declares variable/ UINT actcnt; /Declares variable/ UINT wupcnt; /Declares variable/ UINT suscnt; /Declares variable/ ATR tskatr; /Declares variable/ PRI itskpri; /Declares variable/ ......... ......... ref_tsk (tskid, &pk_rtsk); /Reference task state/ tskstat = pk_rtsk.tskstat; /Reference current state/ tskpri = pk_rtsk.tskpri; /Reference current priority/ tskwait = pk_rtsk.tskwait; /Reference reason for waiting/ wobjid = pk_rtsk.wobjid; /Reference object ID number for which the / /task is waiting/ lefttmo = pk_rtsk.lefttmo; /Reference remaining time until timeout/ actcnt = pk_rtsk.actcnt; /Reference activation request count/ wupcnt = pk_rtsk.wupcnt; /Reference wakeup request count/ suscnt = pk_rtsk.suscnt; /Reference suspension count/ tskatr = pk_rtsk.tskatr; /Reference attribute/ itskpri = pk_rtsk.itskpri; /Reference initial priority/ ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;              /*Declares and initializes variable*/

     T_RTSK  pk_rtsk;                /*Declares data structure*/

     STAT    tskstat;                /*Declares variable*/

     PRI     tskpri;                 /*Declares variable*/

     STAT    tskwait;                /*Declares variable*/

     ID      wobjid;                 /*Declares variable*/

     TMO     lefttmo;                /*Declares variable*/

     UINT    actcnt;                 /*Declares variable*/

     UINT    wupcnt;                 /*Declares variable*/

     UINT    suscnt;                 /*Declares variable*/

     ATR     tskatr;                 /*Declares variable*/

     PRI     itskpri;                /*Declares variable*/

     .........

     .........

     ref_tsk (tskid, &pk_rtsk);      /*Reference task state*/

     tskstat = pk_rtsk.tskstat;      /*Reference current state*/

     tskpri = pk_rtsk.tskpri;        /*Reference current priority*/

     tskwait = pk_rtsk.tskwait;      /*Reference reason for waiting*/

     wobjid = pk_rtsk.wobjid;        /*Reference object ID number for which the */

                                     /*task is waiting*/

     lefttmo = pk_rtsk.lefttmo;      /*Reference remaining time until timeout*/

     actcnt = pk_rtsk.actcnt;        /*Reference activation request count*/

     wupcnt = pk_rtsk.wupcnt;        /*Reference wakeup request count*/

     suscnt = pk_rtsk.suscnt;        /*Reference suspension count*/

     tskatr = pk_rtsk.tskatr;        /*Reference attribute*/

     itskpri = pk_rtsk.itskpri;      /*Reference initial priority*/

     .........

     .........

Note For details about the task state packet, refer to "15.2.1 Task state packet".

3.9.2 Reference task state (simplified version)

A task status (simplified version) is referenced by issuing the following service call from the processing program.

- ref_tst, iref_tst
Stores task state packet (current state, reason for waiting) of the task specified by parameter tskid in the area specified by parameter pk_rtst.
Used for referencing only the current state and reason for wait among task information.
Response becomes faster than using ref_tsk or iref_tsk because only a few information items are acquired.
The following describes an example for coding this service call.

#include <kernel.h> /Standard header file definition/ #include <kernel_id.h> /System information header file definition/ void task (VP_INT exinf) { ID tskid = 8; /Declares and initializes variable/ T_RTST pk_rtst; /Declares data structure/ STAT tskstat; /Declares variable/ STAT tskwait; /Declares variable/ ......... ......... ref_tst (tskid, &pk_rtst); /Reference task state (simplified version)/ tskstat = pk_rtst.tskstat; /Reference current state/ tskwait = pk_rtst.tskwait; /Reference reason for waiting/ ......... ......... }

 #include    <kernel.h>              /*Standard header file definition*/

 #include    <kernel_id.h>           /*System information header file definition*/

 void task (VP_INT exinf)

     ID      tskid = 8;              /*Declares and initializes variable*/

     T_RTST  pk_rtst;                /*Declares data structure*/

     STAT    tskstat;                /*Declares variable*/

     STAT    tskwait;                /*Declares variable*/

     .........

     .........

     ref_tst (tskid, &pk_rtst);      /*Reference task state (simplified version)*/

     tskstat = pk_rtst.tskstat;      /*Reference current state*/

     tskwait = pk_rtst.tskwait;      /*Reference reason for waiting*/

     .........

     .........

Note For details about the task state packet (simplified version), refer to "15.2.2 Task state packet (simplified version)".

3.10 Memory Saving

The RI850V4 provides the method (Disable preempt) for reducing the task stack size required by tasks to perform processing.

3.10.1 Disable preempt

In the RI850V4, preempt acknowledge status attribute TA_DISPREEMPT can be defined in Task information when creating a system configuration file.

The task for which this attribute is defined performs the operation that continues processing by ignoring the scheduling request issued from a non-task, so a management area of 24 to 44 bytes can be reduced per task.