doc/html/ref/compat-uitron-over-ecos.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >µITRON and eCos</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="µITRON API"
  23 HREF="compat-uitron-microitron-api.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="µITRON API"
  26 HREF="compat-uitron-microitron-api.html"><LINK
  27 REL="NEXT"
  28 TITLE="Task Management Functions"
  29 HREF="compat-uitron-task-management-functions.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="compat-uitron-microitron-api.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 32. &micro;ITRON API</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="compat-uitron-task-management-functions.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="COMPAT-UITRON-OVER-ECOS">&micro;ITRON and <SPAN
  86 CLASS="emphasis"
  87 ><I
  88 CLASS="EMPHASIS"
  89 >eCos</I
  90 ></SPAN
  91 ></H1
  92 ><P
  93 >The <SPAN
  94 CLASS="emphasis"
  95 ><I
  96 CLASS="EMPHASIS"
  97 >eCos</I
  98 ></SPAN
  99 > kernel implements the functionality
 100 used by the &micro;ITRON compatibility subsystem.
 101 The configuration of the kernel influences the behavior of &micro;ITRON
 102 programs.</P
 103 ><P
 104 >In particular, the default configuration has time slicing
 105 (also known as round-robin scheduling) switched on; this means that
 106 a task can be moved from <TT
 107 CLASS="VARNAME"
 108 >RUN</TT
 109 > state
 110 to <TT
 111 CLASS="VARNAME"
 112 >READY</TT
 113 > state at any time, in
 114 order that one of its peers may run. This is not strictly conformant
 115 to the &micro;ITRON specification, which
 116 states that timeslicing may be implemented by periodically issuing
 117 a <TT
 118 CLASS="LITERAL"
 119 >rot_rdq(0)</TT
 120 > call from
 121 within a periodic task or cyclic handler; otherwise it is expected
 122 that a task runs until it is pre-empted in consequence of synchronization
 123 or communication calls it makes, or the effects of an interrupt
 124 or other external event on a higher priority task cause that task
 125 to become <TT
 126 CLASS="VARNAME"
 127 >READY</TT
 128 >. To disable timeslicing
 129 functionality in the kernel and &micro;ITRON
 130 compatibility environment, please disable the
 131 <TT
 132 CLASS="LITERAL"
 133 >CYGSEM_KERNEL_SCHED_TIMESLICE</TT
 134 >
 135 configuration option in the kernel package. A description of kernel
 136 scheduling is in <A
 137 HREF="kernel-overview.html"
 138 >Kernel Overview</A
 139 >. </P
 140 ><P
 141 >For another example, the semantics of task queueing when waiting
 142 on a synchronization object depend solely on the way the underlying
 143 kernel is configured. As discussed above, the multi-level queue
 144 scheduler is the only one which is &micro;ITRON
 145 compliant, and it queues waiting tasks in FIFO order. Future releases
 146 of that scheduler might be configurable to support priority ordering
 147 of task queues. Other schedulers might be different again: for example
 148 the bitmap scheduler can be used with the &micro;ITRON
 149 compatibility layer, even though it only allows one task at each
 150 priority and as such is not &micro;ITRON
 151 compliant, but it supports only priority ordering of task queues.
 152 So which queueing scheme is supported is not really a property of
 153 the &micro;ITRON compatibility layer; it
 154 depends on the kernel. </P
 155 ><P
 156 >In this version of the &micro;ITRON
 157 compatibility layer, the calls to disable and enable scheduling
 158 and interrupts (<TT
 159 CLASS="FUNCTION"
 160 >dis_dsp()</TT
 161 >,
 162 <TT
 163 CLASS="FUNCTION"
 164 >ena_dsp()</TT
 165 >, <TT
 166 CLASS="FUNCTION"
 167 >loc_cpu()</TT
 168 >
 169 and <TT
 170 CLASS="FUNCTION"
 171 >unl_cpu()</TT
 172 >)
 173 call underlying kernel functions; in particular, the <TT
 174 CLASS="FUNCTION"
 175 >xxx_dsp()</TT
 176 > functions
 177 lock the scheduler entirely, which prevents dispatching of DSRs; functions
 178 implemented by DSRs include clock counters and alarm timers. Thus time &#8220;stops&#8221; while
 179 dispatching is disabled with <TT
 180 CLASS="FUNCTION"
 181 >dis_dsp()</TT
 182 >. </P
 183 ><P
 184 >Like all parts of the <SPAN
 185 CLASS="emphasis"
 186 ><I
 187 CLASS="EMPHASIS"
 188 >eCos</I
 189 ></SPAN
 190 > system, the
 191 detailed semantics of the &micro;ITRON layer
 192 are dependent on its configuration and the configuration of other components
 193 that it uses. The &micro;ITRON configuration
 194 options are all defined in the file <TT
 195 CLASS="FILENAME"
 196 >pkgconf/uitron.h</TT
 197 >,
 198 and can be set using the configuration tool or editing the
 199 <TT
 200 CLASS="FILENAME"
 201 >.ecc</TT
 202 >
 203 file in your build directory by hand. </P
 204 ><P
 205 >An important configuration option for the &micro;ITRON
 206 compatibility layer is &#8220;Option: Return Error Codes for Bad Params&#8221;
 207 (
 208 <TT
 209 CLASS="LITERAL"
 210 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
 211 >
 212 ), which allows a lot of the error
 213 checking code in the &micro;ITRON compatibility layer to
 214 be removed. Of course this leaves a program open to undetected errors,
 215 so it should only be used once an application is fully debugged and
 216 tested. Its benefits include reduced code size and faster execution.
 217 However, it affects the API significantly, in that with this option
 218 enabled, bad calls do not return errors, but cause an assert
 219 failure (if that is itself enabled) or malfunction internally. There
 220 is discussion in more detail about this in each section below.</P
 221 ><P
 222 >We now give a brief description of the &micro;ITRON
 223 functions which are implemented in this release. Note that all C
 224 and C&#0043;&#0043; source files should have the following <TT
 225 CLASS="LITERAL"
 226 >#include</TT
 227 > statement: </P
 228 ><TABLE
 229 BORDER="5"
 230 BGCOLOR="#E0E0F0"
 231 WIDTH="70%"
 232 ><TR
 233 ><TD
 234 ><PRE
 235 CLASS="PROGRAMLISTING"
 236 >#include &lt;cyg/compat/uitron/uit_func.h&gt;</PRE
 237 ></TD
 238 ></TR
 239 ></TABLE
 240 ></DIV
 241 ><DIV
 242 CLASS="NAVFOOTER"
 243 ><HR
 244 ALIGN="LEFT"
 245 WIDTH="100%"><TABLE
 246 SUMMARY="Footer navigation table"
 247 WIDTH="100%"
 248 BORDER="0"
 249 CELLPADDING="0"
 250 CELLSPACING="0"
 251 ><TR
 252 ><TD
 253 WIDTH="33%"
 254 ALIGN="left"
 255 VALIGN="top"
 256 ><A
 257 HREF="compat-uitron-microitron-api.html"
 258 ACCESSKEY="P"
 259 >Prev</A
 260 ></TD
 261 ><TD
 262 WIDTH="34%"
 263 ALIGN="center"
 264 VALIGN="top"
 265 ><A
 266 HREF="ecos-ref.html"
 267 ACCESSKEY="H"
 268 >Home</A
 269 ></TD
 270 ><TD
 271 WIDTH="33%"
 272 ALIGN="right"
 273 VALIGN="top"
 274 ><A
 275 HREF="compat-uitron-task-management-functions.html"
 276 ACCESSKEY="N"
 277 >Next</A
 278 ></TD
 279 ></TR
 280 ><TR
 281 ><TD
 282 WIDTH="33%"
 283 ALIGN="left"
 284 VALIGN="top"
 285 >&micro;ITRON API</TD
 286 ><TD
 287 WIDTH="34%"
 288 ALIGN="center"
 289 VALIGN="top"
 290 ><A
 291 HREF="compat-uitron-microitron-api.html"
 292 ACCESSKEY="U"
 293 >Up</A
 294 ></TD
 295 ><TD
 296 WIDTH="33%"
 297 ALIGN="right"
 298 VALIGN="top"
 299 >Task Management Functions</TD
 300 ></TR
 301 ></TABLE
 302 ></DIV
 303 ></BODY
 304 ></HTML
 305 >