packages/compat/uitron/v2_0/doc/uitron.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     uitron.sgml                                                 -->
   6 <!--                                                                 -->
   7 <!--     uITRON Compatibility                                        -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <part id="compat-uitron">
  33   <title>&micro;ITRON</title>
  34 <CHAPTER id="compat-uitron-microitron-api">
  35 <TITLE><!-- <xref> -->&micro;ITRON API</TITLE>
  36 <SECT1 id="compat-uitron-introduction">
  37 <TITLE><!-- <index></index> -->Introduction to &micro;ITRON</TITLE>
  38 <PARA>The <!-- <index></index> -->&micro;ITRON specification
  39 defines a highly flexible operating system architecture designed
  40 specifically for application in embedded systems. The specification addresses
  41 features which are common to the majority of processor architectures and
  42 deliberately avoids virtualization which would adversely impact
  43 real-time performance. The &micro;ITRON specification
  44 may be implemented on many hardware platforms and provides significant
  45 advantages by reducing the effort involved in understanding and
  46 porting application software to new processor architectures. </PARA>
  47 <PARA>Several revisions of the &micro;ITRON specification exist.
  48         In this release, <EMPHASIS>eCos</EMPHASIS> supports the
  49         &micro;ITRON version 3.02 specification, with complete
  50         &ldquo;Standard functionality&rdquo; (level S), plus many
  51         &ldquo;Extended&rdquo; (level E) functions. The definitive
  52         reference on &micro;ITRON is Dr. Sakamura&rsquo;s book:
  53           <CITETITLE>&micro;ITRON 3.0, An Open and Portable Real-Time Operating
  54           System for Embedded Systems</CITETITLE>.
  55         The book can be purchased from the IEEE Press, and
  56         an ASCII version of the standard can be found online at
  57 <ulink url="http://www.itron.gr.jp/">http://www.itron.gr.jp/</ulink>.
  58 The old address
  59 <ulink url="http://tron.um.u-tokyo.ac.jp/TRON/ITRON/">
  60 http://tron.um.u-tokyo.ac.jp/TRON/ITRON/</ulink>
  61 still exists as a mirror site. </PARA>
  62 </SECT1>
  63 <SECT1 id="compat-uitron-over-ecos">
  64 <TITLE><!-- <index></index> -->&micro;ITRON and <EMPHASIS>eCos</EMPHASIS></TITLE>
  65 <PARA>The <EMPHASIS>eCos</EMPHASIS> kernel implements the functionality
  66 used by the &micro;ITRON compatibility subsystem.
  67 The configuration of the kernel influences the behavior of &micro;ITRON
  68 programs.</PARA>
  69 <PARA>In particular, the default configuration has time slicing
  70 (also known as round-robin scheduling) switched on; this means that
  71 a task can be moved from <varname>RUN</varname> state
  72 to <varname>READY</varname> state at any time, in
  73 order that one of its peers may run. This is not strictly conformant
  74 to the &micro;ITRON specification, which
  75 states that timeslicing may be implemented by periodically issuing
  76 a <literal>rot_rdq(0)</literal> call from
  77 within a periodic task or cyclic handler; otherwise it is expected
  78 that a task runs until it is pre-empted in consequence of synchronization
  79 or communication calls it makes, or the effects of an interrupt
  80 or other external event on a higher priority task cause that task
  81 to become <varname>READY</varname>. To disable timeslicing
  82 functionality in the kernel and &micro;ITRON
  83 compatibility environment, please disable the
  84 <LITERAL>CYGSEM_KERNEL_SCHED_TIMESLICE</LITERAL>
  85 configuration option in the kernel package. A description of kernel
  86 scheduling is in <xref linkend="kernel-overview">. </PARA>
  87 <PARA>For another example, the semantics of task queueing when waiting
  88 on a synchronization object depend solely on the way the underlying
  89 kernel is configured. As discussed above, the multi-level queue
  90 scheduler is the only one which is &micro;ITRON
  91 compliant, and it queues waiting tasks in FIFO order. Future releases
  92 of that scheduler might be configurable to support priority ordering
  93 of task queues. Other schedulers might be different again: for example
  94 the bitmap scheduler can be used with the &micro;ITRON
  95 compatibility layer, even though it only allows one task at each
  96 priority and as such is not &micro;ITRON
  97 compliant, but it supports only priority ordering of task queues.
  98 So which queueing scheme is supported is not really a property of
  99 the &micro;ITRON compatibility layer; it
 100 depends on the kernel. </PARA>
 101 <PARA>In this version of the &micro;ITRON
 102 compatibility layer, the calls to disable and enable scheduling
 103 and interrupts (<FUNCTION>dis_dsp()</FUNCTION>,
 104 <FUNCTION>ena_dsp()</FUNCTION>, <FUNCTION>loc_cpu()</FUNCTION>
 105 and <FUNCTION>unl_cpu()</FUNCTION>)
 106 call underlying kernel functions; in particular, the <FUNCTION>xxx_dsp()</FUNCTION> functions
 107 lock the scheduler entirely, which prevents dispatching of DSRs; functions
 108 implemented by DSRs include clock counters and alarm timers. Thus time &ldquo;stops&rdquo; while
 109 dispatching is disabled with <FUNCTION>dis_dsp()</FUNCTION>. </PARA>
 110 <PARA>Like all parts of the <EMPHASIS>eCos</EMPHASIS> system, the
 111 detailed semantics of the &micro;ITRON layer
 112 are dependent on its configuration and the configuration of other components
 113 that it uses. The &micro;ITRON configuration
 114 options are all defined in the file <filename>pkgconf/uitron.h</filename>,
 115 and can be set using the configuration tool or editing the
 116 <filename>.ecc</filename>
 117 file in your build directory by hand. </PARA>
 118 <PARA>An important configuration option for the &micro;ITRON
 119 compatibility layer is &ldquo;Option: Return Error Codes for Bad Params&rdquo;
 120 (
 121 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 122 ), which allows a lot of the error
 123 checking code in the &micro;ITRON compatibility layer to
 124 be removed. Of course this leaves a program open to undetected errors,
 125 so it should only be used once an application is fully debugged and
 126 tested. Its benefits include reduced code size and faster execution.
 127 However, it affects the API significantly, in that with this option
 128 enabled, bad calls do not return errors, but cause an assert
 129 failure (if that is itself enabled) or malfunction internally. There
 130 is discussion in more detail about this in each section below.</PARA>
 131 <PARA>We now give a brief description of the &micro;ITRON
 132 functions which are implemented in this release. Note that all C
 133 and C&plus;&plus; source files should have the following <literal>#include</literal> statement: </PARA>
 134 <PROGRAMLISTING>#include &lt;cyg/compat/uitron/uit_func.h&gt;</PROGRAMLISTING>
 135 </SECT1>
 136 <SECT1 id="compat-uitron-task-management-functions">
 137 <TITLE><!-- <index></index> -->Task Management Functions</TITLE>
 138 <PARA>The following functions are fully supported in this release: </PARA>
 139 <PROGRAMLISTING>ER <FUNCTION>sta_tsk</FUNCTION>(
 140   ID <EMPHASIS>tskid,</EMPHASIS>
 141   INT <EMPHASIS>stacd</EMPHASIS> )</programlisting>
 142         <programlisting>
 143 void <FUNCTION>ext_tsk</FUNCTION>( void )</programlisting>
 144         <programlisting>
 145 void <FUNCTION>exd_tsk</FUNCTION>( void )</programlisting>
 146         <programlisting>
 147 ER <FUNCTION>dis_dsp</FUNCTION>( void )</programlisting>
 148         <programlisting>
 149 ER <FUNCTION>ena_dsp</FUNCTION>( void )</programlisting>
 150         <programlisting>
 151 ER <FUNCTION>chg_pri</FUNCTION>(
 152   ID <EMPHASIS>tskid,</EMPHASIS>
 153   PRI <EMPHASIS>tskpri</EMPHASIS> )</programlisting>
 154         <programlisting>
 155 ER <FUNCTION>rot_rdq</FUNCTION>(
 156   PRI <EMPHASIS>tskpri</EMPHASIS> )</programlisting>
 157         <programlisting>
 158 ER <FUNCTION>get_tid</FUNCTION>(
 159   ID *<EMPHASIS>p_tskid</EMPHASIS> )</programlisting>
 160         <programlisting>
 161 ER <FUNCTION>ref_tsk</FUNCTION>(
 162   T_RTSK *<EMPHASIS>pk_rtsk,</EMPHASIS>
 163   ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 164         <programlisting>
 165 ER <FUNCTION>ter_tsk</FUNCTION>(
 166   ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 167         <programlisting>
 168 ER <FUNCTION>rel_wai</FUNCTION>(
 169   ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
 170 <PARA>The following two functions are supported in this release,
 171 when enabled with the configuration option
 172 <LITERAL>CYGPKG_UITRON_TASKS_CREATE_DELETE</LITERAL>
 173 with some restrictions:</PARA>
 174 <PROGRAMLISTING>ER <FUNCTION>cre_tsk</FUNCTION>(
 175   ID <EMPHASIS>tskid,</EMPHASIS>
 176   T_CTSK *<EMPHASIS>pk_ctsk</EMPHASIS> )</programlisting>
 177         <programlisting>
 178 ER <FUNCTION>del_tsk</FUNCTION>(
 179   ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
 180 <PARA>These functions are restricted as follows:</PARA>
 181 <PARA>Because of the static initialization facilities provided for
 182 system objects, a task is allocated stack space statically in the
 183 configuration. So while tasks can be created and deleted, the same
 184 stack space is used for that task (task ID number) each time. Thus
 185 the stack size (pk_ctsk-&gt;stksz) requested in <FUNCTION>cre_tsk()</FUNCTION> is
 186 checked for being less than that which was statically allocated,
 187 and otherwise ignored. This ensures that the new task will have
 188 enough stack to run. For this reason <FUNCTION>del_tsk()</FUNCTION> does
 189 not in any sense free the memory that was in use for the task's
 190 stack. </PARA>
 191 <PARA>The task attributes (pk_ctsk-&gt;tskatr) are
 192 ignored; current versions of <EMPHASIS>eCos</EMPHASIS> do not need
 193 to know whether a task is written in assembler or C/C&plus;&plus; so
 194 long as the procedure call standard appropriate to the CPU is followed.</PARA>
 195 <PARA>Extended information (pk_ctsk-&gt;exinf) is
 196           ignored.</PARA>
 197 <SECT2>
 198 <TITLE>Error checking</TITLE>
 199 <PARA>For all these calls, an invalid task id (tskid) (less than
 200 1 or greater than the number of configured tasks) only returns E_ID
 201 when bad params return errors (
 202 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 203 is enabled, see above).</PARA>
 204 <PARA>Similarly, the following conditions are only checked for,
 205 and only return errors if
 206 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 207 is enabled:</PARA>
 208 <ITEMIZEDLIST>
 209 <LISTITEM>
 210 <PARA>pk_crtk in
 211 <FUNCTION>cre_tsk()</FUNCTION>
 212  is a valid pointer, otherwise return E_PAR</PARA>
 213 </LISTITEM>
 214 <LISTITEM>
 215 <PARA><FUNCTION>ter_tsk()</FUNCTION>
 216  or
 217 <FUNCTION>rel_wai()</FUNCTION>
 218  on the calling task returns E_OBJ</PARA>
 219 </LISTITEM>
 220 <LISTITEM>
 221 <PARA>the CPU is not locked already in
 222 <FUNCTION>dis_dsp()</FUNCTION>
 223  and
 224 <FUNCTION>ena_dsp()</FUNCTION>
 225 ; returns E_CTX</PARA>
 226 </LISTITEM>
 227 <LISTITEM>
 228 <PARA>priority level in
 229 <FUNCTION>chg_pri()</FUNCTION>
 230  and
 231 <FUNCTION>rot_rdq()</FUNCTION>
 232  is checked for validity, E_PAR</PARA>
 233 </LISTITEM>
 234 <LISTITEM>
 235 <PARA>return value pointer in
 236 <FUNCTION>get_tid()</FUNCTION>
 237  and
 238 <FUNCTION>ref_tsk()</FUNCTION>
 239  is a valid pointer, or E_PAR</PARA>
 240 </LISTITEM>
 241 </ITEMIZEDLIST>
 242 <PARA>The following conditions are checked for, and return
 243             error codes if appropriate, regardless of the setting of
 244 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 245 :</PARA>
 246 <ITEMIZEDLIST>
 247 <LISTITEM>
 248 <PARA>When create and delete functions
 249 <FUNCTION>cre_tsk()</FUNCTION>
 250  and
 251 <FUNCTION>del_tsk()</FUNCTION>
 252  are supported, all calls which use a valid task ID number check
 253 that the task exists; if not, E_NOEXS is returned</PARA>
 254 </LISTITEM>
 255 <LISTITEM>
 256 <PARA>When supported,
 257 <FUNCTION>cre_tsk()</FUNCTION>
 258 : the task must not already exist; otherwise E_OBJ</PARA>
 259 </LISTITEM>
 260 <LISTITEM>
 261 <PARA>When supported,
 262 <FUNCTION>cre_tsk()</FUNCTION>
 263 : the requested stack size must not be larger than that statically
 264 configured for the task; see the configuration options
 265 &ldquo;Static initializers&rdquo;, and &ldquo;Default stack size&rdquo;.
 266 Else E_NOMEM</PARA>
 267 </LISTITEM>
 268 <LISTITEM>
 269 <PARA>When supported,
 270 <FUNCTION>del_tsk()</FUNCTION>
 271 : the underlying
 272 <EMPHASIS>eCos</EMPHASIS>
 273  thread must not be running - this would imply either a bug or some
 274 program bypassing the
 275 &micro;ITRON compatibility layer and manipulating the thread directly.
 276 E_OBJ</PARA>
 277 </LISTITEM>
 278 <LISTITEM>
 279 <PARA><FUNCTION>sta_tsk()</FUNCTION>
 280 : the task must be dormant, else E_OBJ</PARA>
 281 </LISTITEM>
 282 <LISTITEM>
 283 <PARA><FUNCTION>ter_tsk()</FUNCTION>
 284 : the task must not be dormant, else E_OBJ</PARA>
 285 </LISTITEM>
 286 <LISTITEM>
 287 <PARA><FUNCTION>chg_pri()</FUNCTION>
 288 : the task must not be dormant, else E_OBJ</PARA>
 289 </LISTITEM>
 290 <LISTITEM>
 291 <PARA><FUNCTION>rel_wai()</FUNCTION>
 292 : the task must be in
 293 <varname>WAIT</varname> or <varname>WAIT-SUSPEND</varname>
 294  state, else E_OBJ</PARA>
 295 </LISTITEM>
 296 </ITEMIZEDLIST>
 297 </SECT2>
 298 </SECT1>
 299 <SECT1 id="compat-uitron-task-dependent-synch-functions">
 300 <TITLE><!-- <index></index> -->Task-Dependent Synchronization Functions</TITLE>
 301 <PARA>These functions are fully supported in this release: </PARA>
 302 <PROGRAMLISTING>ER <FUNCTION>sus_tsk</FUNCTION>(
 303     ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 304         <programlisting>
 305 ER <FUNCTION>rsm_tsk</FUNCTION>(
 306     ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 307         <programlisting>
 308 ER <FUNCTION>frsm_tsk</FUNCTION>(
 309     ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 310 <programlisting>
 311 ER <FUNCTION>slp_tsk</FUNCTION>( void )</programlisting>
 312         <programlisting>
 313 ER <FUNCTION>tslp_tsk</FUNCTION>(
 314     TMO <EMPHASIS>tmout</EMPHASIS> )</programlisting>
 315         <programlisting>
 316 ER <FUNCTION>wup_tsk</FUNCTION>(
 317     ID <EMPHASIS>tskid</EMPHASIS> )</programlisting>
 318         <programlisting>
 319 ER <FUNCTION>can_wup</FUNCTION>(
 320     INT *<EMPHASIS>p_wupcnt,</EMPHASIS>    ID <EMPHASIS>tskid</EMPHASIS> )</PROGRAMLISTING>
 321 <SECT2>
 322 <TITLE>Error checking</TITLE>
 323 <PARA>The following conditions are only checked for, and only return
 324 errors if
 325 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 326 is enabled (see the configuration option &ldquo;Return Error Codes for Bad
 327 Params&rdquo;):</PARA>
 328 <ITEMIZEDLIST>
 329 <LISTITEM>
 330 <PARA>invalid tskid; less than 1 or greater than
 331 <LITERAL>CYGNUM_UITRON_TASKS</LITERAL>
 332 returns E_ID</PARA>
 333 </LISTITEM>
 334 <LISTITEM>
 335 <PARA><FUNCTION>wup_tsk()</FUNCTION>
 336 ,
 337 <FUNCTION>sus_tsk()</FUNCTION>
 338 ,
 339 <FUNCTION>rsm_tsk()</FUNCTION>
 340 ,
 341 <FUNCTION>frsm_tsk()</FUNCTION>
 342  on the calling task returns E_OBJ</PARA>
 343 </LISTITEM>
 344 <LISTITEM>
 345 <PARA>dispatching is enabled in
 346 <FUNCTION>tslp_tsk()</FUNCTION>
 347  and
 348 <FUNCTION>slp_tsk()</FUNCTION>
 349 , or E_CTX</PARA>
 350 </LISTITEM>
 351 <LISTITEM>
 352 <PARA>tmout must be positive, otherwise E_PAR</PARA>
 353 </LISTITEM>
 354 <LISTITEM>
 355 <PARA>return value pointer in
 356 <FUNCTION>can_wup()</FUNCTION>
 357  is a valid pointer, or E_PAR</PARA>
 358 </LISTITEM>
 359 </ITEMIZEDLIST>
 360 <PARA>The following conditions are checked for, and can
 361             return error codes, regardless of the setting of
 362 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>:
 363 </PARA>
 364 <ITEMIZEDLIST>
 365 <LISTITEM>
 366 <PARA>When create and delete functions
 367 <FUNCTION>cre_tsk()</FUNCTION>
 368  and
 369 <FUNCTION>del_tsk()</FUNCTION>
 370  are supported, all calls which use a valid task ID number check
 371 that the task exists; if not, E_NOEXS is returned</PARA>
 372 </LISTITEM>
 373 <LISTITEM>
 374 <PARA><FUNCTION>sus_tsk()</FUNCTION>
 375 : the task must not be dormant, else E_OBJ</PARA>
 376 </LISTITEM>
 377 <LISTITEM>
 378 <PARA><FUNCTION>frsm/rsm_tsk()</FUNCTION>
 379 : the task must be suspended, else E_OBJ</PARA>
 380 </LISTITEM>
 381 <LISTITEM>
 382 <PARA><FUNCTION>tslp/slp_tsk()</FUNCTION>
 383 : return codes E_TMOUT, E_RLWAI and E_DLT
 384 are returned depending on the reason for terminating the sleep</PARA>
 385 </LISTITEM>
 386 <LISTITEM>
 387 <PARA><FUNCTION>wup_tsk()</FUNCTION>
 388  and
 389 <FUNCTION>can_wup()</FUNCTION>
 390 : the task must not be dormant, or E_OBJ is returned</PARA>
 391 </LISTITEM>
 392 </ITEMIZEDLIST>
 393 </SECT2>
 394 </SECT1>
 395 <SECT1 id="compat-uitron-sync-and-comm-functions">
 396 <TITLE><!-- <index></index> -->   Synchronization and Communication Functions</TITLE>
 397 <PARA>These functions are fully supported in this release: </PARA>
 398 <PROGRAMLISTING>ER <FUNCTION>sig_sem</FUNCTION>(
 399     ID <EMPHASIS>semid</EMPHASIS> )
 400 </programlisting>
 401 <programlisting>
 402 ER <FUNCTION>wai_sem</FUNCTION>(
 403     ID <EMPHASIS>semid</EMPHASIS> )
 404 </programlisting>
 405 <programlisting>
 406 ER <FUNCTION>preq_sem</FUNCTION>(
 407     ID <EMPHASIS>semid</EMPHASIS> )
 408 </programlisting>
 409 <programlisting>
 410 ER <FUNCTION>twai_sem</FUNCTION>(
 411     ID <EMPHASIS>semid,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
 412 </programlisting>
 413 <programlisting>
 414 ER <FUNCTION>ref_sem</FUNCTION>(
 415     T_RSEM *<EMPHASIS>pk_rsem ,</EMPHASIS>    ID <EMPHASIS>semid</EMPHASIS> )
 416 </programlisting>
 417 <programlisting>
 418 ER <FUNCTION>set_flg</FUNCTION>(
 419     ID <EMPHASIS>flgid,</EMPHASIS>    UINT <EMPHASIS>setptn</EMPHASIS> )
 420 </programlisting>
 421 <programlisting>
 422 ER <FUNCTION>clr_flg</FUNCTION>(
 423     ID <EMPHASIS>flgid,</EMPHASIS>    UINT <EMPHASIS>clrptn</EMPHASIS> )
 424 </programlisting>
 425 <programlisting>
 426 ER <FUNCTION>wai_flg</FUNCTION>(
 427     UINT *<EMPHASIS>p_flgptn,</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
 428     UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode</EMPHASIS> )
 429 </programlisting>
 430 <programlisting>
 431 ER <FUNCTION>pol_flg</FUNCTION>(
 432     UINT *<EMPHASIS>p_flgptn,</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
 433     UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode</EMPHASIS> )
 434 </programlisting>
 435 <programlisting>
 436 ER <FUNCTION>twai_flg</FUNCTION>(
 437     UINT *<EMPHASIS>p_flgptn</EMPHASIS>    ID <EMPHASIS>flgid ,</EMPHASIS>
 438     UINT <EMPHASIS>waiptn ,</EMPHASIS>    UINT <EMPHASIS>wfmode,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
 439 </programlisting>
 440 <programlisting>
 441 ER <FUNCTION>ref_flg</FUNCTION>(
 442     T_RFLG *<EMPHASIS>pk_rflg,</EMPHASIS>    ID <EMPHASIS>flgid</EMPHASIS> )
 443 </programlisting>
 444 <programlisting>
 445 ER <FUNCTION>snd_msg</FUNCTION>(
 446     ID <EMPHASIS>mbxid,</EMPHASIS>    T_MSG <EMPHASIS>*pk_msg</EMPHASIS> )
 447 </programlisting>
 448 <programlisting>
 449 ER <FUNCTION>rcv_msg</FUNCTION>(
 450     T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )
 451 </programlisting>
 452 <programlisting>
 453 ER <FUNCTION>prcv_msg</FUNCTION>(
 454     T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )
 455 </programlisting>
 456 <programlisting>
 457 ER <FUNCTION>trcv_msg</FUNCTION>(
 458     T_MSG **<EMPHASIS>ppk_msg,</EMPHASIS>    ID <EMPHASIS>mbxid ,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
 459 </programlisting>
 460 <programlisting>
 461 ER <FUNCTION>ref_mbx</FUNCTION>(
 462     T_RMBX *<EMPHASIS>pk_rmbx,</EMPHASIS>    ID <EMPHASIS>mbxid</EMPHASIS> )</PROGRAMLISTING>
 463 <PARA>The following functions are supported in this release (with
 464 some restrictions) if enabled with the appropriate configuration
 465 option for the object type (for example
 466 <LITERAL>CYGPKG_UITRON_SEMAS_CREATE_DELETE</LITERAL>):
 467 </PARA>
 468 <PROGRAMLISTING>ER <FUNCTION>cre_sem</FUNCTION>(
 469     ID <EMPHASIS>semid,</EMPHASIS>    T_CSEM *<EMPHASIS>pk_csem</EMPHASIS> )
 470 </programlisting>
 471 <programlisting>
 472 ER <FUNCTION>del_sem</FUNCTION>(
 473     ID <EMPHASIS>semid</EMPHASIS> )
 474 </programlisting>
 475 <programlisting>
 476 ER <FUNCTION>cre_flg</FUNCTION>(
 477     ID <EMPHASIS>flgid,</EMPHASIS>    T_CFLG *<EMPHASIS>pk_cflg</EMPHASIS> )
 478 </programlisting>
 479 <programlisting>
 480 ER <FUNCTION>del_flg</FUNCTION>(
 481     ID <EMPHASIS>flgid</EMPHASIS> )
 482 </programlisting>
 483 <programlisting>
 484 ER <FUNCTION>cre_mbx</FUNCTION>(
 485     ID <EMPHASIS>mbxid,</EMPHASIS>    T_CMBX *<EMPHASIS>pk_cmbx</EMPHASIS> )
 486 </programlisting>
 487 <programlisting>
 488 ER <FUNCTION>del_mbx</FUNCTION>(
 489     ID <EMPHASIS>mbxid</EMPHASIS> )</PROGRAMLISTING>
 490 <PARA>In general the queueing order when waiting on a synchronization
 491 object depends on the underlying kernel configuration. The multi-level
 492 queue scheduler is required for strict &micro;ITRON
 493 conformance and it queues tasks in FIFO order, so requests to create
 494 an object with priority queueing of tasks (<literal>pk_cxxx-&gt;xxxatr = TA_TPRI</literal>)
 495 are rejected with E_RSATR. Additional undefined bits in
 496 the attributes fields must be zero. </PARA>
 497 <PARA>In general, extended information (pk_cxxx-&gt;exinf)
 498 is ignored. </PARA>
 499 <PARA>For semaphores, the initial semaphore count (pk_csem-&gt;isemcnt)
 500 is supported; the new semaphore's count is set. The maximum
 501 count is not supported, and is not in fact defined in type pk_csem. </PARA>
 502 <PARA>For flags, multiple tasks are allowed to wait. Because single
 503 task waiting is a subset of this, the W bit (TA_WMUL) of
 504 the flag attributes is ignored; all other bits must be zero. The
 505 initial flag value is supported. </PARA>
 506 <PARA>For mailboxes, the buffer count is defined statically by kernel
 507 configuration option
 508 <LITERAL>CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</LITERAL>;
 509 therefore the buffer count field is not supported and is not in
 510 fact defined in type pk_cmbx. Queueing of messages is FIFO
 511 ordered only, so TA_MPRI (in pk_cmbx-&gt;mbxatr)
 512 is not supported. </PARA>
 513 <SECT2>
 514 <TITLE>Error checking</TITLE>
 515 <PARA>The following conditions are only checked for, and only return
 516 errors if
 517 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 518 is enabled:</PARA>
 519 <ITEMIZEDLIST>
 520 <LISTITEM>
 521 <PARA>invalid object id; less than 1 or greater than
 522 <LITERAL>CYGNUM_UITRON_TASKS/SEMAS/MBOXES</LITERAL>
 523 as appropriate returns E_ID</PARA>
 524 </LISTITEM>
 525 <LISTITEM>
 526 <PARA>dispatching is enabled in any call which can sleep, or
 527 E_CTX</PARA>
 528 </LISTITEM>
 529 <LISTITEM>
 530 <PARA>tmout must be positive, otherwise E_PAR</PARA>
 531 </LISTITEM>
 532 <LISTITEM>
 533 <PARA>pk_cxxx pointers in
 534 <FUNCTION>cre_xxx()</FUNCTION>
 535  must be valid pointers, or E_PAR</PARA>
 536 </LISTITEM>
 537 <LISTITEM>
 538 <PARA>return value pointer in
 539 <FUNCTION>ref_xxx()</FUNCTION>
 540  is valid pointer, or E_PAR</PARA>
 541 </LISTITEM>
 542 <LISTITEM>
 543 <PARA>flag wait pattern must be non-zero, and mode must be valid,
 544 or E_PAR</PARA>
 545 </LISTITEM>
 546 <LISTITEM>
 547 <PARA>return value pointer in flag wait calls is a valid pointer,
 548 or E_PAR</PARA>
 549 </LISTITEM>
 550 </ITEMIZEDLIST>
 551 <PARA>The following conditions are checked for, and can return error
 552 codes, regardless of the setting of
 553 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 554 :</PARA>
 555 <ITEMIZEDLIST>
 556 <LISTITEM>
 557 <PARA>When create and delete functions
 558 <FUNCTION>cre_xxx()</FUNCTION>
 559  and
 560 <FUNCTION>del_xxx()</FUNCTION>
 561  are supported, all calls which use a valid object ID number check
 562 that the object exists. If not, E_NOEXS is returned.</PARA>
 563 </LISTITEM>
 564 <LISTITEM>
 565 <PARA>In create functions
 566 <FUNCTION>cre_xxx()</FUNCTION>
 567 , when supported, if the object already exists, then E_OBJ</PARA>
 568 </LISTITEM>
 569 <LISTITEM>
 570 <PARA>In any call which can sleep, such as
 571 <FUNCTION>twai_sem()</FUNCTION>
 572 : return codes E_TMOUT, E_RLWAI, E_DLT
 573 or of course E_OK are returned depending on the reason
 574 for terminating the sleep</PARA>
 575 </LISTITEM>
 576 <LISTITEM>
 577 <PARA>In polling functions such as
 578 <FUNCTION>preq_sem()</FUNCTION>
 579 return codes E_TMOUT or E_OK are returned depending
 580 on the state of the synchronization object</PARA>
 581 </LISTITEM>
 582 <LISTITEM>
 583 <PARA>In creation functions, the attributes must be compatible
 584 with the selected underlying kernel configuration: in
 585 <FUNCTION>cre_sem()</FUNCTION>
 586  <literal>pk_csem-&gt;sematr</literal>
 587  must be equal to
 588 <literal>TA_TFIFO</literal>
 589  else E_RSATR.</PARA>
 590 </LISTITEM>
 591 <LISTITEM>
 592 <PARA>In
 593 <FUNCTION>cre_flg()</FUNCTION>
 594  <literal>pk_cflg-&gt;flgatr</literal>
 595  must be either
 596 <varname>TA_WMUL</varname>
 597  or
 598 <varname>TA_WSGL</varname>
 599  else <varname>E_RSATR</varname>.</PARA>
 600 </LISTITEM>
 601 <LISTITEM>
 602 <PARA>In
 603 <FUNCTION>cre_mbx()</FUNCTION>
 604
 605 <LITERAL>pk_cmbx-&gt;mbxatr</LITERAL>
 606  must be
 607 <LITERAL>TA_TFIFO &plus; TA_MFIFO</LITERAL>
 608  else E_RSATR.</PARA>
 609 </LISTITEM>
 610 </ITEMIZEDLIST>
 611 </SECT2>
 612 </SECT1>
 613 <SECT1 id="compat-uitron-extended-sync-comm-functions">
 614 <TITLE><!-- <index></index> -->Extended Synchronization and Communication Functions</TITLE>
 615 <PARA>None of these functions are supported in this release. </PARA>
 616 </SECT1>
 617 <SECT1 id="compat-uitron-interrupt-management-functions">
 618 <TITLE><!-- <index></index> -->Interrupt management functions</TITLE>
 619 <PARA>These functions are fully supported in this release:</PARA>
 620 <PROGRAMLISTING>void    <FUNCTION> ret_int</FUNCTION>( void )
 621 </programlisting>
 622 <programlisting>
 623 ER <FUNCTION>loc_cpu</FUNCTION>( void )
 624 </programlisting>
 625 <programlisting>
 626 ER <FUNCTION>unl_cpu</FUNCTION>( void )
 627 </programlisting>
 628 <programlisting>
 629 ER <FUNCTION>dis_int</FUNCTION>(
 630     UINT <EMPHASIS>eintno</EMPHASIS> )
 631 </programlisting>
 632 <programlisting>
 633 ER <FUNCTION>ena_int</FUNCTION>(
 634     UINT <EMPHASIS>eintno</EMPHASIS> )
 635 </programlisting>
 636 <programlisting>
 637 void    <FUNCTION>ret_wup</FUNCTION>(
 638     ID <EMPHASIS>tskid</EMPHASIS> )
 639 </programlisting>
 640 <programlisting>
 641 ER <FUNCTION>iwup_tsk</FUNCTION>(
 642     ID <EMPHASIS>tskid</EMPHASIS> )
 643 </programlisting>
 644 <programlisting>
 645 ER <FUNCTION>isig_sem</FUNCTION>(
 646     ID <EMPHASIS>semid</EMPHASIS> )
 647 </programlisting>
 648 <programlisting>
 649 ER <FUNCTION>iset_flg</FUNCTION>(
 650     ID <EMPHASIS>flgid ,</EMPHASIS>
 651     UID<EMPHASIS> setptn</EMPHASIS> )
 652 </programlisting>
 653 <programlisting>
 654 ER <FUNCTION>isend_msg</FUNCTION>(
 655     ID <EMPHASIS>mbxid ,</EMPHASIS>
 656     T_MSG<EMPHASIS> *pk_msg</EMPHASIS> )</PROGRAMLISTING>
 657 <PARA>Note that <FUNCTION>ret_int()</FUNCTION> and
 658 the <FUNCTION>ret_wup()</FUNCTION> are  implemented
 659 as macros, containing a &ldquo;return&rdquo; statement.</PARA>
 660 <PARA>Also note that <FUNCTION>ret_wup()</FUNCTION> and
 661 the <FUNCTION>ixxx_yyy()</FUNCTION> style functions
 662 will only work when called from an ISR whose associated DSR is <FUNCTION>cyg_uitron_dsr()</FUNCTION>,
 663 as specified in include file <filename>&lt;cyg/compat/uitron/uit_ifnc.h&gt;</filename>,
 664 which defines the <FUNCTION>ixxx_yyy()</FUNCTION> style
 665 functions also.</PARA>
 666 <PARA>If you are writing interrupt handlers more in the
 667 <EMPHASIS>eCos</EMPHASIS> style, with separate ISR and DSR routines both of
 668 your own devising, do not use these special functions from a DSR: use plain
 669 <FUNCTION>xxx_yyy()</FUNCTION> style functions (with no &lsquo;i&rsquo; prefix)
 670 instead, and do not call any &micro;ITRON functions from the ISR at
 671 all.</PARA>
 672 <PARA>The following functions are not supported in this release: </PARA>
 673 <PROGRAMLISTING>ER <FUNCTION>def_int</FUNCTION>(
 674     UINT <EMPHASIS>dintno,</EMPHASIS>
 675   T_DINT *<EMPHASIS>pk_dint</EMPHASIS> )</programlisting>
 676         <programlisting>
 677 ER <FUNCTION>chg_iXX</FUNCTION>(
 678     UINT <EMPHASIS>iXXXX</EMPHASIS> )
 679   </programlisting>
 680         <programlisting>
 681 ER <FUNCTION>ref_iXX</FUNCTION>(
 682     UINT * <EMPHASIS>p_iXXXX</EMPHASIS> )</PROGRAMLISTING>
 683 <PARA>These unsupported functions are all Level C (CPU dependent).
 684 Equivalent functionality is available via other <EMPHASIS>eCos</EMPHASIS>-specific
 685 APIs. </PARA>
 686 <SECT2>
 687 <TITLE>Error checking</TITLE>
 688 <PARA>The following conditions are only checked for, and only return
 689 errors if
 690 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 691 is enabled:</PARA>
 692 <ITEMIZEDLIST>
 693 <LISTITEM>
 694 <PARA><FUNCTION>loc/unl_cpu()</FUNCTION>
 695 : these must only be called in a
 696 &micro;ITRON task context, else E_CTX.</PARA>
 697 </LISTITEM>
 698 <LISTITEM>
 699 <PARA><FUNCTION>dis/ena_int()</FUNCTION>
 700 : the interrupt number must be in range as specified by the platform
 701 HAL in qustion, else E_PAR.</PARA>
 702 </LISTITEM>
 703 </ITEMIZEDLIST>
 704 </SECT2>
 705 </SECT1>
 706 <SECT1 id="compat-uitron-memory-pool-mgmt-functions">
 707 <TITLE><!-- <index></index> -->   Memory pool Management Functions</TITLE>
 708 <PARA>These functions are fully supported in this release: </PARA>
 709 <PROGRAMLISTING>ER <FUNCTION>get_blf</FUNCTION>(
 710     VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
 711 </programlisting>
 712 <programlisting>
 713 ER <FUNCTION>pget_blf</FUNCTION>(
 714     VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
 715 </programlisting>
 716 <programlisting>
 717 ER <FUNCTION>tget_blf</FUNCTION>(
 718     VP *<EMPHASIS>p_blf,</EMPHASIS>    ID <EMPHASIS>mpfid,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
 719 </programlisting>
 720 <programlisting>
 721 ER <FUNCTION>rel_blf</FUNCTION>(
 722     ID <EMPHASIS>mpfid,</EMPHASIS>    VP <EMPHASIS>blf</EMPHASIS> )
 723 </programlisting>
 724 <programlisting>
 725 ER <FUNCTION>ref_mpf</FUNCTION>(
 726     T_RMPF *<EMPHASIS>pk_rmpf,</EMPHASIS>    ID <EMPHASIS>mpfid</EMPHASIS> )
 727 </programlisting>
 728 <programlisting>
 729 ER <FUNCTION>get_blk</FUNCTION>(
 730     VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz</EMPHASIS> )
 731 </programlisting>
 732 <programlisting>
 733 ER <FUNCTION>pget_blk</FUNCTION>(
 734     VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz</EMPHASIS> )
 735 </programlisting>
 736 <programlisting>
 737 ER <FUNCTION>tget_blk</FUNCTION>(
 738     VP *<EMPHASIS>p_blk,</EMPHASIS>    ID <EMPHASIS>mplid,</EMPHASIS>    INT <EMPHASIS>blksz,</EMPHASIS>    TMO <EMPHASIS>tmout</EMPHASIS> )
 739 </programlisting>
 740 <programlisting>
 741 ER <FUNCTION>rel_blk</FUNCTION>(
 742     ID <EMPHASIS>mplid,</EMPHASIS>    VP <EMPHASIS>blk</EMPHASIS> )
 743 </programlisting>
 744 <programlisting>
 745 ER <FUNCTION>ref_mpl</FUNCTION>(
 746     T_RMPL *<EMPHASIS>pk_rmpl,</EMPHASIS>    ID <EMPHASIS>mplid )
 747 </EMPHASIS></programlisting>
 748
 749 <PARA>Note that of the memory provided for a particular pool to
 750 manage in the static initialization of the memory pool objects,
 751 some memory will be used to manage the pool itself. Therefore the
 752 number of blocks * the blocksize will be less than the total
 753 memory size. </PARA>
 754 <PARA>The following functions are supported in this release, when
 755 enabled with
 756 <LITERAL>CYGPKG_UITRON_MEMPOOLVAR_CREATE_DELETE</LITERAL>
 757 or
 758 <LITERAL>CYGPKG_UITRON_MEMPOOLFIXED_CREATE_DELETE</LITERAL>
 759 as appropriate, with some restrictions: </PARA>
 760 <PROGRAMLISTING>ER <FUNCTION>cre_mpl</FUNCTION>(
 761     ID <EMPHASIS>mplid,</EMPHASIS>    T_CMPL *<EMPHASIS>pk_cmpl</EMPHASIS> )
 762 </programlisting>
 763 <programlisting>
 764 ER <FUNCTION>del_mpl</FUNCTION>(
 765     ID <EMPHASIS>mplid</EMPHASIS> )
 766 </programlisting>
 767 <programlisting>
 768 ER <FUNCTION>cre_mpf</FUNCTION>(
 769     ID <EMPHASIS>mpfid,</EMPHASIS>    T_CMPF *<EMPHASIS>pk_cmpf</EMPHASIS> )
 770 </programlisting>
 771 <programlisting>
 772 ER <FUNCTION>del_mpf</FUNCTION>(
 773     ID <EMPHASIS>mpfid</EMPHASIS> )</PROGRAMLISTING>
 774 <PARA>Because of the static initialization facilities provided for
 775 system objects, a memory pool is allocated a region of memory to
 776 manage statically in the configuration. So while memory pools can
 777 be created and deleted, the same area of memory is used for that
 778 memory pool (memory pool ID number) each time. The requested variable pool
 779 size (pk_cmpl-&gt;mplsz) or the number of fixed-size
 780 blocks (pk_cmpf-&gt;mpfcnt) times the block size
 781 (pk_cmpf-&gt;blfsz) are checked for fitting within
 782 the statically allocated memory area, so if a create call succeeds,
 783 the resulting pool will be at least as large as that requested.
 784 For this reason <FUNCTION>del_mpl()</FUNCTION> and <FUNCTION>del_mpf()</FUNCTION> do
 785 not in any sense free the memory that was managed by the deleted
 786 pool for use by other pools; it may only be managed by a pool of
 787 the same object id. </PARA>
 788 <PARA>For both fixed and variable memory pools, the queueing order
 789 when waiting on a synchronization object depends on the underlying
 790 kernel configuration. The multi-level queue scheduler is required
 791 for strict &micro;ITRON conformance and
 792 it queues tasks in FIFO order, so requests to create an object with
 793 priority queueing of tasks (pk_cxxx-&gt;xxxatr = TA_TPRI)
 794 are rejected with E_RSATR. Additional undefined bits in
 795 the attributes fields must be zero. </PARA>
 796 <PARA>In general, extended information (pk_cxxx-&gt;exinf)
 797 is ignored. </PARA>
 798 <SECT2>
 799 <TITLE>Error checking</TITLE>
 800 <PARA>The following conditions are only checked for, and only return
 801 errors if
 802 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 803 is enabled:</PARA>
 804 <ITEMIZEDLIST>
 805 <LISTITEM>
 806 <PARA>invalid object id; less than 1 or greater than
 807 <LITERAL>CYGNUM_UITRON_MEMPOOLVAR/MEMPOOLFIXED</LITERAL>
 808 as appropriate returns E_ID</PARA>
 809 </LISTITEM>
 810 <LISTITEM>
 811 <PARA>dispatching is enabled in any call which can sleep, or
 812 E_CTX</PARA>
 813 </LISTITEM>
 814 <LISTITEM>
 815 <PARA>tmout must be positive, otherwise E_PAR</PARA>
 816 </LISTITEM>
 817 <LISTITEM>
 818 <PARA>pk_cxxx pointers in
 819 <FUNCTION>cre_xxx()</FUNCTION>
 820  must be valid pointers, or E_PAR</PARA>
 821 </LISTITEM>
 822 <LISTITEM>
 823 <PARA>return value pointer in
 824 <FUNCTION>ref_xxx()</FUNCTION>
 825  is a valid pointer, or E_PAR</PARA>
 826 </LISTITEM>
 827 <LISTITEM>
 828 <PARA>return value pointers in get block routines is a valid
 829 pointer, or E_PAR</PARA>
 830 </LISTITEM>
 831 <LISTITEM>
 832 <PARA>blocksize request in get variable block routines is greater
 833 than zero, or E_PAR</PARA>
 834 </LISTITEM>
 835 </ITEMIZEDLIST>
 836 <PARA>The following conditions are checked for, and can return error
 837 codes, regardless of the setting of
 838 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>:
 839 </PARA>
 840 <ITEMIZEDLIST>
 841 <LISTITEM>
 842 <PARA>When create and delete functions
 843 <FUNCTION>cre_xxx()</FUNCTION>
 844  and
 845 <FUNCTION>del_xxx()</FUNCTION>
 846  are supported, all calls which use a valid object ID number check
 847 that the object exists. If not, E_NOEXS is returned.</PARA>
 848 </LISTITEM>
 849 <LISTITEM>
 850 <PARA>When create functions
 851 <FUNCTION>cre_xxx()</FUNCTION>
 852  are supported, if the object already exists, then E_OBJ</PARA>
 853 </LISTITEM>
 854 <LISTITEM>
 855 <PARA>In any call which can sleep, such as
 856 <FUNCTION>get_blk()</FUNCTION>
 857 : return codes E_TMOUT, E_RLWAI, E_DLT
 858 or of course E_OK are returned depending on the reason
 859 for terminating the sleep</PARA>
 860 </LISTITEM>
 861 <LISTITEM>
 862 <PARA>In polling functions such as
 863 <FUNCTION>pget_blk()</FUNCTION>
 864 return codes E_TMOUT or E_OK are returned depending
 865 on the state of the synchronization object</PARA>
 866 </LISTITEM>
 867 <LISTITEM>
 868 <PARA>In creation functions, the attributes must be compatible
 869 with the selected underlying kernel configuration: in
 870 <FUNCTION>cre_mpl()</FUNCTION>
 871
 872 <LITERAL>pk_cmpl-&gt;mplatr</LITERAL>
 873  must be equal to
 874 <LITERAL>TA_TFIFO</LITERAL>
 875  else E_RSATR.</PARA>
 876 </LISTITEM>
 877 <LISTITEM>
 878 <PARA>In
 879 <FUNCTION>cre_mpf()</FUNCTION>
 880
 881 <LITERAL>pk_cmpf-&gt;mpfatr</LITERAL>
 882  must be equal to
 883 <LITERAL>TA_TFIFO</LITERAL>
 884  else E_RSATR.</PARA>
 885 </LISTITEM>
 886 <LISTITEM>
 887 <PARA>In creation functions, the requested size of the memory
 888 pool must not be larger than that statically configured for the
 889 pool else E_RSATR; see the configuration option
 890 &ldquo;Option: Static initializers&rdquo;.
 891  In
 892 <FUNCTION>cre_mpl()</FUNCTION>
 893
 894 <LITERAL>pk_cmpl-&gt;mplsz</LITERAL>
 895  is the field of interest</PARA>
 896 </LISTITEM>
 897 <LISTITEM>
 898 <PARA>In
 899 <FUNCTION>cre_mpf()</FUNCTION>
 900  the product of
 901 <LITERAL>pk_cmpf-&gt;blfsz</LITERAL>
 902  and
 903 <LITERAL>pk_cmpf-&gt;mpfcnt</LITERAL>
 904  must be smaller than the memory statically configured for the pool
 905 else E_RSATR</PARA>
 906 </LISTITEM>
 907 <LISTITEM>
 908 <PARA>In functions which return memory to the pool
 909 <FUNCTION>rel_blk()</FUNCTION>
 910  and
 911 <FUNCTION>rel_blf()</FUNCTION>
 912 , if the free fails, for example because the memory did not come
 913 from that pool originally, then E_PAR is returned</PARA>
 914 </LISTITEM>
 915 </ITEMIZEDLIST>
 916 </SECT2>
 917 </SECT1>
 918 <SECT1 id="compat-uitron-time-mgmt-functions">
 919 <TITLE><!-- <index></index> -->Time Management Functions</TITLE>
 920 <PARA>These functions are fully supported in this release: </PARA>
 921 <PROGRAMLISTING>ER <FUNCTION>set_tim</FUNCTION>(
 922     SYSTIME *<EMPHASIS>pk_tim</EMPHASIS> )</PROGRAMLISTING>
 923 <CAUTION>
 924 <PARA>      Setting the time may cause erroneous operation of the
 925             kernel, for example a task performing a wait with a
 926             time-out may never awaken.</PARA>
 927 </CAUTION>
 928 <PROGRAMLISTING>ER <FUNCTION>get_tim</FUNCTION>(
 929     SYSTIME *<EMPHASIS>pk_tim</EMPHASIS> )
 930 </programlisting>
 931 <programlisting>
 932 ER <FUNCTION>dly_tsk</FUNCTION>(
 933     DLYTIME <EMPHASIS>dlytim</EMPHASIS> )
 934 </programlisting>
 935 <programlisting>
 936 ER <FUNCTION>def_cyc</FUNCTION>(
 937     HNO <EMPHASIS>cycno,</EMPHASIS>    T_DCYC *<EMPHASIS>pk_dcyc</EMPHASIS> )
 938 </programlisting>
 939 <programlisting>
 940 ER <FUNCTION>act_cyc</FUNCTION>(
 941     HNO <EMPHASIS>cycno,</EMPHASIS>    UINT <EMPHASIS>cycact</EMPHASIS> )
 942 </programlisting>
 943 <programlisting>
 944 ER <FUNCTION>ref_cyc</FUNCTION>(
 945     T_RCYC *<EMPHASIS>pk_rcyc,</EMPHASIS>    HNO <EMPHASIS>cycno</EMPHASIS> )
 946 </programlisting>
 947 <programlisting>
 948 ER <FUNCTION>def_alm</FUNCTION>(
 949     HNO <EMPHASIS>almno,</EMPHASIS>    T_DALM *<EMPHASIS>pk_dalm</EMPHASIS> )
 950 </programlisting>
 951 <programlisting>
 952 ER <FUNCTION>ref_alm</FUNCTION>(
 953     T_RALM *<EMPHASIS>pk_ralm,</EMPHASIS>    HNO <EMPHASIS>almno</EMPHASIS> )
 954 </programlisting>
 955 <programlisting>
 956 void <FUNCTION>ret_tmr</FUNCTION>( void )</programlisting>
 957         <sect2>
 958           <title>Error checking</title>
 959 <PARA>The following conditions are only checked for, and only return
 960 errors if
 961 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
 962 is enabled:</PARA>
 963 <ITEMIZEDLIST>
 964 <LISTITEM>
 965 <PARA>invalid handler number; less than 1 or greater than
 966 <LITERAL>CYGNUM_UITRON_CYCLICS/ALARMS</LITERAL>
 967 as appropriate, or E_PAR</PARA>
 968 </LISTITEM>
 969 <LISTITEM>
 970 <PARA>dispatching is enabled in
 971 <FUNCTION>dly_tsk()</FUNCTION>
 972 , or E_CTX</PARA>
 973 </LISTITEM>
 974 <LISTITEM>
 975 <PARA>dlytim must be positive or zero, otherwise E_PAR</PARA>
 976 </LISTITEM>
 977 <LISTITEM>
 978 <PARA>return value pointer in
 979 <FUNCTION>ref_xxx()</FUNCTION>
 980  is a valid pointer, or E_PAR</PARA>
 981 </LISTITEM>
 982 <LISTITEM>
 983 <PARA>params within pk_dalm and pk_dcyc must
 984 be valid, or E_PAR</PARA>
 985 </LISTITEM>
 986 <LISTITEM>
 987 <PARA>cycact in
 988 <FUNCTION>act_cyc()</FUNCTION>
 989  must be valid, or E_PAR</PARA>
 990 </LISTITEM>
 991 <LISTITEM>
 992 <PARA>handler must be defined in
 993 <FUNCTION>ref_xxx()</FUNCTION>
 994  and
 995 <FUNCTION>act_cyc()</FUNCTION>
 996 , or E_NOEXS</PARA>
 997 </LISTITEM>
 998 <LISTITEM>
 999 <PARA>parameter pointer must be a good pointer in
1000 <FUNCTION>get_tim()</FUNCTION>
1001  and
1002 <FUNCTION>set_tim()</FUNCTION>
1003 , otherwise E_PAR is returned</PARA>
1004 </LISTITEM>
1005 </ITEMIZEDLIST>
1006 <PARA>The following conditions are checked for, and can return
1007           error codes, regardless of the setting of
1008 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
1009 :</PARA>
1010 <ITEMIZEDLIST>
1011 <LISTITEM>
1012 <PARA><FUNCTION>dly_tsk()</FUNCTION>
1013 : return code E_RLWAI is returned depending on the reason
1014 for terminating the sleep</PARA>
1015 </LISTITEM>
1016 </ITEMIZEDLIST>
1017 </sect2>
1018 </SECT1>
1019 <SECT1 id="compat-uitron-system-mgmt-functions">
1020 <TITLE><!-- <index></index> -->   System Management Functions</TITLE>
1021 <PARA>These functions are fully supported in this release:
1022         </PARA>
1023 <PROGRAMLISTING>ER <FUNCTION>get_ver</FUNCTION>(
1024     T_VER *<EMPHASIS>pk_ver</EMPHASIS> )
1025 </PROGRAMLISTING>
1026 <PROGRAMLISTING>ER <FUNCTION>ref_sys</FUNCTION>(
1027     T_RSYS *<EMPHASIS>pk_rsys</EMPHASIS> )
1028 </PROGRAMLISTING>
1029 <PROGRAMLISTING>ER <FUNCTION>ref_cfg</FUNCTION>(
1030     T_RCFG *<EMPHASIS>pk_rcfg</EMPHASIS> )
1031 </PROGRAMLISTING>
1032 <PARA>Note that the information returned by each of these calls
1033 may be configured to match the user's own versioning system,
1034 and the values supplied by the default configuration may be inappropriate. </PARA>
1035 <PARA>These functions are not supported in this release: </PARA>
1036 <PROGRAMLISTING>ER <FUNCTION>def_svc</FUNCTION>(
1037     FN <EMPHASIS>s_fncd,</EMPHASIS>
1038     T_DSVC *<EMPHASIS>pk_dsvc</EMPHASIS> )
1039 </PROGRAMLISTING>
1040 <PROGRAMLISTING>ER <FUNCTION>def_exc</FUNCTION>(
1041     UINT <EMPHASIS>exckind,</EMPHASIS>
1042     T_DEXC *<EMPHASIS>pk_dexc</EMPHASIS> )
1043 </PROGRAMLISTING>
1044 <SECT2>
1045 <TITLE>Error checking</TITLE>
1046 <PARA>The following conditions are only checked for, and
1047             only return errors if
1048
1049 <LITERAL>CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</LITERAL>
1050  is enabled: </PARA>
1051 <ITEMIZEDLIST>
1052 <LISTITEM>
1053 <PARA>return value pointer in all calls is a valid
1054               pointer, or E_PAR</PARA>
1055 </LISTITEM>
1056 </ITEMIZEDLIST>
1057 </SECT2>
1058 </SECT1>
1059 <SECT1 id="compat-uitron-network-support-functions">
1060 <TITLE><!-- <index></index> -->   Network Support Functions</TITLE>
1061 <PARA>None of these functions are supported in this release.
1062         </PARA>
1063 </SECT1>
1064 <SECT1 id="compat-uitron-configuration-faq">
1065 <TITLE><!-- <index></index> -->&micro;ITRON Configuration FAQ</TITLE>
1066 <PARA><EMPHASIS>Q: How are &micro;ITRON objects created?</EMPHASIS>
1067 </PARA>
1068 <PARA>
1069 For each type of uITRON object (tasks, semaphores, flags, mboxes, mpf, mpl)
1070 these two quantities are controlled by configuration:
1071 </PARA>
1072 <ITEMIZEDLIST>
1073 <LISTITEM><PARA>
1074 The <EMPHASIS>maximum</EMPHASIS> number of this type of object.
1075 </PARA></LISTITEM>
1076 <LISTITEM><PARA>
1077 The number of these objects which exist <EMPHASIS>initially</EMPHASIS>.
1078 </PARA></LISTITEM>
1079 </ITEMIZEDLIST>
1080 <PARA>
1081 This is assuming that for the relevant object type,
1082 <EMPHASIS>create</EMPHASIS> and <EMPHASIS>delete</EMPHASIS>
1083 operations are enabled; enabled is the default.  For example, the option
1084 <LITERAL>CYGPKG_UITRON_MBOXES_CREATE_DELETE</LITERAL>
1085 controls whether the functions
1086 <FUNCTION>cre_mbx()</FUNCTION>
1087 and
1088 <FUNCTION>del_mbx()</FUNCTION>
1089 exist in the API.  If not, then the maximum number of
1090 mboxes is the same as the initial number of mboxes, and so on for all
1091 &micro;ITRON object types.
1092 </PARA>
1093 <PARA>
1094 Mboxes have no initialization, so there are only a few, simple
1095 configuration options:
1096 </PARA>
1097 <ITEMIZEDLIST>
1098 <LISTITEM><PARA>
1099 <LITERAL>CYGNUM_UITRON_MBOXES</LITERAL>
1100 is the total number of mboxes that you can have in the
1101 system.  By default this is 4, so you can use mboxes 1,2,3 and 4.  You
1102 cannot create mboxes outside this range; trying to
1103 <FUNCTION>cre_mbx(5,...)</FUNCTION>
1104 will return an error.
1105 </PARA></LISTITEM>
1106 <LISTITEM><PARA>
1107 <LITERAL>CYGNUM_UITRON_MBOXES_INITIALLY</LITERAL>
1108 is the number of mboxes created
1109 automatically for you, during startup.  By default this is 4, so all 4
1110 mboxes exist already, and an attempt to create one of these
1111 eg. <FUNCTION>cre_mbx(3,...)</FUNCTION>
1112 will return an error because the mbox in quesion already
1113 exists.  You can delete a pre-existing mbox, and then re-create it.
1114 </PARA></LISTITEM>
1115 </ITEMIZEDLIST>
1116 <PARA>
1117 If you change
1118 <LITERAL>CYGNUM_UITRON_MBOXES_INITIALLY</LITERAL>,
1119 for example to 0, no mboxes
1120 are created automatically for you during startup.  Any attempt to use an
1121 mbox without creating it will return E_NOEXS because the mbox does not
1122 exist.  You can create an mbox, say <FUNCTION>cre_mbx(3,...)</FUNCTION>
1123 and then use it, say
1124 <FUNCTION>snd_msg(3,&amp;foo)</FUNCTION>, and all will be well.
1125 </PARA>
1126 <PARA><EMPHASIS>Q: How are &micro;ITRON objects initialized?</EMPHASIS>
1127 </PARA>
1128 <PARA>
1129 Some object types have optional initialization.  Semaphores are an
1130 example.  You could have
1131 <LITERAL>CYGNUM_UITRON_SEMAS</LITERAL>=10 and
1132 <LITERAL>CYGNUM_UITRON_SEMAS_INITIALLY</LITERAL>=5
1133 which means you can use semaphores 1-5
1134 straight off, but you must create semaphores 6-10 before you can use them.
1135 If you decide not to initialize semaphores, semaphores 1-5 will have an
1136 initial count of zero.  If you decide to initialize them, you must supply
1137 a dummy initializer for semaphores 6-10 also.  For example,
1138 in terms of the configuration output in
1139 <filename>pkgconf/uitron.h</filename>:
1140 </PARA>
1141 <PROGRAMLISTING>
1142    #define CYGDAT_UITRON_SEMA_INITIALIZERS \
1143         CYG_UIT_SEMA(  1 ),     \
1144         CYG_UIT_SEMA(  0 ),     \
1145         CYG_UIT_SEMA(  0 ),     \
1146         CYG_UIT_SEMA( 99 ),     \
1147         CYG_UIT_SEMA(  1 ),     \
1148         CYG_UIT_SEMA_NOEXS,     \
1149         CYG_UIT_SEMA_NOEXS,     \
1150         CYG_UIT_SEMA_NOEXS,     \
1151         CYG_UIT_SEMA_NOEXS,     \
1152         CYG_UIT_SEMA_NOEXS
1153 </PROGRAMLISTING>
1154 <PARA>
1155 Semaphore 1 will have initial count 1, semaphores 2 and 3 will be zero,
1156 number 4 will be 99 initially, 5 will be one and numbers 6 though 10 do not
1157 exist initially.
1158 </PARA>
1159 <PARA>
1160 Aside: this is how the definition of the symbol would appear in the
1161 configuration header file <filename>pkgconf/uitron.h</filename> &mdash;
1162 unfortunately editing such a long, multi-line definition is somewhat
1163 cumbersome in the GUI config tool in current releases.  The macros
1164 <LITERAL>CYG_UIT_SEMA()</LITERAL>
1165 &mdash; to create a semaphore initializer &mdash; and
1166 <LITERAL>CYG_UIT_SEMA_NOEXS</LITERAL>
1167 &mdash; to invoke a dummy initializer &mdash;
1168 are provided in in the environment to help with this.  Similar macros are
1169 provided for other object types.  The resulting #define symbol is used in
1170 the context of a C++ array initializer, such as:
1171 <PROGRAMLISTING>
1172 Cyg_Counting_Semaphore2 cyg_uitron_SEMAS[ CYGNUM_UITRON_SEMAS ] = {
1173         CYGDAT_UITRON_SEMA_INITIALIZERS
1174 };
1175 </PROGRAMLISTING>
1176 which is eventually macro-processed to give
1177 <PROGRAMLISTING>
1178 Cyg_Counting_Semaphore2 cyg_uitron_SEMAS[ 10 ] = {
1179         Cyg_Counting_Semaphore2( ( 1 ) ),
1180         Cyg_Counting_Semaphore2( ( 0 ) ),
1181         Cyg_Counting_Semaphore2( ( 0 ) ),
1182         Cyg_Counting_Semaphore2( ( 99 ) ),
1183         Cyg_Counting_Semaphore2( ( 1 ) ),
1184         Cyg_Counting_Semaphore2(0),
1185         Cyg_Counting_Semaphore2(0),
1186         Cyg_Counting_Semaphore2(0),
1187         Cyg_Counting_Semaphore2(0),
1188         Cyg_Counting_Semaphore2(0),
1189 };
1190 </PROGRAMLISTING>
1191 so you can see how it is necessary to include the dummy entries in that
1192 definition, otherwise the resulting code will not compile correctly.
1193 </PARA>
1194 <PARA>
1195 If you choose
1196 <LITERAL>CYGNUM_UITRON_SEMAS_INITIALLY</LITERAL>=0
1197 it is meaningless to initialize them, for they must be created and so
1198 initialized then, before use.
1199 </PARA>
1200 <PARA><EMPHASIS>Q: What about &micro;ITRON tasks?</EMPHASIS>
1201 </PARA>
1202 <PARA>
1203 Some object types require initialization.  Tasks are an example of this.
1204 You must provide a task with a priority, a function to enter when the task
1205 starts, a name (for debugging purposes), and some memory to use for the stack.
1206 For example (again in terms of the resulting
1207 definitions in <filename>pkgconf/uitron.h</filename>):
1208 </PARA>
1209 <PROGRAMLISTING>
1210 #define CYGNUM_UITRON_TASKS 4           // valid task ids are 1,2,3,4
1211 #define CYGNUM_UITRON_TASKS_INITIALLY 4 // they all exist at start
1212
1213 #define CYGDAT_UITRON_TASK_EXTERNS              \
1214 extern "C" void startup( unsigned int );        \
1215 extern "C" void worktask( unsigned int );       \
1216 extern "C" void lowtask( unsigned int );        \
1217 static char stack1[ CYGNUM_UITRON_STACK_SIZE ], \
1218             stack2[ CYGNUM_UITRON_STACK_SIZE ], \
1219             stack3[ CYGNUM_UITRON_STACK_SIZE ], \
1220             stack4[ CYGNUM_UITRON_STACK_SIZE ];
1221
1222 #define CYGDAT_UITRON_TASK_INITIALIZERS \
1223  CYG_UIT_TASK("main task", 8, startup,  &amp;stack1, sizeof( stack1 )), \
1224  CYG_UIT_TASK("worker 2" , 9, worktask, &amp;stack2, sizeof( stack2 )), \
1225  CYG_UIT_TASK("worker 3" , 9, worktask, &amp;stack3, sizeof( stack3 )), \
1226  CYG_UIT_TASK("low task" ,20, lowtask,  &amp;stack4, sizeof( stack4 )), \
1227
1228 </PROGRAMLISTING>
1229 <PARA>
1230 So this example has all four tasks statically configured to exist, ready to
1231 run, from the start of time.  The &ldquo;main task&rdquo; runs a routine
1232 called <FUNCTION>startup()</FUNCTION> at priority 8.  Two
1233 &ldquo;worker&rdquo; tasks run both a priority 9, and a &ldquo;low
1234 priority&rdquo; task runs at priority 20 to do useful non-urgent background
1235 work.
1236 </PARA>
1237 <screen>
1238 Task ID | Exists at | Function | Priority | Stack   | Stack
1239  number |  startup  |  entry   |          | address | size
1240 --------+-----------+----------+----------+---------+----------
1241    1    |    Yes    |  startup |    8     | &amp;stack1 | CYGNUM...
1242    2    |    Yes    | worktask |    9     | &amp;stack2 | CYGNUM...
1243    3    |    Yes    | worktask |    9     | &amp;stack3 | CYGNUM...
1244    4    |    Yes    |  lowtask |   20     | &amp;stack4 | CYGNUM...
1245 --------+-----------+----------+----------+---------+----------
1246 </screen>
1247 <PARA><EMPHASIS>Q: How can I create &micro;ITRON tasks in the program?</EMPHASIS>
1248 </PARA>
1249 <PARA>
1250 You must provide free slots in the task table in which to create new tasks,
1251 by configuring the number of tasks existing initially to be smaller than
1252 the total.
1253 For a task ID which does not initially exist, it will be told what routine
1254 to call, and what priority it is, when the task is created.  But you must
1255 still set aside memory for the task to use for its stack, and give it a
1256 name during initialization.  For example:
1257 </PARA>
1258
1259 <PROGRAMLISTING>
1260 #define CYGNUM_UITRON_TASKS 4           // valid task ids are 1-4
1261 #define CYGNUM_UITRON_TASKS_INITIALLY 1 // only task #1 exists
1262
1263 #define CYGDAT_UITRON_TASK_EXTERNS \
1264 extern "C" void startup( unsigned int ); \
1265 static char stack1[ CYGNUM_UITRON_STACK_SIZE ], \
1266             stack2[ CYGNUM_UITRON_STACK_SIZE ], \
1267             stack3[ CYGNUM_UITRON_STACK_SIZE ], \
1268             stack4[ CYGNUM_UITRON_STACK_SIZE ];
1269
1270 #define CYGDAT_UITRON_TASK_INITIALIZERS \
1271    CYG_UIT_TASK( "main", 8, startup, &amp;stack1, sizeof( stack1 ) ), \
1272    CYG_UIT_TASK_NOEXS( "slave",      &amp;stack2, sizeof( stack2 ) ), \
1273    CYG_UIT_TASK_NOEXS( "slave2",     &amp;stack3, sizeof( stack3 ) ), \
1274    CYG_UIT_TASK_NOEXS( "slave3",     &amp;stack4, sizeof( stack4 ) ), \
1275
1276 </PROGRAMLISTING>
1277 <PARA>
1278 So tasks numbered 2,3 and 4 have been given their stacks during startup,
1279 though they do not yet exist in terms of <FUNCTION>cre_tsk()</FUNCTION> and
1280 <FUNCTION>del_tsk()</FUNCTION> so you can create tasks 2&ndash;4 at
1281 runtime.
1282 </PARA>
1283 <screen>
1284 Task ID | Exists at | Function | Priority | Stack   | Stack
1285  number |  startup  |  entry   |          | address | size
1286 --------+-----------+----------+----------+---------+----------
1287    1    |    Yes    |  startup |    8     | &amp;stack1 | CYGNUM...
1288    2    |    No     |   N/A    |   N/A    | &amp;stack2 | CYGNUM...
1289    3    |    No     |   N/A    |   N/A    | &amp;stack3 | CYGNUM...
1290    4    |    No     |   N/A    |   N/A    | &amp;stack4 | CYGNUM...
1291 --------+-----------+----------+----------+---------+----------
1292 </screen>
1293 <PARA>
1294 (you must have at least one task at startup in order that the system can
1295  actually run; this is not so for other uITRON object types)
1296 </PARA>
1297 <PARA><EMPHASIS>Q: Can I have different stack sizes for &micro;ITRON tasks?</EMPHASIS>
1298 </PARA>
1299 <PARA>
1300 Simply set aside different amounts of memory for each task to use for its
1301 stack.  Going back to a typical default setting for the &micro;ITRON tasks,
1302 the definitions in <filename>pkgconf/uitron.h</filename> might look like this:
1303 </PARA>
1304 <PROGRAMLISTING>
1305 #define CYGDAT_UITRON_TASK_EXTERNS \
1306 extern "C" void task1( unsigned int ); \
1307 extern "C" void task2( unsigned int ); \
1308 extern "C" void task3( unsigned int ); \
1309 extern "C" void task4( unsigned int ); \
1310 static char stack1[ CYGNUM_UITRON_STACK_SIZE ], \
1311             stack2[ CYGNUM_UITRON_STACK_SIZE ], \
1312             stack3[ CYGNUM_UITRON_STACK_SIZE ], \
1313             stack4[ CYGNUM_UITRON_STACK_SIZE ];
1314
1315 #define CYGDAT_UITRON_TASK_INITIALIZERS \
1316   CYG_UIT_TASK( "t1", 1, task1, &amp;stack1, CYGNUM_UITRON_STACK_SIZE ), \
1317   CYG_UIT_TASK( "t2", 2, task2, &amp;stack2, CYGNUM_UITRON_STACK_SIZE ), \
1318   CYG_UIT_TASK( "t3", 3, task3, &amp;stack3, CYGNUM_UITRON_STACK_SIZE ), \
1319   CYG_UIT_TASK( "t4", 4, task4, &amp;stack4, CYGNUM_UITRON_STACK_SIZE )
1320
1321 </PROGRAMLISTING>
1322 <PARA>
1323 Note that
1324 <LITERAL>CYGNUM_UITRON_STACK_SIZE</LITERAL>
1325 is used to control the size of the stack
1326 objects themselves, and to tell the system what size stack is being provided.
1327 </PARA>
1328 <PARA>
1329 Suppose instead stack sizes of 2000, 1000, 800 and 800 were required:
1330 this could be achieved by using the GUI config tool to edit these
1331 options, or editting the <filename>.ecc</filename> file to get these
1332 results in <filename>pkgconf/uitron.h</filename>:
1333 </PARA>
1334 <PROGRAMLISTING>
1335 #define CYGDAT_UITRON_TASK_EXTERNS \
1336 extern "C" void task1( unsigned int ); \
1337 extern "C" void task2( unsigned int ); \
1338 extern "C" void task3( unsigned int ); \
1339 extern "C" void task4( unsigned int ); \
1340 static char stack1[ 2000 ], \
1341             stack2[ 1000 ], \
1342             stack3[  800 ], \
1343             stack4[  800 ];
1344
1345 #define CYGDAT_UITRON_TASK_INITIALIZERS \
1346       CYG_UIT_TASK( "t1", 1, task1, &amp;stack1, sizeof( stack1 ) ), \
1347       CYG_UIT_TASK( "t2", 2, task2, &amp;stack2, sizeof( stack2 ) ), \
1348       CYG_UIT_TASK( "t3", 3, task3, &amp;stack3, sizeof( stack3 ) ), \
1349       CYG_UIT_TASK( "t4", 4, task4, &amp;stack4, sizeof( stack4 ) )
1350 </PROGRAMLISTING>
1351 <PARA>
1352 Note that the sizeof() operator has been used to tell the system what size
1353 stacks are provided, rather than quoting a number (which is difficult for
1354 maintenance) or the symbol
1355 <LITERAL>CYGNUM_UITRON_STACK_SIZE</LITERAL>
1356 (which is wrong).
1357 </PARA>
1358 <PARA>
1359 We recommend using (if available in your release) the stacksize symbols
1360 provided in the architectural HAL for your target, called
1361 <LITERAL>CYGNUM_HAL_STACK_SIZE_TYPICAL</LITERAL>
1362 and
1363 <LITERAL>CYGNUM_HAL_STACK_SIZE_MINIMUM</LITERAL>.
1364 So a better (more portable) version of the above might be:
1365 </PARA>
1366 <PROGRAMLISTING>
1367 #define CYGDAT_UITRON_TASK_EXTERNS \
1368 extern "C" void task1( unsigned int ); \
1369 extern "C" void task2( unsigned int ); \
1370 extern "C" void task3( unsigned int ); \
1371 extern "C" void task4( unsigned int ); \
1372 static char stack1[ CYGNUM_HAL_STACK_SIZE_TYPICAL + 1200 ], \
1373             stack2[ CYGNUM_HAL_STACK_SIZE_TYPICAL +  200 ], \
1374             stack3[ CYGNUM_HAL_STACK_SIZE_TYPICAL        ], \
1375             stack4[ CYGNUM_HAL_STACK_SIZE_TYPICAL        ];
1376
1377 #define CYGDAT_UITRON_TASK_INITIALIZERS \
1378       CYG_UIT_TASK( "t1", 1, task1, &amp;stack1, sizeof( stack1 ) ), \
1379       CYG_UIT_TASK( "t2", 2, task2, &amp;stack2, sizeof( stack2 ) ), \
1380       CYG_UIT_TASK( "t3", 3, task3, &amp;stack3, sizeof( stack3 ) ), \
1381       CYG_UIT_TASK( "t4", 4, task4, &amp;stack4, sizeof( stack4 ) )
1382 </PROGRAMLISTING>
1383 </SECT1>
1384 </CHAPTER>
1385 </part>