uitron.sgml

eCos/RedBoot for勤研ARM AnywhereII(4510) 含全部源代码

: these must only be called in a 
&micro;ITRON task context, else E_CTX.</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>dis/ena_int()</FUNCTION>
: the interrupt number must be in range as specified by the platform
HAL in qustion, else E_PAR.</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</SECT2>
</SECT1>
<SECT1 id="compat-uitron-memory-pool-mgmt-functions">
<TITLE><!-- <index></index> -->	  Memory pool Management Functions</TITLE>
<PARA>These functions are fully supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>get_blf</FUNCTION>( 
    VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>pget_blf</FUNCTION>( 
    VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>tget_blf</FUNCTION>( 
    VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>rel_blf</FUNCTION>( 
    ID <EMPHASIS>mpfid,</EMPHASIS>    VP <EMPHASIS>blf</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_mpf</FUNCTION>( 
    T_RMPF *<EMPHASIS>pk_rmpf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>get_blk</FUNCTION>( 
    VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>pget_blk</FUNCTION>( 
    VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>tget_blk</FUNCTION>( 
    VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>rel_blk</FUNCTION>( 
    ID <EMPHASIS>mplid,</EMPHASIS>    VP <EMPHASIS>blk</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_mpl</FUNCTION>( 
    T_RMPL *<EMPHASIS>pk_rmpl,</EMPHASIS>    ID <EMPHASIS>mplid )
</EMPHASIS></programlisting>

<PARA>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. </PARA>
<PARA>The following functions are supported in this release, when
enabled with 
<LITERAL>CYGPKG_UITRON_MEMPOOLVAR_CREATE_DELETE</LITERAL>
or 
<LITERAL>CYGPKG_UITRON_MEMPOOLFIXED_CREATE_DELETE</LITERAL>
as appropriate, with some restrictions: </PARA>
<PROGRAMLISTING>ER <FUNCTION>cre_mpl</FUNCTION>( 
    ID <EMPHASIS>mplid,</EMPHASIS>    T_CMPL *<EMPHASIS>pk_cmpl</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>del_mpl</FUNCTION>( 
    ID <EMPHASIS>mplid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>cre_mpf</FUNCTION>( 
    ID <EMPHASIS>mpfid,</EMPHASIS>    T_CMPF *<EMPHASIS>pk_cmpf</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>del_mpf</FUNCTION>( 
    ID <EMPHASIS>mpfid</EMPHASIS> )</PROGRAMLISTING>
<PARA>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-&gt;mplsz) or the number of fixed-size
blocks (pk_cmpf-&gt;mpfcnt) times the block size
(pk_cmpf-&gt;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 <FUNCTION>del_mpl()</FUNCTION> and <FUNCTION>del_mpf()</FUNCTION> 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. </PARA>
<PARA>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 &micro;ITRON conformance and
it queues tasks in FIFO order, so requests to create an object with
priority queueing of tasks (pk_cxxx-&gt;xxxatr = TA_TPRI)
are rejected with E_RSATR. Additional undefined bits in
the attributes fields must be zero. </PARA>
<PARA>In general, extended information (pk_cxxx-&gt;exinf)
is ignored. </PARA>
<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:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>invalid object id; less than 1 or greater than 
<LITERAL>CYGNUM_UITRON_MEMPOOLVAR/MEMPOOLFIXED</LITERAL>
as appropriate returns E_ID</PARA>
</LISTITEM>
<LISTITEM>
<PARA>dispatching is enabled in any call which can sleep, or
E_CTX</PARA>
</LISTITEM>
<LISTITEM>
<PARA>tmout must be positive, otherwise E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>pk_cxxx pointers in 
<FUNCTION>cre_xxx()</FUNCTION>
 must be valid pointers, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointer in 
<FUNCTION>ref_xxx()</FUNCTION>
 is a valid pointer, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointers in get block routines is a valid
pointer, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>blocksize request in get variable block routines is greater
than zero, or E_PAR</PARA>
</LISTITEM>
</ITEMIZEDLIST>
<PARA>The following conditions are checked for, and can return error
codes, regardless of the setting of 
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>:
</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>When create and delete functions 
<FUNCTION>cre_xxx()</FUNCTION>
 and 
<FUNCTION>del_xxx()</FUNCTION>
 are supported, all calls which use a valid object ID number check
that the object exists. If not, E_NOEXS is returned.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>When create functions 
<FUNCTION>cre_xxx()</FUNCTION>
 are supported, if the object already exists, then E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In any call which can sleep, such as 
<FUNCTION>get_blk()</FUNCTION>
: return codes E_TMOUT, E_RLWAI, E_DLT
or of course E_OK are returned depending on the reason
for terminating the sleep</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In polling functions such as 
<FUNCTION>pget_blk()</FUNCTION>
return codes E_TMOUT or E_OK are returned depending
on the state of the synchronization object</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In creation functions, the attributes must be compatible
with the selected underlying kernel configuration: in 
<FUNCTION>cre_mpl()</FUNCTION>
 
<LITERAL>pk_cmpl-&gt;mplatr</LITERAL>
 must be equal to 
<LITERAL>TA_TFIFO</LITERAL>
 else E_RSATR.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In 
<FUNCTION>cre_mpf()</FUNCTION>
 
<LITERAL>pk_cmpf-&gt;mpfatr</LITERAL>
 must be equal to 
<LITERAL>TA_TFIFO</LITERAL>
 else E_RSATR.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In creation functions, the requested size of the memory
pool must not be larger than that statically configured for the
pool else E_RSATR; see the configuration option
&ldquo;Option: Static initializers&rdquo;.
 In 
<FUNCTION>cre_mpl()</FUNCTION>
 
<LITERAL>pk_cmpl-&gt;mplsz</LITERAL>
 is the field of interest</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In 
<FUNCTION>cre_mpf()</FUNCTION>
 the product of 
<LITERAL>pk_cmpf-&gt;blfsz</LITERAL>
 and 
<LITERAL>pk_cmpf-&gt;mpfcnt</LITERAL>
 must be smaller than the memory statically configured for the pool
else E_RSATR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In functions which return memory to the pool 
<FUNCTION>rel_blk()</FUNCTION>
 and 
<FUNCTION>rel_blf()</FUNCTION>
, if the free fails, for example because the memory did not come
from that pool originally, then E_PAR is returned</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</SECT2>
</SECT1>
<SECT1 id="compat-uitron-time-mgmt-functions">
<TITLE><!-- <index></index> -->Time Management Functions</TITLE>
<PARA>These functions are fully supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>set_tim</FUNCTION>( 
    SYSTIME *<EMPHASIS>pk_tim</EMPHASIS> )</PROGRAMLISTING>
<CAUTION>
<PARA>	    Setting the time may cause erroneous operation of the
	    kernel, for example a task performing a wait with a
	    time-out may never awaken.</PARA>
</CAUTION>
<PROGRAMLISTING>ER <FUNCTION>get_tim</FUNCTION>( 
    SYSTIME *<EMPHASIS>pk_tim</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>dly_tsk</FUNCTION>( 
    DLYTIME <EMPHASIS>dlytim</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>def_cyc</FUNCTION>( 
    HNO <EMPHASIS>cycno,</EMPHASIS>    T_DCYC *<EMPHASIS>pk_dcyc</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>act_cyc</FUNCTION>( 
    HNO <EMPHASIS>cycno,</EMPHASIS>    UINT <EMPHASIS>cycact</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_cyc</FUNCTION>( 
    T_RCYC *<EMPHASIS>pk_rcyc,</EMPHASIS>    HNO <EMPHASIS>cycno</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>def_alm</FUNCTION>( 
    HNO <EMPHASIS>almno,</EMPHASIS>    T_DALM *<EMPHASIS>pk_dalm</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_alm</FUNCTION>( 
    T_RALM *<EMPHASIS>pk_ralm,</EMPHASIS>    HNO <EMPHASIS>almno</EMPHASIS> )
</programlisting>
<programlisting>
void <FUNCTION>ret_tmr</FUNCTION>( void )</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:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>invalid handler number; less than 1 or greater than 
<LITERAL>CYGNUM_UITRON_CYCLICS/ALARMS</LITERAL>
as appropriate, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>dispatching is enabled in 
<FUNCTION>dly_tsk()</FUNCTION>
, or E_CTX</PARA>
</LISTITEM>
<LISTITEM>
<PARA>dlytim must be positive or zero, otherwise E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointer in 
<FUNCTION>ref_xxx()</FUNCTION>
 is a valid pointer, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>params within pk_dalm and pk_dcyc must
be valid, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>cycact in 
<FUNCTION>act_cyc()</FUNCTION>
 must be valid, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>handler must be defined in 
<FUNCTION>ref_xxx()</FUNCTION>
 and 
<FUNCTION>act_cyc()</FUNCTION>
, or E_NOEXS</PARA>
</LISTITEM>
<LISTITEM>
<PARA>parameter pointer must be a good pointer in 
<FUNCTION>get_tim()</FUNCTION>
 and 
<FUNCTION>set_tim()</FUNCTION>
, otherwise E_PAR is returned</PARA>
</LISTITEM>
</ITEMIZEDLIST>
<PARA>The following conditions are checked for, and can return
	  error codes, regardless of the setting of
<LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA><FUNCTION>dly_tsk()</FUNCTION>
: return code E_RLWAI is returned depending on the reason
for terminating the sleep</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</sect2>
</SECT1>
<SECT1 id="compat-uitron-system-mgmt-functions">
<TITLE><!-- <index></index> -->	  System Management Functions</TITLE>
<PARA>These functions are fully supported in this release:
	</PARA>
<PROGRAMLISTING>ER <FUNCTION>get_ver</FUNCTION>( 
    T_VER *<EMPHASIS>pk_ver</EMPHASIS> )
</PROGRAMLISTING>
<PROGRAMLISTING>ER <FUNCTION>ref_sys</FUNCTION>( 
    T_RSYS *<EMPHASIS>pk_rsys</EMPHASIS> )
</PROGRAMLISTING>
<PROGRAMLISTING>ER <FUNCTION>ref_cfg</FUNCTION>( 
    T_RCFG *<EMPHASIS>pk_rcfg</EMPHASIS> )
</PROGRAMLISTING>
<PARA>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. </PARA>
<PARA>These functions are not supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>def_svc</FUNCTION>( 
    FN <EMPHASIS>s_fncd,</EMPHASIS>
    T_DSVC *<EMPHASIS>pk_dsvc</EMPHASIS> )
</PROGRAMLISTING>
<PROGRAMLISTING>ER <FUNCTION>def_exc</FUNCTION>( 
    UINT <EMPHASIS>exckind,</EMPHASIS>