Subversion Repositories or1k

The µITRON specification

defines a highly flexible operating system architecture designed

specifically for application in embedded systems. The specification addresses

features which are common to the majority of processor architectures and

deliberately avoids virtualization which would adversely impact

real-time performance. The µITRON specification

may be implemented on many hardware platforms and provides significant

advantages by reducing the effort involved in understanding and

porting application software to new processor architectures. 

Several revisions of the µITRON specification exist.

        In this release, eCos supports the

        µITRON version 3.02 specification, with complete

        “Standard functionality” (level S), plus many

        “Extended” (level E) functions. The definitive

        reference on µITRON is Dr. Sakamura’s book:

          µITRON 3.0, An Open and Portable Real-Time Operating

          System for Embedded Systems.

        The book can be purchased from the IEEE Press, and

        an ASCII version of the standard can be found online at

http://www.itron.gr.jp/.

The old address

http://tron.um.u-tokyo.ac.jp/TRON/ITRON/

still exists as a mirror site. 

The eCos kernel implements the functionality

used by the µITRON compatibility subsystem.

The configuration of the kernel influences the behavior of µITRON

programs.

In particular, the default configuration has time slicing

(also known as round-robin scheduling) switched on; this means that

a task can be moved from RUN state

to READY state at any time, in

order that one of its peers may run. This is not strictly conformant

to the µITRON specification, which

states that timeslicing may be implemented by periodically issuing

a rot_rdq(0) call from

within a periodic task or cyclic handler; otherwise it is expected

that a task runs until it is pre-empted in consequence of synchronization

or communication calls it makes, or the effects of an interrupt

or other external event on a higher priority task cause that task

to become READY. To disable timeslicing

functionality in the kernel and µITRON

compatibility environment, please disable the

CYGSEM_KERNEL_SCHED_TIMESLICE

configuration option in the kernel package. A description of kernel

scheduling is in . 

For another example, the semantics of task queueing when waiting

on a synchronization object depend solely on the way the underlying

kernel is configured. As discussed above, the multi-level queue

scheduler is the only one which is µITRON

compliant, and it queues waiting tasks in FIFO order. Future releases

of that scheduler might be configurable to support priority ordering

of task queues. Other schedulers might be different again: for example

the bitmap scheduler can be used with the µITRON

compatibility layer, even though it only allows one task at each

priority and as such is not µITRON

compliant, but it supports only priority ordering of task queues.

So which queueing scheme is supported is not really a property of

the µITRON compatibility layer; it

depends on the kernel. 

In this version of the µITRON

compatibility layer, the calls to disable and enable scheduling

and interrupts (dis_dsp(),

ena_dsp(), loc_cpu()

and unl_cpu())

call underlying kernel functions; in particular, the xxx_dsp() functions

lock the scheduler entirely, which prevents dispatching of DSRs; functions

implemented by DSRs include clock counters and alarm timers. Thus time “stops” while

dispatching is disabled with dis_dsp(). 

Like all parts of the eCos system, the

detailed semantics of the µITRON layer

are dependent on its configuration and the configuration of other components

that it uses. The µITRON configuration

options are all defined in the file pkgconf/uitron.h,

and can be set using the configuration tool or editing the

.ecc

file in your build directory by hand. 

An important configuration option for the µITRON

compatibility layer is “Option: Return Error Codes for Bad Params”

(

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

), which allows a lot of the error

checking code in the µITRON compatibility layer to

be removed. Of course this leaves a program open to undetected errors,

so it should only be used once an application is fully debugged and

tested. Its benefits include reduced code size and faster execution.

However, it affects the API significantly, in that with this option

enabled, bad calls do not return errors, but cause an assert

failure (if that is itself enabled) or malfunction internally. There

is discussion in more detail about this in each section below.

We now give a brief description of the µITRON

functions which are implemented in this release. Note that all C

and C++ source files should have the following #include statement: 

#include <cyg/compat/uitron/uit_func.h>

The following functions are fully supported in this release: 

ER sta_tsk(

  ID tskid,

  INT stacd )

void ext_tsk( void )

void exd_tsk( void )

ER dis_dsp( void )

ER ena_dsp( void )

ER chg_pri(

  ID tskid,

  PRI tskpri )

ER rot_rdq(

  PRI tskpri )

ER get_tid(

  ID *p_tskid )

ER ref_tsk(

  T_RTSK *pk_rtsk,

  ID tskid )

