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.
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.
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.
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.
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.
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[].
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.
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.
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.
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.
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".
- 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 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 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".
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 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 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.
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 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.
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 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 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".
- 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 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*/ /* ......... */ } |