doc/html/ref/kernel-exceptions.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 >Exception handling</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="The eCos Kernel"
  23 HREF="kernel.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Thread destructors"
  26 HREF="kernel-thread-destructors.html"><LINK
  27 REL="NEXT"
  28 TITLE="Counters"
  29 HREF="kernel-counters.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  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="kernel-thread-destructors.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="kernel-counters.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="KERNEL-EXCEPTIONS">Exception handling</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN782"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_exception_set_handler, cyg_exception_clear_handler, cyg_exception_call_handler&nbsp;--&nbsp;Handle processor exceptions</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN787"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN788"><P
 100 ></P
 101 ><TABLE
 102 BORDER="5"
 103 BGCOLOR="#E0E0F0"
 104 WIDTH="70%"
 105 ><TR
 106 ><TD
 107 ><PRE
 108 CLASS="FUNCSYNOPSISINFO"
 109 >#include &lt;cyg/kernel/kapi.h&gt;
 110         </PRE
 111 ></TD
 112 ></TR
 113 ></TABLE
 114 ><P
 115 ><CODE
 116 ><CODE
 117 CLASS="FUNCDEF"
 118 >void cyg_exception_set_handler</CODE
 119 >(cyg_code_t exception_number, cyg_exception_handler_t* new_handler, cyg_addrword_t new_data, cyg_exception_handler_t** old_handler, cyg_addrword_t* old_data);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void cyg_exception_clear_handler</CODE
 126 >(cyg_code_t exception_number);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >void cyg_exception_call_handler</CODE
 133 >(cyg_handle_t thread, cyg_code_t exception_number, cyg_addrword_t exception_info);</CODE
 134 ></P
 135 ><P
 136 ></P
 137 ></DIV
 138 ></DIV
 139 ><DIV
 140 CLASS="REFSECT1"
 141 ><A
 142 NAME="AEN817"
 143 ></A
 144 ><H2
 145 >Description</H2
 146 ><P
 147 >Sometimes code attempts operations that are not legal on the current
 148 hardware, for example dividing by zero, or accessing data through a
 149 pointer that is not properly aligned. When this happens the hardware
 150 will raise an exception. This is very similar to an interrupt, but
 151 happens synchronously with code execution rather than asynchronously
 152 and hence can be tied to the thread that is currently running.
 153       </P
 154 ><P
 155 >The exceptions that can be raised depend very much on the hardware,
 156 especially the processor. The corresponding documentation should be
 157 consulted for more details. Alternatively the architectural HAL header
 158 file <TT
 159 CLASS="FILENAME"
 160 >hal_intr.h</TT
 161 >, or one of the
 162 variant or platform header files it includes, will contain appropriate
 163 definitions. The details of how to handle exceptions, including
 164 whether or not it is possible to recover from them, also depend on the
 165 hardware.
 166       </P
 167 ><P
 168 >Exception handling is optional, and can be disabled through the
 169 configuration option <TT
 170 CLASS="VARNAME"
 171 >CYGPKG_KERNEL_EXCEPTIONS</TT
 172 >. If
 173 an application has been exhaustively tested and is trusted never to
 174 raise a hardware exception then this option can be disabled and code
 175 and data sizes will be reduced somewhat. If exceptions are left
 176 enabled then the system will provide default handlers for the various
 177 exceptions, but these do nothing. Even the specific type of exception
 178 is ignored, so there is no point in attempting to decode this and
 179 distinguish between say a divide-by-zero and an unaligned access.
 180 If the application installs its own handlers and wants details of the
 181 specific exception being raised then the configuration option
 182 <TT
 183 CLASS="VARNAME"
 184 >CYGSEM_KERNEL_EXCEPTIONS_DECODE</TT
 185 > has to be enabled.
 186       </P
 187 ><P
 188 >An alternative handler can be installed using
 189 <TT
 190 CLASS="FUNCTION"
 191 >cyg_exception_set_handler</TT
 192 >. This requires a code
 193 for the exception, a function pointer for the new exception handler,
 194 and a parameter to be passed to this handler. Details of the
 195 previously installed exception handler will be returned via the
 196 remaining two arguments, allowing that handler to be reinstated, or
 197 null pointers can be used if this information is of no interest. An
 198 exception handling function should take the following form:
 199       </P
 200 ><TABLE
 201 BORDER="5"
 202 BGCOLOR="#E0E0F0"
 203 WIDTH="70%"
 204 ><TR
 205 ><TD
 206 ><PRE
 207 CLASS="PROGRAMLISTING"
 208 >void
 209 my_exception_handler(cyg_addrword_t data, cyg_code_t exception, cyg_addrword_t info)
 210 {
 211     &#8230;
 212 }
 213       </PRE
 214 ></TD
 215 ></TR
 216 ></TABLE
 217 ><P
 218 >The data argument corresponds to the <TT
 219 CLASS="PARAMETER"
 220 ><I
 221 >new_data</I
 222 ></TT
 223 >
 224 parameter supplied to <TT
 225 CLASS="FUNCTION"
 226 >cyg_exception_set_handler</TT
 227 >.
 228 The exception code is provided as well, in case a single handler is
 229 expected to support multiple exceptions. The <TT
 230 CLASS="PARAMETER"
 231 ><I
 232 >info</I
 233 ></TT
 234 >
 235 argument will depend on the hardware and on the specific exception.
 236       </P
 237 ><P
 238 ><TT
 239 CLASS="FUNCTION"
 240 >cyg_exception_clear_handler</TT
 241 > can be used to
 242 restore the default handler, if desired. It is also possible for
 243 software to raise an exception and cause the current handler to be
 244 invoked, but generally this is useful only for testing.
 245       </P
 246 ><P
 247 >By default the system maintains a single set of global exception
 248 handlers. However, since exceptions occur synchronously it is
 249 sometimes useful to handle them on a per-thread basis, and have a
 250 different set of handlers for each thread. This behaviour can be
 251 obtained by disabling the configuration option
 252 <TT
 253 CLASS="VARNAME"
 254 >CYGSEM_KERNEL_EXCEPTIONS_GLOBAL</TT
 255 >. If per-thread
 256 exception handlers are being used then
 257 <TT
 258 CLASS="FUNCTION"
 259 >cyg_exception_set_handler</TT
 260 > and
 261 <TT
 262 CLASS="FUNCTION"
 263 >cyg_exception_clear_handler</TT
 264 > apply to the current
 265 thread. Otherwise they apply to the global set of handlers.
 266       </P
 267 ><DIV
 268 CLASS="CAUTION"
 269 ><P
 270 ></P
 271 ><TABLE
 272 CLASS="CAUTION"
 273 BORDER="1"
 274 WIDTH="100%"
 275 ><TR
 276 ><TD
 277 ALIGN="CENTER"
 278 ><B
 279 >Caution</B
 280 ></TD
 281 ></TR
 282 ><TR
 283 ><TD
 284 ALIGN="LEFT"
 285 ><P
 286 >In the current implementation
 287 <TT
 288 CLASS="FUNCTION"
 289 >cyg_exception_call_handler</TT
 290 > can only be used on
 291 the current thread. There is no support for delivering an exception to
 292 another thread.
 293       </P
 294 ></TD
 295 ></TR
 296 ></TABLE
 297 ></DIV
 298 ><DIV
 299 CLASS="NOTE"
 300 ><BLOCKQUOTE
 301 CLASS="NOTE"
 302 ><P
 303 ><B
 304 >Note: </B
 305 >Exceptions at the eCos kernel level refer specifically to
 306 hardware-related events such as unaligned accesses to memory or
 307 division by zero. There is no relation with other concepts that are
 308 also known as exceptions, for example the <TT
 309 CLASS="LITERAL"
 310 >throw</TT
 311 > and
 312 <TT
 313 CLASS="LITERAL"
 314 >catch</TT
 315 > facilities associated with C++.
 316       </P
 317 ></BLOCKQUOTE
 318 ></DIV
 319 ></DIV
 320 ><DIV
 321 CLASS="REFSECT1"
 322 ><A
 323 NAME="KERNEL-EXCEPTIONS-CONTEXT"
 324 ></A
 325 ><H2
 326 >Valid contexts</H2
 327 ><P
 328 >If the system is configured with a single set of global exception
 329 handlers then
 330 <TT
 331 CLASS="FUNCTION"
 332 >cyg_exception_set_handler</TT
 333 > and
 334 <TT
 335 CLASS="FUNCTION"
 336 >cyg_exception_clear_handler</TT
 337 > may be called during
 338 initialization or from thread context. If instead per-thread exception
 339 handlers are being used then it is not possible to install new
 340 handlers during initialization because the functions operate
 341 implicitly on the current thread, so they can only be called from
 342 thread context. <TT
 343 CLASS="FUNCTION"
 344 >cyg_exception_call_handler</TT
 345 > should
 346 only be called from thread context.
 347       </P
 348 ></DIV
 349 ><DIV
 350 CLASS="NAVFOOTER"
 351 ><HR
 352 ALIGN="LEFT"
 353 WIDTH="100%"><TABLE
 354 SUMMARY="Footer navigation table"
 355 WIDTH="100%"
 356 BORDER="0"
 357 CELLPADDING="0"
 358 CELLSPACING="0"
 359 ><TR
 360 ><TD
 361 WIDTH="33%"
 362 ALIGN="left"
 363 VALIGN="top"
 364 ><A
 365 HREF="kernel-thread-destructors.html"
 366 ACCESSKEY="P"
 367 >Prev</A
 368 ></TD
 369 ><TD
 370 WIDTH="34%"
 371 ALIGN="center"
 372 VALIGN="top"
 373 ><A
 374 HREF="ecos-ref.html"
 375 ACCESSKEY="H"
 376 >Home</A
 377 ></TD
 378 ><TD
 379 WIDTH="33%"
 380 ALIGN="right"
 381 VALIGN="top"
 382 ><A
 383 HREF="kernel-counters.html"
 384 ACCESSKEY="N"
 385 >Next</A
 386 ></TD
 387 ></TR
 388 ><TR
 389 ><TD
 390 WIDTH="33%"
 391 ALIGN="left"
 392 VALIGN="top"
 393 >Thread destructors</TD
 394 ><TD
 395 WIDTH="34%"
 396 ALIGN="center"
 397 VALIGN="top"
 398 ><A
 399 HREF="kernel.html"
 400 ACCESSKEY="U"
 401 >Up</A
 402 ></TD
 403 ><TD
 404 WIDTH="33%"
 405 ALIGN="right"
 406 VALIGN="top"
 407 >Counters</TD
 408 ></TR
 409 ></TABLE
 410 ></DIV
 411 ></BODY
 412 ></HTML
 413 >