eCosTM Reference Manual
Prev | Chapter 6. µ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`) (see the section called Component: Support create and delete in Chapter 18):

`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` (see the section called Component: Synchronization primitives in Chapter 17); 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 pointer, or E_PAR

- return value pointers in `ref_xxx()` is a 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; see the section called Component: Support create and delete in Chapter 18.

- 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