<head>
<title>Exception Handling in LLVM</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="description"
+ <meta name="description"
content="Exception Handling in LLVM.">
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<li><a href="#introduction">Introduction</a>
<ol>
<li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
+ <li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li>
<li><a href="#overview">Overview</a></li>
</ol></li>
<li><a href="#codegen">LLVM Code Generation</a>
<li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li>
<li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li>
<li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li>
+ <li><a href="#llvm_eh_sjlj_callsite"><tt>llvm.eh.sjlj.callsite</tt></a></li>
+ <li><a href="#llvm_eh_sjlj_dispatchsetup"><tt>llvm.eh.sjlj.dispatchsetup</tt></a></li>
</ol></li>
<li><a href="#asm">Asm Table Formats</a>
<ol>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="introduction">Introduction</a></div>
+<div class="doc_section"><a name="introduction">Introduction</a></div>
<!-- *********************************************************************** -->
<div class="doc_text">
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="sjlj">Setjmp/Longjmp Exception Handling</a>
+</div>
+
+<div class="doc_text">
+
+<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+ <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and
+ <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to
+ handle control flow for exception handling.</p>
+
+<p>For each function which does exception processing, be it try/catch blocks
+ or cleanups, that function registers itself on a global frame list. When
+ exceptions are being unwound, the runtime uses this list to identify which
+ functions need processing.<p>
+
+<p>Landing pad selection is encoded in the call site entry of the function
+ context. The runtime returns to the function via
+ <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where
+ a switch table transfers control to the appropriate landing pad based on
+ the index stored in the function context.</p>
+
+<p>In contrast to DWARF exception handling, which encodes exception regions
+ and frame information in out-of-line tables, SJLJ exception handling
+ builds and removes the unwind frame context at runtime. This results in
+ faster exception handling at the expense of slower execution when no
+ exceptions are thrown. As exceptions are, by their nature, intended for
+ uncommon code paths, DWARF exception handling is generally preferred to
+ SJLJ.</p>
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="overview">Overview</a>
<li><tt>__cxa_begin_catch</tt> takes a exception structure reference as an
argument and returns the value of the exception object.</li>
- <li><tt>__cxa_end_catch</tt> takes a exception structure reference as an
- argument. This function clears the exception from the exception space.
- Note: a rethrow from within the catch may replace this call with
- a <tt>__cxa_rethrow</tt>.</li>
+ <li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br>
+ <ol>
+ <li>Locates the most recently caught exception and decrements its handler
+ count,</li>
+ <li>Removes the exception from the "caught" stack if the handler count
+ goes to zero, and</li>
+ <li>Destroys the exception if the handler count goes to zero, and the
+ exception was not re-thrown by throw.</li>
+ </ol>
+ <p>Note: a rethrow from within the catch may replace this call with
+ a <tt>__cxa_rethrow</tt>.</p></li>
</ul>
</div>
from the landing pad to clean up code and then to the first catch. Since the
required clean up for each <tt>invoke</tt> in a <tt>try</tt> may be different
(e.g. intervening constructor), there may be several landing pads for a given
- try. If cleanups need to be run, the number zero should be passed as the
+ try. If cleanups need to be run, an <tt>i32 0</tt> should be passed as the
last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument.
- However for C++ a <tt>null i8*</tt> <b><a href="#restrictions">must</a></b>
- be passed instead.</p>
+ However, when using DWARF exception handling with C++, a <tt>i8* null</tt>
+ <a href="#restrictions">must</a> be passed instead.</p>
</div>
<div class="doc_text">
<pre>
- i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( )
+ i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>()
</pre>
<p>This intrinsic returns a pointer to the exception structure.</p>
<div class="doc_text">
<pre>
- i32 %<a href="#llvm_eh_selector">llvm.eh.selector.i32</a>(i8*, i8*, i8*, ...)
- i64 %<a href="#llvm_eh_selector">llvm.eh.selector.i64</a>(i8*, i8*, i8*, ...)
+ i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, ...)
</pre>
<p>This intrinsic is used to compare the exception with the given type infos,
<div class="doc_text">
<pre>
- i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i32</a>(i8*)
- i64 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i64</a>(i8*)
+ i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*)
</pre>
<p>This intrinsic returns the type info index in the exception table of the
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+ <a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a>
+</div>
+
+<div class="doc_text">
+
+<pre>
+ void %<a href="#llvm_eh_sjlj_longjmp">llvm.eh.sjlj.setjmp</a>(i8*)
+</pre>
+
+<p>The <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>
+ intrinsic is used to implement <tt>__builtin_longjmp()</tt> for SJLJ
+ style exception handling. The single parameter is a pointer to a
+ buffer populated by <a href="#llvm_eh_sjlj_setjmp">
+ <tt>llvm.eh.sjlj.setjmp</tt></a>. The frame pointer and stack pointer
+ are restored from the buffer, then control is transfered to the
+ destination address.</p>
+
+</div>
<!-- ======================================================================= -->
<div class="doc_subsubsection">
<a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>
<div class="doc_text">
<pre>
- i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>( )
+ i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>()
</pre>
<p>Used for SJLJ based exception handling, the <a href="#llvm_eh_sjlj_lsda">
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+ <a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>
+</div>
+
+<div class="doc_text">
+
+<pre>
+ void %<a href="#llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>(i32)
+</pre>
+
+<p>For SJLJ based exception handling, the <a href="#llvm_eh_sjlj_callsite">
+ <tt>llvm.eh.sjlj.callsite</tt></a> intrinsic identifies the callsite value
+ associated with the following invoke instruction. This is used to ensure
+ that landing pad entries in the LSDA are generated in the matching order.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+ <a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>
+</div>
+
+<div class="doc_text">
+
+<pre>
+ void %<a href="#llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>(i32)
+</pre>
+
+<p>For SJLJ based exception handling, the <a href="#llvm_eh_sjlj_dispatchsetup">
+ <tt>llvm.eh.sjlj.dispatchsetup</tt></a> intrinsic is used by targets to do
+ any unwind-edge setup they need. By default, no action is taken. </p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_section">
<a name="asm">Asm Table Formats</a>
projects / oota-llvm.git / blobdiff