Synchronization and Communication Functions
Synchronization and communication functions use objects independent of tasks used to synchronize tasks and achieve communication between tasks. The objects available for these purposes include semaphores, event flags, and mailboxes.
Semaphore
A semaphore is an object indicating the availability of a resource and its quantity as a numerical value. A semaphore is used to realize mutual exclusion control and synchronization when using a resource. Functions are provided for creating and deleting a semaphore, acquiring and returning resources corresponding to semaphores, and referencing semaphore status. A semaphore is an object identified by an ID number. The ID number for the semaphore is called a semaphore ID.
A semaphore contains a resource count (semaphore resource count) indicating whether the corresponding resource exists and in what quantity, and a queue of tasks waiting to acquire the resource. When a task (the task making event notification) returns m resources, it increments the semaphore resource count by m. When a task (the task waiting for an event) acquires n resources, it decreases the semaphore resource count by n. If the number of semaphore resources is insufficient (i.e., further reducing the semaphore resource count would cause it to be negative), a task attempting to acquire resources goes into WAITING state until the next time resources are returned. A task waiting for semaphore resources is put in the semaphore queue.
To prevent too many resources from being returned to a semaphore, a maximum value of semaphore resource count can be set for each semaphore. Error is reported if it is attempted to return resources to a semaphore that would cause this maximum count to be exceeded.
tk_cre_sem - Create Semaphore
Parameter
pk_csem Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
sematr
| Semaphore Attribute | Semaphore attribute |
| INT |
isemcnt
| Initial Semaphore Count | Initial semaphore resource count |
| INT |
maxsem
| Maximum Semaphore Count | Maximum semaphore resource count |
| UB |
dsname[8]
| DS Object name | DS object name |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Description
Creates a semaphore, assigning a semaphore ID to it. This system call allocates a control block to the created semaphore and sets its initial value of semaphore resource count to isemcnt, and its maximum (upper limit) to maxsem. Note that the lowest number that can be specified to maxsem shall be 32767. Whether a number larger than 32767 can be set is implementation-dependent.
exinf can be used freely by the user to set miscellaneous information about the created semaphore. The information set in this parameter can be referenced by tk_ref_sem. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
sematr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of sematr is as follows.
sematr := (TA_TFIFO || TA_TPRI) | (TA_FIRST || TA_CNT) | [TA_DSNAME] | [TA_NODISWAI]
| TA_TFIFO | Tasks are queued in FIFO order |
| TA_TPRI | Tasks are queued in priority order |
| TA_FIRST | The first task in the queue has precedence |
| TA_CNT | Tasks with fewer requests have precedence |
| TA_DSNAME | Specifies DS object name |
| TA_NODISWAI | Disabling of wait by tk_dis_wai is prohibited |
The queuing order of tasks waiting for a semaphore can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting.
TA_FIRST and TA_CNT specify precedence of resource acquisition. TA_FIRST and TA_CNT do not change the order of the queue, which is determined by TA_TFIFO and TA_TPRI.
When TA_FIRST is specified, resources are allocated starting from the first task in the queue regardless of requested semaphore resource count. As long as the first task in the queue cannot obtain the requested number of resources, tasks behind it in the queue are prevented from obtaining resources.
TA_CNT means resources are assigned based on the order in which tasks are able to obtain the requested semaphore resource count. The requested semaphore resource counts are checked starting from the first task in the queue, and tasks to which their requested counts can be allocated receive resources. This is not the same as allocating in order of fewest requests.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
#define TA_TFIFO 0x00000000 /* manage queue by FIFO */ #define TA_TPRI 0x00000001 /* manage queue by priority */ #define TA_FIRST 0x00000000 /* first task in queue has precedence */ #define TA_CNT 0x00000002 /* tasks with fewer requests have precedence */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_NODISWAI 0x00000080 /* reject request to disable wait */
tk_del_sem - Delete Semaphore
Description
Deletes the semaphore specified in semid.
The semaphore ID and control block area are released as a result of this system call.
This system call completes normally even if there is a task waiting for condition fulfillment on the semaphore, but error code E_DLT is returned to the task in WAITING state.
tk_sig_sem - Signal Semaphore
Description
Returns to the semaphore specified in semid the number of resources indicated in cnt. If there is a task waiting for the semaphore, the requested semaphore resource count is checked and resources allocated if possible. A task allocated resources goes to READY state. In some conditions more than one task may be allocated resources and put in READY state.
If the semaphore resource count increases to the point where the maximum semaphore resource count (maxsem) would be exceeded by the return of more resources, error code E_QOVR is returned. In this case no resources are returned and the semaphore resource count (semcnt) does not change.
Additional Notes
Error is not returned even if semcnt goes over the initial semaphore resource count (isemcnt). When semaphores are used not for mutual exclusion control but for synchronization (like tk_wup_tsk and tk_slp_tsk), the semaphore resource count (semcnt) will sometimes go over the initial setting (isemcnt). The semaphore function can be used for mutual exclusion control by setting isemcnt and the maximum semaphore resource count (maxsem) to the same value and checking for the error that is returned when the count increases.
tk_wai_sem - Wait on Semaphore
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (semid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the semaphore specified in semid does not exist) |
| E_PAR | Parameter error (tmout ≦ (-2), cnt ≦ 0) |
| E_DLT | The object being waited for was deleted (the specified semaphore was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Description
Obtains from the semaphore specified in semid the number of resources indicated in cnt. If the requested resources can be allocated, the task issuing this system call does not enter WAITING state but continues executing. In this case the semaphore resource count (semcnt) is decreased by the size of cnt. If the resources are not available, the task issuing this system call enters WAITING state, and is put in the queue of tasks waiting for the semaphore. The semaphore resource count (semcnt) for this semaphore does not change in this case.
A maximum wait time (timeout) can be set in tmout. The time unit for tmout is the same as that for system time (= 1 ms). If the tmout time elapses before the wait release condition is met (tk_sig_sem is not executed), the system call terminates, returning timeout error code E_TMOUT.
When TMO_POL＝0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAITING state even if no resources are acquired. When TMO_FEVR＝(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for resource acquisition without timing out.
tk_wai_sem_u - Wait on Semaphore (Microseconds)
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (semid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the semaphore specified in semid does not exist) |
| E_PAR | Parameter error (tmout_u ≦ (-2), cnt ≦ 0) |
| E_DLT | The object being waited for was deleted (the specified semaphore was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
This system call takes 64-bit tmout_u in microseconds instead of the parameter tmout of tk_wai_sem.
The specification of this system call is same as that of tk_wai_sem, except that the parameter is replaced with tmout_u. For more details, see the description of tk_wai_sem.
tk_ref_sem - Reference Semaphore Status
Return Parameter
pk_rsem Detail:
Description
References the status of the semaphore specified in semid, passing in the return parameters the current semaphore resource count (semcnt), the waiting task ID (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for the semaphore. If there are two or more such tasks, the ID of the task at the head of the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the specified semaphore does not exist, error code E_NOEXS is returned.
Event Flag
An event flag is an object used for synchronization, consisting of a pattern of bits used as flags to indicate the existence of the corresponding events. Functions are provided for creating and deleting an event flag, for event flag setting and clearing, event flag waiting, and event flag status reference. An event flag is an object identified by an ID number. The ID number for the event flag is called an event flag ID.
In addition to the bit pattern indicating the existence of corresponding events, an event flag has a queue of tasks waiting for the event flag. The event flag bit pattern is sometimes called simply event flag. The event notifier sets or clears the specified bits of the event flag. A task can be made to wait for all or some of the event flag bits to be set. A task waiting for an event flag is put in the queue of that event flag.
tk_cre_flg - Create Event Flag
Parameter
pk_cflg Detail:
Description
Creates an event flag, assigning to it an event flag ID. This system call allocates a control block to the created event flag and sets its initial value to iflgptn. An event flag handles one word's worth of bits as a group. All operations are performed in single word units.
exinf can be used freely by the user to set miscellaneous information about the created event flag. The information set in this parameter can be referenced by tk_ref_flg. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
flgatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of flgatr is as follows.
flgatr := (TA_TFIFO || TA_TPRI) | (TA_WMUL || TA_WSGL) | [TA_DSNAME] | [TA_NODISWAI]
| TA_TFIFO | Tasks are queued in FIFO order |
| TA_TPRI | Tasks are queued in priority order |
| TA_WSGL | Waiting by multiple tasks is not allowed (Wait Single Task) |
| TA_WMUL | Waiting by multiple tasks is allowed (Wait Multiple Tasks) |
| TA_DSNAME | Specifies DS object name |
| TA_NODISWAI | Disabling of wait by tk_dis_wai is prohibited |
When TA_WSGL is specified, multiple tasks cannot be in the WAITING state at the same time. Specifying TA_WMUL allows waiting by multiple tasks at the same time.
The queuing order of tasks waiting for an event flag can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting. When TA_WSGL is specified, however, since tasks cannot be queued, TA_TFIFO or TA_TPRI makes no difference.
When multiple tasks are waiting for an event flag, tasks are checked in order from the head of the queue, and the wait is released for tasks meeting the conditions. The first task to have its WAITING state released is therefore not necessarily the first in the queue. If multiple tasks meet the conditions, wait state is released for each of them.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
#define TA_TFIFO 0x00000000 /* manage queue by FIFO */ #define TA_TPRI 0x00000001 /* manage queue by priority */ #define TA_WSGL 0x00000000 /* prohibit multiple task waiting */ #define TA_WMUL 0x00000008 /* permit multiple task waiting */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_NODISWAI 0x00000080 /* reject request to disable wait */
Porting Guideline
Note that member, iflgptn, of T_CFLG is UINT type, and its value range is implementation-dependent, so care must be taken.
tk_del_flg - Delete Event Flag
Description
Deletes the event flag specified in flgid.
Issuing this system call releases the corresponding event flag ID and control block memory space.
This system call is completed normally even if there are tasks waiting for the event flag, but error code E_DLT is returned to each task in WAITING state.
tk_set_flg - Set Event Flag
Description
tk_set_flg sets the bits indicated in setptn in a one-word event flag specified in flgid. That is, a logical sum is taken of the values of the event flag specified in flgid and the values indicated in setptn. (the processing flgptn |= setptn is executed for the event flag value flgptn)
After event flag values are changed by tk_set_flg, if the condition for releasing the wait state of a task that called tk_wai_flg is met, the WAITING state of that task is cleared, putting it in RUNNING state or READY state (or SUSPENDED state if the waiting task was in WAITING-SUSPENDED state).
If all the bits of setptn are cleared to 0 in tk_set_flg, no operation is made to the target event flag. No error will result in either case.
Multiple tasks can wait for a single event flag if that event flag has the TA_WMUL attribute. The event flag in that case has a queue for the waiting tasks. A single tk_set_flg call for such an event flag may result in the release of multiple waiting tasks.
Porting Guideline
Note that setptn is UINT type, and its value range is implementation-dependent, so care must be taken.
tk_clr_flg - Clear Event Flag
Description
tk_clr_flg clears the bits of the one-word event flag specified in flgid, based on the corresponding zero bits of clrptn. That is, a logical product is taken of the values of the event flag specified in flgid and the values indicated in clrptn.(the processing flgptn &= clrptn is executed for the event flag value flgptn)
Issuing tk_clr_flg never results in wait conditions being released for a task waiting for the specified event flag; that is, dispatching never occurs with tk_clr_flg.
If all the bits of clrptn are set to 1 in tk_clr_flg, no operation is made to the target event flag. No error will be returned in either case.
Porting Guideline
Note that clrptn is UINT type, and its value range is implementation-dependent, so care must be taken.
tk_wai_flg - Wait Event Flag
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (flgid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the event flag specified in flgid does not exist) |
| E_PAR | Parameter error (waiptn = 0, wfmode is invalid, or tmout ≦ (-2)) |
| E_OBJ | Invalid object state (multiple tasks are waiting for an event flag with TA_WSGL attribute) |
| E_DLT | The object being waited for was deleted (the specified event flag was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Description
Waits for the event flag specified in flgid to be set, fulfilling the wait release condition specified in wfmode.
If the event flag specified in flgid already meets the wait release condition set in wfmode, the waiting task continues executing without going to WAITING state.
wfmode is specified as follows.
wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR || TWF_BITCLR]
| TWF_ANDW | 0x00 | AND wait condition |
| TWF_ORW | 0x01 | OR wait condition |
| TWF_CLR | 0x10 | Clear all |
| TWF_BITCLR | 0x20 | Clear condition bit only |
If TWF_ORW is specified, the issuing task waits for any of the bits specified in waiptn to be set for the event flag specified in flgid (OR wait). If TWF_ANDW is specified, the issuing task will wait for all of the bits specified in waiptn to be set for the event flag specified in flgid (AND wait).
If TWF_CLR specification is not specified, the event flag values will remain unchanged even after the conditions have been satisfied and the task has been released from WAITING state. If TWF_CLR is specified, all bits of the event flag will be cleared to 0 once wait conditions of the waiting task have been met. If TWF_BITCLR is specified, then when the conditions are met and the task is released from WAITING state, only the bits matching the event flag wait release conditions are cleared to 0(event flag values &= ~wait release conditions).
The return parameter flgptn returns the value of the event flag after the WAITING state of a task has been released due to this system call. If TWF_CLR or TWF_BITCLR was specified, the value before event flag bits were cleared is returned. The value returned by flgptn meets the wait release conditions of this system call. The contents of flgptn are indeterminate if the wait is released due to timeout or the like.
A maximum wait time (timeout) can be set in tmout. The time unit for tmout is the same as that for system time (= 1 ms). If the tmout time elapses before the wait release condition is met, the system call terminates, returning timeout error code E_TMOUT.
When TMO_POL＝0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAITING state even if the condition is not met. When TMO_FEVR＝(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for the condition to be met without timing out.
In the case of a timeout, the event flag bits are not cleared even if TWF_CLR or TWF_BITCLR was specified.
Setting waiptn to 0 results in Parameter error E_PAR.
A task cannot execute tk_wai_flg for an event flag having the TA_WSGL attribute while another task is waiting for it. Error code E_OBJ will be returned for the task issuing the subsequent tk_wai_flg, regardless of whether that task would have gone to WAITING state; i.e., regardless of whether the wait release conditions would be met.
If an event flag has the TA_WMUL attribute, multiple tasks can wait for it at the same time. The event flag in that case has a queue for the waiting tasks. A single tk_set_flg call for such an event flag may result in the release of multiple waiting tasks.
If multiple tasks are queued for an event flag with TA_WMUL attribute, the behavior is as follows.
Tasks are queued in either FIFO or priority order. (Release of wait state does not always start from the head of the queue, however, depending on factors such as
waiptnandwfmodesettings.)If TWF_CLR or TWF_BITCLR was specified by a task in the queue, the event flag is cleared when that task is released from WAITING state.
Tasks later in the queue than a task specifying TWF_CLR or TWF_BITCLR will see the event flag after it has already been cleared.
If multiple tasks having the same priority are released from waiting simultaneously as a result of tk_set_flg, the order of tasks in the ready queue (precedence) after release will continue to be the same as their original order in the event flag queue.
Additional Notes
If a logical sum of all bits is specified as the wait release condition when tk_wai_flg is called (waiptn = 0xfff...ff, wfmode = TWF_ORW), it is possible to transfer messages using one-word bit patterns in combination with tk_set_flg. However, it is not possible to send a message containing only 0s for all bits. Moreover, if the next message is sent by tk_set_flg before a previous message has been read by tk_wai_flg, the previous message will be lost; that is, message queuing is not possible.
Since setting waiptn = 0 will result in an E_PAR error, it is guaranteed that the waiptn of tasks waiting for an event flag will not be 0. The result is that if tk_set_flg sets all bits of an event flag to 1, the task at the head of the queue will always be released from waiting no matter what its wait condition is.
The ability to have multiple tasks wait for the same event flag is useful in situations like the following. Suppose, for example, that Task B and Task C are waiting for tk_wai_flg calls (2) and (3) until Task A issues (1) tk_set_flg. If multiple tasks are allowed to wait for the event flag, the result will be the same regardless of the order in which system calls (1)(2)(3) are executed (see Figure 1). On the other hand, if multiple task waiting is not allowed and system calls are executed in the order (2), (3), (1), an E_OBJ error will result from the execution of (3) tk_wai_flg.
Rationale for the Specification
The reason for returning E_PAR error for specifying waiptn = 0 is that if waiptn = 0 were allowed, it would not be possible to get out of WAITING state regardless of the subsequent event flag values.
Porting Guideline
Note that the data pointed at waiptn and p_flgptn are UINT type, and their value range is implementation-dependent, so care must be taken.
tk_wai_flg_u - Wait Event Flag (Microseconds)
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (flgid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the event flag specified in flgid does not exist) |
| E_PAR | Parameter error (waiptn = 0, wfmode is invalid, or tmout_u ≦ (-2)) |
| E_OBJ | Invalid object state (multiple tasks are waiting for an event flag with TA_WSGL attribute) |
| E_DLT | The object being waited for was deleted (the specified event flag was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
This system call takes 64-bit tmout_u in microseconds instead of the parameter tmout of tk_wai_flg.
The specification of this system call is same as that of tk_wai_flg, except that the parameter is replaced with tmout_u. For more details, see the description of tk_wai_flg.
Porting Guideline
Note that the data pointed at waiptn and p_flgptn are UINT type, and their value range is implementation-dependent, so care must be taken.
tk_ref_flg - Reference Event Flag Status
Return Parameter
pk_rflg Detail:
Description
References the status of the event flag specified in flgid, passing in the return parameters the current flag pattern (flgptn), waiting task ID (wtsk), and extended information (exinf).
wtsk returns the ID of a task waiting for this event flag. If more than one task is waiting (only when the TA_WMUL was specified), the ID of the first task in the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the specified event flag does not exist, error code E_NOEXS is returned.
Mailbox
A mailbox is an object used to achieve synchronization and communication by passing messages in system (shared) memory space. Functions are provided for creating and deleting a mailbox, sending and receiving messages in a mailbox, and referencing the mailbox status. A mailbox is an object identified by an ID number. The ID number for the mailbox is called a mailbox ID.
A mailbox has a message queue for sent messages, and a task queue for tasks waiting to receive messages. At the message sending end (posting event notification), messages to be sent go in the message queue. On the message receiving end (waiting for event notification), a task fetches one message from the message queue. If there are no queued messages, the task goes to WAITING state for receipt from the mailbox until the next message is sent. Tasks waiting for message receipt from a mailbox are put in the task queue of that mailbox.
Since the contents of messages using this function are in memory space shared both by the sending and receiving sides, only the start address of a message located in this shared space is actually sent and received. The contents of the messages themselves are not copied. T-Kernel manages messages in the message queue by means of a linked listed. An application program must allocate space at the beginning of a message to be sent, for linked list processing by T-Kernel. This area is called the message header. The message header and the message body together are called a message packet. When a system call sends a message to a mailbox, the start address of the message packet (pk_msg) is passed in a parameter.
When a system call receives a message from a mailbox, the start address of the message packet is passed in a return parameter.
If messages are assigned a priority in the message queue, the message priority (msgpri) of each message must be specified in the message header. [Figure 2]
The user puts the message contents not at the beginning of the packet but after the header part (the message contents part in the figure).
T-Kernel overwrites the contents of the header when a message is put in the message queue (except for the message priority area). An application, on the other hand, must not overwrite the header of a message in the queue (including the message priority area). The behavior when an application overwrites the message header is not defined. This specification applies not only to the direct writing of a message header by an application program, but also to the multiple passing of a header address to T-Kernel and having T-Kernel overwrite the message header. Accordingly, the behavior when a message already in the message queue is again sent to a mailbox is undefined.
 | Additional Notes |
|---|---|
Since the application program allocates the message header space for this mailbox function, there is no limit on the number of messages that can be queued. A system call sending a message does not enter WAITING state. Memory blocks allocated dynamically from a fixed-size memory pool or variable-size memory pool, or else a statically allocated area can be used for message packets. Generally, a sending task allocates a memory block from a memory pool, sending it as a message packet. After a task on the receiving end fetches the message, it returns the memory block directly to its memory pool. The following sample programs show the above usage:
/* Message type definition */
typedef struct {
T_MSG msgque; /* Message header with T_MFIFO attribute */
UB msgcont[MSG_SIZE]; /* Message content */
} T_MSG_PACKET;
/* Task operation that acquires a memory block and sends a message */ T_MSG_PACKET *pk_msg; ... /* Acquire a memory block from the fixed-size memory pool. */ /* Fixed-memory block size must be sizeof(T_MSG_PACKET) or more */ tk_get_mpf( mpfid, (void**)&pk_msg, TMO_FEVR ); /* Create a message at pk_msg -> msgcont[] */ ... /* Send a message */ tk_snd_mbx( mbxid, (T_MSG*)pk_msg ); /* Task operation that receives a message and releases a memory block */ T_MSG_PACKET *pk_msg; ... /* Receive a message */ tk_rcv_mbx( mbxid, (T_MSG**)&pk_msg, TMO_FEVR ); /* Check message content at pk_msg -> msgcont[] and process them accordingly */ ... /* Return the memory block to the fixed-size memory pool. */ tk_rel_mpf( mpfid, (void*)pk_msg ); |
tk_cre_mbx - Create Mailbox
Parameter
pk_cmbx Detail:
Description
Creates a mailbox, assigning to it a mailbox ID. This system call allocates a control block, etc. for the created mailbox.
exinf can be used freely by the user to set miscellaneous information about the created mailbox. The information set in this parameter can be referenced by tk_ref_mbx. If a larger area is needed for indicating user information, or if the information may need to be changed after the message buffer is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
mbxatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of mbxatr is as follows.
mbxatr := (TA_TFIFO || TA_TPRI) | (TA_MFIFO || TA_MPRI) | [TA_DSNAME] | [TA_NODISWAI]
| TA_TFIFO | Tasks are queued in FIFO order |
| TA_TPRI | Tasks are queued in priority order |
| TA_MFIFO | Messages are queued in FIFO order |
| TA_MPRI | Messages are queued in priority order |
| TA_DSNAME | Specifies DS object name |
| TA_NODISWAI | Disabling of wait by tk_dis_wai is prohibited |
The queuing order of tasks waiting for a mailbox can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting.
TA_MFIFO and TA_MPRI are used to specify the order of messages in the message queue (messages waiting to be received). If the attribute is TA_MFIFO , messages are ordered by FIFO; TA_MPRI specifies queuing of messages in priority order. Message priority is set in a special field in the message packet. Message priority is specified by positive values, with 1 indicating the highest priority and higher numbers indicating successively lower priority. The largest value that can be expressed in the PRI type is the lowest priority. Messages having the same priority are ordered as FIFO.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
#define TA_TFIFO 0x00000000 /* manage queue by FIFO */ #define TA_TPRI 0x00000001 /* manage queue by priority */ #define TA_MFIFO 0x00000000 /* manage message queue by FIFO */ #define TA_MPRI 0x00000002 /* manage message queue by priority */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_NODISWAI 0x00000080 /* reject request to disable wait */
Additional Notes
The body of a message passed by the mailbox function is located in memory; only its start address is actually sent and received.
tk_del_mbx - Delete Mailbox
Description
Deletes the mailbox specified in mbxid.
Issuing this system call releases the mailbox ID and control block memory space, etc., associated with the mailbox.
This system call completes normally even if there are tasks waiting for messages in the deleted mailbox, but error code E_DLT is returned to each of the tasks in WAITING state. Even if there are messages still in the deleted mailbox, the mailbox is deleted without returning an error code.
tk_snd_mbx - Send Message to Mailbox
Description
Sends the message packet having pk_msg as its start address to the mailbox specified in mbxid.
The message packet contents are not copied; only the start address (pk_msg) is passed at the time of message receipt. Therefore, the content of the message packet must not be overwritten until it is fetched by the task that receives this message.
If tasks are already waiting for messages in the same mailbox, the WAITING state of the task at the head of the queue is released, and the pk_msg specified in tk_snd_mbx is sent to that task, becoming a parameter returned by tk_rcv_mbx. If there are no tasks waiting for messages in the specified mailbox, the sent message goes in the message queue of that mailbox. In neither case does the task issuing tk_snd_mbx enter WAITING state.
pk_msg is the start address of the packet containing the message, including header. The message header has the following format.
typedef struct t_msg {
? ? /* Implementation-dependent content (fixed-size) */
} T_MSG;
typedef struct t_msg_pri {
T_MSG msgque; /* message queue area */
PRI msgpri; /* message priority */
} T_MSG_PRI;
The message header is T_MSG (if TA_MFIFO attribute is specified) or T_MSG_PRI (if TA_MPRI). In either case the message header has a fixed-size, which can be obtained by sizeof(T_MSG) or sizeof (T_MSG_PRI).
The actual message must be put in the area after the header. There is no limit on message size, which may be variable.
Additional Notes
Messages are sent by tk_snd_mbx regardless of the status of the receiving tasks. In other words, message sending is asynchronous. What waits in the queue is not the sending task itself, but the sent message. So while there are queues of waiting messages and receiving tasks, the sending task does not go to WAITING state.
tk_rcv_mbx - Receive Message from Mailbox
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mbxid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the mailbox specified in mbxid does not exist) |
| E_PAR | Parameter error (tmout ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the mailbox was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Description
tk_rcv_mbx receives a message from the mailbox specified in mbxid.
If no messages have been sent to the mailbox (the message queue is empty), the task issuing this system call enters WAITING state and is queued for message arrival. If there are messages in the mailbox, the task issuing this system call fetches the first message in the message queue, passing this in the return parameter pk_msg.
A maximum wait time (timeout) can be set in tmout. The time unit for tmout is the same as that for system time (= 1 ms). If the tmout time elapses before the wait release condition is met (before a message arrives), the system call terminates, returning timeout error code E_TMOUT.
When TMO_POL＝0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAITING state even if no message arrives. When TMO_FEVR＝(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for message arrival without timing out.
Additional Notes
pk_msg is the start address of the packet containing the message, including header. The message header is T_MSG (if TA_MFIFO attribute is specified) or T_MSG_PRI (if TA_MPRI).
tk_rcv_mbx_u - Receive Message from Mailbox (Microseconds)
Error Code
| E_OK | Normal completion |
| E_ID | Invalid ID number (mbxid is invalid or cannot be used) |
| E_NOEXS | Object does not exist (the mailbox specified in mbxid does not exist) |
| E_PAR | Parameter error (tmout_u ≦ (-2)) |
| E_DLT | The object being waited for was deleted (the mailbox was deleted while waiting) |
| E_RLWAI | Waiting state released (tk_rel_wai received in waiting state) |
| E_DISWAI | Wait released due to disabling of wait |
| E_TMOUT | Polling failed or timeout |
| E_CTX | Context error (issued from task-independent portion, or in dispatch disabled state) |
Related Service Profile Items
Only when all the service profile items below are set to be effective, this system call can be used.
Description
This system call takes 64-bit tmout_u in microseconds instead of the parameter tmout of tk_rcv_mbx.
The specification of this system call is same as that of tk_rcv_mbx, except that the parameter is replaced with tmout_u. For more details, see the description of tk_rcv_mbx.
tk_ref_mbx - Reference Mailbox Status
Return Parameter
pk_rmbx Detail:
Description
References the status of the mailbox specified in mbxid, passing in the return parameters the next message to be received (the first message in the message queue), waiting task ID (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for the mailbox. If there are multiple waiting tasks, the ID of the first task in the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the specified mailbox does not exist, error code E_NOEXS is returned.
pk_msg indicates the message that will be received the next time tk_rcv_mbx is issued. If there are no messages in the message queue, pk_msg = NULL is returned. At least one of pk_msg= NULL and wtsk = 0 is always true for this system call.