Everything

CHAPTER 7 SYNCHRONIZATION AND COMMUNICATION FUNCTIONS


This chapter describes the synchronization and communication functions performed by the RI600PX.
7.1 Outline
The synchronization and communication functions of the RI600PX consist of Semaphores, Eventflags, Data Queues, and Mailboxes that are provided as means for realizing exclusive control, queuing, and communication among tasks.
7.2 Semaphores
In the RI600PX, 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 7-1 Processing Flow (Semaphore)
7.2.1 Create semaphore
Semaphores are created by one of the following methods.
1 ) Creation by the system configuration file
The static API semaphore[] described in the system configuration file creates a semaphore.
Refer to 20.11 Semaphore Information (semaphore[]) for the details of semaphore[].
2 ) Creation by cre_sem or acre_sem
The cre_sem creates a semaphore with semaphore ID indicated by parameter semid according to the content of parameter pk_csem.
The acre_sem creates a semaphore according to the content of parameter pk_csem, and returns the created semaphore ID.
The information specified is shown below.
- Semaphore attribute (sematr)
The following informations are specified as sematr.
- The order of task wait queue (FIFO order or task current priority order)
- Initial semaphore count (isemcnt)
- Maximum semaphore count (maxsem)
These service calls can be called from tasks that belong to Trusted Domain.
The following describes an example for coding acre_sem as a representative.
 #include    "kernel.h"              /*Standard header file definition*/
 #include    "kernel_id.h"           /*Header file generated by cfg600px*/
 #pragma task Task1                  /*Refer to note*/
 void Task1 (VP_INT exinf);          /*Refer to note*/
 void Task1 (VP_INT exinf)
 {
     ER      semid;              /*Declares variable*/
     T_CSEM  pk_csem = {         /*Declares and initializes variable*/
         TA_TFIFO,                   /*Semaphore attribute (sematr)*/
         1,                          /*Initial semaphore count (isemcnt)*/
         0                           /*Maximum semaphore count (maxsem)*/
     };
 
     /* ......... */
 
     semid = acre_sem ( &pk_csem );  /*Create semaphore/
 
     /* ......... */
 }

Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
7.2.2 Delete semaphore
- del_sem
This service call deletes the semaphore specified by parameter semid.
When there are waiting tasks for the target semaphore by using wai_sem or twai_sem, this service call cancels the WAITING state of the tasks and returns E_DLT as a return value of the wai_sem or twai_sem.
This service call can be called from tasks that belong to Trusted Domain.
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 cfg600px*/
 #pragma task Task1                  /*Refer to note*/
 void Task1 (VP_INT exinf);          /*Refer to note*/
 void Task1 (VP_INT exinf)
 {
     ID      semid = 8;          /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = del_sem ( semid );   /*Delete semaphore*/
 
     /* ......... */
 }

Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
7.2.3 Acquire semaphore resource
A resource is acquired (waiting forever, polling, or with time-out) by issuing the following service call from the processing program.
- wai_sem (Wait)
- pol_sem, ipol_sem (Polling)
- twai_sem (Wait with time-out)
- wai_sem (Wait)
This service call acquires a resource from the semaphore specified by parameter semid (subtracts 1 from the semaphore counter).
When 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.
WAITING State for a Semaphore Resource Cancel Operation
Return Value
The resource was released to the target semaphore as a result of issuing sig_sem.
E_OK
The resource was released 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
Forced release from waiting (accept del_sem while waiting).
E_DLT

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 cfg600px*/
 #pragma task Task1                  /*Refer to note 2*/
 void Task1 (VP_INT exinf);          /*Refer to note 2*/
 void Task1 (VP_INT exinf)
 {
     ER      ercd;               /*Declares variable*/
     ID      semid = 1;          /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = wai_sem (semid );    /*Acquire semaphore resource*/
 
     if (ercd == E_OK) {
         /* ......... */         /*Normal termination processing*/
 
         sig_sem ( semid );      /*Release semaphore resource*/
     } else if (ercd == E_RLWAI) {
         /* ......... */         /*Forced termination processing*/
     }
 
     /* ......... */
 }

