Everything

CHAPTER 5 SYNCHRONIZATION AND COMMUNICATION FUNCTIONS


This chapter describes the synchronization and communication functions performed by the RI850V4.
5.1 Outline
The synchronization and communication functions of the RI850V4 consist of Semaphores, Eventflags, Data Queues, and Mailboxes that are provided as means for realizing exclusive control, queuing, and communication among tasks.
5.2 Semaphores
In the RI850V4, non-negative number counting semaphores are provided as a means (exclusive control function) for preventing contention for limited resources (hardware devices, library function, etc.) arising from the required conditions of simultaneously running tasks.
The following shows a processing flow when using a semaphore.
Figure 5-1 Processing Flow (Semaphore)
5.2.1 Create semaphore
In the RI850V4, the method of creating a semaphore is limited to "static creation".
Semaphores therefore cannot be created dynamically using a method such as issuing a service call from a processing program.
Static semaphore creation means defining of semaphores using static API "CRE_SEM" in the system configuration file.
For details about the static API "CRE_SEM", refer to "17.5.2 Semaphore information".
5.2.2 Acquire semaphore resource
A resource is acquired (waiting forever, polling, or with timeout) by issuing the following service call from the processing program.
- wai_sem
This service call acquires a resource from the semaphore specified by parameter semid (subtracts 0x1 from the semaphore counter).
If no resources are acquired from the target semaphore when this service call is issued (no available resources exist), this service call does not acquire resources but queues the invoking task to the target semaphore wait queue and moves it from the RUNNING state to the WAITING state (resource acquisition wait state).
The WAITING state for a semaphore resource is cancelled in the following cases, and then moved to the READY state.
WAITING State for a Semaphore Resource Cancel Operation
Return Value
The resource was returned to the target semaphore as a result of issuing sig_sem.
E_OK
The resource was returned to the target semaphore as a result of issuing isig_sem.
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*/
     ID      semid = ID_SEM1;    /*Declares and initializes variable*/
 
 
     ercd = wai_sem (semid);     /*Acquire semaphore resource (waiting forever)*/
 
     if (ercd == E_OK) {
         .........               /*Normal termination processing*/
     } else if (ercd == E_RLWAI) {
         .........               /*Forced termination processing*/
         .........
     }
 
 }

Note Invoking tasks are queued to the target semaphore wait queue in the order defined during configuration (FIFO order or priority order).
- pol_sem, ipol_sem
This service call acquires a resource from the semaphore specified by parameter semid (subtracts 0x1 from the semaphore counter).
If a resource could not be acquired from the target semaphore (semaphore counter is set to 0x0) when this service call is issued, the counter manipulation processing is not performed but "E_TMOUT" 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      ercd;                   /*Declares variable*/
     ID      semid = ID_SEM1;        /*Declares and initializes variable*/
 
 
     ercd = pol_sem (semid);         /*Acquire semaphore resource (polling)*/
 
     if (ercd == E_OK) {
         .........                   /*Polling success processing*/
     } else if (ercd == E_TMOUT) {
         .........                   /*Polling failure processing*/
     }
 
     .........
 }

- twai_sem
This service call acquires a resource from the semaphore specified by parameter semid (subtracts 0x1 from the semaphore counter).
If no resources are acquired from the target semaphore when service call is issued this (no available resources exist), this service call does not acquire resources but queues the invoking task to the target semaphore wait queue and moves it from the RUNNING state to the WAITING state with timeout (resource acquisition wait state).
The WAITING state for a semaphore resource is cancelled in the following cases, and then moved to the READY state.
WAITING State for a Semaphore Resource Cancel Operation
Return Value
The resource was returned to the target semaphore as a result of issuing sig_sem.
E_OK
The resource was returned to the target semaphore as a result of issuing isig_sem.
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*/
     ID      semid = ID_SEM1;        /*Declares and initializes variable*/
     TMO     tmout = 3600;           /*Declares and initializes variable*/
 
 
     ercd = twai_sem (semid, tmout); /*Acquire semaphore resource (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 1 Invoking tasks are queued to the target semaphore wait queue in the order defined during configuration (FIFO order or priority order).
Note 2 TMO_FEVR is specified for wait time tmout, processing equivalent to wai_sem will be executed. When TMO_POL is specified, processing equivalent to pol_sem /ipol_sem will be executed.
5.2.3 Release semaphore resource
A resource is returned by issuing the following service call from the processing program.
- sig_sem, isig_sem
These service calls return the resource to the semaphore specified by parameter semid (adds 0x1 to the semaphore counter).
If a task is queued in the wait queue of the target semaphore when this service call is issued, the counter manipulation processing is not performed but the resource is passed to the relevant task (first task of wait queue).
As a result, the relevant task is unlinked from the wait queue and is moved from the WAITING state (WAITING state for a semaphore resource) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED 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      semid = ID_SEM1;        /*Declares and initializes variable*/
 
     .........
 
     sig_sem (semid);                /*Release semaphore resource*/
 
     .........
 }

Note With the RI850V4, the maximum possible number of semaphore resources (maximum resource count) is defined during configuration. If the number of resources exceeds the specified maximum resource count, this service call therefore does not return the acquired resources (addition to the semaphore counter value) but returns E_QOVR.
5.2.4 Reference semaphore state
A semaphore status is referenced by issuing the following service call from the processing program.
- ref_sem, iref_sem
Stores semaphore state packet (ID number of the task at the head of the wait queue, current resource count, etc.) of the semaphore specified by parameter semid in the area specified by parameter pk_rsem.
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      semid = ID_SEM1;        /*Declares and initializes variable*/
     T_RSEM  pk_rsem;                /*Declares data structure*/
     ID      wtskid;                 /*Declares variable*/
     UINT    semcnt;                 /*Declares variable*/
     ATR     sematr;                 /*Declares variable*/
     UINT    maxsem;                 /*Declares variable*/
 
     .........
 
     ref_sem (semid, &pk_rsem);      /*Reference semaphore state*/
 
     wtskid = pk_rsem.wtskid;        /*Reference ID number of the task at the */
                                     /*head of the wait queue*/
     semcnt = pk_rsem.semcnt;        /*Reference current resource count*/
     sematr = pk_rsem.sematr;        /*Reference attribute*/
     maxsem = pk_rsem.maxsem;        /*Reference maximum resource count*/
 
     .........
 }

Note For details about the semaphore state packet, refer to "15.2.3 Semaphore state packet".