uitron.sgml

eCos操作系统源码

<FUNCTION>slp_tsk()</FUNCTION>
, or E_CTX</PARA>
</LISTITEM>
<LISTITEM>
<PARA>tmout must be positive, otherwise E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointer in 
<FUNCTION>can_wup()</FUNCTION>
 is a valid pointer, 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_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><FUNCTION>sus_tsk()</FUNCTION>
: the task must not be dormant, else E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>frsm/rsm_tsk()</FUNCTION>
: the task must be suspended, else E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>tslp/slp_tsk()</FUNCTION>
: return codes E_TMOUT, E_RLWAI and E_DLT
are returned depending on the reason for terminating the sleep</PARA>
</LISTITEM>
<LISTITEM>
<PARA><FUNCTION>wup_tsk()</FUNCTION>
 and 
<FUNCTION>can_wup()</FUNCTION>
: the task must not be dormant, or E_OBJ is returned</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</SECT2>
</SECT1>
<SECT1 id="compat-uitron-sync-and-comm-functions">
<TITLE><!-- <index></index> -->	  Synchronization and Communication Functions</TITLE>
<PARA>These functions are fully supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>sig_sem</FUNCTION>( 
    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>wai_sem</FUNCTION>( 
    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>preq_sem</FUNCTION>( 
    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>twai_sem</FUNCTION>( 
    ID <EMPHASIS>semid,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_sem</FUNCTION>( 
    T_RSEM *<EMPHASIS>pk_rsem ,</EMPHASIS>    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>set_flg</FUNCTION>( 
    ID <EMPHASIS>flgid,</EMPHASIS>    UINT <EMPHASIS>setptn</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>clr_flg</FUNCTION>( 
    ID <EMPHASIS>flgid,</EMPHASIS>    UINT <EMPHASIS>clrptn</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>wai_flg</FUNCTION>( 
    UINT *<EMPHASIS>p_flgptn,</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
    UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>pol_flg</FUNCTION>( 
    UINT *<EMPHASIS>p_flgptn,</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
    UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>twai_flg</FUNCTION>( 
    UINT *<EMPHASIS>p_flgptn</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
    UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_flg</FUNCTION>( 
    T_RFLG *<EMPHASIS>pk_rflg,</EMPHASIS>    ID <EMPHASIS>flgid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>snd_msg</FUNCTION>( 
    ID <EMPHASIS>mbxid,</EMPHASIS>    T_MSG <EMPHASIS>*pk_msg</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>rcv_msg</FUNCTION>( 
    T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>prcv_msg</FUNCTION>( 
    T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>trcv_msg</FUNCTION>( 
    T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid ,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ref_mbx</FUNCTION>( 
    T_RMBX *<EMPHASIS>pk_rmbx,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )</PROGRAMLISTING>
<PARA>The following functions are supported in this release (with
some restrictions) if enabled with the appropriate configuration
option for the object type (for example 
<LITERAL>CYGPKG_UITRON_SEMAS_CREATE_DELETE</LITERAL>):
</PARA>
<PROGRAMLISTING>ER <FUNCTION>cre_sem</FUNCTION>( 
    ID <EMPHASIS>semid,</EMPHASIS>    T_CSEM *<EMPHASIS>pk_csem</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>del_sem</FUNCTION>( 
    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>cre_flg</FUNCTION>( 
    ID <EMPHASIS>flgid,</EMPHASIS>    T_CFLG *<EMPHASIS>pk_cflg</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>del_flg</FUNCTION>( 
    ID <EMPHASIS>flgid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>cre_mbx</FUNCTION>( 
    ID <EMPHASIS>mbxid,</EMPHASIS>    T_CMBX *<EMPHASIS>pk_cmbx</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>del_mbx</FUNCTION>( 
    ID <EMPHASIS>mbxid</EMPHASIS> )</PROGRAMLISTING>
<PARA>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 &micro;ITRON
conformance and it queues tasks in FIFO order, so requests to create
an object with priority queueing of tasks (<literal>pk_cxxx-&gt;xxxatr = TA_TPRI</literal>)
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>
<PARA>For semaphores, the initial semaphore count (pk_csem-&gt;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. </PARA>
<PARA>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. </PARA>
<PARA>For mailboxes, the buffer count is defined statically by kernel
configuration option 
<LITERAL>CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</LITERAL>;
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-&gt;mbxatr)
is not supported. </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_TASKS/SEMAS/MBOXES</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 valid pointer, or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>flag wait pattern must be non-zero, and mode must be valid,
or E_PAR</PARA>
</LISTITEM>
<LISTITEM>
<PARA>return value pointer in flag wait calls is a valid pointer,
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>In create functions 
<FUNCTION>cre_xxx()</FUNCTION>
, when supported, if the object already exists, then E_OBJ</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In any call which can sleep, such as 
<FUNCTION>twai_sem()</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>preq_sem()</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_sem()</FUNCTION>
 <literal>pk_csem-&gt;sematr</literal>
 must be equal to 
<literal>TA_TFIFO</literal>
 else E_RSATR.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In 
<FUNCTION>cre_flg()</FUNCTION>
 <literal>pk_cflg-&gt;flgatr</literal>
 must be either 
<varname>TA_WMUL</varname>
 or 
<varname>TA_WSGL</varname>
 else <varname>E_RSATR</varname>.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>In 
<FUNCTION>cre_mbx()</FUNCTION>
 
<LITERAL>pk_cmbx-&gt;mbxatr</LITERAL>
 must be 
<LITERAL>TA_TFIFO &plus; TA_MFIFO</LITERAL>
 else E_RSATR.</PARA>
</LISTITEM>
</ITEMIZEDLIST>
</SECT2>
</SECT1>
<SECT1 id="compat-uitron-extended-sync-comm-functions">
<TITLE><!-- <index></index> -->Extended Synchronization and Communication Functions</TITLE>
<PARA>None of these functions are supported in this release. </PARA>
</SECT1>
<SECT1 id="compat-uitron-interrupt-management-functions">
<TITLE><!-- <index></index> -->Interrupt management functions</TITLE>
<PARA>These functions are fully supported in this release:</PARA>
<PROGRAMLISTING>void	<FUNCTION> ret_int</FUNCTION>( void )
</programlisting>
<programlisting>
ER <FUNCTION>loc_cpu</FUNCTION>( void )
</programlisting>
<programlisting>
ER <FUNCTION>unl_cpu</FUNCTION>( void )
</programlisting>
<programlisting>
ER <FUNCTION>dis_int</FUNCTION>( 
    UINT <EMPHASIS>eintno</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>ena_int</FUNCTION>( 
    UINT <EMPHASIS>eintno</EMPHASIS> )
</programlisting>
<programlisting>
void	<FUNCTION>ret_wup</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>iwup_tsk</FUNCTION>( 
    ID <EMPHASIS>tskid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>isig_sem</FUNCTION>( 
    ID <EMPHASIS>semid</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>iset_flg</FUNCTION>( 
    ID <EMPHASIS>flgid ,</EMPHASIS>
    UID<EMPHASIS> setptn</EMPHASIS> )
</programlisting>
<programlisting>
ER <FUNCTION>isend_msg</FUNCTION>( 
    ID <EMPHASIS>mbxid ,</EMPHASIS>
    T_MSG<EMPHASIS> *pk_msg</EMPHASIS> )</PROGRAMLISTING>
<PARA>Note that <FUNCTION>ret_int()</FUNCTION> and
the <FUNCTION>ret_wup()</FUNCTION> are  implemented
as macros, containing a &ldquo;return&rdquo; statement.</PARA>
<PARA>Also note that <FUNCTION>ret_wup()</FUNCTION> and
the <FUNCTION>ixxx_yyy()</FUNCTION> style functions
will only work when called from an ISR whose associated DSR is <FUNCTION>cyg_uitron_dsr()</FUNCTION>,
as specified in include file <filename>&lt;cyg/compat/uitron/uit_ifnc.h&gt;</filename>,
which defines the <FUNCTION>ixxx_yyy()</FUNCTION> style
functions also.</PARA>
<PARA>If you are writing interrupt handlers more in the
<EMPHASIS>eCos</EMPHASIS> style, with separate ISR and DSR routines both of
your own devising, do not use these special functions from a DSR: use plain
<FUNCTION>xxx_yyy()</FUNCTION> style functions (with no &lsquo;i&rsquo; prefix)
instead, and do not call any &micro;ITRON functions from the ISR at
all.</PARA>
<PARA>The following functions are not supported in this release: </PARA>
<PROGRAMLISTING>ER <FUNCTION>def_int</FUNCTION>( 
    UINT <EMPHASIS>dintno,</EMPHASIS>
  T_DINT *<EMPHASIS>pk_dint</EMPHASIS> )</programlisting>
	<programlisting>
ER <FUNCTION>chg_iXX</FUNCTION>( 
    UINT <EMPHASIS>iXXXX</EMPHASIS> )
  </programlisting>
	<programlisting>
ER <FUNCTION>ref_iXX</FUNCTION>( 
    UINT * <EMPHASIS>p_iXXXX</EMPHASIS> )</PROGRAMLISTING>
<PARA>These unsupported functions are all Level C (CPU dependent).
Equivalent functionality is available via other <EMPHASIS>eCos</EMPHASIS>-specific
APIs. </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><FUNCTION>loc/unl_cpu()</FUNCTION>