Note 1 Invoking tasks are queued to the target semaphore wait queue in the order defined at creating the semaphore (FIFO order or current priority order).
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- pol_sem, ipol_sem (Polling)
These service calls acquire a resource from the semaphore specified by parameter semid (subtracts 1 from the semaphore counter).
If a resource could not be acquired from the target semaphore (semaphore counter is set to 0) when these service calls are issued, the counter manipulation processing is not performed but E_TMOUT 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 cfg600px*/
 #pragma task Task1                  /*Refer to note*/
 void Task1 (VP_INT exinf);          /*Refer to note*/
 void Task1 (VP_INT exinf)
 {
     ER      ercd;                   /*Declares variable*/
     ID      semid = 1;              /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = pol_sem (semid);         /*Acquire semaphore resource*/
 
     if (ercd == E_OK) {
         /* ......... */             /*Polling success processing*/
 
         sig_sem ( semid );          /*Release semaphore resource*/
     } else if (ercd == E_TMOUT) {
         /* ......... */             /*Polling failure processing*/
     }
 
     /* ......... */
 }

Note These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
- twai_sem (Wait with time-out)
This service call acquires a resource from the semaphore specified by parameter semid (subtracts 1 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 time-out (resource acquisition wait state).
The WAITING state for a semaphore resource is cancelled in the following cases.
WAITING State for a Semaphore Resource Cancel Operation
Return Value
The resource was released to the target semaphore as a result of issuing sig_sem.
E_OK
The resource was released 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 time specified by tmout has elapsed.
E_TMOUT
Forced release from waiting (accept del_sem while waiting).
E_DLT

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 cfg600px*/
 #pragma task Task1                  /*Refer to note 3*/
 void Task1 (VP_INT exinf);          /*Refer to note 3*/
 void Task1 (VP_INT exinf)
 {
     ER      ercd;                   /*Declares variable*/
     ID      semid = 1;              /*Declares and initializes variable*/
     TMO     tmout = 3600;           /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = twai_sem (semid, tmout); /*Acquire semaphore resource*/
 
     if (ercd == E_OK) {
         /* ......... */             /*Normal termination processing*/
 
         sig_sem ( semid );          /*Release semaphore resource*/
     } else if (ercd == E_RLWAI) {
         /* ......... */             /*Forced termination processing*/
     } else if (ercd == E_TMOUT) {
         /* ......... */             /*Time-out processing*/
     }
 
     /* ......... */
 }

Note 1 Invoking tasks are queued to the target semaphore wait queue in the order defined at creating the semaphore (FIFO order or current 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 will be executed.
Note 3 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
7.2.4 Release semaphore resource
A resource is released by issuing the following service call from the processing program.
- sig_sem, isig_sem
These service calls releases the resource to the semaphore specified by parameter semid (adds 1 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 these service calls.
 #include    "kernel.h"          /*Standard header file definition*/
 #include    "kernel_id.h"       /*Header file generated by cfg600px*/
 #pragma task Task1              /*Refer to note 2*/
 void Task1 (VP_INT exinf);      /*Refer to note 2*/
 void Task1 (VP_INT exinf)
 {
     ER      ercd;               /*Declares variable*/
     ID      semid = 1;          /*Declares and initializes variable*/
 
     /* ......... */
 
     ercd = wai_sem (semid );    /*Acquire semaphore resource*/
 
     if (ercd == E_OK) {
         /* ......... */         /*Normal termination processing*/
 
         sig_sem ( semid );      /*Release semaphore resource*/
     } else if (ercd == E_RLWAI) {
         /* ......... */         /*Forced termination processing*/
     }
 
     /* ......... */
 }

Note 1 With the RI600PX, 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 release the acquired resources (addition to the semaphore counter value) but returns E_QOVR.
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".
7.2.5 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 these service calls.
 #include    "kernel.h"            /*Standard header file definition*/
 #include    "kernel_id.h"         /*Header file generated by cfg600px*/
 #pragma task Task1                /*Refer to note 2*/
 void Task1 (VP_INT exinf);        /*Refer to note 2*/
 void Task1 (VP_INT exinf)
 {
     ID      semid = 1;            /*Declares and initializes variable*/
     T_RSEM  pk_rsem;              /*Declares variable*/
     ID      wtskid;               /*Declares variable*/
     UINT    semcnt;               /*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*/
 
     /* ......... */
 }

Note 1 For details about the semaphore state packet, refer to "[Semaphore state packet: T_RSEM]".
Note 2 These statements are unnecessary for the task which is created by the system configuration file because the cfg600px generates these statement into the "kernel_id.h".