5.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 RI850V4 therefore provides the data queues that have the data queue area in which data read/write is enabled for transferring the prescribed size of data.

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

Figure 5-3 Processing Flow (Data Queue)

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

5.4.1 Create data queue

In the RI850V4, the method of creating a data queue is limited to "static creation".

Data queues therefore cannot be created dynamically using a method such as issuing a service call from a processing program.

Static data queue creation means defining of data queues using static API "CRE_DTQ" in the system configuration file.

For details about the static API "CRE_DTQ", refer to "17.5.4 Data queue information".

5.4.2 Send to data queue

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

- snd_dtq
This service call writes data specified by parameter data to the data queue area of the data queue specified by parameter dtqid.
If there is no available space for writing data in the data queue area of the target data queue when this service call is issued, this service call does not write data but 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, and then moved to the READY state.

Sending WAITING State for a Data Queue Cancel Operation	Return Value
Available space was secured in the data queue area of the target data queue as a result of issuing rcv_dtq.	E_OK
Available space was secured in the data queue area of the target data queue as a result of issuing prcv_dtq.	E_OK
Available space was secured in the data queue area of the target data queue as a result of issuing iprcv_dtq.	E_OK
Available space was secured in the data queue area of the target data queue 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

If a task has been queued to the reception wait queue of the target data queue when this service call is issued, this service call does not write data but transfers the data to the task. 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.
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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ ercd = snd_dtq (dtqid, data); /*Send to data queue (waiting forever)*/ 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 of the target data queue 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 during configuration (FIFO order or priority order).

- psnd_dtq, ipsnd_dtq
These service calls write data specified by parameter data to the data queue area of the data queue specified by parameter dtqid.
If there is no available space for writing data in the data queue area of the target data queue when either of these service calls is issued, data is not written but E_TMOUT is returned.
If a task has been queued to the reception wait queue of the target data queue when this service call is issued, this service call does not write data but transfers the data to the task. 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.
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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ ......... /*Send to data queue (polling)*/ ercd = psnd_dtq (dtqid, data); if (ercd == E_OK) { ......... /*Polling success processing*/ } else if (ercd == E_TMOUT) { ......... /*Polling failure processing*/ } ......... }

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

- tsnd_dtq
This service call writes data specified by parameter data to the data queue area of the data queue specified by parameter dtqid.
If there is no available space for writing data in the data queue area of the target data queue when this service call is issued, the service call does not write data but 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, and then moved to the READY state.

Sending WAITING State for a Data Queue Cancel Operation	Return Value
An available space was secured in the data queue area of the target data queue as a result of issuing rcv_dtq.	E_OK
An available space was secured in the data queue area of the target data queue as a result of issuing prcv_dtq.	E_OK
An available space was secured in the data queue area of the target data queue as a result of issuing iprcv_dtq.	E_OK
An available space was secured in the data queue area of the target data queue 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
Polling failure or timeout.	E_TMOUT

If a task has been queued to the reception wait queue of the target data queue when this service call is issued, this service call does not write data but transfers the data to the task. 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.
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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ TMO tmout = 3600; /*Declares and initializes variable*/ ......... /*Send to data queue (with timeout)*/ 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) { ......... /*Timeout processing*/ } ......... }

Note 1 Data is written to the data queue area of the target data queue 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 during configuration (FIFO order or 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 /ipsnd_dtq will be executed.

5.4.3 Forced send to data queue

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

- fsnd_dtq, ifsnd_dtq
These service calls write data specified by parameter data to the data queue area of the data queue specified by parameter dtqid.
If there is no available space for writing data in the data queue area of the target data queue when either of these service calls is issued, the service call overwrites data to the area with the oldest data that was written.
If a task has been queued to the reception wait queue of the target data queue when this service call is issued, this service call does not write data but transfers the data to the task. 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.
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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT data = 123; /*Declares and initializes variable*/ ......... fsnd_dtq (dtqid, data); /*Forced send to data queue*/ ......... }

5.4.4 Receive from data queue

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

- rcv_dtq
This service call reads data in the data queue area of the data queue specified by parameter dtqid and stores it to the area specified by parameter p_data.
If no data could be read from the data queue area of the target data queue (no data has been written to the data queue area) when this service call is issued, the service call does not read data but 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, and then moved to the READY state.

Receiving WAITING State for a Data Queue Cancel Operation	Return Value
Data was written to the data queue area of the target data queue as a result of issuing snd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing psnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing ipsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing tsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing fsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue 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 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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ ......... /*Receive from data queue (waiting forever)*/ 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 If the receiving WAITING state for a data queue is forcibly released by issuing rel_wai or irel_wai, the contents of the area specified by parameter p_data will be undefined.

- prcv_dtq, iprcv_dtq
These service calls read data in the data queue area of the data queue specified by parameter dtqid and stores it to the area specified by parameter p_data.
If no data could be read from the data queue area of the target data queue (no data has been written to the data queue area) when either of these service calls is issued, the service call does not read data 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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ ......... /*Receive from data queue (polling)*/ ercd = prcv_dtq (dtqid, &p_data); if (ercd == E_OK) { ......... /*Polling success processing*/ } else if (ercd == E_TMOUT) { ......... /*Polling failure processing*/ } ......... }

Note If no data could be read from the data queue area of the target data queue (no data has been written to the data queue area) when either of these service calls is issued, the contents in the area specified by parameter p_data become undefined.

- trcv_dtq
This service call reads data in the data queue area of the data queue specified by parameter dtqid and stores it to the area specified by parameter p_data.
If no data could be read from the data queue area of the target data queue (no data has been written to the data queue area) when this service call is issued, the service call does not read data but 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 out (data reception wait state).
The receiving WAITING state for a data queue is cancelled in the following cases, and then moved to the READY state.

Receiving WAITING State for a Data Queue Cancel Operation	Return Value
Data was written to the data queue area of the target data queue as a result of issuing snd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing psnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing ipsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing tsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue as a result of issuing fsnd_dtq.	E_OK
Data was written to the data queue area of the target data queue 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
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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ VP_INT p_data; /*Declares variable*/ TMO tmout = 3600; /*Declares and initializes variable*/ ......... /*Receive from data queue (with timeout)*/ 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) { ......... /*Timeout 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 If the data reception wait state is cancelled because rel_wai or irel_wai was issued or the wait time elapsed, the contents in the area specified by parameter p_data become undefined.

Note 3 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 /iprcv_dtq will be executed.

5.4.5 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 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 dtqid = ID_DTQ1; /*Declares and initializes variable*/ T_RDTQ pk_rdtq; /*Declares data structure*/ ID stskid; /*Declares variable*/ ID rtskid; /*Declares variable*/ UINT sdtqcnt; /*Declares variable*/ ATR dtqatr; /*Declares variable*/ UINT dtqcnt; /*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*/ dtqatr = pk_rdtq.dtqatr; /*Reference attribute*/ dtqcnt = pk_rdtq.dtqcnt; /*Reference data count*/ ......... }

Note For details about the data queue state packet, refer to "15.2.5 Data queue state packet".