ER ter_tsk(

  ID tskid )

ER rel_wai(

  ID tskid )

The following two functions are supported in this release,

when enabled with the configuration option

CYGPKG_UITRON_TASKS_CREATE_DELETE

with some restrictions:

ER cre_tsk(

  ID tskid,

  T_CTSK *pk_ctsk )

ER del_tsk(

  ID tskid )

These functions are restricted as follows:

Because of the static initialization facilities provided for

system objects, a task is allocated stack space statically in the

configuration. So while tasks can be created and deleted, the same

stack space is used for that task (task ID number) each time. Thus

the stack size (pk_ctsk->stksz) requested in cre_tsk() is

checked for being less than that which was statically allocated,

and otherwise ignored. This ensures that the new task will have

enough stack to run. For this reason del_tsk() does

not in any sense free the memory that was in use for the task's

stack. 

The task attributes (pk_ctsk->tskatr) are

ignored; current versions of eCos do not need

to know whether a task is written in assembler or C/C++ so

long as the procedure call standard appropriate to the CPU is followed.

Extended information (pk_ctsk->exinf) is

          ignored.

For all these calls, an invalid task id (tskid) (less than

1 or greater than the number of configured tasks) only returns E_ID

when bad params return errors (

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

is enabled, see above).

Similarly, the following conditions are only checked for,

and only return errors if

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

is enabled:

pk_crtk in

cre_tsk()

 is a valid pointer, otherwise return E_PAR

ter_tsk()

 or

rel_wai()

 on the calling task returns E_OBJ

the CPU is not locked already in

dis_dsp()

 and

ena_dsp()

; returns E_CTX

priority level in

chg_pri()

 and

rot_rdq()

 is checked for validity, E_PAR

return value pointer in

get_tid()

 and

ref_tsk()

 is a valid pointer, or E_PAR

The following conditions are checked for, and return

            error codes if appropriate, regardless of the setting of

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

:

When create and delete functions

cre_tsk()

 and

del_tsk()

 are supported, all calls which use a valid task ID number check

that the task exists; if not, E_NOEXS is returned

When supported,

cre_tsk()

: the task must not already exist; otherwise E_OBJ

When supported,

cre_tsk()

: the requested stack size must not be larger than that statically

configured for the task; see the configuration options

“Static initializers”, and “Default stack size”.

Else E_NOMEM

When supported,

del_tsk()

: the underlying

eCos

 thread must not be running - this would imply either a bug or some

program bypassing the

µITRON compatibility layer and manipulating the thread directly.

E_OBJ

sta_tsk()

: the task must be dormant, else E_OBJ

ter_tsk()

: the task must not be dormant, else E_OBJ

chg_pri()

: the task must not be dormant, else E_OBJ

rel_wai()

: the task must be in

WAIT or WAIT-SUSPEND

 state, else E_OBJ

These functions are fully supported in this release: 

ER sus_tsk(

    ID tskid )

ER rsm_tsk(

    ID tskid )

ER frsm_tsk(

    ID tskid )

ER slp_tsk( void )

ER tslp_tsk(

    TMO tmout )

ER wup_tsk(

    ID tskid )

ER can_wup(

    INT *p_wupcnt,    ID tskid )

The following conditions are only checked for, and only return

errors if

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

is enabled (see the configuration option “Return Error Codes for Bad

Params”):

invalid tskid; less than 1 or greater than

CYGNUM_UITRON_TASKS

returns E_ID

wup_tsk()

,

sus_tsk()

,

rsm_tsk()

,

frsm_tsk()

 on the calling task returns E_OBJ

dispatching is enabled in

tslp_tsk()

 and

slp_tsk()

, or E_CTX

tmout must be positive, otherwise E_PAR

return value pointer in

can_wup()

 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_tsk()

 and

del_tsk()

 are supported, all calls which use a valid task ID number check

that the task exists; if not, E_NOEXS is returned

sus_tsk()

: the task must not be dormant, else E_OBJ

frsm/rsm_tsk()

: the task must be suspended, else E_OBJ

tslp/slp_tsk()

: return codes E_TMOUT, E_RLWAI and E_DLT

are returned depending on the reason for terminating the sleep

wup_tsk()

 and

can_wup()

: the task must not be dormant, or E_OBJ is returned

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. 

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.

None of these functions are supported in this release. 

These functions are fully supported in this release:

void     ret_int( void )

ER loc_cpu( void )

