diff options
Diffstat (limited to 'docs')
39 files changed, 4000 insertions, 3066 deletions
diff --git a/docs/Atomics.html b/docs/Atomics.html new file mode 100644 index 0000000..fc15e27 --- /dev/null +++ b/docs/Atomics.html @@ -0,0 +1,569 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>LLVM Atomic Instructions and Concurrency Guide</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<h1> + LLVM Atomic Instructions and Concurrency Guide +</h1> + +<ol> + <li><a href="#introduction">Introduction</a></li> + <li><a href="#outsideatomic">Optimization outside atomic</a></li> + <li><a href="#atomicinst">Atomic instructions</a></li> + <li><a href="#ordering">Atomic orderings</a></li> + <li><a href="#iropt">Atomics and IR optimization</a></li> + <li><a href="#codegen">Atomics and Codegen</a></li> +</ol> + +<div class="doc_author"> + <p>Written by Eli Friedman</p> +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="introduction">Introduction</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>Historically, LLVM has not had very strong support for concurrency; some +minimal intrinsics were provided, and <code>volatile</code> was used in some +cases to achieve rough semantics in the presence of concurrency. However, this +is changing; there are now new instructions which are well-defined in the +presence of threads and asynchronous signals, and the model for existing +instructions has been clarified in the IR.</p> + +<p>The atomic instructions are designed specifically to provide readable IR and + optimized code generation for the following:</p> +<ul> + <li>The new C++0x <code><atomic></code> header. + (<a href="http://www.open-std.org/jtc1/sc22/wg21/">C++0x draft available here</a>.) + (<a href="http://www.open-std.org/jtc1/sc22/wg14/">C1x draft available here</a>)</li> + <li>Proper semantics for Java-style memory, for both <code>volatile</code> and + regular shared variables. + (<a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">Java Specification</a>)</li> + <li>gcc-compatible <code>__sync_*</code> builtins. + (<a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Description</a>)</li> + <li>Other scenarios with atomic semantics, including <code>static</code> + variables with non-trivial constructors in C++.</li> +</ul> + +<p>Atomic and volatile in the IR are orthogonal; "volatile" is the C/C++ + volatile, which ensures that every volatile load and store happens and is + performed in the stated order. A couple examples: if a + SequentiallyConsistent store is immediately followed by another + SequentiallyConsistent store to the same address, the first store can + be erased. This transformation is not allowed for a pair of volatile + stores. On the other hand, a non-volatile non-atomic load can be moved + across a volatile load freely, but not an Acquire load.</p> + +<p>This document is intended to provide a guide to anyone either writing a + frontend for LLVM or working on optimization passes for LLVM with a guide + for how to deal with instructions with special semantics in the presence of + concurrency. This is not intended to be a precise guide to the semantics; + the details can get extremely complicated and unreadable, and are not + usually necessary.</p> + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="outsideatomic">Optimization outside atomic</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>The basic <code>'load'</code> and <code>'store'</code> allow a variety of + optimizations, but can lead to undefined results in a concurrent environment; + see <a href="#o_nonatomic">NonAtomic</a>. This section specifically goes + into the one optimizer restriction which applies in concurrent environments, + which gets a bit more of an extended description because any optimization + dealing with stores needs to be aware of it.</p> + +<p>From the optimizer's point of view, the rule is that if there + are not any instructions with atomic ordering involved, concurrency does + not matter, with one exception: if a variable might be visible to another + thread or signal handler, a store cannot be inserted along a path where it + might not execute otherwise. Take the following example:</p> + +<pre> +/* C code, for readability; run through clang -O2 -S -emit-llvm to get + equivalent IR */ +int x; +void f(int* a) { + for (int i = 0; i < 100; i++) { + if (a[i]) + x += 1; + } +} +</pre> + +<p>The following is equivalent in non-concurrent situations:</p> + +<pre> +int x; +void f(int* a) { + int xtemp = x; + for (int i = 0; i < 100; i++) { + if (a[i]) + xtemp += 1; + } + x = xtemp; +} +</pre> + +<p>However, LLVM is not allowed to transform the former to the latter: it could + indirectly introduce undefined behavior if another thread can access x at + the same time. (This example is particularly of interest because before the + concurrency model was implemented, LLVM would perform this + transformation.)</p> + +<p>Note that speculative loads are allowed; a load which + is part of a race returns <code>undef</code>, but does not have undefined + behavior.</p> + + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="atomicinst">Atomic instructions</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>For cases where simple loads and stores are not sufficient, LLVM provides + various atomic instructions. The exact guarantees provided depend on the + ordering; see <a href="#ordering">Atomic orderings</a></p> + +<p><code>load atomic</code> and <code>store atomic</code> provide the same + basic functionality as non-atomic loads and stores, but provide additional + guarantees in situations where threads and signals are involved.</p> + +<p><code>cmpxchg</code> and <code>atomicrmw</code> are essentially like an + atomic load followed by an atomic store (where the store is conditional for + <code>cmpxchg</code>), but no other memory operation can happen on any thread + between the load and store. Note that LLVM's cmpxchg does not provide quite + as many options as the C++0x version.</p> + +<p>A <code>fence</code> provides Acquire and/or Release ordering which is not + part of another operation; it is normally used along with Monotonic memory + operations. A Monotonic load followed by an Acquire fence is roughly + equivalent to an Acquire load.</p> + +<p>Frontends generating atomic instructions generally need to be aware of the + target to some degree; atomic instructions are guaranteed to be lock-free, + and therefore an instruction which is wider than the target natively supports + can be impossible to generate.</p> + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="ordering">Atomic orderings</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>In order to achieve a balance between performance and necessary guarantees, + there are six levels of atomicity. They are listed in order of strength; + each level includes all the guarantees of the previous level except for + Acquire/Release. (See also <a href="LangRef.html#ordering">LangRef</a>.)</p> + +<!-- ======================================================================= --> +<h3> + <a name="o_notatomic">NotAtomic</a> +</h3> + +<div> + +<p>NotAtomic is the obvious, a load or store which is not atomic. (This isn't + really a level of atomicity, but is listed here for comparison.) This is + essentially a regular load or store. If there is a race on a given memory + location, loads from that location return undef.</p> + +<dl> + <dt>Relevant standard</dt> + <dd>This is intended to match shared variables in C/C++, and to be used + in any other context where memory access is necessary, and + a race is impossible. (The precise definition is in + <a href="LangRef.html#memmodel">LangRef</a>.) + <dt>Notes for frontends</dt> + <dd>The rule is essentially that all memory accessed with basic loads and + stores by multiple threads should be protected by a lock or other + synchronization; otherwise, you are likely to run into undefined + behavior. If your frontend is for a "safe" language like Java, + use Unordered to load and store any shared variable. Note that NotAtomic + volatile loads and stores are not properly atomic; do not try to use + them as a substitute. (Per the C/C++ standards, volatile does provide + some limited guarantees around asynchronous signals, but atomics are + generally a better solution.) + <dt>Notes for optimizers</dt> + <dd>Introducing loads to shared variables along a codepath where they would + not otherwise exist is allowed; introducing stores to shared variables + is not. See <a href="#outsideatomic">Optimization outside + atomic</a>.</dd> + <dt>Notes for code generation</dt> + <dd>The one interesting restriction here is that it is not allowed to write + to bytes outside of the bytes relevant to a store. This is mostly + relevant to unaligned stores: it is not allowed in general to convert + an unaligned store into two aligned stores of the same width as the + unaligned store. Backends are also expected to generate an i8 store + as an i8 store, and not an instruction which writes to surrounding + bytes. (If you are writing a backend for an architecture which cannot + satisfy these restrictions and cares about concurrency, please send an + email to llvmdev.)</dd> +</dl> + +</div> + + +<!-- ======================================================================= --> +<h3> + <a name="o_unordered">Unordered</a> +</h3> + +<div> + +<p>Unordered is the lowest level of atomicity. It essentially guarantees that + races produce somewhat sane results instead of having undefined behavior. + It also guarantees the operation to be lock-free, so it do not depend on + the data being part of a special atomic structure or depend on a separate + per-process global lock. Note that code generation will fail for + unsupported atomic operations; if you need such an operation, use explicit + locking.</p> + +<dl> + <dt>Relevant standard</dt> + <dd>This is intended to match the Java memory model for shared + variables.</dd> + <dt>Notes for frontends</dt> + <dd>This cannot be used for synchronization, but is useful for Java and + other "safe" languages which need to guarantee that the generated + code never exhibits undefined behavior. Note that this guarantee + is cheap on common platforms for loads of a native width, but can + be expensive or unavailable for wider loads, like a 64-bit store + on ARM. (A frontend for Java or other "safe" languages would normally + split a 64-bit store on ARM into two 32-bit unordered stores.) + <dt>Notes for optimizers</dt> + <dd>In terms of the optimizer, this prohibits any transformation that + transforms a single load into multiple loads, transforms a store + into multiple stores, narrows a store, or stores a value which + would not be stored otherwise. Some examples of unsafe optimizations + are narrowing an assignment into a bitfield, rematerializing + a load, and turning loads and stores into a memcpy call. Reordering + unordered operations is safe, though, and optimizers should take + advantage of that because unordered operations are common in + languages that need them.</dd> + <dt>Notes for code generation</dt> + <dd>These operations are required to be atomic in the sense that if you + use unordered loads and unordered stores, a load cannot see a value + which was never stored. A normal load or store instruction is usually + sufficient, but note that an unordered load or store cannot + be split into multiple instructions (or an instruction which + does multiple memory operations, like <code>LDRD</code> on ARM).</dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="o_monotonic">Monotonic</a> +</h3> + +<div> + +<p>Monotonic is the weakest level of atomicity that can be used in + synchronization primitives, although it does not provide any general + synchronization. It essentially guarantees that if you take all the + operations affecting a specific address, a consistent ordering exists. + +<dl> + <dt>Relevant standard</dt> + <dd>This corresponds to the C++0x/C1x <code>memory_order_relaxed</code>; + see those standards for the exact definition. + <dt>Notes for frontends</dt> + <dd>If you are writing a frontend which uses this directly, use with caution. + The guarantees in terms of synchronization are very weak, so make + sure these are only used in a pattern which you know is correct. + Generally, these would either be used for atomic operations which + do not protect other memory (like an atomic counter), or along with + a <code>fence</code>.</dd> + <dt>Notes for optimizers</dt> + <dd>In terms of the optimizer, this can be treated as a read+write on the + relevant memory location (and alias analysis will take advantage of + that). In addition, it is legal to reorder non-atomic and Unordered + loads around Monotonic loads. CSE/DSE and a few other optimizations + are allowed, but Monotonic operations are unlikely to be used in ways + which would make those optimizations useful.</dd> + <dt>Notes for code generation</dt> + <dd>Code generation is essentially the same as that for unordered for loads + and stores. No fences are required. <code>cmpxchg</code> and + <code>atomicrmw</code> are required to appear as a single operation.</dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="o_acquire">Acquire</a> +</h3> + +<div> + +<p>Acquire provides a barrier of the sort necessary to acquire a lock to access + other memory with normal loads and stores. + +<dl> + <dt>Relevant standard</dt> + <dd>This corresponds to the C++0x/C1x <code>memory_order_acquire</code>. It + should also be used for C++0x/C1x <code>memory_order_consume</code>. + <dt>Notes for frontends</dt> + <dd>If you are writing a frontend which uses this directly, use with caution. + Acquire only provides a semantic guarantee when paired with a Release + operation.</dd> + <dt>Notes for optimizers</dt> + <dd>Optimizers not aware of atomics can treat this like a nothrow call. + It is also possible to move stores from before an Acquire load + or read-modify-write operation to after it, and move non-Acquire + loads from before an Acquire operation to after it.</dd> + <dt>Notes for code generation</dt> + <dd>Architectures with weak memory ordering (essentially everything relevant + today except x86 and SPARC) require some sort of fence to maintain + the Acquire semantics. The precise fences required varies widely by + architecture, but for a simple implementation, most architectures provide + a barrier which is strong enough for everything (<code>dmb</code> on ARM, + <code>sync</code> on PowerPC, etc.). Putting such a fence after the + equivalent Monotonic operation is sufficient to maintain Acquire + semantics for a memory operation.</dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="o_acquire">Release</a> +</h3> + +<div> + +<p>Release is similar to Acquire, but with a barrier of the sort necessary to + release a lock. + +<dl> + <dt>Relevant standard</dt> + <dd>This corresponds to the C++0x/C1x <code>memory_order_release</code>.</dd> + <dt>Notes for frontends</dt> + <dd>If you are writing a frontend which uses this directly, use with caution. + Release only provides a semantic guarantee when paired with a Acquire + operation.</dd> + <dt>Notes for optimizers</dt> + <dd>Optimizers not aware of atomics can treat this like a nothrow call. + It is also possible to move loads from after a Release store + or read-modify-write operation to before it, and move non-Release + stores from after an Release operation to before it.</dd> + <dt>Notes for code generation</dt> + <dd>See the section on Acquire; a fence before the relevant operation is + usually sufficient for Release. Note that a store-store fence is not + sufficient to implement Release semantics; store-store fences are + generally not exposed to IR because they are extremely difficult to + use correctly.</dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="o_acqrel">AcquireRelease</a> +</h3> + +<div> + +<p>AcquireRelease (<code>acq_rel</code> in IR) provides both an Acquire and a + Release barrier (for fences and operations which both read and write memory). + +<dl> + <dt>Relevant standard</dt> + <dd>This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>. + <dt>Notes for frontends</dt> + <dd>If you are writing a frontend which uses this directly, use with caution. + Acquire only provides a semantic guarantee when paired with a Release + operation, and vice versa.</dd> + <dt>Notes for optimizers</dt> + <dd>In general, optimizers should treat this like a nothrow call; the + the possible optimizations are usually not interesting.</dd> + <dt>Notes for code generation</dt> + <dd>This operation has Acquire and Release semantics; see the sections on + Acquire and Release.</dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="o_seqcst">SequentiallyConsistent</a> +</h3> + +<div> + +<p>SequentiallyConsistent (<code>seq_cst</code> in IR) provides + Acquire semantics for loads and Release semantics for + stores. Additionally, it guarantees that a total ordering exists + between all SequentiallyConsistent operations. + +<dl> + <dt>Relevant standard</dt> + <dd>This corresponds to the C++0x/C1x <code>memory_order_seq_cst</code>, + Java volatile, and the gcc-compatible <code>__sync_*</code> builtins + which do not specify otherwise. + <dt>Notes for frontends</dt> + <dd>If a frontend is exposing atomic operations, these are much easier to + reason about for the programmer than other kinds of operations, and using + them is generally a practical performance tradeoff.</dd> + <dt>Notes for optimizers</dt> + <dd>Optimizers not aware of atomics can treat this like a nothrow call. + For SequentiallyConsistent loads and stores, the same reorderings are + allowed as for Acquire loads and Release stores, except that + SequentiallyConsistent operations may not be reordered.</dd> + <dt>Notes for code generation</dt> + <dd>SequentiallyConsistent loads minimally require the same barriers + as Acquire operations and SequentiallyConsistent stores require + Release barriers. Additionally, the code generator must enforce + ordering between SequentiallyConsistent stores followed by + SequentiallyConsistent loads. This is usually done by emitting + either a full fence before the loads or a full fence after the + stores; which is preferred varies by architecture.</dd> +</dl> + +</div> + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="iropt">Atomics and IR optimization</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>Predicates for optimizer writers to query: +<ul> + <li>isSimple(): A load or store which is not volatile or atomic. This is + what, for example, memcpyopt would check for operations it might + transform.</li> + <li>isUnordered(): A load or store which is not volatile and at most + Unordered. This would be checked, for example, by LICM before hoisting + an operation.</li> + <li>mayReadFromMemory()/mayWriteToMemory(): Existing predicate, but note + that they return true for any operation which is volatile or at least + Monotonic.</li> + <li>Alias analysis: Note that AA will return ModRef for anything Acquire or + Release, and for the address accessed by any Monotonic operation.</li> +</ul> + +<p>To support optimizing around atomic operations, make sure you are using + the right predicates; everything should work if that is done. If your + pass should optimize some atomic operations (Unordered operations in + particular), make sure it doesn't replace an atomic load or store with + a non-atomic operation.</p> + +<p>Some examples of how optimizations interact with various kinds of atomic + operations: +<ul> + <li>memcpyopt: An atomic operation cannot be optimized into part of a + memcpy/memset, including unordered loads/stores. It can pull operations + across some atomic operations. + <li>LICM: Unordered loads/stores can be moved out of a loop. It just treats + monotonic operations like a read+write to a memory location, and anything + stricter than that like a nothrow call. + <li>DSE: Unordered stores can be DSE'ed like normal stores. Monotonic stores + can be DSE'ed in some cases, but it's tricky to reason about, and not + especially important. + <li>Folding a load: Any atomic load from a constant global can be + constant-folded, because it cannot be observed. Similar reasoning allows + scalarrepl with atomic loads and stores. +</ul> + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="codegen">Atomics and Codegen</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>Atomic operations are represented in the SelectionDAG with + <code>ATOMIC_*</code> opcodes. On architectures which use barrier + instructions for all atomic ordering (like ARM), appropriate fences are + split out as the DAG is built.</p> + +<p>The MachineMemOperand for all atomic operations is currently marked as + volatile; this is not correct in the IR sense of volatile, but CodeGen + handles anything marked volatile very conservatively. This should get + fixed at some point.</p> + +<p>Common architectures have some way of representing at least a pointer-sized + lock-free <code>cmpxchg</code>; such an operation can be used to implement + all the other atomic operations which can be represented in IR up to that + size. Backends are expected to implement all those operations, but not + operations which cannot be implemented in a lock-free manner. It is + expected that backends will give an error when given an operation which + cannot be implemented. (The LLVM code generator is not very helpful here + at the moment, but hopefully that will change.)</p> + +<p>The implementation of atomics on LL/SC architectures (like ARM) is currently + a bit of a mess; there is a lot of copy-pasted code across targets, and + the representation is relatively unsuited to optimization (it would be nice + to be able to optimize loops involving cmpxchg etc.).</p> + +<p>On x86, all atomic loads generate a <code>MOV</code>. + SequentiallyConsistent stores generate an <code>XCHG</code>, other stores + generate a <code>MOV</code>. SequentiallyConsistent fences generate an + <code>MFENCE</code>, other fences do not cause any code to be generated. + cmpxchg uses the <code>LOCK CMPXCHG</code> instruction. + <code>atomicrmw xchg</code> uses <code>XCHG</code>, + <code>atomicrmw add</code> and <code>atomicrmw sub</code> use + <code>XADD</code>, and all other <code>atomicrmw</code> operations generate + a loop with <code>LOCK CMPXCHG</code>. Depending on the users of the + result, some <code>atomicrmw</code> operations can be translated into + operations like <code>LOCK AND</code>, but that does not work in + general.</p> + +<p>On ARM, MIPS, and many other RISC architectures, Acquire, Release, and + SequentiallyConsistent semantics require barrier instructions + for every such operation. Loads and stores generate normal instructions. + <code>cmpxchg</code> and <code>atomicrmw</code> can be represented using + a loop with LL/SC-style instructions which take some sort of exclusive + lock on a cache line (<code>LDREX</code> and <code>STREX</code> on + ARM, etc.). At the moment, the IR does not provide any way to represent a + weak <code>cmpxchg</code> which would not require a loop.</p> +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + + <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> + Last modified: $Date: 2011-08-09 02:07:00 -0700 (Tue, 09 Aug 2011) $ +</address> + +</body> +</html> diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html index 05c867b..bc78933 100644 --- a/docs/Bugpoint.html +++ b/docs/Bugpoint.html @@ -216,18 +216,6 @@ non-obvious ways. Here are some hints and tips:<p> the list of specified optimizations to be randomized and applied to the program. This process will repeat until a bug is found or the user kills <tt>bugpoint</tt>. - -<li><p><tt>bugpoint</tt> does not understand the <tt>-O</tt> option - that is used to specify optimization level to <tt>opt</tt>. You - can use e.g.</p> - -<div class="doc_code"> -<p><tt>opt -O2 -debug-pass=Arguments foo.bc -disable-output</tt></p> -</div> - - <p>to get a list of passes that are used with <tt>-O2</tt> and - then pass this list to <tt>bugpoint</tt>.</p> - </ol> </div> @@ -243,7 +231,7 @@ non-obvious ways. Here are some hints and tips:<p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-08-30 20:26:11 +0200 (Tue, 30 Aug 2011) $ </address> </body> diff --git a/docs/CMake.html b/docs/CMake.html index 0d8cf62..6389c7f 100644 --- a/docs/CMake.html +++ b/docs/CMake.html @@ -340,7 +340,7 @@ on Visual C++ and Xcode, <tt>"-sv"</tt> on others.</dd> - <dt><b>LLVM_LIT_TOOLS_DIR</b>:STRING</dt> + <dt><b>LLVM_LIT_TOOLS_DIR</b>:PATH</dt> <dd>The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to "", then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first, @@ -423,8 +423,9 @@ set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake") include(LLVMConfig) <b># Now set the header and library paths:</b> - include_directories( ${LLVM_ROOT}/include ) - link_directories( ${LLVM_ROOT}/lib ) + include_directories( ${LLVM_INCLUDE_DIRS} ) + link_directories( ${LLVM_LIBRARY_DIRS} ) + add_definitions( ${LLVM_DEFINITIONS} ) <b># Let's suppose we want to build a JIT compiler with support for # binary code (no interpreter):</b> llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 29a2cce..e693a22 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -114,6 +114,7 @@ <li><a href="#ppc_prolog">Prolog/Epilog</a></li> <li><a href="#ppc_dynamic">Dynamic Allocation</a></li> </ul></li> + <li><a href="#ptx">The PTX backend</a></li> </ul></li> </ol> @@ -1768,22 +1769,28 @@ bool RegMapping_Fer::compatible_class(MachineFunction &mf, different register allocators:</p> <ul> - <li><i>Linear Scan</i> — <i>The default allocator</i>. This is the - well-know linear scan register allocator. Whereas the - <i>Simple</i> and <i>Local</i> algorithms use a direct mapping - implementation technique, the <i>Linear Scan</i> implementation - uses a spiller in order to place load and stores.</li> - <li><i>Fast</i> — This register allocator is the default for debug builds. It allocates registers on a basic block level, attempting to keep values in registers and reusing registers as appropriate.</li> + <li><i>Basic</i> — This is an incremental approach to register + allocation. Live ranges are assigned to registers one at a time in + an order that is driven by heuristics. Since code can be rewritten + on-the-fly during allocation, this framework allows interesting + allocators to be developed as extensions. It is not itself a + production register allocator but is a potentially useful + stand-alone mode for triaging bugs and as a performance baseline. + + <li><i>Greedy</i> — <i>The default allocator</i>. This is a + highly tuned implementation of the <i>Basic</i> allocator that + incorporates global live range splitting. This allocator works hard + to minimize the cost of spill code. + <li><i>PBQP</i> — A Partitioned Boolean Quadratic Programming (PBQP) based register allocator. This allocator works by constructing a PBQP problem representing the register allocation problem under consideration, solving this using a PBQP solver, and mapping the solution back to a register assignment.</li> - </ul> <p>The type of register allocator used in <tt>llc</tt> can be chosen with the @@ -1805,7 +1812,121 @@ $ llc -regalloc=pbqp file.bc -o pbqp.s; <h3> <a name="proepicode">Prolog/Epilog Code Insertion</a> </h3> -<div><p>To Be Written</p></div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="compact_unwind">Compact Unwind</a> +</h4> + +<div> + +<p>Throwing an exception requires <em>unwinding</em> out of a function. The + information on how to unwind a given function is traditionally expressed in + DWARF unwind (a.k.a. frame) info. But that format was originally developed + for debuggers to backtrace, and each Frame Description Entry (FDE) requires + ~20-30 bytes per function. There is also the cost of mapping from an address + in a function to the corresponding FDE at runtime. An alternative unwind + encoding is called <em>compact unwind</em> and requires just 4-bytes per + function.</p> + +<p>The compact unwind encoding is a 32-bit value, which is encoded in an + architecture-specific way. It specifies which registers to restore and from + where, and how to unwind out of the function. When the linker creates a final + linked image, it will create a <code>__TEXT,__unwind_info</code> + section. This section is a small and fast way for the runtime to access + unwind info for any given function. If we emit compact unwind info for the + function, that compact unwind info will be encoded in + the <code>__TEXT,__unwind_info</code> section. If we emit DWARF unwind info, + the <code>__TEXT,__unwind_info</code> section will contain the offset of the + FDE in the <code>__TEXT,__eh_frame</code> section in the final linked + image.</p> + +<p>For X86, there are three modes for the compact unwind encoding:</p> + +<dl> + <dt><i>Function with a Frame Pointer (<code>EBP</code> or <code>RBP</code>)</i></dt> + <dd><p><code>EBP/RBP</code>-based frame, where <code>EBP/RBP</code> is pushed + onto the stack immediately after the return address, + then <code>ESP/RSP</code> is moved to <code>EBP/RBP</code>. Thus to + unwind, <code>ESP/RSP</code> is restored with the + current <code>EBP/RBP</code> value, then <code>EBP/RBP</code> is restored + by popping the stack, and the return is done by popping the stack once + more into the PC. All non-volatile registers that need to be restored must + have been saved in a small range on the stack that + starts <code>EBP-4</code> to <code>EBP-1020</code> (<code>RBP-8</code> + to <code>RBP-1020</code>). The offset (divided by 4 in 32-bit mode and 8 + in 64-bit mode) is encoded in bits 16-23 (mask: <code>0x00FF0000</code>). + The registers saved are encoded in bits 0-14 + (mask: <code>0x00007FFF</code>) as five 3-bit entries from the following + table:</p> +<table border="1" cellspacing="0"> + <tr> + <th>Compact Number</th> + <th>i386 Register</th> + <th>x86-64 Regiser</th> + </tr> + <tr> + <td>1</td> + <td><code>EBX</code></td> + <td><code>RBX</code></td> + </tr> + <tr> + <td>2</td> + <td><code>ECX</code></td> + <td><code>R12</code></td> + </tr> + <tr> + <td>3</td> + <td><code>EDX</code></td> + <td><code>R13</code></td> + </tr> + <tr> + <td>4</td> + <td><code>EDI</code></td> + <td><code>R14</code></td> + </tr> + <tr> + <td>5</td> + <td><code>ESI</code></td> + <td><code>R15</code></td> + </tr> + <tr> + <td>6</td> + <td><code>EBP</code></td> + <td><code>RBP</code></td> + </tr> +</table> + +</dd> + + <dt><i>Frameless with a Small Constant Stack Size (<code>EBP</code> + or <code>RBP</code> is not used as a frame pointer)</i></dt> + <dd><p>To return, a constant (encoded in the compact unwind encoding) is added + to the <code>ESP/RSP</code>. Then the return is done by popping the stack + into the PC. All non-volatile registers that need to be restored must have + been saved on the stack immediately after the return address. The stack + size (divided by 4 in 32-bit mode and 8 in 64-bit mode) is encoded in bits + 16-23 (mask: <code>0x00FF0000</code>). There is a maximum stack size of + 1024 bytes in 32-bit mode and 2048 in 64-bit mode. The number of registers + saved is encoded in bits 9-12 (mask: <code>0x00001C00</code>). Bits 0-9 + (mask: <code>0x000003FF</code>) contain which registers were saved and + their order. (See + the <code>encodeCompactUnwindRegistersWithoutFrame()</code> function + in <code>lib/Target/X86FrameLowering.cpp</code> for the encoding + algorithm.)</p></dd> + + <dt><i>Frameless with a Large Constant Stack Size (<code>EBP</code> + or <code>RBP</code> is not used as a frame pointer)</i></dt> + <dd><p>This case is like the "Frameless with a Small Constant Stack Size" + case, but the stack size is too large to encode in the compact unwind + encoding. Instead it requires that the function contains "<code>subl + $nnnnnn, %esp</code>" in its prolog. The compact encoding contains the + offset to the <code>$nnnnnn</code> value in the function in bits 9-12 + (mask: <code>0x00001C00</code>).</p></dd> +</dl> + +</div> + <!-- ======================================================================= --> <h3> <a name="latemco">Late Machine Code Optimizations</a> @@ -2165,7 +2286,7 @@ is the key:</p> <td class="yes"></td> <!-- PowerPC --> <td class="unknown"></td> <!-- Sparc --> <td class="unknown"></td> <!-- SystemZ --> - <td class="yes"><a href="#feat_inlineasm_x86">*</a></td> <!-- X86 --> + <td class="yes"></td> <!-- X86 --> <td class="unknown"></td> <!-- XCore --> </tr> @@ -2261,9 +2382,6 @@ disassembling machine opcode bytes into MCInst's.</p> <p>This box indicates whether the target supports most popular inline assembly constraints and modifiers.</p> -<p id="feat_inlineasm_x86">X86 lacks reliable support for inline assembly -constraints relating to the X86 floating point stack.</p> - </div> <!-- _______________________________________________________________________ --> @@ -2794,6 +2912,70 @@ MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory </div> +<!-- ======================================================================= --> +<h3> + <a name="ptx">The PTX backend</a> +</h3> + +<div> + +<p>The PTX code generator lives in the lib/Target/PTX directory. It is + currently a work-in-progress, but already supports most of the code + generation functionality needed to generate correct PTX kernels for + CUDA devices.</p> + +<p>The code generator can target PTX 2.0+, and shader model 1.0+. The + PTX ISA Reference Manual is used as the primary source of ISA + information, though an effort is made to make the output of the code + generator match the output of the NVidia nvcc compiler, whenever + possible.</p> + +<p>Code Generator Options:</p> +<table border="1" cellspacing="0"> + <tr> + <th>Option</th> + <th>Description</th> + </tr> + <tr> + <td><code>double</code></td> + <td align="left">If enabled, the map_f64_to_f32 directive is + disabled in the PTX output, allowing native double-precision + arithmetic</td> + </tr> + <tr> + <td><code>no-fma</code></td> + <td align="left">Disable generation of Fused-Multiply Add + instructions, which may be beneficial for some devices</td> + </tr> + <tr> + <td><code>smxy / computexy</code></td> + <td align="left">Set shader model/compute capability to x.y, + e.g. sm20 or compute13</td> + </tr> +</table> + +<p>Working:</p> +<ul> + <li>Arithmetic instruction selection (including combo FMA)</li> + <li>Bitwise instruction selection</li> + <li>Control-flow instruction selection</li> + <li>Function calls (only on SM 2.0+ and no return arguments)</li> + <li>Addresses spaces (0 = global, 1 = constant, 2 = local, 4 = + shared)</li> + <li>Thread synchronization (bar.sync)</li> + <li>Special register reads ([N]TID, [N]CTAID, PMx, CLOCK, etc.)</li> +</ul> + +<p>In Progress:</p> +<ul> + <li>Robust call instruction selection</li> + <li>Stack frame allocation</li> + <li>Device-specific instruction scheduling optimizations</li> +</ul> + + +</div> + </div> <!-- *********************************************************************** --> @@ -2806,7 +2988,7 @@ MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-05-23 00:28:47 +0200 (Mon, 23 May 2011) $ + Last modified: $Date: 2011-09-19 20:15:46 +0200 (Mon, 19 Sep 2011) $ </address> </body> diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 139bbdb..3153a6e 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -854,8 +854,12 @@ rules:</p> <ul> <li><p><b>Type names</b> (including classes, structs, enums, typedefs, etc) - should be nouns and start with an upper-case letter (e.g. - <tt>TextFileReader</tt>).</p></li> + should be nouns and start with an upper-case letter (e.g. + <tt>TextFileReader</tt>).</p></li> + +<li><p><b>Variable names</b> should be nouns (as they represent state). The + name should be camel case, and start with an upper case letter (e.g. + <tt>Leader</tt> or <tt>Boats</tt>).</p></li> <li><p><b>Function names</b> should be verb phrases (as they represent actions), and command-like function should be imperative. The name should @@ -1522,7 +1526,7 @@ something.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-08-12 21:49:16 +0200 (Fri, 12 Aug 2011) $ </address> </body> diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index cb5438f..3e4e220 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -69,9 +69,6 @@ options) arguments to the tool you are interested in.</p> <li><a href="/cmds/llvm-config.html"><b>llvm-config</b></a> - print out LLVM compilation options, libraries, etc. as configured</li> -<li><a href="/cmds/llvmc.html"><b>llvmc</b></a> - - a generic customizable compiler driver</li> - <li><a href="/cmds/llvm-diff.html"><b>llvm-diff</b></a> - structurally compare two modules</li> @@ -81,25 +78,6 @@ options) arguments to the tool you are interested in.</p> <!-- *********************************************************************** --> <h2> - <a name="frontend">C and C++ Front-end Commands</a> -</h2> -<!-- *********************************************************************** --> - -<div> -<ul> - -<li><a href="/cmds/llvmgcc.html"><b>llvm-gcc</b></a> - - GCC-based C front-end for LLVM - -<li><a href="/cmds/llvmgxx.html"><b>llvm-g++</b></a> - - GCC-based C++ front-end for LLVM</li> - -</ul> - -</div> - -<!-- *********************************************************************** --> -<h2> <a name="debug">Debugging Tools</a> </h2> <!-- *********************************************************************** --> @@ -151,7 +129,7 @@ options) arguments to the tool you are interested in.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-09-20 20:24:04 +0200 (Tue, 20 Sep 2011) $ </address> </body> diff --git a/docs/CommandGuide/llvm-extract.pod b/docs/CommandGuide/llvm-extract.pod index 797e79d..67f00f0 100644 --- a/docs/CommandGuide/llvm-extract.pod +++ b/docs/CommandGuide/llvm-extract.pod @@ -37,11 +37,23 @@ B<llvm-extract> will write raw bitcode regardless of the output device. Extract the function named I<function-name> from the LLVM bitcode. May be specified multiple times to extract multiple functions at once. +=item B<--rfunc> I<function-regular-expr> + +Extract the function(s) matching I<function-regular-expr> from the LLVM bitcode. +All functions matching the regular expression will be extracted. May be +specified multiple times. + =item B<--glob> I<global-name> Extract the global variable named I<global-name> from the LLVM bitcode. May be specified multiple times to extract multiple global variables at once. +=item B<--rglob> I<glob-regular-expr> + +Extract the global variable(s) matching I<global-regular-expr> from the LLVM +bitcode. All global variables matching the regular expression will be extracted. +May be specified multiple times. + =item B<-help> Print a summary of command line options. diff --git a/docs/CommandGuide/llvmc.pod b/docs/CommandGuide/llvmc.pod deleted file mode 100644 index 95a9e5e..0000000 --- a/docs/CommandGuide/llvmc.pod +++ /dev/null @@ -1,190 +0,0 @@ -=pod - -=head1 NAME - -llvmc - The LLVM Compiler Driver (WIP) - -=head1 SYNOPSIS - -B<llvmc> [I<options>] I<filenames...> - -=head1 DESCRIPTION - -B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools -in order to compile, optimize and link software for multiple languages. For -those familiar with FSF's B<gcc> tool, it is very similar. Please note that -B<llvmc> is considered an experimental tool. - -=head1 OPTIONS - -=head2 Built-in Options - -LLVMC has some built-in options that can't be overridden in the -configuration libraries. - -=over - -=item B<-o> I<filename> - -Output file name. - -=item B<-x> I<language> - -Specify the language of the following input files until the next B<-x> -option. - -=item B<-load> I<plugin_name> - -Load the specified plugin DLL. Example: -S<-load $LLVM_DIR/Release/lib/LLVMCSimple.so>. - -=item B<-v> or B<--verbose> - -Enable verbose mode, i.e. print out all executed commands. - -=item B<--check-graph> - -Check the compilation for common errors like mismatched output/input language -names, multiple default edges and cycles. Because of plugins, these checks can't -be performed at compile-time. Exit with code zero if no errors were found, and -return the number of found errors otherwise. Hidden option, useful for debugging -LLVMC plugins. - -=item B<--view-graph> - -Show a graphical representation of the compilation graph and exit. Requires that -you have I<dot> and I<gv> programs installed. Hidden option, useful for -debugging LLVMC plugins. - -=item B<--write-graph> - -Write a I<compilation-graph.dot> file in the current directory with the -compilation graph description in Graphviz format (identical to the file used by -the B<--view-graph> option). The B<-o> option can be used to set the output file -name. Hidden option, useful for debugging LLVMC plugins. - -=item B<--save-temps> - -Write temporary files to the current directory and do not delete them on -exit. This option can also take an argument: the I<--save-temps=obj> switch will -write files into the directory specified with the I<-o> option. The -I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the -default behaviour. - -=item B<--temp-dir> I<directory> - -Store temporary files in the given directory. This directory is deleted on exit -unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified, -I<--temp-dir> is given the precedence. - -=item B<-help> - -Print a summary of command-line options and exit. - -=item B<-help-hidden> - -Print a summary of command-line options and exit. Print help even for -options intended for developers. - -=item B<--version> - -Print version information and exit. - -=item B<@>I<file> - -Read command-line options from I<file>. The options read are inserted -in place of the original @I<file> option. If I<file> does not exist, or -cannot be read, then the option will be treated literally, and not -removed. - -Options in I<file> are separated by whitespace. A whitespace character -may be included in an option by surrounding the entire option in -either single or double quotes. Any character (including a backslash) -may be included by prefixing the character to be included with a -backslash. The file may itself contain additional @I<file> options; -any such options will be processed recursively. - - -=back - - -=head2 Control Options - -By default, LLVMC is built with some standard configuration libraries -that define the following options: - -=over - -=item B<-clang> - -Use Clang instead of llvm-gcc. - -=item B<-opt> - -Enable optimization passes with B<opt>. To pass options to the B<opt> program -use the B<-Wo,> option. - -=item B<-I> I<directory> - -Add a directory to the header file search path. - -=item B<-L> I<directory> - -Add I<directory> to the library search path. - -=item B<-F> I<directory> - -Add I<directory> to the framework search path. - -=item B<-l>I<name> - -Link in the library libI<name>.[bc | a | so]. This library should -be a bitcode library. - -=item B<-framework> I<name> - -Link in the library libI<name>.[bc | a | so]. This library should -be a bitcode library. - -=item B<-emit-llvm> - -Output LLVM bitcode (with B<-c>) or assembly (with B<-S>) instead of native -object (or assembly). If B<-emit-llvm> is given without either B<-c> or B<-S> -it has no effect. - -=item B<-Wa> - -Pass options to assembler. - -=item B<-Wl> - -Pass options to linker. - -=item B<-Wo> - -Pass options to opt. - -=item B<-Wllc> - -Pass options to llc (code generator). - -=back - -=head1 EXIT STATUS - -If B<llvmc> succeeds, it will exit with code 0. Otherwise, if an -error occurs, it will exit with a non-zero value. If one of the -compilation tools returns a non-zero status, pending actions will be -discarded and B<llvmc> will return the same result code as the failing -compilation tool. - -=head1 SEE ALSO - -L<llvm-gcc|llvmgcc>, L<llvm-g++|llvmgxx>, L<llvm-as|llvm-as>, -L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link> - -=head1 AUTHORS - -Maintained by the LLVM Team (L<http://llvm.org/>). - -=cut diff --git a/docs/CommandGuide/llvmgcc.pod b/docs/CommandGuide/llvmgcc.pod deleted file mode 100644 index 30af0a06e..0000000 --- a/docs/CommandGuide/llvmgcc.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -llvm-gcc - LLVM C front-end - -=head1 SYNOPSIS - -B<llvm-gcc> [I<options>] I<filename> - -=head1 DESCRIPTION - -The B<llvm-gcc> command is the LLVM C front end. It is a modified -version of gcc that compiles C/ObjC programs into native objects, LLVM -bitcode or LLVM assembly language, depending upon the options. - -By default, B<llvm-gcc> compiles to native objects just like GCC does. If the -B<-emit-llvm> and B<-c> options are given then it will generate LLVM bitcode files -instead. If B<-emit-llvm> and B<-S> are given, then it will generate LLVM -assembly. - -Being derived from the GNU Compiler Collection, B<llvm-gcc> has many -of gcc's features and accepts most of gcc's options. It handles a -number of gcc's extensions to the C programming language. See the gcc -documentation for details. - -=head1 OPTIONS - -=over - -=item B<--help> - -Print a summary of command line options. - -=item B<-o> I<filename> - -Specify the output file to be I<filename>. - -=item B<-I> I<directory> - -Add a directory to the header file search path. This option can be -repeated. - -=item B<-L> I<directory> - -Add I<directory> to the library search path. This option can be -repeated. - -=item B<-l>I<name> - -Link in the library libI<name>.[bc | a | so]. This library should -be a bitcode library. - -=item B<-emit-llvm> - -Make the output be LLVM bitcode (with B<-c>) or assembly (with B<-s>) instead -of native object (or assembly). If B<-emit-llvm> is given without either B<-c> -or B<-S> it has no effect. - -=back - -=head1 EXIT STATUS - -If B<llvm-gcc> succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value. - -=head1 SEE ALSO - -L<llvm-g++|llvmgxx> - -=head1 AUTHORS - -Maintained by the LLVM Team (L<http://llvm.org/>). - -=cut - diff --git a/docs/CommandGuide/llvmgxx.pod b/docs/CommandGuide/llvmgxx.pod deleted file mode 100644 index 1ea3d49..0000000 --- a/docs/CommandGuide/llvmgxx.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -llvm-g++ - LLVM C++ front-end - -=head1 SYNOPSIS - -B<llvm-g++> [I<options>] I<filename> - -=head1 DESCRIPTION - -The B<llvm-g++> command is the LLVM C++ front end. It is a modified -version of g++ that compiles C++/ObjC++ programs into native code, -LLVM bitcode or assembly language, depending upon the options. - -By default, B<llvm-g++> compiles to native objects just like GCC does. If the -B<-emit-llvm> option is given then it will generate LLVM bitcode files instead. -If B<-S> (assembly) is also given, then it will generate LLVM assembly. - -Being derived from the GNU Compiler Collection, B<llvm-g++> has many -of g++'s features and accepts most of g++'s options. It handles a -number of g++'s extensions to the C++ programming language. - -=head1 OPTIONS - -=over - -=item B<--help> - -Print a summary of command line options. - -=item B<-S> - -Do not generate an LLVM bitcode file. Rather, compile the source -file into an LLVM assembly language file. - -=item B<-c> - -Do not generate a linked executable. Rather, compile the source -file into an LLVM bitcode file. This bitcode file can then be -linked with other bitcode files later on to generate a full LLVM -executable. - -=item B<-o> I<filename> - -Specify the output file to be I<filename>. - -=item B<-I> I<directory> - -Add a directory to the header file search path. This option can be -repeated. - -=item B<-L> I<directory> - -Add I<directory> to the library search path. This option can be -repeated. - -=item B<-l>I<name> - -Link in the library libI<name>.[bc | a | so]. This library should -be a bitcode library. - -=item B<-emit-llvm> - -Make the output be LLVM bitcode (or assembly) instead of native object (or -assembly). - -=back - -=head1 EXIT STATUS - -If B<llvm-g++> succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value. - -=head1 SEE ALSO - -L<llvm-gcc|llvmgcc> - -=head1 AUTHORS - -Maintained by the LLVM Team (L<http://llvm.org/>). - -=cut - diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html deleted file mode 100644 index 1b2f808..0000000 --- a/docs/CompilerDriver.html +++ /dev/null @@ -1,687 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> -<title>Customizing LLVMC: Reference Manual</title> -<link rel="stylesheet" href="llvm.css" type="text/css" /> -</head> -<body> -<div class="document" id="customizing-llvmc-reference-manual"> -<h1 class="title">Customizing LLVMC: Reference Manual</h1> - -<!-- This file was automatically generated by rst2html. -Please do not edit directly! -The ReST source lives in the directory 'tools/llvmc/doc'. --> -<div class="contents topic" id="contents"> -<p class="topic-title first">Contents</p> -<ul class="simple"> -<li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li> -<li><a class="reference internal" href="#compiling-with-llvmc" id="id8">Compiling with <tt class="docutils literal">llvmc</tt></a></li> -<li><a class="reference internal" href="#predefined-options" id="id9">Predefined options</a></li> -<li><a class="reference internal" href="#compiling-llvmc-based-drivers" id="id10">Compiling LLVMC-based drivers</a></li> -<li><a class="reference internal" href="#customizing-llvmc-the-compilation-graph" id="id11">Customizing LLVMC: the compilation graph</a></li> -<li><a class="reference internal" href="#describing-options" id="id12">Describing options</a></li> -<li><a class="reference internal" href="#conditional-evaluation" id="id13">Conditional evaluation</a></li> -<li><a class="reference internal" href="#writing-a-tool-description" id="id14">Writing a tool description</a><ul> -<li><a class="reference internal" href="#id4" id="id15">Actions</a></li> -</ul> -</li> -<li><a class="reference internal" href="#language-map" id="id16">Language map</a></li> -<li><a class="reference internal" href="#option-preprocessor" id="id17">Option preprocessor</a></li> -<li><a class="reference internal" href="#more-advanced-topics" id="id18">More advanced topics</a><ul> -<li><a class="reference internal" href="#hooks-and-environment-variables" id="id19">Hooks and environment variables</a></li> -<li><a class="reference internal" href="#debugging" id="id20">Debugging</a></li> -<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id21">Conditioning on the executable name</a></li> -</ul> -</li> -</ul> -</div> -<div class="doc_author"> -<p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p> -</div><div class="section" id="introduction"> -<h1><a class="toc-backref" href="#id7">Introduction</a></h1> -<p>LLVMC is a generic compiler driver, designed to be customizable and -extensible. It plays the same role for LLVM as the <tt class="docutils literal">gcc</tt> program does for -GCC - LLVMC's job is essentially to transform a set of input files into a set of -targets depending on configuration rules and user options. What makes LLVMC -different is that these transformation rules are completely customizable - in -fact, LLVMC knows nothing about the specifics of transformation (even the -command-line options are mostly not hard-coded) and regards the transformation -structure as an abstract graph. The structure of this graph is described in -high-level TableGen code, from which an efficient C++ representation is -automatically derived. This makes it possible to adapt LLVMC for other -purposes - for example, as a build tool for game resources.</p> -<p>Because LLVMC employs <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you -need to be familiar with it to customize LLVMC.</p> -</div> -<div class="section" id="compiling-with-llvmc"> -<h1><a class="toc-backref" href="#id8">Compiling with <tt class="docutils literal">llvmc</tt></a></h1> -<p>LLVMC tries hard to be as compatible with <tt class="docutils literal">gcc</tt> as possible, -although there are some small differences. Most of the time, however, -you shouldn't be able to notice them:</p> -<pre class="literal-block"> -$ # This works as expected: -$ llvmc -O3 -Wall hello.cpp -$ ./a.out -hello -</pre> -<p>One nice feature of LLVMC is that one doesn't have to distinguish between -different compilers for different languages (think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</tt>) - the -right toolchain is chosen automatically based on input language names (which -are, in turn, determined from file extensions). If you want to force files -ending with ".c" to compile as C++, use the <tt class="docutils literal"><span class="pre">-x</span></tt> option, just like you would -do it with <tt class="docutils literal">gcc</tt>:</p> -<pre class="literal-block"> -$ # hello.c is really a C++ file -$ llvmc -x c++ hello.c -$ ./a.out -hello -</pre> -<p>On the other hand, when using LLVMC as a linker to combine several C++ -object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's -impossible for LLVMC to choose the right linker in that case:</p> -<pre class="literal-block"> -$ llvmc -c hello.cpp -$ llvmc hello.o -[A lot of link-time errors skipped] -$ llvmc --linker=c++ hello.o -$ ./a.out -hello -</pre> -<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is also -possible to choose the <tt class="docutils literal">clang</tt> compiler with the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p> -</div> -<div class="section" id="predefined-options"> -<h1><a class="toc-backref" href="#id9">Predefined options</a></h1> -<p>LLVMC has some built-in options that can't be overridden in the TableGen code:</p> -<ul class="simple"> -<li><tt class="docutils literal"><span class="pre">-o</span> FILE</tt> - Output file name.</li> -<li><tt class="docutils literal"><span class="pre">-x</span> LANGUAGE</tt> - Specify the language of the following input files -until the next -x option.</li> -<li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li> -<li><tt class="docutils literal"><span class="pre">--save-temps</span></tt> - Write temporary files to the current directory and do not -delete them on exit. This option can also take an argument: the -<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> switch will write files into the directory specified with -the <tt class="docutils literal"><span class="pre">-o</span></tt> option. The <tt class="docutils literal"><span class="pre">--save-temps=cwd</span></tt> and <tt class="docutils literal"><span class="pre">--save-temps</span></tt> switches are -both synonyms for the default behaviour.</li> -<li><tt class="docutils literal"><span class="pre">--temp-dir</span> DIRECTORY</tt> - Store temporary files in the given directory. This -directory is deleted on exit unless <tt class="docutils literal"><span class="pre">--save-temps</span></tt> is specified. If -<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> is also specified, <tt class="docutils literal"><span class="pre">--temp-dir</span></tt> is given the -precedence.</li> -<li><tt class="docutils literal"><span class="pre">--check-graph</span></tt> - Check the compilation for common errors like mismatched -output/input language names, multiple default edges and cycles. Exit with code -zero if no errors were found, and return the number of found errors -otherwise. Hidden option, useful for debugging.</li> -<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation graph -and exit. Requires that you have <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gv</tt> programs installed. Hidden -option, useful for debugging.</li> -<li><tt class="docutils literal"><span class="pre">--write-graph</span></tt> - Write a <tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt> file in the current -directory with the compilation graph description in Graphviz format (identical -to the file used by the <tt class="docutils literal"><span class="pre">--view-graph</span></tt> option). The <tt class="docutils literal"><span class="pre">-o</span></tt> option can be -used to set the output file name. Hidden option, useful for debugging.</li> -<li><tt class="docutils literal"><span class="pre">--help</span></tt>, <tt class="docutils literal"><span class="pre">--help-hidden</span></tt>, <tt class="docutils literal"><span class="pre">--version</span></tt> - These options have -their standard meaning.</li> -</ul> -</div> -<div class="section" id="compiling-llvmc-based-drivers"> -<h1><a class="toc-backref" href="#id10">Compiling LLVMC-based drivers</a></h1> -<p>It's easiest to start working on your own LLVMC driver by copying the skeleton -project which lives under <tt class="docutils literal">$LLVMC_DIR/examples/Skeleton</tt>:</p> -<pre class="literal-block"> -$ cd $LLVMC_DIR/examples -$ cp -r Skeleton MyDriver -$ cd MyDriver -$ ls -AutoGenerated.td Hooks.cpp Main.cpp Makefile -</pre> -<p>As you can see, our basic driver consists of only three files (not counting the -build script). <tt class="docutils literal">AutoGenerated.td</tt> contains TableGen description of the -compilation graph; its format is documented in the following -sections. <tt class="docutils literal">Hooks.cpp</tt> is an empty file that should be used for hook -definitions (see <a class="reference internal" href="#hooks">below</a>). <tt class="docutils literal">Main.cpp</tt> is just a helper used to compile the -auto-generated C++ code produced from TableGen source.</p> -<p>The first thing that you should do is to change the <tt class="docutils literal">LLVMC_BASED_DRIVER</tt> -variable in the <tt class="docutils literal">Makefile</tt>:</p> -<pre class="literal-block"> -LLVMC_BASED_DRIVER=MyDriver -</pre> -<p>It can also be a good idea to put your TableGen code into a file with a less -generic name:</p> -<pre class="literal-block"> -$ touch MyDriver.td -$ vim AutoGenerated.td -[...] -include "MyDriver.td" -</pre> -<p>If you have more than one TableGen source file, they all should be included from -<tt class="docutils literal">AutoGenerated.td</tt>, since this file is used by the build system to generate -C++ code.</p> -<p>To build your driver, just <tt class="docutils literal">cd</tt> to its source directory and run <tt class="docutils literal">make</tt>. The -resulting executable will be put into <tt class="docutils literal"><span class="pre">$LLVM_OBJ_DIR/$(BuildMode)/bin</span></tt>.</p> -<p>If you're compiling LLVM with different source and object directories, then you -must perform the following additional steps before running <tt class="docutils literal">make</tt>:</p> -<pre class="literal-block"> -# LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/ -# LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/ -$ mkdir $LLVMC_OBJ_DIR/examples/MyDriver/ -$ cp $LLVMC_SRC_DIR/examples/MyDriver/Makefile \ - $LLVMC_OBJ_DIR/examples/MyDriver/ -$ cd $LLVMC_OBJ_DIR/examples/MyDriver -$ make -</pre> -</div> -<div class="section" id="customizing-llvmc-the-compilation-graph"> -<h1><a class="toc-backref" href="#id11">Customizing LLVMC: the compilation graph</a></h1> -<p>Each TableGen configuration file should include the common definitions:</p> -<pre class="literal-block"> -include "llvm/CompilerDriver/Common.td" -</pre> -<p>Internally, LLVMC stores information about possible source transformations in -form of a graph. Nodes in this graph represent tools, and edges between two -nodes represent a transformation path. A special "root" node is used to mark -entry points for the transformations. LLVMC also assigns a weight to each edge -(more on this later) to choose between several alternative edges.</p> -<p>The definition of the compilation graph (see file <tt class="docutils literal">llvmc/src/Base.td</tt> for an -example) is just a list of edges:</p> -<pre class="literal-block"> -def CompilationGraph : CompilationGraph<[ - Edge<"root", "llvm_gcc_c">, - Edge<"root", "llvm_gcc_assembler">, - ... - - Edge<"llvm_gcc_c", "llc">, - Edge<"llvm_gcc_cpp", "llc">, - ... - - OptionalEdge<"llvm_gcc_c", "opt", (case (switch_on "opt"), - (inc_weight))>, - OptionalEdge<"llvm_gcc_cpp", "opt", (case (switch_on "opt"), - (inc_weight))>, - ... - - OptionalEdge<"llvm_gcc_assembler", "llvm_gcc_cpp_linker", - (case (input_languages_contain "c++"), (inc_weight), - (or (parameter_equals "linker", "g++"), - (parameter_equals "linker", "c++")), (inc_weight))>, - ... - - ]>; -</pre> -<p>As you can see, the edges can be either default or optional, where optional -edges are differentiated by an additional <tt class="docutils literal">case</tt> expression used to calculate -the weight of this edge. Notice also that we refer to tools via their names (as -strings). This makes it possible to add edges to an existing compilation graph -without having to know about all tool definitions used in the graph.</p> -<p>The default edges are assigned a weight of 1, and optional edges get a weight of -0 + 2*N where N is the number of tests that evaluated to true in the <tt class="docutils literal">case</tt> -expression. It is also possible to provide an integer parameter to -<tt class="docutils literal">inc_weight</tt> and <tt class="docutils literal">dec_weight</tt> - in this case, the weight is increased (or -decreased) by the provided value instead of the default 2. Default weight of an -optional edge can be changed by using the <tt class="docutils literal">default</tt> clause of the <tt class="docutils literal">case</tt> -construct.</p> -<p>When passing an input file through the graph, LLVMC picks the edge with the -maximum weight. To avoid ambiguity, there should be only one default edge -between two nodes (with the exception of the root node, which gets a special -treatment - there you are allowed to specify one default edge <em>per language</em>).</p> -<p>When multiple compilation graphs are defined, they are merged together. Multiple -edges with the same end nodes are not allowed (i.e. the graph is not a -multigraph), and will lead to a compile-time error.</p> -<p>To get a visual representation of the compilation graph (useful for debugging), -run <tt class="docutils literal">llvmc <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gsview</tt> installed for -this to work properly.</p> -</div> -<div class="section" id="describing-options"> -<h1><a class="toc-backref" href="#id12">Describing options</a></h1> -<p>Command-line options supported by the driver are defined by using an -<tt class="docutils literal">OptionList</tt>:</p> -<pre class="literal-block"> -def Options : OptionList<[ -(switch_option "E", (help "Help string")), -(alias_option "quiet", "q") -... -]>; -</pre> -<p>As you can see, the option list is just a list of DAGs, where each DAG is an -option description consisting of the option name and some properties. More than -one option list can be defined (they are all merged together in the end), which -can be handy if one wants to separate option groups syntactically.</p> -<ul> -<li><p class="first">Possible option types:</p> -<blockquote> -<ul class="simple"> -<li><tt class="docutils literal">switch_option</tt> - a simple boolean switch without arguments, for example -<tt class="docutils literal"><span class="pre">-O2</span></tt> or <tt class="docutils literal"><span class="pre">-time</span></tt>. At most one occurrence is allowed by default.</li> -<li><tt class="docutils literal">parameter_option</tt> - option that takes one argument, for example -<tt class="docutils literal"><span class="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality -sign: <tt class="docutils literal"><span class="pre">-std</span> c99</tt>. At most one occurrence is allowed.</li> -<li><tt class="docutils literal">parameter_list_option</tt> - same as the above, but more than one option -occurrence is allowed.</li> -<li><tt class="docutils literal">prefix_option</tt> - same as the parameter_option, but the option name and -argument do not have to be separated. Example: <tt class="docutils literal"><span class="pre">-ofile</span></tt>. This can be also -specified as <tt class="docutils literal"><span class="pre">-o</span> file</tt>; however, <tt class="docutils literal"><span class="pre">-o=file</span></tt> will be parsed incorrectly -(<tt class="docutils literal">=file</tt> will be interpreted as option value). At most one occurrence is -allowed.</li> -<li><tt class="docutils literal">prefix_list_option</tt> - same as the above, but more than one occurrence of -the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li> -<li><tt class="docutils literal">alias_option</tt> - a special option type for creating aliases. Unlike other -option types, aliases are not allowed to have any properties besides the -aliased option name. -Usage example: <tt class="docutils literal">(alias_option "preprocess", "E")</tt></li> -<li><tt class="docutils literal">switch_list_option</tt> - like <tt class="docutils literal">switch_option</tt> with the <tt class="docutils literal">zero_or_more</tt> -property, but remembers how many times the switch was turned on. Useful -mostly for forwarding. Example: when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch option (with the -<tt class="docutils literal">zero_or_more</tt> property), the command <tt class="docutils literal">driver <span class="pre">-foo</span> <span class="pre">-foo</span></tt> is forwarded -as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span></tt>, but when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch list, the same command -is forwarded as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span> <span class="pre">-foo</span></tt>.</li> -</ul> -</blockquote> -</li> -<li><p class="first">Possible option properties:</p> -<blockquote> -<ul class="simple"> -<li><tt class="docutils literal">help</tt> - help string associated with this option. Used for <tt class="docutils literal"><span class="pre">--help</span></tt> -output.</li> -<li><tt class="docutils literal">required</tt> - this option must be specified exactly once (or, in case of -the list options without the <tt class="docutils literal">multi_val</tt> property, at least -once). Incompatible with <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li> -<li><tt class="docutils literal">optional</tt> - the option can be specified either zero times or exactly -once. The default for switch options. Useful only for list options in -conjunction with <tt class="docutils literal">multi_val</tt>. Incompatible with <tt class="docutils literal">required</tt>, -<tt class="docutils literal">zero_or_more</tt> and <tt class="docutils literal">one_or_more</tt>.</li> -<li><tt class="docutils literal">one_or_more</tt> - the option must be specified at least once. Can be useful -to allow switch options be both obligatory and be specified multiple -times. For list options is useful only in conjunction with <tt class="docutils literal">multi_val</tt>; -for ordinary it is synonymous with <tt class="docutils literal">required</tt>. Incompatible with -<tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">zero_or_more</tt>.</li> -<li><tt class="docutils literal">zero_or_more</tt> - the option can be specified zero or more times. Useful -to allow a single switch option to be specified more than -once. Incompatible with <tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li> -<li><tt class="docutils literal">hidden</tt> - the description of this option will not appear in -the <tt class="docutils literal"><span class="pre">--help</span></tt> output (but will appear in the <tt class="docutils literal"><span class="pre">--help-hidden</span></tt> -output).</li> -<li><tt class="docutils literal">really_hidden</tt> - the option will not be mentioned in any help -output.</li> -<li><tt class="docutils literal">comma_separated</tt> - Indicates that any commas specified for an option's -value should be used to split the value up into multiple values for the -option. This property is valid only for list options. In conjunction with -<tt class="docutils literal">forward_value</tt> can be used to implement option forwarding in style of -gcc's <tt class="docutils literal"><span class="pre">-Wa,</span></tt>.</li> -<li><tt class="docutils literal">multi_val n</tt> - this option takes <em>n</em> arguments (can be useful in some -special cases). Usage example: <tt class="docutils literal">(parameter_list_option "foo", (multi_val -3))</tt>; the command-line syntax is '-foo a b c'. Only list options can have -this attribute; you can, however, use the <tt class="docutils literal">one_or_more</tt>, <tt class="docutils literal">optional</tt> -and <tt class="docutils literal">required</tt> properties.</li> -<li><tt class="docutils literal">init</tt> - this option has a default value, either a string (if it is a -parameter), or a boolean (if it is a switch; as in C++, boolean constants -are called <tt class="docutils literal">true</tt> and <tt class="docutils literal">false</tt>). List options can't have <tt class="docutils literal">init</tt> -attribute. -Usage examples: <tt class="docutils literal">(switch_option "foo", (init true))</tt>; <tt class="docutils literal">(prefix_option -"bar", (init <span class="pre">"baz"))</span></tt>.</li> -</ul> -</blockquote> -</li> -</ul> -</div> -<div class="section" id="conditional-evaluation"> -<span id="case"></span><h1><a class="toc-backref" href="#id13">Conditional evaluation</a></h1> -<p>The 'case' construct is the main means by which programmability is achieved in -LLVMC. It can be used to calculate edge weights, program actions and modify the -shell commands to be executed. The 'case' expression is designed after the -similarly-named construct in functional languages and takes the form <tt class="docutils literal">(case -(test_1), statement_1, (test_2), statement_2, ... (test_N), statement_N)</tt>. The -statements are evaluated only if the corresponding tests evaluate to true.</p> -<p>Examples:</p> -<pre class="literal-block"> -// Edge weight calculation - -// Increases edge weight by 5 if "-A" is provided on the -// command-line, and by 5 more if "-B" is also provided. -(case - (switch_on "A"), (inc_weight 5), - (switch_on "B"), (inc_weight 5)) - - -// Tool command line specification - -// Evaluates to "cmdline1" if the option "-A" is provided on the -// command line; to "cmdline2" if "-B" is provided; -// otherwise to "cmdline3". - -(case - (switch_on "A"), "cmdline1", - (switch_on "B"), "cmdline2", - (default), "cmdline3") -</pre> -<p>Note the slight difference in 'case' expression handling in contexts of edge -weights and command line specification - in the second example the value of the -<tt class="docutils literal">"B"</tt> switch is never checked when switch <tt class="docutils literal">"A"</tt> is enabled, and the whole -expression always evaluates to <tt class="docutils literal">"cmdline1"</tt> in that case.</p> -<p>Case expressions can also be nested, i.e. the following is legal:</p> -<pre class="literal-block"> -(case (switch_on "E"), (case (switch_on "o"), ..., (default), ...) - (default), ...) -</pre> -<p>You should, however, try to avoid doing that because it hurts readability. It is -usually better to split tool descriptions and/or use TableGen inheritance -instead.</p> -<ul class="simple"> -<li>Possible tests are:<ul> -<li><tt class="docutils literal">switch_on</tt> - Returns true if a given command-line switch is provided by -the user. Can be given multiple arguments, in that case <tt class="docutils literal">(switch_on "foo", -"bar", "baz")</tt> is equivalent to <tt class="docutils literal">(and (switch_on <span class="pre">"foo"),</span> (switch_on -<span class="pre">"bar"),</span> (switch_on <span class="pre">"baz"))</span></tt>. -Example: <tt class="docutils literal">(switch_on "opt")</tt>.</li> -<li><tt class="docutils literal">any_switch_on</tt> - Given a number of switch options, returns true if any of -the switches is turned on. -Example: <tt class="docutils literal">(any_switch_on "foo", "bar", "baz")</tt> is equivalent to <tt class="docutils literal">(or -(switch_on <span class="pre">"foo"),</span> (switch_on <span class="pre">"bar"),</span> (switch_on <span class="pre">"baz"))</span></tt>.</li> -<li><tt class="docutils literal">parameter_equals</tt> - Returns true if a command-line parameter (first -argument) equals a given value (second argument). -Example: <tt class="docutils literal">(parameter_equals "W", "all")</tt>.</li> -<li><tt class="docutils literal">element_in_list</tt> - Returns true if a command-line parameter list (first -argument) contains a given value (second argument). -Example: <tt class="docutils literal">(element_in_list "l", "pthread")</tt>.</li> -<li><tt class="docutils literal">input_languages_contain</tt> - Returns true if a given language -belongs to the current input language set. -Example: <tt class="docutils literal">(input_languages_contain <span class="pre">"c++")</span></tt>.</li> -<li><tt class="docutils literal">in_language</tt> - Evaluates to true if the input file language is equal to -the argument. At the moment works only with <tt class="docutils literal">command</tt> and <tt class="docutils literal">actions</tt> (on -non-join nodes). -Example: <tt class="docutils literal">(in_language <span class="pre">"c++")</span></tt>.</li> -<li><tt class="docutils literal">not_empty</tt> - Returns true if a given option (which should be either a -parameter or a parameter list) is set by the user. Like <tt class="docutils literal">switch_on</tt>, can -be also given multiple arguments. -Examples: <tt class="docutils literal">(not_empty "o")</tt>, <tt class="docutils literal">(not_empty "o", "l")</tt>.</li> -<li><tt class="docutils literal">any_not_empty</tt> - Returns true if <tt class="docutils literal">not_empty</tt> returns true for any of -the provided options. -Example: <tt class="docutils literal">(any_not_empty "foo", "bar", "baz")</tt> is equivalent to <tt class="docutils literal">(or -(not_empty <span class="pre">"foo"),</span> (not_empty <span class="pre">"bar"),</span> (not_empty <span class="pre">"baz"))</span></tt>.</li> -<li><tt class="docutils literal">empty</tt> - The opposite of <tt class="docutils literal">not_empty</tt>. Equivalent to <tt class="docutils literal">(not (not_empty -X))</tt>. Can be given multiple arguments.</li> -<li><tt class="docutils literal">any_not_empty</tt> - Returns true if <tt class="docutils literal">not_empty</tt> returns true for any of -the provided options. -Example: <tt class="docutils literal">(any_empty "foo", "bar", "baz")</tt> is equivalent to <tt class="docutils literal">(or -(not_empty <span class="pre">"foo"),</span> (not_empty <span class="pre">"bar"),</span> (not_empty <span class="pre">"baz"))</span></tt>.</li> -<li><tt class="docutils literal">single_input_file</tt> - Returns true if there was only one input file -provided on the command-line. Used without arguments: -<tt class="docutils literal">(single_input_file)</tt>.</li> -<li><tt class="docutils literal">multiple_input_files</tt> - Equivalent to <tt class="docutils literal">(not (single_input_file))</tt> (the -case of zero input files is considered an error).</li> -<li><tt class="docutils literal">default</tt> - Always evaluates to true. Should always be the last -test in the <tt class="docutils literal">case</tt> expression.</li> -<li><tt class="docutils literal">and</tt> - A standard logical combinator that returns true iff all of -its arguments return true. Used like this: <tt class="docutils literal">(and (test1), (test2), -... (testN))</tt>. Nesting of <tt class="docutils literal">and</tt> and <tt class="docutils literal">or</tt> is allowed, but not -encouraged.</li> -<li><tt class="docutils literal">or</tt> - A logical combinator that returns true iff any of its arguments -return true. -Example: <tt class="docutils literal">(or (test1), (test2), ... (testN))</tt>.</li> -<li><tt class="docutils literal">not</tt> - Standard unary logical combinator that negates its -argument. -Example: <tt class="docutils literal">(not (or (test1), (test2), ... <span class="pre">(testN)))</span></tt>.</li> -</ul> -</li> -</ul> -</div> -<div class="section" id="writing-a-tool-description"> -<h1><a class="toc-backref" href="#id14">Writing a tool description</a></h1> -<p>As was said earlier, nodes in the compilation graph represent tools, which are -described separately. A tool definition looks like this (taken from the -<tt class="docutils literal">llvmc/src/Base.td</tt> file):</p> -<pre class="literal-block"> -def llvm_gcc_cpp : Tool<[ - (in_language "c++"), - (out_language "llvm-assembler"), - (output_suffix "bc"), - (command "llvm-g++ -c -emit-llvm"), - (sink) - ]>; -</pre> -<p>This defines a new tool called <tt class="docutils literal">llvm_gcc_cpp</tt>, which is an alias for -<tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of properties; -most of them should be self-explanatory. The <tt class="docutils literal">sink</tt> property means that this -tool should be passed all command-line options that aren't mentioned in the -option list.</p> -<p>The complete list of all currently implemented tool properties follows.</p> -<ul class="simple"> -<li>Possible tool properties:<ul> -<li><tt class="docutils literal">in_language</tt> - input language name. Can be given multiple arguments, in -case the tool supports multiple input languages. Used for typechecking and -mapping file extensions to tools.</li> -<li><tt class="docutils literal">out_language</tt> - output language name. Multiple output languages are -allowed. Used for typechecking the compilation graph.</li> -<li><tt class="docutils literal">output_suffix</tt> - output file suffix. Can also be changed dynamically, see -documentation on <a class="reference internal" href="#actions">actions</a>.</li> -</ul> -</li> -</ul> -<blockquote> -<ul class="simple"> -<li><tt class="docutils literal">command</tt> - the actual command used to run the tool. You can use output -redirection with <tt class="docutils literal">></tt>, hook invocations (<tt class="docutils literal">$CALL</tt>), environment variables -(via <tt class="docutils literal">$ENV</tt>) and the <tt class="docutils literal">case</tt> construct.</li> -<li><tt class="docutils literal">join</tt> - this tool is a "join node" in the graph, i.e. it gets a list of -input files and joins them together. Used for linkers.</li> -<li><tt class="docutils literal">sink</tt> - all command-line options that are not handled by other tools are -passed to this tool.</li> -<li><tt class="docutils literal">actions</tt> - A single big <tt class="docutils literal">case</tt> expression that specifies how this tool -reacts on command-line options (described in more detail <a class="reference internal" href="#actions">below</a>).</li> -</ul> -</blockquote> -<blockquote> -<ul class="simple"> -<li><tt class="docutils literal">out_file_option</tt>, <tt class="docutils literal">in_file_option</tt> - Options appended to the -<tt class="docutils literal">command</tt> string to designate output and input files. Default values are -<tt class="docutils literal"><span class="pre">"-o"</span></tt> and <tt class="docutils literal">""</tt>, respectively.</li> -</ul> -</blockquote> -<div class="section" id="id4"> -<span id="actions"></span><h2><a class="toc-backref" href="#id15">Actions</a></h2> -<p>A tool often needs to react to command-line options, and this is precisely what -the <tt class="docutils literal">actions</tt> property is for. The next example illustrates this feature:</p> -<pre class="literal-block"> -def llvm_gcc_linker : Tool<[ - (in_language "object-code"), - (out_language "executable"), - (output_suffix "out"), - (command "llvm-gcc"), - (join), - (actions (case (not_empty "L"), (forward "L"), - (not_empty "l"), (forward "l"), - (not_empty "dummy"), - [(append_cmd "-dummy1"), (append_cmd "-dummy2")]) - ]>; -</pre> -<p>The <tt class="docutils literal">actions</tt> tool property is implemented on top of the omnipresent <tt class="docutils literal">case</tt> -expression. It associates one or more different <em>actions</em> with given -conditions - in the example, the actions are <tt class="docutils literal">forward</tt>, which forwards a given -option unchanged, and <tt class="docutils literal">append_cmd</tt>, which appends a given string to the tool -execution command. Multiple actions can be associated with a single condition by -using a list of actions (used in the example to append some dummy options). The -same <tt class="docutils literal">case</tt> construct can also be used in the <tt class="docutils literal">cmd_line</tt> property to modify -the tool command line.</p> -<p>The "join" property used in the example means that this tool behaves like a -linker.</p> -<p>The list of all possible actions follows.</p> -<ul> -<li><p class="first">Possible actions:</p> -<blockquote> -<ul class="simple"> -<li><tt class="docutils literal">append_cmd</tt> - Append a string to the tool invocation command. -Example: <tt class="docutils literal">(case (switch_on <span class="pre">"pthread"),</span> (append_cmd <span class="pre">"-lpthread"))</span></tt>.</li> -<li><tt class="docutils literal">error</tt> - Exit with error. -Example: <tt class="docutils literal">(error "Mixing <span class="pre">-c</span> and <span class="pre">-S</span> is not <span class="pre">allowed!")</span></tt>.</li> -<li><tt class="docutils literal">warning</tt> - Print a warning. -Example: <tt class="docutils literal">(warning "Specifying both <span class="pre">-O1</span> and <span class="pre">-O2</span> is <span class="pre">meaningless!")</span></tt>.</li> -<li><tt class="docutils literal">forward</tt> - Forward the option unchanged. -Example: <tt class="docutils literal">(forward "Wall")</tt>.</li> -<li><tt class="docutils literal">forward_as</tt> - Change the option's name, but forward the argument -unchanged. -Example: <tt class="docutils literal">(forward_as "O0", <span class="pre">"--disable-optimization")</span></tt>.</li> -<li><tt class="docutils literal">forward_value</tt> - Forward only option's value. Cannot be used with switch -options (since they don't have values), but works fine with lists. -Example: <tt class="docutils literal">(forward_value <span class="pre">"Wa,")</span></tt>.</li> -<li><tt class="docutils literal">forward_transformed_value</tt> - As above, but applies a hook to the -option's value before forwarding (see <a class="reference internal" href="#hooks">below</a>). When -<tt class="docutils literal">forward_transformed_value</tt> is applied to a list -option, the hook must have signature -<tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::HookName</span> (const <span class="pre">std::vector<std::string>&)</span></tt>. -Example: <tt class="docutils literal">(forward_transformed_value "m", "ConvertToMAttr")</tt>.</li> -<li><tt class="docutils literal">output_suffix</tt> - Modify the output suffix of this tool. -Example: <tt class="docutils literal">(output_suffix "i")</tt>.</li> -<li><tt class="docutils literal">stop_compilation</tt> - Stop compilation after this tool processes its -input. Used without arguments. -Example: <tt class="docutils literal">(stop_compilation)</tt>.</li> -</ul> -</blockquote> -</li> -</ul> -</div> -</div> -<div class="section" id="language-map"> -<h1><a class="toc-backref" href="#id16">Language map</a></h1> -<p>If you are adding support for a new language to LLVMC, you'll need to modify the -language map, which defines mappings from file extensions to language names. It -is used to choose the proper toolchain(s) for a given input file set. Language -map definition looks like this:</p> -<pre class="literal-block"> -def LanguageMap : LanguageMap< - [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, - LangToSuffixes<"c", ["c"]>, - ... - ]>; -</pre> -<p>For example, without those definitions the following command wouldn't work:</p> -<pre class="literal-block"> -$ llvmc hello.cpp -llvmc: Unknown suffix: cpp -</pre> -<p>The language map entries are needed only for the tools that are linked from the -root node. A tool can have multiple output languages.</p> -</div> -<div class="section" id="option-preprocessor"> -<h1><a class="toc-backref" href="#id17">Option preprocessor</a></h1> -<p>It is sometimes useful to run error-checking code before processing the -compilation graph. For example, if optimization options "-O1" and "-O2" are -implemented as switches, we might want to output a warning if the user invokes -the driver with both of these options enabled.</p> -<p>The <tt class="docutils literal">OptionPreprocessor</tt> feature is reserved specially for these -occasions. Example (adapted from <tt class="docutils literal">llvm/src/Base.td.in</tt>):</p> -<pre class="literal-block"> -def Preprocess : OptionPreprocessor< -(case (not (any_switch_on "O0", "O1", "O2", "O3")), - (set_option "O2"), - (and (switch_on "O3"), (any_switch_on "O0", "O1", "O2")), - (unset_option "O0", "O1", "O2"), - (and (switch_on "O2"), (any_switch_on "O0", "O1")), - (unset_option "O0", "O1"), - (and (switch_on "O1"), (switch_on "O0")), - (unset_option "O0")) ->; -</pre> -<p>Here, <tt class="docutils literal">OptionPreprocessor</tt> is used to unset all spurious <tt class="docutils literal"><span class="pre">-O</span></tt> options so -that they are not forwarded to the compiler. If no optimization options are -specified, <tt class="docutils literal"><span class="pre">-O2</span></tt> is enabled.</p> -<p><tt class="docutils literal">OptionPreprocessor</tt> is basically a single big <tt class="docutils literal">case</tt> expression, which is -evaluated only once right after the driver is started. The only allowed actions -in <tt class="docutils literal">OptionPreprocessor</tt> are <tt class="docutils literal">error</tt>, <tt class="docutils literal">warning</tt>, and two special actions: -<tt class="docutils literal">unset_option</tt> and <tt class="docutils literal">set_option</tt>. As their names suggest, they can be used to -set or unset a given option. To set an option with <tt class="docutils literal">set_option</tt>, use the -two-argument form: <tt class="docutils literal">(set_option "parameter", VALUE)</tt>. Here, <tt class="docutils literal">VALUE</tt> can be -either a string, a string list, or a boolean constant.</p> -<p>For convenience, <tt class="docutils literal">set_option</tt> and <tt class="docutils literal">unset_option</tt> also work with multiple -arguments. That is, instead of <tt class="docutils literal">[(unset_option <span class="pre">"A"),</span> (unset_option <span class="pre">"B")]</span></tt> you -can use <tt class="docutils literal">(unset_option "A", "B")</tt>. Obviously, <tt class="docutils literal">(set_option "A", "B")</tt> is -only valid if both <tt class="docutils literal">A</tt> and <tt class="docutils literal">B</tt> are switches.</p> -</div> -<div class="section" id="more-advanced-topics"> -<h1><a class="toc-backref" href="#id18">More advanced topics</a></h1> -<div class="section" id="hooks-and-environment-variables"> -<span id="hooks"></span><h2><a class="toc-backref" href="#id19">Hooks and environment variables</a></h2> -<p>Normally, LLVMC searches for programs in the system <tt class="docutils literal">PATH</tt>. Sometimes, this is -not sufficient: for example, we may want to specify tool paths or names in the -configuration file. This can be achieved via the hooks mechanism. To write your -own hooks, add their definitions to the <tt class="docutils literal">Hooks.cpp</tt> or drop a <tt class="docutils literal">.cpp</tt> file -into your driver directory. Hooks should live in the <tt class="docutils literal">hooks</tt> namespace and -have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span> ([const char* Arg0 [ const -char* Arg2 [, <span class="pre">...]]])</span></tt>. They can be used from the <tt class="docutils literal">command</tt> tool property:</p> -<pre class="literal-block"> -(command "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)") -</pre> -<p>To pass arguments to hooks, use the following syntax:</p> -<pre class="literal-block"> -(command "$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2") -</pre> -<p>It is also possible to use environment variables in the same manner:</p> -<pre class="literal-block"> -(command "$ENV(VAR1)/path/to/file -o $ENV(VAR2)") -</pre> -<p>To change the command line string based on user-provided options use -the <tt class="docutils literal">case</tt> expression (documented <a class="reference internal" href="#case">above</a>):</p> -<pre class="literal-block"> -(command - (case - (switch_on "E"), - "llvm-g++ -E -x c $INFILE -o $OUTFILE", - (default), - "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) -</pre> -</div> -<div class="section" id="debugging"> -<h2><a class="toc-backref" href="#id20">Debugging</a></h2> -<p>When writing LLVMC-based drivers, it can be useful to get a visual view of the -resulting compilation graph. This can be achieved via the command line option -<tt class="docutils literal"><span class="pre">--view-graph</span></tt> (which assumes that <a class="reference external" href="http://www.graphviz.org/">Graphviz</a> and <a class="reference external" href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are -installed). There is also a <tt class="docutils literal"><span class="pre">--write-graph</span></tt> option that creates a Graphviz -source file (<tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt>) in the current directory.</p> -<p>Another useful <tt class="docutils literal">llvmc</tt> option is <tt class="docutils literal"><span class="pre">--check-graph</span></tt>. It checks the compilation -graph for common errors like mismatched output/input language names, multiple -default edges and cycles. When invoked with <tt class="docutils literal"><span class="pre">--check-graph</span></tt>, <tt class="docutils literal">llvmc</tt> doesn't -perform any compilation tasks and returns the number of encountered errors as -its status code. In the future, these checks will be performed at compile-time -and this option will disappear.</p> -</div> -<div class="section" id="conditioning-on-the-executable-name"> -<h2><a class="toc-backref" href="#id21">Conditioning on the executable name</a></h2> -<p>For now, the executable name (the value passed to the driver in <tt class="docutils literal">argv[0]</tt>) is -accessible only in the C++ code (i.e. hooks). Use the following code:</p> -<pre class="literal-block"> -namespace llvmc { -extern const char* ProgramName; -} - -namespace hooks { - -std::string MyHook() { -//... -if (strcmp(ProgramName, "mydriver") == 0) { - //... - -} - -} // end namespace hooks -</pre> -<p>In general, you're encouraged not to make the behaviour dependent on the -executable file name, and use command-line switches instead. See for example how -the <tt class="docutils literal">llvmc</tt> program behaves when it needs to choose the correct linker options -(think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</tt>).</p> -<hr /> -<address> -<a href="http://jigsaw.w3.org/css-validator/check/referer"> -<img src="http://jigsaw.w3.org/css-validator/images/vcss-blue" - alt="Valid CSS" /></a> -<a href="http://validator.w3.org/check?uri=referer"> -<img src="http://www.w3.org/Icons/valid-xhtml10-blue" - alt="Valid XHTML 1.0 Transitional"/></a> - -<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br /> -<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br /> - -Last modified: $Date: 2011-05-07 00:11:29 +0200 (Sat, 07 May 2011) $ -</address></div> -</div> -</div> -</body> -</html> diff --git a/docs/CompilerDriverTutorial.html b/docs/CompilerDriverTutorial.html deleted file mode 100644 index 4ed373a..0000000 --- a/docs/CompilerDriverTutorial.html +++ /dev/null @@ -1,125 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> -<title>Tutorial - Using LLVMC</title> -<link rel="stylesheet" href="llvm.css" type="text/css" /> -</head> -<body> -<div class="document" id="tutorial-using-llvmc"> -<h1 class="title">Tutorial - Using LLVMC</h1> - -<!-- This file was automatically generated by rst2html. -Please do not edit directly! -The ReST source lives in the directory 'tools/llvmc/doc'. --> -<div class="contents topic" id="contents"> -<p class="topic-title first">Contents</p> -<ul class="simple"> -<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> -<li><a class="reference internal" href="#using-the-llvmc-program" id="id2">Using the <tt class="docutils literal">llvmc</tt> program</a></li> -<li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></li> -</ul> -</div> -<div class="doc_author"> -<p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p> -</div><div class="section" id="introduction"> -<h1><a class="toc-backref" href="#id1">Introduction</a></h1> -<p>LLVMC is a generic compiler driver, which plays the same role for LLVM as the -<tt class="docutils literal">gcc</tt> program does for GCC - the difference being that LLVMC is designed to be -more adaptable and easier to customize. Most of LLVMC functionality is -implemented via high-level TableGen code, from which a corresponding C++ source -file is automatically generated. This tutorial describes the basic usage and -configuration of LLVMC.</p> -</div> -<div class="section" id="using-the-llvmc-program"> -<h1><a class="toc-backref" href="#id2">Using the <tt class="docutils literal">llvmc</tt> program</a></h1> -<p>In general, <tt class="docutils literal">llvmc</tt> tries to be command-line compatible with <tt class="docutils literal">gcc</tt> as much -as possible, so most of the familiar options work:</p> -<pre class="literal-block"> -$ llvmc -O3 -Wall hello.cpp -$ ./a.out -hello -</pre> -<p>This will invoke <tt class="docutils literal"><span class="pre">llvm-g++</span></tt> under the hood (you can see which commands are -executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on command-line LLVMC -usage, refer to the <tt class="docutils literal">llvmc <span class="pre">--help</span></tt> output.</p> -</div> -<div class="section" id="using-llvmc-to-generate-toolchain-drivers"> -<h1><a class="toc-backref" href="#id3">Using LLVMC to generate toolchain drivers</a></h1> -<p>LLVMC-based drivers are written mostly using <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a>, so you need to be -familiar with it to get anything done.</p> -<p>Start by compiling <tt class="docutils literal">example/Simple</tt>, which is a primitive wrapper for -<tt class="docutils literal">gcc</tt>:</p> -<pre class="literal-block"> -$ cd $LLVM_OBJ_DIR/tools/examples/Simple -$ make -$ cat > hello.c -#include <stdio.h> -int main() { printf("Hello\n"); } -$ $LLVM_BIN_DIR/Simple -v hello.c -gcc hello.c -o hello.out -$ ./hello.out -Hello -</pre> -<p>We have thus produced a simple driver called, appropriately, <tt class="docutils literal">Simple</tt>, from -the input TableGen file <tt class="docutils literal">Simple.td</tt>. The <tt class="docutils literal">llvmc</tt> program itself is generated -using a similar process (see <tt class="docutils literal">llvmc/src</tt>). Contents of the file <tt class="docutils literal">Simple.td</tt> -look like this:</p> -<pre class="literal-block"> -// Include common definitions -include "llvm/CompilerDriver/Common.td" - -// Tool descriptions -def gcc : Tool< -[(in_language "c"), - (out_language "executable"), - (output_suffix "out"), - (command "gcc"), - (sink), - - // -o is what is used by default, out_file_option here is included for - // instructive purposes. - (out_file_option "-o") -]>; - -// Language map -def LanguageMap : LanguageMap<[(lang_to_suffixes "c", "c")]>; - -// Compilation graph -def CompilationGraph : CompilationGraph<[(edge "root", "gcc")]>; -</pre> -<p>As you can see, this file consists of three parts: tool descriptions, language -map, and the compilation graph definition.</p> -<p>At the heart of LLVMC is the idea of a compilation graph: vertices in this graph -are tools, and edges represent a transformation path between two tools (for -example, assembly source produced by the compiler can be transformed into -executable code by an assembler). The compilation graph is basically a list of -edges; a special node named <tt class="docutils literal">root</tt> is used to mark graph entry points.</p> -<p>Tool descriptions are represented as property lists: most properties in the -example above should be self-explanatory; the <tt class="docutils literal">sink</tt> property means that all -options lacking an explicit description should be forwarded to this tool.</p> -<p>The <tt class="docutils literal">LanguageMap</tt> associates a language name with a list of suffixes and is -used for deciding which toolchain corresponds to a given input file.</p> -<p>To learn more about writing your own drivers with LLVMC, refer to the reference -manual and examples in the <tt class="docutils literal">examples</tt> directory. Of a particular interest is -the <tt class="docutils literal">Skeleton</tt> example, which can serve as a template for your LLVMC-based -drivers.</p> -<hr /> -<address> -<a href="http://jigsaw.w3.org/css-validator/check/referer"> -<img src="http://jigsaw.w3.org/css-validator/images/vcss-blue" - alt="Valid CSS" /></a> -<a href="http://validator.w3.org/check?uri=referer"> -<img src="http://www.w3.org/Icons/valid-xhtml10-blue" - alt="Valid XHTML 1.0 Transitional"/></a> - -<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br /> -<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br /> - -Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $ -</address></div> -</div> -</body> -</html> diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index c121657..7c78016 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -207,7 +207,11 @@ <li><b>Chris Lattner</b>: Everything not covered by someone else.</li> - <li><b>Duncan Sands</b>: llvm-gcc 4.2.</li> + <li><b>John McCall</b>: Clang LLVM IR generation.</li> + + <li><b>Jakob Olesen</b>: Register allocators and TableGen.</li> + + <li><b>Duncan Sands</b>: dragonegg and llvm-gcc 4.2.</li> </ol> <p>Note that code ownership is completely different than reviewers: anyone can @@ -492,8 +496,9 @@ <div> <p>This section addresses the issues of copyright, license and patents for the - LLVM project. Currently, the University of Illinois is the LLVM copyright - holder and the terms of its license to LLVM users and developers is the + LLVM project. The copyright holder for the code is held by the individual + contributors of the code and the terms of its license to LLVM users and + developers is the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>.</p> @@ -611,7 +616,7 @@ Written by the <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-07 19:26:38 +0200 (Fri, 07 Oct 2011) $ </address> </body> </html> diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html index c0f50e3..85ab796 100644 --- a/docs/ExceptionHandling.html +++ b/docs/ExceptionHandling.html @@ -33,9 +33,6 @@ </ol></li> <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a> <ol> - <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a></li> - <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a></li> - <li><a href="#llvm_eh_resume"><tt>llvm.eh.resume</tt></a></li> <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li> <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> @@ -48,7 +45,6 @@ <li><a href="#unwind_tables">Exception Handling Frame</a></li> <li><a href="#exception_tables">Exception Tables</a></li> </ol></li> - <li><a href="#todo">ToDo</a></li> </ul> </td> </tr></table> @@ -69,7 +65,7 @@ handling information takes, which is useful for those interested in creating front-ends or dealing directly with the information. Further, this document provides specific examples of what exception handling information is used for - in C/C++.</p> + in C and C++.</p> <!-- ======================================================================= --> <h3> @@ -96,8 +92,8 @@ Exception Handling</a>. A description of the exception frame format can be found at <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception - Frames</a>, with details of the DWARF 3 specification at - <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 Standard</a>. + Frames</a>, with details of the DWARF 4 specification at + <a href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>. A description for the C++ exception table formats can be found at <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling Tables</a>.</p> @@ -116,10 +112,10 @@ <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>For each function which does exception processing — be + it <tt>try</tt>/<tt>catch</tt> blocks or cleanups — that function + registers itself on a global frame list. When exceptions are unwinding, 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 @@ -134,6 +130,7 @@ exceptions are thrown. As exceptions are, by their nature, intended for uncommon code paths, DWARF exception handling is generally preferred to SJLJ.</p> + </div> <!-- ======================================================================= --> @@ -148,19 +145,19 @@ <p>The runtime first attempts to find an <i>exception frame</i> corresponding to the function where the exception was thrown. If the programming language - (e.g. C++) supports exception handling, the exception frame contains a + supports exception handling (e.g. C++), the exception frame contains a reference to an exception table describing how to process the exception. If - the language (e.g. C) does not support exception handling, or if the + the language does not support exception handling (e.g. C), or if the exception needs to be forwarded to a prior activation, the exception frame contains information about how to unwind the current activation and restore the state of the prior activation. This process is repeated until the - exception is handled. If the exception is not handled and no activations + exception is handled. If the exception is not handled and no activations remain, then the application is terminated with an appropriate error message.</p> <p>Because different programming languages have different behaviors when handling exceptions, the exception handling ABI provides a mechanism for - supplying <i>personalities.</i> An exception handling personality is defined + supplying <i>personalities</i>. An exception handling personality is defined by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt> in C++), which receives the context of the exception, an <i>exception structure</i> containing the exception object type and value, and a reference @@ -168,19 +165,20 @@ for the current compile unit is specified in a <i>common exception frame</i>.</p> -<p>The organization of an exception table is language dependent. For C++, an +<p>The organization of an exception table is language dependent. For C++, an exception table is organized as a series of code ranges defining what to do - if an exception occurs in that range. Typically, the information associated + if an exception occurs in that range. Typically, the information associated with a range defines which types of exception objects (using C++ <i>type info</i>) that are handled in that range, and an associated action that - should take place. Actions typically pass control to a <i>landing + should take place. Actions typically pass control to a <i>landing pad</i>.</p> -<p>A landing pad corresponds to the code found in the <i>catch</i> portion of - a <i>try</i>/<i>catch</i> sequence. When execution resumes at a landing - pad, it receives the exception structure and a selector corresponding to - the <i>type</i> of exception thrown. The selector is then used to determine - which <i>catch</i> should actually process the exception.</p> +<p>A landing pad corresponds roughly to the code found in the <tt>catch</tt> + portion of a <tt>try</tt>/<tt>catch</tt> sequence. When execution resumes at + a landing pad, it receives an <i>exception structure</i> and a + <i>selector value</i> corresponding to the <i>type</i> of exception + thrown. The selector is then used to determine which <i>catch</i> should + actually process the exception.</p> </div> @@ -193,11 +191,8 @@ <div> -<p>At the time of this writing, only C++ exception handling support is available - in LLVM. So the remainder of this document will be somewhat C++-centric.</p> - -<p>From the C++ developers perspective, exceptions are defined in terms of the - <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section +<p>From a C++ developer's perspective, exceptions are defined in terms of the + <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section we will describe the implementation of LLVM exception handling in terms of C++ examples.</p> @@ -209,17 +204,22 @@ <div> <p>Languages that support exception handling typically provide a <tt>throw</tt> - operation to initiate the exception process. Internally, a throw operation - breaks down into two steps. First, a request is made to allocate exception - space for an exception structure. This structure needs to survive beyond the - current activation. This structure will contain the type and value of the - object being thrown. Second, a call is made to the runtime to raise the - exception, passing the exception structure as an argument.</p> - -<p>In C++, the allocation of the exception structure is done by - the <tt>__cxa_allocate_exception</tt> runtime function. The exception - raising is handled by <tt>__cxa_throw</tt>. The type of the exception is - represented using a C++ RTTI structure.</p> + operation to initiate the exception process. Internally, a <tt>throw</tt> + operation breaks down into two steps.</p> + +<ol> + <li>A request is made to allocate exception space for an exception structure. + This structure needs to survive beyond the current activation. This + structure will contain the type and value of the object being thrown.</li> + + <li>A call is made to the runtime to raise the exception, passing the + exception structure as an argument.</li> +</ol> + +<p>In C++, the allocation of the exception structure is done by the + <tt>__cxa_allocate_exception</tt> runtime function. The exception raising is + handled by <tt>__cxa_throw</tt>. The type of the exception is represented + using a C++ RTTI structure.</p> </div> @@ -231,81 +231,68 @@ <div> <p>A call within the scope of a <i>try</i> statement can potentially raise an - exception. In those circumstances, the LLVM C++ front-end replaces the call - with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has - two potential continuation points: where to continue when the call succeeds - as per normal; and where to continue if the call raises an exception, either - by a throw or the unwinding of a throw.</p> + exception. In those circumstances, the LLVM C++ front-end replaces the call + with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has + two potential continuation points:</p> + +<ol> + <li>where to continue when the call succeeds as per normal, and</li> + + <li>where to continue if the call raises an exception, either by a throw or + the unwinding of a throw</li> +</ol> <p>The term used to define a the place where an <tt>invoke</tt> continues after - an exception is called a <i>landing pad</i>. LLVM landing pads are + an exception is called a <i>landing pad</i>. LLVM landing pads are conceptually alternative function entry points where an exception structure - reference and a type info index are passed in as arguments. The landing pad + reference and a type info index are passed in as arguments. The landing pad saves the exception structure reference and then proceeds to select the catch block that corresponds to the type info of the exception object.</p> -<p>Two LLVM intrinsic functions are used to convey information about the landing - pad to the back end.</p> - -<ol> - <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no - arguments and returns a pointer to the exception structure. This only - returns a sensible value if called after an <tt>invoke</tt> has branched - to a landing pad. Due to code generation limitations, it must currently - be called in the landing pad itself.</li> - - <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum - of three arguments. The first argument is the reference to the exception - structure. The second argument is a reference to the personality function - to be used for this <tt>try</tt>/<tt>catch</tt> sequence. Each of the - remaining arguments is either a reference to the type info for - a <tt>catch</tt> statement, a <a href="#throw_filters">filter</a> - expression, or the number zero (<tt>0</tt>) representing - a <a href="#cleanups">cleanup</a>. The exception is tested against the - arguments sequentially from first to last. The result of - the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a - positive number if the exception matched a type info, a negative number if - it matched a filter, and zero if it matched a cleanup. If nothing is - matched, the behaviour of the program - is <a href="#restrictions">undefined</a>. This only returns a sensible - value if called after an <tt>invoke</tt> has branched to a landing pad. - Due to codegen limitations, it must currently be called in the landing pad - itself. If a type info matched, then the selector value is the index of - the type info in the exception table, which can be obtained using the - <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> - intrinsic.</li> -</ol> +<p>The LLVM <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> + instruction</a> is used to convey information about the landing pad to the + back end. For C++, the <tt>landingpad</tt> instruction returns a pointer and + integer pair corresponding to the pointer to the <i>exception structure</i> + and the <i>selector value</i> respectively.</p> + +<p>The <tt>landingpad</tt> instruction takes a reference to the personality + function to be used for this <tt>try</tt>/<tt>catch</tt> sequence. The + remainder of the instruction is a list of <i>cleanup</i>, <i>catch</i>, + and <i>filter</i> clauses. The exception is tested against the clauses + sequentially from first to last. The selector value is a positive number if + the exception matched a type info, a negative number if it matched a filter, + and zero if it matched a cleanup. If nothing is matched, the behavior of + the program is <a href="#restrictions">undefined</a>. If a type info matched, + then the selector value is the index of the type info in the exception table, + which can be obtained using the + <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> <p>Once the landing pad has the type info selector, the code branches to the - code for the first catch. The catch then checks the value of the type info + code for the first catch. The catch then checks the value of the type info selector against the index of type info for that catch. Since the type info - index is not known until all the type info have been gathered in the backend, - the catch code will call the - <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic - to determine the index for a given type info. If the catch fails to match - the selector then control is passed on to the next catch. Note: Since the - landing pad will not be used if there is no match in the list of type info on - the call to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then - neither the last catch nor <i>catch all</i> need to perform the check - against the selector.</p> - -<p>Finally, the entry and exit of catch code is bracketed with calls - to <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p> + index is not known until all the type infos have been gathered in the + backend, the catch code must call the + <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to + determine the index for a given type info. If the catch fails to match the + selector then control is passed on to the next catch.</p> + +<p>Finally, the entry and exit of catch code is bracketed with calls to + <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p> <ul> - <li><tt>__cxa_begin_catch</tt> takes a exception structure reference as an + <li><tt>__cxa_begin_catch</tt> takes an exception structure reference as an argument and returns the value of the exception object.</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 + <li>Removes the exception from the <i>caught</i> 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 + <p><b>Note:</b> a rethrow from within the catch may replace this call with a <tt>__cxa_rethrow</tt>.</p></li> </ul> @@ -318,28 +305,26 @@ <div> -<p>A cleanup is extra code which needs to be run as part of unwinding - a scope. C++ destructors are a prominent example, but other - languages and language extensions provide a variety of different - kinds of cleanup. In general, a landing pad may need to run - arbitrary amounts of cleanup code before actually entering a catch - block. To indicate the presence of cleanups, a landing pad's call - to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> should - end with the argument <tt>i32 0</tt>; otherwise, the unwinder will - not stop at the landing pad if there are no catches or filters that - require it to.</p> - -<p>Do not allow a new exception to propagate out of the execution of a - cleanup. This can corrupt the internal state of the unwinder. - Different languages describe different high-level semantics for - these situations: for example, C++ requires that the process be - terminated, whereas Ada cancels both exceptions and throws a third.</p> - -<p>When all cleanups have completed, if the exception is not handled - by the current function, resume unwinding by calling the - <a href="#llvm_eh_resume"><tt>llvm.eh.resume</tt></a> intrinsic, - passing in the results of <tt>llvm.eh.exception</tt> and - <tt>llvm.eh.selector</tt> for the original landing pad.</p> +<p>A cleanup is extra code which needs to be run as part of unwinding a scope. + C++ destructors are a typical example, but other languages and language + extensions provide a variety of different kinds of cleanups. In general, a + landing pad may need to run arbitrary amounts of cleanup code before actually + entering a catch block. To indicate the presence of cleanups, a + <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> + should have a <i>cleanup</i> clause. Otherwise, the unwinder will not stop at + the landing pad if there are no catches or filters that require it to.</p> + +<p><b>Note:</b> Do not allow a new exception to propagate out of the execution + of a cleanup. This can corrupt the internal state of the unwinder. + Different languages describe different high-level semantics for these + situations: for example, C++ requires that the process be terminated, whereas + Ada cancels both exceptions and throws a third.</p> + +<p>When all cleanups are finished, if the exception is not handled by the + current function, resume unwinding by calling the + <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a>, passing in + the result of the <tt>landingpad</tt> instruction for the original landing + pad.</p> </div> @@ -350,23 +335,21 @@ <div> -<p>C++ allows the specification of which exception types can be thrown from a - function. To represent this a top level landing pad may exist to filter out - invalid types. To express this in LLVM code the landing pad will - call <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The - arguments are a reference to the exception structure, a reference to the - personality function, the length of the filter expression (the number of type - infos plus one), followed by the type infos themselves. - <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> will return a - negative value if the exception does not match any of the type infos. If no - match is found then a call to <tt>__cxa_call_unexpected</tt> should be made, - otherwise <tt>_Unwind_Resume</tt>. Each of these functions requires a - reference to the exception structure. Note that the most general form of an - <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> call can contain - any number of type infos, filter expressions and cleanups (though having more - than one cleanup is pointless). The LLVM C++ front-end can generate such - <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls due to - inlining creating nested exception handling scopes.</p> +<p>C++ allows the specification of which exception types may be thrown from a + function. To represent this, a top level landing pad may exist to filter out + invalid types. To express this in LLVM code the + <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> will + have a filter clause. The clause consists of an array of type infos. + <tt>landingpad</tt> will return a negative value if the exception does not + match any of the type infos. If no match is found then a call + to <tt>__cxa_call_unexpected</tt> should be made, otherwise + <tt>_Unwind_Resume</tt>. Each of these functions requires a reference to the + exception structure. Note that the most general form of a + <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> can + have any number of catch, cleanup, and filter clauses (though having more + than one cleanup is pointless). The LLVM C++ front-end can generate such + <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instructions</a> due + to inlining creating nested exception handling scopes.</p> </div> @@ -377,29 +360,23 @@ <div> -<p>The unwinder delegates the decision of whether to stop in a call - frame to that call frame's language-specific personality function. - Not all personalities functions guarantee that they will stop to - perform cleanups: for example, the GNU C++ personality doesn't do - so unless the exception is actually caught somewhere further up the - stack. When using this personality to implement EH for a language - that guarantees that cleanups will always be run, be sure to - indicate a catch-all in the - <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> call - rather than just cleanups.</p> - -<p>In order for inlining to behave correctly, landing pads must be - prepared to handle selector results that they did not originally - advertise. Suppose that a function catches exceptions of - type <tt>A</tt>, and it's inlined into a function that catches - exceptions of type <tt>B</tt>. The inliner will update the - selector for the inlined landing pad to include the fact - that <tt>B</tt> is caught. If that landing pad assumes that it - will only be entered to catch an <tt>A</tt>, it's in for a rude - surprise. Consequently, landing pads must test for the selector - results they understand and then resume exception propagation - with the <a href="#llvm_eh_resume"><tt>llvm.eh.resume</tt></a> - intrinsic if none of the conditions match.</p> +<p>The unwinder delegates the decision of whether to stop in a call frame to + that call frame's language-specific personality function. Not all unwinders + guarantee that they will stop to perform cleanups. For example, the GNU C++ + unwinder doesn't do so unless the exception is actually caught somewhere + further up the stack.</p> + +<p>In order for inlining to behave correctly, landing pads must be prepared to + handle selector results that they did not originally advertise. Suppose that + a function catches exceptions of type <tt>A</tt>, and it's inlined into a + function that catches exceptions of type <tt>B</tt>. The inliner will update + the <tt>landingpad</tt> instruction for the inlined landing pad to include + the fact that <tt>B</tt> is also caught. If that landing pad assumes that it + will only be entered to catch an <tt>A</tt>, it's in for a rude awakening. + Consequently, landing pads must test for the selector results they understand + and then resume exception propagation with the + <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a> if none of + the conditions match.</p> </div> @@ -412,109 +389,28 @@ <div> -<p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to +<p>In addition to the + <a href="LangRef.html#i_landingpad"><tt>landingpad</tt></a> and + <a href="LangRef.html#i_resume"><tt>resume</tt></a> instructions, LLVM uses + several intrinsic functions (name prefixed with <i><tt>llvm.eh</tt></i>) to provide exception handling information at various points in generated code.</p> <!-- ======================================================================= --> <h4> - <a name="llvm_eh_exception">llvm.eh.exception</a> -</h4> - -<div> - -<pre> - i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>() -</pre> - -<p>This intrinsic returns a pointer to the exception structure.</p> - -</div> - -<!-- ======================================================================= --> -<h4> - <a name="llvm_eh_selector">llvm.eh.selector</a> -</h4> - -<div> - -<pre> - 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, - filters and cleanups.</p> - -<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a - minimum of three arguments. The first argument is the reference to - the exception structure. The second argument is a reference to the - personality function to be used for this try catch sequence. Each - of the remaining arguments is either a reference to the type info - for a catch statement, a <a href="#throw_filters">filter</a> - expression, or the number zero representing - a <a href="#cleanups">cleanup</a>. The exception is tested against - the arguments sequentially from first to last. The result of - the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a - positive number if the exception matched a type info, a negative - number if it matched a filter, and zero if it matched a cleanup. - If nothing is matched, or if only a cleanup is matched, different - personality functions may or may not cause control to stop at the - landing pad; see <a href="#restrictions">the restrictions</a> for - more information. If a type info matched then the selector value - is the index of the type info in the exception table, which can be - obtained using the - <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> - -<p>If a landing pad containing a call to <tt>llvm.eh.selector</tt> is - inlined into an <tt>invoke</tt> instruction, the selector arguments - for the outer landing pad are appended to those of the inlined - landing pad. Consequently, landing pads must be written to ignore - selector values that they did not originally advertise.</p> - -</div> - -<!-- ======================================================================= --> -<h4> <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a> </h4> <div> <pre> - i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*) + i32 @llvm.eh.typeid.for(i8* %type_info) </pre> <p>This intrinsic returns the type info index in the exception table of the current function. This value can be used to compare against the result - of <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single - argument is a reference to a type info.</p> - -</div> - -<!-- ======================================================================= --> -<h4> - <a name="llvm_eh_resume">llvm.eh.resume</a> -</h4> - -<div> - -<pre> - void %<a href="#llvm_eh_resume">llvm.eh.resume</a>(i8*, i32) noreturn -</pre> - -<p>This intrinsic is used to resume propagation of an exception after - landing at a landing pad. The first argument should be the result - of <a href="#llvm_eh_exception">llvm.eh.exception</a> for that - landing pad, and the second argument should be the result of - <a href="#llvm_eh_selector">llvm.eh.selector</a>. When a call to - this intrinsic is inlined into an invoke, the call is transformed - into a branch to the invoke's unwind destination, using its - arguments in place of the calls - to <a href="#llvm_eh_exception">llvm.eh.exception</a> and - <a href="#llvm_eh_selector">llvm.eh.selector</a> there.</p> - -<p>This intrinsic is not implicitly <tt>nounwind</tt>; calls to it - will always throw. It may not be invoked.</p> + of <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>. + The single argument is a reference to a type info.</p> </div> @@ -526,16 +422,16 @@ <div> <pre> - i32 %<a href="#llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>(i8*) + i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf) </pre> -<p>The SJLJ exception handling uses this intrinsic to force register saving for - the current function and to store the address of the following instruction - for use as a destination address by <a href="#llvm_eh_sjlj_longjmp"> - <tt>llvm.eh.sjlj.longjmp</tt></a>. The buffer format and the overall - functioning of this intrinsic is compatible with the GCC - <tt>__builtin_setjmp</tt> implementation, allowing code built with the - two compilers to interoperate.</p> +<p>For SJLJ based exception handling, this intrinsic forces register saving for + the current function and stores the address of the following instruction for + use as a destination address + by <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>. The + buffer format and the overall functioning of this intrinsic is compatible + with the GCC <tt>__builtin_setjmp</tt> implementation allowing code built + with the clang and GCC to interoperate.</p> <p>The single parameter is a pointer to a five word buffer in which the calling context is saved. The front end places the frame pointer in the first word, @@ -555,16 +451,15 @@ <div> <pre> - void %<a href="#llvm_eh_sjlj_longjmp">llvm.eh.sjlj.setjmp</a>(i8*) + void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf) </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 transferred to the - destination address.</p> +<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.longjmp</tt> + intrinsic is used to implement <tt>__builtin_longjmp()</tt>. 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 + transferred to the destination address.</p> </div> <!-- ======================================================================= --> @@ -575,14 +470,13 @@ <div> <pre> - i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>() + i8* @llvm.eh.sjlj.lsda() </pre> -<p>Used for SJLJ based exception handling, the <a href="#llvm_eh_sjlj_lsda"> - <tt>llvm.eh.sjlj.lsda</tt></a> intrinsic returns the address of the Language - Specific Data Area (LSDA) for the current function. The SJLJ front-end code - stores this address in the exception handling function context for use by the - runtime.</p> +<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.lsda</tt> intrinsic + returns the address of the Language Specific Data Area (LSDA) for the current + function. The SJLJ front-end code stores this address in the exception + handling function context for use by the runtime.</p> </div> @@ -594,13 +488,13 @@ <div> <pre> - void %<a href="#llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>(i32) + void @llvm.eh.sjlj.callsite(i32 %call_site_num) </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> +<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.callsite</tt> + intrinsic identifies the callsite value associated with the + following <tt>invoke</tt> instruction. This is used to ensure that landing + pad entries in the LSDA are generated in matching order.</p> </div> @@ -612,12 +506,12 @@ <div> <pre> - void %<a href="#llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>(i32) + void @llvm.eh.sjlj.dispatchsetup(i32 %dispatch_value) </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> +<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.dispatchsetup</tt> + intrinsic is used by targets to do any unwind edge setup they need. By + default, no action is taken.</p> </div> @@ -631,7 +525,7 @@ <div> <p>There are two tables that are used by the exception handling runtime to - determine which actions should take place when an exception is thrown.</p> + determine which actions should be taken when an exception is thrown.</p> <!-- ======================================================================= --> <h3> @@ -641,13 +535,13 @@ <div> <p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind - frame used by dwarf debug info. The frame contains all the information + frame used by DWARF debug info. The frame contains all the information necessary to tear down the current frame and restore the state of the prior - frame. There is an exception handling frame for each function in a compile + frame. There is an exception handling frame for each function in a compile unit, plus a common exception handling frame that defines information common to all functions in the unit.</p> -<p>Todo - Table details here.</p> +<!-- Todo - Table details here. --> </div> @@ -659,31 +553,17 @@ <div> <p>An exception table contains information about what actions to take when an - exception is thrown in a particular part of a function's code. There is one - exception table per function except leaf routines and functions that have - only calls to non-throwing functions will not need an exception table.</p> + exception is thrown in a particular part of a function's code. There is one + exception table per function, except leaf functions and functions that have + calls only to non-throwing functions. They do not need an exception + table.</p> -<p>Todo - Table details here.</p> +<!-- Todo - Table details here. --> </div> </div> -<!-- ======================================================================= --> -<h2> - <a name="todo">ToDo</a> -</h2> - -<div> - -<ol> - - <li>Testing/Testing/Testing.</li> - -</ol> - -</div> - <!-- *********************************************************************** --> <hr> @@ -695,7 +575,7 @@ <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-05-28 09:45:59 +0200 (Sat, 28 May 2011) $ + Last modified: $Date: 2011-09-27 22:16:57 +0200 (Tue, 27 Sep 2011) $ </address> </body> diff --git a/docs/FAQ.html b/docs/FAQ.html index 20ba1d5..341f1c9 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -72,9 +72,6 @@ <li>After Subversion update, rebuilding gives the error "No rule to make target".</li> - <li><a href="#llvmc">The <tt>llvmc</tt> program gives me errors/doesn't - work.</a></li> - <li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it fails. Why?</a></li> </ol></li> @@ -420,16 +417,6 @@ Stop. </div> <div class="question"> -<p><a name="llvmc">The <tt>llvmc</tt> program gives me errors/doesn't - work.</a></p> -</div> - -<div class="answer"> -<p><tt>llvmc</tt> is experimental and isn't really supported. We suggest - using <tt>llvm-gcc</tt> instead.</p> -</div> - -<div class="question"> <p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it fails. Why?</a></p> </div> @@ -540,10 +527,7 @@ Stop. <p>Currently, there isn't much. LLVM supports an intermediate representation which is useful for code representation but will not support the high level (abstract syntax tree) representation needed by most compilers. There are no - facilities for lexical nor semantic analysis. There is, however, a <i>mostly - implemented</i> configuration-driven - <a href="CompilerDriver.html">compiler driver</a> which simplifies the task - of running optimizations, linking, and executable generation.</p> + facilities for lexical nor semantic analysis.</p> </div> <div class="question"> @@ -933,7 +917,7 @@ F.i: src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-19 01:59:50 +0200 (Tue, 19 Apr 2011) $ + Last modified: $Date: 2011-09-20 02:42:28 +0200 (Tue, 20 Sep 2011) $ </address> </body> diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index 13a3714..10bc663 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -290,10 +290,8 @@ doing so is very simple. (This code is heavily commented to help you understand the data structure, but there are only 20 lines of meaningful code.)</p> -</div> - -<div class="doc_code"><pre ->/// @brief The map for a single function's stack frame. One of these is +<pre class="doc_code"> +/// @brief The map for a single function's stack frame. One of these is /// compiled as constant data into the executable for each function. /// /// Storage of metadata values is elided if the %metadata parameter to @@ -338,7 +336,9 @@ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) { for (unsigned e = R->Map->NumRoots; i != e; ++i) Visitor(&R->Roots[i], NULL); } -}</pre></div> +}</pre> + +</div> <!-- ======================================================================= --> <h3> @@ -395,12 +395,12 @@ program.</p> <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a> </h3> +<div> + <div class="doc_code"><tt> define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ... </tt></div> -<div> - <p>The <tt>gc</tt> function attribute is used to specify the desired GC style to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of <tt>Function</tt>.</p> @@ -420,12 +420,12 @@ programs that use different garbage collection algorithms (or none at all).</p> <a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a> </h3> +<div> + <div class="doc_code"><tt> void @llvm.gcroot(i8** %ptrloc, i8* %metadata) </tt></div> -<div> - <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack variable references an object on the heap and is to be tracked for garbage collection. The exact impact on generated code is specified by a <a @@ -453,7 +453,7 @@ the stack frame.</p> <p>Consider the following fragment of Java code:</p> -<pre> +<pre class="doc_code"> { Object X; // A null-initialized reference to an object ... @@ -463,7 +463,7 @@ the stack frame.</p> <p>This block (which may be located in the middle of a function or in a loop nest), could be compiled to this LLVM code:</p> -<pre> +<pre class="doc_code"> Entry: ;; In the entry block for the function, allocate the ;; stack space for X, which is an LLVM pointer. @@ -537,12 +537,12 @@ are used.</p> <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a> </h4> +<div> + <div class="doc_code"><tt> void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived) </tt></div> -<div> - <p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic function. It has exactly the same semantics as a non-volatile <tt>store</tt> to the derived pointer (the third argument). The exact code generated is specified @@ -559,12 +559,12 @@ implement reference counting.</p> <a name="gcread">Read barrier: <tt>llvm.gcread</tt></a> </h4> +<div> + <div class="doc_code"><tt> i8* @llvm.gcread(i8* %object, i8** %derived)<br> </tt></div> -<div> - <p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function. It has exactly the same semantics as a non-volatile <tt>load</tt> from the derived pointer (the second argument). The exact code generated is specified by @@ -1379,7 +1379,7 @@ Fergus Henderson. International Symposium on Memory Management 2002.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-08-12 08:17:17 +0200 (Fri, 12 Aug 2011) $ </address> </body> diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index cc5c59e..e198e02 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -441,13 +441,13 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <tr> <td><a href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a></td> - <td>2.60</td> + <td>2.61</td> <td>Configuration script builder<sup><a href="#sf4">4</a></sup></td> </tr> <tr> <td><a href="http://www.gnu.org/software/automake/">GNU Automake</a></td> - <td>1.9.6</td> + <td>1.10</td> <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td> </tr> @@ -471,8 +471,8 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <li><a name="sf3">Only needed if you want to run the automated test suite in the <tt>llvm/test</tt> directory.</a></li> <li><a name="sf4">If you want to make changes to the configure scripts, - you will need GNU autoconf (2.60), and consequently, GNU M4 (version 1.4 - or higher). You will also need automake (1.9.6). We only use aclocal + you will need GNU autoconf (2.61), and consequently, GNU M4 (version 1.4 + or higher). You will also need automake (1.10). We only use aclocal from that package.</a></li> </ol> </div> @@ -747,6 +747,7 @@ revision), you can checkout it from the '<tt>tags</tt>' directory (instead of subdirectories of the '<tt>tags</tt>' directory:</p> <ul> +<li>Release 3.0: <b>RELEASE_30/final</b></li> <li>Release 2.9: <b>RELEASE_29/final</b></li> <li>Release 2.8: <b>RELEASE_28</b></li> <li>Release 2.7: <b>RELEASE_27</b></li> @@ -802,12 +803,152 @@ instructions</a> to successfully get and build the LLVM GCC front-end.</p> now mirrors reflect only <tt>trunk</tt> for each project. You can do the read-only GIT clone of LLVM via:</p> -<pre> -% git clone http://llvm.org/git/llvm.git +<pre class="doc_code"> +git clone http://llvm.org/git/llvm.git +</pre> + +<p>If you want to check out clang too, run:</p> + +<pre class="doc_code"> +git clone http://llvm.org/git/llvm.git +cd llvm/tools +git clone http://llvm.org/git/clang.git +</pre> + +<p> +Since the upstream repository is in Subversion, you should use +<tt>"git pull --rebase"</tt> +instead of <tt>"git pull"</tt> to avoid generating a non-linear +history in your clone. +To configure <tt>"git pull"</tt> to pass <tt>--rebase</tt> by default +on the master branch, run the following command: +</p> + +<pre class="doc_code"> +git config branch.master.rebase true +</pre> + +<h4>Sending patches with Git</h4> +<div> +<p> +Please read <a href="DeveloperPolicy.html#patches">Developer Policy</a>, too. +</p> + +<p> +Assume <tt>master</tt> points the upstream and <tt>mybranch</tt> points your +working branch, and <tt>mybranch</tt> is rebased onto <tt>master</tt>. +At first you may check sanity of whitespaces: +</p> + +<pre class="doc_code"> +git diff --check master..mybranch +</pre> + +<p> +The easiest way to generate a patch is as below: +</p> + +<pre class="doc_code"> +git diff master..mybranch > /path/to/mybranch.diff +</pre> + +<p> +It is a little different from svn-generated diff. git-diff-generated diff has +prefixes like <tt>a/</tt> and <tt>b/</tt>. Don't worry, most developers might +know it could be accepted with <tt>patch -p1 -N</tt>. +</p> + +<p> +But you may generate patchset with git-format-patch. It generates +by-each-commit patchset. To generate patch files to attach to your article: +</p> + +<pre class="doc_code"> +git format-patch --no-attach master..mybranch -o /path/to/your/patchset +</pre> + +<p> +If you would like to send patches directly, you may use git-send-email or +git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. +</p> + +<pre class="doc_code"> +git format-patch --attach master..mybranch --stdout | git imap-send +</pre> + +<p> +Then, your .git/config should have [imap] sections. +</p> + +<pre class="doc_code"> +[imap] + host = imaps://imap.gmail.com + user = <em>your.gmail.account</em>@gmail.com + pass = <em>himitsu!</em> + port = 993 + sslverify = false +; in English + folder = "[Gmail]/Drafts" +; example for Japanese, "Modified UTF-7" encoded. + folder = "[Gmail]/&Tgtm+DBN-" </pre> </div> +<h4>For developers to work with git-svn</h4> +<div> + +<p>To set up clone from which you can submit code using + <tt>git-svn</tt>, run:</p> + +<pre class="doc_code"> +git clone http://llvm.org/git/llvm.git +cd llvm +git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username> +git config svn-remote.svn.fetch :refs/remotes/origin/master +git svn rebase -l # -l avoids fetching ahead of the git mirror. + +# If you have clang too: +cd tools +git clone http://llvm.org/git/clang.git +cd clang +git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username> +git config svn-remote.svn.fetch :refs/remotes/origin/master +git svn rebase -l +</pre> + +<p>To update this clone without generating git-svn tags that conflict +with the upstream git repo, run:</p> + +<pre class="doc_code"> +git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. +git checkout master +git svn rebase -l +(cd tools/clang && + git checkout master && + git svn rebase -l) +</pre> + +<p>This leaves your working directories on their master branches, so +you'll need to <tt>checkout</tt> each working branch individually and +<tt>rebase</tt> it on top of its parent branch. (Note: This script is +intended for relative newbies to git. If you have more experience, +you can likely improve on it.)</p> + +<p>The git-svn metadata can get out of sync after you mess around with +branches and <code>dcommit</code>. When that happens, <code>git svn +dcommit</code> stops working, complaining about files with uncommitted +changes. The fix is to rebuild the metadata:</p> + +<pre class="doc_code"> +rm -rf .git/svn +git svn rebase -l +</pre> + +</div> + +</div> + <!-- ======================================================================= --> <h3> <a name="installcf">Install the GCC Front End</a> @@ -1362,13 +1503,9 @@ different <a href="#tools">tools</a>.</p> at runtime in both interpreted and JIT compiled fashions.</dd> <dt><tt><b>llvm/lib/Support/</b></tt></dt> - <dd> This directory contains the source code that corresponds to the header - files located in <tt>llvm/include/Support/</tt>.</dd> - - <!--FIXME: obsoleted --> - <dt><tt><b>llvm/lib/System/</b></tt></dt> - <dd>This directory contains the operating system abstraction layer that - shields LLVM from platform-specific coding.</dd> + <dd> This directory contains the source code that corresponds to the header + files located in <tt>llvm/include/ADT/</tt> + and <tt>llvm/include/Support/</tt>.</dd> </dl> </div> @@ -1455,16 +1592,6 @@ information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p> href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information on using <tt>bugpoint</tt>.</dd> - <dt><tt><b>llvmc</b></tt></dt> - <dd>The LLVM Compiler Driver. This program can - be configured to utilize both LLVM and non-LLVM compilation tools to enable - pre-processing, translation, optimization, assembly, and linking of programs - all from one command line. <tt>llvmc</tt> also takes care of processing the - dependent libraries found in bitcode. This reduces the need to get the - traditional <tt>-l<name></tt> options right on the command line. Please - note that this tool, while functional, is still experimental and not feature - complete.</dd> - <dt><tt><b>llvm-ar</b></tt></dt> <dd>The archiver produces an archive containing the given LLVM bitcode files, optionally with an index for faster @@ -1480,9 +1607,9 @@ information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p> <dt><tt><b>llvm-ld</b></tt></dt> <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM. - This is the linker invoked by <tt>llvmc</tt>. It performs standard link time - optimizations and allows optimization modules to be loaded and run so that - language specific optimizations can be applied at link time.</dd> + It performs standard link time optimizations and allows optimization + modules to be loaded and run so that language specific optimizations can + be applied at link time.</dd> <dt><tt><b>llvm-link</b></tt></dt> <dd><tt>llvm-link</tt>, not surprisingly, links multiple LLVM modules into @@ -1743,7 +1870,7 @@ out:</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-17 08:31:32 +0200 (Mon, 17 Oct 2011) $ </address> </body> </html> diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index e25c457..92ba411 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -75,6 +75,7 @@ placed. <h2><a name="usage">Usage</a></h2> <!--=========================================================================--> <div> + <p>The linker takes a <tt>-plugin</tt> option that points to the path of the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt> would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look @@ -82,19 +83,21 @@ placed. <tt>ld-new -plugin /path/to/LLVMgold.so</tt> to test it out. Once you're ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt> then replace it with <tt>ld-new</tt>.</p> - <p>You can produce bitcode files from <tt>llvm-gcc</tt> using + + <p>You can produce bitcode files from <tt>clang</tt> using <tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is synonymous with <tt>-O3 -flto</tt>.</p> - <p><tt>llvm-gcc</tt> has a <tt>-use-gold-plugin</tt> option which looks - for the gold plugin in the same directories as it looks for <tt>cc1</tt> and - passes the <tt>-plugin</tt> option to ld. It will not look for an alternate + + <p><tt>Clang</tt> has a <tt>-use-gold-plugin</tt> option which looks for the + gold plugin in the same directories as it looks for <tt>cc1</tt> and passes + the <tt>-plugin</tt> option to <tt>ld</tt>. It will not look for an alternate linker, which is why you need gold to be the installed system linker in your path.</p> + <p>If you want <tt>ar</tt> and <tt>nm</tt> to work seamlessly as well, install <tt>LLVMgold.so</tt> to <tt>/usr/lib/bfd-plugins</tt>. If you built your own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to - <tt>/usr/bin</tt>. - <p> + <tt>/usr/bin</tt>.<p> <!-- ======================================================================= --> <h3> @@ -137,11 +140,12 @@ void foo4(void) { } --- command lines --- -$ llvm-gcc -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file +$ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file $ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode -$ llvm-gcc b.c -c -o b.o # <-- b.o is native object file -$ llvm-gcc -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin +$ clang b.c -c -o b.o # <-- b.o is native object file +$ clang -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin </pre> + <p>Gold informs the plugin that foo3 is never referenced outside the IR, leading LLVM to delete that function. However, unlike in the <a href="LinkTimeOptimization.html#example1">libLTO @@ -158,20 +162,21 @@ $ llvm-gcc -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin </h2> <!--=========================================================================--> <div> - <p>Once your system <tt>ld</tt>, <tt>ar</tt> and <tt>nm</tt> all support LLVM - bitcode, everything is in place for an easy to use LTO build of autotooled - projects:</p> + <p>Once your system <tt>ld</tt>, <tt>ar</tt>, and <tt>nm</tt> all support LLVM + bitcode, everything is in place for an easy to use LTO build of autotooled + projects:</p> + <ul> <li>Follow the instructions <a href="#build">on how to build LLVMgold.so</a>.</li> <li>Install the newly built binutils to <tt>$PREFIX</tt></li> <li>Copy <tt>Release/lib/LLVMgold.so</tt> to - <tt>$PREFIX/libexec/gcc/x86_64-unknown-linux-gnu/4.2.1/</tt> and - <tt>$PREFIX/lib/bfd-plugins/</tt></li> - <li>Set environment variables (<tt>$PREFIX</tt> is where you installed llvm-gcc and - binutils): - <pre class="doc_code"> -export CC="$PREFIX/bin/llvm-gcc -use-gold-plugin" -export CXX="$PREFIX/bin/llvm-g++ -use-gold-plugin" + <tt>$PREFIX/libexec/gcc/x86_64-unknown-linux-gnu/4.2.1/</tt> and + <tt>$PREFIX/lib/bfd-plugins/</tt></li> + <li>Set environment variables (<tt>$PREFIX</tt> is where you installed clang and + binutils): +<pre class="doc_code"> +export CC="$PREFIX/bin/clang -use-gold-plugin" +export CXX="$PREFIX/bin/clang++ -use-gold-plugin" export AR="$PREFIX/bin/ar" export NM="$PREFIX/bin/nm" export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a @@ -179,18 +184,22 @@ export CFLAGS="-O4" </pre> </li> <li>Or you can just set your path: - <pre class="doc_code"> +<pre class="doc_code"> export PATH="$PREFIX/bin:$PATH" -export CC="llvm-gcc -use-gold-plugin" -export CXX="llvm-g++ -use-gold-plugin" +export CC="clang -use-gold-plugin" +export CXX="clang++ -use-gold-plugin" export RANLIB=/bin/true export CFLAGS="-O4" -</pre> - </li> - <li>Configure & build the project as usual: <tt>./configure && make && make check</tt> </li> +</pre></li> + <li>Configure & build the project as usual: +<pre class="doc_code"> +% ./configure && make && make check +</pre></li> </ul> - <p> The environment variable settings may work for non-autotooled projects - too, but you may need to set the <tt>LD</tt> environment variable as well.</p> + + <p>The environment variable settings may work for non-autotooled projects + too, but you may need to set the <tt>LD</tt> environment variable as + well.</p> </div> <!--=========================================================================--> diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index f52f326..c46ed5aa 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -29,7 +29,7 @@ <div> <p>This document contains information about successfully releasing LLVM — - including subprojects: e.g., <tt>llvm-gcc</tt> and <tt>clang</tt> — to + including subprojects: e.g., <tt>clang</tt> and <tt>dragonegg</tt> — to the public. It is the Release Manager's responsibility to ensure that a high quality build of LLVM is released.</p> @@ -92,7 +92,6 @@ <ol> <li><a href="#dist">Build the LLVM Source Distributions</a></li> <li><a href="#build">Build LLVM</a></li> - <li><a href="#llvmgccbin">Build the LLVM-GCC Binary Distribution</a></li> <li><a href="#clangbin">Build the Clang Binary Distribution</a></li> <li><a href="#target-build">Target Specific Build Details</a></li> </ol> @@ -100,7 +99,6 @@ <li><a href="#release-qualify">Release Qualification Criteria</a> <ol> <li><a href="#llvm-qualify">Qualify LLVM</a></li> - <li><a href="#llvmgcc-qualify">Qualify LLVM-GCC</a></li> <li><a href="#clang-qualify">Qualify Clang</a></li> <li><a href="#targets">Specific Target Qualification Details</a></li> </ol> @@ -149,25 +147,25 @@ <li><p>Verify that the current Subversion trunk is in decent shape by examining nightly tester and buildbot results.</p></li> - <li><p>Create the release branch for <tt>llvm</tt>, <tt>llvm-gcc-4.2</tt>, - <tt>clang</tt>, and the <tt>test-suite</tt> from the last known good - revision. The branch's name is <tt>release_XY</tt>, where <tt>X</tt> is - the major and <tt>Y</tt> the minor release numbers. The branches should be - created using the following commands:</p> + <li><p>Create the release branch for <tt>llvm</tt>, <tt>clang</tt>, + the <tt>test-suite</tt>, and <tt>dragonegg</tt> from the last known good + revision. The branch's name is <tt>release_<i>XY</i></tt>, + where <tt>X</tt> is the major and <tt>Y</tt> the minor release + numbers. The branches should be created using the following commands:</p> <div class="doc_code"> <pre> $ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \ https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> -$ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \ - https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XY</i> +$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \ + https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> + +$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \ + https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> $ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> - -$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \ - https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> </pre> </div></li> @@ -182,11 +180,11 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \ <pre> $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> llvm-<i>X.Y</i> -$ svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XY</i> llvm-gcc-4.2-<i>X.Y</i> +$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-<i>X.Y</i> -$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> test-suite-<i>X.Y</i> +$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> dragonegg-<i>X.Y</i> -$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-<i>X.Y</i> +$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> test-suite-<i>X.Y</i> </pre> </div></li> </ol> @@ -214,10 +212,10 @@ $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang- <div> -<p>Create release candidates for <tt>llvm</tt>, <tt>llvm-gcc</tt>, - <tt>clang</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch with - the respective release candidate number. For instance, to create <b>Release - Candidate 1</b> you would issue the following commands:</p> +<p>Create release candidates for <tt>llvm</tt>, <tt>clang</tt>, + <tt>dragonegg</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch + with the respective release candidate number. For instance, to + create <b>Release Candidate 1</b> you would issue the following commands:</p> <div class="doc_code"> <pre> @@ -225,17 +223,17 @@ $ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i> $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> \ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1 -$ svn mkdir https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XY</i> -$ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XY</i> \ - https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XY</i>/rc1 +$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i> +$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \ + https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 + +$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i> +$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> \ + https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1 $ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i> $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> \ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 - -$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i> -$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \ - https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 </pre> </div> @@ -251,14 +249,14 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \ <div class="doc_code"> <pre> $ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1 llvm-<i>X.Y</i>rc1 -$ svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XY</i>/rc1 llvm-gcc4.2-<i>X.Y</i>rc1 -$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 llvm-test-<i>X.Y</i>rc1 $ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 clang-<i>X.Y</i>rc1 +$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1 dragonegg-<i>X.Y</i>rc1 +$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 llvm-test-<i>X.Y</i>rc1 $ tar -cvf - llvm-<i>X.Y</i>rc1 | gzip > llvm-<i>X.Y</i>rc1.src.tar.gz -$ tar -cvf - llvm-test-<i>X.Y</i>rc1 | gzip > llvm-test-<i>X.Y</i>rc1.src.tar.gz -$ tar -cvf - llvm-gcc4.2-<i>X.Y</i>rc1 | gzip > llvm-gcc-4.2-<i>X.Y</i>rc1.src.tar.gz $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.gz +$ tar -cvf - dragonegg-<i>X.Y</i>rc1 | gzip > dragonegg-<i>X.Y</i>rc1.src.tar.gz +$ tar -cvf - llvm-test-<i>X.Y</i>rc1 | gzip > llvm-test-<i>X.Y</i>rc1.src.tar.gz </pre> </div> @@ -271,7 +269,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <div> -<p>The builds of <tt>llvm</tt>, <tt>llvm-gcc</tt>, and <tt>clang</tt> +<p>The builds of <tt>llvm</tt>, <tt>clang</tt>, and <tt>dragonegg</tt> <em>must</em> be free of errors and warnings in Debug, Release+Asserts, and Release builds. If all builds are clean, then the release passes Build Qualification.</p> @@ -292,35 +290,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions of <tt>llvm</tt> on all supported platforms. Directions to build - <tt>llvm</tt> are - <a href="GettingStarted.html#quickstart">here</a>.</p> - -</div> - -<!-- ======================================================================= --> -<h4><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></h4> - -<div> - -<p>Creating the <tt>llvm-gcc</tt> binary distribution (Release/Optimized) - requires performing the following steps for each supported platform:</p> - -<ol> - <li><p>Build the <tt>llvm-gcc</tt> front-end by following the directions in - the <tt>README.LLVM</tt> file. The front-end must be compiled with C, C++, - Objective-C (Mac only), Objective-C++ (Mac only), and Fortran - support.</p></li> - - <li><p>Boostrapping must be enabled.</p></li> - - <li><p>Be sure to build with <tt>LLVM_VERSION_INFO=X.Y</tt>, where <tt>X</tt> - is the major and <tt>Y</tt> is the minor release numbers.</p></li> - - <li><p>Copy the installation directory to a directory named for the specific - target. For example on Red Hat Enterprise Linux, the directory would be - named <tt>llvm-gcc4.2-2.6-x86-linux-RHEL4</tt>. Archive and compress the - new directory.</p></li> -</ol> + <tt>llvm</tt> are <a href="GettingStarted.html#quickstart">here</a>.</p> </div> @@ -337,8 +307,8 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <li>Build clang according to the directions <a href="http://clang.llvm.org/get_started.html">here</a>.</li> - <li>Build both a debug and release version of clang. The binary will be the - release build.</lI> + <li>Build both a Debug and Release version of clang. The binary will be the + Release build.</lI> <li>Package <tt>clang</tt> (details to follow).</li> </ol> @@ -351,18 +321,18 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <div> <p>The table below specifies which compilers are used for each Arch/OS - combination when qualifying the build of <tt>llvm</tt>, <tt>llvm-gcc</tt>, - and <tt>clang</tt>.</p> + combination when qualifying the build of <tt>llvm</tt>, <tt>clang</tt>, + and <tt>dragonegg</tt>.</p> <table> - <tr><th>Architecture</th><th>OS</th><th>compiler</th></tr> - <tr><td>x86-32</td><td>Mac OS 10.5</td><td>gcc 4.0.1</td></tr> - <tr><td>x86-32</td><td>Linux</td><td>gcc 4.2.X, gcc 4.3.X</td></tr> - <tr><td>x86-32</td><td>FreeBSD</td><td>gcc 4.2.X</td></tr> - <tr><td>x86-32</td><td>mingw</td><td>gcc 3.4.5</td></tr> - <tr><td>x86-64</td><td>Mac OS 10.5</td><td>gcc 4.0.1</td></tr> - <tr><td>x86-64</td><td>Linux</td><td>gcc 4.2.X, gcc 4.3.X</td></tr> - <tr><td>x86-64</td><td>FreeBSD</td><td>gcc 4.2.X</td></tr> + <tr><th>Architecture</th> <th>OS</th> <th>compiler</th></tr> + <tr><td>x86-32</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr> + <tr><td>x86-32</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr> + <tr><td>x86-32</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr> + <tr><td>x86-32</td> <td>mingw</td> <td>gcc 3.4.5</td></tr> + <tr><td>x86-64</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr> + <tr><td>x86-64</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr> + <tr><td>x86-64</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr> </table> </div> @@ -394,21 +364,8 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <div> <p>LLVM is qualified when it has a clean test run without a front-end. And it - has no regressions when using either <tt>llvm-gcc</tt> or <tt>clang</tt> with - the <tt>test-suite</tt> from the previous release.</p> - -</div> - -<!-- ======================================================================= --> -<h4><a name="llvmgcc-qualify">Qualify LLVM-GCC</a></h4> - -<div> - -<p><tt>LLVM-GCC</tt> is qualified when front-end specific tests in the - <tt>llvm</tt> regression test suite all pass and there are no regressions in - the <tt>test-suite</tt>.</p> - -<p>We do not use the GCC DejaGNU test suite as release criteria.</p> + has no regressions when using either <tt>clang</tt> or <tt>dragonegg</tt> + with the <tt>test-suite</tt> from the previous release.</p> </div> @@ -429,13 +386,13 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <div> <table> - <tr><th>Architecture</th><th>OS</th><th>llvm-gcc baseline</th><th>clang baseline</th><th>tests</th></tr> - <tr><td>x86-32</td><td>Linux</td><td>last release</td><td>last release</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> - <tr><td>x86-32</td><td>FreeBSD</td><td>none</td><td>last release</td><td>llvm dejagnu, clang tests, test-suite</td></tr> - <tr><td>x86-32</td><td>mingw</td><td>last release</td><td>none</td><td>QT</td></tr> - <tr><td>x86-64</td><td>Mac OS 10.X</td><td>last release</td><td>last release</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> - <tr><td>x86-64</td><td>Linux</td><td>last release</td><td>last release</td><td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> - <tr><td>x86-64</td><td>FreeBSD</td><td>none</td><td>last release</td><td>llvm dejagnu, clang tests, test-suite</td></tr> + <tr><th>Architecture</th> <th>OS</th> <th>clang baseline</th> <th>tests</th></tr> + <tr><td>x86-32</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-32</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr> + <tr><td>x86-32</td> <td>mingw</td> <td>none</td> <td>QT</td></tr> + <tr><td>x86-64</td> <td>Mac OS 10.X</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-64</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr> + <tr><td>x86-64</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr> </table> </div> @@ -452,14 +409,12 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g <ol> <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the - appropriate <tt>llvm-gcc</tt> and/or <tt>clang</tt> binary. Build - LLVM. Run <tt>make check</tt> and the full LLVM test suite (<tt>make - TEST=nightly report</tt>).</li> + appropriate <tt>clang</tt> binary. Build LLVM. Run <tt>make check</tt> and + the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li> <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the - <tt>llvm-gcc</tt> and/or <tt>clang</tt> source. Compile everything. Run - <tt>make check</tt> and the full LLVM test suite (<tt>make TEST=nightly - report</tt>).</li> + <tt>clang</tt> sources. Compile everything. Run <tt>make check</tt> and + the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li> </ol> <p>Ask LLVM developers to submit the test suite report and <tt>make check</tt> @@ -538,14 +493,14 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip > clang-<i>X.Y</i>rc1.src.tar.g $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/Final -$ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XY \ - https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XY</i>/Final +$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \ + https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/Final + +$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \ + https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/Final $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/Final - -$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \ - https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/Final </pre> </div> @@ -559,7 +514,7 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \ <div> <p>The LLVM demo page must be updated to use the new release. This consists of - using the new <tt>llvm-gcc</tt> binary and building LLVM.</p> + using the new <tt>clang</tt> binary and building LLVM.</p> <!-- ======================================================================= --> <h4><a name="webupdates">Update the LLVM Website</a></h4> @@ -574,8 +529,8 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \ <li>Create a new subdirectory <tt>X.Y</tt> in the releases directory.</li> - <li>Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>llvm-gcc</tt> source, - <tt>clang source</tt>, <tt>clang binaries</tt>, and <tt>llvm-gcc</tt> + <li>Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>clang</tt> source, + <tt>clang binaries</tt>, <tt>dragonegg</tt> source, and <tt>dragonegg</tt> binaries in this new directory.</li> <li>Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt> files @@ -619,7 +574,7 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-17 22:32:14 +0200 (Mon, 17 Oct 2011) $ </address> </body> </html> diff --git a/docs/LangRef.html b/docs/LangRef.html index 8e17243..71e606d 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -35,7 +35,7 @@ <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li> <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li> <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li> - <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li> + <li><a href="#linkage_external">'<tt>external</tt>' Linkage</a></li> <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li> <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li> </ol> @@ -53,6 +53,8 @@ <li><a href="#datalayout">Data Layout</a></li> <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li> <li><a href="#volatile">Volatile Memory Accesses</a></li> + <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li> + <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li> </ol> </li> <li><a href="#typesystem">Type System</a> @@ -74,7 +76,7 @@ <ol> <li><a href="#t_array">Array Type</a></li> <li><a href="#t_struct">Structure Type</a></li> - <li><a href="#t_opaque">Opaque Type</a></li> + <li><a href="#t_opaque">Opaque Structure Types</a></li> <li><a href="#t_vector">Vector Type</a></li> </ol> </li> @@ -122,6 +124,7 @@ <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li> <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li> <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li> + <li><a href="#i_resume">'<tt>resume</tt>' Instruction</a></li> <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li> </ol> </li> @@ -166,9 +169,12 @@ </li> <li><a href="#memoryops">Memory Access and Addressing Operations</a> <ol> - <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li> - <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li> - <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li> + <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li> + <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li> + <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li> + <li><a href="#i_fence">'<tt>fence</tt>' Instruction</a></li> + <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li> + <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li> <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li> </ol> </li> @@ -196,6 +202,7 @@ <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li> <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li> <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li> + <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li> </ol> </li> </ol> @@ -268,9 +275,10 @@ </li> <li><a href="#int_debugger">Debugger intrinsics</a></li> <li><a href="#int_eh">Exception Handling intrinsics</a></li> - <li><a href="#int_trampoline">Trampoline Intrinsic</a> + <li><a href="#int_trampoline">Trampoline Intrinsics</a> <ol> <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li> + <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li> </ol> </li> <li><a href="#int_atomics">Atomic intrinsics</a> @@ -639,7 +647,7 @@ define i32 @main() { <i>; i32()* </i> be merged with equivalent globals. These linkage types are otherwise the same as their non-<tt>odr</tt> versions.</dd> - <dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt> + <dt><tt><b><a name="linkage_external">external</a></b></tt>:</dt> <dd>If none of the above identifiers are used, the global is externally visible, meaning that it participates in linkage and can be used to resolve external symbol references.</dd> @@ -672,8 +680,8 @@ define i32 @main() { <i>; i32()* </i> declarations), they are accessible outside of the current module.</p> <p>It is illegal for a function <i>declaration</i> to have any linkage type - other than "externally visible", <tt>dllimport</tt> - or <tt>extern_weak</tt>.</p> + other than <tt>external</tt>, <tt>dllimport</tt> + or <tt>extern_weak</tt>.</p> <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt> or <tt>weak_odr</tt> linkages.</p> @@ -1155,14 +1163,6 @@ define void @f() optsize { ... } function into callers whenever possible, ignoring any active inlining size threshold for this caller.</dd> - <dt><tt><b>hotpatch</b></tt></dt> - <dd>This attribute indicates that the function should be 'hotpatchable', - meaning the function can be patched and/or hooked even while it is - loaded into memory. On x86, the function prologue will be preceded - by six bytes of padding and will begin with a two-byte instruction. - Most of the functions in the Windows system DLLs in Windows XP SP2 or - higher were compiled in this fashion.</dd> - <dt><tt><b>nonlazybind</b></tt></dt> <dd>This attribute suppresses lazy symbol binding for the function. This may make calls to the function faster, at the cost of extra program @@ -1246,6 +1246,19 @@ define void @f() optsize { ... } function that doesn't have an <tt>sspreq</tt> attribute or which has an <tt>ssp</tt> attribute, then the resulting function will have an <tt>sspreq</tt> attribute.</dd> + + <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt> + <dd>This attribute indicates that the ABI being targeted requires that + an unwind table entry be produce for this function even if we can + show that no exceptions passes by it. This is normally the case for + the ELF x86-64 abi, but it can be disabled for some compilation + units.</dd> + + <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt> + <dd>This attribute indicates that this function can return + twice. The C <code>setjmp</code> is an example of such a function. + The compiler disables some optimizations (like tail calls) in the caller of + these functions.</dd> </dl> </div> @@ -1306,6 +1319,13 @@ target datalayout = "<i>layout specification</i>" the bits with the least significance have the lowest address location.</dd> + <dt><tt>S<i>size</i></tt></dt> + <dd>Specifies the natural alignment of the stack in bits. Alignment promotion + of stack variables is limited to the natural stack alignment to avoid + dynamic stack realignment. The stack alignment must be a multiple of + 8-bits. If omitted, the natural stack alignment defaults to "unspecified", + which does not prevent any alignment promotions.</dd> + <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and <i>preferred</i> alignments. All sizes are in bits. Specifying @@ -1386,6 +1406,22 @@ target datalayout = "<i>layout specification</i>" implemented in terms of 64 <2 x double>, for example.</li> </ol> +<p>The function of the data layout string may not be what you expect. Notably, + this is not a specification from the frontend of what alignment the code + generator should use.</p> + +<p>Instead, if specified, the target data layout is required to match what the + ultimate <em>code generator</em> expects. This string is used by the + mid-level optimizers to + improve code, and this only works if it matches what the ultimate code + generator uses. If you would like to generate IR that does not embed this + target-specific detail into the IR, then you don't have to specify the + string. This will disable some optimizations that require precise layout + information, but this also prevents those optimizations from introducing + target specificity into the IR.</p> + + + </div> <!-- ======================================================================= --> @@ -1470,6 +1506,185 @@ synchronization behavior.</p> </div> +<!-- ======================================================================= --> +<h3> + <a name="memmodel">Memory Model for Concurrent Operations</a> +</h3> + +<div> + +<p>The LLVM IR does not define any way to start parallel threads of execution +or to register signal handlers. Nonetheless, there are platform-specific +ways to create them, and we define LLVM IR's behavior in their presence. This +model is inspired by the C++0x memory model.</p> + +<p>For a more informal introduction to this model, see the +<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>. + +<p>We define a <i>happens-before</i> partial order as the least partial order +that</p> +<ul> + <li>Is a superset of single-thread program order, and</li> + <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from + <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced + by platform-specific techniques, like pthread locks, thread + creation, thread joining, etc., and by atomic instructions. + (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>). + </li> +</ul> + +<p>Note that program order does not introduce <i>happens-before</i> edges +between a thread and signals executing inside that thread.</p> + +<p>Every (defined) read operation (load instructions, memcpy, atomic +loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by +(defined) write operations (store instructions, atomic +stores/read-modify-writes, memcpy, etc.). For the purposes of this section, +initialized globals are considered to have a write of the initializer which is +atomic and happens before any other read or write of the memory in question. +For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see +any write to the same byte, except:</p> + +<ul> + <li>If <var>write<sub>1</sub></var> happens before + <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens + before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var> + does not see <var>write<sub>1</sub></var>. + <li>If <var>R<sub>byte</sub></var> happens before + <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not + see <var>write<sub>3</sub></var>. +</ul> + +<p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows: +<ul> + <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile + is supposed to give guarantees which can support + <code>sig_atomic_t</code> in C/C++, and may be used for accesses to + addresses which do not behave like normal memory. It does not generally + provide cross-thread synchronization.) + <li>Otherwise, if there is no write to the same byte that happens before + <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns + <tt>undef</tt> for that byte. + <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write, + <var>R<sub>byte</sub></var> returns the value written by that + write.</li> + <li>Otherwise, if <var>R</var> is atomic, and all the writes + <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the + values written. See the <a href="#ordering">Atomic Memory Ordering + Constraints</a> section for additional constraints on how the choice + is made. + <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li> +</ul> + +<p><var>R</var> returns the value composed of the series of bytes it read. +This implies that some bytes within the value may be <tt>undef</tt> +<b>without</b> the entire value being <tt>undef</tt>. Note that this only +defines the semantics of the operation; it doesn't mean that targets will +emit more than one instruction to read the series of bytes.</p> + +<p>Note that in cases where none of the atomic intrinsics are used, this model +places only one restriction on IR transformations on top of what is required +for single-threaded execution: introducing a store to a byte which might not +otherwise be stored is not allowed in general. (Specifically, in the case +where another thread might write to and read from an address, introducing a +store can change a load that may see exactly one write into a load that may +see multiple writes.)</p> + +<!-- FIXME: This model assumes all targets where concurrency is relevant have +a byte-size store which doesn't affect adjacent bytes. As far as I can tell, +none of the backends currently in the tree fall into this category; however, +there might be targets which care. If there are, we want a paragraph +like the following: + +Targets may specify that stores narrower than a certain width are not +available; on such a target, for the purposes of this model, treat any +non-atomic write with an alignment or width less than the minimum width +as if it writes to the relevant surrounding bytes. +--> + +</div> + +<!-- ======================================================================= --> +<h3> + <a name="ordering">Atomic Memory Ordering Constraints</a> +</h3> + +<div> + +<p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>, +<a href="#i_atomicrmw"><code>atomicrmw</code></a>, +<a href="#i_fence"><code>fence</code></a>, +<a href="#i_load"><code>atomic load</code></a>, and +<a href="#i_store"><code>atomic store</code></a>) take an ordering parameter +that determines which other atomic instructions on the same address they +<i>synchronize with</i>. These semantics are borrowed from Java and C++0x, +but are somewhat more colloquial. If these descriptions aren't precise enough, +check those specs (see spec references in the +<a href="Atomic.html#introduction">atomics guide</a>). +<a href="#i_fence"><code>fence</code></a> instructions +treat these orderings somewhat differently since they don't take an address. +See that instruction's documentation for details.</p> + +<p>For a simpler introduction to the ordering constraints, see the +<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p> + +<dl> +<dt><code>unordered</code></dt> +<dd>The set of values that can be read is governed by the happens-before +partial order. A value cannot be read unless some operation wrote it. +This is intended to provide a guarantee strong enough to model Java's +non-volatile shared variables. This ordering cannot be specified for +read-modify-write operations; it is not strong enough to make them atomic +in any interesting way.</dd> +<dt><code>monotonic</code></dt> +<dd>In addition to the guarantees of <code>unordered</code>, there is a single +total order for modifications by <code>monotonic</code> operations on each +address. All modification orders must be compatible with the happens-before +order. There is no guarantee that the modification orders can be combined to +a global total order for the whole program (and this often will not be +possible). The read in an atomic read-modify-write operation +(<a href="#i_cmpxchg"><code>cmpxchg</code></a> and +<a href="#i_atomicrmw"><code>atomicrmw</code></a>) +reads the value in the modification order immediately before the value it +writes. If one atomic read happens before another atomic read of the same +address, the later read must see the same value or a later value in the +address's modification order. This disallows reordering of +<code>monotonic</code> (or stronger) operations on the same address. If an +address is written <code>monotonic</code>ally by one thread, and other threads +<code>monotonic</code>ally read that address repeatedly, the other threads must +eventually see the write. This corresponds to the C++0x/C1x +<code>memory_order_relaxed</code>.</dd> +<dt><code>acquire</code></dt> +<dd>In addition to the guarantees of <code>monotonic</code>, +a <i>synchronizes-with</i> edge may be formed with a <code>release</code> +operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd> +<dt><code>release</code></dt> +<dd>In addition to the guarantees of <code>monotonic</code>, if this operation +writes a value which is subsequently read by an <code>acquire</code> operation, +it <i>synchronizes-with</i> that operation. (This isn't a complete +description; see the C++0x definition of a release sequence.) This corresponds +to the C++0x/C1x <code>memory_order_release</code>.</dd> +<dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an +<code>acquire</code> and <code>release</code> operation on its address. +This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd> +<dt><code>seq_cst</code> (sequentially consistent)</dt><dd> +<dd>In addition to the guarantees of <code>acq_rel</code> +(<code>acquire</code> for an operation which only reads, <code>release</code> +for an operation which only writes), there is a global total order on all +sequentially-consistent operations on all addresses, which is consistent with +the <i>happens-before</i> partial order and with the modification orders of +all the affected addresses. Each sequentially-consistent read sees the last +preceding write to the same address in this global order. This corresponds +to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd> +</dl> + +<p id="singlethread">If an atomic operation is marked <code>singlethread</code>, +it only <i>synchronizes with</i> or participates in modification and seq_cst +total orderings with other operations running in the same thread (for example, +in signal handlers).</p> + +</div> + </div> <!-- *********************************************************************** --> @@ -1852,20 +2067,22 @@ synchronization behavior.</p> <p>Structures may optionally be "packed" structures, which indicate that the alignment of the struct is one byte, and that there is no padding between - the elements. In non-packed structs, padding between field types is defined - by the target data string to match the underlying processor.</p> - -<p>Structures can either be "anonymous" or "named". An anonymous structure is - defined inline with other types (e.g. <tt>{i32, i32}*</tt>) and a named types - are always defined at the top level with a name. Anonmyous types are uniqued - by their contents and can never be recursive since there is no way to write - one. Named types can be recursive. + the elements. In non-packed structs, padding between field types is inserted + as defined by the TargetData string in the module, which is required to match + what the underlying code generator expects.</p> + +<p>Structures can either be "literal" or "identified". A literal structure is + defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified + types are always defined at the top level with a name. Literal types are + uniqued by their contents and can never be recursive or opaque since there is + no way to write one. Identified types can be recursive, can be opaqued, and are + never uniqued. </p> <h5>Syntax:</h5> <pre> - %T1 = type { <type list> } <i>; Named normal struct type</i> - %T2 = type <{ <type list> }> <i>; Named packed struct type</i> + %T1 = type { <type list> } <i>; Identified normal struct type</i> + %T2 = type <{ <type list> }> <i>; Identified packed struct type</i> </pre> <h5>Examples:</h5> @@ -1891,15 +2108,15 @@ synchronization behavior.</p> <!-- _______________________________________________________________________ --> <h4> - <a name="t_opaque">Opaque Type</a> + <a name="t_opaque">Opaque Structure Types</a> </h4> <div> <h5>Overview:</h5> -<p>Opaque types are used to represent named structure types that do not have a - body specified. This corresponds (for example) to the C notion of a forward - declared structure.</p> +<p>Opaque structure types are used to represent named structure types that do + not have a body specified. This corresponds (for example) to the C notion of + a forward declared structure.</p> <h5>Syntax:</h5> <pre> @@ -2006,6 +2223,8 @@ synchronization behavior.</p> </div> +</div> + <!-- *********************************************************************** --> <h2><a name="constants">Constants</a></h2> <!-- *********************************************************************** --> @@ -2361,7 +2580,7 @@ b: unreachable </ul> <p>Whenever a trap value is generated, all values which depend on it evaluate - to trap. If they have side effects, the evoke their side effects as if each + to trap. If they have side effects, they evoke their side effects as if each operand with a trap value were undef. If they have externally-visible side effects, the behavior is undefined.</p> @@ -2844,14 +3063,15 @@ should not be exposed to source languages.</p> control flow, not values (the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> -<p>There are seven different terminator instructions: the - '<a href="#i_ret"><tt>ret</tt></a>' instruction, the - '<a href="#i_br"><tt>br</tt></a>' instruction, the - '<a href="#i_switch"><tt>switch</tt></a>' instruction, the - '<a href="#i_indirectbr">'<tt>indirectbr</tt></a>' Instruction, the - '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the - '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the - '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p> +<p>The terminator instructions are: + '<a href="#i_ret"><tt>ret</tt></a>', + '<a href="#i_br"><tt>br</tt></a>', + '<a href="#i_switch"><tt>switch</tt></a>', + '<a href="#i_indirectbr"><tt>indirectbr</tt></a>', + '<a href="#i_invoke"><tt>invoke</tt></a>', + '<a href="#i_unwind"><tt>unwind</tt></a>', + '<a href="#i_resume"><tt>resume</tt></a>', and + '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p> <!-- _______________________________________________________________________ --> <h4> @@ -2912,7 +3132,8 @@ should not be exposed to source languages.</p> <h5>Syntax:</h5> <pre> - br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i> + br i1 <cond>, label <iftrue>, label <iffalse> + br label <dest> <i>; Unconditional branch</i> </pre> <h5>Overview:</h5> @@ -3072,6 +3293,17 @@ IfUnequal: instruction, control is interrupted and continued at the dynamically nearest "exception" label.</p> +<p>The '<tt>exception</tt>' label is a + <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the + exception. As such, '<tt>exception</tt>' label is required to have the + "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains + the information about about the behavior of the program after unwinding + happens, as its first non-PHI instruction. The restrictions on the + "<tt>landingpad</tt>" instruction's tightly couples it to the + "<tt>invoke</tt>" instruction, so that the important information contained + within the "<tt>landingpad</tt>" instruction can't be lost through normal + code motion.</p> + <h5>Arguments:</h5> <p>This instruction requires several arguments:</p> @@ -3170,6 +3402,40 @@ that the invoke/unwind semantics are likely to change in future versions.</p> </div> + <!-- _______________________________________________________________________ --> + +<h4> + <a name="i_resume">'<tt>resume</tt>' Instruction</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + resume <type> <value> +</pre> + +<h5>Overview:</h5> +<p>The '<tt>resume</tt>' instruction is a terminator instruction that has no + successors.</p> + +<h5>Arguments:</h5> +<p>The '<tt>resume</tt>' instruction requires one argument, which must have the + same type as the result of any '<tt>landingpad</tt>' instruction in the same + function.</p> + +<h5>Semantics:</h5> +<p>The '<tt>resume</tt>' instruction resumes propagation of an existing + (in-flight) exception whose unwinding was interrupted with + a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p> + +<h5>Example:</h5> +<pre> + resume { i8*, i32 } %exn +</pre> + +</div> + <!-- _______________________________________________________________________ --> <h4> @@ -4237,7 +4503,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* <i>; yields <aggregate type></i> + <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* <i>; yields <aggregate type></i> </pre> <h5>Overview:</h5> @@ -4342,8 +4608,8 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - <result> = load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] - <result> = volatile load <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] + <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] + <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> !<index> = !{ i32 1 } </pre> @@ -4358,6 +4624,19 @@ that the invoke/unwind semantics are likely to change in future versions.</p> number or order of execution of this <tt>load</tt> with other <a href="#volatile">volatile operations</a>.</p> +<p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra + <a href="#ordering">ordering</a> and optional <code>singlethread</code> + argument. The <code>release</code> and <code>acq_rel</code> orderings are + not valid on <code>load</code> instructions. Atomic loads produce <a + href="#memorymodel">defined</a> results when they may see multiple atomic + stores. The type of the pointee must be an integer type whose bit width + is a power of two greater than or equal to eight and less than or equal + to a target-specific size limit. <code>align</code> must be explicitly + specified on atomic loads, and the load has undefined behavior if the + alignment is not set to a value which is at least the size in bytes of + the pointee. <code>!nontemporal</code> does not have any defined semantics + for atomic loads.</p> + <p>The optional constant <tt>align</tt> argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 or an omitted <tt>align</tt> argument means that the operation has the preferential @@ -4401,8 +4680,8 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i> - volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i> + store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i> + store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i> </pre> <h5>Overview:</h5> @@ -4418,6 +4697,19 @@ that the invoke/unwind semantics are likely to change in future versions.</p> order of execution of this <tt>store</tt> with other <a href="#volatile">volatile operations</a>.</p> +<p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra + <a href="#ordering">ordering</a> and optional <code>singlethread</code> + argument. The <code>acquire</code> and <code>acq_rel</code> orderings aren't + valid on <code>store</code> instructions. Atomic loads produce <a + href="#memorymodel">defined</a> results when they may see multiple atomic + stores. The type of the pointee must be an integer type whose bit width + is a power of two greater than or equal to eight and less than or equal + to a target-specific size limit. <code>align</code> must be explicitly + specified on atomic stores, and the store has undefined behavior if the + alignment is not set to a value which is at least the size in bytes of + the pointee. <code>!nontemporal</code> does not have any defined semantics + for atomic stores.</p> + <p>The optional constant "align" argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 or an omitted "align" argument means that the operation has the preferential @@ -4456,6 +4748,215 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <!-- _______________________________________________________________________ --> <h4> +<a name="i_fence">'<tt>fence</tt>' Instruction</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + fence [singlethread] <ordering> <i>; yields {void}</i> +</pre> + +<h5>Overview:</h5> +<p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges +between operations.</p> + +<h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a +href="#ordering">ordering</a> argument which defines what +<i>synchronizes-with</i> edges they add. They can only be given +<code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and +<code>seq_cst</code> orderings.</p> + +<h5>Semantics:</h5> +<p>A fence <var>A</var> which has (at least) <code>release</code> ordering +semantics <i>synchronizes with</i> a fence <var>B</var> with (at least) +<code>acquire</code> ordering semantics if and only if there exist atomic +operations <var>X</var> and <var>Y</var>, both operating on some atomic object +<var>M</var>, such that <var>A</var> is sequenced before <var>X</var>, +<var>X</var> modifies <var>M</var> (either directly or through some side effect +of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before +<var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a +<i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather +than an explicit <code>fence</code>, one (but not both) of the atomic operations +<var>X</var> or <var>Y</var> might provide a <code>release</code> or +<code>acquire</code> (resp.) ordering constraint and still +<i>synchronize-with</i> the explicit <code>fence</code> and establish the +<i>happens-before</i> edge.</p> + +<p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to +having both <code>acquire</code> and <code>release</code> semantics specified +above, participates in the global program order of other <code>seq_cst</code> +operations and/or fences.</p> + +<p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument +specifies that the fence only synchronizes with other fences in the same +thread. (This is useful for interacting with signal handlers.)</p> + +<h5>Example:</h5> +<pre> + fence acquire <i>; yields {void}</i> + fence singlethread seq_cst <i>; yields {void}</i> +</pre> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> +<a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i> +</pre> + +<h5>Overview:</h5> +<p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory. +It loads a value in memory and compares it to a given value. If they are +equal, it stores a new value into the memory.</p> + +<h5>Arguments:</h5> +<p>There are three arguments to the '<code>cmpxchg</code>' instruction: an +address to operate on, a value to compare to the value currently be at that +address, and a new value to place at that address if the compared values are +equal. The type of '<var><cmp></var>' must be an integer type whose +bit width is a power of two greater than or equal to eight and less than +or equal to a target-specific size limit. '<var><cmp></var>' and +'<var><new></var>' must have the same type, and the type of +'<var><pointer></var>' must be a pointer to that type. If the +<code>cmpxchg</code> is marked as <code>volatile</code>, then the +optimizer is not allowed to modify the number or order of execution +of this <code>cmpxchg</code> with other <a href="#volatile">volatile +operations</a>.</p> + +<!-- FIXME: Extend allowed types. --> + +<p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this +<code>cmpxchg</code> synchronizes with other atomic operations.</p> + +<p>The optional "<code>singlethread</code>" argument declares that the +<code>cmpxchg</code> is only atomic with respect to code (usually signal +handlers) running in the same thread as the <code>cmpxchg</code>. Otherwise the +cmpxchg is atomic with respect to all other code in the system.</p> + +<p>The pointer passed into cmpxchg must have alignment greater than or equal to +the size in memory of the operand. + +<h5>Semantics:</h5> +<p>The contents of memory at the location specified by the +'<tt><pointer></tt>' operand is read and compared to +'<tt><cmp></tt>'; if the read value is the equal, +'<tt><new></tt>' is written. The original value at the location +is returned. + +<p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the +purpose of identifying <a href="#release_sequence">release sequences</a>. A +failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering +parameter determined by dropping any <code>release</code> part of the +<code>cmpxchg</code>'s ordering.</p> + +<!-- +FIXME: Is compare_exchange_weak() necessary? (Consider after we've done +optimization work on ARM.) + +FIXME: Is a weaker ordering constraint on failure helpful in practice? +--> + +<h5>Example:</h5> +<pre> +entry: + %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered <i>; yields {i32}</i> + <a href="#i_br">br</a> label %loop + +loop: + %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop] + %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp + %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared <i>; yields {i32}</i> + %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old + <a href="#i_br">br</a> i1 %success, label %done, label %loop + +done: + ... +</pre> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> +<a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i> +</pre> + +<h5>Overview:</h5> +<p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p> + +<h5>Arguments:</h5> +<p>There are three arguments to the '<code>atomicrmw</code>' instruction: an +operation to apply, an address whose value to modify, an argument to the +operation. The operation must be one of the following keywords:</p> +<ul> + <li>xchg</li> + <li>add</li> + <li>sub</li> + <li>and</li> + <li>nand</li> + <li>or</li> + <li>xor</li> + <li>max</li> + <li>min</li> + <li>umax</li> + <li>umin</li> +</ul> + +<p>The type of '<var><value></var>' must be an integer type whose +bit width is a power of two greater than or equal to eight and less than +or equal to a target-specific size limit. The type of the +'<code><pointer></code>' operand must be a pointer to that type. +If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the +optimizer is not allowed to modify the number or order of execution of this +<code>atomicrmw</code> with other <a href="#volatile">volatile + operations</a>.</p> + +<!-- FIXME: Extend allowed types. --> + +<h5>Semantics:</h5> +<p>The contents of memory at the location specified by the +'<tt><pointer></tt>' operand are atomically read, modified, and written +back. The original value at the location is returned. The modification is +specified by the <var>operation</var> argument:</p> + +<ul> + <li>xchg: <code>*ptr = val</code></li> + <li>add: <code>*ptr = *ptr + val</code></li> + <li>sub: <code>*ptr = *ptr - val</code></li> + <li>and: <code>*ptr = *ptr & val</code></li> + <li>nand: <code>*ptr = ~(*ptr & val)</code></li> + <li>or: <code>*ptr = *ptr | val</code></li> + <li>xor: <code>*ptr = *ptr ^ val</code></li> + <li>max: <code>*ptr = *ptr > val ? *ptr : val</code> (using a signed comparison)</li> + <li>min: <code>*ptr = *ptr < val ? *ptr : val</code> (using a signed comparison)</li> + <li>umax: <code>*ptr = *ptr > val ? *ptr : val</code> (using an unsigned comparison)</li> + <li>umin: <code>*ptr = *ptr < val ? *ptr : val</code> (using an unsigned comparison)</li> +</ul> + +<h5>Example:</h5> +<pre> + %old = atomicrmw add i32* %ptr, i32 1 acquire <i>; yields {i32}</i> +</pre> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a> </h4> @@ -4489,7 +4990,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> When indexing into a (optionally packed) structure, only <tt>i32</tt> integer <b>constants</b> are allowed. When indexing into an array, pointer or vector, integers of any width are allowed, and they are not required to be - constant.</p> + constant. These integers are treated as signed values where relevant.</p> <p>For example, let's consider a C code fragment and how it gets compiled to LLVM:</p> @@ -4555,18 +5056,20 @@ entry: base pointer is not an <i>in bounds</i> address of an allocated object, or if any of the addresses that would be formed by successive addition of the offsets implied by the indices to the base address with infinitely - precise arithmetic are not an <i>in bounds</i> address of that allocated - object. The <i>in bounds</i> addresses for an allocated object are all - the addresses that point into the object, plus the address one byte past - the end.</p> + precise signed arithmetic are not an <i>in bounds</i> address of that + allocated object. The <i>in bounds</i> addresses for an allocated object + are all the addresses that point into the object, plus the address one + byte past the end.</p> <p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to - the base address with silently-wrapping two's complement arithmetic, and - the result value of the <tt>getelementptr</tt> may be outside the object - pointed to by the base pointer. The result value may not necessarily be - used to access memory though, even if it happens to point into allocated - storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a> - section for more information.</p> + the base address with silently-wrapping two's complement arithmetic. If the + offsets have a different width from the pointer, they are sign-extended or + truncated to the width of the pointer. The result value of the + <tt>getelementptr</tt> may be outside the object pointed to by the base + pointer. The result value may not necessarily be used to access memory + though, even if it happens to point into allocated storage. See the + <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more + information.</p> <p>The getelementptr instruction is often confusing. For some more insight into how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p> @@ -5544,6 +6047,87 @@ freestanding environments and non-C-based languages.</p> </div> +<!-- _______________________________________________________________________ --> +<h4> + <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+ + <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>* + + <clause> := catch <type> <value> + <clause> := filter <array constant type> <array constant> +</pre> + +<h5>Overview:</h5> +<p>The '<tt>landingpad</tt>' instruction is used by + <a href="ExceptionHandling.html#overview">LLVM's exception handling + system</a> to specify that a basic block is a landing pad — one where + the exception lands, and corresponds to the code found in the + <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It + defines values supplied by the personality function (<tt>pers_fn</tt>) upon + re-entry to the function. The <tt>resultval</tt> has the + type <tt>somety</tt>.</p> + +<h5>Arguments:</h5> +<p>This instruction takes a <tt>pers_fn</tt> value. This is the personality + function associated with the unwinding mechanism. The optional + <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p> + +<p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt> + or <tt>filter</tt> — and contains the global variable representing the + "type" that may be caught or filtered respectively. Unlike the + <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as + its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot + throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em> + one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p> + +<h5>Semantics:</h5> +<p>The '<tt>landingpad</tt>' instruction defines the values which are set by the + personality function (<tt>pers_fn</tt>) upon re-entry to the function, and + therefore the "result type" of the <tt>landingpad</tt> instruction. As with + calling conventions, how the personality function results are represented in + LLVM IR is target specific.</p> + +<p>The clauses are applied in order from top to bottom. If two + <tt>landingpad</tt> instructions are merged together through inlining, the + clauses from the calling function are appended to the list of clauses.</p> + +<p>The <tt>landingpad</tt> instruction has several restrictions:</p> + +<ul> + <li>A landing pad block is a basic block which is the unwind destination of an + '<tt>invoke</tt>' instruction.</li> + <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its + first non-PHI instruction.</li> + <li>There can be only one '<tt>landingpad</tt>' instruction within the landing + pad block.</li> + <li>A basic block that is not a landing pad block may not include a + '<tt>landingpad</tt>' instruction.</li> + <li>All '<tt>landingpad</tt>' instructions in a function must have the same + personality function.</li> +</ul> + +<h5>Example:</h5> +<pre> + ;; A landing pad which can catch an integer. + %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + catch i8** @_ZTIi + ;; A landing pad that is a cleanup. + %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + cleanup + ;; A landing pad which can catch an integer and can only throw a double. + %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + catch i8** @_ZTIi + filter [1 x i8**] [@_ZTId] +</pre> + +</div> + </div> </div> @@ -5737,6 +6321,8 @@ declare void @llvm.va_end(i8*) </div> +</div> + <!-- ======================================================================= --> <h3> <a name="int_gc">Accurate Garbage Collection Intrinsics</a> @@ -7115,12 +7701,12 @@ LLVM</a>.</p> <!-- ======================================================================= --> <h3> - <a name="int_trampoline">Trampoline Intrinsic</a> + <a name="int_trampoline">Trampoline Intrinsics</a> </h3> <div> -<p>This intrinsic makes it possible to excise one parameter, marked with +<p>These intrinsics make it possible to excise one parameter, marked with the <a href="#nest"><tt>nest</tt></a> attribute, from a function. The result is a callable function pointer lacking the nest parameter - the caller does not need to @@ -7137,7 +7723,8 @@ LLVM</a>.</p> <pre class="doc_code"> %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0 - %p = call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval) + call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval) + %p = call i8* @llvm.adjust.trampoline(i8* %tramp1) %fp = bitcast i8* %p to i32 (i32, i32)* </pre> @@ -7155,12 +7742,12 @@ LLVM</a>.</p> <h5>Syntax:</h5> <pre> - declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) + declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) </pre> <h5>Overview:</h5> -<p>This fills the memory pointed to by <tt>tramp</tt> with code and returns a - function pointer suitable for executing it.</p> +<p>This fills the memory pointed to by <tt>tramp</tt> with executable code, + turning it into a trampoline.</p> <h5>Arguments:</h5> <p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all @@ -7174,17 +7761,50 @@ LLVM</a>.</p> <h5>Semantics:</h5> <p>The block of memory pointed to by <tt>tramp</tt> is filled with target - dependent code, turning it into a function. A pointer to this function is - returned, but needs to be bitcast to an <a href="#int_trampoline">appropriate - function pointer type</a> before being called. The new function's signature - is the same as that of <tt>func</tt> with any arguments marked with - the <tt>nest</tt> attribute removed. At most one such <tt>nest</tt> argument - is allowed, and it must be of pointer type. Calling the new function is - equivalent to calling <tt>func</tt> with the same argument list, but - with <tt>nval</tt> used for the missing <tt>nest</tt> argument. If, after - calling <tt>llvm.init.trampoline</tt>, the memory pointed to - by <tt>tramp</tt> is modified, then the effect of any later call to the - returned function pointer is undefined.</p> + dependent code, turning it into a function. Then <tt>tramp</tt> needs to be + passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer + which can be <a href="#int_trampoline">bitcast (to a new function) and + called</a>. The new function's signature is the same as that of + <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute + removed. At most one such <tt>nest</tt> argument is allowed, and it must be of + pointer type. Calling the new function is equivalent to calling <tt>func</tt> + with the same argument list, but with <tt>nval</tt> used for the missing + <tt>nest</tt> argument. If, after calling <tt>llvm.init.trampoline</tt>, the + memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call + to the returned function pointer is undefined.</p> +</div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="int_at"> + '<tt>llvm.adjust.trampoline</tt>' Intrinsic + </a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + declare i8* @llvm.adjust.trampoline(i8* <tramp>) +</pre> + +<h5>Overview:</h5> +<p>This performs any required machine-specific adjustment to the address of a + trampoline (passed as <tt>tramp</tt>).</p> + +<h5>Arguments:</h5> +<p><tt>tramp</tt> must point to a block of memory which already has trampoline code + filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt> + </a>.</p> + +<h5>Semantics:</h5> +<p>On some architectures the address of the code to be executed needs to be + different to the address where the trampoline is actually stored. This + intrinsic returns the executable address corresponding to <tt>tramp</tt> + after performing the required machine specific adjustments. + The pointer returned can then be <a href="#int_trampoline"> bitcast and + executed</a>. +</p> </div> @@ -7846,7 +8466,7 @@ LLVM</a>.</p> <h5>Semantics:</h5> <p>This intrinsic allows annotation of local variables with arbitrary strings. This can be useful for special purpose optimizations that want to look for - these annotations. These have no other defined use, they are ignored by code + these annotations. These have no other defined use; they are ignored by code generation and optimization.</p> </div> @@ -7882,7 +8502,7 @@ LLVM</a>.</p> <h5>Semantics:</h5> <p>This intrinsic allows annotations to be put on arbitrary expressions with arbitrary strings. This can be useful for special purpose optimizations that - want to look for these annotations. These have no other defined use, they + want to look for these annotations. These have no other defined use; they are ignored by code generation and optimization.</p> </div> @@ -7995,7 +8615,7 @@ LLVM</a>.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-07-09 19:41:24 +0200 (Sat, 09 Jul 2011) $ + Last modified: $Date: 2011-10-14 01:04:49 +0200 (Fri, 14 Oct 2011) $ </address> </body> diff --git a/docs/Lexicon.html b/docs/Lexicon.html index 449e26e..e12041d 100644 --- a/docs/Lexicon.html +++ b/docs/Lexicon.html @@ -35,6 +35,10 @@ <td><a href="#DSA">DSA</a></td> <td><a href="#DSE">DSE</a></td> </tr> + <tr><th colspan="8"><b>- <a href="#F">F</a> -</b></th></tr> + <tr> + <td><a href="#FCA">FCA</a></td> + </tr> <tr><th colspan="8"><b>- <a href="#G">G</a> -</b></th></tr> <tr> <td><a href="#GC">GC</a></td> @@ -137,6 +141,14 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd> </dl> </div> <!-- _______________________________________________________________________ --> +<h3><a name="F">- F -</a></h3> +<div> + <dl> + <dt><a name="FCA"><b>FCA</b></a></dt> + <dd>First Class Aggregate</dd> + </dl> +</div> +<!-- _______________________________________________________________________ --> <h3><a name="G">- G -</a></h3> <div> <dl> @@ -272,7 +284,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a><a href="http://llvm.org/">The LLVM Team</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> -Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ +Last modified: $Date: 2011-09-27 20:44:01 +0200 (Tue, 27 Sep 2011) $ </address> <!-- vim: sw=2 --> diff --git a/docs/LinkTimeOptimization.html b/docs/LinkTimeOptimization.html index 289da23..a1e8bba 100644 --- a/docs/LinkTimeOptimization.html +++ b/docs/LinkTimeOptimization.html @@ -79,7 +79,7 @@ conservative escape analysis. <p>The following example illustrates the advantages of LTO's integrated approach and clean interface. This example requires a system linker which supports LTO through the interface described in this document. Here, - llvm-gcc transparently invokes system linker. </p> + clang transparently invokes system linker. </p> <ul> <li> Input source file <tt>a.c</tt> is compiled into LLVM bitcode form. <li> Input source file <tt>main.c</tt> is compiled into native object code. @@ -89,27 +89,29 @@ conservative escape analysis. extern int foo1(void); extern void foo2(void); extern void foo4(void); + --- a.c --- #include "a.h" static signed int i = 0; void foo2(void) { - i = -1; + i = -1; } static int foo3() { -foo4(); -return 10; + foo4(); + return 10; } int foo1(void) { -int data = 0; + int data = 0; -if (i < 0) { data = foo3(); } + if (i < 0) + data = foo3(); -data = data + 42; -return data; + data = data + 42; + return data; } --- main.c --- @@ -117,30 +119,35 @@ return data; #include "a.h" void foo4(void) { - printf ("Hi\n"); + printf("Hi\n"); } int main() { - return foo1(); + return foo1(); } --- command lines --- -$ llvm-gcc --emit-llvm -c a.c -o a.o # <-- a.o is LLVM bitcode file -$ llvm-gcc -c main.c -o main.o # <-- main.o is native object file -$ llvm-gcc a.o main.o -o main # <-- standard link command without any modifications +$ clang -emit-llvm -c a.c -o a.o # <-- a.o is LLVM bitcode file +$ clang -c main.c -o main.o # <-- main.o is native object file +$ clang a.o main.o -o main # <-- standard link command without any modifications </pre> - <p>In this example, the linker recognizes that <tt>foo2()</tt> is an - externally visible symbol defined in LLVM bitcode file. The linker completes - its usual symbol resolution - pass and finds that <tt>foo2()</tt> is not used anywhere. This information - is used by the LLVM optimizer and it removes <tt>foo2()</tt>. As soon as - <tt>foo2()</tt> is removed, the optimizer recognizes that condition - <tt>i < 0</tt> is always false, which means <tt>foo3()</tt> is never - used. Hence, the optimizer removes <tt>foo3()</tt>, also. And this in turn, - enables linker to remove <tt>foo4()</tt>. This example illustrates the - advantage of tight integration with the linker. Here, the optimizer can not - remove <tt>foo3()</tt> without the linker's input. - </p> + +<ul> + <li>In this example, the linker recognizes that <tt>foo2()</tt> is an + externally visible symbol defined in LLVM bitcode file. The linker + completes its usual symbol resolution pass and finds that <tt>foo2()</tt> + is not used anywhere. This information is used by the LLVM optimizer and + it removes <tt>foo2()</tt>.</li> + <li>As soon as <tt>foo2()</tt> is removed, the optimizer recognizes that condition + <tt>i < 0</tt> is always false, which means <tt>foo3()</tt> is never + used. Hence, the optimizer also removes <tt>foo3()</tt>.</li> + <li>And this in turn, enables linker to remove <tt>foo4()</tt>.</li> +</ul> + +<p>This example illustrates the advantage of tight integration with the + linker. Here, the optimizer can not remove <tt>foo3()</tt> without the + linker's input.</p> + </div> <!-- ======================================================================= --> @@ -385,7 +392,7 @@ of the native object files.</p> Devang Patel and Nick Kledzik<br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-09-18 14:51:05 +0200 (Sun, 18 Sep 2011) $ </address> </body> diff --git a/docs/Passes.html b/docs/Passes.html index ca9602c..eb4a115 100644 --- a/docs/Passes.html +++ b/docs/Passes.html @@ -161,7 +161,6 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#loop-unswitch">-loop-unswitch</a></td><td>Unswitch loops</td></tr> <tr><td><a href="#loweratomic">-loweratomic</a></td><td>Lower atomic intrinsics to non-atomic form</td></tr> <tr><td><a href="#lowerinvoke">-lowerinvoke</a></td><td>Lower invoke and unwind, for unwindless code generators</td></tr> -<tr><td><a href="#lowersetjmp">-lowersetjmp</a></td><td>Lower Set Jump</td></tr> <tr><td><a href="#lowerswitch">-lowerswitch</a></td><td>Lower SwitchInst's to branches</td></tr> <tr><td><a href="#mem2reg">-mem2reg</a></td><td>Promote Memory to Register</td></tr> <tr><td><a href="#memcpyopt">-memcpyopt</a></td><td>MemCpy Optimization</td></tr> @@ -1478,35 +1477,6 @@ if (X < 3) {</pre> <!-------------------------------------------------------------------------- --> <h3> - <a name="lowersetjmp">-lowersetjmp: Lower Set Jump</a> -</h3> -<div> - <p> - Lowers <tt>setjmp</tt> and <tt>longjmp</tt> to use the LLVM invoke and unwind - instructions as necessary. - </p> - - <p> - Lowering of <tt>longjmp</tt> is fairly trivial. We replace the call with a - call to the LLVM library function <tt>__llvm_sjljeh_throw_longjmp()</tt>. - This unwinds the stack for us calling all of the destructors for - objects allocated on the stack. - </p> - - <p> - At a <tt>setjmp</tt> call, the basic block is split and the <tt>setjmp</tt> - removed. The calls in a function that have a <tt>setjmp</tt> are converted to - invoke where the except part checks to see if it's a <tt>longjmp</tt> - exception and, if so, if it's handled in the function. If it is, then it gets - the value returned by the <tt>longjmp</tt> and goes to where the basic block - was split. <tt>invoke</tt> instructions are handled in a similar fashion with - the original except block being executed if it isn't a <tt>longjmp</tt> - except that is handled by that function. - </p> -</div> - -<!-------------------------------------------------------------------------- --> -<h3> <a name="lowerswitch">-lowerswitch: Lower SwitchInst's to branches</a> </h3> <div> @@ -2071,7 +2041,7 @@ if (X < 3) {</pre> <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-08-04 00:18:20 +0200 (Thu, 04 Aug 2011) $ </address> </body> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index ed43f1f..3697dd7 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -59,6 +59,7 @@ option</a></li> <li><a href="#dss_arrayref">llvm/ADT/ArrayRef.h</a></li> <li><a href="#dss_fixedarrays">Fixed Size Arrays</a></li> <li><a href="#dss_heaparrays">Heap Allocated Arrays</a></li> + <li><a href="#dss_tinyptrvector">"llvm/ADT/TinyPtrVector.h"</a></li> <li><a href="#dss_smallvector">"llvm/ADT/SmallVector.h"</a></li> <li><a href="#dss_vector"><vector></a></li> <li><a href="#dss_deque"><deque></a></li> @@ -67,6 +68,13 @@ option</a></li> <li><a href="#dss_packedvector">llvm/ADT/PackedVector.h</a></li> <li><a href="#dss_other">Other Sequential Container Options</a></li> </ul></li> + <li><a href="#ds_string">String-like containers</a> + <ul> + <li><a href="#dss_stringref">llvm/ADT/StringRef.h</a></li> + <li><a href="#dss_twine">llvm/ADT/Twine.h</a></li> + <li><a href="#dss_smallstring">llvm/ADT/SmallString.h</a></li> + <li><a href="#dss_stdstring">std::string</a></li> + </ul></li> <li><a href="#ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a> <ul> <li><a href="#dss_sortedvectorset">A sorted 'vector'</a></li> @@ -91,10 +99,6 @@ option</a></li> <li><a href="#dss_inteqclasses">"llvm/ADT/IntEqClasses.h"</a></li> <li><a href="#dss_othermap">Other Map-Like Container Options</a></li> </ul></li> - <li><a href="#ds_string">String-like containers</a> - <!--<ul> - todo - </ul>--></li> <li><a href="#ds_bit">BitVector-like containers</a> <ul> <li><a href="#dss_bitvector">A dense bitvector</a></li> @@ -875,6 +879,9 @@ elements (but could contain many), for example, it's much better to use . Doing so avoids (relatively) expensive malloc/free calls, which dwarf the cost of adding the elements to the container. </p> +</div> + + <!-- ======================================================================= --> <h3> <a name="ds_sequential">Sequential Containers (std::vector, std::list, etc)</a> @@ -883,7 +890,7 @@ cost of adding the elements to the container. </p> <div> There are a variety of sequential containers available for you, based on your needs. Pick the first in this section that will do what you want. - + <!-- _______________________________________________________________________ --> <h4> <a name="dss_arrayref">llvm/ADT/ArrayRef.h</a> @@ -928,6 +935,22 @@ construct those elements actually used).</p> <!-- _______________________________________________________________________ --> <h4> + <a name="dss_tinyptrvector">"llvm/ADT/TinyPtrVector.h"</a> +</h4> + + +<div> +<p><tt>TinyPtrVector<Type></tt> is a highly specialized collection class +that is optimized to avoid allocation in the case when a vector has zero or one +elements. It has two major restrictions: 1) it can only hold values of pointer +type, and 2) it cannot hold a null pointer.</p> + +<p>Since this container is highly specialized, it is rarely used.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="dss_smallvector">"llvm/ADT/SmallVector.h"</a> </h4> @@ -1190,9 +1213,187 @@ std::priority_queue, std::stack, etc. These provide simplified access to an underlying container but don't affect the cost of the container itself.</p> </div> +</div> +<!-- ======================================================================= --> +<h3> + <a name="ds_string">String-like containers</a> +</h3> + +<div> + +<p> +There are a variety of ways to pass around and use strings in C and C++, and +LLVM adds a few new options to choose from. Pick the first option on this list +that will do what you need, they are ordered according to their relative cost. +</p> +<p> +Note that is is generally preferred to <em>not</em> pass strings around as +"<tt>const char*</tt>"'s. These have a number of problems, including the fact +that they cannot represent embedded nul ("\0") characters, and do not have a +length available efficiently. The general replacement for '<tt>const +char*</tt>' is StringRef. +</p> + +<p>For more information on choosing string containers for APIs, please see +<a href="#string_apis">Passing strings</a>.</p> + + +<!-- _______________________________________________________________________ --> +<h4> + <a name="dss_stringref">llvm/ADT/StringRef.h</a> +</h4> + +<div> +<p> +The StringRef class is a simple value class that contains a pointer to a +character and a length, and is quite related to the <a +href="#dss_arrayref">ArrayRef</a> class (but specialized for arrays of +characters). Because StringRef carries a length with it, it safely handles +strings with embedded nul characters in it, getting the length does not require +a strlen call, and it even has very convenient APIs for slicing and dicing the +character range that it represents. +</p> + +<p> +StringRef is ideal for passing simple strings around that are known to be live, +either because they are C string literals, std::string, a C array, or a +SmallVector. Each of these cases has an efficient implicit conversion to +StringRef, which doesn't result in a dynamic strlen being executed. +</p> + +<p>StringRef has a few major limitations which make more powerful string +containers useful:</p> + +<ol> +<li>You cannot directly convert a StringRef to a 'const char*' because there is +no way to add a trailing nul (unlike the .c_str() method on various stronger +classes).</li> + + +<li>StringRef doesn't own or keep alive the underlying string bytes. +As such it can easily lead to dangling pointers, and is not suitable for +embedding in datastructures in most cases (instead, use an std::string or +something like that).</li> + +<li>For the same reason, StringRef cannot be used as the return value of a +method if the method "computes" the result string. Instead, use +std::string.</li> + +<li>StringRef's do not allow you to mutate the pointed-to string bytes and it +doesn't allow you to insert or remove bytes from the range. For editing +operations like this, it interoperates with the <a +href="#dss_twine">Twine</a> class.</li> +</ol> + +<p>Because of its strengths and limitations, it is very common for a function to +take a StringRef and for a method on an object to return a StringRef that +points into some string that it owns.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="dss_twine">llvm/ADT/Twine.h</a> +</h4> + +<div> + <p> + The Twine class is used as an intermediary datatype for APIs that want to take + a string that can be constructed inline with a series of concatenations. + Twine works by forming recursive instances of the Twine datatype (a simple + value object) on the stack as temporary objects, linking them together into a + tree which is then linearized when the Twine is consumed. Twine is only safe + to use as the argument to a function, and should always be a const reference, + e.g.: + </p> + + <pre> + void foo(const Twine &T); + ... + StringRef X = ... + unsigned i = ... + foo(X + "." + Twine(i)); + </pre> + + <p>This example forms a string like "blarg.42" by concatenating the values + together, and does not form intermediate strings containing "blarg" or + "blarg.". + </p> + + <p>Because Twine is constructed with temporary objects on the stack, and + because these instances are destroyed at the end of the current statement, + it is an inherently dangerous API. For example, this simple variant contains + undefined behavior and will probably crash:</p> + + <pre> + void foo(const Twine &T); + ... + StringRef X = ... + unsigned i = ... + const Twine &Tmp = X + "." + Twine(i); + foo(Tmp); + </pre> + + <p>... because the temporaries are destroyed before the call. That said, + Twine's are much more efficient than intermediate std::string temporaries, and + they work really well with StringRef. Just be aware of their limitations.</p> + +</div> + + +<!-- _______________________________________________________________________ --> +<h4> + <a name="dss_smallstring">llvm/ADT/SmallString.h</a> +</h4> + +<div> + +<p>SmallString is a subclass of <a href="#dss_smallvector">SmallVector</a> that +adds some convenience APIs like += that takes StringRef's. SmallString avoids +allocating memory in the case when the preallocated space is enough to hold its +data, and it calls back to general heap allocation when required. Since it owns +its data, it is very safe to use and supports full mutation of the string.</p> + +<p>Like SmallVector's, the big downside to SmallString is their sizeof. While +they are optimized for small strings, they themselves are not particularly +small. This means that they work great for temporary scratch buffers on the +stack, but should not generally be put into the heap: it is very rare to +see a SmallString as the member of a frequently-allocated heap data structure +or returned by-value. +</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="dss_stdstring">std::string</a> +</h4> + +<div> + + <p>The standard C++ std::string class is a very general class that (like + SmallString) owns its underlying data. sizeof(std::string) is very reasonable + so it can be embedded into heap data structures and returned by-value. + On the other hand, std::string is highly inefficient for inline editing (e.g. + concatenating a bunch of stuff together) and because it is provided by the + standard library, its performance characteristics depend a lot of the host + standard library (e.g. libc++ and MSVC provide a highly optimized string + class, GCC contains a really slow implementation). + </p> + + <p>The major disadvantage of std::string is that almost every operation that + makes them larger can allocate memory, which is slow. As such, it is better + to use SmallVector or Twine as a scratch buffer, but then use std::string to + persist the result.</p> + + +</div> + +<!-- end of strings --> </div> + <!-- ======================================================================= --> <h3> <a name="ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a> @@ -1381,12 +1582,13 @@ elements out of (linear time), unless you use it's "pop_back" method, which is faster. </p> -<p>SetVector is an adapter class that defaults to using std::vector and std::set -for the underlying containers, so it is quite expensive. However, -<tt>"llvm/ADT/SetVector.h"</tt> also provides a SmallSetVector class, which -defaults to using a SmallVector and SmallSet of a specified size. If you use -this, and if your sets are dynamically smaller than N, you will save a lot of -heap traffic.</p> +<p><tt>SetVector</tt> is an adapter class that defaults to + using <tt>std::vector</tt> and a size 16 <tt>SmallSet</tt> for the underlying + containers, so it is quite expensive. However, + <tt>"llvm/ADT/SetVector.h"</tt> also provides a <tt>SmallSetVector</tt> + class, which defaults to using a <tt>SmallVector</tt> and <tt>SmallSet</tt> + of a specified size. If you use this, and if your sets are dynamically + smaller than <tt>N</tt>, you will save a lot of heap traffic.</p> </div> @@ -1636,20 +1838,6 @@ always better.</p> <!-- ======================================================================= --> <h3> - <a name="ds_string">String-like containers</a> -</h3> - -<div> - -<p> -TODO: const char* vs stringref vs smallstring vs std::string. Describe twine, -xref to #string_apis. -</p> - -</div> - -<!-- ======================================================================= --> -<h3> <a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a> </h3> @@ -3867,7 +4055,7 @@ arguments. An argument has a pointer to the parent Function.</p> <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-07-12 13:37:02 +0200 (Tue, 12 Jul 2011) $ + Last modified: $Date: 2011-10-11 08:33:56 +0200 (Tue, 11 Oct 2011) $ </address> </body> diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index d54698d..b0d4f67 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -44,21 +44,21 @@ Release Notes</a>.</h1> <div> <p>This document contains the release notes for the LLVM Compiler -Infrastructure, release 3.0. Here we describe the status of LLVM, including -major improvements from the previous release and significant known problems. -All LLVM releases may be downloaded from the <a -href="http://llvm.org/releases/">LLVM releases web site</a>.</p> + Infrastructure, release 3.0. Here we describe the status of LLVM, including + major improvements from the previous release and significant known problems. + All LLVM releases may be downloaded from + the <a href="http://llvm.org/releases/">LLVM releases web site</a>.</p> <p>For more information about LLVM, including information about the latest -release, please check out the <a href="http://llvm.org/">main LLVM -web site</a>. If you have questions or comments, the <a -href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developer's -Mailing List</a> is a good place to send them.</p> + release, please check out the <a href="http://llvm.org/">main LLVM web + site</a>. If you have questions or comments, + the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM + Developer's Mailing List</a> is a good place to send them.</p> -<p>Note that if you are reading this file from a Subversion checkout or the -main LLVM web page, this document applies to the <i>next</i> release, not the -current one. To see the release notes for a specific release, please see the -<a href="http://llvm.org/releases/">releases page</a>.</p> +<p>Note that if you are reading this file from a Subversion checkout or the main + LLVM web page, this document applies to the <i>next</i> release, not the + current one. To see the release notes for a specific release, please see the + <a href="http://llvm.org/releases/">releases page</a>.</p> </div> @@ -78,13 +78,12 @@ current one. To see the release notes for a specific release, please see the <!-- *********************************************************************** --> <div> -<p> -The LLVM 3.0 distribution currently consists of code from the core LLVM -repository (which roughly includes the LLVM optimizers, code generators -and supporting tools), the Clang repository and the llvm-gcc repository. In -addition to this code, the LLVM Project includes other sub-projects that are in -development. Here we include updates on these subprojects. -</p> + +<p>The LLVM 3.0 distribution currently consists of code from the core LLVM + repository (which roughly includes the LLVM optimizers, code generators and + supporting tools), the Clang repository and the llvm-gcc repository. In + addition to this code, the LLVM Project includes other sub-projects that are + in development. Here we include updates on these subprojects.</p> <!--=========================================================================--> <h3> @@ -94,20 +93,47 @@ development. Here we include updates on these subprojects. <div> <p><a href="http://clang.llvm.org/">Clang</a> is an LLVM front end for the C, -C++, and Objective-C languages. Clang aims to provide a better user experience -through expressive diagnostics, a high level of conformance to language -standards, fast compilation, and low memory use. Like LLVM, Clang provides a -modular, library-based architecture that makes it suitable for creating or -integrating with other development tools. Clang is considered a -production-quality compiler for C, Objective-C, C++ and Objective-C++ on x86 -(32- and 64-bit), and for darwin/arm targets.</p> + C++, and Objective-C languages. Clang aims to provide a better user + experience through expressive diagnostics, a high level of conformance to + language standards, fast compilation, and low memory use. Like LLVM, Clang + provides a modular, library-based architecture that makes it suitable for + creating or integrating with other development tools. Clang is considered a + production-quality compiler for C, Objective-C, C++ and Objective-C++ on x86 + (32- and 64-bit), and for darwin/arm targets.</p> <p>In the LLVM 3.0 time-frame, the Clang team has made many improvements:</p> + +<ul> + <li>Greatly improved support for building C++ applications, with greater + stability and better diagnostics.</li> + + <li><a href="http://clang.llvm.org/cxx_status.html">Improved support</a> for + the <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=50372">C++ + 2011</a> standard, including implementations of non-static data member + initializers, alias templates, delegating constructors, the range-based + for loop, and implicitly-generated move constructors and move assignment + operators, among others.</li> + + <li>Implemented support for some features of the upcoming C1x standard, + including static assertions and generic selections.</li> + + <li>Better detection of include and linking paths for system headers and + libraries, especially for Linux distributions.</li> + + <li>Implemented support + for <a href="http://clang.llvm.org/docs/AutomaticReferenceCounting.html">Automatic + Reference Counting</a> for Objective-C.</li> + + <li>Implemented a number of optimizations in <tt>libclang</tt>, the Clang C + interface, to improve the performance of code completion and the mapping + from source locations to abstract syntax tree nodes.</li> +</ul> + <p>If Clang rejects your code but another compiler accepts it, please take a -look at the <a href="http://clang.llvm.org/compatibility.html">language -compatibility</a> guide to make sure this is not intentional or a known issue. -</p> + look at the <a href="http://clang.llvm.org/compatibility.html">language + compatibility</a> guide to make sure this is not intentional or a known + issue.</p> </div> @@ -117,20 +143,17 @@ compatibility</a> guide to make sure this is not intentional or a known issue. </h3> <div> -<p> -<a href="http://dragonegg.llvm.org/">DragonEgg</a> is a -<a href="http://gcc.gnu.org/wiki/plugins">gcc plugin</a> that replaces GCC's -optimizers and code generators with LLVM's. -Currently it requires a patched version of gcc-4.5. -The plugin can target the x86-32 and x86-64 processor families and has been -used successfully on the Darwin, FreeBSD and Linux platforms. -The Ada, C, C++ and Fortran languages work well. -The plugin is capable of compiling plenty of Obj-C, Obj-C++ and Java but it is -not known whether the compiled code actually works or not! -</p> +<p><a href="http://dragonegg.llvm.org/">DragonEgg</a> is a + <a href="http://gcc.gnu.org/wiki/plugins">gcc plugin</a> that replaces GCC's + optimizers and code generators with LLVM's. Currently it requires a patched + version of gcc-4.5. The plugin can target the x86-32 and x86-64 processor + families and has been used successfully on the Darwin, FreeBSD and Linux + platforms. The Ada, C, C++ and Fortran languages work well. The plugin is + capable of compiling plenty of Obj-C, Obj-C++ and Java but it is not known + whether the compiled code actually works or not!</p> + +<p>The 3.0 release has the following notable changes:</p> -<p> -The 3.0 release has the following notable changes: <ul> <!-- <li></li> @@ -145,15 +168,15 @@ The 3.0 release has the following notable changes: </h3> <div> -<p> -The new LLVM <a href="http://compiler-rt.llvm.org/">compiler-rt project</a> -is a simple library that provides an implementation of the low-level -target-specific hooks required by code generation and other runtime components. -For example, when compiling for a 32-bit target, converting a double to a 64-bit -unsigned integer is compiled into a runtime call to the "__fixunsdfdi" -function. The compiler-rt library provides highly optimized implementations of -this and other low-level routines (some are 3x faster than the equivalent -libgcc routines).</p> + +<p>The new LLVM <a href="http://compiler-rt.llvm.org/">compiler-rt project</a> + is a simple library that provides an implementation of the low-level + target-specific hooks required by code generation and other runtime + components. For example, when compiling for a 32-bit target, converting a + double to a 64-bit unsigned integer is compiled into a runtime call to the + "__fixunsdfdi" function. The compiler-rt library provides highly optimized + implementations of this and other low-level routines (some are 3x faster than + the equivalent libgcc routines).</p> <p>In the LLVM 3.0 timeframe,</p> @@ -165,19 +188,18 @@ libgcc routines).</p> </h3> <div> -<p> -<a href="http://lldb.llvm.org/">LLDB</a> is a brand new member of the LLVM -umbrella of projects. LLDB is a next generation, high-performance debugger. It -is built as a set of reusable components which highly leverage existing -libraries in the larger LLVM Project, such as the Clang expression parser, the -LLVM disassembler and the LLVM JIT.</p> -<p> -LLDB is has advanced by leaps and bounds in the 3.0 timeframe. It is -dramatically more stable and useful, and includes both a new <a -href="http://lldb.llvm.org/tutorial.html">tutorial</a> and a <a -href="http://lldb.llvm.org/lldb-gdb.html">side-by-side comparison with -GDB</a>.</p> +<p><a href="http://lldb.llvm.org/">LLDB</a> is a brand new member of the LLVM + umbrella of projects. LLDB is a next generation, high-performance + debugger. It is built as a set of reusable components which highly leverage + existing libraries in the larger LLVM Project, such as the Clang expression + parser, the LLVM disassembler and the LLVM JIT.</p> + +<p>LLDB is has advanced by leaps and bounds in the 3.0 timeframe. It is + dramatically more stable and useful, and includes both a + new <a href="http://lldb.llvm.org/tutorial.html">tutorial</a> and + a <a href="http://lldb.llvm.org/lldb-gdb.html">side-by-side comparison with + GDB</a>.</p> </div> @@ -187,20 +209,17 @@ GDB</a>.</p> </h3> <div> -<p> -<a href="http://libcxx.llvm.org/">libc++</a> is another new member of the LLVM -family. It is an implementation of the C++ standard library, written from the -ground up to specifically target the forthcoming C++'0X standard and focus on -delivering great performance.</p> -<p> -In the LLVM 3.0 timeframe,</p> +<p><a href="http://libcxx.llvm.org/">libc++</a> is another new member of the + LLVM family. It is an implementation of the C++ standard library, written + from the ground up to specifically target the forthcoming C++'0X standard and + focus on delivering great performance.</p> + +<p>In the LLVM 3.0 timeframe,</p> -<p> -Like compiler_rt, libc++ is now <a href="DeveloperPolicy.html#license">dual - licensed</a> under the MIT and UIUC license, allowing it to be used more - permissively. -</p> +<p>Like compiler_rt, libc++ is now <a href="DeveloperPolicy.html#license">dual + licensed</a> under the MIT and UIUC license, allowing it to be used more + permissively.</p> </div> @@ -211,13 +230,14 @@ Like compiler_rt, libc++ is now <a href="DeveloperPolicy.html#license">dual </h3> <div> -<p> -<a href="http://llvm.org/svn/llvm-project/llbrowse/trunk/doc/LLBrowse.html"> - LLBrowse</a> is an interactive viewer for LLVM modules. It can load any LLVM - module and displays its contents as an expandable tree view, facilitating an - easy way to inspect types, functions, global variables, or metadata nodes. It - is fully cross-platform, being based on the popular wxWidgets GUI toolkit. -</p> + +<p><a href="http://llvm.org/svn/llvm-project/llbrowse/trunk/doc/LLBrowse.html"> + LLBrowse</a> is an interactive viewer for LLVM modules. It can load any LLVM + module and displays its contents as an expandable tree view, facilitating an + easy way to inspect types, functions, global variables, or metadata nodes. It + is fully cross-platform, being based on the popular wxWidgets GUI + toolkit.</p> + </div> <!--=========================================================================--> @@ -226,13 +246,14 @@ Like compiler_rt, libc++ is now <a href="DeveloperPolicy.html#license">dual </h3> <div> + <p>The <a href="http://vmkit.llvm.org/">VMKit project</a> is an implementation - of a Java Virtual Machine (Java VM or JVM) that uses LLVM for static and - just-in-time compilation. As of LLVM 3.0, VMKit now supports generational - garbage collectors. The garbage collectors are provided by the MMTk framework, - and VMKit can be configured to use one of the numerous implemented collectors - of MMTk. -</p> + of a Java Virtual Machine (Java VM or JVM) that uses LLVM for static and + just-in-time compilation. As of LLVM 3.0, VMKit now supports generational + garbage collectors. The garbage collectors are provided by the MMTk + framework, and VMKit can be configured to use one of the numerous implemented + collectors of MMTk.</p> + </div> @@ -272,125 +293,133 @@ be used to verify some algorithms. <h3>Crack Programming Language</h3> <div> -<p> -<a href="http://code.google.com/p/crack-language/">Crack</a> aims to provide the -ease of development of a scripting language with the performance of a compiled -language. The language derives concepts from C++, Java and Python, incorporating -object-oriented programming, operator overloading and strong typing.</p> + +<p><a href="http://code.google.com/p/crack-language/">Crack</a> aims to provide + the ease of development of a scripting language with the performance of a + compiled language. The language derives concepts from C++, Java and Python, + incorporating object-oriented programming, operator overloading and strong + typing.</p> + </div> - <!--=========================================================================--> <h3>TTA-based Codesign Environment (TCE)</h3> <div> + <p>TCE is a toolset for designing application-specific processors (ASP) based on -the Transport triggered architecture (TTA). The toolset provides a complete -co-design flow from C/C++ programs down to synthesizable VHDL and parallel -program binaries. Processor customization points include the register files, -function units, supported operations, and the interconnection network.</p> + the Transport triggered architecture (TTA). The toolset provides a complete + co-design flow from C/C++ programs down to synthesizable VHDL and parallel + program binaries. Processor customization points include the register files, + function units, supported operations, and the interconnection network.</p> <p>TCE uses Clang and LLVM for C/C++ language support, target independent -optimizations and also for parts of code generation. It generates new LLVM-based -code generators "on the fly" for the designed TTA processors and loads them in -to the compiler backend as runtime libraries to avoid per-target recompilation -of larger parts of the compiler chain.</p> -</div> - + optimizations and also for parts of code generation. It generates new + LLVM-based code generators "on the fly" for the designed TTA processors and + loads them in to the compiler backend as runtime libraries to avoid + per-target recompilation of larger parts of the compiler chain.</p> +</div> <!--=========================================================================--> <h3>PinaVM</h3> <div> + <p><a href="http://gitorious.org/pinavm/pages/Home">PinaVM</a> is an open -source, <a href="http://www.systemc.org/">SystemC</a> front-end. Unlike many -other front-ends, PinaVM actually executes the elaboration of the -program analyzed using LLVM's JIT infrastructure. It later enriches the -bitcode with SystemC-specific information.</p> + source, <a href="http://www.systemc.org/">SystemC</a> front-end. Unlike many + other front-ends, PinaVM actually executes the elaboration of the program + analyzed using LLVM's JIT infrastructure. It later enriches the bitcode with + SystemC-specific information.</p> + </div> <!--=========================================================================--> <h3>Pure</h3> <div> + <p><a href="http://pure-lang.googlecode.com/">Pure</a> is an - algebraic/functional - programming language based on term rewriting. Programs are collections - of equations which are used to evaluate expressions in a symbolic - fashion. The interpreter uses LLVM as a backend to JIT-compile Pure - programs to fast native code. Pure offers dynamic typing, eager and lazy - evaluation, lexical closures, a hygienic macro system (also based on - term rewriting), built-in list and matrix support (including list and - matrix comprehensions) and an easy-to-use interface to C and other - programming languages (including the ability to load LLVM bitcode - modules, and inline C, C++, Fortran and Faust code in Pure programs if - the corresponding LLVM-enabled compilers are installed).</p> + algebraic/functional programming language based on term rewriting. Programs + are collections of equations which are used to evaluate expressions in a + symbolic fashion. The interpreter uses LLVM as a backend to JIT-compile Pure + programs to fast native code. Pure offers dynamic typing, eager and lazy + evaluation, lexical closures, a hygienic macro system (also based on term + rewriting), built-in list and matrix support (including list and matrix + comprehensions) and an easy-to-use interface to C and other programming + languages (including the ability to load LLVM bitcode modules, and inline C, + C++, Fortran and Faust code in Pure programs if the corresponding + LLVM-enabled compilers are installed).</p> -<p>Pure version 0.47 has been tested and is known to work with LLVM 3.0 - (and continues to work with older LLVM releases >= 2.5).</p> +<p>Pure version 0.47 has been tested and is known to work with LLVM 3.0 (and + continues to work with older LLVM releases >= 2.5).</p> + </div> <!--=========================================================================--> <h3 id="icedtea">IcedTea Java Virtual Machine Implementation</h3> <div> -<p> -<a href="http://icedtea.classpath.org/wiki/Main_Page">IcedTea</a> provides a -harness to build OpenJDK using only free software build tools and to provide -replacements for the not-yet free parts of OpenJDK. One of the extensions that -IcedTea provides is a new JIT compiler named <a -href="http://icedtea.classpath.org/wiki/ZeroSharkFaq">Shark</a> which uses LLVM -to provide native code generation without introducing processor-dependent -code. -</p> -<p> OpenJDK 7 b112, IcedTea6 1.9 and IcedTea7 1.13 and later have been tested -and are known to work with LLVM 3.0 (and continue to work with older LLVM -releases >= 2.6 as well).</p> +<p><a href="http://icedtea.classpath.org/wiki/Main_Page">IcedTea</a> provides a + harness to build OpenJDK using only free software build tools and to provide + replacements for the not-yet free parts of OpenJDK. One of the extensions + that IcedTea provides is a new JIT compiler + named <a href="http://icedtea.classpath.org/wiki/ZeroSharkFaq">Shark</a> + which uses LLVM to provide native code generation without introducing + processor-dependent code.</p> + +<p>OpenJDK 7 b112, IcedTea6 1.9 and IcedTea7 1.13 and later have been tested and + are known to work with LLVM 3.0 (and continue to work with older LLVM + releases >= 2.6 as well).</p> + </div> <!--=========================================================================--> <h3>Glasgow Haskell Compiler (GHC)</h3> <div> -<p>GHC is an open source, state-of-the-art programming suite for Haskell, -a standard lazy functional programming language. It includes an -optimizing static compiler generating good code for a variety of -platforms, together with an interactive system for convenient, quick -development.</p> + +<p>GHC is an open source, state-of-the-art programming suite for Haskell, a + standard lazy functional programming language. It includes an optimizing + static compiler generating good code for a variety of platforms, together + with an interactive system for convenient, quick development.</p> <p>In addition to the existing C and native code generators, GHC 7.0 now -supports an LLVM code generator. GHC supports LLVM 2.7 and later.</p> + supports an LLVM code generator. GHC supports LLVM 2.7 and later.</p> + </div> <!--=========================================================================--> <h3>Polly - Polyhedral optimizations for LLVM</h3> <div> + <p>Polly is a project that aims to provide advanced memory access optimizations -to better take advantage of SIMD units, cache hierarchies, multiple cores or -even vector accelerators for LLVM. Built around an abstract mathematical -description based on Z-polyhedra, it provides the infrastructure to develop -advanced optimizations in LLVM and to connect complex external optimizers. In -its first year of existence Polly already provides an exact value-based -dependency analysis as well as basic SIMD and OpenMP code generation support. -Furthermore, Polly can use PoCC(Pluto) an advanced optimizer for data-locality -and parallelism.</p> + to better take advantage of SIMD units, cache hierarchies, multiple cores or + even vector accelerators for LLVM. Built around an abstract mathematical + description based on Z-polyhedra, it provides the infrastructure to develop + advanced optimizations in LLVM and to connect complex external optimizers. In + its first year of existence Polly already provides an exact value-based + dependency analysis as well as basic SIMD and OpenMP code generation support. + Furthermore, Polly can use PoCC(Pluto) an advanced optimizer for + data-locality and parallelism.</p> + </div> <!--=========================================================================--> <h3>Rubinius</h3> <div> - <p><a href="http://github.com/evanphx/rubinius">Rubinius</a> is an environment - for running Ruby code which strives to write as much of the implementation in - Ruby as possible. Combined with a bytecode interpreting VM, it uses LLVM to - optimize and compile ruby code down to machine code. Techniques such as type - feedback, method inlining, and deoptimization are all used to remove dynamism - from ruby execution and increase performance.</p> -</div> +<p><a href="http://github.com/evanphx/rubinius">Rubinius</a> is an environment + for running Ruby code which strives to write as much of the implementation in + Ruby as possible. Combined with a bytecode interpreting VM, it uses LLVM to + optimize and compile ruby code down to machine code. Techniques such as type + feedback, method inlining, and deoptimization are all used to remove dynamism + from ruby execution and increase performance.</p> + +</div> <!--=========================================================================--> <h3> @@ -398,12 +427,13 @@ and parallelism.</p> </h3> <div> -<p> -<a href="http://faust.grame.fr">FAUST</a> is a compiled language for real-time -audio signal processing. The name FAUST stands for Functional AUdio STream. Its -programming model combines two approaches: functional programming and block -diagram composition. In addition with the C, C++, JAVA output formats, the -Faust compiler can now generate LLVM bitcode, and works with LLVM 2.7-3.0.</p> + +<p><a href="http://faust.grame.fr">FAUST</a> is a compiled language for + real-time audio signal processing. The name FAUST stands for Functional AUdio + STream. Its programming model combines two approaches: functional programming + and block diagram composition. In addition with the C, C++, JAVA output + formats, the Faust compiler can now generate LLVM bitcode, and works with + LLVM 2.7-3.0.</p> </div> @@ -418,9 +448,8 @@ Faust compiler can now generate LLVM bitcode, and works with LLVM 2.7-3.0.</p> <div> <p>This release includes a huge number of bug fixes, performance tweaks and -minor improvements. Some of the major improvements and new features are listed -in this section. -</p> + minor improvements. Some of the major improvements and new features are + listed in this section.</p> <!--=========================================================================--> <h3> @@ -447,15 +476,121 @@ in this section. </h3> <div> + <p>LLVM IR has several new features for better support of new targets and that -expose new optimization opportunities:</p> + expose new optimization opportunities:</p> + +<p>One of the biggest changes is that 3.0 has a new exception handling + system. The old system used LLVM intrinsics to convey the exception handling + information to the code generator. It worked in most cases, but not + all. Inlining was especially difficult to get right. Also, the intrinsics + could be moved away from the <code>invoke</code> instruction, making it hard + to recover that information.</p> + +<p>The new EH system makes exception handling a first-class member of the IR. It + adds two new instructions:</p> <ul> -<!-- -<li></li> ---> + <li><a href="LangRef.html#i_landingpad"><code>landingpad</code></a> — + this instruction defines a landing pad basic block. It contains all of the + information that's needed by the code generator. It's also required to be + the first non-PHI instruction in the landing pad. In addition, a landing + pad may be jumped to only by the unwind edge of an <code>invoke</code> + instruction.</li> + + <li><a href="LangRef.html#i_resume"><code>resume</code></a> — this + instruction causes the current exception to resume traveling up the + stack. It replaces the <code>@llvm.eh.resume</code> intrinsic.</li> </ul> +<p>Converting from the old EH API to the new EH API is rather simple, because a + lot of complexity has been removed. The two intrinsics, + <code>@llvm.eh.exception</code> and <code>@llvm.eh.selector</code> have been + superceded by the <code>landingpad</code> instruction. Instead of generating + a call to <code>@llvm.eh.exception</code> and <code>@llvm.eh.selector</code>: + +<div class="doc_code"> +<pre> +Function *ExcIntr = Intrinsic::getDeclaration(TheModule, + Intrinsic::eh_exception); +Function *SlctrIntr = Intrinsic::getDeclaration(TheModule, + Intrinsic::eh_selector); + +// The exception pointer. +Value *ExnPtr = Builder.CreateCall(ExcIntr, "exc_ptr"); + +std::vector<Value*> Args; +Args.push_back(ExnPtr); +Args.push_back(Builder.CreateBitCast(Personality, + Type::getInt8PtrTy(Context))); + +<i>// Add selector clauses to Args.</i> + +// The selector call. +Builder.CreateCall(SlctrIntr, Args, "exc_sel"); +</pre> +</div> + +<p>You should instead generate a <code>landingpad</code> instruction, that + returns an exception object and selector value:</p> + +<div class="doc_code"> +<pre> +LandingPadInst *LPadInst = + Builder.CreateLandingPad(StructType::get(Int8PtrTy, Int32Ty, NULL), + Personality, 0); + +Value *LPadExn = Builder.CreateExtractValue(LPadInst, 0); +Builder.CreateStore(LPadExn, getExceptionSlot()); + +Value *LPadSel = Builder.CreateExtractValue(LPadInst, 1); +Builder.CreateStore(LPadSel, getEHSelectorSlot()); +</pre> +</div> + +<p>It's now trivial to add the individual clauses to the <code>landingpad</code> + instruction.</p> + +<div class="doc_code"> +<pre> +<i><b>// Adding a catch clause</b></i> +Constant *TypeInfo = getTypeInfo(); +LPadInst->addClause(TypeInfo); + +<i><b>// Adding a C++ catch-all</b></i> +LPadInst->addClause(Constant::getNullValue(Builder.getInt8PtrTy())); + +<i><b>// Adding a cleanup</b></i> +LPadInst->setCleanup(true); + +<i><b>// Adding a filter clause</b></i> +std::vector<Constant*> TypeInfos; +Constant *TypeInfo = getFilterTypeInfo(); +TypeInfos.push_back(Builder.CreateBitCast(TypeInfo, Builder.getInt8PtrTy())); + +ArrayType *FilterTy = ArrayType::get(Int8PtrTy, TypeInfos.size()); +LPadInst->addClause(ConstantArray::get(FilterTy, TypeInfos)); +</pre> +</div> + +<p>Converting from using the <code>@llvm.eh.resume</code> intrinsic to + the <code>resume</code> instruction is trivial. It takes the exception + pointer and exception selector values returned by + the <code>landingpad</code> instruction:</p> + +<div class="doc_code"> +<pre> +Type *UnwindDataTy = StructType::get(Builder.getInt8PtrTy(), + Builder.getInt32Ty(), NULL); +Value *UnwindData = UndefValue::get(UnwindDataTy); +Value *ExcPtr = Builder.CreateLoad(getExceptionObjSlot()); +Value *ExcSel = Builder.CreateLoad(getExceptionSelSlot()); +UnwindData = Builder.CreateInsertValue(UnwindData, ExcPtr, 0, "exc_ptr"); +UnwindData = Builder.CreateInsertValue(UnwindData, ExcSel, 1, "exc_sel"); +Builder.CreateResume(UnwindData); +</pre> +</div> + </div> <!--=========================================================================--> @@ -466,7 +601,8 @@ expose new optimization opportunities:</p> <div> <p>In addition to a large array of minor performance tweaks and bug fixes, this -release includes a few major enhancements and additions to the optimizers:</p> + release includes a few major enhancements and additions to the + optimizers:</p> <ul> <!-- @@ -484,11 +620,11 @@ release includes a few major enhancements and additions to the optimizers:</p> </h3> <div> -<p> -The LLVM Machine Code (aka MC) subsystem was created to solve a number -of problems in the realm of assembly, disassembly, object file format handling, -and a number of other related areas that CPU instruction-set level tools work -in.</p> + +<p>The LLVM Machine Code (aka MC) subsystem was created to solve a number of + problems in the realm of assembly, disassembly, object file format handling, + and a number of other related areas that CPU instruction-set level tools work + in.</p> <ul> <!-- @@ -496,10 +632,9 @@ in.</p> --> </ul> -<p>For more information, please see the <a -href="http://blog.llvm.org/2010/04/intro-to-llvm-mc-project.html">Intro to the -LLVM MC Project Blog Post</a>. -</p> +<p>For more information, please see + the <a href="http://blog.llvm.org/2010/04/intro-to-llvm-mc-project.html">Intro + to the LLVM MC Project Blog Post</a>.</p> </div> @@ -511,8 +646,8 @@ LLVM MC Project Blog Post</a>. <div> <p>We have put a significant amount of work into the code generator -infrastructure, which allows us to implement more aggressive algorithms and make -it run faster:</p> + infrastructure, which allows us to implement more aggressive algorithms and + make it run faster:</p> <ul> <!-- @@ -527,14 +662,16 @@ it run faster:</p> </h3> <div> -<p>New features and major changes in the X86 target include: -</p> + +<p>New features and major changes in the X86 target include:</p> <ul> -<li>The CRC32 intrinsics have been renamed. The intrinsics were previously - @llvm.x86.sse42.crc32.[8|16|32] and @llvm.x86.sse42.crc64.[8|64]. They have - been renamed to @llvm.x86.sse42.crc32.32.[8|16|32] and - @llvm.x86.sse42.crc32.64.[8|64].</li> + + <li>The CRC32 intrinsics have been renamed. The intrinsics were previously + <code>@llvm.x86.sse42.crc32.[8|16|32]</code> + and <code>@llvm.x86.sse42.crc64.[8|64]</code>. They have been renamed to + <code>@llvm.x86.sse42.crc32.32.[8|16|32]</code> and + <code>@llvm.x86.sse42.crc32.64.[8|64]</code>.</li> </ul> @@ -546,8 +683,8 @@ it run faster:</p> </h3> <div> -<p>New features of the ARM target include: -</p> + +<p>New features of the ARM target include:</p> <ul> <!-- @@ -562,11 +699,13 @@ it run faster:</p> </h3> <div> + <ul> <!-- <li></li> --> </ul> + </div> <!--=========================================================================--> @@ -576,18 +715,35 @@ it run faster:</p> <div> -<p>If you're already an LLVM user or developer with out-of-tree changes based -on LLVM 2.9, this section lists some "gotchas" that you may run into upgrading -from the previous release.</p> +<p>If you're already an LLVM user or developer with out-of-tree changes based on + LLVM 2.9, this section lists some "gotchas" that you may run into upgrading + from the previous release.</p> <ul> -<!-- -<li></li> ---> + <li>The <code>LLVMC</code> front end code was removed while separating + out language independence.</li> + <li>The <code>LowerSetJmp</code> pass wasn't used effectively by any + target and has been removed.</li> + <li>The old <code>TailDup</code> pass was not used in the standard pipeline + and was unable to update ssa form, so it has been removed. + <li>The syntax of volatile loads and stores in IR has been changed to + "<code>load volatile</code>"/"<code>store volatile</code>". The old + syntax ("<code>volatile load</code>"/"<code>volatile store</code>") + is still accepted, but is now considered deprecated.</li> +</ul> + +<h4>Windows (32-bit)</h4> +<div> + +<ul> + <li>On Win32(MinGW32 and MSVC), Windows 2000 will not be supported. + Windows XP or higher is required.</li> </ul> </div> +</div> + <!--=========================================================================--> <h3> <a name="api_changes">Internal API Changes</a> @@ -596,33 +752,41 @@ from the previous release.</p> <div> <p>In addition, many APIs have changed in this release. Some of the major - LLVM API changes are:</p> + LLVM API changes are:</p> <ul> - -<li><code>PHINode::reserveOperandSpace</code> has been removed. Instead, you - must specify how many operands to reserve space for when you create the - PHINode, by passing an extra argument into <code>PHINode::Create</code>.</li> - -<li>PHINodes no longer store their incoming BasicBlocks as operands. Instead, - the list of incoming BasicBlocks is stored separately, and can be accessed - with new functions <code>PHINode::block_begin</code> - and <code>PHINode::block_end</code>.</li> - -<li>Various functions now take an <code>ArrayRef</code> instead of either a pair - of pointers (or iterators) to the beginning and end of a range, or a pointer - and a length. Others now return an <code>ArrayRef</code> instead of a - reference to a <code>SmallVector</code> or <code>std::vector</code>. These - include: + <li>The biggest and most pervasive change is that llvm::Type's are no longer + returned or accepted as 'const' values. Instead, just pass around + non-const Type's.</li> + + <li><code>PHINode::reserveOperandSpace</code> has been removed. Instead, you + must specify how many operands to reserve space for when you create the + PHINode, by passing an extra argument + into <code>PHINode::Create</code>.</li> + + <li>PHINodes no longer store their incoming BasicBlocks as operands. Instead, + the list of incoming BasicBlocks is stored separately, and can be accessed + with new functions <code>PHINode::block_begin</code> + and <code>PHINode::block_end</code>.</li> + + <li>Various functions now take an <code>ArrayRef</code> instead of either a + pair of pointers (or iterators) to the beginning and end of a range, or a + pointer and a length. Others now return an <code>ArrayRef</code> instead + of a reference to a <code>SmallVector</code> + or <code>std::vector</code>. These include: <ul> <!-- Please keep this list sorted. --> <li><code>CallInst::Create</code></li> <li><code>ComputeLinearIndex</code> (in <code>llvm/CodeGen/Analysis.h</code>)</li> <li><code>ConstantArray::get</code></li> <li><code>ConstantExpr::getExtractElement</code></li> +<li><code>ConstantExpr::getGetElementPtr</code></li> +<li><code>ConstantExpr::getInBoundsGetElementPtr</code></li> <li><code>ConstantExpr::getIndices</code></li> <li><code>ConstantExpr::getInsertElement</code></li> <li><code>ConstantExpr::getWithOperands</code></li> +<li><code>ConstantFoldCall</code> (in <code>llvm/Analysis/ConstantFolding.h</code>)</li> +<li><code>ConstantFoldInstOperands</code> (in <code>llvm/Analysis/ConstantFolding.h</code>)</li> <li><code>ConstantVector::get</code></li> <li><code>DIBuilder::createComplexVariable</code></li> <li><code>DIBuilder::getOrCreateArray</code></li> @@ -630,23 +794,67 @@ from the previous release.</p> <li><code>ExtractValueInst::getIndexedType</code></li> <li><code>ExtractValueInst::getIndices</code></li> <li><code>FindInsertedValue</code> (in <code>llvm/Analysis/ValueTracking.h</code>)</li> +<li><code>gep_type_begin</code> (in <code>llvm/Support/GetElementPtrTypeIterator.h</code>)</li> +<li><code>gep_type_end</code> (in <code>llvm/Support/GetElementPtrTypeIterator.h</code>)</li> +<li><code>GetElementPtrInst::Create</code></li> +<li><code>GetElementPtrInst::CreateInBounds</code></li> +<li><code>GetElementPtrInst::getIndexedType</code></li> +<li><code>InsertValueInst::Create</code></li> +<li><code>InsertValueInst::getIndices</code></li> +<li><code>InvokeInst::Create</code></li> <li><code>IRBuilder::CreateCall</code></li> <li><code>IRBuilder::CreateExtractValue</code></li> +<li><code>IRBuilder::CreateGEP</code></li> +<li><code>IRBuilder::CreateInBoundsGEP</code></li> <li><code>IRBuilder::CreateInsertValue</code></li> <li><code>IRBuilder::CreateInvoke</code></li> -<li><code>InsertValueInst::Create</code></li> -<li><code>InsertValueInst::getIndices</code></li> -<li><code>InvokeInst::Create</code></li> <li><code>MDNode::get</code></li> <li><code>MDNode::getIfExists</code></li> <li><code>MDNode::getTemporary</code></li> <li><code>MDNode::getWhenValsUnresolved</code></li> +<li><code>SimplifyGEPInst</code> (in <code>llvm/Analysis/InstructionSimplify.h</code>)</li> +<li><code>TargetData::getIndexedOffset</code></li> </ul></li> -<li>All forms of <code>StringMap::getOrCreateValue</code> have been remove - except for the one which takes a <code>StringRef</code>.</li> + <li>All forms of <code>StringMap::getOrCreateValue</code> have been remove + except for the one which takes a <code>StringRef</code>.</li> + + <li>The <code>LLVMBuildUnwind</code> function from the C API was removed. The + LLVM <code>unwind</code> instruction has been deprecated for a long time + and isn't used by the current front-ends. So this was removed during the + exception handling rewrite.</li> + + <li>The <code>LLVMAddLowerSetJmpPass</code> function from the C API was + removed because the <code>LowerSetJmp</code> pass was removed.</li> + + <li>The <code>DIBuilder</code> interface used by front ends to encode + debugging information in the LLVM IR now expects clients to + use <code>DIBuilder::finalize()</code> at the end of translation unit to + complete debugging information encoding.</li> + + <li>The way the type system works has been + rewritten: <code>PATypeHolder</code> and <code>OpaqueType</code> are gone, + and all APIs deal with <code>Type*</code> instead of <code>const + Type*</code>. If you need to create recursive structures, then create a + named structure, and use <code>setBody()</code> when all its elements are + built. Type merging and refining is gone too: named structures are not + merged with other structures, even if their layout is identical. (of + course anonymous structures are still uniqued by layout).</li> + + <li>TargetSelect.h moved to Support/ from Target/</li> + <li>UpgradeIntrinsicCall no longer upgrades pre-2.9 intrinsic calls (for + example <code>llvm.memset.i32</code>).</li> + + <li>It is mandatory to initialize all out-of-tree passes too and their dependencies now with + <code>INITIALIZE_PASS{BEGIN,END,}</code> + and <code>INITIALIZE_{PASS,AG}_DEPENDENCY</code>.</li> + + <li>The interface for MemDepResult in MemoryDependenceAnalysis has been + enhanced with new return types Unknown and NonFuncLocal, in addition to + the existing types Clobber, Def, and NonLocal.</li> </ul> + </div> </div> @@ -659,10 +867,10 @@ from the previous release.</p> <div> -<p>This section contains significant known problems with the LLVM system, -listed by component. If you run into a problem, please check the <a -href="http://llvm.org/bugs/">LLVM bug database</a> and submit a bug if -there isn't already one.</p> +<p>This section contains significant known problems with the LLVM system, listed + by component. If you run into a problem, please check + the <a href="http://llvm.org/bugs/">LLVM bug database</a> and submit a bug if + there isn't already one.</p> <!-- ======================================================================= --> <h3> @@ -672,18 +880,19 @@ there isn't already one.</p> <div> <p>The following components of this LLVM release are either untested, known to -be broken or unreliable, or are in early development. These components should -not be relied on, and bugs should not be filed against them, but they may be -useful to some people. In particular, if you would like to work on one of these -components, please contact us on the <a -href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev list</a>.</p> + be broken or unreliable, or are in early development. These components + should not be relied on, and bugs should not be filed against them, but they + may be useful to some people. In particular, if you would like to work on + one of these components, please contact us on + the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev + list</a>.</p> <ul> -<li>The Alpha, Blackfin, CellSPU, MicroBlaze, MSP430, MIPS, PTX, SystemZ - and XCore backends are experimental.</li> -<li><tt>llc</tt> "<tt>-filetype=obj</tt>" is experimental on all targets - other than darwin and ELF X86 systems.</li> - + <li>The Alpha, Blackfin, CellSPU, MicroBlaze, MSP430, MIPS, PTX, SystemZ and + XCore backends are experimental.</li> + + <li><tt>llc</tt> "<tt>-filetype=obj</tt>" is experimental on all targets other + than darwin and ELF X86 systems.</li> </ul> </div> @@ -697,23 +906,28 @@ href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev list</a>.</p> <ul> <li>The X86 backend does not yet support - all <a href="http://llvm.org/PR879">inline assembly that uses the X86 - floating point stack</a>. It supports the 'f' and 't' constraints, but not - 'u'.</li> + all <a href="http://llvm.org/PR879">inline assembly that uses the X86 + floating point stack</a>. It supports the 'f' and 't' constraints, but + not 'u'.</li> + <li>The X86-64 backend does not yet support the LLVM IR instruction - <tt>va_arg</tt>. Currently, front-ends support variadic - argument constructs on X86-64 by lowering them manually.</li> + <tt>va_arg</tt>. Currently, front-ends support variadic argument + constructs on X86-64 by lowering them manually.</li> + <li>Windows x64 (aka Win64) code generator has a few issues. <ul> - <li>llvm-gcc cannot build the mingw-w64 runtime currently - due to lack of support for the 'u' inline assembly - constraint and for X87 floating point inline assembly.</li> - <li>On mingw-w64, you will see unresolved symbol <tt>__chkstk</tt> - due to <a href="http://llvm.org/bugs/show_bug.cgi?id=8919">Bug 8919</a>. - It is fixed in <a href="http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20110321/118499.html">r128206</a>.</li> + <li>llvm-gcc cannot build the mingw-w64 runtime currently due to lack of + support for the 'u' inline assembly constraint and for X87 floating + point inline assembly.</li> + + <li>On mingw-w64, you will see unresolved symbol <tt>__chkstk</tt> due + to <a href="http://llvm.org/bugs/show_bug.cgi?id=8919">Bug 8919</a>. + It is fixed + in <a href="http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20110321/118499.html">r128206</a>.</li> + <li>Miss-aligned MOVDQA might crash your program. It is due to - <a href="http://llvm.org/bugs/show_bug.cgi?id=9483">Bug 9483</a>, - lack of handling aligned internal globals.</li> + <a href="http://llvm.org/bugs/show_bug.cgi?id=9483">Bug 9483</a>, lack + of handling aligned internal globals.</li> </ul> </li> @@ -729,8 +943,8 @@ href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev list</a>.</p> <div> <ul> -<li>The Linux PPC32/ABI support needs testing for the interpreter and static -compilation, and lacks support for debug information.</li> + <li>The Linux PPC32/ABI support needs testing for the interpreter and static + compilation, and lacks support for debug information.</li> </ul> </div> @@ -743,11 +957,12 @@ compilation, and lacks support for debug information.</li> <div> <ul> -<li>Thumb mode works only on ARMv6 or higher processors. On sub-ARMv6 -processors, thumb programs can crash or produce wrong -results (<a href="http://llvm.org/PR1388">PR1388</a>).</li> -<li>Compilation for ARM Linux OABI (old ABI) is supported but not fully tested. -</li> + <li>Thumb mode works only on ARMv6 or higher processors. On sub-ARMv6 + processors, thumb programs can crash or produce wrong results + (<a href="http://llvm.org/PR1388">PR1388</a>).</li> + + <li>Compilation for ARM Linux OABI (old ABI) is supported but not fully + tested.</li> </ul> </div> @@ -760,8 +975,8 @@ results (<a href="http://llvm.org/PR1388">PR1388</a>).</li> <div> <ul> -<li>The SPARC backend only supports the 32-bit SPARC ABI (-m32); it does not - support the 64-bit SPARC ABI (-m64).</li> + <li>The SPARC backend only supports the 32-bit SPARC ABI (-m32); it does not + support the 64-bit SPARC ABI (-m64).</li> </ul> </div> @@ -774,7 +989,7 @@ results (<a href="http://llvm.org/PR1388">PR1388</a>).</li> <div> <ul> -<li>64-bit MIPS targets are not supported yet.</li> + <li>64-bit MIPS targets are not supported yet.</li> </ul> </div> @@ -787,11 +1002,10 @@ results (<a href="http://llvm.org/PR1388">PR1388</a>).</li> <div> <ul> - -<li>On 21164s, some rare FP arithmetic sequences which may trap do not have the -appropriate nops inserted to ensure restartability.</li> - + <li>On 21164s, some rare FP arithmetic sequences which may trap do not have + the appropriate nops inserted to ensure restartability.</li> </ul> + </div> <!-- ======================================================================= --> @@ -802,16 +1016,19 @@ appropriate nops inserted to ensure restartability.</li> <div> <p>The C backend has numerous problems and is not being actively maintained. -Depending on it for anything serious is not advised.</p> + Depending on it for anything serious is not advised.</p> <ul> -<li><a href="http://llvm.org/PR802">The C backend has only basic support for - inline assembly code</a>.</li> -<li><a href="http://llvm.org/PR1658">The C backend violates the ABI of common - C++ programs</a>, preventing intermixing between C++ compiled by the CBE and - C++ code compiled with <tt>llc</tt> or native compilers.</li> -<li>The C backend does not support all exception handling constructs.</li> -<li>The C backend does not support arbitrary precision integers.</li> + <li><a href="http://llvm.org/PR802">The C backend has only basic support for + inline assembly code</a>.</li> + + <li><a href="http://llvm.org/PR1658">The C backend violates the ABI of common + C++ programs</a>, preventing intermixing between C++ compiled by the CBE + and C++ code compiled with <tt>llc</tt> or native compilers.</li> + + <li>The C backend does not support all exception handling constructs.</li> + + <li>The C backend does not support arbitrary precision integers.</li> </ul> </div> @@ -824,7 +1041,7 @@ Depending on it for anything serious is not advised.</p> <div> -<p><b>LLVM 3.0 will be the last release of llvm-gcc.</b></p> +<p><b>LLVM 2.9 was the last release of llvm-gcc.</b></p> <p>llvm-gcc is generally very stable for the C family of languages. The only major language feature of GCC not supported by llvm-gcc is the @@ -841,8 +1058,9 @@ Depending on it for anything serious is not advised.</p> <a href="#dragonegg">dragonegg</a> instead.</p> <p>The llvm-gcc 4.2 Ada compiler has basic functionality, but is no longer being -actively maintained. If you are interested in Ada, we recommend that you -consider using <a href="#dragonegg">dragonegg</a> instead.</p> + actively maintained. If you are interested in Ada, we recommend that you + consider using <a href="#dragonegg">dragonegg</a> instead.</p> + </div> </div> @@ -855,17 +1073,16 @@ consider using <a href="#dragonegg">dragonegg</a> instead.</p> <div> -<p>A wide variety of additional information is available on the <a -href="http://llvm.org/">LLVM web page</a>, in particular in the <a -href="http://llvm.org/docs/">documentation</a> section. The web page also -contains versions of the API documentation which is up-to-date with the -Subversion version of the source code. -You can access versions of these documents specific to this release by going -into the "<tt>llvm/doc/</tt>" directory in the LLVM tree.</p> +<p>A wide variety of additional information is available on + the <a href="http://llvm.org/">LLVM web page</a>, in particular in + the <a href="http://llvm.org/docs/">documentation</a> section. The web page + also contains versions of the API documentation which is up-to-date with the + Subversion version of the source code. You can access versions of these + documents specific to this release by going into the "<tt>llvm/doc/</tt>" + directory in the LLVM tree.</p> <p>If you have any questions or comments about LLVM, please feel free to contact -us via the <a href="http://llvm.org/docs/#maillist"> mailing -lists</a>.</p> + us via the <a href="http://llvm.org/docs/#maillist"> mailing lists</a>.</p> </div> @@ -879,7 +1096,7 @@ lists</a>.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-07-15 10:37:34 +0200 (Fri, 15 Jul 2011) $ + Last modified: $Date: 2011-10-17 08:31:58 +0200 (Mon, 17 Oct 2011) $ </address> </body> diff --git a/docs/SegmentedStacks.html b/docs/SegmentedStacks.html new file mode 100644 index 0000000..a91b109 --- /dev/null +++ b/docs/SegmentedStacks.html @@ -0,0 +1,99 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> + <head> + <title>Segmented Stacks in LLVM</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + </head> + + <body> + <h1>Segmented Stacks in LLVM</h1> + <div class="doc_author"> + <p>Written by <a href="mailto:sanjoy@playingwithpointers.com">Sanjoy Das</a></p> + </div> + + <ol> + <li><a href="#intro">Introduction</a></li> + <li><a href="#implementation">Implementation Details</a> + <ol> + <li><a href="#morestack">Allocating Stacklets</a></li> + <li><a href="#alloca">Variable Sized Allocas</a></li> + </ol> + </li> + <li><a href="#results">Results</a> + <ol> + <li><a href="#go">Go on LLVM</a></li> + <li><a href="#abi">Runtime ABI</a></li> + </ol> + </li> + </ol> + + <h2><a name="intro">Introduction</a></h2> + <div> + <p> + Segmented stack allows stack space to be allocated incrementally than as a monolithic chunk (of some worst case size) at thread initialization. This is done by allocating stack blocks (henceforth called <em>stacklets</em>) and linking them into a doubly linked list. The function prologue is responsible for checking if the current stacklet has enough space for the function to execute; and if not, call into the libgcc runtime to allocate more stack space. Support for segmented stacks on x86 / Linux is currently being worked on. + </p> + <p> + The runtime functionality is <a href="http://gcc.gnu.org/wiki/SplitStacks">already there in libgcc</a>. + </p> + </div> + + <h2><a name="implementation">Implementation Details</a></h2> + <div> + <h3><a name="morestack">Allocating Stacklets</a></h3> + <div> + <p> + As mentioned above, the function prologue checks if the current stacklet has enough space. The current approach is to use a slot in the TCB to store the current stack limit (minus the amount of space needed to allocate a new block) - this slot's offset is again dictated by <code>libgcc</code>. The generated assembly looks like this on x86-64: + </p> + <pre> + leaq -8(%rsp), %r10 + cmpq %fs:112, %r10 + jg .LBB0_2 + + # More stack space needs to be allocated + movabsq $8, %r10 # The amount of space needed + movabsq $0, %r11 # The total size of arguments passed on stack + callq __morestack + ret # The reason for this extra return is explained below + .LBB0_2: + # Usual prologue continues here + </pre> + <p> + The size of function arguments on the stack needs to be passed to <code> __morestack</code> (this function is implemented in <code>libgcc</code>) since that number of bytes has to be copied from the previous stacklet to the current one. This is so that SP (and FP) relative addressing of function arguments work as expected. + </p> + <p> + The unusual <code>ret</code> is needed to have the function which made a call to <code>__morestack</code> return correctly. <code>__morestack</code>, instead of returning, calls into <code>.LBB0_2</code>. This is possible since both, the size of the <code>ret</code> instruction and the PC of call to <code>__morestack</code> are known. When the function body returns, control is transferred back to <code>__morestack</code>. <code>__morestack</code> then de-allocates the new stacklet, restores the correct SP value, and does a second return, which returns control to the correct caller. + </p> + </div> + + <h3><a name="alloca">Variable Sized Allocas</a></h3> + <div> + <p> + The section on <a href="#morestack">allocating stacklets</a> automatically assumes that every stack frame will be of fixed size. However, LLVM allows the use of the <code>llvm.alloca</code> intrinsic to allocate dynamically sized blocks of memory on the stack. When faced with such a variable-sized alloca, code is generated to + </p> + <ul> + <li>Check if the current stacklet has enough space. If yes, just bump the SP, like in the normal case.</li> + <li>If not, generate a call to <code>libgcc</code>, which allocates the memory from the heap.</li> + </ul> + <p> + The memory allocated from the heap is linked into a list in the current stacklet, and freed along with the same. This prevents a memory leak. + </p> + </div> + + </div> + + <hr> + <address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"> + <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"> + </a> + <a href="http://validator.w3.org/check/referer"> + <img src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> + </a> + <a href="mailto:sanjoy@playingwithpointers.com">Sanjoy Das</a><br> + <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ + </address> + </body> +</html> + diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index bab42a8..75fae6e89 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -298,8 +298,8 @@ height="369"> of tags are loosely bound to the tag values of DWARF information entries. However, that does not restrict the use of the information supplied to DWARF targets. To facilitate versioning of debug information, the tag is augmented - with the current debug version (LLVMDebugVersion = 8 << 16 or 0x80000 or - 524288.)</a></p> + with the current debug version (LLVMDebugVersion = 8 << 16 or + 0x80000 or 524288.)</a></p> <p>The details of the various descriptors follow.</p> @@ -324,6 +324,10 @@ height="369"> i1, ;; True if this is optimized. metadata, ;; Flags i32 ;; Runtime version + metadata ;; List of enums types + metadata ;; List of retained types + metadata ;; List of subprograms + metadata ;; List of global variables } </pre> </div> @@ -337,7 +341,8 @@ height="369"> <p>Compile unit descriptors provide the root context for objects declared in a specific compilation unit. File descriptors are defined using this context. These descriptors are collected by a named metadata - <tt>!llvm.dbg.cu</tt>. + <tt>!llvm.dbg.cu</tt>. Compile unit descriptor keeps track of subprograms, + global variables and type information. </div> @@ -355,7 +360,7 @@ height="369"> ;; (DW_TAG_file_type) metadata, ;; Source file name metadata, ;; Source file directory (includes trailing slash) - metadata ;; Reference to compile unit where defined + metadata ;; Unused } </pre> </div> @@ -365,8 +370,7 @@ height="369"> provide context for source line correspondence. </p> <p>Each input file is encoded as a separate file descriptor in LLVM debugging - information output. Each file descriptor would be defined using a - compile unit. </p> + information output. </p> </div> @@ -434,6 +438,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> Function *,;; Pointer to LLVM function metadata, ;; Lists function template parameters metadata ;; Function declaration descriptor + metadata ;; List of function variables } </pre> </div> @@ -467,10 +472,23 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> </pre> </div> -<p>These descriptors provide debug information about nested blocks within a +<p>This descriptor provides debug information about nested blocks within a subprogram. The line number and column numbers are used to dinstinguish two lexical blocks at same depth. </p> +<div class="doc_code"> +<pre> +!3 = metadata !{ + i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) + metadata ;; Reference to the scope we're annotating with a file change + metadata,;; Reference to the file the scope is enclosed in. +} +</pre> +</div> + +<p>This descriptor provides a wrapper around a lexical scope to handle file + changes in the middle of a lexical block.</p> + </div> <!-- ======================================================================= --> @@ -485,7 +503,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> !4 = metadata !{ i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_base_type) - metadata, ;; Reference to context (typically a compile unit) + metadata, ;; Reference to context metadata, ;; Name (may be "" for anonymous types) metadata, ;; Reference to file where defined (may be NULL) i32, ;; Line number where defined (may be 0) @@ -500,7 +518,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> <p>These descriptors define primitive types used in the code. Example int, bool and float. The context provides the scope of the type, which is usually the - top level. Since basic types are not usually user defined the compile unit + top level. Since basic types are not usually user defined the context and line number can be left as NULL and 0. The size, alignment and offset are expressed in bits and can be 64 bit values. The alignment is used to round the offset when embedded in a @@ -585,7 +603,7 @@ DW_TAG_restrict_type = 55 the <a href="#format_derived_type">derived type</a>. </p> <p><a href="#format_derived_type">Derived type</a> location can be determined - from the compile unit and line number. The size, alignment and offset are + from the context and line number. The size, alignment and offset are expressed in bits and can be 64 bit values. The alignment is used to round the offset when embedded in a <a href="#format_composite_type">composite type</a> (example to keep float doubles on 64 bit boundaries.) The offset is @@ -675,7 +693,7 @@ DW_TAG_inheritance = 28 the formal arguments to the subroutine.</p> <p><a href="#format_composite_type">Composite type</a> location can be - determined from the compile unit and line number. The size, alignment and + determined from the context and line number. The size, alignment and offset are expressed in bits and can be 64 bit values. The alignment is used to round the offset when embedded in a <a href="#format_composite_type">composite type</a> (as an example, to keep @@ -750,7 +768,9 @@ DW_TAG_inheritance = 28 metadata, ;; Reference to file where defined i32, ;; 24 bit - Line number where defined ;; 8 bit - Argument number. 1 indicates 1st argument. - metadata ;; Type descriptor + metadata, ;; Type descriptor + i32, ;; flags + metadata ;; (optional) Reference to inline location } </pre> </div> @@ -772,7 +792,7 @@ DW_TAG_return_variable = 258 has no source correspondent.</p> <p>The context is either the subprogram or block where the variable is defined. - Name the source variable name. Compile unit and line indicate where the + Name the source variable name. Context and line indicate where the variable was defined. Type descriptor defines the declared type of the variable.</p> @@ -1794,7 +1814,7 @@ enum Trees { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-05-31 20:06:14 +0200 (Tue, 31 May 2011) $ + Last modified: $Date: 2011-10-12 00:59:11 +0200 (Wed, 12 Oct 2011) $ </address> </body> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 37ca046..f607ef8 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -911,7 +911,7 @@ This should highlight the APIs in <tt>TableGen/Record.h</tt>.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-07 20:25:05 +0200 (Fri, 07 Oct 2011) $ </address> </body> diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index 75426e0..adbd691 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -227,11 +227,13 @@ the pass itself.</p> <p>Now that we have a way to compile our new pass, we just have to write it. Start out with:</p> -<div class="doc_code"><pre> +<div class="doc_code"> +<pre> <b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>" -</pre></div> +</pre> +</div> <p>Which are needed because we are writing a <tt><a href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>, @@ -240,53 +242,66 @@ href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a></tt>'s, and we will be doing some printing.</p> <p>Next we have:</p> -<div class="doc_code"><pre> + +<div class="doc_code"> +<pre> <b>using namespace llvm;</b> -</pre></div> +</pre> +</div> + <p>... which is required because the functions from the include files -live in the llvm namespace. -</p> +live in the llvm namespace.</p> <p>Next we have:</p> -<div class="doc_code"><pre> +<div class="doc_code"> +<pre> <b>namespace</b> { -</pre></div> +</pre> +</div> <p>... which starts out an anonymous namespace. Anonymous namespaces are to C++ what the "<tt>static</tt>" keyword is to C (at global scope). It makes the -things declared inside of the anonymous namespace only visible to the current +things declared inside of the anonymous namespace visible only to the current file. If you're not familiar with them, consult a decent C++ book for more information.</p> <p>Next, we declare our pass itself:</p> -<div class="doc_code"><pre> +<div class="doc_code"> +<pre> <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> { -</pre></div><p> +</pre> +</div> <p>This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a href="http://llvm.org/doxygen/classllvm_1_1FunctionPass.html">FunctionPass</a></tt>. The different builtin pass subclasses are described in detail <a href="#passtype">later</a>, but for now, know that <a -href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate a function at a +href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate on a function at a time.</p> -<div class="doc_code"><pre> - static char ID; - Hello() : FunctionPass(ID) {} -</pre></div><p> +<div class="doc_code"> +<pre> + static char ID; + Hello() : FunctionPass(ID) {} +</pre> +</div> -<p> This declares pass identifier used by LLVM to identify pass. This allows LLVM to -avoid using expensive C++ runtime information.</p> +<p>This declares pass identifier used by LLVM to identify pass. This allows LLVM +to avoid using expensive C++ runtime information.</p> -<div class="doc_code"><pre> +<div class="doc_code"> +<pre> <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - errs() << "<i>Hello: </i>" << F.getName() << "\n"; + errs() << "<i>Hello: </i>"; + errs().write_escaped(F.getName()) << "\n"; <b>return false</b>; } }; <i>// end of struct Hello</i> -</pre></div> +} <i>// end of anonymous namespace</i> +</pre> +</div> <p>We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method, which overloads an abstract virtual method inherited from <a @@ -294,31 +309,34 @@ href="#FunctionPass"><tt>FunctionPass</tt></a>. This is where we are supposed to do our thing, so we just print out our message with the name of each function.</p> -<div class="doc_code"><pre> - char Hello::ID = 0; -</pre></div> +<div class="doc_code"> +<pre> +char Hello::ID = 0; +</pre> +</div> -<p> We initialize pass ID here. LLVM uses ID's address to identify pass so +<p>We initialize pass ID here. LLVM uses ID's address to identify a pass, so initialization value is not important.</p> -<div class="doc_code"><pre> - static RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>", - false /* Only looks at CFG */, - false /* Analysis Pass */); -} <i>// end of anonymous namespace</i> -</pre></div> +<div class="doc_code"> +<pre> +static RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>", + false /* Only looks at CFG */, + false /* Analysis Pass */); +</pre> +</div> -<p>Lastly, we <a href="#registration">register our class</a> <tt>Hello</tt>, -giving it a command line -argument "<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>". -Last two arguments describe its behavior. -If a pass walks CFG without modifying it then third argument is set to true. -If a pass is an analysis pass, for example dominator tree pass, then true -is supplied as fourth argument. </p> +<p>Lastly, we <a href="#registration">register our class</a> <tt>Hello</tt>, +giving it a command line argument "<tt>hello</tt>", and a name "<tt>Hello World +Pass</tt>". The last two arguments describe its behavior: if a pass walks CFG +without modifying it then the third argument is set to <tt>true</tt>; if a pass +is an analysis pass, for example dominator tree pass, then <tt>true</tt> is +supplied as the fourth argument.</p> <p>As a whole, the <tt>.cpp</tt> file looks like:</p> -<div class="doc_code"><pre> +<div class="doc_code"> +<pre> <b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>" <b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>" @@ -332,24 +350,26 @@ is supplied as fourth argument. </p> Hello() : FunctionPass(ID) {} <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { - errs() << "<i>Hello: </i>" << F.getName() << "\n"; + errs() << "<i>Hello: </i>"; + errs().write_escaped(F.getName()) << '\n'; <b>return false</b>; } + }; - - char Hello::ID = 0; - static RegisterPass<Hello> X("hello", "Hello World Pass", false, false); } - -</pre></div> + +char Hello::ID = 0; +static RegisterPass<Hello> X("hello", "Hello World Pass", false, false); +</pre> +</div> <p>Now that it's all together, compile the file with a simple "<tt>gmake</tt>" command in the local directory and you should get a new file "<tt>Debug+Asserts/lib/Hello.so</tt>" under the top level directory of the LLVM source tree (not in the local directory). Note that everything in this file is -contained in an anonymous namespace: this reflects the fact that passes are self -contained units that do not need external interfaces (although they can have -them) to be useful.</p> +contained in an anonymous namespace — this reflects the fact that passes +are self contained units that do not need external interfaces (although they can +have them) to be useful.</p> </div> @@ -1929,7 +1949,7 @@ Despite that, we have kept the LLVM passes SMP ready, and you should too.</p> <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-11 09:03:52 +0200 (Tue, 11 Oct 2011) $ </address> </body> diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index 45b8f42..bc4ab9f 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -1,4 +1,4 @@ -# Doxyfile 1.5.6 +# Doxyfile 1.7.1 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project @@ -11,214 +11,219 @@ # Values that contain spaces should be placed between quotes (" ") #--------------------------------------------------------------------------- -# Project related configuration options +# Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all -# text before the first occurrence of this tag. Doxygen uses libiconv (or the -# iconv built into libc) for the transcoding. See +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See # http://www.gnu.org/software/libiconv for the list of possible encodings. DOXYFILE_ENCODING = UTF-8 -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. PROJECT_NAME = LLVM -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or # if some version control system is used. PROJECT_NUMBER = @PACKAGE_VERSION@ -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. OUTPUT_DIRECTORY = @abs_top_builddir@/docs/doxygen -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would # otherwise cause performance problems for the file system. -CREATE_SUBDIRS = NO +CREATE_SUBDIRS = YES -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Farsi, Finnish, French, German, Greek, -# Hungarian, Italian, Japanese, Japanese-en (Japanese with English messages), -# Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, Polish, -# Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, -# and Ukrainian. +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). # Set to NO to disable this. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. REPEAT_BRIEF = YES -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" # "represents" "a" "an" "the" -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief # description. ALWAYS_DETAILED_SEC = NO -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set # to NO the shortest path that makes the file name unique will be used. FULL_PATH_NAMES = NO -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the # path to strip. STRIP_FROM_PATH = ../.. -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that # are normally passed to the compiler using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems # doesn't support long names like on DOS, Mac, or CD-ROM. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) JAVADOC_AUTOBRIEF = NO -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring # an explicit \brief command for a brief description.) QT_AUTOBRIEF = NO -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed # description. Set this tag to YES if you prefer the old behaviour instead. MULTILINE_CPP_IS_BRIEF = NO -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -DETAILS_AT_TOP = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it # re-implements. INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will # be part of the file/class/namespace that contains it. SEPARATE_MEMBER_PAGES = NO -# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# The TAB_SIZE tag can be used to set the number of spaces in a tab. # Doxygen uses this value to replace tabs by spaces in code fragments. TAB_SIZE = 2 -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = +ALIASES = -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list # of all members will be omitted, etc. OPTIMIZE_OUTPUT_FOR_C = NO -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified # scopes will look different, etc. OPTIMIZE_OUTPUT_JAVA = NO -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for # Fortran. OPTIMIZE_FOR_FORTRAN = NO -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for # VHDL. OPTIMIZE_OUTPUT_VHDL = NO -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. BUILTIN_STL_SUPPORT = NO @@ -228,414 +233,459 @@ BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public # instead of private inheritance when no explicit protection keyword is present. SIP_SUPPORT = NO -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen to replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the # methods anyway, you should set this option to NO. IDL_PROPERTY_SUPPORT = YES -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. DISTRIBUTE_GROUP_DOC = NO -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using # the \nosubgrouping command. SUBGROUPING = YES -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. TYPEDEF_HIDES_STRUCT = NO +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penality. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will rougly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES EXTRACT_ALL = YES -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. EXTRACT_PRIVATE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file +# If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. EXTRACT_STATIC = YES -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. # If set to NO (the default) only methods in the interface are included. EXTRACT_LOCAL_METHODS = NO -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default # anonymous namespace are hidden. EXTRACT_ANON_NSPACES = NO -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. # This option has no effect if EXTRACT_ALL is enabled. HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various # overviews. This option has no effect if EXTRACT_ALL is enabled. HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the # documentation. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the # function's detailed documentation block. HIDE_IN_BODY_DOCS = NO -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. # Set it to YES to include the internal documentation. INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the # documentation. If set to YES the scope will be hidden. HIDE_SCOPE_NAMES = NO -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation # of that file. SHOW_INCLUDE_FILES = YES -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] # is inserted in the documentation for inline members. INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in # declaration order. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in # declaration order. SORT_BRIEF_DOCS = NO -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) # the group names will appear in their defined order. SORT_GROUP_NAMES = NO -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the +# Note: This option applies only to the class list, not to the # alphabetical list. SORT_BY_SCOPE_NAME = NO -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo # commands in the documentation. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test # commands in the documentation. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug # commands in the documentation. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting # \deprecated commands in the documentation. GENERATE_DEPRECATEDLIST= YES -# The ENABLED_SECTIONS tag can be used to enable conditional +# The ENABLED_SECTIONS tag can be used to enable conditional # documentation sections, marked by \if sectionname ... \endif. -ENABLED_SECTIONS = +ENABLED_SECTIONS = -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer # command in the documentation regardless of this setting. MAX_INITIALIZER_LINES = 30 -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the # list will mention the files that were used to generate the documentation. SHOW_USED_FILES = YES -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy # in the documentation. The default is NO. SHOW_DIRECTORIES = YES # Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the +# This will remove the Files entry from the Quick Index and from the # Folder Tree View (if specified). The default is YES. SHOW_FILES = YES -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. This will remove the Namespaces entry from the Quick Index +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index # and from the Folder Tree View (if specified). The default is YES. SHOW_NAMESPACES = YES -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command <command> <input-file>, where <command> is the value of -# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file -# provided by doxygen. Whatever the program writes to standard output +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command <command> <input-file>, where <command> is the value of +# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file +# provided by doxygen. Whatever the program writes to standard output # is used as the file version. See the manual for examples. -FILE_VERSION_FILTER = +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- -# The QUIET tag can be used to turn on/off the messages that are generated +# The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. QUIET = NO -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank # NO is used. WARNINGS = NO -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. WARN_IF_UNDOCUMENTED = NO -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that # don't exist or using markup commands wrongly. WARN_IF_DOC_ERROR = YES -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of # documentation. WARN_NO_PARAMDOC = NO -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could # be obtained via FILE_VERSION_FILTER) -WARN_FORMAT = +WARN_FORMAT = -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written # to stderr. -WARN_LOGFILE = +WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories # with spaces. INPUT = @abs_top_srcdir@/include \ @abs_top_srcdir@/lib \ @abs_top_srcdir@/docs/doxygen.intro -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for # the list of possible encodings. INPUT_ENCODING = UTF-8 -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 -FILE_PATTERNS = +FILE_PATTERNS = -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. RECURSIVE = YES -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = +EXCLUDE = -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded # from the input. EXCLUDE_SYMLINKS = NO -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, # AClass::ANamespace, ANamespace::*Test -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see # the \include command). EXAMPLE_PATH = @abs_top_srcdir@/examples -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left # blank all files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. # Possible values are YES and NO. If left blank NO is used. EXAMPLE_RECURSIVE = YES -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see # the \image command). IMAGE_PATH = @abs_top_srcdir@/docs/img -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command <filter> <input-file>, where <filter> -# is the value of the INPUT_FILTER tag, and <input-file> is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be # ignored. -INPUT_FILTER = +INPUT_FILTER = -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER # is applied to all files. -FILTER_PATTERNS = +FILTER_PATTERNS = -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source # files to browse (i.e. when SOURCE_BROWSER is set to YES). FILTER_SOURCE_FILES = NO @@ -644,32 +694,32 @@ FILTER_SOURCE_FILES = NO # configuration options related to source browsing #--------------------------------------------------------------------------- -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also # VERBATIM_HEADERS is set to NO. SOURCE_BROWSER = YES -# Setting the INLINE_SOURCES tag to YES will include the body +# Setting the INLINE_SOURCES tag to YES will include the body # of functions and classes directly in the documentation. INLINE_SOURCES = NO -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code # fragments. Normal C and C++ comments will always remain visible. STRIP_CODE_COMMENTS = NO -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented # functions referencing it will be listed. REFERENCED_BY_RELATION = YES -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities # called/used by that function will be listed. REFERENCES_RELATION = YES @@ -677,20 +727,21 @@ REFERENCES_RELATION = YES # If the REFERENCES_LINK_SOURCE tag is set to YES (the default) # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from # functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. Otherwise they will link to the documentstion. +# link to the source code. +# Otherwise they will link to the documentation. REFERENCES_LINK_SOURCE = YES -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You # will need version 4.8.6 or higher. USE_HTAGS = NO -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for # which an include is specified. Set to NO to disable this. VERBATIM_HEADERS = YES @@ -699,21 +750,21 @@ VERBATIM_HEADERS = YES # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project # contains a lot of classes, structs, unions or interfaces. ALPHABETICAL_INDEX = YES -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns # in which this list will be split (can be a number in the range [1..20]) COLS_IN_ALPHA_INDEX = 4 -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that # should be ignored while generating the index headers. IGNORE_PREFIX = llvm:: @@ -722,106 +773,149 @@ IGNORE_PREFIX = llvm:: # configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will # generate HTML output. GENERATE_HTML = YES -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `html' will be used as the default path. HTML_OUTPUT = html -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank # doxygen will generate files with .html extension. HTML_FILE_EXTENSION = .html -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a # standard header. HTML_HEADER = @abs_top_srcdir@/docs/doxygen.header -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a # standard footer. HTML_FOOTER = @abs_top_srcdir@/docs/doxygen.footer -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own # stylesheet in the HTML output directory as well, or it will be erased! HTML_STYLESHEET = @abs_top_srcdir@/docs/doxygen.css -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the stylesheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to # NO a bullet list will be used. HTML_ALIGN_MEMBERS = YES -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). -GENERATE_HTMLHELP = NO +HTML_DYNAMIC_SECTIONS = NO -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find # it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. GENERATE_DOCSET = NO -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) # can be grouped. DOCSET_FEEDNAME = "Doxygen generated docs" -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen # will append .docset to the name. DOCSET_BUNDLE_ID = org.doxygen.Project -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. -HTML_DYNAMIC_SECTIONS = NO +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be # written to the html output directory. -CHM_FILE = +CHM_FILE = -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run # the HTML help compiler on the generated index.hhp. -HHC_LOCATION = +HHC_LOCATION = -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that # it should be included in the master .chm file (NO). GENERATE_CHI = NO @@ -830,203 +924,314 @@ GENERATE_CHI = NO # is used to encode HtmlHelp index (hhk), content (hhc) and project file # content. -CHM_INDEX_ENCODING = +CHM_INDEX_ENCODING = -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a # normal table of contents (NO) in the .chm file. BINARY_TOC = NO -# The TOC_EXPAND flag can be set to YES to add extra items for group members +# The TOC_EXPAND flag can be set to YES to add extra items for group members # to the contents of the HTML help documentation and to the tree view. TOC_EXPAND = NO -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> +# Qt Help Project / Custom Filters</a>. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> +# Qt Help Project / Filter Attributes</a>. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and # the value YES disables it. DISABLE_INDEX = NO -# This tag can be used to set the number of enum values (range [1..20]) +# This tag can be used to set the number of enum values (range [1..20]) # that doxygen will group on one line in the generated HTML documentation. ENUM_VALUES_PER_LINE = 4 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. -# If the tag value is set to FRAME, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. Other possible values -# for this tag are: HIERARCHIES, which will generate the Groups, Directories, -# and Class Hiererachy pages using a tree view instead of an ordered list; -# ALL, which combines the behavior of FRAME and HIERARCHIES; and NONE, which -# disables this behavior completely. For backwards compatibility with previous -# releases of Doxygen, the values YES and NO are equivalent to FRAME and NONE -# respectively. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. GENERATE_TREEVIEW = NO -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree # is shown. TREEVIEW_WIDTH = 250 -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory # to force them to be regenerated. FORMULA_FONTSIZE = 10 +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvances is that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + #--------------------------------------------------------------------------- # configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. GENERATE_LATEX = NO -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `latex' will be used as the default path. -LATEX_OUTPUT = +LATEX_OUTPUT = -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. LATEX_CMD_NAME = latex -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the # default command name. MAKEINDEX_CMD_NAME = makeindex -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to # save some trees in general. COMPACT_LATEX = NO -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and # executive. If left blank a4wide will be used. PAPER_TYPE = letter -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX # packages that should be included in the LaTeX output. -EXTRA_PACKAGES = +EXTRA_PACKAGES = -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a # standard header. Notice: only use this tag if you know what you are doing! -LATEX_HEADER = +LATEX_HEADER = -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references # This makes the output suitable for online browsing using a pdf viewer. PDF_HYPERLINKS = NO -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a # higher quality PDF documentation. USE_PDFLATEX = NO -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. # This option is also used when generating formulas in HTML. LATEX_BATCHMODE = NO -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) # in the output. LATEX_HIDE_INDICES = NO +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + #--------------------------------------------------------------------------- # configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with # other RTF readers or editors. GENERATE_RTF = NO -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `rtf' will be used as the default path. -RTF_OUTPUT = +RTF_OUTPUT = -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to # save some trees in general. COMPACT_RTF = NO -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. # Note: wordpad (write) and others do not support links. RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide # replacements, missing definitions are set to their default value. -RTF_STYLESHEET_FILE = +RTF_STYLESHEET_FILE = -# Set optional variables used in the generation of an rtf document. +# Set optional variables used in the generation of an rtf document. # Syntax is similar to doxygen's config file. -RTF_EXTENSIONS_FILE = +RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- # configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages GENERATE_MAN = NO -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `man' will be used as the default path. -MAN_OUTPUT = +MAN_OUTPUT = -# The MAN_EXTENSION tag determines the extension that is added to +# The MAN_EXTENSION tag determines the extension that is added to # the generated man pages (default is the subroutine's section .3) -MAN_EXTENSION = +MAN_EXTENSION = -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command # would be unable to find the correct page. The default is NO. MAN_LINKS = NO @@ -1035,33 +1240,33 @@ MAN_LINKS = NO # configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of # the code including all documentation. GENERATE_XML = NO -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `xml' will be used as the default path. XML_OUTPUT = xml -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the # syntax of the XML files. -XML_SCHEMA = +XML_SCHEMA = -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the # syntax of the XML files. -XML_DTD = +XML_DTD = -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that # enabling this will significantly increase the size of the XML output. XML_PROGRAMLISTING = YES @@ -1070,10 +1275,10 @@ XML_PROGRAMLISTING = YES # configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental # and incomplete at the moment. GENERATE_AUTOGEN_DEF = NO @@ -1082,338 +1287,346 @@ GENERATE_AUTOGEN_DEF = NO # configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the # moment. GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able # to generate PDF and DVI output from the Perl module output. PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller # and Perl will parse it just the same. PERLMOD_PRETTY = YES -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same # Makefile don't overwrite each other's variables. -PERLMOD_MAKEVAR_PREFIX = +PERLMOD_MAKEVAR_PREFIX = #--------------------------------------------------------------------------- -# Configuration options related to the preprocessor +# Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include # files. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. MACRO_EXPANSION = NO -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. SEARCH_INCLUDES = YES -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by # the preprocessor. INCLUDE_PATH = ../include -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will # be used. -INCLUDE_FILE_PATTERNS = +INCLUDE_FILE_PATTERNS = -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. # Use the PREDEFINED tag if you want to use a different macro definition. -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse # the parser if not removed. SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration::additions related to external references #--------------------------------------------------------------------------- -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool # does not have to be run to correct the links. # Note that each tag file must have a unique name # (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen +# If a tag file is not located in the directory in which doxygen # is run, you must also specify the path to the tagfile here. -TAGFILES = +TAGFILES = -# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. -GENERATE_TAGFILE = +GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes # will be listed. ALLEXTERNALS = YES -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will # be listed. EXTERNAL_GROUPS = YES -# The PERL_PATH should be the absolute path and name of the perl script +# The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). -PERL_PATH = +PERL_PATH = #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more # powerful graphs. CLASS_DIAGRAMS = YES -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see -# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the # default search path. -MSCGEN_PATH = +MSCGEN_PATH = -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented # or is not a class. HIDE_UNDOC_RELATIONS = NO -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) HAVE_DOT = YES -# By default doxygen will write a font called FreeSans.ttf to the output -# directory and reference it in all dot files that doxygen generates. This -# font does not include all possible unicode characters however, so when you need -# these (or just want a differently looking font) you can specify the font name -# using DOT_FONTNAME. You need need to make sure dot is able to find the font, -# which can be done by putting it in a standard location or by setting the -# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory # containing the font. DOT_FONTNAME = FreeSans -# By default doxygen will tell dot to use the output directory to look for the -# FreeSans.ttf font (which doxygen will put there itself). If you specify a -# different font using DOT_FONTNAME you can set the path where dot +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot # can find it using this tag. -DOT_FONTPATH = +DOT_FONTPATH = -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the # the CLASS_DIAGRAMS tag to NO. CLASS_GRAPH = YES -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and # class references variables) of the class with other documented classes. COLLABORATION_GRAPH = YES -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen # will generate a graph for groups, showing the direct groups dependencies GROUP_GRAPHS = YES -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. UML_LOOK = NO -# If set to YES, the inheritance and collaboration graphs will show the +# If set to YES, the inheritance and collaboration graphs will show the # relations between templates and their instances. TEMPLATE_RELATIONS = YES -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with # other documented files. INCLUDE_GRAPH = YES -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or # indirectly include this file. INCLUDED_BY_GRAPH = YES -# If the CALL_GRAPH and HAVE_DOT options are set to YES then -# doxygen will generate a call dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable call graphs +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs # for selected functions only using the \callgraph command. CALL_GRAPH = NO -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then -# doxygen will generate a caller dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable caller +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller # graphs for selected functions only using the \callergraph command. CALLER_GRAPH = NO -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen # will graphical hierarchy of all classes instead of a textual one. GRAPHICAL_HIERARCHY = YES -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories # in a graphical way. The dependency relations are determined by the #include # relations between the files in the directories. DIRECTORY_GRAPH = YES -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. Possible values are png, jpg, or gif # If left blank png will be used. DOT_IMAGE_FORMAT = png -# The tag DOT_PATH can be used to specify the path where the dot tool can be +# The tag DOT_PATH can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. DOT_PATH = @DOT@ -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the # \dotfile command). -DOTFILE_DIRS = +DOTFILE_DIRS = -# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the -# number of direct children of the root node in a graph is already larger than -# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note # that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. DOT_GRAPH_MAX_NODES = 50 -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by # DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is enabled by default, which results in a transparent -# background. Warning: Depending on the platform used, enabling this option -# may lead to badly anti-aliased labels on the edges of a graph (i.e. they -# become hard to read). +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). DOT_TRANSPARENT = YES -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) # support this, this feature is disabled by default. DOT_MULTI_TARGETS = NO -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and # arrows in the dot generated graphs. GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate # the various graphs. DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/docs/index.html b/docs/index.html index fc43569..e22d991 100644 --- a/docs/index.html +++ b/docs/index.html @@ -63,6 +63,11 @@ Discusses how to get up and running quickly with the LLVM infrastructure. Everything from unpacking and compilation of the distribution to execution of some tools.</li> +<li><a href="CMake.html">LLVM CMake guide</a> - An addendum to the main Getting +Started guide for those using the <a href="http://www.cmake.org/">CMake build +system</a>. +</li> + <li><a href="GettingStartedVS.html">Getting Started with the LLVM System using Microsoft Visual Studio</a> - An addendum to the main Getting Started guide for those using Visual Studio on Windows.</li> @@ -87,7 +92,6 @@ Current tools: <a href="/cmds/opt.html">opt</a>, <a href="/cmds/llc.html">llc</a>, <a href="/cmds/lli.html">lli</a>, - <a href="/cmds/llvmc.html">llvmc</a> <a href="/cmds/llvmgcc.html">llvm-gcc</a>, <a href="/cmds/llvmgxx.html">llvm-g++</a>, <a href="/cmds/bugpoint.html">bugpoint</a>, @@ -216,14 +220,6 @@ in LLVM.</li> <li><a href="Bugpoint.html">Bugpoint</a> - automatic bug finder and test-case reducer description and usage information.</li> -<li><a href="CompilerDriverTutorial.html">Compiler Driver (llvmc) Tutorial</a> -- This document is a tutorial introduction to the usage and -configuration of the LLVM compiler driver tool, <tt>llvmc</tt>.</li> - -<li><a href="CompilerDriver.html">Compiler Driver (llvmc) -Reference</a> - This document describes the design and configuration -of <tt>llvmc</tt> in more detail.</li> - <li><a href="BitCodeFormat.html">LLVM Bitcode File Format</a> - This describes the file format and encoding used for LLVM "bc" files.</li> @@ -289,7 +285,7 @@ times each day, making it a high volume list.</li> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-07-06 20:31:02 +0200 (Wed, 06 Jul 2011) $ + Last modified: $Date: 2011-10-11 18:35:07 +0200 (Tue, 11 Oct 2011) $ </address> </body></html> diff --git a/docs/llvm.css b/docs/llvm.css index 1222cf1..e3e6351 100644 --- a/docs/llvm.css +++ b/docs/llvm.css @@ -70,6 +70,14 @@ h4, .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em; display: table; } +blockquote pre { + padding: 1em 2em 1em 1em; + border: solid 1px gray; + background: #eeeeee; + margin: 0 1em 0 1em; + display: table; +} + h2+div, h2+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} h3+div, h3+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} h4+div, h4+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} diff --git a/docs/tutorial/LangImpl2.html b/docs/tutorial/LangImpl2.html index c6a9bb1..2696d86 100644 --- a/docs/tutorial/LangImpl2.html +++ b/docs/tutorial/LangImpl2.html @@ -801,10 +801,10 @@ course.) To build this, just compile with:</p> <div class="doc_code"> <pre> - # Compile - g++ -g -O3 toy.cpp - # Run - ./a.out +# Compile +clang++ -g -O3 toy.cpp +# Run +./a.out </pre> </div> @@ -1225,7 +1225,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html index 47406ca..c9517a0 100644 --- a/docs/tutorial/LangImpl3.html +++ b/docs/tutorial/LangImpl3.html @@ -266,7 +266,7 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } </pre> </div> @@ -308,11 +308,11 @@ bodies and external function declarations. The code starts with:</p> <pre> Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); - + Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); </pre> </div> @@ -532,9 +532,9 @@ functions. For example: <pre> ready> <b>4+5</b>; Read top-level expression: -define double @""() { +define double @0() { entry: - ret double 9.000000e+00 + ret double 9.000000e+00 } </pre> </div> @@ -553,13 +553,13 @@ ready> <b>def foo(a b) a*a + 2*a*b + b*b;</b> Read function definition: define double @foo(double %a, double %b) { entry: - %multmp = fmul double %a, %a - %multmp1 = fmul double 2.000000e+00, %a - %multmp2 = fmul double %multmp1, %b - %addtmp = fadd double %multmp, %multmp2 - %multmp3 = fmul double %b, %b - %addtmp4 = fadd double %addtmp, %multmp3 - ret double %addtmp4 + %multmp = fmul double %a, %a + %multmp1 = fmul double 2.000000e+00, %a + %multmp2 = fmul double %multmp1, %b + %addtmp = fadd double %multmp, %multmp2 + %multmp3 = fmul double %b, %b + %addtmp4 = fadd double %addtmp, %multmp3 + ret double %addtmp4 } </pre> </div> @@ -573,10 +573,10 @@ ready> <b>def bar(a) foo(a, 4.0) + bar(31337);</b> Read function definition: define double @bar(double %a) { entry: - %calltmp = call double @foo(double %a, double 4.000000e+00) - %calltmp1 = call double @bar(double 3.133700e+04) - %addtmp = fadd double %calltmp, %calltmp1 - ret double %addtmp + %calltmp = call double @foo(double %a, double 4.000000e+00) + %calltmp1 = call double @bar(double 3.133700e+04) + %addtmp = fadd double %calltmp, %calltmp1 + ret double %addtmp } </pre> </div> @@ -593,10 +593,10 @@ declare double @cos(double) ready> <b>cos(1.234);</b> Read top-level expression: -define double @""() { +define double @1() { entry: - %calltmp = call double @cos(double 1.234000e+00) - ret double %calltmp + %calltmp = call double @cos(double 1.234000e+00) + ret double %calltmp } </pre> </div> @@ -609,37 +609,37 @@ entry: ready> <b>^D</b> ; ModuleID = 'my cool jit' -define double @""() { +define double @0() { entry: - %addtmp = fadd double 4.000000e+00, 5.000000e+00 - ret double %addtmp + %addtmp = fadd double 4.000000e+00, 5.000000e+00 + ret double %addtmp } define double @foo(double %a, double %b) { entry: - %multmp = fmul double %a, %a - %multmp1 = fmul double 2.000000e+00, %a - %multmp2 = fmul double %multmp1, %b - %addtmp = fadd double %multmp, %multmp2 - %multmp3 = fmul double %b, %b - %addtmp4 = fadd double %addtmp, %multmp3 - ret double %addtmp4 + %multmp = fmul double %a, %a + %multmp1 = fmul double 2.000000e+00, %a + %multmp2 = fmul double %multmp1, %b + %addtmp = fadd double %multmp, %multmp2 + %multmp3 = fmul double %b, %b + %addtmp4 = fadd double %addtmp, %multmp3 + ret double %addtmp4 } define double @bar(double %a) { entry: - %calltmp = call double @foo(double %a, double 4.000000e+00) - %calltmp1 = call double @bar(double 3.133700e+04) - %addtmp = fadd double %calltmp, %calltmp1 - ret double %addtmp + %calltmp = call double @foo(double %a, double 4.000000e+00) + %calltmp1 = call double @bar(double 3.133700e+04) + %addtmp = fadd double %calltmp, %calltmp1 + ret double %addtmp } declare double @cos(double) -define double @""() { +define double @1() { entry: - %calltmp = call double @cos(double 1.234000e+00) - ret double %calltmp + %calltmp = call double @cos(double 1.234000e+00) + ret double %calltmp } </pre> </div> @@ -670,10 +670,10 @@ our makefile/command line about which options to use:</p> <div class="doc_code"> <pre> - # Compile - g++ -g -O3 toy.cpp `llvm-config --cppflags --ldflags --libs core` -o toy - # Run - ./toy +# Compile +clang++ -g -O3 toy.cpp `llvm-config --cppflags --ldflags --libs core` -o toy +# Run +./toy </pre> </div> @@ -1081,13 +1081,13 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); @@ -1262,7 +1262,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html index 5b8990e4..e910cc1 100644 --- a/docs/tutorial/LangImpl4.html +++ b/docs/tutorial/LangImpl4.html @@ -343,9 +343,10 @@ code that is statically linked into your application.</p> <div class="doc_code"> <pre> ready> <b>4+5;</b> -define double @""() { +Read top-level expression: +define double @0() { entry: - ret double 9.000000e+00 + ret double 9.000000e+00 } <em>Evaluated to 9.000000</em> @@ -363,16 +364,17 @@ ready> <b>def testfunc(x y) x + y*2; </b> Read function definition: define double @testfunc(double %x, double %y) { entry: - %multmp = fmul double %y, 2.000000e+00 - %addtmp = fadd double %multmp, %x - ret double %addtmp + %multmp = fmul double %y, 2.000000e+00 + %addtmp = fadd double %multmp, %x + ret double %addtmp } ready> <b>testfunc(4, 10);</b> -define double @""() { +Read top-level expression: +define double @1() { entry: - %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01) - ret double %calltmp + %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01) + ret double %calltmp } <em>Evaluated to 24.000000</em> @@ -404,21 +406,34 @@ Read extern: declare double @cos(double) ready> <b>sin(1.0);</b> +Read top-level expression: +define double @2() { +entry: + ret double 0x3FEAED548F090CEE +} + <em>Evaluated to 0.841471</em> ready> <b>def foo(x) sin(x)*sin(x) + cos(x)*cos(x);</b> Read function definition: define double @foo(double %x) { entry: - %calltmp = call double @sin(double %x) - %multmp = fmul double %calltmp, %calltmp - %calltmp2 = call double @cos(double %x) - %multmp4 = fmul double %calltmp2, %calltmp2 - %addtmp = fadd double %multmp, %multmp4 - ret double %addtmp + %calltmp = call double @sin(double %x) + %multmp = fmul double %calltmp, %calltmp + %calltmp2 = call double @cos(double %x) + %multmp4 = fmul double %calltmp2, %calltmp2 + %addtmp = fadd double %multmp, %multmp4 + ret double %addtmp } ready> <b>foo(4.0);</b> +Read top-level expression: +define double @3() { +entry: + %calltmp = call double @foo(double 4.000000e+00) + ret double %calltmp +} + <em>Evaluated to 1.000000</em> </pre> </div> @@ -484,10 +499,10 @@ LLVM JIT and optimizer. To build this example, use: <div class="doc_code"> <pre> - # Compile - g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy - # Run - ./toy +# Compile +clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy +# Run +./toy </pre> </div> @@ -509,9 +524,9 @@ at runtime.</p> #include "llvm/Analysis/Verifier.h" #include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" -#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" +#include "llvm/Support/TargetSelect.h" #include <cstdio> #include <string> #include <map> @@ -905,13 +920,13 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); @@ -1013,6 +1028,9 @@ static void HandleTopLevelExpression() { // Evaluate a top-level expression into an anonymous function. if (FunctionAST *F = ParseTopLevelExpr()) { if (Function *LF = F->Codegen()) { + fprintf(stderr, "Read top-level expression:"); + LF->dump(); + // JIT the function, returning a function pointer. void *FPtr = TheExecutionEngine->getPointerToFunction(LF); @@ -1076,7 +1094,7 @@ int main() { // Create the JIT. This takes ownership of the module. std::string ErrStr; -TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); + TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); if (!TheExecutionEngine) { fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str()); exit(1); @@ -1129,7 +1147,7 @@ TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html index 4fc23a1..95144dc 100644 --- a/docs/tutorial/LangImpl5.html +++ b/docs/tutorial/LangImpl5.html @@ -259,20 +259,20 @@ declare double @bar() define double @baz(double %x) { entry: - %ifcond = fcmp one double %x, 0.000000e+00 - br i1 %ifcond, label %then, label %else + %ifcond = fcmp one double %x, 0.000000e+00 + br i1 %ifcond, label %then, label %else then: ; preds = %entry - %calltmp = call double @foo() - br label %ifcont + %calltmp = call double @foo() + br label %ifcont else: ; preds = %entry - %calltmp1 = call double @bar() - br label %ifcont + %calltmp1 = call double @bar() + br label %ifcont ifcont: ; preds = %else, %then - %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ] - ret double %iftmp + %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ] + ret double %iftmp } </pre> </div> @@ -660,25 +660,25 @@ declare double @putchard(double) define double @printstar(double %n) { entry: - ; initial value = 1.0 (inlined into phi) - br label %loop + ; initial value = 1.0 (inlined into phi) + br label %loop loop: ; preds = %loop, %entry - %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ] - ; body - %calltmp = call double @putchard(double 4.200000e+01) - ; increment - %nextvar = fadd double %i, 1.000000e+00 - - ; termination test - %cmptmp = fcmp ult double %i, %n - %booltmp = uitofp i1 %cmptmp to double - %loopcond = fcmp one double %booltmp, 0.000000e+00 - br i1 %loopcond, label %loop, label %afterloop + %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ] + ; body + %calltmp = call double @putchard(double 4.200000e+01) + ; increment + %nextvar = fadd double %i, 1.000000e+00 + + ; termination test + %cmptmp = fcmp ult double %i, %n + %booltmp = uitofp i1 %cmptmp to double + %loopcond = fcmp one double %booltmp, 0.000000e+00 + br i1 %loopcond, label %loop, label %afterloop afterloop: ; preds = %loop - ; loop always returns 0.0 - ret double 0.000000e+00 + ; loop always returns 0.0 + ret double 0.000000e+00 } </pre> </div> @@ -829,10 +829,11 @@ statement.</p> </div> <p>With the code for the body of the loop complete, we just need to finish up -the control flow for it. This code remembers the end block (for the phi node), then creates the block for the loop exit ("afterloop"). Based on the value of the -exit condition, it creates a conditional branch that chooses between executing -the loop again and exiting the loop. Any future code is emitted in the -"afterloop" block, so it sets the insertion position to it.</p> +the control flow for it. This code remembers the end block (for the phi node), +then creates the block for the loop exit ("afterloop"). Based on the value of +the exit condition, it creates a conditional branch that chooses between +executing the loop again and exiting the loop. Any future code is emitted in +the "afterloop" block, so it sets the insertion position to it.</p> <div class="doc_code"> <pre> @@ -880,10 +881,10 @@ if/then/else and for expressions.. To build this example, use: <div class="doc_code"> <pre> - # Compile - g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy - # Run - ./toy +# Compile +clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy +# Run +./toy </pre> </div> @@ -900,9 +901,9 @@ if/then/else and for expressions.. To build this example, use: #include "llvm/Analysis/Verifier.h" #include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" -#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" +#include "llvm/Support/TargetSelect.h" #include <cstdio> #include <string> #include <map> @@ -1397,7 +1398,7 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } Value *IfExprAST::Codegen() { @@ -1546,8 +1547,8 @@ Value *ForExprAST::Codegen() { Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); @@ -1765,7 +1766,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html index 31d7ff4..8876e83 100644 --- a/docs/tutorial/LangImpl6.html +++ b/docs/tutorial/LangImpl6.html @@ -293,8 +293,8 @@ Value *BinaryExprAST::Codegen() { Function *F = TheModule->getFunction(std::string("binary")+Op); assert(F && "binary operator not found!"); - Value *Ops[] = { L, R }; - return Builder.CreateCall(F, Ops, Ops+2, "binop");</b> + Value *Ops[2] = { L, R }; + return Builder.CreateCall(F, Ops, "binop");</b> } </pre> @@ -505,7 +505,9 @@ defined to print out the specified value and a newline):</p> <div class="doc_code"> <pre> ready> <b>extern printd(x);</b> -Read extern: declare double @printd(double) +Read extern: +declare double @printd(double) + ready> <b>def binary : 1 (x y) 0; # Low-precedence operator that ignores operands.</b> .. ready> <b>printd(123) : printd(456) : printd(789);</b> @@ -555,6 +557,9 @@ def binary& 6 (LHS RHS) def binary = 9 (LHS RHS) !(LHS < RHS | LHS > RHS); +# Define ':' for sequencing: as a low-precedence operator that ignores operands +# and just returns the RHS. +def binary : 1 (x y) y; </pre> </div> @@ -579,9 +584,10 @@ def printdensity(d) else putchard(42); # '*'</b> ... -ready> <b>printdensity(1): printdensity(2): printdensity(3) : - printdensity(4): printdensity(5): printdensity(9): putchard(10);</b> -*++.. +ready> <b>printdensity(1): printdensity(2): printdensity(3): + printdensity(4): printdensity(5): printdensity(9): + putchard(10);</b> +**++. Evaluated to 0.000000 </pre> </div> @@ -593,7 +599,7 @@ converge:</p> <div class="doc_code"> <pre> -# determine whether the specific location diverges. +# Determine whether the specific location diverges. # Solve for z = z^2 + c in the complex plane. def mandleconverger(real imag iters creal cimag) if iters > 255 | (real*real + imag*imag > 4) then @@ -603,25 +609,25 @@ def mandleconverger(real imag iters creal cimag) 2*real*imag + cimag, iters+1, creal, cimag); -# return the number of iterations required for the iteration to escape +# Return the number of iterations required for the iteration to escape def mandleconverge(real imag) mandleconverger(real, imag, 0, real, imag); </pre> </div> -<p>This "z = z<sup>2</sup> + c" function is a beautiful little creature that is the basis -for computation of the <a -href="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot Set</a>. Our -<tt>mandelconverge</tt> function returns the number of iterations that it takes -for a complex orbit to escape, saturating to 255. This is not a very useful -function by itself, but if you plot its value over a two-dimensional plane, -you can see the Mandelbrot set. Given that we are limited to using putchard -here, our amazing graphical output is limited, but we can whip together +<p>This "<code>z = z<sup>2</sup> + c</code>" function is a beautiful little +creature that is the basis for computation of +the <a href="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot Set</a>. +Our <tt>mandelconverge</tt> function returns the number of iterations that it +takes for a complex orbit to escape, saturating to 255. This is not a very +useful function by itself, but if you plot its value over a two-dimensional +plane, you can see the Mandelbrot set. Given that we are limited to using +putchard here, our amazing graphical output is limited, but we can whip together something using the density plotter above:</p> <div class="doc_code"> <pre> -# compute and plot the mandlebrot set with the specified 2 dimensional range +# Compute and plot the mandlebrot set with the specified 2 dimensional range # info. def mandelhelp(xmin xmax xstep ymin ymax ystep) for y = ymin, y < ymax, ystep in ( @@ -808,13 +814,19 @@ if/then/else and for expressions.. To build this example, use: <div class="doc_code"> <pre> - # Compile - g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy - # Run - ./toy +# Compile +clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy +# Run +./toy </pre> </div> +<p>On some platforms, you will need to specify -rdynamic or -Wl,--export-dynamic +when linking. This ensures that symbols defined in the main executable are +exported to the dynamic linker and so are available for symbol resolution at +run time. This is not needed if you compile your support code into a shared +library, although doing that will cause problems on Windows.</p> + <p>Here is the code:</p> <div class="doc_code"> @@ -828,9 +840,9 @@ if/then/else and for expressions.. To build this example, use: #include "llvm/Analysis/Verifier.h" #include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" -#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" +#include "llvm/Support/TargetSelect.h" #include <cstdio> #include <string> #include <map> @@ -1409,8 +1421,8 @@ Value *BinaryExprAST::Codegen() { Function *F = TheModule->getFunction(std::string("binary")+Op); assert(F && "binary operator not found!"); - Value *Ops[] = { L, R }; - return Builder.CreateCall(F, Ops, Ops+2, "binop"); + Value *Ops[2] = { L, R }; + return Builder.CreateCall(F, Ops, "binop"); } Value *CallExprAST::Codegen() { @@ -1429,7 +1441,7 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } Value *IfExprAST::Codegen() { @@ -1578,8 +1590,8 @@ Value *ForExprAST::Codegen() { Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); @@ -1811,7 +1823,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html index a4a21f1..939987b 100644 --- a/docs/tutorial/LangImpl7.html +++ b/docs/tutorial/LangImpl7.html @@ -102,19 +102,19 @@ The LLVM IR that we want for this example looks like this:</p> define i32 @test(i1 %Condition) { entry: - br i1 %Condition, label %cond_true, label %cond_false + br i1 %Condition, label %cond_true, label %cond_false cond_true: - %X.0 = load i32* @G - br label %cond_next + %X.0 = load i32* @G + br label %cond_next cond_false: - %X.1 = load i32* @H - br label %cond_next + %X.1 = load i32* @H + br label %cond_next cond_next: - %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ] - ret i32 %X.2 + %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ] + ret i32 %X.2 } </pre> </div> @@ -174,12 +174,12 @@ being declared with global variable definitions, they are declared with the <pre> define i32 @example() { entry: - %X = alloca i32 ; type of %X is i32*. - ... - %tmp = load i32* %X ; load the stack value %X from the stack. - %tmp2 = add i32 %tmp, 1 ; increment it - store i32 %tmp2, i32* %X ; store it back - ... + %X = alloca i32 ; type of %X is i32*. + ... + %tmp = load i32* %X ; load the stack value %X from the stack. + %tmp2 = add i32 %tmp, 1 ; increment it + store i32 %tmp2, i32* %X ; store it back + ... </pre> </div> @@ -196,22 +196,22 @@ example to use the alloca technique to avoid using a PHI node:</p> define i32 @test(i1 %Condition) { entry: - %X = alloca i32 ; type of %X is i32*. - br i1 %Condition, label %cond_true, label %cond_false + %X = alloca i32 ; type of %X is i32*. + br i1 %Condition, label %cond_true, label %cond_false cond_true: - %X.0 = load i32* @G - store i32 %X.0, i32* %X ; Update X - br label %cond_next + %X.0 = load i32* @G + store i32 %X.0, i32* %X ; Update X + br label %cond_next cond_false: - %X.1 = load i32* @H - store i32 %X.1, i32* %X ; Update X - br label %cond_next + %X.1 = load i32* @H + store i32 %X.1, i32* %X ; Update X + br label %cond_next cond_next: - %X.2 = load i32* %X ; Read X - ret i32 %X.2 + %X.2 = load i32* %X ; Read X + ret i32 %X.2 } </pre> </div> @@ -242,19 +242,19 @@ $ <b>llvm-as < example.ll | opt -mem2reg | llvm-dis</b> define i32 @test(i1 %Condition) { entry: - br i1 %Condition, label %cond_true, label %cond_false + br i1 %Condition, label %cond_true, label %cond_false cond_true: - %X.0 = load i32* @G - br label %cond_next + %X.0 = load i32* @G + br label %cond_next cond_false: - %X.1 = load i32* @H - br label %cond_next + %X.1 = load i32* @H + br label %cond_next cond_next: - %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ] - ret i32 %X.01 + %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ] + ret i32 %X.01 } </pre> </div> @@ -542,30 +542,30 @@ recursive fib function. Before the optimization:</p> <pre> define double @fib(double %x) { entry: - <b>%x1 = alloca double - store double %x, double* %x1 - %x2 = load double* %x1</b> - %cmptmp = fcmp ult double %x2, 3.000000e+00 - %booltmp = uitofp i1 %cmptmp to double - %ifcond = fcmp one double %booltmp, 0.000000e+00 - br i1 %ifcond, label %then, label %else + <b>%x1 = alloca double + store double %x, double* %x1 + %x2 = load double* %x1</b> + %cmptmp = fcmp ult double %x2, 3.000000e+00 + %booltmp = uitofp i1 %cmptmp to double + %ifcond = fcmp one double %booltmp, 0.000000e+00 + br i1 %ifcond, label %then, label %else then: ; preds = %entry - br label %ifcont + br label %ifcont else: ; preds = %entry - <b>%x3 = load double* %x1</b> - %subtmp = fsub double %x3, 1.000000e+00 - %calltmp = call double @fib(double %subtmp) - <b>%x4 = load double* %x1</b> - %subtmp5 = fsub double %x4, 2.000000e+00 - %calltmp6 = call double @fib(double %subtmp5) - %addtmp = fadd double %calltmp, %calltmp6 - br label %ifcont + <b>%x3 = load double* %x1</b> + %subtmp = fsub double %x3, 1.000000e+00 + %calltmp = call double @fib(double %subtmp) + <b>%x4 = load double* %x1</b> + %subtmp5 = fsub double %x4, 2.000000e+00 + %calltmp6 = call double @fib(double %subtmp5) + %addtmp = fadd double %calltmp, %calltmp6 + br label %ifcont ifcont: ; preds = %else, %then - %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ] - ret double %iftmp + %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ] + ret double %iftmp } </pre> </div> @@ -584,25 +584,25 @@ PHI node for it, so we still just make the PHI.</p> <pre> define double @fib(double %x) { entry: - %cmptmp = fcmp ult double <b>%x</b>, 3.000000e+00 - %booltmp = uitofp i1 %cmptmp to double - %ifcond = fcmp one double %booltmp, 0.000000e+00 - br i1 %ifcond, label %then, label %else + %cmptmp = fcmp ult double <b>%x</b>, 3.000000e+00 + %booltmp = uitofp i1 %cmptmp to double + %ifcond = fcmp one double %booltmp, 0.000000e+00 + br i1 %ifcond, label %then, label %else then: - br label %ifcont + br label %ifcont else: - %subtmp = fsub double <b>%x</b>, 1.000000e+00 - %calltmp = call double @fib(double %subtmp) - %subtmp5 = fsub double <b>%x</b>, 2.000000e+00 - %calltmp6 = call double @fib(double %subtmp5) - %addtmp = fadd double %calltmp, %calltmp6 - br label %ifcont + %subtmp = fsub double <b>%x</b>, 1.000000e+00 + %calltmp = call double @fib(double %subtmp) + %subtmp5 = fsub double <b>%x</b>, 2.000000e+00 + %calltmp6 = call double @fib(double %subtmp5) + %addtmp = fadd double %calltmp, %calltmp6 + br label %ifcont ifcont: ; preds = %else, %then - %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ] - ret double %iftmp + %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ] + ret double %iftmp } </pre> </div> @@ -617,21 +617,21 @@ such blatent inefficiencies :).</p> <pre> define double @fib(double %x) { entry: - %cmptmp = fcmp ult double %x, 3.000000e+00 - %booltmp = uitofp i1 %cmptmp to double - %ifcond = fcmp ueq double %booltmp, 0.000000e+00 - br i1 %ifcond, label %else, label %ifcont + %cmptmp = fcmp ult double %x, 3.000000e+00 + %booltmp = uitofp i1 %cmptmp to double + %ifcond = fcmp ueq double %booltmp, 0.000000e+00 + br i1 %ifcond, label %else, label %ifcont else: - %subtmp = fsub double %x, 1.000000e+00 - %calltmp = call double @fib(double %subtmp) - %subtmp5 = fsub double %x, 2.000000e+00 - %calltmp6 = call double @fib(double %subtmp5) - %addtmp = fadd double %calltmp, %calltmp6 - ret double %addtmp + %subtmp = fsub double %x, 1.000000e+00 + %calltmp = call double @fib(double %subtmp) + %subtmp5 = fsub double %x, 2.000000e+00 + %calltmp6 = call double @fib(double %subtmp5) + %addtmp = fadd double %calltmp, %calltmp6 + ret double %addtmp ifcont: - ret double 1.000000e+00 + ret double 1.000000e+00 } </pre> </div> @@ -988,10 +988,10 @@ variables and var/in support. To build this example, use: <div class="doc_code"> <pre> - # Compile - g++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy - # Run - ./toy +# Compile +clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy +# Run +./toy </pre> </div> @@ -1008,9 +1008,9 @@ variables and var/in support. To build this example, use: #include "llvm/Analysis/Verifier.h" #include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" -#include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" #include "llvm/Support/IRBuilder.h" +#include "llvm/Support/TargetSelect.h" #include <cstdio> #include <string> #include <map> @@ -1686,8 +1686,8 @@ Value *BinaryExprAST::Codegen() { Function *F = TheModule->getFunction(std::string("binary")+Op); assert(F && "binary operator not found!"); - Value *Ops[] = { L, R }; - return Builder.CreateCall(F, Ops, Ops+2, "binop"); + Value *Ops[2] = { L, R }; + return Builder.CreateCall(F, Ops, "binop"); } Value *CallExprAST::Codegen() { @@ -1706,7 +1706,7 @@ Value *CallExprAST::Codegen() { if (ArgsV.back() == 0) return 0; } - return Builder.CreateCall(CalleeF, ArgsV.begin(), ArgsV.end(), "calltmp"); + return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); } Value *IfExprAST::Codegen() { @@ -1907,8 +1907,8 @@ Value *VarExprAST::Codegen() { Function *PrototypeAST::Codegen() { // Make the function type: double(double,double) etc. - std::vector<const Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); + std::vector<Type*> Doubles(Args.size(), + Type::getDoubleTy(getGlobalContext())); FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), Doubles, false); @@ -2158,7 +2158,7 @@ int main() { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/Makefile b/docs/tutorial/Makefile index 9082ad4..fdf1bb6 100644 --- a/docs/tutorial/Makefile +++ b/docs/tutorial/Makefile @@ -11,6 +11,7 @@ LEVEL := ../.. include $(LEVEL)/Makefile.common HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) +PNG := $(wildcard $(PROJ_SRC_DIR)/*.png) EXTRA_DIST := $(HTML) index.html HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/tutorial @@ -18,6 +19,7 @@ install-local:: $(HTML) $(Echo) Installing HTML Tutorial Documentation $(Verb) $(MKDIR) $(HTML_DIR) $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) + $(Verb) $(DataInstall) $(PNG) $(HTML_DIR) $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/index.html $(HTML_DIR) uninstall-local:: |
