Everything

CHAPTER 4 TASK DEPENDENT SYNCHRONIZATION FUNCTIONS


This chapter describes the task dependent synchronization functions performed by the RI600V4.
4.1 Outline
The RI600V4 provides several task-dependent synchronization functions.
4.2 Put Task to Sleep
4.2.1 Waiting forever
A task is moved to the sleeping state (waiting forever) by issuing the following service call from the processing program.
- slp_tsk
This service call moves the invoking task from the RUNNING state to the WAITING state (sleeping state).
If a wake-up request has been queued to the target task (the wake-up request counter > 0) when this service call is issued, this service call does not move the state but decrements the wake-up request counter (by subtracting 1 from the wake-up request counter).
The sleeping state is cancelled in the following cases.
Sleeping State Cancel Operation
Return Value
A wake-up request was issued as a result of issuing wup_tsk.
E_OK
A wake-up request was issued as a result of issuing iwup_tsk.
E_OK
Forced release from waiting (accept rel_wai while waiting).
E_RLWAI
Forced release from waiting (accept irel_wai while waiting).
E_RLWAI

The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ER      ercd;                   /*Declares variable*/
 
     /* ......... */
     ercd = slp_tsk ();              /*Put task to sleep*/
     if (ercd == E_OK) {
         /* ......... */             /*Normal termination processing*/
     } else if (ercd == E_RLWAI) {
         /* ......... */             /*Forced termination processing*/
     }
     /* ......... */
 

4.2.2 With time-out
A task is moved to the sleeping state (with time-out) by issuing the following service call from the processing program.
- tslp_tsk
This service call moves the invoking task from the RUNNING state to the WAITING state with time-out(sleeping state).
As a result, the invoking task is unlinked from the ready queue and excluded from the RI600V4 scheduling subject.
If a wake-up request has been queued to the target task (the wake-up request counter > 0) when this service call is issued, this service call does not move the state but decrements the wake-up request counter (by subtracting 1 from the wake-up request counter).
The sleeping state is cancelled in the following cases.
Sleeping State Cancel Operation
Return Value
A wake-up request was issued as a result of issuing wup_tsk.
E_OK
A wake-up request was issued as a result of issuing iwup_tsk.
E_OK
Forced release from waiting (accept rel_wai while waiting).
E_RLWAI
Forced release from waiting (accept irel_wai while waiting).
E_RLWAI
The time specified by tmout has elapsed.
E_TMOUT

The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ER      ercd;               /*Declares variable*/
     TMO     tmout = 3600;       /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = tslp_tsk (tmout);    /*Put task to sleep*/
 
     if (ercd == E_OK) {
         /* ......... */         /*Normal termination processing*/
     } else if (ercd == E_RLWAI) {
         /* ......... */         /*Forced termination processing*/
     } else if (ercd == E_TMOUT) {
         /* ......... */         /*Time-out processing*/
     }
 
     /* ......... */
 }

Note When TMO_FEVR is specified for wait time tmout, processing equivalent to slp_tsk will be executed.
4.3 Wake-up Task
A task is woken up by issuing the following service call from the processing program.
- wup_tsk, iwup_tsk
These service calls cancel the WAITING state (sleeping state) of the task specified by parameter tskid.
As a result, the target task is moved from the sleeping state to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
If the target task is in a state other than the sleeping state when this service call is issued, this service call does not move the state but increments the wake-up request counter (by added 1 to the wake-up request counter).
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     wup_tsk (tskid);                /*Wake-up task*/
 
     /* ......... */
 }

Note The wake-up request counter managed by the RI600V4 is configured in 8-bit widths. If the number of wake-up requests exceeds the maximum count value 255 as a result of issuing this service call, the counter manipulation processing is therefore not performed but "E_QOVR" is returned.
4.4 Cancel Task Wake-up Requests
A wake-up request is cancelled by issuing the following service call from the processing program.
- can_wup, ican_wup
These service calls cancel all of the wake-up requests queued to the task specified by parameter tskid (the wake-up request counter is set to 0).
When this service call is terminated normally, the number of cancelled wake-up requests is returned.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ER_UINT ercd;                   /*Declares variable*/
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = can_wup (tskid);         /*Cancel task wake-up requests*/
 
     if (ercd >= 0) {
         /* ......... */             /*Normal termination processing*/
     }
 
     /* ......... */
 }