ER unl_cpu( void )

ER dis_int(

    UINT eintno )

ER ena_int(

    UINT eintno )

void    ret_wup(

    ID tskid )

ER iwup_tsk(

    ID tskid )

ER isig_sem(

    ID semid )

ER iset_flg(

    ID flgid ,

    UID setptn )

ER isend_msg(

    ID mbxid ,

    T_MSG *pk_msg )

Note that ret_int() and

the ret_wup() are  implemented

as macros, containing a “return” statement.

Also note that ret_wup() and

the ixxx_yyy() style functions

will only work when called from an ISR whose associated DSR is cyg_uitron_dsr(),

as specified in include file <cyg/compat/uitron/uit_ifnc.h>,

which defines the ixxx_yyy() style

functions also.

If you are writing interrupt handlers more in the

eCos style, with separate ISR and DSR routines both of

your own devising, do not use these special functions from a DSR: use plain

xxx_yyy() style functions (with no ‘i’ prefix)

instead, and do not call any µITRON functions from the ISR at

all.

The following functions are not supported in this release: 

ER def_int(

    UINT dintno,

  T_DINT *pk_dint )

ER chg_iXX(

    UINT iXXXX )

ER ref_iXX(

    UINT * p_iXXXX )

These unsupported functions are all Level C (CPU dependent).

Equivalent functionality is available via other eCos-specific

APIs. 

The following conditions are only checked for, and only return

errors if

CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS

is enabled:

loc/unl_cpu()

: these must only be called in a

µITRON task context, else E_CTX.

dis/ena_int()

: the interrupt number must be in range as specified by the platform

HAL in qustion, else E_PAR.

These functions are fully supported in this release: 

ER get_blf(

    VP *p_blf,    ID mpfid )

ER pget_blf(

    VP *p_blf,    ID mpfid )

ER tget_blf(

    VP *p_blf,    ID mpfid,    TMO tmout )

ER rel_blf(

    ID mpfid,    VP blf )

ER ref_mpf(

    T_RMPF *pk_rmpf,    ID mpfid )

ER get_blk(

    VP *p_blk,    ID mplid,    INT blksz )

ER pget_blk(

    VP *p_blk,    ID mplid,    INT blksz )

ER tget_blk(

    VP *p_blk,    ID mplid,    INT blksz,    TMO tmout )

ER rel_blk(

    ID mplid,    VP blk )

ER ref_mpl(

    T_RMPL *pk_rmpl,    ID mplid )

Note that of the memory provided for a particular pool to

manage in the static initialization of the memory pool objects,

some memory will be used to manage the pool itself. Therefore the

number of blocks * the blocksize will be less than the total

memory size. 

The following functions are supported in this release, when

enabled with

CYGPKG_UITRON_MEMPOOLVAR_CREATE_DELETE

or

CYGPKG_UITRON_MEMPOOLFIXED_CREATE_DELETE

as appropriate, with some restrictions: 

ER cre_mpl(

    ID mplid,    T_CMPL *pk_cmpl )

ER del_mpl(

    ID mplid )

ER cre_mpf(

    ID mpfid,    T_CMPF *pk_cmpf )

ER del_mpf(

    ID mpfid )

Because of the static initialization facilities provided for

system objects, a memory pool is allocated a region of memory to

manage statically in the configuration. So while memory pools can

be created and deleted, the same area of memory is used for that

memory pool (memory pool ID number) each time. The requested variable pool

size (pk_cmpl->mplsz) or the number of fixed-size

blocks (pk_cmpf->mpfcnt) times the block size

(pk_cmpf->blfsz) are checked for fitting within

the statically allocated memory area, so if a create call succeeds,

the resulting pool will be at least as large as that requested.

For this reason del_mpl() and del_mpf() do

not in any sense free the memory that was managed by the deleted

pool for use by other pools; it may only be managed by a pool of

the same object id. 

For both fixed and variable memory pools, 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. 

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_MEMPOOLVAR/MEMPOOLFIXED

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 a valid pointer, or E_PAR

return value pointers in get block routines is a valid

pointer, or E_PAR

blocksize request in get variable block routines is greater

than zero, 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.

When create functions

cre_xxx()

 are supported, if the object already exists, then E_OBJ

In any call which can sleep, such as

get_blk()

: return codes E_TMOUT, E_RLWAI, E_DLT

or of course E_OK are returned depending on the reason

for terminating the sleep