5.5 Mailboxes
Multitask processing requires the inter-task communication function (message transfer function) that reports the processing result of a task to another task. The RI600V4 therefore provides the mailbox for transferring the start address of a message written in the shared memory area.
The following shows a processing flow when using a mailbox.
Figure 5-4 Processing Flow (Mailbox)
The information exchanged among processing programs via the mailbox is called "messages".
Messages can be transmitted to any processing program via the mailbox, but it should be noted that, in the case of the synchronization and communication functions of the RI600V4, only the start address of the message is handed over to the receiving processing program, but the message contents are not copied to a separate area.
- Message area
In the case of the RI600V4, it is recommended to use the memory area secured by issuing
get_mpf and
get_mpl for messages.
- Basic form of messages
In the RI600V4, the message contents and length are prescribed as follows, according to the attributes of the mailbox to be used.
- When using a mailbox with the TA_MFIFO attribute
The message must be started from the T_MSG structure. This area is used by the kernel. The use message should be arranged following the T_MSG structure.
The length of the message is prescribed among the processing programs that exchange data using the mailbox.
The following shows the basic form of coding TA_MFIFO attribute messages.
[ Message packet for TA_MFIFO attribute ]
/* T_MSG structure, which is defined in the kernel.h*/
typedef struct {
VP msghead; /*RI600V4 management area*/
} T_MSG;
/* Message structure defined by user*/
typedef struct {
T_MSG t_msg; /*T_MSG structure*/
B data[8]; /*User message*/
} USER_MSG;
|
- When using a mailbox with the TA_MPRI attribute
The message must be started from the T_MSG_PRI structure. The T_MSG_PRI.msgque is used by the kernel. The message priority should be set to T_MSG_PRI.msgpri.
The length of the message is prescribed among the processing programs that exchange data using the mailbox.
The following shows the basic form of coding TA_MPRI attribute messages.
[ Message packet for TA_MPRI attribute ]
/* T_MSG structure, which is defined in the kernel.h*/
typedef struct {
VP msghead; /*RI600V4 management area*/
} T_MSG;
/* T_MSG_PRI structure, which is defined in the kernel.h*/
typedef struct {
T_MSG msgque; /*Message header*/
PRI msgpri; /*Message priority*/
} T_MSG_PRI;
/* Message structure defined by user*/
typedef struct {
T_MSG_PRI t_msg; /*T_MSG_PRI structure*/
B data[8]; /*User message*/
} USER_MSG;
|
Note 1 In the RI600V4, a message having a smaller priority number is given a higher priority.
In the RI600V4, the method of creating a mailbox is limited to "static creation".
Mailboxes therefore cannot be created dynamically using a method such as issuing a service call from a processing program.
Static mailbox creation means defining of mailboxes using static API "mailbox[]" in the system configuration file.
A message is transmitted by issuing the following service call from the processing program.
-
snd_mbx,
isnd_mbx
This service call transmits the message specified by parameter
pk_msg to the mailbox specified by parameter
mbxid (queues the message in the wait queue).
If a task is queued to the target mailbox wait queue when this service call is issued, the message is not queued but handed over to the relevant task (first task of the wait queue).
As a result, the relevant task is unlinked from the wait queue and is moved from the WAITING state (receiving WAITING state for a mailbox) 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 cfg600*/
void task (VP_INT exinf)
{
ID mbxid = 1; /*Declares and initializes variable*/
T_MSG_PRI *pk_msg; /*Declares data structure*/
/* ......... */
/* ......... */ /*Secures memory area (for message)*/
pk_msg = ... /* and set the pointer to pk_msg*/
/* ......... */ /*Creates message (contents)*/
pk_msg->msgpri = 8; /*Initializes data structure*/
/*Send to mailbox*/
snd_mbx (mbxid, (T_MSG *) pk_msg);
/* ......... */
}
|
Note 1 Messages are queued to the target mailbox in the order defined by queuing method during configuration (FIFO order or message priority order).
Note 2 For details about the message packet T_MSG and T_MSG_PRI, refer to "
5.5.1 Messages".
5.5.4 Receive from mailbox
A message is received (infinite wait, polling, or with time-out) by issuing the following service call from the processing program.
-
rcv_mbx (Wait)
This service call receives a message from the mailbox specified by parameter
mbxid, and stores its start address in the area specified by parameter
ppk_msg.
If no message could be received from the target mailbox (no messages were queued to the wait queue) when this service call is issued, this service call does not receive messages but queues the invoking task to the target mailbox wait queue and moves it from the RUNNING state to the WAITING state (message reception wait state).
The receiving WAITING state for a mailbox is cancelled in the following cases.
Receiving WAITING State for a Mailbox Cancel Operation
|
|
A message was transmitted to the target mailbox as a result of issuing snd_mbx.
|
|
A message was transmitted to the target mailbox as a result of issuing isnd_mbx.
|
|
Forced release from waiting (accept rel_wai while waiting).
|
|
Forced release from waiting (accept irel_wai while waiting).
|
|
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 cfg600*/
void task (VP_INT exinf)
{
ER ercd; /*Declares variable*/
ID mbxid = 1; /*Declares and initializes variable*/
T_MSG *ppk_msg; /*Declares data structure*/
/* ......... */
/*Receive from mailbox*/
ercd = rcv_mbx (mbxid, &ppk_msg);
if (ercd == E_OK) {
/* ......... */ /*Normal termination processing*/
} else if (ercd == E_RLWAI) {
/* ......... */ /*Forced termination processing*/
}
/* ......... */
}
|
Note 1 Invoking tasks are queued to the target mailbox wait queue in the order defined during configuration (FIFO order or current priority order).
Note 2 For details about the message packet T_MSG and T_MSG_PRI, refer to "
5.5.1 Messages".
-
prcv_mbx,
iprcv_mbx (Polling)
This service call receives a message from the mailbox specified by parameter
mbxid, and stores its start address in the area specified by parameter
ppk_msg.
If the message could not be received from the target mailbox (no messages were queued in the wait queue) when this service call is issued, message reception processing is not executed 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 cfg600*/
void task (VP_INT exinf)
{
ER ercd; /*Declares variable*/
ID mbxid = 1; /*Declares and initializes variable*/
T_MSG *ppk_msg; /*Declares data structure*/
/* ......... */
/*Receive from mailbox*/
ercd = prcv_mbx (mbxid, &ppk_msg);
if (ercd == E_OK) {
/* ......... */ /*Polling success processing*/
} else if (ercd == E_TMOUT) {
/* ......... */ /*Polling failure processing*/
}
/* ......... */
}
|
Note For details about the message packet T_MSG and T_MSG_PRI, refer to "
5.5.1 Messages".
-
trcv_mbx (Wait with time-out)
This service call receives a message from the mailbox specified by parameter
mbxid, and stores its start address in the area specified by parameter
ppk_msg.
If no message could be received from the target mailbox (no messages were queued to the wait queue) when this service call is issued, this service call does not receive messages but queues the invoking task to the target mailbox wait queue and moves it from the RUNNING state to the WAITING state with time-out (message reception wait state).
The receiving WAITING state for a mailbox is cancelled in the following cases.
Receiving WAITING State for a Mailbox Cancel Operation
|
|
A message was transmitted to the target mailbox as a result of issuing snd_mbx.
|
|
A message was transmitted to the target mailbox as a result of issuing isnd_mbx.
|
|
Forced release from waiting (accept rel_wai while waiting).
|
|
Forced release from waiting (accept irel_wai while waiting).
|
|
The time specified by tmout has elapsed.
|
|
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 cfg600*/
void task (VP_INT exinf)
{
ER ercd; /*Declares variable*/
ID mbxid = 1; /*Declares and initializes variable*/
T_MSG *ppk_msg; /*Declares data structure*/
TMO tmout = 3600; /*Declares and initializes variable*/
/* ......... */
/*Receive from mailbox*/
ercd = trcv_mbx (mbxid, &ppk_msg, 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 target mailbox wait queue in the order defined during configuration (FIFO order or current priority order).
Note 2
TMO_FEVR is specified for wait time
tmout, processing equivalent to
rcv_mbx will be executed. When
TMO_POL is specified, processing equivalent to
prcv_mbx will be executed.
Note 3 For details about the message packet T_MSG and T_MSG_PRI, refer to "
5.5.1 Messages".
5.5.5 Reference mailbox state
A mailbox status is referenced by issuing the following service call from the processing program.
-
ref_mbx,
iref_mbx
Stores mailbox state packet (ID number of the task at the head of the wait queue, start address of the message packet at the head of the wait queue) of the mailbox specified by parameter
mbxid in the area specified by parameter
pk_rmbx.
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 cfg600*/
void task (VP_INT exinf)
{
ID mbxid = 1; /*Declares and initializes variable*/
T_RMBX pk_rmbx; /*Declares data structure*/
ID wtskid; /*Declares variable*/
T_MSG *pk_msg; /*Declares data structure*/
/* ......... */
ref_mbx (mbxid, &pk_rmbx); /*Reference mailbox state*/
wtskid = pk_rmbx.wtskid; /*Reference ID number of the task at the */
/*head of the wait queue*/
pk_msg = pk_rmbx.pk_msg; /*Reference start address of the message */
/*packet at the head of the wait queue*/
/* ......... */
}
|
