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.
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.
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.
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.
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.
- 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.
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.
Note 2 Values that can be specified as the message priority level are limited to the range defined by Maximum message priority (max_pri) in Mailbox Information (mailbox[])) when the system configuration file is created.
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.
- 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.
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).
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.
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.
#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).
- 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.
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*/ } /* ......... */ } |
- 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.
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.
#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.
- 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.
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*/ /* ......... */ } |