uitron.sgml

eCos操作系统源码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     uitron.sgml                                                 -->
<!--                                                                 -->
<!--     uITRON Compatibility                                        -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="compat-uitron">
  <title>&micro;ITRON</title>
<CHAPTER id="compat-uitron-microitron-api">
<TITLE><!-- <xref> -->&micro;ITRON API</TITLE>
<SECT1 id="compat-uitron-introduction">
<TITLE><!-- <index></index> -->Introduction to &micro;ITRON</TITLE>
<PARA>The <!-- <index></index> -->&micro;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 &micro;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. </PARA>
<PARA>Several revisions of the &micro;ITRON specification exist.
	In this release, <EMPHASIS>eCos</EMPHASIS> supports the
	&micro;ITRON version 3.02 specification, with complete
	&ldquo;Standard functionality&rdquo; (level S), plus many
	&ldquo;Extended&rdquo; (level E) functions. The definitive
	reference on &micro;ITRON is Dr. Sakamura&rsquo;s book:
	  <CITETITLE>&micro;ITRON 3.0, An Open and Portable Real-Time Operating
	  System for Embedded Systems</CITETITLE>. 
	The book can be purchased from the IEEE Press, and
	an ASCII version of the standard can be found online at
<ulink url="http://www.itron.gr.jp/">http://www.itron.gr.jp/</ulink>.
The old address 
<ulink url="http://tron.um.u-tokyo.ac.jp/TRON/ITRON/">
http://tron.um.u-tokyo.ac.jp/TRON/ITRON/</ulink>
still exists as a mirror site. </PARA>
</SECT1>
<SECT1 id="compat-uitron-over-ecos">
<TITLE><!-- <index></index> -->&micro;ITRON and <EMPHASIS>eCos</EMPHASIS></TITLE>
<PARA>The <EMPHASIS>eCos</EMPHASIS> kernel implements the functionality
used by the &micro;ITRON compatibility subsystem.
The configuration of the kernel influences the behavior of &micro;ITRON
programs.</PARA>
<PARA>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 <varname>RUN</varname> state
to <varname>READY</varname> state at any time, in
order that one of its peers may run. This is not strictly conformant
to the &micro;ITRON specification, which
states that timeslicing may be implemented by periodically issuing
a <literal>rot_rdq(0)</literal> 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 <varname>READY</varname>. To disable timeslicing
functionality in the kernel and &micro;ITRON
compatibility environment, please disable the 
<LITERAL>CYGSEM_KERNEL_SCHED_TIMESLICE</LITERAL>
configuration option in the kernel package. A description of kernel
scheduling is in <xref linkend="kernel-overview">. </PARA>
<PARA>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 &micro;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 &micro;ITRON
compatibility layer, even though it only allows one task at each
priority and as such is not &micro;ITRON
compliant, but it supports only priority ordering of task queues.
So which queueing scheme is supported is not really a property of
the &micro;ITRON compatibility layer; it
depends on the kernel. </PARA>
<PARA>In this version of the &micro;ITRON
compatibility layer, the calls to disable and enable scheduling
and interrupts (<FUNCTION>dis_dsp()</FUNCTION>,
<FUNCTION>ena_dsp()</FUNCTION>, <FUNCTION>loc_cpu()</FUNCTION>
and <FUNCTION>unl_cpu()</FUNCTION>)
call underlying kernel functions; in particular, the <FUNCTION>xxx_dsp()</FUNCTION> functions
lock the scheduler entirely, which prevents dispatching of DSRs; functions
implemented by DSRs include clock counters and alarm timers. Thus time &ldquo;stops&rdquo; while
dispatching is disabled with <FUNCTION>dis_dsp()</FUNCTION>. </PARA>
<PARA>Like all parts of the <EMPHASIS>eCos</EMPHASIS> system, the
detailed semantics of the &micro;ITRON layer
are dependent on its configuration and the configuration of other components
that it uses. The &micro;ITRON configuration
options are all defined in the file <filename>pkgconf/uitron.h</filename>,
and can be set using the configuration tool or editing the
<filename>.ecc</filename>
file in your build directory by hand. </PARA>
<PARA>An important configuration option for the &micro;ITRON
compatibility layer is &ldquo;Option: Return Error Codes for Bad Params&rdquo;
(
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
), which allows a lot of the error
checking code in the &micro;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.</PARA>
<PARA>We now give a brief description of the &micro;ITRON
functions which are implemented in this release. Note that all C
and C&plus;&plus; source files should have the following <literal>#include</literal> statement: </PARA>
<PROGRAMLISTING>#include &lt;cyg/compat/uitron/uit_func.h&gt;</PROGRAMLISTING>
</SECT1>
<SECT1 id="compat-uitron-task-management-functions">
<TITLE><!-- <index></index> -->Task Management Functions</TITLE>
<PARA>The following functions are fully supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>sta_tsk</FUNCTION>( 
  ID <EMPHASIS>tskid,</EMPHASIS>
  INT <EMPHASIS>stacd</EMPHASIS> )</programlisting>
	<programlisting>
void <FUNCTION>ext_tsk</FUNCTION>( void )</programlisting>
	<programlisting>
void <FUNCTION>exd_tsk</FUNCTION>( void )</programlisting>
	<programlisting>
ER <FUNCTION>dis_dsp</FUNCTION>( void )</programlisting>
	<programlisting>
ER <FUNCTION>ena_dsp</FUNCTION>( void )</programlisting>
	<programlisting>
