5.5 Mailboxes
The RI78V4 provides a mailbox, as a communication function between tasks, that hands over the execution result of a given processing program to another processing program.
In the RI78V4, the method of creating a mailbox is limited to "static creation by the Kernel Initialization Module".
Mailboxes therefore cannot be created dynamically using a method such as issuing a service call from a processing program.
- Static create
Static mailbox creation is realized by defining Mailbox information in the system configuration file.
The RI78V4 executes mailbox creation processing based on data stored in information files, using the Kernel Initialization Module, and handles the created mailboxes as management targets.
Static mailbox creation is realized by defining Mailbox information in the system configuration file.
The RI78V4 executes mailbox creation processing based on data stored in information files, using the Kernel Initialization Module, and handles the created mailboxes as management targets.
In the RI78V4, mailboxes created statically by the Kernel Initialization Module cannot be deleted dynamically using a method such as issuing a service call from a 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 RI78V4, 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 RI78V4, it is recommended to use the memory area secured by issuing service calls such as get_mpf and pget_mpf for messages.
In the case of the RI78V4, it is recommended to use the memory area secured by issuing service calls such as get_mpf and pget_mpf for messages.
Note The RI78V4 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 RI78V4, it must be secured from 4-byte aligned addresses.
- Basic form of messages
In the RI78V4, the message contents and length are prescribed as follows, according to the attributes of the mailbox to be used.
In the RI78V4, 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 msgque) are not restricted in particular in the RI78V4.
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 msgque) are not restricted in particular in the RI78V4.
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 5 bytes of a message (system reserved area msgque, priority level msgpri) are not restricted in particular in the RI78V4.
Therefore, the contents and length past the first 5 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 5 bytes of a message (system reserved area msgque, priority level msgpri) are not restricted in particular in the RI78V4.
Therefore, the contents and length past the first 5 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 __near *msgque; /*Reserved for future use*/ PRI msgpri; /*Message priority*/ } T_MSG_PRI; |
- snd_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 func_task ( VP_INT exinf ) { ID mpfid = ID_mpfA; /*Declares and initializes variable*/ VP p_blk; /*Declares variable*/ char *p; /*Declares variable*/ ID mbxid = ID_mbxA; /*Declares and initializes variable*/ T_MSG_PRI *pk_msg; /*Declares data structure*/ /* ............ */ get_mpf ( mpfid, &p_blk ); /*Secures memory area (for message)*/ /*Initializes variable*/ p = (char *)p_blk + sizeof (T_MSG_PRI); while ( expr ) { *p++ = ............ /*Creates message (contents)*/ } /*Initializes data structure*/ (T_MSG_PRI *)p_blk->msgpri = 8; /*Send to mailbox*/ snd_mbx ( mbxid, (T_MSG_PRI *)p_blk ); /* ............ */ } |
Note 1 If the first task of the wait queue is moved to the READY state after this service call is issued, this service call also re-queues the task at the end of the ready queue corresponding to the priority of the task.
Note 2 Messages are queued to the target mailbox wait queue in the order defined by Attribute (queuing method): mbxatr during configuration (FIFO order or priority order).
Note 3 With the RI78V4 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 (waiting forever, 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 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 the invoking task is queued to the target mailbox wait queue in the order of message reception request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (receiving waiting for a mailbox).
The receiving waiting 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 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 the invoking task is queued to the target mailbox wait queue in the order of message reception request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (receiving waiting for a mailbox).
The receiving waiting 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 func_task ( VP_INT exinf ) { ER ercd; /*Declares variable*/ ID mbxid = ID_mbxA; /*Declares and initializes variable*/ T_MSG *ppk_msg; /*Declares data structure*/ /* ............ */ /*Receive from mailbox (waiting forever)*/ ercd = rcv_mbx ( mbxid, &ppk_msg ); if ( ercd == E_OK ) { /* ............ */ /*Normal termination processing*/ } else if ( ercd == E_RLWAI ) { /* ............ */ /*Forced termination processing*/ } /* ............ */ } |
- prcv_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 func_task ( VP_INT exinf ) { ER ercd; /*Declares variable*/ ID mbxid = ID_mbxA; /*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*/ } /* ............ */ } |
- 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 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 the invoking task is queued to the target mailbox wait queue in the order of message reception request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (receiving waiting for a mailbox).
The receiving waiting 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 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 the invoking task is queued to the target mailbox wait queue in the order of message reception request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (receiving waiting for a mailbox).
The receiving waiting 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 func_task ( VP_INT exinf ) { ER ercd; /*Declares variable*/ ID mbxid = ID_mbxA; /*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 When 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
Stores mailbox state packet (such as existence of waiting tasks) 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 (such as existence of waiting tasks) 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 func_task ( VP_INT exinf ) { ID mbxid = ID_mbxA; /*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; /*Referenc start address of the message packet at the head of the message queue*/ /* ............ */ } |