μT-Kernel 2.0 Specification
Prev	μT-Kernel/OS Functions	Next

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

C Language Interface

#include <tk/tkernel.h>

ID semid = tk_cre_sem (CONST T_CSEM *pk_csem );

Parameter

CONST T_CSEM* pk_csem Packet to Create Semaphore Semaphore creation information

pk_csem Detail:

void*	`exinf`	Extended Information	Extended information
ATR	`sematr`	Semaphore Attribute	Semaphore attribute
INT	`isemcnt`	Initial Semaphore Count	Initial semaphore count
INT	`maxsem`	Maximum Semaphore Count	Maximum semaphore count
UB	`dsname[8]`	DS Object name	DS object name
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ID	`semid`	Semaphore ID	Semaphore ID
or		Error Code	Error code

Error Code

E_NOMEM	Insufficient memory (memory for control block cannot be allocated)
E_LIMIT	Semaphore count exceeds the system limit
E_RSATR	Reserved attribute (`sematr` is invalid or cannot be used)
E_PAR	Parameter error (`pk_csem` is invalid, or `isemcnt` or `maxsem` is negative or invalid)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

`TK_SUPPORT_DISWAI`	Support for specifying `TA_NODISWAI` (reject request to disable wait) to semaphore attribute
`TK_SUPPORT_DSNAME`	Support for specifying `TA_DSNAME` for semaphore attribute
`TK_SEMAPHORE_MAXCNT`	Maximum number of semaphore resources (must be larger than or equal to 32767)

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 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 request 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 number of resources. The request counts are checked starting from the first task in the queue, and tasks to which their requested amount 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 */

Difference from T-Kernel 2.0

The lowest number that can be specified to maxsem is changed from 65535 to 32767. This is because that INT type on 16-bit CPU can accommodate only up to 32767 in virtually all the cases.

tk_del_sem - Delete Semaphore

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_sem (ID semid );

Parameter

ID semid Semaphore ID Semaphore ID

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_sig_sem (ID semid , INT cnt );

Parameter

ID	`semid`	Semaphore ID	Semaphore ID
INT	`cnt`	Count	Resource return count

Return Parameter

ER ercd Error Code Error code

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_QOVR	Queuing or nesting overflow (`semcnt` over limit)
E_PAR	Parameter error (`cnt` ≦ 0)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

None.

Description

Returns to the semaphore specified in semid the number of resources indicated in cnt. If there is a task waiting for the semaphore, its request 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 count increases to the point where the maximum 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 count (semcnt) does not change.

Additional Notes

Error is not returned even if semcnt goes over the semaphore initial count (isemcnt). When semaphores are used not for mutual exclusion control but for synchronization (like tk_wup_tsk and tk_slp_tsk), the semaphore 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 count (maxsem) to the same value and checking for the error that is returned when the count increases.

tk_wai_sem - Wait on Semaphore

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_wai_sem (ID semid , INT cnt , TMO tmout );

Parameter

ID	`semid`	Semaphore ID	Semaphore ID
INT	`cnt`	Count	Resource request count
TMO	`tmout`	Timeout	Timeout (ms)

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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 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 count (semcnt) for this semaphore does not change in this case.

A maximum wait time (timeout) can be set in tmout. 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.

Only positive values can be set in tmout. The time unit for tmout (time unit) is the same as that for system time (= 1 ms).

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 (in microseconds)

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_wai_sem_u (ID semid , INT cnt , TMO_U tmout_u );

Parameter

ID	`semid`	Semaphore ID	Semaphore ID
INT	`cnt`	Count	Resource request count
TMO_U	`tmout_u`	Timeout	Timeout (in microseconds)

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_USEC Support instructions that can handle time in microsecond resolutions

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.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

tk_ref_sem - Reference Semaphore Status

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_sem (ID semid , T_RSEM *pk_rsem );

Parameter

ID	`semid`	Semaphore ID	Semaphore ID
T_RSEM*	`pk_rsem`	Packet to Return Semaphore Status	Pointer to the area to return the semaphore status

Return Parameter

ER ercd Error Code Error code

pk_rsem Detail:

