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.

The following shows a processing flow when using a mailbox.

Figure 5-4 Processing Flow (Mailbox)

5.5.1 Messages

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 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.

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.

- 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.

[Message packet for TA_MFIFO attribute ]

typedef struct t_msg { struct t_msg *msgnext; /*Reserved for future use*/ } T_MSG;

- 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.

[Message packet for TA_MPRI attribute]

typedef struct t_msg_pri { struct t_msg msgque; /*Reserved for future use*/ PRI msgpri; /*Message priority*/ } T_MSG_PRI;

Note 1 In the RI850V4, a message having a smaller priority number is given a higher priority.

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.

Note 3 For details about the message packet, refer to "15.2.6 Message packet".

5.5.2 Create mailbox

In the RI850V4, 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 "CRE_MBX" in the system configuration file.

For details about the static API "CRE_MBX", refer to "17.5.5 Mailbox information".

5.5.3 Send to mailbox

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 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.

Note 3 For details about the message packet, refer to "15.2.6 Message packet".

5.5.4 Receive from mailbox

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.

Receiving WAITING State for a Mailbox Cancel Operation	Return Value
A message was transmitted to the target mailbox as a result of issuing snd_mbx.	E_OK
A message was transmitted to the target mailbox as a result of issuing isnd_mbx.	E_OK
Forced release from waiting (accept rel_wai while waiting).	E_RLWAI
Forced release from waiting (accept irel_wai while waiting).	E_RLWAI

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*/ 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.

Note 3 For details about the message packet, refer to "15.2.6 Message packet".

- 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.

#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.

Note 2 For details about the message packet, refer to "15.2.6 Message packet".

- 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.

Receiving WAITING State for a Mailbox Cancel Operation	Return Value
A message was transmitted to the target mailbox as a result of issuing snd_mbx.	E_OK
A message was transmitted to the target mailbox as a result of issuing isnd_mbx.	E_OK
Forced release from waiting (accept rel_wai while waiting).	E_RLWAI
Forced release from waiting (accept irel_wai while waiting).	E_RLWAI
Polling failure or timeout.	E_TMOUT

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_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.

Note 4 For details about the message packet, refer to "15.2.6 Message packet".

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

Note For details about the mailbox state packet, refer to "15.2.7 Mailbox state packet".