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.

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


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


- 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;       /*RI600V4 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;       /*RI600V4 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 RI600V4, 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 by Maximum message priority (max_pri) in Mailbox Information (mailbox[])) when the system configuration file is created.

5.5.2 Create mailbox

In the RI600V4, 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 "mailbox[]" in the system configuration file.

For details about the static API "mailbox[]", refer to "19.11 Mailbox Information (mailbox[])".

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

Note 2 For details about the message packet T_MSG and T_MSG_PRI, refer to "5.5.1 Messages".

5.5.4 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)

- prcv_mbx, iprcv_mbx (Polling)

- trcv_mbx (Wait with time-out)

- 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

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

Note 2 For details about the message packet T_MSG and T_MSG_PRI, refer to "5.5.1 Messages".

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


Note For details about the message packet T_MSG and T_MSG_PRI, refer to "5.5.1 Messages".

- 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

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 time specified by tmout has elapsed.

E_TMOUT



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

Note 3 For details about the message packet T_MSG and T_MSG_PRI, refer to "5.5.1 Messages".

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


Note For details about the mailbox state packet, refer to "[Mailbox state packet: T_RMBX]".