CHAPTER 4 TASK DEPENDENT SYNCHRONIZATION FUNCTIONS

---

This chapter describes the task dependent synchronization functions performed by the RI850V4.

4.1 Outline

The RI850V4 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
As a result, the invoking task is unlinked from the ready queue and excluded from the RI850V4 scheduling subject.
If a wakeup request has been queued to the target task (the wakeup request counter is not set to 0x0) when this service call is issued, this service call does not move the state but decrements the wakeup request counter (by subtracting 0x1 from the wakeup request counter).
The sleeping state is cancelled in the following cases, and then moved to the READY state.

Sleeping State Cancel Operation	Return Value
A wakeup request was issued as a result of issuing wup_tsk.	E_OK
A wakeup 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> /*System information header file definition*/ void task (VP_INT exinf) { ER ercd; /*Declares variable*/ ......... ......... ercd = slp_tsk (); /*Put task to sleep (waiting forever)*/ if (ercd == E_OK) { ......... /*Normal termination processing*/ ......... } else if (ercd == E_RLWAI) { ......... /*Forced termination processing*/ ......... } ......... .........

4.2.2 With timeout

A task is moved to the sleeping state (with timeout) by issuing the following service call from the processing program.

- tslp_tsk
This service call moves an invoking task from the RUNNING state to the WAITING state (sleeping state).
As a result, the invoking task is unlinked from the ready queue and excluded from the RI850V4 scheduling subject.
If a wakeup request has been queued to the target task (the wakeup request counter is not set to 0x0) when this service call is issued, this service call does not move the state but decrements the wakeup request counter (by subtracting 0x1 from the wakeup request counter).
The sleeping state is cancelled in the following cases, and then moved to the READY state.

Sleeping State Cancel Operation	Return Value
A wakeup request was issued as a result of issuing wup_tsk.	E_OK
A wakeup 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
Polling failure or timeout.	E_TMOUT

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 ercd; /*Declares variable*/ TMO tmout = 3600; /*Declares and initializes variable*/ ......... ......... ercd = tslp_tsk (tmout); /*Put task to sleep (with timeout)*/ if (ercd == E_OK) { ......... /*Normal termination processing*/ ......... } else if (ercd == E_RLWAI) { ......... /*Forced termination processing*/ ......... } else if (ercd == E_TMOUT) { ......... /*Timeout processing*/ ......... } ......... ......... }

Note When TMO_FEVR is specified for wait time tmout, processing equivalent to slp_tsk will be executed.

4.3 Wakeup 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 wakeup 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 information header file definition*/ void task (VP_INT exinf) { ID tskid = ID_TSK1; /*Declares and initializes variable*/ ......... ......... wup_tsk (tskid); /*Wakeup task*/ ......... ......... }

Note The wakeup request counter managed by the RI850V4 is configured in 7-bit widths. If the number of wakeup 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.

4.4 Cancel Task Wakeup Requests

A wakeup request is cancelled by issuing the following service call from the processing program.

- can_wup, ican_wup
These service calls cancel all of the wakeup requests queued to the task specified by parameter tskid (the wakeup request counter is set to 0x0).
When this service call is terminated normally, the number of cancelled wakeup 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 = ID_TSK1; /*Declares and initializes variable*/ ......... ercd = can_wup (tskid); /*Cancel task wakeup requests*/ if (ercd >= 0x0) { ......... /*Normal termination processing*/ } ......... }

4.5 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 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 = ID_TSK1; /*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 add 0x1 to the suspend request counter for the task specified by parameter tskid, and then move the target task 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, the counter manipulation processing is not performed but only the suspend request counter increment processing is executed.
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 = ID_TSK1; /*Declares and initializes variable*/ ......... sus_tsk (tskid); /*Suspend task*/ ......... }

Note The suspend request counter managed by the RI850V4 is configured in 7-bit widths. If the number of suspend 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.

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
This service call subtracts 0x1 from the suspend request counter for the task specified by parameter tskid, and then cancels the SUSPENDED state of the target task.
As a result, the target task is moved from the SUSPENDED state to the READY state, or from the WAITING-SUSPENDED state to the WAITING state.
If a suspend request is queued (subtraction result is other than 0x0) when this service call is issued, the counter manipulation processing is not performed but only the suspend request counter decrement processing is executed.
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 = ID_TSK1; /*Declares and initializes variable*/ ......... rsm_tsk (tskid); /*Resume suspended task*/ ......... }

Note 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.

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 cancel all of the suspend requests issued for the task specified by parameter tskid (by setting the suspend request counter to 0x0). As a result, the target task moves 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 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 = ID_TSK1; /*Declares and initializes variable*/ ......... frsm_tsk (tskid); /*Forcibly resume suspended task*/ ......... }

Note 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.

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 RI850V4 scheduling subject.
The delayed state is cancelled in the following cases, and then moved to the READY state.

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> /*System information header file definition*/ 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*/ } ......... }

4.9 Differences Between Wakeup Wait with Timeout and Time Elapse Wait

Wakeup waits with timeout and time elapse waits differ on the following points.

Table 4-1 Differences Between Wakeup Wait with Timeout and Time Elapse Wait

	Wakeup Wait with Timeout	Time Elapse Wait
Service call that causes status change	tslp_tsk	dly_tsk
Return value when timed out	E_TMOUT	E_OK
Operation when wup_tsk or iwup_tsk is issued	Wakeup	Queues the wakeup request (time elapse wait is not cancelled).