Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / ece1f685a8899e458e41b1b50c5c914acd95e175 / . / docs / ExceptionHandling.html
blob: 57b0c4d84887555b480bed8cabfa2007842aafcb [file] [log] [blame]
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>Exception Handling in LLVM</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
10<div class="doc_title">Exception Handling in LLVM</div>
11
12<table class="layout" style="width:100%">
13 <tr class="layout">
14 <td class="left">
15<ul>
16 <li><a href="#introduction">Introduction</a>
17 <ol>
18 <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
19 <li><a href="#overview">Overview</a></li>
20 </ol></li>
21 <li><a href="#codegen">LLVM Code Generation</a>
22 <ol>
23 <li><a href="#throw">Throw</a></li>
24 <li><a href="#try_catch">Try/Catch</a></li>
Duncan Sands8036ca42007-03-30 12:22:09 +0000[diff] [blame]25 <li><a href="#finallys">Finallys</a></li>
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]26 <li><a href="#throw_filters">Throw Filters</a></li>
27 </ol></li>
Duncan Sands8036ca42007-03-30 12:22:09 +0000[diff] [blame]28 <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a>
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]29 <ol>
30 <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a></li>
31 <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a></li>
32 <li><a href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a></li>
33 <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li>
34 </ol></li>
35 <li><a href="#asm">Asm Table Formats</a>
36 <ol>
37 <li><a href="#unwind_tables">Exception Handling Frame</a></li>
38 <li><a href="#exception_tables">Exception Tables</a></li>
39 </ol></li>
40 <li><a href="#todo">ToDo</a></li>
41</ul>
42</td>
43</tr></table>
44
45<div class="doc_author">
46 <p>Written by <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
47</div>
48
49
50<!-- *********************************************************************** -->
51<div class="doc_section"><a name="introduction">Introduction</a></div>
52<!-- *********************************************************************** -->
53
54<div class="doc_text">
55
56<p>This document is the central repository for all information pertaining to
57exception handling in LLVM. It describes the format that LLVM exception
58handling information takes, which is useful for those interested in creating
59front-ends or dealing directly with the information. Further, this document
60provides specific examples of what exception handling information is used for
61C/C++.</p>
62
63</div>
64
65<!-- ======================================================================= -->
66<div class="doc_subsection">
67 <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
68</div>
69
70<div class="doc_text">
71
72<p>Exception handling for most programming languages is designed to recover from
73conditions that rarely occur during general use of an application. To that end,
74exception handling should not interfere with the main flow of an
75application&apos;s algorithm by performing checkpointing tasks such as saving
76the current pc or register state.</p>
77
78<p>The Itanium ABI Exception Handling Specification defines a methodology for
79providing outlying data in the form of exception tables without inlining
80speculative exception handling code in the flow of an application&apos;s main
81algorithm. Thus, the specification is said to add "zero-cost" to the normal
82execution of an application.</p>
83
84<p>A more complete description of the Itanium ABI exception handling runtime
85support of can be found at <a
86href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI:
87Exception Handling.</a> A description of the exception frame format can be
88found at <a
89href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-
90Core-generic/ehframechpt.html">Exception Frames</a>, with details of the Dwarf
91specification at <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3
92Standard.</a> A description for the C++ exception table formats can be found at
93<a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling
94Tables.</a></p>
95
96</div>
97
98<!-- ======================================================================= -->
99<div class="doc_subsection">
100 <a name="overview">Overview</a>
101</div>
102
103<div class="doc_text">
104
105<p>When an exception is thrown in llvm code, the runtime does a best effort to
106find a handler suited to process the circumstance.</p>
107
108<p>The runtime first attempts to find an <i>exception frame</i> corresponding to
109the function where the exception was thrown. If the programming language (ex.
110C++) supports exception handling, the exception frame contains a reference to an
111exception table describing how to process the exception. If the language (ex.
112C) does not support exception handling or if the exception needs to be forwarded
113to a prior activation, the exception frame contains information about how to
114unwind the current activation and restore the state of the prior activation.
115This process is repeated until the exception is handled. If the exception is
116not handled and no activations remain, then the application is terminated with
117an appropriate error message.</p>
118
119<p>Since different programming languages have different behaviors when handling
120exceptions, the exception handling ABI provides a mechanism for supplying
121<i>personalities.</i> An exception handling personality is defined by way of a
122<i>personality function</i> (ex. for C++ <tt>__gxx_personality_v0</tt>) which
123receives the context of the exception, an <i>exception structure</i> containing
Duncan Sandsfb0a64a2007-04-16 13:02:27 +0000[diff] [blame]124the exception object type and value, and a reference to the exception table for
125the current function. The personality function for the current compile unit is
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]126specified in a <i>common exception frame</i>.</p>
127
128<p>The organization of an exception table is language dependent. For C++, an
129exception table is organized as a series of code ranges defining what to do if
130an exception occurs in that range. Typically, the information associated with a
131range defines which types of exception objects (using C++ <i>type info</i>) that
132are handled in that range, and an associated action that should take place.
133Actions typically pass control to a <i>landing pad</i>.</p>
134
135<p>A landing pad corresponds to the code found in the catch portion of a
136try/catch sequence. When execution resumes at a landing pad, it receives the
137exception structure and a selector corresponding to the <i>type</i> of exception
138thrown. The selector is then used to determine which catch should actually
139process the exception.</p>
140
141</div>
142
143<!-- ======================================================================= -->
144<div class="doc_section">
145 <a name="codegen">LLVM Code Generation</a>
146</div>
147
148<div class="doc_text">
149
150<p>At the time of this writing, only C++ exception handling support is available
151in LLVM. So the remainder of this document will be somewhat C++-centric.</p>
152
153<p>From the C++ developers perspective, exceptions are defined in terms of the
154<tt>throw</tt> and <tt>try/catch</tt> statements. In this section we will
155describe the implementation of llvm exception handling in terms of C++
156examples.</p>
157
158</div>
159
160<!-- ======================================================================= -->
161<div class="doc_subsection">
162 <a name="throw">Throw</a>
163</div>
164
165<div class="doc_text">
166
167<p>Languages that support exception handling typically provide a <tt>throw</tt>
168operation to initiate the exception process. Internally, a throw operation
169breaks down into two steps. First, a request is made to allocate exception
170space for an exception structure. This structure needs to survive beyond the
171current activation. This structure will contain the type and value of the
172object being thrown. Second, a call is made to the runtime to raise the
173exception, passing the exception structure as an argument.</p>
174
175<p>In C++, the allocation of the exception structure is done by the
176<tt>__cxa_allocate_exception</tt> runtime function. The exception raising is
177handled by <tt>__cxa_throw</tt>. The type of the exception is represented using
178a C++ RTTI type info structure.</p>
179
180</div>
181
182<!-- ======================================================================= -->
183<div class="doc_subsection">
184 <a name="try_catch">Try/Catch</a>
185</div>
186
187<div class="doc_text">
188
Duncan Sandsb0a1cbf2007-04-14 12:30:27 +0000[diff] [blame]189<p>A call within the scope of a try statement can potentially raise an exception.
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]190In those circumstances, the LLVM C++ front-end replaces the call with an
191<tt>invoke</tt> instruction. Unlike a call, the invoke has two potential
192continuation points; where to continue when the call succeeds as per normal, and
193where to continue if the call raises an exception, either by a throw or the
194unwinding of a throw.</p>
195
196<p>The term used to define a the place where an invoke continues after an
197exception is called a <i>landing pad</i>. LLVM landing pads are conceptually
Duncan Sandsfb0a64a2007-04-16 13:02:27 +0000[diff] [blame]198alternative function entry points where a exception structure reference and a type
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]199info index are passed in as arguments. The landing pad saves the exception
200structure reference and then proceeds to select the catch block that corresponds
201to the type info of the exception object.</p>
202
203<p>Two llvm intrinsic functions are used convey information about the landing
204pad to the back end.</p>
205
206<p><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no
207arguments and returns the exception structure reference. The backend replaces
208this intrinsic with the code that accesses the first argument of a call. The
209LLVM C++ front end generates code to save this value in an alloca location for
210further use in the landing pad and catch code.</p>
211
212<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
213three arguments. The first argument is the reference to the exception
214structure. The second argument is a reference to the personality function to be
215used for this try catch sequence. The remaining arguments are references to the
216type infos for each of the catch statements in the order they should be tested.
217The <i>catch all</i> (...) is represented with a <tt>null i8*</tt>. The result
218of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is the index of
219the type info in the corresponding exception table. The LLVM C++ front end
220generates code to save this value in an alloca location for further use in the
221landing pad and catch code.</p>
222
223<p>Once the landing pad has the type info selector, the code branches to the
224code for the first catch. The catch then checks the value of the type info
225selector against the index of type info for that catch. Since the type info
226index is not known until all the type info have been gathered in the backend,
227the catch code will call the <a
228href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to
229determine the index for a given type info. If the catch fails to match the
230selector then control is passed on to the next catch. Note: Since the landing
231pad will not be used if there is no match in the list of type info on the call
232to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then neither the
233last catch nor <i>catch all</i> need to perform the the check against the
234selector.</p>
235
236<p>Finally, the entry and exit of catch code is bracketed with calls to
237<tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.
238<tt>__cxa_begin_catch</tt> takes a exception structure reference as an argument
239and returns the value of the exception object.</tt> <tt>__cxa_end_catch</tt>
240takes a exception structure reference as an argument. This function clears the
241exception from the exception space. Note: a rethrow from within the catch may
242replace this call with a <tt>__cxa_rethrow</tt>.</p>
243
244</div>
245
246<!-- ======================================================================= -->
247<div class="doc_subsection">
248 <a name="finallys">Finallys</a>
249</div>
250
251<div class="doc_text">
252
253<p>To handle destructors and cleanups in try code, control may not run directly
254from a landing pad to the first catch. Control may actually flow from the
255landing pad to clean up code and then to the first catch. Since the required
256clean up for each invoke in a try may be different (ex., intervening
257constructor), there may be several landing pads for a given try.</p>
258
259</div>
260
261<!-- ======================================================================= -->
262<div class="doc_subsection">
263 <a name="throw_filters">Throw Filters</a>
264</div>
265
266<div class="doc_text">
267
268<p>C++ allows the specification of which exception types that can be thrown from
269a function. To represent this a top level landing pad may exist to filter out
270invalid types. To express this in LLVM code the landing pad will call <a
271href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a> instead of <a
272href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The arguments are the
273same, but what gets created in the exception table is different. <a
274href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a> will return a negative value
275if it doesn't find a match. If no match is found then a call to
276<tt>__cxa_call_unexpected</tt> should be made, otherwise
277<tt>_Unwind_Resume</tt>. Each of these functions require a reference to the
278exception structure.</p>
279
280</div>
281
282<!-- ======================================================================= -->
283<div class="doc_section">
Duncan Sands8036ca42007-03-30 12:22:09 +0000[diff] [blame]284 <a name="format_common_intrinsics">Exception Handling Intrinsics</a>
Jim Laskeyd0d39b62007-03-14 19:29:42 +0000[diff] [blame]285</div>
286
287<div class="doc_text">
288
289<p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to
290provide exception handling information at various points in generated code.</p>
291
292</div>
293
294<!-- ======================================================================= -->
295<div class="doc_subsubsection">
296 <a name="llvm_eh_exception">llvm.eh.exception</a>
297</div>
298
299<div class="doc_text">
300<pre>
301 i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( )
302</pre>
303
304<p>This intrinsic indicates that the exception structure is available at this
305point in the code. The backend will replace this intrinsic with code to fetch
306the first argument of a call. The effect is that the intrinsic result is the
307exception structure reference.</p>
308
309</div>
310
311<!-- ======================================================================= -->
312<div class="doc_subsubsection">
313 <a name="llvm_eh_selector">llvm.eh.selector</a>
314</div>
315
316<div class="doc_text">
317<pre>
318 i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...)
319</pre>
320
321<p>This intrinsic indicates that the exception selector is available at this
322point in the code. The backend will replace this intrinsic with code to fetch
323the second argument of a call. The effect is that the intrinsic result is the
324exception selector.</p>
325
326<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
327three arguments. The first argument is the reference to the exception
328structure. The second argument is a reference to the personality function to be
329used for this try catch sequence. The remaining arguments are references to the
330type infos for each of the catch statements in the order they should be tested.
331The <i>catch all</i> (...) is represented with a <tt>null i8*</tt>.</p>
332
333</div>
334
335<!-- ======================================================================= -->
336<div class="doc_subsubsection">
337 <a name="llvm_eh_filter">llvm.eh.filter</a>
338</div>
339
340<div class="doc_text">
341<pre>
342 i32 %<a href="#llvm_eh_filter">llvm.eh.filter</a>(i8*, i8*, i8*, ...)
343</pre>
344
345<p>This intrinsic indicates that the exception selector is available at this
346point in the code. The backend will replace this intrinsic with code to fetch
347the second argument of a call. The effect is that the intrinsic result is the
348exception selector.</p>
349
350<p><a href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a> takes a minimum of
351three arguments. The first argument is the reference to the exception
352structure. The second argument is a reference to the personality function to be
353used for this function. The remaining arguments are references to the type infos
354for each type that can be thrown by the current function.</p>
355
356</div>
357
358<!-- ======================================================================= -->
359<div class="doc_subsubsection">
360 <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
361</div>
362
363<div class="doc_text">
364<pre>
365 i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*)
366</pre>
367
368<p>This intrinsic returns the type info index in the exception table of the
369current function. This value can be used to compare against the result of <a
370href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single argument is
371a reference to a type info.</p>
372
373</div>
374
375<!-- ======================================================================= -->
376<div class="doc_section">
377 <a name="asm">Asm Table Formats</a>
378</div>
379
380<div class="doc_text">
381
382<p>There are two tables that are used by the exception handling runtime to
383determine which actions should take place when an exception is thrown.</p>
384
385</div>
386
387<!-- ======================================================================= -->
388<div class="doc_subsection">
389 <a name="unwind_tables">Exception Handling Frame</a>
390</div>
391
392<div class="doc_text">
393
394<p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
395frame used by dwarf debug info. The frame contains all the information
396necessary to tear down the current frame and restore the state of the prior
397frame. There is an exception handling frame for each function in a compile
398unit, plus a common exception handling frame that defines information common to
399all functions in the unit.</p>
400
401<p>Todo - Table details here.</p>
402
403</div>
404
405<!-- ======================================================================= -->
406<div class="doc_subsection">
407 <a name="exception_tables">Exception Tables</a>
408</div>
409
410<div class="doc_text">
411
412<p>An exception table contains information about what actions to take when an
413exception is thrown in a particular part of a function&apos;s code. There is
414one exception table per function except leaf routines and functions that have
415only calls to non-throwing functions will not need an exception table.</p>
416
417<p>Todo - Table details here.</p>
418
419</div>
420
421<!-- ======================================================================= -->
422<div class="doc_section">
423 <a name="todo">ToDo</a>
424</div>
425
426<div class="doc_text">
427
428<ol>
429
430<li><p>Need to create landing pads for code in between explicit landing pads.
431The landing pads will have a zero action and a NULL landing pad address and are
432used to inform the runtime that the exception should be rethrown.</li></p>
433
434<li><p>Actions for a given function should be folded to save space.</p></li>
435
436<li><p>Filters for inlined functions need to be handled more extensively.
437Currently it&apos;s hardwired for one filter per function.</li></p>
438
439<li><p>Testing/Testing/Testing.</li></p>
440
441</ol>
442
443</div>
444
445<!-- *********************************************************************** -->
446
447<hr>
448<address>
449 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
450 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
451 <a href="http://validator.w3.org/check/referer"><img
452 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
453
454 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
455 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
456 Last modified: $Date$
457</address>
458
459</body>
460</html>