diff options
Diffstat (limited to 'docs')
36 files changed, 2280 insertions, 722 deletions
diff --git a/docs/AliasAnalysis.html b/docs/AliasAnalysis.html index cffaa8206228e..20b7e96460f30 100644 --- a/docs/AliasAnalysis.html +++ b/docs/AliasAnalysis.html @@ -31,7 +31,7 @@ <li><a href="#chaining"><tt>AliasAnalysis</tt> chaining behavior</a></li> <li><a href="#updating">Updating analysis results for transformations</a></li> <li><a href="#implefficiency">Efficiency Issues</a></li> - <li><a href="#passmanager">Pass Manager Issues</a></li> + <li><a href="#limitations">Limitations</a></li> </ul> </li> @@ -188,7 +188,8 @@ that the accesses alias.</p> <div class="doc_text"> <p>The <tt>alias</tt> method is the primary interface used to determine whether or not two memory objects alias each other. It takes two memory objects as -input and returns MustAlias, MayAlias, or NoAlias as appropriate.</p> +input and returns MustAlias, PartialAlias, MayAlias, or NoAlias as +appropriate.</p> <p>Like all <tt>AliasAnalysis</tt> interfaces, the <tt>alias</tt> method requires that either the two pointer values be defined within the same function, or at @@ -215,8 +216,10 @@ and reallocation.</p> dependencies are ignored.</p> <p>The MayAlias response is used whenever the two pointers might refer to the -same object. If the two memory objects overlap, but do not start at the same -location, return MayAlias.</p> +same object.</p> + +<p>The PartialAlias response is used when the two memory objects are known +to be overlapping in some way, but do not start at the same address.</p> <p>The MustAlias response may only be returned if the two memory objects are guaranteed to always start at exactly the same location. A MustAlias response @@ -461,7 +464,7 @@ analysis results updated to reflect the changes made by these transformations. </p> <p> -The <tt>AliasAnalysis</tt> interface exposes two methods which are used to +The <tt>AliasAnalysis</tt> interface exposes four methods which are used to communicate program changes from the clients to the analysis implementations. Various alias analysis implementations should use these methods to ensure that their internal data structures are kept up-to-date as the program changes (for @@ -502,6 +505,28 @@ value, then deleting the old value. This method cannot be overridden by alias analysis implementations. </div> +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection">The <tt>addEscapingUse</tt> method</div> + +<div class="doc_text"> +<p>The <tt>addEscapingUse</tt> method is used when the uses of a pointer +value have changed in ways that may invalidate precomputed analysis information. +Implementations may either use this callback to provide conservative responses +for points whose uses have change since analysis time, or may recompute some +or all of their internal state to continue providing accurate responses.</p> + +<p>In general, any new use of a pointer value is considered an escaping use, +and must be reported through this callback, <em>except</em> for the +uses below:</p> + +<ul> + <li>A <tt>bitcast</tt> or <tt>getelementptr</tt> of the pointer</li> + <li>A <tt>store</tt> through the pointer (but not a <tt>store</tt> + <em>of</em> the pointer)</li> + <li>A <tt>load</tt> through the pointer</li> +</ul> +</div> + <!-- ======================================================================= --> <div class="doc_subsection"> <a name="implefficiency">Efficiency Issues</a> @@ -520,13 +545,13 @@ method as possible (within reason).</p> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="passmanager">Pass Manager Issues</a> + <a name="limitations">Limitations</a> </div> <div class="doc_text"> -<p>PassManager support for alternative AliasAnalysis implementation -has some issues.</p> +<p>The AliasAnalysis infrastructure has several limitations which make +writing a new <tt>AliasAnalysis</tt> implementation difficult.</p> <p>There is no way to override the default alias analysis. It would be very useful to be able to do something like "opt -my-aa -O2" and @@ -555,6 +580,40 @@ silently route alias analysis queries directly to passes between each pass, which prevents the use of <tt>FunctionPass</tt> alias analysis passes.</p> +<p>The <tt>AliasAnalysis</tt> API does have functions for notifying +implementations when values are deleted or copied, however these +aren't sufficient. There are many other ways that LLVM IR can be +modified which could be relevant to <tt>AliasAnalysis</tt> +implementations which can not be expressed.</p> + +<p>The <tt>AliasAnalysisDebugger</tt> utility seems to suggest that +<tt>AliasAnalysis</tt> implementations can expect that they will be +informed of any relevant <tt>Value</tt> before it appears in an +alias query. However, popular clients such as <tt>GVN</tt> don't +support this, and are known to trigger errors when run with the +<tt>AliasAnalysisDebugger</tt>.</p> + +<p>Due to several of the above limitations, the most obvious use for +the <tt>AliasAnalysisCounter</tt> utility, collecting stats on all +alias queries in a compilation, doesn't work, even if the +<tt>AliasAnalysis</tt> implementations don't use <tt>FunctionPass</tt>. +There's no way to set a default, much less a default sequence, +and there's no way to preserve it.</p> + +<p>The <tt>AliasSetTracker</tt> class (which is used by <tt>LICM</tt> +makes a non-deterministic number of alias queries. This can cause stats +collected by <tt>AliasAnalysisCounter</tt> to have fluctuations among +identical runs, for example. Another consequence is that debugging +techniques involving pausing execution after a predetermined number +of queries can be unreliable.</p> + +<p>Many alias queries can be reformulated in terms of other alias +queries. When multiple <tt>AliasAnalysis</tt> queries are chained together, +it would make sense to start those queries from the beginning of the chain, +with care taken to avoid infinite looping, however currently an +implementation which wants to do this can only start such queries +from itself.</p> + </div> <!-- *********************************************************************** --> @@ -713,8 +772,8 @@ problem.</p> <div class="doc_text"> -<p>The <tt>-basicaa</tt> pass is the default LLVM alias analysis. It is an -aggressive local analysis that "knows" many important facts:</p> +<p>The <tt>-basicaa</tt> pass is an aggressive local analysis that "knows" +many important facts:</p> <ul> <li>Distinct globals, stack allocations, and heap allocations can never @@ -998,7 +1057,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: 2010-08-31 01:47:24 +0200 (Tue, 31 Aug 2010) $ + Last modified: $Date: 2011-01-03 22:38:41 +0100 (Mon, 03 Jan 2011) $ </address> </body> diff --git a/docs/BitCodeFormat.html b/docs/BitCodeFormat.html index bd53a1edd76c1..8d3d382da7a93 100644 --- a/docs/BitCodeFormat.html +++ b/docs/BitCodeFormat.html @@ -922,6 +922,9 @@ encoding of the visibility of this variable: <li><i>threadlocal</i>: If present and non-zero, indicates that the variable is <tt>thread_local</tt></li> +<li><i>unnamed_addr</i>: If present and non-zero, indicates that the variable +has <tt>unnamed_addr<tt></li> + </ul> </div> @@ -975,6 +978,10 @@ entries.</li> <li><i>gc</i>: If present and nonzero, the 1-based garbage collector index in the table of <a href="#MODULE_CODE_GCNAME">MODULE_CODE_GCNAME</a> entries.</li> + +<li><i>unnamed_addr</i>: If present and non-zero, indicates that the function +has <tt>unnamed_addr<tt></li> + </ul> </div> @@ -1474,7 +1481,7 @@ name. Each entry corresponds to a single named type. 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">The LLVM Compiler Infrastructure</a><br> -Last modified: $Date: 2010-08-28 06:09:24 +0200 (Sat, 28 Aug 2010) $ +Last modified: $Date: 2011-01-08 17:42:36 +0100 (Sat, 08 Jan 2011) $ </address> </body> </html> diff --git a/docs/CMake.html b/docs/CMake.html index ca0b50f628e98..e303d132b5902 100644 --- a/docs/CMake.html +++ b/docs/CMake.html @@ -68,7 +68,7 @@ <ol> <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a> - and install CMake. Version 2.6.2 is the minimum required.</p> + and install CMake. Version 2.8 is the minimum required.</p> <li><p>Open a shell. Your development tools must be reachable from this shell through the PATH environment variable.</p> @@ -257,11 +257,41 @@ with a makefile-based system executing <i>make llvm-as</i> on the root of your build directory.</dd> + <dt><b>LLVM_INCLUDE_TOOLS</b>:BOOL</dt> + <dd>Generate build targets for the LLVM tools. Defaults to + ON. You can use that option for disabling the generation of build + targets for the LLVM tools.</dd> + <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt> <dd>Build LLVM examples. Defaults to OFF. Targets for building each example are generated in any case. See documentation for <i>LLVM_BUILD_TOOLS</i> above for more details.</dd> + <dt><b>LLVM_INCLUDE_EXAMPLES</b>:BOOL</dt> + <dd>Generate build targets for the LLVM examples. Defaults to + ON. You can use that option for disabling the generation of build + targets for the LLVM examples.</dd> + + <dt><b>LLVM_BUILD_TESTS</b>:BOOL</dt> + <dd>Build LLVM unit tests. Defaults to OFF. Targets for building + each unit test are generated in any case. You can build a specific + unit test with the target <i>UnitTestNameTests</i> (where at this + time <i>UnitTestName</i> can be ADT, Analysis, ExecutionEngine, + JIT, Support, Transform, VMCore; see the subdirectories + of <i>unittests</i> for an updated list.) It is possible to build + all unit tests with the target <i>UnitTests</i>.</dd> + + <dt><b>LLVM_INCLUDE_TESTS</b>:BOOL</dt> + <dd>Generate build targets for the LLVM unit tests. Defaults to + ON. You can use that option for disabling the generation of build + targets for the LLVM unit tests.</dd> + + <dt><b>LLVM_APPEND_VC_REV</b>:BOOL</dt> + <dd>Append version control revision info (svn revision number or git + revision id) to LLVM version string (stored in the PACKAGE_VERSION + macro). For this to work cmake must be invoked before the + build. Defaults to OFF.</dd> + <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt> <dd>Build with threads support, if available. Defaults to ON.</dd> @@ -301,6 +331,25 @@ <dd>Full path to a native TableGen executable (usually named <i>tblgen</i>). This is intented for cross-compiling: if the user sets this variable, no native TableGen will be created.</dd> + + <dt><b>LLVM_LIT_ARGS</b>:STRING</dt> + <dd>Arguments given to lit. + <tt>make check</tt> and <tt>make clang-test</tt> are affected. + By default, <tt>"-sv --no-progress-bar"</tt> + on Visual C++ and Xcode, + <tt>"-sv"</tt> on others.</dd> + + <dt><b>LLVM_LIT_TOOLS_DIR</b>:STRING</dt> + <dd>The path to GnuWin32 tools for tests. Valid on Windows host. + Defaults to "", then Lit seeks tools according to %PATH%. + Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first, + without specifying GnuWin32 to %PATH%.</dd> + + <dt><b>LLVM_ENABLE_FFI</b>:BOOL</dt> + <dd>Indicates whether LLVM Interpreter will be linked with Foreign + 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> </dl> </div> @@ -321,7 +370,7 @@ <p><tt>make check</tt></p> </div> -<p>Testing is not supported on Visual Studio.</p> +<p>On Visual Studio, you may run tests to build the project "check".</p> </div> diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 4b2e261094bd6..925156ff07872 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -5,6 +5,17 @@ <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>The LLVM Target-Independent Code Generator</title> <link rel="stylesheet" href="llvm.css" type="text/css"> + + <style type="text/css"> + .unknown { background-color: #C0C0C0; text-align: center; } + .unknown:before { content: "?" } + .no { background-color: #C11B17 } + .no:before { content: "N" } + .partial { background-color: #F88017 } + .yes { background-color: #0F0; } + .yes:before { content: "Y" } + </style> + </head> <body> @@ -33,7 +44,7 @@ <li><a href="#targetjitinfo">The <tt>TargetJITInfo</tt> class</a></li> </ul> </li> - <li><a href="#codegendesc">Machine code description classes</a> + <li><a href="#codegendesc">The "Machine" Code Generator classes</a> <ul> <li><a href="#machineinstr">The <tt>MachineInstr</tt> class</a></li> <li><a href="#machinebasicblock">The <tt>MachineBasicBlock</tt> @@ -41,6 +52,15 @@ <li><a href="#machinefunction">The <tt>MachineFunction</tt> class</a></li> </ul> </li> + <li><a href="#mc">The "MC" Layer</a> + <ul> + <li><a href="#mcstreamer">The <tt>MCStreamer</tt> API</a></li> + <li><a href="#mccontext">The <tt>MCContext</tt> class</a> + <li><a href="#mcsymbol">The <tt>MCSymbol</tt> class</a></li> + <li><a href="#mcsection">The <tt>MCSection</tt> class</a></li> + <li><a href="#mcinst">The <tt>MCInst</tt> class</a></li> + </ul> + </li> <li><a href="#codegenalgs">Target-independent code generation algorithms</a> <ul> <li><a href="#instselect">Instruction Selection</a> @@ -76,15 +96,14 @@ <li><a href="#regAlloc_fold">Instruction folding</a></li> <li><a href="#regAlloc_builtIn">Built in register allocators</a></li> </ul></li> - <li><a href="#codeemit">Code Emission</a> - <ul> - <li><a href="#codeemit_asm">Generating Assembly Code</a></li> - <li><a href="#codeemit_bin">Generating Binary Machine Code</a></li> - </ul></li> + <li><a href="#codeemit">Code Emission</a></li> </ul> </li> + <li><a href="#nativeassembler">Implementing a Native Assembler</a></li> + <li><a href="#targetimpls">Target-specific Implementation Notes</a> <ul> + <li><a href="#targetfeatures">Target Feature Matrix</a></li> <li><a href="#tailcallopt">Tail call optimization</a></li> <li><a href="#sibcallopt">Sibling call optimization</a></li> <li><a href="#x86">The X86 backend</a></li> @@ -100,11 +119,7 @@ </ol> <div class="doc_author"> - <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>, - <a href="mailto:isanbard@gmail.com">Bill Wendling</a>, - <a href="mailto:pronesto@gmail.com">Fernando Magno Quintao - Pereira</a> and - <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p> + <p>Written by the LLVM Team.</p> </div> <div class="doc_warning"> @@ -123,7 +138,7 @@ suite of reusable components for translating the LLVM internal representation to the machine code for a specified target—either in assembly form (suitable for a static compiler) or in binary machine code format (usable for - a JIT compiler). The LLVM target-independent code generator consists of five + a JIT compiler). The LLVM target-independent code generator consists of six main components:</p> <ol> @@ -132,10 +147,17 @@ independently of how they will be used. These interfaces are defined in <tt>include/llvm/Target/</tt>.</li> - <li>Classes used to represent the <a href="#codegendesc">machine code</a> - being generated for a target. These classes are intended to be abstract + <li>Classes used to represent the <a href="#codegendesc">code being + generated</a> for a target. These classes are intended to be abstract enough to represent the machine code for <i>any</i> target machine. These - classes are defined in <tt>include/llvm/CodeGen/</tt>.</li> + classes are defined in <tt>include/llvm/CodeGen/</tt>. At this level, + concepts like "constant pool entries" and "jump tables" are explicitly + exposed.</li> + + <li>Classes and algorithms used to represent code as the object file level, + the <a href="#mc">MC Layer</a>. These classes represent assembly level + constructs like labels, sections, and instructions. At this level, + concepts like "constant pool entries" and "jump tables" don't exist.</li> <li><a href="#codegenalgs">Target-independent algorithms</a> used to implement various phases of native code generation (register allocation, scheduling, @@ -732,6 +754,157 @@ ret </div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="mc">The "MC" Layer</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +The MC Layer is used to represent and process code at the raw machine code +level, devoid of "high level" information like "constant pools", "jump tables", +"global variables" or anything like that. At this level, LLVM handles things +like label names, machine instructions, and sections in the object file. The +code in this layer is used for a number of important purposes: the tail end of +the code generator uses it to write a .s or .o file, and it is also used by the +llvm-mc tool to implement standalone machine codeassemblers and disassemblers. +</p> + +<p> +This section describes some of the important classes. There are also a number +of important subsystems that interact at this layer, they are described later +in this manual. +</p> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mcstreamer">The <tt>MCStreamer</tt> API</a> +</div> + +<div class="doc_text"> + +<p> +MCStreamer is best thought of as an assembler API. It is an abstract API which +is <em>implemented</em> in different ways (e.g. to output a .s file, output an +ELF .o file, etc) but whose API correspond directly to what you see in a .s +file. MCStreamer has one method per directive, such as EmitLabel, +EmitSymbolAttribute, SwitchSection, EmitValue (for .byte, .word), etc, which +directly correspond to assembly level directives. It also has an +EmitInstruction method, which is used to output an MCInst to the streamer. +</p> + +<p> +This API is most important for two clients: the llvm-mc stand-alone assembler is +effectively a parser that parses a line, then invokes a method on MCStreamer. In +the code generator, the <a href="#codeemit">Code Emission</a> phase of the code +generator lowers higher level LLVM IR and Machine* constructs down to the MC +layer, emitting directives through MCStreamer.</p> + +<p> +On the implementation side of MCStreamer, there are two major implementations: +one for writing out a .s file (MCAsmStreamer), and one for writing out a .o +file (MCObjectStreamer). MCAsmStreamer is a straight-forward implementation +that prints out a directive for each method (e.g. EmitValue -> .byte), but +MCObjectStreamer implements a full assembler. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mccontext">The <tt>MCContext</tt> class</a> +</div> + +<div class="doc_text"> + +<p> +The MCContext class is the owner of a variety of uniqued data structures at the +MC layer, including symbols, sections, etc. As such, this is the class that you +interact with to create symbols and sections. This class can not be subclassed. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mcsymbol">The <tt>MCSymbol</tt> class</a> +</div> + +<div class="doc_text"> + +<p> +The MCSymbol class represents a symbol (aka label) in the assembly file. There +are two interesting kinds of symbols: assembler temporary symbols, and normal +symbols. Assembler temporary symbols are used and processed by the assembler +but are discarded when the object file is produced. The distinction is usually +represented by adding a prefix to the label, for example "L" labels are +assembler temporary labels in MachO. +</p> + +<p>MCSymbols are created by MCContext and uniqued there. This means that +MCSymbols can be compared for pointer equivalence to find out if they are the +same symbol. Note that pointer inequality does not guarantee the labels will +end up at different addresses though. It's perfectly legal to output something +like this to the .s file:<p> + +<pre> + foo: + bar: + .byte 4 +</pre> + +<p>In this case, both the foo and bar symbols will have the same address.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mcsection">The <tt>MCSection</tt> class</a> +</div> + +<div class="doc_text"> + +<p> +The MCSection class represents an object-file specific section. It is subclassed +by object file specific implementations (e.g. <tt>MCSectionMachO</tt>, +<tt>MCSectionCOFF</tt>, <tt>MCSectionELF</tt>) and these are created and uniqued +by MCContext. The MCStreamer has a notion of the current section, which can be +changed with the SwitchToSection method (which corresponds to a ".section" +directive in a .s file). +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mcinst">The <tt>MCInst</tt> class</a> +</div> + +<div class="doc_text"> + +<p> +The MCInst class is a target-independent representation of an instruction. It +is a simple class (much more so than <a href="#machineinstr">MachineInstr</a>) +that holds a target-specific opcode and a vector of MCOperands. MCOperand, in +turn, is a simple discriminated union of three cases: 1) a simple immediate, +2) a target register ID, 3) a symbolic expression (e.g. "Lfoo-Lbar+42") as an +MCExpr. +</p> + +<p>MCInst is the common currency used to represent machine instructions at the +MC layer. It is the type used by the instruction encoder, the instruction +printer, and the type generated by the assembly parser and disassembler. +</p> + +</div> + + <!-- *********************************************************************** --> <div class="doc_section"> <a name="codegenalgs">Target-independent code generation algorithms</a> @@ -857,9 +1030,9 @@ ret SelectionDAG optimizer is run to clean up redundancies exposed by type legalization.</li> - <li><a href="#selectiondag_legalize">Legalize SelectionDAG Types</a> — - This stage transforms SelectionDAG nodes to eliminate any types that are - unsupported on the target.</li> + <li><a href="#selectiondag_legalize">Legalize SelectionDAG Ops</a> — + This stage transforms SelectionDAG nodes to eliminate any operations + that are unsupported on the target.</li> <li><a href="#selectiondag_optimize">Optimize SelectionDAG</a> — The SelectionDAG optimizer is run to eliminate inefficiencies introduced by @@ -1386,18 +1559,25 @@ bool RegMapping_Fer::compatible_class(MachineFunction &mf, </p> <p>Virtual registers are also denoted by integer numbers. Contrary to physical - registers, different virtual registers never share the same number. The - smallest virtual register is normally assigned the number 1024. This may - change, so, in order to know which is the first virtual register, you should - access <tt>TargetRegisterInfo::FirstVirtualRegister</tt>. Any register whose - number is greater than or equal - to <tt>TargetRegisterInfo::FirstVirtualRegister</tt> is considered a virtual - register. Whereas physical registers are statically defined in - a <tt>TargetRegisterInfo.td</tt> file and cannot be created by the - application developer, that is not the case with virtual registers. In order - to create new virtual registers, use the + registers, different virtual registers never share the same number. Whereas + physical registers are statically defined in a <tt>TargetRegisterInfo.td</tt> + file and cannot be created by the application developer, that is not the case + with virtual registers. In order to create new virtual registers, use the method <tt>MachineRegisterInfo::createVirtualRegister()</tt>. This method - will return a virtual register with the highest code.</p> + will return a new virtual register. Use an <tt>IndexedMap<Foo, + VirtReg2IndexFunctor></tt> to hold information per virtual register. If you + need to enumerate all virtual registers, use the function + <tt>TargetRegisterInfo::index2VirtReg()</tt> to find the virtual register + numbers:</p> + +<div class="doc_code"> +<pre> + for (unsigned i = 0, e = MRI->getNumVirtRegs(); i != e; ++i) { + unsigned VirtReg = TargetRegisterInfo::index2VirtReg(i); + stuff(VirtReg); + } +</pre> +</div> <p>Before register allocation, the operands of an instruction are mostly virtual registers, although physical registers may also be used. In order to check if @@ -1635,25 +1815,228 @@ $ llc -regalloc=pbqp file.bc -o pbqp.s; <a name="latemco">Late Machine Code Optimizations</a> </div> <div class="doc_text"><p>To Be Written</p></div> + <!-- ======================================================================= --> <div class="doc_subsection"> <a name="codeemit">Code Emission</a> </div> -<div class="doc_text"><p>To Be Written</p></div> -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="codeemit_asm">Generating Assembly Code</a> + +<div class="doc_text"> + +<p>The code emission step of code generation is responsible for lowering from +the code generator abstractions (like <a +href="#machinefunction">MachineFunction</a>, <a +href="#machineinstr">MachineInstr</a>, etc) down +to the abstractions used by the MC layer (<a href="#mcinst">MCInst</a>, +<a href="#mcstreamer">MCStreamer</a>, etc). This is +done with a combination of several different classes: the (misnamed) +target-independent AsmPrinter class, target-specific subclasses of AsmPrinter +(such as SparcAsmPrinter), and the TargetLoweringObjectFile class.</p> + +<p>Since the MC layer works at the level of abstraction of object files, it +doesn't have a notion of functions, global variables etc. Instead, it thinks +about labels, directives, and instructions. A key class used at this time is +the MCStreamer class. This is an abstract API that is implemented in different +ways (e.g. to output a .s file, output an ELF .o file, etc) that is effectively +an "assembler API". MCStreamer has one method per directive, such as EmitLabel, +EmitSymbolAttribute, SwitchSection, etc, which directly correspond to assembly +level directives. +</p> + +<p>If you are interested in implementing a code generator for a target, there +are three important things that you have to implement for your target:</p> + +<ol> +<li>First, you need a subclass of AsmPrinter for your target. This class +implements the general lowering process converting MachineFunction's into MC +label constructs. The AsmPrinter base class provides a number of useful methods +and routines, and also allows you to override the lowering process in some +important ways. You should get much of the lowering for free if you are +implementing an ELF, COFF, or MachO target, because the TargetLoweringObjectFile +class implements much of the common logic.</li> + +<li>Second, you need to implement an instruction printer for your target. The +instruction printer takes an <a href="#mcinst">MCInst</a> and renders it to a +raw_ostream as text. Most of this is automatically generated from the .td file +(when you specify something like "<tt>add $dst, $src1, $src2</tt>" in the +instructions), but you need to implement routines to print operands.</li> + +<li>Third, you need to implement code that lowers a <a +href="#machineinstr">MachineInstr</a> to an MCInst, usually implemented in +"<target>MCInstLower.cpp". This lowering process is often target +specific, and is responsible for turning jump table entries, constant pool +indices, global variable addresses, etc into MCLabels as appropriate. This +translation layer is also responsible for expanding pseudo ops used by the code +generator into the actual machine instructions they correspond to. The MCInsts +that are generated by this are fed into the instruction printer or the encoder. +</li> + +</ol> + +<p>Finally, at your choosing, you can also implement an subclass of +MCCodeEmitter which lowers MCInst's into machine code bytes and relocations. +This is important if you want to support direct .o file emission, or would like +to implement an assembler for your target.</p> + </div> + + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="nativeassembler">Implementing a Native Assembler</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>Though you're probably reading this because you want to write or maintain a +compiler backend, LLVM also fully supports building a native assemblers too. +We've tried hard to automate the generation of the assembler from the .td files +(in particular the instruction syntax and encodings), which means that a large +part of the manual and repetitive data entry can be factored and shared with the +compiler.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection" id="na_instparsing">Instruction Parsing</div> + <div class="doc_text"><p>To Be Written</p></div> + + +<!-- ======================================================================= --> +<div class="doc_subsection" id="na_instaliases"> + Instruction Alias Processing +</div> + +<div class="doc_text"> +<p>Once the instruction is parsed, it enters the MatchInstructionImpl function. +The MatchInstructionImpl function performs alias processing and then does +actual matching.</p> + +<p>Alias processing is the phase that canonicalizes different lexical forms of +the same instructions down to one representation. There are several different +kinds of alias that are possible to implement and they are listed below in the +order that they are processed (which is in order from simplest/weakest to most +complex/powerful). Generally you want to use the first alias mechanism that +meets the needs of your instruction, because it will allow a more concise +description.</p> + +</div> + <!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="codeemit_bin">Generating Binary Machine Code</a> +<div class="doc_subsubsection">Mnemonic Aliases</div> + +<div class="doc_text"> + +<p>The first phase of alias processing is simple instruction mnemonic +remapping for classes of instructions which are allowed with two different +mnemonics. This phase is a simple and unconditionally remapping from one input +mnemonic to one output mnemonic. It isn't possible for this form of alias to +look at the operands at all, so the remapping must apply for all forms of a +given mnemonic. Mnemonic aliases are defined simply, for example X86 has: +</p> + +<div class="doc_code"> +<pre> +def : MnemonicAlias<"cbw", "cbtw">; +def : MnemonicAlias<"smovq", "movsq">; +def : MnemonicAlias<"fldcww", "fldcw">; +def : MnemonicAlias<"fucompi", "fucomip">; +def : MnemonicAlias<"ud2a", "ud2">; +</pre> +</div> + +<p>... and many others. With a MnemonicAlias definition, the mnemonic is +remapped simply and directly. Though MnemonicAlias's can't look at any aspect +of the instruction (such as the operands) they can depend on global modes (the +same ones supported by the matcher), through a Requires clause:</p> + +<div class="doc_code"> +<pre> +def : MnemonicAlias<"pushf", "pushfq">, Requires<[In64BitMode]>; +def : MnemonicAlias<"pushf", "pushfl">, Requires<[In32BitMode]>; +</pre> </div> +<p>In this example, the mnemonic gets mapped into different a new one depending +on the current instruction set.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection">Instruction Aliases</div> + <div class="doc_text"> - <p>For the JIT or <tt>.o</tt> file writer</p> + +<p>The most general phase of alias processing occurs while matching is +happening: it provides new forms for the matcher to match along with a specific +instruction to generate. An instruction alias has two parts: the string to +match and the instruction to generate. For example: +</p> + +<div class="doc_code"> +<pre> +def : InstAlias<"movsx $src, $dst", (MOVSX16rr8W GR16:$dst, GR8 :$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX16rm8W GR16:$dst, i8mem:$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX32rr8 GR32:$dst, GR8 :$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX32rr16 GR32:$dst, GR16 :$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX64rr8 GR64:$dst, GR8 :$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX64rr16 GR64:$dst, GR16 :$src)>; +def : InstAlias<"movsx $src, $dst", (MOVSX64rr32 GR64:$dst, GR32 :$src)>; +</pre> </div> +<p>This shows a powerful example of the instruction aliases, matching the +same mnemonic in multiple different ways depending on what operands are present +in the assembly. The result of instruction aliases can include operands in a +different order than the destination instruction, and can use an input +multiple times, for example:</p> + +<div class="doc_code"> +<pre> +def : InstAlias<"clrb $reg", (XOR8rr GR8 :$reg, GR8 :$reg)>; +def : InstAlias<"clrw $reg", (XOR16rr GR16:$reg, GR16:$reg)>; +def : InstAlias<"clrl $reg", (XOR32rr GR32:$reg, GR32:$reg)>; +def : InstAlias<"clrq $reg", (XOR64rr GR64:$reg, GR64:$reg)>; +</pre> +</div> + +<p>This example also shows that tied operands are only listed once. In the X86 +backend, XOR8rr has two input GR8's and one output GR8 (where an input is tied +to the output). InstAliases take a flattened operand list without duplicates +for tied operands. The result of an instruction alias can also use immediates +and fixed physical registers which are added as simple immediate operands in the +result, for example:</p> + +<div class="doc_code"> +<pre> +// Fixed Immediate operand. +def : InstAlias<"aad", (AAD8i8 10)>; + +// Fixed register operand. +def : InstAlias<"fcomi", (COM_FIr ST1)>; + +// Simple alias. +def : InstAlias<"fcomi $reg", (COM_FIr RST:$reg)>; +</pre> +</div> + + +<p>Instruction aliases can also have a Requires clause to make them +subtarget specific.</p> + +</div> + + + +<!-- ======================================================================= --> +<div class="doc_subsection" id="na_matching">Instruction Matching</div> + +<div class="doc_text"><p>To Be Written</p></div> + + + <!-- *********************************************************************** --> <div class="doc_section"> @@ -1664,10 +2047,275 @@ $ llc -regalloc=pbqp file.bc -o pbqp.s; <div class="doc_text"> <p>This section of the document explains features or design decisions that are - specific to the code generator for a particular target.</p> + specific to the code generator for a particular target. First we start + with a table that summarizes what features are supported by each target.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="targetfeatures">Target Feature Matrix</a> +</div> + +<div class="doc_text"> + +<p>Note that this table does not include the C backend or Cpp backends, since +they do not use the target independent code generator infrastructure. It also +doesn't list features that are not supported fully by any target yet. It +considers a feature to be supported if at least one subtarget supports it. A +feature being supported means that it is useful and works for most cases, it +does not indicate that there are zero known bugs in the implementation. Here +is the key:</p> + + +<table border="1" cellspacing="0"> + <tr> + <th>Unknown</th> + <th>No support</th> + <th>Partial Support</th> + <th>Complete Support</th> + </tr> + <tr> + <td class="unknown"></td> + <td class="no"></td> + <td class="partial"></td> + <td class="yes"></td> + </tr> +</table> + +<p>Here is the table:</p> + +<table width="689" border="1" cellspacing="0"> +<tr><td></td> +<td colspan="13" align="center" style="background-color:#ffc">Target</td> +</tr> + <tr> + <th>Feature</th> + <th>ARM</th> + <th>Alpha</th> + <th>Blackfin</th> + <th>CellSPU</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> + +<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="no"></td> <!-- MBlaze --> + <td class="unknown"></td> <!-- MSP430 --> + <td class="no"></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> + +<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="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> + +<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="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> + +<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> <!-- 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"><a href="#feat_inlineasm_x86">*</a></td> <!-- X86 --> + <td class="unknown"></td> <!-- XCore --> +</tr> + +<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> <!-- 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_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="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> + +<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="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> + + +</table> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_reliable">Is Generally Reliable</div> + +<div class="doc_text"> +<p>This box indicates whether the target is considered to be production quality. +This indicates that the target has been used as a static compiler to +compile large amounts of code by a variety of different people and is in +continuous use.</p> +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_asmparser">Assembly Parser</div> + +<div class="doc_text"> +<p>This box indicates whether the target supports parsing target specific .s +files by implementing the MCAsmParser interface. This is required for llvm-mc +to be able to act as a native assembler and is required for inline assembly +support in the native .o file writer.</p> </div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_disassembler">Disassembler</div> + +<div class="doc_text"> +<p>This box indicates whether the target supports the MCDisassembler API for +disassembling machine opcode bytes into MCInst's.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_inlineasm">Inline Asm</div> + +<div class="doc_text"> +<p>This box indicates whether the target supports most popular inline assembly +constraints and modifiers.</p> + +<p id="feat_inlineasm_x86">X86 lacks reliable support for inline assembly +constraints relating to the X86 floating point stack.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_jit">JIT Support</div> + +<div class="doc_text"> +<p>This box indicates whether the target supports the JIT compiler through +the ExecutionEngine interface.</p> + +<p id="feat_jit_arm">The ARM backend has basic support for integer code +in ARM codegen mode, but lacks NEON and full Thumb support.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_objectwrite">.o File Writing</div> + +<div class="doc_text"> + +<p>This box indicates whether the target supports writing .o files (e.g. MachO, +ELF, and/or COFF) files directly from the target. Note that the target also +must include an assembly parser and general inline assembly support for full +inline assembly support in the .o writer.</p> + +<p>Targets that don't support this feature can obviously still write out .o +files, they just rely on having an external assembler to translate from a .s +file to a .o file (as is the case for many C compilers).</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection" id="feat_tailcall">Tail Calls</div> + +<div class="doc_text"> + +<p>This box indicates whether the target supports guaranteed tail calls. These +are calls marked "<a href="LangRef.html#i_call">tail</a>" and use the fastcc +calling convention. Please see the <a href="#tailcallopt">tail call section +more more details</a>.</p> + +</div> + + + + <!-- ======================================================================= --> <div class="doc_subsection"> <a name="tailcallopt">Tail call optimization</a> @@ -2162,7 +2810,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: 2010-09-01 00:01:07 +0200 (Wed, 01 Sep 2010) $ + Last modified: $Date: 2011-01-09 00:10:59 +0100 (Sun, 09 Jan 2011) $ </address> </body> diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index bb88a91772aaf..4a9ab7d857a8e 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -29,37 +29,39 @@ <li><a href="#ci_warningerrors">Treat Compiler Warnings Like Errors</a></li> <li><a href="#ci_portable_code">Write Portable Code</a></li> - <li><a href="#ci_class_struct">Use of class/struct Keywords</a></li> + <li><a href="#ci_rtti_exceptions">Do not use RTTI or Exceptions</a></li> + <li><a href="#ci_class_struct">Use of <tt>class</tt>/<tt>struct</tt> Keywords</a></li> </ol></li> </ol></li> <li><a href="#styleissues">Style Issues</a> <ol> - <li><a href="#macro">The High Level Issues</a> + <li><a href="#macro">The High-Level Issues</a> <ol> <li><a href="#hl_module">A Public Header File <b>is</b> a Module</a></li> - <li><a href="#hl_dontinclude">#include as Little as Possible</a></li> + <li><a href="#hl_dontinclude"><tt>#include</tt> as Little as Possible</a></li> <li><a href="#hl_privateheaders">Keep "internal" Headers Private</a></li> - <li><a href="#hl_earlyexit">Use Early Exits and 'continue' to Simplify + <li><a href="#hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a></li> - <li><a href="#hl_else_after_return">Don't use "else" after a - return</a></li> + <li><a href="#hl_else_after_return">Don't use <tt>else</tt> after a + <tt>return</tt></a></li> <li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate Functions</a></li> </ol></li> - <li><a href="#micro">The Low Level Issues</a> + <li><a href="#micro">The Low-Level Issues</a> <ol> + <li><a href="#ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a></li> <li><a href="#ll_assert">Assert Liberally</a></li> - <li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li> + <li><a href="#ll_ns_std">Do not use '<tt>using namespace std</tt>'</a></li> <li><a href="#ll_virtual_anch">Provide a virtual method anchor for classes in headers</a></li> - <li><a href="#ll_end">Don't evaluate end() every time through a + <li><a href="#ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a></li> <li><a href="#ll_iostream"><tt>#include <iostream></tt> is <em>forbidden</em></a></li> + <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a></li> <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li> - <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a</li> </ol></li> <li><a href="#nano">Microscopic Details</a> @@ -167,8 +169,8 @@ this:</p> <p>A few things to note about this particular format: The "<tt>-*- C++ -*-</tt>" string on the first line is there to tell Emacs that the source file -is a C++ file, not a C file (Emacs assumes .h files are C files by default). -Note that this tag is not necessary in .cpp files. The name of the file is also +is a C++ file, not a C file (Emacs assumes <tt>.h</tt> files are C files by default). +Note that this tag is not necessary in <tt>.cpp</tt> files. The name of the file is also on the first line, along with a very short description of the purpose of the file. This is important when printing out code and flipping though lots of pages.</p> @@ -217,7 +219,7 @@ require less typing, don't have nesting problems, etc. There are a few cases when it is useful to use C style (<tt>/* */</tt>) comments however:</p> <ol> - <li>When writing a C code: Obviously if you are writing C code, use C style + <li>When writing C code: Obviously if you are writing C code, use C style comments.</li> <li>When writing a header file that may be <tt>#include</tt>d by a C source file.</li> @@ -244,12 +246,12 @@ file should be listed. We prefer these <tt>#include</tt>s to be listed in this order:</p> <ol> - <li><a href="#mmheader">Main Module header</a></li> + <li><a href="#mmheader">Main Module Header</a></li> <li><a href="#hl_privateheaders">Local/Private Headers</a></li> <li><tt>llvm/*</tt></li> <li><tt>llvm/Analysis/*</tt></li> <li><tt>llvm/Assembly/*</tt></li> - <li><tt>llvm/Bytecode/*</tt></li> + <li><tt>llvm/Bitcode/*</tt></li> <li><tt>llvm/CodeGen/*</tt></li> <li>...</li> <li><tt>Support/*</tt></li> @@ -257,15 +259,15 @@ order:</p> <li>System <tt>#includes</tt></li> </ol> -<p>... and each category should be sorted by name.</p> +<p>and each category should be sorted by name.</p> -<p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file -which implement an interface defined by a .h file. This <tt>#include</tt> +<p><a name="mmheader">The "Main Module Header"</a> file applies to <tt>.cpp</tt> files +which implement an interface defined by a <tt>.h</tt> file. This <tt>#include</tt> should always be included <b>first</b> regardless of where it lives on the file -system. By including a header file first in the .cpp files that implement the +system. By including a header file first in the <tt>.cpp</tt> files that implement the interfaces, we ensure that the header does not have any hidden dependencies which are not explicitly #included in the header, but should be. It is also a -form of documentation in the .cpp file to indicate where the interfaces it +form of documentation in the <tt>.cpp</tt> file to indicate where the interfaces it implements are defined.</p> </div> @@ -290,7 +292,7 @@ value and would be detrimental to printing out code. Also many other projects have standardized on 80 columns, so some people have already configured their editors for it (vs something else, like 90 columns).</p> -<p>This is one of many contentious issues in coding standards, but is not up +<p>This is one of many contentious issues in coding standards, but it is not up for debate.</p> </div> @@ -304,12 +306,12 @@ for debate.</p> <p>In all cases, prefer spaces to tabs in source files. People have different preferred indentation levels, and different styles of indentation that they -like... this is fine. What isn't is that different editors/viewers expand tabs -out to different tab stops. This can cause your code to look completely +like; this is fine. What isn't fine is that different editors/viewers expand +tabs out to different tab stops. This can cause your code to look completely unreadable, and it is not worth dealing with.</p> <p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the -style of existing code if your are modifying and extending it. If you like four +style of existing code if you are modifying and extending it. If you like four spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code with two spaces of indentation. Also, do not reindent a whole source file: it makes for incredible diffs that are absolutely worthless.</p> @@ -323,7 +325,7 @@ makes for incredible diffs that are absolutely worthless.</p> <div class="doc_text"> -<p>Okay, your first year of programming you were told that indentation is +<p>Okay, in your first year of programming you were told that indentation is important. If you didn't believe and internalize this then, now is the time. Just do it.</p> @@ -343,17 +345,17 @@ Just do it.</p> <div class="doc_text"> -<p>If your code has compiler warnings in it, something is wrong: you aren't -casting values correctly, your have "questionable" constructs in your code, or -you are doing something legitimately wrong. Compiler warnings can cover up -legitimate errors in output and make dealing with a translation unit +<p>If your code has compiler warnings in it, something is wrong — you +aren't casting values correctly, your have "questionable" constructs in your +code, or you are doing something legitimately wrong. Compiler warnings can +cover up legitimate errors in output and make dealing with a translation unit difficult.</p> <p>It is not possible to prevent all warnings from all compilers, nor is it desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides -a good thorough set of warnings, and stick to them. At least in the case of +a good thorough set of warnings, and stick to it. At least in the case of <tt>gcc</tt>, it is possible to work around any spurious errors by changing the -syntax of the code slightly. For example, an warning that annoys me occurs when +syntax of the code slightly. For example, a warning that annoys me occurs when I write code like this:</p> <div class="doc_code"> @@ -377,11 +379,16 @@ if ((V = getValue())) { </pre> </div> -<p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can +<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: <tt>-Wall --Winline -W -Wwrite-strings -Wno-unused</tt></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> @@ -397,9 +404,31 @@ portable code. If there are cases where it isn't possible to write portable code, isolate it behind a well defined (and well documented) interface.</p> <p>In practice, this means that you shouldn't assume much about the host -compiler, including its support for "high tech" features like partial -specialization of templates. If these features are used, they should only be -an implementation detail of a library which has a simple exposed API.</p> +compiler, and Visual Studio tends to be the lowest common denominator. +If advanced features are used, they should only be an implementation detail of +a library which has a simple exposed API, and preferably be buried in +libSystem.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> +<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a> +</div> +<div class="doc_text"> + +<p>In an effort to reduce code and executable size, LLVM does not use RTTI +(e.g. <tt>dynamic_cast<></tt>) or exceptions. These two language features +violate the general C++ principle of <i>"you only pay for what you use"</i>, +causing executable bloat even if exceptions are never used in the code base, or +if RTTI is never used for a class. Because of this, we turn them off globally +in the code.</p> + +<p>That said, LLVM does make extensive use of a hand-rolled form of RTTI that +use templates like <a href="ProgrammersManual.html#isa"><tt>isa<></tt>, +<tt>cast<></tt>, and <tt>dyn_cast<></tt></a>. This form of RTTI is +opt-in and can be added to any class. It is also substantially more efficient +than <tt>dynamic_cast<></tt>.</p> </div> @@ -419,8 +448,9 @@ different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to declare the symbol. This can lead to problems at link time.</p> <p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless -<b>all</b> members are public and the type is a C++ "POD" type, in which case -<tt>struct</tt> is allowed.</p> +<b>all</b> members are public and the type is a C++ +<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">POD</a> type, in +which case <tt>struct</tt> is allowed.</p> </div> @@ -433,7 +463,7 @@ declare the symbol. This can lead to problems at link time.</p> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="macro">The High Level Issues</a> + <a name="macro">The High-Level Issues</a> </div> <!-- ======================================================================= --> @@ -448,20 +478,20 @@ declare the symbol. This can lead to problems at link time.</p> <p>C++ doesn't do too well in the modularity department. There is no real encapsulation or data hiding (unless you use expensive protocol classes), but it is what we have to work with. When you write a public header file (in the LLVM -source tree, they live in the top level "include" directory), you are defining a -module of functionality.</p> +source tree, they live in the top level "<tt>include</tt>" directory), you are +defining a module of functionality.</p> <p>Ideally, modules should be completely independent of each other, and their -header files should only include the absolute minimum number of headers -possible. A module is not just a class, a function, or a namespace: <a -href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection -of these</a> that defines an interface. This interface may be several -functions, classes or data structures, but the important issue is how they work -together.</p> - -<p>In general, a module should be implemented with one or more <tt>.cpp</tt> +header files should only <tt>#include</tt> the absolute minimum number of +headers possible. A module is not just a class, a function, or a +namespace: <a href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's +a collection of these</a> that defines an interface. This interface may be +several functions, classes, or data structures, but the important issue is how +they work together.</p> + +<p>In general, a module should be implemented by one or more <tt>.cpp</tt> files. Each of these <tt>.cpp</tt> files should include the header that defines -their interface first. This ensure that all of the dependences of the module +their interface first. This ensures that all of the dependences of the module header have been properly added to the module header itself, and are not implicit. System headers should be included after user headers for a translation unit.</p> @@ -478,29 +508,28 @@ translation unit.</p> <p><tt>#include</tt> hurts compile time performance. Don't do it unless you have to, especially in header files.</p> -<p>But wait, sometimes you need to have the definition of a class to use it, or +<p>But wait! Sometimes you need to have the definition of a class to use it, or to inherit from it. In these cases go ahead and <tt>#include</tt> that header file. Be aware however that there are many cases where you don't need to have the full definition of a class. If you are using a pointer or reference to a class, you don't need the header file. If you are simply returning a class instance from a prototyped function or method, you don't need it. In fact, for -most cases, you simply don't need the definition of a class... and not +most cases, you simply don't need the definition of a class. And not <tt>#include</tt>'ing speeds up compilation.</p> <p>It is easy to try to go too overboard on this recommendation, however. You -<b>must</b> include all of the header files that you are using -- you can -include them either directly -or indirectly (through another header file). To make sure that you don't -accidentally forget to include a header file in your module header, make sure to -include your module header <b>first</b> in the implementation file (as mentioned -above). This way there won't be any hidden dependencies that you'll find out -about later...</p> +<b>must</b> include all of the header files that you are using — you can +include them either directly or indirectly (through another header file). To +make sure that you don't accidentally forget to include a header file in your +module header, make sure to include your module header <b>first</b> in the +implementation file (as mentioned above). This way there won't be any hidden +dependencies that you'll find out about later.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="hl_privateheaders">Keep "internal" Headers Private</a> + <a name="hl_privateheaders">Keep "Internal" Headers Private</a> </div> <div class="doc_text"> @@ -508,20 +537,20 @@ about later...</p> <p>Many modules have a complex implementation that causes them to use more than one implementation (<tt>.cpp</tt>) file. It is often tempting to put the internal communication interface (helper classes, extra functions, etc) in the -public module header file. Don't do this.</p> +public module header file. Don't do this!</p> <p>If you really need to do something like this, put a private header file in the same directory as the source files, and include it locally. This ensures that your private interface remains private and undisturbed by outsiders.</p> -<p>Note however, that it's okay to put extra implementation methods a public -class itself... just make them private (or protected), and all is well.</p> +<p>Note however, that it's okay to put extra implementation methods in a public +class itself. Just make them private (or protected) and all is well.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="hl_earlyexit">Use Early Exits and 'continue' to Simplify Code</a> + <a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a> </div> <div class="doc_text"> @@ -530,8 +559,8 @@ class itself... just make them private (or protected), and all is well.</p> decisions have to be remembered by the reader to understand a block of code. Aim to reduce indentation where possible when it doesn't make it more difficult to understand the code. One great way to do this is by making use of early -exits and the 'continue' keyword in long loops. As an example of using an early -exit from a function, consider this "bad" code:</p> +exits and the <tt>continue</tt> keyword in long loops. As an example of using +an early exit from a function, consider this "bad" code:</p> <div class="doc_code"> <pre> @@ -546,23 +575,23 @@ Value *DoSomething(Instruction *I) { </pre> </div> -<p>This code has several problems if the body of the 'if' is large. When you're -looking at the top of the function, it isn't immediately clear that this -<em>only</em> does interesting things with non-terminator instructions, and only -applies to things with the other predicates. Second, it is relatively difficult -to describe (in comments) why these predicates are important because the if -statement makes it difficult to lay out the comments. Third, when you're deep -within the body of the code, it is indented an extra level. Finally, when -reading the top of the function, it isn't clear what the result is if the -predicate isn't true, you have to read to the end of the function to know that -it returns null.</p> +<p>This code has several problems if the body of the '<tt>if</tt>' is large. +When you're looking at the top of the function, it isn't immediately clear that +this <em>only</em> does interesting things with non-terminator instructions, and +only applies to things with the other predicates. Second, it is relatively +difficult to describe (in comments) why these predicates are important because +the <tt>if</tt> statement makes it difficult to lay out the comments. Third, +when you're deep within the body of the code, it is indented an extra level. +Finally, when reading the top of the function, it isn't clear what the result is +if the predicate isn't true; you have to read to the end of the function to know +that it returns null.</p> <p>It is much preferred to format the code like this:</p> <div class="doc_code"> <pre> Value *DoSomething(Instruction *I) { - // Terminators never need 'something' done to them because, ... + // Terminators never need 'something' done to them because ... if (isa<TerminatorInst>(I)) return 0; @@ -580,7 +609,7 @@ Value *DoSomething(Instruction *I) { </pre> </div> -<p>This fixes these problems. A similar problem frequently happens in for +<p>This fixes these problems. A similar problem frequently happens in <tt>for</tt> loops. A silly example is something like this:</p> <div class="doc_code"> @@ -597,14 +626,13 @@ loops. A silly example is something like this:</p> </pre> </div> -<p>When you have very very small loops, this sort of structure is fine, but if +<p>When you have very, very small loops, this sort of structure is fine. But if it exceeds more than 10-15 lines, it becomes difficult for people to read and -understand at a glance. -The problem with this sort of code is that it gets very nested very quickly, -meaning that the reader of the code has to keep a lot of context in their brain -to remember what is going immediately on in the loop, because they don't know -if/when the if conditions will have elses etc. It is strongly preferred to -structure the loop like this:</p> +understand at a glance. The problem with this sort of code is that it gets very +nested very quickly. Meaning that the reader of the code has to keep a lot of +context in their brain to remember what is going immediately on in the loop, +because they don't know if/when the <tt>if</tt> conditions will have elses etc. +It is strongly preferred to structure the loop like this:</p> <div class="doc_code"> <pre> @@ -615,30 +643,32 @@ structure the loop like this:</p> Value *LHS = BO->getOperand(0); Value *RHS = BO->getOperand(1); if (LHS == RHS) continue; + + ... } </pre> </div> -<p>This has all the benefits of using early exits from functions: it reduces +<p>This has all the benefits of using early exits for functions: it reduces nesting of the loop, it makes it easier to describe why the conditions are true, -and it makes it obvious to the reader that there is no "else" coming up that -they have to push context into their brain for. If a loop is large, this can -be a big understandability win.</p> +and it makes it obvious to the reader that there is no <tt>else</tt> coming up +that they have to push context into their brain for. If a loop is large, this +can be a big understandability win.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="hl_else_after_return">Don't use "else" after a return</a> + <a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a> </div> <div class="doc_text"> <p>For similar reasons above (reduction of indentation and easier reading), - please do not use "else" or "else if" after something that interrupts - control flow like return, break, continue, goto, etc. For example, this is - "bad":</p> - +please do not use '<tt>else</tt>' or '<tt>else if</tt>' after something that +interrupts control flow — like <tt>return</tt>, <tt>break</tt>, +<tt>continue</tt>, <tt>goto</tt>, etc. For example, this is <em>bad</em>:</p> + <div class="doc_code"> <pre> case 'J': { @@ -647,24 +677,24 @@ be a big understandability win.</p> if (Type.isNull()) { Error = ASTContext::GE_Missing_sigjmp_buf; return QualType(); - } else { + <b>} else { break; - } + }</b> } else { Type = Context.getjmp_bufType(); if (Type.isNull()) { Error = ASTContext::GE_Missing_jmp_buf; return QualType(); - } else { + <b>} else { break; - } + }</b> } } } </pre> </div> -<p>It is better to write this something like:</p> +<p>It is better to write it like this:</p> <div class="doc_code"> <pre> @@ -682,11 +712,11 @@ be a big understandability win.</p> return QualType(); } } - break; + <b>break;</b> </pre> </div> -<p>Or better yet (in this case), as:</p> +<p>Or better yet (in this case) as:</p> <div class="doc_code"> <pre> @@ -701,12 +731,12 @@ be a big understandability win.</p> ASTContext::GE_Missing_jmp_buf; return QualType(); } - break; + <b>break;</b> </pre> </div> <p>The idea is to reduce indentation and the amount of code you have to keep - track of when reading the code.</p> +track of when reading the code.</p> </div> @@ -717,9 +747,9 @@ be a big understandability win.</p> <div class="doc_text"> -<p>It is very common to write small loops that just compute a boolean - value. There are a number of ways that people commonly write these, but an - example of this sort of thing is:</p> +<p>It is very common to write small loops that just compute a boolean value. +There are a number of ways that people commonly write these, but an example of +this sort of thing is:</p> <div class="doc_code"> <pre> @@ -740,9 +770,7 @@ be a big understandability win.</p> Instead of this sort of loop, we strongly prefer to use a predicate function (which may be <a href="#micro_anonns">static</a>) that uses <a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer -the code to be structured like this: -</p> - +the code to be structured like this:</p> <div class="doc_code"> <pre> @@ -777,19 +805,102 @@ locality.</p> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="micro">The Low Level Issues</a> + <a name="micro">The Low-Level Issues</a> </div> <!-- ======================================================================= --> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> + <a name="ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a> +</div> + +<div class="doc_text"> + +<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress +enough how important it is to use <em>descriptive</em> names. Pick names that +match the semantics and role of the underlying entities, within reason. Avoid +abbreviations unless they are well known. After picking a good name, make sure +to use consistent capitalization for the name, as inconsistency requires clients +to either memorize the APIs or to look it up to find the exact spelling.</p> + +<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt> +and <tt>isLValue()</tt>). Different kinds of declarations have different +rules:</p> + +<ul> +<li><p><b>Type names</b> (including classes, structs, enums, typedefs, etc) + should be nouns and start with an upper-case letter (e.g. + <tt>TextFileReader</tt>).</p></li> + +<li><p><b>Function names</b> should be verb phrases (as they represent + actions), and command-like function should be imperative. The name should + be camel case, and start with a lower case letter (e.g. <tt>openFile()</tt> + or <tt>isFoo()</tt>).</p></li> + +<li><p><b>Enum declarations</b> (e.g. <tt>enum Foo {...}</tt>) are types, so + they should follow the naming conventions for types. A common use for enums + is as a discriminator for a union, or an indicator of a subclass. When an + enum is used for something like this, it should have a <tt>Kind</tt> suffix + (e.g. <tt>ValueKind</tt>).</p></li> + +<li><p><b>Enumerators</b> (e.g. <tt>enum { Foo, Bar }</tt>) and <b>public member + variables</b> should start with an upper-case letter, just like types. + Unless the enumerators are defined in their own small namespace or inside a + class, enumerators should have a prefix corresponding to the enum + declaration name. For example, <tt>enum ValueKind { ... };</tt> may contain + enumerators like <tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc. + Enumerators that are just convenience constants are exempt from the + requirement for a prefix. For instance:</p> + +<div class="doc_code"> +<pre> +enum { + MaxSize = 42, + Density = 12 +}; +</pre> +</div> +</li> + +</ul> + +<p>As an exception, classes that mimic STL classes can have member names in +STL's style of lower-case words separated by underscores (e.g. <tt>begin()</tt>, +<tt>push_back()</tt>, and <tt>empty()</tt>).</p> + +<p>Here are some examples of good and bad names:</p> + +<div class="doc_code"> +<pre> +class VehicleMaker { + ... + Factory<Tire> F; // Bad -- abbreviation and non-descriptive. + Factory<Tire> Factory; // Better. + Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one + // kind of factories. +}; + +Vehicle MakeVehicle(VehicleType Type) { + VehicleMaker M; // Might be OK if having a short life-span. + Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information. + Light headlight = M.makeLight("head"); // Good -- descriptive. + ... +} +</pre> +</div> + +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="ll_assert">Assert Liberally</a> </div> <div class="doc_text"> -<p>Use the "<tt>assert</tt>" function to its fullest. Check all of your +<p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your preconditions and assumptions, you never know when a bug (not necessarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<tt><cassert></tt>" header file is probably already @@ -797,8 +908,8 @@ included by the header files you are using, so it doesn't cost anything to use it.</p> <p>To further assist with debugging, make sure to put some kind of error message -in the assertion statement (which is printed if the assertion is tripped). This -helps the poor debugging make sense of why an assertion is being made and +in the assertion statement, which is printed if the assertion is tripped. This +helps the poor debugger make sense of why an assertion is being made and enforced, and hopefully what to do about it. Here is one complete example:</p> <div class="doc_code"> @@ -810,7 +921,7 @@ inline Value *getOperand(unsigned i) { </pre> </div> -<p>Here are some examples:</p> +<p>Here are more examples:</p> <div class="doc_code"> <pre> @@ -826,9 +937,9 @@ assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!" </pre> </div> -<p>You get the idea...</p> +<p>You get the idea.</p> -<p>Please be aware when adding assert statements that not all compilers are aware of +<p>Please be aware that, when adding assert statements, not all compilers are aware of the semantics of the assert. In some places, asserts are used to indicate a piece of code that should not be reached. These are typically of the form:</p> @@ -851,14 +962,47 @@ return 0; </pre> </div> +<p>Another issue is that values used only by assertions will produce an "unused +value" warning when assertions are disabled. For example, this code will +warn:</p> + +<div class="doc_code"> +<pre> +unsigned Size = V.size(); +assert(Size > 42 && "Vector smaller than it should be"); + +bool NewToSet = Myset.insert(Value); +assert(NewToSet && "The value shouldn't be in the set yet"); +</pre> +</div> + +<p>These are two interesting different cases. In the first case, the call to +V.size() is only useful for the assert, and we don't want it executed when +assertions are disabled. Code like this should move the call into the assert +itself. In the second case, the side effects of the call must happen whether +the assert is enabled or not. In this case, the value should be cast to void to +disable the warning. To be specific, it is preferred to write the code like +this:</p> + +<div class="doc_code"> +<pre> +assert(V.size() > 42 && "Vector smaller than it should be"); + +bool NewToSet = Myset.insert(Value); (void)NewToSet; +assert(NewToSet && "The value shouldn't be in the set yet"); +</pre> +</div> + + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a> + <a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a> </div> <div class="doc_text"> + <p>In LLVM, we prefer to explicitly prefix all identifiers from the standard namespace with an "<tt>std::</tt>" prefix, rather than rely on "<tt>using namespace std;</tt>".</p> @@ -867,10 +1011,10 @@ namespace with an "<tt>std::</tt>" prefix, rather than rely on the namespace of any source file that <tt>#include</tt>s the header. This is clearly a bad thing.</p> -<p>In implementation files (e.g. .cpp files), the rule is more of a stylistic +<p>In implementation files (e.g. <tt>.cpp</tt> files), the rule is more of a stylistic rule, but is still important. Basically, using explicit namespace prefixes makes the code <b>clearer</b>, because it is immediately obvious what facilities -are being used and where they are coming from, and <b>more portable</b>, because +are being used and where they are coming from. And <b>more portable</b>, because namespace clashes cannot occur between LLVM code and other namespaces. The portability rule is important because different standard library implementations expose different symbols (potentially ones they shouldn't), and future revisions @@ -880,18 +1024,20 @@ such, we never use '<tt>using namespace std;</tt>' in LLVM.</p> <p>The exception to the general rule (i.e. it's not an exception for the <tt>std</tt> namespace) is for implementation files. For example, all of the code in the LLVM project implements code that lives in the 'llvm' namespace. -As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using -namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The -general form of this rule is that any .cpp file that implements code in any -namespace may use that namespace (and its parents'), but should not use any -others.</p> +As such, it is ok, and actually clearer, for the <tt>.cpp</tt> files to have a +'<tt>using namespace llvm;</tt>' directive at the top, after the +<tt>#include</tt>s. This reduces indentation in the body of the file for source +editors that indent based on braces, and keeps the conceptual context cleaner. +The general form of this rule is that any <tt>.cpp</tt> file that implements +code in any namespace may use that namespace (and its parents'), but should not +use any others.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_virtual_anch">Provide a virtual method anchor for classes - in headers</a> + <a name="ll_virtual_anch">Provide a Virtual Method Anchor for Classes + in Headers</a> </div> <div class="doc_text"> @@ -907,15 +1053,16 @@ increasing link times.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_end">Don't evaluate end() every time through a loop</a> + <a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a> </div> <div class="doc_text"> -<p>Because C++ doesn't have a standard "foreach" loop (though it can be emulated -with macros and may be coming in C++'0x) we end up writing a lot of loops that -manually iterate from begin to end on a variety of containers or through other -data structures. One common mistake is to write a loop in this style:</p> +<p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it can be +emulated with macros and may be coming in C++'0x) we end up writing a lot of +loops that manually iterate from begin to end on a variety of containers or +through other data structures. One common mistake is to write a loop in this +style:</p> <div class="doc_code"> <pre> @@ -946,10 +1093,10 @@ behavior, please write the loop in the first form and add a comment indicating that you did it intentionally.</p> <p>Why do we prefer the second form (when correct)? Writing the loop in the -first form has two problems: First it may be less efficient than evaluating it -at the start of the loop. In this case, the cost is probably minor: a few extra -loads every time through the loop. However, if the base expression is more -complex, then the cost can rise quickly. I've seen loops where the end +first form has two problems. First it may be less efficient than evaluating it +at the start of the loop. In this case, the cost is probably minor — a +few extra loads every time through the loop. However, if the base expression is +more complex, then the cost can rise quickly. I've seen loops where the end expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map lookups really aren't cheap. By writing it in the second form consistently, you eliminate the issue entirely and don't even have to think about it.</p> @@ -968,7 +1115,7 @@ prefer it.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a> + <a name="ll_iostream"><tt>#include <iostream></tt> is Forbidden</a> </div> <div class="doc_text"> @@ -977,12 +1124,13 @@ prefer it.</p> 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 c'tors are run whenever an application start up that uses the dynamic -library. There are two problems with this:</p> +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 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 @@ -990,12 +1138,10 @@ library. There are two problems with this:</p> </ol> <p>Note that using the other stream headers (<tt><sstream></tt> for -example) is not problematic in this regard (just <tt><iostream></tt>). -However, raw_ostream provides various APIs that are better performing for almost -every use than std::ostream style APIs, so you should just use it for new -code.</p> - -<p><b>New code should always +example) is not problematic in this regard — +just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides various +APIs that are better performing for almost every use than <tt>std::ostream</tt> +style APIs. <b>Therefore new code should always use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p> @@ -1004,44 +1150,44 @@ the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a> + <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a> </div> <div class="doc_text"> -<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline -to the output stream specified. In addition to doing this, however, it also -flushes the output stream. In other words, these are equivalent:</p> - -<div class="doc_code"> -<pre> -std::cout << std::endl; -std::cout << '\n' << std::flush; -</pre> -</div> +<p>LLVM includes a lightweight, simple, and efficient stream implementation +in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common +features of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt> +instead of <tt>ostream</tt>.</p> -<p>Most of the time, you probably have no reason to flush the output stream, so -it's better to use a literal <tt>'\n'</tt>.</p> +<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can +be forward declared as <tt>class raw_ostream</tt>. Public headers should +generally not include the <tt>raw_ostream</tt> header, but use forward +declarations and constant references to <tt>raw_ostream</tt> instances.</p> </div> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> - <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a> + <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a> </div> <div class="doc_text"> -<p>LLVM includes a lightweight, simple, and efficient stream implementation -in <tt>llvm/Support/raw_ostream.h</tt> which provides all of the common features -of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt> instead -of <tt>ostream</tt>.</p> +<p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt> outputs a +newline to the output stream specified. In addition to doing this, however, it +also flushes the output stream. In other words, these are equivalent:</p> -<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can -be forward declared as <tt>class raw_ostream</tt>. Public headers should -generally not include the <tt>raw_ostream</tt> header, but use forward -declarations and constant references to <tt>raw_ostream</tt> instances.</p> +<div class="doc_code"> +<pre> +std::cout << std::endl; +std::cout << '\n' << std::flush; +</pre> +</div> + +<p>Most of the time, you probably have no reason to flush the output stream, so +it's better to use a literal <tt>'\n'</tt>.</p> </div> @@ -1062,54 +1208,54 @@ reasoning on why we prefer them.</p> <div class="doc_text"> -<p>We prefer to put a space before a parentheses only in control flow +<p>We prefer to put a space before an open parenthesis only in control flow statements, but not in normal function call expressions and function-like macros. For example, this is good:</p> <div class="doc_code"> <pre> - <b>if (</b>x) ... - <b>for (</b>i = 0; i != 100; ++i) ... - <b>while (</b>llvm_rocks) ... +<b>if (</b>x) ... +<b>for (</b>i = 0; i != 100; ++i) ... +<b>while (</b>llvm_rocks) ... - <b>somefunc(</b>42); - <b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me"); +<b>somefunc(</b>42); +<b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me"); - a = <b>foo(</b>42, 92) + <b>bar(</b>x); - </pre> +a = <b>foo(</b>42, 92) + <b>bar(</b>x); +</pre> </div> -<p>... and this is bad:</p> +<p>and this is bad:</p> <div class="doc_code"> <pre> - <b>if(</b>x) ... - <b>for(</b>i = 0; i != 100; ++i) ... - <b>while(</b>llvm_rocks) ... +<b>if(</b>x) ... +<b>for(</b>i = 0; i != 100; ++i) ... +<b>while(</b>llvm_rocks) ... - <b>somefunc (</b>42); - <b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me"); +<b>somefunc (</b>42); +<b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me"); - a = <b>foo (</b>42, 92) + <b>bar (</b>x); +a = <b>foo (</b>42, 92) + <b>bar (</b>x); </pre> </div> <p>The reason for doing this is not completely arbitrary. This style makes - control flow operators stand out more, and makes expressions flow better. The - function call operator binds very tightly as a postfix operator. Putting - a space after a function name (as in the last example) makes it appear that - the code might bind the arguments of the left-hand-side of a binary operator - with the argument list of a function and the name of the right side. More - specifically, it is easy to misread the "a" example as:</p> +control flow operators stand out more, and makes expressions flow better. The +function call operator binds very tightly as a postfix operator. Putting a +space after a function name (as in the last example) makes it appear that the +code might bind the arguments of the left-hand-side of a binary operator with +the argument list of a function and the name of the right side. More +specifically, it is easy to misread the "a" example as:</p> <div class="doc_code"> <pre> - a = foo <b>(</b>(42, 92) + bar<b>)</b> (x); +a = foo <b>(</b>(42, 92) + bar<b>)</b> (x); </pre> </div> -<p>... when skimming through the code. By avoiding a space in a function, we -avoid this misinterpretation.</p> +<p>when skimming through the code. By avoiding a space in a function, we avoid +this misinterpretation.</p> </div> @@ -1141,7 +1287,7 @@ get in the habit of always using preincrement, and you won't have a problem.</p> <div class="doc_text"> <p> -In general, we strive to reduce indentation where ever possible. This is useful +In general, we strive to reduce indentation wherever possible. This is useful because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without wrapping horribly, but also because it makes it easier to understand the code. Namespaces are a funny thing: they are often large, and we often desire to put @@ -1186,7 +1332,7 @@ namespace llvm { <p>Since the body is small, indenting adds value because it makes it very clear where the namespace starts and ends, and it is easy to take the whole thing in in one "gulp" when reading the code. If the blob of code in the namespace is -larger (as it typically is in a header in the llvm or clang namespaces), do not +larger (as it typically is in a header in the <tt>llvm</tt> or <tt>clang</tt> namespaces), do not indent the code, and add a comment indicating what namespace is being closed. For example:</p> @@ -1346,7 +1492,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: 2010-05-07 02:28:04 +0200 (Fri, 07 May 2010) $ + Last modified: $Date: 2011-02-20 03:03:04 +0100 (Sun, 20 Feb 2011) $ </address> </body> diff --git a/docs/CommandGuide/FileCheck.pod b/docs/CommandGuide/FileCheck.pod index 433979a87190e..3ccaa63e176ba 100644 --- a/docs/CommandGuide/FileCheck.pod +++ b/docs/CommandGuide/FileCheck.pod @@ -133,7 +133,7 @@ both 32-bit and 64-bit code generation. =head2 The "CHECK-NEXT:" directive Sometimes you want to match lines and would like to verify that matches -happen on exactly consequtive lines with no other lines in between them. In +happen on exactly consecutive lines with no other lines in between them. In this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If you specified a custom check prefix, just use "<PREFIX>-NEXT:". For example, something like this works as you'd expect: @@ -165,7 +165,7 @@ directive in a file. =head2 The "CHECK-NOT:" directive The CHECK-NOT: directive is used to verify that a string doesn't occur -between two matches (or the first match and the beginning of the file). For +between two matches (or before the first match, or after the last match). For example, to verify that a load is removed by a transformation, a test like this can be used: diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index 67f0cfc1a110c..3c1a9f9ed4f0b 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -151,7 +151,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: 2010-09-08 01:32:02 +0200 (Wed, 08 Sep 2010) $ + Last modified: $Date: 2010-09-08 01:10:21 +0200 (Wed, 08 Sep 2010) $ </address> </body> diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod index ac24aab4ff6b5..eb26ec00fd76c 100644 --- a/docs/CommandGuide/llc.pod +++ b/docs/CommandGuide/llc.pod @@ -84,6 +84,14 @@ Disable optimizations that may produce excess precision for floating point. Note that this option can dramatically slow down code on some systems (e.g. X86). +=item B<--enable-no-infs-fp-math> + +Enable optimizations that assume no Inf values. + +=item B<--enable-no-nans-fp-math> + +Enable optimizations that assume no NAN values. + =item B<--enable-unsafe-fp-math> Enable optimizations that make unsafe assumptions about IEEE math (e.g. that diff --git a/docs/CommandGuide/lli.pod b/docs/CommandGuide/lli.pod index d368bec8660a4..52a2721e7d70b 100644 --- a/docs/CommandGuide/lli.pod +++ b/docs/CommandGuide/lli.pod @@ -102,10 +102,13 @@ B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help> Disable optimizations that may increase floating point precision. -=item B<-enable-finite-only-fp-math> +=item B<-enable-no-infs-fp-math> -Enable optimizations that assumes only finite floating point math. That is, -there is no NAN or Inf values. +Enable optimizations that assume no Inf values. + +=item B<-enable-no-nans-fp-math> + +Enable optimizations that assume no NAN values. =item B<-enable-unsafe-fp-math> diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index 47352009ea043..ef99ebc9d4120 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -29,7 +29,6 @@ <li><a href="#copyright">Copyright</a></li> <li><a href="#license">License</a></li> <li><a href="#patents">Patents</a></li> - <li><a href="#devagree">Developer Agreements</a></li> </ol></li> </ol> <div class="doc_author">Written by the LLVM Oversight Team</div> @@ -196,7 +195,11 @@ <ol> <li><b>Evan Cheng</b>: Code generator and all targets.</li> - <li><b>Doug Gregor</b>: Clang Basic, Lex, Parse, and Sema Libraries.</li> + <li><b>Greg Clayton</b>: LLDB.</li> + + <li><b>Doug Gregor</b>: Clang Frontend Libraries.</li> + + <li><b>Howard Hinnant</b>: libc++.</li> <li><b>Anton Korobeynikov</b>: Exception handling, debug information, and Windows codegen.</li> @@ -506,40 +509,40 @@ Changes</a></div> <!-- _______________________________________________________________________ --> <div class="doc_subsection"><a name="copyright">Copyright</a></div> <div class="doc_text"> -<p>For consistency and ease of management, the project requires the copyright - for all LLVM software to be held by a single copyright holder: the University - of Illinois (UIUC).</p> - -<p>Although UIUC may eventually reassign the copyright of the software to - another entity (e.g. a dedicated non-profit "LLVM Organization") the intent - for the project is to always have a single entity hold the copyrights to LLVM - at any given time.</p> - -<p>We believe that having a single copyright holder is in the best interests of - all developers and users as it greatly reduces the managerial burden for any - kind of administrative or technical decisions about LLVM. The goal of the - LLVM project is to always keep the code open and <a href="#license">licensed - under a very liberal license</a>.</p> + +<p>The LLVM project does not require copyright assignments, which means that the + copyright for the code in the project is held by its respective contributors + who have each agreed to release their contributed code under the terms of the + <a href="#license">LLVM License</a>.</p> + +<p>An implication of this is that the LLVM license is unlikely to ever change: + changing it would require tracking down all the contributors to LLVM and + getting them to agree that a license change is acceptable for their + contribution. Since there are no plans to change the license, this is not a + cause for concern.</p> + +<p>As a contributor to the project, this means that you (or your company) retain + ownership of the code you contribute, that it cannot be used in a way that + contradicts the license (which is a liberal BSD-style license), and that the + license for your contributions won't change without your approval in the + future.</p> + </div> <!-- _______________________________________________________________________ --> <div class="doc_subsection"><a name="license">License</a></div> <div class="doc_text"> <p>We intend to keep LLVM perpetually open source and to use a liberal open - source license. The current license is the + source license. 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> <ul> <li>You can freely distribute LLVM.</li> - <li>You must retain the copyright notice if you redistribute LLVM.</li> - - <li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in - an included readme file).</li> - + <li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in an + included readme file).</li> <li>You can't use our names to promote your LLVM derived products.</li> - <li>There's no warranty on LLVM at all.</li> </ul> @@ -549,7 +552,22 @@ Changes</a></div> LLVM's license is not a "copyleft" license like the GPL). We suggest that you read the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a> 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 + 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 + license (and thus don't need the binary redistribution clause), and as a + contributor to the code that you agree that any contributions to these + libraries be licensed under both licenses. We feel that this is important + for runtime libraries, because they are implicitly linked into applications + and therefore should not subject those applications to the binary + redistribution clause. This also means that it is ok to move code from (e.g.) + libc++ to the LLVM core without concern, but that code cannot be moved from + 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> 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 @@ -563,7 +581,7 @@ Changes</a></div> <p>We have no plans to change the license of LLVM. If you have questions or comments about the license, please contact the - <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a>.</p> + <a href="mailto:llvmdev@cs.uiuc.edu">LLVM Developer's Mailing List</a>.</p> </div> <!-- _______________________________________________________________________ --> @@ -584,21 +602,6 @@ Changes</a></div> details.</p> </div> -<!-- _______________________________________________________________________ --> -<div class="doc_subsection"><a name="devagree">Developer Agreements</a></div> -<div class="doc_text"> -<p>With regards to the LLVM copyright and licensing, developers agree to assign - their copyrights to UIUC for any contribution made so that the entire - software base can be managed by a single copyright holder. This implies that - any contributions can be licensed under the license that the project - uses.</p> - -<p>When contributing code, you also affirm that you are legally entitled to - grant this copyright, personally or on behalf of your employer. If the code - belongs to some other entity, please raise this issue with the oversight - group before the code is committed.</p> -</div> - <!-- *********************************************************************** --> <hr> <address> @@ -609,7 +612,7 @@ Changes</a></div> 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: 2010-09-02 02:09:17 +0200 (Thu, 02 Sep 2010) $ + Last modified: $Date: 2010-11-16 22:32:53 +0100 (Tue, 16 Nov 2010) $ </address> </body> </html> diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html index d324c15390cda..009dbb5abd537 100644 --- a/docs/ExceptionHandling.html +++ b/docs/ExceptionHandling.html @@ -40,6 +40,7 @@ <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> @@ -419,7 +420,7 @@ <div class="doc_text"> <pre> - i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...) + i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, ...) </pre> <p>This intrinsic is used to compare the exception with the given type infos, @@ -548,6 +549,23 @@ </div> <!-- ======================================================================= --> +<div class="doc_subsubsection"> + <a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a> +</div> + +<div class="doc_text"> + +<pre> + void %<a href="#llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>(i32) +</pre> + +<p>For SJLJ based exception handling, the <a href="#llvm_eh_sjlj_dispatchsetup"> + <tt>llvm.eh.sjlj.dispatchsetup</tt></a> intrinsic is used by targets to do + any unwind-edge setup they need. By default, no action is taken. </p> + +</div> + +<!-- ======================================================================= --> <div class="doc_section"> <a name="asm">Asm Table Formats</a> </div> @@ -619,7 +637,7 @@ <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2010-05-28 19:07:41 +0200 (Fri, 28 May 2010) $ + Last modified: $Date: 2010-12-10 00:05:48 +0100 (Fri, 10 Dec 2010) $ </address> </body> diff --git a/docs/GetElementPtr.html b/docs/GetElementPtr.html index d840c9788ac1a..5410137861ffc 100644 --- a/docs/GetElementPtr.html +++ b/docs/GetElementPtr.html @@ -598,13 +598,27 @@ idx3 = (char*) &MyVar + 8 <a name="overflow"><b>What happens if a GEP computation overflows?</b></a> </div> <div class="doc_text"> - <p>If the GEP has the <tt>inbounds</tt> keyword, the result value is - undefined.</p> - - <p>Otherwise, the result value is the result from evaluating the implied - two's complement integer computation. However, since there's no - guarantee of where an object will be allocated in the address space, - such values have limited meaning.</p> + <p>If the GEP lacks the <tt>inbounds</tt> keyword, the value is the result + from evaluating the implied two's complement integer computation. However, + since there's no guarantee of where an object will be allocated in the + address space, such values have limited meaning.</p> + + <p>If the GEP has the <tt>inbounds</tt> keyword, the result value is + undefined (a "<a href="LangRef.html#trapvalues">trap value</a>") if the GEP + overflows (i.e. wraps around the end of the address space).</p> + + <p>As such, there are some ramifications of this for inbounds GEPs: scales + implied by array/vector/pointer indices are always known to be "nsw" since + they are signed values that are scaled by the element size. These values + are also allowed to be negative (e.g. "gep i32 *%P, i32 -1") but the + pointer itself is logically treated as an unsigned value. This means that + GEPs have an asymmetric relation between the pointer base (which is treated + as unsigned) and the offset applied to it (which is treated as signed). The + result of the additions within the offset calculation cannot have signed + overflow, but when applied to the base pointer, there can be signed + overflow. + </p> + </div> @@ -719,7 +733,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: 2010-08-28 06:09:24 +0200 (Sat, 28 Aug 2010) $ + Last modified: $Date: 2011-02-11 22:50:52 +0100 (Fri, 11 Feb 2011) $ </address> </body> </html> diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 7c105fea8d116..dfb976a29f1e5 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -28,6 +28,7 @@ <li><a href="#environment">Setting Up Your Environment</a></li> <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> @@ -44,10 +45,9 @@ <li><a href="#projects"><tt>llvm/projects</tt></a></li> <li><a href="#runtime"><tt>llvm/runtime</tt></a></li> <li><a href="#test"><tt>llvm/test</tt></a></li> - <li><a href="#llvmtest"><tt>llvm-test</tt></a></li> + <li><a href="#test-suite"><tt>test-suite</tt></a></li> <li><a href="#tools"><tt>llvm/tools</tt></a></li> <li><a href="#utils"><tt>llvm/utils</tt></a></li> - <li><a href="#win32"><tt>llvm/win32</tt></a></li> </ol></li> <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> @@ -80,11 +80,12 @@ <p>Welcome to LLVM! In order to get started, you first need to know some basic information.</p> -<p>First, LLVM comes in two 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 a test suite that can be -used to test the LLVM tools and the GCC front end.</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 @@ -93,7 +94,7 @@ 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 llvm-test. It is a suite of programs +There is a third, optional piece called Test Suite. It is a suite of programs with a testing harness that can be used to further test LLVM's functionality and performance. </p> @@ -142,6 +143,7 @@ and performance. <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> </ul></li> @@ -162,7 +164,7 @@ and performance. <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 the testsuite or do some special kinds of LLVM builds.</p></li> + 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 @@ -243,6 +245,11 @@ software you will need.</p> <td>GCC</td> </tr> <tr> + <td>FreeBSD</td> + <td>amd64</td> + <td>GCC</td> +</tr> +<tr> <td>MacOS X<sup><a href="#pf_2">2</a></sup></td> <td>PowerPC</td> <td>GCC</td> @@ -564,6 +571,9 @@ as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</ <p><b>GCC 4.3.3 (Debian 4.3.3-10) on ARM</b>: Miscompiles parts of LLVM 2.6 when optimizations are turned on. The symptom is an infinite loop in FoldingSetImpl::RemoveNode while running the code generator.</p> +<p><b>GCC 4.3.5 and GCC 4.4.5 on ARM</b>: These can miscompile <tt>value >> +1</tt> even at -O0. A test failure in <tt>test/Assembler/alignstack.ll</tt> is +one symptom of the problem. <p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very long warning messages complaining that some ".gnu.linkonce.t.*" symbol was defined in a discarded section. You can safely ignore these messages as they are @@ -684,7 +694,7 @@ compressed with the gzip program. <dd>Source release for the LLVM libraries and tools.<br></dd> <dt><tt>llvm-test-x.y.tar.gz</tt></dt> - <dd>Source release for the LLVM test suite.</dd> + <dd>Source release for the LLVM test-suite.</dd> <dt><tt>llvm-gcc-4.2-x.y.source.tar.gz</tt></dt> <dd>Source release of the llvm-gcc-4.2 front end. See README.LLVM in the root @@ -726,6 +736,8 @@ revision), you can checkout it from the '<tt>tags</tt>' directory (instead of subdirectories of the '<tt>tags</tt>' directory:</p> <ul> +<li>Release 2.8: <b>RELEASE_28</b></li> +<li>Release 2.7: <b>RELEASE_27</b></li> <li>Release 2.6: <b>RELEASE_26</b></li> <li>Release 2.5: <b>RELEASE_25</b></li> <li>Release 2.4: <b>RELEASE_24</b></li> @@ -751,7 +763,7 @@ you get it from the Subversion repository:</p> <div class="doc_code"> <pre> % cd llvm/projects -% svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test +% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite </pre> </div> @@ -767,6 +779,25 @@ instructions</a> to successfully get and build the LLVM GCC front-end.</p> <!-- ======================================================================= --> <div class="doc_subsection"> + <a name="git_mirror">GIT mirror</a> +</div> + +<div class="doc_text"> + +<p>GIT mirrors are available for a number of LLVM subprojects. These mirrors + sync automatically with each Subversion commit and contain all necessary + git-svn marks (so, you can recreate git-svn metadata locally). Note that right + now mirrors reflect only <tt>trunk</tt> for each project. You can do the + read-only GIT clone of LLVM via: +<pre> +% git clone http://llvm.org/git/llvm.git +</pre> +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> <a name="installcf">Install the GCC Front End</a> </div> @@ -774,7 +805,7 @@ instructions</a> to successfully get and build the LLVM GCC front-end.</p> <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 testsuite and for compiling C/C++ programs. Note that +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> @@ -795,9 +826,9 @@ to your <tt>PATH</tt> environment variable. For example, if you uncompressed th <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 llvm-test. Note that you can always build or install <tt>llvm-gcc</tt> at any +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 -llvm-test will pick it up. +test-suite will pick it up. </p> <p>As a convenience for Windows users, the front end binaries for MinGW/x86 include @@ -1348,7 +1379,7 @@ end to compile.</p> </div> <!-- ======================================================================= --> -<div class="doc_subsection"><a name="llvmtest"><tt>test-suite</tt></a></div> +<div class="doc_subsection"><a name="test-suite"><tt>test-suite</tt></a></div> <div class="doc_text"> <p>This is not a directory in the normal llvm module; it is a separate Subversion @@ -1408,7 +1439,7 @@ information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p> <dt><tt><b>llvm-ld</b></tt></dt> <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM. - This is the linker invoked by <tt>llvmc</tt>. It performsn standard link time + This is the linker invoked by <tt>llvmc</tt>. It performs standard link time optimizations and allows optimization modules to be loaded and run so that language specific optimizations can be applied at link time.</dd> @@ -1511,15 +1542,6 @@ are code generators for parts of LLVM infrastructure.</p> </div> -<!-- ======================================================================= --> -<div class="doc_subsection"><a name="win32"><tt>llvm/win32</tt></a></div> -<div class="doc_text"> - <p>This directory contains build scripts and project files for use with - Visual C++. This allows developers on Windows to build LLVM without the need - for Cygwin. The contents of this directory should be considered experimental - at this time. - </p> -</div> <!-- *********************************************************************** --> <div class="doc_section"> <a name="tutorial">An Example Using the LLVM Tool Chain</a> @@ -1673,7 +1695,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: 2010-07-08 10:27:18 +0200 (Thu, 08 Jul 2010) $ + Last modified: $Date: 2011-02-01 21:08:28 +0100 (Tue, 01 Feb 2011) $ </address> </body> </html> diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index e467e087c5878..b6aa4c692d434 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -14,26 +14,19 @@ <ul> <li><a href="#overview">Overview</a> - <li><a href="#quickstart">Getting Started Quickly (A Summary)</a> <li><a href="#requirements">Requirements</a> <ol> <li><a href="#hardware">Hardware</a> <li><a href="#software">Software</a> </ol></li> - - <li><a href="#starting">Getting Started with LLVM</a> - <ol> - <li><a href="#terminology">Terminology and Notation</a> - <li><a href="#objfiles">The Location of LLVM Object Files</a> - </ol></li> - + <li><a href="#quickstart">Getting Started</a> <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> <li><a href="#problems">Common Problems</a> <li><a href="#links">Links</a> </ul> <div class="doc_author"> - <p>Written by: + <p>Written by: <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a> </p> </div> @@ -47,26 +40,30 @@ <div class="doc_text"> - <p>The Visual Studio port at this time is experimental. It is suitable for - use only if you are writing your own compiler front end or otherwise have a - need to dynamically generate machine code. The JIT and interpreter are - functional, but it is currently not possible to generate assembly code which - is then assembled into an executable. You can indirectly create executables - by using the C back end.</p> - - <p>To emphasize, there is no C/C++ front end currently available. - <tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped using VC++. - Eventually there should be a <tt>llvm-gcc</tt> based on Cygwin or MinGW that - is usable. There is also the option of generating bitcode files on Unix and - copying them over to Windows. But be aware the odds of linking C++ code - compiled with <tt>llvm-gcc</tt> with code compiled with VC++ is essentially - zero.</p> - - <p>The LLVM test suite cannot be run on the Visual Studio port at this + <p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using + Visual Studio, not mingw or cygwin. In order to get started, you first need to + know some basic information.</p> + + <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, + bitcode analyzer and bitcode optimizer. It also contains a test suite that can + be used to test the LLVM tools.</p> + + <p>Another useful project on Windows is + <a href="http://clang.llvm.org/">clang</a>. Clang is a C family + ([Objective]C/C++) compiler. Clang mostly works on Windows, but does not + currently understand all of the Microsoft extensions to C and C++. Because of + this, clang cannot parse the C++ standard library included with Visual Studio, + nor parts of the Windows Platform SDK. However, most standard C programs do + compile. Clang can be used to emit bitcode, directly emit object files or + even linked executables using Visual Studio's <tt>link.exe</tt></p> + + <p>The large LLVM test suite cannot be run on the Visual Studio port at this time.</p> <p>Most of the tools build and work. <tt>bugpoint</tt> does build, but does - not work. The other tools 'should' work, but have not been fully tested.</p> + not work.</p> <p>Additional information about the LLVM directory structure and tool chain can be found on the main <a href="GettingStarted.html">Getting Started</a> @@ -76,89 +73,6 @@ <!-- *********************************************************************** --> <div class="doc_section"> - <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>Here's the short story for getting up and running quickly with LLVM:</p> - -<ol> - <li>Read the documentation.</li> - <li>Seriously, read the documentation.</li> - <li>Remember that you were warned twice about reading the documentation.</li> - - <li>Get the Source Code - <ul> - <li>With the distributed files: - <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> - <i> or use WinZip</i> - <li><tt>cd llvm</tt></li> - </ol></li> - - <li>With anonymous Subversion access: - <ol> - <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li> - <li><tt>svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top - </tt></li> - <li><tt>make checkout MODULE=llvm</tt> - <li><tt>cd llvm</tt></li> - </ol></li> - </ul></li> - - <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date - project files: - <ul><li>This step is currently optional as LLVM does still come with a - normal Visual Studio solution file, but it is not always kept up-to-date - and will soon be deprecated in favor of the multi-platform generator - CMake.</li> - <li>If CMake is installed then the most simple way is to just start the - CMake GUI, select the directory where you have LLVM extracted to, and - the default options should all be fine. The one option you may really - want to change, regardless of anything else, might be the - CMAKE_INSTALL_PREFIX setting to select a directory to INSTALL to once - compiling is complete.</li> - <li>If you use CMake to generate the Visual Studio solution and project - files, then the Solution will have a few extra options compared to the - current included one. The projects may still be built individually, but - to build them all do not just select all of them in batch build (as some - are meant as configuration projects), but rather select and build just - the ALL_BUILD project to build everything, or the INSTALL project, which - first builds the ALL_BUILD project, then installs the LLVM headers, libs, - and other useful things to the directory set by the CMAKE_INSTALL_PREFIX - setting when you first configured CMake.</li> - </ul> - </li> - - <li>Start Visual Studio - <ul> - <li>If you did not use CMake, then simply double click on the solution - file <tt>llvm/win32/llvm.sln</tt>.</li> - <li>If you used CMake, then the directory you created the project files, - the root directory will have an <tt>llvm.sln</tt> file, just - double-click on that to open Visual Studio.</li> - </ul></li> - - <li>Build the LLVM Suite: - <ul> - <li>Simply build the solution.</li> - <li>The Fibonacci project is a sample program that uses the JIT. Modify - the project's debugging properties to provide a numeric command line - argument. The program will print the corresponding fibonacci value.</li> - </ul></li> - -</ol> - -<p>It is strongly encouraged that you get the latest version from Subversion as -changes are continually making the VS support better.</p> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> <a name="requirements"><b>Requirements</b></a> </div> <!-- *********************************************************************** --> @@ -178,7 +92,7 @@ changes are continually making the VS support better.</p> <div class="doc_text"> - <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine. + <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 approximately 3GB.</p> @@ -190,75 +104,126 @@ changes are continually making the VS support better.</p> <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. VS2003 would work except (at last check) it has a bug with - friend classes that you can work-around with some minor code rewriting - (and please submit a patch if you do). Earlier versions of Visual Studio - do not support the C++ standard well enough and will not work.</p> - + compatible. Earlier versions of Visual Studio do not support the C++ standard + well enough and will not work.</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> - <p> - Do not install the LLVM directory tree into a path containing spaces (e.g. + <p>If you would like to run the LLVM tests you will need + <a href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to + work. You will need <a href="http://gnuwin32.sourceforge.net/">"GnuWin32"</a> + tools, too.</p> + + <p>Do not install the LLVM directory tree into a path containing spaces (e.g. C:\Documents and Settings\...) as the configure step will fail.</p> </div> <!-- *********************************************************************** --> <div class="doc_section"> - <a name="starting"><b>Getting Started with LLVM</b></a> + <a name="quickstart"><b>Getting Started</b></a> </div> <!-- *********************************************************************** --> <div class="doc_text"> -<p>The remainder of this guide is meant to get you up and running with -LLVM using Visual Studio and to give you some basic information about the LLVM -environment.</p> +<p>Here's the short story for getting up and running quickly with LLVM:</p> -</div> +<ol> + <li>Read the documentation.</li> + <li>Seriously, read the documentation.</li> + <li>Remember that you were warned twice about reading the documentation.</li> -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="terminology">Terminology and Notation</a> -</div> + <li>Get the Source Code + <ul> + <li>With the distributed files: + <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> + <i> or use WinZip</i> + <li><tt>cd llvm</tt></li> + </ol></li> -<div class="doc_text"> + <li>With anonymous Subversion access: + <ol> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> + <li><tt>cd llvm</tt></li> + </ol></li> + </ul></li> -<p>Throughout this manual, the following names are used to denote paths -specific to the local system and working environment. <i>These are not -environment variables you need to set but just strings used in the rest -of this document below</i>. In any of the examples below, simply replace -each of these names with the appropriate pathname on your local system. -All these paths are absolute:</p> + <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date + project files: + <ul> + <li>Once CMake is installed then the simplest way is to just start the + CMake GUI, select the directory where you have LLVM extracted to, and the + default options should all be fine. One option you may really want to + change, regardless of anything else, might be the CMAKE_INSTALL_PREFIX + setting to select a directory to INSTALL to once compiling is complete, + although installation is not mandatory for using LLVM. Another important + option is LLVM_TARGETS_TO_BUILD, which controls the LLVM target + architectures that are included on the build. + <li>See the <a href="CMake.html">LLVM CMake guide</a> for + detailed information about how to configure the LLVM + build.</li> + </ul> + </li> -<dl> - <dt>SRC_ROOT</dt> - <dd><p>This is the top level directory of the LLVM source tree.</p></dd> + <li>Start Visual Studio + <ul> + <li>In the directory you created the project files will have + an <tt>llvm.sln</tt> file, just double-click on that to open + Visual Studio.</li> + </ul></li> - <dt>OBJ_ROOT</dt> - <dd><p>This is the top level directory of the LLVM object tree (i.e. the - tree where object files and compiled programs will be placed. It is - fixed at SRC_ROOT/win32).</p></dd> -</dl> + <li>Build the LLVM Suite: + <ul> + <li>The projects may still be built individually, but + to build them all do not just select all of them in batch build (as some + are meant as configuration projects), but rather select and build just + the ALL_BUILD project to build everything, or the INSTALL project, which + first builds the ALL_BUILD project, then installs the LLVM headers, libs, + and other useful things to the directory set by the CMAKE_INSTALL_PREFIX + setting when you first configured CMake.</li> + <li>The Fibonacci project is a sample program that uses the JIT. + Modify the project's debugging properties to provide a numeric + command line argument or run it from the command line. The + program will print the corresponding fibonacci value.</li> + </ul></li> -</div> + <li>Test LLVM on Visual Studio: + <ul> + <li>If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR + on CMake for the path to GnuWin32.</li> + <li>You can run LLVM tests to build the project "check".</li> + </ul> + </li> -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="objfiles">The Location of LLVM Object Files</a> + <!-- FIXME: Is it up-to-date? --> + <li>Test LLVM: + <ul> + <li>The LLVM tests can be run by <tt>cd</tt>ing to the llvm source directory + and running: + +<div class="doc_code"> +<pre> +% llvm-lit test +</pre> </div> -<div class="doc_text"> + <p>Note that quite a few of these test will fail.</p> + </li> - <p>The object files are placed under <tt>OBJ_ROOT/Debug</tt> for debug builds - and <tt>OBJ_ROOT/Release</tt> for release (optimized) builds. These include - both executables and libararies that your application can link against.</p> + <li>A specific test or test directory can be run with:</li> - <p>The files that <tt>configure</tt> would create when building on Unix are - created by the <tt>Configure</tt> project and placed in - <tt>OBJ_ROOT/llvm</tt>. You application must have OBJ_ROOT in its include - search path just before <tt>SRC_ROOT/include</tt>.</p> +<div class="doc_code"> +<pre> +% llvm-lit test/path/to/test +</pre> +</div> + +</ol> </div> @@ -286,7 +251,7 @@ int main() { <div class="doc_code"> <pre> -% llvm-gcc -c hello.c -emit-llvm -o hello.bc +% clang -c hello.c -emit-llvm -o hello.bc </pre> </div> @@ -295,23 +260,27 @@ int main() { facilities that it required. You can execute this file directly using <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>, optimize or analyze it further with the <tt>opt</tt> tool, etc.</p> - - <p><b>Note: while you cannot do this step on Windows, you can do it on a - Unix system and transfer <tt>hello.bc</tt> to Windows. Important: - transfer as a binary file!</b></p></li> + + <p>Alternatively you can directly output an executable with clang with: + </p> + +<div class="doc_code"> +<pre> +% clang hello.c -o hello.exe +</pre> +</div> + + <p>The <tt>-o hello.exe</tt> is required because clang currently outputs + <tt>a.out</tt> when neither <tt>-o</tt> nor <tt>-c</tt> are given.</p> <li><p>Run the program using the just-in-time compiler:</p> - + <div class="doc_code"> <pre> % lli hello.bc </pre> </div> - <p>Note: this will only work for trivial C programs. Non-trivial programs - (and any C++ program) will have dependencies on the GCC runtime that - won't be satisfied by the Microsoft runtime libraries.</p></li> - <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly code:</p> @@ -321,31 +290,27 @@ int main() { </pre> </div></li> - <li><p>Compile the program to C using the LLC code generator:</p> + <li><p>Compile the program to object code using the LLC code generator:</p> <div class="doc_code"> <pre> -% llc -march=c hello.bc +% llc -filetype=obj hello.bc </pre> </div></li> - <li><p>Compile to binary using Microsoft C:</p> + <li><p>Link to binary using Microsoft link:</p> <div class="doc_code"> <pre> -% cl hello.cbe.c +% link hello.obj -defaultlib:libcmt </pre> </div> - <p>Note: this will only work for trivial C programs. Non-trivial programs - (and any C++ program) will have dependencies on the GCC runtime that won't - be satisfied by the Microsoft runtime libraries.</p></li> - <li><p>Execute the native code program:</p> <div class="doc_code"> <pre> -% hello.cbe.exe +% hello.exe </pre> </div></li> </ol> @@ -360,17 +325,6 @@ int main() { <div class="doc_text"> - <ul> - <li>In Visual C++, if you are linking with the x86 target statically, the - linker will remove the x86 target library from your generated executable or - shared library because there are no references to it. You can force the - linker to include these references by using - <tt>"/INCLUDE:_X86TargetMachineModule"</tt> when linking. In the Visual - Studio IDE, this can be added in -<tt>Project Properties->Linker->Input->Force Symbol References</tt>. - </li> - </ul> - <p>If you are having problems building or using LLVM, or if you have any other general questions about LLVM, please consult the <a href="FAQ.html">Frequently Asked Questions</a> page.</p> @@ -411,7 +365,7 @@ out:</p> <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2010-05-07 02:28:04 +0200 (Fri, 07 May 2010) $ + Last modified: $Date: 2011-02-09 05:19:28 +0100 (Wed, 09 Feb 2011) $ </address> </body> </html> diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index 3f2e9fb2e6402..68c5cf1928028 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -55,7 +55,7 @@ mkdir binutils cd binutils cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login <em>{enter "anoncvs" as the password}</em> -cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co src +cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils mkdir build cd build ../src/configure --enable-gold --enable-plugins diff --git a/docs/LangRef.html b/docs/LangRef.html index b717531e34792..05130c29efc29 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -62,6 +62,7 @@ <ol> <li><a href="#t_integer">Integer Type</a></li> <li><a href="#t_floating">Floating Point Types</a></li> + <li><a href="#t_x86mmx">X86mmx Type</a></li> <li><a href="#t_void">Void Type</a></li> <li><a href="#t_label">Label Type</a></li> <li><a href="#t_metadata">Metadata Type</a></li> @@ -492,7 +493,7 @@ <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">@.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> <i>; External declaration of the puts function</i> <a href="#functionstructure">declare</a> i32 @puts(i8*) <i>; i32 (i8*)* </i> @@ -845,6 +846,13 @@ define i32 @main() { <i>; i32()* </i> region of memory, and all memory objects in LLVM are accessed through pointers.</p> +<p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates + that the address is not significant, only the content. Constants marked + like this can be merged with other constants if they have the same + initializer. Note that a constant with significant address <em>can</em> + be merged with a <tt>unnamed_addr</tt> constant, the result being a + constant whose address is significant.</p> + <p>A global variable may be declared to reside in a target-specific numbered address space. For targets that support them, address spaces may affect how optimizations are performed and/or what target instructions are used to @@ -884,7 +892,8 @@ define i32 @main() { <i>; i32()* </i> <p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an optional <a href="#linkage">linkage type</a>, an optional <a href="#visibility">visibility style</a>, an optional - <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#callingconv">calling convention</a>, + an optional <tt>unnamed_addr</tt> attribute, a return type, an optional <a href="#paramattrs">parameter attribute</a> for the return type, a function name, a (possibly empty) argument list (each with optional <a href="#paramattrs">parameter attributes</a>), optional @@ -895,7 +904,8 @@ define i32 @main() { <i>; i32()* </i> <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an optional <a href="#linkage">linkage type</a>, an optional <a href="#visibility">visibility style</a>, an optional - <a href="#callingconv">calling convention</a>, a return type, an optional + <a href="#callingconv">calling convention</a>, + an optional <tt>unnamed_addr</tt> attribute, a return type, an optional <a href="#paramattrs">parameter attribute</a> for the return type, a function name, a possibly empty list of arguments, an optional alignment, and an optional <a href="#gc">garbage collector name</a>.</p> @@ -921,6 +931,9 @@ define i32 @main() { <i>; i32()* </i> specified, the function is forced to have at least that much alignment. All 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>. + <h5>Syntax:</h5> <pre class="doc_code"> define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] @@ -1020,8 +1033,9 @@ declare signext i8 @returns_signed_char() registers). Use of this attribute is target-specific.</dd> <dt><tt><b><a name="byval">byval</a></b></tt></dt> - <dd>This indicates that the pointer parameter should really be passed by value - to the function. The attribute implies that a hidden copy of the pointee + <dd><p>This indicates that the pointer parameter should really be passed by + value to the function. The attribute implies that a hidden copy of the + pointee is made between the caller and the callee, so the callee is unable to modify the value in the callee. This attribute is only valid on LLVM pointer arguments. It is generally used to pass structs and arrays by @@ -1029,10 +1043,13 @@ declare signext i8 @returns_signed_char() to belong to the caller not the callee (for example, <tt><a href="#readonly">readonly</a></tt> functions should not write to <tt>byval</tt> parameters). This is not a valid attribute for return - values. The byval attribute also supports specifying an alignment with - the align attribute. This has a target-specific effect on the code - generator that usually indicates a desired alignment for the synthesized - stack slot.</dd> + values.</p> + + <p>The byval attribute also supports specifying an alignment with + the align attribute. It indicates the alignment of the stack slot to + form and the known alignment of the pointer specified to the call site. If + the alignment is not specified, then the code generator makes a + target-specific assumption.</p></dd> <dt><tt><b><a name="sret">sret</a></b></tt></dt> <dd>This indicates that the pointer parameter specifies the address of a @@ -1130,6 +1147,14 @@ define void @f() optsize { ... } function into callers whenever possible, ignoring any active inlining size threshold for this caller.</dd> + <dt><tt><b>hotpatch</b></tt></dt> + <dd>This attribute indicates that the function should be 'hotpatchable', + meaning the function can be patched and/or hooked even while it is + loaded into memory. On x86, the function prologue will be preceded + by six bytes of padding and will begin with a two-byte instruction. + Most of the functions in the Windows system DLLs in Windows XP SP2 or + higher were compiled in this fashion.</dd> + <dt><tt><b>inlinehint</b></tt></dt> <dd>This attribute indicates that the source code contained a hint that inlining this function is desirable (such as the "inline" keyword in C/C++). It @@ -1483,7 +1508,9 @@ Classifications</a> </div> <td><a href="#t_primitive">primitive</a></td> <td><a href="#t_label">label</a>, <a href="#t_void">void</a>, + <a href="#t_integer">integer</a>, <a href="#t_floating">floating point</a>, + <a href="#t_x86mmx">x86mmx</a>, <a href="#t_metadata">metadata</a>.</td> </tr> <tr> @@ -1571,6 +1598,21 @@ Classifications</a> </div> </div> <!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="t_x86mmx">X86mmx Type</a> </div> + +<div class="doc_text"> + +<h5>Overview:</h5> +<p>The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.</p> + +<h5>Syntax:</h5> +<pre> + x86mmx +</pre> + +</div> + +<!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> <a name="t_void">Void Type</a> </div> <div class="doc_text"> @@ -1893,8 +1935,9 @@ Classifications</a> </div> < <# elements> x <elementtype> > </pre> -<p>The number of elements is a constant integer value; elementtype may be any - integer or floating point type.</p> +<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> <h5>Examples:</h5> <table class="layout"> @@ -2050,6 +2093,7 @@ Classifications</a> </div> they match the long double format on your target. All hexadecimal formats are big-endian (sign bit at the left).</p> +<p>There are no constants of type x86mmx.</p> </div> <!-- ======================================================================= --> @@ -2135,8 +2179,8 @@ Classifications</a> </div> <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and indicates that the user of the value may receive an unspecified bit-pattern. - Undefined values may be of any type (other than label or void) and be used - anywhere a constant is permitted.</p> + Undefined values may be of any type (other than '<tt>label</tt>' + or '<tt>void</tt>') and be used anywhere a constant is permitted.</p> <p>Undefined values are useful because they indicate to the compiler that the program is well defined no matter what value is used. This gives the @@ -2155,7 +2199,7 @@ Safe: </pre> <p>This is safe because all of the output bits are affected by the undef bits. -Any output bit can have a zero or one depending on the input bits.</p> + Any output bit can have a zero or one depending on the input bits.</p> <pre class="doc_code"> %A = or %X, undef @@ -2169,13 +2213,14 @@ Unsafe: </pre> <p>These logical operations have bits that are not always affected by the input. -For example, if "%X" has a zero bit, then the output of the 'and' operation will -always be a zero, no matter what the corresponding bit from the undef is. As -such, it is unsafe to optimize or assume that the result of the and is undef. -However, it is safe to assume that all bits of the undef could be 0, and -optimize the and to 0. Likewise, it is safe to assume that all the bits of -the undef operand to the or could be set, allowing the or to be folded to --1.</p> + For example, if <tt>%X</tt> has a zero bit, then the output of the + '<tt>and</tt>' operation will always be a zero for that bit, no matter what + the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to + optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'. + However, it is safe to assume that all bits of the '<tt>undef</tt>' could be + 0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that + all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be + set, allowing the '<tt>or</tt>' to be folded to -1.</p> <pre class="doc_code"> %A = select undef, %X, %Y @@ -2191,13 +2236,14 @@ Unsafe: %C = undef </pre> -<p>This set of examples show that undefined select (and conditional branch) -conditions can go "either way" but they have to come from one of the two -operands. In the %A example, if %X and %Y were both known to have a clear low -bit, then %A would have to have a cleared low bit. However, in the %C example, -the optimizer is allowed to assume that the undef operand could be the same as -%Y, allowing the whole select to be eliminated.</p> - +<p>This set of examples shows that undefined '<tt>select</tt>' (and conditional + branch) conditions can go <em>either way</em>, but they have to come from one + of the two operands. In the <tt>%A</tt> example, if <tt>%X</tt> and + <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would + have to have a cleared low bit. However, in the <tt>%C</tt> example, the + optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the + same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be + eliminated.</p> <pre class="doc_code"> %A = xor undef, undef @@ -2218,16 +2264,17 @@ Safe: %F = undef </pre> -<p>This example points out that two undef operands are not necessarily the same. -This can be surprising to people (and also matches C semantics) where they -assume that "X^X" is always zero, even if X is undef. This isn't true for a -number of reasons, but the short answer is that an undef "variable" can -arbitrarily change its value over its "live range". This is true because the -"variable" doesn't actually <em>have a live range</em>. Instead, the value is -logically read from arbitrary registers that happen to be around when needed, -so the value is not necessarily consistent over time. In fact, %A and %C need -to have the same semantics or the core LLVM "replace all uses with" concept -would not hold.</p> +<p>This example points out that two '<tt>undef</tt>' operands are not + necessarily the same. This can be surprising to people (and also matches C + semantics) where they assume that "<tt>X^X</tt>" is always zero, even + if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the + short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change + its value over its "live range". This is true because the variable doesn't + actually <em>have a live range</em>. Instead, the value is logically read + from arbitrary registers that happen to be around when needed, so the value + is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt> + need to have the same semantics or the core LLVM "replace all uses with" + concept would not hold.</p> <pre class="doc_code"> %A = fdiv undef, %X @@ -2238,17 +2285,17 @@ b: unreachable </pre> <p>These examples show the crucial difference between an <em>undefined -value</em> and <em>undefined behavior</em>. An undefined value (like undef) is -allowed to have an arbitrary bit-pattern. This means that the %A operation -can be constant folded to undef because the undef could be an SNaN, and fdiv is -not (currently) defined on SNaN's. However, in the second example, we can make -a more aggressive assumption: because the undef is allowed to be an arbitrary -value, we are allowed to assume that it could be zero. Since a divide by zero -has <em>undefined behavior</em>, we are allowed to assume that the operation -does not execute at all. This allows us to delete the divide and all code after -it: since the undefined operation "can't happen", the optimizer can assume that -it occurs in dead code. -</p> + value</em> and <em>undefined behavior</em>. An undefined value (like + '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that + the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because + the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently) + defined on SNaN's. However, in the second example, we can make a more + aggressive assumption: because the <tt>undef</tt> is allowed to be an + arbitrary value, we are allowed to assume that it could be zero. Since a + divide by zero has <em>undefined behavior</em>, we are allowed to assume that + the operation does not execute at all. This allows us to delete the divide and + all code after it. Because the undefined operation "can't happen", the + optimizer can assume that it occurs in dead code.</p> <pre class="doc_code"> a: store undef -> %X @@ -2258,11 +2305,11 @@ a: <deleted> b: unreachable </pre> -<p>These examples reiterate the fdiv example: a store "of" an undefined value -can be assumed to not have any effect: we can assume that the value is -overwritten with bits that happen to match what was already there. However, a -store "to" an undefined location could clobber arbitrary memory, therefore, it -has undefined behavior.</p> +<p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an + undefined value can be assumed to not have any effect; we can assume that the + value is overwritten with bits that happen to match what was already there. + However, a store <em>to</em> an undefined location could clobber arbitrary + memory, therefore, it has undefined behavior.</p> </div> @@ -2383,18 +2430,17 @@ end: the address of the entry block is illegal.</p> <p>This value only has defined behavior when used as an operand to the - '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons - against null. Pointer equality tests between labels addresses is undefined - behavior - though, again, comparison against null is ok, and no label is - equal to the null pointer. This may also be passed around as an opaque - pointer sized value as long as the bits are not inspected. This allows - <tt>ptrtoint</tt> and arithmetic to be performed on these values so long as - the original value is reconstituted before the <tt>indirectbr</tt>.</p> + '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction, or for + comparisons against null. Pointer equality tests between labels addresses + results in undefined behavior — though, again, comparison against null + is ok, and no label is equal to the null pointer. This may be passed around + as an opaque pointer sized value as long as the bits are not inspected. This + allows <tt>ptrtoint</tt> and arithmetic to be performed on these values so + long as the original value is reconstituted before the <tt>indirectbr</tt> + instruction.</p> -<p>Finally, some targets may provide defined semantics when - using the value as the operand to an inline assembly, but that is target - specific. - </p> +<p>Finally, some targets may provide defined semantics when using the value as + the operand to an inline assembly, but that is target specific.</p> </div> @@ -2409,7 +2455,7 @@ end: to be used as constants. Constant expressions may be of any <a href="#t_firstclass">first class</a> type and may involve any LLVM operation that does not have side effects (e.g. load and call are not - supported). The following is the syntax for constant expressions:</p> + supported). The following is the syntax for constant expressions:</p> <dl> <dt><b><tt>trunc (CST to TYPE)</tt></b></dt> @@ -2596,8 +2642,8 @@ call void asm alignstack "eieio", ""() <div class="doc_text"> <p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode - attached to it that contains a constant integer. If present, the code - generator will use the integer as the location cookie value when report + 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> @@ -2609,7 +2655,8 @@ 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.</p> + 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> @@ -3394,7 +3441,8 @@ Instruction</a> </div> <h5>Syntax:</h5> <pre> - <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = udiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> @@ -3413,6 +3461,11 @@ Instruction</a> </div> <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 + multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p> + + <h5>Example:</h5> <pre> <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> @@ -3631,7 +3684,10 @@ Instruction</a> </div> <h5>Syntax:</h5> <pre> - <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = shl nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = shl nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = shl nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> @@ -3651,6 +3707,14 @@ Instruction</a> </div> vectors, each vector element of <tt>op1</tt> is shifted by the corresponding 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 + 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 + 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> + <h5>Example:</h5> <pre> <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i> @@ -3670,7 +3734,8 @@ Instruction</a> </div> <h5>Syntax:</h5> <pre> - <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = lshr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> @@ -3690,6 +3755,11 @@ Instruction</a> </div> vectors, each vector element of <tt>op1</tt> is shifted by the corresponding 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 + shifted out are non-zero.</p> + + <h5>Example:</h5> <pre> <result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i> @@ -3709,7 +3779,8 @@ Instruction</a> </div> <h5>Syntax:</h5> <pre> - <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> + <result> = ashr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> </pre> <h5>Overview:</h5> @@ -3730,6 +3801,10 @@ Instruction</a> </div> the arguments are vectors, each vector element of <tt>op1</tt> is shifted by 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 + shifted out are non-zero.</p> + <h5>Example:</h5> <pre> <result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i> @@ -4097,6 +4172,14 @@ Instruction</a> </div> <a href="#t_array">array</a> type. The operands are constant indices to specify which value to extract in a similar manner as indices in a '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> + <p>The major differences to <tt>getelementptr</tt> indexing are:</p> + <ul> + <li>Since the value being indexed is not a pointer, the first index is + omitted and assumed to be zero.</li> + <li>At least one index must be specified.</li> + <li>Not only struct indices but also array indices must be in + bounds.</li> + </ul> <h5>Semantics:</h5> <p>The result is the value at the position in the aggregate specified by the @@ -4131,7 +4214,7 @@ Instruction</a> </div> <a href="#t_array">array</a> type. The second operand is a first-class value to insert. The following operands are constant indices indicating the position at which to insert the value in a similar manner as indices in a - '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. The + '<tt><a href="#i_extractvalue">extractvalue</a></tt>' instruction. The value to insert must have the same type as the value identified by the indices.</p> @@ -7472,7 +7555,7 @@ LLVM</a>.</p> <h5>Syntax:</h5> <pre> - declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) readonly + declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) </pre> <h5>Overview:</h5> @@ -7647,7 +7730,7 @@ LLVM</a>.</p> the <tt>AllocaInst</tt> stack slot to be before local variables on the stack. This is to ensure that if a local variable on the stack is overwritten, it will destroy the value of the guard. When the function exits, - the guard on the stack is checked against the original guard. If they're + the guard on the stack is checked against the original guard. If they are different, then the program aborts by calling the <tt>__stack_chk_fail()</tt> function.</p> @@ -7667,25 +7750,24 @@ LLVM</a>.</p> </pre> <h5>Overview:</h5> -<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information - to the optimizers to discover at compile time either a) when an - operation like memcpy will either overflow a buffer that corresponds to - an object, or b) to determine that a runtime check for overflow isn't - necessary. An object in this context means an allocation of a - specific class, structure, array, or other object.</p> +<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information to + the optimizers to determine at compile time whether a) an operation (like + memcpy) will overflow a buffer that corresponds to an object, or b) that a + runtime check for overflow isn't necessary. An object in this context means + an allocation of a specific class, structure, array, or other object.</p> <h5>Arguments:</h5> -<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first +<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first argument is a pointer to or into the <tt>object</tt>. The second argument - is a boolean 0 or 1. This argument determines whether you want the - maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or + is a boolean 0 or 1. This argument determines whether you want the + maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or 1, variables are not allowed.</p> <h5>Semantics:</h5> <p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant - representing the size of the object concerned or <tt>i32/i64 -1 or 0</tt> - (depending on the <tt>type</tt> argument if the size cannot be determined - at compile time.</p> + representing the size of the object concerned, or <tt>i32/i64 -1 or 0</tt>, + depending on the <tt>type</tt> argument, if the size cannot be determined at + compile time.</p> </div> @@ -7699,7 +7781,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: 2010-08-28 06:09:24 +0200 (Sat, 28 Aug 2010) $ + Last modified: $Date: 2011-02-09 17:44:44 +0100 (Wed, 09 Feb 2011) $ </address> </body> diff --git a/docs/LinkTimeOptimization.html b/docs/LinkTimeOptimization.html index 03dc677679902..30334744d7f9b 100644 --- a/docs/LinkTimeOptimization.html +++ b/docs/LinkTimeOptimization.html @@ -19,7 +19,7 @@ </ul></li> <li><a href="#multiphase">Multi-phase communication between LLVM and linker</a> <ul> - <li><a href="#phase1">Phase 1 : Read LLVM Bytecode Files</a></li> + <li><a href="#phase1">Phase 1 : Read LLVM Bitcode Files</a></li> <li><a href="#phase2">Phase 2 : Symbol Resolution</a></li> <li><a href="#phase3">Phase 3 : Optimize Bitcode Files</a></li> <li><a href="#phase4">Phase 4 : Symbol Resolution after optimization</a></li> @@ -382,7 +382,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: 2010-05-07 02:28:04 +0200 (Fri, 07 May 2010) $ + Last modified: $Date: 2010-09-29 22:09:55 +0200 (Wed, 29 Sep 2010) $ </address> </body> diff --git a/docs/Makefile b/docs/Makefile index 8f7d6171d3b33..389fd90a485e7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -37,14 +37,21 @@ install_targets := install-html ifeq ($(ENABLE_DOXYGEN),1) install_targets += install-doxygen endif +ifdef OCAMLDOC ifneq (,$(filter ocaml,$(BINDINGS_TO_BUILD))) install_targets += install-ocamldoc endif +endif install-local:: $(install_targets) +generated_targets := doxygen +ifdef OCAMLDOC +generated_targets += ocamldoc +endif + # Live documentation is generated for the web site using this target: # 'make generated BUILD_FOR_WEBSITE=1' -generated:: doxygen ocamldoc +generated:: $(generated_targets) install-html: $(PROJ_OBJ_DIR)/html.tar.gz $(Echo) Installing HTML documentation @@ -59,7 +66,7 @@ $(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar $(Verb) cd $(PROJ_SRC_DIR) && \ $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html - $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/html.tar + $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar install-doxygen: doxygen $(Echo) Installing doxygen documentation @@ -82,7 +89,7 @@ $(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg $(Echo) Packaging doxygen documentation $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen - $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/doxygen.tar + $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/ userloc: $(LLVM_SRC_ROOT)/docs/userloc.html @@ -104,7 +111,7 @@ ocamldoc: regen-ocamldoc $(Echo) Packaging ocamldoc documentation $(Verb) $(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc.tar* $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/ocamldoc.tar ocamldoc - $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/ocamldoc.tar + $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/ocamldoc.tar $(Verb) $(CP) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(PROJ_OBJ_DIR)/ocamldoc/html/ regen-ocamldoc: diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index 38b7ae19fa64b..6ceb09db32746 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -640,18 +640,18 @@ generate dependencies when running the compiler. Use of this feature is discouraged and it may be removed at a later date.</dd> <dt><a name="ENABLE_OPTIMIZED"><tt>ENABLE_OPTIMIZED</tt></a></dt> - <dd>If set to any value, causes the build to generate optimized objects, + <dd>If set to 1, causes the build to generate optimized objects, libraries and executables. This alters the flags specified to the compilers and linkers. Generally debugging won't be a fun experience with an optimized build.</dd> <dt><a name="ENABLE_PROFILING"><tt>ENABLE_PROFILING</tt></a></dt> - <dd>If set to any value, causes the build to generate both optimized and + <dd>If set to 1, causes the build to generate both optimized and profiled objects, libraries and executables. This alters the flags specified to the compilers and linkers to ensure that profile data can be collected from the tools built. Use the <tt>gprof</tt> tool to analyze the output from the profiled tools (<tt>gmon.out</tt>).</dd> <dt><a name="DISABLE_ASSERTIONS"><tt>DISABLE_ASSERTIONS</tt></a></dt> - <dd>If set to any value, causes the build to disable assertions, even if + <dd>If set to 1, causes the build to disable assertions, even if building a debug or profile build. This will exclude all assertion check code from the build. LLVM will execute faster, but with little help when things go wrong.</dd> @@ -1028,7 +1028,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2010-07-24 19:54:00 +0200 (Sat, 24 Jul 2010) $ + Last modified: $Date: 2010-10-22 14:54:34 +0200 (Fri, 22 Oct 2010) $ </address> </body> </html> diff --git a/docs/Passes.html b/docs/Passes.html index 0358745f79f7a..fb2aff585bdb2 100644 --- a/docs/Passes.html +++ b/docs/Passes.html @@ -166,7 +166,7 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#loop-rotate">-loop-rotate</a></td><td>Rotate Loops</td></tr> <tr><td><a href="#loop-unroll">-loop-unroll</a></td><td>Unroll loops</td></tr> <tr><td><a href="#loop-unswitch">-loop-unswitch</a></td><td>Unswitch loops</td></tr> -<tr><td><a href="#loopsimplify">-loopsimplify</a></td><td>Canonicalize natural loops</td></tr> +<tr><td><a href="#loop-simplify">-loop-simplify</a></td><td>Canonicalize natural loops</td></tr> <tr><td><a href="#loweratomic">-loweratomic</a></td><td>Lower atomic intrinsics</td></tr> <tr><td><a href="#lowerinvoke">-lowerinvoke</a></td><td>Lower invoke and unwind, for unwindless code generators</td></tr> <tr><td><a href="#lowersetjmp">-lowersetjmp</a></td><td>Lower Set Jump</td></tr> @@ -382,7 +382,7 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="dot-postdom">dot-postdom: Print post dominator tree of function to 'dot' file</a> + <a name="dot-postdom">-dot-postdom: Print post dominator tree of function to 'dot' file</a> </div> <div class="doc_text"> <p> @@ -394,7 +394,7 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="dot-postdom-only">dot-postdom-only: Print post dominator tree of function to 'dot' file + <a name="dot-postdom-only">-dot-postdom-only: Print post dominator tree of function to 'dot' file (with no function bodies)</a> </div> <div class="doc_text"> @@ -1491,7 +1491,7 @@ if (X < 3) {</pre> <!-------------------------------------------------------------------------- --> <div class="doc_subsection"> - <a name="loopsimplify">-loopsimplify: Canonicalize natural loops</a> + <a name="loop-simplify">-loop-simplify: Canonicalize natural loops</a> </div> <div class="doc_text"> <p> @@ -2242,7 +2242,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: 2010-08-20 03:03:44 +0200 (Fri, 20 Aug 2010) $ + Last modified: $Date: 2011-02-13 21:57:25 +0100 (Sun, 13 Feb 2011) $ </address> </body> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 8fdd8a00b9bc6..0351dd03b7d0b 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -84,6 +84,7 @@ option</a></li> <li><a href="#dss_indexedmap">"llvm/ADT/IndexedMap.h"</a></li> <li><a href="#dss_densemap">"llvm/ADT/DenseMap.h"</a></li> <li><a href="#dss_valuemap">"llvm/ADT/ValueMap.h"</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_othermap">Other Map-Like Container Options</a></li> </ul></li> @@ -269,9 +270,9 @@ can get, so it will not be discussed in this document.</p> <ol> -<li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++ Library -reference</a> - an excellent reference for the STL and other parts of the -standard C++ library.</li> +<li><a href="http://www.dinkumware.com/manuals/#Standard C++ Library">Dinkumware +C++ Library reference</a> - an excellent reference for the STL and other parts +of the standard C++ library.</li> <li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an O'Reilly book in the making. It has a decent Standard Library @@ -1509,6 +1510,23 @@ a <code>Config</code> parameter to the ValueMap template.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> + <a name="dss_intervalmap">"llvm/ADT/IntervalMap.h"</a> +</div> + +<div class="doc_text"> + +<p> IntervalMap is a compact map for small keys and values. It maps key +intervals instead of single keys, and it will automatically coalesce adjacent +intervals. When then map only contains a few intervals, they are stored in the +map object itself to avoid allocations.</p> + +<p> The IntervalMap iterators are quite big, so they should not be passed around +as STL iterators. The heavyweight iterators allow a smaller data structure.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="dss_map"><map></a> </div> @@ -3838,7 +3856,7 @@ doxygen info: <a href="/doxygen/classllvm_1_1BasicBlock.html">BasicBlock Class</a><br> Superclass: <a href="#Value"><tt>Value</tt></a></p> -<p>This class represents a single entry multiple exit section of the code, +<p>This class represents a single entry single exit section of the code, commonly known as a basic block by the compiler community. The <tt>BasicBlock</tt> class maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block. @@ -3940,7 +3958,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: 2010-08-04 17:59:16 +0200 (Wed, 04 Aug 2010) $ + Last modified: $Date: 2011-02-17 03:19:22 +0100 (Thu, 17 Feb 2011) $ </address> </body> diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 9b6d5e847e942..84298376a7326 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -126,7 +126,7 @@ production-quality compiler for C, Objective-C, C++ and Objective-C++ on x86 <li>Introduced many new warnings, including <code>-Wmissing-field-initializers</code>, <code>-Wshadow</code>, <code>-Wno-protocol</code>, <code>-Wtautological-compare</code>, <code>-Wstrict-selector-match</code>, <code>-Wcast-align</code>, <code>-Wunused</code> improvements, and greatly improved format-string checking.</li> <li>Introduced the "libclang" library, a C interface to Clang intended to support IDE clients.</li> <li>Added support for <code>#pragma GCC visibility</code>, <code>#pragma align</code>, and others.</li> - <li>Added support for SSE, ARM NEON, and Altivec.</li> + <li>Added support for SSE, AVX, ARM NEON, and AltiVec.</li> <li>Improved support for many Microsoft extensions.</li> <li>Implemented support for blocks in C++.</li> <li>Implemented precompiled headers for C++.</li> @@ -269,7 +269,7 @@ support new platforms, new languages, new architectures, and new features. <div class="doc_text"> <p> -<a href="http://libc++.llvm.org/">libc++</a> is another new member of the LLVM +<a href="http://libcxx.llvm.org/">libc++</a> is another new member of the LLVM family. It is an implementation of the C++ standard library, written from the ground up to specifically target the forthcoming C++'0X standard and focus on delivering great performance.</p> @@ -673,7 +673,7 @@ release includes a few major enhancements and additions to the optimizers:</p> be 13 in one of the predecessors of a block. It does this in conjunction with the new LazyValueInfo analysis pass.</li> <li>The new RegionInfo analysis pass identifies single-entry single-exit regions - in the CFG. You can play with it with the "opt -regions analyze" or + in the CFG. You can play with it with the "opt -regions -analyze" or "opt -view-regions" commands.</li> <li>The loop optimizer has significantly improved strength reduction and analysis capabilities. Notably it is able to build on the trap value and signed @@ -879,8 +879,9 @@ it run faster:</p> variables can be accessed via same base address) and potentially reducing register pressure.</li> -<li>The ARM has received many minor improvements and tweaks which lead to -substantially better performance in a wide range of different scenarios.</li> +<li>The ARM backend has received many minor improvements and tweaks which lead + to substantially better performance in a wide range of different scenarios. +</li> <li>The ARM NEON intrinsics have been substantially reworked to reduce redundancy and improve code generation. Some of the major changes are: @@ -1010,6 +1011,17 @@ API changes are:</p> LLVM. The Triple::normalize utility method has been added to help front-ends deal with funky triples. </li> +<li> + The signature of the <tt>GCMetadataPrinter::finishAssembly</tt> virtual + function changed: the <tt>raw_ostream</tt> and <tt>MCAsmInfo</tt> arguments + were dropped. GC plugins which compute stack maps must be updated to avoid + having the old definition overload the new signature. +</li> +<li> + The signature of <tt>MemoryBuffer::getMemBuffer</tt> changed. Unfortunately + calls intended for the old version still compile, but will not work correctly, + leading to a confusing error about an invalid header in the bitcode. +</li> <li> Some APIs were renamed: @@ -1102,7 +1114,7 @@ components, please contact us on the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVMdev list</a>.</p> <ul> -<li>The Alpha, Blackfin, CellSPU, MicroBlaze, MSP430, MIPS, PIC16, SystemZ +<li>The Alpha, Blackfin, CellSPU, MicroBlaze, MSP430, MIPS, SystemZ and XCore backends are experimental.</li> <li><tt>llc</tt> "<tt>-filetype=obj</tt>" is experimental on all targets other than darwin-i386 and darwin-x86_64.</li> @@ -1287,7 +1299,7 @@ lists</a>.</p> src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2010-10-04 22:41:06 +0200 (Mon, 04 Oct 2010) $ + Last modified: $Date: 2010-10-26 14:43:36 +0200 (Tue, 26 Oct 2010) $ </address> </body> diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index 9d82e3ff5c690..186ea4abe732e 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -78,7 +78,7 @@ height="369"> that the LLVM debug information</a> takes, which is useful for those interested in creating front-ends or dealing directly with the information. Further, this document provides specific examples of what debug information - for C/C++.</p> + for C/C++ looks like.</p> </div> @@ -460,15 +460,17 @@ provide details such as name, type and where the variable is defined.</p> <div class="doc_code"> <pre> !3 = metadata !{ - i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) - metadata ;; Reference to context descriptor + i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) + metadata,;; Reference to context descriptor + i32, ;; Line number + i32 ;; Column number } </pre> </div> <p>These descriptors provide debug information about nested blocks within a - subprogram. The array of member descriptors is used to define local - variables and deeper nested blocks.</p> + subprogram. The line number and column numbers are used to dinstinguish + two lexical blocks at same depth. </p> </div> @@ -539,9 +541,9 @@ DW_ATE_unsigned_char = 8 metadata, ;; Name (may be "" for anonymous types) metadata, ;; Reference to file where defined (may be NULL) i32, ;; Line number where defined (may be 0) - i32, ;; Size in bits - i32, ;; Alignment in bits - i32, ;; Offset in bits + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits metadata ;; Reference to type derived from } </pre> @@ -586,9 +588,8 @@ DW_TAG_restrict_type = 55 the bit offset if embedded in a <a href="#format_composite_type">composite type</a>.</p> -<p>Note that the <tt>void *</tt> type is expressed as a - <tt>llvm.dbg.derivedtype.type</tt> with tag of <tt>DW_TAG_pointer_type</tt> - and <tt>NULL</tt> derived type.</p> +<p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL. +</p> </div> @@ -687,7 +688,7 @@ DW_TAG_inheritance = 28 <div class="doc_code"> <pre> -%<a href="#format_subrange">llvm.dbg.subrange.type</a> = type { +!42 = metadata !{ i32, ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type) i64, ;; Low value i64 ;; High value @@ -789,15 +790,12 @@ DW_TAG_return_variable = 258 <div class="doc_text"> <pre> - void %<a href="#format_common_declare">llvm.dbg.declare</a>({}*, metadata) + 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 the alloca for the variable, cast to a <tt>{}*</tt>. The - second argument is - the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing - the description of the variable. </p> - + first argument is metadata holding alloca for the variable.</tt>. The + second argument is metadata containing description of the variable. </p> </div> <!-- ======================================================================= --> @@ -813,10 +811,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 - the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing - the description of the user source variable. </p> - + is written. The third argument is metadata containing description of the + user source variable. </p> </div> <!-- ======================================================================= --> @@ -862,13 +858,13 @@ entry: %Y = alloca i32, align 4 ; <i32*> [#uses=4] %Z = alloca i32, align 4 ; <i32*> [#uses=3] %0 = bitcast i32* %X to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare({}* %0, metadata !0), !dbg !7 + call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7 store i32 21, i32* %X, !dbg !8 %1 = bitcast i32* %Y to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare({}* %1, metadata !9), !dbg !10 + call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10 store i32 22, i32* %Y, !dbg !11 %2 = bitcast i32* %Z to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare({}* %2, metadata !12), !dbg !14 + call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14 store i32 23, i32* %Z, !dbg !15 %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1] %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1] @@ -879,7 +875,7 @@ entry: ret void, !dbg !18 } -declare void @llvm.dbg.declare({}*, metadata) nounwind readnone +declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone !0 = metadata !{i32 459008, metadata !1, metadata !"X", metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ] @@ -921,7 +917,7 @@ declare void @llvm.dbg.declare({}*, metadata) nounwind readnone <div class="doc_code"> <pre> -call void @llvm.dbg.declare({}* %0, metadata !0), !dbg !7 +call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7 </pre> </div> @@ -956,7 +952,7 @@ call void @llvm.dbg.declare({}* %0, metadata !0), !dbg !7 <div class="doc_code"> <pre> -call void @llvm.dbg.declare({}* %2, metadata !12), !dbg !14 +call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14 </pre> </div> @@ -1780,7 +1776,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: 2010-07-13 18:53:20 +0200 (Tue, 13 Jul 2010) $ + Last modified: $Date: 2011-02-03 01:22:17 +0100 (Thu, 03 Feb 2011) $ </address> </body> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 0bdb6dd62c53e..d118332c99393 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -405,8 +405,6 @@ which case the user must specify it explicitly.</dd> the symbol table. If the type of 'a' does not match <em>type</em>, TableGen aborts with an error. !cast<string> is a special case in that the argument must be an object defined by a 'def' construct.</dd> -<dt><tt>!nameconcat<type>(a, b)</tt></dt> - <dd>Shorthand for !cast<type>(!strconcat(a, b))</dd> <dt><tt>!subst(a, b, c)</tt></dt> <dd>If 'a' and 'b' are of string type or are symbol references, substitute 'b' for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.</dd> @@ -414,18 +412,18 @@ be an object defined by a 'def' construct.</dd> <dd>For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy variable that should be declared as a member variable of an instantiated class. This operation is analogous to $(foreach) in GNU make.</dd> -<dt><tt>!car(a)</tt></dt> +<dt><tt>!head(a)</tt></dt> <dd>The first element of list 'a.'</dd> -<dt><tt>!cdr(a)</tt></dt> +<dt><tt>!tail(a)</tt></dt> <dd>The 2nd-N elements of list 'a.'</dd> -<dt><tt>!null(a)</tt></dt> +<dt><tt>!empty(a)</tt></dt> <dd>An integer {0,1} indicating whether list 'a' is empty.</dd> <dt><tt>!if(a,b,c)</tt></dt> <dd>'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.</dd> <dt><tt>!eq(a,b)</tt></dt> - <dd>Integer one if string a is equal to string b, zero otherwise. This - only operates on string, int and bit objects. Use !cast<string> to + <dd>'bit 1' if string a is equal to string b, 0 otherwise. This + only operates on string, int and bit objects. Use !cast<string> to compare other types of objects.</dd> </dl> @@ -844,8 +842,7 @@ more ways to factor out commonality from the records, specially if using several levels of multiclass instanciations. This also avoids the need of using "let" expressions within subsequent records inside a multiclass.</p> -<div class="doc_code"> -<pre> +<pre class="doc_code"> <b>multiclass </b>basic_r<bits<4> opc> { <b>let </b>Predicates = [HasSSE2] in { <b>def </b>rr : Instruction<opc, "rr">; @@ -871,16 +868,17 @@ several levels of multiclass instanciations. This also avoids the need of using <div class="doc_section"><a name="codegen">Code Generator backend info</a></div> <!-- *********************************************************************** --> +<div class="doc_text"> + <p>Expressions used by code generator to describe instructions and isel patterns:</p> -<div class="doc_text"> - +<dl> <dt><tt>(implicit a)</tt></dt> <dd>an implicitly defined physical register. This tells the dag instruction selection emitter the input pattern's extra definitions matches implicit physical register definitions.</dd> - +</dl> </div> <!-- *********************************************************************** --> @@ -906,7 +904,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: 2010-06-21 22:35:09 +0200 (Mon, 21 Jun 2010) $ + Last modified: $Date: 2011-01-07 18:05:37 +0100 (Fri, 07 Jan 2011) $ </address> </body> diff --git a/docs/TestingGuide.html b/docs/TestingGuide.html index c7353ebb0d436..964bdc31247d4 100644 --- a/docs/TestingGuide.html +++ b/docs/TestingGuide.html @@ -18,12 +18,14 @@ <ul> <li><a href="#regressiontests">Regression tests</a></li> <li><a href="#testsuite">Test suite</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> <li><a href="#rtstructure">Regression test structure</a> @@ -40,7 +42,7 @@ <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 llvm-test</a></li> + <li><a href="#testsuitecustom">Writing custom tests for test-suite</a></li> </ul> </li> </ol> @@ -141,6 +143,23 @@ generates code.</p> </div> +<!-- _______________________________________________________________________ --> +<div class="doc_subsection"><a name="debuginfotests">Debugging Information +tests</a></div> +<!-- _______________________________________________________________________ --> + +<div class="doc_text"> + +<p>The test suite contains tests to check quality of debugging information. +The test are written in C based languages or in LLVM assembly language. </p> + +<p>These tests are compiled and run under a debugger. The debugger output +is checked to validate of debugging information. See README.txt in the +test suite for more information . This test suite is located in the +<tt>debuginfo-tests</tt> Subversion module. </p> + +</div> + <!--=========================================================================--> <div class="doc_section"><a name="quick">Quick start</a></div> <!--=========================================================================--> @@ -153,7 +172,7 @@ generates code.</p> 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 -then the default "test-suite", for then the test suite will be run every time +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. @@ -237,7 +256,7 @@ programs), first checkout and setup the <tt>test-suite</tt> module:</p> </div> <p>where <tt>$LLVM_GCC_DIR</tt> is the directory where -you <em>installed</em> llvm-gcc, not it's src or obj +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++ @@ -272,6 +291,25 @@ that subdirectory.</p> </div> +<!-- _______________________________________________________________________ --> +<div class="doc_subsection"><a name="quickdebuginfotests">Debugging Information +tests</a></div> +<!-- _______________________________________________________________________ --> + +<p> To run debugging information tests simply checkout the tests inside +clang/test directory. </p> + +<div class="doc_code"> +<pre> +%cd clang/test +% svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests +</pre> +</div> + +<p> These tests are already set up to run as part of clang regression tests.</p> + +</div> + <!--=========================================================================--> <div class="doc_section"><a name="rtstructure">Regression test structure</a></div> <!--=========================================================================--> @@ -338,6 +376,11 @@ that subdirectory.</p> shell. Consequently the syntax differs from normal shell script syntax in a few ways. You can specify as many RUN lines as needed.</p> + <p>lit performs substitution on each RUN line to replace LLVM tool + names with the full paths to the executable built for each tool (in + $(LLVM_OBJ_ROOT)/$(BuildMode)/bin). This ensures that lit does not + invoke any stray LLVM tools in the user's path during testing.</p> + <p>Each RUN line is executed on its own, distinct from other lines unless its last character is <tt>\</tt>. This continuation character causes the RUN line to be concatenated with the next one. In this way you can build up long @@ -561,7 +604,7 @@ name="FileCheck-CHECK-NEXT">The "CHECK-NEXT:" directive</a></div> <div class="doc_text"> <p>Sometimes you want to match lines and would like to verify that matches -happen on exactly consequtive lines with no other lines in between them. In +happen on exactly consecutive lines with no other lines in between them. In this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If you specified a custom check prefix, just use "<PREFIX>-NEXT:". For example, something like this works as you'd expect:</p> @@ -870,34 +913,34 @@ 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>llvm-test</tt> directory also +<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>llvm-test</tt> tests are divided into three types of tests: MultiSource, +<p><tt>test-suite</tt> tests are divided into three types of tests: MultiSource, SingleSource, and External.</p> <ul> -<li><tt>llvm-test/SingleSource</tt> +<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>llvm-test/MultiSource</tt> +<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>llvm-test/External</tt> +<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 llvm-test +location of these external programs is configured by the test-suite <tt>configure</tt> script.</p></li> </ul> @@ -1084,9 +1127,9 @@ many times it triggers. First thing you should do is add an LLVM 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, an +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 an "<tt>llvm-test/TEST.XXX.report</tt>" file that indicates how to +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> @@ -1147,7 +1190,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: 2010-08-02 03:20:23 +0200 (Mon, 02 Aug 2010) $ + Last modified: $Date: 2011-02-15 10:23:02 +0100 (Tue, 15 Feb 2011) $ </address> </body> </html> diff --git a/docs/UsingLibraries.html b/docs/UsingLibraries.html index e7a1d3d4b60f9..ea28dbec0cc42 100644 --- a/docs/UsingLibraries.html +++ b/docs/UsingLibraries.html @@ -23,7 +23,11 @@ <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, please see <a href="CommandGuide/html/llvm-config.html">llvm-config</a> for more information.</p> +<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> <!-- ======================================================================= --> <div class="doc_section"><a name="abstract">Abstract</a></div> @@ -432,7 +436,7 @@ <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> </address> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> -<br>Last modified: $Date: 2010-05-07 02:28:04 +0200 (Fri, 07 May 2010) $ </div> +<br>Last modified: $Date: 2010-09-17 02:30:52 +0200 (Fri, 17 Sep 2010) $ </div> </body> </html> <!-- vim: sw=2 ts=2 ai diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index 2dc0ef772cca2..193a1d4d68c98 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -1825,7 +1825,7 @@ register to convert the floating-point value to an integer. static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &DAG) { assert(Op.getValueType() == MVT::i32); Op = DAG.getNode(SPISD::FTOI, MVT::f32, Op.getOperand(0)); - return DAG.getNode(ISD::BIT_CONVERT, MVT::i32, Op); + return DAG.getNode(ISD::BITCAST, MVT::i32, Op); } </pre> </div> @@ -2549,7 +2549,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: 2010-07-17 00:35:46 +0200 (Sat, 17 Jul 2010) $ + Last modified: $Date: 2010-11-23 04:31:01 +0100 (Tue, 23 Nov 2010) $ </address> </body> diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html index 1a6edcfc59f3d..80258e428352b 100644 --- a/docs/WritingAnLLVMPass.html +++ b/docs/WritingAnLLVMPass.html @@ -51,6 +51,14 @@ <li><a href="#doFinalization_loop">The <tt>doFinalization() </tt> method</a></li> </ul></li> + <li><a href="#RegionPass">The <tt>RegionPass</tt> class</a> + <ul> + <li><a href="#doInitialization_region">The <tt>doInitialization(Region *, + RGPassManager &)</tt> method</a></li> + <li><a href="#runOnRegion">The <tt>runOnRegion</tt> method</a></li> + <li><a href="#doFinalization_region">The <tt>doFinalization() + </tt> method</a></li> + </ul></li> <li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a> <ul> <li><a href="#doInitialization_fn">The <tt>doInitialization(Function @@ -134,6 +142,7 @@ the <tt><a href="#ModulePass">ModulePass</a></tt>, <tt><a href="#CallGraphSCCPass">CallGraphSCCPass</a></tt>, <tt><a href="#FunctionPass">FunctionPass</a></tt>, or <tt><a href="#LoopPass">LoopPass</a></tt>, or <tt><a +href="#RegionPass">RegionPass</a></tt>, or <tt><a href="#BasicBlockPass">BasicBlockPass</a></tt> classes, which gives the system more information about what your pass does, and how it can be combined with other passes. One of the main features of the LLVM Pass Framework is that it @@ -169,9 +178,11 @@ source tree in the <tt>lib/Transforms/Hello</tt> directory.</p> <div class="doc_text"> - <p>First, you need to create a new directory somewhere in the LLVM source + <p>First, configure and build LLVM. This needs to be done directly inside the + LLVM source tree rather than in a separate objects directory. + Next, you need to create a new directory somewhere in the LLVM source base. For this example, we'll assume that you made - <tt>lib/Transforms/Hello</tt>. Next, you must set up a build script + <tt>lib/Transforms/Hello</tt>. Finally, you must set up a build script (Makefile) that will compile the source code for the new pass. To do this, copy the following into <tt>Makefile</tt>:</p> <hr/> @@ -194,8 +205,8 @@ include $(LEVEL)/Makefile.common </pre></div> <p>This makefile specifies that all of the <tt>.cpp</tt> files in the current -directory are to be compiled and linked together into a -<tt>Debug+Asserts/lib/Hello.so</tt> shared object that can be dynamically loaded by +directory are to be compiled and linked together into a shared object +<tt>$(LEVEL)/Debug+Asserts/lib/Hello.so</tt> that can be dynamically loaded by the <tt>opt</tt> or <tt>bugpoint</tt> tools via their <tt>-load</tt> options. If your operating system uses a suffix other than .so (such as windows or Mac OS/X), the appropriate extension will be used.</p> @@ -262,7 +273,7 @@ time.</p> <div class="doc_code"><pre> static char ID; - Hello() : FunctionPass(&ID) {} + Hello() : FunctionPass(ID) {} </pre></div><p> <p> This declares pass identifier used by LLVM to identify pass. This allows LLVM to @@ -290,7 +301,7 @@ function.</p> initialization value is not important.</p> <div class="doc_code"><pre> - INITIALIZE_PASS(Hello, "<i>hello</i>", "<i>Hello World Pass</i>", + static RegisterPass<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>", false /* Only looks at CFG */, false /* Analysis Pass */); } <i>// end of anonymous namespace</i> @@ -317,7 +328,7 @@ is supplied as fourth argument. </p> <b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> { static char ID; - Hello() : FunctionPass(&ID) {} + Hello() : FunctionPass(ID) {} <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) { errs() << "<i>Hello: </i>" << F.getName() << "\n"; @@ -326,14 +337,15 @@ is supplied as fourth argument. </p> }; char Hello::ID = 0; - INITIALIZE_PASS(Hello, "<i>Hello</i>", "<i>Hello World Pass</i>", false, false); + static RegisterPass<Hello> X("hello", "Hello World Pass", false, false); } </pre></div> <p>Now that it's all together, compile the file with a simple "<tt>gmake</tt>" -command in the local directory and you should get a new -"<tt>Debug+Asserts/lib/Hello.so</tt> file. Note that everything in this file is +command in the local directory and you should get a new file +"<tt>Debug+Asserts/lib/Hello.so</tt>" under the top level directory of the LLVM +source tree (not in the local directory). Note that everything in this file is contained in an anonymous namespace: this reflects the fact that passes are self contained units that do not need external interfaces (although they can have them) to be useful.</p> @@ -349,7 +361,7 @@ them) to be useful.</p> <p>Now that you have a brand new shiny shared object file, we can use the <tt>opt</tt> command to run an LLVM program through your pass. Because you -registered your pass with the <tt>INITIALIZE_PASS</tt> macro, you will be able to +registered your pass with <tt>RegisterPass</tt>, you will be able to use the <tt>opt</tt> tool to access it, once loaded.</p> <p>To test it, follow the example at the end of the <a @@ -547,11 +559,9 @@ href="#BasicBlockPass">BasicBlockPass</a></tt>, you should derive from <ol> -<li>... <em>not allowed</em> to modify any <tt>Function</tt>s that are not in -the current SCC.</li> - -<li>... <em>not allowed</em> to inspect any Function's other than those in the -current SCC and the direct callees of the SCC.</li> +<li>... <em>not allowed</em> to inspect or modify any <tt>Function</tt>s other +than those in the current SCC and the direct callers and direct callees of the +SCC.</li> <li>... <em>required</em> to preserve the current CallGraph object, updating it to reflect any changes made to the program.</li> @@ -805,6 +815,84 @@ program being compiled. </p> </div> +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="RegionPass">The <tt>RegionPass</tt> class </a> +</div> + +<div class="doc_text"> + +<p> <tt>RegionPass</tt> is similar to <a href="#LoopPass"><tt>LoopPass</tt></a>, +but executes on each single entry single exit region in the function. +<tt>RegionPass</tt> processes regions in nested order such that the outer most +region is processed last. </p> + +<p> <tt>RegionPass</tt> subclasses are allowed to update the region tree by using +the <tt>RGPassManager</tt> interface. You may overload three virtual methods of +<tt>RegionPass</tt> to implementing your own region pass is usually. All these +methods should return true if they modified the program, or false if they didn not. +</p> +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="doInitialization_region">The <tt>doInitialization(Region *, + RGPassManager &)</tt> + method</a> +</div> + +<div class="doc_text"> + +<div class="doc_code"><pre> + <b>virtual bool</b> doInitialization(Region *, RGPassManager &RGM); +</pre></div> + +<p>The <tt>doInitialization</tt> method is designed to do simple initialization +type of stuff that does not depend on the functions being processed. The +<tt>doInitialization</tt> method call is not scheduled to overlap with any +other pass executions (thus it should be very fast). RPPassManager +interface should be used to access Function or Module level analysis +information.</p> + +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="runOnRegion">The <tt>runOnRegion</tt> method</a> +</div> + +<div class="doc_text"> + +<div class="doc_code"><pre> + <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 +the transformation or analysis work of your pass. As usual, a true value should +be returned if the region is modified. <tt>RGPassManager</tt> interface +should be used to update region tree.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="doFinalization_region">The <tt>doFinalization()</tt> method</a> +</div> + +<div class="doc_text"> + +<div class="doc_code"><pre> + <b>virtual bool</b> doFinalization(); +</pre></div> + +<p>The <tt>doFinalization</tt> method is an infrequently used method that is +called when the pass framework has finished calling <a +href="#runOnRegion"><tt>runOnRegion</tt></a> for every region in the +program being compiled. </p> + +</div> + <!-- ======================================================================= --> @@ -967,10 +1055,10 @@ remember, you may not modify the LLVM <tt>Function</tt> or its contents from a pass registration works, and discussed some of the reasons that it is used and what it does. Here we discuss how and why passes are registered.</p> -<p>As we saw above, passes are registered with the <b><tt>INITIALIZE_PASS</tt></b> -macro. The first parameter is the name of the pass that is to be used on +<p>As we saw above, passes are registered with the <b><tt>RegisterPass</tt></b> +template. The template parameter is the name of the pass that is to be used on the command line to specify that the pass should be added to a program (for -example, with <tt>opt</tt> or <tt>bugpoint</tt>). The second argument is the +example, with <tt>opt</tt> or <tt>bugpoint</tt>). The first argument is the name of the pass, which is to be used for the <tt>-help</tt> output of programs, as well as for debug output generated by the <tt>--debug-pass</tt> option.</p> @@ -1386,7 +1474,7 @@ results as soon as they are no longer needed.</li> <li><b>Pipeline the execution of passes on the program</b> - The <tt>PassManager</tt> attempts to get better cache and memory usage behavior out of a series of passes by pipelining the passes together. This means that, given -a series of consequtive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it +a series of consecutive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it will execute all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s on the first function, then all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>es on the second function, @@ -1833,7 +1921,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: 2010-07-22 01:07:00 +0200 (Thu, 22 Jul 2010) $ + Last modified: $Date: 2011-02-15 10:23:02 +0100 (Tue, 15 Feb 2011) $ </address> </body> diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html index 6cd33b010adc4..a320ff7e9064f 100644 --- a/docs/tutorial/LangImpl3.html +++ b/docs/tutorial/LangImpl3.html @@ -353,8 +353,8 @@ above.</p> </div> <p>The Module symbol table works just like the Function symbol table when it -comes to name conflicts: if a new function is created with a name was previously -added to the symbol table, it will get implicitly renamed when added to the +comes to name conflicts: if a new function is created with a name that was previously +added to the symbol table, the new function will get implicitly renamed when added to the Module. The code above exploits this fact to determine if there was a previous definition of this function.</p> @@ -1263,7 +1263,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: 2010-09-01 22:09:20 +0200 (Wed, 01 Sep 2010) $ + Last modified: $Date: 2011-02-15 01:24:32 +0100 (Tue, 15 Feb 2011) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html index d286364d2a561..a2511d959e7b9 100644 --- a/docs/tutorial/LangImpl4.html +++ b/docs/tutorial/LangImpl4.html @@ -176,6 +176,8 @@ add a set of optimizations to run. The code looks like this:</p> // Set up the optimizer pipeline. Start with registering info about how the // target lays out data structures. OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Provide basic AliasAnalysis support for GVN. + OurFPM.add(createBasicAliasAnalysisPass()); // Do simple "peephole" optimizations and bit-twiddling optzns. OurFPM.add(createInstructionCombiningPass()); // Reassociate expressions. @@ -507,6 +509,7 @@ at runtime.</p> #include "llvm/Module.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" +#include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" @@ -1086,6 +1089,8 @@ int main() { // Set up the optimizer pipeline. Start with registering info about how the // target lays out data structures. OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Provide basic AliasAnalysis support for GVN. + OurFPM.add(createBasicAliasAnalysisPass()); // Do simple "peephole" optimizations and bit-twiddling optzns. OurFPM.add(createInstructionCombiningPass()); // Reassociate expressions. @@ -1126,7 +1131,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: 2010-06-14 08:09:39 +0200 (Mon, 14 Jun 2010) $ + Last modified: $Date: 2010-11-16 18:28:22 +0100 (Tue, 16 Nov 2010) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html index 4450f2e3a11af..d2c3bd03dc4ec 100644 --- a/docs/tutorial/LangImpl5.html +++ b/docs/tutorial/LangImpl5.html @@ -907,6 +907,7 @@ if/then/else and for expressions.. To build this example, use: #include "llvm/Module.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" +#include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" @@ -1731,6 +1732,8 @@ int main() { // Set up the optimizer pipeline. Start with registering info about how the // target lays out data structures. OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Provide basic AliasAnalysis support for GVN. + OurFPM.add(createBasicAliasAnalysisPass()); // Do simple "peephole" optimizations and bit-twiddling optzns. OurFPM.add(createInstructionCombiningPass()); // Reassociate expressions. @@ -1771,7 +1774,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: 2010-09-01 22:09:20 +0200 (Wed, 01 Sep 2010) $ + Last modified: $Date: 2010-11-16 18:28:22 +0100 (Tue, 16 Nov 2010) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html index c6a0b8a7d603f..7ddf3a099cbc3 100644 --- a/docs/tutorial/LangImpl6.html +++ b/docs/tutorial/LangImpl6.html @@ -826,6 +826,7 @@ if/then/else and for expressions.. To build this example, use: #include "llvm/Module.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" +#include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" @@ -1768,6 +1769,8 @@ int main() { // Set up the optimizer pipeline. Start with registering info about how the // target lays out data structures. OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Provide basic AliasAnalysis support for GVN. + OurFPM.add(createBasicAliasAnalysisPass()); // Do simple "peephole" optimizations and bit-twiddling optzns. OurFPM.add(createInstructionCombiningPass()); // Reassociate expressions. @@ -1808,7 +1811,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: 2010-09-01 22:09:20 +0200 (Wed, 01 Sep 2010) $ + Last modified: $Date: 2010-11-16 18:28:22 +0100 (Tue, 16 Nov 2010) $ </address> </body> </html> diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html index 1ec99b15bf5c6..3b36129d67163 100644 --- a/docs/tutorial/LangImpl7.html +++ b/docs/tutorial/LangImpl7.html @@ -1009,6 +1009,7 @@ variables and var/in support. To build this example, use: #include "llvm/Module.h" #include "llvm/PassManager.h" #include "llvm/Analysis/Verifier.h" +#include "llvm/Analysis/Passes.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetSelect.h" #include "llvm/Transforms/Scalar.h" @@ -2116,6 +2117,8 @@ int main() { // Set up the optimizer pipeline. Start with registering info about how the // target lays out data structures. OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData())); + // Provide basic AliasAnalysis support for GVN. + OurFPM.add(createBasicAliasAnalysisPass()); // Promote allocas to registers. OurFPM.add(createPromoteMemoryToRegisterPass()); // Do simple "peephole" optimizations and bit-twiddling optzns. @@ -2158,7 +2161,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: 2010-09-01 22:09:20 +0200 (Wed, 01 Sep 2010) $ + Last modified: $Date: 2010-11-16 18:28:22 +0100 (Tue, 16 Nov 2010) $ </address> </body> </html> diff --git a/docs/tutorial/OCamlLangImpl7.html b/docs/tutorial/OCamlLangImpl7.html index ac31fbfc0766f..a9fcd704cf8b5 100644 --- a/docs/tutorial/OCamlLangImpl7.html +++ b/docs/tutorial/OCamlLangImpl7.html @@ -30,7 +30,7 @@ <li><a href="#code">Full Code Listing</a></li> </ol> </li> -<li><a href="LangImpl8.html">Chapter 8</a>: Conclusion and other useful LLVM +<li><a href="OCamlLangImpl8.html">Chapter 8</a>: Conclusion and other useful LLVM tidbits</li> </ul> @@ -1901,7 +1901,7 @@ extern double printd(double X) { <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> <a href="mailto:idadesub@users.sourceforge.net">Erick Tryzelaar</a><br> - Last modified: $Date: 2010-05-28 19:07:41 +0200 (Fri, 28 May 2010) $ + Last modified: $Date: 2011-01-01 04:27:43 +0100 (Sat, 01 Jan 2011) $ </address> </body> </html> diff --git a/docs/tutorial/OCamlLangImpl8.html b/docs/tutorial/OCamlLangImpl8.html new file mode 100644 index 0000000000000..64a62002c4ccd --- /dev/null +++ b/docs/tutorial/OCamlLangImpl8.html @@ -0,0 +1,365 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> + +<html> +<head> + <title>Kaleidoscope: Conclusion and other useful LLVM tidbits</title> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <meta name="author" content="Chris Lattner"> + <link rel="stylesheet" href="../llvm.css" type="text/css"> +</head> + +<body> + +<div class="doc_title">Kaleidoscope: Conclusion and other useful LLVM + tidbits</div> + +<ul> +<li><a href="index.html">Up to Tutorial Index</a></li> +<li>Chapter 8 + <ol> + <li><a href="#conclusion">Tutorial Conclusion</a></li> + <li><a href="#llvmirproperties">Properties of LLVM IR</a> + <ul> + <li><a href="#targetindep">Target Independence</a></li> + <li><a href="#safety">Safety Guarantees</a></li> + <li><a href="#langspecific">Language-Specific Optimizations</a></li> + </ul> + </li> + <li><a href="#tipsandtricks">Tips and Tricks</a> + <ul> + <li><a href="#offsetofsizeof">Implementing portable + offsetof/sizeof</a></li> + <li><a href="#gcstack">Garbage Collected Stack Frames</a></li> + </ul> + </li> + </ol> +</li> +</ul> + + +<div class="doc_author"> + <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"><a name="conclusion">Tutorial Conclusion</a></div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>Welcome to the the final chapter of the "<a href="index.html">Implementing a +language with LLVM</a>" tutorial. In the course of this tutorial, we have grown +our little Kaleidoscope language from being a useless toy, to being a +semi-interesting (but probably still useless) toy. :)</p> + +<p>It is interesting to see how far we've come, and how little code it has +taken. We built the entire lexer, parser, AST, code generator, and an +interactive run-loop (with a JIT!) by-hand in under 700 lines of +(non-comment/non-blank) code.</p> + +<p>Our little language supports a couple of interesting features: it supports +user defined binary and unary operators, it uses JIT compilation for immediate +evaluation, and it supports a few control flow constructs with SSA construction. +</p> + +<p>Part of the idea of this tutorial was to show you how easy and fun it can be +to define, build, and play with languages. Building a compiler need not be a +scary or mystical process! Now that you've seen some of the basics, I strongly +encourage you to take the code and hack on it. For example, try adding:</p> + +<ul> +<li><b>global variables</b> - While global variables have questional value in +modern software engineering, they are often useful when putting together quick +little hacks like the Kaleidoscope compiler itself. Fortunately, our current +setup makes it very easy to add global variables: just have value lookup check +to see if an unresolved variable is in the global variable symbol table before +rejecting it. To create a new global variable, make an instance of the LLVM +<tt>GlobalVariable</tt> class.</li> + +<li><b>typed variables</b> - Kaleidoscope currently only supports variables of +type double. This gives the language a very nice elegance, because only +supporting one type means that you never have to specify types. Different +languages have different ways of handling this. The easiest way is to require +the user to specify types for every variable definition, and record the type +of the variable in the symbol table along with its Value*.</li> + +<li><b>arrays, structs, vectors, etc</b> - Once you add types, you can start +extending the type system in all sorts of interesting ways. Simple arrays are +very easy and are quite useful for many different applications. Adding them is +mostly an exercise in learning how the LLVM <a +href="../LangRef.html#i_getelementptr">getelementptr</a> instruction works: it +is so nifty/unconventional, it <a +href="../GetElementPtr.html">has its own FAQ</a>! If you add support +for recursive types (e.g. linked lists), make sure to read the <a +href="../ProgrammersManual.html#TypeResolve">section in the LLVM +Programmer's Manual</a> that describes how to construct them.</li> + +<li><b>standard runtime</b> - Our current language allows the user to access +arbitrary external functions, and we use it for things like "printd" and +"putchard". As you extend the language to add higher-level constructs, often +these constructs make the most sense if they are lowered to calls into a +language-supplied runtime. For example, if you add hash tables to the language, +it would probably make sense to add the routines to a runtime, instead of +inlining them all the way.</li> + +<li><b>memory management</b> - Currently we can only access the stack in +Kaleidoscope. It would also be useful to be able to allocate heap memory, +either with calls to the standard libc malloc/free interface or with a garbage +collector. If you would like to use garbage collection, note that LLVM fully +supports <a href="../GarbageCollection.html">Accurate Garbage Collection</a> +including algorithms that move objects and need to scan/update the stack.</li> + +<li><b>debugger support</b> - LLVM supports generation of <a +href="../SourceLevelDebugging.html">DWARF Debug info</a> which is understood by +common debuggers like GDB. Adding support for debug info is fairly +straightforward. The best way to understand it is to compile some C/C++ code +with "<tt>llvm-gcc -g -O0</tt>" and taking a look at what it produces.</li> + +<li><b>exception handling support</b> - LLVM supports generation of <a +href="../ExceptionHandling.html">zero cost exceptions</a> which interoperate +with code compiled in other languages. You could also generate code by +implicitly making every function return an error value and checking it. You +could also make explicit use of setjmp/longjmp. There are many different ways +to go here.</li> + +<li><b>object orientation, generics, database access, complex numbers, +geometric programming, ...</b> - Really, there is +no end of crazy features that you can add to the language.</li> + +<li><b>unusual domains</b> - We've been talking about applying LLVM to a domain +that many people are interested in: building a compiler for a specific language. +However, there are many other domains that can use compiler technology that are +not typically considered. For example, LLVM has been used to implement OpenGL +graphics acceleration, translate C++ code to ActionScript, and many other +cute and clever things. Maybe you will be the first to JIT compile a regular +expression interpreter into native code with LLVM?</li> + +</ul> + +<p> +Have fun - try doing something crazy and unusual. Building a language like +everyone else always has, is much less fun than trying something a little crazy +or off the wall and seeing how it turns out. If you get stuck or want to talk +about it, feel free to email the <a +href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev mailing +list</a>: it has lots of people who are interested in languages and are often +willing to help out. +</p> + +<p>Before we end this tutorial, I want to talk about some "tips and tricks" for generating +LLVM IR. These are some of the more subtle things that may not be obvious, but +are very useful if you want to take advantage of LLVM's capabilities.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"><a name="llvmirproperties">Properties of the LLVM +IR</a></div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>We have a couple common questions about code in the LLVM IR form - lets just +get these out of the way right now, shall we?</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="targetindep">Target +Independence</a></div> +<!-- ======================================================================= --> + +<div class="doc_text"> + +<p>Kaleidoscope is an example of a "portable language": any program written in +Kaleidoscope will work the same way on any target that it runs on. Many other +languages have this property, e.g. lisp, java, haskell, javascript, python, etc +(note that while these languages are portable, not all their libraries are).</p> + +<p>One nice aspect of LLVM is that it is often capable of preserving target +independence in the IR: you can take the LLVM IR for a Kaleidoscope-compiled +program and run it on any target that LLVM supports, even emitting C code and +compiling that on targets that LLVM doesn't support natively. You can trivially +tell that the Kaleidoscope compiler generates target-independent code because it +never queries for any target-specific information when generating code.</p> + +<p>The fact that LLVM provides a compact, target-independent, representation for +code gets a lot of people excited. Unfortunately, these people are usually +thinking about C or a language from the C family when they are asking questions +about language portability. I say "unfortunately", because there is really no +way to make (fully general) C code portable, other than shipping the source code +around (and of course, C source code is not actually portable in general +either - ever port a really old application from 32- to 64-bits?).</p> + +<p>The problem with C (again, in its full generality) is that it is heavily +laden with target specific assumptions. As one simple example, the preprocessor +often destructively removes target-independence from the code when it processes +the input text:</p> + +<div class="doc_code"> +<pre> +#ifdef __i386__ + int X = 1; +#else + int X = 42; +#endif +</pre> +</div> + +<p>While it is possible to engineer more and more complex solutions to problems +like this, it cannot be solved in full generality in a way that is better than shipping +the actual source code.</p> + +<p>That said, there are interesting subsets of C that can be made portable. If +you are willing to fix primitive types to a fixed size (say int = 32-bits, +and long = 64-bits), don't care about ABI compatibility with existing binaries, +and are willing to give up some other minor features, you can have portable +code. This can make sense for specialized domains such as an +in-kernel language.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="safety">Safety Guarantees</a></div> +<!-- ======================================================================= --> + +<div class="doc_text"> + +<p>Many of the languages above are also "safe" languages: it is impossible for +a program written in Java to corrupt its address space and crash the process +(assuming the JVM has no bugs). +Safety is an interesting property that requires a combination of language +design, runtime support, and often operating system support.</p> + +<p>It is certainly possible to implement a safe language in LLVM, but LLVM IR +does not itself guarantee safety. The LLVM IR allows unsafe pointer casts, +use after free bugs, buffer over-runs, and a variety of other problems. Safety +needs to be implemented as a layer on top of LLVM and, conveniently, several +groups have investigated this. Ask on the <a +href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev mailing +list</a> if you are interested in more details.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="langspecific">Language-Specific +Optimizations</a></div> +<!-- ======================================================================= --> + +<div class="doc_text"> + +<p>One thing about LLVM that turns off many people is that it does not solve all +the world's problems in one system (sorry 'world hunger', someone else will have +to solve you some other day). One specific complaint is that people perceive +LLVM as being incapable of performing high-level language-specific optimization: +LLVM "loses too much information".</p> + +<p>Unfortunately, this is really not the place to give you a full and unified +version of "Chris Lattner's theory of compiler design". Instead, I'll make a +few observations:</p> + +<p>First, you're right that LLVM does lose information. For example, as of this +writing, there is no way to distinguish in the LLVM IR whether an SSA-value came +from a C "int" or a C "long" on an ILP32 machine (other than debug info). Both +get compiled down to an 'i32' value and the information about what it came from +is lost. The more general issue here, is that the LLVM type system uses +"structural equivalence" instead of "name equivalence". Another place this +surprises people is if you have two types in a high-level language that have the +same structure (e.g. two different structs that have a single int field): these +types will compile down into a single LLVM type and it will be impossible to +tell what it came from.</p> + +<p>Second, while LLVM does lose information, LLVM is not a fixed target: we +continue to enhance and improve it in many different ways. In addition to +adding new features (LLVM did not always support exceptions or debug info), we +also extend the IR to capture important information for optimization (e.g. +whether an argument is sign or zero extended, information about pointers +aliasing, etc). Many of the enhancements are user-driven: people want LLVM to +include some specific feature, so they go ahead and extend it.</p> + +<p>Third, it is <em>possible and easy</em> to add language-specific +optimizations, and you have a number of choices in how to do it. As one trivial +example, it is easy to add language-specific optimization passes that +"know" things about code compiled for a language. In the case of the C family, +there is an optimization pass that "knows" about the standard C library +functions. If you call "exit(0)" in main(), it knows that it is safe to +optimize that into "return 0;" because C specifies what the 'exit' +function does.</p> + +<p>In addition to simple library knowledge, it is possible to embed a variety of +other language-specific information into the LLVM IR. If you have a specific +need and run into a wall, please bring the topic up on the llvmdev list. At the +very worst, you can always treat LLVM as if it were a "dumb code generator" and +implement the high-level optimizations you desire in your front-end, on the +language-specific AST. +</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"><a name="tipsandtricks">Tips and Tricks</a></div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>There is a variety of useful tips and tricks that you come to know after +working on/with LLVM that aren't obvious at first glance. Instead of letting +everyone rediscover them, this section talks about some of these issues.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="offsetofsizeof">Implementing portable +offsetof/sizeof</a></div> +<!-- ======================================================================= --> + +<div class="doc_text"> + +<p>One interesting thing that comes up, if you are trying to keep the code +generated by your compiler "target independent", is that you often need to know +the size of some LLVM type or the offset of some field in an llvm structure. +For example, you might need to pass the size of a type into a function that +allocates memory.</p> + +<p>Unfortunately, this can vary widely across targets: for example the width of +a pointer is trivially target-specific. However, there is a <a +href="http://nondot.org/sabre/LLVMNotes/SizeOf-OffsetOf-VariableSizedStructs.txt">clever +way to use the getelementptr instruction</a> that allows you to compute this +in a portable way.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsubsection"><a name="gcstack">Garbage Collected +Stack Frames</a></div> +<!-- ======================================================================= --> + +<div class="doc_text"> + +<p>Some languages want to explicitly manage their stack frames, often so that +they are garbage collected or to allow easy implementation of closures. There +are often better ways to implement these features than explicit stack frames, +but <a +href="http://nondot.org/sabre/LLVMNotes/ExplicitlyManagedStackFrames.txt">LLVM +does support them,</a> if you want. It requires your front-end to convert the +code into <a +href="http://en.wikipedia.org/wiki/Continuation-passing_style">Continuation +Passing Style</a> and the use of tail calls (which LLVM also supports).</p> + +</div> + +<!-- *********************************************************************** --> +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a> + + <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> + <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> +</body> +</html> diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html index 250b533f3f8a7..11dd5e2d732a5 100644 --- a/docs/tutorial/index.html +++ b/docs/tutorial/index.html @@ -35,7 +35,7 @@ <li><a href="OCamlLangImpl5.html">Extending the language: control flow</a></li> <li><a href="OCamlLangImpl6.html">Extending the language: user-defined operators</a></li> <li><a href="OCamlLangImpl7.html">Extending the language: mutable variables / SSA construction</a></li> - <li><a href="LangImpl8.html">Conclusion and other useful LLVM tidbits</a></li> + <li><a href="OCamlLangImpl8.html">Conclusion and other useful LLVM tidbits</a></li> </ol></li> <li>Advanced Topics <ol> |