ER <FUNCTION>chg_pri</FUNCTION>( 
  ID <EMPHASIS>tskid,</EMPHASIS>
  PRI <EMPHASIS>tskpri</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>rot_rdq</FUNCTION>( 
  PRI <EMPHASIS>tskpri</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>get_tid</FUNCTION>( 
  ID *<EMPHASIS>p_tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>ref_tsk</FUNCTION>( 
  T_RTSK *<EMPHASIS>pk_rtsk,</EMPHASIS>
  ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>ter_tsk</FUNCTION>( 
  ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>rel_wai</FUNCTION>( 
  ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
<PARA>The following two functions are supported in this release,
when enabled with the configuration option 
<LITERAL>CYGPKG_UITRON_TASKS_CREATE_DELETE</LITERAL>
with some restrictions:</PARA>
<PROGRAMLISTING>ER <FUNCTION>cre_tsk</FUNCTION>( 
  ID <EMPHASIS>tskid,</EMPHASIS>
  T_CTSK *<EMPHASIS>pk_ctsk</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>del_tsk</FUNCTION>( 
  ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
<PARA>These functions are restricted as follows:</PARA>
<PARA>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-&gt;stksz) requested in <FUNCTION>cre_tsk()</FUNCTION> 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 <FUNCTION>del_tsk()</FUNCTION> does
not in any sense free the memory that was in use for the task's
stack. </PARA>
<PARA>The task attributes (pk_ctsk-&gt;tskatr) are
ignored; current versions of <EMPHASIS>eCos</EMPHASIS> do not need
to know whether a task is written in assembler or C/C&plus;&plus; so
long as the procedure call standard appropriate to the CPU is followed.</PARA>
<PARA>Extended information (pk_ctsk-&gt;exinf) is
	  ignored.</PARA>
<SECT2>
<TITLE>Error checking</TITLE>
<PARA>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 (
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
is enabled, see above).</PARA>
<PARA>Similarly, the following conditions are only checked for,
and only return errors if 
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
is enabled:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>pk_crtk in 
<FUNCTION>cre_tsk()</FUNCTION>
 is a valid pointer, otherwise return E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>ter_tsk()</FUNCTION>
 or 
<FUNCTION>rel_wai()</FUNCTION>
 on the calling task returns E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA>the CPU is not locked already in 
<FUNCTION>dis_dsp()</FUNCTION>
 and 
<FUNCTION>ena_dsp()</FUNCTION>
; returns E_CTX</PARA>
</LISTITEM>
<LISTITEM>
<PARA>priority level in 
<FUNCTION>chg_pri()</FUNCTION>
 and 
<FUNCTION>rot_rdq()</FUNCTION>
 is checked for validity, E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointer in 
<FUNCTION>get_tid()</FUNCTION>
 and 
<FUNCTION>ref_tsk()</FUNCTION>
 is a valid pointer, or E_PAR</PARA>
</LISTITEM>
</ITEMIZEDLIST>
<PARA>The following conditions are checked for, and return
	    error codes if appropriate, regardless of the setting of
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>When create and delete functions 
<FUNCTION>cre_tsk()</FUNCTION>
 and 
<FUNCTION>del_tsk()</FUNCTION>
 are supported, all calls which use a valid task ID number check
that the task exists; if not, E_NOEXS is returned</PARA>
</LISTITEM>
<LISTITEM>
<PARA>When supported, 
<FUNCTION>cre_tsk()</FUNCTION>
: the task must not already exist; otherwise E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA>When supported, 
<FUNCTION>cre_tsk()</FUNCTION>
: the requested stack size must not be larger than that statically
configured for the task; see the configuration options
&ldquo;Static initializers&rdquo;, and &ldquo;Default stack size&rdquo;.
Else E_NOMEM</PARA>
</LISTITEM>
<LISTITEM>
<PARA>When supported, 
<FUNCTION>del_tsk()</FUNCTION>
: the underlying 
<EMPHASIS>eCos</EMPHASIS>
 thread must not be running - this would imply either a bug or some
program bypassing the 
&micro;ITRON compatibility layer and manipulating the thread directly.
E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>sta_tsk()</FUNCTION>
: the task must be dormant, else E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>ter_tsk()</FUNCTION>
: the task must not be dormant, else E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>chg_pri()</FUNCTION>
: the task must not be dormant, else E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>rel_wai()</FUNCTION>
: the task must be in 
<varname>WAIT</varname> or <varname>WAIT-SUSPEND</varname>
 state, else E_OBJ</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</SECT2>
</SECT1>
<SECT1 id="compat-uitron-task-dependent-synch-functions">
<TITLE><!-- <index></index> -->Task-Dependent Synchronization Functions</TITLE>
<PARA>These functions are fully supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>sus_tsk</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>rsm_tsk</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>frsm_tsk</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
<programlisting>
ER <FUNCTION>slp_tsk</FUNCTION>( void )</programlisting>
	<programlisting>
ER <FUNCTION>tslp_tsk</FUNCTION>( 
    TMO <EMPHASIS>tmout</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>wup_tsk</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>can_wup</FUNCTION>( 
    INT *<EMPHASIS>p_wupcnt,</EMPHASIS>    ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
<SECT2>
<TITLE>Error checking</TITLE>
<PARA>The following conditions are only checked for, and only return
errors if 
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
is enabled (see the configuration option &ldquo;Return Error Codes for Bad
Params&rdquo;):</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>invalid tskid; less than 1 or greater than 
<LITERAL>CYGNUM_UITRON_TASKS</LITERAL>
returns E_ID</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>wup_tsk()</FUNCTION>
, 
<FUNCTION>sus_tsk()</FUNCTION>
, 
<FUNCTION>rsm_tsk()</FUNCTION>
, 
<FUNCTION>frsm_tsk()</FUNCTION>
 on the calling task returns E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA>dispatching is enabled in 
<FUNCTION>tslp_tsk()</FUNCTION>
 and