7.4 Data Queues

Multitask processing requires the inter-task communication function (data transfer function) that reports the processing result of a task to another task. The RI600PX therefore provides the data queues for transferring the prescribed size of data.

The following shows a processing flow when using a data queue.

Figure 7-3 Processing Flow (Data Queue)

Note Data units of 4 bytes are transmitted or received at a time.

7.4.1 Create data queue

Data queues are created by one of the following methods.

1 ) Creation by the system configuration file
The static API data_queue[] described in the system configuration file creates a data queue.
Refer to 20.13 Data Queue Information (dataqueue[]) for the details of data_queue[].

2 ) Creation by cre_dtq or acre_dtq
The cre_dtq creates a data queue with data queue ID indicated by parameter dtqid according to the content of parameter pk_cdtq.
The acre_dtq creates a data queue according to the content of parameter pk_cdtq, and returns the created data queue ID.
The information specified is shown below.

- Data queue attribute (dtqatr)
The following informations are specified as dtqatr.

- The order of task wait queue for sending (FIFO order or task current priority order)

- Capacity of the data queue area (dtqcnt), Start address of the data queue area (dtq)
The TSZ_DTQ(dtqcnt) bytes area from the address indicated by parameter dtq is used for the data queue area. Refer to 18.3.2 Macros for Data Queue for details of TSZ_DTQ macro.
The data queue area should be generated to the area other than memory objects and user stacks.

These service calls can be called from tasks that belong to Trusted Domain.
The following describes an example for coding acre_dtq as a representative.

#include "kernel.h" /*Standard header file definition*/ #include "kernel_id.h" /*Header file generated by cfg600px*/ #define DTQCNT 10 /*Capacity of the data queue area*/ /*(the number of data elements)*/ #pragma section B BRI_RAM /*Section for the data queue area*/ static UW dtq_area[ TSZ_DTQ(dtqcnt)/sizeof(UW)]; /*Data queue area*/ #pragma section #pragma task Task1 /*Refer to note*/ void Task1 (VP_INT exinf); /*Refer to note*/ void Task1 (VP_INT exinf) { ER dtqid; /*Declares variable*/ T_CDTQ pk_cdtq = { /*Declares and initializes variable*/ TA_TFIFO, /*Data queue attribute (dtqatr)*/ DTQCNT, /*Capacity of the data queue area (dtqcnt)*/ (VP)dtq_area /*Start address of the data queue area (dtq)*/ }; /* ......... */ dtqid = acre_dtq ( &pk_cdtq ); /*Create data queue/ /* ......... */ }

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.4.2 Delete data queue

- del_dtq
This service call deletes the data queue specified by parameter dtqid.
When there are waiting tasks for the target data queue by using snd_dtq, tsnd_dtq, rcv_dtq or trcv_dtq, this service call cancels the WAITING state of the tasks and returns E_DLT as a return value of the snd_dtq, tsnd_dtq, rcv_dtq or trcv_dtq.
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 dtqid = 8; /*Declares and initializes variable*/ /* ......... */ ercd = del_dtq ( dtqid ); /*Delete data queue*/ /* ......... */ }

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.4.3 Send to data queue

A data is transmitted by issuing the following service call from the processing program.

- snd_dtq (Wait)

- psnd_dtq, ipsnd_dtq (Polling)

- tsnd_dtq (Wait with time-out)

- snd_dtq (Wait)
This service call processes as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a task in the reception wait queue.
This service call transfers the data specified by parameter data to the task in the top of the reception wait queue. As a result, the task is unlinked from the reception wait queue and moves from the WAITING state (data reception wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.

- There is no task neither in the reception wait queue and transmission wait queue and there is available space in the data queue.
This service call stores the data specified by parameter data to the data queue.

- There is no task neither in the reception wait queue and transmission wait queue and there is no available space in the data queue, or there is a task in the transmission wait queue.
This service call queues the invoking task to the transmission wait queue of the target data queue and moves it from the RUNNING state to the WAITING state (data transmission wait state).
The sending WAITING state for a data queue is cancelled in the following cases.

Sending WAITING State for a Data Queue Cancel Operation	Return Value
Available space was secured in the data queue area as a result of issuing rcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing prcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing iprcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing trcv_dtq.	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 data queue is reset as a result of issuing vrst_dtq.	EV_RST
Forced release from waiting (accept del_dtq 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 dtqid = 1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ /* ......... */ ercd = snd_dtq (dtqid, data); /*Send to data queue*/ if (ercd == E_OK) { /* ......... */ /*Normal termination processing*/ } else if (ercd == E_RLWAI) { /* ......... */ /*Forced termination processing*/ } /* ......... */ }

Note 1 Data is written to the data queue area in the order of the data transmission request.

Note 2 Invoking tasks are queued to the transmission wait queue of the target data queue in the order defined at creating the data queue (FIFO order or current priority order).

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

- psnd_dtq, ipsnd_dtq (Polling)
These service calls process as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a task in the reception wait queue.
These service calls transfer the data specified by parameter data to the task in the top of the reception wait queue. As a result, the task is unlinked from the reception wait queue and moves from the WAITING state (data reception wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.

- There is no task neither in the reception wait queue and transmission wait queue and there is available space in the data queue.
These service calls store the data specified by parameter data to the data queue.

- There is no task neither in the reception wait queue and transmission wait queue and there is no available space in the data queue, or there is a task in the transmission wait queue.
These service calls return "E_TMOUT".

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 dtqid = 1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ /* ......... */ ercd = psnd_dtq (dtqid, data); /*Send to data queue* if (ercd == E_OK) { /* ......... */ /*Polling success processing*/ } else if (ercd == E_TMOUT) { /* ......... */ /*Polling failure processing*/ } /* ......... */ }

