diff options
Diffstat (limited to 'docs')
58 files changed, 4048 insertions, 2714 deletions
diff --git a/docs/AliasAnalysis.html b/docs/AliasAnalysis.html index e65279c..c59f60d 100644 --- a/docs/AliasAnalysis.html +++ b/docs/AliasAnalysis.html @@ -418,9 +418,8 @@ implementing, you just override the interfaces you can improve.</p> <div> -<p>With only two special exceptions (the <tt><a -href="#basic-aa">basicaa</a></tt> and <a href="#no-aa"><tt>no-aa</tt></a> -passes) every alias analysis pass chains to another alias analysis +<p>With only one special exception (the <a href="#no-aa"><tt>no-aa</tt></a> +pass) every alias analysis pass chains to another alias analysis implementation (for example, the user can specify "<tt>-basicaa -ds-aa -licm</tt>" to get the maximum benefit from both alias analyses). The alias analysis class automatically takes care of most of this @@ -1061,7 +1060,7 @@ analysis directly.</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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-01-31 00:05:41 +0100 (Tue, 31 Jan 2012) $ </address> </body> diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html index a1de242..d9cce0b 100644 --- a/docs/Bugpoint.html +++ b/docs/Bugpoint.html @@ -232,7 +232,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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> diff --git a/docs/CFEBuildInstrs.html b/docs/CFEBuildInstrs.html deleted file mode 100644 index ab10844..0000000 --- a/docs/CFEBuildInstrs.html +++ /dev/null @@ -1,29 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> - <link rel="stylesheet" href="llvm.css" type="text/css" media="screen"> - <title>Building the LLVM C/C++ Front-End</title> - <meta HTTP-EQUIV="REFRESH" CONTENT="3; URL=GCCFEBuildInstrs.html"> -</head> -<body> -<div class="doc_title"> -This page has moved <a href="GCCFEBuildInstrs.html">here</A>. -</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: 2008-02-13 17:46:10 +0100 (Wed, 13 Feb 2008) $ -</address> - -</body> -</html> diff --git a/docs/CMake.html b/docs/CMake.html index feb1db0..acc7fe9 100644 --- a/docs/CMake.html +++ b/docs/CMake.html @@ -145,7 +145,7 @@ text. Generator's names are case-sensitive. Example:</p> <div class="doc_code"> - <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p> + <p><tt>cmake -G "Visual Studio 9 2008" path/to/llvm/source/root</tt></p> </div> <p>For a given development platform there can be more than one @@ -250,7 +250,7 @@ <dd>Semicolon-separated list of targets to build, or <i>all</i> for building all targets. Case-sensitive. For Visual C++ defaults to <i>X86</i>. On the other cases defaults to <i>all</i>. Example: - <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd> + <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"</i>.</dd> <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt> <dd>Build LLVM tools. Defaults to ON. Targets for building each tool @@ -352,6 +352,24 @@ Function Interface library. If the library or its headers are installed on a custom location, you can set the variables FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. Defaults to OFF.</dd> + + <dt><b>LLVM_CLANG_SOURCE_DIR</b>:PATH</dt> + <dd>Path to Clang's source directory. Defaults to tools/clang. + Clang will not be built when it is empty or it does not point valid + path.</dd> + + <dt><b>LLVM_USE_OPROFILE</b>:BOOL</dt> + <dd> Enable building OProfile JIT support. Defaults to OFF</dd> + + <dt><b>LLVM_USE_INTEL_JITEVENTS</b>:BOOL</dt> + <dd> Enable building support for Intel JIT Events API. Defaults to OFF</dd> + + <dt><b>LLVM_INTEL_JITEVENTS_DIR</b>:PATH</dt> + <dd> Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, + used to locate the <tt>jitprofiling</tt> library. Default = + <tt>%VTUNE_AMPLIFIER_XE_2011_DIR%</tt> (Windows) + | <tt>/opt/intel/vtune_amplifier_xe_2011</tt> (Linux) </dd> + </dl> </div> diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 9d0370fd..a37c3dc 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -50,6 +50,7 @@ <li><a href="#machinebasicblock">The <tt>MachineBasicBlock</tt> class</a></li> <li><a href="#machinefunction">The <tt>MachineFunction</tt> class</a></li> + <li><a href="#machineinstrbundle"><tt>MachineInstr Bundles</tt></a></li> </ul> </li> <li><a href="#mc">The "MC" Layer</a> @@ -97,6 +98,14 @@ <li><a href="#regAlloc_builtIn">Built in register allocators</a></li> </ul></li> <li><a href="#codeemit">Code Emission</a></li> + <li><a href="#vliw_packetizer">VLIW Packetizer</a> + <ul> + <li><a href="#vliw_mapping">Mapping from instructions to functional + units</a></li> + <li><a href="#vliw_repr">How the packetization tables are + generated and used</a></li> + </ul> + </li> </ul> </li> <li><a href="#nativeassembler">Implementing a Native Assembler</a></li> @@ -700,6 +709,21 @@ ret <!-- _______________________________________________________________________ --> <h4> + <a name="callclobber">Call-clobbered registers</a> +</h4> + +<div> + +<p>Some machine instructions, like calls, clobber a large number of physical + registers. Rather than adding <code><def,dead></code> operands for + all of them, it is possible to use an <code>MO_RegisterMask</code> operand + instead. The register mask operand holds a bit mask of preserved registers, + and everything else is considered to be clobbered by the instruction. </p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="ssa">Machine code in SSA form</a> </h4> @@ -753,6 +777,90 @@ ret </div> +<!-- ======================================================================= --> +<h3> + <a name="machineinstrbundle"><tt>MachineInstr Bundles</tt></a> +</h3> + +<div> + +<p>LLVM code generator can model sequences of instructions as MachineInstr + bundles. A MI bundle can model a VLIW group / pack which contains an + arbitrary number of parallel instructions. It can also be used to model + a sequential list of instructions (potentially with data dependencies) that + cannot be legally separated (e.g. ARM Thumb2 IT blocks).</p> + +<p>Conceptually a MI bundle is a MI with a number of other MIs nested within: +</p> + +<div class="doc_code"> +<pre> +-------------- +| Bundle | --------- +-------------- \ + | ---------------- + | | MI | + | ---------------- + | | + | ---------------- + | | MI | + | ---------------- + | | + | ---------------- + | | MI | + | ---------------- + | +-------------- +| Bundle | -------- +-------------- \ + | ---------------- + | | MI | + | ---------------- + | | + | ---------------- + | | MI | + | ---------------- + | | + | ... + | +-------------- +| Bundle | -------- +-------------- \ + | + ... +</pre> +</div> + +<p> MI bundle support does not change the physical representations of + MachineBasicBlock and MachineInstr. All the MIs (including top level and + nested ones) are stored as sequential list of MIs. The "bundled" MIs are + marked with the 'InsideBundle' flag. A top level MI with the special BUNDLE + opcode is used to represent the start of a bundle. It's legal to mix BUNDLE + MIs with indiviual MIs that are not inside bundles nor represent bundles. +</p> + +<p> MachineInstr passes should operate on a MI bundle as a single unit. Member + methods have been taught to correctly handle bundles and MIs inside bundles. + The MachineBasicBlock iterator has been modified to skip over bundled MIs to + enforce the bundle-as-a-single-unit concept. An alternative iterator + instr_iterator has been added to MachineBasicBlock to allow passes to + iterate over all of the MIs in a MachineBasicBlock, including those which + are nested inside bundles. The top level BUNDLE instruction must have the + correct set of register MachineOperand's that represent the cumulative + inputs and outputs of the bundled MIs.</p> + +<p> Packing / bundling of MachineInstr's should be done as part of the register + allocation super-pass. More specifically, the pass which determines what + MIs should be bundled together must be done after code generator exits SSA + form (i.e. after two-address pass, PHI elimination, and copy coalescing). + Bundles should only be finalized (i.e. adding BUNDLE MIs and input and + output register MachineOperands) after virtual registers have been + rewritten into physical registers. This requirement eliminates the need to + add virtual register operands to BUNDLE instructions which would effectively + double the virtual register def and use lists.</p> + +</div> + </div> <!-- *********************************************************************** --> @@ -2001,6 +2109,73 @@ to implement an assembler for your target.</p> </div> +<!-- ======================================================================= --> +<h3> + <a name="vliw_packetizer">VLIW Packetizer</a> +</h3> + +<div> + +<p>In a Very Long Instruction Word (VLIW) architecture, the compiler is + responsible for mapping instructions to functional-units available on + the architecture. To that end, the compiler creates groups of instructions + called <i>packets</i> or <i>bundles</i>. The VLIW packetizer in LLVM is + a target-independent mechanism to enable the packetization of machine + instructions.</p> + +<!-- _______________________________________________________________________ --> + +<h4> + <a name="vliw_mapping">Mapping from instructions to functional units</a> +</h4> + +<div> + +<p>Instructions in a VLIW target can typically be mapped to multiple functional +units. During the process of packetizing, the compiler must be able to reason +about whether an instruction can be added to a packet. This decision can be +complex since the compiler has to examine all possible mappings of instructions +to functional units. Therefore to alleviate compilation-time complexity, the +VLIW packetizer parses the instruction classes of a target and generates tables +at compiler build time. These tables can then be queried by the provided +machine-independent API to determine if an instruction can be accommodated in a +packet.</p> +</div> + +<!-- ======================================================================= --> +<h4> + <a name="vliw_repr"> + How the packetization tables are generated and used + </a> +</h4> + +<div> + +<p>The packetizer reads instruction classes from a target's itineraries and +creates a deterministic finite automaton (DFA) to represent the state of a +packet. A DFA consists of three major elements: inputs, states, and +transitions. The set of inputs for the generated DFA represents the instruction +being added to a packet. The states represent the possible consumption +of functional units by instructions in a packet. In the DFA, transitions from +one state to another occur on the addition of an instruction to an existing +packet. If there is a legal mapping of functional units to instructions, then +the DFA contains a corresponding transition. The absence of a transition +indicates that a legal mapping does not exist and that the instruction cannot +be added to the packet.</p> + +<p>To generate tables for a VLIW target, add <i>Target</i>GenDFAPacketizer.inc +as a target to the Makefile in the target directory. The exported API provides +three functions: <tt>DFAPacketizer::clearResources()</tt>, +<tt>DFAPacketizer::reserveResources(MachineInstr *MI)</tt>, and +<tt>DFAPacketizer::canReserveResources(MachineInstr *MI)</tt>. These functions +allow a target packetizer to add an instruction to an existing packet and to +check whether an instruction can be added to a packet. See +<tt>llvm/CodeGen/DFAPacketizer.h</tt> for more information.</p> + +</div> + +</div> + </div> <!-- *********************************************************************** --> @@ -2212,16 +2387,14 @@ is the key:</p> <tr> <th>Feature</th> <th>ARM</th> - <th>Alpha</th> - <th>Blackfin</th> <th>CellSPU</th> + <th>Hexagon</th> <th>MBlaze</th> <th>MSP430</th> <th>Mips</th> <th>PTX</th> <th>PowerPC</th> <th>Sparc</th> - <th>SystemZ</th> <th>X86</th> <th>XCore</th> </tr> @@ -2229,16 +2402,14 @@ is the key:</p> <tr> <td><a href="#feat_reliable">is generally reliable</a></td> <td class="yes"></td> <!-- ARM --> - <td class="unknown"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="yes"></td> <!-- Hexagon --> <td class="no"></td> <!-- MBlaze --> <td class="unknown"></td> <!-- MSP430 --> - <td class="no"></td> <!-- Mips --> + <td class="yes"></td> <!-- Mips --> <td class="no"></td> <!-- PTX --> <td class="yes"></td> <!-- PowerPC --> <td class="yes"></td> <!-- Sparc --> - <td class="unknown"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="unknown"></td> <!-- XCore --> </tr> @@ -2246,16 +2417,14 @@ is the key:</p> <tr> <td><a href="#feat_asmparser">assembly parser</a></td> <td class="no"></td> <!-- ARM --> - <td class="no"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> <td class="yes"></td> <!-- MBlaze --> <td class="no"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> <td class="no"></td> <!-- PTX --> <td class="no"></td> <!-- PowerPC --> <td class="no"></td> <!-- Sparc --> - <td class="no"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="no"></td> <!-- XCore --> </tr> @@ -2263,16 +2432,14 @@ is the key:</p> <tr> <td><a href="#feat_disassembler">disassembler</a></td> <td class="yes"></td> <!-- ARM --> - <td class="no"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> <td class="yes"></td> <!-- MBlaze --> <td class="no"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> <td class="no"></td> <!-- PTX --> <td class="no"></td> <!-- PowerPC --> <td class="no"></td> <!-- Sparc --> - <td class="no"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="no"></td> <!-- XCore --> </tr> @@ -2280,16 +2447,14 @@ is the key:</p> <tr> <td><a href="#feat_inlineasm">inline asm</a></td> <td class="yes"></td> <!-- ARM --> - <td class="unknown"></td> <!-- Alpha --> - <td class="yes"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="yes"></td> <!-- Hexagon --> <td class="yes"></td> <!-- MBlaze --> <td class="unknown"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> <td class="unknown"></td> <!-- PTX --> <td class="yes"></td> <!-- PowerPC --> <td class="unknown"></td> <!-- Sparc --> - <td class="unknown"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="unknown"></td> <!-- XCore --> </tr> @@ -2297,16 +2462,14 @@ is the key:</p> <tr> <td><a href="#feat_jit">jit</a></td> <td class="partial"><a href="#feat_jit_arm">*</a></td> <!-- ARM --> - <td class="no"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> <td class="no"></td> <!-- MBlaze --> <td class="unknown"></td> <!-- MSP430 --> - <td class="no"></td> <!-- Mips --> + <td class="yes"></td> <!-- Mips --> <td class="unknown"></td> <!-- PTX --> <td class="yes"></td> <!-- PowerPC --> <td class="unknown"></td> <!-- Sparc --> - <td class="unknown"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="unknown"></td> <!-- XCore --> </tr> @@ -2314,16 +2477,14 @@ is the key:</p> <tr> <td><a href="#feat_objectwrite">.o file writing</a></td> <td class="no"></td> <!-- ARM --> - <td class="no"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> <td class="yes"></td> <!-- MBlaze --> <td class="no"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> <td class="no"></td> <!-- PTX --> <td class="no"></td> <!-- PowerPC --> <td class="no"></td> <!-- Sparc --> - <td class="no"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="no"></td> <!-- XCore --> </tr> @@ -2331,20 +2492,33 @@ is the key:</p> <tr> <td><a href="#feat_tailcall">tail calls</a></td> <td class="yes"></td> <!-- ARM --> - <td class="unknown"></td> <!-- Alpha --> - <td class="no"></td> <!-- Blackfin --> <td class="no"></td> <!-- CellSPU --> + <td class="yes"></td> <!-- Hexagon --> <td class="no"></td> <!-- MBlaze --> <td class="unknown"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> <td class="unknown"></td> <!-- PTX --> <td class="yes"></td> <!-- PowerPC --> <td class="unknown"></td> <!-- Sparc --> - <td class="unknown"></td> <!-- SystemZ --> <td class="yes"></td> <!-- X86 --> <td class="unknown"></td> <!-- XCore --> </tr> +<tr> + <td><a href="#feat_segstacks">segmented stacks</a></td> + <td class="no"></td> <!-- ARM --> + <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> + <td class="no"></td> <!-- MBlaze --> + <td class="no"></td> <!-- MSP430 --> + <td class="no"></td> <!-- Mips --> + <td class="no"></td> <!-- PTX --> + <td class="no"></td> <!-- PowerPC --> + <td class="no"></td> <!-- Sparc --> + <td class="partial"><a href="#feat_segstacks_x86">*</a></td> <!-- X86 --> + <td class="no"></td> <!-- XCore --> +</tr> + </table> @@ -2428,6 +2602,22 @@ more more details</a>.</p> </div> +<!-- _______________________________________________________________________ --> +<h4 id="feat_segstacks">Segmented Stacks</h4> + +<div> + +<p>This box indicates whether the target supports segmented stacks. This +replaces the traditional large C stack with many linked segments. It +is compatible with the <a href="http://gcc.gnu.org/wiki/SplitStacks">gcc +implementation</a> used by the Go front end.</p> + +<p id="feat_segstacks_x86">Basic support exists on the X86 backend. Currently +vararg doesn't work and the object files are not marked the way the gold +linker expects, but simple Go programs can be built by dragonegg.</p> + +</div> + </div> <!-- ======================================================================= --> @@ -2992,7 +3182,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-11-03 07:43:54 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 3ccbfc9..847ac4c 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -31,6 +31,7 @@ Errors</a></li> <li><a href="#ci_portable_code">Write Portable Code</a></li> <li><a href="#ci_rtti_exceptions">Do not use RTTI or Exceptions</a></li> + <li><a href="#ci_static_ctors">Do not use Static Constructors</a></li> <li><a href="#ci_class_struct">Use of <tt>class</tt>/<tt>struct</tt> Keywords</a></li> </ol></li> </ol></li> @@ -84,17 +85,16 @@ <!-- *********************************************************************** --> -<h2> - <a name="introduction">Introduction</a> -</h2> +<h2><a name="introduction">Introduction</a></h2> <!-- *********************************************************************** --> <div> <p>This document attempts to describe a few coding standards that are being used in the LLVM source tree. Although no coding standards should be regarded as -absolute requirements to be followed in all instances, coding standards can be -useful.</p> +absolute requirements to be followed in all instances, coding standards are +particularly important for large-scale code bases that follow a library-based +design (like LLVM).</p> <p>This document intentionally does not prescribe fixed standards for religious issues such as brace placement and space usage. For issues like this, follow @@ -102,14 +102,27 @@ the golden rule:</p> <blockquote> -<p><b><a name="goldenrule">If you are adding a significant body of source to a -project, feel free to use whatever style you are most comfortable with. If you -are extending, enhancing, or bug fixing already implemented code, use the style -that is already being used so that the source is uniform and easy to -follow.</a></b></p> +<p><b><a name="goldenrule">If you are extending, enhancing, or bug fixing +already implemented code, use the style that is already being used so that the +source is uniform and easy to follow.</a></b></p> </blockquote> - + +<p>Note that some code bases (e.g. libc++) have really good reasons to deviate +from the coding standards. In the case of libc++, this is because the naming +and other conventions are dictated by the C++ standard. If you think there is +a specific good reason to deviate from the standards here, please bring it up +on the LLVMdev mailing list.</p> + +<p>There are some conventions that are not uniformly followed in the code base +(e.g. the naming convention). This is because they are relatively new, and a +lot of code was written before they were put in place. Our long term goal is +for the entire codebase to follow the convention, but we explicitly <em>do +not</em> want patches that do large-scale reformating of existing code. OTOH, +it is reasonable to rename the methods of a class if you're about to change it +in some other way. Just do the reformating as a separate commit from the +functionality change. </p> + <p>The ultimate goal of these guidelines is the increase readability and maintainability of our common source base. If you have suggestions for topics to be included, please mail them to <a @@ -140,11 +153,11 @@ href="mailto:sabre@nondot.org">Chris</a>.</p> <div> <p>Comments are one critical part of readability and maintainability. Everyone -knows they should comment, so should you. When writing comments, write them as -English prose, which means they should use proper capitalization, punctuation, -etc. Although we all should probably -comment our code more than we do, there are a few very critical places that -documentation is very useful:</p> +knows they should comment their code, and so should you. When writing comments, +write them as English prose, which means they should use proper capitalization, +punctuation, etc. Aim to describe what a code is trying to do and why, not +"how" it does it at a micro level. Here are a few critical things to +document:</p> <h5>File Headers</h5> @@ -152,9 +165,7 @@ documentation is very useful:</p> <p>Every source file should have a header on it that describes the basic purpose of the file. If a file does not have a header, it should not be -checked into Subversion. Most source trees will probably have a standard -file header format. The standard format for the LLVM source tree looks like -this:</p> +checked into the tree. The standard header looks like this:</p> <div class="doc_code"> <pre> @@ -197,9 +208,8 @@ included, as well as any notes or "gotchas" in the code to watch out for.</p> <p>Classes are one fundamental part of a good object oriented design. As such, a class definition should have a comment block that explains what the class is -used for... if it's not obvious. If it's so completely obvious your grandma -could figure it out, it's probably safe to leave it out. Naming classes -something sane goes a long ways towards avoiding writing documentation.</p> +used for and how it works. Every non-trivial class is expected to have a +doxygen comment block.</p> <h5>Method information</h5> @@ -210,8 +220,7 @@ something sane goes a long ways towards avoiding writing documentation.</p> documented properly. A quick note about what it does and a description of the borderline behaviour is all that is necessary here (unless something particularly tricky or insidious is going on). The hope is that people can -figure out how to use your interfaces without reading the code itself... that is -the goal metric.</p> +figure out how to use your interfaces without reading the code itself.</p> <p>Good things to talk about here are what happens when something unexpected happens: does the method return null? Abort? Format your hard disk?</p> @@ -397,14 +406,6 @@ if ((V = getValue())) { <p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can be fixed by massaging the code appropriately.</p> -<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p> - -<div class="doc_code"> -<pre> --Wall -Winline -W -Wwrite-strings -Wno-unused -</pre> -</div> - </div> <!-- _______________________________________________________________________ --> @@ -449,6 +450,51 @@ than <tt>dynamic_cast<></tt>.</p> <!-- _______________________________________________________________________ --> <h4> +<a name="ci_static_ctors">Do not use Static Constructors</a> +</h4> +<div> + +<p>Static constructors and destructors (e.g. global variables whose types have +a constructor or destructor) should not be added to the code base, and should be +removed wherever possible. Besides <a +href="http://yosefk.com/c++fqa/ctors.html#fqa-10.12">well known problems</a> +where the order of initialization is undefined between globals in different +source files, the entire concept of static constructors is at odds with the +common use case of LLVM as a library linked into a larger application.</p> + +<p>Consider the use of LLVM as a JIT linked into another application (perhaps +for <a href="http://llvm.org/Users.html">OpenGL, custom languages</a>, +<a href="http://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf">shaders in +movies</a>, etc). Due to the design of static constructors, they must be +executed at startup time of the entire application, regardless of whether or +how LLVM is used in that larger application. There are two problems with +this:</p> + +<ol> + <li>The time to run the static constructors impacts startup time of + applications — a critical time for GUI apps, among others.</li> + + <li>The static constructors cause the app to pull many extra pages of memory + off the disk: both the code for the constructor in each <tt>.o</tt> file and + the small amount of data that gets touched. In addition, touched/dirty pages + put more pressure on the VM system on low-memory machines.</li> +</ol> + +<p>We would really like for there to be zero cost for linking in an additional +LLVM target or other library into an application, but static constructors +violate this goal.</p> + +<p>That said, LLVM unfortunately does contain static constructors. It would be +a <a href="http://llvm.org/PR11944">great project</a> for someone to purge all +static constructors from LLVM, and then enable the +<tt>-Wglobal-constructors</tt> warning flag (when building with Clang) to ensure +we do not regress in the future. +</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a> </h4> <div> @@ -1151,22 +1197,10 @@ prefer it.</p> <div> <p>The use of <tt>#include <iostream></tt> in library files is -hereby <b><em>forbidden</em></b>. The primary reason for doing this is to -support clients using LLVM libraries as part of larger systems. In particular, -we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, -the static constructors are run whenever an application starts up that uses the -dynamic library. There are two problems with this:</p> - -<ol> - <li>The time to run the static c'tors impacts startup time of applications - — a critical time for GUI apps.</li> - - <li>The static c'tors cause the app to pull many extra pages of memory off the - disk: both the code for the static c'tors in each <tt>.o</tt> file and the - small amount of data that gets touched. In addition, touched/dirty pages - put more pressure on the VM system on low-memory machines.</li> -</ol> - +hereby <b><em>forbidden</em></b>, because many common implementations +transparently inject a <a href="#ci_static_ctors">static constructor</a> into +every translation unit that includes it.</p> + <p>Note that using the other stream headers (<tt><sstream></tt> for example) is not problematic in this regard — just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides various @@ -1527,7 +1561,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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/CommandGuide/Makefile b/docs/CommandGuide/Makefile index 2c2d076..3f9f60b 100644 --- a/docs/CommandGuide/Makefile +++ b/docs/CommandGuide/Makefile @@ -49,7 +49,7 @@ MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) # The set of man pages we will not install -NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1 +NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1 $(DST_MAN_DIR)llvm-build.1 # The set of man pages that we will install INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN)) diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index 3e4e220..74ac004 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -72,6 +72,12 @@ options) arguments to the tool you are interested in.</p> <li><a href="/cmds/llvm-diff.html"><b>llvm-diff</b></a> - structurally compare two modules</li> +<li><a href="/cmds/llvm-cov.html"><b>llvm-cov</b></a> - + emit coverage information</li> + +<li><a href="/cmds/llvm-stress.html"><b>llvm-stress</b></a> - + generate random .ll files to fuzz different llvm components</li> + </ul> </div> @@ -129,7 +135,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-09-20 20:24:04 +0200 (Tue, 20 Sep 2011) $ + Last modified: $Date: 2012-02-26 09:35:53 +0100 (Sun, 26 Feb 2012) $ </address> </body> diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod index faf4811..81fc2c9 100644 --- a/docs/CommandGuide/lit.pod +++ b/docs/CommandGuide/lit.pod @@ -28,7 +28,7 @@ By default B<lit> will use a succinct progress display and will only print summary information for test failures. See L<"OUTPUT OPTIONS"> for options controlling the B<lit> progress display and output. -B<lit> also includes a number of options for controlling how tests are exected +B<lit> also includes a number of options for controlling how tests are executed (specific features may depend on the particular test format). See L<"EXECUTION OPTIONS"> for more information. @@ -37,7 +37,7 @@ the options specified on the command line, see L<"SELECTION OPTIONS"> for more information. Users interested in the B<lit> architecture or designing a B<lit> testing -implementation should see L<"LIT ARCHITECTURE"> +implementation should see L<"LIT INFRASTRUCTURE"> =head1 GENERAL OPTIONS @@ -159,8 +159,8 @@ other results are not collated in any reasonable fashion. =head1 EXIT STATUS B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS -results. Otherwise, it will exit with the status 0. Other exit codes used for -non-test related failures (for example a user error or an internal program +results. Otherwise, it will exit with the status 0. Other exit codes are used +for non-test related failures (for example a user error or an internal program error). =head1 TEST DISCOVERY @@ -208,7 +208,7 @@ suite. The test succeeded, but it was expected to fail. This is used for tests which were specified as expected to fail, but are now succeeding (generally because -the feautre they test was broken and has been fixed). +the feature they test was broken and has been fixed). =item B<FAIL> @@ -227,7 +227,7 @@ which can report unsupported tests. =back Depending on the test format tests may produce additional information about -their status (generally only for failures). See the L<Output|"LIT OUTPUT"> +their status (generally only for failures). See the L<Output|"OUTPUT OPTIONS"> section for more information. =head1 LIT INFRASTRUCTURE @@ -247,7 +247,7 @@ suite>. Test suites serve to define the format of the tests they contain, the logic for finding those tests, and any additional information to run the tests. B<lit> identifies test suites as directories containing I<lit.cfg> or -I<lit.site.cfg> files (see also B<--config-prefix>. Test suites are initially +I<lit.site.cfg> files (see also B<--config-prefix>). Test suites are initially discovered by recursively searching up the directory hierarchy for all the input files passed on the command line. You can use B<--show-suites> to display the discovered test suites at startup. @@ -283,13 +283,13 @@ builds this is the directory that will be scanned for tests. B<test_exec_root> For out-of-dir builds, the path to the test suite root inside the object directory. This is where tests will be run and temporary output files -places. +placed. B<environment> A dictionary representing the environment to use when executing tests in the suite. B<suffixes> For B<lit> test formats which scan directories for tests, this -variable as a list of suffixes to identify test files. Used by: I<ShTest>, +variable is a list of suffixes to identify test files. Used by: I<ShTest>, I<TclTest>. B<substitutions> For B<lit> test formats which substitute variables into a test @@ -301,6 +301,9 @@ reported as unsupported. Used by: I<ShTest>, I<TclTest>. B<parent> The parent configuration, this is the config object for the directory containing the test suite, or None. +B<root> The root configuration. This is the top-most B<lit> configuration in +the project. + B<on_clone> The config is actually cloned for every subdirectory inside a test suite, to allow local configuration on a per-directory basis. The I<on_clone> variable can be set to a Python function which will be called whenever a @@ -315,7 +318,7 @@ directory being scanned. Once test suites are located, B<lit> recursively traverses the source directory (following I<test_src_root>) looking for tests. When B<lit> enters a -sub-directory, it first checks to see if a nest test suite is defined in that +sub-directory, it first checks to see if a nested test suite is defined in that directory. If so, it loads that test suite recursively, otherwise it instantiates a local test config for the directory (see L<"LOCAL CONFIGURATION FILES">). @@ -338,6 +341,53 @@ define subdirectories of optional tests, or to change other configuration parameters -- for example, to change the test format, or the suffixes which identify test files. +=head2 TEST RUN OUTPUT FORMAT + +The b<lit> output for a test run conforms to the following schema, in both short +and verbose modes (although in short mode no PASS lines will be shown). This +schema has been chosen to be relatively easy to reliably parse by a machine (for +example in buildbot log scraping), and for other tools to generate. + +Each test result is expected to appear on a line that matches: + +<result code>: <test name> (<progress info>) + +where <result-code> is a standard test result such as PASS, FAIL, XFAIL, XPASS, +UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and +REGRESSED are also allowed. + +The <test name> field can consist of an arbitrary string containing no newline. + +The <progress info> field can be used to report progress information such as +(1/300) or can be empty, but even when empty the parentheses are required. + +Each test result may include additional (multiline) log information in the +following format. + +<log delineator> TEST '(<test name>)' <trailing delineator> +... log message ... +<log delineator> + +where <test name> should be the name of a preceeding reported test, <log +delineator> is a string of '*' characters I<at least> four characters long (the +recommended length is 20), and <trailing delineator> is an arbitrary (unparsed) +string. + +The following is an example of a test run output which consists of four tests A, +B, C, and D, and a log message for the failing test C. + +=head3 Example Test Run Output Listing + +PASS: A (1 of 4) +PASS: B (2 of 4) +FAIL: C (3 of 4) +******************** TEST 'C' FAILED ******************** +Test 'C' failed as a result of exit code 1. +******************** +PASS: D (4 of 4) + +=back + =head2 LIT EXAMPLE TESTS The B<lit> distribution contains several example implementations of test suites diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod index 50b45c8..35abdae 100644 --- a/docs/CommandGuide/llc.pod +++ b/docs/CommandGuide/llc.pod @@ -45,7 +45,7 @@ Print a summary of command line options. =item B<-O>=I<uint> Generate code at different optimization levels. These correspond to the I<-O0>, -I<-O1>, I<-O2>, I<-O3>, and I<-O4> optimization levels used by B<llvm-gcc> and +I<-O1>, I<-O2>, and I<-O3> optimization levels used by B<llvm-gcc> and B<clang>. =item B<-mtriple>=I<target triple> diff --git a/docs/CommandGuide/llvm-build.pod b/docs/CommandGuide/llvm-build.pod new file mode 100644 index 0000000..14e08cb --- /dev/null +++ b/docs/CommandGuide/llvm-build.pod @@ -0,0 +1,86 @@ +=pod + +=head1 NAME + +llvm-build - LLVM Project Build Utility + +=head1 SYNOPSIS + +B<llvm-build> [I<options>] + +=head1 DESCRIPTION + +B<llvm-build> is a tool for working with LLVM projects that use the LLVMBuild +system for describing their components. + +At heart, B<llvm-build> is responsible for loading, verifying, and manipulating +the project's component data. The tool is primarily designed for use in +implementing build systems and tools which need access to the project structure +information. + +=head1 OPTIONS + +=over + +=item B<-h>, B<--help> + +Print the builtin program help. + +=item B<--source-root>=I<PATH> + +If given, load the project at the given source root path. If this option is not +given, the location of the project sources will be inferred from the location of +the B<llvm-build> script itself. + +=item B<--print-tree> + +Print the component tree for the project. + +=item B<--write-library-table> + +Write out the C++ fragment which defines the components, library names, and +required libraries. This C++ fragment is built into L<llvm-config|llvm-config> +in order to provide clients with the list of required libraries for arbitrary +component combinations. + +=item B<--write-llvmbuild> + +Write out new I<LLVMBuild.txt> files based on the loaded components. This is +useful for auto-upgrading the schema of the files. B<llvm-build> will try to a +limited extent to preserve the comments which were written in the original +source file, although at this time it only preserves block comments that preceed +the section names in the I<LLVMBuild> files. + +=item B<--write-cmake-fragment> + +Write out the LLVMBuild in the form of a CMake fragment, so it can easily be +consumed by the CMake based build system. The exact contents and format of this +file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's +top-level CMakeLists.txt. + +=item B<--write-make-fragment> + +Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be +consumed by a Make based build system. The exact contents and format of this +file are closely tied to how LLVMBuild is integrated with the Makefiles, see +LLVM's Makefile.rules. + +=item B<--llvmbuild-source-root>=I<PATH> + +If given, expect the I<LLVMBuild> files for the project to be rooted at the +given path, instead of inside the source tree itself. This option is primarily +designed for use in conjunction with B<--write-llvmbuild> to test changes to +I<LLVMBuild> schema. + +=back + +=head1 EXIT STATUS + +B<llvm-build> exits with 0 if operation was successful. Otherwise, it will exist +with a non-zero value. + +=head1 AUTHOR + +Maintained by the LLVM Team (L<http://llvm.org/>). + +=cut diff --git a/docs/CommandGuide/llvm-cov.pod b/docs/CommandGuide/llvm-cov.pod new file mode 100644 index 0000000..e8ff683 --- /dev/null +++ b/docs/CommandGuide/llvm-cov.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +llvm-cov - emit coverage information + +=head1 SYNOPSIS + +B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump] + +=head1 DESCRIPTION + +The experimental B<llvm-cov> tool reads in description file generated by compiler +and coverage data file generated by instrumented program. This program assumes +that the description and data file uses same format as gcov files. + +=head1 OPTIONS + +=over + +=item B<-gcno=filename] + +This option selects input description file generated by compiler while instrumenting +program. + +=item B<-gcda=filename] + +This option selects coverage data file generated by instrumented compiler. + +=item B<-dump> + +This options enables output dump that is suitable for a developer to help debug +B<llvm-cov> itself. + +=back + +=head1 EXIT STATUS + +B<llvm-cov> returns 1 if it cannot read input files. Otherwise, it exits with zero. + +=head1 AUTHOR + +B<llvm-cov> is maintained by the LLVM Team (L<http://llvm.org/>). + +=cut diff --git a/docs/CommandGuide/llvm-stress.pod b/docs/CommandGuide/llvm-stress.pod new file mode 100644 index 0000000..92083d2 --- /dev/null +++ b/docs/CommandGuide/llvm-stress.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +llvm-stress - generate random .ll files + +=head1 SYNOPSIS + +B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump] + +=head1 DESCRIPTION + +The B<llvm-stress> tool is used to generate random .ll files that can be used to +test different components of LLVM. + +=head1 OPTIONS + +=over + +=item B<-o> I<filename> + +Specify the output filename. + +=item B<-size> I<size> + +Specify the size of the generated .ll file. + +=item B<-seed> I<seed> + +Specify the seed to be used for the randomly generated instructions. + +=back + +=head1 EXIT STATUS + +B<llvm-stress> returns 0. + +=head1 AUTHOR + +B<llvm-stress> is maintained by the LLVM Team (L<http://llvm.org/>). + +=cut diff --git a/docs/CommandGuide/tblgen.pod b/docs/CommandGuide/tblgen.pod index fe1be5e..180bcc1 100644 --- a/docs/CommandGuide/tblgen.pod +++ b/docs/CommandGuide/tblgen.pod @@ -41,6 +41,10 @@ Specify where to find other target description files for inclusion. The F<directory> value should be a full or partial path to a directory that contains target description files. +=item B<-asmparsernum> F<N> + +Make -gen-asm-parser emit assembly writer number F<N>. + =item B<-asmwriternum> F<N> Make -gen-asm-writer emit assembly writer number F<N>. @@ -57,38 +61,50 @@ Print all records to standard output (default). Print enumeration values for a class -=item B<-gen-emitter> +=item B<-print-sets> -Generate machine code emitter. +Print expanded sets for testing DAG exprs. -=item B<-gen-register-enums> +=item B<-gen-emitter> -Generate the enumeration values for all registers. +Generate machine code emitter. -=item B<-gen-register-desc> +=item B<-gen-register-info> -Generate a register info description for each register. +Generate registers and register classes info. -=item B<-gen-register-desc-header> +=item B<-gen-instr-info> -Generate a register info description header for each register. +Generate instruction descriptions. -=item B<-gen-instr-enums> +=item B<-gen-asm-writer> -Generate enumeration values for instructions. +Generate the assembly writer. -=item B<-gen-instr-desc> +=item B<-gen-disassembler> -Generate instruction descriptions. +Generate disassembler. -=item B<-gen-asm-writer> +=item B<-gen-pseudo-lowering> -Generate the assembly writer. +Generate pseudo instruction lowering. =item B<-gen-dag-isel> Generate a DAG (Directed Acycle Graph) instruction selector. +=item B<-gen-asm-matcher> + +Generate assembly instruction matcher. + +=item B<-gen-dfa-packetizer> + +Generate DFA Packetizer for VLIW targets. + +=item B<-gen-fast-isel> + +Generate a "fast" instruction selector. + =item B<-gen-subtarget> Generate subtarget enumerations. @@ -97,6 +113,14 @@ Generate subtarget enumerations. Generate intrinsic information. +=item B<-gen-tgt-intrinsic> + +Generate target intrinsic information. + +=item B<-gen-enhanced-disassembly-info> + +Generate enhanced disassembly info. + =item B<-version> Show the version number of this program. diff --git a/docs/CompilerWriterInfo.html b/docs/CompilerWriterInfo.html index ed326b3..5fdb4fc 100644 --- a/docs/CompilerWriterInfo.html +++ b/docs/CompilerWriterInfo.html @@ -21,7 +21,6 @@ <ol> <li><a href="#hw">Hardware</a> <ol> - <li><a href="#alpha">Alpha</a></li> <li><a href="#arm">ARM</a></li> <li><a href="#ia64">Itanium</a></li> <li><a href="#mips">MIPS</a></li> @@ -49,17 +48,6 @@ <div> <!-- ======================================================================= --> -<h3><a name="alpha">Alpha</a></h3> - -<div> -<ul> -<li><a -href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-library.html">Alpha manuals</a> -</li> -</ul> -</div> - -<!-- ======================================================================= --> <h3><a name="arm">ARM</a></h3> <div> @@ -272,7 +260,7 @@ processors.</li> <a href="http://misha.brukman.net">Misha Brukman</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-28 00:56:32 +0200 (Fri, 28 Oct 2011) $ </address> </body> diff --git a/docs/DebuggingJITedCode.html b/docs/DebuggingJITedCode.html index a6883ad..1946fdd 100644 --- a/docs/DebuggingJITedCode.html +++ b/docs/DebuggingJITedCode.html @@ -147,7 +147,7 @@ coordinate with GDB to get better debug information. src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="mailto:reid.kleckner@gmail.com">Reid Kleckner</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> </html> diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index 7c78016..264975e 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -43,7 +43,7 @@ the distributed nature of LLVM's development. By stating the policy in clear terms, we hope each developer can know ahead of time what to expect when making LLVM contributions. This policy covers all llvm.org subprojects, - including Clang, LLDB, etc.</p> + including Clang, LLDB, libc++, etc.</p> <p>This policy is also designed to accomplish the following objectives:</p> <ol> @@ -52,6 +52,9 @@ <li>Make life as simple and easy for contributors as possible.</li> <li>Keep the top of Subversion trees as stable as possible.</li> + + <li>Establish awareness of the project's <a href="#clp">copyright, + license, and patent policies</a> with contributors to the project.</li> </ol> <p>This policy is aimed at frequent contributors to LLVM. People interested in @@ -212,6 +215,10 @@ <li><b>Jakob Olesen</b>: Register allocators and TableGen.</li> <li><b>Duncan Sands</b>: dragonegg and llvm-gcc 4.2.</li> + + <li><b>Peter Collingbourne</b>: libclc.</li> + + <li><b>Tobias Grosser</b>: polly.</li> </ol> <p>Note that code ownership is completely different than reviewers: anyone can @@ -495,18 +502,24 @@ <!--=========================================================================--> <div> + +<div class="doc_notes"> +<p style="text-align:center;font-weight:bold">NOTE: This section deals with + legal matters but does not provide legal advice. We are not lawyers — + please seek legal counsel from an attorney.</p> +</div> + +<div> <p>This section addresses the issues of copyright, license and patents for the - LLVM project. The copyright holder for the code is held by the individual + LLVM project. The copyright 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> + Illinois/NCSA Open Source License</a> (with portions dual licensed under the + <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, + see below). As contributor to the LLVM project, you agree to allow any + contributions to the project to licensed under these terms.</p> -<div class="doc_notes"> -<p style="text-align:center;font-weight:bold">NOTE: This section deals with - legal matters but does not provide legal advice. We are not lawyers, please - seek legal counsel from an attorney.</p> -</div> <!-- _______________________________________________________________________ --> <h3><a name="copyright">Copyright</a></h3> @@ -535,7 +548,10 @@ <h3><a name="license">License</a></h3> <div> <p>We intend to keep LLVM perpetually open source and to use a liberal open - source license. All of the code in LLVM is available under the + source license. <b>As a contributor to the project, you agree that any + contributions be licensed under the terms of the corresponding + subproject.</b> + All of the code in LLVM is available under the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>, which boils down to this:</p> @@ -556,7 +572,7 @@ if further clarification is needed.</p> <p>In addition to the UIUC license, the runtime library components of LLVM - (<b>compiler_rt and libc++</b>) are also licensed under the <a + (<b>compiler_rt, libc++, and libclc</b>) are also licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>, which does not contain the binary redistribution clause. As a user of these runtime libraries, it means that you can choose to use the code under either @@ -570,16 +586,17 @@ the LLVM core to libc++ without the copyright owner's permission. </p> -<p>Note that the LLVM Project does distribute llvm-gcc, <b>which is GPL.</b> +<p>Note that the LLVM Project does distribute llvm-gcc and dragonegg, <b>which + are GPL.</b> This means that anything "linked" into llvm-gcc must itself be compatible with the GPL, and must be releasable under the terms of the GPL. This implies that <b>any code linked into llvm-gcc and distributed to others may be subject to the viral aspects of the GPL</b> (for example, a proprietary code generator linked into llvm-gcc must be made available under the GPL). This is not a problem for code already distributed under a more liberal - license (like the UIUC license), and does not affect code generated by - llvm-gcc. It may be a problem if you intend to base commercial development - on llvm-gcc without redistributing your source code.</p> + license (like the UIUC license), and GPL-containing subprojects are kept + in separate SVN repositories whose LICENSE.txt files specifically indicate + that they contain GPL code.</p> <p>We have no plans to change the license of LLVM. If you have questions or comments about the license, please contact the @@ -596,7 +613,8 @@ arbitrary purposes (including commercial use).</p> <p>When contributing code, we expect contributors to notify us of any potential - for patent-related trouble with their changes. If you or your employer own + for patent-related trouble with their changes (including from third parties). + If you or your employer own the rights to a patent and would like to contribute code to LLVM that relies on it, we require that the copyright owner sign an agreement that allows any other user of LLVM to freely use your patent. Please contact @@ -606,6 +624,8 @@ </div> +</div> + <!-- *********************************************************************** --> <hr> <address> @@ -616,7 +636,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-10-07 19:26:38 +0200 (Fri, 07 Oct 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> </html> diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html index 85ab796..49e6b01 100644 --- a/docs/ExceptionHandling.html +++ b/docs/ExceptionHandling.html @@ -38,7 +38,6 @@ <li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li> <li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li> <li><a href="#llvm_eh_sjlj_callsite"><tt>llvm.eh.sjlj.callsite</tt></a></li> - <li><a href="#llvm_eh_sjlj_dispatchsetup"><tt>llvm.eh.sjlj.dispatchsetup</tt></a></li> </ol></li> <li><a href="#asm">Asm Table Formats</a> <ol> @@ -50,7 +49,7 @@ </tr></table> <div class="doc_author"> - <p>Written by <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p> + <p>Written by the <a href="http://llvm.org/">LLVM Team</a></p> </div> @@ -498,23 +497,6 @@ </div> -<!-- ======================================================================= --> -<h4> - <a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a> -</h4> - -<div> - -<pre> - void @llvm.eh.sjlj.dispatchsetup(i32 %dispatch_value) -</pre> - -<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> - </div> <!-- ======================================================================= --> @@ -573,9 +555,8 @@ <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:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-09-27 22:16:57 +0200 (Tue, 27 Sep 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/ExtendingLLVM.html b/docs/ExtendingLLVM.html index 15e6984..a0cc4ea 100644 --- a/docs/ExtendingLLVM.html +++ b/docs/ExtendingLLVM.html @@ -105,19 +105,6 @@ function and then be turned into an instruction if warranted.</p> support for it. Generally you must do the following steps:</p> <dl> -<dt>Add support to the C backend in <tt>lib/Target/CBackend/</tt></dt> - -<dd>Depending on the intrinsic, there are a few ways to implement this. For - most intrinsics, it makes sense to add code to lower your intrinsic in - <tt>LowerIntrinsicCall</tt> in <tt>lib/CodeGen/IntrinsicLowering.cpp</tt>. - Second, if it makes sense to lower the intrinsic to an expanded sequence of - C code in all cases, just emit the expansion in <tt>visitCallInst</tt> in - <tt>Writer.cpp</tt>. If the intrinsic has some way to express it with GCC - (or any other compiler) extensions, it can be conditionally supported based - on the compiler compiling the CBE output (see <tt>llvm.prefetch</tt> for an - example). Third, if the intrinsic really has no way to be lowered, just - have the code generator emit code that prints an error message and calls - abort if executed.</dd> <dt>Add support to the .td file for the target(s) of your choice in <tt>lib/Target/*/*.td</tt>.</dt> @@ -385,7 +372,7 @@ void calcTypeName(const Type *Ty, <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-23 06:50:46 +0100 (Fri, 23 Mar 2012) $ </address> </body> diff --git a/docs/FAQ.html b/docs/FAQ.html index 341f1c9..78c0268 100644 --- a/docs/FAQ.html +++ b/docs/FAQ.html @@ -140,6 +140,8 @@ </h2> <!-- *********************************************************************** --> +<div> + <div class="question"> <p>Why are the LLVM source code and the front-end distributed under different licenses?</p> @@ -185,12 +187,16 @@ GPL, as explained in the first question above.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="source">Source Code</a> </h2> <!-- *********************************************************************** --> +<div> + <div class="question"> <p>In what language is LLVM written?</p> </div> @@ -223,12 +229,16 @@ LLVM have been ported to a plethora of platforms.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="build">Build Problems</a> </h2> <!-- *********************************************************************** --> +<div> + <div class="question"> <p>When I run configure, it finds the wrong C compiler.</p> </div> @@ -435,11 +445,15 @@ Stop. <p>We regret the inconvenience.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="felangs">Source Languages</a> </h2> +<div> + <div class="question"> <p><a name="langs">What source languages are supported?</a></p> </div> @@ -540,11 +554,15 @@ Stop. Instruction</a>.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="cfe">Using the GCC Front End</a> </h2> +<div> + <div class="question"> <p>When I compile software that uses a configure script, the configure script thinks my system has all of the header files and libraries it is testing for. @@ -697,11 +715,15 @@ Stop. order to have the result conform to the platform ABI.</p> </div> +</div> + <!-- *********************************************************************** --> <h2> <a name="cfe_code">Questions about code generated by the GCC front-end</a> </h2> +<div> + <div class="question"> <p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include @@ -907,6 +929,8 @@ F.i: </div> +</div> + <!-- *********************************************************************** --> <hr> @@ -917,7 +941,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-09-20 02:42:28 +0200 (Tue, 20 Sep 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index 10bc663..9463eaa 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -429,7 +429,8 @@ programs that use different garbage collection algorithms (or none at all).</p> <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 -href="#plugin">compiler plugin</a>.</p> +href="#plugin">compiler plugin</a>. All calls to <tt>llvm.gcroot</tt> <b>must</b> reside + inside the first basic block.</p> <p>A compiler which uses mem2reg to raise imperative code using <tt>alloca</tt> into SSA form need only add a call to <tt>@llvm.gcroot</tt> for those variables @@ -437,7 +438,9 @@ which a pointers into the GC heap.</p> <p>It is also important to mark intermediate values with <tt>llvm.gcroot</tt>. For example, consider <tt>h(f(), g())</tt>. Beware leaking the result of -<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection.</p> +<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection. Note, that +stack variables must be initialized and marked with <tt>llvm.gcroot</tt> in +function's prologue.</p> <p>The first argument <b>must</b> be a value referring to an alloca instruction or a bitcast of an alloca. The second contains a pointer to metadata that @@ -1379,7 +1382,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-08-12 08:17:17 +0200 (Fri, 12 Aug 2011) $ + Last modified: $Date: 2012-03-03 05:32:33 +0100 (Sat, 03 Mar 2012) $ </address> </body> diff --git a/docs/GetElementPtr.html b/docs/GetElementPtr.html index f678e27..17a93f5 100644 --- a/docs/GetElementPtr.html +++ b/docs/GetElementPtr.html @@ -594,10 +594,10 @@ idx3 = (char*) &MyVar + 8 because LLVM has no restrictions on mixing types in addressing, loads or stores.</p> - <p>It would be possible to add special annotations to the IR, probably using - metadata, to describe a different type system (such as the C type system), - and do type-based aliasing on top of that. This is a much bigger - undertaking though.</p> + <p>LLVM's type-based alias analysis pass uses metadata to describe a different + type system (such as the C type system), and performs type-based aliasing + on top of that. Further details are in the + <a href="LangRef.html#tbaa">language reference</a>.</p> </div> @@ -747,7 +747,7 @@ idx3 = (char*) &MyVar + 8 <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/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-11-03 07:43:54 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 14:04:26 +0100 (Mon, 31 Oct 2011) $ </address> </body> </html> diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index e198e02..52baf90 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -29,7 +29,6 @@ <li><a href="#unpack">Unpacking the LLVM Archives</a></li> <li><a href="#checkout">Checkout LLVM from Subversion</a></li> <li><a href="#git_mirror">LLVM GIT mirror</a></li> - <li><a href="#installcf">Install the GCC Front End</a></li> <li><a href="#config">Local LLVM Configuration</a></li> <li><a href="#compile">Compiling the LLVM Suite Source Code</a></li> <li><a href="#cross-compile">Cross-Compiling LLVM</a></li> @@ -52,7 +51,7 @@ <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> <ol> - <li><a href="#tutorial4">Example with llvm-gcc4</a></li> + <li><a href="#tutorial4">Example with Clang</a></li> </ol> <li><a href="#problems">Common Problems</a> <li><a href="#links">Links</a> @@ -82,16 +81,15 @@ basic information.</p> <p>First, LLVM comes in three pieces. The first piece is the LLVM suite. This contains all of the tools, libraries, and header files -needed to use the low level virtual machine. It contains an -assembler, disassembler, bitcode analyzer and bitcode optimizer. It -also contains basic regression tests that can be used to test the LLVM -tools and the GCC front end.</p> - -<p>The second piece is the GCC front end. This component provides a version of -GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front -end uses the GCC parser to convert code to LLVM. Once -compiled into LLVM bitcode, a program can be manipulated with the LLVM tools -from the LLVM suite.</p> +needed to use LLVM. It contains an assembler, disassembler, bitcode +analyzer and bitcode optimizer. It also contains basic regression tests that +can be used to test the LLVM tools and the Clang front end.</p> + +<p>The second piece is the <a href="http://clang.llvm.org/">Clang</a> front end. +This component compiles C, C++, Objective C, and Objective C++ code into LLVM +bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the +LLVM tools from the LLVM suite. +</p> <p> There is a third, optional piece called Test Suite. It is a suite of programs @@ -109,83 +107,98 @@ and performance. <div> +<p>The LLVM Getting Started documentation may be out of date. So, the Clang +<a href="http://clang.llvm.org/get_started.html">Getting Started</a> page might +also be a good place to start.</p> + <p>Here's the short story for getting up and running quickly with LLVM:</p> <ol> <li>Read the documentation.</li> <li>Read the documentation.</li> <li>Remember that you were warned twice about reading the documentation.</li> - <li>Install the llvm-gcc-4.2 front end if you intend to compile C or C++ - (see <a href="#installcf">Install the GCC Front End</a> for details): - <ol> - <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li> - <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf -</tt></li> - <li><tt><i>install-binutils-binary-from-MinGW</i></tt> (Windows only)</li> - <li>Note: If the binary extension is "<tt>.bz</tt>" use <tt>bunzip2</tt> instead of <tt>gunzip</tt>.</li> - <li>Note: On Windows, use <a href="http://www.7-zip.org/">7-Zip</a> or a similar archiving tool.</li> - <li>Add <tt>llvm-gcc</tt>'s "<tt>bin</tt>" directory to your <tt>PATH</tt> environment variable.</li> - </ol></li> - <li>Get the LLVM Source Code + <li>Checkout LLVM: <ul> - <li>With the distributed files (or use <a href="#checkout">SVN</a>): - <ol> - <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> - <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt> - </ol></li> - - </ul></li> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> + </ul> + </li> - <li><b>[Optional]</b> Get the Test Suite Source Code + <li>Checkout Clang: <ul> - <li>With the distributed files (or use <a href="#checkout">SVN</a>): - <ol> - <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> - <li><tt>cd llvm/projects</tt> - <li><tt>gunzip --stdout llvm-test-<i>version</i>.tar.gz | tar -xvf -</tt> - <li><tt>mv llvm-test-<i>version</i> test-suite</tt> - </ol></li> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/tools</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> + </ul> + </li> - </ul></li> + <li>Checkout Compiler-RT: + <ul> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/projects</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk + compiler-rt</tt></li> + </ul> + </li> + <li>Get the Test Suite Source Code <b>[Optional]</b> + <ul> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/projects</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite</tt></li> + </ul> + </li> - <li>Configure the LLVM Build Environment - <ol> + <li>Configure and build LLVM and Clang: + <ul> <li><tt>cd <i>where-you-want-to-build-llvm</i></tt></li> - <li><tt><i>/path/to/llvm/</i>configure [options]</tt><br> - Some common options: + <li><tt>mkdir build</tt> (for building without polluting the source dir)</li> + <li><tt>cd build</tt></li> + <li><tt>../llvm/configure [options]</tt> + <br>Some common options: <ul> - <li><tt>--prefix=<i>directory</i></tt> - <p>Specify for <i>directory</i> the full pathname of where you + <li><tt>--prefix=<i>directory</i></tt> - + Specify for <i>directory</i> the full pathname of where you want the LLVM tools and libraries to be installed (default - <tt>/usr/local</tt>).</p></li> - <li><tt>--with-llvmgccdir=<i>directory</i></tt> - <p>Optionally, specify for <i>directory</i> the full pathname of the - C/C++ front end installation to use with this LLVM configuration. If - not specified, the PATH will be searched. This is only needed if you - want to run test-suite or do some special kinds of LLVM builds.</p></li> - <li><tt>--enable-spec2000=<i>directory</i></tt> - <p>Enable the SPEC2000 benchmarks for testing. The SPEC2000 - benchmarks should be available in - <tt><i>directory</i></tt>.</p></li> + <tt>/usr/local</tt>).</li> </ul> - </ol></li> - <li>Build the LLVM Suite: - <ol> - <li><tt>gmake -k |& tee gnumake.out - # this is csh or tcsh syntax</tt></li> - <li>If you get an "internal compiler error (ICE)" or test failures, see - <a href="#brokengcc">below</a>.</li> - </ol> + <ul> + <li><tt>--enable-optimized</tt> - + Compile with optimizations enabled (default is NO).</li> + </ul> + + <ul> + <li><tt>--enable-assertions</tt> - + Compile with assertion checks enabled (default is YES).</li> + </ul> + </li> + <li><tt>make [-j]</tt> - The -j specifies the number of jobs (commands) to + run simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. + The --enabled-optimized configure option is used to specify a Release build.</li> + <li><tt>make check-all</tt> - + This run the regression tests to ensure everything is in working order.</li> + <li><tt>make update</tt> - + This command is used to update all the svn repositories at once, rather then + having to <tt>cd</tt> into the individual repositories and running + <tt>svn update</tt>.</li> + <li>It is also possible to use CMake instead of the makefiles. With CMake + it is also possible to generate project files for several IDEs: Eclipse + CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.</li> + <li>If you get an "internal compiler error (ICE)" or test failures, see + <a href="#brokengcc">below</a>.</li> + + </ul> + </li> </ol> <p>Consult the <a href="#starting">Getting Started with LLVM</a> section for detailed information on configuring and compiling LLVM. See <a href="#environment">Setting Up Your Environment</a> for tips that simplify -working with the GCC front end and LLVM tools. Go to <a href="#layout">Program +working with the Clang front end and LLVM tools. Go to <a href="#layout">Program Layout</a> to learn about the layout of the source code tree.</p> </div> @@ -283,7 +296,7 @@ software you will need.</p> <tr> <td>Windows</td> <td>x86<sup><a href="#pf_1">1</a></sup></td> - <td>Visual Studio 2005 SP1 or higher<sup><a href="#pf_4">4</a>,<a href="#pf_5">5</a></sup></td> + <td>Visual Studio 2008 or higher<sup><a href="#pf_4">4</a>,<a href="#pf_5">5</a></sup></td> <tr> <td>AIX<sup><a href="#pf_3">3</a>,<a href="#pf_4">4</a></sup></td> <td>PowerPC</td> @@ -361,10 +374,6 @@ able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation should work as well, although the generated native code may not work on your platform.</p> -<p>The GCC front end is not very portable at the moment. If you want to get it -to work on another platform, you can download a copy of the source and <a -href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> - </div> <!-- ======================================================================= --> @@ -430,7 +439,7 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <tr> <td><a href="http://www.perl.com/download.csp">perl</a></td> <td>≥5.6.0</td> - <td>Nightly tester, utilities</td> + <td>Utilities</td> </tr> <tr> @@ -441,13 +450,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.61</td> + <td>2.60</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.10</td> + <td>1.9.6</td> <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td> </tr> @@ -471,8 +480,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.61), and consequently, GNU M4 (version 1.4 - or higher). You will also need automake (1.10). We only use aclocal + 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 from that package.</a></li> </ol> </div> @@ -516,9 +525,8 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <p>LLVM is very demanding of the host C++ compiler, and as such tends to expose bugs in the compiler. In particular, several versions of GCC crash when trying -to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1 -successfully with them (however, see important notes below). Other versions -of GCC will probably work as well. GCC versions listed +to compile LLVM. We routinely use GCC 4.2 (and higher) or Clang. +Other versions of GCC will probably work as well. GCC versions listed here are known to not work. If you are using one of these versions, please try to upgrade your GCC to something more recent. If you run into a problem with a version of GCC not listed here, please <a href="mailto:llvmdev@cs.uiuc.edu">let @@ -538,8 +546,7 @@ href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in the "<tt>convert_from_eh_region_ranges_1</tt>" GCC function.</p> <p><b>Cygwin GCC 3.3.3</b>: The version of GCC 3.3.3 commonly shipped with - Cygwin does not work. Please <a href="GCCFEBuildInstrs.html#cygwin">upgrade - to a newer version</a> if possible.</p> + Cygwin does not work.</p> <p><b>SuSE GCC 3.3.3</b>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly others) does not compile LLVM correctly (it appears that exception handling is broken in some cases). Please download the FSF 3.3.3 or upgrade @@ -651,12 +658,6 @@ All these paths are absolute:</p> can be the same as SRC_ROOT). <br><br> - <dt>LLVMGCCDIR - <dd> - This is where the LLVM GCC Front End is installed. - <p> - For the pre-built GCC front end binaries, the LLVMGCCDIR is - <tt>llvm-gcc/<i>platform</i>/llvm-gcc</tt>. </dl> </div> @@ -747,7 +748,6 @@ 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> @@ -784,10 +784,6 @@ you get it from the Subversion repository:</p> configured by the LLVM configure script as well as automatically updated when you run <tt>svn update</tt>.</p> -<p>If you would like to get the GCC front end source code, you can also get it -and build it yourself. Please follow <a href="GCCFEBuildInstrs.html">these -instructions</a> to successfully get and build the LLVM GCC front-end.</p> - </div> <!-- ======================================================================= --> @@ -891,6 +887,8 @@ Then, your .git/config should have [imap] sections. folder = "[Gmail]/Drafts" ; example for Japanese, "Modified UTF-7" encoded. folder = "[Gmail]/&Tgtm+DBN-" +; example for Traditional Chinese + folder = "[Gmail]/&g0l6Pw-" </pre> </div> @@ -951,76 +949,6 @@ git svn rebase -l <!-- ======================================================================= --> <h3> - <a name="installcf">Install the GCC Front End</a> -</h3> - -<div> - -<p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM -GCC front end) you can optionally extract the front end from the binary distribution. -It is used for running the LLVM test-suite and for compiling C/C++ programs. Note that -you can optionally <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the -main LLVM repository.</p> - -<p>To install the GCC front end, do the following (on Windows, use an archival tool -like <a href="http://www.7-zip.org/">7-zip</a> that understands gzipped tars):</p> - -<ol> - <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li> - <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf - -</tt></li> -</ol> - -<p>Once the binary is uncompressed, if you're using a *nix-based system, add a symlink for -<tt>llvm-gcc</tt> and <tt>llvm-g++</tt> to some directory in your path. If you're using a -Windows-based system, add the <tt>bin</tt> subdirectory of your front end installation directory -to your <tt>PATH</tt> environment variable. For example, if you uncompressed the binary to -<tt>c:\llvm-gcc</tt>, add <tt>c:\llvm-gcc\bin</tt> to your <tt>PATH</tt>.</p> - -<p>If you now want to build LLVM from source, when you configure LLVM, it will -automatically detect <tt>llvm-gcc</tt>'s presence (if it is in your path) enabling its -use in test-suite. Note that you can always build or install <tt>llvm-gcc</tt> at any -point after building the main LLVM repository: just reconfigure llvm and -test-suite will pick it up. -</p> - -<p>As a convenience for Windows users, the front end binaries for MinGW/x86 include -versions of the required w32api and mingw-runtime binaries. The last remaining step for -Windows users is to simply uncompress the binary binutils package from -<a href="http://mingw.org/">MinGW</a> into your front end installation directory. While the -front end installation steps are not quite the same as a typical manual MinGW installation, -they should be similar enough to those who have previously installed MinGW on Windows systems.</p> - -<p>To install binutils on Windows:</p> - -<ol> - <li><tt><i>download GNU Binutils from <a href="http://sourceforge.net/projects/mingw/files/">MinGW Downloads</a></i></tt></li> - <li><tt>cd <i>where-you-uncompressed-the-front-end</i></tt></li> - <li><tt><i>uncompress archived binutils directories (not the tar file) into the current directory</i></tt></li> -</ol> - -<p>The binary versions of the LLVM GCC front end may not suit all of your needs. For -example, the binary distribution may include an old version of a system header -file, not "fix" a header file that needs to be fixed for GCC, or it may be linked with -libraries not available on your system. In cases like these, you may want to try -<a href="GCCFEBuildInstrs.html">building the GCC front end from source</a>. Thankfully, -this is much easier now than it was in the past.</p> - -<p>We also do not currently support updating of the GCC front end by manually overlaying -newer versions of the w32api and mingw-runtime binary packages that may become available -from MinGW. At this time, it's best to think of the MinGW LLVM GCC front end binary as -a self-contained convenience package that requires Windows users to simply download and -uncompress the GNU Binutils binary package from the MinGW project.</p> - -<p>Regardless of your platform, if you discover that installing the LLVM GCC front end -binaries is not as easy as previously described, or you would like to suggest improvements, -please let us know how you would like to see things improved by dropping us a note on our -<a href="http://llvm.org/docs/#maillist">mailing list</a>.</p> - -</div> - -<!-- ======================================================================= --> -<h3> <a name="config">Local LLVM Configuration</a> </h3> @@ -1057,29 +985,6 @@ script to configure the build system:</p> <p>The following options can be used to set or enable LLVM specific options:</p> <dl> - <dt><i>--with-llvmgccdir</i></dt> - <dd>Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration. - The value of this option should specify the full pathname of the C/C++ Front - End to be used. If this option is not provided, the PATH will be searched for - a program named <i>llvm-gcc</i> and the C/C++ FrontEnd install directory will - be inferred from the path found. If the option is not given, and no llvm-gcc - can be found in the path then a warning will be produced by - <tt>configure</tt> indicating this situation. LLVM may still be built with - the <tt>tools-only</tt> target but attempting to build the runtime libraries - will fail as these libraries require llvm-gcc and llvm-g++. See - <a href="#installcf">Install the GCC Front End</a> for details on installing - the C/C++ Front End. See - <a href="GCCFEBuildInstrs.html">Bootstrapping the LLVM C/C++ Front-End</a> - for details on building the C/C++ Front End.</dd> - <dt><i>--with-tclinclude</i></dt> - <dd>Path to the tcl include directory under which <tt>tclsh</tt> can be - found. Use this if you have multiple tcl installations on your machine and you - want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the - dejagnu based test suite in <tt>llvm/test</tt>. If you don't specify this - option, the LLVM configure script will search for the tcl 8.4 and 8.3 - releases. - <br><br> - </dd> <dt><i>--enable-optimized</i></dt> <dd> Enables optimized compilation (debugging symbols are removed @@ -1110,7 +1015,7 @@ script to configure the build system:</p> selected as the target of the build host. You can also specify a comma separated list of target names that you want available in llc. The target names use all lower case. The current set of targets is: <br> - <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>. + <tt>arm, cbe, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu, x86, x86_64, xcore</tt>. <br><br></dd> <dt><i>--enable-doxygen</i></dt> <dd>Look for the doxygen program and enable construction of doxygen based @@ -1483,7 +1388,7 @@ different <a href="#tools">tools</a>.</p> <dd> This directory contains files that describe various target architectures for code generation. For example, the <tt>llvm/lib/Target/X86</tt> directory holds the X86 machine description while - <tt>llvm/lib/Target/CBackend</tt> implements the LLVM-to-C converter.</dd> + <tt>llvm/lib/Target/ARM</tt> implements the ARM backend.</dd> <dt><tt><b>llvm/lib/CodeGen/</b></tt></dt> <dd> This directory contains the major parts of the code generator: Instruction @@ -1530,7 +1435,7 @@ different <a href="#tools">tools</a>.</p> <div> <p>This directory contains libraries which are compiled into LLVM bitcode and -used when linking programs with the GCC front end. Most of these libraries are +used when linking programs with the Clang front end. Most of these libraries are skeleton versions of real libraries; for example, libc is a stripped down version of glibc.</p> @@ -1692,12 +1597,6 @@ are code generators for parts of LLVM infrastructure.</p> directory, switch to directory <tt>llvm/tools/llc</tt> and build it, causing a re-linking of LLC.<br><br> - <dt><tt><b>NewNightlyTest.pl</b></tt> and - <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a - cron script to generate nightly status reports of the functionality of - tools, and the results can be seen by following the appropriate link on - the <a href="http://llvm.org/">LLVM homepage</a>.<br><br> - <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains the tool used to generate register descriptions, instruction set descriptions, and even assemblers from common TableGen description @@ -1722,20 +1621,11 @@ are code generators for parts of LLVM infrastructure.</p> <!-- *********************************************************************** --> <div> -<p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete, -so we only include instructions for llvm-gcc4. -</p> - -<p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b> -from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b> -create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates, -the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and -<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode -output.</p> +<p>This section gives an example of using LLVM with the Clang front end.</p> <!-- ======================================================================= --> <h3> - <a name="tutorial4">Example with llvm-gcc4</a> + <a name="tutorial4">Example with clang</a> </h3> <div> @@ -1755,24 +1645,21 @@ int main() { <li><p>Next, compile the C file into a native executable:</p> - <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div> + <div class="doc_code"><pre>% clang hello.c -o hello</pre></div> - <p>Note that llvm-gcc works just like GCC by default. The standard -S and + <p>Note that clang works just like GCC by default. The standard -S and -c arguments work as usual (producing a native .s or .o file, respectively).</p></li> <li><p>Next, compile the C file into a LLVM bitcode file:</p> <div class="doc_code"> - <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div> + <pre>% clang -O3 -emit-llvm hello.c -c -o hello.bc</pre></div> <p>The -emit-llvm option can be used with the -S or -c options to emit an LLVM ".ll" or ".bc" file (respectively) for the code. This allows you to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on - the bitcode file.</p> - - <p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. - </p></li> + the bitcode file.</p></li> <li><p>Run the program in both forms. To run the program, use:</p> @@ -1811,7 +1698,7 @@ int main() { <div class="doc_code"><pre>% ./hello.native</pre></div> - <p>Note that using llvm-gcc to compile directly to native code (i.e. when + <p>Note that using clang to compile directly to native code (i.e. when the -emit-llvm option is not present) does steps 6/7/8 for you.</p> </li> @@ -1870,7 +1757,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-10-17 08:31:32 +0200 (Mon, 17 Oct 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> </html> diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index 6a60433..beadd0b 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -44,7 +44,7 @@ <p>There are many different projects that compose LLVM. The first is the LLVM suite. This contains all of the tools, libraries, and header files needed to - use the low level virtual machine. It contains an assembler, disassembler, + use LLVM. It contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It also contains a test suite that can be used to test the LLVM tools.</p> @@ -88,8 +88,8 @@ <div> - <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine. - The LLVM source tree and object files, libraries and executables will consume + <p>Any system that can adequately run Visual Studio 2008 is fine. The LLVM + source tree and object files, libraries and executables will consume approximately 3GB.</p> </div> @@ -98,10 +98,9 @@ <h3><a name="software"><b>Software</b></a></h3> <div> - <p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1 - beta and the normal VS2005 still have bugs that are not completely - compatible. Earlier versions of Visual Studio do not support the C++ standard - well enough and will not work.</p> + <p>You will need Visual Studio 2008 or higher. Earlier versions of Visual + Studio have bugs, are not completely compatible, or do not support the C++ + standard well enough.</p> <p>You will also need the <a href="http://www.cmake.org/">CMake</a> build system since it generates the project files you will use to build with.</p> @@ -363,7 +362,7 @@ out:</p> 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: 2012-01-25 23:00:23 +0100 (Wed, 25 Jan 2012) $ </address> </body> </html> diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index 375dd3c..2c08bd0 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -89,11 +89,11 @@ placed. <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>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>Any of these flags will also cause <tt>clang</tt> to look for the + gold plugin in the <tt>lib</tt> directory under its prefix and pass 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 @@ -141,10 +141,10 @@ void foo4(void) { } --- command lines --- -$ 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 -$ 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 +$ 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 +$ clang b.c -c -o b.o # <-- b.o is native object file +$ clang -flto a.a b.o -o main # <-- link with LLVMgold plugin </pre> <p>Gold informs the plugin that foo3 is never referenced outside the IR, @@ -171,13 +171,12 @@ $ clang -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin <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 clang and binutils): <pre class="doc_code"> -export CC="$PREFIX/bin/clang -use-gold-plugin" -export CXX="$PREFIX/bin/clang++ -use-gold-plugin" +export CC="$PREFIX/bin/clang -flto" +export CXX="$PREFIX/bin/clang++ -flto" 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 @@ -187,8 +186,8 @@ export CFLAGS="-O4" <li>Or you can just set your path: <pre class="doc_code"> export PATH="$PREFIX/bin:$PATH" -export CC="clang -use-gold-plugin" -export CXX="clang++ -use-gold-plugin" +export CC="clang -flto" +export CXX="clang++ -flto" export RANLIB=/bin/true export CFLAGS="-O4" </pre></li> diff --git a/docs/HowToAddABuilder.html b/docs/HowToAddABuilder.html new file mode 100644 index 0000000..0de2dac --- /dev/null +++ b/docs/HowToAddABuilder.html @@ -0,0 +1,142 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title> + How To Add Your Build Configuration To LLVM Buildbot Infrastructure + </title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<h1>How To Add Your Build Configuration To LLVM Buildbot Infrastructure</h1> +<ol> + <li><a href="#introduction">Introduction</a></li> + <li><a href="#steps">Steps To Add Builder To LLVM Buildbot</a></li> +</ol> +<div class="doc_author"> + <p>Written by <a href="mailto:gkistanova@gmail.com">Galina Kistanova</a></p> +</div> + +<!-- *********************************************************************** --> +<h2><a name="introduction">Introduction</a></h2> +<!-- *********************************************************************** --> + +<div> + +<p>This document contains information about adding a build configuration and + buildslave to private slave builder to LLVM Buildbot Infrastructure + <a href="http://lab.llvm.org:8011">http://lab.llvm.org:8011</a></p> + +</div> + +<!-- *********************************************************************** --> +<h2><a name="steps">Steps To Add Builder To LLVM Buildbot</a></h2> +<!-- *********************************************************************** --> + +<div> + +<p>Volunteers can provide their build machines to work as build slaves to + public LLVM Buildbot.</p> + +<p>Here are the steps you can follow to do so:</p> + +<ol> + <li><p>Check the existing build configurations to make sure the one you are + interested in is not covered yet or gets built on your computer much + faster than on the existing one. We prefer faster builds so developers + will get feedback sooner after changes get committed.</p></li> + + <li><p>The computer you will be registering with the LLVM buildbot + infrastructure should have all dependencies installed and you can + actually build your configuration successfully. Please check what degree + of parallelism (-j param) would give the fastest build. + You can build multiple configurations on one computer.</p></li> + + <li><p>Install buildslave (currently we are using buildbot version 0.8.5). + Depending on the platform, buildslave could be available to download and + install with your packet manager, or you can download it directly from + <a href="http://trac.buildbot.net">http://trac.buildbot.net</a> and + install it manually.</p></li> + + <li><p>Create a designated user account, your buildslave will be running + under, and set appropriate permissions.</p></li> + + <li><p>Choose the buildslave root directory (all builds will be placed under + it), buildslave access name and password the build master will be using + to authenticate your buildslave.</p></li> + + <li><p>Create a buildslave in context of that buildslave account. + Point it to the <b>lab.llvm.org</b> port <b>9990</b> (see + <a href="http://buildbot.net/buildbot/docs/current/full.html#creating-a-slave"> + Buildbot documentation, Creating a slave</a> + for more details) by running the following command:</p> + +<div class="doc_code"> +<pre> +$ buildslave create-slave <i>buildslave-root-directory</i> \ + lab.llvm.org:9990 \ + <i>buildslave-access-name buildslave-access-password</i> +</pre> +</div></li> + + <li><p>Fill the buildslave description and admin name/e-mail. + Here is an example of the buildslave description:</p> + +<div class="doc_code"> +<pre> +Windows 7 x64 +Core i7 (2.66GHz), 16GB of RAM + +g++.exe (TDM-1 mingw32) 4.4.0 +GNU Binutils 2.19.1 +cmake version 2.8.4 +Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86 +</pre> +</div></li> + + <li><p>Make sure you can actually start the buildslave successfully. Then set + up your buildslave to start automatically at the start up time. + See the buildbot documentation for help. + You may want to restart your computer to see if it works.</p></li> + + <li><p>Send a patch which adds your build slave and your builder to zorg.</p> + <ul> + <li>slaves are added to + <tt>buildbot/osuosl/master/config/slaves.py</tt></li> + <li>builders are added to + <tt>buildbot/osuosl/master/config/builders.py</tt></li> + </ul></li> + + <li><p>Send the buildslave access name and the access password directly + to <a href="mailto:gkistanova@gmail.com">Galina Kistanova</a>, and wait + till she will let you know that your changes are applied and buildmaster + is reconfigured.</p> + + <li><p>Check the status of your buildslave on the + <a href="http://lab.llvm.org:8011/waterfall">Waterfall Display</a> + to make sure it is connected, and + <a href="http://lab.llvm.org:8011/buildslaves/your-buildslave-name"> + http://lab.llvm.org:8011/buildslaves/<your-buildslave-name></a> + to see if administrator contact and slave information are correct.</p> + </li> + + <li><p>Wait for the first build to succeed and enjoy.</p></li> +</ol> + +</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/">The LLVM Compiler Infrastructure</a> + <br> + Last modified: $Date: 2011-10-31 12:50:0 -0700 (Mon, 31 Oct 2011) $ +</address> +</body> +</html> diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index 8588f3f..30c4f0c 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -575,7 +575,7 @@ $ svn copy https://llvm.org/svn/llvm-project/test-suite/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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> </html> diff --git a/docs/HowToSubmitABug.html b/docs/HowToSubmitABug.html index a6e5a70..0071ec6 100644 --- a/docs/HowToSubmitABug.html +++ b/docs/HowToSubmitABug.html @@ -341,7 +341,7 @@ the following:</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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> diff --git a/docs/LLVMBuild.html b/docs/LLVMBuild.html new file mode 100644 index 0000000..cce607d --- /dev/null +++ b/docs/LLVMBuild.html @@ -0,0 +1,363 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title>LLVMBuild Documentation</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<h1>LLVMBuild Guide</h1> + +<ol> + <li><a href="#introduction">Introduction</a></li> + <li><a href="#projectorg">Project Organization</a></li> + <li><a href="#buildintegration">Build Integration</a></li> + <li><a href="#componentoverview">Component Overview</a></li> + <li><a href="#formatreference">Format Reference</a></li> +</ol> + +<!-- *********************************************************************** --> +<h2><a name="introduction">Introduction</a></h2> +<!-- *********************************************************************** --> + +<div> + <p>This document describes the <tt>LLVMBuild</tt> organization and files which + we use to describe parts of the LLVM ecosystem. For description of specific + LLVMBuild related tools, please see the command guide.</p> + + <p>LLVM is designed to be a modular set of libraries which can be flexibly + mixed together in order to build a variety of tools, like compilers, JITs, + custom code generators, optimization passes, interpreters, and so on. Related + projects in the LLVM system like Clang and LLDB also tend to follow this + philosophy.</p> + + <p>In order to support this usage style, LLVM has a fairly strict structure as + to how the source code and various components are organized. The + <tt>LLVMBuild.txt</tt> files are the explicit specification of that structure, + and are used by the build systems and other tools in order to develop the LLVM + project.</p> +</div> + +<!-- *********************************************************************** --> +<h2><a name="projectorg">Project Organization</a></h2> +<!-- *********************************************************************** --> + +<!-- FIXME: We should probably have an explicit top level project object. Good +place to hang project level data, name, etc. Also useful for serving as the +$ROOT of project trees for things which can be checked out separately. --> + +<div> + <p>The source code for LLVM projects using the LLVMBuild system (LLVM, Clang, + and LLDB) is organized into <em>components</em>, which define the separate + pieces of functionality that make up the project. These projects may consist + of many libraries, associated tools, build tools, or other utility tools (for + example, testing tools).</p> + + <p>For the most part, the project contents are organized around defining one + main component per each subdirectory. Each such directory contains + an <tt>LLVMBuild.txt</tt> which contains the component definitions.</p> + + <p>The component descriptions for the project as a whole are automatically + gathered by the LLVMBuild tools. The tools automatically traverse the source + directory structure to find all of the component description files. NOTE: For + performance/sanity reasons, we only traverse into subdirectories when the + parent itself contains an <tt>LLVMBuild.txt</tt> description file.</p> +</div> + +<!-- *********************************************************************** --> +<h2><a name="buildintegration">Build Integration</a></h2> +<!-- *********************************************************************** --> + +<div> + <p>The LLVMBuild files themselves are just a declarative way to describe the + project structure. The actual building of the LLVM project is handled by + another build system (currently we support + both <a href="MakefileGuide.html">Makefiles</a> + and <a href="CMake.html">CMake</a>.</p> + + <p>The build system implementation will load the relevant contents of the + LLVMBuild files and use that to drive the actual project build. Typically, the + build system will only need to load this information at "configure" time, and + use it to generative native information. Build systems will also handle + automatically reconfiguring their information when the contents of + the <i>LLVMBuild.txt</i> files change.</p> + + <p>Developers generally are not expected to need to be aware of the details of + how the LLVMBuild system is integrated into their build. Ideally, LLVM + developers who are not working on the build system would only ever need to + modify the contents of the <i>LLVMBuild.txt</i> description files (although we + have not reached this goal yet).</p> + + <p>For more information on the utility tool we provide to help interfacing + with the build system, please see + the <a href="CommandGuide/html/llvm-build.html">llvm-build</a> + documentation.</p> +</div> + +<!-- *********************************************************************** --> +<h2><a name="componentoverview">Component Overview</a></h2> +<!-- *********************************************************************** --> + +<div> + <p>As mentioned earlier, LLVM projects are organized into + logical <em>components</em>. Every component is typically grouped into it's + own subdirectory. Generally, a component is organized around a coherent group + of sources which have some kind of clear API separation from other parts of + the code.</p> + + <p>LLVM primarily uses the following types of components:</p> + <ul> + <li><em>Libraries</em> - Library components define a distinct API which can + be independently linked into LLVM client applications. Libraries typically + have private and public header files, and may specify a link of required + libraries that they build on top of.</li> + + <li><em>Build Tools</em> - Build tools are applications which are designed + to be run as part of the build process (typically to generate other source + files). Currently, LLVM uses one main build tool + called <a href="TableGenFundamentals.html">TableGen</a> to generate a + variety of source files.</li> + + <li><em>Tools</em> - Command line applications which are built using the + LLVM component libraries. Most LLVM tools are small and are primarily + frontends to the library interfaces.</li> + +<!-- FIXME: We also need shared libraries as a first class component, but this + is not yet implemented. --> + </ul> + + <p>Components are described using <em>LLVMBuild.txt</em> files in the + directories that define the component. See + the <a href="#formatreference">Format Reference</a> section for information on + the exact format of these files.</p> +</div> + +<!-- *********************************************************************** --> +<h2><a name="formatreference">LLVMBuild Format Reference</a></h2> +<!-- *********************************************************************** --> + +<div> + <p>LLVMBuild files are written in a simple variant of the INI or configuration + file format (<a href="http://en.wikipedia.org/wiki/INI_file">Wikipedia + entry</a>). The format defines a list of sections each of which may contain + some number of properties. A simple example of the file format is below:</p> + <div class="doc_code"> + <pre> +<i>; Comments start with a semi-colon.</i> + +<i>; Sections are declared using square brackets.</i> +[component_0] + +<i>; Properties are declared using '=' and are contained in the previous section. +; +; We support simple string and boolean scalar values and list values, where +; items are separated by spaces. There is no support for quoting, and so +; property values may not contain spaces.</i> +property_name = property_value +list_property_name = value_1 value_2 <em>...</em> value_n +boolean_property_name = 1 <em>(or 0)</em> +</pre> + </div> + + <p>LLVMBuild files are expected to define a strict set of sections and + properties. An typical component description file for a library + component would look typically look like the following example:</p> + <div class="doc_code"> + <pre> +[component_0] +type = Library +name = Linker +parent = Libraries +required_libraries = Archive BitReader Core Support TransformUtils +</pre> + </div> + + <p>A full description of the exact sections and properties which are allowed + follows.</p> + + <p>Each file may define exactly one common component, named "common". The + common component may define the following properties:</p> + <ul> + <li><i>subdirectories</i> <b>[optional]</b> + <p>If given, a list of the names of the subdirectories from the current + subpath to search for additional LLVMBuild files.</p></li> + </ul> + + <p>Each file may define multiple components. Each component is described by a + section who name starts with "component". The remainder of the section name is + ignored, but each section name must be unique. Typically components are just + number in order for files with multiple components ("component_0", + "component_1", and so on).<p> + + <p><b>Section names not matches this format (or the "common" section) are + currently unused and are disallowed.</b></p> + + <p>Every component is defined by the properties in the section. The exact list + of properties that are allowed depends on the component + type. Components <b>may not</b> define any properties other than those + expected by the component type.</p> + + <p>Every component must define the following properties:</p> + <ul> + <li><i>type</i> <b>[required]</b> + <p>The type of the component. Supported component types are + detailed below. Most components will define additional properties which + may be required or optional.</p></li> + + <li><i>name</i> <b>[required]</b> + <p>The name of the component. Names are required to be unique + across the entire project.</p></li> + + <li><i>parent</i> <b>[required]</b> + <p>The name of the logical parent of the component. Components are + organized into a logical tree to make it easier to navigate and organize + groups of components. The parent's have no semantics as far as the project + build is concerned, however. Typically, the parent will be the main + component of the parent directory.</p> + + <!-- FIXME: Should we make the parent optional, and default to parent + directories component? --> + + <p>Components may reference the root pseudo component using '$ROOT' to + indicate they should logically be grouped at the top-level.</p> + </li> + </ul> + + <p>Components may define the following properties:</p> + <ul> + <li><i>dependencies</i> <b>[optional]</b> + <p>If specified, a list of names of components which <i>must</i> be built + prior to this one. This should only be exactly those components which + produce some tool or source code required for building the + component.</p> + + <p><em>NOTE:</em> Group and LibraryGroup components have no semantics for + the actual build, and are not allowed to specify dependencies.</p></li> + </ul> + + <p>The following section lists the available component types, as well as the + properties which are associated with that component.</p> + + <ul> + <li><i>type = Group</i> + <p>Group components exist purely to allow additional arbitrary structuring + of the logical components tree. For example, one might define a + "Libraries" group to hold all of the root library components.</p> + + <p>Group components have no additionally properties.</p> + </li> + + <li><i>type = Library</i> + <p>Library components define an individual library which should be built + from the source code in the component directory.</p> + + <p>Components with this type use the following properties:</p> + <ul> + <li><i>library_name</i> <b>[optional]</b> + <p>If given, the name to use for the actual library file on disk. If + not given, the name is derived from the component name + itself.</p></li> + + <li><i>required_libraries</i> <b>[optional]</b> + <p>If given, a list of the names of Library or LibraryGroup components + which must also be linked in whenever this library is used. That is, + the link time dependencies for this component. When tools are built, + the build system will include the transitive closer of + all <i>required_libraries</i> for the components the tool needs.</p></li> + + <li><i>add_to_library_groups</i> <b>[optional]</b> + <p>If given, a list of the names of LibraryGroup components which this + component is also part of. This allows nesting groups of + components. For example, the <i>X86</i> target might define a library + group for all of the <i>X86</i> components. That library group might + then be included in the <i>all-targets</i> library group.</p></li> + </ul> + </li> + + <li><i>type = LibraryGroup</i> + <p>LibraryGroup components are a mechanism to allow easy definition of + useful sets of related components. In particular, we use them to easily + specify things like "all targets", or "all assembly printers".</p> + + <p>Components with this type use the following properties:</p> + <ul> + <li><i>required_libraries</i> <b>[optional]</b> + <p>See the Library type for a description of this property.</p></li> + + <li><i>add_to_library_groups</i> <b>[optional]</b> + <p>See the Library type for a description of this property.</p></li> + </ul> + </li> + + <li><i>type = TargetGroup</i> + <p>TargetGroup components are an extension of LibraryGroups, specifically + for defining LLVM targets (which are handled specially in a few + places).</p> + + <p>The name of the component should always be the name of the target.</p> + + <p>Components with this type use the LibraryGroup properties in addition + to:</p> + <ul> + <li><i>has_asmparser</i> <b>[optional]</b> <b>[boolean]</b> + <p>Whether this target defines an assembly parser.</p></li> + <li><i>has_asmprinter</i> <b>[optional]</b> <b>[boolean]</b> + <p>Whether this target defines an assembly printer.</p></li> + <li><i>has_disassembler</i> <b>[optional]</b> <b>[boolean]</b> + <p>Whether this target defines a disassembler.</p></li> + <li><i>has_jit</i> <b>[optional]</b> <b>[boolean]</b> + <p>Whether this target supports JIT compilation.</p></li> + </ul> + </li> + + <li><i>type = Tool</i> + <p>Tool components define standalone command line tools which should be + built from the source code in the component directory and linked.</p> + + <p>Components with this type use the following properties:</p> + <ul> + <li><i>required_libraries</i> <b>[optional]</b> + + <p>If given, a list of the names of Library or LibraryGroup components + which this tool is required to be linked with. <b>NOTE:</b> The values + should be the component names, which may not always match up with the + actual library names on disk.</p> + + <p>Build systems are expected to properly include all of the libraries + required by the linked components (i.e., the transitive closer + of <em>required_libraries</em>).</p> + + <p>Build systems are also expected to understand that those library + components must be built prior to linking -- they do not also need to + be listed under <i>dependencies</i>.</p></li> + </ul> + </li> + + <li><i>type = BuildTool</i> + <p>BuildTool components are like Tool components, except that the tool is + supposed to be built for the platform where the build is running (instead + of that platform being targetted). Build systems are expected to handle + the fact that required libraries may need to be built for multiple + platforms in order to be able to link this tool.</p> + + <p>BuildTool components currently use the exact same properties as Tool + components, the type distinction is only used to differentiate what the + tool is built for.</p> + </li> + </ul> +</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/">The LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> +</body> +</html> diff --git a/docs/LLVMBuild.txt b/docs/LLVMBuild.txt new file mode 100644 index 0000000..d5aea86 --- /dev/null +++ b/docs/LLVMBuild.txt @@ -0,0 +1,21 @@ +;===- ./docs/LLVMBuild.txt -------------------------------------*- Conf -*--===; +; +; The LLVM Compiler Infrastructure +; +; This file is distributed under the University of Illinois Open Source +; License. See LICENSE.TXT for details. +; +;===------------------------------------------------------------------------===; +; +; This is an LLVMBuild description file for the components in this subdirectory. +; +; For more information on the LLVMBuild system, please see: +; +; http://llvm.org/docs/LLVMBuild.html +; +;===------------------------------------------------------------------------===; + +[component_0] +type = Group +name = Docs +parent = $ROOT diff --git a/docs/LangRef.html b/docs/LangRef.html index 3d01b60..d1c6e58 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -92,7 +92,7 @@ <li><a href="#complexconstants">Complex Constants</a></li> <li><a href="#globalconstants">Global Variable and Function Addresses</a></li> <li><a href="#undefvalues">Undefined Values</a></li> - <li><a href="#trapvalues">Trap Values</a></li> + <li><a href="#poisonvalues">Poison Values</a></li> <li><a href="#blockaddress">Addresses of Basic Blocks</a></li> <li><a href="#constantexprs">Constant Expressions</a></li> </ol> @@ -100,7 +100,18 @@ <li><a href="#othervalues">Other Values</a> <ol> <li><a href="#inlineasm">Inline Assembler Expressions</a></li> - <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li> + <li><a href="#metadata">Metadata Nodes and Metadata Strings</a> + <ol> + <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li> + <li><a href="#fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a></li> + <li><a href="#range">'<tt>range</tt>' Metadata</a></li> + </ol> + </li> + </ol> + </li> + <li><a href="#module_flags">Module Flags Metadata</a> + <ol> + <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a></li> </ol> </li> <li><a href="#intrinsic_globals">Intrinsic Global Variables</a> @@ -123,7 +134,6 @@ <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li> <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> @@ -283,10 +293,10 @@ </li> <li><a href="#int_memorymarkers">Memory Use Markers</a> <ol> - <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li> - <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li> - <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li> - <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li> + <li><a href="#int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a></li> + <li><a href="#int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a></li> + <li><a href="#int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a></li> + <li><a href="#int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a></li> </ol> </li> <li><a href="#int_general">General intrinsics</a> @@ -301,6 +311,8 @@ '<tt>llvm.stackprotector</tt>' Intrinsic</a></li> <li><a href="#int_objectsize"> '<tt>llvm.objectsize</tt>' Intrinsic</a></li> + <li><a href="#int_expect"> + '<tt>llvm.expect</tt>' Intrinsic</a></li> </ol> </li> </ol> @@ -479,43 +491,43 @@ <div> -<p>LLVM programs are composed of "Module"s, each of which is a translation unit - of the input programs. Each module consists of functions, global variables, - and symbol table entries. Modules may be combined together with the LLVM - linker, which merges function (and global variable) definitions, resolves - forward declarations, and merges symbol table entries. Here is an example of - the "hello world" module:</p> +<p>LLVM programs are composed of <tt>Module</tt>s, each of which is a + translation unit of the input programs. Each module consists of functions, + global variables, and symbol table entries. Modules may be combined together + with the LLVM linker, which merges function (and global variable) + definitions, resolves forward declarations, and merges symbol table + entries. Here is an example of the "hello world" module:</p> <pre class="doc_code"> <i>; Declare the string constant as a global constant.</i> -<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i> +<a href="#identifiers">@.str</a> = <a href="#linkage_private">private</a> <a href="#globalvars">unnamed_addr</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; External declaration of the puts function</i> -<a href="#functionstructure">declare</a> i32 @puts(i8*) <i>; i32 (i8*)* </i> +<a href="#functionstructure">declare</a> i32 @puts(i8* <a href="#nocapture">nocapture</a>) <a href="#fnattrs">nounwind</a> <i>; Definition of main function</i> define i32 @main() { <i>; i32()* </i> <i>; Convert [13 x i8]* to i8 *...</i> - %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8*</i> + %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.str, i64 0, i64 0 <i>; Call puts function to write out the string to stdout.</i> - <a href="#i_call">call</a> i32 @puts(i8* %cast210) <i>; i32</i> + <a href="#i_call">call</a> i32 @puts(i8* %cast210) <a href="#i_ret">ret</a> i32 0 } <i>; Named metadata</i> -!1 = metadata !{i32 41} +!1 = metadata !{i32 42} !foo = !{!1, null} </pre> <p>This example is made up of a <a href="#globalvars">global variable</a> named - "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, + "<tt>.str</tt>", an external declaration of the "<tt>puts</tt>" function, a <a href="#functionstructure">function definition</a> for "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a> - "<tt>foo"</tt>.</p> + "<tt>foo</tt>".</p> -<p>In general, a module is made up of a list of global values, where both - functions and global variables are global values. Global values are +<p>In general, a module is made up of a list of global values (where both + functions and global variables are global values). Global values are represented by a pointer to a memory location (in this case, a pointer to an array of char, and a pointer to a function), and have one of the following <a href="#linkage">linkage types</a>.</p> @@ -630,7 +642,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">external</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> @@ -927,7 +939,7 @@ define i32 @main() { <i>; i32()* </i> alignments must be a power of 2.</p> <p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not - be significant and two identical functions can be merged</p>. + be significant and two identical functions can be merged.</p> <h5>Syntax:</h5> <pre class="doc_code"> @@ -1136,6 +1148,10 @@ define void @f() optsize { ... } </pre> <dl> + <dt><tt><b>address_safety</b></tt></dt> + <dd>This attribute indicates that the address safety analysis + is enabled for this function. </dd> + <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt> <dd>This attribute indicates that, when emitting the prologue and epilogue, the backend should forcibly align the stack pointer. Specify the @@ -1195,8 +1211,7 @@ define void @f() optsize { ... } It does not write through any pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) and never changes any state visible to callers. This means that it cannot unwind - exceptions by calling the <tt>C++</tt> exception throwing methods, but - could use the <tt>unwind</tt> instruction.</dd> + exceptions by calling the <tt>C++</tt> exception throwing methods.</dd> <dt><tt><b><a name="readonly">readonly</a></b></tt></dt> <dd>This attribute indicates that the function does not write through any @@ -1206,8 +1221,13 @@ define void @f() optsize { ... } and read state that may be set in the caller. A readonly function always returns the same value (or unwinds an exception identically) when called with the same set of arguments and global state. It cannot unwind an - exception by calling the <tt>C++</tt> exception throwing methods, but may - use the <tt>unwind</tt> instruction.</dd> + exception by calling the <tt>C++</tt> exception throwing methods.</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> <dt><tt><b><a name="ssp">ssp</a></b></tt></dt> <dd>This attribute indicates that the function should emit a stack smashing @@ -1236,12 +1256,6 @@ define void @f() optsize { ... } 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> @@ -1603,7 +1617,7 @@ 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="Atomics.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> @@ -1702,7 +1716,7 @@ in signal handlers).</p> </tr> <tr> <td><a href="#t_floating">floating point</a></td> - <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td> + <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td> </tr> <tr> <td><a name="t_firstclass">first class</a></td> @@ -1802,6 +1816,7 @@ in signal handlers).</p> <table> <tbody> <tr><th>Type</th><th>Description</th></tr> + <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr> <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> @@ -1906,9 +1921,9 @@ in signal handlers).</p> <div> <p>Aggregate Types are a subset of derived types that can contain multiple - member types. <a href="#t_array">Arrays</a>, - <a href="#t_struct">structs</a>, and <a href="#t_vector">vectors</a> are - aggregate types.</p> + member types. <a href="#t_array">Arrays</a> and + <a href="#t_struct">structs</a> are aggregate types. + <a href="#t_vector">Vectors</a> are not considered to be aggregate types.</p> </div> @@ -2182,8 +2197,8 @@ in signal handlers).</p> </pre> <p>The number of elements is a constant integer value larger than 0; elementtype - may be any integer or floating point type. Vectors of size zero are not - allowed, and pointers are not allowed as the element type.</p> + may be any integer or floating point type, or a pointer to these types. + Vectors of size zero are not allowed. </p> <h5>Examples:</h5> <table class="layout"> @@ -2199,6 +2214,10 @@ in signal handlers).</p> <td class="left"><tt><2 x i64></tt></td> <td class="left">Vector of 2 64-bit integer values.</td> </tr> + <tr class="layout"> + <td class="left"><tt><4 x i64*></tt></td> + <td class="left">Vector of 4 pointers to 64-bit integer values.</td> + </tr> </table> </div> @@ -2257,10 +2276,11 @@ in signal handlers).</p> represented in their IEEE hexadecimal format so that assembly and disassembly do not cause any bits to change in the constants.</p> -<p>When using the hexadecimal form, constants of types float and double are +<p>When using the hexadecimal form, constants of types half, float, and double are represented using the 16-digit form shown above (which matches the IEEE754 - representation for double); float values must, however, be exactly - representable as IEE754 single precision. Hexadecimal format is always used + representation for double); half and float values must, however, be exactly + representable as IEE754 half and single precision, respectively. + Hexadecimal format is always used for long double, and there are three forms of long double. The 80-bit format used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. The 128-bit format used by PowerPC (two adjacent doubles) is represented @@ -2495,22 +2515,21 @@ b: unreachable <!-- ======================================================================= --> <h3> - <a name="trapvalues">Trap Values</a> + <a name="poisonvalues">Poison Values</a> </h3> <div> -<p>Trap values are similar to <a href="#undefvalues">undef values</a>, however - instead of representing an unspecified bit pattern, they represent the - fact that an instruction or constant expression which cannot evoke side - effects has nevertheless detected a condition which results in undefined - behavior.</p> +<p>Poison values are similar to <a href="#undefvalues">undef values</a>, however + they also represent the fact that an instruction or constant expression which + cannot evoke side effects has nevertheless detected a condition which results + in undefined behavior.</p> -<p>There is currently no way of representing a trap value in the IR; they +<p>There is currently no way of representing a poison value in the IR; they only exist when produced by operations such as <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p> -<p>Trap value behavior is defined in terms of value <i>dependence</i>:</p> +<p>Poison value behavior is defined in terms of value <i>dependence</i>:</p> <ul> <li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on @@ -2527,7 +2546,7 @@ b: unreachable control back to them.</li> <li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the - <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>, + <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>, or exception-throwing call instructions that dynamically transfer control back to them.</li> @@ -2561,62 +2580,61 @@ b: unreachable </ul> -<p>Whenever a trap value is generated, all values which depend on it evaluate - 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> +<p>Poison Values have the same behavior as <a href="#undefvalues">undef values</a>, + with the additional affect that any instruction which has a <i>dependence</i> + on a poison value has undefined behavior.</p> <p>Here are some examples:</p> <pre class="doc_code"> entry: - %trap = sub nuw i32 0, 1 ; Results in a trap value. - %still_trap = and i32 %trap, 0 ; Whereas (and i32 undef, 0) would return 0. - %trap_yet_again = getelementptr i32* @h, i32 %still_trap - store i32 0, i32* %trap_yet_again ; undefined behavior + %poison = sub nuw i32 0, 1 ; Results in a poison value. + %still_poison = and i32 %poison, 0 ; 0, but also poison. + %poison_yet_again = getelementptr i32* @h, i32 %still_poison + store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned - store i32 %trap, i32* @g ; Trap value conceptually stored to memory. - %trap2 = load i32* @g ; Returns a trap value, not just undef. + store i32 %poison, i32* @g ; Poison value stored to memory. + %poison2 = load i32* @g ; Poison value loaded back from memory. - volatile store i32 %trap, i32* @g ; External observation; undefined behavior. + store volatile i32 %poison, i32* @g ; External observation; undefined behavior. %narrowaddr = bitcast i32* @g to i16* %wideaddr = bitcast i32* @g to i64* - %trap3 = load i16* %narrowaddr ; Returns a trap value. - %trap4 = load i64* %wideaddr ; Returns a trap value. + %poison3 = load i16* %narrowaddr ; Returns a poison value. + %poison4 = load i64* %wideaddr ; Returns a poison value. - %cmp = icmp slt i32 %trap, 0 ; Returns a trap value. - br i1 %cmp, label %true, label %end ; Branch to either destination. + %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. + br i1 %cmp, label %true, label %end ; Branch to either destination. true: - volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so - ; it has undefined behavior. + store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so + ; it has undefined behavior. br label %end end: %p = phi i32 [ 0, %entry ], [ 1, %true ] - ; Both edges into this PHI are - ; control-dependent on %cmp, so this - ; always results in a trap value. + ; Both edges into this PHI are + ; control-dependent on %cmp, so this + ; always results in a poison value. - volatile store i32 0, i32* @g ; This would depend on the store in %true - ; if %cmp is true, or the store in %entry - ; otherwise, so this is undefined behavior. + store volatile i32 0, i32* @g ; This would depend on the store in %true + ; if %cmp is true, or the store in %entry + ; otherwise, so this is undefined behavior. br i1 %cmp, label %second_true, label %second_end - ; The same branch again, but this time the - ; true block doesn't have side effects. + ; The same branch again, but this time the + ; true block doesn't have side effects. second_true: ; No side effects! ret void second_end: - volatile store i32 0, i32* @g ; This time, the instruction always depends - ; on the store in %end. Also, it is - ; control-equivalent to %end, so this is - ; well-defined (again, ignoring earlier - ; undefined behavior in this example). + store volatile i32 0, i32* @g ; This time, the instruction always depends + ; on the store in %end. Also, it is + ; control-equivalent to %end, so this is + ; well-defined (ignoring earlier undefined + ; behavior in this example). </pre> </div> @@ -2795,7 +2813,7 @@ second_end: <div> <p>LLVM supports inline assembler expressions (as opposed - to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of + to <a href="#moduleasm">Module-Level Inline Assembly</a>) through the use of a special value. This value represents the inline assembler as a string (containing the instructions to emit), a list of operand constraints (stored as a string), a flag that indicates whether or not the inline asm @@ -2837,23 +2855,27 @@ call void asm alignstack "eieio", ""() <p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come first.</p> +<!-- <p>TODO: The format of the asm and constraints string still need to be documented here. Constraints on what can be done (e.g. duplication, moving, etc need to be documented). This is probably best done by reference to another document that covers inline asm from a holistic perspective.</p> + --> +<!-- _______________________________________________________________________ --> <h4> -<a name="inlineasm_md">Inline Asm Metadata</a> + <a name="inlineasm_md">Inline Asm Metadata</a> </h4> <div> -<p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode - attached to it that contains a list of constant integers. If present, the - code generator will use the integer as the location cookie value when report - errors through the LLVMContext error reporting mechanisms. This allows a - front-end to correlate backend errors that occur with inline asm back to the - source code that produced it. For example:</p> +<p>The call instructions that wrap inline asm nodes may have a + "<tt>!srcloc</tt>" MDNode attached to it that contains a list of constant + integers. If present, the code generator will use the integer as the + location cookie value when report errors through the <tt>LLVMContext</tt> + error reporting mechanisms. This allows a front-end to correlate backend + errors that occur with inline asm back to the source code that produced it. + For example:</p> <pre class="doc_code"> call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b> @@ -2862,7 +2884,7 @@ call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b> </pre> <p>It is up to the front-end to make sense of the magic numbers it places in the - IR. If the MDNode contains multiple constants, the code generator will use + IR. If the MDNode contains multiple constants, the code generator will use the one that corresponds to the line of the asm that the error occurs on.</p> </div> @@ -2884,20 +2906,33 @@ call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b> preceding exclamation point ('<tt>!</tt>').</p> <p>A metadata string is a string surrounded by double quotes. It can contain - any character by escaping non-printable characters with "\xx" where "xx" is - the two digit hex code. For example: "<tt>!"test\00"</tt>".</p> + any character by escaping non-printable characters with "<tt>\xx</tt>" where + "<tt>xx</tt>" is the two digit hex code. For example: + "<tt>!"test\00"</tt>".</p> <p>Metadata nodes are represented with notation similar to structure constants (a comma separated list of elements, surrounded by braces and preceded by an - exclamation point). For example: "<tt>!{ metadata !"test\00", i32 - 10}</tt>". Metadata nodes can have any values as their operand.</p> + exclamation point). Metadata nodes can have any values as their operand. For + example:</p> + +<div class="doc_code"> +<pre> +!{ metadata !"test\00", i32 10} +</pre> +</div> <p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of metadata nodes, which can be looked up in the module symbol table. For - example: "<tt>!foo = metadata !{!4, !3}</tt>". + example:</p> + +<div class="doc_code"> +<pre> +!foo = metadata !{!4, !3} +</pre> +</div> <p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt> - function is using two metadata arguments.</p> + function is using two metadata arguments:</p> <div class="doc_code"> <pre> @@ -2906,7 +2941,8 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) </div> <p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is - attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.</p> + attached to the <tt>add</tt> instruction using the <tt>!dbg</tt> + identifier:</p> <div class="doc_code"> <pre> @@ -2914,6 +2950,325 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) </pre> </div> +<p>More information about specific metadata nodes recognized by the optimizers + and code generator is found below.</p> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="tbaa">'<tt>tbaa</tt>' Metadata</a> +</h4> + +<div> + +<p>In LLVM IR, memory does not have types, so LLVM's own type system is not + suitable for doing TBAA. Instead, metadata is added to the IR to describe + a type system of a higher level language. This can be used to implement + typical C/C++ TBAA, but it can also be used to implement custom alias + analysis behavior for other languages.</p> + +<p>The current metadata format is very simple. TBAA metadata nodes have up to + three fields, e.g.:</p> + +<div class="doc_code"> +<pre> +!0 = metadata !{ metadata !"an example type tree" } +!1 = metadata !{ metadata !"int", metadata !0 } +!2 = metadata !{ metadata !"float", metadata !0 } +!3 = metadata !{ metadata !"const float", metadata !2, i64 1 } +</pre> +</div> + +<p>The first field is an identity field. It can be any value, usually + a metadata string, which uniquely identifies the type. The most important + name in the tree is the name of the root node. Two trees with + different root node names are entirely disjoint, even if they + have leaves with common names.</p> + +<p>The second field identifies the type's parent node in the tree, or + is null or omitted for a root node. A type is considered to alias + all of its descendants and all of its ancestors in the tree. Also, + a type is considered to alias all types in other trees, so that + bitcode produced from multiple front-ends is handled conservatively.</p> + +<p>If the third field is present, it's an integer which if equal to 1 + indicates that the type is "constant" (meaning + <tt>pointsToConstantMemory</tt> should return true; see + <a href="AliasAnalysis.html#OtherItfs">other useful + <tt>AliasAnalysis</tt> methods</a>).</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="fpaccuracy">'<tt>fpaccuracy</tt>' Metadata</a> +</h4> + +<div> + +<p><tt>fpaccuracy</tt> metadata may be attached to any instruction of floating + point type. It expresses the maximum relative error allowed in the result + of that instruction, in ULPs, thus potentially allowing the compiler to use + a more efficient but less accurate method of computing it. + ULP is defined as follows:</p> + +<blockquote> + +<p>If <tt>x</tt> is a real number that lies between two finite consecutive + floating-point numbers <tt>a</tt> and <tt>b</tt>, without being equal to one + of them, then <tt>ulp(x) = |b - a|</tt>, otherwise <tt>ulp(x)</tt> is the + distance between the two non-equal finite floating-point numbers nearest + <tt>x</tt>. Moreover, <tt>ulp(NaN)</tt> is <tt>NaN</tt>.</p> + +</blockquote> + +<p>The metadata node shall consist of a single non-negative floating + point number representing the maximum relative error. For example, + 2.5 ULP:</p> + +<div class="doc_code"> +<pre> +!0 = metadata !{ float 2.5 } +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> + <a name="range">'<tt>range</tt>' Metadata</a> +</h4> + +<div> +<p><tt>range</tt> metadata may be attached only to loads of integer types. It + expresses the possible ranges the loaded value is in. The ranges are + represented with a flattened list of integers. The loaded value is known to + be in the union of the ranges defined by each consecutive pair. Each pair + has the following properties:</p> +<ul> + <li>The type must match the type loaded by the instruction.</li> + <li>The pair <tt>a,b</tt> represents the range <tt>[a,b)</tt>.</li> + <li>Both <tt>a</tt> and <tt>b</tt> are constants.</li> + <li>The range is allowed to wrap.</li> + <li>The range should not represent the full or empty set. That is, + <tt>a!=b</tt>. </li> +</ul> + +<p>Examples:</p> +<div class="doc_code"> +<pre> + %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1 + %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 + %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5 +... +!0 = metadata !{ i8 0, i8 2 } +!1 = metadata !{ i8 255, i8 2 } +!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 } +</pre> +</div> +</div> +</div> + +</div> + +<!-- *********************************************************************** --> +<h2> + <a name="module_flags">Module Flags Metadata</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>Information about the module as a whole is difficult to convey to LLVM's + subsystems. The LLVM IR isn't sufficient to transmit this + information. The <tt>llvm.module.flags</tt> named metadata exists in order to + facilitate this. These flags are in the form of key / value pairs — + much like a dictionary — making it easy for any subsystem who cares + about a flag to look it up.</p> + +<p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata + triplets. Each triplet has the following form:</p> + +<ul> + <li>The first element is a <i>behavior</i> flag, which specifies the behavior + when two (or more) modules are merged together, and it encounters two (or + more) metadata with the same ID. The supported behaviors are described + below.</li> + + <li>The second element is a metadata string that is a unique ID for the + metadata. How each ID is interpreted is documented below.</li> + + <li>The third element is the value of the flag.</li> +</ul> + +<p>When two (or more) modules are merged together, the resulting + <tt>llvm.module.flags</tt> metadata is the union of the + modules' <tt>llvm.module.flags</tt> metadata. The only exception being a flag + with the <i>Override</i> behavior, which may override another flag's value + (see below).</p> + +<p>The following behaviors are supported:</p> + +<table border="1" cellspacing="0" cellpadding="4"> + <tbody> + <tr> + <th>Value</th> + <th>Behavior</th> + </tr> + <tr> + <td>1</td> + <td align="left"> + <dl> + <dt><b>Error</b></dt> + <dd>Emits an error if two values disagree. It is an error to have an ID + with both an Error and a Warning behavior.</dd> + </dl> + </td> + </tr> + <tr> + <td>2</td> + <td align="left"> + <dl> + <dt><b>Warning</b></dt> + <dd>Emits a warning if two values disagree.</dd> + </dl> + </td> + </tr> + <tr> + <td>3</td> + <td align="left"> + <dl> + <dt><b>Require</b></dt> + <dd>Emits an error when the specified value is not present or doesn't + have the specified value. It is an error for two (or more) + <tt>llvm.module.flags</tt> with the same ID to have the Require + behavior but different values. There may be multiple Require flags + per ID.</dd> + </dl> + </td> + </tr> + <tr> + <td>4</td> + <td align="left"> + <dl> + <dt><b>Override</b></dt> + <dd>Uses the specified value if the two values disagree. It is an + error for two (or more) <tt>llvm.module.flags</tt> with the same + ID to have the Override behavior but different values.</dd> + </dl> + </td> + </tr> + </tbody> +</table> + +<p>An example of module flags:</p> + +<pre class="doc_code"> +!0 = metadata !{ i32 1, metadata !"foo", i32 1 } +!1 = metadata !{ i32 4, metadata !"bar", i32 37 } +!2 = metadata !{ i32 2, metadata !"qux", i32 42 } +!3 = metadata !{ i32 3, metadata !"qux", + metadata !{ + metadata !"foo", i32 1 + } +} +!llvm.module.flags = !{ !0, !1, !2, !3 } +</pre> + +<ul> + <li><p>Metadata <tt>!0</tt> has the ID <tt>!"foo"</tt> and the value '1'. The + behavior if two or more <tt>!"foo"</tt> flags are seen is to emit an + error if their values are not equal.</p></li> + + <li><p>Metadata <tt>!1</tt> has the ID <tt>!"bar"</tt> and the value '37'. The + behavior if two or more <tt>!"bar"</tt> flags are seen is to use the + value '37' if their values are not equal.</p></li> + + <li><p>Metadata <tt>!2</tt> has the ID <tt>!"qux"</tt> and the value '42'. The + behavior if two or more <tt>!"qux"</tt> flags are seen is to emit a + warning if their values are not equal.</p></li> + + <li><p>Metadata <tt>!3</tt> has the ID <tt>!"qux"</tt> and the value:</p> + +<pre class="doc_code"> +metadata !{ metadata !"foo", i32 1 } +</pre> + + <p>The behavior is to emit an error if the <tt>llvm.module.flags</tt> does + not contain a flag with the ID <tt>!"foo"</tt> that has the value + '1'. If two or more <tt>!"qux"</tt> flags exist, then they must have + the same value or an error will be issued.</p></li> +</ul> + + +<!-- ======================================================================= --> +<h3> +<a name="objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a> +</h3> + +<div> + +<p>On the Mach-O platform, Objective-C stores metadata about garbage collection + in a special section called "image info". The metadata consists of a version + number and a bitmask specifying what types of garbage collection are + supported (if any) by the file. If two or more modules are linked together + their garbage collection metadata needs to be merged rather than appended + together.</p> + +<p>The Objective-C garbage collection module flags metadata consists of the + following key-value pairs:</p> + +<table border="1" cellspacing="0" cellpadding="4"> + <col width="30%"> + <tbody> + <tr> + <th>Key</th> + <th>Value</th> + </tr> + <tr> + <td><tt>Objective-C Version</tt></td> + <td align="left"><b>[Required]</b> — The Objective-C ABI + version. Valid values are 1 and 2.</td> + </tr> + <tr> + <td><tt>Objective-C Image Info Version</tt></td> + <td align="left"><b>[Required]</b> — The version of the image info + section. Currently always 0.</td> + </tr> + <tr> + <td><tt>Objective-C Image Info Section</tt></td> + <td align="left"><b>[Required]</b> — The section to place the + metadata. Valid values are <tt>"__OBJC, __image_info, regular"</tt> for + Objective-C ABI version 1, and <tt>"__DATA,__objc_imageinfo, regular, + no_dead_strip"</tt> for Objective-C ABI version 2.</td> + </tr> + <tr> + <td><tt>Objective-C Garbage Collection</tt></td> + <td align="left"><b>[Required]</b> — Specifies whether garbage + collection is supported or not. Valid values are 0, for no garbage + collection, and 2, for garbage collection supported.</td> + </tr> + <tr> + <td><tt>Objective-C GC Only</tt></td> + <td align="left"><b>[Optional]</b> — Specifies that only garbage + collection is supported. If present, its value must be 6. This flag + requires that the <tt>Objective-C Garbage Collection</tt> flag have the + value 2.</td> + </tr> + </tbody> +</table> + +<p>Some important flag interactions:</p> + +<ul> + <li>If a module with <tt>Objective-C Garbage Collection</tt> set to 0 is + merged with a module with <tt>Objective-C Garbage Collection</tt> set to + 2, then the resulting module has the <tt>Objective-C Garbage + Collection</tt> flag set to 0.</li> + + <li>A module with <tt>Objective-C Garbage Collection</tt> set to 0 cannot be + merged with a module with <tt>Objective-C GC Only</tt> set to 6.</li> +</ul> + </div> </div> @@ -2942,26 +3297,29 @@ href="#linkage_appending">appending linkage</a>. This array contains a list of pointers to global variables and functions which may optionally have a pointer cast formed of bitcast or getelementptr. For example, a legal use of it is:</p> +<div class="doc_code"> <pre> - @X = global i8 4 - @Y = global i32 123 +@X = global i8 4 +@Y = global i32 123 - @llvm.used = appending global [2 x i8*] [ - i8* @X, - i8* bitcast (i32* @Y to i8*) - ], section "llvm.metadata" +@llvm.used = appending global [2 x i8*] [ + i8* @X, + i8* bitcast (i32* @Y to i8*) +], section "llvm.metadata" </pre> +</div> <p>If a global variable appears in the <tt>@llvm.used</tt> list, then the -compiler, assembler, and linker are required to treat the symbol as if there is -a reference to the global that it cannot see. For example, if a variable has -internal linkage and no references other than that from the <tt>@llvm.used</tt> -list, it cannot be deleted. This is commonly used to represent references from -inline asms and other things the compiler cannot "see", and corresponds to -"attribute((used))" in GNU C.</p> + compiler, assembler, and linker are required to treat the symbol as if there + is a reference to the global that it cannot see. For example, if a variable + has internal linkage and no references other than that from + the <tt>@llvm.used</tt> list, it cannot be deleted. This is commonly used to + represent references from inline asms and other things the compiler cannot + "see", and corresponds to "<tt>attribute((used))</tt>" in GNU C.</p> <p>On some targets, the code generator must emit a directive to the assembler or -object file to prevent the assembler and linker from molesting the symbol.</p> + object file to prevent the assembler and linker from molesting the + symbol.</p> </div> @@ -2975,13 +3333,13 @@ object file to prevent the assembler and linker from molesting the symbol.</p> <div> <p>The <tt>@llvm.compiler.used</tt> directive is the same as the -<tt>@llvm.used</tt> directive, except that it only prevents the compiler from -touching the symbol. On targets that support it, this allows an intelligent -linker to optimize references to the symbol without being impeded as it would be -by <tt>@llvm.used</tt>.</p> + <tt>@llvm.used</tt> directive, except that it only prevents the compiler from + touching the symbol. On targets that support it, this allows an intelligent + linker to optimize references to the symbol without being impeded as it would + be by <tt>@llvm.used</tt>.</p> <p>This is a rare construct that should only be used in rare circumstances, and -should not be exposed to source languages.</p> + should not be exposed to source languages.</p> </div> @@ -2991,12 +3349,19 @@ should not be exposed to source languages.</p> </h3> <div> + +<div class="doc_code"> <pre> %0 = type { i32, void ()* } @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }] </pre> -<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor functions and associated priorities. The functions referenced by this array will be called in ascending order of priority (i.e. lowest first) when the module is loaded. The order of functions with the same priority is not defined. -</p> +</div> + +<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor + functions and associated priorities. The functions referenced by this array + will be called in ascending order of priority (i.e. lowest first) when the + module is loaded. The order of functions with the same priority is not + defined.</p> </div> @@ -3006,13 +3371,18 @@ should not be exposed to source languages.</p> </h3> <div> + +<div class="doc_code"> <pre> %0 = type { i32, void ()* } @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }] </pre> +</div> -<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions and associated priorities. The functions referenced by this array will be called in descending order of priority (i.e. highest first) when the module is loaded. The order of functions with the same priority is not defined. -</p> +<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions + and associated priorities. The functions referenced by this array will be + called in descending order of priority (i.e. highest first) when the module + is loaded. The order of functions with the same priority is not defined.</p> </div> @@ -3051,7 +3421,6 @@ should not be exposed to source languages.</p> '<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> @@ -3271,15 +3640,15 @@ IfUnequal: '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the "normal" label. If the callee (or any - indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>" - instruction, control is interrupted and continued at the dynamically nearest - "exception" label.</p> + indirect callees) returns via the "<a href="#i_resume"><tt>resume</tt></a>" + instruction or other exception handling mechanism, 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 + the information 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 @@ -3315,8 +3684,9 @@ IfUnequal: <li>'<tt>normal label</tt>': the label reached when the called function executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> - <li>'<tt>exception label</tt>': the label reached when a callee returns with - the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> + <li>'<tt>exception label</tt>': the label reached when a callee returns via + the <a href="#i_resume"><tt>resume</tt></a> instruction or other exception + handling mechanism.</li> <li>The optional <a href="#fnattrs">function attributes</a> list. Only '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and @@ -3339,9 +3709,6 @@ IfUnequal: block to the "normal" label. If the callee unwinds then no return value is available.</p> -<p>Note that the code generator does not yet completely support unwind, and -that the invoke/unwind semantics are likely to change in future versions.</p> - <h5>Example:</h5> <pre> %retval = invoke i32 @Test(i32 15) to label %Continue @@ -3352,38 +3719,6 @@ that the invoke/unwind semantics are likely to change in future versions.</p> </div> -<!-- _______________________________________________________________________ --> - -<h4> - <a name="i_unwind">'<tt>unwind</tt>' Instruction</a> -</h4> - -<div> - -<h5>Syntax:</h5> -<pre> - unwind -</pre> - -<h5>Overview:</h5> -<p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow - at the first callee in the dynamic call stack which used - an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. - This is primarily used to implement exception handling.</p> - -<h5>Semantics:</h5> -<p>The '<tt>unwind</tt>' instruction causes execution of the current function to - immediately halt. The dynamic call stack is then searched for the - first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. - Once found, execution continues at the "exceptional" destination block - specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> - instruction in the dynamic call chain, undefined behavior results.</p> - -<p>Note that the code generator does not yet completely support unwind, and -that the invoke/unwind semantics are likely to change in future versions.</p> - -</div> - <!-- _______________________________________________________________________ --> <h4> @@ -3494,7 +3829,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt> - is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, + is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow, respectively, occurs.</p> <h5>Example:</h5> @@ -3575,7 +3910,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt> - is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, + is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow, respectively, occurs.</p> <h5>Example:</h5> @@ -3662,7 +3997,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt> - is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, + is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow, respectively, occurs.</p> <h5>Example:</h5> @@ -3732,7 +4067,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <p>Division by zero leads to undefined behavior.</p> <p>If the <tt>exact</tt> keyword is present, the result value of the - <tt>udiv</tt> is a <a href="#trapvalues">trap value</a> if %op1 is not a + <tt>udiv</tt> is a <a href="#poisonvalues">poison value</a> if %op1 is not a multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p> @@ -3776,7 +4111,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> a 32-bit division of -2147483648 by -1.</p> <p>If the <tt>exact</tt> keyword is present, the result value of the - <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would + <tt>sdiv</tt> is a <a href="#poisonvalues">poison value</a> if the result would be rounded.</p> <h5>Example:</h5> @@ -3985,9 +4320,9 @@ that the invoke/unwind semantics are likely to change in future versions.</p> shift amount in <tt>op2</tt>.</p> <p>If the <tt>nuw</tt> keyword is present, then the shift produces a - <a href="#trapvalues">trap value</a> if it shifts out any non-zero bits. If + <a href="#poisonvalues">poison value</a> if it shifts out any non-zero bits. If the <tt>nsw</tt> keyword is present, then the shift produces a - <a href="#trapvalues">trap value</a> if it shifts out any bits that disagree + <a href="#poisonvalues">poison value</a> if it shifts out any bits that disagree with the resultant sign bit. As such, NUW/NSW have the same semantics as they would if the shift were expressed as a mul instruction with the same nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p> @@ -4034,7 +4369,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> shift amount in <tt>op2</tt>.</p> <p>If the <tt>exact</tt> keyword is present, the result value of the - <tt>lshr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits + <tt>lshr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits shifted out are non-zero.</p> @@ -4082,7 +4417,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> the corresponding shift amount in <tt>op2</tt>.</p> <p>If the <tt>exact</tt> keyword is present, the result value of the - <tt>ashr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits + <tt>ashr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits shifted out are non-zero.</p> <h5>Example:</h5> @@ -4124,9 +4459,9 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> - <td>In0</td> - <td>In1</td> - <td>Out</td> + <th>In0</th> + <th>In1</th> + <th>Out</th> </tr> <tr> <td>0</td> @@ -4185,9 +4520,9 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> - <td>In0</td> - <td>In1</td> - <td>Out</td> + <th>In0</th> + <th>In1</th> + <th>Out</th> </tr> <tr> <td>0</td> @@ -4249,9 +4584,9 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <table border="1" cellspacing="0" cellpadding="4"> <tbody> <tr> - <td>In0</td> - <td>In1</td> - <td>Out</td> + <th>In0</th> + <th>In1</th> + <th>Out</th> </tr> <tr> <td>0</td> @@ -4568,8 +4903,12 @@ that the invoke/unwind semantics are likely to change in future versions.</p> '<tt>alloca</tt>' instruction is commonly used to represent automatic variables that must have an address available. When the function returns (either with the <tt><a href="#i_ret">ret</a></tt> - or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is - reclaimed. Allocating zero bytes is legal, but the result is undefined.</p> + or <tt><a href="#i_resume">resume</a></tt> instructions), the memory is + reclaimed. Allocating zero bytes is legal, but the result is undefined. + The order in which memory is allocated (ie., which way the stack grows) is + not specified.</p> + +<p> <h5>Example:</h5> <pre> @@ -4590,7 +4929,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] + <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>] <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> !<index> = !{ i32 1 } </pre> @@ -4635,6 +4974,14 @@ that the invoke/unwind semantics are likely to change in future versions.</p> The code generator may select special instructions to save cache bandwidth, such as the <tt>MOVNT</tt> instruction on x86.</p> +<p>The optional <tt>!invariant.load</tt> metadata must reference a single + metatadata name <index> corresponding to a metadata node with no + entries. The existence of the <tt>!invariant.load</tt> metatadata on the + instruction tells the optimizer and code generator that this load address + points to memory which does not change value during program execution. + The optimizer may then move this load around, for example, by hoisting it + out of loops using loop invariant code motion.</p> + <h5>Semantics:</h5> <p>The location of memory pointed to is loaded. If the value being loaded is of scalar type then the number of bytes read does not exceed the minimum number @@ -4662,8 +5009,8 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - 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> + 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> @@ -4792,7 +5139,7 @@ thread. (This is useful for interacting with signal handlers.)</p> <h5>Syntax:</h5> <pre> - cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i> + cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i> </pre> <h5>Overview:</h5> @@ -4850,13 +5197,13 @@ 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> + %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> + %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 @@ -4948,6 +5295,7 @@ specified by the <var>operation</var> argument:</p> <pre> <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}* <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}* + <result> = getelementptr <ptr vector> ptrval, <vector index type> idx </pre> <h5>Overview:</h5> @@ -4956,7 +5304,8 @@ specified by the <var>operation</var> argument:</p> It performs address calculation only and does not access memory.</p> <h5>Arguments:</h5> -<p>The first argument is always a pointer, and forms the basis of the +<p>The first argument is always a pointer or a vector of pointers, + and forms the basis of the calculation. The remaining arguments are indices that indicate which of the elements of the aggregate object are indexed. The interpretation of each index is dependent on the type being indexed into. The first index always @@ -4994,54 +5343,57 @@ int *foo(struct ST *s) { } </pre> -<p>The LLVM code generated by the GCC frontend is:</p> +<p>The LLVM code generated by Clang is:</p> <pre class="doc_code"> -%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 } -%ST = <a href="#namedtypes">type</a> { i32, double, %RT } +%struct.RT = <a href="#namedtypes">type</a> { i8, [10 x [20 x i32]], i8 } +%struct.ST = <a href="#namedtypes">type</a> { i32, double, %struct.RT } -define i32* @foo(%ST* %s) { +define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp { entry: - %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13 - ret i32* %reg + %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13 + ret i32* %arrayidx } </pre> <h5>Semantics:</h5> -<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>' - type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT - }</tt>' type, a structure. The second index indexes into the third element - of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], - i8 }</tt>' type, another structure. The third index indexes into the second - element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an - array. The two dimensions of the array are subscripted into, yielding an - '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a - pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p> +<p>In the example above, the first index is indexing into the + '<tt>%struct.ST*</tt>' type, which is a pointer, yielding a + '<tt>%struct.ST</tt>' = '<tt>{ i32, double, %struct.RT }</tt>' type, a + structure. The second index indexes into the third element of the structure, + yielding a '<tt>%struct.RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], i8 }</tt>' + type, another structure. The third index indexes into the second element of + the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an array. The + two dimensions of the array are subscripted into, yielding an '<tt>i32</tt>' + type. The '<tt>getelementptr</tt>' instruction returns a pointer to this + element, thus computing a value of '<tt>i32*</tt>' type.</p> <p>Note that it is perfectly legal to index partially through a structure, returning a pointer to an inner element. Because of this, the LLVM code for the given testcase is equivalent to:</p> -<pre> - define i32* @foo(%ST* %s) { - %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i> - %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i> - %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i> - %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i> - %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i> - ret i32* %t5 - } +<pre class="doc_code"> +define i32* @foo(%struct.ST* %s) { + %t1 = getelementptr %struct.ST* %s, i32 1 <i>; yields %struct.ST*:%t1</i> + %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 <i>; yields %struct.RT*:%t2</i> + %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i> + %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i> + %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i> + ret i32* %t5 +} </pre> <p>If the <tt>inbounds</tt> keyword is present, the result value of the - <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the + <tt>getelementptr</tt> is a <a href="#poisonvalues">poison value</a> if the 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 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> + byte past the end. + In cases where the base is a vector of pointers the <tt>inbounds</tt> keyword + applies to each of the computations element-wise. </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. If the @@ -5068,6 +5420,13 @@ entry: %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0 </pre> +<p>In cases where the pointer argument is a vector of pointers, only a + single index may be used, and the number of vector elements has to be + the same. For example: </p> +<pre class="doc_code"> + %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets, +</pre> + </div> </div> @@ -5440,13 +5799,16 @@ entry: </pre> <h5>Overview:</h5> -<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to - the integer type <tt>ty2</tt>.</p> +<p>The '<tt>ptrtoint</tt>' instruction converts the pointer or a vector of + pointers <tt>value</tt> to + the integer (or vector of integers) type <tt>ty2</tt>.</p> <h5>Arguments:</h5> <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which - must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to - <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> + must be a a value of type <a href="#t_pointer">pointer</a> or a vector of + pointers, and a type to cast it to + <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> or a vector + of integers type.</p> <h5>Semantics:</h5> <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type @@ -5459,8 +5821,9 @@ entry: <h5>Example:</h5> <pre> - %X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit architecture</i> - %Y = ptrtoint i32* %x to i64 <i>; yields zero extension on 32-bit architecture</i> + %X = ptrtoint i32* %P to i8 <i>; yields truncation on 32-bit architecture</i> + %Y = ptrtoint i32* %P to i64 <i>; yields zero extension on 32-bit architecture</i> + %Z = ptrtoint <4 x i32*> %P to <4 x i64><i>; yields vector zero extension for a vector of addresses on 32-bit architecture</i> </pre> </div> @@ -5499,6 +5862,7 @@ entry: %X = inttoptr i32 255 to i32* <i>; yields zero extension on 64-bit architecture</i> %Y = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i> %Z = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i> + %Z = inttoptr <4 x i32> %G to <4 x i8*><i>; yields truncation of vector G to four pointers</i> </pre> </div> @@ -5533,8 +5897,9 @@ entry: <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with this conversion. The conversion is done as if the <tt>value</tt> had been - stored to memory and read back as type <tt>ty2</tt>. Pointer types may only - be converted to other pointer types with this instruction. To convert + stored to memory and read back as type <tt>ty2</tt>. + Pointer (or vector of pointers) types may only be converted to other pointer + (or vector of pointers) types with this instruction. To convert pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> @@ -5542,7 +5907,8 @@ entry: <pre> %X = bitcast i8 255 to i8 <i>; yields i8 :-1</i> %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i> - %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i> + %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i> + %Z = bitcast <2 x i32*> %V to <2 x i64*> <i>; yields <2 x i64*></i> </pre> </div> @@ -5573,8 +5939,8 @@ entry: <h5>Overview:</h5> <p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of - boolean values based on comparison of its two integer, integer vector, or - pointer operands.</p> + boolean values based on comparison of its two integer, integer vector, + pointer, or pointer vector operands.</p> <h5>Arguments:</h5> <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is @@ -5869,9 +6235,6 @@ Loop: ; Infinite loop that counts from 0 on up... %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i> </pre> -<p>Note that the code generator does not yet support conditions - with vector type.</p> - </div> <!-- _______________________________________________________________________ --> @@ -6038,8 +6401,8 @@ freestanding environments and non-C-based languages.</p> <h5>Syntax:</h5> <pre> - <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+ - <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>* + <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+ + <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>* <clause> := catch <type> <value> <clause> := filter <array constant type> <array constant> @@ -6053,7 +6416,7 @@ freestanding environments and non-C-based languages.</p> <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> + type <tt>resultty</tt>.</p> <h5>Arguments:</h5> <p>This instruction takes a <tt>pers_fn</tt> value. This is the personality @@ -6077,7 +6440,11 @@ freestanding environments and non-C-based languages.</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> + clauses from the calling function are appended to the list of clauses. + When the call stack is being unwound due to an exception being thrown, the + exception is compared against each <tt>clause</tt> in turn. If it doesn't + match any of the clauses, and the <tt>cleanup</tt> flag is not set, then + unwinding continues further up the call stack.</p> <p>The <tt>landingpad</tt> instruction has several restrictions:</p> @@ -7194,12 +7561,12 @@ LLVM</a>.</p> targets support all bit widths or vector types, however.</p> <pre> - declare i8 @llvm.ctlz.i8 (i8 <src>) - declare i16 @llvm.ctlz.i16(i16 <src>) - declare i32 @llvm.ctlz.i32(i32 <src>) - declare i64 @llvm.ctlz.i64(i64 <src>) - declare i256 @llvm.ctlz.i256(i256 <src>) - declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src;gt) + declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>) + declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>) + declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>) + declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>) + declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>) + declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) </pre> <h5>Overview:</h5> @@ -7207,15 +7574,22 @@ LLVM</a>.</p> leading zeros in a variable.</p> <h5>Arguments:</h5> -<p>The only argument is the value to be counted. The argument may be of any - integer type, or any vector type with integer element type. - The return type must match the argument type.</p> +<p>The first argument is the value to be counted. This argument may be of any + integer type, or a vectory with integer element type. The return type + must match the first argument type.</p> + +<p>The second argument must be a constant and is a flag to indicate whether the + intrinsic should ensure that a zero as the first argument produces a defined + result. Historically some architectures did not provide a defined result for + zero values as efficiently, and many algorithms are now predicated on + avoiding zero-value inputs.</p> <h5>Semantics:</h5> <p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) - zeros in a variable, or within each element of the vector if the operation - is of vector type. If the src == 0 then the result is the size in bits of - the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p> + zeros in a variable, or within each element of the vector. + If <tt>src == 0</tt> then the result is the size in bits of the type of + <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise. + For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p> </div> @@ -7232,12 +7606,12 @@ LLVM</a>.</p> support all bit widths or vector types, however.</p> <pre> - declare i8 @llvm.cttz.i8 (i8 <src>) - declare i16 @llvm.cttz.i16(i16 <src>) - declare i32 @llvm.cttz.i32(i32 <src>) - declare i64 @llvm.cttz.i64(i64 <src>) - declare i256 @llvm.cttz.i256(i256 <src>) - declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>) + declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>) + declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>) + declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>) + declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>) + declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>) + declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) </pre> <h5>Overview:</h5> @@ -7245,15 +7619,22 @@ LLVM</a>.</p> trailing zeros.</p> <h5>Arguments:</h5> -<p>The only argument is the value to be counted. The argument may be of any - integer type, or a vectory with integer element type.. The return type - must match the argument type.</p> +<p>The first argument is the value to be counted. This argument may be of any + integer type, or a vectory with integer element type. The return type + must match the first argument type.</p> + +<p>The second argument must be a constant and is a flag to indicate whether the + intrinsic should ensure that a zero as the first argument produces a defined + result. Historically some architectures did not provide a defined result for + zero values as efficiently, and many algorithms are now predicated on + avoiding zero-value inputs.</p> <h5>Semantics:</h5> <p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros in a variable, or within each element of a vector. - If the src == 0 then the result is the size in bits of - the type of src. For example, <tt>llvm.cttz(2) = 1</tt>.</p> + If <tt>src == 0</tt> then the result is the size in bits of the type of + <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise. + For example, <tt>llvm.cttz(2) = 1</tt>.</p> </div> @@ -8086,11 +8467,35 @@ LLVM</a>.</p> compile time.</p> </div> +<!-- _______________________________________________________________________ --> +<h4> + <a name="int_expect">'<tt>llvm.expect</tt>' Intrinsic</a> +</h4> + +<div> + +<h5>Syntax:</h5> +<pre> + declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>) + declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>) +</pre> + +<h5>Overview:</h5> +<p>The <tt>llvm.expect</tt> intrinsic provides information about expected (the + most probable) value of <tt>val</tt>, which can be used by optimizers.</p> +<h5>Arguments:</h5> +<p>The <tt>llvm.expect</tt> intrinsic takes two arguments. The first + argument is a value. The second argument is an expected value, this needs to + be a constant value, variables are not allowed.</p> + +<h5>Semantics:</h5> +<p>This intrinsic is lowered to the <tt>val</tt>.</p> </div> </div> +</div> <!-- *********************************************************************** --> <hr> <address> @@ -8101,7 +8506,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-11-03 07:43:54 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-04-10 10:22:43 +0200 (Tue, 10 Apr 2012) $ </address> </body> diff --git a/docs/Lexicon.html b/docs/Lexicon.html index e12041d..dbb7f9b 100644 --- a/docs/Lexicon.html +++ b/docs/Lexicon.html @@ -275,7 +275,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd> </dl> </div> -</div> +</div> <!-- *********************************************************************** --> <hr> <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img @@ -284,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-09-27 20:44:01 +0200 (Tue, 27 Sep 2011) $ +Last modified: $Date: 2012-01-05 09:18:41 +0100 (Thu, 05 Jan 2012) $ </address> <!-- vim: sw=2 --> diff --git a/docs/LinkTimeOptimization.html b/docs/LinkTimeOptimization.html index 63403ca..5652555 100644 --- a/docs/LinkTimeOptimization.html +++ b/docs/LinkTimeOptimization.html @@ -393,7 +393,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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> diff --git a/docs/Packaging.html b/docs/Packaging.html index e3cdf79..ac4dcf0 100644 --- a/docs/Packaging.html +++ b/docs/Packaging.html @@ -113,7 +113,7 @@ line numbers.</dd> <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/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> </html> diff --git a/docs/Passes.html b/docs/Passes.html index 96d1aee..37a304d 100644 --- a/docs/Passes.html +++ b/docs/Passes.html @@ -126,6 +126,7 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#adce">-adce</a></td><td>Aggressive Dead Code Elimination</td></tr> <tr><td><a href="#always-inline">-always-inline</a></td><td>Inliner for always_inline functions</td></tr> <tr><td><a href="#argpromotion">-argpromotion</a></td><td>Promote 'by reference' arguments to scalars</td></tr> +<tr><td><a href="#bb-vectorize">-bb-vectorize</a></td><td>Combine instructions to form vector instructions within basic blocks</td></tr> <tr><td><a href="#block-placement">-block-placement</a></td><td>Profile Guided Basic Block Placement</td></tr> <tr><td><a href="#break-crit-edges">-break-crit-edges</a></td><td>Break critical edges in CFG</td></tr> <tr><td><a href="#codegenprepare">-codegenprepare</a></td><td>Optimize for code generation</td></tr> @@ -817,6 +818,26 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <h3> + <a name="bb-vectorize">-bb-vectorize: Basic-Block Vectorization</a> +</h3> +<div> + <p>This pass combines instructions inside basic blocks to form vector + instructions. It iterates over each basic block, attempting to pair + compatible instructions, repeating this process until no additional + pairs are selected for vectorization. When the outputs of some pair + of compatible instructions are used as inputs by some other pair of + compatible instructions, those pairs are part of a potential + vectorization chain. Instruction pairs are only fused into vector + instructions when they are part of a chain longer than some + threshold length. Moreover, the pass attempts to find the best + possible chain for each pair of compatible instructions. These + heuristics are intended to prevent vectorization in cases where + it would not yield a performance increase of the resulting code. + </p> +</div> + +<!-------------------------------------------------------------------------- --> +<h3> <a name="block-placement">-block-placement: Profile Guided Basic Block Placement</a> </h3> <div> @@ -2039,7 +2060,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-11-04 07:30:50 +0100 (Fri, 04 Nov 2011) $ + Last modified: $Date: 2012-02-01 04:51:43 +0100 (Wed, 01 Feb 2012) $ </address> </body> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 47fc6e9..951e2d5 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -81,11 +81,13 @@ option</a></li> <li><a href="#dss_smallset">"llvm/ADT/SmallSet.h"</a></li> <li><a href="#dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a></li> <li><a href="#dss_denseset">"llvm/ADT/DenseSet.h"</a></li> + <li><a href="#dss_sparseset">"llvm/ADT/SparseSet.h"</a></li> <li><a href="#dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li> <li><a href="#dss_set"><set></a></li> <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li> <li><a href="#dss_uniquevector">"llvm/ADT/UniqueVector.h"</a></li> - <li><a href="#dss_otherset">Other Set-Like ContainerOptions</a></li> + <li><a href="#dss_immutableset">"llvm/ADT/ImmutableSet.h"</a></li> + <li><a href="#dss_otherset">Other Set-Like Container Options</a></li> </ul></li> <li><a href="#ds_map">Map-Like Containers (std::map, DenseMap, etc)</a> <ul> @@ -97,6 +99,7 @@ option</a></li> <li><a href="#dss_intervalmap">"llvm/ADT/IntervalMap.h"</a></li> <li><a href="#dss_map"><map></a></li> <li><a href="#dss_inteqclasses">"llvm/ADT/IntEqClasses.h"</a></li> + <li><a href="#dss_immutablemap">"llvm/ADT/ImmutableMap.h"</a></li> <li><a href="#dss_othermap">Other Map-Like Container Options</a></li> </ul></li> <li><a href="#ds_bit">BitVector-like containers</a> @@ -995,7 +998,7 @@ vector is also useful when interfacing with code that expects vectors :). <pre> for ( ... ) { std::vector<foo> V; - use V; + // make use of V. } </pre> </div> @@ -1006,7 +1009,7 @@ for ( ... ) { <pre> std::vector<foo> V; for ( ... ) { - use V; + // make use of V. V.clear(); } </pre> @@ -1488,6 +1491,24 @@ href="#dss_densemap">DenseMap</a> has. <!-- _______________________________________________________________________ --> <h4> + <a name="dss_sparseset">"llvm/ADT/SparseSet.h"</a> +</h4> + +<div> + +<p>SparseSet holds a small number of objects identified by unsigned keys of +moderate size. It uses a lot of memory, but provides operations that are +almost as fast as a vector. Typical keys are physical registers, virtual +registers, or numbered basic blocks.</p> + +<p>SparseSet is useful for algorithms that need very fast clear/find/insert/erase +and fast iteration over small sets. It is not intended for building composite +data structures.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a> </h4> @@ -1608,6 +1629,29 @@ factors, and produces a lot of malloc traffic. It should be avoided.</p> </div> +<!-- _______________________________________________________________________ --> +<h4> + <a name="dss_immutableset">"llvm/ADT/ImmutableSet.h"</a> +</h4> + +<div> + +<p> +ImmutableSet is an immutable (functional) set implementation based on an AVL +tree. +Adding or removing elements is done through a Factory object and results in the +creation of a new ImmutableSet object. +If an ImmutableSet already exists with the given contents, then the existing one +is returned; equality is compared with a FoldingSetNodeID. +The time and space complexity of add or remove operations is logarithmic in the +size of the original set. + +<p> +There is no method for returning an element of the set, you can only check for +membership. + +</div> + <!-- _______________________________________________________________________ --> <h4> @@ -1728,7 +1772,7 @@ pointers, or map other small types to each other. <p> There are several aspects of DenseMap that you should be aware of, however. The -iterators in a densemap are invalidated whenever an insertion occurs, unlike +iterators in a DenseMap are invalidated whenever an insertion occurs, unlike map. Also, because DenseMap allocates space for a large number of key/value pairs (it starts with 64 by default), it will waste a lot of space if your keys or values are large. Finally, you must implement a partial specialization of @@ -1736,6 +1780,14 @@ DenseMapInfo for the key that you want, if it isn't already supported. This is required to tell DenseMap about two special marker values (which can never be inserted into the map) that it needs internally.</p> +<p> +DenseMap's find_as() method supports lookup operations using an alternate key +type. This is useful in cases where the normal key type is expensive to +construct, but cheap to compare against. The DenseMapInfo is responsible for +defining the appropriate comparison and hashing methods for each alternate +key type used. +</p> + </div> <!-- _______________________________________________________________________ --> @@ -1814,6 +1866,25 @@ it can be edited again.</p> <!-- _______________________________________________________________________ --> <h4> + <a name="dss_immutablemap">"llvm/ADT/ImmutableMap.h"</a> +</h4> + +<div> + +<p> +ImmutableMap is an immutable (functional) map implementation based on an AVL +tree. +Adding or removing elements is done through a Factory object and results in the +creation of a new ImmutableMap object. +If an ImmutableMap already exists with the given key set, then the existing one +is returned; equality is compared with a FoldingSetNodeID. +The time and space complexity of add or remove operations is logarithmic in the +size of the original map. + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="dss_othermap">Other Map-Like Container Options</a> </h4> @@ -2496,7 +2567,7 @@ block but not delete it, you can use the <tt>removeFromParent()</tt> method.</p> <div> -<p><i>Replacing individual instructions</i></p> +<h5><i>Replacing individual instructions</i></h5> <p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>" permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt> @@ -2504,6 +2575,7 @@ and <tt>ReplaceInstWithInst</tt>.</p> <h5><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h5> +<div> <ul> <li><tt>ReplaceInstWithValue</tt> @@ -2540,7 +2612,9 @@ ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii, </pre></div></li> </ul> -<p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p> +</div> + +<h5><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></h5> <p>You can use <tt>Value::replaceAllUsesWith</tt> and <tt>User::replaceUsesOfWith</tt> to change more than one use at a time. See the @@ -3234,13 +3308,12 @@ helpful member functions that try to make common operations easy.</p> <div> <ul> - <li><tt>Module::Module(std::string name = "")</tt></li> -</ul> + <li><tt>Module::Module(std::string name = "")</tt> -<p>Constructing a <a href="#Module">Module</a> is easy. You can optionally + <p>Constructing a <a href="#Module">Module</a> is easy. You can optionally provide a name for it (probably based on the name of the translation unit).</p> + </li> -<ul> <li><tt>Module::iterator</tt> - Typedef for function list iterator<br> <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br> @@ -4052,7 +4125,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-11-03 07:43:54 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/Projects.html b/docs/Projects.html index a3d6891..ebd7203 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -482,7 +482,7 @@ Mailing List</a>.</p> <a href="mailto:criswell@uiuc.edu">John Criswell</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 56d0eb9..bcac293 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -4,20 +4,22 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <link rel="stylesheet" href="llvm.css" type="text/css"> - <title>LLVM 3.0 Release Notes</title> + <title>LLVM 3.1 Release Notes</title> </head> <body> -<h1>LLVM 3.0 Release Notes</h1> +<h1>LLVM 3.1 Release Notes</h1> -<img align=right src="http://llvm.org/img/DragonSmall.png" - width="136" height="136" alt="LLVM Dragon Logo"> +<div> +<img style="float:right" src="http://llvm.org/img/DragonSmall.png" + width="136" height="136" alt="LLVM Dragon Logo"> +</div> <ol> <li><a href="#intro">Introduction</a></li> <li><a href="#subproj">Sub-project Status Update</a></li> - <li><a href="#externalproj">External Projects Using LLVM 3.0</a></li> - <li><a href="#whatsnew">What's New in LLVM 3.0?</a></li> + <li><a href="#externalproj">External Projects Using LLVM 3.1</a></li> + <li><a href="#whatsnew">What's New in LLVM?</a></li> <li><a href="GettingStarted.html">Installation Instructions</a></li> <li><a href="#knownproblems">Known Problems</a></li> <li><a href="#additionalinfo">Additional Information</a></li> @@ -27,13 +29,11 @@ <p>Written by the <a href="http://llvm.org/">LLVM Team</a></p> </div> -<!-- -<h1 style="color:red">These are in-progress notes for the upcoming LLVM 3.0 +<h1 style="color:red">These are in-progress notes for the upcoming LLVM 3.1 release.<br> You may prefer the -<a href="http://llvm.org/releases/2.9/docs/ReleaseNotes.html">LLVM 2.9 +<a href="http://llvm.org/releases/3.0/docs/ReleaseNotes.html">LLVM 3.0 Release Notes</a>.</h1> - --> <!-- *********************************************************************** --> <h2> @@ -44,8 +44,9 @@ 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. + Infrastructure, release 3.1. Here we describe the status of LLVM, including + major improvements from the previous release, improvements in various + subprojects of LLVM, and some of the current users of the code. All LLVM releases may be downloaded from the <a href="http://llvm.org/releases/">LLVM releases web site</a>.</p> @@ -61,16 +62,8 @@ Release Notes</a>.</h1> <a href="http://llvm.org/releases/">releases page</a>.</p> </div> - -<!-- Features that need text if they're finished for 3.1: - ARM EHABI - combiner-aa? - strong phi elim - loop dependence analysis - CorrelatedValuePropagation - lib/Transforms/IPO/MergeFunctions.cpp => consider for 3.1. - --> - + + <!-- *********************************************************************** --> <h2> <a name="subproj">Sub-project Status Update</a> @@ -79,9 +72,9 @@ Release Notes</a>.</h1> <div> -<p>The LLVM 3.0 distribution currently consists of code from the core LLVM +<p>The LLVM 3.1 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 + supporting tools), and the Clang 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> @@ -99,37 +92,18 @@ Release Notes</a>.</h1> 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> + (32- and 64-bit), and for Darwin/ARM targets.</p> +<p>In the LLVM 3.1 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> + <li>...</li> </ul> - + <p>For more details about the changes to Clang since the 2.9 release, see the +<a href="http://clang.llvm.org/docs/ReleaseNotes.html">Clang release notes</a> +</p> + + <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 @@ -145,19 +119,18 @@ Release Notes</a>.</h1> <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> + optimizers and code generators with LLVM's. It works with gcc-4.5 or gcc-4.6, + targets the x86-32 and x86-64 processor families, and has been successfully + used on the Darwin, FreeBSD, KFreeBSD, Linux and OpenBSD platforms. It fully + supports Ada, C, C++ and Fortran. It has partial support for Go, Java, Obj-C + and Obj-C++.</p> -<p>The 3.0 release has the following notable changes:</p> +<p>The 3.1 release has the following notable changes:</p> + + <ul> + + <li>...</li> -<ul> -<!-- -<li></li> ---> </ul> </div> @@ -178,7 +151,7 @@ Release Notes</a>.</h1> 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> +<p>....</p> </div> @@ -189,11 +162,12 @@ Release Notes</a>.</h1> <div> -<p>LLDB 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>LLDB is a ground-up implementation of a command line debugger, as well as a + debugger API that can be used from other applications. LLDB makes use of the + Clang parser to provide high-fidelity expression parsing (particularly for + C++) and uses the LLVM JIT for target support.</p> + +<p>...</p> </div> @@ -208,22 +182,7 @@ Release Notes</a>.</h1> licensed</a> under the MIT and UIUC license, allowing it to be used more permissively.</p> -</div> - - -<!--=========================================================================--> -<h3> -<a name="LLBrowse">LLBrowse: IR Browser</a> -</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>...</p> </div> @@ -234,39 +193,24 @@ Release Notes</a>.</h1> <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> + <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. -</div> - - -<!--=========================================================================--> -<!-- -<h3> -<a name="klee">KLEE: A Symbolic Execution Virtual Machine</a> -</h3> + <p>In the LLVM 3.1 time-frame, VMKit has had significant improvements on both + runtime and startup performance:</p> -<div> -<p> -<a href="http://klee.llvm.org/">KLEE</a> is a symbolic execution framework for -programs in LLVM bitcode form. KLEE tries to symbolically evaluate "all" paths -through the application and records state transitions that lead to fault -states. This allows it to construct testcases that lead to faults and can even -be used to verify some algorithms. -</p> + <ul> + <li>...</li> + </ul> -<p>UPDATE!</p> -</div>--> +</div> </div> <!-- *********************************************************************** --> <h2> - <a name="externalproj">External Open Source Projects Using LLVM 3.0</a> + <a name="externalproj">External Open Source Projects Using LLVM 3.1</a> </h2> <!-- *********************************************************************** --> @@ -274,415 +218,15 @@ be used to verify some algorithms. <p>An exciting aspect of LLVM is that it is used as an enabling technology for a lot of other language and tools projects. This section lists some of the - projects that have already been updated to work with LLVM 3.0.</p> - -<!--=========================================================================--> -<h3>AddressSanitizer</h3> - -<div> - -<p><a href="http://code.google.com/p/address-sanitizer/">AddressSanitizer</a> - uses compiler instrumentation and a specialized malloc library to find C/C++ - bugs such as use-after-free and out-of-bound accesses to heap, stack, and - globals. The key feature of the tool is speed: the average slowdown - introduced by AddressSanitizer is less than 2x.</p> - -</div> - -<!--=========================================================================--> -<h3>ClamAV</h3> - -<div> - -<p><a href="http://www.clamav.net">Clam AntiVirus</a> is an open source (GPL) - anti-virus toolkit for UNIX, designed especially for e-mail scanning on mail - gateways.</p> - -<p>Since version 0.96 it - has <a href="http://vrt-sourcefire.blogspot.com/2010/09/introduction-to-clamavs-low-level.html">bytecode - signatures</a> that allow writing detections for complex malware.</p> - -<p>It uses LLVM's JIT to speed up the execution of bytecode on X86, X86-64, - PPC32/64, falling back to its own interpreter otherwise. The git version was - updated to work with LLVM 3.0.</p> - -</div> - -<!--=========================================================================--> -<h3>clReflect</h3> - -<div> - -<p><a href="https://bitbucket.org/dwilliamson/clreflect">clReflect</a> is a C++ - parser that uses clang/LLVM to derive a light-weight reflection database - suitable for use in game development. It comes with a very simple runtime - library for loading and querying the database, requiring no external - dependencies (including CRT), and an additional utility library for object - management and serialisation.</p> - -</div> - -<!--=========================================================================--> -<h3>Cling C++ Interpreter</h3> - -<div> - -<p><a href="http://cern.ch/cling">Cling</a> is an interactive compiler interface - (aka C++ interpreter). It uses LLVM's JIT and clang; it currently supports - C++ and C. It has a prompt interface, runs source files, calls into shared - libraries, prints the value of expressions, even does runtime lookup of - identifiers (dynamic scopes). And it just behaves like one would expect from - an interpreter.</p> - -</div> - -<!--=========================================================================--> -<!-- FIXME: Comment out -<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> -</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 7.0 and onwards include an LLVM code generator, supporting LLVM 2.8 and - later. Since LLVM 2.9, GHC now includes experimental support for the ARM - platform with LLVM 3.0.</p> - -</div> - -<!--=========================================================================--> -<h3>gwXscript</h3> - -<div> - -<p><a href="http://botwars.tk/gwscript/">gwXscript</a> is an object oriented, - aspect oriented programming language which can create both executables (ELF, - EXE) and shared libraries (DLL, SO, DYNLIB). The compiler is implemented in - its own language and translates scripts into LLVM-IR which can be optimized - and translated into native code by the LLVM framework. Source code in - gwScript contains definitions that expand the namespaces. So you can build - your project and simply 'plug out' features by removing a file. The remaining - project does not leave scars since you directly separate concerns by the - 'template' feature of gwX. It is also possible to add new features to a - project by just adding files and without editing the original project. This - language is used for example to create games or content management systems - that should be extendable.</p> - -<p>gwXscript is strongly typed and offers comfort with its native types string, - hash and array. You can easily write new libraries in gwXscript or native - code. gwXscript is type safe and users should not be able to crash your - program or execute malicious code except code that is eating CPU time.</p> - -</div> - -<!--=========================================================================--> -<h3>include-what-you-use</h3> - -<div> - -<p><a href="http://code.google.com/p/include-what-you-use">include-what-you-use</a> - is a tool to ensure that a file directly <code>#include</code>s - all <code>.h</code> files that provide a symbol that the file uses. It also - removes superfluous <code>#include</code>s from source files.</p> - -</div> - -<!--=========================================================================--> -<h3>LanguageKit and Pragmatic Smalltalk</h3> - -<div> - -<p><a href="http://etoileos.com/etoile/features/languagekit/">LanguageKit</a> is - a framework for implementing dynamic languages sharing an object model with - Objective-C. It provides static and JIT compilation using LLVM along with - its own interpreter. Pragmatic Smalltalk is a dialect of Smalltalk, built on - top of LanguageKit, that interfaces directly with Objective-C, sharing the - same object representation and message sending behaviour. These projects are - developed as part of the Étoié desktop environment.</p> - -</div> - -<!--=========================================================================--> -<h3>LuaAV</h3> - -<div> - -<p><a href="http://lua-av.mat.ucsb.edu/blog/">LuaAV</a> is a real-time - audiovisual scripting environment based around the Lua language and a - collection of libraries for sound, graphics, and other media protocols. LuaAV - uses LLVM and Clang to JIT compile efficient user-defined audio synthesis - routines specified in a declarative syntax.</p> - -</div> - -<!--=========================================================================--> -<h3>Mono</h3> - -<div> - -<p>An open source, cross-platform implementation of C# and the CLR that is - binary compatible with Microsoft.NET. Has an optional, dynamically-loaded - LLVM code generation backend in Mini, the JIT compiler.</p> - -<p>Note that we use a Git mirror of LLVM with some patches. See: - https://github.com/mono/llvm</p> - -</div> - -<!--=========================================================================--> -<h3>Portable OpenCL (pocl)</h3> - -<div> - -<p>Portable OpenCL is an open source implementation of the OpenCL standard which - can be easily adapted for new targets. One of the goals of the project is - improving performance portability of OpenCL programs, avoiding the need for - target-dependent manual optimizations. A "native" target is included, which - allows running OpenCL kernels on the host (CPU).</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> - -<p>Pure version 0.48 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>Renderscript</h3> - -<div> - -<p><a href="http://developer.android.com/guide/topics/renderscript/index.html">Renderscript</a> - is Android's advanced 3D graphics rendering and compute API. It provides a - portable C99-based language with extensions to facilitate common use cases - for enhancing graphics and thread level parallelism. The Renderscript - compiler frontend is based on Clang/LLVM. It emits a portable bitcode format - for the actual compiled script code, as well as reflects a Java interface for - developers to control the execution of the compiled bitcode. Executable - machine code is then generated from this bitcode by an LLVM backend on the - device. Renderscript is thus able to provide a mechanism by which Android - developers can improve performance of their applications while retaining - portability.</p> - -</div> - -<!--=========================================================================--> -<h3>SAFECode</h3> - -<div> - -<p><a href="http://safecode.cs.illinois.edu">SAFECode</a> is a memory safe C/C++ - compiler built using LLVM. It takes standard, unannotated C/C++ code, - analyzes the code to ensure that memory accesses and array indexing - operations are safe, and instruments the code with run-time checks when - safety cannot be proven statically. SAFECode can be used as a debugging aid - (like Valgrind) to find and repair memory safety bugs. It can also be used - to protect code from security attacks at run-time.</p> - -</div> - -<!--=========================================================================--> -<h3>The Stupid D Compiler (SDC)</h3> - -<div> - -<p><a href="https://github.com/bhelyer/SDC">The Stupid D Compiler</a> is a - project seeking to write a self-hosting compiler for the D programming - language without using the frontend of the reference compiler (DMD).</p> - -</div> - -<!--=========================================================================--> -<h3>TTA-based Co-design 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> - -<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> - -<!--=========================================================================--> -<h3>Tart Programming Language</h3> - -<div> - -<p><a href="http://code.google.com/p/tart/">Tart</a> is a general-purpose, - strongly typed programming language designed for application - developers. Strongly inspired by Python and C#, Tart focuses on practical - solutions for the professional software developer, while avoiding the clutter - and boilerplate of legacy languages like Java and C++. Although Tart is still - in development, the current implementation supports many features expected of - a modern programming language, such as garbage collection, powerful - bidirectional type inference, a greatly simplified syntax for template - metaprogramming, closures and function literals, reflection, operator - overloading, explicit mutability and immutability, and much more. Tart is - flexible enough to accommodate a broad range of programming styles and - philosophies, while maintaining a strong commitment to simplicity, minimalism - and elegance in design.</p> - -</div> - -<!--=========================================================================--> -<h3>ThreadSanitizer</h3> - -<div> - -<p><a href="http://code.google.com/p/data-race-test/">ThreadSanitizer</a> is a - data race detector for (mostly) C and C++ code, available for Linux, Mac OS - and Windows. On different systems, we use binary instrumentation frameworks - (Valgrind and Pin) as frontends that generate the program events for the race - detection algorithm. On Linux, there's an option of using LLVM-based - compile-time instrumentation.</p> - -</div> - -<!--=========================================================================--> -<h3>The ZooLib C++ Cross-Platform Application Framework</h3> - -<div> - -<p><a href="http://www.zoolib.org/">ZooLib</a> is Open Source under the MIT - License. It provides GUI, filesystem access, TCP networking, thread-safe - memory management, threading and locking for Mac OS X, Classic Mac OS, - Microsoft Windows, POSIX operating systems with X11, BeOS, Haiku, Apple's iOS - and Research in Motion's BlackBerry.</p> - -<p>My current work is to use CLang's static analyzer to improve ZooLib's code - quality. I also plan to set up LLVM compiles of the demo programs and test - programs using CLang and LLVM on all the platforms that CLang, LLVM and - ZooLib all support.</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> -</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> + projects that have already been updated to work with LLVM 3.1.</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>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> -</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> ---> - -<!--=========================================================================--> -<!-- -<h3> -<a name="FAUST">FAUST Real-Time Audio Signal Processing Language</a> -</h3> + ... to be filled in right before the release ... -<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> - -</div> ---> - </div> <!-- *********************************************************************** --> <h2> - <a name="whatsnew">What's New in LLVM 3.0?</a> + <a name="whatsnew">What's New in LLVM 3.1?</a> </h2> <!-- *********************************************************************** --> @@ -699,18 +243,38 @@ Faust compiler can now generate LLVM bitcode, and works with LLVM 2.7-3.0.</p> <div> -<p>LLVM 3.0 includes several major new capabilities:</p> + <!-- Features that need text if they're finished for 3.1: + ARM EHABI + combiner-aa? + strong phi elim + loop dependence analysis + CorrelatedValuePropagation + lib/Transforms/IPO/MergeFunctions.cpp => consider for 3.1. + Integrated assembler on by default for arm/thumb? -<ul> + --> + + <!-- Near dead: + Analysis/RegionInfo.h + Dom Frontiers + SparseBitVector: used in LiveVar. + llvm/lib/Archive - replace with lib object? + --> + +<p>LLVM 3.1 includes several major changes and big features:</p> -<!-- -<li></li> ---> - +<ul> + <li><a href="../tools/clang/docs/AddressSanitizer.html">AddressSanitizer</a>, + a fast memory error detector.</li> + <li><a href="CodeGenerator.html#machineinstrbundle">MachineInstr Bundles</a>, + Support to model instruction bundling / packing.</li> + <li><a href="#armintegratedassembler">ARM Integrated Assembler</a>, + A full featured assembler and direct-to-object support for ARM.</li> + <li>....</li> </ul> - + </div> + <!--=========================================================================--> <h3> <a name="coreimprovements">LLVM IR and Core Improvements</a> @@ -721,117 +285,15 @@ Faust compiler can now generate LLVM bitcode, and works with LLVM 2.7-3.0.</p> <p>LLVM IR has several new features for better support of new targets and that 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><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> - + <ul> + <li>IR support for half float</li> + <li>IR support for vectors of pointers, including vector GEPs.</li> + <li>Module flags have been introduced. They convey information about the + module as a whole to LLVM subsystems.</li> + <li>Loads can now have range metadata attached to them to describe the + possible values being loaded.</li> + <li>....</li> + </ul> </div> <!--=========================================================================--> @@ -841,16 +303,12 @@ Builder.CreateResume(UnwindData); <div> -<p>In addition to a large array of minor performance tweaks and bug fixes, this +<p>In addition to many minor performance tweaks and bug fixes, this release includes a few major enhancements and additions to the optimizers:</p> <ul> -<!-- -<li></li> ---> -</li> - + <li>....</li> </ul> </div> @@ -865,18 +323,14 @@ Builder.CreateResume(UnwindData); <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> + in. 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> <ul> -<!-- -<li></li> ---> + <li>....</li> </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> - </div> <!--=========================================================================--> @@ -886,15 +340,39 @@ Builder.CreateResume(UnwindData); <div> +<p>We have changed the way that the Type Legalizer legalizes vectors. The type + legalizer now attempts to promote integer elements. This enabled the + implementation of vector-select. Additionally, we see a performance boost on + workloads which use vectors of chars and shorts, since they are now promoted + to 32-bit types, which are better supported by the SIMD instruction set. + Floating point types are still widened as before.</p> + + <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> <ul> -<!-- -<li></li> ---> + <li>TableGen can now synthesize register classes that are only needed to + represent combinations of constraints from instructions and sub-registers. + The synthetic register classes inherit most of their properties form their + closest user-defined super-class.</li> + <li><code>MachineRegisterInfo</code> now allows the reserved registers to be + frozen when register allocation starts. Target hooks should use the + <code>MRI->canReserveReg(FramePtr)</code> method to avoid accidentally + disabling frame pointer elimination during register allocation.</li> + <li>A new kind of <code>MachineOperand</code> provides a compact + representation of large clobber lists on call instructions. The register + mask operand references a bit mask of preserved registers. Everything else + is clobbered.</li> </ul> + +<p> We added new TableGen infrastructure to support bundling for + Very Long Instruction Word (VLIW) architectures. TableGen can now + automatically generate a deterministic finite automaton from a VLIW + target's schedule description which can be queried to determine + legal groupings of instructions in a bundle.</p> + </div> <!--=========================================================================--> @@ -907,13 +385,12 @@ Builder.CreateResume(UnwindData); <p>New features and major changes in the X86 target include:</p> <ul> - - <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> - + <li>Bug fixes and improved support for AVX1</li> + <li>Support for AVX2 (still incomplete at this point)</li> + <li>Call instructions use the new register mask operands for faster compile + times and better support for different calling conventions. The old WINCALL + instructions are no longer needed.</li> + <li>DW2 Exception Handling is enabled on Cygwin and MinGW.</li> </ul> </div> @@ -928,386 +405,188 @@ Builder.CreateResume(UnwindData); <p>New features of the ARM target include:</p> <ul> -<!-- -<li></li> ---> + <li>The constant island pass now supports basic block and constant pool entry + alignments greater than 4 bytes.</li> + <li>On Darwin, the ARM target now has a full-featured integrated assembler. + </li> </ul> -</div> - -<!--=========================================================================--> -<h3> -<a name="OtherTS">Other Target Specific Improvements</a> -</h3> - -<p>PPC32/ELF va_arg was implemented.</p> -<p>PPC32 initial support for .o file writing was implemented.</p> +<h4> +<a name="armintegratedassembler">ARM Integrated Assembler</a> +</h4> <div> +<p>The ARM target now includes a full featured macro assembler, including +direct-to-object module support for clang. The assembler is currently enabled +by default for Darwin only pending testing and any additional necessary +platform specific support for Linux.</p> -<ul> -<!-- -<li></li> ---> -</ul> +<p>Full support is included for Thumb1, Thumb2 and ARM modes, along with +subtarget and CPU specific extensions for VFP2, VFP3 and NEON.</p> +<p>The assembler is Unified Syntax only (see ARM Architecural Reference Manual +for details). While there is some, and growing, support for pre-unfied (divided) +syntax, there are still significant gaps in that support.</p> </div> +</div> <!--=========================================================================--> <h3> -<a name="changes">Major Changes and Removed Features</a> +<a name="MIPS">MIPS Target Improvements</a> </h3> <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>This release has seen major new work on just about every aspect of the MIPS + backend. Some of the major new features include:</p> <ul> - <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> - <li>The old atomic intrinscs (<code>llvm.memory.barrier</code> and - <code>llvm.atomic.*</code>) are now gone. Please use the new atomic - instructions, described in the <a href="Atomics.html">atomics guide</a>. + <li>....</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> +<a name="OtherTS">Other Target Specific Improvements</a> </h3> <div> -<p>In addition, many APIs have changed in this release. Some of the major - LLVM API changes are:</p> - <ul> - <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> -<li><code>ExtractValueInst::Create</code></li> -<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>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>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>....</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> - -<!-- *********************************************************************** --> -<h2> - <a name="knownproblems">Known Problems</a> -</h2> -<!-- *********************************************************************** --> - -<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> - -<!-- ======================================================================= --> +<!--=========================================================================--> <h3> - <a name="experimental">Experimental features included with this release</a> +<a name="changes">Major Changes and Removed Features</a> </h3> <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> +<p>If you're already an LLVM user or developer with out-of-tree changes based on + LLVM 3.1, this section lists some "gotchas" that you may run into upgrading + from the previous release.</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>LLVM 3.1 removes support for reading LLVM 2.9 bitcode files. Going + forward, we aim for all future versions of LLVM to read bitcode files and + <tt>.ll</tt> files produced by LLVM 3.0 and later.</li> + <li>The <tt>unwind</tt> instruction is now gone. With the introduction of the + new exception handling system in LLVM 3.0, the <tt>unwind</tt> instruction + became obsolete.</li> + <li>....</li> </ul> </div> -<!-- ======================================================================= --> +<!--=========================================================================--> <h3> - <a name="x86-be">Known problems with the X86 back-end</a> +<a name="api_changes">Internal API Changes</a> </h3> <div> -<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> - - <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> - - <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>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> - </ul> - </li> - -</ul> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="ppc-be">Known problems with the PowerPC back-end</a> -</h3> - -<div> +<p>In addition, many APIs have changed in this release. Some of the major + LLVM API changes are:</p> <ul> - <li>The PPC32/ELF support lacks PIC support.</li> -</ul> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="arm-be">Known problems with the ARM back-end</a> -</h3> - -<div> - + <li>Target specific options have been moved from global variables to members + on the new <code>TargetOptions</code> class, which is local to each + <code>TargetMachine</code>. As a consequence, the associated flags will + no longer be accepted by <tt>clang -mllvm</tt>. This includes: <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><code>llvm::PrintMachineCode</code></li> +<li><code>llvm::NoFramePointerElim</code></li> +<li><code>llvm::NoFramePointerElimNonLeaf</code></li> +<li><code>llvm::DisableFramePointerElim(const MachineFunction &)</code></li> +<li><code>llvm::LessPreciseFPMADOption</code></li> +<li><code>llvm::LessPrecideFPMAD()</code></li> +<li><code>llvm::NoExcessFPPrecision</code></li> +<li><code>llvm::UnsafeFPMath</code></li> +<li><code>llvm::NoInfsFPMath</code></li> +<li><code>llvm::NoNaNsFPMath</code></li> +<li><code>llvm::HonorSignDependentRoundingFPMathOption</code></li> +<li><code>llvm::HonorSignDependentRoundingFPMath()</code></li> +<li><code>llvm::UseSoftFloat</code></li> +<li><code>llvm::FloatABIType</code></li> +<li><code>llvm::NoZerosInBSS</code></li> +<li><code>llvm::JITExceptionHandling</code></li> +<li><code>llvm::JITEmitDebugInfo</code></li> +<li><code>llvm::JITEmitDebugInfoToDisk</code></li> +<li><code>llvm::GuaranteedTailCallOpt</code></li> +<li><code>llvm::StackAlignmentOverride</code></li> +<li><code>llvm::RealignStack</code></li> +<li><code>llvm::DisableJumpTables</code></li> +<li><code>llvm::EnableFastISel</code></li> +<li><code>llvm::getTrapFunctionName()</code></li> +<li><code>llvm::EnableSegmentedStacks</code></li> +</ul></li> + <li>....</li> </ul> </div> -<!-- ======================================================================= --> +<!--=========================================================================--> <h3> - <a name="sparc-be">Known problems with the SPARC back-end</a> +<a name="tools_changes">Tools Changes</a> </h3> <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> -</ul> +<p>In addition, some tools have changed in this release. Some of the changes + are:</p> -</div> - -<!-- ======================================================================= --> -<h3> - <a name="mips-be">Known problems with the MIPS back-end</a> -</h3> - -<div> <ul> - <li>64-bit MIPS targets are not supported yet.</li> + <li>llvm-stress is a command line tool for generating random .ll files to fuzz + different LLVM components. </li> + <li>....</li> </ul> -</div> - -<!-- ======================================================================= --> -<h3> - <a name="alpha-be">Known problems with the Alpha back-end</a> -</h3> - -<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>....</li> </ul> </div> -<!-- ======================================================================= --> -<h3> - <a name="c-be">Known problems with the C back-end</a> -</h3> - -<div> - -<p>The C backend has numerous problems and is not being actively maintained. - 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> -</ul> - </div> - -<!-- ======================================================================= --> -<h3> - <a name="llvm-gcc">Known problems with the llvm-gcc front-end</a> -</h3> +<!-- *********************************************************************** --> +<h2> + <a name="knownproblems">Known Problems</a> +</h2> +<!-- *********************************************************************** --> <div> -<p><b>LLVM 2.9 was the last release of llvm-gcc.</b></p> +<p>LLVM is generally a production quality compiler, and is used by a broad range + of applications and shipping in many products. That said, not every + subsystem is as mature as the aggregate, particularly the more obscure + targets. 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 or ask on the <a + href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev + list</a>.</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 - <tt>__builtin_apply</tt> family of builtins. However, some extensions - are only supported on some targets. For example, trampolines are only - supported on some targets (these are used when you take the address of a - nested function).</p> + <p>Known problem areas include:</p> -<p>Fortran support generally works, but there are still several unresolved bugs - in <a href="http://llvm.org/bugs/">Bugzilla</a>. Please see the - tools/gfortran component for details. Note that llvm-gcc is missing major - Fortran performance work in the frontend and library that went into GCC after - 4.2. If you are interested in Fortran, we recommend that you consider using - <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> +<ul> + <li>The Alpha, Blackfin, CellSPU, MSP430, PTX, SystemZ and + XCore backends are experimental, and the Alpha, Blackfin and SystemZ + targets have already been removed from mainline.</li> + + <li>The integrated assembler, disassembler, and JIT is not supported by + several targets. If an integrated assembler is not supported, then a + system assembler is required. For more details, see the <a + href="CodeGenerator.html#targetfeatures">Target Features Matrix</a>. + </li> -</div> + <li>The C backend has numerous problems and is not being actively maintained. + Depending on it for anything serious is not advised.</li> +</ul> </div> @@ -1342,7 +621,7 @@ Builder.CreateResume(UnwindData); 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-11-01 05:51:35 +0100 (Tue, 01 Nov 2011) $ + Last modified: $Date: 2012-04-12 17:17:35 +0200 (Thu, 12 Apr 2012) $ </address> </body> diff --git a/docs/SegmentedStacks.html b/docs/SegmentedStacks.html index a91b109..16f5507 100644 --- a/docs/SegmentedStacks.html +++ b/docs/SegmentedStacks.html @@ -20,18 +20,12 @@ <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. + 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. When using <tt>llc</tt>, segmented stacks can be enabled by adding <tt>-segmented-stacks</tt> to the command line. </p> <p> The runtime functionality is <a href="http://gcc.gnu.org/wiki/SplitStacks">already there in libgcc</a>. diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index 75fae6e89..259a259 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -53,6 +53,28 @@ <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li> <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li> </ol></li> + <li><a href="#llvmdwarfextension">LLVM Dwarf Extensions</a> + <ol> + <li><a href="#objcproperty">Debugging Information Extension + for Objective C Properties</a> + <ul> + <li><a href="#objcpropertyintroduction">Introduction</a></li> + <li><a href="#objcpropertyproposal">Proposal</a></li> + <li><a href="#objcpropertynewattributes">New DWARF Attributes</a></li> + <li><a href="#objcpropertynewconstants">New DWARF Constants</a></li> + </ul> + </li> + <li><a href="#acceltable">Name Accelerator Tables</a> + <ul> + <li><a href="#acceltableintroduction">Introduction</a></li> + <li><a href="#acceltablehashes">Hash Tables</a></li> + <li><a href="#acceltabledetails">Details</a></li> + <li><a href="#acceltablecontents">Contents</a></li> + <li><a href="#acceltableextensions">Language Extensions and File Format Changes</a></li> + </ul> + </li> + </ol> + </li> </ul> </td> <td class="right"> @@ -231,8 +253,8 @@ height="369"> for the optimizer to optimize the program and debugging information without necessarily having to know anything about debugging information. In particular, the use of metadata avoids duplicated debugging information from - the beginning, and the global dead code elimination pass automatically - deletes debugging information for a function if it decides to delete the + the beginning, and the global dead code elimination pass automatically + deletes debugging information for a function if it decides to delete the function. </p> <p>To do this, most of the debugging information (descriptors for types, @@ -241,9 +263,9 @@ height="369"> <p>Debug information is designed to be agnostic about the target debugger and debugging information representation (e.g. DWARF/Stabs/etc). It uses a - generic pass to decode the information that represents variables, types, - functions, namespaces, etc: this allows for arbitrary source-language - semantics and type-systems to be used, as long as there is a module + generic pass to decode the information that represents variables, types, + functions, namespaces, etc: this allows for arbitrary source-language + semantics and type-systems to be used, as long as there is a module written for the target debugger to interpret the information. </p> <p>To provide basic functionality, the LLVM debugger does have to make some @@ -279,7 +301,7 @@ height="369"> the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base = 0x1000.)</p> -<p>The fields of debug descriptors used internally by LLVM +<p>The fields of debug descriptors used internally by LLVM are restricted to only the simple data types <tt>i32</tt>, <tt>i1</tt>, <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and <tt>mdnode</tt>. </p> @@ -301,7 +323,7 @@ height="369"> with the current debug version (LLVMDebugVersion = 8 << 16 or 0x80000 or 524288.)</a></p> -<p>The details of the various descriptors follow.</p> +<p>The details of the various descriptors follow.</p> <!-- ======================================================================= --> <h4> @@ -313,14 +335,14 @@ height="369"> <div class="doc_code"> <pre> !0 = metadata !{ - i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_compile_unit) - i32, ;; Unused field. - i32, ;; DWARF language identifier (ex. DW_LANG_C89) + i32, ;; Unused field. + i32, ;; DWARF language identifier (ex. DW_LANG_C89) metadata, ;; Source file name metadata, ;; Source file directory (includes trailing slash) metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") - i1, ;; True if this is a main compile unit. + i1, ;; True if this is a main compile unit. i1, ;; True if this is optimized. metadata, ;; Flags i32 ;; Runtime version @@ -340,7 +362,7 @@ 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 + These descriptors are collected by a named metadata <tt>!llvm.dbg.cu</tt>. Compile unit descriptor keeps track of subprograms, global variables and type information. @@ -356,7 +378,7 @@ height="369"> <div class="doc_code"> <pre> !0 = metadata !{ - i32, ;; Tag = 41 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32, ;; Tag = 41 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_file_type) metadata, ;; Source file name metadata, ;; Source file directory (includes trailing slash) @@ -384,7 +406,7 @@ height="369"> <div class="doc_code"> <pre> !1 = metadata !{ - i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_variable) i32, ;; Unused field. metadata, ;; Reference to context descriptor @@ -403,7 +425,8 @@ height="369"> <p>These descriptors provide debug information about globals variables. The provide details such as name, type and where the variable is defined. All -global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> +global variables are collected inside the named metadata +<tt>!llvm.dbg.cu</tt>.</p> </div> @@ -429,11 +452,12 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> metadata, ;; Reference to type descriptor i1, ;; True if the global is local to compile unit (static) i1, ;; True if the global is defined in the compile unit (not extern) + i32, ;; Line number where the scope of the subprogram begins i32, ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual i32, ;; Index into a virtual function - metadata, ;; indicates which base type contains the vtable pointer for the + metadata, ;; indicates which base type contains the vtable pointer for the ;; derived class - i1, ;; isArtificial + i32, ;; Flags - Artifical, Private, Protected, Explicit, Prototyped. i1, ;; isOptimized Function *,;; Pointer to LLVM function metadata, ;; Lists function template parameters @@ -446,8 +470,6 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> <p>These descriptors provide debug information about functions, methods and subprograms. They provide details such as name, return types and the source location where the subprogram is defined. - All subprogram descriptors are collected by a named metadata - <tt>!llvm.dbg.sp</tt>. </p> </div> @@ -501,9 +523,9 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> <div class="doc_code"> <pre> !4 = metadata !{ - i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_base_type) - metadata, ;; Reference to context + 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) @@ -561,9 +583,10 @@ DW_ATE_unsigned_char = 8 i64, ;; Size in bits i64, ;; Alignment in bits i64, ;; Offset in bits + i32, ;; Flags to encode attributes, e.g. private metadata, ;; Reference to type derived from - metadata, ;; (optional) Name of the Objective C property assoicated with - ;; Objective-C an ivar + metadata, ;; (optional) Name of the Objective C property associated with + ;; Objective-C an ivar metadata, ;; (optional) Name of the Objective C property getter selector. metadata, ;; (optional) Name of the Objective C property setter selector. i32 ;; (optional) Objective C property attributes. @@ -597,9 +620,9 @@ DW_TAG_restrict_type = 55 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p> -<p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>, - <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> - and <tt>DW_TAG_restrict_type</tt> are used to qualify +<p><tt>DW_TAG_pointer_type</tt>, <tt>DW_TAG_reference_type</tt>, + <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> and + <tt>DW_TAG_restrict_type</tt> are used to qualify the <a href="#format_derived_type">derived type</a>. </p> <p><a href="#format_derived_type">Derived type</a> location can be determined @@ -667,7 +690,8 @@ DW_TAG_inheritance = 28 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are <a href="#format_enumeration">enumerator descriptors</a>, each representing the definition of enumeration value for the set. All enumeration type - descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p> + descriptors are collected inside the named metadata + <tt>!llvm.dbg.cu</tt>.</p> <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag = <tt>DW_TAG_union_type</tt>) types are any one of @@ -738,7 +762,7 @@ DW_TAG_inheritance = 28 <div class="doc_code"> <pre> !6 = metadata !{ - i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> ;; (DW_TAG_enumerator) metadata, ;; Name i64 ;; Value @@ -820,9 +844,9 @@ DW_TAG_return_variable = 258 void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata) </pre> -<p>This intrinsic provides information about a local element (ex. variable.) The - first argument is metadata holding alloca for the variable. The - second argument is metadata containing description of the variable. </p> +<p>This intrinsic provides information about a local element (e.g., variable). The + first argument is metadata holding the alloca for the variable. The + second argument is metadata containing a description of the variable.</p> </div> <!-- ======================================================================= --> @@ -838,8 +862,8 @@ DW_TAG_return_variable = 258 <p>This intrinsic provides information when a user source variable is set to a new value. The first argument is the new value (wrapped as metadata). The second argument is the offset in the user source variable where the new value - is written. The third argument is metadata containing description of the - user source variable. </p> + is written. The third argument is metadata containing a description of the + user source variable.</p> </div> </div> @@ -906,27 +930,27 @@ entry: declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone -!0 = metadata !{i32 459008, metadata !1, metadata !"X", +!0 = metadata !{i32 459008, metadata !1, metadata !"X", metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ] !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] -!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo", - metadata !"foo", metadata !3, i32 1, metadata !4, +!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo", + metadata !"foo", metadata !3, i32 1, metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ] -!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c", - metadata !"/private/tmp", metadata !"clang 1.1", i1 true, +!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c", + metadata !"/private/tmp", metadata !"clang 1.1", i1 true, i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ] -!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0, +!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0, i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ] !5 = metadata !{null} -!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0, +!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0, i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ] !7 = metadata !{i32 2, i32 7, metadata !1, null} !8 = metadata !{i32 2, i32 3, metadata !1, null} -!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3, +!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3, metadata !6}; [ DW_TAG_auto_variable ] !10 = metadata !{i32 3, i32 7, metadata !1, null} !11 = metadata !{i32 3, i32 3, metadata !1, null} -!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5, +!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5, metadata !6}; [ DW_TAG_auto_variable ] !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ] !14 = metadata !{i32 5, i32 9, metadata !13, null} @@ -946,7 +970,7 @@ declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone <div class="doc_code"> <pre> -call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7 +call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7 </pre> </div> @@ -960,9 +984,9 @@ call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7 <pre> !7 = metadata !{i32 2, i32 7, metadata !1, null} !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] -!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", - metadata !"foo", metadata !"foo", metadata !3, i32 1, - metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ] +!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", + metadata !"foo", metadata !"foo", metadata !3, i32 1, + metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ] </pre> </div> @@ -987,7 +1011,7 @@ call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14 <p>The second intrinsic <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt> - encodes debugging information for variable <tt>Z</tt>. The metadata + encodes debugging information for variable <tt>Z</tt>. The metadata <tt>!dbg !14</tt> attached to the intrinsic provides scope information for the variable <tt>Z</tt>.</p> @@ -1068,9 +1092,9 @@ int main(int argc, char *argv[]) { i32 524305, ;; Tag i32 0, ;; Unused i32 4, ;; Language Id - metadata !"MySource.cpp", - metadata !"/Users/mine/sources", - metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", + metadata !"MySource.cpp", + metadata !"/Users/mine/sources", + metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", i1 true, ;; Main Compile Unit i1 false, ;; Optimized compile unit metadata !"", ;; Compiler flags @@ -1081,8 +1105,8 @@ int main(int argc, char *argv[]) { ;; !1 = metadata !{ i32 524329, ;; Tag - metadata !"MySource.cpp", - metadata !"/Users/mine/sources", + metadata !"MySource.cpp", + metadata !"/Users/mine/sources", metadata !2 ;; Compile unit } @@ -1092,7 +1116,7 @@ int main(int argc, char *argv[]) { !3 = metadata !{ i32 524329, ;; Tag metadata !"Myheader.h" - metadata !"/Users/mine/sources", + metadata !"/Users/mine/sources", metadata !2 ;; Compile unit } @@ -1100,9 +1124,9 @@ int main(int argc, char *argv[]) { </pre> </div> -<p>llvm::Instruction provides easy access to metadata attached with an +<p>llvm::Instruction provides easy access to metadata attached with an instruction. One can extract line number information encoded in LLVM IR -using <tt>Instruction::getMetadata()</tt> and +using <tt>Instruction::getMetadata()</tt> and <tt>DILocation::getLineNumber()</tt>. <pre> if (MDNode *N = I->getMetadata("dbg")) { // Here I is an LLVM instruction @@ -1141,44 +1165,79 @@ int MyGlobal = 100; ;; ;; List of debug info of globals ;; -!llvm.dbg.gv = !{!0} +!llvm.dbg.cu = !{!0} -;; -;; Define the global variable descriptor. Note the reference to the global -;; variable anchor and the global variable itself. -;; +;; Define the compile unit. !0 = metadata !{ - i32 524340, ;; Tag - i32 0, ;; Unused - metadata !1, ;; Context - metadata !"MyGlobal", ;; Name - metadata !"MyGlobal", ;; Display Name - metadata !"MyGlobal", ;; Linkage Name - metadata !3, ;; Compile Unit - i32 1, ;; Line Number - metadata !4, ;; Type - i1 false, ;; Is a local variable - i1 true, ;; Is this a definition - i32* @MyGlobal ;; The global variable + i32 786449, ;; Tag + i32 0, ;; Context + i32 4, ;; Language + metadata !"foo.cpp", ;; File + metadata !"/Volumes/Data/tmp", ;; Directory + metadata !"clang version 3.1 ", ;; Producer + i1 true, ;; Deprecated field + i1 false, ;; "isOptimized"? + metadata !"", ;; Flags + i32 0, ;; Runtime Version + metadata !1, ;; Enum Types + metadata !1, ;; Retained Types + metadata !1, ;; Subprograms + metadata !3 ;; Global Variables +} ; [ DW_TAG_compile_unit ] + +;; The Array of Global Variables +!3 = metadata !{ + metadata !4 } -;; -;; Define the basic type of 32 bit signed integer. Note that since int is an -;; intrinsic type the source file is NULL and line 0. -;; !4 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context - metadata !"int", ;; Name - metadata !1, ;; File - i32 0, ;; Line number - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 5 ;; Encoding + metadata !5 } +;; +;; Define the global variable itself. +;; +!5 = metadata !{ + i32 786484, ;; Tag + i32 0, ;; Unused + null, ;; Unused + metadata !"MyGlobal", ;; Name + metadata !"MyGlobal", ;; Display Name + metadata !"", ;; Linkage Name + metadata !6, ;; File + i32 1, ;; Line + metadata !7, ;; Type + i32 0, ;; IsLocalToUnit + i32 1, ;; IsDefinition + i32* @MyGlobal ;; LLVM-IR Value +} ; [ DW_TAG_variable ] + +;; +;; Define the file +;; +!6 = metadata !{ + i32 786473, ;; Tag + metadata !"foo.cpp", ;; File + metadata !"/Volumes/Data/tmp", ;; Directory + null ;; Unused +} ; [ DW_TAG_file_type ] + +;; +;; Define the type +;; +!7 = metadata !{ + i32 786468, ;; Tag + null, ;; Unused + metadata !"int", ;; Name + null, ;; Unused + i32 0, ;; Line + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset + i32 0, ;; Flags + i32 5 ;; Encoding +} ; [ DW_TAG_base_type ] + </pre> </div> @@ -1220,7 +1279,7 @@ int main(int argc, char *argv[]) { metadata !1, ;; File i32 1, ;; Line number metadata !4, ;; Type - i1 false, ;; Is local + i1 false, ;; Is local i1 true, ;; Is definition i32 0, ;; Virtuality attribute, e.g. pure virtual function i32 0, ;; Index into virtual table for C++ methods @@ -1314,7 +1373,7 @@ define i32 @main(i32 %argc, i8** %argv) { !2 = metadata !{ i32 524324, ;; Tag metadata !1, ;; Context - metadata !"unsigned char", + metadata !"unsigned char", metadata !1, ;; File i32 0, ;; Line number i64 8, ;; Size in Bits @@ -1803,6 +1862,988 @@ enum Trees { </div> + +<!-- *********************************************************************** --> +<h2> + <a name="llvmdwarfextension">Debugging information format</a> +</h2> +<!-- *********************************************************************** --> +<div> +<!-- ======================================================================= --> +<h3> + <a name="objcproperty">Debugging Information Extension for Objective C Properties</a> +</h3> +<div> +<!-- *********************************************************************** --> +<h4> + <a name="objcpropertyintroduction">Introduction</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<p>Objective C provides a simpler way to declare and define accessor methods +using declared properties. The language provides features to declare a +property and to let compiler synthesize accessor methods. +</p> + +<p>The debugger lets developer inspect Objective C interfaces and their +instance variables and class variables. However, the debugger does not know +anything about the properties defined in Objective C interfaces. The debugger +consumes information generated by compiler in DWARF format. The format does +not support encoding of Objective C properties. This proposal describes DWARF +extensions to encode Objective C properties, which the debugger can use to let +developers inspect Objective C properties. +</p> + +</div> + + +<!-- *********************************************************************** --> +<h4> + <a name="objcpropertyproposal">Proposal</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<p>Objective C properties exist separately from class members. A property +can be defined only by "setter" and "getter" selectors, and +be calculated anew on each access. Or a property can just be a direct access +to some declared ivar. Finally it can have an ivar "automatically +synthesized" for it by the compiler, in which case the property can be +referred to in user code directly using the standard C dereference syntax as +well as through the property "dot" syntax, but there is no entry in +the @interface declaration corresponding to this ivar. +</p> +<p> +To facilitate debugging, these properties we will add a new DWARF TAG into the +DW_TAG_structure_type definition for the class to hold the description of a +given property, and a set of DWARF attributes that provide said description. +The property tag will also contain the name and declared type of the property. +</p> +<p> +If there is a related ivar, there will also be a DWARF property attribute placed +in the DW_TAG_member DIE for that ivar referring back to the property TAG for +that property. And in the case where the compiler synthesizes the ivar directly, +the compiler is expected to generate a DW_TAG_member for that ivar (with the +DW_AT_artificial set to 1), whose name will be the name used to access this +ivar directly in code, and with the property attribute pointing back to the +property it is backing. +</p> +<p> +The following examples will serve as illustration for our discussion: +</p> + +<div class="doc_code"> +<pre> +@interface I1 { + int n2; +} + +@property int p1; +@property int p2; +@end + +@implementation I1 +@synthesize p1; +@synthesize p2 = n2; +@end +</pre> +</div> + +<p> +This produces the following DWARF (this is a "pseudo dwarfdump" output): +</p> +<div class="doc_code"> +<pre> +0x00000100: TAG_structure_type [7] * + AT_APPLE_runtime_class( 0x10 ) + AT_name( "I1" ) + AT_decl_file( "Objc_Property.m" ) + AT_decl_line( 3 ) + +0x00000110 TAG_APPLE_property + AT_name ( "p1" ) + AT_type ( {0x00000150} ( int ) ) + +0x00000120: TAG_APPLE_property + AT_name ( "p2" ) + AT_type ( {0x00000150} ( int ) ) + +0x00000130: TAG_member [8] + AT_name( "_p1" ) + AT_APPLE_property ( {0x00000110} "p1" ) + AT_type( {0x00000150} ( int ) ) + AT_artificial ( 0x1 ) + +0x00000140: TAG_member [8] + AT_name( "n2" ) + AT_APPLE_property ( {0x00000120} "p2" ) + AT_type( {0x00000150} ( int ) ) + +0x00000150: AT_type( ( int ) ) +</pre> +</div> + +<p> Note, the current convention is that the name of the ivar for an +auto-synthesized property is the name of the property from which it derives with +an underscore prepended, as is shown in the example. +But we actually don't need to know this convention, since we are given the name +of the ivar directly. +</p> + +<p> +Also, it is common practice in ObjC to have different property declarations in +the @interface and @implementation - e.g. to provide a read-only property in +the interface,and a read-write interface in the implementation. In that case, +the compiler should emit whichever property declaration will be in force in the +current translation unit. +</p> + +<p> Developers can decorate a property with attributes which are encoded using +DW_AT_APPLE_property_attribute. +</p> + +<div class="doc_code"> +<pre> +@property (readonly, nonatomic) int pr; +</pre> +</div> +<p> +Which produces a property tag: +<p> +<div class="doc_code"> +<pre> +TAG_APPLE_property [8] + AT_name( "pr" ) + AT_type ( {0x00000147} (int) ) + AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic) +</pre> +</div> + +<p> The setter and getter method names are attached to the property using +DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes. +</p> +<div class="doc_code"> +<pre> +@interface I1 +@property (setter=myOwnP3Setter:) int p3; +-(void)myOwnP3Setter:(int)a; +@end + +@implementation I1 +@synthesize p3; +-(void)myOwnP3Setter:(int)a{ } +@end +</pre> +</div> + +<p> +The DWARF for this would be: +</p> +<div class="doc_code"> +<pre> +0x000003bd: TAG_structure_type [7] * + AT_APPLE_runtime_class( 0x10 ) + AT_name( "I1" ) + AT_decl_file( "Objc_Property.m" ) + AT_decl_line( 3 ) + +0x000003cd TAG_APPLE_property + AT_name ( "p3" ) + AT_APPLE_property_setter ( "myOwnP3Setter:" ) + AT_type( {0x00000147} ( int ) ) + +0x000003f3: TAG_member [8] + AT_name( "_p3" ) + AT_type ( {0x00000147} ( int ) ) + AT_APPLE_property ( {0x000003cd} ) + AT_artificial ( 0x1 ) +</pre> +</div> + +</div> + +<!-- *********************************************************************** --> +<h4> + <a name="objcpropertynewtags">New DWARF Tags</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<table border="1" cellspacing="0"> + <col width="200"> + <col width="200"> + <tr> + <th>TAG</th> + <th>Value</th> + </tr> + <tr> + <td>DW_TAG_APPLE_property</td> + <td>0x4200</td> + </tr> +</table> + +</div> + +<!-- *********************************************************************** --> +<h4> + <a name="objcpropertynewattributes">New DWARF Attributes</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<table border="1" cellspacing="0"> + <col width="200"> + <col width="200"> + <col width="200"> + <tr> + <th>Attribute</th> + <th>Value</th> + <th>Classes</th> + </tr> + <tr> + <td>DW_AT_APPLE_property</td> + <td>0x3fed</td> + <td>Reference</td> + </tr> + <tr> + <td>DW_AT_APPLE_property_getter</td> + <td>0x3fe9</td> + <td>String</td> + </tr> + <tr> + <td>DW_AT_APPLE_property_setter</td> + <td>0x3fea</td> + <td>String</td> + </tr> + <tr> + <td>DW_AT_APPLE_property_attribute</td> + <td>0x3feb</td> + <td>Constant</td> + </tr> +</table> + +</div> + +<!-- *********************************************************************** --> +<h4> + <a name="objcpropertynewconstants">New DWARF Constants</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<table border="1" cellspacing="0"> + <col width="200"> + <col width="200"> + <tr> + <th>Name</th> + <th>Value</th> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_readonly</td> + <td>0x1</td> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_readwrite</td> + <td>0x2</td> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_assign</td> + <td>0x4</td> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_retain</td> + <td>0x8</td> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_copy</td> + <td>0x10</td> + </tr> + <tr> + <td>DW_AT_APPLE_PROPERTY_nonatomic</td> + <td>0x20</td> + </tr> +</table> + +</div> +</div> + +<!-- ======================================================================= --> +<h3> + <a name="acceltable">Name Accelerator Tables</a> +</h3> +<!-- ======================================================================= --> +<div> +<!-- ======================================================================= --> +<h4> + <a name="acceltableintroduction">Introduction</a> +</h4> +<!-- ======================================================================= --> +<div> +<p>The .debug_pubnames and .debug_pubtypes formats are not what a debugger + needs. The "pub" in the section name indicates that the entries in the + table are publicly visible names only. This means no static or hidden + functions show up in the .debug_pubnames. No static variables or private class + variables are in the .debug_pubtypes. Many compilers add different things to + these tables, so we can't rely upon the contents between gcc, icc, or clang.</p> + +<p>The typical query given by users tends not to match up with the contents of + these tables. For example, the DWARF spec states that "In the case of the + name of a function member or static data member of a C++ structure, class or + union, the name presented in the .debug_pubnames section is not the simple + name given by the DW_AT_name attribute of the referenced debugging information + entry, but rather the fully qualified name of the data or function member." + So the only names in these tables for complex C++ entries is a fully + qualified name. Debugger users tend not to enter their search strings as + "a::b::c(int,const Foo&) const", but rather as "c", "b::c" , or "a::b::c". So + the name entered in the name table must be demangled in order to chop it up + appropriately and additional names must be manually entered into the table + to make it effective as a name lookup table for debuggers to use.</p> + +<p>All debuggers currently ignore the .debug_pubnames table as a result of + its inconsistent and useless public-only name content making it a waste of + space in the object file. These tables, when they are written to disk, are + not sorted in any way, leaving every debugger to do its own parsing + and sorting. These tables also include an inlined copy of the string values + in the table itself making the tables much larger than they need to be on + disk, especially for large C++ programs.</p> + +<p>Can't we just fix the sections by adding all of the names we need to this + table? No, because that is not what the tables are defined to contain and we + won't know the difference between the old bad tables and the new good tables. + At best we could make our own renamed sections that contain all of the data + we need.</p> + +<p>These tables are also insufficient for what a debugger like LLDB needs. + LLDB uses clang for its expression parsing where LLDB acts as a PCH. LLDB is + then often asked to look for type "foo" or namespace "bar", or list items in + namespace "baz". Namespaces are not included in the pubnames or pubtypes + tables. Since clang asks a lot of questions when it is parsing an expression, + we need to be very fast when looking up names, as it happens a lot. Having new + accelerator tables that are optimized for very quick lookups will benefit + this type of debugging experience greatly.</p> + +<p>We would like to generate name lookup tables that can be mapped into + memory from disk, and used as is, with little or no up-front parsing. We would + also be able to control the exact content of these different tables so they + contain exactly what we need. The Name Accelerator Tables were designed + to fix these issues. In order to solve these issues we need to:</p> + +<ul> + <li>Have a format that can be mapped into memory from disk and used as is</li> + <li>Lookups should be very fast</li> + <li>Extensible table format so these tables can be made by many producers</li> + <li>Contain all of the names needed for typical lookups out of the box</li> + <li>Strict rules for the contents of tables</li> +</ul> + +<p>Table size is important and the accelerator table format should allow the + reuse of strings from common string tables so the strings for the names are + not duplicated. We also want to make sure the table is ready to be used as-is + by simply mapping the table into memory with minimal header parsing.</p> + +<p>The name lookups need to be fast and optimized for the kinds of lookups + that debuggers tend to do. Optimally we would like to touch as few parts of + the mapped table as possible when doing a name lookup and be able to quickly + find the name entry we are looking for, or discover there are no matches. In + the case of debuggers we optimized for lookups that fail most of the time.</p> + +<p>Each table that is defined should have strict rules on exactly what is in + the accelerator tables and documented so clients can rely on the content.</p> + +</div> + +<!-- ======================================================================= --> +<h4> + <a name="acceltablehashes">Hash Tables</a> +</h4> +<!-- ======================================================================= --> + +<div> +<h5>Standard Hash Tables</h5> + +<p>Typical hash tables have a header, buckets, and each bucket points to the +bucket contents: +</p> + +<div class="doc_code"> +<pre> +.------------. +| HEADER | +|------------| +| BUCKETS | +|------------| +| DATA | +`------------' +</pre> +</div> + +<p>The BUCKETS are an array of offsets to DATA for each hash:</p> + +<div class="doc_code"> +<pre> +.------------. +| 0x00001000 | BUCKETS[0] +| 0x00002000 | BUCKETS[1] +| 0x00002200 | BUCKETS[2] +| 0x000034f0 | BUCKETS[3] +| | ... +| 0xXXXXXXXX | BUCKETS[n_buckets] +'------------' +</pre> +</div> + +<p>So for bucket[3] in the example above, we have an offset into the table + 0x000034f0 which points to a chain of entries for the bucket. Each bucket + must contain a next pointer, full 32 bit hash value, the string itself, + and the data for the current string value.</p> + +<div class="doc_code"> +<pre> + .------------. +0x000034f0: | 0x00003500 | next pointer + | 0x12345678 | 32 bit hash + | "erase" | string value + | data[n] | HashData for this bucket + |------------| +0x00003500: | 0x00003550 | next pointer + | 0x29273623 | 32 bit hash + | "dump" | string value + | data[n] | HashData for this bucket + |------------| +0x00003550: | 0x00000000 | next pointer + | 0x82638293 | 32 bit hash + | "main" | string value + | data[n] | HashData for this bucket + `------------' +</pre> +</div> + +<p>The problem with this layout for debuggers is that we need to optimize for + the negative lookup case where the symbol we're searching for is not present. + So if we were to lookup "printf" in the table above, we would make a 32 hash + for "printf", it might match bucket[3]. We would need to go to the offset + 0x000034f0 and start looking to see if our 32 bit hash matches. To do so, we + need to read the next pointer, then read the hash, compare it, and skip to + the next bucket. Each time we are skipping many bytes in memory and touching + new cache pages just to do the compare on the full 32 bit hash. All of these + accesses then tell us that we didn't have a match.</p> + +<h5>Name Hash Tables</h5> + +<p>To solve the issues mentioned above we have structured the hash tables + a bit differently: a header, buckets, an array of all unique 32 bit hash + values, followed by an array of hash value data offsets, one for each hash + value, then the data for all hash values:</p> + +<div class="doc_code"> +<pre> +.-------------. +| HEADER | +|-------------| +| BUCKETS | +|-------------| +| HASHES | +|-------------| +| OFFSETS | +|-------------| +| DATA | +`-------------' +</pre> +</div> + +<p>The BUCKETS in the name tables are an index into the HASHES array. By + making all of the full 32 bit hash values contiguous in memory, we allow + ourselves to efficiently check for a match while touching as little + memory as possible. Most often checking the 32 bit hash values is as far as + the lookup goes. If it does match, it usually is a match with no collisions. + So for a table with "n_buckets" buckets, and "n_hashes" unique 32 bit hash + values, we can clarify the contents of the BUCKETS, HASHES and OFFSETS as:</p> + +<div class="doc_code"> +<pre> +.-------------------------. +| HEADER.magic | uint32_t +| HEADER.version | uint16_t +| HEADER.hash_function | uint16_t +| HEADER.bucket_count | uint32_t +| HEADER.hashes_count | uint32_t +| HEADER.header_data_len | uint32_t +| HEADER_DATA | HeaderData +|-------------------------| +| BUCKETS | uint32_t[n_buckets] // 32 bit hash indexes +|-------------------------| +| HASHES | uint32_t[n_buckets] // 32 bit hash values +|-------------------------| +| OFFSETS | uint32_t[n_buckets] // 32 bit offsets to hash value data +|-------------------------| +| ALL HASH DATA | +`-------------------------' +</pre> +</div> + +<p>So taking the exact same data from the standard hash example above we end up + with:</p> + +<div class="doc_code"> +<pre> + .------------. + | HEADER | + |------------| + | 0 | BUCKETS[0] + | 2 | BUCKETS[1] + | 5 | BUCKETS[2] + | 6 | BUCKETS[3] + | | ... + | ... | BUCKETS[n_buckets] + |------------| + | 0x........ | HASHES[0] + | 0x........ | HASHES[1] + | 0x........ | HASHES[2] + | 0x........ | HASHES[3] + | 0x........ | HASHES[4] + | 0x........ | HASHES[5] + | 0x12345678 | HASHES[6] hash for BUCKETS[3] + | 0x29273623 | HASHES[7] hash for BUCKETS[3] + | 0x82638293 | HASHES[8] hash for BUCKETS[3] + | 0x........ | HASHES[9] + | 0x........ | HASHES[10] + | 0x........ | HASHES[11] + | 0x........ | HASHES[12] + | 0x........ | HASHES[13] + | 0x........ | HASHES[n_hashes] + |------------| + | 0x........ | OFFSETS[0] + | 0x........ | OFFSETS[1] + | 0x........ | OFFSETS[2] + | 0x........ | OFFSETS[3] + | 0x........ | OFFSETS[4] + | 0x........ | OFFSETS[5] + | 0x000034f0 | OFFSETS[6] offset for BUCKETS[3] + | 0x00003500 | OFFSETS[7] offset for BUCKETS[3] + | 0x00003550 | OFFSETS[8] offset for BUCKETS[3] + | 0x........ | OFFSETS[9] + | 0x........ | OFFSETS[10] + | 0x........ | OFFSETS[11] + | 0x........ | OFFSETS[12] + | 0x........ | OFFSETS[13] + | 0x........ | OFFSETS[n_hashes] + |------------| + | | + | | + | | + | | + | | + |------------| +0x000034f0: | 0x00001203 | .debug_str ("erase") + | 0x00000004 | A 32 bit array count - number of HashData with name "erase" + | 0x........ | HashData[0] + | 0x........ | HashData[1] + | 0x........ | HashData[2] + | 0x........ | HashData[3] + | 0x00000000 | String offset into .debug_str (terminate data for hash) + |------------| +0x00003500: | 0x00001203 | String offset into .debug_str ("collision") + | 0x00000002 | A 32 bit array count - number of HashData with name "collision" + | 0x........ | HashData[0] + | 0x........ | HashData[1] + | 0x00001203 | String offset into .debug_str ("dump") + | 0x00000003 | A 32 bit array count - number of HashData with name "dump" + | 0x........ | HashData[0] + | 0x........ | HashData[1] + | 0x........ | HashData[2] + | 0x00000000 | String offset into .debug_str (terminate data for hash) + |------------| +0x00003550: | 0x00001203 | String offset into .debug_str ("main") + | 0x00000009 | A 32 bit array count - number of HashData with name "main" + | 0x........ | HashData[0] + | 0x........ | HashData[1] + | 0x........ | HashData[2] + | 0x........ | HashData[3] + | 0x........ | HashData[4] + | 0x........ | HashData[5] + | 0x........ | HashData[6] + | 0x........ | HashData[7] + | 0x........ | HashData[8] + | 0x00000000 | String offset into .debug_str (terminate data for hash) + `------------' +</pre> +</div> + +<p>So we still have all of the same data, we just organize it more efficiently + for debugger lookup. If we repeat the same "printf" lookup from above, we + would hash "printf" and find it matches BUCKETS[3] by taking the 32 bit hash + value and modulo it by n_buckets. BUCKETS[3] contains "6" which is the index + into the HASHES table. We would then compare any consecutive 32 bit hashes + values in the HASHES array as long as the hashes would be in BUCKETS[3]. We + do this by verifying that each subsequent hash value modulo n_buckets is still + 3. In the case of a failed lookup we would access the memory for BUCKETS[3], and + then compare a few consecutive 32 bit hashes before we know that we have no match. + We don't end up marching through multiple words of memory and we really keep the + number of processor data cache lines being accessed as small as possible.</p> + +<p>The string hash that is used for these lookup tables is the Daniel J. + Bernstein hash which is also used in the ELF GNU_HASH sections. It is a very + good hash for all kinds of names in programs with very few hash collisions.</p> + +<p>Empty buckets are designated by using an invalid hash index of UINT32_MAX.</p> +</div> + +<!-- ======================================================================= --> +<h4> + <a name="acceltabledetails">Details</a> +</h4> +<!-- ======================================================================= --> +<div> +<p>These name hash tables are designed to be generic where specializations of + the table get to define additional data that goes into the header + ("HeaderData"), how the string value is stored ("KeyType") and the content + of the data for each hash value.</p> + +<h5>Header Layout</h5> +<p>The header has a fixed part, and the specialized part. The exact format of + the header is:</p> +<div class="doc_code"> +<pre> +struct Header +{ + uint32_t magic; // 'HASH' magic value to allow endian detection + uint16_t version; // Version number + uint16_t hash_function; // The hash function enumeration that was used + uint32_t bucket_count; // The number of buckets in this hash table + uint32_t hashes_count; // The total number of unique hash values and hash data offsets in this table + uint32_t header_data_len; // The bytes to skip to get to the hash indexes (buckets) for correct alignment + // Specifically the length of the following HeaderData field - this does not + // include the size of the preceding fields + HeaderData header_data; // Implementation specific header data +}; +</pre> +</div> +<p>The header starts with a 32 bit "magic" value which must be 'HASH' encoded as + an ASCII integer. This allows the detection of the start of the hash table and + also allows the table's byte order to be determined so the table can be + correctly extracted. The "magic" value is followed by a 16 bit version number + which allows the table to be revised and modified in the future. The current + version number is 1. "hash_function" is a uint16_t enumeration that specifies + which hash function was used to produce this table. The current values for the + hash function enumerations include:</p> +<div class="doc_code"> +<pre> +enum HashFunctionType +{ + eHashFunctionDJB = 0u, // Daniel J Bernstein hash function +}; +</pre> +</div> +<p>"bucket_count" is a 32 bit unsigned integer that represents how many buckets + are in the BUCKETS array. "hashes_count" is the number of unique 32 bit hash + values that are in the HASHES array, and is the same number of offsets are + contained in the OFFSETS array. "header_data_len" specifies the size in + bytes of the HeaderData that is filled in by specialized versions of this + table.</p> + +<h5>Fixed Lookup</h5> +<p>The header is followed by the buckets, hashes, offsets, and hash value + data. +<div class="doc_code"> +<pre> +struct FixedTable +{ + uint32_t buckets[Header.bucket_count]; // An array of hash indexes into the "hashes[]" array below + uint32_t hashes [Header.hashes_count]; // Every unique 32 bit hash for the entire table is in this table + uint32_t offsets[Header.hashes_count]; // An offset that corresponds to each item in the "hashes[]" array above +}; +</pre> +</div> +<p>"buckets" is an array of 32 bit indexes into the "hashes" array. The + "hashes" array contains all of the 32 bit hash values for all names in the + hash table. Each hash in the "hashes" table has an offset in the "offsets" + array that points to the data for the hash value.</p> + +<p>This table setup makes it very easy to repurpose these tables to contain + different data, while keeping the lookup mechanism the same for all tables. + This layout also makes it possible to save the table to disk and map it in + later and do very efficient name lookups with little or no parsing.</p> + +<p>DWARF lookup tables can be implemented in a variety of ways and can store + a lot of information for each name. We want to make the DWARF tables + extensible and able to store the data efficiently so we have used some of the + DWARF features that enable efficient data storage to define exactly what kind + of data we store for each name.</p> + +<p>The "HeaderData" contains a definition of the contents of each HashData + chunk. We might want to store an offset to all of the debug information + entries (DIEs) for each name. To keep things extensible, we create a list of + items, or Atoms, that are contained in the data for each name. First comes the + type of the data in each atom:</p> +<div class="doc_code"> +<pre> +enum AtomType +{ + eAtomTypeNULL = 0u, + eAtomTypeDIEOffset = 1u, // DIE offset, check form for encoding + eAtomTypeCUOffset = 2u, // DIE offset of the compiler unit header that contains the item in question + eAtomTypeTag = 3u, // DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2 + eAtomTypeNameFlags = 4u, // Flags from enum NameFlags + eAtomTypeTypeFlags = 5u, // Flags from enum TypeFlags +}; +</pre> +</div> +<p>The enumeration values and their meanings are:</p> +<div class="doc_code"> +<pre> + eAtomTypeNULL - a termination atom that specifies the end of the atom list + eAtomTypeDIEOffset - an offset into the .debug_info section for the DWARF DIE for this name + eAtomTypeCUOffset - an offset into the .debug_info section for the CU that contains the DIE + eAtomTypeDIETag - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is + eAtomTypeNameFlags - Flags for functions and global variables (isFunction, isInlined, isExternal...) + eAtomTypeTypeFlags - Flags for types (isCXXClass, isObjCClass, ...) +</pre> +</div> +<p>Then we allow each atom type to define the atom type and how the data for + each atom type data is encoded:</p> +<div class="doc_code"> +<pre> +struct Atom +{ + uint16_t type; // AtomType enum value + uint16_t form; // DWARF DW_FORM_XXX defines +}; +</pre> +</div> +<p>The "form" type above is from the DWARF specification and defines the + exact encoding of the data for the Atom type. See the DWARF specification for + the DW_FORM_ definitions.</p> +<div class="doc_code"> +<pre> +struct HeaderData +{ + uint32_t die_offset_base; + uint32_t atom_count; + Atoms atoms[atom_count0]; +}; +</pre> +</div> +<p>"HeaderData" defines the base DIE offset that should be added to any atoms + that are encoded using the DW_FORM_ref1, DW_FORM_ref2, DW_FORM_ref4, + DW_FORM_ref8 or DW_FORM_ref_udata. It also defines what is contained in + each "HashData" object -- Atom.form tells us how large each field will be in + the HashData and the Atom.type tells us how this data should be interpreted.</p> + +<p>For the current implementations of the ".apple_names" (all functions + globals), + the ".apple_types" (names of all types that are defined), and the + ".apple_namespaces" (all namespaces), we currently set the Atom array to be:</p> +<div class="doc_code"> +<pre> +HeaderData.atom_count = 1; +HeaderData.atoms[0].type = eAtomTypeDIEOffset; +HeaderData.atoms[0].form = DW_FORM_data4; +</pre> +</div> +<p>This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is + encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have + multiple matching DIEs in a single file, which could come up with an inlined + function for instance. Future tables could include more information about the + DIE such as flags indicating if the DIE is a function, method, block, + or inlined.</p> + +<p>The KeyType for the DWARF table is a 32 bit string table offset into the + ".debug_str" table. The ".debug_str" is the string table for the DWARF which + may already contain copies of all of the strings. This helps make sure, with + help from the compiler, that we reuse the strings between all of the DWARF + sections and keeps the hash table size down. Another benefit to having the + compiler generate all strings as DW_FORM_strp in the debug info, is that + DWARF parsing can be made much faster.</p> + +<p>After a lookup is made, we get an offset into the hash data. The hash data + needs to be able to deal with 32 bit hash collisions, so the chunk of data + at the offset in the hash data consists of a triple:</p> +<div class="doc_code"> +<pre> +uint32_t str_offset +uint32_t hash_data_count +HashData[hash_data_count] +</pre> +</div> +<p>If "str_offset" is zero, then the bucket contents are done. 99.9% of the + hash data chunks contain a single item (no 32 bit hash collision):</p> +<div class="doc_code"> +<pre> +.------------. +| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main") +| 0x00000004 | uint32_t HashData count +| 0x........ | uint32_t HashData[0] DIE offset +| 0x........ | uint32_t HashData[1] DIE offset +| 0x........ | uint32_t HashData[2] DIE offset +| 0x........ | uint32_t HashData[3] DIE offset +| 0x00000000 | uint32_t KeyType (end of hash chain) +`------------' +</pre> +</div> +<p>If there are collisions, you will have multiple valid string offsets:</p> +<div class="doc_code"> +<pre> +.------------. +| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main") +| 0x00000004 | uint32_t HashData count +| 0x........ | uint32_t HashData[0] DIE offset +| 0x........ | uint32_t HashData[1] DIE offset +| 0x........ | uint32_t HashData[2] DIE offset +| 0x........ | uint32_t HashData[3] DIE offset +| 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print") +| 0x00000002 | uint32_t HashData count +| 0x........ | uint32_t HashData[0] DIE offset +| 0x........ | uint32_t HashData[1] DIE offset +| 0x00000000 | uint32_t KeyType (end of hash chain) +`------------' +</pre> +</div> +<p>Current testing with real world C++ binaries has shown that there is around 1 + 32 bit hash collision per 100,000 name entries.</p> +</div> +<!-- ======================================================================= --> +<h4> + <a name="acceltablecontents">Contents</a> +</h4> +<!-- ======================================================================= --> +<div> +<p>As we said, we want to strictly define exactly what is included in the + different tables. For DWARF, we have 3 tables: ".apple_names", ".apple_types", + and ".apple_namespaces".</p> + +<p>".apple_names" sections should contain an entry for each DWARF DIE whose + DW_TAG is a DW_TAG_label, DW_TAG_inlined_subroutine, or DW_TAG_subprogram that + has address attributes: DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges or + DW_AT_entry_pc. It also contains DW_TAG_variable DIEs that have a DW_OP_addr + in the location (global and static variables). All global and static variables + should be included, including those scoped withing functions and classes. For + example using the following code:</p> +<div class="doc_code"> +<pre> +static int var = 0; + +void f () +{ + static int var = 0; +} +</pre> +</div> +<p>Both of the static "var" variables would be included in the table. All + functions should emit both their full names and their basenames. For C or C++, + the full name is the mangled name (if available) which is usually in the + DW_AT_MIPS_linkage_name attribute, and the DW_AT_name contains the function + basename. If global or static variables have a mangled name in a + DW_AT_MIPS_linkage_name attribute, this should be emitted along with the + simple name found in the DW_AT_name attribute.</p> + +<p>".apple_types" sections should contain an entry for each DWARF DIE whose + tag is one of:</p> +<ul> + <li>DW_TAG_array_type</li> + <li>DW_TAG_class_type</li> + <li>DW_TAG_enumeration_type</li> + <li>DW_TAG_pointer_type</li> + <li>DW_TAG_reference_type</li> + <li>DW_TAG_string_type</li> + <li>DW_TAG_structure_type</li> + <li>DW_TAG_subroutine_type</li> + <li>DW_TAG_typedef</li> + <li>DW_TAG_union_type</li> + <li>DW_TAG_ptr_to_member_type</li> + <li>DW_TAG_set_type</li> + <li>DW_TAG_subrange_type</li> + <li>DW_TAG_base_type</li> + <li>DW_TAG_const_type</li> + <li>DW_TAG_constant</li> + <li>DW_TAG_file_type</li> + <li>DW_TAG_namelist</li> + <li>DW_TAG_packed_type</li> + <li>DW_TAG_volatile_type</li> + <li>DW_TAG_restrict_type</li> + <li>DW_TAG_interface_type</li> + <li>DW_TAG_unspecified_type</li> + <li>DW_TAG_shared_type</li> +</ul> +<p>Only entries with a DW_AT_name attribute are included, and the entry must + not be a forward declaration (DW_AT_declaration attribute with a non-zero value). + For example, using the following code:</p> +<div class="doc_code"> +<pre> +int main () +{ + int *b = 0; + return *b; +} +</pre> +</div> +<p>We get a few type DIEs:</p> +<div class="doc_code"> +<pre> +0x00000067: TAG_base_type [5] + AT_encoding( DW_ATE_signed ) + AT_name( "int" ) + AT_byte_size( 0x04 ) + +0x0000006e: TAG_pointer_type [6] + AT_type( {0x00000067} ( int ) ) + AT_byte_size( 0x08 ) +</pre> +</div> +<p>The DW_TAG_pointer_type is not included because it does not have a DW_AT_name.</p> + +<p>".apple_namespaces" section should contain all DW_TAG_namespace DIEs. If + we run into a namespace that has no name this is an anonymous namespace, + and the name should be output as "(anonymous namespace)" (without the quotes). + Why? This matches the output of the abi::cxa_demangle() that is in the standard + C++ library that demangles mangled names.</p> +</div> + +<!-- ======================================================================= --> +<h4> + <a name="acceltableextensions">Language Extensions and File Format Changes</a> +</h4> +<!-- ======================================================================= --> +<div> +<h5>Objective-C Extensions</h5> +<p>".apple_objc" section should contain all DW_TAG_subprogram DIEs for an + Objective-C class. The name used in the hash table is the name of the + Objective-C class itself. If the Objective-C class has a category, then an + entry is made for both the class name without the category, and for the class + name with the category. So if we have a DIE at offset 0x1234 with a name + of method "-[NSString(my_additions) stringWithSpecialString:]", we would add + an entry for "NSString" that points to DIE 0x1234, and an entry for + "NSString(my_additions)" that points to 0x1234. This allows us to quickly + track down all Objective-C methods for an Objective-C class when doing + expressions. It is needed because of the dynamic nature of Objective-C where + anyone can add methods to a class. The DWARF for Objective-C methods is also + emitted differently from C++ classes where the methods are not usually + contained in the class definition, they are scattered about across one or more + compile units. Categories can also be defined in different shared libraries. + So we need to be able to quickly find all of the methods and class functions + given the Objective-C class name, or quickly find all methods and class + functions for a class + category name. This table does not contain any selector + names, it just maps Objective-C class names (or class names + category) to all + of the methods and class functions. The selectors are added as function + basenames in the .debug_names section.</p> + +<p>In the ".apple_names" section for Objective-C functions, the full name is the + entire function name with the brackets ("-[NSString stringWithCString:]") and the + basename is the selector only ("stringWithCString:").</p> + +<h5>Mach-O Changes</h5> +<p>The sections names for the apple hash tables are for non mach-o files. For + mach-o files, the sections should be contained in the "__DWARF" segment with + names as follows:</p> +<ul> + <li>".apple_names" -> "__apple_names"</li> + <li>".apple_types" -> "__apple_types"</li> + <li>".apple_namespaces" -> "__apple_namespac" (16 character limit)</li> + <li> ".apple_objc" -> "__apple_objc"</li> +</ul> +</div> +</div> +</div> + <!-- *********************************************************************** --> <hr> @@ -1814,7 +2855,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-10-12 00:59:11 +0200 (Wed, 12 Oct 2011) $ + Last modified: $Date: 2012-04-03 02:43:49 +0200 (Tue, 03 Apr 2012) $ </address> </body> diff --git a/docs/SystemLibrary.html b/docs/SystemLibrary.html index 24c4dc5..7cafedf 100644 --- a/docs/SystemLibrary.html +++ b/docs/SystemLibrary.html @@ -310,7 +310,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ </address> </body> </html> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 92b90e6..a211389 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -37,6 +37,7 @@ <ol> <li><a href="#include">File inclusion</a></li> <li><a href="#globallet">'let' expressions</a></li> + <li><a href="#foreach">'foreach' blocks</a></li> </ol></li> </ol></li> <li><a href="#backends">TableGen backends</a> @@ -208,6 +209,14 @@ file, to factor out the common features that instructions of its class share. A key feature of TableGen is that it allows the end-user to define the abstractions they prefer to use when describing their information.</p> +<p>Each def record has a special entry called "NAME." This is the +name of the def ("ADD32rr" above). In the general case def names can +be formed from various kinds of string processing expressions and NAME +resolves to the final value obtained after resolving all of those +expressions. The user may refer to NAME anywhere she desires to use +the ultimate name of the def. NAME should not be defined anywhere +else in user code to avoid conflict problems.</p> + </div> <!-- ======================================================================= --> @@ -393,6 +402,14 @@ which case the user must specify it explicitly.</dd> <dt><tt>list[4-7,17,2-3]</tt></dt> <dd>A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it. Elements may be included multiple times.</dd> +<dt><tt>foreach <var> = <list> in { <body> }</tt></dt> +<dt><tt>foreach <var> = <list> in <def></tt></dt> + <dd> Replicate <body> or <def>, replacing instances of + <var> with each value in <list>. <var> is scoped at the + level of the <tt>foreach</tt> loop and must not conflict with any other object + introduced in <body> or <def>. Currently only <tt>def</tt>s are + expanded within <body>. + </dd> <dt><tt>(DEF a, b)</tt></dt> <dd>a dag value. The first element is required to be a record definition, the remaining elements in the list may be arbitrary other values, including nested @@ -400,6 +417,10 @@ which case the user must specify it explicitly.</dd> <dt><tt>!strconcat(a, b)</tt></dt> <dd>A string value that is the result of concatenating the 'a' and 'b' strings.</dd> +<dt><tt>str1#str2</tt></dt> + <dd>"#" (paste) is a shorthand for !strconcat. It may concatenate + things that are not quoted strings, in which case an implicit + !cast<string> is done on the operand of the paste.</dd> <dt><tt>!cast<type>(a)</tt></dt> <dd>A symbol of type <em>type</em> obtained by looking up the string 'a' in the symbol table. If the type of 'a' does not match <em>type</em>, TableGen @@ -868,6 +889,39 @@ several levels of multiclass instanciations. This also avoids the need of using </pre> </div> +<!-- --------------------------------------------------------------------------> +<h4> + <a name="foreach">Looping</a> +</h4> + +<div> +<p>TableGen supports the '<tt>foreach</tt>' block, which textually replicates +the loop body, substituting iterator values for iterator references in the +body. Example:</p> + +<div class="doc_code"> +<pre> +<b>foreach</b> i = [0, 1, 2, 3] in { + <b>def</b> R#i : Register<...>; + <b>def</b> F#i : Register<...>; +} +</pre> +</div> + +<p>This will create objects <tt>R0</tt>, <tt>R1</tt>, <tt>R2</tt> and +<tt>R3</tt>. <tt>foreach</tt> blocks may be nested. If there is only +one item in the body the braces may be elided:</p> + +<div class="doc_code"> +<pre> +<b>foreach</b> i = [0, 1, 2, 3] in + <b>def</b> R#i : Register<...>; + +</pre> +</div> + +</div> + </div> </div> @@ -912,7 +966,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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> diff --git a/docs/TestSuiteMakefileGuide.html b/docs/TestSuiteMakefileGuide.html new file mode 100644 index 0000000..876fe42 --- /dev/null +++ b/docs/TestSuiteMakefileGuide.html @@ -0,0 +1,351 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title>LLVM test-suite Makefile Guide</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<h1> + LLVM test-suite Makefile Guide +</h1> + +<ol> + <li><a href="#overview">Overview</a></li> + <li><a href="#testsuitestructure">Test suite structure</a></li> + <li><a href="#testsuiterun">Running the test suite</a> + <ul> + <li><a href="#testsuiteexternal">Configuring External Tests</a></li> + <li><a href="#testsuitetests">Running different tests</a></li> + <li><a href="#testsuiteoutput">Generating test output</a></li> + <li><a href="#testsuitecustom">Writing custom tests for test-suite</a></li> + </ul> + </li> +</ol> + +<div class="doc_author"> + <p>Written by John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner</p> +</div> + +<!--=========================================================================--> +<h2><a name="overview">Overview</a></h2> +<!--=========================================================================--> + +<div> + +<p>This document describes the features of the Makefile-based LLVM +test-suite. This way of interacting with the test-suite is deprecated in favor +of running the test-suite using LNT, but may continue to prove useful for some +users. See the Testing +Guide's <a href="TestingGuide.html#testsuitequickstart">test-suite +Quickstart</a> section for more information.</p> + +</div> + +<!--=========================================================================--> +<h2><a name="testsuitestructure">Test suite Structure</a></h2> +<!--=========================================================================--> + +<div> + +<p>The <tt>test-suite</tt> module contains a number of programs that can be compiled +with LLVM and executed. These programs are compiled using the native compiler +and various LLVM backends. The output from the program compiled with the +native compiler is assumed correct; the results from the other programs are +compared to the native program output and pass if they match.</p> + +<p>When executing tests, it is usually a good idea to start out with a subset of +the available tests or programs. This makes test run times smaller at first and +later on this is useful to investigate individual test failures. To run some +test only on a subset of programs, simply change directory to the programs you +want tested and run <tt>gmake</tt> there. Alternatively, you can run a different +test using the <tt>TEST</tt> variable to change what tests or run on the +selected programs (see below for more info).</p> + +<p>In addition for testing correctness, the <tt>test-suite</tt> directory also +performs timing tests of various LLVM optimizations. It also records +compilation times for the compilers and the JIT. This information can be +used to compare the effectiveness of LLVM's optimizations and code +generation.</p> + +<p><tt>test-suite</tt> tests are divided into three types of tests: MultiSource, +SingleSource, and External.</p> + +<ul> +<li><tt>test-suite/SingleSource</tt> +<p>The SingleSource directory contains test programs that are only a single +source file in size. These are usually small benchmark programs or small +programs that calculate a particular value. Several such programs are grouped +together in each directory.</p></li> + +<li><tt>test-suite/MultiSource</tt> +<p>The MultiSource directory contains subdirectories which contain entire +programs with multiple source files. Large benchmarks and whole applications +go here.</p></li> + +<li><tt>test-suite/External</tt> +<p>The External directory contains Makefiles for building code that is external +to (i.e., not distributed with) LLVM. The most prominent members of this +directory are the SPEC 95 and SPEC 2000 benchmark suites. The <tt>External</tt> +directory does not contain these actual tests, but only the Makefiles that know +how to properly compile these programs from somewhere else. The presence and +location of these external programs is configured by the test-suite +<tt>configure</tt> script.</p></li> +</ul> + +<p>Each tree is then subdivided into several categories, including applications, +benchmarks, regression tests, code that is strange grammatically, etc. These +organizations should be relatively self explanatory.</p> + +<p>Some tests are known to fail. Some are bugs that we have not fixed yet; +others are features that we haven't added yet (or may never add). In the +regression tests, the result for such tests will be XFAIL (eXpected FAILure). +In this way, you can tell the difference between an expected and unexpected +failure.</p> + +<p>The tests in the test suite have no such feature at this time. If the +test passes, only warnings and other miscellaneous output will be generated. If +a test fails, a large <program> FAILED message will be displayed. This +will help you separate benign warnings from actual test failures.</p> + +</div> + +<!--=========================================================================--> +<h2><a name="testsuiterun">Running the test suite</a></h2> +<!--=========================================================================--> + +<div> + +<p>First, all tests are executed within the LLVM object directory tree. They +<i>are not</i> executed inside of the LLVM source tree. This is because the +test suite creates temporary files during execution.</p> + +<p>To run the test suite, you need to use the following steps:</p> + +<ol> + <li><tt>cd</tt> into the <tt>llvm/projects</tt> directory in your source tree. + </li> + + <li><p>Check out the <tt>test-suite</tt> module with:</p> + +<div class="doc_code"> +<pre> +% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite +</pre> +</div> + <p>This will get the test suite into <tt>llvm/projects/test-suite</tt>.</p> + </li> + <li><p>Configure and build <tt>llvm</tt>.</p></li> + <li><p>Configure and build <tt>llvm-gcc</tt>.</p></li> + <li><p>Install <tt>llvm-gcc</tt> somewhere.</p></li> + <li><p><em>Re-configure</em> <tt>llvm</tt> from the top level of + each build tree (LLVM object directory tree) in which you want + to run the test suite, just as you do before building LLVM.</p> + <p>During the <em>re-configuration</em>, you must either: (1) + have <tt>llvm-gcc</tt> you just built in your path, or (2) + specify the directory where your just-built <tt>llvm-gcc</tt> is + installed using <tt>--with-llvmgccdir=$LLVM_GCC_DIR</tt>.</p> + <p>You must also tell the configure machinery that the test suite + is available so it can be configured for your build tree:</p> +<div class="doc_code"> +<pre> +% cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure [--with-llvmgccdir=$LLVM_GCC_DIR] +</pre> +</div> + <p>[Remember that <tt>$LLVM_GCC_DIR</tt> is the directory where you + <em>installed</em> llvm-gcc, not its src or obj directory.]</p> + </li> + + <li><p>You can now run the test suite from your build tree as follows:</p> +<div class="doc_code"> +<pre> +% cd $LLVM_OBJ_ROOT/projects/test-suite +% make +</pre> +</div> + </li> +</ol> +<p>Note that the second and third steps only need to be done once. After you +have the suite checked out and configured, you don't need to do it again (unless +the test code or configure script changes).</p> + +<!-- _______________________________________________________________________ --> +<h3> + <a name="testsuiteexternal">Configuring External Tests</a> +</h3> +<!-- _______________________________________________________________________ --> + +<div> +<p>In order to run the External tests in the <tt>test-suite</tt> + module, you must specify <i>--with-externals</i>. This + must be done during the <em>re-configuration</em> step (see above), + and the <tt>llvm</tt> re-configuration must recognize the + previously-built <tt>llvm-gcc</tt>. If any of these is missing or + neglected, the External tests won't work.</p> +<dl> +<dt><i>--with-externals</i></dt> +<dt><i>--with-externals=<<tt>directory</tt>></i></dt> +</dl> + This tells LLVM where to find any external tests. They are expected to be + in specifically named subdirectories of <<tt>directory</tt>>. + If <tt>directory</tt> is left unspecified, + <tt>configure</tt> uses the default value + <tt>/home/vadve/shared/benchmarks/speccpu2000/benchspec</tt>. + Subdirectory names known to LLVM include: + <dl> + <dt>spec95</dt> + <dt>speccpu2000</dt> + <dt>speccpu2006</dt> + <dt>povray31</dt> + </dl> + Others are added from time to time, and can be determined from + <tt>configure</tt>. +</div> + +<!-- _______________________________________________________________________ --> +<h3> + <a name="testsuitetests">Running different tests</a> +</h3> +<!-- _______________________________________________________________________ --> +<div> +<p>In addition to the regular "whole program" tests, the <tt>test-suite</tt> +module also provides a mechanism for compiling the programs in different ways. +If the variable TEST is defined on the <tt>gmake</tt> command line, the test system will +include a Makefile named <tt>TEST.<value of TEST variable>.Makefile</tt>. +This Makefile can modify build rules to yield different results.</p> + +<p>For example, the LLVM nightly tester uses <tt>TEST.nightly.Makefile</tt> to +create the nightly test reports. To run the nightly tests, run <tt>gmake +TEST=nightly</tt>.</p> + +<p>There are several TEST Makefiles available in the tree. Some of them are +designed for internal LLVM research and will not work outside of the LLVM +research group. They may still be valuable, however, as a guide to writing your +own TEST Makefile for any optimization or analysis passes that you develop with +LLVM.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h3> + <a name="testsuiteoutput">Generating test output</a> +</h3> +<!-- _______________________________________________________________________ --> +<div> + <p>There are a number of ways to run the tests and generate output. The most + simple one is simply running <tt>gmake</tt> with no arguments. This will + compile and run all programs in the tree using a number of different methods + and compare results. Any failures are reported in the output, but are likely + drowned in the other output. Passes are not reported explicitely.</p> + + <p>Somewhat better is running <tt>gmake TEST=sometest test</tt>, which runs + the specified test and usually adds per-program summaries to the output + (depending on which sometest you use). For example, the <tt>nightly</tt> test + explicitely outputs TEST-PASS or TEST-FAIL for every test after each program. + Though these lines are still drowned in the output, it's easy to grep the + output logs in the Output directories.</p> + + <p>Even better are the <tt>report</tt> and <tt>report.format</tt> targets + (where <tt>format</tt> is one of <tt>html</tt>, <tt>csv</tt>, <tt>text</tt> or + <tt>graphs</tt>). The exact contents of the report are dependent on which + <tt>TEST</tt> you are running, but the text results are always shown at the + end of the run and the results are always stored in the + <tt>report.<type>.format</tt> file (when running with + <tt>TEST=<type></tt>). + + The <tt>report</tt> also generate a file called + <tt>report.<type>.raw.out</tt> containing the output of the entire test + run. +</div> + +<!-- _______________________________________________________________________ --> +<h3> + <a name="testsuitecustom">Writing custom tests for the test suite</a> +</h3> +<!-- _______________________________________________________________________ --> + +<div> + +<p>Assuming you can run the test suite, (e.g. "<tt>gmake TEST=nightly report</tt>" +should work), it is really easy to run optimizations or code generator +components against every program in the tree, collecting statistics or running +custom checks for correctness. At base, this is how the nightly tester works, +it's just one example of a general framework.</p> + +<p>Lets say that you have an LLVM optimization pass, and you want to see how +many times it triggers. First thing you should do is add an LLVM +<a href="ProgrammersManual.html#Statistic">statistic</a> to your pass, which +will tally counts of things you care about.</p> + +<p>Following this, you can set up a test and a report that collects these and +formats them for easy viewing. This consists of two files, a +"<tt>test-suite/TEST.XXX.Makefile</tt>" fragment (where XXX is the name of your +test) and a "<tt>test-suite/TEST.XXX.report</tt>" file that indicates how to +format the output into a table. There are many example reports of various +levels of sophistication included with the test suite, and the framework is very +general.</p> + +<p>If you are interested in testing an optimization pass, check out the +"libcalls" test as an example. It can be run like this:<p> + +<div class="doc_code"> +<pre> +% cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level +% make TEST=libcalls report +</pre> +</div> + +<p>This will do a bunch of stuff, then eventually print a table like this:</p> + +<div class="doc_code"> +<pre> +Name | total | #exit | +... +FreeBench/analyzer/analyzer | 51 | 6 | +FreeBench/fourinarow/fourinarow | 1 | 1 | +FreeBench/neural/neural | 19 | 9 | +FreeBench/pifft/pifft | 5 | 3 | +MallocBench/cfrac/cfrac | 1 | * | +MallocBench/espresso/espresso | 52 | 12 | +MallocBench/gs/gs | 4 | * | +Prolangs-C/TimberWolfMC/timberwolfmc | 302 | * | +Prolangs-C/agrep/agrep | 33 | 12 | +Prolangs-C/allroots/allroots | * | * | +Prolangs-C/assembler/assembler | 47 | * | +Prolangs-C/bison/mybison | 74 | * | +... +</pre> +</div> + +<p>This basically is grepping the -stats output and displaying it in a table. +You can also use the "TEST=libcalls report.html" target to get the table in HTML +form, similarly for report.csv and report.tex.</p> + +<p>The source for this is in test-suite/TEST.libcalls.*. The format is pretty +simple: the Makefile indicates how to run the test (in this case, +"<tt>opt -simplify-libcalls -stats</tt>"), and the report contains one line for +each column of the output. The first value is the header for the column and the +second is the regex to grep the output of the command for. There are lots of +example reports that can do fancy stuff.</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> + + John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner<br> + <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> +</body> +</html> diff --git a/docs/TestingGuide.html b/docs/TestingGuide.html index eb37142..805ae77 100644 --- a/docs/TestingGuide.html +++ b/docs/TestingGuide.html @@ -18,14 +18,13 @@ <li><a href="#org">LLVM testing infrastructure organization</a> <ul> <li><a href="#regressiontests">Regression tests</a></li> - <li><a href="#testsuite">Test suite</a></li> + <li><a href="#testsuite"><tt>test-suite</tt></a></li> <li><a href="#debuginfotests">Debugging Information tests</a></li> </ul> </li> <li><a href="#quick">Quick start</a> <ul> <li><a href="#quickregressiontests">Regression tests</a></li> - <li><a href="#quicktestsuite">Test suite</a></li> <li><a href="#quickdebuginfotests">Debugging Information tests</a></li> </ul> </li> @@ -37,13 +36,10 @@ <li><a href="#rtfeatures">Other features</a></li> </ul> </li> - <li><a href="#testsuitestructure">Test suite structure</a></li> - <li><a href="#testsuiterun">Running the test suite</a> + <li><a href="#testsuiteoverview"><tt>test-suite</tt> Overview</a> <ul> - <li><a href="#testsuiteexternal">Configuring External Tests</a></li> - <li><a href="#testsuitetests">Running different tests</a></li> - <li><a href="#testsuiteoutput">Generating test output</a></li> - <li><a href="#testsuitecustom">Writing custom tests for test-suite</a></li> + <li><a href="#testsuitequickstart"><tt>test-suite</tt> Quickstart</a></li> + <li><a href="#testsuitemakefiles"><tt>test-suite</tt> Makefiles</a></li> </ul> </li> </ol> @@ -85,10 +81,13 @@ as <a href="http://python.org">Python</a> 2.4 or later.</p> <p>The LLVM testing infrastructure contains two major categories of tests: regression tests and whole programs. The regression tests are contained inside the LLVM repository itself under <tt>llvm/test</tt> and are expected to always -pass -- they should be run before every commit. The whole programs tests are -referred to as the "LLVM test suite" and are in the <tt>test-suite</tt> module -in subversion. -</p> +pass -- they should be run before every commit.</p> + +<p>The whole programs tests are referred to as the "LLVM test suite" (or +"test-suite") and are in the <tt>test-suite</tt> module in subversion. For +historical reasons, these tests are also referred to as the "nightly tests" in +places, which is less ambiguous than "test-suite" and remains in use although we +run them much more often than nightly.</p> <!-- _______________________________________________________________________ --> <h3><a name="regressiontests">Regression tests</a></h3> @@ -118,20 +117,19 @@ application or benchmark.</p> </div> <!-- _______________________________________________________________________ --> -<h3><a name="testsuite">Test suite</a></h3> +<h3><a name="testsuite"><tt>test-suite</tt></a></h3> <!-- _______________________________________________________________________ --> <div> -<p>The test suite contains whole programs, which are pieces of -code which can be compiled and linked into a stand-alone program that can be -executed. These programs are generally written in high level languages such as -C or C++, but sometimes they are written straight in LLVM assembly.</p> +<p>The test suite contains whole programs, which are pieces of code which can be +compiled and linked into a stand-alone program that can be executed. These +programs are generally written in high level languages such as C or C++.</p> -<p>These programs are compiled and then executed using several different -methods (native compiler, LLVM C backend, LLVM JIT, LLVM native code generation, -etc). The output of these programs is compared to ensure that LLVM is compiling -the program correctly.</p> +<p>These programs are compiled using a user specified compiler and set of flags, +and then executed to capture the program output and timing information. The +output of these programs is compared to a reference output to ensure that the +program is being compiled correctly.</p> <p>In addition to compiling and executing programs, whole program tests serve as a way of benchmarking LLVM performance, both in terms of the efficiency of the @@ -168,15 +166,14 @@ test suite for more information . This test suite is located in the <p>The tests are located in two separate Subversion modules. The regressions tests are in the main "llvm" module under the directory - <tt>llvm/test</tt> (so you get these tests for free with the main llvm tree). - The more comprehensive test suite that includes whole -programs in C and C++ is in the <tt>test-suite</tt> module. This module should -be checked out to the <tt>llvm/projects</tt> directory (don't use another name -than the default "test-suite", for then the test suite will be run every time -you run <tt>make</tt> in the main <tt>llvm</tt> directory). -When you <tt>configure</tt> the <tt>llvm</tt> module, -the <tt>test-suite</tt> directory will be automatically configured. -Alternatively, you can configure the <tt>test-suite</tt> module manually.</p> + <tt>llvm/test</tt> (so you get these tests for free with the main llvm + tree). Use "make check-all" to run the regression tests after building + LLVM.</p> + + <p>The more comprehensive test suite that includes whole programs in C and C++ + is in the <tt>test-suite</tt> + module. See <a href="#testsuitequickstart"><tt>test-suite</tt> Quickstart</a> + for more information on running these tests.</p> <!-- _______________________________________________________________________ --> <h3><a name="quickregressiontests">Regression tests</a></h3> @@ -243,60 +240,6 @@ script which is built as part of LLVM. For example, to run the </div> <!-- _______________________________________________________________________ --> -<h3><a name="quicktestsuite">Test suite</a></h3> -<!-- _______________________________________________________________________ --> - -<div> - -<p>To run the comprehensive test suite (tests that compile and execute whole -programs), first checkout and setup the <tt>test-suite</tt> module:</p> - -<div class="doc_code"> -<pre> -% cd llvm/projects -% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite -% cd .. -% ./configure --with-llvmgccdir=$LLVM_GCC_DIR -</pre> -</div> - -<p>where <tt>$LLVM_GCC_DIR</tt> is the directory where -you <em>installed</em> llvm-gcc, not its src or obj -dir. The <tt>--with-llvmgccdir</tt> option assumes that -the <tt>llvm-gcc-4.2</tt> module was configured with -<tt>--program-prefix=llvm-</tt>, and therefore that the C and C++ -compiler drivers are called <tt>llvm-gcc</tt> and <tt>llvm-g++</tt> -respectively. If this is not the case, -use <tt>--with-llvmgcc</tt>/<tt>--with-llvmgxx</tt> to specify each -executable's location.</p> - -<p>Then, run the entire test suite by running make in the <tt>test-suite</tt> -directory:</p> - -<div class="doc_code"> -<pre> -% cd projects/test-suite -% gmake -</pre> -</div> - -<p>Usually, running the "nightly" set of tests is a good idea, and you can also -let it generate a report by running:</p> - -<div class="doc_code"> -<pre> -% cd projects/test-suite -% gmake TEST=nightly report report.html -</pre> -</div> - -<p>Any of the above commands can also be run in a subdirectory of -<tt>projects/test-suite</tt> to run the specified test only on the programs in -that subdirectory.</p> - -</div> - -<!-- _______________________________________________________________________ --> <h3><a name="quickdebuginfotests">Debugging Information tests</a></h3> <div> <!-- _______________________________________________________________________ --> @@ -799,37 +742,10 @@ define two separate CHECK lines that match on the same line. you need multiple temporaries. This is useful as the destination of some redirected output.</dd> - <dt><b>llvmlibsdir</b> (%llvmlibsdir)</dt> - <dd>The directory where the LLVM libraries are located.</dd> - <dt><b>target_triplet</b> (%target_triplet)</dt> <dd>The target triplet that corresponds to the current host machine (the one running the test cases). This should probably be called "host".<dd> - <dt><b>llvmgcc</b> (%llvmgcc)</dt> - <dd>The full path to the <tt>llvm-gcc</tt> executable as specified in the - configured LLVM environment</dd> - - <dt><b>llvmgxx</b> (%llvmgxx)</dt> - <dd>The full path to the <tt>llvm-gxx</tt> executable as specified in the - configured LLVM environment</dd> - - <dt><b>gccpath</b></dt> - <dd>The full path to the C compiler used to <i>build </i> LLVM. Note that - this might not be gcc.</dd> - - <dt><b>gxxpath</b></dt> - <dd>The full path to the C++ compiler used to <i>build </i> LLVM. Note that - this might not be g++.</dd> - - <dt><b>compile_c</b> (%compile_c)</dt> - <dd>The full command line used to compile LLVM C source code. This has all - the configured -I, -D and optimization options.</dd> - - <dt><b>compile_cxx</b> (%compile_cxx)</dt> - <dd>The full command used to compile LLVM C++ source code. This has - all the configured -I, -D and optimization options.</dd> - <dt><b>link</b> (%link)</dt> <dd>This full link command used to link LLVM executables. This has all the configured -I, -L and -l options.</dd> @@ -907,30 +823,15 @@ define two separate CHECK lines that match on the same line. </div> <!--=========================================================================--> -<h2><a name="testsuitestructure">Test suite Structure</a></h2> +<h2><a name="testsuiteoverview"><tt>test-suite</tt> Overview</a></h2> <!--=========================================================================--> <div> -<p>The <tt>test-suite</tt> module contains a number of programs that can be compiled -with LLVM and executed. These programs are compiled using the native compiler -and various LLVM backends. The output from the program compiled with the -native compiler is assumed correct; the results from the other programs are -compared to the native program output and pass if they match.</p> - -<p>When executing tests, it is usually a good idea to start out with a subset of -the available tests or programs. This makes test run times smaller at first and -later on this is useful to investigate individual test failures. To run some -test only on a subset of programs, simply change directory to the programs you -want tested and run <tt>gmake</tt> there. Alternatively, you can run a different -test using the <tt>TEST</tt> variable to change what tests or run on the -selected programs (see below for more info).</p> - -<p>In addition for testing correctness, the <tt>test-suite</tt> directory also -performs timing tests of various LLVM optimizations. It also records -compilation times for the compilers and the JIT. This information can be -used to compare the effectiveness of LLVM's optimizations and code -generation.</p> +<p>The <tt>test-suite</tt> module contains a number of programs that can be +compiled and executed. The <tt>test-suite</tt> includes reference outputs for +all of the programs, so that the output of the executed program can be checked +for correctness.</p> <p><tt>test-suite</tt> tests are divided into three types of tests: MultiSource, SingleSource, and External.</p> @@ -952,248 +853,40 @@ go here.</p></li> to (i.e., not distributed with) LLVM. The most prominent members of this directory are the SPEC 95 and SPEC 2000 benchmark suites. The <tt>External</tt> directory does not contain these actual tests, but only the Makefiles that know -how to properly compile these programs from somewhere else. The presence and -location of these external programs is configured by the test-suite -<tt>configure</tt> script.</p></li> +how to properly compile these programs from somewhere else. When +using <tt>LNT</tt>, use the <tt>--test-externals</tt> option to include these +tests in the results.</p></li> </ul> - -<p>Each tree is then subdivided into several categories, including applications, -benchmarks, regression tests, code that is strange grammatically, etc. These -organizations should be relatively self explanatory.</p> - -<p>Some tests are known to fail. Some are bugs that we have not fixed yet; -others are features that we haven't added yet (or may never add). In the -regression tests, the result for such tests will be XFAIL (eXpected FAILure). -In this way, you can tell the difference between an expected and unexpected -failure.</p> - -<p>The tests in the test suite have no such feature at this time. If the -test passes, only warnings and other miscellaneous output will be generated. If -a test fails, a large <program> FAILED message will be displayed. This -will help you separate benign warnings from actual test failures.</p> - </div> <!--=========================================================================--> -<h2><a name="testsuiterun">Running the test suite</a></h2> +<h2><a name="testsuitequickstart"><tt>test-suite</tt> Quickstart</a></h2> <!--=========================================================================--> <div> +<p>The modern way of running the <tt>test-suite</tt> is focused on testing and +benchmarking complete compilers using +the <a href="http://llvm.org/docs/lnt">LNT</a> testing infrastructure.</p> -<p>First, all tests are executed within the LLVM object directory tree. They -<i>are not</i> executed inside of the LLVM source tree. This is because the -test suite creates temporary files during execution.</p> - -<p>To run the test suite, you need to use the following steps:</p> - -<ol> - <li><tt>cd</tt> into the <tt>llvm/projects</tt> directory in your source tree. - </li> - - <li><p>Check out the <tt>test-suite</tt> module with:</p> - -<div class="doc_code"> -<pre> -% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite -</pre> -</div> - <p>This will get the test suite into <tt>llvm/projects/test-suite</tt>.</p> - </li> - <li><p>Configure and build <tt>llvm</tt>.</p></li> - <li><p>Configure and build <tt>llvm-gcc</tt>.</p></li> - <li><p>Install <tt>llvm-gcc</tt> somewhere.</p></li> - <li><p><em>Re-configure</em> <tt>llvm</tt> from the top level of - each build tree (LLVM object directory tree) in which you want - to run the test suite, just as you do before building LLVM.</p> - <p>During the <em>re-configuration</em>, you must either: (1) - have <tt>llvm-gcc</tt> you just built in your path, or (2) - specify the directory where your just-built <tt>llvm-gcc</tt> is - installed using <tt>--with-llvmgccdir=$LLVM_GCC_DIR</tt>.</p> - <p>You must also tell the configure machinery that the test suite - is available so it can be configured for your build tree:</p> -<div class="doc_code"> -<pre> -% cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure [--with-llvmgccdir=$LLVM_GCC_DIR] -</pre> -</div> - <p>[Remember that <tt>$LLVM_GCC_DIR</tt> is the directory where you - <em>installed</em> llvm-gcc, not its src or obj directory.]</p> - </li> - - <li><p>You can now run the test suite from your build tree as follows:</p> -<div class="doc_code"> -<pre> -% cd $LLVM_OBJ_ROOT/projects/test-suite -% make -</pre> -</div> - </li> -</ol> -<p>Note that the second and third steps only need to be done once. After you -have the suite checked out and configured, you don't need to do it again (unless -the test code or configure script changes).</p> - -<!-- _______________________________________________________________________ --> -<h3> - <a name="testsuiteexternal">Configuring External Tests</a> -</h3> -<!-- _______________________________________________________________________ --> - -<div> -<p>In order to run the External tests in the <tt>test-suite</tt> - module, you must specify <i>--with-externals</i>. This - must be done during the <em>re-configuration</em> step (see above), - and the <tt>llvm</tt> re-configuration must recognize the - previously-built <tt>llvm-gcc</tt>. If any of these is missing or - neglected, the External tests won't work.</p> -<dl> -<dt><i>--with-externals</i></dt> -<dt><i>--with-externals=<<tt>directory</tt>></i></dt> -</dl> - This tells LLVM where to find any external tests. They are expected to be - in specifically named subdirectories of <<tt>directory</tt>>. - If <tt>directory</tt> is left unspecified, - <tt>configure</tt> uses the default value - <tt>/home/vadve/shared/benchmarks/speccpu2000/benchspec</tt>. - Subdirectory names known to LLVM include: - <dl> - <dt>spec95</dt> - <dt>speccpu2000</dt> - <dt>speccpu2006</dt> - <dt>povray31</dt> - </dl> - Others are added from time to time, and can be determined from - <tt>configure</tt>. -</div> - -<!-- _______________________________________________________________________ --> -<h3> - <a name="testsuitetests">Running different tests</a> -</h3> -<!-- _______________________________________________________________________ --> -<div> -<p>In addition to the regular "whole program" tests, the <tt>test-suite</tt> -module also provides a mechanism for compiling the programs in different ways. -If the variable TEST is defined on the <tt>gmake</tt> command line, the test system will -include a Makefile named <tt>TEST.<value of TEST variable>.Makefile</tt>. -This Makefile can modify build rules to yield different results.</p> - -<p>For example, the LLVM nightly tester uses <tt>TEST.nightly.Makefile</tt> to -create the nightly test reports. To run the nightly tests, run <tt>gmake -TEST=nightly</tt>.</p> - -<p>There are several TEST Makefiles available in the tree. Some of them are -designed for internal LLVM research and will not work outside of the LLVM -research group. They may still be valuable, however, as a guide to writing your -own TEST Makefile for any optimization or analysis passes that you develop with -LLVM.</p> - -</div> - -<!-- _______________________________________________________________________ --> -<h3> - <a name="testsuiteoutput">Generating test output</a> -</h3> -<!-- _______________________________________________________________________ --> -<div> - <p>There are a number of ways to run the tests and generate output. The most - simple one is simply running <tt>gmake</tt> with no arguments. This will - compile and run all programs in the tree using a number of different methods - and compare results. Any failures are reported in the output, but are likely - drowned in the other output. Passes are not reported explicitely.</p> - - <p>Somewhat better is running <tt>gmake TEST=sometest test</tt>, which runs - the specified test and usually adds per-program summaries to the output - (depending on which sometest you use). For example, the <tt>nightly</tt> test - explicitely outputs TEST-PASS or TEST-FAIL for every test after each program. - Though these lines are still drowned in the output, it's easy to grep the - output logs in the Output directories.</p> - - <p>Even better are the <tt>report</tt> and <tt>report.format</tt> targets - (where <tt>format</tt> is one of <tt>html</tt>, <tt>csv</tt>, <tt>text</tt> or - <tt>graphs</tt>). The exact contents of the report are dependent on which - <tt>TEST</tt> you are running, but the text results are always shown at the - end of the run and the results are always stored in the - <tt>report.<type>.format</tt> file (when running with - <tt>TEST=<type></tt>). - - The <tt>report</tt> also generate a file called - <tt>report.<type>.raw.out</tt> containing the output of the entire test - run. +<p>For more information on using LNT to execute the <tt>test-suite</tt>, please +see the <a href="http://llvm.org/docs/lnt/quickstart.html">LNT Quickstart</a> +documentation.</p> </div> -<!-- _______________________________________________________________________ --> -<h3> - <a name="testsuitecustom">Writing custom tests for the test suite</a> -</h3> -<!-- _______________________________________________________________________ --> +<!--=========================================================================--> +<h2><a name="testsuitemakefiles"><tt>test-suite</tt> Makefiles</a></h2> +<!--=========================================================================--> <div> +<p>Historically, the <tt>test-suite</tt> was executed using a complicated setup +of Makefiles. The LNT based approach above is recommended for most users, but +there are some testing scenarios which are not supported by the LNT approach. In +addition, LNT currently uses the Makefile setup under the covers and so +developers who are interested in how LNT works under the hood may want to +understand the Makefile based setup.</p> -<p>Assuming you can run the test suite, (e.g. "<tt>gmake TEST=nightly report</tt>" -should work), it is really easy to run optimizations or code generator -components against every program in the tree, collecting statistics or running -custom checks for correctness. At base, this is how the nightly tester works, -it's just one example of a general framework.</p> - -<p>Lets say that you have an LLVM optimization pass, and you want to see how -many times it triggers. First thing you should do is add an LLVM -<a href="ProgrammersManual.html#Statistic">statistic</a> to your pass, which -will tally counts of things you care about.</p> - -<p>Following this, you can set up a test and a report that collects these and -formats them for easy viewing. This consists of two files, a -"<tt>test-suite/TEST.XXX.Makefile</tt>" fragment (where XXX is the name of your -test) and a "<tt>test-suite/TEST.XXX.report</tt>" file that indicates how to -format the output into a table. There are many example reports of various -levels of sophistication included with the test suite, and the framework is very -general.</p> - -<p>If you are interested in testing an optimization pass, check out the -"libcalls" test as an example. It can be run like this:<p> - -<div class="doc_code"> -<pre> -% cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level -% make TEST=libcalls report -</pre> -</div> - -<p>This will do a bunch of stuff, then eventually print a table like this:</p> - -<div class="doc_code"> -<pre> -Name | total | #exit | -... -FreeBench/analyzer/analyzer | 51 | 6 | -FreeBench/fourinarow/fourinarow | 1 | 1 | -FreeBench/neural/neural | 19 | 9 | -FreeBench/pifft/pifft | 5 | 3 | -MallocBench/cfrac/cfrac | 1 | * | -MallocBench/espresso/espresso | 52 | 12 | -MallocBench/gs/gs | 4 | * | -Prolangs-C/TimberWolfMC/timberwolfmc | 302 | * | -Prolangs-C/agrep/agrep | 33 | 12 | -Prolangs-C/allroots/allroots | * | * | -Prolangs-C/assembler/assembler | 47 | * | -Prolangs-C/bison/mybison | 74 | * | -... -</pre> -</div> - -<p>This basically is grepping the -stats output and displaying it in a table. -You can also use the "TEST=libcalls report.html" target to get the table in HTML -form, similarly for report.csv and report.tex.</p> - -<p>The source for this is in test-suite/TEST.libcalls.*. The format is pretty -simple: the Makefile indicates how to run the test (in this case, -"<tt>opt -simplify-libcalls -stats</tt>"), and the report contains one line for -each column of the output. The first value is the header for the column and the -second is the regex to grep the output of the command for. There are lots of -example reports that can do fancy stuff.</p> - -</div> - +<p>For more information on the <tt>test-suite</tt> Makefile setup, please see +the <a href="TestSuiteMakefileGuide.html">Test Suite Makefile Guide.</a></p> </div> <!-- *********************************************************************** --> @@ -1207,7 +900,7 @@ example reports that can do fancy stuff.</p> John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner<br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ </address> </body> </html> diff --git a/docs/UsingLibraries.html b/docs/UsingLibraries.html deleted file mode 100644 index 6c1dd18..0000000 --- a/docs/UsingLibraries.html +++ /dev/null @@ -1,448 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title>Using The LLVM Libraries</title> - <link rel="stylesheet" href="llvm.css" type="text/css"> -</head> -<body> -<h1>Using The LLVM Libraries</h1> -<ol> - <li><a href="#abstract">Abstract</a></li> - <li><a href="#introduction">Introduction</a></li> - <li><a href="#descriptions">Library Descriptions</a></li> - <li><a href="#dependencies">Library Dependencies</a></li> - <li><a href="#rot">Linkage Rules Of Thumb</a> - <ol> - <li><a href="#always">Always link LLVMCore, LLVMSupport, LLVMSystem</a> - <li><a href="#onlyone">Never link both archive and re-linked</a> - </ol> - </li> -</ol> - -<div class="doc_author"> - <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a></p> -</div> - -<p class="doc_warning">Warning: This document is out of date, for more - information please - see <a href="CommandGuide/html/llvm-config.html">llvm-config</a> or, - if you use CMake, <a href="CMake.html#embedding">the CMake LLVM - guide</a>.</p> - -<!-- ======================================================================= --> -<h2><a name="abstract">Abstract</a></h2> -<div> - <p>Amongst other things, LLVM is a toolkit for building compilers, linkers, - runtime executives, virtual machines, and other program execution related - tools. In addition to the LLVM tool set, the functionality of LLVM is - available through a set of libraries. To use LLVM as a toolkit for - constructing tools, a developer needs to understand what is contained in the - various libraries, what they depend on, and how to use them. Fortunately, - there is a tool, <tt>llvm-config</tt> to aid with this. This document - describes the contents of the libraries and how to use <tt>llvm-config</tt> - to generate command line options. -</p> -</div> - -<!-- ======================================================================= --> -<h2><a name="introduction">Introduction</a></h2> -<div> - <p>If you're writing a compiler, virtual machine, or any other utility based - on LLVM, you'll need to figure out which of the many libraries files you will - need to link with to be successful. An understanding of the contents of these - libraries will be useful in coming up with an optimal specification for the - libraries to link with. The purpose of this document is to reduce some of - the trial and error that the author experienced in using LLVM.</p> - <p>LLVM produces two types of libraries: archives (ending in <tt>.a</tt>) and - objects (ending in <tt>.o</tt>). However, both are libraries. Libraries ending - in <tt>.o</tt> are known as re-linked libraries because they contain all the - compilation units of the library linked together as a single <tt>.o</tt> file. - Furthermore, several of the libraries have <em>both</em> forms of library. The - re-linked libraries are used whenever you want to include all symbols from the - library. The archive libraries are used whenever you want to only resolve - outstanding symbols at that point in the link without including everything in - the library. </p> - <p>If you're using the LLVM Makefile system to link your tools,you will use - the <tt>LLVMLIBS</tt> make variable. - (see the <a href="MakefileGuide.html#LLVMLIBS">Makefile Guide</a> for - details). This variable specifies which LLVM libraries to link into your tool - and the order in which they will be linked. You specify re-linked libraries by - naming the library without a suffix. You specify archive libraries by naming - the library with a <tt>.a</tt> suffix but without the <tt>lib</tt> prefix. The - order in which the libraries appear in the <tt>LLVMLIBS</tt> variable - definition is the order in which they will be linked. Getting this order - correct for your tool can sometimes be challenging. -</div> -<!-- ======================================================================= --> -<h2><a name="descriptions">Library Descriptions</a></h2> -<div> - <p>The table below categorizes each library -<table style="text-align:left"> - <tr><th>Library</th><th>Forms</th><th>Description</th></tr> - <tr><th colspan="3">Core Libraries</th></tr> - <tr><td>LLVMArchive</td><td><tt>.a</tt></td> - <td>LLVM archive reading and writing</td></tr> - <tr><td>LLVMAsmParser</td><td><tt>.a</tt></td> - <td>LLVM assembly parsing</td></tr> - <tr><td>LLVMBCReader</td><td><tt>.a</tt></td> - <td>LLVM bitcode reading</td></tr> - <tr><td>LLVMBCWriter</td><td><tt>.a</tt></td> - <td>LLVM bitcode writing</td></tr> - <tr><td>LLVMCore</td><td><tt>.a</tt></td> - <td>LLVM core intermediate representation</td></tr> - <tr><td>LLVMDebugger</td><td><tt>.a</tt></td> - <td>Source level debugging support</td></tr> - <tr><td>LLVMLinker</td><td><tt>.a</tt></td> - <td>Bitcode and archive linking interface</td></tr> - <tr><td>LLVMSupport</td><td><tt>.a</tt></td> - <td>General support utilities</td></tr> - <tr><td>LLVMSystem</td><td><tt>.a</tt></td> - <td>Operating system abstraction layer</td></tr> - <tr><td>LLVMbzip2</td><td><tt>.a</tt></td> - <td>BZip2 compression library</td></tr> - - <tr><th colspan="3">Analysis Libraries</th></tr> - <tr><td>LLVMAnalysis</td><td><tt>.a</tt></td> - <td>Various analysis passes.</td></tr> - <tr><td>LLVMDataStructure</td><td><tt>.o</tt></td> - <td>Data structure analysis passes.</td></tr> - <tr><td>LLVMipa</td><td><tt>.a</tt></td> - <td>Inter-procedural analysis passes.</td></tr> - - <tr><th colspan="3">Transformation Libraries</th></tr> - <tr><td>LLVMInstrumentation</td><td><tt>.a</tt></td> - <td>Instrumentation passes.</td></tr> - <tr><td>LLVMipo</td><td><tt>.a</tt></td> - <td>All inter-procedural optimization passes.</td></tr> - <tr><td>LLVMScalarOpts</td><td><tt>.a</tt></td> - <td>All scalar optimization passes.</td></tr> - <tr><td>LLVMTransformUtils</td><td><tt>.a</tt></td> - <td>Transformation utilities used by many passes.</td></tr> - - <tr><th colspan="3">Code Generation Libraries </th></tr> - <tr><td>LLVMCodeGen</td><td><tt>.o</tt></td> - <td>Native code generation infrastructure</td></tr> - <tr><td>LLVMSelectionDAG</td><td><tt>.o</tt></td> - <td>Aggressive instruction selector for directed acyclic graphs</td></tr> - - <tr><th colspan="3">Target Libraries</th></tr> - <tr><td>LLVMAlpha</td><td><tt>.o</tt></td> - <td>Code generation for Alpha architecture</td></tr> - <tr><td>LLVMARM</td><td><tt>.o</tt></td> - <td>Code generation for ARM architecture</td></tr> - <tr><td>LLVMCBackend</td><td><tt>.o</tt></td> - <td>'C' language code generator.</td></tr> - <tr><td>LLVMPowerPC</td><td><tt>.o</tt></td> - <td>Code generation for PowerPC architecture</td></tr> - <tr><td>LLVMSparc</td><td><tt>.o</tt></td> - <td>Code generation for Sparc architecture</td></tr> - <tr><td>LLVMTarget</td><td><tt>.a</tt></td> - <td>Generic code generation utilities.</td></tr> - <tr><td>LLVMX86</td><td><tt>.o</tt></td> - <td>Code generation for Intel x86 architecture</td></tr> - - <tr><th colspan="3">Runtime Libraries</th></tr> - <tr><td>LLVMInterpreter</td><td><tt>.o</tt></td> - <td>Bitcode Interpreter</td></tr> - <tr><td>LLVMJIT</td><td><tt>.o</tt></td> - <td>Bitcode JIT Compiler</td></tr> - <tr><td>LLVMExecutionEngine</td><td><tt>.o</tt></td> - <td>Virtual machine engine</td></tr> -</table> -</div> - -<!-- ======================================================================= --> -<h2><a name="dependencies">Using llvm-config</a></h2> -<div> - <p>The <tt>llvm-config</tt> tool is a perl script that produces on its output - various kinds of information. For example, the source or object directories - used to build LLVM can be accessed by passing options to <tt>llvm-config</tt>. - For complete details on this tool, please see the - <a href="CommandGuide/html/llvm-config.html">manual page</a>.</p> - <p>To understand the relationships between libraries, the <tt>llvm-config</tt> - can be very useful. If all you know is that you want certain libraries to - be available, you can generate the complete set of libraries to link with - using one of four options, as below:</p> - <ol> - <li><tt>--ldflags</tt>. This generates the command line options necessary to - be passed to the <tt>ld</tt> tool in order to link with LLVM. Most notably, - the <tt>-L</tt> option is provided to specify a library search directory - that contains the LLVM libraries.</li> - <li><tt>--libs</tt>. This generates command line options suitable for - use with a gcc-style linker. That is, libraries are given with a -l option - and object files are given with a full path.</li> - <li><tt>--libnames</tt>. This generates a list of just the library file - names. If you know the directory in which these files reside (see --ldflags) - then you can find the libraries there.</li> - <li><tt>--libfiles</tt>. This generates the full path names of the - LLVM library files.</li> - </ol> - <p>If you wish to delve further into how <tt>llvm-config</tt> generates the - correct order (based on library dependencies), please see the tool named - <tt>GenLibDeps.pl</tt> in the <tt>utils</tt> source directory of LLVM.</p> - - <!-- =======NOTE: =========================================================--> - <!-- === The following graphs and <dl> list are generated automatically ===--> - <!-- === by the util named GenLibDeps.pl in the llvm/utils directory. ===--> - <!-- === This should be updated whenever new libraries are added, ===--> - <!-- === removed, or changed ===--> - <!-- =======NOTE: =========================================================--> - <h3>Dependency Relationships Of Libraries</h3> - <p>This graph shows the dependency of archive libraries on other archive - libraries or objects. Where a library has both archive and object forms, only - the archive form is shown.</p> - <img src="img/libdeps.gif" alt="Library Dependencies"> - <h3>Dependency Relationships Of Object Files</h3> - <p>This graph shows the dependency of object files on archive libraries or - other objects. Where a library has both object and archive forms, only the - dependency to the archive form is shown.</p> - <img src="img/objdeps.gif" alt="Object File Dependencies"> - <p>The following list shows the dependency relationships between libraries in - textual form. The information is the same as shown on the graphs but arranged - alphabetically.</p> -<dl> - <dt><b>libLLVMAnalysis.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>libLLVMArchive.a</b></dt><dd><ul> - <li>libLLVMBCReader.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMAsmParser.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMBCReader.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMBCWriter.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMCodeGen.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMScalarOpts.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMTransformUtils.a</li> - </ul></dd> - <dt><b>libLLVMCore.a</b></dt><dd><ul> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMDebugger.a</b></dt><dd><ul> - <li>libLLVMBCReader.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMInstrumentation.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMScalarOpts.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMTransformUtils.a</li> - </ul></dd> - <dt><b>libLLVMLinker.a</b></dt><dd><ul> - <li>libLLVMArchive.a</li> - <li>libLLVMBCReader.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMScalarOpts.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMTransformUtils.a</li> - </ul></dd> - <dt><b>libLLVMSelectionDAG.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMTransformUtils.a</li> - </ul></dd> - <dt><b>libLLVMSupport.a</b></dt><dd><ul> - <li>libLLVMSystem.a</li> - <li>libLLVMbzip2.a</li> - </ul></dd> - <dt><b>libLLVMSystem.a</b></dt><dd> - </dd> - <dt><b>libLLVMTarget.a</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMTransformUtils.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMipa.a</li> - </ul></dd> - <dt><b>libLLVMbzip2.a</b></dt><dd> - </dd> - <dt><b>libLLVMipa.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - </ul></dd> - <dt><b>libLLVMipo.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMTransformUtils.a</li> - <li>libLLVMipa.a</li> - </ul></dd> - <dt><b>libLLVMlto.a</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMBCReader.a</li> - <li>libLLVMBCWriter.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMLinker.a</li> - <li>libLLVMScalarOpts.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMipa.a</li> - <li>libLLVMipo.a</li> - </ul></dd> - <dt><b>LLVMARM.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMAlpha.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMCBackend.o</b></dt><dd><ul> - <li>libLLVMAnalysis.a</li> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMScalarOpts.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - <li>libLLVMTransformUtils.a</li> - <li>libLLVMipa.a</li> - </ul></dd> - <dt><b>LLVMExecutionEngine.o</b></dt><dd><ul> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMInterpreter.o</b></dt><dd><ul> - <li>LLVMExecutionEngine.o</li> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMJIT.o</b></dt><dd><ul> - <li>LLVMExecutionEngine.o</li> - <li>libLLVMCore.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMPowerPC.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMSparc.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> - <dt><b>LLVMX86.o</b></dt><dd><ul> - <li>libLLVMCodeGen.a</li> - <li>libLLVMCore.a</li> - <li>libLLVMSelectionDAG.a</li> - <li>libLLVMSupport.a</li> - <li>libLLVMSystem.a</li> - <li>libLLVMTarget.a</li> - </ul></dd> -</dl> -</div> - -<!-- ======================================================================= --> -<h2><a name="rot">Linkage Rules Of Thumb</a></h2> -<div> - <p>This section contains various "rules of thumb" about what files you - should link into your programs.</p> -<!-- ======================================================================= --> -<h3> - <a name="always">Always Link LLVMCore, LLVMSupport, and LLVMSystem</a> -</h3> -<div> - <p>No matter what you do with LLVM, the last three entries in the value of - your LLVMLIBS make variable should always be: - <tt>LLVMCore LLVMSupport.a LLVMSystem.a</tt>. There are no <tt>LLVM</tt> - programs that don't depend on these three.</p> -</div> -<!-- ======================================================================= --> -<h3> - <a name="onlyone">Never link both archive and re-linked library</a> -</h3> -<div> - <p>There is never any point to linking both the re-linked (<tt>.o</tt>) and - the archive (<tt>.a</tt>) versions of a library. Since the re-linked version - includes the entire library, the archive version will not resolve any symbols. - You could even end up with link error if you place the archive version before - the re-linked version on the linker's command line.</p> -</div> - -</div> - -<!-- ======================================================================= --> -<hr> -<div class="doc_footer"> -<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:rspencer@x10sys.com">Reid Spencer</a> -</address> -<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> -<br>Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ </div> -</body> -</html> -<!-- vim: sw=2 ts=2 ai ---> diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index dd6f1ec..85548ea 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -77,7 +77,7 @@ either assembly code or binary code (usable for a JIT compiler). <p> The backend of LLVM features a target-independent code generator that may create -output for several types of target CPUs — including X86, PowerPC, Alpha, +output for several types of target CPUs — including X86, PowerPC, ARM, and SPARC. The backend may also be used to generate code targeted at SPUs of the Cell processor or GPUs to support the execution of compute kernels. </p> @@ -2526,7 +2526,7 @@ with assembler. <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a><br> <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> <br> - Last modified: $Date: 2011-06-16 01:28:14 +0200 (Thu, 16 Jun 2011) $ + Last modified: $Date: 2012-03-01 16:14:19 +0100 (Thu, 01 Mar 2012) $ </address> </body> diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index adbd691..5dc67ae 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -417,17 +417,17 @@ USAGE: opt [options] <input bitcode> OPTIONS: Optimizations available: ... - -funcresolve - Resolve Functions - -gcse - Global Common Subexpression Elimination - -globaldce - Dead Global Elimination - <b>-hello - Hello World Pass</b> - -indvars - Canonicalize Induction Variables - -inline - Function Integration/Inlining - -instcombine - Combine redundant instructions + -globalopt - Global Variable Optimizer + -globalsmodref-aa - Simple mod/ref analysis for globals + -gvn - Global Value Numbering + <b>-hello - Hello World Pass</b> + -indvars - Induction Variable Simplification + -inline - Function Integration/Inlining + -insert-edge-profiling - Insert instrumentation for edge profiling ... </pre></div> -<p>The pass name get added as the information string for your pass, giving some +<p>The pass name gets added as the information string for your pass, giving some documentation to users of <tt>opt</tt>. Now that you have a working pass, you would go ahead and make it do the cool transformations you want. Once you get it all working and tested, it may become useful to find out how fast your pass @@ -545,7 +545,7 @@ following signature:</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnModule(Module &M) = 0; +<b>virtual bool</b> runOnModule(Module &M) = 0; </pre></div> <p>The <tt>runOnModule</tt> method performs the interesting work of the pass. @@ -612,7 +612,7 @@ false if they didn't.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doInitialization(CallGraph &CG); +<b>virtual bool</b> doInitialization(CallGraph &CG); </pre></div> <p>The <tt>doIninitialize</tt> method is allowed to do most of the things that @@ -633,7 +633,7 @@ fast).</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnSCC(CallGraphSCC &SCC) = 0; +<b>virtual bool</b> runOnSCC(CallGraphSCC &SCC) = 0; </pre></div> <p>The <tt>runOnSCC</tt> method performs the interesting work of the pass, and @@ -652,7 +652,7 @@ otherwise.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doFinalization(CallGraph &CG); +<b>virtual bool</b> doFinalization(CallGraph &CG); </pre></div> <p>The <tt>doFinalization</tt> method is an infrequently used method that is @@ -704,7 +704,7 @@ should return true if they modified the program, or false if they didn't.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doInitialization(Module &M); +<b>virtual bool</b> doInitialization(Module &M); </pre></div> <p>The <tt>doIninitialize</tt> method is allowed to do most of the things that @@ -732,7 +732,7 @@ free functions that it needs, adding prototypes to the module if necessary.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnFunction(Function &F) = 0; +<b>virtual bool</b> runOnFunction(Function &F) = 0; </pre></div><p> <p>The <tt>runOnFunction</tt> method must be implemented by your subclass to do @@ -751,7 +751,7 @@ be returned if the function is modified.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doFinalization(Module &M); +<b>virtual bool</b> doFinalization(Module &M); </pre></div> <p>The <tt>doFinalization</tt> method is an infrequently used method that is @@ -790,7 +790,7 @@ program, or false if they didn't. </p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM); +<b>virtual bool</b> doInitialization(Loop *, LPPassManager &LPM); </pre></div> <p>The <tt>doInitialization</tt> method is designed to do simple initialization @@ -811,7 +811,7 @@ information.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnLoop(Loop *, LPPassManager &LPM) = 0; +<b>virtual bool</b> runOnLoop(Loop *, LPPassManager &LPM) = 0; </pre></div><p> <p>The <tt>runOnLoop</tt> method must be implemented by your subclass to do @@ -829,7 +829,7 @@ should be used to update loop nest.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doFinalization(); +<b>virtual bool</b> doFinalization(); </pre></div> <p>The <tt>doFinalization</tt> method is an infrequently used method that is @@ -869,7 +869,7 @@ methods should return true if they modified the program, or false if they didn n <div> <div class="doc_code"><pre> - <b>virtual bool</b> doInitialization(Region *, RGPassManager &RGM); +<b>virtual bool</b> doInitialization(Region *, RGPassManager &RGM); </pre></div> <p>The <tt>doInitialization</tt> method is designed to do simple initialization @@ -890,7 +890,7 @@ information.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnRegion(Region *, RGPassManager &RGM) = 0; +<b>virtual bool</b> runOnRegion(Region *, RGPassManager &RGM) = 0; </pre></div><p> <p>The <tt>runOnRegion</tt> method must be implemented by your subclass to do @@ -908,7 +908,7 @@ should be used to update region tree.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doFinalization(); +<b>virtual bool</b> doFinalization(); </pre></div> <p>The <tt>doFinalization</tt> method is an infrequently used method that is @@ -957,7 +957,7 @@ href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the followi <div> <div class="doc_code"><pre> - <b>virtual bool</b> doInitialization(Function &F); +<b>virtual bool</b> doInitialization(Function &F); </pre></div> <p>The <tt>doIninitialize</tt> method is allowed to do most of the things that @@ -978,7 +978,7 @@ fast).</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0; +<b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0; </pre></div> <p>Override this function to do the work of the <tt>BasicBlockPass</tt>. This @@ -998,7 +998,7 @@ if the basic block is modified.</p> <div> <div class="doc_code"><pre> - <b>virtual bool</b> doFinalization(Function &F); +<b>virtual bool</b> doFinalization(Function &F); </pre></div> <p>The <tt>doFinalization</tt> method is an infrequently used method that is @@ -1051,7 +1051,7 @@ data)</li> <div> <div class="doc_code"><pre> - <b>virtual bool</b> runOnMachineFunction(MachineFunction &MF) = 0; +<b>virtual bool</b> runOnMachineFunction(MachineFunction &MF) = 0; </pre></div> <p><tt>runOnMachineFunction</tt> can be considered the main entry point of a @@ -1104,7 +1104,7 @@ implement the virtual <tt>print</tt> method:</p> <div> <div class="doc_code"><pre> - <b>virtual void</b> print(std::ostream &O, <b>const</b> Module *M) <b>const</b>; +<b>virtual void</b> print(std::ostream &O, <b>const</b> Module *M) <b>const</b>; </pre></div> <p>The <tt>print</tt> method must be implemented by "analyses" in order to print @@ -1154,7 +1154,7 @@ having any prerequisite passes, and invalidating <b>all</b> other passes.</p> <div> <div class="doc_code"><pre> - <b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>; +<b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>; </pre></div> <p>By implementing the <tt>getAnalysisUsage</tt> method, the required and @@ -1242,11 +1242,11 @@ the fact that it hacks on the CFG. <div> <div class="doc_code"><pre> - <i>// This example modifies the program, but does not modify the CFG</i> - <b>void</b> <a href="http://llvm.org/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> { - AU.setPreservesCFG(); - AU.addRequired<<a href="http://llvm.org/doxygen/classllvm_1_1LoopInfo.html">LoopInfo</a>>(); - } +<i>// This example modifies the program, but does not modify the CFG</i> +<b>void</b> <a href="http://llvm.org/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> { + AU.setPreservesCFG(); + AU.addRequired<<a href="http://llvm.org/doxygen/classllvm_1_1LoopInfo.html">LoopInfo</a>>(); +} </pre></div> </div> @@ -1268,10 +1268,10 @@ method. It takes a single template argument that specifies which pass class you want, and returns a reference to that pass. For example:</p> <div class="doc_code"><pre> - bool LICM::runOnFunction(Function &F) { - LoopInfo &LI = getAnalysis<LoopInfo>(); - ... - } +bool LICM::runOnFunction(Function &F) { + LoopInfo &LI = getAnalysis<LoopInfo>(); + ... +} </pre></div> <p>This method call returns a reference to the pass desired. You may get a @@ -1285,11 +1285,11 @@ A module level pass can use function level analysis info using this interface. For example:</p> <div class="doc_code"><pre> - bool ModuleLevelPass::runOnModule(Module &M) { - ... - DominatorTree &DT = getAnalysis<DominatorTree>(Func); - ... - } +bool ModuleLevelPass::runOnModule(Module &M) { + ... + DominatorTree &DT = getAnalysis<DominatorTree>(Func); + ... +} </pre></div> <p>In above example, runOnFunction for DominatorTree is called by pass manager @@ -1302,11 +1302,11 @@ If your pass is capable of updating analyses if they exist (e.g., if it is active. For example:</p> <div class="doc_code"><pre> - ... - if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) { - <i>// A DominatorSet is active. This code will update it.</i> - } - ... +... +if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) { + <i>// A DominatorSet is active. This code will update it.</i> +} +... </pre></div> </div> @@ -1405,7 +1405,7 @@ Unlike registration of passes, there is no command line argument to be specified for the Analysis Group Interface itself, because it is "abstract":</p> <div class="doc_code"><pre> - <b>static</b> RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>> A("<i>Alias Analysis</i>"); +<b>static</b> RegisterAnalysisGroup<<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>> A("<i>Alias Analysis</i>"); </pre></div> <p>Once the analysis is registered, passes can declare that they are valid @@ -1416,10 +1416,9 @@ implementations of the interface by using the following code:</p> //<i> Declare that we implement the AliasAnalysis interface</i> INITIALIZE_AG_PASS(FancyAA, <a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, "<i>somefancyaa</i>", "<i>A more complex alias analysis implementation</i>", - false, // <i>Is CFG Only?</i> - true, // <i>Is Analysis?</i> - false, // <i>Is default Analysis Group implementation?</i> - ); + false, // <i>Is CFG Only?</i> + true, // <i>Is Analysis?</i> + false); // <i>Is default Analysis Group implementation?</i> } </pre></div> @@ -1436,8 +1435,7 @@ this macro.</p> "<i>Basic Alias Analysis (default AA impl)</i>", false, // <i>Is CFG Only?</i> true, // <i>Is Analysis?</i> - true, // <i>Is default Analysis Group implementation?</i> - ); + true); // <i>Is default Analysis Group implementation?</i> } </pre></div> @@ -1606,10 +1604,10 @@ we need to add the following <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:</p> <div class="doc_code"><pre> - <i>// We don't modify the program, so we preserve all analyses</i> - <b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> { - AU.setPreservesAll(); - } +<i>// We don't modify the program, so we preserve all analyses</i> +<b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> { + AU.setPreservesAll(); +} </pre></div> <p>Now when we run our pass, we get this output:</p> @@ -1717,19 +1715,19 @@ machine passes. Here we will describe how to <i>register</i> a register allocator machine pass.</p> <p>Implement your register allocator machine pass. In your register allocator -.cpp file add the following include;</p> +<tt>.cpp</tt> file add the following include;</p> <div class="doc_code"><pre> - #include "llvm/CodeGen/RegAllocRegistry.h" +#include "llvm/CodeGen/RegAllocRegistry.h" </pre></div> <p>Also in your register allocator .cpp file, define a creator function in the form; </p> <div class="doc_code"><pre> - FunctionPass *createMyRegisterAllocator() { - return new MyRegisterAllocator(); - } +FunctionPass *createMyRegisterAllocator() { + return new MyRegisterAllocator(); +} </pre></div> <p>Note that the signature of this function should match the type of @@ -1737,9 +1735,9 @@ form; </p> "installing" declaration, in the form;</p> <div class="doc_code"><pre> - static RegisterRegAlloc myRegAlloc("myregalloc", - " my register allocator help string", - createMyRegisterAllocator); +static RegisterRegAlloc myRegAlloc("myregalloc", + "my register allocator help string", + createMyRegisterAllocator); </pre></div> <p>Note the two spaces prior to the help string produces a tidy result on the @@ -1790,11 +1788,11 @@ MachinePassRegistry RegisterMyPasses::Registry; <p>And finally, declare the command line option for your passes. Example:</p> <div class="doc_code"><pre> - cl::opt<RegisterMyPasses::FunctionPassCtor, false, - RegisterPassParser<RegisterMyPasses> > - MyPassOpt("mypass", - cl::init(&createDefaultMyPass), - cl::desc("my pass option help")); +cl::opt<RegisterMyPasses::FunctionPassCtor, false, + RegisterPassParser<RegisterMyPasses> > +MyPassOpt("mypass", + cl::init(&createDefaultMyPass), + cl::desc("my pass option help")); </pre></div> <p>Here the command option is "mypass", with createDefaultMyPass as the default @@ -1949,7 +1947,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-10-11 09:03:52 +0200 (Tue, 11 Oct 2011) $ + Last modified: $Date: 2012-04-08 13:52:52 +0200 (Sun, 08 Apr 2012) $ </address> </body> diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index bc4ab9f..20de077 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -47,7 +47,7 @@ OUTPUT_DIRECTORY = @abs_top_builddir@/docs/doxygen # source files, where putting all generated files in the same directory would # otherwise cause performance problems for the file system. -CREATE_SUBDIRS = YES +CREATE_SUBDIRS = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this diff --git a/docs/doxygen.footer b/docs/doxygen.footer index 15585b8..c492e7d 100644 --- a/docs/doxygen.footer +++ b/docs/doxygen.footer @@ -3,7 +3,7 @@ Generated on $datetime for <a href="http://llvm.org/">$projectname</a> by <a href="http://www.doxygen.org"><img src="doxygen.png" alt="Doxygen" align="middle" border="0"/>$doxygenversion</a><br> -Copyright © 2003-2009 University of Illinois at Urbana-Champaign. +Copyright © 2003-2012 University of Illinois at Urbana-Champaign. All Rights Reserved.</p> <hr> diff --git a/docs/doxygen.header b/docs/doxygen.header index a520434..56fb77f 100644 --- a/docs/doxygen.header +++ b/docs/doxygen.header @@ -2,7 +2,7 @@ <html><head> <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/> <meta name="keywords" content="LLVM,Low Level Virtual Machine,C++,doxygen,API,documentation"/> -<meta name="description" content="C++ source code API documentation for the Low Level Virtual Machine (LLVM)."/> +<meta name="description" content="C++ source code API documentation for LLVM."/> <title>LLVM: $title</title> <link href="doxygen.css" rel="stylesheet" type="text/css"/> </head><body> diff --git a/docs/doxygen.intro b/docs/doxygen.intro index 547730c..699dadc 100644 --- a/docs/doxygen.intro +++ b/docs/doxygen.intro @@ -1,7 +1,7 @@ -/// @mainpage Low Level Virtual Machine +/// @mainpage LLVM /// /// @section main_intro Introduction -/// Welcome to the Low Level Virtual Machine (LLVM). +/// Welcome to LLVM. /// /// This documentation describes the @b internal software that makes /// up LLVM, not the @b external use of LLVM. There are no instructions diff --git a/docs/index.html b/docs/index.html index b17ca03..edd476d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -19,8 +19,9 @@ your documentation.</p> <li><a href="#llvmdesign">LLVM Design</a></li> <li><a href="/pubs/">LLVM Publications</a></li> <li><a href="#userguide">LLVM User Guides</a></li> - <li><a href="#llvmprog">General LLVM Programming Documentation</a></li> + <li><a href="#llvmprog">LLVM Programming Documentation</a></li> <li><a href="#subsystems">LLVM Subsystem Documentation</a></li> + <li><a href="#develprocess">LLVM Development Process Documentation</a></li> <li><a href="#maillist">LLVM Mailing Lists</a></li> </ul> </td><td class="right"> @@ -79,25 +80,7 @@ LLVM for a custom language, and the facilities LLVM offers in tutorial form.</li policy towards developers and their contributions.</li> <li><a href="CommandGuide/index.html">LLVM Command Guide</a> - A reference -manual for the LLVM command line utilities ("man" pages for LLVM tools).<br> -Current tools: - <a href="/cmds/llvm-ar.html">llvm-ar</a>, - <a href="/cmds/llvm-as.html">llvm-as</a>, - <a href="/cmds/llvm-dis.html">llvm-dis</a>, - <a href="/cmds/llvm-extract.html">llvm-extract</a>, - <a href="/cmds/llvm-ld.html">llvm-ld</a>, - <a href="/cmds/llvm-link.html">llvm-link</a>, - <a href="/cmds/llvm-nm.html">llvm-nm</a>, - <a href="/cmds/llvm-prof.html">llvm-prof</a>, - <a href="/cmds/llvm-ranlib.html">llvm-ranlib</a>, - <a href="/cmds/opt.html">opt</a>, - <a href="/cmds/llc.html">llc</a>, - <a href="/cmds/lli.html">lli</a>, - <a href="/cmds/llvmgcc.html">llvm-gcc</a>, - <a href="/cmds/llvmgxx.html">llvm-g++</a>, - <a href="/cmds/bugpoint.html">bugpoint</a>, - <a href="/cmds/llvm-bcanalyzer.html">llvm-bcanalyzer</a>, -</li> +manual for the LLVM command line utilities ("man" pages for LLVM tools).</li> <li><a href="Passes.html">LLVM's Analysis and Transform Passes</a> - A list of optimizations and analyses implemented in LLVM.</li> @@ -115,8 +98,9 @@ the LLVM system.</li> <li><a href="TestingGuide.html">LLVM Testing Infrastructure Guide</a> - A reference manual for using the LLVM testing infrastructure.</li> -<li><a href="GCCFEBuildInstrs.html">How to build the Ada/C/C++/Fortran front-ends</a> - -Instructions for building gcc front-ends from source.</li> +<li><a href="http://clang.llvm.org/get_started.html">How to build the C, C++, ObjC, +and ObjC++ front end</a> - Instructions for building the clang front-end from +source.</li> <li><a href="Packaging.html">Packaging guide</a> - Advice on packaging LLVM into a distribution.</li> @@ -129,11 +113,15 @@ channel</a>. We often are on irc.oftc.net in the #llvm channel. If you are using the mozilla browser, and have chatzilla installed, you can <a href="irc://irc.oftc.net/llvm">join #llvm on irc.oftc.net</a> directly.</li> +<li><a href="HowToAddABuilder.html">How To Add Your Build Configuration +To LLVM Buildbot Infrastructure</a> - Instructions for adding new builder to +LLVM buildbot master.</li> + </ul> <!--=======================================================================--> -<h2><a name="llvmprog">General LLVM Programming Documentation</a></h2> +<h2><a name="llvmprog">LLVM Programming Documentation</a></h2> <!--=======================================================================--> <ul> @@ -144,15 +132,6 @@ intermediate representation and the assembly form of the different nodes.</li> Introduction to the general layout of the LLVM sourcebase, important classes and APIs, and some tips & tricks.</li> -<li><a href="Projects.html">LLVM Project Guide</a> - How-to guide and -templates for new projects that <em>use</em> the LLVM infrastructure. The -templates (directory organization, Makefiles, and test tree) allow the project -code to be located outside (or inside) the <tt>llvm/</tt> tree, while using LLVM -header files and libraries.</li> - -<li><a href="MakefileGuide.html">LLVM Makefile Guide</a> - Describes how the -LLVM makefiles work and how to use them.</li> - <li><a href="CommandLine.html">CommandLine library Reference Manual</a> - Provides information on using the command line parsing library.</li> @@ -163,13 +142,6 @@ efficient C++ code.</li> <li><a href="ExtendingLLVM.html">Extending LLVM</a> - Look here to see how to add instructions and intrinsics to LLVM.</li> -<li><a href="UsingLibraries.html">Using LLVM Libraries</a> - Look here to -understand how to use the libraries produced when LLVM is compiled.</li> - -<li><a href="HowToReleaseLLVM.html">How To Release LLVM To The Public</a> - This -is a guide to preparing LLVM releases. Most developers can ignore it.</li> - - <li><a href="http://llvm.org/doxygen/">Doxygen generated documentation</a> (<a href="http://llvm.org/doxygen/inherits.html">classes</a>) @@ -243,6 +215,29 @@ information about Branch Prediction Information.</li> </ul> +<!--=======================================================================--> +<h2><a name="develprocess">LLVM Development Process Documentation</a></h2> +<!--=======================================================================--> + +<ul> + +<li><a href="Projects.html">LLVM Project Guide</a> - How-to guide and +templates for new projects that <em>use</em> the LLVM infrastructure. The +templates (directory organization, Makefiles, and test tree) allow the project +code to be located outside (or inside) the <tt>llvm/</tt> tree, while using LLVM +header files and libraries.</li> + +<li><a href="LLVMBuild.html">LLVMBuild Documentation</a> - Describes the +LLVMBuild organization and files used by LLVM to specify component +descriptions.</li> + +<li><a href="MakefileGuide.html">LLVM Makefile Guide</a> - Describes how the +LLVM makefiles work and how to use them.</li> + +<li><a href="HowToReleaseLLVM.html">How To Release LLVM To The Public</a> - This +is a guide to preparing LLVM releases. Most developers can ignore it.</li> + +</ul> <!--=======================================================================--> <h2><a name="maillist">LLVM Mailing Lists</a></h2> @@ -286,7 +281,6 @@ 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-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-02-26 23:26:37 +0100 (Sun, 26 Feb 2012) $ </address> </body></html> - diff --git a/docs/tutorial/LangImpl2.html b/docs/tutorial/LangImpl2.html index 2696d86..e4707b3 100644 --- a/docs/tutorial/LangImpl2.html +++ b/docs/tutorial/LangImpl2.html @@ -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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html index c9517a0..9647b43 100644 --- a/docs/tutorial/LangImpl3.html +++ b/docs/tutorial/LangImpl3.html @@ -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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html index e910cc1..06a8a13 100644 --- a/docs/tutorial/LangImpl4.html +++ b/docs/tutorial/LangImpl4.html @@ -1147,7 +1147,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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html index 95144dc..0164ca3 100644 --- a/docs/tutorial/LangImpl5.html +++ b/docs/tutorial/LangImpl5.html @@ -1766,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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html index 8876e83..4fcf109 100644 --- a/docs/tutorial/LangImpl6.html +++ b/docs/tutorial/LangImpl6.html @@ -1823,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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html index 939987b..ebf6514 100644 --- a/docs/tutorial/LangImpl7.html +++ b/docs/tutorial/LangImpl7.html @@ -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-10-16 10:07:38 +0200 (Sun, 16 Oct 2011) $ + Last modified: $Date: 2011-10-16 10:06:54 +0200 (Sun, 16 Oct 2011) $ </address> </body> </html> |
