eCosTM Reference Manual
Prev |  | Next

# Chapter 6. µITRON API

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 athttp://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 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 the section called Thread operations in Chapter 5, and the configuration options for scheduling are detailed in the section called Component: Kernel schedulers in Chapter 17.

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 the section called Option: Return Error Codes for Bad Params in Chapter 18), 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: see the section called Component: Use asserts in Chapter 16) 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>

# Task Management Functions

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 (see the section called Component: Support create and delete in Chapter 18), 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 (see the section called Component: Tasks in Chapter 18). 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.

## Error checking

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 section called Option: Static initializers in Chapter 18 and the section called Option: Default stack size in Chapter 18. 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

Prev | Home | Next
Flags | Up | Task-Dependent Synchronization Functions