Note 1 Data is written to the data queue area in the order of the data transmission request.

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

- tsnd_dtq (Wait with time-out)
This service call processes as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a task in the reception wait queue.
This service call transfers the data specified by parameter data to the task in the top of the reception wait queue. As a result, the task is unlinked from the reception wait queue and moves from the WAITING state (data reception wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.

- There is no task neither in the reception wait queue and transmission wait queue and there is available space in the data queue.
This service call stores the data specified by parameter data to the data queue.

- There is no task neither in the reception wait queue and transmission wait queue and there is no available space in the data queue, or there is a task in the transmission wait queue.
This service call queues the invoking task to the transmission wait queue of the target data queue and moves it from the RUNNING state to the WAITING state with time (data transmission wait state).
The sending WAITING state for a data queue is cancelled in the following cases.

Sending WAITING State for a Data Queue Cancel Operation	Return Value
Available space was secured in the data queue area as a result of issuing rcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing prcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing iprcv_dtq.	E_OK
Available space was secured in the data queue area as a result of issuing trcv_dtq.	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 data queue is reset as a result of issuing vrst_dtq.	EV_RST
The time specified by tmout has elapsed.	E_TMOUT
Forced release from waiting (accept del_dtq 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 4*/ void Task1 (VP_INT exinf); /*Refer to note 4*/ void Task1 (VP_INT exinf) { ER ercd; /*Declares variable*/ ID dtqid = 1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ TMO tmout = 3600; /*Declares and initializes variable*/ /* ......... */ /*Send to data queue*/ ercd = tsnd_dtq (dtqid, data, tmout); if (ercd == E_OK) { /* ......... */ /*Normal termination processing*/ } else if (ercd == E_RLWAI) { /* ......... */ /*Forced termination processing*/ } else if (ercd == E_TMOUT) { /* ......... */ /*Time-out processing*/ } /* ......... */ }

Note 1 Data is written to the data queue area in the order of the data transmission request.

Note 2 Invoking tasks are queued to the transmission wait queue of the target data queue in the order defined at creating the data queue (FIFO order or current priority order).

Note 3 TMO_FEVR is specified for wait time tmout, processing equivalent to snd_dtq will be executed. When TMO_POL is specified, processing equivalent to psnd_dtq will be executed.

Note 4 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.4.4 Forced send to data queue

Data is forcibly transmitted by issuing the following service call from the processing program.

- fsnd_dtq, ifsnd_dtq
This service call processes as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a task in the reception wait queue.
This service call transfers the data specified by parameter data to the task in the top of the reception wait queue. As a result, the task is unlinked from the reception wait queue and moves from the WAITING state (data reception wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.

- There is no task neither in the reception wait queue and transmission wait queue.
This service call stores the data specified by parameter data to the data queue.
If there is no available space in the data queue, this service call deletes the oldest data in the data queue before storing the data specified by data to the data queue.

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 dtqid = 1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ /* ......... */ fsnd_dtq (dtqid, data); /*Forced send to data queue*/ /* ......... */ }

Note 1 Data is written to the data queue area in the order of the data transmission request.

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.4.5 Receive from data queue

A data is received (waiting forever, polling, or with time-out) by issuing the following service call from the processing program.

- rcv_dtq (Wait)

- prcv_dtq, iprcv_dtq (Polling)

- trcv_dtq (Wait with time-out)

- rcv_dtq (Wait)
This service call processes as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a data in the data queue.
This service call takes out the oldest data from the data queue and stores the data to the area specified by p_data.
When there is a task in the transmission wait queue, this service call stores the data sent by the task in the top of the transmission wait queue and moves it from the WAITING state (data transmission wait state) to the READY state.

- There is no data in the data queue and there is a task in the transmission wait queue.
This service call stores the data specified by the task in the top of the transmission wait queue to the area specified by p_data. As a result, the task is unlinked from the transmission wait queue and moves from the WAITING state (data transmission wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
Note, this situation is caused only when the capacity of the data queue is 0.

- There is no data in the data queue and there is no task in the transmission wait queue.
This service call queues the invoking task to the reception wait queue of the target data queue and moves it from the RUNNING state to the WAITING state (data reception wait state).
The receiving WAITING state for a data queue is cancelled in the following cases.

Receiving WAITING State for a Data Queue Cancel Operation	Return Value
Data was sent to the data queue area as a result of issuing snd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing psnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing ipsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing tsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing fsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing ifsnd_dtq.	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_dtq 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 dtqid = 1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ /* ......... */ /*Receive from data queue*/ ercd = rcv_dtq (dtqid, &p_data); if (ercd == E_OK) { /* ......... */ /*Normal termination processing*/ } else if (ercd == E_RLWAI) { /* ......... */ /*Forced termination processing*/ } /* ......... */ }

Note 1 Invoking tasks are queued to the reception wait queue of the target data queue in the order of the data reception request.

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

- prcv_dtq, iprcv_dtq (Polling)
These service calls process as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a data in the data queue.
This service call takes out the oldest data from the data queue and stores the data to the area specified by p_data.
When there is a task in the transmission wait queue, this service call stores the data sent by the task in the top of the transmission wait queue and moves it from the WAITING state (data transmission wait state) to the READY state.

- There is no data in the data queue and there is a task in the transmission wait queue.
These service calls store the data specified by the task in the top of the transmission wait queue to the area specified by p_data. As a result, the task is unlinked from the transmission wait queue and moves from the WAITING state (data transmission wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
Note, this situation is caused only when the capacity of the data queue is 0.

- There is no data in the data queue and there is no task in the transmission wait queue.
These service calls return "E_TMOUT".

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 dtqid = 1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ /* ......... */ /*Receive from data queue*/ ercd = prcv_dtq (dtqid, &p_data); if (ercd == E_OK) { /* ......... */ /*Polling success processing*/ } 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".

- trcv_dtq (Wait with time-out)
This service call processes as follows according to the situation of the data queue specified by the parameter dtqid.

- There is a data in the data queue.
This service call takes out the oldest data from the data queue and stores the data to the area specified by p_data.
When there is a task in the transmission wait queue, this service call stores the data sent by the task in the top of the transmission wait queue and moves it from the WAITING state (data transmission wait state) to the READY state.

- There is no data in the data queue and there is a task in the transmission wait queue.
This service call stores the data specified by the task in the top of the transmission wait queue to the area specified by p_data. As a result, the task is unlinked from the transmission wait queue and moves from the WAITING state (data transmission wait state) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
Note, this situation is caused only when the capacity of the data queue is 0.

- There is no data in the data queue and there is no task in the transmission wait queue.
This service call queues the invoking task to the reception wait queue of the target data queue and moves it from the RUNNING state to the WAITING state with time (data reception wait state).
The receiving WAITING state for a data queue is cancelled in the following cases.

Receiving WAITING State for a Data Queue Cancel Operation	Return Value
Data was sent to the data queue area as a result of issuing snd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing psnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing ipsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing tsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing fsnd_dtq.	E_OK
Data was sent to the data queue area as a result of issuing ifsnd_dtq.	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_dtq 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 dtqid = 1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ TMO tmout = 3600; /*Declares and initializes variable*/ /* ......... */ /*Receive from data queue*/ ercd = trcv_dtq (dtqid, &p_data, tmout); if (ercd == E_OK) { /* ......... */ /*Normal termination processing*/ } else if (ercd == E_RLWAI) { /* ......... */ /*Forced termination processing*/ } else if (ercd == E_TMOUT) { /* ......... */ /*Time-out processing*/ } /* ......... */ }

Note 1 Invoking tasks are queued to the reception wait queue of the target data queue in the order of the data reception request.

Note 2 TMO_FEVR is specified for wait time tmout, processing equivalent to rcv_dtq will be executed. When TMO_POL is specified, processing equivalent to prcv_dtq 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.4.6 Reference data queue state

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

- ref_dtq, iref_dtq
These service calls store the detailed information of the data queue (existence of waiting tasks, number of data elements in the data queue, etc.) specified by parameter dtqid into the area specified by parameter pk_rdtq.
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 dtqid = 1; /*Declares and initializes variable*/ T_RDTQ pk_rdtq; /*Declares data structure*/ ID stskid; /*Declares variable*/ ID rtskid; /*Declares variable*/ UINT sdtqcnt; /*Declares variable*/ /* ......... */ ref_dtq (dtqid, &pk_rdtq); /*Reference data queue state*/ stskid = pk_rdtq.stskid; /*Acquires existence of tasks waiting for */ /*data transmission*/ rtskid = pk_rdtq.rtskid; /*Acquires existence of tasks waiting for */ /*data reception*/ sdtqcnt = pk_rdtq.sdtqcnt; /*Reference the number of data elements in */ /*data queue*/ /* ......... */ }

Note 1 For details about the data queue state packet, refer to "[Data queue state packet: T_RDTQ]".

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