7.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 RI600PX 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 7-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 RI600PX, 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
The message must be generated in the memory objects that both transmitting task and receiving task can access.
However, the management table exists in the top of message area. The system operation cannot be guaranteed if the management table is destroyed. For this reason, data queue or message buffer is recommended for message communication.
- Basic form of messages
In the RI600PX, 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; /*RI600PX 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; /*RI600PX 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 RI600PX, a message having a smaller priority number is given a higher priority.
Mailboxes are created by one of the following methods.
1 ) Creation by the system configuration file
The static API mailbox[] described in the system configuration file creates a mailbox.
Refer to
20.14 Mailbox Information (mailbox[]) for the details of mailbox[].
2 ) Creation by
cre_mbx or
acre_mbx
The cre_mbx creates a mailbox with mailbox ID indicated by parameter
mbxid according to the content of parameter
pk_cmbx.
The acre_mbx creates a mailbox according to the content of parameter
pk_cmbx, and returns the created mailbox ID.
The information specified is shown below.
- Mailbox attribute (
mbxatr)
The following informations are specified as
mbxatr.
- The order of task wait queue (FIFO order or task current priority order)
- The order of message queue (FIFO order or message priority order)
- Maximum message priority (
maxmpri)
These service calls can be called from tasks that belong to
Trusted Domain.
The following describes an example for coding acre_mbx 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 mbxid; /*Declares variable*/
T_CMBX pk_cmbx = { /*Declares and initializes variable*/
TA_TFIFO|TA_MFIFO, /*Mailbox attribute (mbxatr)*/
1, /*Maximum message priority (maxmpri)*/
0 /*Reserved (mprihd)*/
};
/* ......... */
mbxid = acre_mbx ( &pk_cmbx ); /*Create mailbox/
/* ......... */
}
|
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".
-
del_mbx This service call deletes the mailbox specified by parameter
mbxid.
When there are waiting tasks for the target mailbox by using
rcv_mbx or
trcv_mbx, this service call cancels the WAITING state of the tasks and returns E_DLT as a return value of the
rcv_mbx or
trcv_mbx.
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 mbxid = 8; /*Declares and initializes variable*/
/* ......... */
ercd = del_mbx ( mbxid ); /*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".
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 cfg600px*/
#pragma task Task1 /*Refer to note 3*/
void Task1 (VP_INT exinf); /*Refer to note 3*/
void Task1 (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 "
7.5.1 Messages".
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.5.5 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).
|
|
Forced release from waiting (accept del_mbx 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 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 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 at creating the mailbox (FIFO order or current priority order).
Note 2 For details about the message packet T_MSG and T_MSG_PRI, refer to "
7.5.1 Messages".
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".
-
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 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 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 1 For details about the message packet T_MSG and T_MSG_PRI, refer to "
7.5.1 Messages".
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".
-
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.
|
|
Forced release from waiting (accept del_mbx 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 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 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 at creating the mailbox (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 "
7.5.1 Messages".
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.5.6 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 cfg600px*/
#pragma task Task1 /*Refer to note 2*/
void Task1 (VP_INT exinf); /*Refer to note 2*/
void Task1 (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*/
/* ......... */
}
|
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.
