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. If you have purchased the eCos Developer's Kit, you will have received a copy of this book. Otherwise, the book can be purchased from the IEEE Press, and an ASCII version of the standard can be found online at
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 communications 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
Thread operations
.
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 this file by hand.
An important configuration option for the µ ITRON compatibility layer is CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS (see "Option: Return Error Codes for Bad Params", in Section V), 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 either 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 )
voidext_tsk
( void ) voidexd_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 )
ERter_tsk
( ID tskid ) ERrel_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_ctskstksz) 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_ctsktskatr) 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_ctskexinf) 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:
cre_tsk()
is a valid pointer, otherwise return E_PAR
ter_tsk()
or
rel_wai()
on the calling task returns E_OBJ
dis_dsp()
and
ena_dsp()
; returns E_CTX
chg_pri()
and
rot_rdq()
is checked for validity, E_PAR
get_tid()
and
ref_tsk()
is a valid pointer, or E_PARThe following conditions are checked for, and return error codes if appropriate, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :
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
cre_tsk()
: the task must not already exist; otherwise E_OBJ
cre_tsk()
: the requested stack size must not be larger than that statically configured for the task; see "Option: Static initializerst", in Section V and "Option: Default stack size", in Section V. Else E_NOMEM
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_OBJThese functions are fully supported in this release:
ERsus_tsk
( ID tskid ) ERrsm_tsk
( ID tskid ) ERfrsm_tsk
( ID tskid ) ERslp_tsk
( void ) ERtslp_tsk
( TMO tmout ) ERwup_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 "Option: Return Error Codes for Bad Params", in Section V):
wup_tsk()
,
sus_tsk()
,
rsm_tsk()
,
frsm_tsk()
on the calling task returns E_OBJ
tslp_tsk()
and
slp_tsk()
, or E_CTX
can_wup()
is a valid pointer, or E_PARThe following conditions are checked for, and can return error codes, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :
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 returnedThese 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 )
ERset_flg
( ID flgid, UINT setptn ) ERclr_flg
( ID flgid, UINT clrptn )
ER wai_flg
(
UINT *p_flgptn,
ID flgid ,
UINT waiptn ,
UINT wfmode )
ERpol_flg
( UINT *p_flgptn, ID flgid , UINT waiptn , UINT wfmode ) ERtwai_flg
( UINT *p_flgptn ID flgid , UINT waiptn , UINT wfmode, TMO tmout ) ERref_flg
( T_RFLG *pk_rflg, ID flgid ) ERsnd_msg
( ID mbxid, T_MSG *pk_msg )
ERrcv_msg
( T_MSG **ppk_msg, ID mbxid ) ERprcv_msg
( T_MSG **ppk_msg, ID mbxid ) ERtrcv_msg
( T_MSG **ppk_msg, ID mbxid , TMO tmout ) ERref_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 ) :
ERcre_sem
( ID semid, T_CSEM *pk_csem ) ERdel_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_cxxxxxxatr = TA_TPRI
) are rejected with E_RSATR. Additional undefined bits in the attributes fields must be zero.
In general, extended information (pk_cxxxexinf) is ignored.
For semaphores, the initial semaphore count (pk_csemisemcnt) 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_cmbxmbxatr) is not supported.
The following conditions are only checked for, and only return errors if CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS is enabled:
cre_xxx()
must be valid pointer, or E_PAR
ref_xxx()
is a valid pointer, or E_PARThe following conditions are checked for, and can return error codes, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :
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.
cre_xxx()
, when supported, if the object already exists, then E_OBJ
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
preq_sem()
return codes E_TMOUT or E_OK are returned depending on the state of the synchronization object
cre_sem()
pk_csemsematr
must be equal to
TA_TFIFO
else E_RSATR.
cre_flg()
pk_cflgflgatr
must be either
TA_WMUL
or
TA_WSGL
else E_RSATR.
cre_mbx()
pk_cmbxmbxatr
must be
TA_TFIFO + TA_MFIFO
else E_RSATR.These functions are fully supported in this release:
voidret_int
( void )
ERloc_cpu
( void )
ERunl_cpu
( void ) ERdis_int
( UINT eintno ) ERena_int
( UINT eintno ) voidret_wup
( ID tskid ) ERiwup_tsk
( ID tskid ) ERisig_sem
( ID semid ) ERiset_flag
( ID flgid,
UINT setptn ) ERisnd_msg
( ID mbxid,
T_MSG *pkmsg )
Note that
ret_int()
and 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 the include file <cyg/compat/uitron/uit_ifnc.h>,
which defines the ixxx_yyy()
style functions also. Do not use them from a DSR: use plain xxx_yyy()
style functions instead.
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:
These functions are fully supported in this release:
ER get_blf
(
VP *p_blf,
ID mpfid )
ER pget_blf
(
VP *p_blf,
ID mpfid )
ERtget_blf
( VP *p_blf, ID mpfid, TMO tmout ) ERrel_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 )
ERtget_blk
( VP *p_blk, ID mplid, INT blksz, TMO tmout ) ERrel_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_cmplmplsz) or the number of fixed-size blocks (pk_cmpfmpfcnt) times the block size (pk_cmpfblfsz) 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_cxxxxxxatr = TA_TPRI) are rejected with E_RSATR. Additional undefined bits in the attributes fields must be zero.
In general, extended information (pk_cxxxexinf) is ignored.
The following conditions are only checked for, and only return errors if CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS is enabled:
cre_xxx()
must be valid pointer, or E_PAR
ref_xxx()
is a valid pointer, or E_PARThe following conditions are checked for, and can return error codes, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :
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.
cre_xxx()
are supported, if the object already exists, then E_OBJ
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
pget_blk()
return codes E_TMOUT or E_OK are returned depending on the state of the synchronization object
cre_mpl()
pk_cmplmplatr
must be equal to
TA_TFIFO
else E_RSATR.
cre_mpf()
pk_cmpfmpfatr
must be equal to
TA_TFIFO
else E_RSATR.
cre_mpl()
pk_cmplmplsz
is the field of interest
cre_mpf()
the product of
pk_cmpfblfsz
and
pk_cmpfmpfcnt
must be smaller than the memory statically configured for the pool else E_RSATR
rel_blk()
and
rel_blf()
, if the free fails, for example because the memory did not come from that pool originally, then E_PAR is returnedThese functions are fully supported in this release:
ER set_tim
(
SYSTIME *pk_tim )
Setting the time may cause erroneous operation of the kernel, for example a task performing a wait with a time-out may never awaken.
ER get_tim
(
SYSTIME *pk_tim )
ER dly_tsk
(
DLYTIME dlytim )
ER def_cyc
(
HNO cycno,
T_DCYC *pk_dcyc )
ER act_cyc
(
HNO cycno,
UINT cycact )
ERref_cyc
( T_RCYC *pk_rcyc, HNO cycno ) ERdef_alm
( HNO almno, T_DALM *pk_dalm ) ERref_alm
( T_RALM *pk_ralm, HNO almno )
void ret_tmr
( void )
Error checking
The following conditions are only checked for, and only return errors if CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS is enabled:
dly_tsk()
, or E_CTX
ref_xxx()
is a valid pointer, or E_PAR
act_cyc()
must be valid, or E_PAR
ref_xxx()
and
act_cyc()
, or E_NOEXS
get_tim()
and
set_tim()
, otherwise E_PAR is returnedThe following conditions are checked for, and can return error codes, regardless of the setting of CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS :
These functions are fully supported in this release:
ER get_ver
(
T_VER *pk_ver )
ER ref_sys
(
T_RSYS *pk_rsys )
ER ref_cfg
(
T_RCFG *pk_rcfg )
Note that the information returned by each of these calls may be configured to match the user's own versioning system, and the values supplied by the default configuration may be inappropriate.
These functions are not supported in this release:
ER def_svc
(
FN s_fncd,
T_DSVC *pk_dsvc )
ER def_exc
(
UINT exckind,
T_DEXC *pk_dexc )
The following conditions are only checked for, and only return errors if CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS is enabled:
µITRON API | ||
---|---|---|