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. -->
12 >Exception handling</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
25 TITLE="Thread destructors"
26 HREF="kernel-thread-destructors.html"><LINK
29 HREF="kernel-counters.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-thread-destructors.html"
71 HREF="kernel-counters.html"
82 NAME="KERNEL-EXCEPTIONS">Exception handling</H1
90 >cyg_exception_set_handler, cyg_exception_clear_handler, cyg_exception_call_handler -- Handle processor exceptions</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
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
125 >void cyg_exception_clear_handler</CODE
126 >(cyg_code_t exception_number);</CODE
132 >void cyg_exception_call_handler</CODE
133 >(cyg_handle_t thread, cyg_code_t exception_number, cyg_addrword_t exception_info);</CODE
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.
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
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
168 >Exception handling is optional, and can be disabled through the
169 configuration option <TT
171 >CYGPKG_KERNEL_EXCEPTIONS</TT
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
184 >CYGSEM_KERNEL_EXCEPTIONS_DECODE</TT
188 >An alternative handler can be installed using
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:
207 CLASS="PROGRAMLISTING"
209 my_exception_handler(cyg_addrword_t data, cyg_code_t exception, cyg_addrword_t info)
218 >The data argument corresponds to the <TT
224 parameter supplied to <TT
226 >cyg_exception_set_handler</TT
228 The exception code is provided as well, in case a single handler is
229 expected to support multiple exceptions. The <TT
235 argument will depend on the hardware and on the specific exception.
240 >cyg_exception_clear_handler</TT
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.
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
254 >CYGSEM_KERNEL_EXCEPTIONS_GLOBAL</TT
256 exception handlers are being used then
259 >cyg_exception_set_handler</TT
263 >cyg_exception_clear_handler</TT
264 > apply to the current
265 thread. Otherwise they apply to the global set of handlers.
286 >In the current implementation
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
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
315 > facilities associated with C++.
323 NAME="KERNEL-EXCEPTIONS-CONTEXT"
328 >If the system is configured with a single set of global exception
332 >cyg_exception_set_handler</TT
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
344 >cyg_exception_call_handler</TT
346 only be called from thread context.
354 SUMMARY="Footer navigation table"
365 HREF="kernel-thread-destructors.html"
383 HREF="kernel-counters.html"
393 >Thread destructors</TD