eCos Reference Manual
Prev	Chapter 37. µITRON API	Next

Synchronization and Communication Functions

These functions are fully supported in this release:

ER sig_sem( 
    ID semid )

ER wai_sem( 
    ID semid )

ER preq_sem( 
    ID semid )

ER twai_sem( 
    ID semid,    TMO tmout )

ER ref_sem( 
    T_RSEM *pk_rsem ,    ID semid )

ER set_flg( 
    ID flgid,    UINT setptn )

ER clr_flg( 
    ID flgid,    UINT clrptn )

ER wai_flg( 
    UINT *p_flgptn,    ID flgid ,
    UINT waiptn ,    UINT wfmode )

ER pol_flg( 
    UINT *p_flgptn,    ID flgid ,
    UINT waiptn ,    UINT wfmode )

ER twai_flg( 
    UINT *p_flgptn    ID flgid ,
    UINT waiptn ,    UINT wfmode,    TMO tmout )

ER ref_flg( 
    T_RFLG *pk_rflg,    ID flgid )

ER snd_msg( 
    ID mbxid,    T_MSG *pk_msg )

ER rcv_msg( 
    T_MSG **ppk_msg,    ID mbxid )

ER prcv_msg( 
    T_MSG **ppk_msg,    ID mbxid )

ER trcv_msg( 
    T_MSG **ppk_msg,    ID mbxid ,    TMO tmout )

ER ref_mbx( 
    T_RMBX *pk_rmbx,    ID mbxid )

The following functions are supported in this release (with some restrictions) if enabled with the appropriate configuration option for the object type (for example CYGPKG_UITRON_SEMAS_CREATE_DELETE):

ER cre_sem( 
    ID semid,    T_CSEM *pk_csem )

ER del_sem( 
    ID semid )

ER cre_flg( 
    ID flgid,    T_CFLG *pk_cflg )

ER del_flg( 
    ID flgid )

ER cre_mbx( 
    ID mbxid,    T_CMBX *pk_cmbx )

ER del_mbx( 
    ID mbxid )

In general the queueing order when waiting on a synchronization object depends on the underlying kernel configuration. The multi-level queue scheduler is required for strict µITRON conformance and it queues tasks in FIFO order, so requests to create an object with priority queueing of tasks (pk_cxxx->xxxatr = TA_TPRI) are rejected with E_RSATR. Additional undefined bits in the attributes fields must be zero.

In general, extended information (pk_cxxx->exinf) is ignored.

For semaphores, the initial semaphore count (pk_csem->isemcnt) is supported; the new semaphore's count is set. The maximum count is not supported, and is not in fact defined in type pk_csem.

For flags, multiple tasks are allowed to wait. Because single task waiting is a subset of this, the W bit (TA_WMUL) of the flag attributes is ignored; all other bits must be zero. The initial flag value is supported.

For mailboxes, the buffer count is defined statically by kernel configuration option CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE; therefore the buffer count field is not supported and is not in fact defined in type pk_cmbx. Queueing of messages is FIFO ordered only, so TA_MPRI (in pk_cmbx->mbxatr) is not supported.

Error checking

The following conditions are only checked for, and only return errors if CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS is enabled:

invalid object id; less than 1 or greater than CYGNUM_UITRON_TASKS/SEMAS/MBOXES as appropriate returns E_ID
dispatching is enabled in any call which can sleep, or E_CTX
tmout must be positive, otherwise E_PAR
pk_cxxx pointers in cre_xxx() must be valid pointers, or E_PAR
return value pointer in ref_xxx() is valid pointer, or E_PAR
flag wait pattern must be non-zero, and mode must be valid, or E_PAR
return value pointer in flag wait calls is a valid pointer, or E_PAR

The following conditions are checked for, and can return error codes, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :

When create and delete functions cre_xxx() and del_xxx() are supported, all calls which use a valid object ID number check that the object exists. If not, E_NOEXS is returned.
In create functions cre_xxx() , when supported, if the object already exists, then E_OBJ
In any call which can sleep, such as twai_sem() : return codes E_TMOUT, E_RLWAI, E_DLT or of course E_OK are returned depending on the reason for terminating the sleep
In polling functions such as preq_sem() return codes E_TMOUT or E_OK are returned depending on the state of the synchronization object
In creation functions, the attributes must be compatible with the selected underlying kernel configuration: in cre_sem() pk_csem->sematr must be equal to TA_TFIFO else E_RSATR.
In cre_flg() pk_cflg->flgatr must be either TA_WMUL or TA_WSGL else E_RSATR.
In cre_mbx() pk_cmbx->mbxatr must be TA_TFIFO + TA_MFIFO else E_RSATR.

Prev	Home	Next
Task-Dependent Synchronization Functions	Up	Extended Synchronization and Communication Functions