5.5 Mailboxes
The RI850V4 provides a mailbox, as a communication function between tasks, that hands over the execution result of a given processing program to another processing program.
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 RI850V4, 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.
- Securement of memory area
In the case of the RI850V4, it is recommended to use the memory area secured by issuing service calls such as get_mpf and get_mpl for messages.
In the case of the RI850V4, it is recommended to use the memory area secured by issuing service calls such as get_mpf and get_mpl for messages.
Note The RI850V4 uses the message start area as a link area during queuing to the wait queue for mailbox messages. Therefore, if the memory area for messages is secured from other than the memory area controlled by the RI850V4, it must be secured from 4-byte aligned addresses.
- Basic form of messages
In the RI850V4, the message contents and length are prescribed as follows, according to the attributes of the mailbox to be used.
In the RI850V4, 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 contents and length past the first 4 bytes of a message (system reserved area msgnext) are not restricted in particular in the RI850V4.
Therefore, the contents and length past the first 4 bytes are prescribed among the processing programs that exchange data using the mailbox with the TA_MFIFO attribute.
The following shows the basic form of coding TA_MFIFO attribute messages in C.
The contents and length past the first 4 bytes of a message (system reserved area msgnext) are not restricted in particular in the RI850V4.
Therefore, the contents and length past the first 4 bytes are prescribed among the processing programs that exchange data using the mailbox with the TA_MFIFO attribute.
The following shows the basic form of coding TA_MFIFO attribute messages in C.
- When using a mailbox with the TA_MPRI attribute
The contents and length past the first 8 bytes of a message (system reserved area msgque, priority level msgpri) are not restricted in particular in the RI850V4.
Therefore, the contents and length past the first 8 bytes are prescribed among the processing programs that exchange data using the mailbox with the TA_MPRI attribute.
The following shows the basic form of coding TA_MPRI attribute messages in C.
The contents and length past the first 8 bytes of a message (system reserved area msgque, priority level msgpri) are not restricted in particular in the RI850V4.
Therefore, the contents and length past the first 8 bytes are prescribed among the processing programs that exchange data using the mailbox with the TA_MPRI attribute.
The following shows the basic form of coding TA_MPRI attribute messages in C.
typedef struct t_msg_pri { struct t_msg msgque; /*Reserved for future use*/ PRI msgpri; /*Message priority*/ } T_MSG_PRI; |
Note 2 Values that can be specified as the message priority level are limited to the range defined in Mailbox information (Maximum message priority: maxmpri) 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 "CRE_MBX" 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 this service call.
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 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 mbxid = ID_MBX1; /*Declares and initializes variable*/ T_MSG_PRI *pk_msg; /*Declares data structure*/ ......... ......... /*Secures memory area (for message)*/ ......... /*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 wait queue in the order defined by queuing method during configuration (FIFO order or priority order).
Note 2 With the RI850V4 mailbox, 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. The message contents can therefore be rewritten even after this service call is issued.
A message is received (infinite wait, polling, or with timeout) by issuing the following service call from the processing program.
- rcv_mbx
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, and then moved to the READY state.
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, and then moved to the READY state.
#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 mbxid = ID_MBX1; /*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 priority order).
Note 2 If the receiving WAITING state for a mailbox is forcibly released by issuing rel_wai or irel_wai, the contents of the area specified by parameter ppk_msg will be undefined.
- prcv_mbx, iprcv_mbx
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 this service call.
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 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 mbxid = ID_MBX1; /*Declares and initializes variable*/ T_MSG *ppk_msg; /*Declares data structure*/ ......... /*Receive from mailbox (polling)*/ ercd = prcv_mbx (mbxid, &ppk_msg); if (ercd == E_OK) { ......... /*Polling success processing*/ } else if (ercd == E_TMOUT) { ......... /*Polling failure processing*/ } ......... } |
Note 1 If no message could be received from the target mailbox (no messages were queued to the wait queue) when this service call is issued, the contents in the area specified by parameter ppk_msg become undefined.
- trcv_mbx
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 timeout (message reception wait state).
The receiving WAITING state for a mailbox is cancelled in the following cases, and then moved to the READY state.
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 timeout (message reception wait state).
The receiving WAITING state for a mailbox is cancelled in the following cases, and then moved to the READY state.
#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 mbxid = ID_MAX1; /*Declares and initializes variable*/ T_MSG *ppk_msg; /*Declares data structure*/ TMO tmout = 3600; /*Declares and initializes variable*/ ......... /*Receive from mailbox (with timeout)*/ 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) { ......... /*Timeout processing*/ } ......... } |
Note 1 Invoking tasks are queued to the target mailbox wait queue in the order defined during configuration (FIFO order or priority order).
Note 2 If the message 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 ppk_msg become undefined.
Note 3 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 /iprcv_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 this service call.
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 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 mbxid = ID_MBX1; /*Declares and initializes variable*/ T_RMBX pk_rmbx; /*Declares data structure*/ ID wtskid; /*Declares variable*/ T_MSG *pk_msg; /*Declares data structure*/ ATR mbxatr; /*Declares variable*/ ......... 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*/ mbxatr = pk_rmbx.mbxatr; /*Reference attribute*/ ......... } |