diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AliasAnalysis.html | 5 | ||||
| -rw-r--r-- | docs/CFEBuildInstrs.html | 29 | ||||
| -rw-r--r-- | docs/CodeGenerator.html | 16 | ||||
| -rw-r--r-- | docs/CodingStandards.html | 66 | ||||
| -rw-r--r-- | docs/CommandGuide/index.html | 3 | ||||
| -rw-r--r-- | docs/CommandGuide/lit.pod | 10 | ||||
| -rw-r--r-- | docs/CommandGuide/llvm-stress.pod | 42 | ||||
| -rw-r--r-- | docs/CommandGuide/tblgen.pod | 52 | ||||
| -rw-r--r-- | docs/DeveloperPolicy.html | 46 | ||||
| -rw-r--r-- | docs/GarbageCollection.html | 7 | ||||
| -rw-r--r-- | docs/GettingStarted.html | 286 | ||||
| -rw-r--r-- | docs/GettingStartedVS.html | 2 | ||||
| -rw-r--r-- | docs/LangRef.html | 305 | ||||
| -rw-r--r-- | docs/Lexicon.html | 2 | ||||
| -rw-r--r-- | docs/Passes.html | 21 | ||||
| -rw-r--r-- | docs/ProgrammersManual.html | 29 | ||||
| -rw-r--r-- | docs/ReleaseNotes.html | 88 | ||||
| -rw-r--r-- | docs/SourceLevelDebugging.html | 185 | ||||
| -rw-r--r-- | docs/TableGenFundamentals.html | 42 | ||||
| -rw-r--r-- | docs/WritingAnLLVMBackend.html | 2 | ||||
| -rw-r--r-- | docs/doxygen.footer | 2 | ||||
| -rw-r--r-- | docs/doxygen.header | 2 | ||||
| -rw-r--r-- | docs/doxygen.intro | 4 | ||||
| -rw-r--r-- | docs/index.html | 7 |
24 files changed, 843 insertions, 410 deletions
diff --git a/docs/AliasAnalysis.html b/docs/AliasAnalysis.html index d04e841..7412712 100644 --- a/docs/AliasAnalysis.html +++ b/docs/AliasAnalysis.html @@ -418,9 +418,8 @@ implementing, you just override the interfaces you can improve.</p> <div> -<p>With only two special exceptions (the <tt><a -href="#basic-aa">basicaa</a></tt> and <a href="#no-aa"><tt>no-aa</tt></a> -passes) every alias analysis pass chains to another alias analysis +<p>With only one special exception (the <a href="#no-aa"><tt>no-aa</tt></a> +pass) every alias analysis pass chains to another alias analysis implementation (for example, the user can specify "<tt>-basicaa -ds-aa -licm</tt>" to get the maximum benefit from both alias analyses). The alias analysis class automatically takes care of most of this diff --git a/docs/CFEBuildInstrs.html b/docs/CFEBuildInstrs.html deleted file mode 100644 index ab10844..0000000 --- a/docs/CFEBuildInstrs.html +++ /dev/null @@ -1,29 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> - <link rel="stylesheet" href="llvm.css" type="text/css" media="screen"> - <title>Building the LLVM C/C++ Front-End</title> - <meta HTTP-EQUIV="REFRESH" CONTENT="3; URL=GCCFEBuildInstrs.html"> -</head> -<body> -<div class="doc_title"> -This page has moved <a href="GCCFEBuildInstrs.html">here</A>. -</div> - -<!-- *********************************************************************** --> - -<hr> -<address> - <a href="http://jigsaw.w3.org/css-validator/check/referer"><img - src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> - <a href="http://validator.w3.org/check/referer"><img - src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> - - <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2008-02-13 17:46:10 +0100 (Wed, 13 Feb 2008) $ -</address> - -</body> -</html> diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 345eb7c..32a3a97 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -709,6 +709,21 @@ ret <!-- _______________________________________________________________________ --> <h4> + <a name="callclobber">Call-clobbered registers</a> +</h4> + +<div> + +<p>Some machine instructions, like calls, clobber a large number of physical + registers. Rather than adding <code><def,dead></code> operands for + all of them, it is possible to use an <code>MO_RegisterMask</code> operand + instead. The register mask operand holds a bit mask of preserved registers, + and everything else is considered to be clobbered by the instruction. </p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="ssa">Machine code in SSA form</a> </h4> @@ -2491,6 +2506,7 @@ is the key:</p> <td><a href="#feat_segstacks">segmented stacks</a></td> <td class="no"></td> <!-- ARM --> <td class="no"></td> <!-- CellSPU --> + <td class="no"></td> <!-- Hexagon --> <td class="no"></td> <!-- MBlaze --> <td class="no"></td> <!-- MSP430 --> <td class="no"></td> <!-- Mips --> diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 7b05573..a5f6f35 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -31,6 +31,7 @@ Errors</a></li> <li><a href="#ci_portable_code">Write Portable Code</a></li> <li><a href="#ci_rtti_exceptions">Do not use RTTI or Exceptions</a></li> + <li><a href="#ci_static_ctors">Do not use Static Constructors</a></li> <li><a href="#ci_class_struct">Use of <tt>class</tt>/<tt>struct</tt> Keywords</a></li> </ol></li> </ol></li> @@ -449,6 +450,51 @@ than <tt>dynamic_cast<></tt>.</p> <!-- _______________________________________________________________________ --> <h4> +<a name="ci_static_ctors">Do not use Static Constructors</a> +</h4> +<div> + +<p>Static constructors and destructors (e.g. global variables whose types have +a constructor or destructor) should not be added to the code base, and should be +removed wherever possible. Besides <a +href="http://yosefk.com/c++fqa/ctors.html#fqa-10.12">well known problems</a> +where the order of initialization is undefined between globals in different +source files, the entire concept of static constructors is at odds with the +common use case of LLVM as a library linked into a larger application.</p> + +<p>Consider the use of LLVM as a JIT linked into another application (perhaps +for <a href="http://llvm.org/Users.html">OpenGL, custom languages</a>, +<a href="http://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf">shaders in +movies</a>, etc</a>). Due to the design of static constructors, they must be +executed at startup time of the entire application, regardless of whether or +how LLVM is used in that larger application. There are two problems with +this:</p> + +<ol> + <li>The time to run the static constructors impacts startup time of + applications — a critical time for GUI apps, among others.</li> + + <li>The static constructors cause the app to pull many extra pages of memory + off the disk: both the code for the constructor in each <tt>.o</tt> file and + the small amount of data that gets touched. In addition, touched/dirty pages + put more pressure on the VM system on low-memory machines.</li> +</ol> + +<p>We would really like for there to be zero cost for linking in an additional +LLVM target or other library into an application, but static constructors +violate this goal.</p> + +<p>That said, LLVM unfortunately does contain static constructors. It would be +a <a href="http://llvm.org/PR11944">great project</a> for someone to purge all +static constructors from LLVM, and then enable the +<tt>-Wglobal-constructors</tt> warning flag (when building with Clang) to ensure +we do not regress in the future. +</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a> </h4> <div> @@ -1151,22 +1197,10 @@ prefer it.</p> <div> <p>The use of <tt>#include <iostream></tt> in library files is -hereby <b><em>forbidden</em></b>. The primary reason for doing this is to -support clients using LLVM libraries as part of larger systems. In particular, -we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, -the static constructors are run whenever an application starts up that uses the -dynamic library. There are two problems with this:</p> - -<ol> - <li>The time to run the static c'tors impacts startup time of applications - — a critical time for GUI apps.</li> - - <li>The static c'tors cause the app to pull many extra pages of memory off the - disk: both the code for the static c'tors in each <tt>.o</tt> file and the - small amount of data that gets touched. In addition, touched/dirty pages - put more pressure on the VM system on low-memory machines.</li> -</ol> - +hereby <b><em>forbidden</em></b>, because many common implementations +transparently inject a <a href="#ci_static_ctors">static constructor</a> into +every translation unit that includes it.</p> + <p>Note that using the other stream headers (<tt><sstream></tt> for example) is not problematic in this regard — just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides various diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index 145569c..5db7020 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -75,6 +75,9 @@ options) arguments to the tool you are interested in.</p> <li><a href="/cmds/llvm-cov.html"><b>llvm-cov</b></a> - emit coverage information</li> +<li><a href="/cmds/llvm-stress.html"><b>llvm-stress</b></a> - + generate random .ll files to fuzz different llvm components</li> + </ul> </div> diff --git a/docs/CommandGuide/lit.pod b/docs/CommandGuide/lit.pod index faf4811..f4289a8 100644 --- a/docs/CommandGuide/lit.pod +++ b/docs/CommandGuide/lit.pod @@ -28,7 +28,7 @@ By default B<lit> will use a succinct progress display and will only print summary information for test failures. See L<"OUTPUT OPTIONS"> for options controlling the B<lit> progress display and output. -B<lit> also includes a number of options for controlling how tests are exected +B<lit> also includes a number of options for controlling how tests are executed (specific features may depend on the particular test format). See L<"EXECUTION OPTIONS"> for more information. @@ -37,7 +37,7 @@ the options specified on the command line, see L<"SELECTION OPTIONS"> for more information. Users interested in the B<lit> architecture or designing a B<lit> testing -implementation should see L<"LIT ARCHITECTURE"> +implementation should see L<"LIT INFRASTRUCTURE"> =head1 GENERAL OPTIONS @@ -208,7 +208,7 @@ suite. The test succeeded, but it was expected to fail. This is used for tests which were specified as expected to fail, but are now succeeding (generally because -the feautre they test was broken and has been fixed). +the feature they test was broken and has been fixed). =item B<FAIL> @@ -227,7 +227,7 @@ which can report unsupported tests. =back Depending on the test format tests may produce additional information about -their status (generally only for failures). See the L<Output|"LIT OUTPUT"> +their status (generally only for failures). See the L<Output|"OUTPUT OPTIONS"> section for more information. =head1 LIT INFRASTRUCTURE @@ -247,7 +247,7 @@ suite>. Test suites serve to define the format of the tests they contain, the logic for finding those tests, and any additional information to run the tests. B<lit> identifies test suites as directories containing I<lit.cfg> or -I<lit.site.cfg> files (see also B<--config-prefix>. Test suites are initially +I<lit.site.cfg> files (see also B<--config-prefix>). Test suites are initially discovered by recursively searching up the directory hierarchy for all the input files passed on the command line. You can use B<--show-suites> to display the discovered test suites at startup. diff --git a/docs/CommandGuide/llvm-stress.pod b/docs/CommandGuide/llvm-stress.pod new file mode 100644 index 0000000..92083d2 --- /dev/null +++ b/docs/CommandGuide/llvm-stress.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +llvm-stress - generate random .ll files + +=head1 SYNOPSIS + +B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump] + +=head1 DESCRIPTION + +The B<llvm-stress> tool is used to generate random .ll files that can be used to +test different components of LLVM. + +=head1 OPTIONS + +=over + +=item B<-o> I<filename> + +Specify the output filename. + +=item B<-size> I<size> + +Specify the size of the generated .ll file. + +=item B<-seed> I<seed> + +Specify the seed to be used for the randomly generated instructions. + +=back + +=head1 EXIT STATUS + +B<llvm-stress> returns 0. + +=head1 AUTHOR + +B<llvm-stress> is maintained by the LLVM Team (L<http://llvm.org/>). + +=cut diff --git a/docs/CommandGuide/tblgen.pod b/docs/CommandGuide/tblgen.pod index fe1be5e..180bcc1 100644 --- a/docs/CommandGuide/tblgen.pod +++ b/docs/CommandGuide/tblgen.pod @@ -41,6 +41,10 @@ Specify where to find other target description files for inclusion. The F<directory> value should be a full or partial path to a directory that contains target description files. +=item B<-asmparsernum> F<N> + +Make -gen-asm-parser emit assembly writer number F<N>. + =item B<-asmwriternum> F<N> Make -gen-asm-writer emit assembly writer number F<N>. @@ -57,38 +61,50 @@ Print all records to standard output (default). Print enumeration values for a class -=item B<-gen-emitter> +=item B<-print-sets> -Generate machine code emitter. +Print expanded sets for testing DAG exprs. -=item B<-gen-register-enums> +=item B<-gen-emitter> -Generate the enumeration values for all registers. +Generate machine code emitter. -=item B<-gen-register-desc> +=item B<-gen-register-info> -Generate a register info description for each register. +Generate registers and register classes info. -=item B<-gen-register-desc-header> +=item B<-gen-instr-info> -Generate a register info description header for each register. +Generate instruction descriptions. -=item B<-gen-instr-enums> +=item B<-gen-asm-writer> -Generate enumeration values for instructions. +Generate the assembly writer. -=item B<-gen-instr-desc> +=item B<-gen-disassembler> -Generate instruction descriptions. +Generate disassembler. -=item B<-gen-asm-writer> +=item B<-gen-pseudo-lowering> -Generate the assembly writer. +Generate pseudo instruction lowering. =item B<-gen-dag-isel> Generate a DAG (Directed Acycle Graph) instruction selector. +=item B<-gen-asm-matcher> + +Generate assembly instruction matcher. + +=item B<-gen-dfa-packetizer> + +Generate DFA Packetizer for VLIW targets. + +=item B<-gen-fast-isel> + +Generate a "fast" instruction selector. + =item B<-gen-subtarget> Generate subtarget enumerations. @@ -97,6 +113,14 @@ Generate subtarget enumerations. Generate intrinsic information. +=item B<-gen-tgt-intrinsic> + +Generate target intrinsic information. + +=item B<-gen-enhanced-disassembly-info> + +Generate enhanced disassembly info. + =item B<-version> Show the version number of this program. diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index dfbba21..08e47a1 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -43,7 +43,7 @@ the distributed nature of LLVM's development. By stating the policy in clear terms, we hope each developer can know ahead of time what to expect when making LLVM contributions. This policy covers all llvm.org subprojects, - including Clang, LLDB, etc.</p> + including Clang, LLDB, libc++, etc.</p> <p>This policy is also designed to accomplish the following objectives:</p> <ol> @@ -52,6 +52,9 @@ <li>Make life as simple and easy for contributors as possible.</li> <li>Keep the top of Subversion trees as stable as possible.</li> + + <li>Establish awareness of the project's <a href="#clp">copyright, + license, and patent policies</a> with contributors to the project.</li> </ol> <p>This policy is aimed at frequent contributors to LLVM. People interested in @@ -212,6 +215,10 @@ <li><b>Jakob Olesen</b>: Register allocators and TableGen.</li> <li><b>Duncan Sands</b>: dragonegg and llvm-gcc 4.2.</li> + + <li><b>Peter Collingbourne</b>: libclc.</li> + + <li><b>Tobias Grosser</b>: polly.</li> </ol> <p>Note that code ownership is completely different than reviewers: anyone can @@ -494,19 +501,23 @@ </h2> <!--=========================================================================--> +<div class="doc_notes"> +<p style="text-align:center;font-weight:bold">NOTE: This section deals with + legal matters but does not provide legal advice. We are not lawyers — + please seek legal counsel from an attorney.</p> +</div> + <div> <p>This section addresses the issues of copyright, license and patents for the - LLVM project. The copyright holder for the code is held by the individual + LLVM project. The copyright for the code is held by the individual contributors of the code and the terms of its license to LLVM users and developers is the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of - Illinois/NCSA Open Source License</a>.</p> + Illinois/NCSA Open Source License</a> (with portions dual licensed under the + <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, + see below). As contributor to the LLVM project, you agree to allow any + contributions to the project to licensed under these terms.</p> -<div class="doc_notes"> -<p style="text-align:center;font-weight:bold">NOTE: This section deals with - legal matters but does not provide legal advice. We are not lawyers, please - seek legal counsel from an attorney.</p> -</div> <!-- _______________________________________________________________________ --> <h3><a name="copyright">Copyright</a></h3> @@ -535,7 +546,10 @@ <h3><a name="license">License</a></h3> <div> <p>We intend to keep LLVM perpetually open source and to use a liberal open - source license. All of the code in LLVM is available under the + source license. <b>As a contributor to the project, you agree that any + contributions be licensed under the terms of the corresponding + subproject.</b> + All of the code in LLVM is available under the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>, which boils down to this:</p> @@ -556,7 +570,7 @@ if further clarification is needed.</p> <p>In addition to the UIUC license, the runtime library components of LLVM - (<b>compiler_rt and libc++</b>) are also licensed under the <a + (<b>compiler_rt, libc++, and libclc</b>) are also licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>, which does not contain the binary redistribution clause. As a user of these runtime libraries, it means that you can choose to use the code under either @@ -570,16 +584,17 @@ the LLVM core to libc++ without the copyright owner's permission. </p> -<p>Note that the LLVM Project does distribute llvm-gcc, <b>which is GPL.</b> +<p>Note that the LLVM Project does distribute llvm-gcc and dragonegg, <b>which + are GPL.</b> This means that anything "linked" into llvm-gcc must itself be compatible with the GPL, and must be releasable under the terms of the GPL. This implies that <b>any code linked into llvm-gcc and distributed to others may be subject to the viral aspects of the GPL</b> (for example, a proprietary code generator linked into llvm-gcc must be made available under the GPL). This is not a problem for code already distributed under a more liberal - license (like the UIUC license), and does not affect code generated by - llvm-gcc. It may be a problem if you intend to base commercial development - on llvm-gcc without redistributing your source code.</p> + license (like the UIUC license), and GPL-containing subprojects are kept + in separate SVN repositories whose LICENSE.txt files specifically indicate + that they contain GPL code.</p> <p>We have no plans to change the license of LLVM. If you have questions or comments about the license, please contact the @@ -596,7 +611,8 @@ arbitrary purposes (including commercial use).</p> <p>When contributing code, we expect contributors to notify us of any potential - for patent-related trouble with their changes. If you or your employer own + for patent-related trouble with their changes (including from third parties). + If you or your employer own the rights to a patent and would like to contribute code to LLVM that relies on it, we require that the copyright owner sign an agreement that allows any other user of LLVM to freely use your patent. Please contact diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index a226b0e..53ea192 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -429,7 +429,8 @@ programs that use different garbage collection algorithms (or none at all).</p> <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack variable references an object on the heap and is to be tracked for garbage collection. The exact impact on generated code is specified by a <a -href="#plugin">compiler plugin</a>.</p> +href="#plugin">compiler plugin</a>. All calls to <tt>llvm.gcroot</tt> <b>must</b> reside + inside the first basic block.</p> <p>A compiler which uses mem2reg to raise imperative code using <tt>alloca</tt> into SSA form need only add a call to <tt>@llvm.gcroot</tt> for those variables @@ -437,7 +438,9 @@ which a pointers into the GC heap.</p> <p>It is also important to mark intermediate values with <tt>llvm.gcroot</tt>. For example, consider <tt>h(f(), g())</tt>. Beware leaking the result of -<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection.</p> +<tt>f()</tt> in the case that <tt>g()</tt> triggers a collection. Note, that +stack variables must be initialized and marked with <tt>llvm.gcroot</tt> in +function's prologue.</p> <p>The first argument <b>must</b> be a value referring to an alloca instruction or a bitcast of an alloca. The second contains a pointer to metadata that diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index d78344a..4d41208 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -29,7 +29,6 @@ <li><a href="#unpack">Unpacking the LLVM Archives</a></li> <li><a href="#checkout">Checkout LLVM from Subversion</a></li> <li><a href="#git_mirror">LLVM GIT mirror</a></li> - <li><a href="#installcf">Install the GCC Front End</a></li> <li><a href="#config">Local LLVM Configuration</a></li> <li><a href="#compile">Compiling the LLVM Suite Source Code</a></li> <li><a href="#cross-compile">Cross-Compiling LLVM</a></li> @@ -52,7 +51,7 @@ <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> <ol> - <li><a href="#tutorial4">Example with llvm-gcc4</a></li> + <li><a href="#tutorial4">Example with Clang</a></li> </ol> <li><a href="#problems">Common Problems</a> <li><a href="#links">Links</a> @@ -82,16 +81,15 @@ basic information.</p> <p>First, LLVM comes in three pieces. The first piece is the LLVM suite. This contains all of the tools, libraries, and header files -needed to use the low level virtual machine. It contains an -assembler, disassembler, bitcode analyzer and bitcode optimizer. It -also contains basic regression tests that can be used to test the LLVM -tools and the GCC front end.</p> - -<p>The second piece is the GCC front end. This component provides a version of -GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front -end uses the GCC parser to convert code to LLVM. Once -compiled into LLVM bitcode, a program can be manipulated with the LLVM tools -from the LLVM suite.</p> +needed to use LLVM. It contains an assembler, disassembler, bitcode +analyzer and bitcode optimizer. It also contains basic regression tests that +can be used to test the LLVM tools and the Clang front end.</p> + +<p>The second piece is the <a href="http://clang.llvm.org/">Clang</a> front end. +This component compiles C, C++, Objective C, and Objective C++ code into LLVM +bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the +LLVM tools from the LLVM suite. +</p> <p> There is a third, optional piece called Test Suite. It is a suite of programs @@ -109,75 +107,91 @@ and performance. <div> +<p>The LLVM Getting Started documentation may be out of date. So, the Clang +<a href="http://clang.llvm.org/get_started.html">Getting Started</a> page might +also be a good place to start.</p> + <p>Here's the short story for getting up and running quickly with LLVM:</p> <ol> <li>Read the documentation.</li> <li>Read the documentation.</li> <li>Remember that you were warned twice about reading the documentation.</li> - <li>Install the llvm-gcc-4.2 front end if you intend to compile C or C++ - (see <a href="#installcf">Install the GCC Front End</a> for details): - <ol> - <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li> - <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf -</tt></li> - <li><tt><i>install-binutils-binary-from-MinGW</i></tt> (Windows only)</li> - <li>Note: If the binary extension is "<tt>.bz</tt>" use <tt>bunzip2</tt> instead of <tt>gunzip</tt>.</li> - <li>Note: On Windows, use <a href="http://www.7-zip.org/">7-Zip</a> or a similar archiving tool.</li> - <li>Add <tt>llvm-gcc</tt>'s "<tt>bin</tt>" directory to your <tt>PATH</tt> environment variable.</li> - </ol></li> - <li>Get the LLVM Source Code + <li>Checkout LLVM: <ul> - <li>With the distributed files (or use <a href="#checkout">SVN</a>): - <ol> - <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> - <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt> - </ol></li> - - </ul></li> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> + </ul> + </li> - <li><b>[Optional]</b> Get the Test Suite Source Code + <li>Checkout Clang: <ul> - <li>With the distributed files (or use <a href="#checkout">SVN</a>): - <ol> - <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> - <li><tt>cd llvm/projects</tt> - <li><tt>gunzip --stdout llvm-test-<i>version</i>.tar.gz | tar -xvf -</tt> - <li><tt>mv llvm-test-<i>version</i> test-suite</tt> - </ol></li> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/tools</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> + </ul> + </li> - </ul></li> + <li>Checkout Compiler-RT: + <ul> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/projects</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk + compiler-rt</tt></li> + </ul> + </li> + <li>Get the Test Suite Source Code <b>[Optional]</b> + <ul> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>cd llvm/projects</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite</tt></li> + </ul> + </li> - <li>Configure the LLVM Build Environment - <ol> + <li>Configure and build LLVM and Clang: + <ul> <li><tt>cd <i>where-you-want-to-build-llvm</i></tt></li> - <li><tt><i>/path/to/llvm/</i>configure [options]</tt><br> + <li><tt>mkdir build</tt> (for building without polluting the source dir)</li> + <li><tt>cd build</tt></li> + <li><tt>../llvm/configure [options]</tt></li> Some common options: <ul> - <li><tt>--prefix=<i>directory</i></tt> - <p>Specify for <i>directory</i> the full pathname of where you + <li><tt>--prefix=<i>directory</i></tt> - + Specify for <i>directory</i> the full pathname of where you want the LLVM tools and libraries to be installed (default - <tt>/usr/local</tt>).</p></li> - <li><tt>--with-llvmgccdir=<i>directory</i></tt> - <p>Optionally, specify for <i>directory</i> the full pathname of the - C/C++ front end installation to use with this LLVM configuration. If - not specified, the PATH will be searched. This is only needed if you - want to run test-suite or do some special kinds of LLVM builds.</p></li> - <li><tt>--enable-spec2000=<i>directory</i></tt> - <p>Enable the SPEC2000 benchmarks for testing. The SPEC2000 - benchmarks should be available in - <tt><i>directory</i></tt>.</p></li> + <tt>/usr/local</tt>).</li> </ul> - </ol></li> - <li>Build the LLVM Suite: - <ol> - <li><tt>gmake -k |& tee gnumake.out - # this is csh or tcsh syntax</tt></li> - <li>If you get an "internal compiler error (ICE)" or test failures, see - <a href="#brokengcc">below</a>.</li> + <ul> + <li><tt>--enable-optimized</tt> - + Compile with optimizations enabled (default is NO).</li> + </ul> + + <ul> + <li><tt>--enable-assertions</tt> - + Compile with assertion checks enabled (default is YES).</li> + </ul> + + <li><tt>make [-j]</tt> - The -j specifies the number of jobs (commands) to + run simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. + The --enabled-optimized configure option is used to specify a Release build.</li> + <li><tt>make check-all</tt> - + This run the regression tests to ensure everything is in working order.</li> + <li><tt>make update</tt> - + This command is used to update all the svn repositories at once, rather then + having to <tt>cd</tt> into the individual repositories and running + <tt>svn update</tt>.</li> + <li>It is also possible to use CMake instead of the makefiles. With CMake + it is also possible to generate project files for several IDEs: Eclipse + CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.</li> + <li>If you get an "internal compiler error (ICE)" or test failures, see + <a href="#brokengcc">below</a>.</li> + + </ul> + </li> </ol> </ol> @@ -185,7 +199,7 @@ and performance. <p>Consult the <a href="#starting">Getting Started with LLVM</a> section for detailed information on configuring and compiling LLVM. See <a href="#environment">Setting Up Your Environment</a> for tips that simplify -working with the GCC front end and LLVM tools. Go to <a href="#layout">Program +working with the Clang front end and LLVM tools. Go to <a href="#layout">Program Layout</a> to learn about the layout of the source code tree.</p> </div> @@ -361,10 +375,6 @@ able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation should work as well, although the generated native code may not work on your platform.</p> -<p>The GCC front end is not very portable at the moment. If you want to get it -to work on another platform, you can download a copy of the source and <a -href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> - </div> <!-- ======================================================================= --> @@ -430,7 +440,7 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p> <tr> <td><a href="http://www.perl.com/download.csp">perl</a></td> <td>≥5.6.0</td> - <td>Nightly tester, utilities</td> + <td>Utilities</td> </tr> <tr> @@ -537,8 +547,7 @@ href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in the "<tt>convert_from_eh_region_ranges_1</tt>" GCC function.</p> <p><b>Cygwin GCC 3.3.3</b>: The version of GCC 3.3.3 commonly shipped with - Cygwin does not work. Please <a href="GCCFEBuildInstrs.html#cygwin">upgrade - to a newer version</a> if possible.</p> + Cygwin does not work.</p> <p><b>SuSE GCC 3.3.3</b>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly others) does not compile LLVM correctly (it appears that exception handling is broken in some cases). Please download the FSF 3.3.3 or upgrade @@ -650,12 +659,6 @@ All these paths are absolute:</p> can be the same as SRC_ROOT). <br><br> - <dt>LLVMGCCDIR - <dd> - This is where the LLVM GCC Front End is installed. - <p> - For the pre-built GCC front end binaries, the LLVMGCCDIR is - <tt>llvm-gcc/<i>platform</i>/llvm-gcc</tt>. </dl> </div> @@ -782,10 +785,6 @@ you get it from the Subversion repository:</p> configured by the LLVM configure script as well as automatically updated when you run <tt>svn update</tt>.</p> -<p>If you would like to get the GCC front end source code, you can also get it -and build it yourself. Please follow <a href="GCCFEBuildInstrs.html">these -instructions</a> to successfully get and build the LLVM GCC front-end.</p> - </div> <!-- ======================================================================= --> @@ -951,76 +950,6 @@ git svn rebase -l <!-- ======================================================================= --> <h3> - <a name="installcf">Install the GCC Front End</a> -</h3> - -<div> - -<p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM -GCC front end) you can optionally extract the front end from the binary distribution. -It is used for running the LLVM test-suite and for compiling C/C++ programs. Note that -you can optionally <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the -main LLVM repository.</p> - -<p>To install the GCC front end, do the following (on Windows, use an archival tool -like <a href="http://www.7-zip.org/">7-zip</a> that understands gzipped tars):</p> - -<ol> - <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li> - <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf - -</tt></li> -</ol> - -<p>Once the binary is uncompressed, if you're using a *nix-based system, add a symlink for -<tt>llvm-gcc</tt> and <tt>llvm-g++</tt> to some directory in your path. If you're using a -Windows-based system, add the <tt>bin</tt> subdirectory of your front end installation directory -to your <tt>PATH</tt> environment variable. For example, if you uncompressed the binary to -<tt>c:\llvm-gcc</tt>, add <tt>c:\llvm-gcc\bin</tt> to your <tt>PATH</tt>.</p> - -<p>If you now want to build LLVM from source, when you configure LLVM, it will -automatically detect <tt>llvm-gcc</tt>'s presence (if it is in your path) enabling its -use in test-suite. Note that you can always build or install <tt>llvm-gcc</tt> at any -point after building the main LLVM repository: just reconfigure llvm and -test-suite will pick it up. -</p> - -<p>As a convenience for Windows users, the front end binaries for MinGW/x86 include -versions of the required w32api and mingw-runtime binaries. The last remaining step for -Windows users is to simply uncompress the binary binutils package from -<a href="http://mingw.org/">MinGW</a> into your front end installation directory. While the -front end installation steps are not quite the same as a typical manual MinGW installation, -they should be similar enough to those who have previously installed MinGW on Windows systems.</p> - -<p>To install binutils on Windows:</p> - -<ol> - <li><tt><i>download GNU Binutils from <a href="http://sourceforge.net/projects/mingw/files/">MinGW Downloads</a></i></tt></li> - <li><tt>cd <i>where-you-uncompressed-the-front-end</i></tt></li> - <li><tt><i>uncompress archived binutils directories (not the tar file) into the current directory</i></tt></li> -</ol> - -<p>The binary versions of the LLVM GCC front end may not suit all of your needs. For -example, the binary distribution may include an old version of a system header -file, not "fix" a header file that needs to be fixed for GCC, or it may be linked with -libraries not available on your system. In cases like these, you may want to try -<a href="GCCFEBuildInstrs.html">building the GCC front end from source</a>. Thankfully, -this is much easier now than it was in the past.</p> - -<p>We also do not currently support updating of the GCC front end by manually overlaying -newer versions of the w32api and mingw-runtime binary packages that may become available -from MinGW. At this time, it's best to think of the MinGW LLVM GCC front end binary as -a self-contained convenience package that requires Windows users to simply download and -uncompress the GNU Binutils binary package from the MinGW project.</p> - -<p>Regardless of your platform, if you discover that installing the LLVM GCC front end -binaries is not as easy as previously described, or you would like to suggest improvements, -please let us know how you would like to see things improved by dropping us a note on our -<a href="http://llvm.org/docs/#maillist">mailing list</a>.</p> - -</div> - -<!-- ======================================================================= --> -<h3> <a name="config">Local LLVM Configuration</a> </h3> @@ -1057,29 +986,6 @@ script to configure the build system:</p> <p>The following options can be used to set or enable LLVM specific options:</p> <dl> - <dt><i>--with-llvmgccdir</i></dt> - <dd>Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration. - The value of this option should specify the full pathname of the C/C++ Front - End to be used. If this option is not provided, the PATH will be searched for - a program named <i>llvm-gcc</i> and the C/C++ FrontEnd install directory will - be inferred from the path found. If the option is not given, and no llvm-gcc - can be found in the path then a warning will be produced by - <tt>configure</tt> indicating this situation. LLVM may still be built with - the <tt>tools-only</tt> target but attempting to build the runtime libraries - will fail as these libraries require llvm-gcc and llvm-g++. See - <a href="#installcf">Install the GCC Front End</a> for details on installing - the C/C++ Front End. See - <a href="GCCFEBuildInstrs.html">Bootstrapping the LLVM C/C++ Front-End</a> - for details on building the C/C++ Front End.</dd> - <dt><i>--with-tclinclude</i></dt> - <dd>Path to the tcl include directory under which <tt>tclsh</tt> can be - found. Use this if you have multiple tcl installations on your machine and you - want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the - dejagnu based test suite in <tt>llvm/test</tt>. If you don't specify this - option, the LLVM configure script will search for the tcl 8.4 and 8.3 - releases. - <br><br> - </dd> <dt><i>--enable-optimized</i></dt> <dd> Enables optimized compilation (debugging symbols are removed @@ -1110,7 +1016,7 @@ script to configure the build system:</p> selected as the target of the build host. You can also specify a comma separated list of target names that you want available in llc. The target names use all lower case. The current set of targets is: <br> - <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>. + <tt>arm, cbe, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu, x86, x86_64, xcore</tt>. <br><br></dd> <dt><i>--enable-doxygen</i></dt> <dd>Look for the doxygen program and enable construction of doxygen based @@ -1530,7 +1436,7 @@ different <a href="#tools">tools</a>.</p> <div> <p>This directory contains libraries which are compiled into LLVM bitcode and -used when linking programs with the GCC front end. Most of these libraries are +used when linking programs with the Clang front end. Most of these libraries are skeleton versions of real libraries; for example, libc is a stripped down version of glibc.</p> @@ -1692,12 +1598,6 @@ are code generators for parts of LLVM infrastructure.</p> directory, switch to directory <tt>llvm/tools/llc</tt> and build it, causing a re-linking of LLC.<br><br> - <dt><tt><b>NewNightlyTest.pl</b></tt> and - <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a - cron script to generate nightly status reports of the functionality of - tools, and the results can be seen by following the appropriate link on - the <a href="http://llvm.org/">LLVM homepage</a>.<br><br> - <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains the tool used to generate register descriptions, instruction set descriptions, and even assemblers from common TableGen description @@ -1722,20 +1622,11 @@ are code generators for parts of LLVM infrastructure.</p> <!-- *********************************************************************** --> <div> -<p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete, -so we only include instructions for llvm-gcc4. -</p> - -<p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b> -from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b> -create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates, -the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and -<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode -output.</p> +<p>This section gives an example of using LLVM with the Clang front end.</p> <!-- ======================================================================= --> <h3> - <a name="tutorial4">Example with llvm-gcc4</a> + <a name="tutorial4">Example with clang</a> </h3> <div> @@ -1755,24 +1646,21 @@ int main() { <li><p>Next, compile the C file into a native executable:</p> - <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div> + <div class="doc_code"><pre>% clang hello.c -o hello</pre></div> - <p>Note that llvm-gcc works just like GCC by default. The standard -S and + <p>Note that clang works just like GCC by default. The standard -S and -c arguments work as usual (producing a native .s or .o file, respectively).</p></li> <li><p>Next, compile the C file into a LLVM bitcode file:</p> <div class="doc_code"> - <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div> + <pre>% clang -O3 -emit-llvm hello.c -c -o hello.bc</pre></div> <p>The -emit-llvm option can be used with the -S or -c options to emit an LLVM ".ll" or ".bc" file (respectively) for the code. This allows you to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on - the bitcode file.</p> - - <p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. - </p></li> + the bitcode file.</p></li> <li><p>Run the program in both forms. To run the program, use:</p> @@ -1811,7 +1699,7 @@ int main() { <div class="doc_code"><pre>% ./hello.native</pre></div> - <p>Note that using llvm-gcc to compile directly to native code (i.e. when + <p>Note that using clang to compile directly to native code (i.e. when the -emit-llvm option is not present) does steps 6/7/8 for you.</p> </li> diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index 8c86ec6..d7c1efc 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -44,7 +44,7 @@ <p>There are many different projects that compose LLVM. The first is the LLVM suite. This contains all of the tools, libraries, and header files needed to - use the low level virtual machine. It contains an assembler, disassembler, + use LLVM. It contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It also contains a test suite that can be used to test the LLVM tools.</p> diff --git a/docs/LangRef.html b/docs/LangRef.html index 90308a4..29ac260 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -108,6 +108,11 @@ </li> </ol> </li> + <li><a href="#module_flags">Module Flags Metadata</a> + <ol> + <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a></li> + </ol> + </li> <li><a href="#intrinsic_globals">Intrinsic Global Variables</a> <ol> <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li> @@ -128,7 +133,6 @@ <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li> <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li> <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li> - <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li> <li><a href="#i_resume">'<tt>resume</tt>' Instruction</a></li> <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li> </ol> @@ -1143,6 +1147,10 @@ define void @f() optsize { ... } </pre> <dl> + <dt><tt><b>address_safety</b></tt></dt> + <dd>This attribute indicates that the address safety analysis + is enabled for this function. </dd> + <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt> <dd>This attribute indicates that, when emitting the prologue and epilogue, the backend should forcibly align the stack pointer. Specify the @@ -1202,8 +1210,7 @@ define void @f() optsize { ... } It does not write through any pointer arguments (including <tt><a href="#byval">byval</a></tt> arguments) and never changes any state visible to callers. This means that it cannot unwind - exceptions by calling the <tt>C++</tt> exception throwing methods, but - could use the <tt>unwind</tt> instruction.</dd> + exceptions by calling the <tt>C++</tt> exception throwing methods.</dd> <dt><tt><b><a name="readonly">readonly</a></b></tt></dt> <dd>This attribute indicates that the function does not write through any @@ -1213,8 +1220,7 @@ define void @f() optsize { ... } and read state that may be set in the caller. A readonly function always returns the same value (or unwinds an exception identically) when called with the same set of arguments and global state. It cannot unwind an - exception by calling the <tt>C++</tt> exception throwing methods, but may - use the <tt>unwind</tt> instruction.</dd> + exception by calling the <tt>C++</tt> exception throwing methods.</dd> <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt> <dd>This attribute indicates that this function can return twice. The @@ -1610,7 +1616,7 @@ that determines which other atomic instructions on the same address they <i>synchronize with</i>. These semantics are borrowed from Java and C++0x, but are somewhat more colloquial. If these descriptions aren't precise enough, check those specs (see spec references in the -<a href="Atomic.html#introduction">atomics guide</a>). +<a href="Atomics.html#introduction">atomics guide</a>). <a href="#i_fence"><code>fence</code></a> instructions treat these orderings somewhat differently since they don't take an address. See that instruction's documentation for details.</p> @@ -1709,7 +1715,7 @@ in signal handlers).</p> </tr> <tr> <td><a href="#t_floating">floating point</a></td> - <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td> + <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td> </tr> <tr> <td><a name="t_firstclass">first class</a></td> @@ -1809,6 +1815,7 @@ in signal handlers).</p> <table> <tbody> <tr><th>Type</th><th>Description</th></tr> + <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr> <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> @@ -2268,10 +2275,11 @@ in signal handlers).</p> represented in their IEEE hexadecimal format so that assembly and disassembly do not cause any bits to change in the constants.</p> -<p>When using the hexadecimal form, constants of types float and double are +<p>When using the hexadecimal form, constants of types half, float, and double are represented using the 16-digit form shown above (which matches the IEEE754 - representation for double); float values must, however, be exactly - representable as IEE754 single precision. Hexadecimal format is always used + representation for double); half and float values must, however, be exactly + representable as IEE754 half and single precision, respectively. + Hexadecimal format is always used for long double, and there are three forms of long double. The 80-bit format used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. The 128-bit format used by PowerPC (two adjacent doubles) is represented @@ -2537,7 +2545,7 @@ b: unreachable control back to them.</li> <li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the - <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>, + <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>, or exception-throwing call instructions that dynamically transfer control back to them.</li> @@ -3028,6 +3036,200 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) <!-- *********************************************************************** --> <h2> + <a name="module_flags">Module Flags Metadata</a> +</h2> +<!-- *********************************************************************** --> + +<div> + +<p>Information about the module as a whole is difficult to convey to LLVM's + subsystems. The LLVM IR isn't sufficient to transmit this + information. The <tt>llvm.module.flags</tt> named metadata exists in order to + facilitate this. These flags are in the form of key / value pairs — + much like a dictionary — making it easy for any subsystem who cares + about a flag to look it up.</p> + +<p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata + triplets. Each triplet has the following form:</p> + +<ul> + <li>The first element is a <i>behavior</i> flag, which specifies the behavior + when two (or more) modules are merged together, and it encounters two (or + more) metadata with the same ID. The supported behaviors are described + below.</li> + + <li>The second element is a metadata string that is a unique ID for the + metadata. How each ID is interpreted is documented below.</li> + + <li>The third element is the value of the flag.</li> +</ul> + +<p>When two (or more) modules are merged together, the resulting + <tt>llvm.module.flags</tt> metadata is the union of the + modules' <tt>llvm.module.flags</tt> metadata. The only exception being a flag + with the <i>Override</i> behavior, which may override another flag's value + (see below).</p> + +<p>The following behaviors are supported:</p> + +<table border="1" cellspacing="0" cellpadding="4"> + <tbody> + <tr> + <th>Value</th> + <th>Behavior</th> + </tr> + <tr> + <td>1</td> + <td align="left"> + <dt><b>Error</b></dt> + <dd>Emits an error if two values disagree. It is an error to have an ID + with both an Error and a Warning behavior.</dd> + </td> + </tr> + <tr> + <td>2</td> + <td align="left"> + <dt><b>Warning</b></dt> + <dd>Emits a warning if two values disagree.</dd> + </td> + </tr> + <tr> + <td>3</td> + <td align="left"> + <dt><b>Require</b></dt> + <dd>Emits an error when the specified value is not present or doesn't + have the specified value. It is an error for two (or more) + <tt>llvm.module.flags</tt> with the same ID to have the Require + behavior but different values. There may be multiple Require flags + per ID.</dd> + </td> + </tr> + <tr> + <td>4</td> + <td align="left"> + <dt><b>Override</b></dt> + <dd>Uses the specified value if the two values disagree. It is an error + for two (or more) <tt>llvm.module.flags</tt> with the same ID to + have the Override behavior but different values.</dd> + </td> + </tr> + </tbody> +</table> + +<p>An example of module flags:</p> + +<pre class="doc_code"> +!0 = metadata !{ i32 1, metadata !"foo", i32 1 } +!1 = metadata !{ i32 4, metadata !"bar", i32 37 } +!2 = metadata !{ i32 2, metadata !"qux", i32 42 } +!3 = metadata !{ i32 3, metadata !"qux", + metadata !{ + metadata !"foo", i32 1 + } +} +!llvm.module.flags = !{ !0, !1, !2, !3 } +</pre> + +<ul> + <li><p>Metadata <tt>!0</tt> has the ID <tt>!"foo"</tt> and the value '1'. The + behavior if two or more <tt>!"foo"</tt> flags are seen is to emit an + error if their values are not equal.</p></li> + + <li><p>Metadata <tt>!1</tt> has the ID <tt>!"bar"</tt> and the value '37'. The + behavior if two or more <tt>!"bar"</tt> flags are seen is to use the + value '37' if their values are not equal.</p></li> + + <li><p>Metadata <tt>!2</tt> has the ID <tt>!"qux"</tt> and the value '42'. The + behavior if two or more <tt>!"qux"</tt> flags are seen is to emit a + warning if their values are not equal.</p></li> + + <li><p>Metadata <tt>!3</tt> has the ID <tt>!"qux"</tt> and the value:</p> + +<pre class="doc_code"> +metadata !{ metadata !"foo", i32 1 } +</pre> + + <p>The behavior is to emit an error if the <tt>llvm.module.flags</tt> does + not contain a flag with the ID <tt>!"foo"</tt> that has the value + '1'. If two or more <tt>!"qux"</tt> flags exist, then they must have + the same value or an error will be issued.</p></li> +</ul> + + +<!-- ======================================================================= --> +<h3> +<a name="objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a> +</h3> + +<div> + +<p>On the Mach-O platform, Objective-C stores metadata about garbage collection + in a special section called "image info". The metadata consists of a version + number and a bitmask specifying what types of garbage collection are + supported (if any) by the file. If two or more modules are linked together + their garbage collection metadata needs to be merged rather than appended + together.</p> + +<p>The Objective-C garbage collection module flags metadata consists of the + following key-value pairs:</p> + +<table border="1" cellspacing="0" cellpadding="4"> + <tbody> + <tr> + <th width="30%">Key</th> + <th>Value</th> + </tr> + <tr> + <td><tt>Objective-C Version</tt></td> + <td align="left"><b>[Required]</b> — The Objective-C ABI + version. Valid values are 1 and 2.</td> + </tr> + <tr> + <td><tt>Objective-C Image Info Version</tt></td> + <td align="left"><b>[Required]</b> — The version of the image info + section. Currently always 0.</td> + </tr> + <tr> + <td><tt>Objective-C Image Info Section</tt></td> + <td align="left"><b>[Required]</b> — The section to place the + metadata. Valid values are <tt>"__OBJC, __image_info, regular"</tt> for + Objective-C ABI version 1, and <tt>"__DATA,__objc_imageinfo, regular, + no_dead_strip"</tt> for Objective-C ABI version 2.</td> + </tr> + <tr> + <td><tt>Objective-C Garbage Collection</tt></td> + <td align="left"><b>[Required]</b> — Specifies whether garbage + collection is supported or not. Valid values are 0, for no garbage + collection, and 2, for garbage collection supported.</td> + </tr> + <tr> + <td><tt>Objective-C GC Only</tt></td> + <td align="left"><b>[Optional]</b> — Specifies that only garbage + collection is supported. If present, its value must be 6. This flag + requires that the <tt>Objective-C Garbage Collection</tt> flag have the + value 2.</td> + </tr> + </tbody> +</table> + +<p>Some important flag interactions:</p> + +<ul> + <li>If a module with <tt>Objective-C Garbage Collection</tt> set to 0 is + merged with a module with <tt>Objective-C Garbage Collection</tt> set to + 2, then the resulting module has the <tt>Objective-C Garbage + Collection</tt> flag set to 0.</li> + + <li>A module with <tt>Objective-C Garbage Collection</tt> set to 0 cannot be + merged with a module with <tt>Objective-C GC Only</tt> set to 6.</li> +</ul> + +</div> + +</div> + +<!-- *********************************************************************** --> +<h2> <a name="intrinsic_globals">Intrinsic Global Variables</a> </h2> <!-- *********************************************************************** --> @@ -3174,7 +3376,6 @@ cast formed of bitcast or getelementptr. For example, a legal use of it is:</p> '<a href="#i_switch"><tt>switch</tt></a>', '<a href="#i_indirectbr"><tt>indirectbr</tt></a>', '<a href="#i_invoke"><tt>invoke</tt></a>', - '<a href="#i_unwind"><tt>unwind</tt></a>', '<a href="#i_resume"><tt>resume</tt></a>', and '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p> @@ -3394,9 +3595,9 @@ IfUnequal: '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the "normal" label. If the callee (or any - indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>" - instruction, control is interrupted and continued at the dynamically nearest - "exception" label.</p> + indirect callees) returns via the "<a href="#i_resume"><tt>resume</tt></a>" + instruction or other exception handling mechanism, control is interrupted and + continued at the dynamically nearest "exception" label.</p> <p>The '<tt>exception</tt>' label is a <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the @@ -3438,8 +3639,9 @@ IfUnequal: <li>'<tt>normal label</tt>': the label reached when the called function executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> - <li>'<tt>exception label</tt>': the label reached when a callee returns with - the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> + <li>'<tt>exception label</tt>': the label reached when a callee returns via + the <a href="#i_resume"><tt>resume</tt></a> instruction or other exception + handling mechanism.</li> <li>The optional <a href="#fnattrs">function attributes</a> list. Only '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and @@ -3462,9 +3664,6 @@ IfUnequal: block to the "normal" label. If the callee unwinds then no return value is available.</p> -<p>Note that the code generator does not yet completely support unwind, and -that the invoke/unwind semantics are likely to change in future versions.</p> - <h5>Example:</h5> <pre> %retval = invoke i32 @Test(i32 15) to label %Continue @@ -3475,38 +3674,6 @@ that the invoke/unwind semantics are likely to change in future versions.</p> </div> -<!-- _______________________________________________________________________ --> - -<h4> - <a name="i_unwind">'<tt>unwind</tt>' Instruction</a> -</h4> - -<div> - -<h5>Syntax:</h5> -<pre> - unwind -</pre> - -<h5>Overview:</h5> -<p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow - at the first callee in the dynamic call stack which used - an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. - This is primarily used to implement exception handling.</p> - -<h5>Semantics:</h5> -<p>The '<tt>unwind</tt>' instruction causes execution of the current function to - immediately halt. The dynamic call stack is then searched for the - first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. - Once found, execution continues at the "exceptional" destination block - specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> - instruction in the dynamic call chain, undefined behavior results.</p> - -<p>Note that the code generator does not yet completely support unwind, and -that the invoke/unwind semantics are likely to change in future versions.</p> - -</div> - <!-- _______________________________________________________________________ --> <h4> @@ -4691,8 +4858,13 @@ that the invoke/unwind semantics are likely to change in future versions.</p> '<tt>alloca</tt>' instruction is commonly used to represent automatic variables that must have an address available. When the function returns (either with the <tt><a href="#i_ret">ret</a></tt> - or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is - reclaimed. Allocating zero bytes is legal, but the result is undefined.</p> + or <tt><a href="#i_resume">resume</a></tt> instructions), the memory is + reclaimed. Allocating zero bytes is legal, but the result is undefined. + The order in which memory is allocated (ie., which way the stack grows) is + not specified, and relational comparisons involving '<tt>alloca</tt>'s are + undefined.</p> + +<p> <h5>Example:</h5> <pre> @@ -4713,7 +4885,7 @@ that the invoke/unwind semantics are likely to change in future versions.</p> <h5>Syntax:</h5> <pre> - <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] + <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>] <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> !<index> = !{ i32 1 } </pre> @@ -4758,6 +4930,14 @@ that the invoke/unwind semantics are likely to change in future versions.</p> The code generator may select special instructions to save cache bandwidth, such as the <tt>MOVNT</tt> instruction on x86.</p> +<p>The optional <tt>!invariant.load</tt> metadata must reference a single + metatadata name <index> corresponding to a metadata node with no + entries. The existence of the <tt>!invariant.load</tt> metatadata on the + instruction tells the optimizer and code generator that this load address + points to memory which does not change value during program execution. + The optimizer may then move this load around, for example, by hoisting it + out of loops using loop invariant code motion.</p> + <h5>Semantics:</h5> <p>The location of memory pointed to is loaded. If the value being loaded is of scalar type then the number of bytes read does not exceed the minimum number @@ -6011,9 +6191,6 @@ Loop: ; Infinite loop that counts from 0 on up... %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i> </pre> -<p>Note that the code generator does not yet support conditions - with vector type.</p> - </div> <!-- _______________________________________________________________________ --> @@ -6180,8 +6357,8 @@ freestanding environments and non-C-based languages.</p> <h5>Syntax:</h5> <pre> - <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+ - <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>* + <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+ + <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>* <clause> := catch <type> <value> <clause> := filter <array constant type> <array constant> @@ -6195,7 +6372,7 @@ freestanding environments and non-C-based languages.</p> <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It defines values supplied by the personality function (<tt>pers_fn</tt>) upon re-entry to the function. The <tt>resultval</tt> has the - type <tt>somety</tt>.</p> + type <tt>resultty</tt>.</p> <h5>Arguments:</h5> <p>This instruction takes a <tt>pers_fn</tt> value. This is the personality @@ -6219,7 +6396,11 @@ freestanding environments and non-C-based languages.</p> <p>The clauses are applied in order from top to bottom. If two <tt>landingpad</tt> instructions are merged together through inlining, the - clauses from the calling function are appended to the list of clauses.</p> + clauses from the calling function are appended to the list of clauses. + When the call stack is being unwound due to an exception being thrown, the + exception is compared against each <tt>clause</tt> in turn. If it doesn't + match any of the clauses, and the <tt>cleanup</tt> flag is not set, then + unwinding continues further up the call stack.</p> <p>The <tt>landingpad</tt> instruction has several restrictions:</p> diff --git a/docs/Lexicon.html b/docs/Lexicon.html index ae09837..c6c3a81 100644 --- a/docs/Lexicon.html +++ b/docs/Lexicon.html @@ -275,7 +275,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd> </dl> </div> -</div> +</div> <!-- *********************************************************************** --> <hr> <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img diff --git a/docs/Passes.html b/docs/Passes.html index 5c42f3f..840b2ef 100644 --- a/docs/Passes.html +++ b/docs/Passes.html @@ -126,6 +126,7 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <tr><td><a href="#adce">-adce</a></td><td>Aggressive Dead Code Elimination</td></tr> <tr><td><a href="#always-inline">-always-inline</a></td><td>Inliner for always_inline functions</td></tr> <tr><td><a href="#argpromotion">-argpromotion</a></td><td>Promote 'by reference' arguments to scalars</td></tr> +<tr><td><a href="#bb-vectorize">-bb-vectorize</a></td><td>Combine instructions to form vector instructions within basic blocks</td></tr> <tr><td><a href="#block-placement">-block-placement</a></td><td>Profile Guided Basic Block Placement</td></tr> <tr><td><a href="#break-crit-edges">-break-crit-edges</a></td><td>Break critical edges in CFG</td></tr> <tr><td><a href="#codegenprepare">-codegenprepare</a></td><td>Optimize for code generation</td></tr> @@ -817,6 +818,26 @@ perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print " <p>\n" if ! <!-------------------------------------------------------------------------- --> <h3> + <a name="bb-vectorize">-bb-vectorize: Basic-Block Vectorization</a> +</h3> +<div> + <p>This pass combines instructions inside basic blocks to form vector + instructions. It iterates over each basic block, attempting to pair + compatible instructions, repeating this process until no additional + pairs are selected for vectorization. When the outputs of some pair + of compatible instructions are used as inputs by some other pair of + compatible instructions, those pairs are part of a potential + vectorization chain. Instruction pairs are only fused into vector + instructions when they are part of a chain longer than some + threshold length. Moreover, the pass attempts to find the best + possible chain for each pair of compatible instructions. These + heuristics are intended to prevent vectorization in cases where + it would not yield a performance increase of the resulting code. + </p> +</div> + +<!-------------------------------------------------------------------------- --> +<h3> <a name="block-placement">-block-placement: Profile Guided Basic Block Placement</a> </h3> <div> diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 5186203..f4c0322 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -81,6 +81,7 @@ option</a></li> <li><a href="#dss_smallset">"llvm/ADT/SmallSet.h"</a></li> <li><a href="#dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a></li> <li><a href="#dss_denseset">"llvm/ADT/DenseSet.h"</a></li> + <li><a href="#dss_sparseset">"llvm/ADT/SparseSet.h"</a></li> <li><a href="#dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li> <li><a href="#dss_set"><set></a></li> <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li> @@ -1490,6 +1491,24 @@ href="#dss_densemap">DenseMap</a> has. <!-- _______________________________________________________________________ --> <h4> + <a name="dss_sparseset">"llvm/ADT/SparseSet.h"</a> +</h4> + +<div> + +<p>SparseSet holds a small number of objects identified by unsigned keys of +moderate size. It uses a lot of memory, but provides operations that are +almost as fast as a vector. Typical keys are physical registers, virtual +registers, or numbered basic blocks.</p> + +<p>SparseSet is useful for algorithms that need very fast clear/find/insert/erase +and fast iteration over small sets. It is not intended for building composite +data structures.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<h4> <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a> </h4> @@ -1753,7 +1772,7 @@ pointers, or map other small types to each other. <p> There are several aspects of DenseMap that you should be aware of, however. The -iterators in a densemap are invalidated whenever an insertion occurs, unlike +iterators in a DenseMap are invalidated whenever an insertion occurs, unlike map. Also, because DenseMap allocates space for a large number of key/value pairs (it starts with 64 by default), it will waste a lot of space if your keys or values are large. Finally, you must implement a partial specialization of @@ -1761,6 +1780,14 @@ DenseMapInfo for the key that you want, if it isn't already supported. This is required to tell DenseMap about two special marker values (which can never be inserted into the map) that it needs internally.</p> +<p> +DenseMap's find_as() method supports lookup operations using an alternate key +type. This is useful in cases where the normal key type is expensive to +construct, but cheap to compare against. The DenseMapInfo is responsible for +defining the appropriate comparison and hashing methods for each alternate +key type used. +</p> + </div> <!-- _______________________________________________________________________ --> diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index b9361a5..fd95a8a 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -267,6 +267,8 @@ Release Notes</a>.</h1> a fast memory error detector.</li> <li><a href="CodeGenerator.html#machineinstrbundle">MachineInstr Bundles</a>, Support to model instruction bundling / packing.</li> + <li><a href="#armintegratedassembler">ARM Integrated Assembler</a>, + A full featured assembler and direct-to-object support for ARM.</li> <li>....</li> </ul> @@ -284,6 +286,10 @@ Release Notes</a>.</h1> expose new optimization opportunities:</p> <ul> + <li>IR support for half float</li> + <li>IR support for vectors of pointers, including vector GEPs.</li> + <li>Module flags have been introduced. They convey information about the + module as a whole to LLVM subsystems.</li> <li>....</li> </ul> </div> @@ -332,13 +338,33 @@ Release Notes</a>.</h1> <div> +<p>We have changed the way that the Type Legalizer legalizes vectors. The type + legalizer now attempts to promote integer elements. This enabled the + implementation of vector-select. Additionally, we see a performance boost on + workloads which use vectors of chars and shorts, since they are now promoted + to 32-bit types, which are better supported by the SIMD instruction set. + Floating point types are still widened as before.</p> + + <p>We have put a significant amount of work into the code generator infrastructure, which allows us to implement more aggressive algorithms and make it run faster:</p> <ul> - <li>....</li> + <li>TableGen can now synthesize register classes that are only needed to + represent combinations of constraints from instructions and sub-registers. + The synthetic register classes inherit most of their properties form their + closest user-defined super-class.</li> + <li><code>MachineRegisterInfo</code> now allows the reserved registers to be + frozen when register allocation starts. Target hooks should use the + <code>MRI->canReserveReg(FramePtr)</code> method to avoid accidentally + disabling frame pointer elimination during register allocation.</li> + <li>A new kind of <code>MachineOperand</code> provides a compact + representation of large clobber lists on call instructions. The register + mask operand references a bit mask of preserved registers. Everything else + is clobbered.</li> </ul> + </div> <!--=========================================================================--> @@ -351,7 +377,11 @@ Release Notes</a>.</h1> <p>New features and major changes in the X86 target include:</p> <ul> - <li>....</li> + <li>Bug fixes and improved support for AVX1</li> + <li>Support for AVX2 (still incomplete at this point)</li> + <li>Call instructions use the new register mask operands for faster compile + times and better support for different calling conventions. The old WINCALL + instructions are no longer needed.</li> </ul> </div> @@ -366,11 +396,29 @@ Release Notes</a>.</h1> <p>New features of the ARM target include:</p> <ul> - <li>....</li> + <li>The constant island pass now supports basic block and constant pool entry + alignments greater than 4 bytes.</li> + <li>On Darwin, the ARM target now has a full-featured integrated assembler. + </li> </ul> </div> +<h4> +<a name="armintegratedassembler">ARM Integrated Assembler</a> +</h4> +<div> +<p>The ARM target now includes a full featured macro assembler, including +direct-to-object module support for clang. The assembler is currently enabled +by default for Darwin only pending testing and any additional necessary +platform specific support for Linux.</p> +<p>Full support is included for Thumb1, Thumb2 and ARM modes, along with +subtarget and CPU specific extensions for VFP2, VFP3 and NEON.</p> + +<p>The assembler is Unified Syntax only (see ARM Architecural Reference Manual +for details). While there is some, and growing, support for pre-unfied (divided) +syntax, there are still significant gaps in that support.</p> +</div> <!--=========================================================================--> <h3> <a name="MIPS">MIPS Target Improvements</a> @@ -413,9 +461,12 @@ Release Notes</a>.</h1> from the previous release.</p> <ul> -<li>LLVM 3.1 removes support for reading LLVM 2.9 bitcode files. Going forward, - we aim for all future versions of LLVM to read bitcode files and .ll files - produced by LLVM 3.0 and later.</li> + <li>LLVM 3.1 removes support for reading LLVM 2.9 bitcode files. Going + forward, we aim for all future versions of LLVM to read bitcode files and + <tt>.ll</tt> files produced by LLVM 3.0 and later.</li> + <li>The <tt>unwind</tt> instruction is now gone. With the introduction of the + new exception handling system in LLVM 3.0, the <tt>unwind</tt> instruction + became obsolete.</li> <li>....</li> </ul> @@ -439,6 +490,31 @@ Release Notes</a>.</h1> </div> +<!--=========================================================================--> +<h3> +<a name="tools_changes">Tools Changes</a> +</h3> + +<div> + +<p>In addition, some tools have changed in this release. Some of the changes + are:</p> + + +<ul> + <li>llvm-stress is a command line tool for generating random .ll files to fuzz + different LLVM components. </li> + <li>....</li> +</ul> + +<ul> + <li>....</li> +</ul> + +</div> + +</div> + <!-- *********************************************************************** --> <h2> <a name="knownproblems">Known Problems</a> diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index f2741a2..e7eac08 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -446,7 +446,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> i32, ;; Index into a virtual function metadata, ;; indicates which base type contains the vtable pointer for the ;; derived class - i1, ;; isArtificial + i32, ;; Flags - Artifical, Private, Protected, Explicit, Prototyped. i1, ;; isOptimized Function *,;; Pointer to LLVM function metadata, ;; Lists function template parameters @@ -459,8 +459,6 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p> <p>These descriptors provide debug information about functions, methods and subprograms. They provide details such as name, return types and the source location where the subprogram is defined. - All subprogram descriptors are collected by a named metadata - <tt>!llvm.dbg.sp</tt>. </p> </div> @@ -574,8 +572,9 @@ DW_ATE_unsigned_char = 8 i64, ;; Size in bits i64, ;; Alignment in bits i64, ;; Offset in bits + i32, ;; Flags to encode attributes, e.g. private metadata, ;; Reference to type derived from - metadata, ;; (optional) Name of the Objective C property assoicated with + metadata, ;; (optional) Name of the Objective C property associated with ;; Objective-C an ivar metadata, ;; (optional) Name of the Objective C property getter selector. metadata, ;; (optional) Name of the Objective C property setter selector. @@ -610,9 +609,9 @@ DW_TAG_restrict_type = 55 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p> -<p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>, - <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> - and <tt>DW_TAG_restrict_type</tt> are used to qualify +<p><tt>DW_TAG_pointer_type</tt>, <tt>DW_TAG_reference_type</tt>, + <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> and + <tt>DW_TAG_restrict_type</tt> are used to qualify the <a href="#format_derived_type">derived type</a>. </p> <p><a href="#format_derived_type">Derived type</a> location can be determined @@ -833,9 +832,9 @@ DW_TAG_return_variable = 258 void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata) </pre> -<p>This intrinsic provides information about a local element (ex. variable.) The - first argument is metadata holding alloca for the variable. The - second argument is metadata containing description of the variable. </p> +<p>This intrinsic provides information about a local element (e.g., variable). The + first argument is metadata holding the alloca for the variable. The + second argument is metadata containing a description of the variable.</p> </div> <!-- ======================================================================= --> @@ -851,8 +850,8 @@ DW_TAG_return_variable = 258 <p>This intrinsic provides information when a user source variable is set to a new value. The first argument is the new value (wrapped as metadata). The second argument is the offset in the user source variable where the new value - is written. The third argument is metadata containing description of the - user source variable. </p> + is written. The third argument is metadata containing a description of the + user source variable.</p> </div> </div> @@ -1860,11 +1859,32 @@ developers inspect Objective C properties. <!-- *********************************************************************** --> <div> -<p>Objective C properties are always backed by an instance variable. The -instance variables backing properties are identified using -DW_AT_APPLE_property_name attribute. The instance variables with this -attribute may not have data location attributes. The location of instance -variables is determined by debugger only after consulting Objective C runtime. +<p>Objective C properties exist separately from class members. A property +can be defined only by "setter" and "getter" selectors, and +be calculated anew on each access. Or a property can just be a direct access +to some declared ivar. Finally it can have an ivar "automatically +synthesized" for it by the compiler, in which case the property can be +referred to in user code directly using the standard C dereference syntax as +well as through the property "dot" syntax, but there is no entry in +the @interface declaration corresponding to this ivar. +</p> +<p> +To facilitate debugging, these properties we will add a new DWARF TAG into the +DW_TAG_structure_type definition for the class to hold the description of a +given property, and a set of DWARF attributes that provide said description. +The property tag will also contain the name and declared type of the property. +</p> +<p> +If there is a related ivar, there will also be a DWARF property attribute placed +in the DW_TAG_member DIE for that ivar referring back to the property TAG for +that property. And in the case where the compiler synthesizes the ivar directly, +the compiler is expected to generate a DW_TAG_member for that ivar (with the +DW_AT_artificial set to 1), whose name will be the name used to access this +ivar directly in code, and with the property attribute pointing back to the +property it is backing. +</p> +<p> +The following examples will serve as illustration for our discussion: </p> <div class="doc_code"> @@ -1873,34 +1893,66 @@ variables is determined by debugger only after consulting Objective C runtime. int n2; } -@property p1; -@property p2; +@property int p1; +@property int p2; @end @implementation I1 @synthesize p1; @synthesize p2 = n2; @end +</pre> +</div> - -TAG_structure_type [7] * - AT_APPLE_runtime_class( 0x10 ) - AT_name( "I1" ) - AT_decl_file( "Objc_Property.m" ) - AT_decl_line( 3 ) - - TAG_member [8] - AT_name( "p1" ) - AT_APPLE_property_name(“p1”) - AT_type( {0x00000147} ( int ) ) - - TAG_member [8] - AT_name( "n2" ) - AT_APPLE_property_name(“p2”) - AT_type( {0x00000147} ( int ) ) +<p> +This produces the following DWARF (this is a "pseudo dwarfdump" output): +</p> +<div class="doc_code"> +<pre> +0x00000100: TAG_structure_type [7] * + AT_APPLE_runtime_class( 0x10 ) + AT_name( "I1" ) + AT_decl_file( "Objc_Property.m" ) + AT_decl_line( 3 ) + +0x00000110 TAG_APPLE_property + AT_name ( "p1" ) + AT_type ( {0x00000150} ( int ) ) + +0x00000120: TAG_APPLE_property + AT_name ( "p2" ) + AT_type ( {0x00000150} ( int ) ) + +0x00000130: TAG_member [8] + AT_name( "_p1" ) + AT_APPLE_property ( {0x00000110} "p1" ) + AT_type( {0x00000150} ( int ) ) + AT_artificial ( 0x1 ) + +0x00000140: TAG_member [8] + AT_name( "n2" ) + AT_APPLE_property ( {0x00000120} "p2" ) + AT_type( {0x00000150} ( int ) ) + +0x00000150: AT_type( ( int ) ) </pre> </div> +<p> Note, the current convention is that the name of the ivar for an +auto-synthesized property is the name of the property from which it derives with +an underscore prepended, as is shown in the example. +But we actually don't need to know this convention, since we are given the name +of the ivar directly. +</p> + +<p> +Also, it is common practice in ObjC to have different property declarations in +the @interface and @implementation - e.g. to provide a read-only property in +the interface,and a read-write interface in the implementation. In that case, +the compiler should emit whichever property declaration will be in force in the +current translation unit. +</p> + <p> Developers can decorate a property with attributes which are encoded using DW_AT_APPLE_property_attribute. </p> @@ -1908,11 +1960,15 @@ DW_AT_APPLE_property_attribute. <div class="doc_code"> <pre> @property (readonly, nonatomic) int pr; - - -TAG_member [8] - AT_name(“pr”) - AT_APPLE_property_name(“pr”) +</pre> +</div> +<p> +Which produces a property tag: +<p> +<div class="doc_code"> +<pre> +TAG_APPLE_property [8] + AT_name( "pr" ) AT_type ( {0x00000147} (int) ) AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic) </pre> @@ -1932,17 +1988,30 @@ DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes. @synthesize p3; -(void)myOwnP3Setter:(int)a{ } @end +</pre> +</div> +<p> +The DWARF for this would be: +</p> +<div class="doc_code"> +<pre> 0x000003bd: TAG_structure_type [7] * AT_APPLE_runtime_class( 0x10 ) AT_name( "I1" ) AT_decl_file( "Objc_Property.m" ) AT_decl_line( 3 ) -0x000003f3: TAG_member [8] - AT_name( "p3" ) - AT_APPLE_property_name(“p3”) - AT_APPLE_property_setter(“myOwnP3Setter:”) - AT_type( {0x00000147} ( int ) ) + +0x000003cd TAG_APPLE_property + AT_name ( "p3" ) + AT_APPLE_property_setter ( "myOwnP3Setter:" ) + AT_type( {0x00000147} ( int ) ) + +0x000003f3: TAG_member [8] + AT_name( "_p3" ) + AT_type ( {0x00000147} ( int ) ) + AT_APPLE_property ( {0x000003cd} ) + AT_artificial ( 0x1 ) </pre> </div> @@ -1950,6 +2019,26 @@ DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes. <!-- *********************************************************************** --> <h4> + <a name="objcpropertynewtags">New DWARF Tags</a> +</h4> +<!-- *********************************************************************** --> + +<div> +<table border="1" cellspacing="0"> + <tr> + <th width=200 >TAG</th> + <th width=200 >Value</th> + </tr> + <tr> + <td width=200 >DW_TAG_APPLE_property</td> + <td width=200 >0x4200</td> + </tr> +</table> + +</div> + +<!-- *********************************************************************** --> +<h4> <a name="objcpropertynewattributes">New DWARF Attributes</a> </h4> <!-- *********************************************************************** --> @@ -1962,9 +2051,9 @@ DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes. <th width=200 >Classes</th> </tr> <tr> - <td width=200 >DW_AT_APPLE_property_name</td> - <td width=200 >0x3fe8</td> - <td width=200 >String</td> + <td width=200 >DW_AT_APPLE_property</td> + <td width=200 >0x3fed</td> + <td width=200 >Reference</td> </tr> <tr> <td width=200 >DW_AT_APPLE_property_getter</td> diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 6db1827..45baf19 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -37,6 +37,7 @@ <ol> <li><a href="#include">File inclusion</a></li> <li><a href="#globallet">'let' expressions</a></li> + <li><a href="#foreach">'foreach' blocks</a></li> </ol></li> </ol></li> <li><a href="#backends">TableGen backends</a> @@ -401,6 +402,14 @@ which case the user must specify it explicitly.</dd> <dt><tt>list[4-7,17,2-3]</tt></dt> <dd>A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it. Elements may be included multiple times.</dd> +<dt><tt>foreach <var> = <list> in { <body> }</tt></dt> +<dt><tt>foreach <var> = <list> in <def></tt></dt> + <dd> Replicate <body> or <def>, replacing instances of + <var> with each value in <list>. <var> is scoped at the + level of the <tt>foreach</tt> loop and must not conflict with any other object + introduced in <body> or <def>. Currently only <tt>def</tt>s are + expanded within <body>. + </dd> <dt><tt>(DEF a, b)</tt></dt> <dd>a dag value. The first element is required to be a record definition, the remaining elements in the list may be arbitrary other values, including nested @@ -880,6 +889,39 @@ several levels of multiclass instanciations. This also avoids the need of using </pre> </div> +<!-- --------------------------------------------------------------------------> +<h4> + <a name="foreach">Looping</a> +</h4> + +<div> +<p>TableGen supports the '<tt>foreach</tt>' block, which textually replicates +the loop body, substituting iterator values for iterator references in the +body. Example:</p> + +<div class="doc_code"> +<pre> +<b>foreach</b> i = [0, 1, 2, 3] in { + <b>def</b> R#i : Register<...>; + <b>def</b> F#i : Register<...>; +} +</pre> +</div> + +<p>This will create objects <tt>R0</tt>, <tt>R1</tt>, <tt>R2</tt> and +<tt>R3</tt>. <tt>foreach</tt> blocks may be nested. If there is only +one item in the body the braces may be elided:</p> + +<div class="doc_code"> +<pre> +<b>foreach</b> i = [0, 1, 2, 3] in + <b>def</b> R#i : Register<...>; + +</pre> +</div> + +</div> + </div> </div> diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index 5e3d070..3d0dc3f 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -77,7 +77,7 @@ either assembly code or binary code (usable for a JIT compiler). <p> The backend of LLVM features a target-independent code generator that may create -output for several types of target CPUs — including X86, PowerPC, Alpha, +output for several types of target CPUs — including X86, PowerPC, ARM, and SPARC. The backend may also be used to generate code targeted at SPUs of the Cell processor or GPUs to support the execution of compute kernels. </p> diff --git a/docs/doxygen.footer b/docs/doxygen.footer index 15585b8..c492e7d 100644 --- a/docs/doxygen.footer +++ b/docs/doxygen.footer @@ -3,7 +3,7 @@ Generated on $datetime for <a href="http://llvm.org/">$projectname</a> by <a href="http://www.doxygen.org"><img src="doxygen.png" alt="Doxygen" align="middle" border="0"/>$doxygenversion</a><br> -Copyright © 2003-2009 University of Illinois at Urbana-Champaign. +Copyright © 2003-2012 University of Illinois at Urbana-Champaign. All Rights Reserved.</p> <hr> diff --git a/docs/doxygen.header b/docs/doxygen.header index a520434..56fb77f 100644 --- a/docs/doxygen.header +++ b/docs/doxygen.header @@ -2,7 +2,7 @@ <html><head> <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/> <meta name="keywords" content="LLVM,Low Level Virtual Machine,C++,doxygen,API,documentation"/> -<meta name="description" content="C++ source code API documentation for the Low Level Virtual Machine (LLVM)."/> +<meta name="description" content="C++ source code API documentation for LLVM."/> <title>LLVM: $title</title> <link href="doxygen.css" rel="stylesheet" type="text/css"/> </head><body> diff --git a/docs/doxygen.intro b/docs/doxygen.intro index 547730c..699dadc 100644 --- a/docs/doxygen.intro +++ b/docs/doxygen.intro @@ -1,7 +1,7 @@ -/// @mainpage Low Level Virtual Machine +/// @mainpage LLVM /// /// @section main_intro Introduction -/// Welcome to the Low Level Virtual Machine (LLVM). +/// Welcome to LLVM. /// /// This documentation describes the @b internal software that makes /// up LLVM, not the @b external use of LLVM. There are no instructions diff --git a/docs/index.html b/docs/index.html index bfca45b..4d50b4f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -21,7 +21,7 @@ your documentation.</p> <li><a href="#userguide">LLVM User Guides</a></li> <li><a href="#llvmprog">LLVM Programming Documentation</a></li> <li><a href="#subsystems">LLVM Subsystem Documentation</a></li> - <li><a href="#develprocess">LLVM Programming Documentation</a></li> + <li><a href="#develprocess">LLVM Development Process Documentation</a></li> <li><a href="#maillist">LLVM Mailing Lists</a></li> </ul> </td><td class="right"> @@ -98,8 +98,9 @@ the LLVM system.</li> <li><a href="TestingGuide.html">LLVM Testing Infrastructure Guide</a> - A reference manual for using the LLVM testing infrastructure.</li> -<li><a href="GCCFEBuildInstrs.html">How to build the Ada/C/C++/Fortran front-ends</a> - -Instructions for building gcc front-ends from source.</li> +<li><a href="http://clang.llvm.org/get_started.html">How to build the C, C++, ObjC, +and ObjC++ front end</a> - Instructions for building the clang front-end from +source.</li> <li><a href="Packaging.html">Packaging guide</a> - Advice on packaging LLVM into a distribution.</li> |