void*	`exinf`	Extended Information	Extended information
ID	`wtsk`	Wait Task Information	Waiting task ID
INT	`semcnt`	Semaphore Count	current semaphore count value
(Other implementation-dependent parameters may be added beyond this point.)

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 (invalid `pk_rsem`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

Description

References the status of the semaphore specified in semid, passing in the return parameters the current semaphore 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

C Language Interface

#include <tk/tkernel.h>

ID flgid = tk_cre_flg (CONST T_CFLG *pk_cflg );

Parameter

CONST T_CFLG* pk_cflg Packet to Create EventFlag Event flag creation information

pk_cflg Detail:

void*	`exinf`	Extended Information	Extended information
ATR	`flgatr`	EventFlag Attribute	Event flag attribute
UINT	`iflgptn`	Initial EventFlag Pattern	Event flag initial value
UB	`dsname[8]`	DS Object name	DS object name
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ID	`flgid`	EventFlag ID	Event flag ID
or		Error Code	Error code

Error Code

E_NOMEM	Insufficient memory (memory for control block cannot be allocated)
E_LIMIT	Number of event flags exceeds the system limit
E_RSATR	Reserved attribute (`flgatr` is invalid or cannot be used)
E_PAR	Parameter error (`pk_cflg` is invalid)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

`TK_SUPPORT_DISWAI`	Support for specifying prohibition of "disabling wait" (`TA_NODISWAI`) to event flag attribute
`TK_SUPPORT_DSNAME`	Support for specifying `TA_DSNAME` for event flag attribute

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.

#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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_flg (ID flgid );

Parameter

ID flgid EventFlag ID Event flag ID

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_set_flg (ID flgid , UINT setptn );

Parameter

ID	`flgid`	EventFlag ID	Event flag ID
UINT	`setptn`	Set Bit Pattern	Bit pattern to be set

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

None.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_clr_flg (ID flgid , UINT clrptn );

Parameter

ID	`flgid`	EventFlag ID	Event flag ID
UINT	`clrptn`	Clear Bit Pattern	Bit pattern to be cleared

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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.

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.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_wai_flg (ID flgid , UINT waiptn , UINT wfmode , UINT *p_flgptn , TMO tmout );

Parameter

ID	`flgid`	EventFlag ID	Event flag ID
UINT	`waiptn`	Wait Bit Pattern	Wait bit pattern
UINT	`wfmode`	Wait EventFlag Mode	Wait release condition
UINT*	`p_flgptn`	Pointer to EventFlag Bit Pattern	Pointer to the area to return the return parameter `flgptn`
TMO	`tmout`	Timeout	Timeout (ms)

Return Parameter

ER	`ercd`	Error Code	Error code
UINT	`flgptn`	EventFlag Bit Pattern	Event flag bit pattern

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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. If the tmout time elapses before the wait release condition is met, the system call terminates, returning timeout error code E_TMOUT.

Only positive values can be set in tmout. The time unit for tmout (time unit) is the same as that for system time (= 1 ms).

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 waiptn and wfmode settings.)
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.

Figure 1. Multiple Tasks Waiting for One Event Flag

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 (in microseconds)

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_wai_flg_u (ID flgid , UINT waiptn , UINT wfmode , UINT *p_flgptn , TMO_U tmout_u );

Parameter

ID	`flgid`	EventFlag ID	Event flag ID
UINT	`waiptn`	Wait Bit Pattern	Wait bit pattern
UINT	`wfmode`	Wait EventFlag Mode	Wait mode
UINT*	`p_flgptn`	Pointer to EventFlag Bit Pattern	Pointer to the area to return the return parameter `flgptn`
TMO_U	`tmout_u`	Timeout	Timeout (in microseconds)

Return Parameter

ER	`ercd`	Error Code	Error code
UINT	`flgptn`	EventFlag Bit Pattern	Bit pattern of wait releasing

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_USEC Support instructions that can handle time in microsecond resolutions

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.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_flg (ID flgid , T_RFLG *pk_rflg );

Parameter

ID	`flgid`	EventFlag ID	Event flag ID
T_RFLG*	`pk_rflg`	Packet to Return EventFlag Status	Pointer to the area to return the event flag status

Return Parameter

ER ercd Error Code Error code

pk_rflg Detail:

