eCos Reference Manual
Prev | Chapter 32. µ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