4.5 Forcibly Release Task from Waiting
The WAITING state is forcibly cancelled by issuing the following service call from the processing program.
- rel_wai, irel_wai
These service calls forcibly cancel the WAITING state of the task specified by parameter tskid.
As a result, the target task unlinked from the wait queue and is moved from the WAITING state to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
"E_RLWAI" is returned from the service call that triggered the move to the WAITING state (slp_tsk, wai_sem, or the like) to the task whose WAITING state is cancelled by this service call.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     rel_wai (tskid);                /*Release task from waiting*/
 
     /* ......... */
 }

Note 1 This service call does not perform queuing of forced cancellation requests. If the target task is in a state other than the WAITING or WAITING-SUSPENDED state, "E_OBJ" is returned.
Note 2 The SUSPENDED state is not cancelled by these service calls.
4.6 Suspend Task
A task is moved to the SUSPENDED state by issuing the following service call from the processing program.
- sus_tsk, isus_tsk
These service calls move the target task specified by parameter tskid from the RUNNING state to the SUSPENDED state, from the READY state to the SUSPENDED state, or from the WAITING state to the WAITING-SUSPENDED state.
If the target task has moved to the SUSPENDED or WAITING-SUSPENDED state when this service call is issued, these service calls return E_QOVR.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     sus_tsk (tskid);                /*Suspend task*/
 
     /* ......... */
 }

4.7 Resume Suspended Task
4.7.1 Resume suspended task
The SUSPENDED state is cancelled by issuing the following service call from the processing program.
- rsm_tsk, irsm_tsk
These service calls move the target task specified by parameter tskid from the SUSPENDED state to the READY state, or from the WAITING-SUSPENDED state to the WAITING state.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     rsm_tsk (tskid);                /*Resume suspended task*/
 
     /* ......... */
 }

Note 1 This service call does not perform queuing of cancellation requests. If the target task is in a state other than the SUSPENDED or WAITING-SUSPENDED state, "E_OBJ" is returned.
Note 2 The RI600V4 does not support queuing of suspend request. The behavior of the frsm_tsk and ifrsm_tsk, that can release from the SUSPENDED state even if suspend request has been queued, are same as rsm_tsk and irsm_tsk.
4.7.2 Forcibly resume suspended task
The SUSPENDED state is forcibly cancelled by issuing the following service calls from the processing program.
- frsm_tsk, ifrsm_tsk
These service calls move the target task specified by parameter tskid from the SUSPENDED state to the READY state, or from the WAITING-SUSPENDED state to the WAITING state.
The following describes an example for coding these service calls.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ID      tskid = 8;              /*Declares and initializes variable*/
 
     /* ......... */
 
     frsm_tsk (tskid);                /*Forcibly resume suspended task*/
 
     /* ......... */
 }

Note 1 This service call does not perform queuing of cancellation requests. If the target task is in a state other than the SUSPENDED or WAITING-SUSPENDED state, "E_OBJ" is therefore returned.
Note 2 The RI600V4 does not support queuing of suspend request. Therefore, the behavior of these service calls are same as rsm_tsk and irsm_tsk.
4.8 Delay Task
A task is moved to the delayed state by issuing the following service call from the processing program.
- dly_tsk
This service call moves the invoking task from the RUNNING state to the WAITING state (delayed state).
As a result, the invoking task is unlinked from the ready queue and excluded from the RI600V4 scheduling subject.
The delayed state is cancelled in the following cases.
Delayed State Cancel Operation
Return Value
Delay time specified by parameter dlytim has elapsed.
E_OK
Forced release from waiting (accept rel_wai while waiting).
E_RLWAI
Forced release from waiting (accept irel_wai while waiting).
E_RLWAI

The following describes an example for coding this service call.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600*/
 
 void task (VP_INT exinf)
 {
     ER      ercd;                   /*Declares variable*/
     RELTIM  dlytim = 3600;          /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = dly_tsk (dlytim);        /*Delay task*/
 
     if (ercd == E_OK) {
         /* ......... */             /*Normal termination processing*/
     } else if (ercd == E_RLWAI) {
         /* ......... */             /*Forced termination processing*/
     }
 
     /* ......... */
 }

Note When 0 is specified as dlytim, the delay time is up to next base clock interrupt generation.
4.9 Differences Between Sleep with Time-out and Delay
There are differences between "Sleep with time-out (4.2.2 With time-out)" and "Delay (4.8 Delay Task)" as shown in Table 4-1.
Table 4-1 Differences Between "Sleep with time-out" and "Delay"
Sleep with time-out
Delay
Service call that causes status change
Return value when time has elapsed
E_TMOUT
E_OK
Operation when wup_tsk or iwup_tsk is issued
Wake-up
Queues the wake-up request (time elapse wait is not cancelled).