void*	`exinf`	Extended Information	Extended information
ID	`wtsk`	Wait Task Information	Waiting task ID
UINT	`flgptn`	EventFlag Bit Pattern	The current event flag bit pattern
(Other implementation-dependent parameters may be added beyond this point.)

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 (invalid `pk_rflg`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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

Figure 2. Format of Messages Using a Mailbox

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; but these must not be located in task space.

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 memory managed by the memory pool management functions is all in system space;

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

C Language Interface

#include <tk/tkernel.h>

ID mbxid = tk_cre_mbx (CONST T_CMBX *pk_cmbx );

Parameter

CONST T_CMBX* pk_cmbx Packet to Create Mailbox Mailbox creation information

pk_cmbx Detail:

void*	`exinf`	Extended Information	Extended information
ATR	`mbxatr`	Mailbox Attribute	Mailbox attribute
UB	`dsname[8]`	DS Object name	DS object name
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ID	`mbxid`	Mailbox ID	Mailbox ID
or		Error Code	Error code

Error Code

E_NOMEM	Insufficient memory (memory for control block cannot be allocated)
E_LIMIT	Number of mailboxes exceeds the system limit
E_RSATR	Reserved attribute (`mbxatr` is invalid or cannot be used)
E_PAR	Parameter error (`pk_cmbx` is invalid)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

`TK_SUPPORT_DISWAI`	Support for specifying `TA_NODISWAI` (reject request to disable wait) to mailbox attribute
`TK_SUPPORT_DSNAME`	Support for specifying `TA_DSNAME` for mailbox attribute

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.

#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 system (shared) memory; only its start address is actually sent and received. For this reason a message must not be located in task space.

tk_del_mbx - Delete Mailbox

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_mbx (ID mbxid );

Parameter

ID mbxid Mailbox ID Mailbox ID

Return Parameter

ER ercd Error Code Error code

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_snd_mbx (ID mbxid , T_MSG *pk_msg );

Parameter

ID	`mbxid`	Mailbox ID	Mailbox ID
T_MSG*	`pk_msg`	Packet of Message	Start address of message packet

Return Parameter

ER ercd Error Code Error code

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 (invalid `pk_msg`, or `msgpri` ≦ 0)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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.

The body of a message passed by the mailbox function is located in system (shared) memory; only its start address is actually sent and received. For this reason, a message must not be located in task space.

tk_rcv_mbx - Receive Message from Mailbox

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rcv_mbx (ID mbxid , T_MSG **ppk_msg , TMO tmout );

Parameter

ID	`mbxid`	Mailbox ID	Mailbox ID
T_MSG**	`ppk_msg`	Pointer to Packet of Message	Pointer to the area to return the return parameter `pk_msg`
TMO	`tmout`	Timeout	Timeout (ms)

Return Parameter

ER	`ercd`	Error Code	Error code
T_MSG*	`pk_msg`	Packet of Message	Start address of message packet

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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

Only positive values can be set in tmout. The time unit for tmout (time unit) is the same as that for system time (= 1 ms).

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 (in microseconds)

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_rcv_mbx_u (ID mbxid , T_MSG **ppk_msg , TMO_U tmout_u );

Parameter

ID	`mbxid`	Mailbox ID	Mailbox ID
T_MSG**	`ppk_msg`	Pointer to Packet of Message	Pointer to the area to return the return parameter `pk_msg`
TMO_U	`tmout_u`	Timeout	Timeout (in microseconds)

Return Parameter

ER	`ercd`	Error Code	Error code
T_MSG*	`pk_msg`	Packet of Message	Start address of message packet

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)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_USEC Support instructions that can handle time in microsecond resolutions

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.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

tk_ref_mbx - Reference Mailbox Status

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_mbx (ID mbxid , T_RMBX *pk_rmbx );

Parameter

ID	`mbxid`	Mailbox ID	Mailbox ID
T_RMBX*	`pk_rmbx`	Packet to Refer Mailbox Status	Pointer to the area to return the mailbox status

Return Parameter

ER ercd Error Code Error code

pk_rmbx Detail:

void*	`exinf`	Extended Information	Extended information
ID	`wtsk`	Wait Task Information	Waiting task ID
T_MSG*	`pk_msg`	Packet of Message	Next message to be received
(Other implementation-dependent parameters may be added beyond this point.)

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 (invalid `pk_rmbx`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Related Service Profile Items

None.

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.

Prev	Home	Next
Task Exception Handling Functions	Up	Extended Synchronization and Communication Functions