[llvm-commits] [www-releases] r145585 [1/3] - in /www-releases/trunk/3.0: ./ docs/ docs/CommandGuide/ docs/CommandGuide/html/ docs/CommandGuide/man/ docs/CommandGuide/man/man1/ docs/CommandGuide/ps/ docs/HistoricalNotes/ docs/img/ docs/tutorial/
Tanya Lattner
tonic at nondot.org
Thu Dec 1 09:03:08 PST 2011
Author: tbrethou
Date: Thu Dec 1 11:03:06 2011
New Revision: 145585
URL: http://llvm.org/viewvc/llvm-project?rev=145585&view=rev
Log:
3.0 release.
Added:
www-releases/trunk/3.0/
www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2 (with props)
www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2 (with props)
www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2 (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz (with props)
www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2 (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz.sig (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz (with props)
www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz.sig (with props)
www-releases/trunk/3.0/clang-3.0.tar.gz (with props)
www-releases/trunk/3.0/clang-3.0.tar.gz.sig (with props)
www-releases/trunk/3.0/docs/
www-releases/trunk/3.0/docs/AliasAnalysis.html
www-releases/trunk/3.0/docs/Atomics.html
www-releases/trunk/3.0/docs/BitCodeFormat.html
www-releases/trunk/3.0/docs/BranchWeightMetadata.html
www-releases/trunk/3.0/docs/Bugpoint.html
www-releases/trunk/3.0/docs/CFEBuildInstrs.html
www-releases/trunk/3.0/docs/CMake.html
www-releases/trunk/3.0/docs/CodeGenerator.html
www-releases/trunk/3.0/docs/CodingStandards.html
www-releases/trunk/3.0/docs/CommandGuide/
www-releases/trunk/3.0/docs/CommandGuide/FileCheck.pod
www-releases/trunk/3.0/docs/CommandGuide/Makefile
www-releases/trunk/3.0/docs/CommandGuide/bugpoint.pod
www-releases/trunk/3.0/docs/CommandGuide/html/
www-releases/trunk/3.0/docs/CommandGuide/html/manpage.css
www-releases/trunk/3.0/docs/CommandGuide/index.html
www-releases/trunk/3.0/docs/CommandGuide/lit.pod
www-releases/trunk/3.0/docs/CommandGuide/llc.pod
www-releases/trunk/3.0/docs/CommandGuide/lli.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-ar.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-as.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-bcanalyzer.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-config.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-diff.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-dis.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-extract.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-ld.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-link.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-nm.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-prof.pod
www-releases/trunk/3.0/docs/CommandGuide/llvm-ranlib.pod
www-releases/trunk/3.0/docs/CommandGuide/man/
www-releases/trunk/3.0/docs/CommandGuide/man/man1/
www-releases/trunk/3.0/docs/CommandGuide/manpage.css
www-releases/trunk/3.0/docs/CommandGuide/opt.pod
www-releases/trunk/3.0/docs/CommandGuide/ps/
www-releases/trunk/3.0/docs/CommandGuide/tblgen.pod
www-releases/trunk/3.0/docs/CommandLine.html
www-releases/trunk/3.0/docs/CompilerWriterInfo.html
www-releases/trunk/3.0/docs/DebuggingJITedCode.html
www-releases/trunk/3.0/docs/DeveloperPolicy.html
www-releases/trunk/3.0/docs/ExceptionHandling.html
www-releases/trunk/3.0/docs/ExtendedIntegerResults.txt
www-releases/trunk/3.0/docs/ExtendingLLVM.html
www-releases/trunk/3.0/docs/FAQ.html
www-releases/trunk/3.0/docs/GCCFEBuildInstrs.html
www-releases/trunk/3.0/docs/GarbageCollection.html
www-releases/trunk/3.0/docs/GetElementPtr.html
www-releases/trunk/3.0/docs/GettingStarted.html
www-releases/trunk/3.0/docs/GettingStartedVS.html
www-releases/trunk/3.0/docs/GoldPlugin.html
www-releases/trunk/3.0/docs/HistoricalNotes/
www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveComments.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2002-05-12-InstListChange.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt
www-releases/trunk/3.0/docs/HistoricalNotes/2007-OriginalClangReadme.txt
www-releases/trunk/3.0/docs/HowToReleaseLLVM.html
www-releases/trunk/3.0/docs/HowToSubmitABug.html
www-releases/trunk/3.0/docs/LangRef.html
www-releases/trunk/3.0/docs/Lexicon.html
www-releases/trunk/3.0/docs/LinkTimeOptimization.html
www-releases/trunk/3.0/docs/Makefile
www-releases/trunk/3.0/docs/MakefileGuide.html
www-releases/trunk/3.0/docs/Packaging.html
www-releases/trunk/3.0/docs/Passes.html
www-releases/trunk/3.0/docs/ProgrammersManual.html
www-releases/trunk/3.0/docs/Projects.html
www-releases/trunk/3.0/docs/ReleaseNotes.html
www-releases/trunk/3.0/docs/SegmentedStacks.html
www-releases/trunk/3.0/docs/SourceLevelDebugging.html
www-releases/trunk/3.0/docs/SystemLibrary.html
www-releases/trunk/3.0/docs/TableGenFundamentals.html
www-releases/trunk/3.0/docs/TestingGuide.html
www-releases/trunk/3.0/docs/UsingLibraries.html
www-releases/trunk/3.0/docs/WritingAnLLVMBackend.html
www-releases/trunk/3.0/docs/WritingAnLLVMPass.html
www-releases/trunk/3.0/docs/doxygen.cfg.in
www-releases/trunk/3.0/docs/doxygen.css
www-releases/trunk/3.0/docs/doxygen.footer
www-releases/trunk/3.0/docs/doxygen.header
www-releases/trunk/3.0/docs/doxygen.intro
www-releases/trunk/3.0/docs/img/
www-releases/trunk/3.0/docs/img/Debugging.gif (with props)
www-releases/trunk/3.0/docs/img/libdeps.gif (with props)
www-releases/trunk/3.0/docs/img/lines.gif (with props)
www-releases/trunk/3.0/docs/img/objdeps.gif (with props)
www-releases/trunk/3.0/docs/img/venusflytrap.jpg (with props)
www-releases/trunk/3.0/docs/index.html
www-releases/trunk/3.0/docs/llvm.css
www-releases/trunk/3.0/docs/re_format.7
www-releases/trunk/3.0/docs/tutorial/
www-releases/trunk/3.0/docs/tutorial/LangImpl1.html
www-releases/trunk/3.0/docs/tutorial/LangImpl2.html
www-releases/trunk/3.0/docs/tutorial/LangImpl3.html
www-releases/trunk/3.0/docs/tutorial/LangImpl4.html
www-releases/trunk/3.0/docs/tutorial/LangImpl5-cfg.png (with props)
www-releases/trunk/3.0/docs/tutorial/LangImpl5.html
www-releases/trunk/3.0/docs/tutorial/LangImpl6.html
www-releases/trunk/3.0/docs/tutorial/LangImpl7.html
www-releases/trunk/3.0/docs/tutorial/LangImpl8.html
www-releases/trunk/3.0/docs/tutorial/Makefile
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl1.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl2.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl3.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl4.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl5.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl6.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl7.html
www-releases/trunk/3.0/docs/tutorial/OCamlLangImpl8.html
www-releases/trunk/3.0/docs/tutorial/index.html
www-releases/trunk/3.0/dragonegg-3.0.tar.gz (with props)
www-releases/trunk/3.0/dragonegg-3.0.tar.gz.sig (with props)
www-releases/trunk/3.0/llvm-3.0.tar.gz (with props)
www-releases/trunk/3.0/llvm-3.0.tar.gz.sig (with props)
www-releases/trunk/3.0/test-suite-3.0.tar.gz (with props)
www-releases/trunk/3.0/test-suite-3.0.tar.gz.sig (with props)
Added: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-freebsd9-amd64.tar.bz2?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-freebsd9-amd64.tar.bz2.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-amd64.tar.bz2.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-freebsd9-i386.tar.bz2?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-freebsd9-i386.tar.bz2.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-freebsd9-i386.tar.bz2.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_04.tar.bz2.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-Ubuntu-11_10.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-Ubuntu-11_10.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-Ubuntu-11_10.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-debian.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-i386-linux-debian.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-i386-linux-debian.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-apple-darwin11.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-apple-darwin11.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-apple-darwin11.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_04.tar.bz2.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-Ubuntu-11_10.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-debian.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang%2Bllvm-3.0-x86_64-linux-debian.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang+llvm-3.0-x86_64-linux-debian.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang-3.0.tar.gz
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang-3.0.tar.gz?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang-3.0.tar.gz
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/clang-3.0.tar.gz.sig
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/clang-3.0.tar.gz.sig?rev=145585&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/3.0/clang-3.0.tar.gz.sig
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/3.0/docs/AliasAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/AliasAnalysis.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/AliasAnalysis.html (added)
+++ www-releases/trunk/3.0/docs/AliasAnalysis.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1068 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM Alias Analysis Infrastructure</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ LLVM Alias Analysis Infrastructure
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+
+ <li><a href="#overview"><tt>AliasAnalysis</tt> Class Overview</a>
+ <ul>
+ <li><a href="#pointers">Representation of Pointers</a></li>
+ <li><a href="#alias">The <tt>alias</tt> method</a></li>
+ <li><a href="#ModRefInfo">The <tt>getModRefInfo</tt> methods</a></li>
+ <li><a href="#OtherItfs">Other useful <tt>AliasAnalysis</tt> methods</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#writingnew">Writing a new <tt>AliasAnalysis</tt> Implementation</a>
+ <ul>
+ <li><a href="#passsubclasses">Different Pass styles</a></li>
+ <li><a href="#requiredcalls">Required initialization calls</a></li>
+ <li><a href="#interfaces">Interfaces which may be specified</a></li>
+ <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="#limitations">Limitations</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#using">Using alias analysis results</a>
+ <ul>
+ <li><a href="#memdep">Using the <tt>MemoryDependenceAnalysis</tt> Pass</a></li>
+ <li><a href="#ast">Using the <tt>AliasSetTracker</tt> class</a></li>
+ <li><a href="#direct">Using the <tt>AliasAnalysis</tt> interface directly</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#exist">Existing alias analysis implementations and clients</a>
+ <ul>
+ <li><a href="#impls">Available <tt>AliasAnalysis</tt> implementations</a></li>
+ <li><a href="#aliasanalysis-xforms">Alias analysis driven transformations</a></li>
+ <li><a href="#aliasanalysis-debug">Clients for debugging and evaluation of
+ implementations</a></li>
+ </ul>
+ </li>
+ <li><a href="#memdep">Memory Dependence Analysis</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Alias Analysis (aka Pointer Analysis) is a class of techniques which attempt
+to determine whether or not two pointers ever can point to the same object in
+memory. There are many different algorithms for alias analysis and many
+different ways of classifying them: flow-sensitive vs flow-insensitive,
+context-sensitive vs context-insensitive, field-sensitive vs field-insensitive,
+unification-based vs subset-based, etc. Traditionally, alias analyses respond
+to a query with a <a href="#MustMayNo">Must, May, or No</a> alias response,
+indicating that two pointers always point to the same object, might point to the
+same object, or are known to never point to the same object.</p>
+
+<p>The LLVM <a
+href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+class is the primary interface used by clients and implementations of alias
+analyses in the LLVM system. This class is the common interface between clients
+of alias analysis information and the implementations providing it, and is
+designed to support a wide range of implementations and clients (but currently
+all clients are assumed to be flow-insensitive). In addition to simple alias
+analysis information, this class exposes Mod/Ref information from those
+implementations which can provide it, allowing for powerful analyses and
+transformations to work well together.</p>
+
+<p>This document contains information necessary to successfully implement this
+interface, use it, and to test both sides. It also explains some of the finer
+points about what exactly results mean. If you feel that something is unclear
+or should be added, please <a href="mailto:sabre at nondot.org">let me
+know</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="overview"><tt>AliasAnalysis</tt> Class Overview</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The <a
+href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+class defines the interface that the various alias analysis implementations
+should support. This class exports two important enums: <tt>AliasResult</tt>
+and <tt>ModRefResult</tt> which represent the result of an alias query or a
+mod/ref query, respectively.</p>
+
+<p>The <tt>AliasAnalysis</tt> interface exposes information about memory,
+represented in several different ways. In particular, memory objects are
+represented as a starting address and size, and function calls are represented
+as the actual <tt>call</tt> or <tt>invoke</tt> instructions that performs the
+call. The <tt>AliasAnalysis</tt> interface also exposes some helper methods
+which allow you to get mod/ref information for arbitrary instructions.</p>
+
+<p>All <tt>AliasAnalysis</tt> interfaces require that in queries involving
+multiple values, values which are not
+<a href="LangRef.html#constants">constants</a> are all defined within the
+same function.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="pointers">Representation of Pointers</a>
+</h3>
+
+<div>
+
+<p>Most importantly, the <tt>AliasAnalysis</tt> class provides several methods
+which are used to query whether or not two memory objects alias, whether
+function calls can modify or read a memory object, etc. For all of these
+queries, memory objects are represented as a pair of their starting address (a
+symbolic LLVM <tt>Value*</tt>) and a static size.</p>
+
+<p>Representing memory objects as a starting address and a size is critically
+important for correct Alias Analyses. For example, consider this (silly, but
+possible) C code:</p>
+
+<div class="doc_code">
+<pre>
+int i;
+char C[2];
+char A[10];
+/* ... */
+for (i = 0; i != 10; ++i) {
+ C[0] = A[i]; /* One byte store */
+ C[1] = A[9-i]; /* One byte store */
+}
+</pre>
+</div>
+
+<p>In this case, the <tt>basicaa</tt> pass will disambiguate the stores to
+<tt>C[0]</tt> and <tt>C[1]</tt> because they are accesses to two distinct
+locations one byte apart, and the accesses are each one byte. In this case, the
+LICM pass can use store motion to remove the stores from the loop. In
+constrast, the following code:</p>
+
+<div class="doc_code">
+<pre>
+int i;
+char C[2];
+char A[10];
+/* ... */
+for (i = 0; i != 10; ++i) {
+ ((short*)C)[0] = A[i]; /* Two byte store! */
+ C[1] = A[9-i]; /* One byte store */
+}
+</pre>
+</div>
+
+<p>In this case, the two stores to C do alias each other, because the access to
+the <tt>&C[0]</tt> element is a two byte access. If size information wasn't
+available in the query, even the first case would have to conservatively assume
+that the accesses alias.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="alias">The <tt>alias</tt> method</a>
+</h3>
+
+<div>
+<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, 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
+least one of the values is a <a href="LangRef.html#constants">constant</a>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="MustMayNo">Must, May, and No Alias Responses</a>
+</h4>
+
+<div>
+<p>The NoAlias response may be used when there is never an immediate dependence
+between any memory reference <i>based</i> on one pointer and any memory
+reference <i>based</i> the other. The most obvious example is when the two
+pointers point to non-overlapping memory ranges. Another is when the two
+pointers are only ever used for reading memory. Another is when the memory is
+freed and reallocated between accesses through one pointer and accesses through
+the other -- in this case, there is a dependence, but it's mediated by the free
+and reallocation.</p>
+
+<p>As an exception to this is with the
+<a href="LangRef.html#noalias"><tt>noalias</tt></a> keyword; the "irrelevant"
+dependencies are ignored.</p>
+
+<p>The MayAlias response is used whenever the two pointers might refer to the
+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
+implies that the pointers compare equal.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ModRefInfo">The <tt>getModRefInfo</tt> methods</a>
+</h3>
+
+<div>
+
+<p>The <tt>getModRefInfo</tt> methods return information about whether the
+execution of an instruction can read or modify a memory location. Mod/Ref
+information is always conservative: if an instruction <b>might</b> read or write
+a location, ModRef is returned.</p>
+
+<p>The <tt>AliasAnalysis</tt> class also provides a <tt>getModRefInfo</tt>
+method for testing dependencies between function calls. This method takes two
+call sites (CS1 & CS2), returns NoModRef if neither call writes to memory
+read or written by the other, Ref if CS1 reads memory written by CS2, Mod if CS1
+writes to memory read or written by CS2, or ModRef if CS1 might read or write
+memory written to by CS2. Note that this relation is not commutative.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="OtherItfs">Other useful <tt>AliasAnalysis</tt> methods</a>
+</h3>
+
+<div>
+
+<p>
+Several other tidbits of information are often collected by various alias
+analysis implementations and can be put to good use by various clients.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ The <tt>pointsToConstantMemory</tt> method
+</h4>
+
+<div>
+
+<p>The <tt>pointsToConstantMemory</tt> method returns true if and only if the
+analysis can prove that the pointer only points to unchanging memory locations
+(functions, constant global variables, and the null pointer). This information
+can be used to refine mod/ref information: it is impossible for an unchanging
+memory location to be modified.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="simplemodref">The <tt>doesNotAccessMemory</tt> and
+ <tt>onlyReadsMemory</tt> methods</a>
+</h4>
+
+<div>
+
+<p>These methods are used to provide very simple mod/ref information for
+function calls. The <tt>doesNotAccessMemory</tt> method returns true for a
+function if the analysis can prove that the function never reads or writes to
+memory, or if the function only reads from constant memory. Functions with this
+property are side-effect free and only depend on their input arguments, allowing
+them to be eliminated if they form common subexpressions or be hoisted out of
+loops. Many common functions behave this way (e.g., <tt>sin</tt> and
+<tt>cos</tt>) but many others do not (e.g., <tt>acos</tt>, which modifies the
+<tt>errno</tt> variable).</p>
+
+<p>The <tt>onlyReadsMemory</tt> method returns true for a function if analysis
+can prove that (at most) the function only reads from non-volatile memory.
+Functions with this property are side-effect free, only depending on their input
+arguments and the state of memory when they are called. This property allows
+calls to these functions to be eliminated and moved around, as long as there is
+no store instruction that changes the contents of memory. Note that all
+functions that satisfy the <tt>doesNotAccessMemory</tt> method also satisfies
+<tt>onlyReadsMemory</tt>.</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="writingnew">Writing a new <tt>AliasAnalysis</tt> Implementation</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Writing a new alias analysis implementation for LLVM is quite
+straight-forward. There are already several implementations that you can use
+for examples, and the following information should help fill in any details.
+For a examples, take a look at the <a href="#impls">various alias analysis
+implementations</a> included with LLVM.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="passsubclasses">Different Pass styles</a>
+</h3>
+
+<div>
+
+<p>The first step to determining what type of <a
+href="WritingAnLLVMPass.html">LLVM pass</a> you need to use for your Alias
+Analysis. As is the case with most other analyses and transformations, the
+answer should be fairly obvious from what type of problem you are trying to
+solve:</p>
+
+<ol>
+ <li>If you require interprocedural analysis, it should be a
+ <tt>Pass</tt>.</li>
+ <li>If you are a function-local analysis, subclass <tt>FunctionPass</tt>.</li>
+ <li>If you don't need to look at the program at all, subclass
+ <tt>ImmutablePass</tt>.</li>
+</ol>
+
+<p>In addition to the pass that you subclass, you should also inherit from the
+<tt>AliasAnalysis</tt> interface, of course, and use the
+<tt>RegisterAnalysisGroup</tt> template to register as an implementation of
+<tt>AliasAnalysis</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="requiredcalls">Required initialization calls</a>
+</h3>
+
+<div>
+
+<p>Your subclass of <tt>AliasAnalysis</tt> is required to invoke two methods on
+the <tt>AliasAnalysis</tt> base class: <tt>getAnalysisUsage</tt> and
+<tt>InitializeAliasAnalysis</tt>. In particular, your implementation of
+<tt>getAnalysisUsage</tt> should explicitly call into the
+<tt>AliasAnalysis::getAnalysisUsage</tt> method in addition to doing any
+declaring any pass dependencies your pass has. Thus you should have something
+like this:</p>
+
+<div class="doc_code">
+<pre>
+void getAnalysisUsage(AnalysisUsage &AU) const {
+ AliasAnalysis::getAnalysisUsage(AU);
+ <i>// declare your dependencies here.</i>
+}
+</pre>
+</div>
+
+<p>Additionally, your must invoke the <tt>InitializeAliasAnalysis</tt> method
+from your analysis run method (<tt>run</tt> for a <tt>Pass</tt>,
+<tt>runOnFunction</tt> for a <tt>FunctionPass</tt>, or <tt>InitializePass</tt>
+for an <tt>ImmutablePass</tt>). For example (as part of a <tt>Pass</tt>):</p>
+
+<div class="doc_code">
+<pre>
+bool run(Module &M) {
+ InitializeAliasAnalysis(this);
+ <i>// Perform analysis here...</i>
+ return false;
+}
+</pre>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="interfaces">Interfaces which may be specified</a>
+</h3>
+
+<div>
+
+<p>All of the <a
+href="/doxygen/classllvm_1_1AliasAnalysis.html"><tt>AliasAnalysis</tt></a>
+virtual methods default to providing <a href="#chaining">chaining</a> to another
+alias analysis implementation, which ends up returning conservatively correct
+information (returning "May" Alias and "Mod/Ref" for alias and mod/ref queries
+respectively). Depending on the capabilities of the analysis you are
+implementing, you just override the interfaces you can improve.</p>
+
+</div>
+
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="chaining"><tt>AliasAnalysis</tt> chaining behavior</a>
+</h3>
+
+<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
+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
+for methods that you don't override. For methods that you do override, in code
+paths that return a conservative MayAlias or Mod/Ref result, simply return
+whatever the superclass computes. For example:</p>
+
+<div class="doc_code">
+<pre>
+AliasAnalysis::AliasResult alias(const Value *V1, unsigned V1Size,
+ const Value *V2, unsigned V2Size) {
+ if (...)
+ return NoAlias;
+ ...
+
+ <i>// Couldn't determine a must or no-alias result.</i>
+ return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
+}
+</pre>
+</div>
+
+<p>In addition to analysis queries, you must make sure to unconditionally pass
+LLVM <a href="#updating">update notification</a> methods to the superclass as
+well if you override them, which allows all alias analyses in a change to be
+updated.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="updating">Updating analysis results for transformations</a>
+</h3>
+
+<div>
+<p>
+Alias analysis information is initially computed for a static snapshot of the
+program, but clients will use this information to make transformations to the
+code. All but the most trivial forms of alias analysis will need to have their
+analysis results updated to reflect the changes made by these transformations.
+</p>
+
+<p>
+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
+example, when an instruction is deleted), and clients of alias analysis must be
+sure to call these interfaces appropriately.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>The <tt>deleteValue</tt> method</h4>
+
+<div>
+The <tt>deleteValue</tt> method is called by transformations when they remove an
+instruction or any other value from the program (including values that do not
+use pointers). Typically alias analyses keep data structures that have entries
+for each value in the program. When this method is called, they should remove
+any entries for the specified value, if they exist.
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>The <tt>copyValue</tt> method</h4>
+
+<div>
+The <tt>copyValue</tt> method is used when a new value is introduced into the
+program. There is no way to introduce a value into the program that did not
+exist before (this doesn't make sense for a safe compiler transformation), so
+this is the only way to introduce a new value. This method indicates that the
+new value has exactly the same properties as the value being copied.
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>The <tt>replaceWithNewValue</tt> method</h4>
+
+<div>
+This method is a simple helper method that is provided to make clients easier to
+use. It is implemented by copying the old analysis information to the new
+value, then deleting the old value. This method cannot be overridden by alias
+analysis implementations.
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>The <tt>addEscapingUse</tt> method</h4>
+
+<div>
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="implefficiency">Efficiency Issues</a>
+</h3>
+
+<div>
+
+<p>From the LLVM perspective, the only thing you need to do to provide an
+efficient alias analysis is to make sure that alias analysis <b>queries</b> are
+serviced quickly. The actual calculation of the alias analysis results (the
+"run" method) is only performed once, but many (perhaps duplicate) queries may
+be performed. Because of this, try to move as much computation to the run
+method as possible (within reason).</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="limitations">Limitations</a>
+</h3>
+
+<div>
+
+<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
+have it use -my-aa for all passes which need AliasAnalysis, but there
+is currently no support for that, short of changing the source code
+and recompiling. Similarly, there is also no way of setting a chain
+of analyses as the default.</p>
+
+<p>There is no way for transform passes to declare that they preserve
+<tt>AliasAnalysis</tt> implementations. The <tt>AliasAnalysis</tt>
+interface includes <tt>deleteValue</tt> and <tt>copyValue</tt> methods
+which are intended to allow a pass to keep an AliasAnalysis consistent,
+however there's no way for a pass to declare in its
+<tt>getAnalysisUsage</tt> that it does so. Some passes attempt to use
+<tt>AU.addPreserved<AliasAnalysis></tt>, however this doesn't
+actually have any effect.</p>
+
+<p><tt>AliasAnalysisCounter</tt> (<tt>-count-aa</tt>) and <tt>AliasDebugger</tt>
+(<tt>-debug-aa</tt>) are implemented as <tt>ModulePass</tt> classes, so if your
+alias analysis uses <tt>FunctionPass</tt>, it won't be able to use
+these utilities. If you try to use them, the pass manager will
+silently route alias analysis queries directly to
+<tt>BasicAliasAnalysis</tt> instead.</p>
+
+<p>Similarly, the <tt>opt -p</tt> option introduces <tt>ModulePass</tt>
+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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="using">Using alias analysis results</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>There are several different ways to use alias analysis results. In order of
+preference, these are...</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="memdep">Using the <tt>MemoryDependenceAnalysis</tt> Pass</a>
+</h3>
+
+<div>
+
+<p>The <tt>memdep</tt> pass uses alias analysis to provide high-level dependence
+information about memory-using instructions. This will tell you which store
+feeds into a load, for example. It uses caching and other techniques to be
+efficient, and is used by Dead Store Elimination, GVN, and memcpy optimizations.
+</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ast">Using the <tt>AliasSetTracker</tt> class</a>
+</h3>
+
+<div>
+
+<p>Many transformations need information about alias <b>sets</b> that are active
+in some scope, rather than information about pairwise aliasing. The <tt><a
+href="/doxygen/classllvm_1_1AliasSetTracker.html">AliasSetTracker</a></tt> class
+is used to efficiently build these Alias Sets from the pairwise alias analysis
+information provided by the <tt>AliasAnalysis</tt> interface.</p>
+
+<p>First you initialize the AliasSetTracker by using the "<tt>add</tt>" methods
+to add information about various potentially aliasing instructions in the scope
+you are interested in. Once all of the alias sets are completed, your pass
+should simply iterate through the constructed alias sets, using the
+<tt>AliasSetTracker</tt> <tt>begin()</tt>/<tt>end()</tt> methods.</p>
+
+<p>The <tt>AliasSet</tt>s formed by the <tt>AliasSetTracker</tt> are guaranteed
+to be disjoint, calculate mod/ref information and volatility for the set, and
+keep track of whether or not all of the pointers in the set are Must aliases.
+The AliasSetTracker also makes sure that sets are properly folded due to call
+instructions, and can provide a list of pointers in each set.</p>
+
+<p>As an example user of this, the <a href="/doxygen/structLICM.html">Loop
+Invariant Code Motion</a> pass uses <tt>AliasSetTracker</tt>s to calculate alias
+sets for each loop nest. If an <tt>AliasSet</tt> in a loop is not modified,
+then all load instructions from that set may be hoisted out of the loop. If any
+alias sets are stored to <b>and</b> are must alias sets, then the stores may be
+sunk to outside of the loop, promoting the memory location to a register for the
+duration of the loop nest. Both of these transformations only apply if the
+pointer argument is loop-invariant.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ The AliasSetTracker implementation
+</h4>
+
+<div>
+
+<p>The AliasSetTracker class is implemented to be as efficient as possible. It
+uses the union-find algorithm to efficiently merge AliasSets when a pointer is
+inserted into the AliasSetTracker that aliases multiple sets. The primary data
+structure is a hash table mapping pointers to the AliasSet they are in.</p>
+
+<p>The AliasSetTracker class must maintain a list of all of the LLVM Value*'s
+that are in each AliasSet. Since the hash table already has entries for each
+LLVM Value* of interest, the AliasesSets thread the linked list through these
+hash-table nodes to avoid having to allocate memory unnecessarily, and to make
+merging alias sets extremely efficient (the linked list merge is constant time).
+</p>
+
+<p>You shouldn't need to understand these details if you are just a client of
+the AliasSetTracker, but if you look at the code, hopefully this brief
+description will help make sense of why things are designed the way they
+are.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="direct">Using the <tt>AliasAnalysis</tt> interface directly</a>
+</h3>
+
+<div>
+
+<p>If neither of these utility class are what your pass needs, you should use
+the interfaces exposed by the <tt>AliasAnalysis</tt> class directly. Try to use
+the higher-level methods when possible (e.g., use mod/ref information instead of
+the <a href="#alias"><tt>alias</tt></a> method directly if possible) to get the
+best precision and efficiency.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="exist">Existing alias analysis implementations and clients</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>If you're going to be working with the LLVM alias analysis infrastructure,
+you should know what clients and implementations of alias analysis are
+available. In particular, if you are implementing an alias analysis, you should
+be aware of the <a href="#aliasanalysis-debug">the clients</a> that are useful
+for monitoring and evaluating different implementations.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="impls">Available <tt>AliasAnalysis</tt> implementations</a>
+</h3>
+
+<div>
+
+<p>This section lists the various implementations of the <tt>AliasAnalysis</tt>
+interface. With the exception of the <a href="#no-aa"><tt>-no-aa</tt></a>
+implementation, all of these <a href="#chaining">chain</a> to other alias
+analysis implementations.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="no-aa">The <tt>-no-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-no-aa</tt> pass is just like what it sounds: an alias analysis that
+never returns any useful information. This pass can be useful if you think that
+alias analysis is doing something wrong and are trying to narrow down a
+problem.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="basic-aa">The <tt>-basicaa</tt> pass</a>
+</h4>
+
+<div>
+
+<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
+ alias.</li>
+<li>Globals, stack allocations, and heap allocations never alias the null
+ pointer.</li>
+<li>Different fields of a structure do not alias.</li>
+<li>Indexes into arrays with statically differing subscripts cannot alias.</li>
+<li>Many common standard C library functions <a
+ href="#simplemodref">never access memory or only read memory</a>.</li>
+<li>Pointers that obviously point to constant globals
+ "<tt>pointToConstantMemory</tt>".</li>
+<li>Function calls can not modify or references stack allocations if they never
+ escape from the function that allocates them (a common case for automatic
+ arrays).</li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="globalsmodref">The <tt>-globalsmodref-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>This pass implements a simple context-sensitive mod/ref and alias analysis
+for internal global variables that don't "have their address taken". If a
+global does not have its address taken, the pass knows that no pointers alias
+the global. This pass also keeps track of functions that it knows never access
+memory or never read memory. This allows certain optimizations (e.g. GVN) to
+eliminate call instructions entirely.
+</p>
+
+<p>The real power of this pass is that it provides context-sensitive mod/ref
+information for call instructions. This allows the optimizer to know that
+calls to a function do not clobber or read the value of the global, allowing
+loads and stores to be eliminated.</p>
+
+<p>Note that this pass is somewhat limited in its scope (only support
+non-address taken globals), but is very quick analysis.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="steens-aa">The <tt>-steens-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-steens-aa</tt> pass implements a variation on the well-known
+"Steensgaard's algorithm" for interprocedural alias analysis. Steensgaard's
+algorithm is a unification-based, flow-insensitive, context-insensitive, and
+field-insensitive alias analysis that is also very scalable (effectively linear
+time).</p>
+
+<p>The LLVM <tt>-steens-aa</tt> pass implements a "speculatively
+field-<b>sensitive</b>" version of Steensgaard's algorithm using the Data
+Structure Analysis framework. This gives it substantially more precision than
+the standard algorithm while maintaining excellent analysis scalability.</p>
+
+<p>Note that <tt>-steens-aa</tt> is available in the optional "poolalloc"
+module, it is not part of the LLVM core.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ds-aa">The <tt>-ds-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-ds-aa</tt> pass implements the full Data Structure Analysis
+algorithm. Data Structure Analysis is a modular unification-based,
+flow-insensitive, context-<b>sensitive</b>, and speculatively
+field-<b>sensitive</b> alias analysis that is also quite scalable, usually at
+O(n*log(n)).</p>
+
+<p>This algorithm is capable of responding to a full variety of alias analysis
+queries, and can provide context-sensitive mod/ref information as well. The
+only major facility not implemented so far is support for must-alias
+information.</p>
+
+<p>Note that <tt>-ds-aa</tt> is available in the optional "poolalloc"
+module, it is not part of the LLVM core.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scev-aa">The <tt>-scev-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-scev-aa</tt> pass implements AliasAnalysis queries by
+translating them into ScalarEvolution queries. This gives it a
+more complete understanding of <tt>getelementptr</tt> instructions
+and loop induction variables than other alias analyses have.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="aliasanalysis-xforms">Alias analysis driven transformations</a>
+</h3>
+
+<div>
+LLVM includes several alias-analysis driven transformations which can be used
+with any of the implementations above.
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="adce">The <tt>-adce</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-adce</tt> pass, which implements Aggressive Dead Code Elimination
+uses the <tt>AliasAnalysis</tt> interface to delete calls to functions that do
+not have side-effects and are not used.</p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="licm">The <tt>-licm</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-licm</tt> pass implements various Loop Invariant Code Motion related
+transformations. It uses the <tt>AliasAnalysis</tt> interface for several
+different transformations:</p>
+
+<ul>
+<li>It uses mod/ref information to hoist or sink load instructions out of loops
+if there are no instructions in the loop that modifies the memory loaded.</li>
+
+<li>It uses mod/ref information to hoist function calls out of loops that do not
+write to memory and are loop-invariant.</li>
+
+<li>If uses alias information to promote memory objects that are loaded and
+stored to in loops to live in a register instead. It can do this if there are
+no may aliases to the loaded/stored memory location.</li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="argpromotion">The <tt>-argpromotion</tt> pass</a>
+</h4>
+
+<div>
+<p>
+The <tt>-argpromotion</tt> pass promotes by-reference arguments to be passed in
+by-value instead. In particular, if pointer arguments are only loaded from it
+passes in the value loaded instead of the address to the function. This pass
+uses alias information to make sure that the value loaded from the argument
+pointer is not modified between the entry of the function and any load of the
+pointer.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="gvn">The <tt>-gvn</tt>, <tt>-memcpyopt</tt>, and <tt>-dse</tt>
+ passes</a>
+</h4>
+
+<div>
+
+<p>These passes use AliasAnalysis information to reason about loads and stores.
+</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="aliasanalysis-debug">Clients for debugging and evaluation of
+ implementations</a>
+</h3>
+
+<div>
+
+<p>These passes are useful for evaluating the various alias analysis
+implementations. You can use them with commands like '<tt>opt -ds-aa
+-aa-eval foo.bc -disable-output -stats</tt>'.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="print-alias-sets">The <tt>-print-alias-sets</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-print-alias-sets</tt> pass is exposed as part of the
+<tt>opt</tt> tool to print out the Alias Sets formed by the <a
+href="#ast"><tt>AliasSetTracker</tt></a> class. This is useful if you're using
+the <tt>AliasSetTracker</tt> class. To use it, use something like:</p>
+
+<div class="doc_code">
+<pre>
+% opt -ds-aa -print-alias-sets -disable-output
+</pre>
+</div>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="count-aa">The <tt>-count-aa</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-count-aa</tt> pass is useful to see how many queries a particular
+pass is making and what responses are returned by the alias analysis. As an
+example,</p>
+
+<div class="doc_code">
+<pre>
+% opt -basicaa -count-aa -ds-aa -count-aa -licm
+</pre>
+</div>
+
+<p>will print out how many queries (and what responses are returned) by the
+<tt>-licm</tt> pass (of the <tt>-ds-aa</tt> pass) and how many queries are made
+of the <tt>-basicaa</tt> pass by the <tt>-ds-aa</tt> pass. This can be useful
+when debugging a transformation or an alias analysis implementation.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="aa-eval">The <tt>-aa-eval</tt> pass</a>
+</h4>
+
+<div>
+
+<p>The <tt>-aa-eval</tt> pass simply iterates through all pairs of pointers in a
+function and asks an alias analysis whether or not the pointers alias. This
+gives an indication of the precision of the alias analysis. Statistics are
+printed indicating the percent of no/may/must aliases found (a more precise
+algorithm will have a lower number of may aliases).</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="memdep">Memory Dependence Analysis</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>If you're just looking to be a client of alias analysis information, consider
+using the Memory Dependence Analysis interface instead. MemDep is a lazy,
+caching layer on top of alias analysis that is able to answer the question of
+what preceding memory operations a given instruction depends on, either at an
+intra- or inter-block level. Because of its laziness and caching
+policy, using MemDep can be a significant performance win over accessing alias
+analysis directly.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:23 -0500 (Thu, 03 Nov 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/Atomics.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/Atomics.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/Atomics.html (added)
+++ www-releases/trunk/3.0/docs/Atomics.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,569 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>LLVM Atomic Instructions and Concurrency Guide</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ LLVM Atomic Instructions and Concurrency Guide
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#outsideatomic">Optimization outside atomic</a></li>
+ <li><a href="#atomicinst">Atomic instructions</a></li>
+ <li><a href="#ordering">Atomic orderings</a></li>
+ <li><a href="#iropt">Atomics and IR optimization</a></li>
+ <li><a href="#codegen">Atomics and Codegen</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by Eli Friedman</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Historically, LLVM has not had very strong support for concurrency; some
+minimal intrinsics were provided, and <code>volatile</code> was used in some
+cases to achieve rough semantics in the presence of concurrency. However, this
+is changing; there are now new instructions which are well-defined in the
+presence of threads and asynchronous signals, and the model for existing
+instructions has been clarified in the IR.</p>
+
+<p>The atomic instructions are designed specifically to provide readable IR and
+ optimized code generation for the following:</p>
+<ul>
+ <li>The new C++0x <code><atomic></code> header.
+ (<a href="http://www.open-std.org/jtc1/sc22/wg21/">C++0x draft available here</a>.)
+ (<a href="http://www.open-std.org/jtc1/sc22/wg14/">C1x draft available here</a>)</li>
+ <li>Proper semantics for Java-style memory, for both <code>volatile</code> and
+ regular shared variables.
+ (<a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">Java Specification</a>)</li>
+ <li>gcc-compatible <code>__sync_*</code> builtins.
+ (<a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Description</a>)</li>
+ <li>Other scenarios with atomic semantics, including <code>static</code>
+ variables with non-trivial constructors in C++.</li>
+</ul>
+
+<p>Atomic and volatile in the IR are orthogonal; "volatile" is the C/C++
+ volatile, which ensures that every volatile load and store happens and is
+ performed in the stated order. A couple examples: if a
+ SequentiallyConsistent store is immediately followed by another
+ SequentiallyConsistent store to the same address, the first store can
+ be erased. This transformation is not allowed for a pair of volatile
+ stores. On the other hand, a non-volatile non-atomic load can be moved
+ across a volatile load freely, but not an Acquire load.</p>
+
+<p>This document is intended to provide a guide to anyone either writing a
+ frontend for LLVM or working on optimization passes for LLVM with a guide
+ for how to deal with instructions with special semantics in the presence of
+ concurrency. This is not intended to be a precise guide to the semantics;
+ the details can get extremely complicated and unreadable, and are not
+ usually necessary.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="outsideatomic">Optimization outside atomic</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The basic <code>'load'</code> and <code>'store'</code> allow a variety of
+ optimizations, but can lead to undefined results in a concurrent environment;
+ see <a href="#o_nonatomic">NonAtomic</a>. This section specifically goes
+ into the one optimizer restriction which applies in concurrent environments,
+ which gets a bit more of an extended description because any optimization
+ dealing with stores needs to be aware of it.</p>
+
+<p>From the optimizer's point of view, the rule is that if there
+ are not any instructions with atomic ordering involved, concurrency does
+ not matter, with one exception: if a variable might be visible to another
+ thread or signal handler, a store cannot be inserted along a path where it
+ might not execute otherwise. Take the following example:</p>
+
+<pre>
+/* C code, for readability; run through clang -O2 -S -emit-llvm to get
+ equivalent IR */
+int x;
+void f(int* a) {
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ x += 1;
+ }
+}
+</pre>
+
+<p>The following is equivalent in non-concurrent situations:</p>
+
+<pre>
+int x;
+void f(int* a) {
+ int xtemp = x;
+ for (int i = 0; i < 100; i++) {
+ if (a[i])
+ xtemp += 1;
+ }
+ x = xtemp;
+}
+</pre>
+
+<p>However, LLVM is not allowed to transform the former to the latter: it could
+ indirectly introduce undefined behavior if another thread can access x at
+ the same time. (This example is particularly of interest because before the
+ concurrency model was implemented, LLVM would perform this
+ transformation.)</p>
+
+<p>Note that speculative loads are allowed; a load which
+ is part of a race returns <code>undef</code>, but does not have undefined
+ behavior.</p>
+
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="atomicinst">Atomic instructions</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>For cases where simple loads and stores are not sufficient, LLVM provides
+ various atomic instructions. The exact guarantees provided depend on the
+ ordering; see <a href="#ordering">Atomic orderings</a></p>
+
+<p><code>load atomic</code> and <code>store atomic</code> provide the same
+ basic functionality as non-atomic loads and stores, but provide additional
+ guarantees in situations where threads and signals are involved.</p>
+
+<p><code>cmpxchg</code> and <code>atomicrmw</code> are essentially like an
+ atomic load followed by an atomic store (where the store is conditional for
+ <code>cmpxchg</code>), but no other memory operation can happen on any thread
+ between the load and store. Note that LLVM's cmpxchg does not provide quite
+ as many options as the C++0x version.</p>
+
+<p>A <code>fence</code> provides Acquire and/or Release ordering which is not
+ part of another operation; it is normally used along with Monotonic memory
+ operations. A Monotonic load followed by an Acquire fence is roughly
+ equivalent to an Acquire load.</p>
+
+<p>Frontends generating atomic instructions generally need to be aware of the
+ target to some degree; atomic instructions are guaranteed to be lock-free,
+ and therefore an instruction which is wider than the target natively supports
+ can be impossible to generate.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="ordering">Atomic orderings</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>In order to achieve a balance between performance and necessary guarantees,
+ there are six levels of atomicity. They are listed in order of strength;
+ each level includes all the guarantees of the previous level except for
+ Acquire/Release. (See also <a href="LangRef.html#ordering">LangRef</a>.)</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_notatomic">NotAtomic</a>
+</h3>
+
+<div>
+
+<p>NotAtomic is the obvious, a load or store which is not atomic. (This isn't
+ really a level of atomicity, but is listed here for comparison.) This is
+ essentially a regular load or store. If there is a race on a given memory
+ location, loads from that location return undef.</p>
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This is intended to match shared variables in C/C++, and to be used
+ in any other context where memory access is necessary, and
+ a race is impossible. (The precise definition is in
+ <a href="LangRef.html#memmodel">LangRef</a>.)
+ <dt>Notes for frontends</dt>
+ <dd>The rule is essentially that all memory accessed with basic loads and
+ stores by multiple threads should be protected by a lock or other
+ synchronization; otherwise, you are likely to run into undefined
+ behavior. If your frontend is for a "safe" language like Java,
+ use Unordered to load and store any shared variable. Note that NotAtomic
+ volatile loads and stores are not properly atomic; do not try to use
+ them as a substitute. (Per the C/C++ standards, volatile does provide
+ some limited guarantees around asynchronous signals, but atomics are
+ generally a better solution.)
+ <dt>Notes for optimizers</dt>
+ <dd>Introducing loads to shared variables along a codepath where they would
+ not otherwise exist is allowed; introducing stores to shared variables
+ is not. See <a href="#outsideatomic">Optimization outside
+ atomic</a>.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>The one interesting restriction here is that it is not allowed to write
+ to bytes outside of the bytes relevant to a store. This is mostly
+ relevant to unaligned stores: it is not allowed in general to convert
+ an unaligned store into two aligned stores of the same width as the
+ unaligned store. Backends are also expected to generate an i8 store
+ as an i8 store, and not an instruction which writes to surrounding
+ bytes. (If you are writing a backend for an architecture which cannot
+ satisfy these restrictions and cares about concurrency, please send an
+ email to llvmdev.)</dd>
+</dl>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_unordered">Unordered</a>
+</h3>
+
+<div>
+
+<p>Unordered is the lowest level of atomicity. It essentially guarantees that
+ races produce somewhat sane results instead of having undefined behavior.
+ It also guarantees the operation to be lock-free, so it do not depend on
+ the data being part of a special atomic structure or depend on a separate
+ per-process global lock. Note that code generation will fail for
+ unsupported atomic operations; if you need such an operation, use explicit
+ locking.</p>
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This is intended to match the Java memory model for shared
+ variables.</dd>
+ <dt>Notes for frontends</dt>
+ <dd>This cannot be used for synchronization, but is useful for Java and
+ other "safe" languages which need to guarantee that the generated
+ code never exhibits undefined behavior. Note that this guarantee
+ is cheap on common platforms for loads of a native width, but can
+ be expensive or unavailable for wider loads, like a 64-bit store
+ on ARM. (A frontend for Java or other "safe" languages would normally
+ split a 64-bit store on ARM into two 32-bit unordered stores.)
+ <dt>Notes for optimizers</dt>
+ <dd>In terms of the optimizer, this prohibits any transformation that
+ transforms a single load into multiple loads, transforms a store
+ into multiple stores, narrows a store, or stores a value which
+ would not be stored otherwise. Some examples of unsafe optimizations
+ are narrowing an assignment into a bitfield, rematerializing
+ a load, and turning loads and stores into a memcpy call. Reordering
+ unordered operations is safe, though, and optimizers should take
+ advantage of that because unordered operations are common in
+ languages that need them.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>These operations are required to be atomic in the sense that if you
+ use unordered loads and unordered stores, a load cannot see a value
+ which was never stored. A normal load or store instruction is usually
+ sufficient, but note that an unordered load or store cannot
+ be split into multiple instructions (or an instruction which
+ does multiple memory operations, like <code>LDRD</code> on ARM).</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_monotonic">Monotonic</a>
+</h3>
+
+<div>
+
+<p>Monotonic is the weakest level of atomicity that can be used in
+ synchronization primitives, although it does not provide any general
+ synchronization. It essentially guarantees that if you take all the
+ operations affecting a specific address, a consistent ordering exists.
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This corresponds to the C++0x/C1x <code>memory_order_relaxed</code>;
+ see those standards for the exact definition.
+ <dt>Notes for frontends</dt>
+ <dd>If you are writing a frontend which uses this directly, use with caution.
+ The guarantees in terms of synchronization are very weak, so make
+ sure these are only used in a pattern which you know is correct.
+ Generally, these would either be used for atomic operations which
+ do not protect other memory (like an atomic counter), or along with
+ a <code>fence</code>.</dd>
+ <dt>Notes for optimizers</dt>
+ <dd>In terms of the optimizer, this can be treated as a read+write on the
+ relevant memory location (and alias analysis will take advantage of
+ that). In addition, it is legal to reorder non-atomic and Unordered
+ loads around Monotonic loads. CSE/DSE and a few other optimizations
+ are allowed, but Monotonic operations are unlikely to be used in ways
+ which would make those optimizations useful.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>Code generation is essentially the same as that for unordered for loads
+ and stores. No fences are required. <code>cmpxchg</code> and
+ <code>atomicrmw</code> are required to appear as a single operation.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_acquire">Acquire</a>
+</h3>
+
+<div>
+
+<p>Acquire provides a barrier of the sort necessary to acquire a lock to access
+ other memory with normal loads and stores.
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This corresponds to the C++0x/C1x <code>memory_order_acquire</code>. It
+ should also be used for C++0x/C1x <code>memory_order_consume</code>.
+ <dt>Notes for frontends</dt>
+ <dd>If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation.</dd>
+ <dt>Notes for optimizers</dt>
+ <dd>Optimizers not aware of atomics can treat this like a nothrow call.
+ It is also possible to move stores from before an Acquire load
+ or read-modify-write operation to after it, and move non-Acquire
+ loads from before an Acquire operation to after it.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>Architectures with weak memory ordering (essentially everything relevant
+ today except x86 and SPARC) require some sort of fence to maintain
+ the Acquire semantics. The precise fences required varies widely by
+ architecture, but for a simple implementation, most architectures provide
+ a barrier which is strong enough for everything (<code>dmb</code> on ARM,
+ <code>sync</code> on PowerPC, etc.). Putting such a fence after the
+ equivalent Monotonic operation is sufficient to maintain Acquire
+ semantics for a memory operation.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_acquire">Release</a>
+</h3>
+
+<div>
+
+<p>Release is similar to Acquire, but with a barrier of the sort necessary to
+ release a lock.
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This corresponds to the C++0x/C1x <code>memory_order_release</code>.</dd>
+ <dt>Notes for frontends</dt>
+ <dd>If you are writing a frontend which uses this directly, use with caution.
+ Release only provides a semantic guarantee when paired with a Acquire
+ operation.</dd>
+ <dt>Notes for optimizers</dt>
+ <dd>Optimizers not aware of atomics can treat this like a nothrow call.
+ It is also possible to move loads from after a Release store
+ or read-modify-write operation to before it, and move non-Release
+ stores from after an Release operation to before it.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>See the section on Acquire; a fence before the relevant operation is
+ usually sufficient for Release. Note that a store-store fence is not
+ sufficient to implement Release semantics; store-store fences are
+ generally not exposed to IR because they are extremely difficult to
+ use correctly.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_acqrel">AcquireRelease</a>
+</h3>
+
+<div>
+
+<p>AcquireRelease (<code>acq_rel</code> in IR) provides both an Acquire and a
+ Release barrier (for fences and operations which both read and write memory).
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.
+ <dt>Notes for frontends</dt>
+ <dd>If you are writing a frontend which uses this directly, use with caution.
+ Acquire only provides a semantic guarantee when paired with a Release
+ operation, and vice versa.</dd>
+ <dt>Notes for optimizers</dt>
+ <dd>In general, optimizers should treat this like a nothrow call; the
+ the possible optimizations are usually not interesting.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>This operation has Acquire and Release semantics; see the sections on
+ Acquire and Release.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="o_seqcst">SequentiallyConsistent</a>
+</h3>
+
+<div>
+
+<p>SequentiallyConsistent (<code>seq_cst</code> in IR) provides
+ Acquire semantics for loads and Release semantics for
+ stores. Additionally, it guarantees that a total ordering exists
+ between all SequentiallyConsistent operations.
+
+<dl>
+ <dt>Relevant standard</dt>
+ <dd>This corresponds to the C++0x/C1x <code>memory_order_seq_cst</code>,
+ Java volatile, and the gcc-compatible <code>__sync_*</code> builtins
+ which do not specify otherwise.
+ <dt>Notes for frontends</dt>
+ <dd>If a frontend is exposing atomic operations, these are much easier to
+ reason about for the programmer than other kinds of operations, and using
+ them is generally a practical performance tradeoff.</dd>
+ <dt>Notes for optimizers</dt>
+ <dd>Optimizers not aware of atomics can treat this like a nothrow call.
+ For SequentiallyConsistent loads and stores, the same reorderings are
+ allowed as for Acquire loads and Release stores, except that
+ SequentiallyConsistent operations may not be reordered.</dd>
+ <dt>Notes for code generation</dt>
+ <dd>SequentiallyConsistent loads minimally require the same barriers
+ as Acquire operations and SequentiallyConsistent stores require
+ Release barriers. Additionally, the code generator must enforce
+ ordering between SequentiallyConsistent stores followed by
+ SequentiallyConsistent loads. This is usually done by emitting
+ either a full fence before the loads or a full fence after the
+ stores; which is preferred varies by architecture.</dd>
+</dl>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="iropt">Atomics and IR optimization</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Predicates for optimizer writers to query:
+<ul>
+ <li>isSimple(): A load or store which is not volatile or atomic. This is
+ what, for example, memcpyopt would check for operations it might
+ transform.</li>
+ <li>isUnordered(): A load or store which is not volatile and at most
+ Unordered. This would be checked, for example, by LICM before hoisting
+ an operation.</li>
+ <li>mayReadFromMemory()/mayWriteToMemory(): Existing predicate, but note
+ that they return true for any operation which is volatile or at least
+ Monotonic.</li>
+ <li>Alias analysis: Note that AA will return ModRef for anything Acquire or
+ Release, and for the address accessed by any Monotonic operation.</li>
+</ul>
+
+<p>To support optimizing around atomic operations, make sure you are using
+ the right predicates; everything should work if that is done. If your
+ pass should optimize some atomic operations (Unordered operations in
+ particular), make sure it doesn't replace an atomic load or store with
+ a non-atomic operation.</p>
+
+<p>Some examples of how optimizations interact with various kinds of atomic
+ operations:
+<ul>
+ <li>memcpyopt: An atomic operation cannot be optimized into part of a
+ memcpy/memset, including unordered loads/stores. It can pull operations
+ across some atomic operations.
+ <li>LICM: Unordered loads/stores can be moved out of a loop. It just treats
+ monotonic operations like a read+write to a memory location, and anything
+ stricter than that like a nothrow call.
+ <li>DSE: Unordered stores can be DSE'ed like normal stores. Monotonic stores
+ can be DSE'ed in some cases, but it's tricky to reason about, and not
+ especially important.
+ <li>Folding a load: Any atomic load from a constant global can be
+ constant-folded, because it cannot be observed. Similar reasoning allows
+ scalarrepl with atomic loads and stores.
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="codegen">Atomics and Codegen</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Atomic operations are represented in the SelectionDAG with
+ <code>ATOMIC_*</code> opcodes. On architectures which use barrier
+ instructions for all atomic ordering (like ARM), appropriate fences are
+ split out as the DAG is built.</p>
+
+<p>The MachineMemOperand for all atomic operations is currently marked as
+ volatile; this is not correct in the IR sense of volatile, but CodeGen
+ handles anything marked volatile very conservatively. This should get
+ fixed at some point.</p>
+
+<p>Common architectures have some way of representing at least a pointer-sized
+ lock-free <code>cmpxchg</code>; such an operation can be used to implement
+ all the other atomic operations which can be represented in IR up to that
+ size. Backends are expected to implement all those operations, but not
+ operations which cannot be implemented in a lock-free manner. It is
+ expected that backends will give an error when given an operation which
+ cannot be implemented. (The LLVM code generator is not very helpful here
+ at the moment, but hopefully that will change.)</p>
+
+<p>The implementation of atomics on LL/SC architectures (like ARM) is currently
+ a bit of a mess; there is a lot of copy-pasted code across targets, and
+ the representation is relatively unsuited to optimization (it would be nice
+ to be able to optimize loops involving cmpxchg etc.).</p>
+
+<p>On x86, all atomic loads generate a <code>MOV</code>.
+ SequentiallyConsistent stores generate an <code>XCHG</code>, other stores
+ generate a <code>MOV</code>. SequentiallyConsistent fences generate an
+ <code>MFENCE</code>, other fences do not cause any code to be generated.
+ cmpxchg uses the <code>LOCK CMPXCHG</code> instruction.
+ <code>atomicrmw xchg</code> uses <code>XCHG</code>,
+ <code>atomicrmw add</code> and <code>atomicrmw sub</code> use
+ <code>XADD</code>, and all other <code>atomicrmw</code> operations generate
+ a loop with <code>LOCK CMPXCHG</code>. Depending on the users of the
+ result, some <code>atomicrmw</code> operations can be translated into
+ operations like <code>LOCK AND</code>, but that does not work in
+ general.</p>
+
+<p>On ARM, MIPS, and many other RISC architectures, Acquire, Release, and
+ SequentiallyConsistent semantics require barrier instructions
+ for every such operation. Loads and stores generate normal instructions.
+ <code>cmpxchg</code> and <code>atomicrmw</code> can be represented using
+ a loop with LL/SC-style instructions which take some sort of exclusive
+ lock on a cache line (<code>LDREX</code> and <code>STREX</code> on
+ ARM, etc.). At the moment, the IR does not provide any way to represent a
+ weak <code>cmpxchg</code> which would not require a loop.</p>
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-08-09 02:07:00 -0700 (Tue, 09 Aug 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/BitCodeFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/BitCodeFormat.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/BitCodeFormat.html (added)
+++ www-releases/trunk/3.0/docs/BitCodeFormat.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1470 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM Bitcode File Format</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+<h1> LLVM Bitcode File Format</h1>
+<ol>
+ <li><a href="#abstract">Abstract</a></li>
+ <li><a href="#overview">Overview</a></li>
+ <li><a href="#bitstream">Bitstream Format</a>
+ <ol>
+ <li><a href="#magic">Magic Numbers</a></li>
+ <li><a href="#primitives">Primitives</a></li>
+ <li><a href="#abbrevid">Abbreviation IDs</a></li>
+ <li><a href="#blocks">Blocks</a></li>
+ <li><a href="#datarecord">Data Records</a></li>
+ <li><a href="#abbreviations">Abbreviations</a></li>
+ <li><a href="#stdblocks">Standard Blocks</a></li>
+ </ol>
+ </li>
+ <li><a href="#wrapper">Bitcode Wrapper Format</a>
+ </li>
+ <li><a href="#llvmir">LLVM IR Encoding</a>
+ <ol>
+ <li><a href="#basics">Basics</a></li>
+ <li><a href="#MODULE_BLOCK">MODULE_BLOCK Contents</a></li>
+ <li><a href="#PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a></li>
+ <li><a href="#TYPE_BLOCK">TYPE_BLOCK Contents</a></li>
+ <li><a href="#CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a></li>
+ <li><a href="#FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a></li>
+ <li><a href="#TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a></li>
+ <li><a href="#VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a></li>
+ <li><a href="#METADATA_BLOCK">METADATA_BLOCK Contents</a></li>
+ <li><a href="#METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a></li>
+ </ol>
+ </li>
+</ol>
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>,
+ <a href="http://www.reverberate.org">Joshua Haberman</a>,
+ and <a href="mailto:housel at acm.org">Peter S. Housel</a>.
+</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="abstract">Abstract</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document describes the LLVM bitstream file format and the encoding of
+the LLVM IR into it.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="overview">Overview</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>
+What is commonly known as the LLVM bitcode file format (also, sometimes
+anachronistically known as bytecode) is actually two things: a <a
+href="#bitstream">bitstream container format</a>
+and an <a href="#llvmir">encoding of LLVM IR</a> into the container format.</p>
+
+<p>
+The bitstream format is an abstract encoding of structured data, very
+similar to XML in some ways. Like XML, bitstream files contain tags, and nested
+structures, and you can parse the file without having to understand the tags.
+Unlike XML, the bitstream format is a binary encoding, and unlike XML it
+provides a mechanism for the file to self-describe "abbreviations", which are
+effectively size optimizations for the content.</p>
+
+<p>LLVM IR files may be optionally embedded into a <a
+href="#wrapper">wrapper</a> structure that makes it easy to embed extra data
+along with LLVM IR files.</p>
+
+<p>This document first describes the LLVM bitstream format, describes the
+wrapper format, then describes the record structure used by LLVM IR files.
+</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="bitstream">Bitstream Format</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>
+The bitstream format is literally a stream of bits, with a very simple
+structure. This structure consists of the following concepts:
+</p>
+
+<ul>
+<li>A "<a href="#magic">magic number</a>" that identifies the contents of
+ the stream.</li>
+<li>Encoding <a href="#primitives">primitives</a> like variable bit-rate
+ integers.</li>
+<li><a href="#blocks">Blocks</a>, which define nested content.</li>
+<li><a href="#datarecord">Data Records</a>, which describe entities within the
+ file.</li>
+<li>Abbreviations, which specify compression optimizations for the file.</li>
+</ul>
+
+<p>Note that the <a
+href="CommandGuide/html/llvm-bcanalyzer.html">llvm-bcanalyzer</a> tool can be
+used to dump and inspect arbitrary bitstreams, which is very useful for
+understanding the encoding.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="magic">Magic Numbers</a>
+</h3>
+
+<div>
+
+<p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43).
+The second two bytes are an application-specific magic number. Generic
+bitcode tools can look at only the first two bytes to verify the file is
+bitcode, while application-specific programs will want to look at all four.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="primitives">Primitives</a>
+</h3>
+
+<div>
+
+<p>
+A bitstream literally consists of a stream of bits, which are read in order
+starting with the least significant bit of each byte. The stream is made up of a
+number of primitive values that encode a stream of unsigned integer values.
+These integers are encoded in two ways: either as <a href="#fixedwidth">Fixed
+Width Integers</a> or as <a href="#variablewidth">Variable Width
+Integers</a>.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="fixedwidth">Fixed Width Integers</a>
+</h4>
+
+<div>
+
+<p>Fixed-width integer values have their low bits emitted directly to the file.
+ For example, a 3-bit integer value encodes 1 as 001. Fixed width integers
+ are used when there are a well-known number of options for a field. For
+ example, boolean values are usually encoded with a 1-bit wide integer.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="variablewidth">Variable Width Integers</a>
+</h4>
+
+<div>
+
+<p>Variable-width integer (VBR) values encode values of arbitrary size,
+optimizing for the case where the values are small. Given a 4-bit VBR field,
+any 3-bit value (0 through 7) is encoded directly, with the high bit set to
+zero. Values larger than N-1 bits emit their bits in a series of N-1 bit
+chunks, where all but the last set the high bit.</p>
+
+<p>For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a
+vbr4 value. The first set of four bits indicates the value 3 (011) with a
+continuation piece (indicated by a high bit of 1). The next word indicates a
+value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
+27.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="char6">6-bit characters</a></h4>
+
+<div>
+
+<p>6-bit characters encode common characters into a fixed 6-bit field. They
+represent the following characters with the following 6-bit values:</p>
+
+<div class="doc_code">
+<pre>
+'a' .. 'z' — 0 .. 25
+'A' .. 'Z' — 26 .. 51
+'0' .. '9' — 52 .. 61
+ '.' — 62
+ '_' — 63
+</pre>
+</div>
+
+<p>This encoding is only suitable for encoding characters and strings that
+consist only of the above characters. It is completely incapable of encoding
+characters not in the set.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="wordalign">Word Alignment</a></h4>
+
+<div>
+
+<p>Occasionally, it is useful to emit zero bits until the bitstream is a
+multiple of 32 bits. This ensures that the bit position in the stream can be
+represented as a multiple of 32-bit words.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="abbrevid">Abbreviation IDs</a>
+</h3>
+
+<div>
+
+<p>
+A bitstream is a sequential series of <a href="#blocks">Blocks</a> and
+<a href="#datarecord">Data Records</a>. Both of these start with an
+abbreviation ID encoded as a fixed-bitwidth field. The width is specified by
+the current block, as described below. The value of the abbreviation ID
+specifies either a builtin ID (which have special meanings, defined below) or
+one of the abbreviation IDs defined for the current block by the stream itself.
+</p>
+
+<p>
+The set of builtin abbrev IDs is:
+</p>
+
+<ul>
+<li><tt>0 - <a href="#END_BLOCK">END_BLOCK</a></tt> — This abbrev ID marks
+ the end of the current block.</li>
+<li><tt>1 - <a href="#ENTER_SUBBLOCK">ENTER_SUBBLOCK</a></tt> — This
+ abbrev ID marks the beginning of a new block.</li>
+<li><tt>2 - <a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt> — This defines
+ a new abbreviation.</li>
+<li><tt>3 - <a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> — This ID
+ specifies the definition of an unabbreviated record.</li>
+</ul>
+
+<p>Abbreviation IDs 4 and above are defined by the stream itself, and specify
+an <a href="#abbrev_records">abbreviated record encoding</a>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="blocks">Blocks</a>
+</h3>
+
+<div>
+
+<p>
+Blocks in a bitstream denote nested regions of the stream, and are identified by
+a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
+function bodies). Block IDs 0-7 are reserved for <a href="#stdblocks">standard blocks</a>
+whose meaning is defined by Bitcode; block IDs 8 and greater are
+application specific. Nested blocks capture the hierarchical structure of the data
+encoded in it, and various properties are associated with blocks as the file is
+parsed. Block definitions allow the reader to efficiently skip blocks
+in constant time if the reader wants a summary of blocks, or if it wants to
+efficiently skip data it does not understand. The LLVM IR reader uses this
+mechanism to skip function bodies, lazily reading them on demand.
+</p>
+
+<p>
+When reading and encoding the stream, several properties are maintained for the
+block. In particular, each block maintains:
+</p>
+
+<ol>
+<li>A current abbrev id width. This value starts at 2 at the beginning of
+ the stream, and is set every time a
+ block record is entered. The block entry specifies the abbrev id width for
+ the body of the block.</li>
+
+<li>A set of abbreviations. Abbreviations may be defined within a block, in
+ which case they are only defined in that block (neither subblocks nor
+ enclosing blocks see the abbreviation). Abbreviations can also be defined
+ inside a <tt><a href="#BLOCKINFO">BLOCKINFO</a></tt> block, in which case
+ they are defined in all blocks that match the ID that the BLOCKINFO block is
+ describing.
+</li>
+</ol>
+
+<p>
+As sub blocks are entered, these properties are saved and the new sub-block has
+its own set of abbreviations, and its own abbrev id width. When a sub-block is
+popped, the saved values are restored.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK Encoding</a></h4>
+
+<div>
+
+<p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>,
+ <align32bits>, blocklen<sub>32</sub>]</tt></p>
+
+<p>
+The <tt>ENTER_SUBBLOCK</tt> abbreviation ID specifies the start of a new block
+record. The <tt>blockid</tt> value is encoded as an 8-bit VBR identifier, and
+indicates the type of block being entered, which can be
+a <a href="#stdblocks">standard block</a> or an application-specific block.
+The <tt>newabbrevlen</tt> value is a 4-bit VBR, which specifies the abbrev id
+width for the sub-block. The <tt>blocklen</tt> value is a 32-bit aligned value
+that specifies the size of the subblock in 32-bit words. This value allows the
+reader to skip over the entire block in one jump.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="END_BLOCK">END_BLOCK Encoding</a></h4>
+
+<div>
+
+<p><tt>[END_BLOCK, <align32bits>]</tt></p>
+
+<p>
+The <tt>END_BLOCK</tt> abbreviation ID specifies the end of the current block
+record. Its end is aligned to 32-bits to ensure that the size of the block is
+an even multiple of 32-bits.
+</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="datarecord">Data Records</a>
+</h3>
+
+<div>
+<p>
+Data records consist of a record code and a number of (up to) 64-bit
+integer values. The interpretation of the code and values is
+application specific and may vary between different block types.
+Records can be encoded either using an unabbrev record, or with an
+abbreviation. In the LLVM IR format, for example, there is a record
+which encodes the target triple of a module. The code is
+<tt>MODULE_CODE_TRIPLE</tt>, and the values of the record are the
+ASCII codes for the characters in the string.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="UNABBREV_RECORD">UNABBREV_RECORD Encoding</a></h4>
+
+<div>
+
+<p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>,
+ op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p>
+
+<p>
+An <tt>UNABBREV_RECORD</tt> provides a default fallback encoding, which is both
+completely general and extremely inefficient. It can describe an arbitrary
+record by emitting the code and operands as VBRs.
+</p>
+
+<p>
+For example, emitting an LLVM IR target triple as an unabbreviated record
+requires emitting the <tt>UNABBREV_RECORD</tt> abbrevid, a vbr6 for the
+<tt>MODULE_CODE_TRIPLE</tt> code, a vbr6 for the length of the string, which is
+equal to the number of operands, and a vbr6 for each character. Because there
+are no letters with values less than 32, each letter would need to be emitted as
+at least a two-part VBR, which means that each letter would require at least 12
+bits. This is not an efficient encoding, but it is fully general.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="abbrev_records">Abbreviated Record Encoding</a></h4>
+
+<div>
+
+<p><tt>[<abbrevid>, fields...]</tt></p>
+
+<p>
+An abbreviated record is a abbreviation id followed by a set of fields that are
+encoded according to the <a href="#abbreviations">abbreviation definition</a>.
+This allows records to be encoded significantly more densely than records
+encoded with the <tt><a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> type,
+and allows the abbreviation types to be specified in the stream itself, which
+allows the files to be completely self describing. The actual encoding of
+abbreviations is defined below.
+</p>
+
+<p>The record code, which is the first field of an abbreviated record,
+may be encoded in the abbreviation definition (as a literal
+operand) or supplied in the abbreviated record (as a Fixed or VBR
+operand value).</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="abbreviations">Abbreviations</a>
+</h3>
+
+<div>
+<p>
+Abbreviations are an important form of compression for bitstreams. The idea is
+to specify a dense encoding for a class of records once, then use that encoding
+to emit many records. It takes space to emit the encoding into the file, but
+the space is recouped (hopefully plus some) when the records that use it are
+emitted.
+</p>
+
+<p>
+Abbreviations can be determined dynamically per client, per file. Because the
+abbreviations are stored in the bitstream itself, different streams of the same
+format can contain different sets of abbreviations according to the needs
+of the specific stream.
+As a concrete example, LLVM IR files usually emit an abbreviation
+for binary operators. If a specific LLVM module contained no or few binary
+operators, the abbreviation does not need to be emitted.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="DEFINE_ABBREV">DEFINE_ABBREV Encoding</a></h4>
+
+<div>
+
+<p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1,
+ ...]</tt></p>
+
+<p>
+A <tt>DEFINE_ABBREV</tt> record adds an abbreviation to the list of currently
+defined abbreviations in the scope of this block. This definition only exists
+inside this immediate block — it is not visible in subblocks or enclosing
+blocks. Abbreviations are implicitly assigned IDs sequentially starting from 4
+(the first application-defined abbreviation ID). Any abbreviations defined in a
+<tt>BLOCKINFO</tt> record for the particular block type
+receive IDs first, in order, followed by any
+abbreviations defined within the block itself. Abbreviated data records
+reference this ID to indicate what abbreviation they are invoking.
+</p>
+
+<p>
+An abbreviation definition consists of the <tt>DEFINE_ABBREV</tt> abbrevid
+followed by a VBR that specifies the number of abbrev operands, then the abbrev
+operands themselves. Abbreviation operands come in three forms. They all start
+with a single bit that indicates whether the abbrev operand is a literal operand
+(when the bit is 1) or an encoding operand (when the bit is 0).
+</p>
+
+<ol>
+<li>Literal operands — <tt>[1<sub>1</sub>, litvalue<sub>vbr8</sub>]</tt>
+— Literal operands specify that the value in the result is always a single
+specific value. This specific value is emitted as a vbr8 after the bit
+indicating that it is a literal operand.</li>
+<li>Encoding info without data — <tt>[0<sub>1</sub>,
+ encoding<sub>3</sub>]</tt> — Operand encodings that do not have extra
+ data are just emitted as their code.
+</li>
+<li>Encoding info with data — <tt>[0<sub>1</sub>, encoding<sub>3</sub>,
+value<sub>vbr5</sub>]</tt> — Operand encodings that do have extra data are
+emitted as their code, followed by the extra data.
+</li>
+</ol>
+
+<p>The possible operand encodings are:</p>
+
+<ul>
+<li>Fixed (code 1): The field should be emitted as
+ a <a href="#fixedwidth">fixed-width value</a>, whose width is specified by
+ the operand's extra data.</li>
+<li>VBR (code 2): The field should be emitted as
+ a <a href="#variablewidth">variable-width value</a>, whose width is
+ specified by the operand's extra data.</li>
+<li>Array (code 3): This field is an array of values. The array operand
+ has no extra data, but expects another operand to follow it, indicating
+ the element type of the array. When reading an array in an abbreviated
+ record, the first integer is a vbr6 that indicates the array length,
+ followed by the encoded elements of the array. An array may only occur as
+ the last operand of an abbreviation (except for the one final operand that
+ gives the array's type).</li>
+<li>Char6 (code 4): This field should be emitted as
+ a <a href="#char6">char6-encoded value</a>. This operand type takes no
+ extra data. Char6 encoding is normally used as an array element type.
+ </li>
+<li>Blob (code 5): This field is emitted as a vbr6, followed by padding to a
+ 32-bit boundary (for alignment) and an array of 8-bit objects. The array of
+ bytes is further followed by tail padding to ensure that its total length is
+ a multiple of 4 bytes. This makes it very efficient for the reader to
+ decode the data without having to make a copy of it: it can use a pointer to
+ the data in the mapped in file and poke directly at it. A blob may only
+ occur as the last operand of an abbreviation.</li>
+</ul>
+
+<p>
+For example, target triples in LLVM modules are encoded as a record of the
+form <tt>[TRIPLE, 'a', 'b', 'c', 'd']</tt>. Consider if the bitstream emitted
+the following abbrev entry:
+</p>
+
+<div class="doc_code">
+<pre>
+[0, Fixed, 4]
+[0, Array]
+[0, Char6]
+</pre>
+</div>
+
+<p>
+When emitting a record with this abbreviation, the above entry would be emitted
+as:
+</p>
+
+<div class="doc_code">
+<p>
+<tt>[4<sub>abbrevwidth</sub>, 2<sub>4</sub>, 4<sub>vbr6</sub>, 0<sub>6</sub>,
+1<sub>6</sub>, 2<sub>6</sub>, 3<sub>6</sub>]</tt>
+</p>
+</div>
+
+<p>These values are:</p>
+
+<ol>
+<li>The first value, 4, is the abbreviation ID for this abbreviation.</li>
+<li>The second value, 2, is the record code for <tt>TRIPLE</tt> records within LLVM IR file <tt>MODULE_BLOCK</tt> blocks.</li>
+<li>The third value, 4, is the length of the array.</li>
+<li>The rest of the values are the char6 encoded values
+ for <tt>"abcd"</tt>.</li>
+</ol>
+
+<p>
+With this abbreviation, the triple is emitted with only 37 bits (assuming a
+abbrev id width of 3). Without the abbreviation, significantly more space would
+be required to emit the target triple. Also, because the <tt>TRIPLE</tt> value
+is not emitted as a literal in the abbreviation, the abbreviation can also be
+used for any other string value.
+</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="stdblocks">Standard Blocks</a>
+</h3>
+
+<div>
+
+<p>
+In addition to the basic block structure and record encodings, the bitstream
+also defines specific built-in block types. These block types specify how the
+stream is to be decoded or other metadata. In the future, new standard blocks
+may be added. Block IDs 0-7 are reserved for standard blocks.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="BLOCKINFO">#0 - BLOCKINFO Block</a></h4>
+
+<div>
+
+<p>
+The <tt>BLOCKINFO</tt> block allows the description of metadata for other
+blocks. The currently specified records are:
+</p>
+
+<div class="doc_code">
+<pre>
+[SETBID (#1), blockid]
+[DEFINE_ABBREV, ...]
+[BLOCKNAME, ...name...]
+[SETRECORDNAME, RecordID, ...name...]
+</pre>
+</div>
+
+<p>
+The <tt>SETBID</tt> record (code 1) indicates which block ID is being
+described. <tt>SETBID</tt> records can occur multiple times throughout the
+block to change which block ID is being described. There must be
+a <tt>SETBID</tt> record prior to any other records.
+</p>
+
+<p>
+Standard <tt>DEFINE_ABBREV</tt> records can occur inside <tt>BLOCKINFO</tt>
+blocks, but unlike their occurrence in normal blocks, the abbreviation is
+defined for blocks matching the block ID we are describing, <i>not</i> the
+<tt>BLOCKINFO</tt> block itself. The abbreviations defined
+in <tt>BLOCKINFO</tt> blocks receive abbreviation IDs as described
+in <tt><a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt>.
+</p>
+
+<p>The <tt>BLOCKNAME</tt> record (code 2) can optionally occur in this block. The elements of
+the record are the bytes of the string name of the block. llvm-bcanalyzer can use
+this to dump out bitcode files symbolically.</p>
+
+<p>The <tt>SETRECORDNAME</tt> record (code 3) can also optionally occur in this block. The
+first operand value is a record ID number, and the rest of the elements of the record are
+the bytes for the string name of the record. llvm-bcanalyzer can use
+this to dump out bitcode files symbolically.</p>
+
+<p>
+Note that although the data in <tt>BLOCKINFO</tt> blocks is described as
+"metadata," the abbreviations they contain are essential for parsing records
+from the corresponding blocks. It is not safe to skip them.
+</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="wrapper">Bitcode Wrapper Format</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>
+Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
+structure. This structure contains a simple header that indicates the offset
+and size of the embedded BC file. This allows additional information to be
+stored alongside the BC file. The structure of this file header is:
+</p>
+
+<div class="doc_code">
+<p>
+<tt>[Magic<sub>32</sub>, Version<sub>32</sub>, Offset<sub>32</sub>,
+Size<sub>32</sub>, CPUType<sub>32</sub>]</tt>
+</p>
+</div>
+
+<p>
+Each of the fields are 32-bit fields stored in little endian form (as with
+the rest of the bitcode file fields). The Magic number is always
+<tt>0x0B17C0DE</tt> and the version is currently always <tt>0</tt>. The Offset
+field is the offset in bytes to the start of the bitcode stream in the file, and
+the Size field is the size in bytes of the stream. CPUType is a target-specific
+value that can be used to encode the CPU of the target.
+</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="llvmir">LLVM IR Encoding</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>
+LLVM IR is encoded into a bitstream by defining blocks and records. It uses
+blocks for things like constant pools, functions, symbol tables, etc. It uses
+records for things like instructions, global variable descriptors, type
+descriptions, etc. This document does not describe the set of abbreviations
+that the writer uses, as these are fully self-described in the file, and the
+reader is not allowed to build in any knowledge of this.
+</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="basics">Basics</a>
+</h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="ir_magic">LLVM IR Magic Number</a></h4>
+
+<div>
+
+<p>
+The magic number for LLVM IR files is:
+</p>
+
+<div class="doc_code">
+<p>
+<tt>[0x0<sub>4</sub>, 0xC<sub>4</sub>, 0xE<sub>4</sub>, 0xD<sub>4</sub>]</tt>
+</p>
+</div>
+
+<p>
+When combined with the bitcode magic number and viewed as bytes, this is
+<tt>"BC 0xC0DE"</tt>.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="ir_signed_vbr">Signed VBRs</a></h4>
+
+<div>
+
+<p>
+<a href="#variablewidth">Variable Width Integer</a> encoding is an efficient way to
+encode arbitrary sized unsigned values, but is an extremely inefficient for
+encoding signed values, as signed values are otherwise treated as maximally large
+unsigned values.
+</p>
+
+<p>
+As such, signed VBR values of a specific width are emitted as follows:
+</p>
+
+<ul>
+<li>Positive values are emitted as VBRs of the specified width, but with their
+ value shifted left by one.</li>
+<li>Negative values are emitted as VBRs of the specified width, but the negated
+ value is shifted left by one, and the low bit is set.</li>
+</ul>
+
+<p>
+With this encoding, small positive and small negative values can both
+be emitted efficiently. Signed VBR encoding is used in
+<tt>CST_CODE_INTEGER</tt> and <tt>CST_CODE_WIDE_INTEGER</tt> records
+within <tt>CONSTANTS_BLOCK</tt> blocks.
+</p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="ir_blocks">LLVM IR Blocks</a></h4>
+
+<div>
+
+<p>
+LLVM IR is defined with the following blocks:
+</p>
+
+<ul>
+<li>8 — <a href="#MODULE_BLOCK"><tt>MODULE_BLOCK</tt></a> — This is the top-level block that
+ contains the entire module, and describes a variety of per-module
+ information.</li>
+<li>9 — <a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a> — This enumerates the parameter
+ attributes.</li>
+<li>10 — <a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a> — This describes all of the types in
+ the module.</li>
+<li>11 — <a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a> — This describes constants for a
+ module or function.</li>
+<li>12 — <a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a> — This describes a function
+ body.</li>
+<li>13 — <a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a> — This describes the type symbol
+ table.</li>
+<li>14 — <a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a> — This describes a value symbol
+ table.</li>
+<li>15 — <a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a> — This describes metadata items.</li>
+<li>16 — <a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a> — This contains records associating metadata with function instruction values.</li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="MODULE_BLOCK">MODULE_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>MODULE_BLOCK</tt> block (id 8) is the top-level block for LLVM
+bitcode files, and each bitcode file must contain exactly one. In
+addition to records (described below) containing information
+about the module, a <tt>MODULE_BLOCK</tt> block may contain the
+following sub-blocks:
+</p>
+
+<ul>
+<li><a href="#BLOCKINFO"><tt>BLOCKINFO</tt></a></li>
+<li><a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a></li>
+<li><a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a></li>
+<li><a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a></li>
+<li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
+<li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
+<li><a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a></li>
+<li><a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a></li>
+</ul>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_VERSION">MODULE_CODE_VERSION Record</a></h4>
+
+<div>
+
+<p><tt>[VERSION, version#]</tt></p>
+
+<p>The <tt>VERSION</tt> record (code 1) contains a single value
+indicating the format version. Only version 0 is supported at this
+time.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_TRIPLE">MODULE_CODE_TRIPLE Record</a></h4>
+
+<div>
+<p><tt>[TRIPLE, ...string...]</tt></p>
+
+<p>The <tt>TRIPLE</tt> record (code 2) contains a variable number of
+values representing the bytes of the <tt>target triple</tt>
+specification string.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_DATALAYOUT">MODULE_CODE_DATALAYOUT Record</a></h4>
+
+<div>
+<p><tt>[DATALAYOUT, ...string...]</tt></p>
+
+<p>The <tt>DATALAYOUT</tt> record (code 3) contains a variable number of
+values representing the bytes of the <tt>target datalayout</tt>
+specification string.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_ASM">MODULE_CODE_ASM Record</a></h4>
+
+<div>
+<p><tt>[ASM, ...string...]</tt></p>
+
+<p>The <tt>ASM</tt> record (code 4) contains a variable number of
+values representing the bytes of <tt>module asm</tt> strings, with
+individual assembly blocks separated by newline (ASCII 10) characters.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME Record</a></h4>
+
+<div>
+<p><tt>[SECTIONNAME, ...string...]</tt></p>
+
+<p>The <tt>SECTIONNAME</tt> record (code 5) contains a variable number
+of values representing the bytes of a single section name
+string. There should be one <tt>SECTIONNAME</tt> record for each
+section name referenced (e.g., in global variable or function
+<tt>section</tt> attributes) within the module. These records can be
+referenced by the 1-based index in the <i>section</i> fields of
+<tt>GLOBALVAR</tt> or <tt>FUNCTION</tt> records.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_DEPLIB">MODULE_CODE_DEPLIB Record</a></h4>
+
+<div>
+<p><tt>[DEPLIB, ...string...]</tt></p>
+
+<p>The <tt>DEPLIB</tt> record (code 6) contains a variable number of
+values representing the bytes of a single dependent library name
+string, one of the libraries mentioned in a <tt>deplibs</tt>
+declaration. There should be one <tt>DEPLIB</tt> record for each
+library name referenced.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_GLOBALVAR">MODULE_CODE_GLOBALVAR Record</a></h4>
+
+<div>
+<p><tt>[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]</tt></p>
+
+<p>The <tt>GLOBALVAR</tt> record (code 7) marks the declaration or
+definition of a global variable. The operand fields are:</p>
+
+<ul>
+<li><i>pointer type</i>: The type index of the pointer type used to point to
+this global variable</li>
+
+<li><i>isconst</i>: Non-zero if the variable is treated as constant within
+the module, or zero if it is not</li>
+
+<li><i>initid</i>: If non-zero, the value index of the initializer for this
+variable, plus 1.</li>
+
+<li><a name="linkage"><i>linkage</i></a>: An encoding of the linkage
+type for this variable:
+ <ul>
+ <li><tt>external</tt>: code 0</li>
+ <li><tt>weak</tt>: code 1</li>
+ <li><tt>appending</tt>: code 2</li>
+ <li><tt>internal</tt>: code 3</li>
+ <li><tt>linkonce</tt>: code 4</li>
+ <li><tt>dllimport</tt>: code 5</li>
+ <li><tt>dllexport</tt>: code 6</li>
+ <li><tt>extern_weak</tt>: code 7</li>
+ <li><tt>common</tt>: code 8</li>
+ <li><tt>private</tt>: code 9</li>
+ <li><tt>weak_odr</tt>: code 10</li>
+ <li><tt>linkonce_odr</tt>: code 11</li>
+ <li><tt>available_externally</tt>: code 12</li>
+ <li><tt>linker_private</tt>: code 13</li>
+ </ul>
+</li>
+
+<li><i>alignment</i>: The logarithm base 2 of the variable's requested
+alignment, plus 1</li>
+
+<li><i>section</i>: If non-zero, the 1-based section index in the
+table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
+entries.</li>
+
+<li><a name="visibility"><i>visibility</i></a>: If present, an
+encoding of the visibility of this variable:
+ <ul>
+ <li><tt>default</tt>: code 0</li>
+ <li><tt>hidden</tt>: code 1</li>
+ <li><tt>protected</tt>: code 2</li>
+ </ul>
+</li>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_FUNCTION">MODULE_CODE_FUNCTION Record</a></h4>
+
+<div>
+
+<p><tt>[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]</tt></p>
+
+<p>The <tt>FUNCTION</tt> record (code 8) marks the declaration or
+definition of a function. The operand fields are:</p>
+
+<ul>
+<li><i>type</i>: The type index of the function type describing this function</li>
+
+<li><i>callingconv</i>: The calling convention number:
+ <ul>
+ <li><tt>ccc</tt>: code 0</li>
+ <li><tt>fastcc</tt>: code 8</li>
+ <li><tt>coldcc</tt>: code 9</li>
+ <li><tt>x86_stdcallcc</tt>: code 64</li>
+ <li><tt>x86_fastcallcc</tt>: code 65</li>
+ <li><tt>arm_apcscc</tt>: code 66</li>
+ <li><tt>arm_aapcscc</tt>: code 67</li>
+ <li><tt>arm_aapcs_vfpcc</tt>: code 68</li>
+ </ul>
+</li>
+
+<li><i>isproto</i>: Non-zero if this entry represents a declaration
+rather than a definition</li>
+
+<li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
+for this function</li>
+
+<li><i>paramattr</i>: If nonzero, the 1-based parameter attribute index
+into the table of <a href="#PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY</a>
+entries.</li>
+
+<li><i>alignment</i>: The logarithm base 2 of the function's requested
+alignment, plus 1</li>
+
+<li><i>section</i>: If non-zero, the 1-based section index in the
+table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
+entries.</li>
+
+<li><i>visibility</i>: An encoding of the <a href="#visibility">visibility</a>
+ of this function</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>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_ALIAS">MODULE_CODE_ALIAS Record</a></h4>
+
+<div>
+
+<p><tt>[ALIAS, alias type, aliasee val#, linkage, visibility]</tt></p>
+
+<p>The <tt>ALIAS</tt> record (code 9) marks the definition of an
+alias. The operand fields are</p>
+
+<ul>
+<li><i>alias type</i>: The type index of the alias</li>
+
+<li><i>aliasee val#</i>: The value index of the aliased value</li>
+
+<li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
+for this alias</li>
+
+<li><i>visibility</i>: If present, an encoding of the
+<a href="#visibility">visibility</a> of the alias</li>
+
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_PURGEVALS">MODULE_CODE_PURGEVALS Record</a></h4>
+
+<div>
+<p><tt>[PURGEVALS, numvals]</tt></p>
+
+<p>The <tt>PURGEVALS</tt> record (code 10) resets the module-level
+value list to the size given by the single operand value. Module-level
+value list items are added by <tt>GLOBALVAR</tt>, <tt>FUNCTION</tt>,
+and <tt>ALIAS</tt> records. After a <tt>PURGEVALS</tt> record is seen,
+new value indices will start from the given <i>numvals</i> value.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="MODULE_CODE_GCNAME">MODULE_CODE_GCNAME Record</a></h4>
+
+<div>
+<p><tt>[GCNAME, ...string...]</tt></p>
+
+<p>The <tt>GCNAME</tt> record (code 11) contains a variable number of
+values representing the bytes of a single garbage collector name
+string. There should be one <tt>GCNAME</tt> record for each garbage
+collector name referenced in function <tt>gc</tt> attributes within
+the module. These records can be referenced by 1-based index in the <i>gc</i>
+fields of <tt>FUNCTION</tt> records.</p>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>PARAMATTR_BLOCK</tt> block (id 9) contains a table of
+entries describing the attributes of function parameters. These
+entries are referenced by 1-based index in the <i>paramattr</i> field
+of module block <a name="MODULE_CODE_FUNCTION"><tt>FUNCTION</tt></a>
+records, or within the <i>attr</i> field of function block <a
+href="#FUNC_CODE_INST_INVOKE"><tt>INST_INVOKE</tt></a> and <a
+href="#FUNC_CODE_INST_CALL"><tt>INST_CALL</tt></a> records.</p>
+
+<p>Entries within <tt>PARAMATTR_BLOCK</tt> are constructed to ensure
+that each is unique (i.e., no two indicies represent equivalent
+attribute lists). </p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY Record</a></h4>
+
+<div>
+
+<p><tt>[ENTRY, paramidx0, attr0, paramidx1, attr1...]</tt></p>
+
+<p>The <tt>ENTRY</tt> record (code 1) contains an even number of
+values describing a unique set of function parameter attributes. Each
+<i>paramidx</i> value indicates which set of attributes is
+represented, with 0 representing the return value attributes,
+0xFFFFFFFF representing function attributes, and other values
+representing 1-based function parameters. Each <i>attr</i> value is a
+bitmap with the following interpretation:
+</p>
+
+<ul>
+<li>bit 0: <tt>zeroext</tt></li>
+<li>bit 1: <tt>signext</tt></li>
+<li>bit 2: <tt>noreturn</tt></li>
+<li>bit 3: <tt>inreg</tt></li>
+<li>bit 4: <tt>sret</tt></li>
+<li>bit 5: <tt>nounwind</tt></li>
+<li>bit 6: <tt>noalias</tt></li>
+<li>bit 7: <tt>byval</tt></li>
+<li>bit 8: <tt>nest</tt></li>
+<li>bit 9: <tt>readnone</tt></li>
+<li>bit 10: <tt>readonly</tt></li>
+<li>bit 11: <tt>noinline</tt></li>
+<li>bit 12: <tt>alwaysinline</tt></li>
+<li>bit 13: <tt>optsize</tt></li>
+<li>bit 14: <tt>ssp</tt></li>
+<li>bit 15: <tt>sspreq</tt></li>
+<li>bits 16–31: <tt>align <var>n</var></tt></li>
+<li>bit 32: <tt>nocapture</tt></li>
+<li>bit 33: <tt>noredzone</tt></li>
+<li>bit 34: <tt>noimplicitfloat</tt></li>
+<li>bit 35: <tt>naked</tt></li>
+<li>bit 36: <tt>inlinehint</tt></li>
+<li>bits 37–39: <tt>alignstack <var>n</var></tt>, represented as
+the logarithm base 2 of the requested alignment, plus 1</li>
+</ul>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="TYPE_BLOCK">TYPE_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>TYPE_BLOCK</tt> block (id 10) contains records which
+constitute a table of type operator entries used to represent types
+referenced within an LLVM module. Each record (with the exception of
+<a href="#TYPE_CODE_NUMENTRY"><tt>NUMENTRY</tt></a>) generates a
+single type table entry, which may be referenced by 0-based index from
+instructions, constants, metadata, type symbol table entries, or other
+type operator records.
+</p>
+
+<p>Entries within <tt>TYPE_BLOCK</tt> are constructed to ensure that
+each entry is unique (i.e., no two indicies represent structurally
+equivalent types). </p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_NUMENTRY">TYPE_CODE_NUMENTRY Record</a></h4>
+
+<div>
+
+<p><tt>[NUMENTRY, numentries]</tt></p>
+
+<p>The <tt>NUMENTRY</tt> record (code 1) contains a single value which
+indicates the total number of type code entries in the type table of
+the module. If present, <tt>NUMENTRY</tt> should be the first record
+in the block.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_VOID">TYPE_CODE_VOID Record</a></h4>
+
+<div>
+
+<p><tt>[VOID]</tt></p>
+
+<p>The <tt>VOID</tt> record (code 2) adds a <tt>void</tt> type to the
+type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_FLOAT">TYPE_CODE_FLOAT Record</a></h4>
+
+<div>
+
+<p><tt>[FLOAT]</tt></p>
+
+<p>The <tt>FLOAT</tt> record (code 3) adds a <tt>float</tt> (32-bit
+floating point) type to the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_DOUBLE">TYPE_CODE_DOUBLE Record</a></h4>
+
+<div>
+
+<p><tt>[DOUBLE]</tt></p>
+
+<p>The <tt>DOUBLE</tt> record (code 4) adds a <tt>double</tt> (64-bit
+floating point) type to the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_LABEL">TYPE_CODE_LABEL Record</a></h4>
+
+<div>
+
+<p><tt>[LABEL]</tt></p>
+
+<p>The <tt>LABEL</tt> record (code 5) adds a <tt>label</tt> type to
+the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_OPAQUE">TYPE_CODE_OPAQUE Record</a></h4>
+
+<div>
+
+<p><tt>[OPAQUE]</tt></p>
+
+<p>The <tt>OPAQUE</tt> record (code 6) adds an <tt>opaque</tt> type to
+the type table. Note that distinct <tt>opaque</tt> types are not
+unified.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_INTEGER">TYPE_CODE_INTEGER Record</a></h4>
+
+<div>
+
+<p><tt>[INTEGER, width]</tt></p>
+
+<p>The <tt>INTEGER</tt> record (code 7) adds an integer type to the
+type table. The single <i>width</i> field indicates the width of the
+integer type.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_POINTER">TYPE_CODE_POINTER Record</a></h4>
+
+<div>
+
+<p><tt>[POINTER, pointee type, address space]</tt></p>
+
+<p>The <tt>POINTER</tt> record (code 8) adds a pointer type to the
+type table. The operand fields are</p>
+
+<ul>
+<li><i>pointee type</i>: The type index of the pointed-to type</li>
+
+<li><i>address space</i>: If supplied, the target-specific numbered
+address space where the pointed-to object resides. Otherwise, the
+default address space is zero.
+</li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_FUNCTION">TYPE_CODE_FUNCTION Record</a></h4>
+
+<div>
+
+<p><tt>[FUNCTION, vararg, ignored, retty, ...paramty... ]</tt></p>
+
+<p>The <tt>FUNCTION</tt> record (code 9) adds a function type to the
+type table. The operand fields are</p>
+
+<ul>
+<li><i>vararg</i>: Non-zero if the type represents a varargs function</li>
+
+<li><i>ignored</i>: This value field is present for backward
+compatibility only, and is ignored</li>
+
+<li><i>retty</i>: The type index of the function's return type</li>
+
+<li><i>paramty</i>: Zero or more type indices representing the
+parameter types of the function</li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_STRUCT">TYPE_CODE_STRUCT Record</a></h4>
+
+<div>
+
+<p><tt>[STRUCT, ispacked, ...eltty...]</tt></p>
+
+<p>The <tt>STRUCT </tt> record (code 10) adds a struct type to the
+type table. The operand fields are</p>
+
+<ul>
+<li><i>ispacked</i>: Non-zero if the type represents a packed structure</li>
+
+<li><i>eltty</i>: Zero or more type indices representing the element
+types of the structure</li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_ARRAY">TYPE_CODE_ARRAY Record</a></h4>
+
+<div>
+
+<p><tt>[ARRAY, numelts, eltty]</tt></p>
+
+<p>The <tt>ARRAY</tt> record (code 11) adds an array type to the type
+table. The operand fields are</p>
+
+<ul>
+<li><i>numelts</i>: The number of elements in arrays of this type</li>
+
+<li><i>eltty</i>: The type index of the array element type</li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_VECTOR">TYPE_CODE_VECTOR Record</a></h4>
+
+<div>
+
+<p><tt>[VECTOR, numelts, eltty]</tt></p>
+
+<p>The <tt>VECTOR</tt> record (code 12) adds a vector type to the type
+table. The operand fields are</p>
+
+<ul>
+<li><i>numelts</i>: The number of elements in vectors of this type</li>
+
+<li><i>eltty</i>: The type index of the vector element type</li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_X86_FP80">TYPE_CODE_X86_FP80 Record</a></h4>
+
+<div>
+
+<p><tt>[X86_FP80]</tt></p>
+
+<p>The <tt>X86_FP80</tt> record (code 13) adds an <tt>x86_fp80</tt> (80-bit
+floating point) type to the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_FP128">TYPE_CODE_FP128 Record</a></h4>
+
+<div>
+
+<p><tt>[FP128]</tt></p>
+
+<p>The <tt>FP128</tt> record (code 14) adds an <tt>fp128</tt> (128-bit
+floating point) type to the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_PPC_FP128">TYPE_CODE_PPC_FP128 Record</a></h4>
+
+<div>
+
+<p><tt>[PPC_FP128]</tt></p>
+
+<p>The <tt>PPC_FP128</tt> record (code 15) adds a <tt>ppc_fp128</tt>
+(128-bit floating point) type to the type table.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TYPE_CODE_METADATA">TYPE_CODE_METADATA Record</a></h4>
+
+<div>
+
+<p><tt>[METADATA]</tt></p>
+
+<p>The <tt>METADATA</tt> record (code 16) adds a <tt>metadata</tt>
+type to the type table.
+</p>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>CONSTANTS_BLOCK</tt> block (id 11) ...
+</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>FUNCTION_BLOCK</tt> block (id 12) ...
+</p>
+
+<p>In addition to the record types described below, a
+<tt>FUNCTION_BLOCK</tt> block may contain the following sub-blocks:
+</p>
+
+<ul>
+<li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
+<li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
+<li><a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a></li>
+</ul>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>TYPE_SYMTAB_BLOCK</tt> block (id 13) contains entries which
+map between module-level named types and their corresponding type
+indices.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4><a name="TST_CODE_ENTRY">TST_CODE_ENTRY Record</a></h4>
+
+<div>
+
+<p><tt>[ENTRY, typeid, ...string...]</tt></p>
+
+<p>The <tt>ENTRY</tt> record (code 1) contains a variable number of
+values, with the first giving the type index of the designated type,
+and the remaining values giving the character codes of the type
+name. Each entry corresponds to a single named type.
+</p>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>VALUE_SYMTAB_BLOCK</tt> block (id 14) ...
+</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="METADATA_BLOCK">METADATA_BLOCK Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>METADATA_BLOCK</tt> block (id 15) ...
+</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a>
+</h3>
+
+<div>
+
+<p>The <tt>METADATA_ATTACHMENT</tt> block (id 16) ...
+</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+<a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+Last modified: $Date: 2011-04-22 19:30:22 -0500 (Fri, 22 Apr 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/BranchWeightMetadata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/BranchWeightMetadata.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/BranchWeightMetadata.html (added)
+++ www-releases/trunk/3.0/docs/BranchWeightMetadata.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,164 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM Branch Weight Metadata</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ LLVM Branch Weight Metadata
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#supported_instructions">Supported Instructions</a></li>
+ <li><a href="#builtin_expect">Built-in "expect" Instruction </a></li>
+ <li><a href="#cfg_modifications">CFG Modifications</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:jstaszak at apple.com">Jakub Staszak</a></p>
+</div>
+
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<div>
+<p>Branch Weight Metadata represents branch weights as its likeliness to
+be taken. Metadata is assigned to the <tt>TerminatorInst</tt> as a
+<tt>MDNode</tt> of the <tt>MD_prof</tt> kind. The first operator is always a
+<tt>MDString</tt> node with the string "branch_weights". Number of operators
+depends on the terminator type.</p>
+
+<p>Branch weights might be fetch from the profiling file, or generated based on
+<a href="#builtin_expect"><tt>__builtin_expect</tt></a> instruction.
+</p>
+
+<p>All weights are represented as an unsigned 32-bit values, where higher value
+indicates greater chance to be taken.</p>
+</div>
+
+<h2>
+ <a name="supported_instructions">Supported Instructions</a>
+</h2>
+
+<div>
+ <h4>BranchInst</h4>
+ <div>
+ <p>Metadata is only assign to the conditional branches. There are two extra
+ operarands, for the true and the false branch.</p>
+ </div>
+ <div class="doc_code">
+ <pre>
+!0 = metadata !{
+ metadata !"branch_weights",
+ i32 <TRUE_BRANCH_WEIGHT>,
+ i32 <FALSE_BRANCH_WEIGHT>
+}
+ </pre>
+ </div>
+
+ <h4>SwitchInst</h4>
+ <div>
+ <p>Branch weights are assign to every case (including <tt>default</tt> case
+ which is always case #0).</p>
+ </div>
+ <div class="doc_code">
+ <pre>
+!0 = metadata !{
+ metadata !"branch_weights",
+ i32 <DEFAULT_BRANCH_WEIGHT>
+ [ , i32 <CASE_BRANCH_WEIGHT> ... ]
+}
+ </pre>
+ </div>
+
+ <h4>IndirectBrInst</h4>
+ <div>
+ <p>Branch weights are assign to every destination.</p>
+ </div>
+ <div class="doc_code">
+ <pre>
+!0 = metadata !{
+ metadata !"branch_weights",
+ i32 <LABEL_BRANCH_WEIGHT>
+ [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
+}
+ </pre>
+ </div>
+
+ <h4>Other</h4>
+ <div>
+ <p>Other terminator instructions are not allowed to contain Branch Weight
+ Metadata.</p>
+ </div>
+</div>
+
+<h2>
+ <a name="builtin_expect">Built-in "expect" Instructions</a>
+</h2>
+<div>
+ <p><tt>__builtin_expect(long exp, long c)</tt> instruction provides branch
+ prediction information. The return value is the value of <tt>exp</tt>.</p>
+
+ <p>It is especially useful in conditional statements. Currently Clang supports
+ two conditional statements:
+ </p>
+ <h4><tt>if</tt> statement</h4>
+ <div>
+ <p>The <tt>exp</tt> parameter is the condition. The <tt>c</tt> parameter is
+ the expected comparision value. If it is equal to 1 (true), the condition is
+ likely to be true, in other case condition is likely to be false. For example:
+ </p>
+ </div>
+ <div class="doc_code">
+ <pre>
+ if (__builtin_expect(x > 0, 1)) {
+ // This block is likely to be taken.
+ }
+ </pre>
+ </div>
+
+ <h4><tt>switch</tt> statement</h4>
+ <div>
+ <p>The <tt>exp</tt> parameter is the value. The <tt>c</tt> parameter is the
+ expected value. If the expected value doesn't show on the cases list, the
+ <tt>default</tt> case is assumed to be likely taken.</p>
+ </div>
+ <div class="doc_code">
+ <pre>
+ switch (__builtin_expect(x, 5)) {
+ default: break;
+ case 0: // ...
+ case 3: // ...
+ case 5: // This case is likely to be taken.
+ }
+ </pre>
+ </div>
+</div>
+
+<h2>
+ <a name="cfg_modifications">CFG Modifications</a>
+</h2>
+<div>
+<p>Branch Weight Metatada is not proof against CFG changes. If terminator
+operands' are changed some action should be taken. In other case some
+misoptimizations may occur due to incorrent branch prediction information.</p>
+</div>
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:jstaszak at apple.com">Jakub Staszak</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/Bugpoint.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/Bugpoint.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/Bugpoint.html (added)
+++ www-releases/trunk/3.0/docs/Bugpoint.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,239 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM bugpoint tool: design and usage</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<h1>
+ LLVM bugpoint tool: design and usage
+</h1>
+
+<ul>
+ <li><a href="#desc">Description</a></li>
+ <li><a href="#design">Design Philosophy</a>
+ <ul>
+ <li><a href="#autoselect">Automatic Debugger Selection</a></li>
+ <li><a href="#crashdebug">Crash debugger</a></li>
+ <li><a href="#codegendebug">Code generator debugger</a></li>
+ <li><a href="#miscompilationdebug">Miscompilation debugger</a></li>
+ </ul></li>
+ <li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li>
+</ul>
+
+<div class="doc_author">
+<p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+<a name="desc">Description</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
+passes. It can be used to debug three types of failures: optimizer crashes,
+miscompilations by optimizers, or bad native code generation (including problems
+in the static and JIT compilers). It aims to reduce large test cases to small,
+useful ones. For example, if <tt>opt</tt> crashes while optimizing a
+file, it will identify the optimization (or combination of optimizations) that
+causes the crash, and reduce the file down to a small example which triggers the
+crash.</p>
+
+<p>For detailed case scenarios, such as debugging <tt>opt</tt>,
+<tt>llvm-ld</tt>, or one of the LLVM code generators, see <a
+href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+<a name="design">Design Philosophy</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
+hooks into the LLVM infrastructure at all. It works with any and all LLVM
+passes and code generators, and does not need to "know" how they work. Because
+of this, it may appear to do stupid things or miss obvious
+simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
+time for computer time in the compiler-debugging process; consequently, it may
+take a long period of (unattended) time to reduce a test case, but we feel it
+is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
+debugging a miscompilation where each test of the program (which requires
+executing it) takes a long time.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="autoselect">Automatic Debugger Selection</a>
+</h3>
+
+<div>
+
+<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
+the command line and links them together into a single module, called the test
+program. If any LLVM passes are specified on the command line, it runs these
+passes on the test program. If any of the passes crash, or if they produce
+malformed output (which causes the verifier to abort), <tt>bugpoint</tt> starts
+the <a href="#crashdebug">crash debugger</a>.</p>
+
+<p>Otherwise, if the <tt>-output</tt> option was not specified,
+<tt>bugpoint</tt> runs the test program with the C backend (which is assumed to
+generate good code) to generate a reference output. Once <tt>bugpoint</tt> has
+a reference output for the test program, it tries executing it with the
+selected code generator. If the selected code generator crashes,
+<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a> on the
+code generator. Otherwise, if the resulting output differs from the reference
+output, it assumes the difference resulted from a code generator failure, and
+starts the <a href="#codegendebug">code generator debugger</a>.</p>
+
+<p>Finally, if the output of the selected code generator matches the reference
+output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
+have been applied to it. If its output differs from the reference output, it
+assumes the difference resulted from a failure in one of the LLVM passes, and
+enters the <a href="#miscompilationdebug">miscompilation debugger</a>.
+Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="crashdebug">Crash debugger</a>
+</h3>
+
+<div>
+
+<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
+as it can to reduce the list of passes (for optimizer crashes) and the size of
+the test program. First, <tt>bugpoint</tt> figures out which combination of
+optimizer passes triggers the bug. This is useful when debugging a problem
+exposed by <tt>opt</tt>, for example, because it runs over 38 passes.</p>
+
+<p>Next, <tt>bugpoint</tt> tries removing functions from the test program, to
+reduce its size. Usually it is able to reduce a test program to a single
+function, when debugging intraprocedural optimizations. Once the number of
+functions has been reduced, it attempts to delete various edges in the control
+flow graph, to reduce the size of the function as much as possible. Finally,
+<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
+not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
+passes crash, give you a bitcode file, and give you instructions on how to
+reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="codegendebug">Code generator debugger</a>
+</h3>
+
+<div>
+
+<p>The code generator debugger attempts to narrow down the amount of code that
+is being miscompiled by the selected code generator. To do this, it takes the
+test program and partitions it into two pieces: one piece which it compiles
+with the C backend (into a shared object), and one piece which it runs with
+either the JIT or the static LLC compiler. It uses several techniques to
+reduce the amount of code pushed through the LLVM code generator, to reduce the
+potential scope of the problem. After it is finished, it emits two bitcode
+files (called "test" [to be compiled with the code generator] and "safe" [to be
+compiled with the C backend], respectively), and instructions for reproducing
+the problem. The code generator debugger assumes that the C backend produces
+good code.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="miscompilationdebug">Miscompilation debugger</a>
+</h3>
+
+<div>
+
+<p>The miscompilation debugger works similarly to the code generator debugger.
+It works by splitting the test program into two pieces, running the
+optimizations specified on one piece, linking the two pieces back together, and
+then executing the result. It attempts to narrow down the list of passes to
+the one (or few) which are causing the miscompilation, then reduce the portion
+of the test program which is being miscompiled. The miscompilation debugger
+assumes that the selected code generator is working properly.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="advice">Advice for using bugpoint</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
+non-obvious ways. Here are some hints and tips:<p>
+
+<ol>
+<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
+ works with programs that have deterministic output. Thus, if the program
+ outputs <tt>argv[0]</tt>, the date, time, or any other "random" data,
+ <tt>bugpoint</tt> may misinterpret differences in these data, when output,
+ as the result of a miscompilation. Programs should be temporarily modified
+ to disable outputs that are likely to vary from run to run.
+
+<li>In the code generator and miscompilation debuggers, debugging will go
+ faster if you manually modify the program or its inputs to reduce the
+ runtime, but still exhibit the problem.
+
+<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
+ it helps track down regressions quickly. To avoid having to relink
+ <tt>bugpoint</tt> every time you change your optimization however, have
+ <tt>bugpoint</tt> dynamically load your optimization with the
+ <tt>-load</tt> option.
+
+<li><p><tt>bugpoint</tt> can generate a lot of output and run for a long period
+ of time. It is often useful to capture the output of the program to file.
+ For example, in the C shell, you can run:</p>
+
+<div class="doc_code">
+<p><tt>bugpoint ... |& tee bugpoint.log</tt></p>
+</div>
+
+ <p>to get a copy of <tt>bugpoint</tt>'s output in the file
+ <tt>bugpoint.log</tt>, as well as on your terminal.</p>
+
+<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
+ <tt>bugpoint</tt> crashes before you see its "All input ok" message,
+ you might try <tt>llvm-link -v</tt> on the same set of input files. If
+ that also crashes, you may be experiencing a linker bug.
+
+<li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM.
+ Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause
+ the list of specified optimizations to be randomized and applied to the
+ program. This process will repeat until a bug is found or the user
+ kills <tt>bugpoint</tt>.
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:23 -0500 (Thu, 03 Nov 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CFEBuildInstrs.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CFEBuildInstrs.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CFEBuildInstrs.html (added)
+++ www-releases/trunk/3.0/docs/CFEBuildInstrs.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,29 @@
+<!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>
Added: www-releases/trunk/3.0/docs/CMake.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CMake.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CMake.html (added)
+++ www-releases/trunk/3.0/docs/CMake.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,566 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Building LLVM with CMake</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<h1>
+ Building LLVM with CMake
+</h1>
+
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#quickstart">Quick start</a></li>
+ <li><a href="#usage">Basic CMake usage</a>
+ <li><a href="#options">Options and variables</a>
+ <ul>
+ <li><a href="#freccmake">Frequently-used CMake variables</a></li>
+ <li><a href="#llvmvars">LLVM-specific variables</a></li>
+ </ul></li>
+ <li><a href="#testing">Executing the test suite</a>
+ <li><a href="#cross">Cross compiling</a>
+ <li><a href="#embedding">Embedding LLVM in your project</a>
+ <ul>
+ <li><a href="#passdev">Developing LLVM pass out of source</a></li>
+ </ul></li>
+ <li><a href="#specifics">Compiler/Platform specific topics</a>
+ <ul>
+ <li><a href="#msvc">Microsoft Visual C++</a></li>
+ </ul></li>
+</ul>
+
+<div class="doc_author">
+<p>Written by <a href="mailto:ofv at wanadoo.es">Oscar Fuentes</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+<a name="intro">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
+ build-generator tool. CMake does not build the project, it generates
+ the files needed by your build tool (GNU make, Visual Studio, etc) for
+ building LLVM.</p>
+
+ <p>If you are really anxious about getting a functional LLVM build,
+ go to the <a href="#quickstart">Quick start</a> section. If you
+ are a CMake novice, start on <a href="#usage">Basic CMake
+ usage</a> and then go back to the <a href="#quickstart">Quick
+ start</a> once you know what you are
+ doing. The <a href="#options">Options and variables</a> section
+ is a reference for customizing your build. If you already have
+ experience with CMake, this is the recommended starting point.
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+<a name="quickstart">Quick start</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p> We use here the command-line, non-interactive CMake interface </p>
+
+<ol>
+
+ <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a>
+ 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>
+
+ <li><p>Create a directory for containing the build. It is not
+ supported to build LLVM on the source directory. cd to this
+ directory:</p>
+ <div class="doc_code">
+ <p><tt>mkdir mybuilddir</tt></p>
+ <p><tt>cd mybuilddir</tt></p>
+ </div>
+
+ <li><p>Execute this command on the shell
+ replacing <i>path/to/llvm/source/root</i> with the path to the
+ root of your LLVM source tree:</p>
+ <div class="doc_code">
+ <p><tt>cmake path/to/llvm/source/root</tt></p>
+ </div>
+
+ <p>CMake will detect your development environment, perform a
+ series of test and generate the files required for building
+ LLVM. CMake will use default values for all build
+ parameters. See the <a href="#options">Options and variables</a>
+ section for fine-tuning your build</p>
+
+ <p>This can fail if CMake can't detect your toolset, or if it
+ thinks that the environment is not sane enough. On this case
+ make sure that the toolset that you intend to use is the only
+ one reachable from the shell and that the shell itself is the
+ correct one for you development environment. CMake will refuse
+ to build MinGW makefiles if you have a POSIX shell reachable
+ through the PATH environment variable, for instance. You can
+ force CMake to use a given build tool, see
+ the <a href="#usage">Usage</a> section.</p>
+
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="usage">Basic CMake usage</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <p>This section explains basic aspects of CMake, mostly for
+ explaining those options which you may need on your day-to-day
+ usage.</p>
+
+ <p>CMake comes with extensive documentation in the form of html
+ files and on the cmake executable itself. Execute <i>cmake
+ --help</i> for further help options.</p>
+
+ <p>CMake requires to know for which build tool it shall generate
+ files (GNU make, Visual Studio, Xcode, etc). If not specified on
+ the command line, it tries to guess it based on you
+ environment. Once identified the build tool, CMake uses the
+ corresponding <i>Generator</i> for creating files for your build
+ tool. You can explicitly specify the generator with the command
+ line option <i>-G "Name of the generator"</i>. For knowing the
+ available generators on your platform, execute</p>
+
+ <div class="doc_code">
+ <p><tt>cmake --help</tt></p>
+ </div>
+
+ <p>This will list the generator's names at the end of the help
+ text. Generator's names are case-sensitive. Example:</p>
+
+ <div class="doc_code">
+ <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p>
+ </div>
+
+ <p>For a given development platform there can be more than one
+ adequate generator. If you use Visual Studio "NMake Makefiles"
+ is a generator you can use for building with NMake. By default,
+ CMake chooses the more specific generator supported by your
+ development environment. If you want an alternative generator,
+ you must tell this to CMake with the <i>-G</i> option.</p>
+
+ <p>TODO: explain variables and cache. Move explanation here from
+ #options section.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="options">Options and variables</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <p>Variables customize how the build will be generated. Options are
+ boolean variables, with possible values ON/OFF. Options and
+ variables are defined on the CMake command line like this:</p>
+
+ <div class="doc_code">
+ <p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p>
+ </div>
+
+ <p>You can set a variable after the initial CMake invocation for
+ changing its value. You can also undefine a variable:</p>
+
+ <div class="doc_code">
+ <p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p>
+ </div>
+
+ <p>Variables are stored on the CMake cache. This is a file
+ named <tt>CMakeCache.txt</tt> on the root of the build
+ directory. Do not hand-edit it.</p>
+
+ <p>Variables are listed here appending its type after a colon. It is
+ correct to write the variable and the type on the CMake command
+ line:</p>
+
+ <div class="doc_code">
+ <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
+ </div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="freccmake">Frequently-used CMake variables</a>
+</h3>
+
+<div>
+
+<p>Here are listed some of the CMake variables that are used often,
+ along with a brief explanation and LLVM-specific notes. For full
+ documentation, check the CMake docs or execute <i>cmake
+ --help-variable VARIABLE_NAME</i>.</p>
+
+<dl>
+ <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
+
+ <dd>Sets the build type for <i>make</i> based generators. Possible
+ values are Release, Debug, RelWithDebInfo and MinSizeRel. On
+ systems like Visual Studio the user sets the build type with the IDE
+ settings.</dd>
+
+ <dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt>
+ <dd>Path where LLVM will be installed if "make install" is invoked
+ or the "INSTALL" target is built.</dd>
+
+ <dt><b>LLVM_LIBDIR_SUFFIX</b>:STRING</dt>
+ <dd>Extra suffix to append to the directory where libraries are to
+ be installed. On a 64-bit architecture, one could use
+ -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.</dd>
+
+ <dt><b>CMAKE_C_FLAGS</b>:STRING</dt>
+ <dd>Extra flags to use when compiling C source files.</dd>
+
+ <dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt>
+ <dd>Extra flags to use when compiling C++ source files.</dd>
+
+ <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
+ <dd>Flag indicating is shared libraries will be built. Its default
+ value is OFF. Shared libraries are not supported on Windows and
+ not recommended in the other OSes.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="llvmvars">LLVM-specific variables</a>
+</h3>
+
+<div>
+
+<dl>
+ <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
+ <dd>Semicolon-separated list of targets to build, or <i>all</i> for
+ building all targets. Case-sensitive. For Visual C++ defaults
+ to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
+ <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd>
+
+ <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt>
+ <dd>Build LLVM tools. Defaults to ON. Targets for building each tool
+ are generated in any case. You can build an tool separately by
+ invoking its target. For example, you can build <i>llvm-as</i>
+ 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>
+
+ <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt>
+ <dd>Enables code assertions. Defaults to OFF if and only if
+ CMAKE_BUILD_TYPE is <i>Release</i>.</dd>
+
+ <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
+ <dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the
+ compiler supports this flag. Some systems, like Windows, do not
+ need this flag. Defaults to ON.</dd>
+
+ <dt><b>LLVM_ENABLE_WARNINGS</b>:BOOL</dt>
+ <dd>Enable all compiler warnings. Defaults to ON.</dd>
+
+ <dt><b>LLVM_ENABLE_PEDANTIC</b>:BOOL</dt>
+ <dd>Enable pedantic mode. This disable compiler specific extensions, is
+ possible. Defaults to ON.</dd>
+
+ <dt><b>LLVM_ENABLE_WERROR</b>:BOOL</dt>
+ <dd>Stop and fail build, if a compiler warning is
+ triggered. Defaults to OFF.</dd>
+
+ <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
+ <dd>Build 32-bits executables and libraries on 64-bits systems. This
+ option is available only on some 64-bits unix systems. Defaults to
+ OFF.</dd>
+
+ <dt><b>LLVM_TARGET_ARCH</b>:STRING</dt>
+ <dd>LLVM target to use for native code generation. This is required
+ for JIT generation. It defaults to "host", meaning that it shall
+ pick the architecture of the machine where LLVM is being built. If
+ you are cross-compiling, set it to the target architecture
+ name.</dd>
+
+ <dt><b>LLVM_TABLEGEN</b>:STRING</dt>
+ <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>:PATH</dt>
+ <dd>The path to GnuWin32 tools for tests. Valid on Windows host.
+ Defaults to "", then Lit seeks tools according to %PATH%.
+ Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first,
+ 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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="testing">Executing the test suite</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Testing is performed when the <i>check</i> target is built. For
+ instance, if you are using makefiles, execute this command while on
+ the top level of your build directory:</p>
+
+<div class="doc_code">
+ <p><tt>make check</tt></p>
+</div>
+
+<p>On Visual Studio, you may run tests to build the project "check".</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="cross">Cross compiling</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
+ wiki page</a> for generic instructions on how to cross-compile
+ with CMake. It goes into detailed explanations and may seem
+ daunting, but it is not. On the wiki page there are several
+ examples including toolchain files. Go directly to
+ <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this
+ section</a> for a quick solution.</p>
+
+<p>Also see the <a href="#llvmvars">LLVM-specific variables</a>
+ section for variables used when cross-compiling.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="embedding">Embedding LLVM in your project</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <p>The most difficult part of adding LLVM to the build of a project
+ is to determine the set of LLVM libraries corresponding to the set
+ of required LLVM features. What follows is an example of how to
+ obtain this information:</p>
+
+ <div class="doc_code">
+ <pre>
+ <b># A convenience variable:</b>
+ set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
+ <b># A bit of a sanity check:</b>
+ if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
+ message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
+ endif()
+ <b># We incorporate the CMake features provided by LLVM:</b>
+ set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
+ include(LLVMConfig)
+ <b># Now set the header and library paths:</b>
+ include_directories( ${LLVM_INCLUDE_DIRS} )
+ link_directories( ${LLVM_LIBRARY_DIRS} )
+ add_definitions( ${LLVM_DEFINITIONS} )
+ <b># Let's suppose we want to build a JIT compiler with support for
+ # binary code (no interpreter):</b>
+ llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+ <b># Finally, we link the LLVM libraries to our executable:</b>
+ target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+ </pre>
+ </div>
+
+ <p>This assumes that LLVM_ROOT points to an install of LLVM. The
+ procedure works too for uninstalled builds although we need to take
+ care to add an <i>include_directories</i> for the location of the
+ headers on the LLVM source directory (if we are building
+ out-of-source.)</p>
+
+ <p>Alternativaly, you can utilize CMake's <i>find_package</i>
+ functionality. Here is an equivalent variant of snippet shown above:</p>
+
+ <div class="doc_code">
+ <pre>
+ find_package(LLVM)
+
+ if( NOT LLVM_FOUND )
+ message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
+ endif()
+
+ include_directories( ${LLVM_INCLUDE_DIRS} )
+ link_directories( ${LLVM_LIBRARY_DIRS} )
+
+ llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+
+ target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+ </pre>
+ </div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="passdev">Developing LLVM pass out of source</a>
+</h3>
+
+<div>
+
+ <p>It is possible to develop LLVM passes against installed LLVM.
+ An example of project layout provided below:</p>
+
+ <div class="doc_code">
+ <pre>
+ <project dir>/
+ |
+ CMakeLists.txt
+ <pass name>/
+ |
+ CMakeLists.txt
+ Pass.cpp
+ ...
+ </pre>
+ </div>
+
+ <p>Contents of <project dir>/CMakeLists.txt:</p>
+
+ <div class="doc_code">
+ <pre>
+ find_package(LLVM)
+
+ <b># Define add_llvm_* macro's.</b>
+ include(AddLLVM)
+
+ add_definitions(${LLVM_DEFINITIONS})
+ include_directories(${LLVM_INCLUDE_DIRS})
+ link_directories(${LLVM_LIBRARY_DIRS})
+
+ add_subdirectory(<pass name>)
+ </pre>
+ </div>
+
+ <p>Contents of <project dir>/<pass name>/CMakeLists.txt:</p>
+
+ <div class="doc_code">
+ <pre>
+ add_llvm_loadable_module(LLVMPassname
+ Pass.cpp
+ )
+ </pre>
+ </div>
+
+ <p>When you are done developing your pass, you may wish to integrate it
+ into LLVM source tree. You can achieve it in two easy steps:<br>
+ 1. Copying <pass name> folder into <LLVM root>/lib/Transform directory.<br>
+ 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/lib/Transform/CMakeLists.txt</p>
+</div>
+<!-- *********************************************************************** -->
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="specifics">Compiler/Platform specific topics</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Notes for specific compilers and/or platforms.</p>
+
+<h3>
+ <a name="msvc">Microsoft Visual C++</a>
+</h3>
+
+<div>
+
+<dl>
+ <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
+ <dd>Specifies the maximum number of parallell compiler jobs to use
+ per project when building with msbuild or Visual Studio. Only supported for
+ Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
+ processors. Default is 0.</dd>
+</dl>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:ofv at wanadoo.es">Oscar Fuentes</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CodeGenerator.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CodeGenerator.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CodeGenerator.html (added)
+++ www-releases/trunk/3.0/docs/CodeGenerator.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,2999 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8">
+ <title>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>
+
+<h1>
+ The LLVM Target-Independent Code Generator
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a>
+ <ul>
+ <li><a href="#required">Required components in the code generator</a></li>
+ <li><a href="#high-level-design">The high-level design of the code
+ generator</a></li>
+ <li><a href="#tablegen">Using TableGen for target description</a></li>
+ </ul>
+ </li>
+ <li><a href="#targetdesc">Target description classes</a>
+ <ul>
+ <li><a href="#targetmachine">The <tt>TargetMachine</tt> class</a></li>
+ <li><a href="#targetdata">The <tt>TargetData</tt> class</a></li>
+ <li><a href="#targetlowering">The <tt>TargetLowering</tt> class</a></li>
+ <li><a href="#targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a></li>
+ <li><a href="#targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a></li>
+ <li><a href="#targetframeinfo">The <tt>TargetFrameInfo</tt> class</a></li>
+ <li><a href="#targetsubtarget">The <tt>TargetSubtarget</tt> class</a></li>
+ <li><a href="#targetjitinfo">The <tt>TargetJITInfo</tt> class</a></li>
+ </ul>
+ </li>
+ <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>
+ class</a></li>
+ <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>
+ <ul>
+ <li><a href="#selectiondag_intro">Introduction to SelectionDAGs</a></li>
+ <li><a href="#selectiondag_process">SelectionDAG Code Generation
+ Process</a></li>
+ <li><a href="#selectiondag_build">Initial SelectionDAG
+ Construction</a></li>
+ <li><a href="#selectiondag_legalize_types">SelectionDAG LegalizeTypes Phase</a></li>
+ <li><a href="#selectiondag_legalize">SelectionDAG Legalize Phase</a></li>
+ <li><a href="#selectiondag_optimize">SelectionDAG Optimization
+ Phase: the DAG Combiner</a></li>
+ <li><a href="#selectiondag_select">SelectionDAG Select Phase</a></li>
+ <li><a href="#selectiondag_sched">SelectionDAG Scheduling and Formation
+ Phase</a></li>
+ <li><a href="#selectiondag_future">Future directions for the
+ SelectionDAG</a></li>
+ </ul></li>
+ <li><a href="#liveintervals">Live Intervals</a>
+ <ul>
+ <li><a href="#livevariable_analysis">Live Variable Analysis</a></li>
+ <li><a href="#liveintervals_analysis">Live Intervals Analysis</a></li>
+ </ul></li>
+ <li><a href="#regalloc">Register Allocation</a>
+ <ul>
+ <li><a href="#regAlloc_represent">How registers are represented in
+ LLVM</a></li>
+ <li><a href="#regAlloc_howTo">Mapping virtual registers to physical
+ registers</a></li>
+ <li><a href="#regAlloc_twoAddr">Handling two address instructions</a></li>
+ <li><a href="#regAlloc_ssaDecon">The SSA deconstruction phase</a></li>
+ <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></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>
+ <li><a href="#ppc">The PowerPC backend</a>
+ <ul>
+ <li><a href="#ppc_abi">LLVM PowerPC ABI</a></li>
+ <li><a href="#ppc_frame">Frame Layout</a></li>
+ <li><a href="#ppc_prolog">Prolog/Epilog</a></li>
+ <li><a href="#ppc_dynamic">Dynamic Allocation</a></li>
+ </ul></li>
+ <li><a href="#ptx">The PTX backend</a></li>
+ </ul></li>
+
+</ol>
+
+<div class="doc_author">
+ <p>Written by the LLVM Team.</p>
+</div>
+
+<div class="doc_warning">
+ <p>Warning: This is a work in progress.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The LLVM target-independent code generator is a framework that provides a
+ 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 six
+ main components:</p>
+
+<ol>
+ <li><a href="#targetdesc">Abstract target description</a> interfaces which
+ capture important properties about various aspects of the machine,
+ 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">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>. 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,
+ stack frame representation, etc). This code lives
+ in <tt>lib/CodeGen/</tt>.</li>
+
+ <li><a href="#targetimpls">Implementations of the abstract target description
+ interfaces</a> for particular targets. These machine descriptions make
+ use of the components provided by LLVM, and can optionally provide custom
+ target-specific passes, to build complete code generators for a specific
+ target. Target descriptions live in <tt>lib/Target/</tt>.</li>
+
+ <li><a href="#jit">The target-independent JIT components</a>. The LLVM JIT is
+ completely target independent (it uses the <tt>TargetJITInfo</tt>
+ structure to interface for target-specific issues. The code for the
+ target-independent JIT lives in <tt>lib/ExecutionEngine/JIT</tt>.</li>
+</ol>
+
+<p>Depending on which part of the code generator you are interested in working
+ on, different pieces of this will be useful to you. In any case, you should
+ be familiar with the <a href="#targetdesc">target description</a>
+ and <a href="#codegendesc">machine code representation</a> classes. If you
+ want to add a backend for a new target, you will need
+ to <a href="#targetimpls">implement the target description</a> classes for
+ your new target and understand the <a href="LangRef.html">LLVM code
+ representation</a>. If you are interested in implementing a
+ new <a href="#codegenalgs">code generation algorithm</a>, it should only
+ depend on the target-description and machine code representation classes,
+ ensuring that it is portable.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="required">Required components in the code generator</a>
+</h3>
+
+<div>
+
+<p>The two pieces of the LLVM code generator are the high-level interface to the
+ code generator and the set of reusable components that can be used to build
+ target-specific backends. The two most important interfaces
+ (<a href="#targetmachine"><tt>TargetMachine</tt></a>
+ and <a href="#targetdata"><tt>TargetData</tt></a>) are the only ones that are
+ required to be defined for a backend to fit into the LLVM system, but the
+ others must be defined if the reusable code generator components are going to
+ be used.</p>
+
+<p>This design has two important implications. The first is that LLVM can
+ support completely non-traditional code generation targets. For example, the
+ C backend does not require register allocation, instruction selection, or any
+ of the other standard components provided by the system. As such, it only
+ implements these two interfaces, and does its own thing. Another example of
+ a code generator like this is a (purely hypothetical) backend that converts
+ LLVM to the GCC RTL form and uses GCC to emit machine code for a target.</p>
+
+<p>This design also implies that it is possible to design and implement
+ radically different code generators in the LLVM system that do not make use
+ of any of the built-in components. Doing so is not recommended at all, but
+ could be required for radically different targets that do not fit into the
+ LLVM machine description model: FPGAs for example.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="high-level-design">The high-level design of the code generator</a>
+</h3>
+
+<div>
+
+<p>The LLVM target-independent code generator is designed to support efficient
+ and quality code generation for standard register-based microprocessors.
+ Code generation in this model is divided into the following stages:</p>
+
+<ol>
+ <li><b><a href="#instselect">Instruction Selection</a></b> — This phase
+ determines an efficient way to express the input LLVM code in the target
+ instruction set. This stage produces the initial code for the program in
+ the target instruction set, then makes use of virtual registers in SSA
+ form and physical registers that represent any required register
+ assignments due to target constraints or calling conventions. This step
+ turns the LLVM code into a DAG of target instructions.</li>
+
+ <li><b><a href="#selectiondag_sched">Scheduling and Formation</a></b> —
+ This phase takes the DAG of target instructions produced by the
+ instruction selection phase, determines an ordering of the instructions,
+ then emits the instructions
+ as <tt><a href="#machineinstr">MachineInstr</a></tt>s with that ordering.
+ Note that we describe this in the <a href="#instselect">instruction
+ selection section</a> because it operates on
+ a <a href="#selectiondag_intro">SelectionDAG</a>.</li>
+
+ <li><b><a href="#ssamco">SSA-based Machine Code Optimizations</a></b> —
+ This optional stage consists of a series of machine-code optimizations
+ that operate on the SSA-form produced by the instruction selector.
+ Optimizations like modulo-scheduling or peephole optimization work
+ here.</li>
+
+ <li><b><a href="#regalloc">Register Allocation</a></b> — The target code
+ is transformed from an infinite virtual register file in SSA form to the
+ concrete register file used by the target. This phase introduces spill
+ code and eliminates all virtual register references from the program.</li>
+
+ <li><b><a href="#proepicode">Prolog/Epilog Code Insertion</a></b> — Once
+ the machine code has been generated for the function and the amount of
+ stack space required is known (used for LLVM alloca's and spill slots),
+ the prolog and epilog code for the function can be inserted and "abstract
+ stack location references" can be eliminated. This stage is responsible
+ for implementing optimizations like frame-pointer elimination and stack
+ packing.</li>
+
+ <li><b><a href="#latemco">Late Machine Code Optimizations</a></b> —
+ Optimizations that operate on "final" machine code can go here, such as
+ spill code scheduling and peephole optimizations.</li>
+
+ <li><b><a href="#codeemit">Code Emission</a></b> — The final stage
+ actually puts out the code for the current function, either in the target
+ assembler format or in machine code.</li>
+</ol>
+
+<p>The code generator is based on the assumption that the instruction selector
+ will use an optimal pattern matching selector to create high-quality
+ sequences of native instructions. Alternative code generator designs based
+ on pattern expansion and aggressive iterative peephole optimization are much
+ slower. This design permits efficient compilation (important for JIT
+ environments) and aggressive optimization (used when generating code offline)
+ by allowing components of varying levels of sophistication to be used for any
+ step of compilation.</p>
+
+<p>In addition to these stages, target implementations can insert arbitrary
+ target-specific passes into the flow. For example, the X86 target uses a
+ special pass to handle the 80x87 floating point stack architecture. Other
+ targets with unusual requirements can be supported with custom passes as
+ needed.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="tablegen">Using TableGen for target description</a>
+</h3>
+
+<div>
+
+<p>The target description classes require a detailed description of the target
+ architecture. These target descriptions often have a large amount of common
+ information (e.g., an <tt>add</tt> instruction is almost identical to a
+ <tt>sub</tt> instruction). In order to allow the maximum amount of
+ commonality to be factored out, the LLVM code generator uses
+ the <a href="TableGenFundamentals.html">TableGen</a> tool to describe big
+ chunks of the target machine, which allows the use of domain-specific and
+ target-specific abstractions to reduce the amount of repetition.</p>
+
+<p>As LLVM continues to be developed and refined, we plan to move more and more
+ of the target description to the <tt>.td</tt> form. Doing so gives us a
+ number of advantages. The most important is that it makes it easier to port
+ LLVM because it reduces the amount of C++ code that has to be written, and
+ the surface area of the code generator that needs to be understood before
+ someone can get something working. Second, it makes it easier to change
+ things. In particular, if tables and other things are all emitted
+ by <tt>tblgen</tt>, we only need a change in one place (<tt>tblgen</tt>) to
+ update all of the targets to a new interface.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="targetdesc">Target description classes</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The LLVM target description classes (located in the
+ <tt>include/llvm/Target</tt> directory) provide an abstract description of
+ the target machine independent of any particular client. These classes are
+ designed to capture the <i>abstract</i> properties of the target (such as the
+ instructions and registers it has), and do not incorporate any particular
+ pieces of code generation algorithms.</p>
+
+<p>All of the target description classes (except the
+ <tt><a href="#targetdata">TargetData</a></tt> class) are designed to be
+ subclassed by the concrete target implementation, and have virtual methods
+ implemented. To get to these implementations, the
+ <tt><a href="#targetmachine">TargetMachine</a></tt> class provides accessors
+ that should be implemented by the target.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetmachine">The <tt>TargetMachine</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetMachine</tt> class provides virtual methods that are used to
+ access the target-specific implementations of the various target description
+ classes via the <tt>get*Info</tt> methods (<tt>getInstrInfo</tt>,
+ <tt>getRegisterInfo</tt>, <tt>getFrameInfo</tt>, etc.). This class is
+ designed to be specialized by a concrete target implementation
+ (e.g., <tt>X86TargetMachine</tt>) which implements the various virtual
+ methods. The only required target description class is
+ the <a href="#targetdata"><tt>TargetData</tt></a> class, but if the code
+ generator components are to be used, the other interfaces should be
+ implemented as well.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetdata">The <tt>TargetData</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetData</tt> class is the only required target description class,
+ and it is the only class that is not extensible (you cannot derived a new
+ class from it). <tt>TargetData</tt> specifies information about how the
+ target lays out memory for structures, the alignment requirements for various
+ data types, the size of pointers in the target, and whether the target is
+ little-endian or big-endian.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetlowering">The <tt>TargetLowering</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetLowering</tt> class is used by SelectionDAG based instruction
+ selectors primarily to describe how LLVM code should be lowered to
+ SelectionDAG operations. Among other things, this class indicates:</p>
+
+<ul>
+ <li>an initial register class to use for various <tt>ValueType</tt>s,</li>
+
+ <li>which operations are natively supported by the target machine,</li>
+
+ <li>the return type of <tt>setcc</tt> operations,</li>
+
+ <li>the type to use for shift amounts, and</li>
+
+ <li>various high-level characteristics, like whether it is profitable to turn
+ division by a constant into a multiplication sequence</li>
+</ul>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetRegisterInfo</tt> class is used to describe the register file
+ of the target and any interactions between the registers.</p>
+
+<p>Registers in the code generator are represented in the code generator by
+ unsigned integers. Physical registers (those that actually exist in the
+ target description) are unique small numbers, and virtual registers are
+ generally large. Note that register #0 is reserved as a flag value.</p>
+
+<p>Each register in the processor description has an associated
+ <tt>TargetRegisterDesc</tt> entry, which provides a textual name for the
+ register (used for assembly output and debugging dumps) and a set of aliases
+ (used to indicate whether one register overlaps with another).</p>
+
+<p>In addition to the per-register description, the <tt>TargetRegisterInfo</tt>
+ class exposes a set of processor specific register classes (instances of the
+ <tt>TargetRegisterClass</tt> class). Each register class contains sets of
+ registers that have the same properties (for example, they are all 32-bit
+ integer registers). Each SSA virtual register created by the instruction
+ selector has an associated register class. When the register allocator runs,
+ it replaces virtual registers with a physical register in the set.</p>
+
+<p>The target-specific implementations of these classes is auto-generated from
+ a <a href="TableGenFundamentals.html">TableGen</a> description of the
+ register file.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetInstrInfo</tt> class is used to describe the machine
+ instructions supported by the target. It is essentially an array of
+ <tt>TargetInstrDescriptor</tt> objects, each of which describes one
+ instruction the target supports. Descriptors define things like the mnemonic
+ for the opcode, the number of operands, the list of implicit register uses
+ and defs, whether the instruction has certain target-independent properties
+ (accesses memory, is commutable, etc), and holds any target-specific
+ flags.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetframeinfo">The <tt>TargetFrameInfo</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetFrameInfo</tt> class is used to provide information about the
+ stack frame layout of the target. It holds the direction of stack growth, the
+ known stack alignment on entry to each function, and the offset to the local
+ area. The offset to the local area is the offset from the stack pointer on
+ function entry to the first location where function data (local variables,
+ spill locations) can be stored.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetsubtarget">The <tt>TargetSubtarget</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetSubtarget</tt> class is used to provide information about the
+ specific chip set being targeted. A sub-target informs code generation of
+ which instructions are supported, instruction latencies and instruction
+ execution itinerary; i.e., which processing units are used, in what order,
+ and for how long.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetjitinfo">The <tt>TargetJITInfo</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>TargetJITInfo</tt> class exposes an abstract interface used by the
+ Just-In-Time code generator to perform target-specific activities, such as
+ emitting stubs. If a <tt>TargetMachine</tt> supports JIT code generation, it
+ should provide one of these objects through the <tt>getJITInfo</tt>
+ method.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="codegendesc">Machine code description classes</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>At the high-level, LLVM code is translated to a machine specific
+ representation formed out of
+ <a href="#machinefunction"><tt>MachineFunction</tt></a>,
+ <a href="#machinebasicblock"><tt>MachineBasicBlock</tt></a>,
+ and <a href="#machineinstr"><tt>MachineInstr</tt></a> instances (defined
+ in <tt>include/llvm/CodeGen</tt>). This representation is completely target
+ agnostic, representing instructions in their most abstract form: an opcode
+ and a series of operands. This representation is designed to support both an
+ SSA representation for machine code, as well as a register allocated, non-SSA
+ form.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="machineinstr">The <tt>MachineInstr</tt> class</a>
+</h3>
+
+<div>
+
+<p>Target machine instructions are represented as instances of the
+ <tt>MachineInstr</tt> class. This class is an extremely abstract way of
+ representing machine instructions. In particular, it only keeps track of an
+ opcode number and a set of operands.</p>
+
+<p>The opcode number is a simple unsigned integer that only has meaning to a
+ specific backend. All of the instructions for a target should be defined in
+ the <tt>*InstrInfo.td</tt> file for the target. The opcode enum values are
+ auto-generated from this description. The <tt>MachineInstr</tt> class does
+ not have any information about how to interpret the instruction (i.e., what
+ the semantics of the instruction are); for that you must refer to the
+ <tt><a href="#targetinstrinfo">TargetInstrInfo</a></tt> class.</p>
+
+<p>The operands of a machine instruction can be of several different types: a
+ register reference, a constant integer, a basic block reference, etc. In
+ addition, a machine operand should be marked as a def or a use of the value
+ (though only registers are allowed to be defs).</p>
+
+<p>By convention, the LLVM code generator orders instruction operands so that
+ all register definitions come before the register uses, even on architectures
+ that are normally printed in other orders. For example, the SPARC add
+ instruction: "<tt>add %i1, %i2, %i3</tt>" adds the "%i1", and "%i2" registers
+ and stores the result into the "%i3" register. In the LLVM code generator,
+ the operands should be stored as "<tt>%i3, %i1, %i2</tt>": with the
+ destination first.</p>
+
+<p>Keeping destination (definition) operands at the beginning of the operand
+ list has several advantages. In particular, the debugging printer will print
+ the instruction like this:</p>
+
+<div class="doc_code">
+<pre>
+%r3 = add %i1, %i2
+</pre>
+</div>
+
+<p>Also if the first operand is a def, it is easier to <a href="#buildmi">create
+ instructions</a> whose only def is the first operand.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="buildmi">Using the <tt>MachineInstrBuilder.h</tt> functions</a>
+</h4>
+
+<div>
+
+<p>Machine instructions are created by using the <tt>BuildMI</tt> functions,
+ located in the <tt>include/llvm/CodeGen/MachineInstrBuilder.h</tt> file. The
+ <tt>BuildMI</tt> functions make it easy to build arbitrary machine
+ instructions. Usage of the <tt>BuildMI</tt> functions look like this:</p>
+
+<div class="doc_code">
+<pre>
+// Create a 'DestReg = mov 42' (rendered in X86 assembly as 'mov DestReg, 42')
+// instruction. The '1' specifies how many operands will be added.
+MachineInstr *MI = BuildMI(X86::MOV32ri, 1, DestReg).addImm(42);
+
+// Create the same instr, but insert it at the end of a basic block.
+MachineBasicBlock &MBB = ...
+BuildMI(MBB, X86::MOV32ri, 1, DestReg).addImm(42);
+
+// Create the same instr, but insert it before a specified iterator point.
+MachineBasicBlock::iterator MBBI = ...
+BuildMI(MBB, MBBI, X86::MOV32ri, 1, DestReg).addImm(42);
+
+// Create a 'cmp Reg, 0' instruction, no destination reg.
+MI = BuildMI(X86::CMP32ri, 2).addReg(Reg).addImm(0);
+// Create an 'sahf' instruction which takes no operands and stores nothing.
+MI = BuildMI(X86::SAHF, 0);
+
+// Create a self looping branch instruction.
+BuildMI(MBB, X86::JNE, 1).addMBB(&MBB);
+</pre>
+</div>
+
+<p>The key thing to remember with the <tt>BuildMI</tt> functions is that you
+ have to specify the number of operands that the machine instruction will
+ take. This allows for efficient memory allocation. You also need to specify
+ if operands default to be uses of values, not definitions. If you need to
+ add a definition operand (other than the optional destination register), you
+ must explicitly mark it as such:</p>
+
+<div class="doc_code">
+<pre>
+MI.addReg(Reg, RegState::Define);
+</pre>
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="fixedregs">Fixed (preassigned) registers</a>
+</h4>
+
+<div>
+
+<p>One important issue that the code generator needs to be aware of is the
+ presence of fixed registers. In particular, there are often places in the
+ instruction stream where the register allocator <em>must</em> arrange for a
+ particular value to be in a particular register. This can occur due to
+ limitations of the instruction set (e.g., the X86 can only do a 32-bit divide
+ with the <tt>EAX</tt>/<tt>EDX</tt> registers), or external factors like
+ calling conventions. In any case, the instruction selector should emit code
+ that copies a virtual register into or out of a physical register when
+ needed.</p>
+
+<p>For example, consider this simple LLVM example:</p>
+
+<div class="doc_code">
+<pre>
+define i32 @test(i32 %X, i32 %Y) {
+ %Z = udiv i32 %X, %Y
+ ret i32 %Z
+}
+</pre>
+</div>
+
+<p>The X86 instruction selector produces this machine code for the <tt>div</tt>
+ and <tt>ret</tt> (use "<tt>llc X.bc -march=x86 -print-machineinstrs</tt>" to
+ get this):</p>
+
+<div class="doc_code">
+<pre>
+;; Start of div
+%EAX = mov %reg1024 ;; Copy X (in reg1024) into EAX
+%reg1027 = sar %reg1024, 31
+%EDX = mov %reg1027 ;; Sign extend X into EDX
+idiv %reg1025 ;; Divide by Y (in reg1025)
+%reg1026 = mov %EAX ;; Read the result (Z) out of EAX
+
+;; Start of ret
+%EAX = mov %reg1026 ;; 32-bit return value goes in EAX
+ret
+</pre>
+</div>
+
+<p>By the end of code generation, the register allocator has coalesced the
+ registers and deleted the resultant identity moves producing the following
+ code:</p>
+
+<div class="doc_code">
+<pre>
+;; X is in EAX, Y is in ECX
+mov %EAX, %EDX
+sar %EDX, 31
+idiv %ECX
+ret
+</pre>
+</div>
+
+<p>This approach is extremely general (if it can handle the X86 architecture, it
+ can handle anything!) and allows all of the target specific knowledge about
+ the instruction stream to be isolated in the instruction selector. Note that
+ physical registers should have a short lifetime for good code generation, and
+ all physical registers are assumed dead on entry to and exit from basic
+ blocks (before register allocation). Thus, if you need a value to be live
+ across basic block boundaries, it <em>must</em> live in a virtual
+ register.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ssa">Machine code in SSA form</a>
+</h4>
+
+<div>
+
+<p><tt>MachineInstr</tt>'s are initially selected in SSA-form, and are
+ maintained in SSA-form until register allocation happens. For the most part,
+ this is trivially simple since LLVM is already in SSA form; LLVM PHI nodes
+ become machine code PHI nodes, and virtual registers are only allowed to have
+ a single definition.</p>
+
+<p>After register allocation, machine code is no longer in SSA-form because
+ there are no virtual registers left in the code.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="machinebasicblock">The <tt>MachineBasicBlock</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>MachineBasicBlock</tt> class contains a list of machine instructions
+ (<tt><a href="#machineinstr">MachineInstr</a></tt> instances). It roughly
+ corresponds to the LLVM code input to the instruction selector, but there can
+ be a one-to-many mapping (i.e. one LLVM basic block can map to multiple
+ machine basic blocks). The <tt>MachineBasicBlock</tt> class has a
+ "<tt>getBasicBlock</tt>" method, which returns the LLVM basic block that it
+ comes from.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="machinefunction">The <tt>MachineFunction</tt> class</a>
+</h3>
+
+<div>
+
+<p>The <tt>MachineFunction</tt> class contains a list of machine basic blocks
+ (<tt><a href="#machinebasicblock">MachineBasicBlock</a></tt> instances). It
+ corresponds one-to-one with the LLVM function input to the instruction
+ selector. In addition to a list of basic blocks,
+ the <tt>MachineFunction</tt> contains a a <tt>MachineConstantPool</tt>,
+ a <tt>MachineFrameInfo</tt>, a <tt>MachineFunctionInfo</tt>, and a
+ <tt>MachineRegisterInfo</tt>. See
+ <tt>include/llvm/CodeGen/MachineFunction.h</tt> for more information.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="mc">The "MC" Layer</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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 code assemblers 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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="mcstreamer">The <tt>MCStreamer</tt> API</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="mccontext">The <tt>MCContext</tt> class</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="mcsymbol">The <tt>MCSymbol</tt> class</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="mcsection">The <tt>MCSection</tt> class</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="mcinst">The <tt>MCInst</tt> class</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="codegenalgs">Target-independent code generation algorithms</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section documents the phases described in the
+ <a href="#high-level-design">high-level design of the code generator</a>.
+ It explains how they work and some of the rationale behind their design.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="instselect">Instruction Selection</a>
+</h3>
+
+<div>
+
+<p>Instruction Selection is the process of translating LLVM code presented to
+ the code generator into target-specific machine instructions. There are
+ several well-known ways to do this in the literature. LLVM uses a
+ SelectionDAG based instruction selector.</p>
+
+<p>Portions of the DAG instruction selector are generated from the target
+ description (<tt>*.td</tt>) files. Our goal is for the entire instruction
+ selector to be generated from these <tt>.td</tt> files, though currently
+ there are still things that require custom C++ code.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_intro">Introduction to SelectionDAGs</a>
+</h4>
+
+<div>
+
+<p>The SelectionDAG provides an abstraction for code representation in a way
+ that is amenable to instruction selection using automatic techniques
+ (e.g. dynamic-programming based optimal pattern matching selectors). It is
+ also well-suited to other phases of code generation; in particular,
+ instruction scheduling (SelectionDAG's are very close to scheduling DAGs
+ post-selection). Additionally, the SelectionDAG provides a host
+ representation where a large variety of very-low-level (but
+ target-independent) <a href="#selectiondag_optimize">optimizations</a> may be
+ performed; ones which require extensive information about the instructions
+ efficiently supported by the target.</p>
+
+<p>The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the
+ <tt>SDNode</tt> class. The primary payload of the <tt>SDNode</tt> is its
+ operation code (Opcode) that indicates what operation the node performs and
+ the operands to the operation. The various operation node types are
+ described at the top of the <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>
+ file.</p>
+
+<p>Although most operations define a single value, each node in the graph may
+ define multiple values. For example, a combined div/rem operation will
+ define both the dividend and the remainder. Many other situations require
+ multiple values as well. Each node also has some number of operands, which
+ are edges to the node defining the used value. Because nodes may define
+ multiple values, edges are represented by instances of the <tt>SDValue</tt>
+ class, which is a <tt><SDNode, unsigned></tt> pair, indicating the node
+ and result value being used, respectively. Each value produced by
+ an <tt>SDNode</tt> has an associated <tt>MVT</tt> (Machine Value Type)
+ indicating what the type of the value is.</p>
+
+<p>SelectionDAGs contain two different kinds of values: those that represent
+ data flow and those that represent control flow dependencies. Data values
+ are simple edges with an integer or floating point value type. Control edges
+ are represented as "chain" edges which are of type <tt>MVT::Other</tt>.
+ These edges provide an ordering between nodes that have side effects (such as
+ loads, stores, calls, returns, etc). All nodes that have side effects should
+ take a token chain as input and produce a new one as output. By convention,
+ token chain inputs are always operand #0, and chain results are always the
+ last value produced by an operation.</p>
+
+<p>A SelectionDAG has designated "Entry" and "Root" nodes. The Entry node is
+ always a marker node with an Opcode of <tt>ISD::EntryToken</tt>. The Root
+ node is the final side-effecting node in the token chain. For example, in a
+ single basic block function it would be the return node.</p>
+
+<p>One important concept for SelectionDAGs is the notion of a "legal" vs.
+ "illegal" DAG. A legal DAG for a target is one that only uses supported
+ operations and supported types. On a 32-bit PowerPC, for example, a DAG with
+ a value of type i1, i8, i16, or i64 would be illegal, as would a DAG that
+ uses a SREM or UREM operation. The
+ <a href="#selectinodag_legalize_types">legalize types</a> and
+ <a href="#selectiondag_legalize">legalize operations</a> phases are
+ responsible for turning an illegal DAG into a legal DAG.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_process">SelectionDAG Instruction Selection Process</a>
+</h4>
+
+<div>
+
+<p>SelectionDAG-based instruction selection consists of the following steps:</p>
+
+<ol>
+ <li><a href="#selectiondag_build">Build initial DAG</a> — This stage
+ performs a simple translation from the input LLVM code to an illegal
+ SelectionDAG.</li>
+
+ <li><a href="#selectiondag_optimize">Optimize SelectionDAG</a> — This
+ stage performs simple optimizations on the SelectionDAG to simplify it,
+ and recognize meta instructions (like rotates
+ and <tt>div</tt>/<tt>rem</tt> pairs) for targets that support these meta
+ operations. This makes the resultant code more efficient and
+ the <a href="#selectiondag_select">select instructions from DAG</a> phase
+ (below) simpler.</li>
+
+ <li><a href="#selectiondag_legalize_types">Legalize SelectionDAG Types</a>
+ — This stage transforms SelectionDAG nodes to eliminate any types
+ that are unsupported on the target.</li>
+
+ <li><a href="#selectiondag_optimize">Optimize SelectionDAG</a> — The
+ SelectionDAG optimizer is run to clean up redundancies exposed by type
+ legalization.</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
+ operation legalization.</li>
+
+ <li><a href="#selectiondag_select">Select instructions from DAG</a> —
+ Finally, the target instruction selector matches the DAG operations to
+ target instructions. This process translates the target-independent input
+ DAG into another DAG of target instructions.</li>
+
+ <li><a href="#selectiondag_sched">SelectionDAG Scheduling and Formation</a>
+ — The last phase assigns a linear order to the instructions in the
+ target-instruction DAG and emits them into the MachineFunction being
+ compiled. This step uses traditional prepass scheduling techniques.</li>
+</ol>
+
+<p>After all of these steps are complete, the SelectionDAG is destroyed and the
+ rest of the code generation passes are run.</p>
+
+<p>One great way to visualize what is going on here is to take advantage of a
+ few LLC command line options. The following options pop up a window
+ displaying the SelectionDAG at specific times (if you only get errors printed
+ to the console while using this, you probably
+ <a href="ProgrammersManual.html#ViewGraph">need to configure your system</a>
+ to add support for it).</p>
+
+<ul>
+ <li><tt>-view-dag-combine1-dags</tt> displays the DAG after being built,
+ before the first optimization pass.</li>
+
+ <li><tt>-view-legalize-dags</tt> displays the DAG before Legalization.</li>
+
+ <li><tt>-view-dag-combine2-dags</tt> displays the DAG before the second
+ optimization pass.</li>
+
+ <li><tt>-view-isel-dags</tt> displays the DAG before the Select phase.</li>
+
+ <li><tt>-view-sched-dags</tt> displays the DAG before Scheduling.</li>
+</ul>
+
+<p>The <tt>-view-sunit-dags</tt> displays the Scheduler's dependency graph.
+ This graph is based on the final SelectionDAG, with nodes that must be
+ scheduled together bundled into a single scheduling-unit node, and with
+ immediate operands and other nodes that aren't relevant for scheduling
+ omitted.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_build">Initial SelectionDAG Construction</a>
+</h4>
+
+<div>
+
+<p>The initial SelectionDAG is naïvely peephole expanded from the LLVM
+ input by the <tt>SelectionDAGLowering</tt> class in the
+ <tt>lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp</tt> file. The intent of
+ this pass is to expose as much low-level, target-specific details to the
+ SelectionDAG as possible. This pass is mostly hard-coded (e.g. an
+ LLVM <tt>add</tt> turns into an <tt>SDNode add</tt> while a
+ <tt>getelementptr</tt> is expanded into the obvious arithmetic). This pass
+ requires target-specific hooks to lower calls, returns, varargs, etc. For
+ these features, the <tt><a href="#targetlowering">TargetLowering</a></tt>
+ interface is used.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_legalize_types">SelectionDAG LegalizeTypes Phase</a>
+</h4>
+
+<div>
+
+<p>The Legalize phase is in charge of converting a DAG to only use the types
+ that are natively supported by the target.</p>
+
+<p>There are two main ways of converting values of unsupported scalar types to
+ values of supported types: converting small types to larger types
+ ("promoting"), and breaking up large integer types into smaller ones
+ ("expanding"). For example, a target might require that all f32 values are
+ promoted to f64 and that all i1/i8/i16 values are promoted to i32. The same
+ target might require that all i64 values be expanded into pairs of i32
+ values. These changes can insert sign and zero extensions as needed to make
+ sure that the final code has the same behavior as the input.</p>
+
+<p>There are two main ways of converting values of unsupported vector types to
+ value of supported types: splitting vector types, multiple times if
+ necessary, until a legal type is found, and extending vector types by adding
+ elements to the end to round them out to legal types ("widening"). If a
+ vector gets split all the way down to single-element parts with no supported
+ vector type being found, the elements are converted to scalars
+ ("scalarizing").</p>
+
+<p>A target implementation tells the legalizer which types are supported (and
+ which register class to use for them) by calling the
+ <tt>addRegisterClass</tt> method in its TargetLowering constructor.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_legalize">SelectionDAG Legalize Phase</a>
+</h4>
+
+<div>
+
+<p>The Legalize phase is in charge of converting a DAG to only use the
+ operations that are natively supported by the target.</p>
+
+<p>Targets often have weird constraints, such as not supporting every operation
+ on every supported datatype (e.g. X86 does not support byte conditional moves
+ and PowerPC does not support sign-extending loads from a 16-bit memory
+ location). Legalize takes care of this by open-coding another sequence of
+ operations to emulate the operation ("expansion"), by promoting one type to a
+ larger type that supports the operation ("promotion"), or by using a
+ target-specific hook to implement the legalization ("custom").</p>
+
+<p>A target implementation tells the legalizer which operations are not
+ supported (and which of the above three actions to take) by calling the
+ <tt>setOperationAction</tt> method in its <tt>TargetLowering</tt>
+ constructor.</p>
+
+<p>Prior to the existence of the Legalize passes, we required that every target
+ <a href="#selectiondag_optimize">selector</a> supported and handled every
+ operator and type even if they are not natively supported. The introduction
+ of the Legalize phases allows all of the canonicalization patterns to be
+ shared across targets, and makes it very easy to optimize the canonicalized
+ code because it is still in the form of a DAG.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_optimize">
+ SelectionDAG Optimization Phase: the DAG Combiner
+ </a>
+</h4>
+
+<div>
+
+<p>The SelectionDAG optimization phase is run multiple times for code
+ generation, immediately after the DAG is built and once after each
+ legalization. The first run of the pass allows the initial code to be
+ cleaned up (e.g. performing optimizations that depend on knowing that the
+ operators have restricted type inputs). Subsequent runs of the pass clean up
+ the messy code generated by the Legalize passes, which allows Legalize to be
+ very simple (it can focus on making code legal instead of focusing on
+ generating <em>good</em> and legal code).</p>
+
+<p>One important class of optimizations performed is optimizing inserted sign
+ and zero extension instructions. We currently use ad-hoc techniques, but
+ could move to more rigorous techniques in the future. Here are some good
+ papers on the subject:</p>
+
+<p>"<a href="http://www.eecs.harvard.edu/~nr/pubs/widen-abstract.html">Widening
+ integer arithmetic</a>"<br>
+ Kevin Redwine and Norman Ramsey<br>
+ International Conference on Compiler Construction (CC) 2004</p>
+
+<p>"<a href="http://portal.acm.org/citation.cfm?doid=512529.512552">Effective
+ sign extension elimination</a>"<br>
+ Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani<br>
+ Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design
+ and Implementation.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_select">SelectionDAG Select Phase</a>
+</h4>
+
+<div>
+
+<p>The Select phase is the bulk of the target-specific code for instruction
+ selection. This phase takes a legal SelectionDAG as input, pattern matches
+ the instructions supported by the target to this DAG, and produces a new DAG
+ of target code. For example, consider the following LLVM fragment:</p>
+
+<div class="doc_code">
+<pre>
+%t1 = fadd float %W, %X
+%t2 = fmul float %t1, %Y
+%t3 = fadd float %t2, %Z
+</pre>
+</div>
+
+<p>This LLVM code corresponds to a SelectionDAG that looks basically like
+ this:</p>
+
+<div class="doc_code">
+<pre>
+(fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
+</pre>
+</div>
+
+<p>If a target supports floating point multiply-and-add (FMA) operations, one of
+ the adds can be merged with the multiply. On the PowerPC, for example, the
+ output of the instruction selector might look like this DAG:</p>
+
+<div class="doc_code">
+<pre>
+(FMADDS (FADDS W, X), Y, Z)
+</pre>
+</div>
+
+<p>The <tt>FMADDS</tt> instruction is a ternary instruction that multiplies its
+first two operands and adds the third (as single-precision floating-point
+numbers). The <tt>FADDS</tt> instruction is a simple binary single-precision
+add instruction. To perform this pattern match, the PowerPC backend includes
+the following instruction definitions:</p>
+
+<div class="doc_code">
+<pre>
+def FMADDS : AForm_1<59, 29,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
+ "fmadds $FRT, $FRA, $FRC, $FRB",
+ [<b>(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
+ F4RC:$FRB))</b>]>;
+def FADDS : AForm_2<59, 21,
+ (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
+ "fadds $FRT, $FRA, $FRB",
+ [<b>(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))</b>]>;
+</pre>
+</div>
+
+<p>The portion of the instruction definition in bold indicates the pattern used
+ to match the instruction. The DAG operators
+ (like <tt>fmul</tt>/<tt>fadd</tt>) are defined in
+ the <tt>include/llvm/Target/TargetSelectionDAG.td</tt> file. "
+ <tt>F4RC</tt>" is the register class of the input and result values.</p>
+
+<p>The TableGen DAG instruction selector generator reads the instruction
+ patterns in the <tt>.td</tt> file and automatically builds parts of the
+ pattern matching code for your target. It has the following strengths:</p>
+
+<ul>
+ <li>At compiler-compiler time, it analyzes your instruction patterns and tells
+ you if your patterns make sense or not.</li>
+
+ <li>It can handle arbitrary constraints on operands for the pattern match. In
+ particular, it is straight-forward to say things like "match any immediate
+ that is a 13-bit sign-extended value". For examples, see the
+ <tt>immSExt16</tt> and related <tt>tblgen</tt> classes in the PowerPC
+ backend.</li>
+
+ <li>It knows several important identities for the patterns defined. For
+ example, it knows that addition is commutative, so it allows the
+ <tt>FMADDS</tt> pattern above to match "<tt>(fadd X, (fmul Y, Z))</tt>" as
+ well as "<tt>(fadd (fmul X, Y), Z)</tt>", without the target author having
+ to specially handle this case.</li>
+
+ <li>It has a full-featured type-inferencing system. In particular, you should
+ rarely have to explicitly tell the system what type parts of your patterns
+ are. In the <tt>FMADDS</tt> case above, we didn't have to tell
+ <tt>tblgen</tt> that all of the nodes in the pattern are of type 'f32'.
+ It was able to infer and propagate this knowledge from the fact that
+ <tt>F4RC</tt> has type 'f32'.</li>
+
+ <li>Targets can define their own (and rely on built-in) "pattern fragments".
+ Pattern fragments are chunks of reusable patterns that get inlined into
+ your patterns during compiler-compiler time. For example, the integer
+ "<tt>(not x)</tt>" operation is actually defined as a pattern fragment
+ that expands as "<tt>(xor x, -1)</tt>", since the SelectionDAG does not
+ have a native '<tt>not</tt>' operation. Targets can define their own
+ short-hand fragments as they see fit. See the definition of
+ '<tt>not</tt>' and '<tt>ineg</tt>' for examples.</li>
+
+ <li>In addition to instructions, targets can specify arbitrary patterns that
+ map to one or more instructions using the 'Pat' class. For example, the
+ PowerPC has no way to load an arbitrary integer immediate into a register
+ in one instruction. To tell tblgen how to do this, it defines:
+ <br>
+ <br>
+<div class="doc_code">
+<pre>
+// Arbitrary immediate support. Implement in terms of LIS/ORI.
+def : Pat<(i32 imm:$imm),
+ (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
+</pre>
+</div>
+ <br>
+ If none of the single-instruction patterns for loading an immediate into a
+ register match, this will be used. This rule says "match an arbitrary i32
+ immediate, turning it into an <tt>ORI</tt> ('or a 16-bit immediate') and
+ an <tt>LIS</tt> ('load 16-bit immediate, where the immediate is shifted to
+ the left 16 bits') instruction". To make this work, the
+ <tt>LO16</tt>/<tt>HI16</tt> node transformations are used to manipulate
+ the input immediate (in this case, take the high or low 16-bits of the
+ immediate).</li>
+
+ <li>While the system does automate a lot, it still allows you to write custom
+ C++ code to match special cases if there is something that is hard to
+ express.</li>
+</ul>
+
+<p>While it has many strengths, the system currently has some limitations,
+ primarily because it is a work in progress and is not yet finished:</p>
+
+<ul>
+ <li>Overall, there is no way to define or match SelectionDAG nodes that define
+ multiple values (e.g. <tt>SMUL_LOHI</tt>, <tt>LOAD</tt>, <tt>CALL</tt>,
+ etc). This is the biggest reason that you currently still <em>have
+ to</em> write custom C++ code for your instruction selector.</li>
+
+ <li>There is no great way to support matching complex addressing modes yet.
+ In the future, we will extend pattern fragments to allow them to define
+ multiple values (e.g. the four operands of the <a href="#x86_memory">X86
+ addressing mode</a>, which are currently matched with custom C++ code).
+ In addition, we'll extend fragments so that a fragment can match multiple
+ different patterns.</li>
+
+ <li>We don't automatically infer flags like isStore/isLoad yet.</li>
+
+ <li>We don't automatically generate the set of supported registers and
+ operations for the <a href="#selectiondag_legalize">Legalizer</a>
+ yet.</li>
+
+ <li>We don't have a way of tying in custom legalized nodes yet.</li>
+</ul>
+
+<p>Despite these limitations, the instruction selector generator is still quite
+ useful for most of the binary and logical operations in typical instruction
+ sets. If you run into any problems or can't figure out how to do something,
+ please let Chris know!</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_sched">SelectionDAG Scheduling and Formation Phase</a>
+</h4>
+
+<div>
+
+<p>The scheduling phase takes the DAG of target instructions from the selection
+ phase and assigns an order. The scheduler can pick an order depending on
+ various constraints of the machines (i.e. order for minimal register pressure
+ or try to cover instruction latencies). Once an order is established, the
+ DAG is converted to a list
+ of <tt><a href="#machineinstr">MachineInstr</a></tt>s and the SelectionDAG is
+ destroyed.</p>
+
+<p>Note that this phase is logically separate from the instruction selection
+ phase, but is tied to it closely in the code because it operates on
+ SelectionDAGs.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="selectiondag_future">Future directions for the SelectionDAG</a>
+</h4>
+
+<div>
+
+<ol>
+ <li>Optional function-at-a-time selection.</li>
+
+ <li>Auto-generate entire selector from <tt>.td</tt> file.</li>
+</ol>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ssamco">SSA-based Machine Code Optimizations</a>
+</h3>
+<div><p>To Be Written</p></div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="liveintervals">Live Intervals</a>
+</h3>
+
+<div>
+
+<p>Live Intervals are the ranges (intervals) where a variable is <i>live</i>.
+ They are used by some <a href="#regalloc">register allocator</a> passes to
+ determine if two or more virtual registers which require the same physical
+ register are live at the same point in the program (i.e., they conflict).
+ When this situation occurs, one virtual register must be <i>spilled</i>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="livevariable_analysis">Live Variable Analysis</a>
+</h4>
+
+<div>
+
+<p>The first step in determining the live intervals of variables is to calculate
+ the set of registers that are immediately dead after the instruction (i.e.,
+ the instruction calculates the value, but it is never used) and the set of
+ registers that are used by the instruction, but are never used after the
+ instruction (i.e., they are killed). Live variable information is computed
+ for each <i>virtual</i> register and <i>register allocatable</i> physical
+ register in the function. This is done in a very efficient manner because it
+ uses SSA to sparsely compute lifetime information for virtual registers
+ (which are in SSA form) and only has to track physical registers within a
+ block. Before register allocation, LLVM can assume that physical registers
+ are only live within a single basic block. This allows it to do a single,
+ local analysis to resolve physical register lifetimes within each basic
+ block. If a physical register is not register allocatable (e.g., a stack
+ pointer or condition codes), it is not tracked.</p>
+
+<p>Physical registers may be live in to or out of a function. Live in values are
+ typically arguments in registers. Live out values are typically return values
+ in registers. Live in values are marked as such, and are given a dummy
+ "defining" instruction during live intervals analysis. If the last basic
+ block of a function is a <tt>return</tt>, then it's marked as using all live
+ out values in the function.</p>
+
+<p><tt>PHI</tt> nodes need to be handled specially, because the calculation of
+ the live variable information from a depth first traversal of the CFG of the
+ function won't guarantee that a virtual register used by the <tt>PHI</tt>
+ node is defined before it's used. When a <tt>PHI</tt> node is encountered,
+ only the definition is handled, because the uses will be handled in other
+ basic blocks.</p>
+
+<p>For each <tt>PHI</tt> node of the current basic block, we simulate an
+ assignment at the end of the current basic block and traverse the successor
+ basic blocks. If a successor basic block has a <tt>PHI</tt> node and one of
+ the <tt>PHI</tt> node's operands is coming from the current basic block, then
+ the variable is marked as <i>alive</i> within the current basic block and all
+ of its predecessor basic blocks, until the basic block with the defining
+ instruction is encountered.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="liveintervals_analysis">Live Intervals Analysis</a>
+</h4>
+
+<div>
+
+<p>We now have the information available to perform the live intervals analysis
+ and build the live intervals themselves. We start off by numbering the basic
+ blocks and machine instructions. We then handle the "live-in" values. These
+ are in physical registers, so the physical register is assumed to be killed
+ by the end of the basic block. Live intervals for virtual registers are
+ computed for some ordering of the machine instructions <tt>[1, N]</tt>. A
+ live interval is an interval <tt>[i, j)</tt>, where <tt>1 <= i <= j
+ < N</tt>, for which a variable is live.</p>
+
+<p><i><b>More to come...</b></i></p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="regalloc">Register Allocation</a>
+</h3>
+
+<div>
+
+<p>The <i>Register Allocation problem</i> consists in mapping a program
+ <i>P<sub>v</sub></i>, that can use an unbounded number of virtual registers,
+ to a program <i>P<sub>p</sub></i> that contains a finite (possibly small)
+ number of physical registers. Each target architecture has a different number
+ of physical registers. If the number of physical registers is not enough to
+ accommodate all the virtual registers, some of them will have to be mapped
+ into memory. These virtuals are called <i>spilled virtuals</i>.</p>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+ <a name="regAlloc_represent">How registers are represented in LLVM</a>
+</h4>
+
+<div>
+
+<p>In LLVM, physical registers are denoted by integer numbers that normally
+ range from 1 to 1023. To see how this numbering is defined for a particular
+ architecture, you can read the <tt>GenRegisterNames.inc</tt> file for that
+ architecture. For instance, by
+ inspecting <tt>lib/Target/X86/X86GenRegisterNames.inc</tt> we see that the
+ 32-bit register <tt>EAX</tt> is denoted by 15, and the MMX register
+ <tt>MM0</tt> is mapped to 48.</p>
+
+<p>Some architectures contain registers that share the same physical location. A
+ notable example is the X86 platform. For instance, in the X86 architecture,
+ the registers <tt>EAX</tt>, <tt>AX</tt> and <tt>AL</tt> share the first eight
+ bits. These physical registers are marked as <i>aliased</i> in LLVM. Given a
+ particular architecture, you can check which registers are aliased by
+ inspecting its <tt>RegisterInfo.td</tt> file. Moreover, the method
+ <tt>TargetRegisterInfo::getAliasSet(p_reg)</tt> returns an array containing
+ all the physical registers aliased to the register <tt>p_reg</tt>.</p>
+
+<p>Physical registers, in LLVM, are grouped in <i>Register Classes</i>.
+ Elements in the same register class are functionally equivalent, and can be
+ interchangeably used. Each virtual register can only be mapped to physical
+ registers of a particular class. For instance, in the X86 architecture, some
+ virtuals can only be allocated to 8 bit registers. A register class is
+ described by <tt>TargetRegisterClass</tt> objects. To discover if a virtual
+ register is compatible with a given physical, this code can be used:</p>
+
+<div class="doc_code">
+<pre>
+bool RegMapping_Fer::compatible_class(MachineFunction &mf,
+ unsigned v_reg,
+ unsigned p_reg) {
+ assert(TargetRegisterInfo::isPhysicalRegister(p_reg) &&
+ "Target register must be physical");
+ const TargetRegisterClass *trc = mf.getRegInfo().getRegClass(v_reg);
+ return trc->contains(p_reg);
+}
+</pre>
+</div>
+
+<p>Sometimes, mostly for debugging purposes, it is useful to change the number
+ of physical registers available in the target architecture. This must be done
+ statically, inside the <tt>TargetRegsterInfo.td</tt> file. Just <tt>grep</tt>
+ for <tt>RegisterClass</tt>, the last parameter of which is a list of
+ registers. Just commenting some out is one simple way to avoid them being
+ used. A more polite way is to explicitly exclude some registers from
+ the <i>allocation order</i>. See the definition of the <tt>GR8</tt> register
+ class in <tt>lib/Target/X86/X86RegisterInfo.td</tt> for an example of this.
+ </p>
+
+<p>Virtual registers are also denoted by integer numbers. Contrary to physical
+ 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 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
+ a given machine operand is a register, use the boolean
+ function <tt>MachineOperand::isRegister()</tt>. To obtain the integer code of
+ a register, use <tt>MachineOperand::getReg()</tt>. An instruction may define
+ or use a register. For instance, <tt>ADD reg:1026 := reg:1025 reg:1024</tt>
+ defines the registers 1024, and uses registers 1025 and 1026. Given a
+ register operand, the method <tt>MachineOperand::isUse()</tt> informs if that
+ register is being used by the instruction. The
+ method <tt>MachineOperand::isDef()</tt> informs if that registers is being
+ defined.</p>
+
+<p>We will call physical registers present in the LLVM bitcode before register
+ allocation <i>pre-colored registers</i>. Pre-colored registers are used in
+ many different situations, for instance, to pass parameters of functions
+ calls, and to store results of particular instructions. There are two types
+ of pre-colored registers: the ones <i>implicitly</i> defined, and
+ those <i>explicitly</i> defined. Explicitly defined registers are normal
+ operands, and can be accessed
+ with <tt>MachineInstr::getOperand(int)::getReg()</tt>. In order to check
+ which registers are implicitly defined by an instruction, use
+ the <tt>TargetInstrInfo::get(opcode)::ImplicitDefs</tt>,
+ where <tt>opcode</tt> is the opcode of the target instruction. One important
+ difference between explicit and implicit physical registers is that the
+ latter are defined statically for each instruction, whereas the former may
+ vary depending on the program being compiled. For example, an instruction
+ that represents a function call will always implicitly define or use the same
+ set of physical registers. To read the registers implicitly used by an
+ instruction,
+ use <tt>TargetInstrInfo::get(opcode)::ImplicitUses</tt>. Pre-colored
+ registers impose constraints on any register allocation algorithm. The
+ register allocator must make sure that none of them are overwritten by
+ the values of virtual registers while still alive.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+ <a name="regAlloc_howTo">Mapping virtual registers to physical registers</a>
+</h4>
+
+<div>
+
+<p>There are two ways to map virtual registers to physical registers (or to
+ memory slots). The first way, that we will call <i>direct mapping</i>, is
+ based on the use of methods of the classes <tt>TargetRegisterInfo</tt>,
+ and <tt>MachineOperand</tt>. The second way, that we will call <i>indirect
+ mapping</i>, relies on the <tt>VirtRegMap</tt> class in order to insert loads
+ and stores sending and getting values to and from memory.</p>
+
+<p>The direct mapping provides more flexibility to the developer of the register
+ allocator; however, it is more error prone, and demands more implementation
+ work. Basically, the programmer will have to specify where load and store
+ instructions should be inserted in the target function being compiled in
+ order to get and store values in memory. To assign a physical register to a
+ virtual register present in a given operand,
+ use <tt>MachineOperand::setReg(p_reg)</tt>. To insert a store instruction,
+ use <tt>TargetInstrInfo::storeRegToStackSlot(...)</tt>, and to insert a
+ load instruction, use <tt>TargetInstrInfo::loadRegFromStackSlot</tt>.</p>
+
+<p>The indirect mapping shields the application developer from the complexities
+ of inserting load and store instructions. In order to map a virtual register
+ to a physical one, use <tt>VirtRegMap::assignVirt2Phys(vreg, preg)</tt>. In
+ order to map a certain virtual register to memory,
+ use <tt>VirtRegMap::assignVirt2StackSlot(vreg)</tt>. This method will return
+ the stack slot where <tt>vreg</tt>'s value will be located. If it is
+ necessary to map another virtual register to the same stack slot,
+ use <tt>VirtRegMap::assignVirt2StackSlot(vreg, stack_location)</tt>. One
+ important point to consider when using the indirect mapping, is that even if
+ a virtual register is mapped to memory, it still needs to be mapped to a
+ physical register. This physical register is the location where the virtual
+ register is supposed to be found before being stored or after being
+ reloaded.</p>
+
+<p>If the indirect strategy is used, after all the virtual registers have been
+ mapped to physical registers or stack slots, it is necessary to use a spiller
+ object to place load and store instructions in the code. Every virtual that
+ has been mapped to a stack slot will be stored to memory after been defined
+ and will be loaded before being used. The implementation of the spiller tries
+ to recycle load/store instructions, avoiding unnecessary instructions. For an
+ example of how to invoke the spiller,
+ see <tt>RegAllocLinearScan::runOnMachineFunction</tt>
+ in <tt>lib/CodeGen/RegAllocLinearScan.cpp</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="regAlloc_twoAddr">Handling two address instructions</a>
+</h4>
+
+<div>
+
+<p>With very rare exceptions (e.g., function calls), the LLVM machine code
+ instructions are three address instructions. That is, each instruction is
+ expected to define at most one register, and to use at most two registers.
+ However, some architectures use two address instructions. In this case, the
+ defined register is also one of the used register. For instance, an
+ instruction such as <tt>ADD %EAX, %EBX</tt>, in X86 is actually equivalent
+ to <tt>%EAX = %EAX + %EBX</tt>.</p>
+
+<p>In order to produce correct code, LLVM must convert three address
+ instructions that represent two address instructions into true two address
+ instructions. LLVM provides the pass <tt>TwoAddressInstructionPass</tt> for
+ this specific purpose. It must be run before register allocation takes
+ place. After its execution, the resulting code may no longer be in SSA
+ form. This happens, for instance, in situations where an instruction such
+ as <tt>%a = ADD %b %c</tt> is converted to two instructions such as:</p>
+
+<div class="doc_code">
+<pre>
+%a = MOVE %b
+%a = ADD %a %c
+</pre>
+</div>
+
+<p>Notice that, internally, the second instruction is represented as
+ <tt>ADD %a[def/use] %c</tt>. I.e., the register operand <tt>%a</tt> is both
+ used and defined by the instruction.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="regAlloc_ssaDecon">The SSA deconstruction phase</a>
+</h4>
+
+<div>
+
+<p>An important transformation that happens during register allocation is called
+ the <i>SSA Deconstruction Phase</i>. The SSA form simplifies many analyses
+ that are performed on the control flow graph of programs. However,
+ traditional instruction sets do not implement PHI instructions. Thus, in
+ order to generate executable code, compilers must replace PHI instructions
+ with other instructions that preserve their semantics.</p>
+
+<p>There are many ways in which PHI instructions can safely be removed from the
+ target code. The most traditional PHI deconstruction algorithm replaces PHI
+ instructions with copy instructions. That is the strategy adopted by
+ LLVM. The SSA deconstruction algorithm is implemented
+ in <tt>lib/CodeGen/PHIElimination.cpp</tt>. In order to invoke this pass, the
+ identifier <tt>PHIEliminationID</tt> must be marked as required in the code
+ of the register allocator.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="regAlloc_fold">Instruction folding</a>
+</h4>
+
+<div>
+
+<p><i>Instruction folding</i> is an optimization performed during register
+ allocation that removes unnecessary copy instructions. For instance, a
+ sequence of instructions such as:</p>
+
+<div class="doc_code">
+<pre>
+%EBX = LOAD %mem_address
+%EAX = COPY %EBX
+</pre>
+</div>
+
+<p>can be safely substituted by the single instruction:</p>
+
+<div class="doc_code">
+<pre>
+%EAX = LOAD %mem_address
+</pre>
+</div>
+
+<p>Instructions can be folded with
+ the <tt>TargetRegisterInfo::foldMemoryOperand(...)</tt> method. Care must be
+ taken when folding instructions; a folded instruction can be quite different
+ from the original
+ instruction. See <tt>LiveIntervals::addIntervalsForSpills</tt>
+ in <tt>lib/CodeGen/LiveIntervalAnalysis.cpp</tt> for an example of its
+ use.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+ <a name="regAlloc_builtIn">Built in register allocators</a>
+</h4>
+
+<div>
+
+<p>The LLVM infrastructure provides the application developer with three
+ different register allocators:</p>
+
+<ul>
+ <li><i>Fast</i> — This register allocator is the default for debug
+ builds. It allocates registers on a basic block level, attempting to keep
+ values in registers and reusing registers as appropriate.</li>
+
+ <li><i>Basic</i> — This is an incremental approach to register
+ allocation. Live ranges are assigned to registers one at a time in
+ an order that is driven by heuristics. Since code can be rewritten
+ on-the-fly during allocation, this framework allows interesting
+ allocators to be developed as extensions. It is not itself a
+ production register allocator but is a potentially useful
+ stand-alone mode for triaging bugs and as a performance baseline.
+
+ <li><i>Greedy</i> — <i>The default allocator</i>. This is a
+ highly tuned implementation of the <i>Basic</i> allocator that
+ incorporates global live range splitting. This allocator works hard
+ to minimize the cost of spill code.
+
+ <li><i>PBQP</i> — A Partitioned Boolean Quadratic Programming (PBQP)
+ based register allocator. This allocator works by constructing a PBQP
+ problem representing the register allocation problem under consideration,
+ solving this using a PBQP solver, and mapping the solution back to a
+ register assignment.</li>
+</ul>
+
+<p>The type of register allocator used in <tt>llc</tt> can be chosen with the
+ command line option <tt>-regalloc=...</tt>:</p>
+
+<div class="doc_code">
+<pre>
+$ llc -regalloc=linearscan file.bc -o ln.s;
+$ llc -regalloc=fast file.bc -o fa.s;
+$ llc -regalloc=pbqp file.bc -o pbqp.s;
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="proepicode">Prolog/Epilog Code Insertion</a>
+</h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="compact_unwind">Compact Unwind</a>
+</h4>
+
+<div>
+
+<p>Throwing an exception requires <em>unwinding</em> out of a function. The
+ information on how to unwind a given function is traditionally expressed in
+ DWARF unwind (a.k.a. frame) info. But that format was originally developed
+ for debuggers to backtrace, and each Frame Description Entry (FDE) requires
+ ~20-30 bytes per function. There is also the cost of mapping from an address
+ in a function to the corresponding FDE at runtime. An alternative unwind
+ encoding is called <em>compact unwind</em> and requires just 4-bytes per
+ function.</p>
+
+<p>The compact unwind encoding is a 32-bit value, which is encoded in an
+ architecture-specific way. It specifies which registers to restore and from
+ where, and how to unwind out of the function. When the linker creates a final
+ linked image, it will create a <code>__TEXT,__unwind_info</code>
+ section. This section is a small and fast way for the runtime to access
+ unwind info for any given function. If we emit compact unwind info for the
+ function, that compact unwind info will be encoded in
+ the <code>__TEXT,__unwind_info</code> section. If we emit DWARF unwind info,
+ the <code>__TEXT,__unwind_info</code> section will contain the offset of the
+ FDE in the <code>__TEXT,__eh_frame</code> section in the final linked
+ image.</p>
+
+<p>For X86, there are three modes for the compact unwind encoding:</p>
+
+<dl>
+ <dt><i>Function with a Frame Pointer (<code>EBP</code> or <code>RBP</code>)</i></dt>
+ <dd><p><code>EBP/RBP</code>-based frame, where <code>EBP/RBP</code> is pushed
+ onto the stack immediately after the return address,
+ then <code>ESP/RSP</code> is moved to <code>EBP/RBP</code>. Thus to
+ unwind, <code>ESP/RSP</code> is restored with the
+ current <code>EBP/RBP</code> value, then <code>EBP/RBP</code> is restored
+ by popping the stack, and the return is done by popping the stack once
+ more into the PC. All non-volatile registers that need to be restored must
+ have been saved in a small range on the stack that
+ starts <code>EBP-4</code> to <code>EBP-1020</code> (<code>RBP-8</code>
+ to <code>RBP-1020</code>). The offset (divided by 4 in 32-bit mode and 8
+ in 64-bit mode) is encoded in bits 16-23 (mask: <code>0x00FF0000</code>).
+ The registers saved are encoded in bits 0-14
+ (mask: <code>0x00007FFF</code>) as five 3-bit entries from the following
+ table:</p>
+<table border="1" cellspacing="0">
+ <tr>
+ <th>Compact Number</th>
+ <th>i386 Register</th>
+ <th>x86-64 Regiser</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td><code>EBX</code></td>
+ <td><code>RBX</code></td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><code>ECX</code></td>
+ <td><code>R12</code></td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td><code>EDX</code></td>
+ <td><code>R13</code></td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td><code>EDI</code></td>
+ <td><code>R14</code></td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td><code>ESI</code></td>
+ <td><code>R15</code></td>
+ </tr>
+ <tr>
+ <td>6</td>
+ <td><code>EBP</code></td>
+ <td><code>RBP</code></td>
+ </tr>
+</table>
+
+</dd>
+
+ <dt><i>Frameless with a Small Constant Stack Size (<code>EBP</code>
+ or <code>RBP</code> is not used as a frame pointer)</i></dt>
+ <dd><p>To return, a constant (encoded in the compact unwind encoding) is added
+ to the <code>ESP/RSP</code>. Then the return is done by popping the stack
+ into the PC. All non-volatile registers that need to be restored must have
+ been saved on the stack immediately after the return address. The stack
+ size (divided by 4 in 32-bit mode and 8 in 64-bit mode) is encoded in bits
+ 16-23 (mask: <code>0x00FF0000</code>). There is a maximum stack size of
+ 1024 bytes in 32-bit mode and 2048 in 64-bit mode. The number of registers
+ saved is encoded in bits 9-12 (mask: <code>0x00001C00</code>). Bits 0-9
+ (mask: <code>0x000003FF</code>) contain which registers were saved and
+ their order. (See
+ the <code>encodeCompactUnwindRegistersWithoutFrame()</code> function
+ in <code>lib/Target/X86FrameLowering.cpp</code> for the encoding
+ algorithm.)</p></dd>
+
+ <dt><i>Frameless with a Large Constant Stack Size (<code>EBP</code>
+ or <code>RBP</code> is not used as a frame pointer)</i></dt>
+ <dd><p>This case is like the "Frameless with a Small Constant Stack Size"
+ case, but the stack size is too large to encode in the compact unwind
+ encoding. Instead it requires that the function contains "<code>subl
+ $nnnnnn, %esp</code>" in its prolog. The compact encoding contains the
+ offset to the <code>$nnnnnn</code> value in the function in bits 9-12
+ (mask: <code>0x00001C00</code>).</p></dd>
+</dl>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="latemco">Late Machine Code Optimizations</a>
+</h3>
+<div><p>To Be Written</p></div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="codeemit">Code Emission</a>
+</h3>
+
+<div>
+
+<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>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="nativeassembler">Implementing a Native Assembler</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3 id="na_instparsing">Instruction Parsing</h3>
+
+<div><p>To Be Written</p></div>
+
+
+<!-- ======================================================================= -->
+<h3 id="na_instaliases">
+ Instruction Alias Processing
+</h3>
+
+<div>
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>Mnemonic Aliases</h4>
+
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>Instruction Aliases</h4>
+
+<div>
+
+<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>
+
+<p>If the back-end supports it, the instruction printer can automatically emit
+ the alias rather than what's being aliased. It typically leads to better,
+ more readable code. If it's better to print out what's being aliased, then
+ pass a '0' as the third parameter to the InstAlias definition.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3 id="na_matching">Instruction Matching</h3>
+
+<div><p>To Be Written</p></div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="targetimpls">Target-specific Implementation Notes</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section of the document explains features or design decisions that are
+ 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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="targetfeatures">Target Feature Matrix</a>
+</h3>
+
+<div>
+
+<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"></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>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_reliable">Is Generally Reliable</h4>
+
+<div>
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_asmparser">Assembly Parser</h4>
+
+<div>
+<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>
+
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_disassembler">Disassembler</h4>
+
+<div>
+<p>This box indicates whether the target supports the MCDisassembler API for
+disassembling machine opcode bytes into MCInst's.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_inlineasm">Inline Asm</h4>
+
+<div>
+<p>This box indicates whether the target supports most popular inline assembly
+constraints and modifiers.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_jit">JIT Support</h4>
+
+<div>
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_objectwrite">.o File Writing</h4>
+
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4 id="feat_tailcall">Tail Calls</h4>
+
+<div>
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="tailcallopt">Tail call optimization</a>
+</h3>
+
+<div>
+
+<p>Tail call optimization, callee reusing the stack of the caller, is currently
+ supported on x86/x86-64 and PowerPC. It is performed if:</p>
+
+<ul>
+ <li>Caller and callee have the calling convention <tt>fastcc</tt> or
+ <tt>cc 10</tt> (GHC call convention).</li>
+
+ <li>The call is a tail call - in tail position (ret immediately follows call
+ and ret uses value of call or is void).</li>
+
+ <li>Option <tt>-tailcallopt</tt> is enabled.</li>
+
+ <li>Platform specific constraints are met.</li>
+</ul>
+
+<p>x86/x86-64 constraints:</p>
+
+<ul>
+ <li>No variable argument lists are used.</li>
+
+ <li>On x86-64 when generating GOT/PIC code only module-local calls (visibility
+ = hidden or protected) are supported.</li>
+</ul>
+
+<p>PowerPC constraints:</p>
+
+<ul>
+ <li>No variable argument lists are used.</li>
+
+ <li>No byval parameters are used.</li>
+
+ <li>On ppc32/64 GOT/PIC only module-local calls (visibility = hidden or protected) are supported.</li>
+</ul>
+
+<p>Example:</p>
+
+<p>Call as <tt>llc -tailcallopt test.ll</tt>.</p>
+
+<div class="doc_code">
+<pre>
+declare fastcc i32 @tailcallee(i32 inreg %a1, i32 inreg %a2, i32 %a3, i32 %a4)
+
+define fastcc i32 @tailcaller(i32 %in1, i32 %in2) {
+ %l1 = add i32 %in1, %in2
+ %tmp = tail call fastcc i32 @tailcallee(i32 %in1 inreg, i32 %in2 inreg, i32 %in1, i32 %l1)
+ ret i32 %tmp
+}
+</pre>
+</div>
+
+<p>Implications of <tt>-tailcallopt</tt>:</p>
+
+<p>To support tail call optimization in situations where the callee has more
+ arguments than the caller a 'callee pops arguments' convention is used. This
+ currently causes each <tt>fastcc</tt> call that is not tail call optimized
+ (because one or more of above constraints are not met) to be followed by a
+ readjustment of the stack. So performance might be worse in such cases.</p>
+
+</div>
+<!-- ======================================================================= -->
+<h3>
+ <a name="sibcallopt">Sibling call optimization</a>
+</h3>
+
+<div>
+
+<p>Sibling call optimization is a restricted form of tail call optimization.
+ Unlike tail call optimization described in the previous section, it can be
+ performed automatically on any tail calls when <tt>-tailcallopt</tt> option
+ is not specified.</p>
+
+<p>Sibling call optimization is currently performed on x86/x86-64 when the
+ following constraints are met:</p>
+
+<ul>
+ <li>Caller and callee have the same calling convention. It can be either
+ <tt>c</tt> or <tt>fastcc</tt>.
+
+ <li>The call is a tail call - in tail position (ret immediately follows call
+ and ret uses value of call or is void).</li>
+
+ <li>Caller and callee have matching return type or the callee result is not
+ used.
+
+ <li>If any of the callee arguments are being passed in stack, they must be
+ available in caller's own incoming argument stack and the frame offsets
+ must be the same.
+</ul>
+
+<p>Example:</p>
+<div class="doc_code">
+<pre>
+declare i32 @bar(i32, i32)
+
+define i32 @foo(i32 %a, i32 %b, i32 %c) {
+entry:
+ %0 = tail call i32 @bar(i32 %a, i32 %b)
+ ret i32 %0
+}
+</pre>
+</div>
+
+</div>
+<!-- ======================================================================= -->
+<h3>
+ <a name="x86">The X86 backend</a>
+</h3>
+
+<div>
+
+<p>The X86 code generator lives in the <tt>lib/Target/X86</tt> directory. This
+ code generator is capable of targeting a variety of x86-32 and x86-64
+ processors, and includes support for ISA extensions such as MMX and SSE.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="x86_tt">X86 Target Triples supported</a>
+</h4>
+
+<div>
+
+<p>The following are the known target triples that are supported by the X86
+ backend. This is not an exhaustive list, and it would be useful to add those
+ that people test.</p>
+
+<ul>
+ <li><b>i686-pc-linux-gnu</b> — Linux</li>
+
+ <li><b>i386-unknown-freebsd5.3</b> — FreeBSD 5.3</li>
+
+ <li><b>i686-pc-cygwin</b> — Cygwin on Win32</li>
+
+ <li><b>i686-pc-mingw32</b> — MingW on Win32</li>
+
+ <li><b>i386-pc-mingw32msvc</b> — MingW crosscompiler on Linux</li>
+
+ <li><b>i686-apple-darwin*</b> — Apple Darwin on X86</li>
+
+ <li><b>x86_64-unknown-linux-gnu</b> — Linux</li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="x86_cc">X86 Calling Conventions supported</a>
+</h4>
+
+
+<div>
+
+<p>The following target-specific calling conventions are known to backend:</p>
+
+<ul>
+<li><b>x86_StdCall</b> — stdcall calling convention seen on Microsoft
+ Windows platform (CC ID = 64).</li>
+<li><b>x86_FastCall</b> — fastcall calling convention seen on Microsoft
+ Windows platform (CC ID = 65).</li>
+<li><b>x86_ThisCall</b> — Similar to X86_StdCall. Passes first argument
+ in ECX, others via stack. Callee is responsible for stack cleaning. This
+ convention is used by MSVC by default for methods in its ABI
+ (CC ID = 70).</li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="x86_memory">Representing X86 addressing modes in MachineInstrs</a>
+</h4>
+
+<div>
+
+<p>The x86 has a very flexible way of accessing memory. It is capable of
+ forming memory addresses of the following expression directly in integer
+ instructions (which use ModR/M addressing):</p>
+
+<div class="doc_code">
+<pre>
+SegmentReg: Base + [1,2,4,8] * IndexReg + Disp32
+</pre>
+</div>
+
+<p>In order to represent this, LLVM tracks no less than 5 operands for each
+ memory operand of this form. This means that the "load" form of
+ '<tt>mov</tt>' has the following <tt>MachineOperand</tt>s in this order:</p>
+
+<div class="doc_code">
+<pre>
+Index: 0 | 1 2 3 4 5
+Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement Segment
+OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm PhysReg
+</pre>
+</div>
+
+<p>Stores, and all other instructions, treat the four memory operands in the
+ same way and in the same order. If the segment register is unspecified
+ (regno = 0), then no segment override is generated. "Lea" operations do not
+ have a segment register specified, so they only have 4 operands for their
+ memory reference.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="x86_memory">X86 address spaces supported</a>
+</h4>
+
+<div>
+
+<p>x86 has a feature which provides
+ the ability to perform loads and stores to different address spaces
+ via the x86 segment registers. A segment override prefix byte on an
+ instruction causes the instruction's memory access to go to the specified
+ segment. LLVM address space 0 is the default address space, which includes
+ the stack, and any unqualified memory accesses in a program. Address spaces
+ 1-255 are currently reserved for user-defined code. The GS-segment is
+ represented by address space 256, while the FS-segment is represented by
+ address space 257. Other x86 segments have yet to be allocated address space
+ numbers.</p>
+
+<p>While these address spaces may seem similar to TLS via the
+ <tt>thread_local</tt> keyword, and often use the same underlying hardware,
+ there are some fundamental differences.</p>
+
+<p>The <tt>thread_local</tt> keyword applies to global variables and
+ specifies that they are to be allocated in thread-local memory. There are
+ no type qualifiers involved, and these variables can be pointed to with
+ normal pointers and accessed with normal loads and stores.
+ The <tt>thread_local</tt> keyword is target-independent at the LLVM IR
+ level (though LLVM doesn't yet have implementations of it for some
+ configurations).<p>
+
+<p>Special address spaces, in contrast, apply to static types. Every
+ load and store has a particular address space in its address operand type,
+ and this is what determines which address space is accessed.
+ LLVM ignores these special address space qualifiers on global variables,
+ and does not provide a way to directly allocate storage in them.
+ At the LLVM IR level, the behavior of these special address spaces depends
+ in part on the underlying OS or runtime environment, and they are specific
+ to x86 (and LLVM doesn't yet handle them correctly in some cases).</p>
+
+<p>Some operating systems and runtime environments use (or may in the future
+ use) the FS/GS-segment registers for various low-level purposes, so care
+ should be taken when considering them.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="x86_names">Instruction naming</a>
+</h4>
+
+<div>
+
+<p>An instruction name consists of the base name, a default operand size, and a
+ a character per operand with an optional special size. For example:</p>
+
+<div class="doc_code">
+<pre>
+ADD8rr -> add, 8-bit register, 8-bit register
+IMUL16rmi -> imul, 16-bit register, 16-bit memory, 16-bit immediate
+IMUL16rmi8 -> imul, 16-bit register, 16-bit memory, 8-bit immediate
+MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ppc">The PowerPC backend</a>
+</h3>
+
+<div>
+
+<p>The PowerPC code generator lives in the lib/Target/PowerPC directory. The
+ code generation is retargetable to several variations or <i>subtargets</i> of
+ the PowerPC ISA; including ppc32, ppc64 and altivec.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ppc_abi">LLVM PowerPC ABI</a>
+</h4>
+
+<div>
+
+<p>LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC
+ relative (PIC) or static addressing for accessing global values, so no TOC
+ (r2) is used. Second, r31 is used as a frame pointer to allow dynamic growth
+ of a stack frame. LLVM takes advantage of having no TOC to provide space to
+ save the frame pointer in the PowerPC linkage area of the caller frame.
+ Other details of PowerPC ABI can be found at <a href=
+ "http://developer.apple.com/documentation/DeveloperTools/Conceptual/LowLevelABI/Articles/32bitPowerPC.html"
+ >PowerPC ABI.</a> Note: This link describes the 32 bit ABI. The 64 bit ABI
+ is similar except space for GPRs are 8 bytes wide (not 4) and r13 is reserved
+ for system use.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ppc_frame">Frame Layout</a>
+</h4>
+
+<div>
+
+<p>The size of a PowerPC frame is usually fixed for the duration of a
+ function's invocation. Since the frame is fixed size, all references
+ into the frame can be accessed via fixed offsets from the stack pointer. The
+ exception to this is when dynamic alloca or variable sized arrays are
+ present, then a base pointer (r31) is used as a proxy for the stack pointer
+ and stack pointer is free to grow or shrink. A base pointer is also used if
+ llvm-gcc is not passed the -fomit-frame-pointer flag. The stack pointer is
+ always aligned to 16 bytes, so that space allocated for altivec vectors will
+ be properly aligned.</p>
+
+<p>An invocation frame is laid out as follows (low memory at top);</p>
+
+<table class="layout">
+ <tr>
+ <td>Linkage<br><br></td>
+ </tr>
+ <tr>
+ <td>Parameter area<br><br></td>
+ </tr>
+ <tr>
+ <td>Dynamic area<br><br></td>
+ </tr>
+ <tr>
+ <td>Locals area<br><br></td>
+ </tr>
+ <tr>
+ <td>Saved registers area<br><br></td>
+ </tr>
+ <tr style="border-style: none hidden none hidden;">
+ <td><br></td>
+ </tr>
+ <tr>
+ <td>Previous Frame<br><br></td>
+ </tr>
+</table>
+
+<p>The <i>linkage</i> area is used by a callee to save special registers prior
+ to allocating its own frame. Only three entries are relevant to LLVM. The
+ first entry is the previous stack pointer (sp), aka link. This allows
+ probing tools like gdb or exception handlers to quickly scan the frames in
+ the stack. A function epilog can also use the link to pop the frame from the
+ stack. The third entry in the linkage area is used to save the return
+ address from the lr register. Finally, as mentioned above, the last entry is
+ used to save the previous frame pointer (r31.) The entries in the linkage
+ area are the size of a GPR, thus the linkage area is 24 bytes long in 32 bit
+ mode and 48 bytes in 64 bit mode.</p>
+
+<p>32 bit linkage area</p>
+
+<table class="layout">
+ <tr>
+ <td>0</td>
+ <td>Saved SP (r1)</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td>Saved CR</td>
+ </tr>
+ <tr>
+ <td>8</td>
+ <td>Saved LR</td>
+ </tr>
+ <tr>
+ <td>12</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>16</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>20</td>
+ <td>Saved FP (r31)</td>
+ </tr>
+</table>
+
+<p>64 bit linkage area</p>
+
+<table class="layout">
+ <tr>
+ <td>0</td>
+ <td>Saved SP (r1)</td>
+ </tr>
+ <tr>
+ <td>8</td>
+ <td>Saved CR</td>
+ </tr>
+ <tr>
+ <td>16</td>
+ <td>Saved LR</td>
+ </tr>
+ <tr>
+ <td>24</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>32</td>
+ <td>Reserved</td>
+ </tr>
+ <tr>
+ <td>40</td>
+ <td>Saved FP (r31)</td>
+ </tr>
+</table>
+
+<p>The <i>parameter area</i> is used to store arguments being passed to a callee
+ function. Following the PowerPC ABI, the first few arguments are actually
+ passed in registers, with the space in the parameter area unused. However,
+ if there are not enough registers or the callee is a thunk or vararg
+ function, these register arguments can be spilled into the parameter area.
+ Thus, the parameter area must be large enough to store all the parameters for
+ the largest call sequence made by the caller. The size must also be
+ minimally large enough to spill registers r3-r10. This allows callees blind
+ to the call signature, such as thunks and vararg functions, enough space to
+ cache the argument registers. Therefore, the parameter area is minimally 32
+ bytes (64 bytes in 64 bit mode.) Also note that since the parameter area is
+ a fixed offset from the top of the frame, that a callee can access its spilt
+ arguments using fixed offsets from the stack pointer (or base pointer.)</p>
+
+<p>Combining the information about the linkage, parameter areas and alignment. A
+ stack frame is minimally 64 bytes in 32 bit mode and 128 bytes in 64 bit
+ mode.</p>
+
+<p>The <i>dynamic area</i> starts out as size zero. If a function uses dynamic
+ alloca then space is added to the stack, the linkage and parameter areas are
+ shifted to top of stack, and the new space is available immediately below the
+ linkage and parameter areas. The cost of shifting the linkage and parameter
+ areas is minor since only the link value needs to be copied. The link value
+ can be easily fetched by adding the original frame size to the base pointer.
+ Note that allocations in the dynamic space need to observe 16 byte
+ alignment.</p>
+
+<p>The <i>locals area</i> is where the llvm compiler reserves space for local
+ variables.</p>
+
+<p>The <i>saved registers area</i> is where the llvm compiler spills callee
+ saved registers on entry to the callee.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ppc_prolog">Prolog/Epilog</a>
+</h4>
+
+<div>
+
+<p>The llvm prolog and epilog are the same as described in the PowerPC ABI, with
+ the following exceptions. Callee saved registers are spilled after the frame
+ is created. This allows the llvm epilog/prolog support to be common with
+ other targets. The base pointer callee saved register r31 is saved in the
+ TOC slot of linkage area. This simplifies allocation of space for the base
+ pointer and makes it convenient to locate programatically and during
+ debugging.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ppc_dynamic">Dynamic Allocation</a>
+</h4>
+
+<div>
+
+<p><i>TODO - More to come.</i></p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="ptx">The PTX backend</a>
+</h3>
+
+<div>
+
+<p>The PTX code generator lives in the lib/Target/PTX directory. It is
+ currently a work-in-progress, but already supports most of the code
+ generation functionality needed to generate correct PTX kernels for
+ CUDA devices.</p>
+
+<p>The code generator can target PTX 2.0+, and shader model 1.0+. The
+ PTX ISA Reference Manual is used as the primary source of ISA
+ information, though an effort is made to make the output of the code
+ generator match the output of the NVidia nvcc compiler, whenever
+ possible.</p>
+
+<p>Code Generator Options:</p>
+<table border="1" cellspacing="0">
+ <tr>
+ <th>Option</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>double</code></td>
+ <td align="left">If enabled, the map_f64_to_f32 directive is
+ disabled in the PTX output, allowing native double-precision
+ arithmetic</td>
+ </tr>
+ <tr>
+ <td><code>no-fma</code></td>
+ <td align="left">Disable generation of Fused-Multiply Add
+ instructions, which may be beneficial for some devices</td>
+ </tr>
+ <tr>
+ <td><code>smxy / computexy</code></td>
+ <td align="left">Set shader model/compute capability to x.y,
+ e.g. sm20 or compute13</td>
+ </tr>
+</table>
+
+<p>Working:</p>
+<ul>
+ <li>Arithmetic instruction selection (including combo FMA)</li>
+ <li>Bitwise instruction selection</li>
+ <li>Control-flow instruction selection</li>
+ <li>Function calls (only on SM 2.0+ and no return arguments)</li>
+ <li>Addresses spaces (0 = global, 1 = constant, 2 = local, 4 =
+ shared)</li>
+ <li>Thread synchronization (bar.sync)</li>
+ <li>Special register reads ([N]TID, [N]CTAID, PMx, CLOCK, etc.)</li>
+</ul>
+
+<p>In Progress:</p>
+<ul>
+ <li>Robust call instruction selection</li>
+ <li>Stack frame allocation</li>
+ <li>Device-specific instruction scheduling optimizations</li>
+</ul>
+
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:54 -0500 (Thu, 03 Nov 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CodingStandards.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CodingStandards.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CodingStandards.html (added)
+++ www-releases/trunk/3.0/docs/CodingStandards.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1534 @@
+<!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">
+ <title>LLVM Coding Standards</title>
+</head>
+<body>
+
+<h1>
+ LLVM Coding Standards
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#mechanicalissues">Mechanical Source Issues</a>
+ <ol>
+ <li><a href="#sourceformating">Source Code Formatting</a>
+ <ol>
+ <li><a href="#scf_commenting">Commenting</a></li>
+ <li><a href="#scf_commentformat">Comment Formatting</a></li>
+ <li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
+ <li><a href="#scf_codewidth">Source Code Width</a></li>
+ <li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li>
+ <li><a href="#scf_indentation">Indent Code Consistently</a></li>
+ </ol></li>
+ <li><a href="#compilerissues">Compiler Issues</a>
+ <ol>
+ <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_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>
+ <ol>
+ <li><a href="#hl_module">A Public Header File <b>is</b> a
+ Module</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 <tt>continue</tt> to Simplify
+ Code</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>
+ <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 '<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 <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>
+ </ol></li>
+
+ <li><a href="#nano">Microscopic Details</a>
+ <ol>
+ <li><a href="#micro_spaceparen">Spaces Before Parentheses</a></li>
+ <li><a href="#micro_preincrement">Prefer Preincrement</a></li>
+ <li><a href="#micro_namespaceindent">Namespace Indentation</a></li>
+ <li><a href="#micro_anonns">Anonymous Namespaces</a></li>
+ </ol></li>
+
+
+ </ol></li>
+ <li><a href="#seealso">See Also</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document attempts to describe a few coding standards that are being used
+in the LLVM source tree. Although no coding standards should be regarded as
+absolute requirements to be followed in all instances, coding standards can be
+useful.</p>
+
+<p>This document intentionally does not prescribe fixed standards for religious
+issues such as brace placement and space usage. For issues like this, follow
+the golden rule:</p>
+
+<blockquote>
+
+<p><b><a name="goldenrule">If you are adding a significant body of source to a
+project, feel free to use whatever style you are most comfortable with. If you
+are extending, enhancing, or bug fixing already implemented code, use the style
+that is already being used so that the source is uniform and easy to
+follow.</a></b></p>
+
+</blockquote>
+
+<p>The ultimate goal of these guidelines is the increase readability and
+maintainability of our common source base. If you have suggestions for topics to
+be included, please mail them to <a
+href="mailto:sabre at nondot.org">Chris</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="mechanicalissues">Mechanical Source Issues</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="sourceformating">Source Code Formatting</a>
+</h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_commenting">Commenting</a>
+</h4>
+
+<div>
+
+<p>Comments are one critical part of readability and maintainability. Everyone
+knows they should comment, so should you. When writing comments, write them as
+English prose, which means they should use proper capitalization, punctuation,
+etc. Although we all should probably
+comment our code more than we do, there are a few very critical places that
+documentation is very useful:</p>
+
+<h5>File Headers</h5>
+
+<div>
+
+<p>Every source file should have a header on it that describes the basic
+purpose of the file. If a file does not have a header, it should not be
+checked into Subversion. Most source trees will probably have a standard
+file header format. The standard format for the LLVM source tree looks like
+this:</p>
+
+<div class="doc_code">
+<pre>
+//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
+//
+// The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This file contains the declaration of the Instruction class, which is the
+// base class for all of the VM instructions.
+//
+//===----------------------------------------------------------------------===//
+</pre>
+</div>
+
+<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 <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>
+
+<p>The next section in the file is a concise note that defines the license
+that the file is released under. This makes it perfectly clear what terms the
+source code can be distributed under and should not be modified in any way.</p>
+
+<p>The main body of the description does not have to be very long in most cases.
+Here it's only two lines. If an algorithm is being implemented or something
+tricky is going on, a reference to the paper where it is published should be
+included, as well as any notes or "gotchas" in the code to watch out for.</p>
+
+</div>
+
+<h5>Class overviews</h5>
+
+<p>Classes are one fundamental part of a good object oriented design. As such,
+a class definition should have a comment block that explains what the class is
+used for... if it's not obvious. If it's so completely obvious your grandma
+could figure it out, it's probably safe to leave it out. Naming classes
+something sane goes a long ways towards avoiding writing documentation.</p>
+
+
+<h5>Method information</h5>
+
+<div>
+
+<p>Methods defined in a class (as well as any global functions) should also be
+documented properly. A quick note about what it does and a description of the
+borderline behaviour is all that is necessary here (unless something
+particularly tricky or insidious is going on). The hope is that people can
+figure out how to use your interfaces without reading the code itself... that is
+the goal metric.</p>
+
+<p>Good things to talk about here are what happens when something unexpected
+happens: does the method return null? Abort? Format your hard disk?</p>
+
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_commentformat">Comment Formatting</a>
+</h4>
+
+<div>
+
+<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
+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 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>
+ <li>When writing a source file that is used by a tool that only accepts C
+ style comments.</li>
+</ol>
+
+<p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
+These nest properly and are better behaved in general than C style comments.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_includes"><tt>#include</tt> Style</a>
+</h4>
+
+<div>
+
+<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
+include guards if working on a header file), the <a
+href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
+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="#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/Bitcode/*</tt></li>
+ <li><tt>llvm/CodeGen/*</tt></li>
+ <li>...</li>
+ <li><tt>Support/*</tt></li>
+ <li><tt>Config/*</tt></li>
+ <li>System <tt>#includes</tt></li>
+</ol>
+
+<p>and each category should be sorted by name.</p>
+
+<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 <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 <tt>.cpp</tt> file to indicate where the interfaces it
+implements are defined.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_codewidth">Source Code Width</a>
+</h4>
+
+<div>
+
+<p>Write your code to fit within 80 columns of text. This helps those of us who
+like to print out code and look at your code in an xterm without resizing
+it.</p>
+
+<p>The longer answer is that there must be some limit to the width of the code
+in order to reasonably allow developers to have multiple files side-by-side in
+windows on a modest display. If you are going to pick a width limit, it is
+somewhat arbitrary but you might as well pick something standard. Going with
+90 columns (for example) instead of 80 columns wouldn't add any significant
+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 it is not up
+for debate.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
+</h4>
+
+<div>
+
+<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 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 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>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="scf_indentation">Indent Code Consistently</a>
+</h4>
+
+<div>
+
+<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>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="compilerissues">Compiler Issues</a>
+</h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
+</h4>
+
+<div>
+
+<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 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, a warning that annoys me occurs when
+I write code like this:</p>
+
+<div class="doc_code">
+<pre>
+if (V = getValue()) {
+ ...
+}
+</pre>
+</div>
+
+<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
+operator, and that I probably mistyped it. In most cases, I haven't, and I
+really don't want the spurious errors. To fix this particular problem, I
+rewrite the code like this:</p>
+
+<div class="doc_code">
+<pre>
+if ((V = getValue())) {
+ ...
+}
+</pre>
+</div>
+
+<p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
+be fixed by massaging the code appropriately.</p>
+
+<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p>
+
+<div class="doc_code">
+<pre>
+-Wall -Winline -W -Wwrite-strings -Wno-unused
+</pre>
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ci_portable_code">Write Portable Code</a>
+</h4>
+
+<div>
+
+<p>In almost all cases, it is possible and within reason to write completely
+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, 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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
+</h4>
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
+</h4>
+<div>
+
+<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
+interchangeably. The only difference is when they are used to declare a class:
+<tt>class</tt> makes all members private by default while <tt>struct</tt> makes
+all members public by default.</p>
+
+<p>Unfortunately, not all compilers follow the rules and some will generate
+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++
+<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">POD</a> type, in
+which case <tt>struct</tt> is allowed.</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="styleissues">Style Issues</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="macro">The High-Level Issues</a>
+</h3>
+<!-- ======================================================================= -->
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_module">A Public Header File <b>is</b> a Module</a>
+</h4>
+
+<div>
+
+<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 "<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 <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 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>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
+</h4>
+
+<div>
+
+<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
+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
+<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>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_privateheaders">Keep "Internal" Headers Private</a>
+</h4>
+
+<div>
+
+<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>
+
+<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 in a public
+class itself. Just make them private (or protected) and all is well.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a>
+</h4>
+
+<div>
+
+<p>When reading code, keep in mind how much state and how many previous
+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 <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>
+Value *DoSomething(Instruction *I) {
+ if (!isa<TerminatorInst>(I) &&
+ I->hasOneUse() && SomeOtherThing(I)) {
+ ... some long code ....
+ }
+
+ return 0;
+}
+</pre>
+</div>
+
+<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 ...
+ if (isa<TerminatorInst>(I))
+ return 0;
+
+ // We conservatively avoid transforming instructions with multiple uses
+ // because goats like cheese.
+ if (!I->hasOneUse())
+ return 0;
+
+ // This is really just here for example.
+ if (!SomeOtherThing(I))
+ return 0;
+
+ ... some long code ....
+}
+</pre>
+</div>
+
+<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">
+<pre>
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
+ if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) {
+ Value *LHS = BO->getOperand(0);
+ Value *RHS = BO->getOperand(1);
+ if (LHS != RHS) {
+ ...
+ }
+ }
+ }
+</pre>
+</div>
+
+<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 <tt>if</tt> conditions will have elses etc.
+It is strongly preferred to structure the loop like this:</p>
+
+<div class="doc_code">
+<pre>
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
+ BinaryOperator *BO = dyn_cast<BinaryOperator>(II);
+ if (!BO) continue;
+
+ 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 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 <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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a>
+</h4>
+
+<div>
+
+<p>For similar reasons above (reduction of indentation and easier reading),
+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': {
+ if (Signed) {
+ Type = Context.getsigjmp_bufType();
+ if (Type.isNull()) {
+ Error = ASTContext::GE_Missing_sigjmp_buf;
+ return QualType();
+ <b>} else {
+ break;
+ }</b>
+ } else {
+ Type = Context.getjmp_bufType();
+ if (Type.isNull()) {
+ Error = ASTContext::GE_Missing_jmp_buf;
+ return QualType();
+ <b>} else {
+ break;
+ }</b>
+ }
+ }
+ }
+</pre>
+</div>
+
+<p>It is better to write it like this:</p>
+
+<div class="doc_code">
+<pre>
+ case 'J':
+ if (Signed) {
+ Type = Context.getsigjmp_bufType();
+ if (Type.isNull()) {
+ Error = ASTContext::GE_Missing_sigjmp_buf;
+ return QualType();
+ }
+ } else {
+ Type = Context.getjmp_bufType();
+ if (Type.isNull()) {
+ Error = ASTContext::GE_Missing_jmp_buf;
+ return QualType();
+ }
+ }
+ <b>break;</b>
+</pre>
+</div>
+
+<p>Or better yet (in this case) as:</p>
+
+<div class="doc_code">
+<pre>
+ case 'J':
+ if (Signed)
+ Type = Context.getsigjmp_bufType();
+ else
+ Type = Context.getjmp_bufType();
+
+ if (Type.isNull()) {
+ Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
+ ASTContext::GE_Missing_jmp_buf;
+ return QualType();
+ }
+ <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>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
+</h4>
+
+<div>
+
+<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>
+ <b>bool FoundFoo = false;</b>
+ for (unsigned i = 0, e = BarList.size(); i != e; ++i)
+ if (BarList[i]->isFoo()) {
+ <b>FoundFoo = true;</b>
+ break;
+ }
+
+ <b>if (FoundFoo) {</b>
+ ...
+ }
+</pre>
+</div>
+
+<p>This sort of code is awkward to write, and is almost always a bad sign.
+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>
+
+<div class="doc_code">
+<pre>
+/// ListContainsFoo - Return true if the specified list has an element that is
+/// a foo.
+static bool ListContainsFoo(const std::vector<Bar*> &List) {
+ for (unsigned i = 0, e = List.size(); i != e; ++i)
+ if (List[i]->isFoo())
+ return true;
+ return false;
+}
+...
+
+ <b>if (ListContainsFoo(BarList)) {</b>
+ ...
+ }
+</pre>
+</div>
+
+<p>There are many reasons for doing this: it reduces indentation and factors out
+code which can often be shared by other code that checks for the same predicate.
+More importantly, it <em>forces you to pick a name</em> for the function, and
+forces you to write a comment for it. In this silly example, this doesn't add
+much value. However, if the condition is complex, this can make it a lot easier
+for the reader to understand the code that queries for this predicate. Instead
+of being faced with the in-line details of how we check to see if the BarList
+contains a foo, we can trust the function name and continue reading with better
+locality.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="micro">The Low-Level Issues</a>
+</h3>
+<!-- ======================================================================= -->
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_naming">
+ Name Types, Functions, Variables, and Enumerators Properly
+ </a>
+</h4>
+
+<div>
+
+<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>Variable names</b> should be nouns (as they represent state). The
+ name should be camel case, and start with an upper case letter (e.g.
+ <tt>Leader</tt> or <tt>Boats</tt>).</p></li>
+
+<li><p><b>Function names</b> should be verb phrases (as they represent
+ actions), and command-like function should be imperative. The name should
+ 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>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_assert">Assert Liberally</a>
+</h4>
+
+<div>
+
+<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
+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 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">
+<pre>
+inline Value *getOperand(unsigned i) {
+ assert(i < Operands.size() && "getOperand() out of range!");
+ return Operands[i];
+}
+</pre>
+</div>
+
+<p>Here are more examples:</p>
+
+<div class="doc_code">
+<pre>
+assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
+
+assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
+
+assert(idx < getNumSuccessors() && "Successor # out of range!");
+
+assert(V1.getType() == V2.getType() && "Constant types must be identical!");
+
+assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
+</pre>
+</div>
+
+<p>You get the idea.</p>
+
+<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>
+
+<div class="doc_code">
+<pre>
+assert(0 && "Some helpful error message");
+</pre>
+</div>
+
+<p>When used in a function that returns a value, they should be followed with a return
+statement and a comment indicating that this line is never reached. This will prevent
+a compiler which is unable to deduce that the assert statement never returns from
+generating a warning.</p>
+
+<div class="doc_code">
+<pre>
+assert(0 && "Some helpful error message");
+// Not reached
+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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a>
+</h4>
+
+<div>
+
+<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>
+
+<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
+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. <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
+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
+to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
+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 <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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_virtual_anch">
+ Provide a Virtual Method Anchor for Classes in Headers
+ </a>
+</h4>
+
+<div>
+
+<p>If a class is defined in a header file and has a v-table (either it has
+virtual methods or it derives from classes with virtual methods), it must
+always have at least one out-of-line virtual method in the class. Without
+this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
+that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
+increasing link times.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a>
+</h4>
+
+<div>
+
+<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>
+ BasicBlock *BB = ...
+ for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
+ ... use I ...
+</pre>
+</div>
+
+<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>"
+every time through the loop. Instead of writing the loop like this, we strongly
+prefer loops to be written so that they evaluate it once before the loop starts.
+A convenient way to do this is like so:</p>
+
+<div class="doc_code">
+<pre>
+ BasicBlock *BB = ...
+ for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I)
+ ... use I ...
+</pre>
+</div>
+
+<p>The observant may quickly point out that these two loops may have different
+semantics: if the container (a basic block in this case) is being mutated, then
+"<tt>BB->end()</tt>" may change its value every time through the loop and the
+second loop may not in fact be correct. If you actually do depend on this
+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
+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>
+
+<p>The second (even bigger) issue is that writing the loop in the first form
+hints to the reader that the loop is mutating the container (a fact that a
+comment would handily confirm!). If you write the loop in the second form, it
+is immediately obvious without even looking at the body of the loop that the
+container isn't being modified, which makes it easier to read the code and
+understand what it does.</p>
+
+<p>While the second form of the loop is a few extra keystrokes, we do strongly
+prefer it.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_iostream"><tt>#include <iostream></tt> is Forbidden</a>
+</h4>
+
+<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>
+
+<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
+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>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
+</h4>
+
+<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>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>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
+</h4>
+
+<div>
+
+<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>
+
+<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>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="nano">Microscopic Details</a>
+</h3>
+<!-- ======================================================================= -->
+
+<div>
+
+<p>This section describes preferred low-level formatting guidelines along with
+reasoning on why we prefer them.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="micro_spaceparen">Spaces Before Parentheses</a>
+</h4>
+
+<div>
+
+<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>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>
+</div>
+
+<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>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>
+</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>
+
+<div class="doc_code">
+<pre>
+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>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="micro_preincrement">Prefer Preincrement</a>
+</h4>
+
+<div>
+
+<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
+postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
+preincrementation whenever possible.</p>
+
+<p>The semantics of postincrement include making a copy of the value being
+incremented, returning it, and then preincrementing the "work value". For
+primitive types, this isn't a big deal... but for iterators, it can be a huge
+issue (for example, some iterators contains stack and set objects in them...
+copying an iterator could invoke the copy ctor's of these as well). In general,
+get in the habit of always using preincrement, and you won't have a problem.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="micro_namespaceindent">Namespace Indentation</a>
+</h4>
+
+<div>
+
+<p>
+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
+lots of stuff into them (so they can be large). Other times they are tiny,
+because they just hold an enum or something similar. In order to balance this,
+we use different approaches for small versus large namespaces.
+</p>
+
+<p>
+If a namespace definition is small and <em>easily</em> fits on a screen (say,
+less than 35 lines of code), then you should indent its body. Here's an
+example:
+</p>
+
+<div class="doc_code">
+<pre>
+namespace llvm {
+ namespace X86 {
+ /// RelocationType - An enum for the x86 relocation codes. Note that
+ /// the terminology here doesn't follow x86 convention - word means
+ /// 32-bit and dword means 64-bit.
+ enum RelocationType {
+ /// reloc_pcrel_word - PC relative relocation, add the relocated value to
+ /// the value already in memory, after we adjust it for where the PC is.
+ reloc_pcrel_word = 0,
+
+ /// reloc_picrel_word - PIC base relative relocation, add the relocated
+ /// value to the value already in memory, after we adjust it for where the
+ /// PIC base is.
+ reloc_picrel_word = 1,
+
+ /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
+ /// add the relocated value to the value already in memory.
+ reloc_absolute_word = 2,
+ reloc_absolute_dword = 3
+ };
+ }
+}
+</pre>
+</div>
+
+<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 <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>
+
+<div class="doc_code">
+<pre>
+namespace llvm {
+namespace knowledge {
+
+/// Grokable - This class represents things that Smith can have an intimate
+/// understanding of and contains the data associated with it.
+class Grokable {
+...
+public:
+ explicit Grokable() { ... }
+ virtual ~Grokable() = 0;
+
+ ...
+
+};
+
+} // end namespace knowledge
+} // end namespace llvm
+</pre>
+</div>
+
+<p>Because the class is large, we don't expect that the reader can easily
+understand the entire concept in a glance, and the end of the file (where the
+namespaces end) may be a long ways away from the place they open. As such,
+indenting the contents of the namespace doesn't add any value, and detracts from
+the readability of the class. In these cases it is best to <em>not</em> indent
+the contents of the namespace.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="micro_anonns">Anonymous Namespaces</a>
+</h4>
+
+<div>
+
+<p>After talking about namespaces in general, you may be wondering about
+anonymous namespaces in particular.
+Anonymous namespaces are a great language feature that tells the C++ compiler
+that the contents of the namespace are only visible within the current
+translation unit, allowing more aggressive optimization and eliminating the
+possibility of symbol name collisions. Anonymous namespaces are to C++ as
+"static" is to C functions and global variables. While "static" is available
+in C++, anonymous namespaces are more general: they can make entire classes
+private to a file.</p>
+
+<p>The problem with anonymous namespaces is that they naturally want to
+encourage indentation of their body, and they reduce locality of reference: if
+you see a random function definition in a C++ file, it is easy to see if it is
+marked static, but seeing if it is in an anonymous namespace requires scanning
+a big chunk of the file.</p>
+
+<p>Because of this, we have a simple guideline: make anonymous namespaces as
+small as possible, and only use them for class declarations. For example, this
+is good:</p>
+
+<div class="doc_code">
+<pre>
+<b>namespace {</b>
+ class StringSort {
+ ...
+ public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+ };
+<b>} // end anonymous namespace</b>
+
+static void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+</pre>
+</div>
+
+<p>This is bad:</p>
+
+
+<div class="doc_code">
+<pre>
+<b>namespace {</b>
+class StringSort {
+...
+public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+};
+
+void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+<b>} // end anonymous namespace</b>
+
+</pre>
+</div>
+
+
+<p>This is bad specifically because if you're looking at "Helper" in the middle
+of a large C++ file, that you have no immediate way to tell if it is local to
+the file. When it is marked static explicitly, this is immediately obvious.
+Also, there is no reason to enclose the definition of "operator<" in the
+namespace just because it was declared there.
+</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="seealso">See Also</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>A lot of these comments and recommendations have been culled for other
+sources. Two particularly important books for our work are:</p>
+
+<ol>
+
+<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
+C++</a> by Scott Meyers. Also
+interesting and useful are "More Effective C++" and "Effective STL" by the same
+author.</li>
+
+<li>Large-Scale C++ Software Design by John Lakos</li>
+
+</ol>
+
+<p>If you get some free time, and you haven't read them: do so, you might learn
+something.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:23 -0500 (Thu, 03 Nov 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CommandGuide/FileCheck.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/FileCheck.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/FileCheck.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/FileCheck.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,245 @@
+
+=pod
+
+=head1 NAME
+
+FileCheck - Flexible pattern matching file verifier
+
+=head1 SYNOPSIS
+
+B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>]
+
+=head1 DESCRIPTION
+
+B<FileCheck> reads two files (one from standard input, and one specified on the
+command line) and uses one to verify the other. This behavior is particularly
+useful for the testsuite, which wants to verify that the output of some tool
+(e.g. llc) contains the expected information (for example, a movsd from esp or
+whatever is interesting). This is similar to using grep, but it is optimized
+for matching multiple different inputs in one file in a specific order.
+
+The I<match-filename> file specifies the file that contains the patterns to
+match. The file to verify is always read from standard input.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<--check-prefix> I<prefix>
+
+FileCheck searches the contents of I<match-filename> for patterns to match. By
+default, these patterns are prefixed with "CHECK:". If you'd like to use a
+different prefix (e.g. because the same input file is checking multiple
+different tool or options), the B<--check-prefix> argument allows you to specify
+a specific prefix to match.
+
+=item B<--strict-whitespace>
+
+By default, FileCheck canonicalizes input horizontal whitespace (spaces and
+tabs) which causes it to ignore these differences (a space will match a tab).
+The --strict-whitespace argument disables this behavior.
+
+=item B<-version>
+
+Show the version number of this program.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<FileCheck> verifies that the file matches the expected contents, it exits
+with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero
+value.
+
+=head1 TUTORIAL
+
+FileCheck is typically used from LLVM regression tests, being invoked on the RUN
+line of the test. A simple example of using FileCheck from a RUN line looks
+like this:
+
+ ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
+
+This syntax says to pipe the current file ("%s") into llvm-as, pipe that into
+llc, then pipe the output of llc into FileCheck. This means that FileCheck will
+be verifying its standard input (the llc output) against the filename argument
+specified (the original .ll file specified by "%s"). To see how this works,
+lets look at the rest of the .ll file (after the RUN line):
+
+ define void @sub1(i32* %p, i32 %v) {
+ entry:
+ ; <b>CHECK: sub1:</b>
+ ; <b>CHECK: subl</b>
+ %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
+ ret void
+ }
+
+ define void @inc4(i64* %p) {
+ entry:
+ ; <b>CHECK: inc4:</b>
+ ; <b>CHECK: incq</b>
+ %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
+ ret void
+ }
+
+Here you can see some "CHECK:" lines specified in comments. Now you can see
+how the file is piped into llvm-as, then llc, and the machine code output is
+what we are verifying. FileCheck checks the machine code output to verify that
+it matches what the "CHECK:" lines specify.
+
+The syntax of the CHECK: lines is very simple: they are fixed strings that
+must occur in order. FileCheck defaults to ignoring horizontal whitespace
+differences (e.g. a space is allowed to match a tab) but otherwise, the contents
+of the CHECK: line is required to match some thing in the test file exactly.
+
+One nice thing about FileCheck (compared to grep) is that it allows merging
+test cases together into logical groups. For example, because the test above
+is checking for the "sub1:" and "inc4:" labels, it will not match unless there
+is a "subl" in between those labels. If it existed somewhere else in the file,
+that would not count: "grep subl" matches if subl exists anywhere in the
+file.
+
+
+
+=head2 The FileCheck -check-prefix option
+
+The FileCheck -check-prefix option allows multiple test configurations to be
+driven from one .ll file. This is useful in many circumstances, for example,
+testing different architectural variants with llc. Here's a simple example:
+
+ ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
+ ; RUN: | <b>FileCheck %s -check-prefix=X32</b>
+ ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
+ ; RUN: | <b>FileCheck %s -check-prefix=X64</b>
+
+ define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
+ %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
+ ret <4 x i32> %tmp1
+ ; <b>X32:</b> pinsrd_1:
+ ; <b>X32:</b> pinsrd $1, 4(%esp), %xmm0
+
+ ; <b>X64:</b> pinsrd_1:
+ ; <b>X64:</b> pinsrd $1, %edi, %xmm0
+ }
+
+In this case, we're testing that we get the expected code generation with
+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 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:
+
+ define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
+ %tmp3 = load <2 x double>* %A, align 16
+ %tmp7 = insertelement <2 x double> undef, double %B, i32 0
+ %tmp9 = shufflevector <2 x double> %tmp3,
+ <2 x double> %tmp7,
+ <2 x i32> < i32 0, i32 2 >
+ store <2 x double> %tmp9, <2 x double>* %r, align 16
+ ret void
+
+ ; <b>CHECK:</b> t2:
+ ; <b>CHECK:</b> movl 8(%esp), %eax
+ ; <b>CHECK-NEXT:</b> movapd (%eax), %xmm0
+ ; <b>CHECK-NEXT:</b> movhpd 12(%esp), %xmm0
+ ; <b>CHECK-NEXT:</b> movl 4(%esp), %eax
+ ; <b>CHECK-NEXT:</b> movapd %xmm0, (%eax)
+ ; <b>CHECK-NEXT:</b> ret
+ }
+
+CHECK-NEXT: directives reject the input unless there is exactly one newline
+between it an the previous directive. A CHECK-NEXT cannot be the first
+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 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:
+
+ define i8 @coerce_offset0(i32 %V, i32* %P) {
+ store i32 %V, i32* %P
+
+ %P2 = bitcast i32* %P to i8*
+ %P3 = getelementptr i8* %P2, i32 2
+
+ %A = load i8* %P3
+ ret i8 %A
+ ; <b>CHECK:</b> @coerce_offset0
+ ; <b>CHECK-NOT:</b> load
+ ; <b>CHECK:</b> ret i8
+ }
+
+
+
+=head2 FileCheck Pattern Matching Syntax
+
+The CHECK: and CHECK-NOT: directives both take a pattern to match. For most
+uses of FileCheck, fixed string matching is perfectly sufficient. For some
+things, a more flexible form of matching is desired. To support this, FileCheck
+allows you to specify regular expressions in matching strings, surrounded by
+double braces: B<{{yourregex}}>. Because we want to use fixed string
+matching for a majority of what we do, FileCheck has been designed to support
+mixing and matching fixed string matching with regular expressions. This allows
+you to write things like this:
+
+ ; CHECK: movhpd <b>{{[0-9]+}}</b>(%esp), <b>{{%xmm[0-7]}}</b>
+
+In this case, any offset from the ESP register will be allowed, and any xmm
+register will be allowed.
+
+Because regular expressions are enclosed with double braces, they are
+visually distinct, and you don't need to use escape characters within the double
+braces like you would in C. In the rare case that you want to match double
+braces explicitly from the input, you can use something ugly like
+B<{{[{][{]}}> as your pattern.
+
+
+
+=head2 FileCheck Variables
+
+It is often useful to match a pattern and then verify that it occurs again
+later in the file. For codegen tests, this can be useful to allow any register,
+but verify that that register is used consistently later. To do this, FileCheck
+allows named variables to be defined and substituted into patterns. Here is a
+simple example:
+
+ ; CHECK: test5:
+ ; CHECK: notw <b>[[REGISTER:%[a-z]+]]</b>
+ ; CHECK: andw {{.*}}<b>[[REGISTER]]</b>
+
+The first check line matches a regex (<tt>%[a-z]+</tt>) and captures it into
+the variables "REGISTER". The second line verifies that whatever is in REGISTER
+occurs later in the file after an "andw". FileCheck variable references are
+always contained in <tt>[[ ]]</tt> pairs, are named, and their names can be
+formed with the regex "<tt>[a-zA-Z_][a-zA-Z0-9_]*</tt>". If a colon follows the
+name, then it is a definition of the variable, if not, it is a use.
+
+FileCheck variables can be defined multiple times, and uses always get the
+latest value. Note that variables are all read at the start of a "CHECK" line
+and are all defined at the end. This means that if you have something like
+"<tt>CHECK: [[XYZ:.*]]x[[XYZ]]<tt>" that the check line will read the previous
+value of the XYZ variable and define a new one after the match is performed. If
+you need to do something like this you can probably take advantage of the fact
+that FileCheck is not actually line-oriented when it matches, this allows you to
+define two separate CHECK lines that match on the same line.
+
+
+
+=head1 AUTHORS
+
+Maintained by The LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/Makefile
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/Makefile?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/Makefile (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/Makefile Thu Dec 1 11:03:06 2011
@@ -0,0 +1,103 @@
+##===- docs/CommandGuide/Makefile --------------------------*- Makefile -*-===##
+#
+# The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+#
+##===----------------------------------------------------------------------===##
+
+ifdef BUILD_FOR_WEBSITE
+# This special case is for keeping the CommandGuide on the LLVM web site
+# up to date automatically as the documents are checked in. It must build
+# the POD files to HTML only and keep them in the src directories. It must also
+# build in an unconfigured tree, hence the ifdef. To use this, run
+# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script.
+SRC_DOC_DIR=
+DST_HTML_DIR=html/
+DST_MAN_DIR=man/man1/
+DST_PS_DIR=ps/
+
+# If we are in BUILD_FOR_WEBSITE mode, default to the all target.
+all:: html man ps
+
+clean:
+ rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS)
+
+# To create other directories, as needed, and timestamp their creation
+%/.dir:
+ -mkdir $* > /dev/null
+ date > $@
+
+else
+
+# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info.
+LEVEL := ../..
+include $(LEVEL)/Makefile.common
+
+SRC_DOC_DIR=$(PROJ_SRC_DIR)/
+DST_HTML_DIR=$(PROJ_OBJ_DIR)/
+DST_MAN_DIR=$(PROJ_OBJ_DIR)/
+DST_PS_DIR=$(PROJ_OBJ_DIR)/
+
+endif
+
+
+POD := $(wildcard $(SRC_DOC_DIR)*.pod)
+HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD))
+MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD))
+PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD))
+
+# The set of man pages we will not install
+NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1
+
+# The set of man pages that we will install
+INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN))
+
+.SUFFIXES:
+.SUFFIXES: .html .pod .1 .ps
+
+$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir
+ pod2html --css=manpage.css --htmlroot=. \
+ --podpath=. --noindex --infile=$< --outfile=$@ --title=$*
+
+$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir
+ pod2man --release=CVS --center="LLVM Command Guide" $< $@
+
+$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir
+ groff -Tps -man $< > $@
+
+
+html: $(HTML)
+man: $(MAN)
+ps: $(PS)
+
+EXTRA_DIST := $(POD) index.html
+
+clean-local::
+ $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS)
+
+HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/CommandGuide
+MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1
+PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps
+
+install-local:: $(HTML) $(INSTALL_MANS) $(PS)
+ $(Echo) Installing HTML CommandGuide Documentation
+ $(Verb) $(MKDIR) $(HTML_DIR)
+ $(Verb) $(DataInstall) $(HTML) $(HTML_DIR)
+ $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/index.html $(HTML_DIR)
+ $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR)
+ $(Echo) Installing MAN CommandGuide Documentation
+ $(Verb) $(MKDIR) $(MAN_DIR)
+ $(Verb) $(DataInstall) $(INSTALL_MANS) $(MAN_DIR)
+ $(Echo) Installing PS CommandGuide Documentation
+ $(Verb) $(MKDIR) $(PS_DIR)
+ $(Verb) $(DataInstall) $(PS) $(PS_DIR)
+
+uninstall-local::
+ $(Echo) Uninstalling CommandGuide Documentation
+ $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR)
+
+printvars::
+ $(Echo) "POD : " '$(POD)'
+ $(Echo) "HTML : " '$(HTML)'
Added: www-releases/trunk/3.0/docs/CommandGuide/bugpoint.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/bugpoint.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/bugpoint.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/bugpoint.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,186 @@
+=pod
+
+=head1 NAME
+
+bugpoint - automatic test case reduction tool
+
+=head1 SYNOPSIS
+
+B<bugpoint> [I<options>] [I<input LLVM ll/bc files>] [I<LLVM passes>] B<--args>
+I<program arguments>
+
+=head1 DESCRIPTION
+
+B<bugpoint> narrows down the source of problems in LLVM tools and passes. It
+can be used to debug three types of failures: optimizer crashes, miscompilations
+by optimizers, or bad native code generation (including problems in the static
+and JIT compilers). It aims to reduce large test cases to small, useful ones.
+For more information on the design and inner workings of B<bugpoint>, as well as
+advice for using bugpoint, see F<llvm/docs/Bugpoint.html> in the LLVM
+distribution.
+
+=head1 OPTIONS
+
+=over
+
+=item B<--additional-so> F<library>
+
+Load the dynamic shared object F<library> into the test program whenever it is
+run. This is useful if you are debugging programs which depend on non-LLVM
+libraries (such as the X or curses libraries) to run.
+
+=item B<--append-exit-code>=I<{true,false}>
+
+Append the test programs exit code to the output file so that a change in exit
+code is considered a test failure. Defaults to false.
+
+=item B<--args> I<program args>
+
+Pass all arguments specified after -args to the test program whenever it runs.
+Note that if any of the I<program args> start with a '-', you should use:
+
+ bugpoint [bugpoint args] --args -- [program args]
+
+The "--" right after the B<--args> option tells B<bugpoint> to consider any
+options starting with C<-> to be part of the B<--args> option, not as options to
+B<bugpoint> itself.
+
+=item B<--tool-args> I<tool args>
+
+Pass all arguments specified after --tool-args to the LLVM tool under test
+(B<llc>, B<lli>, etc.) whenever it runs. You should use this option in the
+following way:
+
+ bugpoint [bugpoint args] --tool-args -- [tool args]
+
+The "--" right after the B<--tool-args> option tells B<bugpoint> to consider any
+options starting with C<-> to be part of the B<--tool-args> option, not as
+options to B<bugpoint> itself. (See B<--args>, above.)
+
+=item B<--safe-tool-args> I<tool args>
+
+Pass all arguments specified after B<--safe-tool-args> to the "safe" execution
+tool.
+
+=item B<--gcc-tool-args> I<gcc tool args>
+
+Pass all arguments specified after B<--gcc-tool-args> to the invocation of
+B<gcc>.
+
+=item B<--opt-args> I<opt args>
+
+Pass all arguments specified after B<--opt-args> to the invocation of B<opt>.
+
+=item B<--disable-{dce,simplifycfg}>
+
+Do not run the specified passes to clean up and reduce the size of the test
+program. By default, B<bugpoint> uses these passes internally when attempting to
+reduce test programs. If you're trying to find a bug in one of these passes,
+B<bugpoint> may crash.
+
+=item B<--enable-valgrind>
+
+Use valgrind to find faults in the optimization phase. This will allow
+bugpoint to find otherwise asymptomatic problems caused by memory
+mis-management.
+
+=item B<-find-bugs>
+
+Continually randomize the specified passes and run them on the test program
+until a bug is found or the user kills B<bugpoint>.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<--input> F<filename>
+
+Open F<filename> and redirect the standard input of the test program, whenever
+it runs, to come from that file.
+
+=item B<--load> F<plugin>
+
+Load the dynamic object F<plugin> into B<bugpoint> itself. This object should
+register new optimization passes. Once loaded, the object will add new command
+line options to enable various optimizations. To see the new complete list of
+optimizations, use the B<-help> and B<--load> options together; for example:
+
+ bugpoint --load myNewPass.so -help
+
+=item B<--mlimit> F<megabytes>
+
+Specifies an upper limit on memory usage of the optimization and codegen. Set
+to zero to disable the limit.
+
+=item B<--output> F<filename>
+
+Whenever the test program produces output on its standard output stream, it
+should match the contents of F<filename> (the "reference output"). If you
+do not use this option, B<bugpoint> will attempt to generate a reference output
+by compiling the program with the "safe" backend and running it.
+
+=item B<--profile-info-file> F<filename>
+
+Profile file loaded by B<--profile-loader>.
+
+=item B<--run-{int,jit,llc,cbe,custom}>
+
+Whenever the test program is compiled, B<bugpoint> should generate code for it
+using the specified code generator. These options allow you to choose the
+interpreter, the JIT compiler, the static native code compiler, the C
+backend, or a custom command (see B<--exec-command>) respectively.
+
+=item B<--safe-{llc,cbe,custom}>
+
+When debugging a code generator, B<bugpoint> should use the specified code
+generator as the "safe" code generator. This is a known-good code generator
+used to generate the "reference output" if it has not been provided, and to
+compile portions of the program that as they are excluded from the testcase.
+These options allow you to choose the
+static native code compiler, the C backend, or a custom command,
+(see B<--exec-command>) respectively. The interpreter and the JIT backends
+cannot currently be used as the "safe" backends.
+
+=item B<--exec-command> I<command>
+
+This option defines the command to use with the B<--run-custom> and
+B<--safe-custom> options to execute the bitcode testcase. This can
+be useful for cross-compilation.
+
+=item B<--compile-command> I<command>
+
+This option defines the command to use with the B<--compile-custom>
+option to compile the bitcode testcase. This can be useful for
+testing compiler output without running any link or execute stages. To
+generate a reduced unit test, you may add CHECK directives to the
+testcase and pass the name of an executable compile-command script in this form:
+
+ #!/bin/sh
+ llc "$@"
+ not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
+
+This script will "fail" as long as FileCheck passes. So the result
+will be the minimum bitcode that passes FileCheck.
+
+=item B<--safe-path> I<path>
+
+This option defines the path to the command to execute with the
+B<--safe-{int,jit,llc,cbe,custom}>
+option.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<bugpoint> succeeds in finding a problem, it will exit with 0. Otherwise,
+if an error occurs, it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<opt|opt>
+
+=head1 AUTHOR
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/html/manpage.css
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/html/manpage.css?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/html/manpage.css (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/html/manpage.css Thu Dec 1 11:03:06 2011
@@ -0,0 +1,256 @@
+/* Based on http://www.perldoc.com/css/perldoc.css */
+
+ at import url("../llvm.css");
+
+body { font-family: Arial,Helvetica; }
+
+blockquote { margin: 10pt; }
+
+h1, a { color: #336699; }
+
+
+/*** Top menu style ****/
+.mmenuon {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ff6600; font-size: 10pt;
+ }
+.mmenuoff {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: 10pt;
+}
+.cpyright {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: xx-small;
+}
+.cpyrightText {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: xx-small;
+}
+.sections {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 11pt;
+}
+.dsections {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 12pt;
+}
+.slink {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #000000; font-size: 9pt;
+}
+
+.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; }
+
+.maintitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 18pt;
+}
+.dblArrow {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: small;
+}
+.menuSec {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: small;
+}
+
+.newstext {
+ font-family: Arial,Helvetica; font-size: small;
+}
+
+.linkmenu {
+ font-family: Arial,Helvetica; color: #000000; font-weight: bold;
+ text-decoration: none;
+}
+
+P {
+ font-family: Arial,Helvetica;
+}
+
+PRE {
+ font-size: 10pt;
+}
+.quote {
+ font-family: Times; text-decoration: none;
+ color: #000000; font-size: 9pt; font-style: italic;
+}
+.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; }
+.std { font-family: Arial,Helvetica; color: #000000; }
+.meerkatTitle {
+ font-family: sans-serif; font-size: x-small; color: black; }
+
+.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black }
+.meerkatCategory {
+ font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic;
+ color: brown; }
+.meerkatChannel {
+ font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; }
+.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; }
+
+.tocTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+.toc-item {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt; text-decoration: underline;
+}
+
+.perlVersion {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt; text-decoration: none;
+}
+
+.podTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #000000;
+}
+
+.docTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #000000; font-size: 10pt;
+}
+.dotDot {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #000000; font-size: 9pt;
+}
+
+.docSec {
+ font-family: Arial,Helvetica; font-weight: normal;
+ color: #333333; font-size: 9pt;
+}
+.docVersion {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 10pt;
+}
+
+.docSecs-on {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #ff0000; font-size: 10pt;
+}
+.docSecs-off {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+h2 {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: medium;
+}
+h1 {
+ font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: large;
+}
+
+DL {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+UL > LI > A {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt;
+}
+
+.moduleInfo {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 11pt;
+}
+
+.moduleInfoSec {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 10pt;
+}
+
+.moduleInfoVal {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline;
+ color: #000000; font-size: 10pt;
+}
+
+.cpanNavTitle {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #ffffff; font-size: 10pt;
+}
+.cpanNavLetter {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 9pt;
+}
+.cpanCat {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 9pt;
+}
+
+.bttndrkblue-bkgd-top {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif);
+}
+.bttndrkblue-bkgd-left {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif);
+}
+.bttndrkblue-bkgd {
+ padding-top: 0px;
+ padding-bottom: 0px;
+ margin-bottom: 0px;
+ margin-top: 0px;
+ background-repeat: no-repeat;
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif);
+ vertical-align: top;
+}
+.bttndrkblue-bkgd-right {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif);
+}
+.bttndrkblue-bkgd-bottom {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif);
+}
+.bttndrkblue-text a {
+ color: #ffffff;
+ text-decoration: none;
+}
+a.bttndrkblue-text:hover {
+ color: #ffDD3C;
+ text-decoration: none;
+}
+.bg-ltblue {
+ background-color: #f0f5fa;
+}
+
+.border-left-b {
+ background: #f0f5fa url(/i/corner-leftline.gif) repeat-y;
+}
+
+.border-right-b {
+ background: #f0f5fa url(/i/corner-rightline.gif) repeat-y;
+}
+
+.border-top-b {
+ background: #f0f5fa url(/i/corner-topline.gif) repeat-x;
+}
+
+.border-bottom-b {
+ background: #f0f5fa url(/i/corner-botline.gif) repeat-x;
+}
+
+.border-right-w {
+ background: #ffffff url(/i/corner-rightline.gif) repeat-y;
+}
+
+.border-top-w {
+ background: #ffffff url(/i/corner-topline.gif) repeat-x;
+}
+
+.border-bottom-w {
+ background: #ffffff url(/i/corner-botline.gif) repeat-x;
+}
+
+.bg-white {
+ background-color: #ffffff;
+}
+
+.border-left-w {
+ background: #ffffff url(/i/corner-leftline.gif) repeat-y;
+}
Added: www-releases/trunk/3.0/docs/CommandGuide/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/index.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/index.html (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/index.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,136 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>LLVM Command Guide</title>
+ <link rel="stylesheet" href="../llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ LLVM Command Guide
+</h1>
+
+<div>
+
+<p>These documents are HTML versions of the <a href="man/man1/">man pages</a>
+for all of the LLVM tools. These pages describe how to use the LLVM commands
+and what their options are. Note that these pages do not describe all of the
+options available for all tools. To get a complete listing, pass the
+<tt>-help</tt> (general options) or <tt>-help-hidden</tt> (general+debugging
+options) arguments to the tool you are interested in.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="basic">Basic Commands</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<ul>
+
+<li><a href="/cmds/llvm-as.html"><b>llvm-as</b></a> -
+ assemble a human-readable .ll file into bytecode</li>
+
+<li><a href="/cmds/llvm-dis.html"><b>llvm-dis</b></a> -
+ disassemble a bytecode file into a human-readable .ll file</li>
+
+<li><a href="/cmds/opt.html"><b>opt</b></a> -
+ run a series of LLVM-to-LLVM optimizations on a bytecode file</li>
+
+<li><a href="/cmds/llc.html"><b>llc</b></a> -
+ generate native machine code for a bytecode file</li>
+
+<li><a href="/cmds/lli.html"><b>lli</b></a> -
+ directly run a program compiled to bytecode using a JIT compiler or
+ interpreter</li>
+
+<li><a href="/cmds/llvm-link.html"><b>llvm-link</b></a> -
+ link several bytecode files into one</li>
+
+<li><a href="/cmds/llvm-ar.html"><b>llvm-ar</b></a> -
+ archive bytecode files</li>
+
+<li><a href="/cmds/llvm-ranlib.html"><b>llvm-ranlib</b></a> -
+ create an index for archives made with llvm-ar</li>
+
+<li><a href="/cmds/llvm-nm.html"><b>llvm-nm</b></a> -
+ print out the names and types of symbols in a bytecode file</li>
+
+<li><a href="/cmds/llvm-prof.html"><b>llvm-prof</b></a> -
+ format raw `<tt>llvmprof.out</tt>' data into a human-readable report</li>
+
+<li><a href="/cmds/llvm-ld.html"><b>llvm-ld</b></a> -
+ general purpose linker with loadable runtime optimization support</li>
+
+<li><a href="/cmds/llvm-config.html"><b>llvm-config</b></a> -
+ print out LLVM compilation options, libraries, etc. as configured</li>
+
+<li><a href="/cmds/llvm-diff.html"><b>llvm-diff</b></a> -
+ structurally compare two modules</li>
+
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="debug">Debugging Tools</a>
+</h2>
+<!-- *********************************************************************** -->
+
+
+<div>
+
+<ul>
+
+<li><a href="/cmds/bugpoint.html"><b>bugpoint</b></a> -
+ automatic test-case reducer</li>
+
+<li><a href="/cmds/llvm-extract.html"><b>llvm-extract</b></a> -
+ extract a function from an LLVM bytecode file</li>
+
+<li><a href="/cmds/llvm-bcanalyzer.html"><b>llvm-bcanalyzer</b></a> -
+ bytecode analyzer (analyzes the binary encoding itself, not the program it
+ represents)</li>
+
+</ul>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="internal">Internal Tools</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+<ul>
+
+<li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> -
+ Flexible file verifier used extensively by the testing harness</li>
+<li><a href="/cmds/tblgen.html"><b>tblgen</b></a> -
+ target description reader and generator</li>
+<li><a href="/cmds/lit.html"><b>lit</b></a> -
+ LLVM Integrated Tester, for running tests</li>
+
+</ul>
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-09-20 13:24:04 -0500 (Tue, 20 Sep 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CommandGuide/lit.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/lit.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/lit.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/lit.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,354 @@
+=pod
+
+=head1 NAME
+
+lit - LLVM Integrated Tester
+
+=head1 SYNOPSIS
+
+B<lit> [I<options>] [I<tests>]
+
+=head1 DESCRIPTION
+
+B<lit> is a portable tool for executing LLVM and Clang style test suites,
+summarizing their results, and providing indication of failures. B<lit> is
+designed to be a lightweight testing tool with as simple a user interface as
+possible.
+
+B<lit> should be run with one or more I<tests> to run specified on the command
+line. Tests can be either individual test files or directories to search for
+tests (see L<"TEST DISCOVERY">).
+
+Each specified test will be executed (potentially in parallel) and once all
+tests have been run B<lit> will print summary information on the number of tests
+which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will
+execute with a non-zero exit code if any tests fail.
+
+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
+(specific features may depend on the particular test format). See L<"EXECUTION
+OPTIONS"> for more information.
+
+Finally, B<lit> also supports additional options for only running a subset of
+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">
+
+=head1 GENERAL OPTIONS
+
+=over
+
+=item B<-h>, B<--help>
+
+Show the B<lit> help message.
+
+=item B<-j> I<N>, B<--threads>=I<N>
+
+Run I<N> tests in parallel. By default, this is automatically chosen to match
+the number of detected available CPUs.
+
+=item B<--config-prefix>=I<NAME>
+
+Search for I<NAME.cfg> and I<NAME.site.cfg> when searching for test suites,
+instead of I<lit.cfg> and I<lit.site.cfg>.
+
+=item B<--param> I<NAME>, B<--param> I<NAME>=I<VALUE>
+
+Add a user defined parameter I<NAME> with the given I<VALUE> (or the empty
+string if not given). The meaning and use of these parameters is test suite
+dependent.
+
+=back
+
+=head1 OUTPUT OPTIONS
+
+=over
+
+=item B<-q>, B<--quiet>
+
+Suppress any output except for test failures.
+
+=item B<-s>, B<--succinct>
+
+Show less output, for example don't show information on tests that pass.
+
+=item B<-v>, B<--verbose>
+
+Show more information on test failures, for example the entire test output
+instead of just the test result.
+
+=item B<--no-progress-bar>
+
+Do not use curses based progress bar.
+
+=back
+
+=head1 EXECUTION OPTIONS
+
+=over
+
+=item B<--path>=I<PATH>
+
+Specify an addition I<PATH> to use when searching for executables in tests.
+
+=item B<--vg>
+
+Run individual tests under valgrind (using the memcheck tool). The
+I<--error-exitcode> argument for valgrind is used so that valgrind failures will
+cause the program to exit with a non-zero status.
+
+=item B<--vg-arg>=I<ARG>
+
+When I<--vg> is used, specify an additional argument to pass to valgrind itself.
+
+=item B<--time-tests>
+
+Track the wall time individual tests take to execute and includes the results in
+the summary output. This is useful for determining which tests in a test suite
+take the most time to execute. Note that this option is most useful with I<-j
+1>.
+
+=back
+
+=head1 SELECTION OPTIONS
+
+=over
+
+=item B<--max-tests>=I<N>
+
+Run at most I<N> tests and then terminate.
+
+=item B<--max-time>=I<N>
+
+Spend at most I<N> seconds (approximately) running tests and then terminate.
+
+=item B<--shuffle>
+
+Run the tests in a random order.
+
+=back
+
+=head1 ADDITIONAL OPTIONS
+
+=over
+
+=item B<--debug>
+
+Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself.
+
+=item B<--show-suites>
+
+List the discovered test suites as part of the standard output.
+
+=item B<--no-tcl-as-sh>
+
+Run Tcl scripts internally (instead of converting to shell scripts).
+
+=item B<--repeat>=I<N>
+
+Run each test I<N> times. Currently this is primarily useful for timing tests,
+other results are not collated in any reasonable fashion.
+
+=back
+
+=head1 EXIT STATUS
+
+B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS
+results. Otherwise, it will exit with the status 0. Other exit codes used for
+non-test related failures (for example a user error or an internal program
+error).
+
+=head1 TEST DISCOVERY
+
+The inputs passed to B<lit> can be either individual tests, or entire
+directories or hierarchies of tests to run. When B<lit> starts up, the first
+thing it does is convert the inputs into a complete list of tests to run as part
+of I<test discovery>.
+
+In the B<lit> model, every test must exist inside some I<test suite>. B<lit>
+resolves the inputs specified on the command line to test suites by searching
+upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg>
+file. These files serve as both a marker of test suites and as configuration
+files which B<lit> loads in order to understand how to find and run the tests
+inside the test suite.
+
+Once B<lit> has mapped the inputs into test suites it traverses the list of
+inputs adding tests for individual files and recursively searching for tests in
+directories.
+
+This behavior makes it easy to specify a subset of tests to run, while still
+allowing the test suite configuration to control exactly how tests are
+interpreted. In addition, B<lit> always identifies tests by the test suite they
+are in, and their relative path inside the test suite. For appropriately
+configured projects, this allows B<lit> to provide convenient and flexible
+support for out-of-tree builds.
+
+=head1 TEST STATUS RESULTS
+
+Each test ultimately produces one of the following six results:
+
+=over
+
+=item B<PASS>
+
+The test succeeded.
+
+=item B<XFAIL>
+
+The test failed, but that is expected. This is used for test formats which allow
+specifying that a test does not currently work, but wish to leave it in the test
+suite.
+
+=item B<XPASS>
+
+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).
+
+=item B<FAIL>
+
+The test failed.
+
+=item B<UNRESOLVED>
+
+The test result could not be determined. For example, this occurs when the test
+could not be run, the test itself is invalid, or the test was interrupted.
+
+=item B<UNSUPPORTED>
+
+The test is not supported in this environment. This is used by test formats
+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">
+section for more information.
+
+=head1 LIT INFRASTRUCTURE
+
+This section describes the B<lit> testing architecture for users interested in
+creating a new B<lit> testing implementation, or extending an existing one.
+
+B<lit> proper is primarily an infrastructure for discovering and running
+arbitrary tests, and to expose a single convenient interface to these
+tests. B<lit> itself doesn't know how to run tests, rather this logic is
+defined by I<test suites>.
+
+=head2 TEST SUITES
+
+As described in L<"TEST DISCOVERY">, tests are always located inside a I<test
+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
+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.
+
+Once a test suite is discovered, its config file is loaded. Config files
+themselves are Python modules which will be executed. When the config file is
+executed, two important global variables are predefined:
+
+=over
+
+=item B<lit>
+
+The global B<lit> configuration object (a I<LitConfig> instance), which defines
+the builtin test formats, global configuration parameters, and other helper
+routines for implementing test configurations.
+
+=item B<config>
+
+This is the config object (a I<TestingConfig> instance) for the test suite,
+which the config file is expected to populate. The following variables are also
+available on the I<config> object, some of which must be set by the config and
+others are optional or predefined:
+
+B<name> I<[required]> The name of the test suite, for use in reports and
+diagnostics.
+
+B<test_format> I<[required]> The test format object which will be used to
+discover and run tests in the test suite. Generally this will be a builtin test
+format available from the I<lit.formats> module.
+
+B<test_src_root> The filesystem path to the test suite root. For out-of-dir
+builds this is the directory that will be scanned for tests.
+
+B<test_exec_root> For out-of-dir builds, the path to the test suite root inside
+the object directory. This is where tests will be run and temporary output files
+places.
+
+B<environment> A dictionary representing the environment to use when executing
+tests in the suite.
+
+B<suffixes> For B<lit> test formats which scan directories for tests, this
+variable as a list of suffixes to identify test files. Used by: I<ShTest>,
+I<TclTest>.
+
+B<substitutions> For B<lit> test formats which substitute variables into a test
+script, the list of substitutions to perform. Used by: I<ShTest>, I<TclTest>.
+
+B<unsupported> Mark an unsupported directory, all tests within it will be
+reported as unsupported. Used by: I<ShTest>, I<TclTest>.
+
+B<parent> The parent configuration, this is the config object for the directory
+containing the test suite, or None.
+
+B<on_clone> The config is actually cloned for every subdirectory inside a test
+suite, to allow local configuration on a per-directory basis. The I<on_clone>
+variable can be set to a Python function which will be called whenever a
+configuration is cloned (for a subdirectory). The function should takes three
+arguments: (1) the parent configuration, (2) the new configuration (which the
+I<on_clone> function will generally modify), and (3) the test path to the new
+directory being scanned.
+
+=back
+
+=head2 TEST DISCOVERY
+
+Once test suites are located, B<lit> recursively traverses the source directory
+(following I<test_src_root>) looking for tests. When B<lit> enters a
+sub-directory, it first checks to see if a nest test suite is defined in that
+directory. If so, it loads that test suite recursively, otherwise it
+instantiates a local test config for the directory (see L<"LOCAL CONFIGURATION
+FILES">).
+
+Tests are identified by the test suite they are contained within, and the
+relative path inside that suite. Note that the relative path may not refer to an
+actual file on disk; some test formats (such as I<GoogleTest>) define "virtual
+tests" which have a path that contains both the path to the actual test file and
+a subpath to identify the virtual test.
+
+=head2 LOCAL CONFIGURATION FILES
+
+When B<lit> loads a subdirectory in a test suite, it instantiates a local test
+configuration by cloning the configuration for the parent direction -- the root
+of this configuration chain will always be a test suite. Once the test
+configuration is cloned B<lit> checks for a I<lit.local.cfg> file in the
+subdirectory. If present, this file will be loaded and can be used to specialize
+the configuration for each individual directory. This facility can be used to
+define subdirectories of optional tests, or to change other configuration
+parameters -- for example, to change the test format, or the suffixes which
+identify test files.
+
+=head2 LIT EXAMPLE TESTS
+
+The B<lit> distribution contains several example implementations of test suites
+in the I<ExampleTests> directory.
+
+=head1 SEE ALSO
+
+L<valgrind(1)>
+
+=head1 AUTHOR
+
+Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llc.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llc.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llc.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llc.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,201 @@
+=pod
+
+=head1 NAME
+
+llc - LLVM static compiler
+
+=head1 SYNOPSIS
+
+B<llc> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+The B<llc> command compiles LLVM source inputs into assembly language for a
+specified architecture. The assembly language output can then be passed through
+a native assembler and linker to generate a native executable.
+
+The choice of architecture for the output assembly code is automatically
+determined from the input file, unless the B<-march> option is used to override
+the default.
+
+=head1 OPTIONS
+
+If I<filename> is - or omitted, B<llc> reads from standard input. Otherwise, it
+will from I<filename>. Inputs can be in either the LLVM assembly language
+format (.ll) or the LLVM bitcode format (.bc).
+
+If the B<-o> option is omitted, then B<llc> will send its output to standard
+output if the input is from standard input. If the B<-o> option specifies -,
+then the output will also be sent to standard output.
+
+If no B<-o> option is specified and an input file other than - is specified,
+then B<llc> creates the output filename by taking the input filename,
+removing any existing F<.bc> extension, and adding a F<.s> suffix.
+
+Other B<llc> options are as follows:
+
+=head2 End-user Options
+
+=over
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-O>=I<uint>
+
+Generate code at different optimization levels. These correspond to the I<-O0>,
+I<-O1>, I<-O2>, I<-O3>, and I<-O4> optimization levels used by B<llvm-gcc> and
+B<clang>.
+
+=item B<-mtriple>=I<target triple>
+
+Override the target triple specified in the input file with the specified
+string.
+
+=item B<-march>=I<arch>
+
+Specify the architecture for which to generate assembly, overriding the target
+encoded in the input file. See the output of B<llc -help> for a list of
+valid architectures. By default this is inferred from the target triple or
+autodetected to the current architecture.
+
+=item B<-mcpu>=I<cpuname>
+
+Specify a specific chip in the current architecture to generate code for.
+By default this is inferred from the target triple and autodetected to
+the current architecture. For a list of available CPUs, use:
+B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help>
+
+=item B<-mattr>=I<a1,+a2,-a3,...>
+
+Override or control specific attributes of the target, such as whether SIMD
+operations are enabled or not. The default set of attributes is set by the
+current CPU. For a list of available attributes, use:
+B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help>
+
+=item B<--disable-fp-elim>
+
+Disable frame pointer elimination optimization.
+
+=item B<--disable-excess-fp-precision>
+
+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
+addition is associative) or may not work for all input ranges. These
+optimizations allow the code generator to make use of some instructions which
+would otherwise not be usable (such as fsin on X86).
+
+=item B<--enable-correct-eh-support>
+
+Instruct the B<lowerinvoke> pass to insert code for correct exception handling
+support. This is expensive and is by default omitted for efficiency.
+
+=item B<--stats>
+
+Print statistics recorded by code-generation passes.
+
+=item B<--time-passes>
+
+Record the amount of time needed for each pass and print a report to standard
+error.
+
+=item B<--load>=F<dso_path>
+
+Dynamically load F<dso_path> (a path to a dynamically shared object) that
+implements an LLVM target. This will permit the target name to be used with the
+B<-march> option so that code can be generated for that target.
+
+=back
+
+=head2 Tuning/Configuration Options
+
+=over
+
+=item B<--print-machineinstrs>
+
+Print generated machine code between compilation phases (useful for debugging).
+
+=item B<--regalloc>=I<allocator>
+
+Specify the register allocator to use. The default I<allocator> is I<local>.
+Valid register allocators are:
+
+=over
+
+=item I<simple>
+
+Very simple "always spill" register allocator
+
+=item I<local>
+
+Local register allocator
+
+=item I<linearscan>
+
+Linear scan global register allocator
+
+=item I<iterativescan>
+
+Iterative scan global register allocator
+
+=back
+
+=item B<--spiller>=I<spiller>
+
+Specify the spiller to use for register allocators that support it. Currently
+this option is used only by the linear scan register allocator. The default
+I<spiller> is I<local>. Valid spillers are:
+
+=over
+
+=item I<simple>
+
+Simple spiller
+
+=item I<local>
+
+Local spiller
+
+=back
+
+=back
+
+=head2 Intel IA-32-specific Options
+
+=over
+
+=item B<--x86-asm-syntax=att|intel>
+
+Specify whether to emit assembly code in AT&T syntax (the default) or intel
+syntax.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llc> succeeds, it will exit with 0. Otherwise, if an error occurs,
+it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<lli|lli>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/lli.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/lli.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/lli.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/lli.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,219 @@
+=pod
+
+=head1 NAME
+
+lli - directly execute programs from LLVM bitcode
+
+=head1 SYNOPSIS
+
+B<lli> [I<options>] [I<filename>] [I<program args>]
+
+=head1 DESCRIPTION
+
+B<lli> directly executes programs in LLVM bitcode format. It takes a program
+in LLVM bitcode format and executes it using a just-in-time compiler, if one is
+available for the current architecture, or an interpreter. B<lli> takes all of
+the same code generator options as L<llc|llc>, but they are only effective when
+B<lli> is using the just-in-time compiler.
+
+If I<filename> is not specified, then B<lli> reads the LLVM bitcode for the
+program from standard input.
+
+The optional I<args> specified on the command line are passed to the program as
+arguments.
+
+=head1 GENERAL OPTIONS
+
+=over
+
+=item B<-fake-argv0>=I<executable>
+
+Override the C<argv[0]> value passed into the executing program.
+
+=item B<-force-interpreter>=I<{false,true}>
+
+If set to true, use the interpreter even if a just-in-time compiler is available
+for this architecture. Defaults to false.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-load>=I<puginfilename>
+
+Causes B<lli> to load the plugin (shared object) named I<pluginfilename> and use
+it for optimization.
+
+=item B<-stats>
+
+Print statistics from the code-generation passes. This is only meaningful for
+the just-in-time compiler, at present.
+
+=item B<-time-passes>
+
+Record the amount of time needed for each code-generation pass and print it to
+standard error.
+
+=item B<-version>
+
+Print out the version of B<lli> and exit without doing anything else.
+
+=back
+
+=head1 TARGET OPTIONS
+
+=over
+
+=item B<-mtriple>=I<target triple>
+
+Override the target triple specified in the input bitcode file with the
+specified string. This may result in a crash if you pick an
+architecture which is not compatible with the current system.
+
+=item B<-march>=I<arch>
+
+Specify the architecture for which to generate assembly, overriding the target
+encoded in the bitcode file. See the output of B<llc -help> for a list of
+valid architectures. By default this is inferred from the target triple or
+autodetected to the current architecture.
+
+=item B<-mcpu>=I<cpuname>
+
+Specify a specific chip in the current architecture to generate code for.
+By default this is inferred from the target triple and autodetected to
+the current architecture. For a list of available CPUs, use:
+B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help>
+
+=item B<-mattr>=I<a1,+a2,-a3,...>
+
+Override or control specific attributes of the target, such as whether SIMD
+operations are enabled or not. The default set of attributes is set by the
+current CPU. For a list of available attributes, use:
+B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help>
+
+=back
+
+
+=head1 FLOATING POINT OPTIONS
+
+=over
+
+=item B<-disable-excess-fp-precision>
+
+Disable optimizations that may increase floating point precision.
+
+=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>
+
+Causes B<lli> to enable optimizations that may decrease floating point
+precision.
+
+=item B<-soft-float>
+
+Causes B<lli> to generate software floating point library calls instead of
+equivalent hardware instructions.
+
+=back
+
+=head1 CODE GENERATION OPTIONS
+
+=over
+
+=item B<-code-model>=I<model>
+
+Choose the code model from:
+
+ default: Target default code model
+ small: Small code model
+ kernel: Kernel code model
+ medium: Medium code model
+ large: Large code model
+
+=item B<-disable-post-RA-scheduler>
+
+Disable scheduling after register allocation.
+
+=item B<-disable-spill-fusing>
+
+Disable fusing of spill code into instructions.
+
+=item B<-enable-correct-eh-support>
+
+Make the -lowerinvoke pass insert expensive, but correct, EH code.
+
+=item B<-jit-enable-eh>
+
+Exception handling should be enabled in the just-in-time compiler.
+
+=item B<-join-liveintervals>
+
+Coalesce copies (default=true).
+
+=item B<-nozero-initialized-in-bss>
+Don't place zero-initialized symbols into the BSS section.
+
+=item B<-pre-RA-sched>=I<scheduler>
+
+Instruction schedulers available (before register allocation):
+
+ =default: Best scheduler for the target
+ =none: No scheduling: breadth first sequencing
+ =simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
+ =simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
+ =list-burr: Bottom-up register reduction list scheduling
+ =list-tdrr: Top-down register reduction list scheduling
+ =list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
+
+=item B<-regalloc>=I<allocator>
+
+Register allocator to use (default=linearscan)
+
+ =bigblock: Big-block register allocator
+ =linearscan: linear scan register allocator =local - local register allocator
+ =simple: simple register allocator
+
+=item B<-relocation-model>=I<model>
+
+Choose relocation model from:
+
+ =default: Target default relocation model
+ =static: Non-relocatable code =pic - Fully relocatable, position independent code
+ =dynamic-no-pic: Relocatable external references, non-relocatable code
+
+=item B<-spiller>
+
+Spiller to use (default=local)
+
+ =simple: simple spiller
+ =local: local spiller
+
+=item B<-x86-asm-syntax>=I<syntax>
+
+Choose style of code to emit from X86 backend:
+
+ =att: Emit AT&T-style assembly
+ =intel: Emit Intel-style assembly
+
+=back
+
+=head1 EXIT STATUS
+
+If B<lli> fails to load the program, it will exit with an exit code of 1.
+Otherwise, it will return the exit code of the program it executes.
+
+=head1 SEE ALSO
+
+L<llc|llc>
+
+=head1 AUTHOR
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-ar.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-ar.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-ar.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-ar.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,406 @@
+=pod
+
+=head1 NAME
+
+llvm-ar - LLVM archiver
+
+=head1 SYNOPSIS
+
+B<llvm-ar> [-]{dmpqrtx}[Rabfikouz] [relpos] [count] <archive> [files...]
+
+
+=head1 DESCRIPTION
+
+The B<llvm-ar> command is similar to the common Unix utility, C<ar>. It
+archives several files together into a single file. The intent for this is
+to produce archive libraries by LLVM bitcode that can be linked into an
+LLVM program. However, the archive can contain any kind of file. By default,
+B<llvm-ar> generates a symbol table that makes linking faster because
+only the symbol table needs to be consulted, not each individual file member
+of the archive.
+
+The B<llvm-ar> command can be used to I<read> both SVR4 and BSD style archive
+files. However, it cannot be used to write them. While the B<llvm-ar> command
+produces files that are I<almost> identical to the format used by other C<ar>
+implementations, it has two significant departures in order to make the
+archive appropriate for LLVM. The first departure is that B<llvm-ar> only
+uses BSD4.4 style long path names (stored immediately after the header) and
+never contains a string table for long names. The second departure is that the
+symbol table is formated for efficient construction of an in-memory data
+structure that permits rapid (red-black tree) lookups. Consequently, archives
+produced with B<llvm-ar> usually won't be readable or editable with any
+C<ar> implementation or useful for linking. Using the C<f> modifier to flatten
+file names will make the archive readable by other C<ar> implementations
+but not for linking because the symbol table format for LLVM is unique. If an
+SVR4 or BSD style archive is used with the C<r> (replace) or C<q> (quick
+update) operations, the archive will be reconstructed in LLVM format. This
+means that the string table will be dropped (in deference to BSD 4.4 long names)
+and an LLVM symbol table will be added (by default). The system symbol table
+will be retained.
+
+Here's where B<llvm-ar> departs from previous C<ar> implementations:
+
+=over
+
+=item I<Symbol Table>
+
+Since B<llvm-ar> is intended to archive bitcode files, the symbol table
+won't make much sense to anything but LLVM. Consequently, the symbol table's
+format has been simplified. It consists simply of a sequence of pairs
+of a file member index number as an LSB 4byte integer and a null-terminated
+string.
+
+=item I<Long Paths>
+
+Some C<ar> implementations (SVR4) use a separate file member to record long
+path names (> 15 characters). B<llvm-ar> takes the BSD 4.4 and Mac OS X
+approach which is to simply store the full path name immediately preceding
+the data for the file. The path name is null terminated and may contain the
+slash (/) character.
+
+=item I<Compression>
+
+B<llvm-ar> can compress the members of an archive to save space. The
+compression used depends on what's available on the platform and what choices
+the LLVM Compressor utility makes. It generally favors bzip2 but will select
+between "no compression" or bzip2 depending on what makes sense for the
+file's content.
+
+=item I<Directory Recursion>
+
+Most C<ar> implementations do not recurse through directories but simply
+ignore directories if they are presented to the program in the F<files>
+option. B<llvm-ar>, however, can recurse through directory structures and
+add all the files under a directory, if requested.
+
+=item I<TOC Verbose Output>
+
+When B<llvm-ar> prints out the verbose table of contents (C<tv> option), it
+precedes the usual output with a character indicating the basic kind of
+content in the file. A blank means the file is a regular file. A 'Z' means
+the file is compressed. A 'B' means the file is an LLVM bitcode file. An
+'S' means the file is the symbol table.
+
+=back
+
+=head1 OPTIONS
+
+The options to B<llvm-ar> are compatible with other C<ar> implementations.
+However, there are a few modifiers (F<zR>) that are not found in other
+C<ar>s. The options to B<llvm-ar> specify a single basic operation to
+perform on the archive, a variety of modifiers for that operation, the
+name of the archive file, and an optional list of file names. These options
+are used to determine how B<llvm-ar> should process the archive file.
+
+The Operations and Modifiers are explained in the sections below. The minimal
+set of options is at least one operator and the name of the archive. Typically
+archive files end with a C<.a> suffix, but this is not required. Following
+the F<archive-name> comes a list of F<files> that indicate the specific members
+of the archive to operate on. If the F<files> option is not specified, it
+generally means either "none" or "all" members, depending on the operation.
+
+=head2 Operations
+
+=over
+
+=item d
+
+Delete files from the archive. No modifiers are applicable to this operation.
+The F<files> options specify which members should be removed from the
+archive. It is not an error if a specified file does not appear in the archive.
+If no F<files> are specified, the archive is not modified.
+
+=item m[abi]
+
+Move files from one location in the archive to another. The F<a>, F<b>, and
+F<i> modifiers apply to this operation. The F<files> will all be moved
+to the location given by the modifiers. If no modifiers are used, the files
+will be moved to the end of the archive. If no F<files> are specified, the
+archive is not modified.
+
+=item p[k]
+
+Print files to the standard output. The F<k> modifier applies to this
+operation. This operation simply prints the F<files> indicated to the
+standard output. If no F<files> are specified, the entire archive is printed.
+Printing bitcode files is ill-advised as they might confuse your terminal
+settings. The F<p> operation never modifies the archive.
+
+=item q[Rfz]
+
+Quickly append files to the end of the archive. The F<R>, F<f>, and F<z>
+modifiers apply to this operation. This operation quickly adds the
+F<files> to the archive without checking for duplicates that should be
+removed first. If no F<files> are specified, the archive is not modified.
+Because of the way that B<llvm-ar> constructs the archive file, its dubious
+whether the F<q> operation is any faster than the F<r> operation.
+
+=item r[Rabfuz]
+
+Replace or insert file members. The F<R>, F<a>, F<b>, F<f>, F<u>, and F<z>
+modifiers apply to this operation. This operation will replace existing
+F<files> or insert them at the end of the archive if they do not exist. If no
+F<files> are specified, the archive is not modified.
+
+=item t[v]
+
+Print the table of contents. Without any modifiers, this operation just prints
+the names of the members to the standard output. With the F<v> modifier,
+B<llvm-ar> also prints out the file type (B=bitcode, Z=compressed, S=symbol
+table, blank=regular file), the permission mode, the owner and group, the
+size, and the date. If any F<files> are specified, the listing is only for
+those files. If no F<files> are specified, the table of contents for the
+whole archive is printed.
+
+=item x[oP]
+
+Extract archive members back to files. The F<o> modifier applies to this
+operation. This operation retrieves the indicated F<files> from the archive
+and writes them back to the operating system's file system. If no
+F<files> are specified, the entire archive is extract.
+
+=back
+
+=head2 Modifiers (operation specific)
+
+The modifiers below are specific to certain operations. See the Operations
+section (above) to determine which modifiers are applicable to which operations.
+
+=over
+
+=item [a]
+
+When inserting or moving member files, this option specifies the destination of
+the new files as being C<a>fter the F<relpos> member. If F<relpos> is not found,
+the files are placed at the end of the archive.
+
+=item [b]
+
+When inserting or moving member files, this option specifies the destination of
+the new files as being C<b>efore the F<relpos> member. If F<relpos> is not
+found, the files are placed at the end of the archive. This modifier is
+identical to the the F<i> modifier.
+
+=item [f]
+
+Normally, B<llvm-ar> stores the full path name to a file as presented to it on
+the command line. With this option, truncated (15 characters max) names are
+used. This ensures name compatibility with older versions of C<ar> but may also
+thwart correct extraction of the files (duplicates may overwrite). If used with
+the F<R> option, the directory recursion will be performed but the file names
+will all be C<f>lattened to simple file names.
+
+=item [i]
+
+A synonym for the F<b> option.
+
+=item [k]
+
+Normally, B<llvm-ar> will not print the contents of bitcode files when the
+F<p> operation is used. This modifier defeats the default and allows the
+bitcode members to be printed.
+
+=item [N]
+
+This option is ignored by B<llvm-ar> but provided for compatibility.
+
+=item [o]
+
+When extracting files, this option will cause B<llvm-ar> to preserve the
+original modification times of the files it writes.
+
+=item [P]
+
+use full path names when matching
+
+=item [R]
+
+This modifier instructions the F<r> option to recursively process directories.
+Without F<R>, directories are ignored and only those F<files> that refer to
+files will be added to the archive. When F<R> is used, any directories specified
+with F<files> will be scanned (recursively) to find files to be added to the
+archive. Any file whose name begins with a dot will not be added.
+
+=item [u]
+
+When replacing existing files in the archive, only replace those files that have
+a time stamp than the time stamp of the member in the archive.
+
+=item [z]
+
+When inserting or replacing any file in the archive, compress the file first.
+This
+modifier is safe to use when (previously) compressed bitcode files are added to
+the archive; the compressed bitcode files will not be doubly compressed.
+
+=back
+
+=head2 Modifiers (generic)
+
+The modifiers below may be applied to any operation.
+
+=over
+
+=item [c]
+
+For all operations, B<llvm-ar> will always create the archive if it doesn't
+exist. Normally, B<llvm-ar> will print a warning message indicating that the
+archive is being created. Using this modifier turns off that warning.
+
+=item [s]
+
+This modifier requests that an archive index (or symbol table) be added to the
+archive. This is the default mode of operation. The symbol table will contain
+all the externally visible functions and global variables defined by all the
+bitcode files in the archive. Using this modifier is more efficient that using
+L<llvm-ranlib|llvm-ranlib> which also creates the symbol table.
+
+=item [S]
+
+This modifier is the opposite of the F<s> modifier. It instructs B<llvm-ar> to
+not build the symbol table. If both F<s> and F<S> are used, the last modifier to
+occur in the options will prevail.
+
+=item [v]
+
+This modifier instructs B<llvm-ar> to be verbose about what it is doing. Each
+editing operation taken against the archive will produce a line of output saying
+what is being done.
+
+=back
+
+=head1 STANDARDS
+
+The B<llvm-ar> utility is intended to provide a superset of the IEEE Std 1003.2
+(POSIX.2) functionality for C<ar>. B<llvm-ar> can read both SVR4 and BSD4.4 (or
+Mac OS X) archives. If the C<f> modifier is given to the C<x> or C<r> operations
+then B<llvm-ar> will write SVR4 compatible archives. Without this modifier,
+B<llvm-ar> will write BSD4.4 compatible archives that have long names
+immediately after the header and indicated using the "#1/ddd" notation for the
+name in the header.
+
+=head1 FILE FORMAT
+
+The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
+archive files. In fact, except for the symbol table, the C<ar> commands on those
+operating systems should be able to read LLVM archive files. The details of the
+file format follow.
+
+Each archive begins with the archive magic number which is the eight printable
+characters "!<arch>\n" where \n represents the newline character (0x0A).
+Following the magic number, the file is composed of even length members that
+begin with an archive header and end with a \n padding character if necessary
+(to make the length even). Each file member is composed of a header (defined
+below), an optional newline-terminated "long file name" and the contents of
+the file.
+
+The fields of the header are described in the items below. All fields of the
+header contain only ASCII characters, are left justified and are right padded
+with space characters.
+
+=over
+
+=item name - char[16]
+
+This field of the header provides the name of the archive member. If the name is
+longer than 15 characters or contains a slash (/) character, then this field
+contains C<#1/nnn> where C<nnn> provides the length of the name and the C<#1/>
+is literal. In this case, the actual name of the file is provided in the C<nnn>
+bytes immediately following the header. If the name is 15 characters or less, it
+is contained directly in this field and terminated with a slash (/) character.
+
+=item date - char[12]
+
+This field provides the date of modification of the file in the form of a
+decimal encoded number that provides the number of seconds since the epoch
+(since 00:00:00 Jan 1, 1970) per Posix specifications.
+
+=item uid - char[6]
+
+This field provides the user id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_uid field of the stat structure returned by the stat(2)
+operating system call.
+
+=item gid - char[6]
+
+This field provides the group id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_gid field of the stat structure returned by the stat(2)
+operating system call.
+
+=item mode - char[8]
+
+This field provides the access mode of the file encoded as an octal ASCII
+string. This field might not make much sense on non-Unix systems. On Unix, it
+is the same value as the st_mode field of the stat structure returned by the
+stat(2) operating system call.
+
+=item size - char[10]
+
+This field provides the size of the file, in bytes, encoded as a decimal ASCII
+string. If the size field is negative (starts with a minus sign, 0x02D), then
+the archive member is stored in compressed form. The first byte of the archive
+member's data indicates the compression type used. A value of 0 (0x30) indicates
+that no compression was used. A value of 2 (0x32) indicates that bzip2
+compression was used.
+
+=item fmag - char[2]
+
+This field is the archive file member magic number. Its content is always the
+two characters back tick (0x60) and newline (0x0A). This provides some measure
+utility in identifying archive files that have been corrupted.
+
+=back
+
+The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed
+that no regular archive member file will want this name. The LLVM symbol table
+is simply composed of a sequence of triplets: byte offset, length of symbol,
+and the symbol itself. Symbols are not null or newline terminated. Here are
+the details on each of these items:
+
+=over
+
+=item offset - vbr encoded 32-bit integer
+
+The offset item provides the offset into the archive file where the bitcode
+member is stored that is associated with the symbol. The offset value is 0
+based at the start of the first "normal" file member. To derive the actual
+file offset of the member, you must add the number of bytes occupied by the file
+signature (8 bytes) and the symbol tables. The value of this item is encoded
+using variable bit rate encoding to reduce the size of the symbol table.
+Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
+if there are more bytes to follow. The remaining 7 bits in each byte carry bits
+from the value. The final byte does not have the high bit set.
+
+=item length - vbr encoded 32-bit integer
+
+The length item provides the length of the symbol that follows. Like this
+I<offset> item, the length is variable bit rate encoded.
+
+=item symbol - character array
+
+The symbol item provides the text of the symbol that is associated with the
+I<offset>. The symbol is not terminated by any character. Its length is provided
+by the I<length> field. Note that is allowed (but unwise) to use non-printing
+characters (even 0x00) in the symbol. This allows for multiple encodings of
+symbol names.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-ar> succeeds, it will exit with 0. A usage error, results
+in an exit code of 1. A hard (file system typically) error results in an
+exit code of 2. Miscellaneous or unknown errors result in an
+exit code of 3.
+
+=head1 SEE ALSO
+
+L<llvm-ranlib|llvm-ranlib>, ar(1)
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-as.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-as.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-as.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-as.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,77 @@
+=pod
+
+=head1 NAME
+
+llvm-as - LLVM assembler
+
+=head1 SYNOPSIS
+
+B<llvm-as> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+B<llvm-as> is the LLVM assembler. It reads a file containing human-readable
+LLVM assembly language, translates it to LLVM bitcode, and writes the result
+into a file or to standard output.
+
+If F<filename> is omitted or is C<->, then B<llvm-as> reads its input from
+standard input.
+
+If an output file is not specified with the B<-o> option, then
+B<llvm-as> sends its output to a file or standard output by following
+these rules:
+
+=over
+
+=item *
+
+If the input is standard input, then the output is standard output.
+
+=item *
+
+If the input is a file that ends with C<.ll>, then the output file is of
+the same name, except that the suffix is changed to C<.bc>.
+
+=item *
+
+If the input is a file that does not end with the C<.ll> suffix, then the
+output file has the same name as the input file, except that the C<.bc>
+suffix is appended.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<-f>
+
+Enable binary output on terminals. Normally, B<llvm-as> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+B<llvm-as> will write raw bitcode regardless of the output device.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-o> F<filename>
+
+Specify the output file name. If F<filename> is C<->, then B<llvm-as>
+sends its output to standard output.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-as> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<llvm-dis|llvm-dis>, L<gccas|gccas>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-bcanalyzer.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-bcanalyzer.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-bcanalyzer.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-bcanalyzer.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,315 @@
+=pod
+
+=head1 NAME
+
+llvm-bcanalyzer - LLVM bitcode analyzer
+
+=head1 SYNOPSIS
+
+B<llvm-bcanalyzer> [I<options>] [F<filename>]
+
+=head1 DESCRIPTION
+
+The B<llvm-bcanalyzer> command is a small utility for analyzing bitcode files.
+The tool reads a bitcode file (such as generated with the B<llvm-as> tool) and
+produces a statistical report on the contents of the bitcode file. The tool
+can also dump a low level but human readable version of the bitcode file.
+This tool is probably not of much interest or utility except for those working
+directly with the bitcode file format. Most LLVM users can just ignore
+this tool.
+
+If F<filename> is omitted or is C<->, then B<llvm-bcanalyzer> reads its input
+from standard input. This is useful for combining the tool into a pipeline.
+Output is written to the standard output.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-nodetails>
+
+Causes B<llvm-bcanalyzer> to abbreviate its output by writing out only a module
+level summary. The details for individual functions are not displayed.
+
+=item B<-dump>
+
+Causes B<llvm-bcanalyzer> to dump the bitcode in a human readable format. This
+format is significantly different from LLVM assembly and provides details about
+the encoding of the bitcode file.
+
+=item B<-verify>
+
+Causes B<llvm-bcanalyzer> to verify the module produced by reading the
+bitcode. This ensures that the statistics generated are based on a consistent
+module.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-bcanalyzer> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value, usually 1.
+
+=head1 SUMMARY OUTPUT DEFINITIONS
+
+The following items are always printed by llvm-bcanalyzer. They comprize the
+summary output.
+
+=over
+
+=item B<Bitcode Analysis Of Module>
+
+This just provides the name of the module for which bitcode analysis is being
+generated.
+
+=item B<Bitcode Version Number>
+
+The bitcode version (not LLVM version) of the file read by the analyzer.
+
+=item B<File Size>
+
+The size, in bytes, of the entire bitcode file.
+
+=item B<Module Bytes>
+
+The size, in bytes, of the module block. Percentage is relative to File Size.
+
+=item B<Function Bytes>
+
+The size, in bytes, of all the function blocks. Percentage is relative to File
+Size.
+
+=item B<Global Types Bytes>
+
+The size, in bytes, of the Global Types Pool. Percentage is relative to File
+Size. This is the size of the definitions of all types in the bitcode file.
+
+=item B<Constant Pool Bytes>
+
+The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
+Size.
+
+=item B<Module Globals Bytes>
+
+Ths size, in bytes, of the Global Variable Definitions and their initializers.
+Percentage is relative to File Size.
+
+=item B<Instruction List Bytes>
+
+The size, in bytes, of all the instruction lists in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.
+
+=item B<Compaction Table Bytes>
+
+The size, in bytes, of all the compaction tables in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.
+
+=item B<Symbol Table Bytes>
+
+The size, in bytes, of all the symbol tables in all the functions. Percentage is
+relative to File Size. Note that this value is also included in the Function
+Bytes.
+
+=item B<Dependent Libraries Bytes>
+
+The size, in bytes, of the list of dependent libraries in the module. Percentage
+is relative to File Size. Note that this value is also included in the Module
+Global Bytes.
+
+=item B<Number Of Bitcode Blocks>
+
+The total number of blocks of any kind in the bitcode file.
+
+=item B<Number Of Functions>
+
+The total number of function definitions in the bitcode file.
+
+=item B<Number Of Types>
+
+The total number of types defined in the Global Types Pool.
+
+=item B<Number Of Constants>
+
+The total number of constants (of any type) defined in the Constant Pool.
+
+=item B<Number Of Basic Blocks>
+
+The total number of basic blocks defined in all functions in the bitcode file.
+
+=item B<Number Of Instructions>
+
+The total number of instructions defined in all functions in the bitcode file.
+
+=item B<Number Of Long Instructions>
+
+The total number of long instructions defined in all functions in the bitcode
+file. Long instructions are those taking greater than 4 bytes. Typically long
+instructions are GetElementPtr with several indices, PHI nodes, and calls to
+functions with large numbers of arguments.
+
+=item B<Number Of Operands>
+
+The total number of operands used in all instructions in the bitcode file.
+
+=item B<Number Of Compaction Tables>
+
+The total number of compaction tables in all functions in the bitcode file.
+
+=item B<Number Of Symbol Tables>
+
+The total number of symbol tables in all functions in the bitcode file.
+
+=item B<Number Of Dependent Libs>
+
+The total number of dependent libraries found in the bitcode file.
+
+=item B<Total Instruction Size>
+
+The total size of the instructions in all functions in the bitcode file.
+
+=item B<Average Instruction Size>
+
+The average number of bytes per instruction across all functions in the bitcode
+file. This value is computed by dividing Total Instruction Size by Number Of
+Instructions.
+
+=item B<Maximum Type Slot Number>
+
+The maximum value used for a type's slot number. Larger slot number values take
+more bytes to encode.
+
+=item B<Maximum Value Slot Number>
+
+The maximum value used for a value's slot number. Larger slot number values take
+more bytes to encode.
+
+=item B<Bytes Per Value>
+
+The average size of a Value definition (of any type). This is computed by
+dividing File Size by the total number of values of any type.
+
+=item B<Bytes Per Global>
+
+The average size of a global definition (constants and global variables).
+
+=item B<Bytes Per Function>
+
+The average number of bytes per function definition. This is computed by
+dividing Function Bytes by Number Of Functions.
+
+=item B<# of VBR 32-bit Integers>
+
+The total number of 32-bit integers encoded using the Variable Bit Rate
+encoding scheme.
+
+=item B<# of VBR 64-bit Integers>
+
+The total number of 64-bit integers encoded using the Variable Bit Rate encoding
+scheme.
+
+=item B<# of VBR Compressed Bytes>
+
+The total number of bytes consumed by the 32-bit and 64-bit integers that use
+the Variable Bit Rate encoding scheme.
+
+=item B<# of VBR Expanded Bytes>
+
+The total number of bytes that would have been consumed by the 32-bit and 64-bit
+integers had they not been compressed with the Variable Bit Rage encoding
+scheme.
+
+=item B<Bytes Saved With VBR>
+
+The total number of bytes saved by using the Variable Bit Rate encoding scheme.
+The percentage is relative to # of VBR Expanded Bytes.
+
+=back
+
+=head1 DETAILED OUTPUT DEFINITIONS
+
+The following definitions occur only if the -nodetails option was not given.
+The detailed output provides additional information on a per-function basis.
+
+=over
+
+=item B<Type>
+
+The type signature of the function.
+
+=item B<Byte Size>
+
+The total number of bytes in the function's block.
+
+=item B<Basic Blocks>
+
+The number of basic blocks defined by the function.
+
+=item B<Instructions>
+
+The number of instructions defined by the function.
+
+=item B<Long Instructions>
+
+The number of instructions using the long instruction format in the function.
+
+=item B<Operands>
+
+The number of operands used by all instructions in the function.
+
+=item B<Instruction Size>
+
+The number of bytes consumed by instructions in the function.
+
+=item B<Average Instruction Size>
+
+The average number of bytes consumed by the instructions in the function. This
+value is computed by dividing Instruction Size by Instructions.
+
+=item B<Bytes Per Instruction>
+
+The average number of bytes used by the function per instruction. This value is
+computed by dividing Byte Size by Instructions. Note that this is not the same
+as Average Instruction Size. It computes a number relative to the total function
+size not just the size of the instruction list.
+
+=item B<Number of VBR 32-bit Integers>
+
+The total number of 32-bit integers found in this function (for any use).
+
+=item B<Number of VBR 64-bit Integers>
+
+The total number of 64-bit integers found in this function (for any use).
+
+=item B<Number of VBR Compressed Bytes>
+
+The total number of bytes in this function consumed by the 32-bit and 64-bit
+integers that use the Variable Bit Rate encoding scheme.
+
+=item B<Number of VBR Expanded Bytes>
+
+The total number of bytes in this function that would have been consumed by
+the 32-bit and 64-bit integers had they not been compressed with the Variable
+Bit Rate encoding scheme.
+
+=item B<Bytes Saved With VBR>
+
+The total number of bytes saved in this function by using the Variable Bit
+Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
+
+=back
+
+=head1 SEE ALSO
+
+L<llvm-dis|llvm-dis>, L<http://llvm.org/docs/BitCodeFormat.html>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-config.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-config.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-config.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-config.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,131 @@
+=pod
+
+=head1 NAME
+
+llvm-config - Print LLVM compilation options
+
+=head1 SYNOPSIS
+
+B<llvm-config> I<option> [I<components>...]
+
+=head1 DESCRIPTION
+
+B<llvm-config> makes it easier to build applications that use LLVM. It can
+print the compiler flags, linker flags and object libraries needed to link
+against LLVM.
+
+=head1 EXAMPLES
+
+To link against the JIT:
+
+ g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
+ g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
+ `llvm-config --libs engine bcreader scalaropts`
+
+=head1 OPTIONS
+
+=over
+
+=item B<--version>
+
+Print the version number of LLVM.
+
+=item B<-help>
+
+Print a summary of B<llvm-config> arguments.
+
+=item B<--prefix>
+
+Print the installation prefix for LLVM.
+
+=item B<--src-root>
+
+Print the source root from which LLVM was built.
+
+=item B<--obj-root>
+
+Print the object root used to build LLVM.
+
+=item B<--bindir>
+
+Print the installation directory for LLVM binaries.
+
+=item B<--includedir>
+
+Print the installation directory for LLVM headers.
+
+=item B<--libdir>
+
+Print the installation directory for LLVM libraries.
+
+=item B<--cxxflags>
+
+Print the C++ compiler flags needed to use LLVM headers.
+
+=item B<--ldflags>
+
+Print the flags needed to link against LLVM libraries.
+
+=item B<--libs>
+
+Print all the libraries needed to link against the specified LLVM
+I<components>, including any dependencies.
+
+=item B<--libnames>
+
+Similar to B<--libs>, but prints the bare filenames of the libraries
+without B<-l> or pathnames. Useful for linking against a not-yet-installed
+copy of LLVM.
+
+=item B<--libfiles>
+
+Similar to B<--libs>, but print the full path to each library file. This is
+useful when creating makefile dependencies, to ensure that a tool is relinked if
+any library it uses changes.
+
+=item B<--components>
+
+Print all valid component names.
+
+=item B<--targets-built>
+
+Print the component names for all targets supported by this copy of LLVM.
+
+=item B<--build-mode>
+
+Print the build mode used when LLVM was built (e.g. Debug or Release)
+
+=back
+
+=head1 COMPONENTS
+
+To print a list of all available components, run B<llvm-config
+--components>. In most cases, components correspond directly to LLVM
+libraries. Useful "virtual" components include:
+
+=over
+
+=item B<all>
+
+Includes all LLVM libaries. The default if no components are specified.
+
+=item B<backend>
+
+Includes either a native backend or the C backend.
+
+=item B<engine>
+
+Includes either a native JIT or the bitcode interpreter.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-config> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-diff.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-diff.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-diff.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-diff.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+llvm-diff - LLVM structural 'diff'
+
+=head1 SYNOPSIS
+
+B<llvm-diff> [I<options>] I<module 1> I<module 2> [I<global name ...>]
+
+=head1 DESCRIPTION
+
+B<llvm-diff> compares the structure of two LLVM modules, primarily
+focusing on differences in function definitions. Insignificant
+differences, such as changes in the ordering of globals or in the
+names of local values, are ignored.
+
+An input module will be interpreted as an assembly file if its name
+ends in '.ll'; otherwise it will be read in as a bitcode file.
+
+If a list of global names is given, just the values with those names
+are compared; otherwise, all global values are compared, and
+diagnostics are produced for globals which only appear in one module
+or the other.
+
+B<llvm-diff> compares two functions by comparing their basic blocks,
+beginning with the entry blocks. If the terminators seem to match,
+then the corresponding successors are compared; otherwise they are
+ignored. This algorithm is very sensitive to changes in control flow,
+which tend to stop any downstream changes from being detected.
+
+B<llvm-diff> is intended as a debugging tool for writers of LLVM
+passes and frontends. It does not have a stable output format.
+
+=head1 EXIT STATUS
+
+If B<llvm-diff> finds no differences between the modules, it will exit
+with 0 and produce no output. Otherwise it will exit with a non-zero
+value.
+
+=head1 BUGS
+
+Many important differences, like changes in linkage or function
+attributes, are not diagnosed.
+
+Changes in memory behavior (for example, coalescing loads) can cause
+massive detected differences in blocks.
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-dis.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-dis.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-dis.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-dis.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+llvm-dis - LLVM disassembler
+
+=head1 SYNOPSIS
+
+B<llvm-dis> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+The B<llvm-dis> command is the LLVM disassembler. It takes an LLVM
+bitcode file and converts it into human-readable LLVM assembly language.
+
+If filename is omitted or specified as C<->, B<llvm-dis> reads its
+input from standard input.
+
+If the input is being read from standard input, then B<llvm-dis>
+will send its output to standard output by default. Otherwise, the
+output will be written to a file named after the input file, with
+a C<.ll> suffix added (any existing C<.bc> suffix will first be
+removed). You can override the choice of output file using the
+B<-o> option.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-f>
+
+Enable binary output on terminals. Normally, B<llvm-dis> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+B<llvm-dis> will write raw bitcode regardless of the output device.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-o> F<filename>
+
+Specify the output file name. If F<filename> is -, then the output is sent
+to standard output.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-dis> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<llvm-as|llvm-as>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-extract.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-extract.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-extract.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-extract.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+llvm-extract - extract a function from an LLVM module
+
+=head1 SYNOPSIS
+
+B<llvm-extract> [I<options>] B<--func> I<function-name> [I<filename>]
+
+=head1 DESCRIPTION
+
+The B<llvm-extract> command takes the name of a function and extracts it from
+the specified LLVM bitcode file. It is primarily used as a debugging tool to
+reduce test cases from larger programs that are triggering a bug.
+
+In addition to extracting the bitcode of the specified function,
+B<llvm-extract> will also remove unreachable global variables, prototypes, and
+unused types.
+
+The B<llvm-extract> command reads its input from standard input if filename is
+omitted or if filename is -. The output is always written to standard output,
+unless the B<-o> option is specified (see below).
+
+=head1 OPTIONS
+
+=over
+
+=item B<-f>
+
+Enable binary output on terminals. Normally, B<llvm-extract> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+B<llvm-extract> will write raw bitcode regardless of the output device.
+
+=item B<--func> I<function-name>
+
+Extract the function named I<function-name> from the LLVM bitcode. May be
+specified multiple times to extract multiple functions at once.
+
+=item B<--rfunc> I<function-regular-expr>
+
+Extract the function(s) matching I<function-regular-expr> from the LLVM bitcode.
+All functions matching the regular expression will be extracted. May be
+specified multiple times.
+
+=item B<--glob> I<global-name>
+
+Extract the global variable named I<global-name> from the LLVM bitcode. May be
+specified multiple times to extract multiple global variables at once.
+
+=item B<--rglob> I<glob-regular-expr>
+
+Extract the global variable(s) matching I<global-regular-expr> from the LLVM
+bitcode. All global variables matching the regular expression will be extracted.
+May be specified multiple times.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-o> I<filename>
+
+Specify the output filename. If filename is "-" (the default), then
+B<llvm-extract> sends its output to standard output.
+
+=item B<-S>
+
+Write output in LLVM intermediate language (instead of bitcode).
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-extract> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<bugpoint|bugpoint>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-ld.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-ld.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-ld.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-ld.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,234 @@
+=pod
+
+=head1 NAME
+
+llvm-ld - LLVM linker
+
+=head1 SYNOPSIS
+
+B<llvm-ld> <options> <files>
+
+=head1 DESCRIPTION
+
+The B<llvm-ld> tool takes a set of LLVM bitcode files and links them
+together into a single LLVM bitcode file. The output bitcode file can be
+another bitcode file or an executable bitcode program. Using additional
+options, B<llvm-ld> is able to produce native code executables.
+
+The B<llvm-ld> tool is the main linker for LLVM. It is used to link together
+the output of LLVM front-end compilers and run "link time" optimizations (mostly
+the inter-procedural kind).
+
+The B<llvm-ld> tools attempts to mimic the interface provided by the default
+system linker so that it can act as a I<drop-in> replacement.
+
+=head2 Search Order
+
+When looking for objects specified on the command line, B<llvm-ld> will search
+for the object first in the current directory and then in the directory
+specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it cannot
+find the object, it fails.
+
+When looking for a library specified with the B<-l> option, B<llvm-ld> first
+attempts to load a file with that name from the current directory. If that
+fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared
+library extension>, in that order, in each directory added to the library search
+path with the B<-L> option. These directories are searched in the order they
+are specified. If the library cannot be located, then B<llvm-ld> looks in the
+directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it
+does not find a library there, it fails.
+
+The I<shared library extension> may be I<.so>, I<.dyld>, I<.dll>, or something
+different, depending upon the system.
+
+The B<-L> option is global. It does not matter where it is specified in the
+list of command line arguments; the directory is simply added to the search path
+and is applied to all libraries, preceding or succeeding, in the command line.
+
+=head2 Link order
+
+All object and bitcode files are linked first in the order they were
+specified on the command line. All library files are linked next.
+Some libraries may not be linked into the object program; see below.
+
+=head2 Library Linkage
+
+Object files and static bitcode objects are always linked into the output
+file. Library archives (.a files) load only the objects within the archive
+that define symbols needed by the output file. Hence, libraries should be
+listed after the object files and libraries which need them; otherwise, the
+library may not be linked in, and the dependent library will not have its
+undefined symbols defined.
+
+=head2 Native code generation
+
+The B<llvm-ld> program has limited support for native code generation, when
+using the B<-native> or B<-native-cbe> options. Native code generation is
+performed by converting the linked bitcode into native assembly (.s) or C code
+and running the system compiler (typically gcc) on the result.
+
+=head1 OPTIONS
+
+=head2 General Options
+
+=over
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-v>
+
+Specifies verbose mode. In this mode the linker will print additional
+information about the actions it takes, programs it executes, etc.
+
+=item B<-stats>
+
+Print statistics.
+
+=item B<-time-passes>
+
+Record the amount of time needed for each pass and print it to standard
+error.
+
+=back
+
+=head2 Input/Output Options
+
+=over
+
+=item B<-o> F<filename>
+
+This overrides the default output file and specifies the name of the file that
+should be generated by the linker. By default, B<llvm-ld> generates a file named
+F<a.out> for compatibility with B<ld>. The output will be written to
+F<filename>.
+
+=item B<-b> F<filename>
+
+This option can be used to override the output bitcode file name. By default,
+the name of the bitcode output file is one more ".bc" suffix added to the name
+specified by B<-o filename> option.
+
+=item B<-l>F<name>
+
+This option specifies the F<name> of a library to search when resolving symbols
+for the program. Only the base name should be specified as F<name>, without a
+F<lib> prefix or any suffix.
+
+=item B<-L>F<Path>
+
+This option tells B<llvm-ld> to look in F<Path> to find any library subsequently
+specified with the B<-l> option. The paths will be searched in the order in
+which they are specified on the command line. If the library is still not found,
+a small set of system specific directories will also be searched. Note that
+libraries specified with the B<-l> option that occur I<before> any B<-L> options
+will not search the paths given by the B<-L> options following it.
+
+=item B<-link-as-library>
+
+Link the bitcode files together as a library, not an executable. In this mode,
+undefined symbols will be permitted.
+
+=item B<-r>
+
+An alias for -link-as-library.
+
+=item B<-native>
+
+Generate a native machine code executable.
+
+When generating native executables, B<llvm-ld> first checks for a bitcode
+version of the library and links it in, if necessary. If the library is
+missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same
+libraries as native code.
+
+In this way, B<llvm-ld> should be able to link in optimized bitcode
+subsets of common libraries and then link in any part of the library that
+hasn't been converted to bitcode.
+
+=item B<-native-cbe>
+
+Generate a native machine code executable with the LLVM C backend.
+
+This option is identical to the B<-native> option, but uses the
+C backend to generate code for the program instead of an LLVM native
+code generator.
+
+=back
+
+=head2 Optimization Options
+
+=over
+
+=item B<-disable-inlining>
+
+Do not run the inlining pass. Functions will not be inlined into other
+functions.
+
+=item B<-disable-opt>
+
+Completely disable optimization.
+
+=item B<-disable-internalize>
+
+Do not mark all symbols as internal.
+
+=item B<-verify-each>
+
+Run the verification pass after each of the passes to verify intermediate
+results.
+
+=item B<-strip-all>
+
+Strip all debug and symbol information from the executable to make it smaller.
+
+=item B<-strip-debug>
+
+Strip all debug information from the executable to make it smaller.
+
+=item B<-s>
+
+An alias for B<-strip-all>.
+
+=item B<-S>
+
+An alias for B<-strip-debug>.
+
+=item B<-export-dynamic>
+
+An alias for B<-disable-internalize>
+
+=item B<-post-link-opt>F<Path>
+
+Run post-link optimization program. After linking is completed a bitcode file
+will be generated. It will be passed to the program specified by F<Path> as the
+first argument. The second argument to the program will be the name of a
+temporary file into which the program should place its optimized output. For
+example, the "no-op optimization" would be a simple shell script:
+
+ #!/bin/bash
+ cp $1 $2
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs,
+it will exit with a non-zero return code.
+
+=head1 ENVIRONMENT
+
+The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode
+libraries. Any paths specified in this variable will be searched after the C<-L>
+options.
+
+=head1 SEE ALSO
+
+L<llvm-link|llvm-link>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-link.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-link.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-link.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-link.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,79 @@
+=pod
+
+=head1 NAME
+
+llvm-link - LLVM linker
+
+=head1 SYNOPSIS
+
+B<llvm-link> [I<options>] I<filename ...>
+
+=head1 DESCRIPTION
+
+B<llvm-link> takes several LLVM bitcode files and links them together into a
+single LLVM bitcode file. It writes the output file to standard output, unless
+the B<-o> option is used to specify a filename.
+
+B<llvm-link> attempts to load the input files from the current directory. If
+that fails, it looks for each file in each of the directories specified by the
+B<-L> options on the command line. The library search paths are global; each
+one is searched for every input file if necessary. The directories are searched
+in the order they were specified on the command line.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-L> F<directory>
+
+Add the specified F<directory> to the library search path. When looking for
+libraries, B<llvm-link> will look in path name for libraries. This option can be
+specified multiple times; B<llvm-link> will search inside these directories in
+the order in which they were specified on the command line.
+
+=item B<-f>
+
+Enable binary output on terminals. Normally, B<llvm-link> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+B<llvm-link> will write raw bitcode regardless of the output device.
+
+=item B<-o> F<filename>
+
+Specify the output file name. If F<filename> is C<->, then B<llvm-link> will
+write its output to standard output.
+
+=item B<-S>
+
+Write output in LLVM intermediate language (instead of bitcode).
+
+=item B<-d>
+
+If specified, B<llvm-link> prints a human-readable version of the output
+bitcode file to standard error.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-v>
+
+Verbose mode. Print information about what B<llvm-link> is doing. This
+typically includes a message for each bitcode file linked in and for each
+library found.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-link> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 SEE ALSO
+
+L<gccld|gccld>
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-nm.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-nm.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-nm.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-nm.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,122 @@
+=pod
+
+=head1 NAME
+
+llvm-nm - list LLVM bitcode file's symbol table
+
+=head1 SYNOPSIS
+
+B<llvm-nm> [I<options>] [I<filenames...>]
+
+=head1 DESCRIPTION
+
+The B<llvm-nm> utility lists the names of symbols from the LLVM bitcode files,
+or B<ar> archives containing LLVM bitcode files, named on the command line.
+Each symbol is listed along with some simple information about its provenance.
+If no file name is specified, or I<-> is used as a file name, B<llvm-nm> will
+process a bitcode file on its standard input stream.
+
+B<llvm-nm>'s default output format is the traditional BSD B<nm> output format.
+Each such output record consists of an (optional) 8-digit hexadecimal address,
+followed by a type code character, followed by a name, for each symbol. One
+record is printed per line; fields are separated by spaces. When the address is
+omitted, it is replaced by 8 spaces.
+
+Type code characters currently supported, and their meanings, are as follows:
+
+=over
+
+=item U
+
+Named object is referenced but undefined in this bitcode file
+
+=item C
+
+Common (multiple definitions link together into one def)
+
+=item W
+
+Weak reference (multiple definitions link together into zero or one definitions)
+
+=item t
+
+Local function (text) object
+
+=item T
+
+Global function (text) object
+
+=item d
+
+Local data object
+
+=item D
+
+Global data object
+
+=item ?
+
+Something unrecognizable
+
+=back
+
+Because LLVM bitcode files typically contain objects that are not considered to
+have addresses until they are linked into an executable image or dynamically
+compiled "just-in-time", B<llvm-nm> does not print an address for any symbol,
+even symbols which are defined in the bitcode file.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-P>
+
+Use POSIX.2 output format. Alias for B<--format=posix>.
+
+=item B<-B> (default)
+
+Use BSD output format. Alias for B<--format=bsd>.
+
+=item B<-help>
+
+Print a summary of command-line options and their meanings.
+
+=item B<--defined-only>
+
+Print only symbols defined in this bitcode file (as opposed to
+symbols which may be referenced by objects in this file, but not
+defined in this file.)
+
+=item B<--extern-only>, B<-g>
+
+Print only symbols whose definitions are external; that is, accessible
+from other bitcode files.
+
+=item B<--undefined-only>, B<-u>
+
+Print only symbols referenced but not defined in this bitcode file.
+
+=item B<--format=>I<fmt>, B<-f>
+
+Select an output format; I<fmt> may be I<sysv>, I<posix>, or I<bsd>. The
+default is I<bsd>.
+
+=back
+
+=head1 BUGS
+
+B<llvm-nm> cannot demangle C++ mangled names, like GNU B<nm> can.
+
+=head1 EXIT STATUS
+
+B<llvm-nm> exits with an exit code of zero.
+
+=head1 SEE ALSO
+
+L<llvm-dis|llvm-dis>, ar(1), nm(1)
+
+=head1 AUTHOR
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-prof.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-prof.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-prof.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-prof.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+llvm-prof - print execution profile of LLVM program
+
+=head1 SYNOPSIS
+
+B<llvm-prof> [I<options>] [I<bitcode file>] [I<llvmprof.out>]
+
+=head1 DESCRIPTION
+
+The B<llvm-prof> tool reads in an F<llvmprof.out> file (which can
+optionally use a specific file with the third program argument), a bitcode file
+for the program, and produces a human readable report, suitable for determining
+where the program hotspots are.
+
+This program is often used in conjunction with the F<utils/profile.pl>
+script. This script automatically instruments a program, runs it with the JIT,
+then runs B<llvm-prof> to format a report. To get more information about
+F<utils/profile.pl>, execute it with the B<-help> option.
+
+=head1 OPTIONS
+
+=over
+
+=item B<--annotated-llvm> or B<-A>
+
+In addition to the normal report printed, print out the code for the
+program, annotated with execution frequency information. This can be
+particularly useful when trying to visualize how frequently basic blocks
+are executed. This is most useful with basic block profiling
+information or better.
+
+=item B<--print-all-code>
+
+Using this option enables the B<--annotated-llvm> option, but it
+prints the entire module, instead of just the most commonly executed
+functions.
+
+=item B<--time-passes>
+
+Record the amount of time needed for each pass and print it to standard
+error.
+
+=back
+
+=head1 EXIT STATUS
+
+B<llvm-prof> returns 1 if it cannot load the bitcode file or the profile
+information. Otherwise, it exits with zero.
+
+=head1 AUTHOR
+
+B<llvm-prof> is maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/llvm-ranlib.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/llvm-ranlib.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/llvm-ranlib.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/llvm-ranlib.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,52 @@
+=pod
+
+=head1 NAME
+
+llvm-ranlib - Generate index for LLVM archive
+
+=head1 SYNOPSIS
+
+B<llvm-ranlib> [--version] [-help] <archive-file>
+
+=head1 DESCRIPTION
+
+The B<llvm-ranlib> command is similar to the common Unix utility, C<ranlib>. It
+adds or updates the symbol table in an LLVM archive file. Note that using the
+B<llvm-ar> modifier F<s> is usually more efficient than running B<llvm-ranlib>
+which is only provided only for completness and compatibility. Unlike other
+implementations of C<ranlib>, B<llvm-ranlib> indexes LLVM bitcode files, not
+native object modules. You can list the contents of the symbol table with the
+C<llvm-nm -s> command.
+
+=head1 OPTIONS
+
+=over
+
+=item F<archive-file>
+
+Specifies the archive-file to which the symbol table is added or updated.
+
+=item F<--version>
+
+Print the version of B<llvm-ranlib> and exit without building a symbol table.
+
+=item F<-help>
+
+Print usage help for B<llvm-ranlib> and exit without building a symbol table.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<llvm-ranlib> succeeds, it will exit with 0. If an error occurs, a non-zero
+exit code will be returned.
+
+=head1 SEE ALSO
+
+L<llvm-ar|llvm-ar>, ranlib(1)
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/manpage.css
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/manpage.css?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/manpage.css (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/manpage.css Thu Dec 1 11:03:06 2011
@@ -0,0 +1,256 @@
+/* Based on http://www.perldoc.com/css/perldoc.css */
+
+ at import url("../llvm.css");
+
+body { font-family: Arial,Helvetica; }
+
+blockquote { margin: 10pt; }
+
+h1, a { color: #336699; }
+
+
+/*** Top menu style ****/
+.mmenuon {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ff6600; font-size: 10pt;
+}
+.mmenuoff {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: 10pt;
+}
+.cpyright {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: xx-small;
+}
+.cpyrightText {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #ffffff; font-size: xx-small;
+}
+.sections {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 11pt;
+}
+.dsections {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 12pt;
+}
+.slink {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #000000; font-size: 9pt;
+}
+
+.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; }
+
+.maintitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 18pt;
+}
+.dblArrow {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: small;
+}
+.menuSec {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: small;
+}
+
+.newstext {
+ font-family: Arial,Helvetica; font-size: small;
+}
+
+.linkmenu {
+ font-family: Arial,Helvetica; color: #000000; font-weight: bold;
+ text-decoration: none;
+}
+
+P {
+ font-family: Arial,Helvetica;
+}
+
+PRE {
+ font-size: 10pt;
+}
+.quote {
+ font-family: Times; text-decoration: none;
+ color: #000000; font-size: 9pt; font-style: italic;
+}
+.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; }
+.std { font-family: Arial,Helvetica; color: #000000; }
+.meerkatTitle {
+ font-family: sans-serif; font-size: x-small; color: black; }
+
+.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black }
+.meerkatCategory {
+ font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic;
+ color: brown; }
+.meerkatChannel {
+ font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; }
+.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; }
+
+.tocTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+.toc-item {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt; text-decoration: underline;
+}
+
+.perlVersion {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt; text-decoration: none;
+}
+
+.podTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #000000;
+}
+
+.docTitle {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #000000; font-size: 10pt;
+}
+.dotDot {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #000000; font-size: 9pt;
+}
+
+.docSec {
+ font-family: Arial,Helvetica; font-weight: normal;
+ color: #333333; font-size: 9pt;
+}
+.docVersion {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 10pt;
+}
+
+.docSecs-on {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #ff0000; font-size: 10pt;
+}
+.docSecs-off {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+h2 {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: medium;
+}
+h1 {
+ font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: large;
+}
+
+DL {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
+ color: #333333; font-size: 10pt;
+}
+
+UL > LI > A {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #336699; font-size: 10pt;
+}
+
+.moduleInfo {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 11pt;
+}
+
+.moduleInfoSec {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 10pt;
+}
+
+.moduleInfoVal {
+ font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline;
+ color: #000000; font-size: 10pt;
+}
+
+.cpanNavTitle {
+ font-family: Arial,Helvetica; font-weight: bold;
+ color: #ffffff; font-size: 10pt;
+}
+.cpanNavLetter {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #333333; font-size: 9pt;
+}
+.cpanCat {
+ font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
+ color: #336699; font-size: 9pt;
+}
+
+.bttndrkblue-bkgd-top {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif);
+}
+.bttndrkblue-bkgd-left {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif);
+}
+.bttndrkblue-bkgd {
+ padding-top: 0px;
+ padding-bottom: 0px;
+ margin-bottom: 0px;
+ margin-top: 0px;
+ background-repeat: no-repeat;
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif);
+ vertical-align: top;
+}
+.bttndrkblue-bkgd-right {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif);
+}
+.bttndrkblue-bkgd-bottom {
+ background-color: #225688;
+ background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif);
+}
+.bttndrkblue-text a {
+ color: #ffffff;
+ text-decoration: none;
+}
+a.bttndrkblue-text:hover {
+ color: #ffDD3C;
+ text-decoration: none;
+}
+.bg-ltblue {
+ background-color: #f0f5fa;
+}
+
+.border-left-b {
+ background: #f0f5fa url(/i/corner-leftline.gif) repeat-y;
+}
+
+.border-right-b {
+ background: #f0f5fa url(/i/corner-rightline.gif) repeat-y;
+}
+
+.border-top-b {
+ background: #f0f5fa url(/i/corner-topline.gif) repeat-x;
+}
+
+.border-bottom-b {
+ background: #f0f5fa url(/i/corner-botline.gif) repeat-x;
+}
+
+.border-right-w {
+ background: #ffffff url(/i/corner-rightline.gif) repeat-y;
+}
+
+.border-top-w {
+ background: #ffffff url(/i/corner-topline.gif) repeat-x;
+}
+
+.border-bottom-w {
+ background: #ffffff url(/i/corner-botline.gif) repeat-x;
+}
+
+.bg-white {
+ background-color: #ffffff;
+}
+
+.border-left-w {
+ background: #ffffff url(/i/corner-leftline.gif) repeat-y;
+}
Added: www-releases/trunk/3.0/docs/CommandGuide/opt.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/opt.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/opt.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/opt.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,143 @@
+=pod
+
+=head1 NAME
+
+opt - LLVM optimizer
+
+=head1 SYNOPSIS
+
+B<opt> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+The B<opt> command is the modular LLVM optimizer and analyzer. It takes LLVM
+source files as input, runs the specified optimizations or analyses on it, and then
+outputs the optimized file or the analysis results. The function of
+B<opt> depends on whether the B<-analyze> option is given.
+
+When B<-analyze> is specified, B<opt> performs various analyses of the input
+source. It will usually print the results on standard output, but in a few
+cases, it will print output to standard error or generate a file with the
+analysis output, which is usually done when the output is meant for another
+program.
+
+While B<-analyze> is I<not> given, B<opt> attempts to produce an optimized
+output file. The optimizations available via B<opt> depend upon what
+libraries were linked into it as well as any additional libraries that have
+been loaded with the B<-load> option. Use the B<-help> option to determine
+what optimizations you can use.
+
+If I<filename> is omitted from the command line or is I<->, B<opt> reads its
+input from standard input. Inputs can be in either the LLVM assembly language
+format (.ll) or the LLVM bitcode format (.bc).
+
+If an output filename is not specified with the B<-o> option, B<opt>
+writes its output to the standard output.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-f>
+
+Enable binary output on terminals. Normally, B<opt> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+B<opt> will write raw bitcode regardless of the output device.
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-o> I<filename>
+
+Specify the output filename.
+
+=item B<-S>
+
+Write output in LLVM intermediate language (instead of bitcode).
+
+=item B<-{passname}>
+
+B<opt> provides the ability to run any of LLVM's optimization or analysis passes
+in any order. The B<-help> option lists all the passes available. The order in
+which the options occur on the command line are the order in which they are
+executed (within pass constraints).
+
+=item B<-std-compile-opts>
+
+This is short hand for a standard list of I<compile time optimization> passes.
+This is typically used to optimize the output from the llvm-gcc front end. It
+might be useful for other front end compilers as well. To discover the full set
+of options available, use the following command:
+
+ llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments
+
+=item B<-disable-inlining>
+
+This option is only meaningful when B<-std-compile-opts> is given. It simply
+removes the inlining pass from the standard list.
+
+=item B<-disable-opt>
+
+This option is only meaningful when B<-std-compile-opts> is given. It disables
+most, but not all, of the B<-std-compile-opts>. The ones that remain are
+B<-verify>, B<-lower-setjmp>, and B<-funcresolve>.
+
+=item B<-strip-debug>
+
+This option causes opt to strip debug information from the module before
+applying other optimizations. It is essentially the same as B<-strip> but it
+ensures that stripping of debug information is done first.
+
+=item B<-verify-each>
+
+This option causes opt to add a verify pass after every pass otherwise specified
+on the command line (including B<-verify>). This is useful for cases where it
+is suspected that a pass is creating an invalid module but it is not clear which
+pass is doing it. The combination of B<-std-compile-opts> and B<-verify-each>
+can quickly track down this kind of problem.
+
+=item B<-profile-info-file> I<filename>
+
+Specify the name of the file loaded by the -profile-loader option.
+
+=item B<-stats>
+
+Print statistics.
+
+=item B<-time-passes>
+
+Record the amount of time needed for each pass and print it to standard
+error.
+
+=item B<-debug>
+
+If this is a debug build, this option will enable debug printouts
+from passes which use the I<DEBUG()> macro. See the B<LLVM Programmer's
+Manual>, section I<#DEBUG> for more information.
+
+=item B<-load>=I<plugin>
+
+Load the dynamic object I<plugin>. This object should register new optimization
+or analysis passes. Once loaded, the object will add new command line options to
+enable various optimizations or analyses. To see the new complete list of
+optimizations, use the B<-help> and B<-load> options together. For example:
+
+ opt -load=plugin.so -help
+
+=item B<-p>
+
+Print module after each transformation.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<opt> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 AUTHORS
+
+Maintained by the LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandGuide/tblgen.pod
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandGuide/tblgen.pod?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandGuide/tblgen.pod (added)
+++ www-releases/trunk/3.0/docs/CommandGuide/tblgen.pod Thu Dec 1 11:03:06 2011
@@ -0,0 +1,115 @@
+
+=pod
+
+=head1 NAME
+
+tblgen - Target Description To C++ Code Generator
+
+=head1 SYNOPSIS
+
+B<tblgen> [I<options>] [I<filename>]
+
+=head1 DESCRIPTION
+
+B<tblgen> translates from target description (.td) files into C++ code that can
+be included in the definition of an LLVM target library. Most users of LLVM will
+not need to use this program. It is only for assisting with writing an LLVM
+target backend.
+
+The input and output of B<tblgen> is beyond the scope of this short
+introduction. Please see the I<CodeGeneration> page in the LLVM documentation.
+
+The F<filename> argument specifies the name of a Target Description (.td) file
+to read as input.
+
+=head1 OPTIONS
+
+=over
+
+=item B<-help>
+
+Print a summary of command line options.
+
+=item B<-o> F<filename>
+
+Specify the output file name. If F<filename> is C<->, then B<tblgen>
+sends its output to standard output.
+
+=item B<-I> F<directory>
+
+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<-asmwriternum> F<N>
+
+Make -gen-asm-writer emit assembly writer number F<N>.
+
+=item B<-class> F<class Name>
+
+Print the enumeration list for this class.
+
+=item B<-print-records>
+
+Print all records to standard output (default).
+
+=item B<-print-enums>
+
+Print enumeration values for a class
+
+=item B<-gen-emitter>
+
+Generate machine code emitter.
+
+=item B<-gen-register-enums>
+
+Generate the enumeration values for all registers.
+
+=item B<-gen-register-desc>
+
+Generate a register info description for each register.
+
+=item B<-gen-register-desc-header>
+
+Generate a register info description header for each register.
+
+=item B<-gen-instr-enums>
+
+Generate enumeration values for instructions.
+
+=item B<-gen-instr-desc>
+
+Generate instruction descriptions.
+
+=item B<-gen-asm-writer>
+
+Generate the assembly writer.
+
+=item B<-gen-dag-isel>
+
+Generate a DAG (Directed Acycle Graph) instruction selector.
+
+=item B<-gen-subtarget>
+
+Generate subtarget enumerations.
+
+=item B<-gen-intrinsic>
+
+Generate intrinsic information.
+
+=item B<-version>
+
+Show the version number of this program.
+
+=back
+
+=head1 EXIT STATUS
+
+If B<tblgen> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+=head1 AUTHORS
+
+Maintained by The LLVM Team (L<http://llvm.org/>).
+
+=cut
Added: www-releases/trunk/3.0/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CommandLine.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CommandLine.html (added)
+++ www-releases/trunk/3.0/docs/CommandLine.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1976 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>CommandLine 2.0 Library Manual</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ CommandLine 2.0 Library Manual
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+
+ <li><a href="#quickstart">Quick Start Guide</a>
+ <ol>
+ <li><a href="#bool">Boolean Arguments</a></li>
+ <li><a href="#alias">Argument Aliases</a></li>
+ <li><a href="#onealternative">Selecting an alternative from a
+ set of possibilities</a></li>
+ <li><a href="#namedalternatives">Named alternatives</a></li>
+ <li><a href="#list">Parsing a list of options</a></li>
+ <li><a href="#bits">Collecting options as a set of flags</a></li>
+ <li><a href="#description">Adding freeform text to help output</a></li>
+ </ol></li>
+
+ <li><a href="#referenceguide">Reference Guide</a>
+ <ol>
+ <li><a href="#positional">Positional Arguments</a>
+ <ul>
+ <li><a href="#--">Specifying positional options with hyphens</a></li>
+ <li><a href="#getPosition">Determining absolute position with
+ getPosition</a></li>
+ <li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
+ modifier</a></li>
+ </ul></li>
+
+ <li><a href="#storage">Internal vs External Storage</a></li>
+
+ <li><a href="#attributes">Option Attributes</a></li>
+
+ <li><a href="#modifiers">Option Modifiers</a>
+ <ul>
+ <li><a href="#hiding">Hiding an option from <tt>-help</tt>
+ output</a></li>
+ <li><a href="#numoccurrences">Controlling the number of occurrences
+ required and allowed</a></li>
+ <li><a href="#valrequired">Controlling whether or not a value must be
+ specified</a></li>
+ <li><a href="#formatting">Controlling other formatting options</a></li>
+ <li><a href="#misc">Miscellaneous option modifiers</a></li>
+ <li><a href="#response">Response files</a></li>
+ </ul></li>
+
+ <li><a href="#toplevel">Top-Level Classes and Functions</a>
+ <ul>
+ <li><a href="#cl::ParseCommandLineOptions">The
+ <tt>cl::ParseCommandLineOptions</tt> function</a></li>
+ <li><a href="#cl::ParseEnvironmentOptions">The
+ <tt>cl::ParseEnvironmentOptions</tt> function</a></li>
+ <li><a href="#cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a></li>
+ <li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
+ <li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
+ <li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
+ <li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
+ <li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
+ </ul></li>
+
+ <li><a href="#builtinparsers">Builtin parsers</a>
+ <ul>
+ <li><a href="#genericparser">The Generic <tt>parser<t></tt>
+ parser</a></li>
+ <li><a href="#boolparser">The <tt>parser<bool></tt>
+ specialization</a></li>
+ <li><a href="#boolOrDefaultparser">The <tt>parser<boolOrDefault></tt>
+ specialization</a></li>
+ <li><a href="#stringparser">The <tt>parser<string></tt>
+ specialization</a></li>
+ <li><a href="#intparser">The <tt>parser<int></tt>
+ specialization</a></li>
+ <li><a href="#doubleparser">The <tt>parser<double></tt> and
+ <tt>parser<float></tt> specializations</a></li>
+ </ul></li>
+ </ol></li>
+ <li><a href="#extensionguide">Extension Guide</a>
+ <ol>
+ <li><a href="#customparser">Writing a custom parser</a></li>
+ <li><a href="#explotingexternal">Exploiting external storage</a></li>
+ <li><a href="#dynamicopts">Dynamically adding command line
+ options</a></li>
+ </ol></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document describes the CommandLine argument processing library. It will
+show you how to use it, and what it can do. The CommandLine library uses a
+declarative approach to specifying the command line options that your program
+takes. By default, these options declarations implicitly hold the value parsed
+for the option declared (of course this <a href="#storage">can be
+changed</a>).</p>
+
+<p>Although there are a <b>lot</b> of command line argument parsing libraries
+out there in many different languages, none of them fit well with what I needed.
+By looking at the features and problems of other libraries, I designed the
+CommandLine library to have the following features:</p>
+
+<ol>
+<li>Speed: The CommandLine library is very quick and uses little resources. The
+parsing time of the library is directly proportional to the number of arguments
+parsed, not the the number of options recognized. Additionally, command line
+argument values are captured transparently into user defined global variables,
+which can be accessed like any other variable (and with the same
+performance).</li>
+
+<li>Type Safe: As a user of CommandLine, you don't have to worry about
+remembering the type of arguments that you want (is it an int? a string? a
+bool? an enum?) and keep casting it around. Not only does this help prevent
+error prone constructs, it also leads to dramatically cleaner source code.</li>
+
+<li>No subclasses required: To use CommandLine, you instantiate variables that
+correspond to the arguments that you would like to capture, you don't subclass a
+parser. This means that you don't have to write <b>any</b> boilerplate
+code.</li>
+
+<li>Globally accessible: Libraries can specify command line arguments that are
+automatically enabled in any tool that links to the library. This is possible
+because the application doesn't have to keep a list of arguments to pass to
+the parser. This also makes supporting <a href="#dynamicopts">dynamically
+loaded options</a> trivial.</li>
+
+<li>Cleaner: CommandLine supports enum and other types directly, meaning that
+there is less error and more security built into the library. You don't have to
+worry about whether your integral command line argument accidentally got
+assigned a value that is not valid for your enum type.</li>
+
+<li>Powerful: The CommandLine library supports many different types of
+arguments, from simple <a href="#boolparser">boolean flags</a> to <a
+href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a
+href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a
+href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of
+arguments</a>. This is possible because CommandLine is...</li>
+
+<li>Extensible: It is very simple to add a new argument type to CommandLine.
+Simply specify the parser that you want to use with the command line option when
+you declare it. <a href="#customparser">Custom parsers</a> are no problem.</li>
+
+<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
+that you, the user, have to do. For example, it automatically provides a
+<tt>-help</tt> option that shows the available command line options for your
+tool. Additionally, it does most of the basic correctness checking for
+you.</li>
+
+<li>Capable: The CommandLine library can handle lots of different forms of
+options often found in real programs. For example, <a
+href="#positional">positional</a> arguments, <tt>ls</tt> style <a
+href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls
+-lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a>
+options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a
+href="#cl::ConsumeAfter">interpreter style options</a>.</li>
+
+</ol>
+
+<p>This document will hopefully let you jump in and start using CommandLine in
+your utility quickly and painlessly. Additionally it should be a simple
+reference manual to figure out how stuff works. If it is failing in some area
+(or you want an extension to the library), nag the author, <a
+href="mailto:sabre at nondot.org">Chris Lattner</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="quickstart">Quick Start Guide</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section of the manual runs through a simple CommandLine'ification of a
+basic compiler tool. This is intended to show you how to jump into using the
+CommandLine library in your own program, and show you some of the cool things it
+can do.</p>
+
+<p>To start out, you need to include the CommandLine header file into your
+program:</p>
+
+<div class="doc_code"><pre>
+ #include "llvm/Support/CommandLine.h"
+</pre></div>
+
+<p>Additionally, you need to add this as the first line of your main
+program:</p>
+
+<div class="doc_code"><pre>
+int main(int argc, char **argv) {
+ <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
+ ...
+}
+</pre></div>
+
+<p>... which actually parses the arguments and fills in the variable
+declarations.</p>
+
+<p>Now that you are ready to support command line arguments, we need to tell the
+system which ones we want, and what type of arguments they are. The CommandLine
+library uses a declarative syntax to model command line arguments with the
+global variable declarations that capture the parsed values. This means that
+for every command line option that you would like to support, there should be a
+global variable declaration to capture the result. For example, in a compiler,
+we would like to support the Unix-standard '<tt>-o <filename></tt>' option
+to specify where to put the output. With the CommandLine library, this is
+represented like this:</p>
+
+<a name="value_desc_example"></a>
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));
+</pre></div>
+
+<p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
+capture the result of the "<tt>o</tt>" argument (first parameter). We specify
+that this is a simple scalar option by using the "<tt><a
+href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a
+href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
+that the data type that we are parsing is a string.</p>
+
+<p>The second and third parameters (which are optional) are used to specify what
+to output for the "<tt>-help</tt>" option. In this case, we get a line that
+looks like this:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options]
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ <b>-o <filename> - Specify output filename</b>
+</pre></div>
+
+<p>Because we specified that the command line option should parse using the
+<tt>string</tt> data type, the variable declared is automatically usable as a
+real string in all contexts that a normal C++ string object may be used. For
+example:</p>
+
+<div class="doc_code"><pre>
+ ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
+ ...
+</pre></div>
+
+<p>There are many different options that you can use to customize the command
+line option handling library, but the above example shows the general interface
+to these options. The options can be specified in any order, and are specified
+with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
+there are no positional dependencies to remember. The available options are
+discussed in detail in the <a href="#referenceguide">Reference Guide</a>.</p>
+
+<p>Continuing the example, we would like to have our compiler take an input
+filename as well as an output filename, but we do not want the input filename to
+be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
+style of argument, the CommandLine library allows for <a
+href="#positional">positional</a> arguments to be specified for the program.
+These positional arguments are filled with command line parameters that are not
+in option form. We use this feature like this:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
+</pre></div>
+
+<p>This declaration indicates that the first positional argument should be
+treated as the input filename. Here we use the <tt><a
+href="#cl::init">cl::init</a></tt> option to specify an initial value for the
+command line option, which is used if the option is not specified (if you do not
+specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then
+the default constructor for the data type is used to initialize the value).
+Command line options default to being optional, so if we would like to require
+that the user always specify an input filename, we would add the <tt><a
+href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
+<tt><a href="#cl::init">cl::init</a></tt> modifier, like this:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <b><a href="#cl::Required">cl::Required</a></b>);
+</pre></div>
+
+<p>Again, the CommandLine library does not require the options to be specified
+in any particular order, so the above declaration is equivalent to:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::Required">cl::Required</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"));
+</pre></div>
+
+<p>By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag,
+the CommandLine library will automatically issue an error if the argument is not
+specified, which shifts all of the command line option verification code out of
+your application into the library. This is just one example of how using flags
+can alter the default behaviour of the library, on a per-option basis. By
+adding one of the declarations above, the <tt>-help</tt> option synopsis is now
+extended to:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options] <b><input file></b>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+</pre></div>
+
+<p>... indicating that an input filename is expected.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="bool">Boolean Arguments</a>
+</h3>
+
+<div>
+
+<p>In addition to input and output filenames, we would like the compiler example
+to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
+a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for
+backwards compatibility with some of our users. We can support these by
+declaring options of boolean type like this:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable binary output on terminals</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
+</pre></div>
+
+<p>This does what you would expect: it declares three boolean variables
+("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
+options. Note that the "<tt>-q</tt>" option is specified with the "<a
+href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
+from being shown by the standard "<tt>-help</tt>" output (note that it is still
+shown in the "<tt>-help-hidden</tt>" output).</p>
+
+<p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
+for different data types. For example, in the string case, the argument passed
+to the option is copied literally into the content of the string variable... we
+obviously cannot do that in the boolean case, however, so we must use a smarter
+parser. In the case of the boolean parser, it allows no options (in which case
+it assigns the value of true to the variable), or it allows the values
+"<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
+following inputs:</p>
+
+<div class="doc_code"><pre>
+ compiler -f # No value, 'Force' == true
+ compiler -f=true # Value specified, 'Force' == true
+ compiler -f=TRUE # Value specified, 'Force' == true
+ compiler -f=FALSE # Value specified, 'Force' == false
+</pre></div>
+
+<p>... you get the idea. The <a href="#boolparser">bool parser</a> just turns
+the string values into boolean values, and rejects things like '<tt>compiler
+-f=foo</tt>'. Similarly, the <a href="#doubleparser">float</a>, <a
+href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work
+like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
+library calls to parse the string value into the specified data type.</p>
+
+<p>With the declarations above, "<tt>compiler -help</tt>" emits this:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ <b>-f - Enable binary output on terminals</b>
+ -o - Override output filename
+ <b>-quiet - Don't print informational messages</b>
+ -help - display available options (-help-hidden for more)
+</pre></div>
+
+<p>and "<tt>compiler -help-hidden</tt>" prints this:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -f - Enable binary output on terminals
+ -o - Override output filename
+ <b>-q - Don't print informational messages</b>
+ -quiet - Don't print informational messages
+ -help - display available options (-help-hidden for more)
+</pre></div>
+
+<p>This brief example has shown you how to use the '<tt><a
+href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
+arguments. In addition to simple scalar arguments, the CommandLine library also
+provides primitives to support CommandLine option <a href="#alias">aliases</a>,
+and <a href="#list">lists</a> of options.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="alias">Argument Aliases</a>
+</h3>
+
+<div>
+
+<p>So far, the example works well, except for the fact that we need to check the
+quiet condition like this now:</p>
+
+<div class="doc_code"><pre>
+...
+ if (!Quiet && !Quiet2) printInformationalMessage(...);
+...
+</pre></div>
+
+<p>... which is a real pain! Instead of defining two values for the same
+condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
+option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
+a value itself:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
+<a href="#cl::alias">cl::alias</a> QuietA("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Alias for -quiet</i>"), <a href="#cl::aliasopt">cl::aliasopt</a>(Quiet));
+</pre></div>
+
+<p>The third line (which is the only one we modified from above) defines a
+"<tt>-q</tt>" alias that updates the "<tt>Quiet</tt>" variable (as specified by
+the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
+specified. Because aliases do not hold state, the only thing the program has to
+query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is
+that they automatically hide themselves from the <tt>-help</tt> output
+(although, again, they are still visible in the <tt>-help-hidden
+output</tt>).</p>
+
+<p>Now the application code can simply use:</p>
+
+<div class="doc_code"><pre>
+...
+ if (!Quiet) printInformationalMessage(...);
+...
+</pre></div>
+
+<p>... which is much nicer! The "<tt><a href="#cl::alias">cl::alias</a></tt>"
+can be used to specify an alternative name for any variable type, and has many
+uses.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="onealternative">Selecting an alternative from a set of
+ possibilities</a>
+</h3>
+
+<div>
+
+<p>So far we have seen how the CommandLine library handles builtin types like
+<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
+things it doesn't know about, like enums or '<tt>int*</tt>'s?</p>
+
+<p>The answer is that it uses a table-driven generic parser (unless you specify
+your own parser, as described in the <a href="#extensionguide">Extension
+Guide</a>). This parser maps literal strings to whatever type is required, and
+requires you to tell it what this mapping should be.</p>
+
+<p>Let's say that we would like to add four optimization levels to our
+optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
+"<tt>-O1</tt>", and "<tt>-O2</tt>". We could easily implement this with boolean
+options like above, but there are several problems with this strategy:</p>
+
+<ol>
+<li>A user could specify more than one of the options at a time, for example,
+"<tt>compiler -O3 -O2</tt>". The CommandLine library would not be able to
+catch this erroneous input for us.</li>
+
+<li>We would have to test 4 different variables to see which ones are set.</li>
+
+<li>This doesn't map to the numeric levels that we want... so we cannot easily
+see if some level >= "<tt>-O1</tt>" is enabled.</li>
+
+</ol>
+
+<p>To cope with these problems, we can use an enum value, and have the
+CommandLine library fill it in with the appropriate level directly, which is
+used like this:</p>
+
+<div class="doc_code"><pre>
+enum OptLevel {
+ g, O1, O2, O3
+};
+
+<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
+ clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
+ clEnumVal(O2, "<i>Enable default optimizations</i>"),
+ clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
+ clEnumValEnd));
+
+...
+ if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
+...
+</pre></div>
+
+<p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
+"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
+that are listed in the declaration (Note that the declaration list must be
+terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
+library enforces
+that the user can only specify one of the options, and it ensure that only valid
+enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
+command line arguments matched the enum values. With this option added, our
+help output now is:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ <b>Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations</b>
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages
+</pre></div>
+
+<p>In this case, it is sort of awkward that flag names correspond directly to
+enum names, because we probably don't want a enum definition named "<tt>g</tt>"
+in our program. Because of this, we can alternatively write this example like
+this:</p>
+
+<div class="doc_code"><pre>
+enum OptLevel {
+ Debug, O1, O2, O3
+};
+
+<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
+ clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
+ clEnumVal(O2 , "<i>Enable default optimizations</i>"),
+ clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
+ clEnumValEnd));
+
+...
+ if (OptimizationLevel == Debug) outputDebugInfo(...);
+...
+</pre></div>
+
+<p>By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we
+can directly specify the name that the flag should get. In general a direct
+mapping is nice, but sometimes you can't or don't want to preserve the mapping,
+which is when you would use it.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="namedalternatives">Named Alternatives</a>
+</h3>
+
+<div>
+
+<p>Another useful argument form is a named alternative style. We shall use this
+style in our compiler to specify different debug levels that can be used.
+Instead of each debug level being its own switch, we want to support the
+following options, of which only one can be specified at a time:
+"<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
+"<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
+our optimization level flags, but we also specify an option name. For this
+case, the code looks like this:</p>
+
+<div class="doc_code"><pre>
+enum DebugLev {
+ nodebuginfo, quick, detailed
+};
+
+// Enable Debug Options to be specified on the command line
+<a href="#cl::opt">cl::opt</a><DebugLev> DebugLevel("<i>debug_level</i>", <a href="#cl::desc">cl::desc</a>("<i>Set the debugging level:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
+ clEnumVal(quick, "<i>enable quick debug information</i>"),
+ clEnumVal(detailed, "<i>enable detailed debug information</i>"),
+ clEnumValEnd));
+</pre></div>
+
+<p>This definition defines an enumerated command line variable of type "<tt>enum
+DebugLev</tt>", which works exactly the same way as before. The difference here
+is just the interface exposed to the user of your program and the help output by
+the "<tt>-help</tt>" option:</p>
+
+<div class="doc_code"><pre>
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ <b>-debug_level - Set the debugging level:
+ =none - disable debug information
+ =quick - enable quick debug information
+ =detailed - enable detailed debug information</b>
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages
+</pre></div>
+
+<p>Again, the only structural difference between the debug level declaration and
+the optimization level declaration is that the debug level declaration includes
+an option name (<tt>"debug_level"</tt>), which automatically changes how the
+library processes the argument. The CommandLine library supports both forms so
+that you can choose the form most appropriate for your application.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="list">Parsing a list of options</a>
+</h3>
+
+<div>
+
+<p>Now that we have the standard run-of-the-mill argument types out of the way,
+lets get a little wild and crazy. Lets say that we want our optimizer to accept
+a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
+might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
+this case, the order of the arguments and the number of appearances is very
+important. This is what the "<tt><a href="#cl::list">cl::list</a></tt>"
+template is for. First, start by defining an enum of the optimizations that you
+would like to perform:</p>
+
+<div class="doc_code"><pre>
+enum Opts {
+ // 'inline' is a C++ keyword, so name it 'inlining'
+ dce, constprop, inlining, strip
+};
+</pre></div>
+
+<p>Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::list">cl::list</a><Opts> OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+</pre></div>
+
+<p>This defines a variable that is conceptually of the type
+"<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
+vector methods:</p>
+
+<div class="doc_code"><pre>
+ for (unsigned i = 0; i != OptimizationList.size(); ++i)
+ switch (OptimizationList[i])
+ ...
+</pre></div>
+
+<p>... to iterate through the list of options specified.</p>
+
+<p>Note that the "<tt><a href="#cl::list">cl::list</a></tt>" template is
+completely general and may be used with any data types or other arguments that
+you can use with the "<tt><a href="#cl::opt">cl::opt</a></tt>" template. One
+especially useful way to use a list is to capture all of the positional
+arguments together if there may be more than one specified. In the case of a
+linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to
+capture them into a list. This is naturally specified as:</p>
+
+<div class="doc_code"><pre>
+...
+<a href="#cl::list">cl::list</a><std::string> InputFilenames(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<Input files>"), <a href="#cl::OneOrMore">cl::OneOrMore</a>);
+...
+</pre></div>
+
+<p>This variable works just like a "<tt>vector<string></tt>" object. As
+such, accessing the list is simple, just like above. In this example, we used
+the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the
+CommandLine library that it is an error if the user does not specify any
+<tt>.o</tt> files on our command line. Again, this just reduces the amount of
+checking we have to do.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="bits">Collecting options as a set of flags</a>
+</h3>
+
+<div>
+
+<p>Instead of collecting sets of options in a list, it is also possible to
+gather information for enum values in a <b>bit vector</b>. The representation used by
+the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
+integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
+position. 1 indicating that the enum was specified, 0 otherwise. As each
+specified value is parsed, the resulting enum's bit is set in the option's bit
+vector:</p>
+
+<div class="doc_code"><pre>
+ <i>bits</i> |= 1 << (unsigned)<i>enum</i>;
+</pre></div>
+
+<p>Options that are specified multiple times are redundant. Any instances after
+the first are discarded.</p>
+
+<p>Reworking the above list example, we could replace <a href="#list">
+<tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+</pre></div>
+
+<p>To test to see if <tt>constprop</tt> was specified, we can use the
+<tt>cl:bits::isSet</tt> function:</p>
+
+<div class="doc_code"><pre>
+ if (OptimizationBits.isSet(constprop)) {
+ ...
+ }
+</pre></div>
+
+<p>It's also possible to get the raw bit vector using the
+<tt>cl::bits::getBits</tt> function:</p>
+
+<div class="doc_code"><pre>
+ unsigned bits = OptimizationBits.getBits();
+</pre></div>
+
+<p>Finally, if external storage is used, then the location specified must be of
+<b>type</b> <tt>unsigned</tt>. In all other ways a <a
+href="#bits"><tt>cl::bits</tt></a> option is equivalent to a <a
+href="#list"> <tt>cl::list</tt></a> option.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="description">Adding freeform text to help output</a>
+</h3>
+
+<div>
+
+<p>As our program grows and becomes more mature, we may decide to put summary
+information about what it does into the help output. The help output is styled
+to look similar to a Unix <tt>man</tt> page, providing concise information about
+a program. Unix <tt>man</tt> pages, however often have a description about what
+the program does. To add this to your CommandLine program, simply pass a third
+argument to the <a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+call in main. This additional argument is then printed as the overview
+information for your program, allowing you to include any additional information
+that you want. For example:</p>
+
+<div class="doc_code"><pre>
+int main(int argc, char **argv) {
+ <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
+ " This program blah blah blah...\n");
+ ...
+}
+</pre></div>
+
+<p>would yield the help output:</p>
+
+<div class="doc_code"><pre>
+<b>OVERVIEW: CommandLine compiler example
+
+ This program blah blah blah...</b>
+
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ ...
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+</pre></div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="referenceguide">Reference Guide</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Now that you know the basics of how to use the CommandLine library, this
+section will give you the detailed information you need to tune how command line
+options work, as well as information on more "advanced" command line option
+processing capabilities.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="positional">Positional Arguments</a>
+</h3>
+
+<div>
+
+<p>Positional arguments are those arguments that are not named, and are not
+specified with a hyphen. Positional arguments should be used when an option is
+specified by its position alone. For example, the standard Unix <tt>grep</tt>
+tool takes a regular expression argument, and an optional filename to search
+through (which defaults to standard input if a filename is not specified).
+Using the CommandLine library, this would be specified as:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> Regex (<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><regular expression></i>"), <a href="#cl::Required">cl::Required</a>);
+<a href="#cl::opt">cl::opt</a><string> Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
+</pre></div>
+
+<p>Given these two option declarations, the <tt>-help</tt> output for our grep
+replacement would look like this:</p>
+
+<div class="doc_code"><pre>
+USAGE: spiffygrep [options] <b><regular expression> <input file></b>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+</pre></div>
+
+<p>... and the resultant program could be used just like the standard
+<tt>grep</tt> tool.</p>
+
+<p>Positional arguments are sorted by their order of construction. This means
+that command line options will be ordered according to how they are listed in a
+.cpp file, but will not have an ordering defined if the positional arguments
+are defined in multiple .cpp files. The fix for this problem is simply to
+define all of your positional arguments in one .cpp file.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="--">Specifying positional options with hyphens</a>
+</h4>
+
+<div>
+
+<p>Sometimes you may want to specify a value to your positional argument that
+starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
+first, you will have trouble doing this, because it will try to find an argument
+named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
+Note that the system <tt>grep</tt> has the same problem:</p>
+
+<div class="doc_code"><pre>
+ $ spiffygrep '-foo' test.txt
+ Unknown command line argument '-foo'. Try: spiffygrep -help'
+
+ $ grep '-foo' test.txt
+ grep: illegal option -- f
+ grep: illegal option -- o
+ grep: illegal option -- o
+ Usage: grep -hblcnsviw pattern file . . .
+</pre></div>
+
+<p>The solution for this problem is the same for both your tool and the system
+version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on
+the command line, it is telling the program that all options after the
+'<tt>--</tt>' should be treated as positional arguments, not options. Thus, we
+can use it like this:</p>
+
+<div class="doc_code"><pre>
+ $ spiffygrep -- -foo test.txt
+ ...output...
+</pre></div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="getPosition">Determining absolute position with getPosition()</a>
+</h4>
+<div>
+ <p>Sometimes an option can affect or modify the meaning of another option. For
+ example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
+ <tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
+ the file to be interpreted as if it contained source code in language
+ <tt>LANG</tt>. In order to handle this properly, you need to know the
+ absolute position of each argument, especially those in lists, so their
+ interaction(s) can be applied correctly. This is also useful for options like
+ <tt>-llibname</tt> which is actually a positional argument that starts with
+ a dash.</p>
+ <p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
+ that interact in some way. To ensure the correct interaction, you can use the
+ <tt>cl::list::getPosition(optnum)</tt> method. This method returns the
+ absolute position (as found on the command line) of the <tt>optnum</tt>
+ item in the <tt>cl::list</tt>.</p>
+ <p>The idiom for usage is like this:</p>
+
+ <div class="doc_code"><pre>
+ static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
+ static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
+
+ int main(int argc, char**argv) {
+ // ...
+ std::vector<std::string>::iterator fileIt = Files.begin();
+ std::vector<std::string>::iterator libIt = Libraries.begin();
+ unsigned libPos = 0, filePos = 0;
+ while ( 1 ) {
+ if ( libIt != Libraries.end() )
+ libPos = Libraries.getPosition( libIt - Libraries.begin() );
+ else
+ libPos = 0;
+ if ( fileIt != Files.end() )
+ filePos = Files.getPosition( fileIt - Files.begin() );
+ else
+ filePos = 0;
+
+ if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {
+ // Source File Is next
+ ++fileIt;
+ }
+ else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {
+ // Library is next
+ ++libIt;
+ }
+ else
+ break; // we're done with the list
+ }
+ }</pre></div>
+
+ <p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
+ <tt>unsigned getPosition()</tt> option that will provide the absolute position
+ of that option. You can apply the same approach as above with a
+ <tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
+used to construct programs that use "interpreter style" option processing. With
+this style of option processing, all arguments specified after the last
+positional argument are treated as special interpreter arguments that are not
+interpreted by the command line argument.</p>
+
+<p>As a concrete example, lets say we are developing a replacement for the
+standard Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first
+you specify options to the shell itself (like <tt>-x</tt> which turns on trace
+output), then you specify the name of the script to run, then you specify
+arguments to the script. These arguments to the script are parsed by the Bourne
+shell command line option processor, but are not interpreted as options to the
+shell itself. Using the CommandLine library, we would specify this as:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::opt">cl::opt</a><string> Script(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input script></i>"), <a href="#cl::init">cl::init</a>("-"));
+<a href="#cl::list">cl::list</a><string> Argv(<a href="#cl::ConsumeAfter">cl::ConsumeAfter</a>, <a href="#cl::desc">cl::desc</a>("<i><program arguments>...</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
+</pre></div>
+
+<p>which automatically provides the help output:</p>
+
+<div class="doc_code"><pre>
+USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ <b>-x - Enable trace output</b>
+</pre></div>
+
+<p>At runtime, if we run our new shell replacement as `<tt>spiffysh -x test.sh
+-a -x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
+<tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
+<tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because they
+were specified after the last positional argument (which is the script
+name).</p>
+
+<p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can
+be specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified
+per program, there must be at least one <a href="#positional">positional
+argument</a> specified, there must not be any <a href="#cl::list">cl::list</a>
+positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a
+href="#cl::list">cl::list</a> option.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="storage">Internal vs External Storage</a>
+</h3>
+
+<div>
+
+<p>By default, all command line options automatically hold the value that they
+parse from the command line. This is very convenient in the common case,
+especially when combined with the ability to define command line options in the
+files that use them. This is called the internal storage model.</p>
+
+<p>Sometimes, however, it is nice to separate the command line option processing
+code from the storage of the value parsed. For example, lets say that we have a
+'<tt>-debug</tt>' option that we would like to use to enable debug information
+across the entire body of our program. In this case, the boolean value
+controlling the debug code should be globally accessible (in a header file, for
+example) yet the command line option processing code should not be exposed to
+all of these clients (requiring lots of .cpp files to #include
+<tt>CommandLine.h</tt>).</p>
+
+<p>To do this, set up your .h file with your option, like this for example:</p>
+
+<div class="doc_code">
+<pre>
+<i>// DebugFlag.h - Get access to the '-debug' command line option
+//
+
+// DebugFlag - This boolean is set to true if the '-debug' command line option
+// is specified. This should probably not be referenced directly, instead, use
+// the DEBUG macro below.
+//</i>
+extern bool DebugFlag;
+
+<i>// DEBUG macro - This macro should be used by code to emit debug information.
+// In the '-debug' option is specified on the command line, and if this is a
+// debug build, then the code specified as the option to the macro will be
+// executed. Otherwise it will not be.</i>
+<span class="doc_hilite">#ifdef NDEBUG
+#define DEBUG(X)
+#else
+#define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
+<span class="doc_hilite">#endif</span>
+</pre>
+</div>
+
+<p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
+<tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
+set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass
+an additional argument to our command line argument processor, and we specify
+where to fill in with the <a href="#cl::location">cl::location</a>
+attribute:</p>
+
+<div class="doc_code">
+<pre>
+bool DebugFlag; <i>// the actual value</i>
+static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
+Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>, <a href="#cl::location">cl::location</a>(DebugFlag));
+</pre>
+</div>
+
+<p>In the above example, we specify "<tt>true</tt>" as the second argument to
+the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
+template should not maintain a copy of the value itself. In addition to this,
+we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
+that <tt>DebugFlag</tt> is automatically set.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="attributes">Option Attributes</a>
+</h3>
+
+<div>
+
+<p>This section describes the basic attributes that you can specify on
+options.</p>
+
+<ul>
+
+<li>The option name attribute (which is required for all options, except <a
+href="#positional">positional options</a>) specifies what the option name is.
+This option is specified in simple double quotes:
+
+<pre>
+<a href="#cl::opt">cl::opt</a><<b>bool</b>> Quiet("<i>quiet</i>");
+</pre>
+
+</li>
+
+<li><a name="cl::desc">The <b><tt>cl::desc</tt></b></a> attribute specifies a
+description for the option to be shown in the <tt>-help</tt> output for the
+program.</li>
+
+<li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute
+specifies a string that can be used to fine tune the <tt>-help</tt> output for
+a command line option. Look <a href="#value_desc_example">here</a> for an
+example.</li>
+
+<li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
+initial value for a <a href="#cl::opt">scalar</a> option. If this attribute is
+not specified then the command line option value defaults to the value created
+by the default constructor for the type. <b>Warning</b>: If you specify both
+<b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
+you must specify <b><tt>cl::location</tt></b> first, so that when the
+command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the
+initial value. (You will get an error at runtime if you don't put them in
+the right order.)</li>
+
+<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where
+to store the value for a parsed command line option if using external storage.
+See the section on <a href="#storage">Internal vs External Storage</a> for more
+information.</li>
+
+<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
+specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
+an alias for.</li>
+
+<li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
+the string-to-value mapping to be used by the generic parser. It takes a
+<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
+that
+specify the option name, the value mapped to, and the description shown in the
+<tt>-help</tt> for the tool. Because the generic parser is used most
+frequently with enum values, two macros are often useful:
+
+<ol>
+
+<li><a name="clEnumVal">The <b><tt>clEnumVal</tt></b></a> macro is used as a
+nice simple way to specify a triplet for an enum. This macro automatically
+makes the option name be the same as the enum name. The first option to the
+macro is the enum, the second is the description for the command line
+option.</li>
+
+<li><a name="clEnumValN">The <b><tt>clEnumValN</tt></b></a> macro is used to
+specify macro options where the option name doesn't equal the enum name. For
+this macro, the first argument is the enum value, the second is the flag name,
+and the second is the description.</li>
+
+</ol>
+
+You will get a compile time error if you try to use cl::values with a parser
+that does not support it.</li>
+
+<li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a>
+attribute specifies that this option takes has multiple values
+(example: <tt>-sectalign segname sectname sectvalue</tt>). This
+attribute takes one unsigned argument - the number of values for the
+option. This attribute is valid only on <tt>cl::list</tt> options (and
+will fail with compile error if you try to use it with other option
+types). It is allowed to use all of the usual modifiers on
+multi-valued options (besides <tt>cl::ValueDisallowed</tt>,
+obviously).</li>
+
+</ul>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="modifiers">Option Modifiers</a>
+</h3>
+
+<div>
+
+<p>Option modifiers are the flags and expressions that you pass into the
+constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
+tweak how options are parsed and how <tt>-help</tt> output is generated to fit
+your application well.</p>
+
+<p>These options fall into five main categories:</p>
+
+<ol>
+<li><a href="#hiding">Hiding an option from <tt>-help</tt> output</a></li>
+<li><a href="#numoccurrences">Controlling the number of occurrences
+ required and allowed</a></li>
+<li><a href="#valrequired">Controlling whether or not a value must be
+ specified</a></li>
+<li><a href="#formatting">Controlling other formatting options</a></li>
+<li><a href="#misc">Miscellaneous option modifiers</a></li>
+</ol>
+
+<p>It is not possible to specify two options from the same category (you'll get
+a runtime error) to a single option, except for options in the miscellaneous
+category. The CommandLine library specifies defaults for all of these settings
+that are the most useful in practice and the most common, which mean that you
+usually shouldn't have to worry about these.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="hiding">Hiding an option from <tt>-help</tt> output</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
+<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
+appears in the <tt>-help</tt> and <tt>-help-hidden</tt> output for the
+compiled program:</p>
+
+<ul>
+
+<li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
+(which is the default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+href="#cl::list">cl::list</a></tt> options) indicates the option is to appear
+in both help listings.</li>
+
+<li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the
+default for <tt><a href="#cl::alias">cl::alias</a></tt> options) indicates that
+the option should not appear in the <tt>-help</tt> output, but should appear in
+the <tt>-help-hidden</tt> output.</li>
+
+<li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier
+indicates that the option should not appear in any help output.</li>
+
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="numoccurrences">Controlling the number of occurrences required and
+ allowed</a>
+</h4>
+
+<div>
+
+<p>This group of options is used to control how many time an option is allowed
+(or required) to be specified on the command line of your program. Specifying a
+value for this setting allows the CommandLine library to do error checking for
+you.</p>
+
+<p>The allowed values for this option group are:</p>
+
+<ul>
+
+<li><a name="cl::Optional">The <b><tt>cl::Optional</tt></b></a> modifier (which
+is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
+href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
+allow either zero or one occurrence of the option to be specified.</li>
+
+<li><a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b></a> modifier
+(which is the default for the <tt><a href="#cl::list">cl::list</a></tt> class)
+indicates that your program will allow the option to be specified zero or more
+times.</li>
+
+<li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier
+indicates that the specified option must be specified exactly one time.</li>
+
+<li><a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b></a> modifier
+indicates that the option must be specified at least one time.</li>
+
+<li>The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
+href="#positional">Positional arguments section</a>.</li>
+
+</ul>
+
+<p>If an option is not specified, then the value of the option is equal to the
+value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If
+the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
+option value is initialized with the default constructor for the data type.</p>
+
+<p>If an option is specified multiple times for an option of the <tt><a
+href="#cl::opt">cl::opt</a></tt> class, only the last value will be
+retained.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="valrequired">Controlling whether or not a value must be specified</a>
+</h4>
+
+<div>
+
+<p>This group of options is used to control whether or not the option allows a
+value to be present. In the case of the CommandLine library, a value is either
+specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
+string (e.g. '<tt>-o a.out</tt>').</p>
+
+<p>The allowed values for this option group are:</p>
+
+<ul>
+
+<li><a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b></a> modifier
+(which is the default for <tt>bool</tt> typed options) specifies that it is
+acceptable to have a value, or not. A boolean argument can be enabled just by
+appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
+If an option is specified with this mode, it is illegal for the value to be
+provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To
+get this behavior, you must use the <a
+href="#cl::ValueRequired">cl::ValueRequired</a> modifier.</li>
+
+<li><a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b></a> modifier
+(which is the default for all other types except for <a
+href="#onealternative">unnamed alternatives using the generic parser</a>)
+specifies that a value must be provided. This mode informs the command line
+library that if an option is not provides with an equal sign, that the next
+argument provided must be the value. This allows things like '<tt>-o
+a.out</tt>' to work.</li>
+
+<li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a>
+modifier (which is the default for <a href="#onealternative">unnamed
+alternatives using the generic parser</a>) indicates that it is a runtime error
+for the user to specify a value. This can be provided to disallow users from
+providing options to boolean options (like '<tt>-foo=true</tt>').</li>
+
+</ul>
+
+<p>In general, the default values for this option group work just like you would
+want them to. As mentioned above, you can specify the <a
+href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
+argument to restrict your command line parser. These options are mostly useful
+when <a href="#extensionguide">extending the library</a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="formatting">Controlling other formatting options</a>
+</h4>
+
+<div>
+
+<p>The formatting option group is used to specify that the command line option
+has special abilities and is otherwise different from other command line
+arguments. As usual, you can only specify one of these arguments at most.</p>
+
+<ul>
+
+<li><a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b></a>
+modifier (which is the default all options) specifies that this option is
+"normal".</li>
+
+<li><a name="cl::Positional">The <b><tt>cl::Positional</tt></b></a> modifier
+specifies that this is a positional argument that does not have a command line
+option associated with it. See the <a href="#positional">Positional
+Arguments</a> section for more information.</li>
+
+<li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
+specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
+
+<li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
+that this option prefixes its value. With 'Prefix' options, the equal sign does
+not separate the value from the option name specified. Instead, the value is
+everything after the prefix, including any equal sign if present. This is useful
+for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
+linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
+'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
+options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
+modifier added to allow the CommandLine library to recognize them. Note that
+<b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
+<b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
+specified.</li>
+
+<li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
+to implement Unix-style tools (like <tt>ls</tt>) that have lots of single letter
+arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
+command actually enables four different options, all of which are single
+letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
+options cannot have values.</li>
+
+</ul>
+
+<p>The CommandLine library does not restrict how you use the <b><tt><a
+href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
+href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
+specify ambiguous argument settings. Thus, it is possible to have multiple
+letter options that are prefix or grouping options, and they will still work as
+designed.</p>
+
+<p>To do this, the CommandLine library uses a greedy algorithm to parse the
+input option into (potentially multiple) prefix and grouping options. The
+strategy basically looks like this:</p>
+
+<div class="doc_code"><tt>parse(string OrigInput) {</tt>
+
+<ol>
+<li><tt>string input = OrigInput;</tt>
+<li><tt>if (isOption(input)) return getOption(input).parse();</tt> <i>// Normal option</i>
+<li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt> <i>// Remove the last letter</i>
+<li><tt>if (input.empty()) return error();</tt> <i>// No matching option</i>
+<li><tt>if (getOption(input).isPrefix())<br>
+ return getOption(input).parse(input);</tt>
+<li><tt>while (!input.empty()) { <i>// Must be grouping options</i><br>
+ getOption(input).parse();<br>
+ OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
+ input = OrigInput;<br>
+ while (!isOption(input) && !input.empty()) input.pop_back();<br>
+}</tt>
+<li><tt>if (!OrigInput.empty()) error();</tt></li>
+</ol>
+
+<p><tt>}</tt></p>
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="misc">Miscellaneous option modifiers</a>
+</h4>
+
+<div>
+
+<p>The miscellaneous option modifiers are the only flags where you can specify
+more than one flag from the set: they are not mutually exclusive. These flags
+specify boolean properties that modify the option.</p>
+
+<ul>
+
+<li><a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b></a> modifier
+indicates that any commas specified for an option's value should be used to
+split the value up into multiple values for the option. For example, these two
+options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
+"<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>". This option only
+makes sense to be used in a case where the option is allowed to accept one or
+more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
+
+<li><a name="cl::PositionalEatsArgs">The
+<b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
+positional arguments, and only makes sense for lists) indicates that positional
+argument should consume any strings after it (including strings that start with
+a "-") up until another recognized positional argument. For example, if you
+have two "eating" positional arguments, "<tt>pos1</tt>" and "<tt>pos2</tt>", the
+string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
+-baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
+"<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
+
+<li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
+used to handle unknown options. If there is at least one option with
+<tt>cl::Sink</tt> modifier specified, the parser passes
+unrecognized option strings to it as values instead of signaling an
+error. As with <tt>cl::CommaSeparated</tt>, this modifier
+only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
+
+</ul>
+
+<p>So far, these are the only three miscellaneous option modifiers.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="response">Response files</a>
+</h4>
+
+<div>
+
+<p>Some systems, such as certain variants of Microsoft Windows and
+some older Unices have a relatively low limit on command-line
+length. It is therefore customary to use the so-called 'response
+files' to circumvent this restriction. These files are mentioned on
+the command-line (using the "@file") syntax. The program reads these
+files and inserts the contents into argv, thereby working around the
+command-line length limits. Response files are enabled by an optional
+fourth argument to
+<a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
+and
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="toplevel">Top-Level Classes and Functions</a>
+</h3>
+
+<div>
+
+<p>Despite all of the built-in flexibility, the CommandLine option library
+really only consists of one function (<a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
+and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
+href="#cl::list"><tt>cl::list</tt></a>, and <a
+href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
+classes in detail.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
+ function</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
+directly from <tt>main</tt>, and is used to fill in the values of all of the
+command line option variables once <tt>argc</tt> and <tt>argv</tt> are
+available.</p>
+
+<p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
+(<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
+which holds <a href="#description">additional extra text</a> to emit when the
+<tt>-help</tt> option is invoked, and a fourth boolean parameter that enables
+<a href="#response">response files</a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
+ function</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
+as <a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
+except that it is designed to take values for options from an environment
+variable, for those cases in which reading the command line is not convenient or
+desired. It fills in the values of all the command line option variables just
+like <a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+does.</p>
+
+<p>It takes four parameters: the name of the program (since <tt>argv</tt> may
+not be available, it can't just look in <tt>argv[0]</tt>), the name of the
+environment variable to examine, the optional
+<a href="#description">additional extra text</a> to emit when the
+<tt>-help</tt> option is invoked, and the boolean
+switch that controls whether <a href="#response">response files</a>
+should be read.</p>
+
+<p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
+variable's value up into words and then process them using
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+<b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
+quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
+be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
+which is different from what you would get from the shell with the same
+input.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
+directly from <tt>main</tt> and <i>before</i>
+<tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
+for a function to be called in response to the <tt>--version</tt> option instead
+of having the <tt>CommandLine</tt> library print out the usual version string
+for LLVM. This is useful for programs that are not part of LLVM but wish to use
+the <tt>CommandLine</tt> facilities. Such programs should just define a small
+function that takes no arguments and returns <tt>void</tt> and that prints out
+whatever version information is appropriate for the program. Pass the address
+of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
+called when the <tt>--version</tt> option is given by the user.</p>
+
+</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::opt">The <tt>cl::opt</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
+options, and is the one used most of the time. It is a templated class which
+can take up to three arguments (all except for the first have default values
+though):</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> opt;
+}
+</pre></div>
+
+<p>The first template argument specifies what underlying data type the command
+line argument is, and is used to select a default parser implementation. The
+second template argument is used to specify whether the option should contain
+the storage for the option (the default) or whether external storage should be
+used to contain the value parsed for the option (see <a href="#storage">Internal
+vs External Storage</a> for more information).</p>
+
+<p>The third template argument specifies which parser to use. The default value
+selects an instantiation of the <tt>parser</tt> class based on the underlying
+data type of the option. In general, this default works well for most
+applications, so this option is only used when using a <a
+href="#customparser">custom parser</a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::list">The <tt>cl::list</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::list</tt> class is the class used to represent a list of command
+line options. It too is a templated class which can take up to three
+arguments:</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> list;
+}
+</pre></div>
+
+<p>This class works the exact same as the <a
+href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
+the <b>type</b> of the external storage, not a boolean value. For this class,
+the marker type '<tt>bool</tt>' is used to indicate that internal storage should
+be used.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::bits">The <tt>cl::bits</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::bits</tt> class is the class used to represent a list of command
+line options in the form of a bit vector. It is also a templated class which
+can take up to three arguments:</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> bits;
+}
+</pre></div>
+
+<p>This class works the exact same as the <a
+href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
+must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::alias">The <tt>cl::alias</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
+aliases for other arguments.</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>class</b> alias;
+}
+</pre></div>
+
+<p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
+used to specify which option this is an alias for. Alias arguments default to
+being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do
+the conversion from string to data.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
+help text to be printed out for the <tt>-help</tt> option.</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>struct</b> extrahelp;
+}
+</pre></div>
+
+<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
+parameter to the constructor. The text passed to the constructor will be printed
+at the bottom of the help message, verbatim. Note that multiple
+<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
+your tool needs to print additional help information, put all that help into a
+single <tt>cl::extrahelp</tt> instance.</p>
+<p>For example:</p>
+<div class="doc_code"><pre>
+ cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
+</pre></div>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="builtinparsers">Builtin parsers</a>
+</h3>
+
+<div>
+
+<p>Parsers control how the string value taken from the command line is
+translated into a typed value, suitable for use in a C++ program. By default,
+the CommandLine library uses an instance of <tt>parser<type></tt> if the
+command line option specifies that it uses values of type '<tt>type</tt>'.
+Because of this, custom option processing is specified with specializations of
+the '<tt>parser</tt>' class.</p>
+
+<p>The CommandLine library provides the following builtin parser
+specializations, which are sufficient for most applications. It can, however,
+also be extended to work with new data types and new ways of interpreting the
+same data. See the <a href="#customparser">Writing a Custom Parser</a> for more
+details on this type of library extension.</p>
+
+<ul>
+
+<li><a name="genericparser">The <b>generic <tt>parser<t></tt> parser</b></a>
+can be used to map strings values to any data type, through the use of the <a
+href="#cl::values">cl::values</a> property, which specifies the mapping
+information. The most common use of this parser is for parsing enum values,
+which allows you to use the CommandLine library for all of the error checking to
+make sure that only valid enum values are specified (as opposed to accepting
+arbitrary strings). Despite this, however, the generic parser class can be used
+for any data type.</li>
+
+<li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b></a>
+is used to convert boolean strings to a boolean value. Currently accepted
+strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
+"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
+
+<li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
+ specialization</b></a> is used for cases where the value is boolean,
+but we also need to know whether the option was specified at all. boolOrDefault
+is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
+the same strings as <b><tt>parser<bool></tt></b>.</li>
+
+<li><a name="stringparser">The <b><tt>parser<string></tt>
+specialization</b></a> simply stores the parsed string into the string value
+specified. No conversion or modification of the data is performed.</li>
+
+<li><a name="intparser">The <b><tt>parser<int></tt> specialization</b></a>
+uses the C <tt>strtol</tt> function to parse the string input. As such, it will
+accept a decimal number (with an optional '+' or '-' prefix) which must start
+with a non-zero digit. It accepts octal numbers, which are identified with a
+'<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
+'<tt>0x</tt>' or '<tt>0X</tt>'.</li>
+
+<li><a name="doubleparser">The <b><tt>parser<double></tt></b></a> and
+<b><tt>parser<float></tt> specializations</b> use the standard C
+<tt>strtod</tt> function to convert floating point strings into floating point
+values. As such, a broad range of string formats is supported, including
+exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
+</li>
+
+</ul>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="extensionguide">Extension Guide</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility. This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="customparser">Writing a custom parser</a>
+</h3>
+
+<div>
+
+<p>One of the simplest and most common extensions is the use of a custom parser.
+As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
+of the CommandLine library that turns string input from the user into a
+particular parsed data type, validating the input in the process.</p>
+
+<p>There are two ways to use a new parser:</p>
+
+<ol>
+
+<li>
+
+<p>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
+your custom data type.<p>
+
+<p>This approach has the advantage that users of your custom data type will
+automatically use your custom parser whenever they define an option with a value
+type of your data type. The disadvantage of this approach is that it doesn't
+work if your fundamental data type is something that is already supported.</p>
+
+</li>
+
+<li>
+
+<p>Write an independent class, using it explicitly from options that need
+it.</p>
+
+<p>This approach works well in situations where you would line to parse an
+option using special syntax for a not-very-special data-type. The drawback of
+this approach is that users of your parser have to be aware that they are using
+your parser instead of the builtin ones.</p>
+
+</li>
+
+</ol>
+
+<p>To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size. For example, we
+would like to parse "102kb", "41M", "1G" into the appropriate integer value. In
+this case, the underlying data type we want to parse into is
+'<tt>unsigned</tt>'. We choose approach #2 above because we don't want to make
+this the default for all <tt>unsigned</tt> options.</p>
+
+<p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
+
+<div class="doc_code"><pre>
+<b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser<<b>unsigned</b>> {
+ <i>// parse - Return true on error.</i>
+ <b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
+ <b>unsigned</b> &Val);
+};
+</pre></div>
+
+<p>Our new class inherits from the <tt>cl::basic_parser</tt> template class to
+fill in the default, boiler plate code for us. We give it the data type that
+we parse into, the last argument to the <tt>parse</tt> method, so that clients of
+our custom parser know what object type to pass in to the parse method. (Here we
+declare that we parse into '<tt>unsigned</tt>' variables.)</p>
+
+<p>For most purposes, the only method that must be implemented in a custom
+parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called
+whenever the option is invoked, passing in the option itself, the option name,
+the string to parse, and a reference to a return value. If the string to parse
+is not well-formed, the parser should output an error message and return true.
+Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In
+our example, we implement <tt>parse</tt> as:</p>
+
+<div class="doc_code"><pre>
+<b>bool</b> FileSizeParser::parse(cl::Option &O, <b>const char</b> *ArgName,
+ <b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
+ <b>const char</b> *ArgStart = Arg.c_str();
+ <b>char</b> *End;
+
+ <i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
+ Val = (unsigned)strtol(ArgStart, &End, 0);
+
+ <b>while</b> (1) {
+ <b>switch</b> (*End++) {
+ <b>case</b> 0: <b>return</b> false; <i>// No error</i>
+ <b>case</b> 'i': <i>// Ignore the 'i' in KiB if people use that</i>
+ <b>case</b> 'b': <b>case</b> 'B': <i>// Ignore B suffix</i>
+ <b>break</b>;
+
+ <b>case</b> 'g': <b>case</b> 'G': Val *= 1024*1024*1024; <b>break</b>;
+ <b>case</b> 'm': <b>case</b> 'M': Val *= 1024*1024; <b>break</b>;
+ <b>case</b> 'k': <b>case</b> 'K': Val *= 1024; <b>break</b>;
+
+ default:
+ <i>// Print an error message if unrecognized character!</i>
+ <b>return</b> O.error("'" + Arg + "' value invalid for file size argument!");
+ }
+ }
+}
+</pre></div>
+
+<p>This function implements a very simple parser for the kinds of strings we are
+interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
+example), it is good enough for this example. Note that we use the option
+itself to print out the error message (the <tt>error</tt> method always returns
+true) in order to get a nice error message (shown below). Now that we have our
+parser class, we can use it like this:</p>
+
+<div class="doc_code"><pre>
+<b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
+MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
+ <a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
+</pre></div>
+
+<p>Which adds this to the output of our program:</p>
+
+<div class="doc_code"><pre>
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ ...
+ <b>-max-file-size=<size> - Maximum file size to accept</b>
+</pre></div>
+
+<p>And we can test that our parse works correctly now (the test program just
+prints out the max-file-size argument value):</p>
+
+<div class="doc_code"><pre>
+$ ./test
+MFS: 0
+$ ./test -max-file-size=123MB
+MFS: 128974848
+$ ./test -max-file-size=3G
+MFS: 3221225472
+$ ./test -max-file-size=dog
+-max-file-size option: 'dog' value invalid for file size argument!
+</pre></div>
+
+<p>It looks like it works. The error message that we get is nice and helpful,
+and we seem to accept reasonable file sizes. This wraps up the "custom parser"
+tutorial.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="explotingexternal">Exploiting external storage</a>
+</h3>
+
+<div>
+ <p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
+ will automatically be included in any program that links with that library.
+ This is a feature. However, sometimes it is necessary to know the value of the
+ command line option outside of the library. In these cases the library does or
+ should provide an external storage location that is accessible to users of the
+ library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
+ <tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
+ flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
+
+<p>TODO: complete this section</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="dynamicopts">Dynamically adding command line options</a>
+</h3>
+
+<div>
+
+<p>TODO: fill in this section</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-04-22 19:30:22 -0500 (Fri, 22 Apr 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/CompilerWriterInfo.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/3.0/docs/CompilerWriterInfo.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,279 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Architecture/platform information for compiler writers</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<body>
+
+<h1>
+ Architecture/platform information for compiler writers
+</h1>
+
+<div class="doc_warning">
+ <p>Note: This document is a work-in-progress. Additions and clarifications
+ are welcome.</p>
+</div>
+
+<ol>
+ <li><a href="#hw">Hardware</a>
+ <ol>
+ <li><a href="#alpha">Alpha</a></li>
+ <li><a href="#arm">ARM</a></li>
+ <li><a href="#ia64">Itanium</a></li>
+ <li><a href="#mips">MIPS</a></li>
+ <li><a href="#ppc">PowerPC</a></li>
+ <li><a href="#sparc">SPARC</a></li>
+ <li><a href="#x86">X86</a></li>
+ <li><a href="#other">Other lists</a></li>
+ </ol></li>
+ <li><a href="#abi">Application Binary Interface (ABI)</a>
+ <ol>
+ <li><a href="#linux">Linux</a></li>
+ <li><a href="#osx">OS X</a></li>
+ </ol></li>
+ <li><a href="#misc">Miscellaneous resources</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Compiled by <a href="http://misha.brukman.net">Misha Brukman</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="hw">Hardware</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<!-- ======================================================================= -->
+<h3><a name="alpha">Alpha</a></h3>
+
+<div>
+<ul>
+<li><a
+href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-library.html">Alpha manuals</a>
+</li>
+</ul>
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="arm">ARM</a></h3>
+
+<div>
+<ul>
+<li><a href="http://www.arm.com/documentation/">ARM documentation</a>
+(<a href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor
+Cores</a>)</li>
+<li><a href="http://www.arm.com/products/DevTools/ABI.html">ABI</a></li>
+</ul>
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="ia64">Itanium (ia64)</a></h3>
+
+<div>
+<ul>
+<li><a
+href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a>
+</li>
+</ul>
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="mips">MIPS</a></h3>
+
+<div>
+<ul>
+<li><a
+href="http://mips.com/content/Documentation/MIPSDocumentation/ProcessorArchitecture/doclibrary">MIPS
+Processor Architecture</a></li>
+</ul>
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="ppc">PowerPC</a></h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>IBM - Official manuals and docs</h4>
+
+<div>
+
+<ul>
+<li><a
+href="http://www-106.ibm.com/developerworks/eserver/articles/archguide.html">PowerPC
+Architecture Book</a>
+<ul>
+ <li>Book I: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub1.pdf">PowerPC
+ User Instruction Set Architecture</a></li>
+ <li>Book II: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub2.pdf">PowerPC
+ Virtual Environment Architecture</a></li>
+ <li>Book III: <a
+ href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub3.pdf">PowerPC
+ Operating Environment Architecture</a></li>
+</ul></li>
+<li><a
+href="http://www-3.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC
+Compiler Writer's Guide</a></li>
+<li><A
+href="http://www-3.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC
+Processor Manuals</a></li>
+<li><a
+href="http://www-106.ibm.com/developerworks/linux/library/l-powarch/">Intro to
+PowerPC architecture</a></li>
+<li><a href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly reference</a></li>
+</ul>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>Other documents, collections, notes</h4>
+
+<div>
+
+<ul>
+<li><a href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
+<li><a href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64
+alignment of long doubles (from GCC)</a></li>
+<li><a href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long
+branch stubs for powerpc64-linux (from binutils)</a></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="sparc">SPARC</a></h3>
+
+<div>
+
+<ul>
+<li><a href="http://www.sparc.org/resource.htm">SPARC resources</a></li>
+<li><a href="http://www.sparc.org/standards.html">SPARC standards</a></li>
+</ul>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="x86">X86</a></h3>
+
+<div>
+
+<!-- _______________________________________________________________________ -->
+<h4>AMD - Official manuals and docs</h4>
+
+<div>
+<ul>
+<li><a
+href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li>
+<li><a href="http://www.x86-64.org/documentation">X86-64 ABI</a></li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>Intel - Official manuals and docs</h4>
+
+<div>
+<ul>
+<li><a
+href="http://developer.intel.com/design/pentium4/manuals/index_new.htm">IA-32
+manuals</a></li>
+<li><a
+href="http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs">Intel
+Itanium documentation</a></li>
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>Other x86-specific information</h4>
+
+<div>
+<ul>
+<li><a href="http://www.agner.org/assem/calling_conventions.pdf">Calling
+conventions for different C++ compilers and operating systems</a></li>
+</ul>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="other">Other relevant lists</a></h3>
+
+<div>
+
+<ul>
+<li><a href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="abi">ABI</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<!-- ======================================================================= -->
+<h3><a name="linux">Linux</a></h3>
+
+<div>
+<ol>
+<li><a href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI
+Supplement</a></li>
+</ol>
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="osx">OS X</a></h3>
+
+<div>
+<ol>
+<li><a
+href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O
+Runtime Architecture</a></li>
+<li><a href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O
+ABI</a></li>
+</ol>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="misc">Miscellaneous resources</a></h2>
+<!-- *********************************************************************** -->
+
+<ul>
+<li><a
+href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable
+File Format library</a></li>
+<li><a href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a>
+page has a good survey of the prefetching capabilities of a variety of modern
+processors.</li>
+</ul>
+
+<!-- *********************************************************************** -->
+
+<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://misha.brukman.net">Misha Brukman</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-04-22 19:30:22 -0500 (Fri, 22 Apr 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/DebuggingJITedCode.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/3.0/docs/DebuggingJITedCode.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,153 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Debugging JITed Code With GDB</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>Debugging JITed Code With GDB</h1>
+<ol>
+ <li><a href="#example">Example usage</a></li>
+ <li><a href="#background">Background</a></li>
+</ol>
+<div class="doc_author">Written by Reid Kleckner</div>
+
+<!--=========================================================================-->
+<h2><a name="example">Example usage</a></h2>
+<!--=========================================================================-->
+<div>
+
+<p>In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is
+available on most modern distributions of Linux. The version of GDB that Apple
+ships with XCode has been frozen at 6.3 for a while. LLDB may be a better
+option for debugging JITed code on Mac OS X.
+</p>
+
+<p>Consider debugging the following code compiled with clang and run through
+lli:
+</p>
+
+<pre class="doc_code">
+#include <stdio.h>
+
+void foo() {
+ printf("%d\n", *(int*)NULL); // Crash here
+}
+
+void bar() {
+ foo();
+}
+
+void baz() {
+ bar();
+}
+
+int main(int argc, char **argv) {
+ baz();
+}
+</pre>
+
+<p>Here are the commands to run that application under GDB and print the stack
+trace at the crash:
+</p>
+
+<pre class="doc_code">
+# Compile foo.c to bitcode. You can use either clang or llvm-gcc with this
+# command line. Both require -fexceptions, or the calls are all marked
+# 'nounwind' which disables DWARF exception handling info. Custom frontends
+# should avoid adding this attribute to JITed code, since it interferes with
+# DWARF CFA generation at the moment.
+$ clang foo.c -fexceptions -emit-llvm -c -o foo.bc
+
+# Run foo.bc under lli with -jit-emit-debug. If you built lli in debug mode,
+# -jit-emit-debug defaults to true.
+$ $GDB_INSTALL/gdb --args lli -jit-emit-debug foo.bc
+...
+
+# Run the code.
+(gdb) run
+Starting program: /tmp/gdb/lli -jit-emit-debug foo.bc
+[Thread debugging using libthread_db enabled]
+
+Program received signal SIGSEGV, Segmentation fault.
+0x00007ffff7f55164 in foo ()
+
+# Print the backtrace, this time with symbols instead of ??.
+(gdb) bt
+#0 0x00007ffff7f55164 in foo ()
+#1 0x00007ffff7f550f9 in bar ()
+#2 0x00007ffff7f55099 in baz ()
+#3 0x00007ffff7f5502a in main ()
+#4 0x00000000007c0225 in llvm::JIT::runFunction(llvm::Function*,
+ std::vector<llvm::GenericValue,
+ std::allocator<llvm::GenericValue> > const&) ()
+#5 0x00000000007d6d98 in
+ llvm::ExecutionEngine::runFunctionAsMain(llvm::Function*,
+ std::vector<std::string,
+ std::allocator<std::string> > const&, char const* const*) ()
+#6 0x00000000004dab76 in main ()
+</pre>
+
+<p>As you can see, GDB can correctly unwind the stack and has the appropriate
+function names.
+</p>
+</div>
+
+<!--=========================================================================-->
+<h2><a name="background">Background</a></h2>
+<!--=========================================================================-->
+<div>
+
+<p>Without special runtime support, debugging dynamically generated code with
+GDB (as well as most debuggers) can be quite painful. Debuggers generally read
+debug information from the object file of the code, but for JITed code, there is
+no such file to look for.
+</p>
+
+<p>Depending on the architecture, this can impact the debugging experience in
+different ways. For example, on most 32-bit x86 architectures, you can simply
+compile with -fno-omit-frame-pointer for GCC and -disable-fp-elim for LLVM.
+When GDB creates a backtrace, it can properly unwind the stack, but the stack
+frames owned by JITed code have ??'s instead of the appropriate symbol name.
+However, on Linux x86_64 in particular, GDB relies on the DWARF call frame
+address (CFA) debug information to unwind the stack, so even if you compile
+your program to leave the frame pointer untouched, GDB will usually be unable
+to unwind the stack past any JITed code stack frames.
+</p>
+
+<p>In order to communicate the necessary debug info to GDB, an interface for
+registering JITed code with debuggers has been designed and implemented for
+GDB and LLVM. At a high level, whenever LLVM generates new machine code, it
+also generates an object file in memory containing the debug information. LLVM
+then adds the object file to the global list of object files and calls a special
+function (__jit_debug_register_code) marked noinline that GDB knows about. When
+GDB attaches to a process, it puts a breakpoint in this function and loads all
+of the object files in the global list. When LLVM calls the registration
+function, GDB catches the breakpoint signal, loads the new object file from
+LLVM's memory, and resumes the execution. In this way, GDB can get the
+necessary debug information.
+</p>
+
+<p>At the time of this writing, LLVM only supports architectures that use ELF
+object files and it only generates symbols and DWARF CFA information. However,
+it would be easy to add more information to the object file, so we don't need to
+coordinate with GDB to get better debug information.
+</p>
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+ <a href="mailto:reid.kleckner at gmail.com">Reid Kleckner</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:23 -0500 (Thu, 03 Nov 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/DeveloperPolicy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/DeveloperPolicy.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/DeveloperPolicy.html (added)
+++ www-releases/trunk/3.0/docs/DeveloperPolicy.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,622 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM Developer Policy</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>LLVM Developer Policy</h1>
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#policies">Developer Policies</a>
+ <ol>
+ <li><a href="#informed">Stay Informed</a></li>
+ <li><a href="#patches">Making a Patch</a></li>
+ <li><a href="#reviews">Code Reviews</a></li>
+ <li><a href="#owners">Code Owners</a></li>
+ <li><a href="#testcases">Test Cases</a></li>
+ <li><a href="#quality">Quality</a></li>
+ <li><a href="#commitaccess">Obtaining Commit Access</a></li>
+ <li><a href="#newwork">Making a Major Change</a></li>
+ <li><a href="#incremental">Incremental Development</a></li>
+ <li><a href="#attribution">Attribution of Changes</a></li>
+ </ol></li>
+ <li><a href="#clp">Copyright, License, and Patents</a>
+ <ol>
+ <li><a href="#copyright">Copyright</a></li>
+ <li><a href="#license">License</a></li>
+ <li><a href="#patents">Patents</a></li>
+ </ol></li>
+</ol>
+<div class="doc_author">Written by the LLVM Oversight Team</div>
+
+<!--=========================================================================-->
+<h2><a name="introduction">Introduction</a></h2>
+<!--=========================================================================-->
+<div>
+<p>This document contains the LLVM Developer Policy which defines the project's
+ policy towards developers and their contributions. The intent of this policy
+ is to eliminate miscommunication, rework, and confusion that might arise from
+ 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>
+<p>This policy is also designed to accomplish the following objectives:</p>
+
+<ol>
+ <li>Attract both users and developers to the LLVM project.</li>
+
+ <li>Make life as simple and easy for contributors as possible.</li>
+
+ <li>Keep the top of Subversion trees as stable as possible.</li>
+</ol>
+
+<p>This policy is aimed at frequent contributors to LLVM. People interested in
+ contributing one-off patches can do so in an informal way by sending them to
+ the
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits
+ mailing list</a> and engaging another developer to see it through the
+ process.</p>
+</div>
+
+<!--=========================================================================-->
+<h2><a name="policies">Developer Policies</a></h2>
+<!--=========================================================================-->
+<div>
+<p>This section contains policies that pertain to frequent LLVM developers. We
+ always welcome <a href="#patches">one-off patches</a> from people who do not
+ routinely contribute to LLVM, but we expect more from frequent contributors
+ to keep the system as efficient as possible for everyone. Frequent LLVM
+ contributors are expected to meet the following requirements in order for
+ LLVM to maintain a high standard of quality.<p>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="informed">Stay Informed</a></h3>
+<div>
+<p>Developers should stay informed by reading at least the "dev" mailing list
+ for the projects you are interested in, such as
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> for
+ LLVM, <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
+ for Clang, or <a
+ href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-dev">lldb-dev</a>
+ for LLDB. If you are doing anything more than just casual work on LLVM, it
+ is suggested that you also subscribe to the "commits" mailing list for the
+ subproject you're interested in, such as
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>,
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>,
+ or <a href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits">lldb-commits</a>.
+ Reading the "commits" list and paying attention to changes being made by
+ others is a good way to see what other people are interested in and watching
+ the flow of the project as a whole.</p>
+
+<p>We recommend that active developers register an email account with
+ <a href="http://llvm.org/bugs/">LLVM Bugzilla</a> and preferably subscribe to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs">llvm-bugs</a>
+ email list to keep track of bugs and enhancements occurring in LLVM. We
+ really appreciate people who are proactive at catching incoming bugs in their
+ components and dealing with them promptly.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="patches">Making a Patch</a></h3>
+
+<div>
+<p>When making a patch for review, the goal is to make it as easy for the
+ reviewer to read it as possible. As such, we recommend that you:</p>
+
+<ol>
+ <li>Make your patch against the Subversion trunk, not a branch, and not an old
+ version of LLVM. This makes it easy to apply the patch. For information
+ on how to check out SVN trunk, please see the <a
+ href="GettingStarted.html#checkout">Getting Started Guide</a>.</li>
+
+ <li>Similarly, patches should be submitted soon after they are generated. Old
+ patches may not apply correctly if the underlying code changes between the
+ time the patch was created and the time it is applied.</li>
+
+ <li>Patches should be made with <tt>svn diff</tt>, or similar. If you use
+ a different tool, make sure it uses the <tt>diff -u</tt> format and
+ that it doesn't contain clutter which makes it hard to read.</li>
+
+ <li>If you are modifying generated files, such as the top-level
+ <tt>configure</tt> script, please separate out those changes into
+ a separate patch from the rest of your changes.</li>
+</ol>
+
+<p>When sending a patch to a mailing list, it is a good idea to send it as an
+ <em>attachment</em> to the message, not embedded into the text of the
+ message. This ensures that your mailer will not mangle the patch when it
+ sends it (e.g. by making whitespace changes or by wrapping lines).</p>
+
+<p><em>For Thunderbird users:</em> Before submitting a patch, please open
+ <em>Preferences → Advanced → General → Config Editor</em>,
+ find the key <tt>mail.content_disposition_type</tt>, and set its value to
+ <tt>1</tt>. Without this setting, Thunderbird sends your attachment using
+ <tt>Content-Disposition: inline</tt> rather than <tt>Content-Disposition:
+ attachment</tt>. Apple Mail gamely displays such a file inline, making it
+ difficult to work with for reviewers using that program.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="reviews">Code Reviews</a></h3>
+<div>
+<p>LLVM has a code review policy. Code review is one way to increase the quality
+ of software. We generally follow these policies:</p>
+
+<ol>
+ <li>All developers are required to have significant changes reviewed before
+ they are committed to the repository.</li>
+
+ <li>Code reviews are conducted by email, usually on the llvm-commits
+ list.</li>
+
+ <li>Code can be reviewed either before it is committed or after. We expect
+ major changes to be reviewed before being committed, but smaller changes
+ (or changes where the developer owns the component) can be reviewed after
+ commit.</li>
+
+ <li>The developer responsible for a code change is also responsible for making
+ all necessary review-related changes.</li>
+
+ <li>Code review can be an iterative process, which continues until the patch
+ is ready to be committed.</li>
+</ol>
+
+<p>Developers should participate in code reviews as both reviewers and
+ reviewees. If someone is kind enough to review your code, you should return
+ the favor for someone else. Note that anyone is welcome to review and give
+ feedback on a patch, but only people with Subversion write access can approve
+ it.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="owners">Code Owners</a></h3>
+<div>
+
+<p>The LLVM Project relies on two features of its process to maintain rapid
+ development in addition to the high quality of its source base: the
+ combination of code review plus post-commit review for trusted maintainers.
+ Having both is a great way for the project to take advantage of the fact that
+ most people do the right thing most of the time, and only commit patches
+ without pre-commit review when they are confident they are right.</p>
+
+<p>The trick to this is that the project has to guarantee that all patches that
+ are committed are reviewed after they go in: you don't want everyone to
+ assume someone else will review it, allowing the patch to go unreviewed. To
+ solve this problem, we have a notion of an 'owner' for a piece of the code.
+ The sole responsibility of a code owner is to ensure that a commit to their
+ area of the code is appropriately reviewed, either by themself or by someone
+ else. The current code owners are:</p>
+
+<ol>
+ <li><b>Evan Cheng</b>: Code generator and all targets.</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>
+
+ <li><b>Ted Kremenek</b>: Clang Static Analyzer.</li>
+
+ <li><b>Chris Lattner</b>: Everything not covered by someone else.</li>
+
+ <li><b>John McCall</b>: Clang LLVM IR generation.</li>
+
+ <li><b>Jakob Olesen</b>: Register allocators and TableGen.</li>
+
+ <li><b>Duncan Sands</b>: dragonegg and llvm-gcc 4.2.</li>
+</ol>
+
+<p>Note that code ownership is completely different than reviewers: anyone can
+ review a piece of code, and we welcome code review from anyone who is
+ interested. Code owners are the "last line of defense" to guarantee that all
+ patches that are committed are actually reviewed.</p>
+
+<p>Being a code owner is a somewhat unglamorous position, but it is incredibly
+ important for the ongoing success of the project. Because people get busy,
+ interests change, and unexpected things happen, code ownership is purely
+ opt-in, and anyone can choose to resign their "title" at any time. For now,
+ we do not have an official policy on how one gets elected to be a code
+ owner.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="testcases">Test Cases</a></h3>
+<div>
+<p>Developers are required to create test cases for any bugs fixed and any new
+ features added. Some tips for getting your testcase approved:</p>
+
+<ol>
+ <li>All feature and regression test cases are added to the
+ <tt>llvm/test</tt> directory. The appropriate sub-directory should be
+ selected (see the <a href="TestingGuide.html">Testing Guide</a> for
+ details).</li>
+
+ <li>Test cases should be written in <a href="LangRef.html">LLVM assembly
+ language</a> unless the feature or regression being tested requires
+ another language (e.g. the bug being fixed or feature being implemented is
+ in the llvm-gcc C++ front-end, in which case it must be written in
+ C++).</li>
+
+ <li>Test cases, especially for regressions, should be reduced as much as
+ possible, by <a href="Bugpoint.html">bugpoint</a> or manually. It is
+ unacceptable to place an entire failing program into <tt>llvm/test</tt> as
+ this creates a <i>time-to-test</i> burden on all developers. Please keep
+ them short.</li>
+</ol>
+
+<p>Note that llvm/test and clang/test are designed for regression and small
+ feature tests only. More extensive test cases (e.g., entire applications,
+ benchmarks, etc)
+ should be added to the <tt>llvm-test</tt> test suite. The llvm-test suite is
+ for coverage (correctness, performance, etc) testing, not feature or
+ regression testing.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="quality">Quality</a></h3>
+<div>
+<p>The minimum quality standards that any change must satisfy before being
+ committed to the main development branch are:</p>
+
+<ol>
+ <li>Code must adhere to the <a href="CodingStandards.html">LLVM Coding
+ Standards</a>.</li>
+
+ <li>Code must compile cleanly (no errors, no warnings) on at least one
+ platform.</li>
+
+ <li>Bug fixes and new features should <a href="#testcases">include a
+ testcase</a> so we know if the fix/feature ever regresses in the
+ future.</li>
+
+ <li>Code must pass the <tt>llvm/test</tt> test suite.</li>
+
+ <li>The code must not cause regressions on a reasonable subset of llvm-test,
+ where "reasonable" depends on the contributor's judgement and the scope of
+ the change (more invasive changes require more testing). A reasonable
+ subset might be something like
+ "<tt>llvm-test/MultiSource/Benchmarks</tt>".</li>
+</ol>
+
+<p>Additionally, the committer is responsible for addressing any problems found
+ in the future that the change is responsible for. For example:</p>
+
+<ul>
+ <li>The code should compile cleanly on all supported platforms.</li>
+
+ <li>The changes should not cause any correctness regressions in the
+ <tt>llvm-test</tt> suite and must not cause any major performance
+ regressions.</li>
+
+ <li>The change set should not cause performance or correctness regressions for
+ the LLVM tools.</li>
+
+ <li>The changes should not cause performance or correctness regressions in
+ code compiled by LLVM on all applicable targets.</li>
+
+ <li>You are expected to address any <a href="http://llvm.org/bugs/">bugzilla
+ bugs</a> that result from your change.</li>
+</ul>
+
+<p>We prefer for this to be handled before submission but understand that it
+ isn't possible to test all of this for every submission. Our build bots and
+ nightly testing infrastructure normally finds these problems. A good rule of
+ thumb is to check the nightly testers for regressions the day after your
+ change. Build bots will directly email you if a group of commits that
+ included yours caused a failure. You are expected to check the build bot
+ messages to see if they are your fault and, if so, fix the breakage.</p>
+
+<p>Commits that violate these quality standards (e.g. are very broken) may be
+ reverted. This is necessary when the change blocks other developers from
+ making progress. The developer is welcome to re-commit the change after the
+ problem has been fixed.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="commitaccess">Obtaining Commit Access</a></h3>
+<div>
+
+<p>We grant commit access to contributors with a track record of submitting high
+ quality patches. If you would like commit access, please send an email to
+ <a href="mailto:sabre at nondot.org">Chris</a> with the following
+ information:</p>
+
+<ol>
+ <li>The user name you want to commit with, e.g. "hacker".</li>
+
+ <li>The full name and email address you want message to llvm-commits to come
+ from, e.g. "J. Random Hacker <hacker at yoyodyne.com>".</li>
+
+ <li>A "password hash" of the password you want to use, e.g. "2ACR96qjUqsyM".
+ Note that you don't ever tell us what your password is, you just give it
+ to us in an encrypted form. To get this, run "htpasswd" (a utility that
+ comes with apache) in crypt mode (often enabled with "-d"), or find a web
+ page that will do it for you.</li>
+</ol>
+
+<p>Once you've been granted commit access, you should be able to check out an
+ LLVM tree with an SVN URL of "https://username@llvm.org/..." instead of the
+ normal anonymous URL of "http://llvm.org/...". The first time you commit
+ you'll have to type in your password. Note that you may get a warning from
+ SVN about an untrusted key, you can ignore this. To verify that your commit
+ access works, please do a test commit (e.g. change a comment or add a blank
+ line). Your first commit to a repository may require the autogenerated email
+ to be approved by a mailing list. This is normal, and will be done when
+ the mailing list owner has time.</p>
+
+<p>If you have recently been granted commit access, these policies apply:</p>
+
+<ol>
+ <li>You are granted <i>commit-after-approval</i> to all parts of LLVM. To get
+ approval, submit a <a href="#patches">patch</a> to
+ <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>.
+ When approved you may commit it yourself.</li>
+
+ <li>You are allowed to commit patches without approval which you think are
+ obvious. This is clearly a subjective decision — we simply expect
+ you to use good judgement. Examples include: fixing build breakage,
+ reverting obviously broken patches, documentation/comment changes, any
+ other minor changes.</li>
+
+ <li>You are allowed to commit patches without approval to those portions of
+ LLVM that you have contributed or maintain (i.e., have been assigned
+ responsibility for), with the proviso that such commits must not break the
+ build. This is a "trust but verify" policy and commits of this nature are
+ reviewed after they are committed.</li>
+
+ <li>Multiple violations of these policies or a single egregious violation may
+ cause commit access to be revoked.</li>
+</ol>
+
+<p>In any case, your changes are still subject to <a href="#reviews">code
+ review</a> (either before or after they are committed, depending on the
+ nature of the change). You are encouraged to review other peoples' patches
+ as well, but you aren't required to.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="newwork">Making a Major Change</a></h3>
+<div>
+<p>When a developer begins a major new project with the aim of contributing it
+ back to LLVM, s/he should inform the community with an email to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>
+ email list, to the extent possible. The reason for this is to:
+
+<ol>
+ <li>keep the community informed about future changes to LLVM, </li>
+
+ <li>avoid duplication of effort by preventing multiple parties working on the
+ same thing and not knowing about it, and</li>
+
+ <li>ensure that any technical issues around the proposed work are discussed
+ and resolved before any significant work is done.</li>
+</ol>
+
+<p>The design of LLVM is carefully controlled to ensure that all the pieces fit
+ together well and are as consistent as possible. If you plan to make a major
+ change to the way LLVM works or want to add a major new extension, it is a
+ good idea to get consensus with the development community before you start
+ working on it.</p>
+
+<p>Once the design of the new feature is finalized, the work itself should be
+ done as a series of <a href="#incremental">incremental changes</a>, not as a
+ long-term development branch.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="incremental">Incremental Development</a></h3>
+<div>
+<p>In the LLVM project, we do all significant changes as a series of incremental
+ patches. We have a strong dislike for huge changes or long-term development
+ branches. Long-term development branches have a number of drawbacks:</p>
+
+<ol>
+ <li>Branches must have mainline merged into them periodically. If the branch
+ development and mainline development occur in the same pieces of code,
+ resolving merge conflicts can take a lot of time.</li>
+
+ <li>Other people in the community tend to ignore work on branches.</li>
+
+ <li>Huge changes (produced when a branch is merged back onto mainline) are
+ extremely difficult to <a href="#reviews">code review</a>.</li>
+
+ <li>Branches are not routinely tested by our nightly tester
+ infrastructure.</li>
+
+ <li>Changes developed as monolithic large changes often don't work until the
+ entire set of changes is done. Breaking it down into a set of smaller
+ changes increases the odds that any of the work will be committed to the
+ main repository.</li>
+</ol>
+
+<p>To address these problems, LLVM uses an incremental development style and we
+ require contributors to follow this practice when making a large/invasive
+ change. Some tips:</p>
+
+<ul>
+ <li>Large/invasive changes usually have a number of secondary changes that are
+ required before the big change can be made (e.g. API cleanup, etc). These
+ sorts of changes can often be done before the major change is done,
+ independently of that work.</li>
+
+ <li>The remaining inter-related work should be decomposed into unrelated sets
+ of changes if possible. Once this is done, define the first increment and
+ get consensus on what the end goal of the change is.</li>
+
+ <li>Each change in the set can be stand alone (e.g. to fix a bug), or part of
+ a planned series of changes that works towards the development goal.</li>
+
+ <li>Each change should be kept as small as possible. This simplifies your work
+ (into a logical progression), simplifies code review and reduces the
+ chance that you will get negative feedback on the change. Small increments
+ also facilitate the maintenance of a high quality code base.</li>
+
+ <li>Often, an independent precursor to a big change is to add a new API and
+ slowly migrate clients to use the new API. Each change to use the new API
+ is often "obvious" and can be committed without review. Once the new API
+ is in place and used, it is much easier to replace the underlying
+ implementation of the API. This implementation change is logically
+ separate from the API change.</li>
+</ul>
+
+<p>If you are interested in making a large change, and this scares you, please
+ make sure to first <a href="#newwork">discuss the change/gather consensus</a>
+ then ask about the best way to go about making the change.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="attribution">Attribution of Changes</a></h3>
+<div>
+<p>We believe in correct attribution of contributions to their contributors.
+ However, we do not want the source code to be littered with random
+ attributions "this code written by J. Random Hacker" (this is noisy and
+ distracting). In practice, the revision control system keeps a perfect
+ history of who changed what, and the CREDITS.txt file describes higher-level
+ contributions. If you commit a patch for someone else, please say "patch
+ contributed by J. Random Hacker!" in the commit message.</p>
+
+<p>Overall, please do not add contributor names to the source code.</p>
+</div>
+
+</div>
+
+<!--=========================================================================-->
+<h2>
+ <a name="clp">Copyright, License, and Patents</a>
+</h2>
+<!--=========================================================================-->
+
+<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
+ 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>
+
+<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>
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<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
+ <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>You can't use our names to promote your LLVM derived products.</li>
+ <li>There's no warranty on LLVM at all.</li>
+</ul>
+
+<p>We believe this fosters the widest adoption of LLVM because it <b>allows
+ commercial products to be derived from LLVM</b> with few restrictions and
+ without a requirement for making any derived works also open source (i.e.
+ 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
+ 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>
+
+<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:llvmdev at cs.uiuc.edu">LLVM Developer's Mailing List</a>.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h3><a name="patents">Patents</a></h3>
+<div>
+<p>To the best of our knowledge, LLVM does not infringe on any patents (we have
+ actually removed code from LLVM in the past that was found to infringe).
+ Having code in LLVM that infringes on patents would violate an important goal
+ of the project by making it hard or impossible to reuse the code for
+ 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
+ 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
+ the <a href="mailto:llvm-oversight at cs.uiuc.edu">oversight group</a> for more
+ details.</p>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+ Written by the
+ <a href="mailto:llvm-oversight at cs.uiuc.edu">LLVM Oversight Group</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-10-07 12:26:38 -0500 (Fri, 07 Oct 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/ExceptionHandling.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/3.0/docs/ExceptionHandling.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,582 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>Exception Handling in LLVM</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <meta name="description"
+ content="Exception Handling in LLVM.">
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Exception Handling in LLVM</h1>
+
+<table class="layout" style="width:100%">
+ <tr class="layout">
+ <td class="left">
+<ul>
+ <li><a href="#introduction">Introduction</a>
+ <ol>
+ <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
+ <li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li>
+ <li><a href="#overview">Overview</a></li>
+ </ol></li>
+ <li><a href="#codegen">LLVM Code Generation</a>
+ <ol>
+ <li><a href="#throw">Throw</a></li>
+ <li><a href="#try_catch">Try/Catch</a></li>
+ <li><a href="#cleanups">Cleanups</a></li>
+ <li><a href="#throw_filters">Throw Filters</a></li>
+ <li><a href="#restrictions">Restrictions</a></li>
+ </ol></li>
+ <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a>
+ <ol>
+ <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li>
+ <li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li>
+ <li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li>
+ <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>
+ <li><a href="#unwind_tables">Exception Handling Frame</a></li>
+ <li><a href="#exception_tables">Exception Tables</a></li>
+ </ol></li>
+</ul>
+</td>
+</tr></table>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:jlaskey at mac.com">Jim Laskey</a></p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2><a name="introduction">Introduction</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document is the central repository for all information pertaining to
+ exception handling in LLVM. It describes the format that LLVM exception
+ handling information takes, which is useful for those interested in creating
+ front-ends or dealing directly with the information. Further, this document
+ provides specific examples of what exception handling information is used for
+ in C and C++.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
+</h3>
+
+<div>
+
+<p>Exception handling for most programming languages is designed to recover from
+ conditions that rarely occur during general use of an application. To that
+ end, exception handling should not interfere with the main flow of an
+ application's algorithm by performing checkpointing tasks, such as saving the
+ current pc or register state.</p>
+
+<p>The Itanium ABI Exception Handling Specification defines a methodology for
+ providing outlying data in the form of exception tables without inlining
+ speculative exception handling code in the flow of an application's main
+ algorithm. Thus, the specification is said to add "zero-cost" to the normal
+ execution of an application.</p>
+
+<p>A more complete description of the Itanium ABI exception handling runtime
+ support of can be found at
+ <a href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI:
+ Exception Handling</a>. A description of the exception frame format can be
+ found at
+ <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception
+ Frames</a>, with details of the DWARF 4 specification at
+ <a href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>.
+ A description for the C++ exception table formats can be found at
+ <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling
+ Tables</a>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="sjlj">Setjmp/Longjmp Exception Handling</a>
+</h3>
+
+<div>
+
+<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+ <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and
+ <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to
+ handle control flow for exception handling.</p>
+
+<p>For each function which does exception processing — be
+ it <tt>try</tt>/<tt>catch</tt> blocks or cleanups — that function
+ registers itself on a global frame list. When exceptions are unwinding, the
+ runtime uses this list to identify which functions need processing.<p>
+
+<p>Landing pad selection is encoded in the call site entry of the function
+ context. The runtime returns to the function via
+ <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where
+ a switch table transfers control to the appropriate landing pad based on
+ the index stored in the function context.</p>
+
+<p>In contrast to DWARF exception handling, which encodes exception regions
+ and frame information in out-of-line tables, SJLJ exception handling
+ builds and removes the unwind frame context at runtime. This results in
+ faster exception handling at the expense of slower execution when no
+ exceptions are thrown. As exceptions are, by their nature, intended for
+ uncommon code paths, DWARF exception handling is generally preferred to
+ SJLJ.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="overview">Overview</a>
+</h3>
+
+<div>
+
+<p>When an exception is thrown in LLVM code, the runtime does its best to find a
+ handler suited to processing the circumstance.</p>
+
+<p>The runtime first attempts to find an <i>exception frame</i> corresponding to
+ the function where the exception was thrown. If the programming language
+ supports exception handling (e.g. C++), the exception frame contains a
+ reference to an exception table describing how to process the exception. If
+ the language does not support exception handling (e.g. C), or if the
+ exception needs to be forwarded to a prior activation, the exception frame
+ contains information about how to unwind the current activation and restore
+ the state of the prior activation. This process is repeated until the
+ exception is handled. If the exception is not handled and no activations
+ remain, then the application is terminated with an appropriate error
+ message.</p>
+
+<p>Because different programming languages have different behaviors when
+ handling exceptions, the exception handling ABI provides a mechanism for
+ supplying <i>personalities</i>. An exception handling personality is defined
+ by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt>
+ in C++), which receives the context of the exception, an <i>exception
+ structure</i> containing the exception object type and value, and a reference
+ to the exception table for the current function. The personality function
+ for the current compile unit is specified in a <i>common exception
+ frame</i>.</p>
+
+<p>The organization of an exception table is language dependent. For C++, an
+ exception table is organized as a series of code ranges defining what to do
+ if an exception occurs in that range. Typically, the information associated
+ with a range defines which types of exception objects (using C++ <i>type
+ info</i>) that are handled in that range, and an associated action that
+ should take place. Actions typically pass control to a <i>landing
+ pad</i>.</p>
+
+<p>A landing pad corresponds roughly to the code found in the <tt>catch</tt>
+ portion of a <tt>try</tt>/<tt>catch</tt> sequence. When execution resumes at
+ a landing pad, it receives an <i>exception structure</i> and a
+ <i>selector value</i> corresponding to the <i>type</i> of exception
+ thrown. The selector is then used to determine which <i>catch</i> should
+ actually process the exception.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h2>
+ <a name="codegen">LLVM Code Generation</a>
+</h2>
+
+<div>
+
+<p>From a C++ developer's perspective, exceptions are defined in terms of the
+ <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section
+ we will describe the implementation of LLVM exception handling in terms of
+ C++ examples.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="throw">Throw</a>
+</h3>
+
+<div>
+
+<p>Languages that support exception handling typically provide a <tt>throw</tt>
+ operation to initiate the exception process. Internally, a <tt>throw</tt>
+ operation breaks down into two steps.</p>
+
+<ol>
+ <li>A request is made to allocate exception space for an exception structure.
+ This structure needs to survive beyond the current activation. This
+ structure will contain the type and value of the object being thrown.</li>
+
+ <li>A call is made to the runtime to raise the exception, passing the
+ exception structure as an argument.</li>
+</ol>
+
+<p>In C++, the allocation of the exception structure is done by the
+ <tt>__cxa_allocate_exception</tt> runtime function. The exception raising is
+ handled by <tt>__cxa_throw</tt>. The type of the exception is represented
+ using a C++ RTTI structure.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="try_catch">Try/Catch</a>
+</h3>
+
+<div>
+
+<p>A call within the scope of a <i>try</i> statement can potentially raise an
+ exception. In those circumstances, the LLVM C++ front-end replaces the call
+ with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has
+ two potential continuation points:</p>
+
+<ol>
+ <li>where to continue when the call succeeds as per normal, and</li>
+
+ <li>where to continue if the call raises an exception, either by a throw or
+ the unwinding of a throw</li>
+</ol>
+
+<p>The term used to define a the place where an <tt>invoke</tt> continues after
+ an exception is called a <i>landing pad</i>. LLVM landing pads are
+ conceptually alternative function entry points where an exception structure
+ reference and a type info index are passed in as arguments. The landing pad
+ saves the exception structure reference and then proceeds to select the catch
+ block that corresponds to the type info of the exception object.</p>
+
+<p>The LLVM <a href="LangRef.html#i_landingpad"><tt>landingpad</tt>
+ instruction</a> is used to convey information about the landing pad to the
+ back end. For C++, the <tt>landingpad</tt> instruction returns a pointer and
+ integer pair corresponding to the pointer to the <i>exception structure</i>
+ and the <i>selector value</i> respectively.</p>
+
+<p>The <tt>landingpad</tt> instruction takes a reference to the personality
+ function to be used for this <tt>try</tt>/<tt>catch</tt> sequence. The
+ remainder of the instruction is a list of <i>cleanup</i>, <i>catch</i>,
+ and <i>filter</i> clauses. The exception is tested against the clauses
+ sequentially from first to last. The selector value is a positive number if
+ the exception matched a type info, a negative number if it matched a filter,
+ and zero if it matched a cleanup. If nothing is matched, the behavior of
+ the program is <a href="#restrictions">undefined</a>. If a type info matched,
+ then the selector value is the index of the type info in the exception table,
+ which can be obtained using the
+ <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p>
+
+<p>Once the landing pad has the type info selector, the code branches to the
+ code for the first catch. The catch then checks the value of the type info
+ selector against the index of type info for that catch. Since the type info
+ index is not known until all the type infos have been gathered in the
+ backend, the catch code must call the
+ <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to
+ determine the index for a given type info. If the catch fails to match the
+ selector then control is passed on to the next catch.</p>
+
+<p>Finally, the entry and exit of catch code is bracketed with calls to
+ <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p>
+
+<ul>
+ <li><tt>__cxa_begin_catch</tt> takes an exception structure reference as an
+ argument and returns the value of the exception object.</li>
+
+ <li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br>
+ <ol>
+ <li>Locates the most recently caught exception and decrements its handler
+ count,</li>
+ <li>Removes the exception from the <i>caught</i> stack if the handler
+ count goes to zero, and</li>
+ <li>Destroys the exception if the handler count goes to zero and the
+ exception was not re-thrown by throw.</li>
+ </ol>
+ <p><b>Note:</b> a rethrow from within the catch may replace this call with
+ a <tt>__cxa_rethrow</tt>.</p></li>
+</ul>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="cleanups">Cleanups</a>
+</h3>
+
+<div>
+
+<p>A cleanup is extra code which needs to be run as part of unwinding a scope.
+ C++ destructors are a typical example, but other languages and language
+ extensions provide a variety of different kinds of cleanups. In general, a
+ landing pad may need to run arbitrary amounts of cleanup code before actually
+ entering a catch block. To indicate the presence of cleanups, a
+ <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>
+ should have a <i>cleanup</i> clause. Otherwise, the unwinder will not stop at
+ the landing pad if there are no catches or filters that require it to.</p>
+
+<p><b>Note:</b> Do not allow a new exception to propagate out of the execution
+ of a cleanup. This can corrupt the internal state of the unwinder.
+ Different languages describe different high-level semantics for these
+ situations: for example, C++ requires that the process be terminated, whereas
+ Ada cancels both exceptions and throws a third.</p>
+
+<p>When all cleanups are finished, if the exception is not handled by the
+ current function, resume unwinding by calling the
+ <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a>, passing in
+ the result of the <tt>landingpad</tt> instruction for the original landing
+ pad.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="throw_filters">Throw Filters</a>
+</h3>
+
+<div>
+
+<p>C++ allows the specification of which exception types may be thrown from a
+ function. To represent this, a top level landing pad may exist to filter out
+ invalid types. To express this in LLVM code the
+ <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> will
+ have a filter clause. The clause consists of an array of type infos.
+ <tt>landingpad</tt> will return a negative value if the exception does not
+ match any of the type infos. If no match is found then a call
+ to <tt>__cxa_call_unexpected</tt> should be made, otherwise
+ <tt>_Unwind_Resume</tt>. Each of these functions requires a reference to the
+ exception structure. Note that the most general form of a
+ <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> can
+ have any number of catch, cleanup, and filter clauses (though having more
+ than one cleanup is pointless). The LLVM C++ front-end can generate such
+ <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instructions</a> due
+ to inlining creating nested exception handling scopes.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="restrictions">Restrictions</a>
+</h3>
+
+<div>
+
+<p>The unwinder delegates the decision of whether to stop in a call frame to
+ that call frame's language-specific personality function. Not all unwinders
+ guarantee that they will stop to perform cleanups. For example, the GNU C++
+ unwinder doesn't do so unless the exception is actually caught somewhere
+ further up the stack.</p>
+
+<p>In order for inlining to behave correctly, landing pads must be prepared to
+ handle selector results that they did not originally advertise. Suppose that
+ a function catches exceptions of type <tt>A</tt>, and it's inlined into a
+ function that catches exceptions of type <tt>B</tt>. The inliner will update
+ the <tt>landingpad</tt> instruction for the inlined landing pad to include
+ the fact that <tt>B</tt> is also caught. If that landing pad assumes that it
+ will only be entered to catch an <tt>A</tt>, it's in for a rude awakening.
+ Consequently, landing pads must test for the selector results they understand
+ and then resume exception propagation with the
+ <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a> if none of
+ the conditions match.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h2>
+ <a name="format_common_intrinsics">Exception Handling Intrinsics</a>
+</h2>
+
+<div>
+
+<p>In addition to the
+ <a href="LangRef.html#i_landingpad"><tt>landingpad</tt></a> and
+ <a href="LangRef.html#i_resume"><tt>resume</tt></a> instructions, LLVM uses
+ several intrinsic functions (name prefixed with <i><tt>llvm.eh</tt></i>) to
+ provide exception handling information at various points in generated
+ code.</p>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
+</h4>
+
+<div>
+
+<pre>
+ i32 @llvm.eh.typeid.for(i8* %type_info)
+</pre>
+
+<p>This intrinsic returns the type info index in the exception table of the
+ current function. This value can be used to compare against the result
+ of <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>.
+ The single argument is a reference to a type info.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>
+</h4>
+
+<div>
+
+<pre>
+ i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
+</pre>
+
+<p>For SJLJ based exception handling, this intrinsic forces register saving for
+ the current function and stores the address of the following instruction for
+ use as a destination address
+ by <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>. The
+ buffer format and the overall functioning of this intrinsic is compatible
+ with the GCC <tt>__builtin_setjmp</tt> implementation allowing code built
+ with the clang and GCC to interoperate.</p>
+
+<p>The single parameter is a pointer to a five word buffer in which the calling
+ context is saved. The front end places the frame pointer in the first word,
+ and the target implementation of this intrinsic should place the destination
+ address for a
+ <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> in the
+ second word. The following three words are available for use in a
+ target-specific manner.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a>
+</h4>
+
+<div>
+
+<pre>
+ void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
+</pre>
+
+<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.longjmp</tt>
+ intrinsic is used to implement <tt>__builtin_longjmp()</tt>. The single
+ parameter is a pointer to a buffer populated
+ by <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a>. The frame
+ pointer and stack pointer are restored from the buffer, then control is
+ transferred to the destination address.</p>
+
+</div>
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>
+</h4>
+
+<div>
+
+<pre>
+ i8* @llvm.eh.sjlj.lsda()
+</pre>
+
+<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.lsda</tt> intrinsic
+ returns the address of the Language Specific Data Area (LSDA) for the current
+ function. The SJLJ front-end code stores this address in the exception
+ handling function context for use by the runtime.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>
+</h4>
+
+<div>
+
+<pre>
+ void @llvm.eh.sjlj.callsite(i32 %call_site_num)
+</pre>
+
+<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.callsite</tt>
+ intrinsic identifies the callsite value associated with the
+ following <tt>invoke</tt> instruction. This is used to ensure that landing
+ pad entries in the LSDA are generated in matching order.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>
+</h4>
+
+<div>
+
+<pre>
+ void @llvm.eh.sjlj.dispatchsetup(i32 %dispatch_value)
+</pre>
+
+<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.dispatchsetup</tt>
+ intrinsic is used by targets to do any unwind edge setup they need. By
+ default, no action is taken.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h2>
+ <a name="asm">Asm Table Formats</a>
+</h2>
+
+<div>
+
+<p>There are two tables that are used by the exception handling runtime to
+ determine which actions should be taken when an exception is thrown.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="unwind_tables">Exception Handling Frame</a>
+</h3>
+
+<div>
+
+<p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
+ frame used by DWARF debug info. The frame contains all the information
+ necessary to tear down the current frame and restore the state of the prior
+ frame. There is an exception handling frame for each function in a compile
+ unit, plus a common exception handling frame that defines information common
+ to all functions in the unit.</p>
+
+<!-- Todo - Table details here. -->
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="exception_tables">Exception Tables</a>
+</h3>
+
+<div>
+
+<p>An exception table contains information about what actions to take when an
+ exception is thrown in a particular part of a function's code. There is one
+ exception table per function, except leaf functions and functions that have
+ calls only to non-throwing functions. They do not need an exception
+ table.</p>
+
+<!-- Todo - Table details here. -->
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-09-27 15:16:57 -0500 (Tue, 27 Sep 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/ExtendedIntegerResults.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/ExtendedIntegerResults.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/ExtendedIntegerResults.txt (added)
+++ www-releases/trunk/3.0/docs/ExtendedIntegerResults.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,133 @@
+//===----------------------------------------------------------------------===//
+// Representing sign/zero extension of function results
+//===----------------------------------------------------------------------===//
+
+Mar 25, 2009 - Initial Revision
+
+Most ABIs specify that functions which return small integers do so in a
+specific integer GPR. This is an efficient way to go, but raises the question:
+if the returned value is smaller than the register, what do the high bits hold?
+
+There are three (interesting) possible answers: undefined, zero extended, or
+sign extended. The number of bits in question depends on the data-type that
+the front-end is referencing (typically i1/i8/i16/i32).
+
+Knowing the answer to this is important for two reasons: 1) we want to be able
+to implement the ABI correctly. If we need to sign extend the result according
+to the ABI, we really really do need to do this to preserve correctness. 2)
+this information is often useful for optimization purposes, and we want the
+mid-level optimizers to be able to process this (e.g. eliminate redundant
+extensions).
+
+For example, lets pretend that X86 requires the caller to properly extend the
+result of a return (I'm not sure this is the case, but the argument doesn't
+depend on this). Given this, we should compile this:
+
+int a();
+short b() { return a(); }
+
+into:
+
+_b:
+ subl $12, %esp
+ call L_a$stub
+ addl $12, %esp
+ cwtl
+ ret
+
+An optimization example is that we should be able to eliminate the explicit
+sign extension in this example:
+
+short y();
+int z() {
+ return ((int)y() << 16) >> 16;
+}
+
+_z:
+ subl $12, %esp
+ call _y
+ ;; movswl %ax, %eax -> not needed because eax is already sext'd
+ addl $12, %esp
+ ret
+
+//===----------------------------------------------------------------------===//
+// What we have right now.
+//===----------------------------------------------------------------------===//
+
+Currently, these sorts of things are modelled by compiling a function to return
+the small type and a signext/zeroext marker is used. For example, we compile
+Z into:
+
+define i32 @z() nounwind {
+entry:
+ %0 = tail call signext i16 (...)* @y() nounwind
+ %1 = sext i16 %0 to i32
+ ret i32 %1
+}
+
+and b into:
+
+define signext i16 @b() nounwind {
+entry:
+ %0 = tail call i32 (...)* @a() nounwind ; <i32> [#uses=1]
+ %retval12 = trunc i32 %0 to i16 ; <i16> [#uses=1]
+ ret i16 %retval12
+}
+
+This has some problems: 1) the actual precise semantics are really poorly
+defined (see PR3779). 2) some targets might want the caller to extend, some
+might want the callee to extend 3) the mid-level optimizer doesn't know the
+size of the GPR, so it doesn't know that %0 is sign extended up to 32-bits
+here, and even if it did, it could not eliminate the sext. 4) the code
+generator has historically assumed that the result is extended to i32, which is
+a problem on PIC16 (and is also probably wrong on alpha and other 64-bit
+targets).
+
+//===----------------------------------------------------------------------===//
+// The proposal
+//===----------------------------------------------------------------------===//
+
+I suggest that we have the front-end fully lower out the ABI issues here to
+LLVM IR. This makes it 100% explicit what is going on and means that there is
+no cause for confusion. For example, the cases above should compile into:
+
+define i32 @z() nounwind {
+entry:
+ %0 = tail call i32 (...)* @y() nounwind
+ %1 = trunc i32 %0 to i16
+ %2 = sext i16 %1 to i32
+ ret i32 %2
+}
+define i32 @b() nounwind {
+entry:
+ %0 = tail call i32 (...)* @a() nounwind
+ %retval12 = trunc i32 %0 to i16
+ %tmp = sext i16 %retval12 to i32
+ ret i32 %tmp
+}
+
+In this model, no functions will return an i1/i8/i16 (and on a x86-64 target
+that extends results to i64, no i32). This solves the ambiguity issue, allows us
+to fully describe all possible ABIs, and now allows the optimizers to reason
+about and eliminate these extensions.
+
+The one thing that is missing is the ability for the front-end and optimizer to
+specify/infer the guarantees provided by the ABI to allow other optimizations.
+For example, in the y/z case, since y is known to return a sign extended value,
+the trunc/sext in z should be eliminable.
+
+This can be done by introducing new sext/zext attributes which mean "I know
+that the result of the function is sign extended at least N bits. Given this,
+and given that it is stuck on the y function, the mid-level optimizer could
+easily eliminate the extensions etc with existing functionality.
+
+The major disadvantage of doing this sort of thing is that it makes the ABI
+lowering stuff even more explicit in the front-end, and that we would like to
+eventually move to having the code generator do more of this work. However,
+the sad truth of the matter is that this is a) unlikely to happen anytime in
+the near future, and b) this is no worse than we have now with the existing
+attributes.
+
+C compilers fundamentally have to reason about the target in many ways.
+This is ugly and horrible, but a fact of life.
+
Added: www-releases/trunk/3.0/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/ExtendingLLVM.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/3.0/docs/ExtendingLLVM.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,392 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Extending LLVM: Adding instructions, intrinsics, types, etc.</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<body>
+
+<h1>
+ Extending LLVM: Adding instructions, intrinsics, types, etc.
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction and Warning</a></li>
+ <li><a href="#intrinsic">Adding a new intrinsic function</a></li>
+ <li><a href="#instruction">Adding a new instruction</a></li>
+ <li><a href="#sdnode">Adding a new SelectionDAG node</a></li>
+ <li><a href="#type">Adding a new type</a>
+ <ol>
+ <li><a href="#fund_type">Adding a new fundamental type</a></li>
+ <li><a href="#derived_type">Adding a new derived type</a></li>
+ </ol></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="http://misha.brukman.net">Misha Brukman</a>,
+ Brad Jones, Nate Begeman,
+ and <a href="http://nondot.org/sabre">Chris Lattner</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction and Warning</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>During the course of using LLVM, you may wish to customize it for your
+research project or for experimentation. At this point, you may realize that
+you need to add something to LLVM, whether it be a new fundamental type, a new
+intrinsic function, or a whole new instruction.</p>
+
+<p>When you come to this realization, stop and think. Do you really need to
+extend LLVM? Is it a new fundamental capability that LLVM does not support at
+its current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the <a
+href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM-dev</a> list. The
+reason is that extending LLVM will get involved as you need to update all the
+different passes that you intend to use with your extension, and there are
+<em>many</em> LLVM analyses and transformations, so it may be quite a bit of
+work.</p>
+
+<p>Adding an <a href="#intrinsic">intrinsic function</a> is far easier than
+adding an instruction, and is transparent to optimization passes. If your added
+functionality can be expressed as a
+function call, an intrinsic function is the method of choice for LLVM
+extension.</p>
+
+<p>Before you invest a significant amount of effort into a non-trivial
+extension, <span class="doc_warning">ask on the list</span> if what you are
+looking to do can be done with already-existing infrastructure, or if maybe
+someone else is already working on it. You will save yourself a lot of time and
+effort by doing so.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="intrinsic">Adding a new intrinsic function</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction. Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.</p>
+
+<ol>
+<li><tt>llvm/docs/LangRef.html</tt>:
+ Document the intrinsic. Decide whether it is code generator specific and
+ what the restrictions are. Talk to other people about it so that you are
+ sure it's a good idea.</li>
+
+<li><tt>llvm/include/llvm/Intrinsics*.td</tt>:
+ Add an entry for your intrinsic. Describe its memory access characteristics
+ for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
+ that any intrinsic using the <tt>llvm_int_ty</tt> type for an argument will
+ be deemed by <tt>tblgen</tt> as overloaded and the corresponding suffix
+ will be required on the intrinsic's name.</li>
+
+<li><tt>llvm/lib/Analysis/ConstantFolding.cpp</tt>: If it is possible to
+ constant fold your intrinsic, add support to it in the
+ <tt>canConstantFoldCallTo</tt> and <tt>ConstantFoldCall</tt> functions.</li>
+
+<li><tt>llvm/test/Regression/*</tt>: Add test cases for your test cases to the
+ test suite</li>
+</ol>
+
+<p>Once the intrinsic has been added to the system, you must add code generator
+support for it. Generally you must do the following steps:</p>
+
+<dl>
+<dt>Add support to the C backend in <tt>lib/Target/CBackend/</tt></dt>
+
+<dd>Depending on the intrinsic, there are a few ways to implement this. For
+ most intrinsics, it makes sense to add code to lower your intrinsic in
+ <tt>LowerIntrinsicCall</tt> in <tt>lib/CodeGen/IntrinsicLowering.cpp</tt>.
+ Second, if it makes sense to lower the intrinsic to an expanded sequence of
+ C code in all cases, just emit the expansion in <tt>visitCallInst</tt> in
+ <tt>Writer.cpp</tt>. If the intrinsic has some way to express it with GCC
+ (or any other compiler) extensions, it can be conditionally supported based
+ on the compiler compiling the CBE output (see <tt>llvm.prefetch</tt> for an
+ example). Third, if the intrinsic really has no way to be lowered, just
+ have the code generator emit code that prints an error message and calls
+ abort if executed.</dd>
+
+<dt>Add support to the .td file for the target(s) of your choice in
+ <tt>lib/Target/*/*.td</tt>.</dt>
+
+<dd>This is usually a matter of adding a pattern to the .td file that matches
+ the intrinsic, though it may obviously require adding the instructions you
+ want to generate as well. There are lots of examples in the PowerPC and X86
+ backend to follow.</dd>
+</dl>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="sdnode">Adding a new SelectionDAG node</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier
+than adding a new instruction. New nodes are often added to help represent
+instructions common to many targets. These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count). In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).</p>
+
+<ol>
+<li><tt>include/llvm/CodeGen/ISDOpcodes.h</tt>:
+ Add an enum value for the new SelectionDAG node.</li>
+<li><tt>lib/CodeGen/SelectionDAG/SelectionDAG.cpp</tt>:
+ Add code to print the node to <tt>getOperationName</tt>. If your new node
+ can be evaluated at compile time when given constant arguments (such as an
+ add of a constant with another constant), find the <tt>getNode</tt> method
+ that takes the appropriate number of arguments, and add a case for your node
+ to the switch statement that performs constant folding for nodes that take
+ the same number of arguments as your new node.</li>
+<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ Add code to <a href="CodeGenerator.html#selectiondag_legalize">legalize,
+ promote, and expand</a> the node as necessary. At a minimum, you will need
+ to add a case statement for your node in <tt>LegalizeOp</tt> which calls
+ LegalizeOp on the node's operands, and returns a new node if any of the
+ operands changed as a result of being legalized. It is likely that not all
+ targets supported by the SelectionDAG framework will natively support the
+ new node. In this case, you must also add code in your node's case
+ statement in <tt>LegalizeOp</tt> to Expand your node into simpler, legal
+ operations. The case for <tt>ISD::UREM</tt> for expanding a remainder into
+ a divide, multiply, and a subtract is a good example.</li>
+<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ If targets may support the new node being added only at certain sizes, you
+ will also need to add code to your node's case statement in
+ <tt>LegalizeOp</tt> to Promote your node's operands to a larger size, and
+ perform the correct operation. You will also need to add code to
+ <tt>PromoteOp</tt> to do this as well. For a good example, see
+ <tt>ISD::BSWAP</tt>,
+ which promotes its operand to a wider size, performs the byteswap, and then
+ shifts the correct bytes right to emulate the narrower byteswap in the
+ wider type.</li>
+<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
+ Add a case for your node in <tt>ExpandOp</tt> to teach the legalizer how to
+ perform the action represented by the new node on a value that has been
+ split into high and low halves. This case will be used to support your
+ node with a 64 bit operand on a 32 bit target.</li>
+<li><tt>lib/CodeGen/SelectionDAG/DAGCombiner.cpp</tt>:
+ If your node can be combined with itself, or other existing nodes in a
+ peephole-like fashion, add a visit function for it, and call that function
+ from <tt></tt>. There are several good examples for simple combines you
+ can do; <tt>visitFABS</tt> and <tt>visitSRL</tt> are good starting places.
+ </li>
+<li><tt>lib/Target/PowerPC/PPCISelLowering.cpp</tt>:
+ Each target has an implementation of the <tt>TargetLowering</tt> class,
+ usually in its own file (although some targets include it in the same
+ file as the DAGToDAGISel). The default behavior for a target is to
+ assume that your new node is legal for all types that are legal for
+ that target. If this target does not natively support your node, then
+ tell the target to either Promote it (if it is supported at a larger
+ type) or Expand it. This will cause the code you wrote in
+ <tt>LegalizeOp</tt> above to decompose your new node into other legal
+ nodes for this target.</li>
+<li><tt>lib/Target/TargetSelectionDAG.td</tt>:
+ Most current targets supported by LLVM generate code using the DAGToDAG
+ method, where SelectionDAG nodes are pattern matched to target-specific
+ nodes, which represent individual instructions. In order for the targets
+ to match an instruction to your new node, you must add a def for that node
+ to the list in this file, with the appropriate type constraints. Look at
+ <tt>add</tt>, <tt>bswap</tt>, and <tt>fadd</tt> for examples.</li>
+<li><tt>lib/Target/PowerPC/PPCInstrInfo.td</tt>:
+ Each target has a tablegen file that describes the target's instruction
+ set. For targets that use the DAGToDAG instruction selection framework,
+ add a pattern for your new node that uses one or more target nodes.
+ Documentation for this is a bit sparse right now, but there are several
+ decent examples. See the patterns for <tt>rotl</tt> in
+ <tt>PPCInstrInfo.td</tt>.</li>
+<li>TODO: document complex patterns.</li>
+<li><tt>llvm/test/Regression/CodeGen/*</tt>: Add test cases for your new node
+ to the test suite. <tt>llvm/test/Regression/CodeGen/X86/bswap.ll</tt> is
+ a good example.</li>
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="instruction">Adding a new instruction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p><span class="doc_warning">WARNING: adding instructions changes the bitcode
+format, and it will take some effort to maintain compatibility with
+the previous version.</span> Only add an instruction if it is absolutely
+necessary.</p>
+
+<ol>
+
+<li><tt>llvm/include/llvm/Instruction.def</tt>:
+ add a number for your instruction and an enum name</li>
+
+<li><tt>llvm/include/llvm/Instructions.h</tt>:
+ add a definition for the class that will represent your instruction</li>
+
+<li><tt>llvm/include/llvm/Support/InstVisitor.h</tt>:
+ add a prototype for a visitor to your new instruction type</li>
+
+<li><tt>llvm/lib/AsmParser/Lexer.l</tt>:
+ add a new token to parse your instruction from assembly text file</li>
+
+<li><tt>llvm/lib/AsmParser/llvmAsmParser.y</tt>:
+ add the grammar on how your instruction can be read and what it will
+ construct as a result</li>
+
+<li><tt>llvm/lib/Bitcode/Reader/Reader.cpp</tt>:
+ add a case for your instruction and how it will be parsed from bitcode</li>
+
+<li><tt>llvm/lib/VMCore/Instruction.cpp</tt>:
+ add a case for how your instruction will be printed out to assembly</li>
+
+<li><tt>llvm/lib/VMCore/Instructions.cpp</tt>:
+ implement the class you defined in
+ <tt>llvm/include/llvm/Instructions.h</tt></li>
+
+<li>Test your instruction</li>
+
+<li><tt>llvm/lib/Target/*</tt>:
+ Add support for your instruction to code generators, or add a lowering
+ pass.</li>
+
+<li><tt>llvm/test/Regression/*</tt>: add your test cases to the test suite.</li>
+
+</ol>
+
+<p>Also, you need to implement (or modify) any analyses or passes that you want
+to understand this new instruction.</p>
+
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="type">Adding a new type</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p><span class="doc_warning">WARNING: adding new types changes the bitcode
+format, and will break compatibility with currently-existing LLVM
+installations.</span> Only add new types if it is absolutely necessary.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="fund_type">Adding a fundamental type</a>
+</h3>
+
+<div>
+
+<ol>
+
+<li><tt>llvm/include/llvm/Type.h</tt>:
+ add enum for the new type; add static <tt>Type*</tt> for this type</li>
+
+<li><tt>llvm/lib/VMCore/Type.cpp</tt>:
+ add mapping from <tt>TypeID</tt> => <tt>Type*</tt>;
+ initialize the static <tt>Type*</tt></li>
+
+<li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
+ add ability to parse in the type from text assembly</li>
+
+<li><tt>llvm/lib/AsmReader/llvmAsmParser.y</tt>:
+ add a token for that type</li>
+
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="derived_type">Adding a derived type</a>
+</h3>
+
+<div>
+
+<ol>
+<li><tt>llvm/include/llvm/Type.h</tt>:
+ add enum for the new type; add a forward declaration of the type
+ also</li>
+
+<li><tt>llvm/include/llvm/DerivedTypes.h</tt>:
+ add new class to represent new class in the hierarchy; add forward
+ declaration to the TypeMap value type</li>
+
+<li><tt>llvm/lib/VMCore/Type.cpp</tt>:
+ add support for derived type to:
+<div class="doc_code">
+<pre>
+std::string getTypeDescription(const Type &Ty,
+ std::vector<const Type*> &TypeStack)
+bool TypesEqual(const Type *Ty, const Type *Ty2,
+ std::map<const Type*, const Type*> & EqTypes)
+</pre>
+</div>
+ add necessary member functions for type, and factory methods</li>
+
+<li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
+ add ability to parse in the type from text assembly</li>
+
+<li><tt>llvm/lib/BitCode/Writer/Writer.cpp</tt>:
+ modify <tt>void BitcodeWriter::outputType(const Type *T)</tt> to serialize
+ your type</li>
+
+<li><tt>llvm/lib/BitCode/Reader/Reader.cpp</tt>:
+ modify <tt>const Type *BitcodeReader::ParseType()</tt> to read your data
+ type</li>
+
+<li><tt>llvm/lib/VMCore/AsmWriter.cpp</tt>:
+ modify
+<div class="doc_code">
+<pre>
+void calcTypeName(const Type *Ty,
+ std::vector<const Type*> &TypeStack,
+ std::map<const Type*,std::string> &TypeNames,
+ std::string & Result)
+</pre>
+</div>
+ to output the new derived type
+</li>
+
+
+</ol>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date: 2011-11-03 01:43:23 -0500 (Thu, 03 Nov 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/FAQ.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/FAQ.html (added)
+++ www-releases/trunk/3.0/docs/FAQ.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,924 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM: Frequently Asked Questions</title>
+ <style type="text/css">
+ @import url("llvm.css");
+ .question { font-weight: bold }
+ .answer { margin-left: 2em }
+ </style>
+</head>
+<body>
+
+<h1>
+ LLVM: Frequently Asked Questions
+</h1>
+
+<ol>
+ <li><a href="#license">License</a>
+ <ol>
+ <li>Why are the LLVM source code and the front-end distributed under
+ different licenses?</li>
+
+ <li>Does the University of Illinois Open Source License really qualify as an
+ "open source" license?</li>
+
+ <li>Can I modify LLVM source code and redistribute the modified source?</li>
+
+ <li>Can I modify LLVM source code and redistribute binaries or other tools
+ based on it, without redistributing the source?</li>
+ </ol></li>
+
+ <li><a href="#source">Source code</a>
+ <ol>
+ <li>In what language is LLVM written?</li>
+
+ <li>How portable is the LLVM source code?</li>
+ </ol></li>
+
+ <li><a href="#build">Build Problems</a>
+ <ol>
+ <li>When I run configure, it finds the wrong C compiler.</li>
+
+ <li>The <tt>configure</tt> script finds the right C compiler, but it uses
+ the LLVM linker from a previous build. What do I do?</li>
+
+ <li>When creating a dynamic library, I get a strange GLIBC error.</li>
+
+ <li>I've updated my source tree from Subversion, and now my build is trying
+ to use a file/directory that doesn't exist.</li>
+
+ <li>I've modified a Makefile in my source tree, but my build tree keeps
+ using the old version. What do I do?</li>
+
+ <li>I've upgraded to a new version of LLVM, and I get strange build
+ errors.</li>
+
+ <li>I've built LLVM and am testing it, but the tests freeze.</li>
+
+ <li>Why do test results differ when I perform different types of
+ builds?</li>
+
+ <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
+
+ <li>Compiling LLVM with GCC succeeds, but the resulting tools do not work,
+ what can be wrong?</li>
+
+ <li>When I use the test suite, all of the C Backend tests fail. What is
+ wrong?</li>
+
+ <li>After Subversion update, rebuilding gives the error "No rule to make
+ target".</li>
+
+ <li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir,
+ it fails. Why?</a></li>
+ </ol></li>
+
+ <li><a href="#felangs">Source Languages</a>
+ <ol>
+ <li><a href="#langs">What source languages are supported?</a></li>
+
+ <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
+ should I interface with the LLVM middle-end optimizers and back-end code
+ generators?</a></li>
+
+ <li><a href="#langhlsupp">What support is there for higher level source
+ language constructs for building a compiler?</a></li>
+
+ <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
+ instruction. Help!</a></li>
+ </ol>
+
+ <li><a href="#cfe">Using the GCC Front End</a>
+ <ol>
+ <li>When I compile software that uses a configure script, the configure
+ script thinks my system has all of the header files and libraries it is
+ testing for. How do I get configure to work correctly?</li>
+
+ <li>When I compile code using the LLVM GCC front end, it complains that it
+ cannot find libcrtend.a?</li>
+
+ <li>How can I disable all optimizations when compiling code using the LLVM
+ GCC front end?</li>
+
+ <li><a href="#translatecxx">Can I use LLVM to convert C++ code to C
+ code?</a></li>
+
+ <li><a href="#platformindependent">Can I compile C or C++ code to
+ platform-independent LLVM bitcode?</a></li>
+ </ol>
+ </li>
+
+ <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
+ <ol>
+ <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
+ <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
+ #include <iostream>?</a></li>
+
+ <li><a href="#codedce">Where did all of my code go??</a></li>
+
+ <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
+ my code?</a></li>
+
+ <li><a href="#callconvwrong">Why does instcombine + simplifycfg turn
+ a call to a function with a mismatched calling convention into "unreachable"?
+ Why not make the verifier reject it?</a></li>
+ </ol>
+ </li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="http://llvm.org/">The LLVM Team</a></p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="license">License</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div class="question">
+<p>Why are the LLVM source code and the front-end distributed under different
+ licenses?</p>
+</div>
+
+<div class="answer">
+<p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
+ Our aim is to distribute LLVM source code under a <em>much less
+ restrictive</em> license, in particular one that does not compel users who
+ distribute tools based on modifying the source to redistribute the modified
+ source code as well.</p>
+</div>
+
+<div class="question">
+<p>Does the University of Illinois Open Source License really qualify as an
+ "open source" license?</p>
+</div>
+
+<div class="answer">
+<p>Yes, the license
+ is <a href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by
+ the Open Source Initiative (OSI).</p>
+</div>
+
+<div class="question">
+<p>Can I modify LLVM source code and redistribute the modified source?</p>
+</div>
+
+<div class="answer">
+<p>Yes. The modified source distribution must retain the copyright notice and
+ follow the three bulletted conditions listed in
+ the <a href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM
+ license</a>.</p>
+</div>
+
+<div class="question">
+<p>Can I modify LLVM source code and redistribute binaries or other tools based
+ on it, without redistributing the source?</p>
+</div>
+
+<div class="answer">
+<p>Yes. This is why we distribute LLVM under a less restrictive license than
+ GPL, as explained in the first question above.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="source">Source Code</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div class="question">
+<p>In what language is LLVM written?</p>
+</div>
+
+<div class="answer">
+<p>All of the LLVM tools and libraries are written in C++ with extensive use of
+ the STL.</p>
+</div>
+
+<div class="question">
+<p>How portable is the LLVM source code?</p>
+</div>
+
+<div class="answer">
+<p>The LLVM source code should be portable to most modern UNIX-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and test
+LLVM have been ported to a plethora of platforms.</p>
+
+<p>Some porting problems may exist in the following areas:</p>
+
+<ul>
+ <li>The GCC front end code is not as portable as the LLVM suite, so it may not
+ compile as well on unsupported platforms.</li>
+
+ <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
+ Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9)
+ will require more effort.</li>
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="build">Build Problems</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div class="question">
+<p>When I run configure, it finds the wrong C compiler.</p>
+</div>
+
+<div class="answer">
+<p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
+ <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt>
+ and <tt>CXX</tt> for the C and C++ compiler, respectively.</p>
+
+<p>If <tt>configure</tt> finds the wrong compiler, either adjust your
+ <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
+ explicitly.</p>
+
+</div>
+
+<div class="question">
+<p>The <tt>configure</tt> script finds the right C compiler, but it uses the
+ LLVM linker from a previous build. What do I do?</p>
+</div>
+
+<div class="answer">
+<p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
+ if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
+ it:</p>
+
+<ol>
+ <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
+ program appears first in the <tt>PATH</tt>. This may work, but may not be
+ convenient when you want them <i>first</i> in your path for other
+ work.</p></li>
+
+ <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
+ correct. In a Borne compatible shell, the syntax would be:</p>
+
+<pre class="doc_code">
+% PATH=[the path without the bad program] ./configure ...
+</pre>
+
+ <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
+ to do its work without having to adjust your <tt>PATH</tt>
+ permanently.</p></li>
+</ol>
+</div>
+
+<div class="question">
+<p>When creating a dynamic library, I get a strange GLIBC error.</p>
+</div>
+
+<div class="answer">
+<p>Under some operating systems (i.e. Linux), libtool does not work correctly if
+ GCC was compiled with the --disable-shared option. To work around this,
+ install your own version of GCC that has shared libraries enabled by
+ default.</p>
+</div>
+
+<div class="question">
+<p>I've updated my source tree from Subversion, and now my build is trying to
+ use a file/directory that doesn't exist.</p>
+</div>
+
+<div class="answer">
+<p>You need to re-run configure in your object directory. When new Makefiles
+ are added to the source tree, they have to be copied over to the object tree
+ in order to be used by the build.</p>
+</div>
+
+<div class="question">
+<p>I've modified a Makefile in my source tree, but my build tree keeps using the
+ old version. What do I do?</p>
+</div>
+
+<div class="answer">
+<p>If the Makefile already exists in your object tree, you can just run the
+ following command in the top level directory of your object tree:</p>
+
+<pre class="doc_code">
+% ./config.status <relative path to Makefile>
+</pre>
+
+<p>If the Makefile is new, you will have to modify the configure script to copy
+ it over.</p>
+</div>
+
+<div class="question">
+<p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
+</div>
+
+<div class="answer">
+
+<p>Sometimes, changes to the LLVM source code alters how the build system works.
+ Changes in libtool, autoconf, or header file dependencies are especially
+ prone to this sort of problem.</p>
+
+<p>The best thing to try is to remove the old files and re-build. In most
+ cases, this takes care of the problem. To do this, just type <tt>make
+ clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
+</div>
+
+<div class="question">
+<p>I've built LLVM and am testing it, but the tests freeze.</p>
+</div>
+
+<div class="answer">
+<p>This is most likely occurring because you built a profile or release
+ (optimized) build of LLVM and have not specified the same information on the
+ <tt>gmake</tt> command line.</p>
+
+<p>For example, if you built LLVM with the command:</p>
+
+<pre class="doc_code">
+% gmake ENABLE_PROFILING=1
+</pre>
+
+<p>...then you must run the tests with the following commands:</p>
+
+<pre class="doc_code">
+% cd llvm/test
+% gmake ENABLE_PROFILING=1
+</pre>
+</div>
+
+<div class="question">
+<p>Why do test results differ when I perform different types of builds?</p>
+</div>
+
+<div class="answer">
+<p>The LLVM test suite is dependent upon several features of the LLVM tools and
+ libraries.</p>
+
+<p>First, the debugging assertions in code are not enabled in optimized or
+ profiling builds. Hence, tests that used to fail may pass.</p>
+
+<p>Second, some tests may rely upon debugging options or behavior that is only
+ available in the debug build. These tests will fail in an optimized or
+ profile build.</p>
+</div>
+
+<div class="question">
+<p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
+</div>
+
+<div class="answer">
+<p>This is <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392">a bug in
+ GCC</a>, and affects projects other than LLVM. Try upgrading or downgrading
+ your GCC.</p>
+</div>
+
+<div class="question">
+<p>Compiling LLVM with GCC succeeds, but the resulting tools do not work, what
+ can be wrong?</p>
+</div>
+
+<div class="answer">
+<p>Several versions of GCC have shown a weakness in miscompiling the LLVM
+ codebase. Please consult your compiler version (<tt>gcc --version</tt>) to
+ find out whether it is <a href="GettingStarted.html#brokengcc">broken</a>.
+ If so, your only option is to upgrade GCC to a known good version.</p>
+</div>
+
+<div class="question">
+<p>After Subversion update, rebuilding gives the error "No rule to make
+ target".</p>
+</div>
+
+<div class="answer">
+<p>If the error is of the form:</p>
+
+<pre class="doc_code">
+gmake[2]: *** No rule to make target `/path/to/somefile', needed by
+`/path/to/another/file.d'.<br>
+Stop.
+</pre>
+
+<p>This may occur anytime files are moved within the Subversion repository or
+ removed entirely. In this case, the best solution is to erase all
+ <tt>.d</tt> files, which list dependencies for source files, and rebuild:</p>
+
+<pre class="doc_code">
+% cd $LLVM_OBJ_DIR
+% rm -f `find . -name \*\.d`
+% gmake
+</pre>
+
+<p>In other cases, it may be necessary to run <tt>make clean</tt> before
+ rebuilding.</p>
+</div>
+
+<div class="question">
+<p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it
+ fails. Why?</a></p>
+</div>
+
+<div class="answer">
+<p>The <tt>GNUmakefile</tt> in the top-level directory of LLVM-GCC is a special
+ <tt>Makefile</tt> used by Apple to invoke the <tt>build_gcc</tt> script after
+ setting up a special environment. This has the unfortunate side-effect that
+ trying to build LLVM-GCC with srcdir == objdir in a "non-Apple way" invokes
+ the <tt>GNUmakefile</tt> instead of <tt>Makefile</tt>. Because the
+ environment isn't set up correctly to do this, the build fails.</p>
+
+<p>People not building LLVM-GCC the "Apple way" need to build LLVM-GCC with
+ srcdir != objdir, or simply remove the GNUmakefile entirely.</p>
+
+<p>We regret the inconvenience.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="felangs">Source Languages</a>
+</h2>
+
+<div class="question">
+<p><a name="langs">What source languages are supported?</a></p>
+</div>
+
+<div class="answer">
+<p>LLVM currently has full support for C and C++ source languages. These are
+ available through a special version of GCC that LLVM calls the
+ <a href="#cfe">C Front End</a></p>
+
+<p>There is an incomplete version of a Java front end available in the
+ <tt>java</tt> module. There is no documentation on this yet so you'll need to
+ download the code, compile it, and try it.</p>
+
+<p>The PyPy developers are working on integrating LLVM into the PyPy backend so
+ that PyPy language can translate to LLVM.</p>
+</div>
+
+<div class="question">
+<p><a name="langirgen">I'd like to write a self-hosting LLVM compiler. How
+ should I interface with the LLVM middle-end optimizers and back-end code
+ generators?</a></p>
+</div>
+
+<div class="answer">
+<p>Your compiler front-end will communicate with LLVM by creating a module in
+ the LLVM intermediate representation (IR) format. Assuming you want to write
+ your language's compiler in the language itself (rather than C++), there are
+ 3 major ways to tackle generating LLVM IR from a front-end:</p>
+
+<ul>
+ <li><strong>Call into the LLVM libraries code using your language's FFI
+ (foreign function interface).</strong>
+
+ <ul>
+ <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc
+ format</li>
+
+ <li><em>for:</em> enables running LLVM optimization passes without a
+ emit/parse overhead</li>
+
+ <li><em>for:</em> adapts well to a JIT context</li>
+
+ <li><em>against:</em> lots of ugly glue code to write</li>
+ </ul></li>
+
+ <li> <strong>Emit LLVM assembly from your compiler's native language.</strong>
+ <ul>
+ <li><em>for:</em> very straightforward to get started</li>
+
+ <li><em>against:</em> the .ll parser is slower than the bitcode reader
+ when interfacing to the middle end</li>
+
+ <li><em>against:</em> you'll have to re-engineer the LLVM IR object model
+ and asm writer in your language</li>
+
+ <li><em>against:</em> it may be harder to track changes to the IR</li>
+ </ul></li>
+
+ <li><strong>Emit LLVM bitcode from your compiler's native language.</strong>
+
+ <ul>
+ <li><em>for:</em> can use the more-efficient bitcode reader when
+ interfacing to the middle end</li>
+
+ <li><em>against:</em> you'll have to re-engineer the LLVM IR object
+ model and bitcode writer in your language</li>
+
+ <li><em>against:</em> it may be harder to track changes to the IR</li>
+ </ul></li>
+</ul>
+
+<p>If you go with the first option, the C bindings in include/llvm-c should help
+ a lot, since most languages have strong support for interfacing with C. The
+ most common hurdle with calling C from managed code is interfacing with the
+ garbage collector. The C interface was designed to require very little memory
+ management, and so is straightforward in this regard.</p>
+</div>
+
+<div class="question">
+<p><a name="langhlsupp">What support is there for a higher level source language
+ constructs for building a compiler?</a></p>
+</div>
+
+<div class="answer">
+<p>Currently, there isn't much. LLVM supports an intermediate representation
+ which is useful for code representation but will not support the high level
+ (abstract syntax tree) representation needed by most compilers. There are no
+ facilities for lexical nor semantic analysis.</p>
+</div>
+
+<div class="question">
+<p><a name="getelementptr">I don't understand the GetElementPtr
+ instruction. Help!</a></p>
+</div>
+
+<div class="answer">
+<p>See <a href="GetElementPtr.html">The Often Misunderstood GEP
+ Instruction</a>.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="cfe">Using the GCC Front End</a>
+</h2>
+
+<div class="question">
+<p>When I compile software that uses a configure script, the configure script
+ thinks my system has all of the header files and libraries it is testing for.
+ How do I get configure to work correctly?</p>
+</div>
+
+<div class="answer">
+<p>The configure script is getting things wrong because the LLVM linker allows
+ symbols to be undefined at link time (so that they can be resolved during JIT
+ or translation to the C back end). That is why configure thinks your system
+ "has everything."</p>
+
+<p>To work around this, perform the following steps:</p>
+
+<ol>
+ <li>Make sure the CC and CXX environment variables contains the full path to
+ the LLVM GCC front end.</li>
+
+ <li>Make sure that the regular C compiler is first in your PATH. </li>
+
+ <li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
+</ol>
+
+<p>This will allow the <tt>llvm-ld</tt> linker to create a native code
+ executable instead of shell script that runs the JIT. Creating native code
+ requires standard linkage, which in turn will allow the configure script to
+ find out if code is not linking on your system because the feature isn't
+ available on your system.</p>
+</div>
+
+<div class="question">
+<p>When I compile code using the LLVM GCC front end, it complains that it cannot
+ find libcrtend.a.
+</p>
+</div>
+
+<div class="answer">
+<p>The only way this can happen is if you haven't installed the runtime
+ library. To correct this, do:</p>
+
+<pre class="doc_code">
+% cd llvm/runtime
+% make clean ; make install-bytecode
+</pre>
+</div>
+
+<div class="question">
+<p>How can I disable all optimizations when compiling code using the LLVM GCC
+ front end?</p>
+</div>
+
+<div class="answer">
+<p>Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
+ optimizations done at the llvm level, leaving you with the truly horrible
+ code that you desire.</p>
+</div>
+
+
+<div class="question">
+<p><a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a></p>
+</div>
+
+<div class="answer">
+<p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
+ Note that the generated C code will be very low level (all loops are lowered
+ to gotos, etc) and not very pretty (comments are stripped, original source
+ formatting is totally lost, variables are renamed, expressions are
+ regrouped), so this may not be what you're looking for. Also, there are
+ several limitations noted below.<p>
+
+<p>Use commands like this:</p>
+
+<ol>
+ <li><p>Compile your program with llvm-g++:</p>
+
+<pre class="doc_code">
+% llvm-g++ -emit-llvm x.cpp -o program.bc -c
+</pre>
+
+ <p>or:</p>
+
+<pre class="doc_code">
+% llvm-g++ a.cpp -c -emit-llvm
+% llvm-g++ b.cpp -c -emit-llvm
+% llvm-ld a.o b.o -o program
+</pre>
+
+ <p>This will generate program and program.bc. The .bc
+ file is the LLVM version of the program all linked together.</p></li>
+
+ <li><p>Convert the LLVM code to C code, using the LLC tool with the C
+ backend:</p>
+
+<pre class="doc_code">
+% llc -march=c program.bc -o program.c
+</pre></li>
+
+ <li><p>Finally, compile the C file:</p>
+
+<pre class="doc_code">
+% cc x.c -lstdc++
+</pre></li>
+
+</ol>
+
+<p>Using LLVM does not eliminate the need for C++ library support. If you use
+ the llvm-g++ front-end, the generated code will depend on g++'s C++ support
+ libraries in the same way that code generated from g++ would. If you use
+ another C++ front-end, the generated code will depend on whatever library
+ that front-end would normally require.</p>
+
+<p>If you are working on a platform that does not provide any C++ libraries, you
+ may be able to manually compile libstdc++ to LLVM bitcode, statically link it
+ into your program, then use the commands above to convert the whole result
+ into C code. Alternatively, you might compile the libraries and your
+ application into two different chunks of C code and link them.</p>
+
+<p>Note that, by default, the C back end does not support exception handling.
+ If you want/need it for a certain program, you can enable it by passing
+ "-enable-correct-eh-support" to the llc program. The resultant code will use
+ setjmp/longjmp to implement exception support that is relatively slow, and
+ not C++-ABI-conforming on most platforms, but otherwise correct.</p>
+
+<p>Also, there are a number of other limitations of the C backend that cause it
+ to produce code that does not fully conform to the C++ ABI on most
+ platforms. Some of the C++ programs in LLVM's test suite are known to fail
+ when compiled with the C back end because of ABI incompatibilities with
+ standard C++ libraries.</p>
+</div>
+
+<div class="question">
+<p><a name="platformindependent">Can I compile C or C++ code to
+ platform-independent LLVM bitcode?</a></p>
+</div>
+
+<div class="answer">
+<p>No. C and C++ are inherently platform-dependent languages. The most obvious
+ example of this is the preprocessor. A very common way that C code is made
+ portable is by using the preprocessor to include platform-specific code. In
+ practice, information about other platforms is lost after preprocessing, so
+ the result is inherently dependent on the platform that the preprocessing was
+ targeting.</p>
+
+<p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
+ vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
+ a constant immediately, thus hard-wiring a platform-specific detail.</p>
+
+<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
+ lower-level than C, front-ends currently must emit platform-specific IR in
+ order to have the result conform to the platform ABI.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="cfe_code">Questions about code generated by the GCC front-end</a>
+</h2>
+
+<div class="question">
+<p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
+ <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include
+ <iostream></tt>?</a></p>
+</div>
+
+<div class="answer">
+<p>If you <tt>#include</tt> the <tt><iostream></tt> header into a C++
+ translation unit, the file will probably use
+ the <tt>std::cin</tt>/<tt>std::cout</tt>/... global objects. However, C++
+ does not guarantee an order of initialization between static objects in
+ different translation units, so if a static ctor/dtor in your .cpp file
+ used <tt>std::cout</tt>, for example, the object would not necessarily be
+ automatically initialized before your use.</p>
+
+<p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
+ STL that we use declares a static object that gets created in every
+ translation unit that includes <tt><iostream></tt>. This object has a
+ static constructor and destructor that initializes and destroys the global
+ iostream objects before they could possibly be used in the file. The code
+ that you see in the .ll file corresponds to the constructor and destructor
+ registration code.
+</p>
+
+<p>If you would like to make it easier to <b>understand</b> the LLVM code
+ generated by the compiler in the demo page, consider using <tt>printf()</tt>
+ instead of <tt>iostream</tt>s to print values.</p>
+</div>
+
+<!--=========================================================================-->
+
+<div class="question">
+<p><a name="codedce">Where did all of my code go??</a></p>
+</div>
+
+<div class="answer">
+<p>If you are using the LLVM demo page, you may often wonder what happened to
+ all of the code that you typed in. Remember that the demo script is running
+ the code through the LLVM optimizers, so if your code doesn't actually do
+ anything useful, it might all be deleted.</p>
+
+<p>To prevent this, make sure that the code is actually needed. For example, if
+ you are computing some expression, return the value from the function instead
+ of leaving it in a local variable. If you really want to constrain the
+ optimizer, you can read from and assign to <tt>volatile</tt> global
+ variables.</p>
+</div>
+
+<!--=========================================================================-->
+
+<div class="question">
+<p><a name="undef">What is this "<tt>undef</tt>" thing that shows up in my
+ code?</a></p>
+</div>
+
+<div class="answer">
+<p><a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of
+ representing a value that is not defined. You can get these if you do not
+ initialize a variable before you use it. For example, the C function:</p>
+
+<pre class="doc_code">
+int X() { int i; return i; }
+</pre>
+
+<p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has a
+ value specified for it.</p>
+</div>
+
+<!--=========================================================================-->
+
+<div class="question">
+<p><a name="callconvwrong">Why does instcombine + simplifycfg turn
+ a call to a function with a mismatched calling convention into "unreachable"?
+ Why not make the verifier reject it?</a></p>
+</div>
+
+<div class="answer">
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For example,
+this code:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ call void @foo()
+ ret void
+}
+</pre>
+
+<p>Is optimized to:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ unreachable
+}
+</pre>
+
+<p>... with "opt -instcombine -simplifycfg". This often bites people because
+"all their code disappears". Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not make
+the verifier reject this sort of thing.</p>
+
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn't, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here's an example:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define internal void @bar(void()* %FP, i1 %cond) {
+ br i1 %cond, label %T, label %F
+T:
+ call void %FP()
+ ret void
+F:
+ call fastcc void %FP()
+ ret void
+}
+define void @test() {
+ %X = or i1 false, false
+ call void @bar(void()* @foo, i1 %X)
+ ret void
+}
+</pre>
+
+<p>In this example, "test" always passes @foo/false into bar, which ensures that
+ it is dynamically called with the right calling conv (thus, the code is
+ perfectly well defined). If you run this through the inliner, you get this
+ (the explicit "or" is there so that the inliner doesn't dead code eliminate
+ a bunch of stuff):
+</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @test() {
+ %X = or i1 false, false
+ br i1 %X, label %T.i, label %F.i
+T.i:
+ call void @foo()
+ br label %bar.exit
+F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+bar.exit:
+ ret void
+}
+</pre>
+
+<p>Here you can see that the inlining pass made an undefined call to @foo with
+ the wrong calling convention. We really don't want to make the inliner have
+ to know about this sort of thing, so it needs to be valid code. In this case,
+ dead code elimination can trivially remove the undefined code. However, if %X
+ was an input argument to @test, the inliner would produce this:
+</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+
+define void @test(i1 %X) {
+ br i1 %X, label %T.i, label %F.i
+T.i:
+ call void @foo()
+ br label %bar.exit
+F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+bar.exit:
+ ret void
+}
+</pre>
+
+<p>The interesting thing about this is that %X <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able to
+delete the broken call as unreachable. However, since instcombine/simplifycfg
+turns the undefined call into unreachable, we end up with a branch on a
+condition that goes to unreachable: a branch to unreachable can never happen, so
+"-inline -instcombine -simplifycfg" is able to produce:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @test(i1 %X) {
+F.i:
+ call fastcc void @foo()
+ ret void
+}
+</pre>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-09-19 19:42:28 -0500 (Mon, 19 Sep 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GCCFEBuildInstrs.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GCCFEBuildInstrs.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GCCFEBuildInstrs.html (added)
+++ www-releases/trunk/3.0/docs/GCCFEBuildInstrs.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,279 @@
+<!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 GCC Front-End</title>
+</head>
+<body>
+
+<h1>
+ Building the LLVM GCC Front-End
+</h1>
+
+<ol>
+ <li><a href="#instructions">Building llvm-gcc from Source</a></li>
+ <li><a href="#ada">Building the Ada front-end</a></li>
+ <li><a href="#fortran">Building the Fortran front-end</a></li>
+ <li><a href="#license">License Information</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by the LLVM Team</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="instructions">Building llvm-gcc from Source</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section describes how to acquire and build llvm-gcc 4.2, which is based
+on the GCC 4.2.1 front-end. Supported languages are Ada, C, C++, Fortran,
+Objective-C and Objective-C++. Note that the instructions for building these
+front-ends are completely different (and much easier!) than those for building
+llvm-gcc3 in the past.</p>
+
+<ol>
+ <li><p>Retrieve the appropriate llvm-gcc-4.2-<i>version</i>.source.tar.gz
+ archive from the <a href="http://llvm.org/releases/">LLVM web
+ site</a>.</p>
+
+ <p>It is also possible to download the sources of the llvm-gcc front end
+ from a read-only mirror using subversion. To check out the 4.2 code
+ for first time use:</p>
+
+<div class="doc_code">
+<pre>
+svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk <i>dst-directory</i>
+</pre>
+</div>
+
+ <p>After that, the code can be be updated in the destination directory
+ using:</p>
+
+<div class="doc_code">
+<pre>svn update</pre>
+</div>
+
+ <p>The mirror is brought up to date every evening.</p></li>
+
+ <li>Follow the directions in the top-level <tt>README.LLVM</tt> file for
+ up-to-date instructions on how to build llvm-gcc. See below for building
+ with support for Ada or Fortran.
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="ada">Building the Ada front-end</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p>Building with support for Ada amounts to following the directions in the
+top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example:
+<tt>EXTRALANGS=,ada</tt></p>
+
+<p>There are some complications however:</p>
+
+<ol>
+ <li><p>The only platform for which the Ada front-end is known to build is
+ 32 bit intel x86 running linux. It is unlikely to build for other
+ systems without some work.</p></li>
+ <li><p>The build requires having a compiler that supports Ada, C and C++.
+ The Ada front-end is written in Ada so an Ada compiler is needed to
+ build it. Compilers known to work with the
+ <a href="http://llvm.org/releases/download.html">LLVM 2.7 release</a>
+ are <a href="http://gcc.gnu.org/releases.html">gcc-4.2</a> and the
+ 2005, 2006 and 2007 versions of the
+ <a href="http://libre.adacore.com/">GNAT GPL Edition</a>.
+ <b>GNAT GPL 2008, gcc-4.3 and later will not work</b>.
+ The LLVM parts of llvm-gcc are written in C++ so a C++ compiler is
+ needed to build them. The rest of gcc is written in C.
+ Some linux distributions provide a version of gcc that supports all
+ three languages (the Ada part often comes as an add-on package to
+ the rest of gcc). Otherwise it is possible to combine two versions
+ of gcc, one that supports Ada and C (such as the
+ <a href="http://libre.adacore.com/">2007 GNAT GPL Edition</a>)
+ and another which supports C++, see below.</p></li>
+ <li><p>Because the Ada front-end is experimental, it is wise to build the
+ compiler with checking enabled. This causes it to run much slower, but
+ helps catch mistakes in the compiler (please report any problems using
+ <a href="http://llvm.org/bugs/">LLVM bugzilla</a>).</p></li>
+ <li><p>The Ada front-end <a href="http://llvm.org/PR2007">fails to
+ bootstrap</a>, due to lack of LLVM support for
+ <tt>setjmp</tt>/<tt>longjmp</tt> style exception handling (used
+ internally by the compiler), so you must specify
+ <tt>--disable-bootstrap</tt>.</p></li>
+</ol>
+
+<p>Supposing appropriate compilers are available, llvm-gcc with Ada support can
+ be built on an x86-32 linux box using the following recipe:</p>
+
+<ol>
+ <li><p>Download the <a href="http://llvm.org/releases/download.html">LLVM source</a>
+ and unpack it:</p>
+
+<pre class="doc_code">
+wget http://llvm.org/releases/2.7/llvm-2.7.tgz
+tar xzf llvm-2.7.tgz
+mv llvm-2.7 llvm
+</pre>
+
+ <p>or <a href="GettingStarted.html#checkout">check out the
+ latest version from subversion</a>:</p>
+
+<pre class="doc_code">svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</pre>
+
+ </li>
+
+ <li><p>Download the
+ <a href="http://llvm.org/releases/download.html">llvm-gcc-4.2 source</a>
+ and unpack it:</p>
+
+<pre class="doc_code">
+wget http://llvm.org/releases/2.7/llvm-gcc-4.2-2.7.source.tgz
+tar xzf llvm-gcc-4.2-2.7.source.tgz
+mv llvm-gcc-4.2-2.7.source llvm-gcc-4.2
+</pre>
+
+ <p>or <a href="GettingStarted.html#checkout">check out the
+ latest version from subversion</a>:</p>
+
+<pre class="doc_code">
+svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk llvm-gcc-4.2
+</pre>
+ </li>
+
+ <li><p>Make a build directory <tt>llvm-objects</tt> for llvm and make it the
+ current directory:</p>
+
+<pre class="doc_code">
+mkdir llvm-objects
+cd llvm-objects
+</pre>
+ </li>
+
+ <li><p>Configure LLVM (here it is configured to install into <tt>/usr/local</tt>):</p>
+
+<pre class="doc_code">
+../llvm/configure --prefix=<b>/usr/local</b> --enable-optimized --enable-assertions
+</pre>
+
+ <p>If you have a multi-compiler setup and the C++ compiler is not the
+ default, then you can configure like this:</p>
+
+<pre class="doc_code">
+CXX=<b>PATH_TO_C++_COMPILER</b> ../llvm/configure --prefix=<b>/usr/local</b> --enable-optimized --enable-assertions
+</pre>
+
+ <p>To compile without checking (not recommended), replace
+ <tt>--enable-assertions</tt> with <tt>--disable-assertions</tt>.</p>
+
+ </li>
+
+ <li><p>Build LLVM:</p>
+
+<pre class="doc_code">
+make
+</pre>
+ </li>
+
+ <li><p>Install LLVM (optional):</p>
+
+<pre class="doc_code">
+make install
+</pre>
+ </li>
+
+ <li><p>Make a build directory <tt>llvm-gcc-4.2-objects</tt> for llvm-gcc and make it the
+ current directory:</p>
+
+<pre class="doc_code">
+cd ..
+mkdir llvm-gcc-4.2-objects
+cd llvm-gcc-4.2-objects
+</pre>
+ </li>
+
+ <li><p>Configure llvm-gcc (here it is configured to install into <tt>/usr/local</tt>).
+ The <tt>--enable-checking</tt> flag turns on sanity checks inside the compiler.
+ To turn off these checks (not recommended), replace <tt>--enable-checking</tt>
+ with <tt>--disable-checking</tt>.
+ Additional languages can be appended to the <tt>--enable-languages</tt> switch,
+ for example <tt>--enable-languages=ada,c,c++</tt>.</p>
+
+<pre class="doc_code">
+../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c \
+ --enable-checking --enable-llvm=$PWD/../llvm-objects \
+ --disable-bootstrap --disable-multilib
+</pre>
+
+ <p>If you have a multi-compiler setup, then you can configure like this:</p>
+
+<pre class="doc_code">
+export CC=<b>PATH_TO_C_AND_ADA_COMPILER</b>
+export CXX=<b>PATH_TO_C++_COMPILER</b>
+../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c \
+ --enable-checking --enable-llvm=$PWD/../llvm-objects \
+ --disable-bootstrap --disable-multilib
+</pre>
+ </li>
+
+ <li><p>Build and install the compiler:</p>
+
+<pre class="doc_code">
+make
+make install
+</pre>
+ </li>
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="fortran">Building the Fortran front-end</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p>To build with support for Fortran, follow the directions in the top-level
+<tt>README.LLVM</tt> file, adding ",fortran" to EXTRALANGS, for example:</p>
+
+<pre class="doc_code">
+EXTRALANGS=,fortran
+</pre>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="license">License Information</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p>
+The LLVM GCC frontend is licensed to you under the GNU General Public License
+and the GNU Lesser General Public License. Please see the files COPYING and
+COPYING.LIB for more details.
+</p>
+
+<p>
+More information is <a href="FAQ.html#license">available in the FAQ</a>.
+</p>
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-04-22 19:30:22 -0500 (Fri, 22 Apr 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GarbageCollection.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GarbageCollection.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GarbageCollection.html (added)
+++ www-releases/trunk/3.0/docs/GarbageCollection.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1386 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" Content="text/html; charset=UTF-8" >
+ <title>Accurate Garbage Collection with LLVM</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <style type="text/css">
+ .rowhead { text-align: left; background: inherit; }
+ .indent { padding-left: 1em; }
+ .optl { color: #BFBFBF; }
+ </style>
+</head>
+<body>
+
+<h1>
+ Accurate Garbage Collection with LLVM
+</h1>
+
+<ol>
+ <li><a href="#introduction">Introduction</a>
+ <ul>
+ <li><a href="#feature">Goals and non-goals</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#quickstart">Getting started</a>
+ <ul>
+ <li><a href="#quickstart-compiler">In your compiler</a></li>
+ <li><a href="#quickstart-runtime">In your runtime library</a></li>
+ <li><a href="#shadow-stack">About the shadow stack</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#core">Core support</a>
+ <ul>
+ <li><a href="#gcattr">Specifying GC code generation:
+ <tt>gc "..."</tt></a></li>
+ <li><a href="#gcroot">Identifying GC roots on the stack:
+ <tt>llvm.gcroot</tt></a></li>
+ <li><a href="#barriers">Reading and writing references in the heap</a>
+ <ul>
+ <li><a href="#gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a></li>
+ <li><a href="#gcread">Read barrier: <tt>llvm.gcread</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+
+ <li><a href="#plugin">Compiler plugin interface</a>
+ <ul>
+ <li><a href="#collector-algos">Overview of available features</a></li>
+ <li><a href="#stack-map">Computing stack maps</a></li>
+ <li><a href="#init-roots">Initializing roots to null:
+ <tt>InitRoots</tt></a></li>
+ <li><a href="#custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>,
+ <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a></li>
+ <li><a href="#safe-points">Generating safe points:
+ <tt>NeededSafePoints</tt></a></li>
+ <li><a href="#assembly">Emitting assembly code:
+ <tt>GCMetadataPrinter</tt></a></li>
+ </ul>
+ </li>
+
+ <li><a href="#runtime-impl">Implementing a collector runtime</a>
+ <ul>
+ <li><a href="#gcdescriptors">Tracing GC pointers from heap
+ objects</a></li>
+ </ul>
+ </li>
+
+ <li><a href="#references">References</a></li>
+
+</ol>
+
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a> and
+ Gordon Henriksen</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="introduction">Introduction</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.</p>
+
+<p>Conservative garbage collection often does not require any special support
+from either the language or the compiler: it can handle non-type-safe
+programming languages (such as C/C++) and does not require any special
+information from the compiler. The
+<a href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is
+an example of a state-of-the-art conservative collector.</p>
+
+<p>Accurate garbage collection requires the ability to identify all pointers in
+the program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+<a href="#gcroot">processor stack and registers</a>.</p>
+
+<p>Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot <i>know</i> that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).</p>
+
+<p>Accurate garbage collectors do not suffer from any of these problems, but
+they can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.</p>
+
+<p>This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="feature">Goals and non-goals</a>
+</h3>
+
+<div>
+
+<p>LLVM's intermediate representation provides <a href="#intrinsics">garbage
+collection intrinsics</a> that offer support for a broad class of
+collector models. For instance, the intrinsics permit:</p>
+
+<ul>
+ <li>semi-space collectors</li>
+ <li>mark-sweep collectors</li>
+ <li>generational collectors</li>
+ <li>reference counting</li>
+ <li>incremental collectors</li>
+ <li>concurrent collectors</li>
+ <li>cooperative collectors</li>
+</ul>
+
+<p>We hope that the primitive support built into the LLVM IR is sufficient to
+support a broad class of garbage collected languages including Scheme, ML, Java,
+C#, Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+
+<p>However, LLVM does not itself provide a garbage collector—this should
+be part of your language's runtime library. LLVM provides a framework for
+compile time <a href="#plugin">code generation plugins</a>. The role of these
+plugins is to generate code and data structures which conforms to the <em>binary
+interface</em> specified by the <em>runtime library</em>. This is similar to the
+relationship between LLVM and DWARF debugging info, for example. The
+difference primarily lies in the lack of an established standard in the domain
+of garbage collection—thus the plugins.</p>
+
+<p>The aspects of the binary interface with which LLVM's GC support is
+concerned are:</p>
+
+<ul>
+ <li>Creation of GC-safe points within code where collection is allowed to
+ execute safely.</li>
+ <li>Computation of the stack map. For each safe point in the code, object
+ references within the stack frame must be identified so that the
+ collector may traverse and perhaps update them.</li>
+ <li>Write barriers when storing object references to the heap. These are
+ commonly used to optimize incremental scans in generational
+ collectors.</li>
+ <li>Emission of read barriers when loading object references. These are
+ useful for interoperating with concurrent collectors.</li>
+</ul>
+
+<p>There are additional areas that LLVM does not directly address:</p>
+
+<ul>
+ <li>Registration of global roots with the runtime.</li>
+ <li>Registration of stack map entries with the runtime.</li>
+ <li>The functions used by the program to allocate memory, trigger a
+ collection, etc.</li>
+ <li>Computation or compilation of type maps, or registration of them with
+ the runtime. These are used to crawl the heap for object
+ references.</li>
+</ul>
+
+<p>In general, LLVM's support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it leaves
+a lot of work for the developer of a novel language. However, it's easy to get
+started quickly and scale up to a more sophisticated implementation as your
+compiler matures.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="quickstart">Getting started</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Using a GC with LLVM implies many things, for example:</p>
+
+<ul>
+ <li>Write a runtime library or find an existing one which implements a GC
+ heap.<ol>
+ <li>Implement a memory allocator.</li>
+ <li>Design a binary interface for the stack map, used to identify
+ references within a stack frame on the machine stack.*</li>
+ <li>Implement a stack crawler to discover functions on the call stack.*</li>
+ <li>Implement a registry for global roots.</li>
+ <li>Design a binary interface for type maps, used to identify references
+ within heap objects.</li>
+ <li>Implement a collection routine bringing together all of the above.</li>
+ </ol></li>
+ <li>Emit compatible code from your compiler.<ul>
+ <li>Initialization in the main function.</li>
+ <li>Use the <tt>gc "..."</tt> attribute to enable GC code generation
+ (or <tt>F.setGC("...")</tt>).</li>
+ <li>Use <tt>@llvm.gcroot</tt> to mark stack roots.</li>
+ <li>Use <tt>@llvm.gcread</tt> and/or <tt>@llvm.gcwrite</tt> to
+ manipulate GC references, if necessary.</li>
+ <li>Allocate memory using the GC allocation routine provided by the
+ runtime library.</li>
+ <li>Generate type maps according to your runtime's binary interface.</li>
+ </ul></li>
+ <li>Write a compiler plugin to interface LLVM with the runtime library.*<ul>
+ <li>Lower <tt>@llvm.gcread</tt> and <tt>@llvm.gcwrite</tt> to appropriate
+ code sequences.*</li>
+ <li>Compile LLVM's stack map to the binary form expected by the
+ runtime.</li>
+ </ul></li>
+ <li>Load the plugin into the compiler. Use <tt>llc -load</tt> or link the
+ plugin statically with your language's compiler.*</li>
+ <li>Link program executables with the runtime.</li>
+</ul>
+
+<p>To help with several of these tasks (those indicated with a *), LLVM
+includes a highly portable, built-in ShadowStack code generator. It is compiled
+into <tt>llc</tt> and works even with the interpreter and C backends.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="quickstart-compiler">In your compiler</a>
+</h3>
+
+<div>
+
+<p>To turn the shadow stack on for your functions, first call:</p>
+
+<div class="doc_code"><pre
+>F.setGC("shadow-stack");</pre></div>
+
+<p>for each function your compiler emits. Since the shadow stack is built into
+LLVM, you do not need to load a plugin.</p>
+
+<p>Your compiler must also use <tt>@llvm.gcroot</tt> as documented.
+Don't forget to create a root for each intermediate value that is generated
+when evaluating an expression. In <tt>h(f(), g())</tt>, the result of
+<tt>f()</tt> could easily be collected if evaluating <tt>g()</tt> triggers a
+collection.</p>
+
+<p>There's no need to use <tt>@llvm.gcread</tt> and <tt>@llvm.gcwrite</tt> over
+plain <tt>load</tt> and <tt>store</tt> for now. You will need them when
+switching to a more advanced GC.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="quickstart-runtime">In your runtime</a>
+</h3>
+
+<div>
+
+<p>The shadow stack doesn't imply a memory allocation algorithm. A semispace
+collector or building atop <tt>malloc</tt> are great places to start, and can
+be implemented with very little code.</p>
+
+<p>When it comes time to collect, however, your runtime needs to traverse the
+stack roots, and for this it needs to integrate with the shadow stack. Luckily,
+doing so is very simple. (This code is heavily commented to help you
+understand the data structure, but there are only 20 lines of meaningful
+code.)</p>
+
+<pre class="doc_code">
+/// @brief The map for a single function's stack frame. One of these is
+/// compiled as constant data into the executable for each function.
+///
+/// Storage of metadata values is elided if the %metadata parameter to
+/// @llvm.gcroot is null.
+struct FrameMap {
+ int32_t NumRoots; //< Number of roots in stack frame.
+ int32_t NumMeta; //< Number of metadata entries. May be < NumRoots.
+ const void *Meta[0]; //< Metadata for each root.
+};
+
+/// @brief A link in the dynamic shadow stack. One of these is embedded in the
+/// stack frame of each function on the call stack.
+struct StackEntry {
+ StackEntry *Next; //< Link to next stack entry (the caller's).
+ const FrameMap *Map; //< Pointer to constant FrameMap.
+ void *Roots[0]; //< Stack roots (in-place array).
+};
+
+/// @brief The head of the singly-linked list of StackEntries. Functions push
+/// and pop onto this in their prologue and epilogue.
+///
+/// Since there is only a global list, this technique is not threadsafe.
+StackEntry *llvm_gc_root_chain;
+
+/// @brief Calls Visitor(root, meta) for each GC root on the stack.
+/// root and meta are exactly the values passed to
+/// <tt>@llvm.gcroot</tt>.
+///
+/// Visitor could be a function to recursively mark live objects. Or it
+/// might copy them to another heap or generation.
+///
+/// @param Visitor A function to invoke for every GC root on the stack.
+void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) {
+ for (StackEntry *R = llvm_gc_root_chain; R; R = R->Next) {
+ unsigned i = 0;
+
+ // For roots [0, NumMeta), the metadata pointer is in the FrameMap.
+ for (unsigned e = R->Map->NumMeta; i != e; ++i)
+ Visitor(&R->Roots[i], R->Map->Meta[i]);
+
+ // For roots [NumMeta, NumRoots), the metadata pointer is null.
+ for (unsigned e = R->Map->NumRoots; i != e; ++i)
+ Visitor(&R->Roots[i], NULL);
+ }
+}</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="shadow-stack">About the shadow stack</a>
+</h3>
+
+<div>
+
+<p>Unlike many GC algorithms which rely on a cooperative code generator to
+compile stack maps, this algorithm carefully maintains a linked list of stack
+roots [<a href="#henderson02">Henderson2002</a>]. This so-called "shadow stack"
+mirrors the machine stack. Maintaining this data structure is slower than using
+a stack map compiled into the executable as constant data, but has a significant
+portability advantage because it requires no special support from the target
+code generator, and does not require tricky platform-specific code to crawl
+the machine stack.</p>
+
+<p>The tradeoff for this simplicity and portability is:</p>
+
+<ul>
+ <li>High overhead per function call.</li>
+ <li>Not thread-safe.</li>
+</ul>
+
+<p>Still, it's an easy way to get started. After your compiler and runtime are
+up and running, writing a <a href="#plugin">plugin</a> will allow you to take
+advantage of <a href="#collector-algos">more advanced GC features</a> of LLVM
+in order to improve performance.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="core">IR features</a><a name="intrinsics"></a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section describes the garbage collection facilities provided by the
+<a href="LangRef.html">LLVM intermediate representation</a>. The exact behavior
+of these IR features is specified by the binary interface implemented by a
+<a href="#plugin">code generation plugin</a>, not by this document.</p>
+
+<p>These facilities are limited to those strictly necessary; they are not
+intended to be a complete interface to any garbage collector. A program will
+need to interface with the GC library using the facilities provided by that
+program.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
+</h3>
+
+<div>
+
+<div class="doc_code"><tt>
+ define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ...
+</tt></div>
+
+<p>The <tt>gc</tt> function attribute is used to specify the desired GC style
+to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of
+<tt>Function</tt>.</p>
+
+<p>Setting <tt>gc "<i>name</i>"</tt> on a function triggers a search for a
+matching code generation plugin "<i>name</i>"; it is that plugin which defines
+the exact nature of the code generated to support GC. If none is found, the
+compiler will raise an error.</p>
+
+<p>Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="gcroot">Identifying GC roots on the stack: <tt>llvm.gcroot</tt></a>
+</h3>
+
+<div>
+
+<div class="doc_code"><tt>
+ void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+</tt></div>
+
+<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>
+
+<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
+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>
+
+<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
+should be associated with the pointer, and <b>must</b> be a constant or global
+value address. If your target collector uses tags, use a null pointer for
+metadata.</p>
+
+<p>The <tt>%metadata</tt> argument can be used to avoid requiring heap objects
+to have 'isa' pointers or tag bits. [<a href="#appel89">Appel89</a>, <a
+href="#goldberg91">Goldberg91</a>, <a href="#tolmach94">Tolmach94</a>] If
+specified, its value will be tracked along with the location of the pointer in
+the stack frame.</p>
+
+<p>Consider the following fragment of Java code:</p>
+
+<pre class="doc_code">
+ {
+ Object X; // A null-initialized reference to an object
+ ...
+ }
+</pre>
+
+<p>This block (which may be located in the middle of a function or in a loop
+nest), could be compiled to this LLVM code:</p>
+
+<pre class="doc_code">
+Entry:
+ ;; In the entry block for the function, allocate the
+ ;; stack space for X, which is an LLVM pointer.
+ %X = alloca %Object*
+
+ ;; Tell LLVM that the stack space is a stack root.
+ ;; Java has type-tags on objects, so we pass null as metadata.
+ %tmp = bitcast %Object** %X to i8**
+ call void @llvm.gcroot(i8** %X, i8* null)
+ ...
+
+ ;; "CodeBlock" is the block corresponding to the start
+ ;; of the scope above.
+CodeBlock:
+ ;; Java null-initializes pointers.
+ store %Object* null, %Object** %X
+
+ ...
+
+ ;; As the pointer goes out of scope, store a null value into
+ ;; it, to indicate that the value is no longer live.
+ store %Object* null, %Object** %X
+ ...
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="barriers">Reading and writing references in the heap</a>
+</h3>
+
+<div>
+
+<p>Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called
+<em>read barriers</em> and <em>write barriers</em>, respectively. The amount of
+code that needs to be executed is usually quite small and not on the critical
+path of any computation, so the overall performance impact of the barrier is
+tolerable.</p>
+
+<p>Barriers often require access to the <em>object pointer</em> rather than the
+<em>derived pointer</em> (which is a pointer to the field within the
+object). Accordingly, these intrinsics take both pointers as separate arguments
+for completeness. In this snippet, <tt>%object</tt> is the object pointer, and
+<tt>%derived</tt> is the derived pointer:</p>
+
+<blockquote><pre>
+ ;; An array type.
+ %class.Array = type { %class.Object, i32, [0 x %class.Object*] }
+ ...
+
+ ;; Load the object pointer from a gcroot.
+ %object = load %class.Array** %object_addr
+
+ ;; Compute the derived pointer.
+ %derived = getelementptr %object, i32 0, i32 2, i32 %n</pre></blockquote>
+
+<p>LLVM does not enforce this relationship between the object and derived
+pointer (although a <a href="#plugin">plugin</a> might). However, it would be
+an unusual collector that violated it.</p>
+
+<p>The use of these intrinsics is naturally optional if the target GC does
+require the corresponding barrier. Such a GC plugin will replace the intrinsic
+calls with the corresponding <tt>load</tt> or <tt>store</tt> instruction if they
+are used.</p>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a>
+</h4>
+
+<div>
+
+<div class="doc_code"><tt>
+void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
+</tt></div>
+
+<p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic
+function. It has exactly the same semantics as a non-volatile <tt>store</tt> to
+the derived pointer (the third argument). The exact code generated is specified
+by a <a href="#plugin">compiler plugin</a>.</p>
+
+<p>Many important algorithms require write barriers, including generational
+and concurrent collectors. Additionally, write barriers could be used to
+implement reference counting.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="gcread">Read barrier: <tt>llvm.gcread</tt></a>
+</h4>
+
+<div>
+
+<div class="doc_code"><tt>
+i8* @llvm.gcread(i8* %object, i8** %derived)<br>
+</tt></div>
+
+<p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function.
+It has exactly the same semantics as a non-volatile <tt>load</tt> from the
+derived pointer (the second argument). The exact code generated is specified by
+a <a href="#plugin">compiler plugin</a>.</p>
+
+<p>Read barriers are needed by fewer algorithms than write barriers, and may
+have a greater performance impact since pointer reads are more frequent than
+writes.</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="plugin">Implementing a collector plugin</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>User code specifies which GC code generation to use with the <tt>gc</tt>
+function attribute or, equivalently, with the <tt>setGC</tt> method of
+<tt>Function</tt>.</p>
+
+<p>To implement a GC plugin, it is necessary to subclass
+<tt>llvm::GCStrategy</tt>, which can be accomplished in a few lines of
+boilerplate code. LLVM's infrastructure provides access to several important
+algorithms. For an uncontroversial collector, all that remains may be to
+compile LLVM's computed stack map to assembly code (using the binary
+representation expected by the runtime library). This can be accomplished in
+about 100 lines of code.</p>
+
+<p>This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the language's runtime
+library. The compiler plugin is responsible for generating code which
+conforms to the binary interface defined by library, most essentially the
+<a href="#stack-map">stack map</a>.</p>
+
+<p>To subclass <tt>llvm::GCStrategy</tt> and register it with the compiler:</p>
+
+<blockquote><pre>// lib/MyGC/MyGC.cpp - Example LLVM GC plugin
+
+#include "llvm/CodeGen/GCStrategy.h"
+#include "llvm/CodeGen/GCMetadata.h"
+#include "llvm/Support/Compiler.h"
+
+using namespace llvm;
+
+namespace {
+ class LLVM_LIBRARY_VISIBILITY MyGC : public GCStrategy {
+ public:
+ MyGC() {}
+ };
+
+ GCRegistry::Add<MyGC>
+ X("mygc", "My bespoke garbage collector.");
+}</pre></blockquote>
+
+<p>This boilerplate collector does nothing. More specifically:</p>
+
+<ul>
+ <li><tt>llvm.gcread</tt> calls are replaced with the corresponding
+ <tt>load</tt> instruction.</li>
+ <li><tt>llvm.gcwrite</tt> calls are replaced with the corresponding
+ <tt>store</tt> instruction.</li>
+ <li>No safe points are added to the code.</li>
+ <li>The stack map is not compiled into the executable.</li>
+</ul>
+
+<p>Using the LLVM makefiles (like the <a
+href="http://llvm.org/viewvc/llvm-project/llvm/trunk/projects/sample/">sample
+project</a>), this code can be compiled as a plugin using a simple
+makefile:</p>
+
+<blockquote><pre
+># lib/MyGC/Makefile
+
+LEVEL := ../..
+LIBRARYNAME = <var>MyGC</var>
+LOADABLE_MODULE = 1
+
+include $(LEVEL)/Makefile.common</pre></blockquote>
+
+<p>Once the plugin is compiled, code using it may be compiled using <tt>llc
+-load=<var>MyGC.so</var></tt> (though <var>MyGC.so</var> may have some other
+platform-specific extension):</p>
+
+<blockquote><pre
+>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < sample.ll | llc -load=MyGC.so</pre></blockquote>
+
+<p>It is also possible to statically link the collector plugin into tools, such
+as a language-specific compiler front-end.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="collector-algos">Overview of available features</a>
+</h3>
+
+<div>
+
+<p><tt>GCStrategy</tt> provides a range of features through which a plugin
+may do useful work. Some of these are callbacks, some are algorithms that can
+be enabled, disabled, or customized. This matrix summarizes the supported (and
+planned) features and correlates them with the collection techniques which
+typically require them.</p>
+
+<table>
+ <tr>
+ <th>Algorithm</th>
+ <th>Done</th>
+ <th>shadow stack</th>
+ <th>refcount</th>
+ <th>mark-sweep</th>
+ <th>copying</th>
+ <th>incremental</th>
+ <th>threaded</th>
+ <th>concurrent</th>
+ </tr>
+ <tr>
+ <th class="rowhead"><a href="#stack-map">stack map</a></th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><a href="#init-roots">initialize roots</a></th>
+ <td>✔</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">derived pointers</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘*</td>
+ <td>✘*</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em><a href="#custom">custom lowering</a></em></th>
+ <td>✔</td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcroot</th>
+ <td>✔</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcwrite</th>
+ <td>✔</td>
+ <td></td>
+ <td>✘</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td></td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">gcread</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em><a href="#safe-points">safe points</a></em></th>
+ <td></td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent">in calls</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">before calls</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">for loops</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead indent">before escape</th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">emit code at safe points</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr>
+ <th class="rowhead"><em>output</em></th>
+ <td></td>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ <th></th>
+ </tr>
+ <tr>
+ <th class="rowhead indent"><a href="#assembly">assembly</a></th>
+ <td>✔</td>
+ <td></td>
+ <td></td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ <td>✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">JIT</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead indent">obj</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">live analysis</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr class="doc_warning">
+ <th class="rowhead">register map</th>
+ <td>NO</td>
+ <td></td>
+ <td></td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ <td class="optl">✘</td>
+ </tr>
+ <tr>
+ <td colspan="10">
+ <div><span class="doc_warning">*</span> Derived pointers only pose a
+ hazard to copying collectors.</div>
+ <div><span class="optl">✘</span> in gray denotes a feature which
+ could be utilized if available.</div>
+ </td>
+ </tr>
+</table>
+
+<p>To be clear, the collection techniques above are defined as:</p>
+
+<dl>
+ <dt>Shadow Stack</dt>
+ <dd>The mutator carefully maintains a linked list of stack roots.</dd>
+ <dt>Reference Counting</dt>
+ <dd>The mutator maintains a reference count for each object and frees an
+ object when its count falls to zero.</dd>
+ <dt>Mark-Sweep</dt>
+ <dd>When the heap is exhausted, the collector marks reachable objects starting
+ from the roots, then deallocates unreachable objects in a sweep
+ phase.</dd>
+ <dt>Copying</dt>
+ <dd>As reachability analysis proceeds, the collector copies objects from one
+ heap area to another, compacting them in the process. Copying collectors
+ enable highly efficient "bump pointer" allocation and can improve locality
+ of reference.</dd>
+ <dt>Incremental</dt>
+ <dd>(Including generational collectors.) Incremental collectors generally have
+ all the properties of a copying collector (regardless of whether the
+ mature heap is compacting), but bring the added complexity of requiring
+ write barriers.</dd>
+ <dt>Threaded</dt>
+ <dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+ ("stop the world") before beginning reachability analysis. Stopping a
+ multithreaded mutator is a complicated problem. It generally requires
+ highly platform specific code in the runtime, and the production of
+ carefully designed machine code at safe points.</dd>
+ <dt>Concurrent</dt>
+ <dd>In this technique, the mutator and the collector run concurrently, with
+ the goal of eliminating pause times. In a <em>cooperative</em> collector,
+ the mutator further aids with collection should a pause occur, allowing
+ collection to take advantage of multiprocessor hosts. The "stop the world"
+ problem of threaded collectors is generally still present to a limited
+ extent. Sophisticated marking algorithms are necessary. Read barriers may
+ be necessary.</dd>
+</dl>
+
+<p>As the matrix indicates, LLVM's garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="stack-map">Computing stack maps</a>
+</h3>
+
+<div>
+
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <tt>GCStrategy</tt> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+
+<ul>
+ <li><tt>RootNum</tt>: The index of the root.</li>
+ <li><tt>StackOffset</tt>: The offset of the object relative to the frame
+ pointer.</li>
+ <li><tt>RootMetadata</tt>: The value passed as the <tt>%metadata</tt>
+ parameter to the <a href="#gcroot"><tt>@llvm.gcroot</tt></a> intrinsic.</li>
+</ul>
+
+<p>Also, for the function as a whole:</p>
+
+<ul>
+ <li><tt>getFrameSize()</tt>: The overall size of the function's initial
+ stack frame, not accounting for any dynamic allocation.</li>
+ <li><tt>roots_size()</tt>: The count of roots in the function.</li>
+</ul>
+
+<p>To access the stack map, use <tt>GCFunctionMetadata::roots_begin()</tt> and
+-<tt>end()</tt> from the <tt><a
+href="#assembly">GCMetadataPrinter</a></tt>:</p>
+
+<blockquote><pre
+>for (iterator I = begin(), E = end(); I != E; ++I) {
+ GCFunctionInfo *FI = *I;
+ unsigned FrameSize = FI->getFrameSize();
+ size_t RootCount = FI->roots_size();
+
+ for (GCFunctionInfo::roots_iterator RI = FI->roots_begin(),
+ RE = FI->roots_end();
+ RI != RE; ++RI) {
+ int RootNum = RI->Num;
+ int RootStackOffset = RI->StackOffset;
+ Constant *RootMetadata = RI->Metadata;
+ }
+}</pre></blockquote>
+
+<p>If the <tt>llvm.gcroot</tt> intrinsic is eliminated before code generation by
+a custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a>
+</h3>
+
+<div>
+
+<blockquote><pre
+>MyGC::MyGC() {
+ InitRoots = true;
+}</pre></blockquote>
+
+<p>When set, LLVM will automatically initialize each root to <tt>null</tt> upon
+entry to the function. This prevents the GC's sweep phase from visiting
+uninitialized pointers, which will almost certainly cause it to crash. This
+initialization occurs before custom lowering, so the two may be used
+together.</p>
+
+<p>Since LLVM does not yet compute liveness information, there is no means of
+distinguishing an uninitialized stack root from an initialized one. Therefore,
+this feature should be used by all GC plugins. It is enabled by default.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="custom">Custom lowering of intrinsics: <tt>CustomRoots</tt>,
+ <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a>
+</h3>
+
+<div>
+
+<p>For GCs which use barriers or unusual treatment of stack roots, these
+flags allow the collector to perform arbitrary transformations of the LLVM
+IR:</p>
+
+<blockquote><pre
+>class MyGC : public GCStrategy {
+public:
+ MyGC() {
+ CustomRoots = true;
+ CustomReadBarriers = true;
+ CustomWriteBarriers = true;
+ }
+
+ virtual bool initializeCustomLowering(Module &M);
+ virtual bool performCustomLowering(Function &F);
+};</pre></blockquote>
+
+<p>If any of these flags are set, then LLVM suppresses its default lowering for
+the corresponding intrinsics and instead calls
+<tt>performCustomLowering</tt>.</p>
+
+<p>LLVM's default action for each intrinsic is as follows:</p>
+
+<ul>
+ <li><tt>llvm.gcroot</tt>: Leave it alone. The code generator must see it
+ or the stack map will not be computed.</li>
+ <li><tt>llvm.gcread</tt>: Substitute a <tt>load</tt> instruction.</li>
+ <li><tt>llvm.gcwrite</tt>: Substitute a <tt>store</tt> instruction.</li>
+</ul>
+
+<p>If <tt>CustomReadBarriers</tt> or <tt>CustomWriteBarriers</tt> are specified,
+then <tt>performCustomLowering</tt> <strong>must</strong> eliminate the
+corresponding barriers.</p>
+
+<p><tt>performCustomLowering</tt> must comply with the same restrictions as <a
+href="WritingAnLLVMPass.html#runOnFunction"><tt
+>FunctionPass::runOnFunction</tt></a>.
+Likewise, <tt>initializeCustomLowering</tt> has the same semantics as <a
+href="WritingAnLLVMPass.html#doInitialization_mod"><tt
+>Pass::doInitialization(Module&)</tt></a>.</p>
+
+<p>The following can be used as a template:</p>
+
+<blockquote><pre
+>#include "llvm/Module.h"
+#include "llvm/IntrinsicInst.h"
+
+bool MyGC::initializeCustomLowering(Module &M) {
+ return false;
+}
+
+bool MyGC::performCustomLowering(Function &F) {
+ bool MadeChange = false;
+
+ for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; )
+ if (IntrinsicInst *CI = dyn_cast<IntrinsicInst>(II++))
+ if (Function *F = CI->getCalledFunction())
+ switch (F->getIntrinsicID()) {
+ case Intrinsic::gcwrite:
+ // Handle llvm.gcwrite.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcread:
+ // Handle llvm.gcread.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcroot:
+ // Handle llvm.gcroot.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ }
+
+ return MadeChange;
+}</pre></blockquote>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a>
+</h3>
+
+<div>
+
+<p>LLVM can compute four kinds of safe points:</p>
+
+<blockquote><pre
+>namespace GC {
+ /// PointKind - The type of a collector-safe point.
+ ///
+ enum PointKind {
+ Loop, //< Instr is a loop (backwards branch).
+ Return, //< Instr is a return instruction.
+ PreCall, //< Instr is a call instruction.
+ PostCall //< Instr is the return address of a call.
+ };
+}</pre></blockquote>
+
+<p>A collector can request any combination of the four by setting the
+<tt>NeededSafePoints</tt> mask:</p>
+
+<blockquote><pre
+>MyGC::MyGC() {
+ NeededSafePoints = 1 << GC::Loop
+ | 1 << GC::Return
+ | 1 << GC::PreCall
+ | 1 << GC::PostCall;
+}</pre></blockquote>
+
+<p>It can then use the following routines to access safe points.</p>
+
+<blockquote><pre
+>for (iterator I = begin(), E = end(); I != E; ++I) {
+ GCFunctionInfo *MD = *I;
+ size_t PointCount = MD->size();
+
+ for (GCFunctionInfo::iterator PI = MD->begin(),
+ PE = MD->end(); PI != PE; ++PI) {
+ GC::PointKind PointKind = PI->Kind;
+ unsigned PointNum = PI->Num;
+ }
+}
+</pre></blockquote>
+
+<p>Almost every collector requires <tt>PostCall</tt> safe points, since these
+correspond to the moments when the function is suspended during a call to a
+subroutine.</p>
+
+<p>Threaded programs generally require <tt>Loop</tt> safe points to guarantee
+that the application will reach a safe point within a bounded amount of time,
+even if it is executing a long-running loop which contains no function
+calls.</p>
+
+<p>Threaded collectors may also require <tt>Return</tt> and <tt>PreCall</tt>
+safe points to implement "stop the world" techniques using self-modifying code,
+where it is important that the program not exit the function without reaching a
+safe point (because only the topmost function has been patched).</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="assembly">Emitting assembly code: <tt>GCMetadataPrinter</tt></a>
+</h3>
+
+<div>
+
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the
+rest of a module's assembly code. At the end of the module, the GC can compile
+the LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)</p>
+
+<p>Since AsmWriter and CodeGen are separate components of LLVM, a separate
+abstract base class and registry is provided for printing assembly code, the
+<tt>GCMetadaPrinter</tt> and <tt>GCMetadataPrinterRegistry</tt>. The AsmWriter
+will look for such a subclass if the <tt>GCStrategy</tt> sets
+<tt>UsesMetadata</tt>:</p>
+
+<blockquote><pre
+>MyGC::MyGC() {
+ UsesMetadata = true;
+}</pre></blockquote>
+
+<p>This separation allows JIT-only clients to be smaller.</p>
+
+<p>Note that LLVM does not currently have analogous APIs to support code
+generation in the JIT, nor using the object writers.</p>
+
+<blockquote><pre
+>// lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer
+
+#include "llvm/CodeGen/GCMetadataPrinter.h"
+#include "llvm/Support/Compiler.h"
+
+using namespace llvm;
+
+namespace {
+ class LLVM_LIBRARY_VISIBILITY MyGCPrinter : public GCMetadataPrinter {
+ public:
+ virtual void beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+
+ virtual void finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+ };
+
+ GCMetadataPrinterRegistry::Add<MyGCPrinter>
+ X("mygc", "My bespoke garbage collector.");
+}</pre></blockquote>
+
+<p>The collector should use <tt>AsmPrinter</tt> and <tt>TargetAsmInfo</tt> to
+print portable assembly code to the <tt>std::ostream</tt>. The collector itself
+contains the stack map for the entire module, and may access the
+<tt>GCFunctionInfo</tt> using its own <tt>begin()</tt> and <tt>end()</tt>
+methods. Here's a realistic example:</p>
+
+<blockquote><pre
+>#include "llvm/CodeGen/AsmPrinter.h"
+#include "llvm/Function.h"
+#include "llvm/Target/TargetMachine.h"
+#include "llvm/Target/TargetData.h"
+#include "llvm/Target/TargetAsmInfo.h"
+
+void MyGCPrinter::beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Nothing to do.
+}
+
+void MyGCPrinter::finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Set up for emitting addresses.
+ const char *AddressDirective;
+ int AddressAlignLog;
+ if (AP.TM.getTargetData()->getPointerSize() == sizeof(int32_t)) {
+ AddressDirective = TAI.getData32bitsDirective();
+ AddressAlignLog = 2;
+ } else {
+ AddressDirective = TAI.getData64bitsDirective();
+ AddressAlignLog = 3;
+ }
+
+ // Put this in the data section.
+ AP.SwitchToDataSection(TAI.getDataSection());
+
+ // For each function...
+ for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
+ GCFunctionInfo &MD = **FI;
+
+ // Emit this data structure:
+ //
+ // struct {
+ // int32_t PointCount;
+ // struct {
+ // void *SafePointAddress;
+ // int32_t LiveCount;
+ // int32_t LiveOffsets[LiveCount];
+ // } Points[PointCount];
+ // } __gcmap_<FUNCTIONNAME>;
+
+ // Align to address width.
+ AP.EmitAlignment(AddressAlignLog);
+
+ // Emit the symbol by which the stack map entry can be found.
+ std::string Symbol;
+ Symbol += TAI.getGlobalPrefix();
+ Symbol += "__gcmap_";
+ Symbol += MD.getFunction().getName();
+ if (const char *GlobalDirective = TAI.getGlobalDirective())
+ OS << GlobalDirective << Symbol << "\n";
+ OS << TAI.getGlobalPrefix() << Symbol << ":\n";
+
+ // Emit PointCount.
+ AP.EmitInt32(MD.size());
+ AP.EOL("safe point count");
+
+ // And each safe point...
+ for (GCFunctionInfo::iterator PI = MD.begin(),
+ PE = MD.end(); PI != PE; ++PI) {
+ // Align to address width.
+ AP.EmitAlignment(AddressAlignLog);
+
+ // Emit the address of the safe point.
+ OS << AddressDirective
+ << TAI.getPrivateGlobalPrefix() << "label" << PI->Num;
+ AP.EOL("safe point address");
+
+ // Emit the stack frame size.
+ AP.EmitInt32(MD.getFrameSize());
+ AP.EOL("stack frame size");
+
+ // Emit the number of live roots in the function.
+ AP.EmitInt32(MD.live_size(PI));
+ AP.EOL("live root count");
+
+ // And for each live root...
+ for (GCFunctionInfo::live_iterator LI = MD.live_begin(PI),
+ LE = MD.live_end(PI);
+ LI != LE; ++LI) {
+ // Print its offset within the stack frame.
+ AP.EmitInt32(LI->StackOffset);
+ AP.EOL("stack offset");
+ }
+ }
+ }
+}
+</pre></blockquote>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="references">References</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew
+W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p>
+
+<p><a name="goldberg91">[Goldberg91]</a> Tag-free garbage collection for
+strongly typed programming languages. Benjamin Goldberg. ACM SIGPLAN
+PLDI'91.</p>
+
+<p><a name="tolmach94">[Tolmach94]</a> Tag-free garbage collection using
+explicit type parameters. Andrew Tolmach. Proceedings of the 1994 ACM
+conference on LISP and functional programming.</p>
+
+<p><a name="henderson02">[Henderson2002]</a> <a
+href="http://citeseer.ist.psu.edu/henderson02accurate.html">
+Accurate Garbage Collection in an Uncooperative Environment</a>.
+Fergus Henderson. International Symposium on Memory Management 2002.</p>
+
+</div>
+
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-08-12 01:17:17 -0500 (Fri, 12 Aug 2011) $
+</address>
+
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GetElementPtr.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GetElementPtr.html (added)
+++ www-releases/trunk/3.0/docs/GetElementPtr.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,753 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>The Often Misunderstood GEP Instruction</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+ <style type="text/css">
+ TABLE { text-align: left; border: 1px solid black; border-collapse: collapse; margin: 0 0 0 0; }
+ </style>
+</head>
+<body>
+
+<h1>
+ The Often Misunderstood GEP Instruction
+</h1>
+
+<ol>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#addresses">Address Computation</a>
+ <ol>
+ <li><a href="#extra_index">Why is the extra 0 index required?</a></li>
+ <li><a href="#deref">What is dereferenced by GEP?</a></li>
+ <li><a href="#firstptr">Why can you index through the first pointer but not
+ subsequent ones?</a></li>
+ <li><a href="#lead0">Why don't GEP x,0,0,1 and GEP x,1 alias? </a></li>
+ <li><a href="#trail0">Why do GEP x,1,0,0 and GEP x,1 alias? </a></li>
+ <li><a href="#vectors">Can GEP index into vector elements?</a>
+ <li><a href="#addrspace">What effect do address spaces have on GEPs?</a>
+ <li><a href="#int">How is GEP different from ptrtoint, arithmetic, and inttoptr?</a></li>
+ <li><a href="#be">I'm writing a backend for a target which needs custom lowering for GEP. How do I do this?</a>
+ <li><a href="#vla">How does VLA addressing work with GEPs?</a>
+ </ol></li>
+ <li><a href="#rules">Rules</a>
+ <ol>
+ <li><a href="#bounds">What happens if an array index is out of bounds?</a>
+ <li><a href="#negative">Can array indices be negative?</a>
+ <li><a href="#compare">Can I compare two values computed with GEPs?</a>
+ <li><a href="#types">Can I do GEP with a different pointer type than the type of the underlying object?</a>
+ <li><a href="#null">Can I cast an object's address to integer and add it to null?</a>
+ <li><a href="#ptrdiff">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a>
+ <li><a href="#tbaa">Can I do type-based alias analysis on LLVM IR?</a>
+ <li><a href="#overflow">What happens if a GEP computation overflows?</a>
+ <li><a href="#check">How can I tell if my front-end is following the rules?</a>
+ </ol></li>
+ <li><a href="#rationale">Rationale</a>
+ <ol>
+ <li><a href="#goals">Why is GEP designed this way?</a></li>
+ <li><a href="#i32">Why do struct member indices always use i32?</a></li>
+ <li><a href="#uglygep">What's an uglygep?</a>
+ </ol></li>
+ <li><a href="#summary">Summary</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by: <a href="mailto:rspencer at reidspencer.com">Reid Spencer</a>.</p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2><a name="intro">Introduction</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+ <p>This document seeks to dispel the mystery and confusion surrounding LLVM's
+ <a href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction.
+ Questions about the wily GEP instruction are
+ probably the most frequently occurring questions once a developer gets down to
+ coding with LLVM. Here we lay out the sources of confusion and show that the
+ GEP instruction is really quite simple.
+ </p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="addresses">Address Computation</a></h2>
+<!-- *********************************************************************** -->
+<div>
+ <p>When people are first confronted with the GEP instruction, they tend to
+ relate it to known concepts from other programming paradigms, most notably C
+ array indexing and field selection. GEP closely resembles C array indexing
+ and field selection, however it's is a little different and this leads to
+ the following questions.</p>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="firstptr">What is the first index of the GEP instruction?</a>
+</h3>
+<div>
+ <p>Quick answer: The index stepping through the first operand.</p>
+ <p>The confusion with the first index usually arises from thinking about
+ the GetElementPtr instruction as if it was a C index operator. They aren't the
+ same. For example, when we write, in "C":</p>
+
+<div class="doc_code">
+<pre>
+AType *Foo;
+...
+X = &Foo->F;
+</pre>
+</div>
+
+ <p>it is natural to think that there is only one index, the selection of the
+ field <tt>F</tt>. However, in this example, <tt>Foo</tt> is a pointer. That
+ pointer must be indexed explicitly in LLVM. C, on the other hand, indices
+ through it transparently. To arrive at the same address location as the C
+ code, you would provide the GEP instruction with two index operands. The
+ first operand indexes through the pointer; the second operand indexes the
+ field <tt>F</tt> of the structure, just as if you wrote:</p>
+
+<div class="doc_code">
+<pre>
+X = &Foo[0].F;
+</pre>
+</div>
+
+ <p>Sometimes this question gets rephrased as:</p>
+ <blockquote><p><i>Why is it okay to index through the first pointer, but
+ subsequent pointers won't be dereferenced?</i></p></blockquote>
+ <p>The answer is simply because memory does not have to be accessed to
+ perform the computation. The first operand to the GEP instruction must be a
+ value of a pointer type. The value of the pointer is provided directly to
+ the GEP instruction as an operand without any need for accessing memory. It
+ must, therefore be indexed and requires an index operand. Consider this
+ example:</p>
+
+<div class="doc_code">
+<pre>
+struct munger_struct {
+ int f1;
+ int f2;
+};
+void munge(struct munger_struct *P) {
+ P[0].f1 = P[1].f1 + P[2].f2;
+}
+...
+munger_struct Array[3];
+...
+munge(Array);
+</pre>
+</div>
+
+ <p>In this "C" example, the front end compiler (llvm-gcc) will generate three
+ GEP instructions for the three indices through "P" in the assignment
+ statement. The function argument <tt>P</tt> will be the first operand of each
+ of these GEP instructions. The second operand indexes through that pointer.
+ The third operand will be the field offset into the
+ <tt>struct munger_struct</tt> type, for either the <tt>f1</tt> or
+ <tt>f2</tt> field. So, in LLVM assembly the <tt>munge</tt> function looks
+ like:</p>
+
+<div class="doc_code">
+<pre>
+void %munge(%struct.munger_struct* %P) {
+entry:
+ %tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
+ %tmp = load i32* %tmp
+ %tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
+ %tmp7 = load i32* %tmp6
+ %tmp8 = add i32 %tmp7, %tmp
+ %tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
+ store i32 %tmp8, i32* %tmp9
+ ret void
+}
+</pre>
+</div>
+
+ <p>In each case the first operand is the pointer through which the GEP
+ instruction starts. The same is true whether the first operand is an
+ argument, allocated memory, or a global variable. </p>
+ <p>To make this clear, let's consider a more obtuse example:</p>
+
+<div class="doc_code">
+<pre>
+%MyVar = uninitialized global i32
+...
+%idx1 = getelementptr i32* %MyVar, i64 0
+%idx2 = getelementptr i32* %MyVar, i64 1
+%idx3 = getelementptr i32* %MyVar, i64 2
+</pre>
+</div>
+
+ <p>These GEP instructions are simply making address computations from the
+ base address of <tt>MyVar</tt>. They compute, as follows (using C syntax):
+ </p>
+
+<div class="doc_code">
+<pre>
+idx1 = (char*) &MyVar + 0
+idx2 = (char*) &MyVar + 4
+idx3 = (char*) &MyVar + 8
+</pre>
+</div>
+
+ <p>Since the type <tt>i32</tt> is known to be four bytes long, the indices
+ 0, 1 and 2 translate into memory offsets of 0, 4, and 8, respectively. No
+ memory is accessed to make these computations because the address of
+ <tt>%MyVar</tt> is passed directly to the GEP instructions.</p>
+ <p>The obtuse part of this example is in the cases of <tt>%idx2</tt> and
+ <tt>%idx3</tt>. They result in the computation of addresses that point to
+ memory past the end of the <tt>%MyVar</tt> global, which is only one
+ <tt>i32</tt> long, not three <tt>i32</tt>s long. While this is legal in LLVM,
+ it is inadvisable because any load or store with the pointer that results
+ from these GEP instructions would produce undefined results.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="extra_index">Why is the extra 0 index required?</a>
+</h3>
+<!-- *********************************************************************** -->
+<div>
+ <p>Quick answer: there are no superfluous indices.</p>
+ <p>This question arises most often when the GEP instruction is applied to a
+ global variable which is always a pointer type. For example, consider
+ this:</p>
+
+<div class="doc_code">
+<pre>
+%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
+</pre>
+</div>
+
+ <p>The GEP above yields an <tt>i32*</tt> by indexing the <tt>i32</tt> typed
+ field of the structure <tt>%MyStruct</tt>. When people first look at it, they
+ wonder why the <tt>i64 0</tt> index is needed. However, a closer inspection
+ of how globals and GEPs work reveals the need. Becoming aware of the following
+ facts will dispel the confusion:</p>
+ <ol>
+ <li>The type of <tt>%MyStruct</tt> is <i>not</i> <tt>{ float*, i32 }</tt>
+ but rather <tt>{ float*, i32 }*</tt>. That is, <tt>%MyStruct</tt> is a
+ pointer to a structure containing a pointer to a <tt>float</tt> and an
+ <tt>i32</tt>.</li>
+ <li>Point #1 is evidenced by noticing the type of the first operand of
+ the GEP instruction (<tt>%MyStruct</tt>) which is
+ <tt>{ float*, i32 }*</tt>.</li>
+ <li>The first index, <tt>i64 0</tt> is required to step over the global
+ variable <tt>%MyStruct</tt>. Since the first argument to the GEP
+ instruction must always be a value of pointer type, the first index
+ steps through that pointer. A value of 0 means 0 elements offset from that
+ pointer.</li>
+ <li>The second index, <tt>i32 1</tt> selects the second field of the
+ structure (the <tt>i32</tt>). </li>
+ </ol>
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="deref">What is dereferenced by GEP?</a>
+</h3>
+<div>
+ <p>Quick answer: nothing.</p>
+ <p>The GetElementPtr instruction dereferences nothing. That is, it doesn't
+ access memory in any way. That's what the Load and Store instructions are for.
+ GEP is only involved in the computation of addresses. For example, consider
+ this:</p>
+
+<div class="doc_code">
+<pre>
+%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+</pre>
+</div>
+
+ <p>In this example, we have a global variable, <tt>%MyVar</tt> that is a
+ pointer to a structure containing a pointer to an array of 40 ints. The
+ GEP instruction seems to be accessing the 18th integer of the structure's
+ array of ints. However, this is actually an illegal GEP instruction. It
+ won't compile. The reason is that the pointer in the structure <i>must</i>
+ be dereferenced in order to index into the array of 40 ints. Since the
+ GEP instruction never accesses memory, it is illegal.</p>
+ <p>In order to access the 18th integer in the array, you would need to do the
+ following:</p>
+
+<div class="doc_code">
+<pre>
+%idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
+%arr = load [40 x i32]** %idx
+%idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
+</pre>
+</div>
+
+ <p>In this case, we have to load the pointer in the structure with a load
+ instruction before we can index into the array. If the example was changed
+ to:</p>
+
+<div class="doc_code">
+<pre>
+%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
+</pre>
+</div>
+
+ <p>then everything works fine. In this case, the structure does not contain a
+ pointer and the GEP instruction can index through the global variable,
+ into the first field of the structure and access the 18th <tt>i32</tt> in the
+ array there.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="lead0">Why don't GEP x,0,0,1 and GEP x,1 alias?</a>
+</h3>
+<div>
+ <p>Quick Answer: They compute different address locations.</p>
+ <p>If you look at the first indices in these GEP
+ instructions you find that they are different (0 and 1), therefore the address
+ computation diverges with that index. Consider this example:</p>
+
+<div class="doc_code">
+<pre>
+%MyVar = global { [10 x i32 ] }
+%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
+</pre>
+</div>
+
+ <p>In this example, <tt>idx1</tt> computes the address of the second integer
+ in the array that is in the structure in <tt>%MyVar</tt>, that is
+ <tt>MyVar+4</tt>. The type of <tt>idx1</tt> is <tt>i32*</tt>. However,
+ <tt>idx2</tt> computes the address of <i>the next</i> structure after
+ <tt>%MyVar</tt>. The type of <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its
+ value is equivalent to <tt>MyVar + 40</tt> because it indexes past the ten
+ 4-byte integers in <tt>MyVar</tt>. Obviously, in such a situation, the
+ pointers don't alias.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="trail0">Why do GEP x,1,0,0 and GEP x,1 alias?</a>
+</h3>
+<div>
+ <p>Quick Answer: They compute the same address location.</p>
+ <p>These two GEP instructions will compute the same address because indexing
+ through the 0th element does not change the address. However, it does change
+ the type. Consider this example:</p>
+
+<div class="doc_code">
+<pre>
+%MyVar = global { [10 x i32 ] }
+%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
+</pre>
+</div>
+
+ <p>In this example, the value of <tt>%idx1</tt> is <tt>%MyVar+40</tt> and
+ its type is <tt>i32*</tt>. The value of <tt>%idx2</tt> is also
+ <tt>MyVar+40</tt> but its type is <tt>{ [10 x i32] }*</tt>.</p>
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="vectors">Can GEP index into vector elements?</a>
+</h3>
+<div>
+ <p>This hasn't always been forcefully disallowed, though it's not recommended.
+ It leads to awkward special cases in the optimizers, and fundamental
+ inconsistency in the IR. In the future, it will probably be outright
+ disallowed.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="addrspace">What effect do address spaces have on GEPs?</a>
+</h3>
+<div>
+ <p>None, except that the address space qualifier on the first operand pointer
+ type always matches the address space qualifier on the result type.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="int">
+ How is GEP different from ptrtoint, arithmetic, and inttoptr?
+ </a>
+</h3>
+<div>
+ <p>It's very similar; there are only subtle differences.</p>
+
+ <p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+ this is safe on everything LLVM supports (LLVM internally assumes pointers
+ are never wider than 64 bits in many places), and the optimizer will actually
+ narrow the i64 arithmetic down to the actual pointer size on targets which
+ don't support 64-bit arithmetic in most cases. However, there are some cases
+ where it doesn't do this. With GEP you can avoid this problem.
+
+ <p>Also, GEP carries additional pointer aliasing rules. It's invalid to take a
+ GEP from one object, address into a different separately allocated
+ object, and dereference it. IR producers (front-ends) must follow this rule,
+ and consumers (optimizers, specifically alias analysis) benefit from being
+ able to rely on it. See the <a href="#rules">Rules</a> section for more
+ information.</p>
+
+ <p>And, GEP is more concise in common cases.</p>
+
+ <p>However, for the underlying integer computation implied, there
+ is no difference.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="be">
+ I'm writing a backend for a target which needs custom lowering for GEP.
+ How do I do this?
+ </a>
+</h3>
+<div>
+ <p>You don't. The integer computation implied by a GEP is target-independent.
+ Typically what you'll need to do is make your backend pattern-match
+ expressions trees involving ADD, MUL, etc., which are what GEP is lowered
+ into. This has the advantage of letting your code work correctly in more
+ cases.</p>
+
+ <p>GEP does use target-dependent parameters for the size and layout of data
+ types, which targets can customize.</p>
+
+ <p>If you require support for addressing units which are not 8 bits, you'll
+ need to fix a lot of code in the backend, with GEP lowering being only a
+ small piece of the overall picture.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="vla">How does VLA addressing work with GEPs?</a>
+</h3>
+<div>
+ <p>GEPs don't natively support VLAs. LLVM's type system is entirely static,
+ and GEP address computations are guided by an LLVM type.</p>
+
+ <p>VLA indices can be implemented as linearized indices. For example, an
+ expression like X[a][b][c], must be effectively lowered into a form
+ like X[a*m+b*n+c], so that it appears to the GEP as a single-dimensional
+ array reference.</p>
+
+ <p>This means if you want to write an analysis which understands array
+ indices and you want to support VLAs, your code will have to be
+ prepared to reverse-engineer the linearization. One way to solve this
+ problem is to use the ScalarEvolution library, which always presents
+ VLA and non-VLA indexing in the same manner.</p>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="rules">Rules</a></h2>
+<!-- *********************************************************************** -->
+<div>
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="bounds">What happens if an array index is out of bounds?</a>
+</h3>
+<div>
+ <p>There are two senses in which an array index can be out of bounds.</p>
+
+ <p>First, there's the array type which comes from the (static) type of
+ the first operand to the GEP. Indices greater than the number of elements
+ in the corresponding static array type are valid. There is no problem with
+ out of bounds indices in this sense. Indexing into an array only depends
+ on the size of the array element, not the number of elements.</p>
+
+ <p>A common example of how this is used is arrays where the size is not known.
+ It's common to use array types with zero length to represent these. The
+ fact that the static type says there are zero elements is irrelevant; it's
+ perfectly valid to compute arbitrary element indices, as the computation
+ only depends on the size of the array element, not the number of
+ elements. Note that zero-sized arrays are not a special case here.</p>
+
+ <p>This sense is unconnected with <tt>inbounds</tt> keyword. The
+ <tt>inbounds</tt> keyword is designed to describe low-level pointer
+ arithmetic overflow conditions, rather than high-level array
+ indexing rules.
+
+ <p>Analysis passes which wish to understand array indexing should not
+ assume that the static array type bounds are respected.</p>
+
+ <p>The second sense of being out of bounds is computing an address that's
+ beyond the actual underlying allocated object.</p>
+
+ <p>With the <tt>inbounds</tt> keyword, the result value of the GEP is
+ undefined if the address is outside the actual underlying allocated
+ object and not the address one-past-the-end.</p>
+
+ <p>Without the <tt>inbounds</tt> keyword, there are no restrictions
+ on computing out-of-bounds addresses. Obviously, performing a load or
+ a store requires an address of allocated and sufficiently aligned
+ memory. But the GEP itself is only concerned with computing addresses.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="negative">Can array indices be negative?</a>
+</h3>
+<div>
+ <p>Yes. This is basically a special case of array indices being out
+ of bounds.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="compare">Can I compare two values computed with GEPs?</a>
+</h3>
+<div>
+ <p>Yes. If both addresses are within the same allocated object, or
+ one-past-the-end, you'll get the comparison result you expect. If either
+ is outside of it, integer arithmetic wrapping may occur, so the
+ comparison may not be meaningful.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="types">
+ Can I do GEP with a different pointer type than the type of
+ the underlying object?
+ </a>
+</h3>
+<div>
+ <p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+ pointer type. The types in a GEP serve only to define the parameters for the
+ underlying integer computation. They need not correspond with the actual
+ type of the underlying object.</p>
+
+ <p>Furthermore, loads and stores don't have to use the same types as the type
+ of the underlying object. Types in this context serve only to specify
+ memory size and alignment. Beyond that there are merely a hint to the
+ optimizer indicating how the value will likely be used.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="null">
+ Can I cast an object's address to integer and add it to null?
+ </a>
+</h3>
+<div>
+ <p>You can compute an address that way, but if you use GEP to do the add,
+ you can't use that pointer to actually access the object, unless the
+ object is managed outside of LLVM.</p>
+
+ <p>The underlying integer computation is sufficiently defined; null has a
+ defined value -- zero -- and you can add whatever value you want to it.</p>
+
+ <p>However, it's invalid to access (load from or store to) an LLVM-aware
+ object with such a pointer. This includes GlobalVariables, Allocas, and
+ objects pointed to by noalias pointers.</p>
+
+ <p>If you really need this functionality, you can do the arithmetic with
+ explicit integer instructions, and use inttoptr to convert the result to
+ an address. Most of GEP's special aliasing rules do not apply to pointers
+ computed from ptrtoint, arithmetic, and inttoptr sequences.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="ptrdiff">
+ Can I compute the distance between two objects, and add
+ that value to one address to compute the other address?
+ </a>
+</h3>
+<div>
+ <p>As with arithmetic on null, You can use GEP to compute an address that
+ way, but you can't use that pointer to actually access the object if you
+ do, unless the object is managed outside of LLVM.</p>
+
+ <p>Also as above, ptrtoint and inttoptr provide an alternative way to do this
+ which do not have this restriction.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="tbaa">Can I do type-based alias analysis on LLVM IR?</a>
+</h3>
+<div>
+ <p>You can't do type-based alias analysis using LLVM's built-in type system,
+ because LLVM has no restrictions on mixing types in addressing, loads or
+ stores.</p>
+
+ <p>It would be possible to add special annotations to the IR, probably using
+ metadata, to describe a different type system (such as the C type system),
+ and do type-based aliasing on top of that. This is a much bigger
+ undertaking though.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="overflow">What happens if a GEP computation overflows?</a>
+</h3>
+<div>
+ <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>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="check">
+ How can I tell if my front-end is following the rules?
+ </a>
+</h3>
+<div>
+ <p>There is currently no checker for the getelementptr rules. Currently,
+ the only way to do this is to manually check each place in your front-end
+ where GetElementPtr operators are created.</p>
+
+ <p>It's not possible to write a checker which could find all rule
+ violations statically. It would be possible to write a checker which
+ works by instrumenting the code with dynamic checks though. Alternatively,
+ it would be possible to write a static checker which catches a subset of
+ possible problems. However, no such checker exists today.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="rationale">Rationale</a></h2>
+<!-- *********************************************************************** -->
+<div>
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="goals">Why is GEP designed this way?</a>
+</h3>
+<div>
+ <p>The design of GEP has the following goals, in rough unofficial
+ order of priority:</p>
+ <ul>
+ <li>Support C, C-like languages, and languages which can be
+ conceptually lowered into C (this covers a lot).</li>
+ <li>Support optimizations such as those that are common in
+ C compilers. In particular, GEP is a cornerstone of LLVM's
+ <a href="LangRef.html#pointeraliasing">pointer aliasing model</a>.</li>
+ <li>Provide a consistent method for computing addresses so that
+ address computations don't need to be a part of load and
+ store instructions in the IR.</li>
+ <li>Support non-C-like languages, to the extent that it doesn't
+ interfere with other goals.</li>
+ <li>Minimize target-specific information in the IR.</li>
+ </ul>
+</div>
+
+<!-- *********************************************************************** -->
+<h3>
+ <a name="i32">Why do struct member indices always use i32?</a>
+</h3>
+<div>
+ <p>The specific type i32 is probably just a historical artifact, however it's
+ wide enough for all practical purposes, so there's been no need to change it.
+ It doesn't necessarily imply i32 address arithmetic; it's just an identifier
+ which identifies a field in a struct. Requiring that all struct indices be
+ the same reduces the range of possibilities for cases where two GEPs are
+ effectively the same but have distinct operand types.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<h3>
+ <a name="uglygep">What's an uglygep?</a>
+</h3>
+<div>
+ <p>Some LLVM optimizers operate on GEPs by internally lowering them into
+ more primitive integer expressions, which allows them to be combined
+ with other integer expressions and/or split into multiple separate
+ integer expressions. If they've made non-trivial changes, translating
+ back into LLVM IR can involve reverse-engineering the structure of
+ the addressing in order to fit it into the static type of the original
+ first operand. It isn't always possibly to fully reconstruct this
+ structure; sometimes the underlying addressing doesn't correspond with
+ the static type at all. In such cases the optimizer instead will emit
+ a GEP with the base pointer casted to a simple address-unit pointer,
+ using the name "uglygep". This isn't pretty, but it's just as
+ valid, and it's sufficient to preserve the pointer aliasing guarantees
+ that GEP provides.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="summary">Summary</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+ <p>In summary, here's some things to always remember about the GetElementPtr
+ instruction:</p>
+ <ol>
+ <li>The GEP instruction never accesses memory, it only provides pointer
+ computations.</li>
+ <li>The first operand to the GEP instruction is always a pointer and it must
+ be indexed.</li>
+ <li>There are no superfluous indices for the GEP instruction.</li>
+ <li>Trailing zero indices are superfluous for pointer aliasing, but not for
+ the types of the pointers.</li>
+ <li>Leading zero indices are not superfluous for pointer aliasing nor the
+ types of the pointers.</li>
+ </ol>
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-11-03 01:43:54 -0500 (Thu, 03 Nov 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GettingStarted.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GettingStarted.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GettingStarted.html (added)
+++ www-releases/trunk/3.0/docs/GettingStarted.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,1876 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Getting Started with LLVM System</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ Getting Started with the LLVM System
+</h1>
+
+<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>
+ <li><a href="#software">Software</a></li>
+ <li><a href="#brokengcc">Broken versions of GCC and other tools</a></li>
+ </ol></li>
+
+ <li><a href="#starting">Getting Started with LLVM</a>
+ <ol>
+ <li><a href="#terminology">Terminology and Notation</a></li>
+ <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>
+ <li><a href="#cross-compile">Cross-Compiling LLVM</a></li>
+ <li><a href="#objfiles">The Location of LLVM Object Files</a></li>
+ <li><a href="#optionalconfig">Optional Configuration Items</a></li>
+ </ol></li>
+
+ <li><a href="#layout">Program layout</a>
+ <ol>
+ <li><a href="#examples"><tt>llvm/examples</tt></a></li>
+ <li><a href="#include"><tt>llvm/include</tt></a></li>
+ <li><a href="#lib"><tt>llvm/lib</tt></a></li>
+ <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="#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>
+ </ol></li>
+
+ <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
+ <ol>
+ <li><a href="#tutorial4">Example with llvm-gcc4</a></li>
+ </ol>
+ <li><a href="#problems">Common Problems</a>
+ <li><a href="#links">Links</a>
+</ul>
+
+<div class="doc_author">
+ <p>Written by:
+ <a href="mailto:criswell at uiuc.edu">John Criswell</a>,
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a>,
+ <a href="http://misha.brukman.net/">Misha Brukman</a>,
+ <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>, and
+ <a href="mailto:gshi1 at uiuc.edu">Guochun Shi</a>.
+ </p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="overview">Overview</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Welcome to LLVM! In order to get started, you first need to know some
+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>
+
+<p>
+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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="quickstart">Getting Started Quickly (A Summary)</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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
+ <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><b>[Optional]</b> Get the Test Suite Source Code
+ <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>
+
+ </ul></li>
+
+
+ <li>Configure the LLVM Build Environment
+ <ol>
+ <li><tt>cd <i>where-you-want-to-build-llvm</i></tt></li>
+ <li><tt><i>/path/to/llvm/</i>configure [options]</tt><br>
+ Some common options:
+
+ <ul>
+ <li><tt>--prefix=<i>directory</i></tt>
+ <p>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>
+ </ul>
+ </ol></li>
+
+ <li>Build the LLVM Suite:
+ <ol>
+ <li><tt>gmake -k |& tee gnumake.out
+ # this is csh or tcsh syntax</tt></li>
+ <li>If you get an "internal compiler error (ICE)" or test failures, see
+ <a href="#brokengcc">below</a>.</li>
+ </ol>
+
+</ol>
+
+<p>Consult the <a href="#starting">Getting Started with LLVM</a> section for
+detailed information on configuring and compiling LLVM. See <a
+href="#environment">Setting Up Your Environment</a> for tips that simplify
+working with the GCC front end and LLVM tools. Go to <a href="#layout">Program
+Layout</a> to learn about the layout of the source code tree.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="requirements">Requirements</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Before you begin to use the LLVM system, review the requirements given below.
+This may save you some trouble by knowing ahead of time what hardware and
+software you will need.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="hardware">Hardware</a>
+</h3>
+
+<div>
+
+<p>LLVM is known to work on the following platforms:</p>
+
+<table cellpadding="3" summary="Known LLVM platforms">
+<tr>
+ <th>OS</th>
+ <th>Arch</th>
+ <th>Compilers</th>
+</tr>
+<tr>
+ <td>AuroraUX</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Linux</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Linux</td>
+ <td>amd64</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Solaris</td>
+ <td>V9 (Ultrasparc)</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>FreeBSD</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <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>
+</tr>
+<tr>
+ <td>MacOS X<sup><a href="#pf_2">2</a>,<a href="#pf_9">9</a></sup></td>
+ <td>x86</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Cygwin/Win32</td>
+ <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_8">8</a>,
+ <a href="#pf_11">11</a></sup></td>
+ <td>GCC 3.4.X, binutils 2.20</td>
+</tr>
+<tr>
+ <td>MinGW/Win32</td>
+ <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>,
+ <a href="#pf_8">8</a>, <a href="#pf_10">10</a>,
+ <a href="#pf_11">11</a></sup></td>
+ <td>GCC 3.4.X, binutils 2.20</td>
+</tr>
+</table>
+
+<p>LLVM has partial support for the following platforms:</p>
+
+<table summary="LLVM partial platform support">
+<tr>
+ <th>OS</th>
+ <th>Arch</th>
+ <th>Compilers</th>
+</tr>
+<tr>
+ <td>Windows</td>
+ <td>x86<sup><a href="#pf_1">1</a></sup></td>
+ <td>Visual Studio 2005 SP1 or higher<sup><a href="#pf_4">4</a>,<a href="#pf_5">5</a></sup></td>
+<tr>
+ <td>AIX<sup><a href="#pf_3">3</a>,<a href="#pf_4">4</a></sup></td>
+ <td>PowerPC</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Linux<sup><a href="#pf_3">3</a>,<a href="#pf_5">5</a></sup></td>
+ <td>PowerPC</td>
+ <td>GCC</td>
+</tr>
+
+<tr>
+ <td>Linux<sup><a href="#pf_7">7</a></sup></td>
+ <td>Alpha</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>Linux<sup><a href="#pf_7">7</a></sup></td>
+ <td>Itanium (IA-64)</td>
+ <td>GCC</td>
+</tr>
+<tr>
+ <td>HP-UX<sup><a href="#pf_7">7</a></sup></td>
+ <td>Itanium (IA-64)</td>
+ <td>HP aCC</td>
+</tr>
+<tr>
+ <td>Windows x64</td>
+ <td>x86-64</td>
+ <td>mingw-w64's GCC-4.5.x<sup><a href="#pf_12">12</a></sup></td>
+</tr>
+</table>
+
+<p><b>Notes:</b></p>
+
+<div class="doc_notes">
+<ol>
+<li><a name="pf_1">Code generation supported for Pentium processors and
+up</a></li>
+<li><a name="pf_2">Code generation supported for 32-bit ABI only</a></li>
+<li><a name="pf_3">No native code generation</a></li>
+<li><a name="pf_4">Build is not complete: one or more tools do not link or function</a></li>
+<li><a name="pf_5">The GCC-based C/C++ frontend does not build</a></li>
+<li><a name="pf_6">The port is done using the MSYS shell.</a></li>
+<li><a name="pf_7">Native code generation exists but is not complete.</a></li>
+<li><a name="pf_8">Binutils 2.20 or later is required to build the assembler
+ generated by LLVM properly.</a></li>
+<li><a name="pf_9">XCode 2.5 and gcc 4.0.1</a> (Apple Build 5370) will trip
+ internal LLVM assert messages when compiled for Release at optimization
+ levels greater than 0 (i.e., <i>"-O1"</i> and higher).
+ Add <i>OPTIMIZE_OPTION="-O0"</i> to the build command line
+ if compiling for LLVM Release or bootstrapping the LLVM toolchain.</li>
+<li><a name="pf_10">For MSYS/MinGW on Windows, be sure to install the MSYS
+ version of the perl package, and be sure it appears in your path
+ before any Windows-based versions such as Strawberry Perl and
+ ActivePerl, as these have Windows-specifics that will cause the
+ build to fail.</a></li>
+<li><a name="pf_11">To use LLVM modules on Win32-based system,
+ you may configure LLVM with <i>"--enable-shared"</i>.</a></li>
+<li><a name="pf_12">To compile SPU backend, you need to add
+ <tt>"LDFLAGS=-Wl,--stack,16777216"</tt> to configure.</a></li>
+</ol>
+</div>
+
+<p>Note that you will need about 1-3 GB of space for a full LLVM build in Debug
+mode, depending on the system (it is so large because of all the debugging
+information and the fact that the libraries are statically linked into multiple
+tools). If you do not need many of the tools and you are space-conscious, you
+can pass <tt>ONLY_TOOLS="tools you need"</tt> to make. The Release build
+requires considerably less space.</p>
+
+<p>The LLVM suite <i>may</i> compile on other platforms, but it is not
+guaranteed to do so. If compilation is successful, the LLVM utilities should be
+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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="software">Software</a>
+</h3>
+<div>
+ <p>Compiling LLVM requires that you have several software packages
+ installed. The table below lists those required packages. The Package column
+ is the usual name for the software package that LLVM depends on. The Version
+ column provides "known to work" versions of the package. The Notes column
+ describes how LLVM uses the package and provides other details.</p>
+ <table summary="Packages required to compile LLVM">
+ <tr><th>Package</th><th>Version</th><th>Notes</th></tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/make">GNU Make</a></td>
+ <td>3.79, 3.79.1</td>
+ <td>Makefile/build processor</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://gcc.gnu.org/">GCC</a></td>
+ <td>3.4.2</td>
+ <td>C/C++ compiler<sup><a href="#sf1">1</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/texinfo/">TeXinfo</a></td>
+ <td>4.5</td>
+ <td>For building the CFE</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://subversion.tigris.org/project_packages.html">SVN</a></td>
+ <td>≥1.3</td>
+ <td>Subversion access to LLVM<sup><a href="#sf2">2</a></sup></td>
+ </tr>
+
+ <!-- FIXME:
+ Do we support dg?
+ Are DejaGnu and expect obsolete?
+ Shall we mention Python? -->
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/dejagnu">DejaGnu</a></td>
+ <td>1.4.2</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.tcl.tk/software/tcltk/">tcl</a></td>
+ <td>8.3, 8.4</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://expect.nist.gov/">expect</a></td>
+ <td>5.38.0</td>
+ <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.perl.com/download.csp">perl</a></td>
+ <td>≥5.6.0</td>
+ <td>Nightly tester, utilities</td>
+ </tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/m4">GNU M4</a>
+ <td>1.4</td>
+ <td>Macro processor for configuration<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a></td>
+ <td>2.61</td>
+ <td>Configuration script builder<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://www.gnu.org/software/automake/">GNU Automake</a></td>
+ <td>1.10</td>
+ <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ <tr>
+ <td><a href="http://savannah.gnu.org/projects/libtool">libtool</a></td>
+ <td>1.5.22</td>
+ <td>Shared library manager<sup><a href="#sf4">4</a></sup></td>
+ </tr>
+
+ </table>
+
+ <p><b>Notes:</b></p>
+ <div class="doc_notes">
+ <ol>
+ <li><a name="sf1">Only the C and C++ languages are needed so there's no
+ need to build the other languages for LLVM's purposes.</a> See
+ <a href="#brokengcc">below</a> for specific version info.</li>
+ <li><a name="sf2">You only need Subversion if you intend to build from the
+ latest LLVM sources. If you're working from a release distribution, you
+ don't need Subversion.</a></li>
+ <li><a name="sf3">Only needed if you want to run the automated test
+ suite in the <tt>llvm/test</tt> directory.</a></li>
+ <li><a name="sf4">If you want to make changes to the configure scripts,
+ you will need GNU autoconf (2.61), and consequently, GNU M4 (version 1.4
+ or higher). You will also need automake (1.10). We only use aclocal
+ from that package.</a></li>
+ </ol>
+ </div>
+
+ <p>Additionally, your compilation host is expected to have the usual
+ plethora of Unix utilities. Specifically:</p>
+ <ul>
+ <li><b>ar</b> - archive library builder</li>
+ <li><b>bzip2*</b> - bzip2 command for distribution generation</li>
+ <li><b>bunzip2*</b> - bunzip2 command for distribution checking</li>
+ <li><b>chmod</b> - change permissions on a file</li>
+ <li><b>cat</b> - output concatenation utility</li>
+ <li><b>cp</b> - copy files</li>
+ <li><b>date</b> - print the current date/time </li>
+ <li><b>echo</b> - print to standard output</li>
+ <li><b>egrep</b> - extended regular expression search utility</li>
+ <li><b>find</b> - find files/dirs in a file system</li>
+ <li><b>grep</b> - regular expression search utility</li>
+ <li><b>gzip*</b> - gzip command for distribution generation</li>
+ <li><b>gunzip*</b> - gunzip command for distribution checking</li>
+ <li><b>install</b> - install directories/files </li>
+ <li><b>mkdir</b> - create a directory</li>
+ <li><b>mv</b> - move (rename) files</li>
+ <li><b>ranlib</b> - symbol table builder for archive libraries</li>
+ <li><b>rm</b> - remove (delete) files and directories</li>
+ <li><b>sed</b> - stream editor for transforming output</li>
+ <li><b>sh</b> - Bourne shell for make build scripts</li>
+ <li><b>tar</b> - tape archive for distribution generation</li>
+ <li><b>test</b> - test things in file system</li>
+ <li><b>unzip*</b> - unzip command for distribution checking</li>
+ <li><b>zip*</b> - zip command for distribution generation</li>
+ </ul>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="brokengcc">Broken versions of GCC and other tools</a>
+</h3>
+
+<div>
+
+<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler. In particular, several versions of GCC crash when trying
+to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1
+successfully with them (however, see important notes below). Other versions
+of GCC will probably work as well. GCC versions listed
+here are known to not work. If you are using one of these versions, please try
+to upgrade your GCC to something more recent. If you run into a problem with a
+version of GCC not listed here, please <a href="mailto:llvmdev at cs.uiuc.edu">let
+us know</a>. Please use the "<tt>gcc -v</tt>" command to find out which version
+of GCC you are using.
+</p>
+
+<p><b>GCC versions prior to 3.0</b>: GCC 2.96.x and before had several
+problems in the STL that effectively prevent it from compiling LLVM.
+</p>
+
+<p><b>GCC 3.2.2 and 3.2.3</b>: These versions of GCC fails to compile LLVM with
+a bogus template error. This was fixed in later GCCs.</p>
+
+<p><b>GCC 3.3.2</b>: This version of GCC suffered from a <a
+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>
+<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
+ to a newer version of GCC.</p>
+<p><b>GCC 3.4.0 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+ code generator, causing an infinite loop in the llvm-gcc build when built
+ with optimizations enabled (i.e. a release build).</p>
+<p><b>GCC 3.4.2 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+ code generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0)
+ correctly compiles LLVM at -O2. A work around is to build release LLVM
+ builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."</p>
+<p><b>GCC 3.4.x on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056">
+ miscompiles portions of LLVM</a>.</p>
+<p><b>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</b>: this compiler miscompiles LLVM
+ when building with optimizations enabled. It appears to work with
+ "<tt>make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1</tt>" or build a debug
+ build.</p>
+<p><b>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to
+ miscompile LLVM.</p>
+<p><b>Apple Xcode 2.3</b>: GCC crashes when compiling LLVM at -O3 (which is the
+ default with ENABLE_OPTIMIZED=1. To work around this, build with
+ "ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2".</p>
+<p><b>GCC 4.1.1</b>: GCC fails to build LLVM with template concept check errors
+ compiling some files. At the time of this writing, GCC mainline (4.2)
+ did not share the problem.</p>
+<p><b>GCC 4.1.1 on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1063">
+ miscompiles portions of LLVM</a> when compiling llvm itself into 64-bit
+ code. LLVM will appear to mostly work but will be buggy, e.g. failing
+ portions of its testsuite.</p>
+<p><b>GCC 4.1.2 on OpenSUSE</b>: Seg faults during libstdc++ build and on x86_64
+platforms compiling md5.c gets a mangled constant.</p>
+<p><b>GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian</b>: Appears
+to miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining
+about symbols remaining in the table on destruction.</p>
+<p><b>GCC 4.1.2 20071124 (Red Hat 4.1.2-42)</b>: Suffers from the same symptoms
+as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</p>
+<p><b>Cygwin GCC 4.3.2 20080827 (beta) 2</b>:
+ Users <a href="http://llvm.org/PR4145">reported</a> various problems related
+ with link errors when using this GCC version.</p>
+<p><b>Debian GCC 4.3.2 on X86</b>: Crashes building some files in LLVM 2.6.</p>
+<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
+erroneous and the linkage is correct. These messages disappear using ld
+2.17.</p>
+
+<p><b>GNU binutils 2.17</b>: Binutils 2.17 contains <a
+href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which
+causes huge link times (minutes instead of seconds) when building LLVM. We
+recommend upgrading to a newer version (2.17.50.0.4 or later).</p>
+
+<p><b>GNU Binutils 2.19.1 Gold</b>: This version of Gold contained
+<a href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a>
+which causes intermittent failures when building LLVM with position independent
+code. The symptom is an error about cyclic dependencies. We recommend
+upgrading to a newer version of Gold.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="starting">Getting Started with LLVM</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The remainder of this guide is meant to get you up and running with
+LLVM and to give you some basic information about the LLVM environment.</p>
+
+<p>The later sections of this guide describe the <a
+href="#layout">general layout</a> of the the LLVM source tree, a <a
+href="#tutorial">simple example</a> using the LLVM tool chain, and <a
+href="#links">links</a> to find more information about LLVM or to get
+help via e-mail.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="terminology">Terminology and Notation</a>
+</h3>
+
+<div>
+
+<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>
+
+<dl>
+ <dt>SRC_ROOT
+ <dd>
+ This is the top level directory of the LLVM source tree.
+ <br><br>
+
+ <dt>OBJ_ROOT
+ <dd>
+ 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
+ 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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="environment">Setting Up Your Environment</a>
+</h3>
+
+<div>
+
+<p>
+In order to compile and use LLVM, you may need to set some environment
+variables.
+
+<dl>
+ <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bitcode/libs</tt></dt>
+ <dd>[Optional] This environment variable helps LLVM linking tools find the
+ locations of your bitcode libraries. It is provided only as a
+ convenience since you can specify the paths using the -L options of the
+ tools and the C/C++ front-end will automatically use the bitcode files
+ installed in its
+ <tt>lib</tt> directory.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="unpack">Unpacking the LLVM Archives</a>
+</h3>
+
+<div>
+
+<p>
+If you have the LLVM distribution, you will need to unpack it before you
+can begin to compile it. LLVM is distributed as a set of two files: the LLVM
+suite and the LLVM GCC front end compiled for your platform. There is an
+additional test suite that is optional. Each file is a TAR archive that is
+compressed with the gzip program.
+</p>
+
+<p>The files are as follows, with <em>x.y</em> marking the version number:
+<dl>
+ <dt><tt>llvm-x.y.tar.gz</tt></dt>
+ <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>
+
+ <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
+ directory for build instructions.<br></dd>
+
+ <dt><tt>llvm-gcc-4.2-x.y-platform.tar.gz</tt></dt>
+ <dd>Binary release of the llvm-gcc-4.2 front end for a specific platform.<br></dd>
+
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="checkout">Checkout LLVM from Subversion</a>
+</h3>
+
+<div>
+
+<p>If you have access to our Subversion repository, you can get a fresh copy of
+the entire source code. All you need to do is check it out from Subversion as
+follows:</p>
+
+<ul>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
+ <li>Read-Only: <tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
+ <li>Read-Write:<tt>svn co https://user@llvm.org/svn/llvm-project/llvm/trunk
+ llvm</tt></li>
+</ul>
+
+
+<p>This will create an '<tt>llvm</tt>' directory in the current
+directory and fully populate it with the LLVM source code, Makefiles,
+test directories, and local copies of documentation files.</p>
+
+<p>If you want to get a specific release (as opposed to the most recent
+revision), you can checkout it from the '<tt>tags</tt>' directory (instead of
+'<tt>trunk</tt>'). The following releases are located in the following
+subdirectories of the '<tt>tags</tt>' directory:</p>
+
+<ul>
+<li>Release 3.0: <b>RELEASE_30/final</b></li>
+<li>Release 2.9: <b>RELEASE_29/final</b></li>
+<li>Release 2.8: <b>RELEASE_28</b></li>
+<li>Release 2.7: <b>RELEASE_27</b></li>
+<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>
+<li>Release 2.3: <b>RELEASE_23</b></li>
+<li>Release 2.2: <b>RELEASE_22</b></li>
+<li>Release 2.1: <b>RELEASE_21</b></li>
+<li>Release 2.0: <b>RELEASE_20</b></li>
+<li>Release 1.9: <b>RELEASE_19</b></li>
+<li>Release 1.8: <b>RELEASE_18</b></li>
+<li>Release 1.7: <b>RELEASE_17</b></li>
+<li>Release 1.6: <b>RELEASE_16</b></li>
+<li>Release 1.5: <b>RELEASE_15</b></li>
+<li>Release 1.4: <b>RELEASE_14</b></li>
+<li>Release 1.3: <b>RELEASE_13</b></li>
+<li>Release 1.2: <b>RELEASE_12</b></li>
+<li>Release 1.1: <b>RELEASE_11</b></li>
+<li>Release 1.0: <b>RELEASE_1</b></li>
+</ul>
+
+<p>If you would like to get the LLVM test suite (a separate package as of 1.4),
+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 test-suite
+</pre>
+</div>
+
+<p>By placing it in the <tt>llvm/projects</tt>, it will be automatically
+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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="git_mirror">GIT mirror</a>
+</h3>
+
+<div>
+
+<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:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+</pre>
+
+<p>If you want to check out clang too, run:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+cd llvm/tools
+git clone http://llvm.org/git/clang.git
+</pre>
+
+<p>
+Since the upstream repository is in Subversion, you should use
+<tt>"git pull --rebase"</tt>
+instead of <tt>"git pull"</tt> to avoid generating a non-linear
+history in your clone.
+To configure <tt>"git pull"</tt> to pass <tt>--rebase</tt> by default
+on the master branch, run the following command:
+</p>
+
+<pre class="doc_code">
+git config branch.master.rebase true
+</pre>
+
+<h4>Sending patches with Git</h4>
+<div>
+<p>
+Please read <a href="DeveloperPolicy.html#patches">Developer Policy</a>, too.
+</p>
+
+<p>
+Assume <tt>master</tt> points the upstream and <tt>mybranch</tt> points your
+working branch, and <tt>mybranch</tt> is rebased onto <tt>master</tt>.
+At first you may check sanity of whitespaces:
+</p>
+
+<pre class="doc_code">
+git diff --check master..mybranch
+</pre>
+
+<p>
+The easiest way to generate a patch is as below:
+</p>
+
+<pre class="doc_code">
+git diff master..mybranch > /path/to/mybranch.diff
+</pre>
+
+<p>
+It is a little different from svn-generated diff. git-diff-generated diff has
+prefixes like <tt>a/</tt> and <tt>b/</tt>. Don't worry, most developers might
+know it could be accepted with <tt>patch -p1 -N</tt>.
+</p>
+
+<p>
+But you may generate patchset with git-format-patch. It generates
+by-each-commit patchset. To generate patch files to attach to your article:
+</p>
+
+<pre class="doc_code">
+git format-patch --no-attach master..mybranch -o /path/to/your/patchset
+</pre>
+
+<p>
+If you would like to send patches directly, you may use git-send-email or
+git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
+</p>
+
+<pre class="doc_code">
+git format-patch --attach master..mybranch --stdout | git imap-send
+</pre>
+
+<p>
+Then, your .git/config should have [imap] sections.
+</p>
+
+<pre class="doc_code">
+[imap]
+ host = imaps://imap.gmail.com
+ user = <em>your.gmail.account</em>@gmail.com
+ pass = <em>himitsu!</em>
+ port = 993
+ sslverify = false
+; in English
+ folder = "[Gmail]/Drafts"
+; example for Japanese, "Modified UTF-7" encoded.
+ folder = "[Gmail]/&Tgtm+DBN-"
+</pre>
+
+</div>
+
+<h4>For developers to work with git-svn</h4>
+<div>
+
+<p>To set up clone from which you can submit code using
+ <tt>git-svn</tt>, run:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+cd llvm
+git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l # -l avoids fetching ahead of the git mirror.
+
+# If you have clang too:
+cd tools
+git clone http://llvm.org/git/clang.git
+cd clang
+git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+</pre>
+
+<p>To update this clone without generating git-svn tags that conflict
+with the upstream git repo, run:</p>
+
+<pre class="doc_code">
+git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees.
+git checkout master
+git svn rebase -l
+(cd tools/clang &&
+ git checkout master &&
+ git svn rebase -l)
+</pre>
+
+<p>This leaves your working directories on their master branches, so
+you'll need to <tt>checkout</tt> each working branch individually and
+<tt>rebase</tt> it on top of its parent branch. (Note: This script is
+intended for relative newbies to git. If you have more experience,
+you can likely improve on it.)</p>
+
+<p>The git-svn metadata can get out of sync after you mess around with
+branches and <code>dcommit</code>. When that happens, <code>git svn
+dcommit</code> stops working, complaining about files with uncommitted
+changes. The fix is to rebuild the metadata:</p>
+
+<pre class="doc_code">
+rm -rf .git/svn
+git svn rebase -l
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="installcf">Install the GCC Front End</a>
+</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>
+
+<div>
+
+ <p>Once checked out from the Subversion repository, the LLVM suite source
+ code must be
+configured via the <tt>configure</tt> script. This script sets variables in the
+various <tt>*.in</tt> files, most notably <tt>llvm/Makefile.config</tt> and
+<tt>llvm/include/Config/config.h</tt>. It also populates <i>OBJ_ROOT</i> with
+the Makefiles needed to begin building LLVM.</p>
+
+<p>The following environment variables are used by the <tt>configure</tt>
+script to configure the build system:</p>
+
+<table summary="LLVM configure script environment variables">
+ <tr><th>Variable</th><th>Purpose</th></tr>
+ <tr>
+ <td>CC</td>
+ <td>Tells <tt>configure</tt> which C compiler to use. By default,
+ <tt>configure</tt> will look for the first GCC C compiler in
+ <tt>PATH</tt>. Use this variable to override
+ <tt>configure</tt>'s default behavior.</td>
+ </tr>
+ <tr>
+ <td>CXX</td>
+ <td>Tells <tt>configure</tt> which C++ compiler to use. By default,
+ <tt>configure</tt> will look for the first GCC C++ compiler in
+ <tt>PATH</tt>. Use this variable to override
+ <tt>configure</tt>'s default behavior.</td>
+ </tr>
+</table>
+
+<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
+ and GCC optimization flags are enabled). Note that this is the default
+ setting if you are using the LLVM distribution. The default behavior
+ of an Subversion checkout is to use an unoptimized build (also known as a
+ debug build).
+ <br><br>
+ </dd>
+ <dt><i>--enable-debug-runtime</i></dt>
+ <dd>
+ Enables debug symbols in the runtime libraries. The default is to strip
+ debug symbols from the runtime libraries.
+ </dd>
+ <dt><i>--enable-jit</i></dt>
+ <dd>
+ Compile the Just In Time (JIT) compiler functionality. This is not
+ available
+ on all platforms. The default is dependent on platform, so it is best
+ to explicitly enable it if you want it.
+ <br><br>
+ </dd>
+ <dt><i>--enable-targets=</i><tt>target-option</tt></dt>
+ <dd>Controls which targets will be built and linked into llc. The default
+ value for <tt>target_options</tt> is "all" which builds and links all
+ available targets. The value "host-only" can be specified to build only a
+ native compiler (no cross-compiler targets available). The "native" target is
+ 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>.
+ <br><br></dd>
+ <dt><i>--enable-doxygen</i></dt>
+ <dd>Look for the doxygen program and enable construction of doxygen based
+ documentation from the source code. This is disabled by default because
+ generating the documentation can take a long time and producess 100s of
+ megabytes of output.</dd>
+ <dt><i>--with-udis86</i></dt>
+ <dd>LLVM can use external disassembler library for various purposes (now it's
+ used only for examining code produced by JIT). This option will enable usage
+ of <a href="http://udis86.sourceforge.net/">udis86</a> x86 (both 32 and 64
+ bits) disassembler library.</dd>
+</dl>
+
+<p>To configure LLVM, follow these steps:</p>
+
+<ol>
+ <li><p>Change directory into the object root directory:</p>
+
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
+
+ <li><p>Run the <tt>configure</tt> script located in the LLVM source
+ tree:</p>
+
+ <div class="doc_code">
+ <pre>% <i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</pre>
+ </div></li>
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="compile">Compiling the LLVM Suite Source Code</a>
+</h3>
+
+<div>
+
+<p>Once you have configured LLVM, you can build it. There are three types of
+builds:</p>
+
+<dl>
+ <dt>Debug Builds
+ <dd>
+ These builds are the default when one is using an Subversion checkout and
+ types <tt>gmake</tt> (unless the <tt>--enable-optimized</tt> option was
+ used during configuration). The build system will compile the tools and
+ libraries with debugging information. To get a Debug Build using the
+ LLVM distribution the <tt>--disable-optimized</tt> option must be passed
+ to <tt>configure</tt>.
+ <br><br>
+
+ <dt>Release (Optimized) Builds
+ <dd>
+ These builds are enabled with the <tt>--enable-optimized</tt> option to
+ <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
+ <tt>gmake</tt> command line. For these builds, the build system will
+ compile the tools and libraries with GCC optimizations enabled and strip
+ debugging information from the libraries and executables it generates.
+ Note that Release Builds are default when using an LLVM distribution.
+ <br><br>
+
+ <dt>Profile Builds
+ <dd>
+ These builds are for use with profiling. They compile profiling
+ information into the code for use with programs like <tt>gprof</tt>.
+ Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
+ on the <tt>gmake</tt> command line.
+</dl>
+
+<p>Once you have LLVM configured, you can build it by entering the
+<i>OBJ_ROOT</i> directory and issuing the following command:</p>
+
+<div class="doc_code"><pre>% gmake</pre></div>
+
+<p>If the build fails, please <a href="#brokengcc">check here</a> to see if you
+are using a version of GCC that is known not to compile LLVM.</p>
+
+<p>
+If you have multiple processors in your machine, you may wish to use some of
+the parallel build options provided by GNU Make. For example, you could use the
+command:</p>
+
+<div class="doc_code"><pre>% gmake -j2</pre></div>
+
+<p>There are several special targets which are useful when working with the LLVM
+source code:</p>
+
+<dl>
+ <dt><tt>gmake clean</tt>
+ <dd>
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+ <br><br>
+
+ <dt><tt>gmake dist-clean</tt>
+ <dd>
+ Removes everything that <tt>gmake clean</tt> does, but also removes files
+ generated by <tt>configure</tt>. It attempts to return the source tree to the
+ original state in which it was shipped.
+ <br><br>
+
+ <dt><tt>gmake install</tt>
+ <dd>
+ Installs LLVM header files, libraries, tools, and documentation in a
+ hierarchy
+ under $PREFIX, specified with <tt>./configure --prefix=[dir]</tt>, which
+ defaults to <tt>/usr/local</tt>.
+ <br><br>
+
+ <dt><tt>gmake -C runtime install-bytecode</tt>
+ <dd>
+ Assuming you built LLVM into $OBJDIR, when this command is run, it will
+ install bitcode libraries into the GCC front end's bitcode library
+ directory. If you need to update your bitcode libraries,
+ this is the target to use once you've built them.
+ <br><br>
+</dl>
+
+<p>Please see the <a href="MakefileGuide.html">Makefile Guide</a> for further
+details on these <tt>make</tt> targets and descriptions of other targets
+available.</p>
+
+<p>It is also possible to override default values from <tt>configure</tt> by
+declaring variables on the command line. The following are some examples:</p>
+
+<dl>
+ <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
+ <dd>
+ Perform a Release (Optimized) build.
+ <br><br>
+
+ <dt><tt>gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt>
+ <dd>
+ Perform a Release (Optimized) build without assertions enabled.
+ <br><br>
+
+ <dt><tt>gmake ENABLE_OPTIMIZED=0</tt>
+ <dd>
+ Perform a Debug build.
+ <br><br>
+
+ <dt><tt>gmake ENABLE_PROFILING=1</tt>
+ <dd>
+ Perform a Profiling build.
+ <br><br>
+
+ <dt><tt>gmake VERBOSE=1</tt>
+ <dd>
+ Print what <tt>gmake</tt> is doing on standard output.
+ <br><br>
+
+ <dt><tt>gmake TOOL_VERBOSE=1</tt></dt>
+ <dd>Ask each tool invoked by the makefiles to print out what it is doing on
+ the standard output. This also implies <tt>VERBOSE=1</tt>.
+ <br><br></dd>
+</dl>
+
+<p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
+it and any subdirectories that it contains. Entering any directory inside the
+LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
+that directory that is out of date.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="cross-compile">Cross-Compiling LLVM</a>
+</h3>
+
+<div>
+ <p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
+ executables and libraries to be hosted on a platform different from the
+ platform where they are build (a Canadian Cross build). To configure a
+ cross-compile, supply the configure script with <tt>--build</tt> and
+ <tt>--host</tt> options that are different. The values of these options must
+ be legal target triples that your GCC compiler supports.</p>
+
+ <p>The result of such a build is executables that are not runnable on
+ on the build host (--build option) but can be executed on the compile host
+ (--host option).</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="objfiles">The Location of LLVM Object Files</a>
+</h3>
+
+<div>
+
+<p>The LLVM build system is capable of sharing a single LLVM source tree among
+several LLVM builds. Hence, it is possible to build LLVM for several different
+platforms or configurations using the same source tree.</p>
+
+<p>This is accomplished in the typical autoconf manner:</p>
+
+<ul>
+ <li><p>Change directory to where the LLVM object files should live:</p>
+
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
+
+ <li><p>Run the <tt>configure</tt> script found in the LLVM source
+ directory:</p>
+
+ <div class="doc_code"><pre>% <i>SRC_ROOT</i>/configure</pre></div></li>
+</ul>
+
+<p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
+named after the build type:</p>
+
+<dl>
+ <dt>Debug Builds with assertions enabled (the default)
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/lib</tt>
+ </dl>
+ <br><br>
+
+ <dt>Release Builds
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Release/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Release/lib</tt>
+ </dl>
+ <br><br>
+
+ <dt>Profile Builds
+ <dd>
+ <dl>
+ <dt>Tools
+ <dd><tt><i>OBJ_ROOT</i>/Profile/bin</tt>
+ <dt>Libraries
+ <dd><tt><i>OBJ_ROOT</i>/Profile/lib</tt>
+ </dl>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="optionalconfig">Optional Configuration Items</a>
+</h3>
+
+<div>
+
+<p>
+If you're running on a Linux system that supports the "<a
+href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>"
+module, and you have root access on the system, you can set your system up to
+execute LLVM bitcode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):</p>
+
+<div class="doc_code">
+<pre>
+$ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+$ echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+$ chmod u+x hello.bc (if needed)
+$ ./hello.bc
+</pre>
+</div>
+
+<p>
+This allows you to execute LLVM bitcode files directly. On Debian, you
+can also use this command instead of the 'echo' command above:
+</p>
+
+<div class="doc_code">
+<pre>
+$ sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="layout">Program Layout</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>One useful source of information about the LLVM source base is the LLVM <a
+href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a
+href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>.
+The following is a brief introduction to code layout:</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="examples"><tt>llvm/examples</tt></a>
+</h3>
+
+<div>
+ <p>This directory contains some simple examples of how to use the LLVM IR and
+ JIT.</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="include"><tt>llvm/include</tt></a>
+</h3>
+
+<div>
+
+<p>This directory contains public header files exported from the LLVM
+library. The three main subdirectories of this directory are:</p>
+
+<dl>
+ <dt><tt><b>llvm/include/llvm</b></tt></dt>
+ <dd>This directory contains all of the LLVM specific header files. This
+ directory also has subdirectories for different portions of LLVM:
+ <tt>Analysis</tt>, <tt>CodeGen</tt>, <tt>Target</tt>, <tt>Transforms</tt>,
+ etc...</dd>
+
+ <dt><tt><b>llvm/include/llvm/Support</b></tt></dt>
+ <dd>This directory contains generic support libraries that are provided with
+ LLVM but not necessarily specific to LLVM. For example, some C++ STL utilities
+ and a Command Line option processing library store their header files here.
+ </dd>
+
+ <dt><tt><b>llvm/include/llvm/Config</b></tt></dt>
+ <dd>This directory contains header files configured by the <tt>configure</tt>
+ script. They wrap "standard" UNIX and C header files. Source code can
+ include these header files which automatically take care of the conditional
+ #includes that the <tt>configure</tt> script generates.</dd>
+</dl>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="lib"><tt>llvm/lib</tt></a>
+</h3>
+
+<div>
+
+<p>This directory contains most of the source files of the LLVM system. In LLVM,
+almost all code exists in libraries, making it very easy to share code among the
+different <a href="#tools">tools</a>.</p>
+
+<dl>
+ <dt><tt><b>llvm/lib/VMCore/</b></tt></dt>
+ <dd> This directory holds the core LLVM source files that implement core
+ classes like Instruction and BasicBlock.</dd>
+
+ <dt><tt><b>llvm/lib/AsmParser/</b></tt></dt>
+ <dd>This directory holds the source code for the LLVM assembly language parser
+ library.</dd>
+
+ <dt><tt><b>llvm/lib/BitCode/</b></tt></dt>
+ <dd>This directory holds code for reading and write LLVM bitcode.</dd>
+
+ <dt><tt><b>llvm/lib/Analysis/</b></tt><dd>This directory contains a variety of
+ different program analyses, such as Dominator Information, Call Graphs,
+ Induction Variables, Interval Identification, Natural Loop Identification,
+ etc.</dd>
+
+ <dt><tt><b>llvm/lib/Transforms/</b></tt></dt>
+ <dd> This directory contains the source code for the LLVM to LLVM program
+ transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
+ Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
+ Elimination, and many others.</dd>
+
+ <dt><tt><b>llvm/lib/Target/</b></tt></dt>
+ <dd> This directory contains files that describe various target architectures
+ for code generation. For example, the <tt>llvm/lib/Target/X86</tt>
+ directory holds the X86 machine description while
+ <tt>llvm/lib/Target/CBackend</tt> implements the LLVM-to-C converter.</dd>
+
+ <dt><tt><b>llvm/lib/CodeGen/</b></tt></dt>
+ <dd> This directory contains the major parts of the code generator: Instruction
+ Selector, Instruction Scheduling, and Register Allocation.</dd>
+
+ <dt><tt><b>llvm/lib/MC/</b></tt></dt>
+ <dd>(FIXME: T.B.D.)</dd>
+
+ <!--FIXME: obsoleted -->
+ <dt><tt><b>llvm/lib/Debugger/</b></tt></dt>
+ <dd> This directory contains the source level debugger library that makes
+ it possible to instrument LLVM programs so that a debugger could identify
+ source code locations at which the program is executing.</dd>
+
+ <dt><tt><b>llvm/lib/ExecutionEngine/</b></tt></dt>
+ <dd> This directory contains libraries for executing LLVM bitcode directly
+ at runtime in both interpreted and JIT compiled fashions.</dd>
+
+ <dt><tt><b>llvm/lib/Support/</b></tt></dt>
+ <dd> This directory contains the source code that corresponds to the header
+ files located in <tt>llvm/include/ADT/</tt>
+ and <tt>llvm/include/Support/</tt>.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="projects"><tt>llvm/projects</tt></a>
+</h3>
+
+<div>
+ <p>This directory contains projects that are not strictly part of LLVM but are
+ shipped with LLVM. This is also the directory where you should create your own
+ LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how
+ to set up your own project.</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="runtime"><tt>llvm/runtime</tt></a>
+</h3>
+
+<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
+skeleton versions of real libraries; for example, libc is a stripped down
+version of glibc.</p>
+
+<p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
+end to compile.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="test"><tt>llvm/test</tt></a>
+</h3>
+
+<div>
+ <p>This directory contains feature and regression tests and other basic sanity
+ checks on the LLVM infrastructure. These are intended to run quickly and cover
+ a lot of territory without being exhaustive.</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="test-suite"><tt>test-suite</tt></a>
+</h3>
+
+<div>
+ <p>This is not a directory in the normal llvm module; it is a separate
+ Subversion
+ module that must be checked out (usually to <tt>projects/test-suite</tt>).
+ This
+ module contains a comprehensive correctness, performance, and benchmarking
+ test
+ suite for LLVM. It is a separate Subversion module because not every LLVM
+ user is
+ interested in downloading or building such a comprehensive test suite. For
+ further details on this test suite, please see the
+ <a href="TestingGuide.html">Testing Guide</a> document.</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="tools"><tt>llvm/tools</tt></a>
+</h3>
+
+<div>
+
+<p>The <b>tools</b> directory contains the executables built out of the
+libraries above, which form the main part of the user interface. You can
+always get help for a tool by typing <tt>tool_name -help</tt>. The
+following is a brief introduction to the most important tools. More detailed
+information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p>
+
+<dl>
+
+ <dt><tt><b>bugpoint</b></tt></dt>
+ <dd><tt>bugpoint</tt> is used to debug
+ optimization passes or code generation backends by narrowing down the
+ given test case to the minimum number of passes and/or instructions that
+ still cause a problem, whether it is a crash or miscompilation. See <a
+ href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
+ on using <tt>bugpoint</tt>.</dd>
+
+ <dt><tt><b>llvm-ar</b></tt></dt>
+ <dd>The archiver produces an archive containing
+ the given LLVM bitcode files, optionally with an index for faster
+ lookup.</dd>
+
+ <dt><tt><b>llvm-as</b></tt></dt>
+ <dd>The assembler transforms the human readable LLVM assembly to LLVM
+ bitcode.</dd>
+
+ <dt><tt><b>llvm-dis</b></tt></dt>
+ <dd>The disassembler transforms the LLVM bitcode to human readable
+ LLVM assembly.</dd>
+
+ <dt><tt><b>llvm-ld</b></tt></dt>
+ <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM.
+ It performs standard link time optimizations and allows optimization
+ modules to be loaded and run so that language specific optimizations can
+ be applied at link time.</dd>
+
+ <dt><tt><b>llvm-link</b></tt></dt>
+ <dd><tt>llvm-link</tt>, not surprisingly, links multiple LLVM modules into
+ a single program.</dd>
+
+ <dt><tt><b>lli</b></tt></dt>
+ <dd><tt>lli</tt> is the LLVM interpreter, which
+ can directly execute LLVM bitcode (although very slowly...). For architectures
+ that support it (currently x86, Sparc, and PowerPC), by default, <tt>lli</tt>
+ will function as a Just-In-Time compiler (if the functionality was compiled
+ in), and will execute the code <i>much</i> faster than the interpreter.</dd>
+
+ <dt><tt><b>llc</b></tt></dt>
+ <dd> <tt>llc</tt> is the LLVM backend compiler, which
+ translates LLVM bitcode to a native code assembly file or to C code (with
+ the -march=c option).</dd>
+
+ <dt><tt><b>llvm-gcc</b></tt></dt>
+ <dd><tt>llvm-gcc</tt> is a GCC-based C frontend that has been retargeted to
+ use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM
+ bitcode or assembly (with the <tt>-emit-llvm</tt> option) instead of the
+ usual machine code output. It works just like any other GCC compiler,
+ taking the typical <tt>-c, -S, -E, -o</tt> options that are typically used.
+ Additionally, the the source code for <tt>llvm-gcc</tt> is available as a
+ separate Subversion module.</dd>
+
+ <dt><tt><b>opt</b></tt></dt>
+ <dd><tt>opt</tt> reads LLVM bitcode, applies a series of LLVM to LLVM
+ transformations (which are specified on the command line), and then outputs
+ the resultant bitcode. The '<tt>opt -help</tt>' command is a good way to
+ get a list of the program transformations available in LLVM.<br>
+ <dd><tt>opt</tt> can also be used to run a specific analysis on an input
+ LLVM bitcode file and print out the results. It is primarily useful for
+ debugging analyses, or familiarizing yourself with what an analysis does.</dd>
+</dl>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="utils"><tt>llvm/utils</tt></a>
+</h3>
+
+<div>
+
+<p>This directory contains utilities for working with LLVM source code, and some
+of the utilities are actually required as part of the build process because they
+are code generators for parts of LLVM infrastructure.</p>
+
+<dl>
+ <dt><tt><b>codegen-diff</b></tt> <dd><tt>codegen-diff</tt> is a script
+ that finds differences between code that LLC generates and code that LLI
+ generates. This is a useful tool if you are debugging one of them,
+ assuming that the other generates correct output. For the full user
+ manual, run <tt>`perldoc codegen-diff'</tt>.<br><br>
+
+ <dt><tt><b>emacs/</b></tt> <dd>The <tt>emacs</tt> directory contains
+ syntax-highlighting files which will work with Emacs and XEmacs editors,
+ providing syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the <tt>README</tt> file in that directory.<br><br>
+
+ <dt><tt><b>getsrcs.sh</b></tt> <dd>The <tt>getsrcs.sh</tt> script finds
+ and outputs all non-generated source files, which is useful if one wishes
+ to do a lot of development across directories and does not want to
+ individually find each file. One way to use it is to run, for example:
+ <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
+ tree.<br><br>
+
+ <dt><tt><b>llvmgrep</b></tt></dt>
+ <dd>This little tool performs an "egrep -H -n" on each source file in LLVM and
+ passes to it a regular expression provided on <tt>llvmgrep</tt>'s command
+ line. This is a very efficient way of searching the source base for a
+ particular regular expression.</dd>
+
+ <dt><tt><b>makellvm</b></tt> <dd>The <tt>makellvm</tt> script compiles all
+ files in the current directory and then compiles and links the tool that
+ is the first argument. For example, assuming you are in the directory
+ <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
+ simply running <tt>makellvm llc</tt> will make a build of the current
+ 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
+ files.<br><br>
+
+ <dt><tt><b>vim/</b></tt> <dd>The <tt>vim</tt> directory contains
+ syntax-highlighting files which will work with the VIM editor, providing
+ syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the <tt>README</tt> file in that directory.<br><br>
+
+</dl>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="tutorial">An Example Using the LLVM Tool Chain</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<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>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="tutorial4">Example with llvm-gcc4</a>
+</h3>
+
+<div>
+
+<ol>
+ <li><p>First, create a simple C file, name it 'hello.c':</p>
+
+<div class="doc_code">
+<pre>
+#include <stdio.h>
+
+int main() {
+ printf("hello world\n");
+ return 0;
+}
+</pre></div></li>
+
+ <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>
+
+ <p>Note that llvm-gcc 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>
+
+ <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>
+
+ <li><p>Run the program in both forms. To run the program, use:</p>
+
+ <div class="doc_code"><pre>% ./hello</pre></div>
+
+ <p>and</p>
+
+ <div class="doc_code"><pre>% lli hello.bc</pre></div>
+
+ <p>The second examples shows how to invoke the LLVM JIT, <a
+ href="CommandGuide/html/lli.html">lli</a>.</p></li>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+<div class="doc_code">
+<pre>llvm-dis < hello.bc | less</pre>
+</div></li>
+
+ <li><p>Compile the program to native assembly using the LLC code
+ generator:</p>
+
+ <div class="doc_code"><pre>% llc hello.bc -o hello.s</pre></div></li>
+
+ <li><p>Assemble the native assembly language file into a program:</p>
+
+<div class="doc_code">
+<pre>
+<b>Solaris:</b> % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+
+<b>Others:</b> % gcc hello.s -o hello.native
+</pre>
+</div></li>
+
+ <li><p>Execute the native code program:</p>
+
+ <div class="doc_code"><pre>% ./hello.native</pre></div>
+
+ <p>Note that using llvm-gcc 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>
+
+</ol>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="problems">Common Problems</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="links">Links</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document is just an <b>introduction</b> on how to use LLVM to do
+some simple things... there are many more interesting and complicated things
+that you can do that aren't documented here (but we'll gladly accept a patch
+if you want to write something up!). For more information about LLVM, check
+out:</p>
+
+<ul>
+ <li><a href="http://llvm.org/">LLVM homepage</a></li>
+ <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
+ <li><a href="http://llvm.org/docs/Projects.html">Starting a Project
+ that Uses LLVM</a></li>
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-10-17 01:31:32 -0500 (Mon, 17 Oct 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GettingStartedVS.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GettingStartedVS.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GettingStartedVS.html (added)
+++ www-releases/trunk/3.0/docs/GettingStartedVS.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,369 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Getting Started with LLVM System for Microsoft Visual Studio</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+ Getting Started with the LLVM System using Microsoft Visual Studio
+</h1>
+
+<ul>
+ <li><a href="#overview">Overview</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="#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: <a href="http://llvm.org/">The LLVM Team</a></p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="overview"><b>Overview</b></a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <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.</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>
+ page.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="requirements"><b>Requirements</b></a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+ <p>Before you begin to use the LLVM system, review the requirements given
+ below. This may save you some trouble by knowing ahead of time what hardware
+ and software you will need.</p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="hardware"><b>Hardware</b></a>
+</h3>
+
+<div>
+
+ <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine.
+ The LLVM source tree and object files, libraries and executables will consume
+ approximately 3GB.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="software"><b>Software</b></a></h3>
+<div>
+
+ <p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1
+ beta and the normal VS2005 still have bugs that are not completely
+ compatible. Earlier versions of Visual Studio do not support the C++ standard
+ well enough and will not work.</p>
+
+ <p>You will 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>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>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="quickstart"><b>Getting Started</b></a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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/trunk llvm</tt></li>
+ <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>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>
+
+ <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>
+
+ <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>
+
+ <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 by merely building the project
+ "check". The test results will be shown in the VS output
+ window.</li>
+ </ul>
+ </li>
+
+ <!-- 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>
+
+ <p>Note that quite a few of these test will fail.</p>
+ </li>
+
+ <li>A specific test or test directory can be run with:
+
+<div class="doc_code">
+<pre>
+% llvm-lit test/path/to/test
+</pre>
+</div>
+ </li>
+ </ul>
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="tutorial">An Example Using the LLVM Tool Chain</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<ol>
+ <li><p>First, create a simple C file, name it 'hello.c':</p>
+
+<div class="doc_code">
+<pre>
+#include <stdio.h>
+int main() {
+ printf("hello world\n");
+ return 0;
+}
+</pre></div></li>
+
+ <li><p>Next, compile the C file into a LLVM bitcode file:</p>
+
+<div class="doc_code">
+<pre>
+% clang -c hello.c -emit-llvm -o hello.bc
+</pre>
+</div>
+
+ <p>This will create the result file <tt>hello.bc</tt> which is the LLVM
+ bitcode that corresponds the the compiled program and the library
+ 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>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>
+
+ <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
+ code:</p>
+
+<div class="doc_code">
+<pre>
+% llvm-dis < hello.bc | more
+</pre>
+</div></li>
+
+ <li><p>Compile the program to object code using the LLC code generator:</p>
+
+<div class="doc_code">
+<pre>
+% llc -filetype=obj hello.bc
+</pre>
+</div></li>
+
+ <li><p>Link to binary using Microsoft link:</p>
+
+<div class="doc_code">
+<pre>
+% link hello.obj -defaultlib:libcmt
+</pre>
+</div>
+
+ <li><p>Execute the native code program:</p>
+
+<div class="doc_code">
+<pre>
+% hello.exe
+</pre>
+</div></li>
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="problems">Common Problems</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="links">Links</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document is just an <b>introduction</b> to how to use LLVM to do
+some simple things... there are many more interesting and complicated things
+that you can do that aren't documented here (but we'll gladly accept a patch
+if you want to write something up!). For more information about LLVM, check
+out:</p>
+
+<ul>
+ <li><a href="http://llvm.org/">LLVM homepage</a></li>
+ <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2011-04-22 19:30:22 -0500 (Fri, 22 Apr 2011) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/GoldPlugin.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/GoldPlugin.html?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/GoldPlugin.html (added)
+++ www-releases/trunk/3.0/docs/GoldPlugin.html Thu Dec 1 11:03:06 2011
@@ -0,0 +1,228 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>LLVM gold plugin</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>LLVM gold plugin</h1>
+<ol>
+ <li><a href="#introduction">Introduction</a></li>
+ <li><a href="#build">How to build it</a></li>
+ <li><a href="#usage">Usage</a>
+ <ul>
+ <li><a href="#example1">Example of link time optimization</a></li>
+ <li><a href="#lto_autotools">Quickstart for using LTO with autotooled projects</a></li>
+ </ul></li>
+ <li><a href="#licensing">Licensing</a></li>
+</ol>
+<div class="doc_author">Written by Nick Lewycky</div>
+
+<!--=========================================================================-->
+<h2><a name="introduction">Introduction</a></h2>
+<!--=========================================================================-->
+<div>
+ <p>Building with link time optimization requires cooperation from the
+system linker. LTO support on Linux systems requires that you use
+the <a href="http://sourceware.org/binutils">gold linker</a> which supports
+LTO via plugins. This is the same mechanism used by the
+<a href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a>
+project.</p>
+ <p>The LLVM gold plugin implements the
+<a href="http://gcc.gnu.org/wiki/whopr/driver">gold plugin interface</a>
+on top of
+<a href="LinkTimeOptimization.html#lto">libLTO</a>.
+The same plugin can also be used by other tools such as <tt>ar</tt> and
+<tt>nm</tt>.
+</div>
+<!--=========================================================================-->
+<h2><a name="build">How to build it</a></h2>
+<!--=========================================================================-->
+<div>
+ <p>You need to have gold with plugin support and build the LLVMgold
+plugin. Check whether you have gold running <tt>/usr/bin/ld -v</tt>. It will
+report “GNU gold” or else “GNU ld” if not. If you have
+gold, check for plugin support by running <tt>/usr/bin/ld -plugin</tt>. If it
+complains “missing argument” then you have plugin support. If not,
+such as an “unknown option” error then you will either need to
+build gold or install a version with plugin support.</p>
+<ul>
+ <li>To build gold with plugin support:
+ <pre class="doc_code">
+mkdir binutils
+cd binutils
+cvs -z 9 -d :pserver:anoncvs at sourceware.org:/cvs/src login
+<em>{enter "anoncvs" as the password}</em>
+cvs -z 9 -d :pserver:anoncvs at sourceware.org:/cvs/src co binutils
+mkdir build
+cd build
+../src/configure --enable-gold --enable-plugins
+make all-gold
+</pre>
+ That should leave you with <tt>binutils/build/gold/ld-new</tt> which supports the <tt>-plugin</tt> option. It also built would have
+<tt>binutils/build/binutils/ar</tt> and <tt>nm-new</tt> which support plugins
+but don't have a visible -plugin option, instead relying on the gold plugin
+being present in <tt>../lib/bfd-plugins</tt> relative to where the binaries are
+placed.
+ <li>Build the LLVMgold plugin: Configure LLVM with
+ <tt>--with-binutils-include=/path/to/binutils/src/include</tt> and run
+ <tt>make</tt>.
+</ul>
+</div>
+<!--=========================================================================-->
+<h2><a name="usage">Usage</a></h2>
+<!--=========================================================================-->
+<div>
+
+ <p>The linker takes a <tt>-plugin</tt> option that points to the path of
+ the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt>
+ would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look
+ for the line where it runs <tt>collect2</tt>. Replace that with
+ <tt>ld-new -plugin /path/to/LLVMgold.so</tt> to test it out. Once you're
+ ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt>
+ then replace it with <tt>ld-new</tt>.</p>
+
+ <p>You can produce bitcode files from <tt>clang</tt> using
+ <tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is
+ synonymous with <tt>-O3 -flto</tt>.</p>
+
+ <p><tt>Clang</tt> has a <tt>-use-gold-plugin</tt> option which looks for the
+ gold plugin in the same directories as it looks for <tt>cc1</tt> and passes
+ the <tt>-plugin</tt> option to <tt>ld</tt>. It will not look for an alternate
+ linker, which is why you need gold to be the installed system linker in your
+ path.</p>
+
+ <p>If you want <tt>ar</tt> and <tt>nm</tt> to work seamlessly as well, install
+ <tt>LLVMgold.so</tt> to <tt>/usr/lib/bfd-plugins</tt>. If you built your
+ own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to
+ <tt>/usr/bin</tt>.<p>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="example1">Example of link time optimization</a>
+</h3>
+
+<div>
+ <p>The following example shows a worked example of the gold plugin mixing
+ LLVM bitcode and native code.
+<pre class="doc_code">
+--- a.c ---
+#include <stdio.h>
+
+extern void foo1(void);
+extern void foo4(void);
+
+void foo2(void) {
+ printf("Foo2\n");
+}
+
+void foo3(void) {
+ foo4();
+}
+
+int main(void) {
+ foo1();
+}
+
+--- b.c ---
+#include <stdio.h>
+
+extern void foo2(void);
+
+void foo1(void) {
+ foo2();
+}
+
+void foo4(void) {
+ printf("Foo4");
+}
+
+--- command lines ---
+$ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file
+$ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode
+$ clang b.c -c -o b.o # <-- b.o is native object file
+$ clang -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin
+</pre>
+
+ <p>Gold informs the plugin that foo3 is never referenced outside the IR,
+ leading LLVM to delete that function. However, unlike in the
+ <a href="LinkTimeOptimization.html#example1">libLTO
+ example</a> gold does not currently eliminate foo4.</p>
+</div>
+
+</div>
+
+<!--=========================================================================-->
+<h2>
+ <a name="lto_autotools">
+ Quickstart for using LTO with autotooled projects
+ </a>
+</h2>
+<!--=========================================================================-->
+<div>
+ <p>Once your system <tt>ld</tt>, <tt>ar</tt>, and <tt>nm</tt> all support LLVM
+ bitcode, everything is in place for an easy to use LTO build of autotooled
+ projects:</p>
+
+ <ul>
+ <li>Follow the instructions <a href="#build">on how to build LLVMgold.so</a>.</li>
+ <li>Install the newly built binutils to <tt>$PREFIX</tt></li>
+ <li>Copy <tt>Release/lib/LLVMgold.so</tt> to
+ <tt>$PREFIX/libexec/gcc/x86_64-unknown-linux-gnu/4.2.1/</tt> and
+ <tt>$PREFIX/lib/bfd-plugins/</tt></li>
+ <li>Set environment variables (<tt>$PREFIX</tt> is where you installed clang and
+ binutils):
+<pre class="doc_code">
+export CC="$PREFIX/bin/clang -use-gold-plugin"
+export CXX="$PREFIX/bin/clang++ -use-gold-plugin"
+export AR="$PREFIX/bin/ar"
+export NM="$PREFIX/bin/nm"
+export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
+export CFLAGS="-O4"
+</pre>
+ </li>
+ <li>Or you can just set your path:
+<pre class="doc_code">
+export PATH="$PREFIX/bin:$PATH"
+export CC="clang -use-gold-plugin"
+export CXX="clang++ -use-gold-plugin"
+export RANLIB=/bin/true
+export CFLAGS="-O4"
+</pre></li>
+ <li>Configure & build the project as usual:
+<pre class="doc_code">
+% ./configure && make && make check
+</pre></li>
+ </ul>
+
+ <p>The environment variable settings may work for non-autotooled projects
+ too, but you may need to set the <tt>LD</tt> environment variable as
+ well.</p>
+</div>
+
+<!--=========================================================================-->
+<h2><a name="licensing">Licensing</a></h2>
+<!--=========================================================================-->
+<div>
+ <p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
+<tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so
+binary is also GPLv3. This can still be used to link non-GPLv3 programs just
+as much as gold could without the plugin.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+ <a href="mailto:nicholas at metrix.on.ca">Nick Lewycky</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2010-04-16 23:58:21 -0800 (Fri, 16 Apr 2010) $
+</address>
+</body>
+</html>
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,74 @@
+Date: Sat, 18 Nov 2000 09:19:35 -0600 (CST)
+From: Vikram Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: a few thoughts
+
+I've been mulling over the virtual machine problem and I had some
+thoughts about some things for us to think about discuss:
+
+1. We need to be clear on our goals for the VM. Do we want to emphasize
+ portability and safety like the Java VM? Or shall we focus on the
+ architecture interface first (i.e., consider the code generation and
+ processor issues), since the architecture interface question is also
+ important for portable Java-type VMs?
+
+ This is important because the audiences for these two goals are very
+ different. Architects and many compiler people care much more about
+ the second question. The Java compiler and OS community care much more
+ about the first one.
+
+ Also, while the architecture interface question is important for
+ Java-type VMs, the design constraints are very different.
+
+
+2. Design issues to consider (an initial list that we should continue
+ to modify). Note that I'm not trying to suggest actual solutions here,
+ but just various directions we can pursue:
+
+ a. A single-assignment VM, which we've both already been thinking about.
+
+ b. A strongly-typed VM. One question is do we need the types to be
+ explicitly declared or should they be inferred by the dynamic compiler?
+
+ c. How do we get more high-level information into the VM while keeping
+ to a low-level VM design?
+
+ o Explicit array references as operands? An alternative is
+ to have just an array type, and let the index computations be
+ separate 3-operand instructions.
+
+ o Explicit instructions to handle aliasing, e.g.s:
+ -- an instruction to say "I speculate that these two values are not
+ aliased, but check at runtime", like speculative execution in
+ EPIC?
+ -- or an instruction to check whether two values are aliased and
+ execute different code depending on the answer, somewhat like
+ predicated code in EPIC
+
+ o (This one is a difficult but powerful idea.)
+ A "thread-id" field on every instruction that allows the static
+ compiler to generate a set of parallel threads, and then have
+ the runtime compiler and hardware do what they please with it.
+ This has very powerful uses, but thread-id on every instruction
+ is expensive in terms of instruction size and code size.
+ We would need to compactly encode it somehow.
+
+ Also, this will require some reading on at least two other
+ projects:
+ -- Multiscalar architecture from Wisconsin
+ -- Simultaneous multithreading architecture from Washington
+
+ o Or forget all this and stick to a traditional instruction set?
+
+
+BTW, on an unrelated note, after the meeting yesterday, I did remember
+that you had suggested doing instruction scheduling on SSA form instead
+of a dependence DAG earlier in the semester. When we talked about
+it yesterday, I didn't remember where the idea had come from but I
+remembered later. Just giving credit where its due...
+
+Perhaps you can save the above as a file under RCS so you and I can
+continue to expand on this.
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,199 @@
+Date: Sun, 19 Nov 2000 16:23:57 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram Adve <vadve at cs.uiuc.edu>
+Subject: Re: a few thoughts
+
+Okay... here are a few of my thoughts on this (it's good to know that we
+think so alike!):
+
+> 1. We need to be clear on our goals for the VM. Do we want to emphasize
+> portability and safety like the Java VM? Or shall we focus on the
+> architecture interface first (i.e., consider the code generation and
+> processor issues), since the architecture interface question is also
+> important for portable Java-type VMs?
+
+I forsee the architecture looking kinda like this: (which is completely
+subject to change)
+
+1. The VM code is NOT guaranteed safe in a java sense. Doing so makes it
+ basically impossible to support C like languages. Besides that,
+ certifying a register based language as safe at run time would be a
+ pretty expensive operation to have to do. Additionally, we would like
+ to be able to statically eliminate many bounds checks in Java
+ programs... for example.
+
+ 2. Instead, we can do the following (eventually):
+ * Java bytecode is used as our "safe" representation (to avoid
+ reinventing something that we don't add much value to). When the
+ user chooses to execute Java bytecodes directly (ie, not
+ precompiled) the runtime compiler can do some very simple
+ transformations (JIT style) to convert it into valid input for our
+ VM. Performance is not wonderful, but it works right.
+ * The file is scheduled to be compiled (rigorously) at a later
+ time. This could be done by some background process or by a second
+ processor in the system during idle time or something...
+ * To keep things "safe" ie to enforce a sandbox on Java/foreign code,
+ we could sign the generated VM code with a host specific private
+ key. Then before the code is executed/loaded, we can check to see if
+ the trusted compiler generated the code. This would be much quicker
+ than having to validate consistency (especially if bounds checks have
+ been removed, for example)
+
+> This is important because the audiences for these two goals are very
+> different. Architects and many compiler people care much more about
+> the second question. The Java compiler and OS community care much more
+> about the first one.
+
+3. By focusing on a more low level virtual machine, we have much more room
+ for value add. The nice safe "sandbox" VM can be provided as a layer
+ on top of it. It also lets us focus on the more interesting compilers
+ related projects.
+
+> 2. Design issues to consider (an initial list that we should continue
+> to modify). Note that I'm not trying to suggest actual solutions here,
+> but just various directions we can pursue:
+
+Understood. :)
+
+> a. A single-assignment VM, which we've both already been thinking
+> about.
+
+Yup, I think that this makes a lot of sense. I am still intrigued,
+however, by the prospect of a minimally allocated VM representation... I
+think that it could have definite advantages for certain applications
+(think very small machines, like PDAs). I don't, however, think that our
+initial implementations should focus on this. :)
+
+Here are some other auxiliary goals that I think we should consider:
+
+1. Primary goal: Support a high performance dynamic compilation
+ system. This means that we have an "ideal" division of labor between
+ the runtime and static compilers. Of course, the other goals of the
+ system somewhat reduce the importance of this point (f.e. portability
+ reduces performance, but hopefully not much)
+2. Portability to different processors. Since we are most familiar with
+ x86 and solaris, I think that these two are excellent candidates when
+ we get that far...
+3. Support for all languages & styles of programming (general purpose
+ VM). This is the point that disallows java style bytecodes, where all
+ array refs are checked for bounds, etc...
+4. Support linking between different language families. For example, call
+ C functions directly from Java without using the nasty/slow/gross JNI
+ layer. This involves several subpoints:
+ A. Support for languages that require garbage collectors and integration
+ with languages that don't. As a base point, we could insist on
+ always using a conservative GC, but implement free as a noop, f.e.
+
+> b. A strongly-typed VM. One question is do we need the types to be
+> explicitly declared or should they be inferred by the dynamic
+> compiler?
+
+ B. This is kind of similar to another idea that I have: make OOP
+ constructs (virtual function tables, class heirarchies, etc) explicit
+ in the VM representation. I believe that the number of additional
+ constructs would be fairly low, but would give us lots of important
+ information... something else that would/could be important is to
+ have exceptions as first class types so that they would be handled in
+ a uniform way for the entire VM... so that C functions can call Java
+ functions for example...
+
+> c. How do we get more high-level information into the VM while keeping
+> to a low-level VM design?
+> o Explicit array references as operands? An alternative is
+> to have just an array type, and let the index computations be
+> separate 3-operand instructions.
+
+ C. In the model I was thinking of (subject to change of course), we
+ would just have an array type (distinct from the pointer
+ types). This would allow us to have arbitrarily complex index
+ expressions, while still distinguishing "load" from "Array load",
+ for example. Perhaps also, switch jump tables would be first class
+ types as well? This would allow better reasoning about the program.
+
+5. Support dynamic loading of code from various sources. Already
+ mentioned above was the example of loading java bytecodes, but we want
+ to support dynamic loading of VM code as well. This makes the job of
+ the runtime compiler much more interesting: it can do interprocedural
+ optimizations that the static compiler can't do, because it doesn't
+ have all of the required information (for example, inlining from
+ shared libraries, etc...)
+
+6. Define a set of generally useful annotations to add to the VM
+ representation. For example, a function can be analysed to see if it
+ has any sideeffects when run... also, the MOD/REF sets could be
+ calculated, etc... we would have to determine what is reasonable. This
+ would generally be used to make IP optimizations cheaper for the
+ runtime compiler...
+
+> o Explicit instructions to handle aliasing, e.g.s:
+> -- an instruction to say "I speculate that these two values are not
+> aliased, but check at runtime", like speculative execution in
+> EPIC?
+> -- or an instruction to check whether two values are aliased and
+> execute different code depending on the answer, somewhat like
+> predicated code in EPIC
+
+These are also very good points... if this can be determined at compile
+time. I think that an epic style of representation (not the instruction
+packing, just the information presented) could be a very interesting model
+to use... more later...
+
+> o (This one is a difficult but powerful idea.)
+> A "thread-id" field on every instruction that allows the static
+> compiler to generate a set of parallel threads, and then have
+> the runtime compiler and hardware do what they please with it.
+> This has very powerful uses, but thread-id on every instruction
+> is expensive in terms of instruction size and code size.
+> We would need to compactly encode it somehow.
+
+Yes yes yes! :) I think it would be *VERY* useful to include this kind
+of information (which EPIC architectures *implicitly* encode. The trend
+that we are seeing supports this greatly:
+
+1. Commodity processors are getting massive SIMD support:
+ * Intel/Amd MMX/MMX2
+ * AMD's 3Dnow!
+ * Intel's SSE/SSE2
+ * Sun's VIS
+2. SMP is becoming much more common, especially in the server space.
+3. Multiple processors on a die are right around the corner.
+
+If nothing else, not designing this in would severely limit our future
+expansion of the project...
+
+> Also, this will require some reading on at least two other
+> projects:
+> -- Multiscalar architecture from Wisconsin
+> -- Simultaneous multithreading architecture from Washington
+>
+> o Or forget all this and stick to a traditional instruction set?
+
+Heh... :) Well, from a pure research point of view, it is almost more
+attactive to go with the most extreme/different ISA possible. On one axis
+you get safety and conservatism, and on the other you get degree of
+influence that the results have. Of course the problem with pure research
+is that often times there is no concrete product of the research... :)
+
+> BTW, on an unrelated note, after the meeting yesterday, I did remember
+> that you had suggested doing instruction scheduling on SSA form instead
+> of a dependence DAG earlier in the semester. When we talked about
+> it yesterday, I didn't remember where the idea had come from but I
+> remembered later. Just giving credit where its due...
+
+:) Thanks.
+
+> Perhaps you can save the above as a file under RCS so you and I can
+> continue to expand on this.
+
+I think it makes sense to do so when we get our ideas more formalized and
+bounce it back and forth a couple of times... then I'll do a more formal
+writeup of our goals and ideas. Obviously our first implementation will
+not want to do all of the stuff that I pointed out above... be we will
+want to design the project so that we do not artificially limit ourselves
+at sometime in the future...
+
+Anyways, let me know what you think about these ideas... and if they sound
+reasonable...
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,30 @@
+From: Chris Lattner [mailto:sabre at nondot.org]
+Sent: Wednesday, December 06, 2000 6:41 PM
+To: Vikram S. Adve
+Subject: Additional idea with respect to encoding
+
+Here's another idea with respect to keeping the common case instruction
+size down (less than 32 bits ideally):
+
+Instead of encoding an instruction to operate on two register numbers,
+have it operate on two negative offsets based on the current register
+number. Therefore, instead of using:
+
+r57 = add r55, r56 (r57 is the implicit dest register, of course)
+
+We could use:
+
+r57 = add -2, -1
+
+My guess is that most SSA references are to recent values (especially if
+they correspond to expressions like (x+y*z+p*q/ ...), so the negative
+numbers would tend to stay small, even at the end of the procedure (where
+the implicit register destination number could be quite large). Of course
+the negative sign is reduntant, so you would be storing small integers
+almost all of the time, and 5-6 bits worth of register number would be
+plenty for most cases...
+
+What do you think?
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,83 @@
+SUMMARY
+-------
+
+We met to discuss the LLVM instruction format and bytecode representation:
+
+ISSUES RESOLVED
+---------------
+
+1. We decided that we shall use a flat namespace to represent our
+ variables in SSA form, as opposed to having a two dimensional namespace
+ of the original variable and the SSA instance subscript.
+
+ARGUMENT AGAINST:
+ * A two dimensional namespace would be valuable when doing alias
+ analysis because the extra information can help limit the scope of
+ analysis.
+
+ARGUMENT FOR:
+ * Including this information would require that all users of the LLVM
+ bytecode would have to parse and handle it. This would slow down the
+ common case and inflate the instruction representation with another
+ infinite variable space.
+
+REASONING:
+ * It was decided that because original variable sources could be
+ reconstructed from SSA form in linear time, that it would be an
+ unjustified expense for the common case to include the extra
+ information for one optimization. Alias analysis itself is typically
+ greater than linear in asymptotic complexity, so this extra analaysis
+ would not affect the runtime of the optimization in a significant
+ way. Additionally, this would be an unlikely optimization to do at
+ runtime.
+
+
+IDEAS TO CONSIDER
+-----------------
+
+1. Including dominator information in the LLVM bytecode
+ representation. This is one example of an analysis result that may be
+ packaged with the bytecodes themselves. As a conceptual implementation
+ idea, we could include an immediate dominator number for each basic block
+ in the LLVM bytecode program. Basic blocks could be numbered according
+ to the order of occurrence in the bytecode representation.
+
+2. Including loop header and body information. This would facilitate
+ detection of intervals and natural loops.
+
+UNRESOLVED ISSUES
+-----------------
+
+1. Will oSUIF provide enough of an infrastructure to support the research
+ that we will be doing? We know that it has less than stellar
+ performance, but hope that this will be of little importance for our
+ static compiler. This could affect us if we decided to do some IP
+ research. Also we do not yet understand the level of exception support
+ currently implemented.
+
+2. Should we consider the requirements of a direct hardware implementation
+ of the LLVM when we design it? If so, several design issues should
+ have their priorities shifted. The other option is to focus on a
+ software layer interpreting the LLVM in all cases.
+
+3. Should we use some form of packetized format to improve forward
+ compatibility? For example, we could design the system to encode a
+ packet type and length field before analysis information, to allow a
+ runtime to skip information that it didn't understand in a bytecode
+ stream. The obvious benefit would be for compatibility, the drawback
+ is that it would tend to splinter that 'standard' LLVM definition.
+
+4. Should we use fixed length instructions or variable length
+ instructions? Fetching variable length instructions is expensive (for
+ either hardware or software based LLVM runtimes), but we have several
+ 'infinite' spaces that instructions operate in (SSA register numbers,
+ type spaces, or packet length [if packets were implemented]). Several
+ options were mentioned including:
+ A. Using 16 or 32 bit numbers, which would be 'big enough'
+ B. A scheme similar to how UTF-8 works, to encode infinite numbers
+ while keeping small number small.
+ C. Use something similar to Huffman encoding, so that the most common
+ numbers are the smallest.
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,39 @@
+Date: Wed, 31 Jan 2001 12:04:33 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: another thought
+
+I have a budding idea about making LLVM a little more ambitious: a
+customizable runtime system that can be used to implement language-specific
+virtual machines for many different languages. E.g., a C vm, a C++ vm, a
+Java vm, a Lisp vm, ..
+
+The idea would be that LLVM would provide a standard set of runtime features
+(some low-level like standard assembly instructions with code generation and
+static and runtime optimization; some higher-level like type-safety and
+perhaps a garbage collection library). Each language vm would select the
+runtime features needed for that language, extending or customizing them as
+needed. Most of the machine-dependent code-generation and optimization
+features as well as low-level machine-independent optimizations (like PRE)
+could be provided by LLVM and should be sufficient for any language,
+simplifying the language compiler. (This would also help interoperability
+between languages.) Also, some or most of the higher-level
+machine-independent features like type-safety and access safety should be
+reusable by different languages, with minor extensions. The language
+compiler could then focus on language-specific analyses and optimizations.
+
+The risk is that this sounds like a universal IR -- something that the
+compiler community has tried and failed to develop for decades, and is
+universally skeptical about. No matter what we say, we won't be able to
+convince anyone that we have a universal IR that will work. We need to
+think about whether LLVM is different or if has something novel that might
+convince people. E.g., the idea of providing a package of separable
+features that different languages select from. Also, using SSA with or
+without type-safety as the intermediate representation.
+
+One interesting starting point would be to discuss how a JVM would be
+implemented on top of LLVM a bit more. That might give us clues on how to
+structure LLVM to support one or more language VMs.
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,67 @@
+Date: Tue, 6 Feb 2001 20:27:37 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Type notation debate...
+
+This is the way that I am currently planning on implementing types:
+
+Primitive Types:
+type ::= void|bool|sbyte|ubyte|short|ushort|int|uint|long|ulong
+
+Method:
+typelist ::= typelisth | /*empty*/
+typelisth ::= type | typelisth ',' type
+type ::= type (typelist)
+
+Arrays (without and with size):
+type ::= '[' type ']' | '[' INT ',' type ']'
+
+Pointer:
+type ::= type '*'
+
+Structure:
+type ::= '{' typelist '}'
+
+Packed:
+type ::= '<' INT ',' type '>'
+
+Simple examples:
+
+[[ %4, int ]] - array of (array of 4 (int))
+[ { int, int } ] - Array of structure
+[ < %4, int > ] - Array of 128 bit SIMD packets
+int (int, [[int, %4]]) - Method taking a 2d array and int, returning int
+
+
+Okay before you comment, please look at:
+
+http://www.research.att.com/~bs/devXinterview.html
+
+Search for "In another interview, you defined the C declarator syntax as
+an experiment that failed. However, this syntactic construct has been
+around for 27 years and perhaps more; why do you consider it problematic
+(except for its cumbersome syntax)?" and read that response for me. :)
+
+Now with this syntax, his example would be represented as:
+
+[ %10, bool (int, int) * ] *
+
+vs
+
+bool (*(*)[10])(int, int)
+
+in C.
+
+Basically, my argument for this type construction system is that it is
+VERY simple to use and understand (although it IS different than C, it is
+very simple and straightforward, which C is NOT). In fact, I would assert
+that most programmers TODAY do not understand pointers to member
+functions, and have to look up an example when they have to write them.
+
+In my opinion, it is critically important to have clear and concise type
+specifications, because types are going to be all over the programs.
+
+Let me know your thoughts on this. :)
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,75 @@
+Date: Thu, 8 Feb 2001 08:42:04 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <sabre at nondot.org>
+Subject: RE: Type notation debate...
+
+Chris,
+
+> Okay before you comment, please look at:
+>
+> http://www.research.att.com/~bs/devXinterview.html
+
+I read this argument. Even before that, I was already in agreement with you
+and him that the C declarator syntax is difficult and confusing.
+
+But in fact, if you read the entire answer carefully, he came to the same
+conclusion I do: that you have to go with familiar syntax over logical
+syntax because familiarity is such a strong force:
+
+ "However, familiarity is a strong force. To compare, in English, we
+live
+more or less happily with the absurd rules for "to be" (am, are, is, been,
+was, were, ...) and all attempts to simplify are treated with contempt or
+(preferably) humor. It be a curious world and it always beed."
+
+> Basically, my argument for this type construction system is that it is
+> VERY simple to use and understand (although it IS different than C, it is
+> very simple and straightforward, which C is NOT). In fact, I would assert
+> that most programmers TODAY do not understand pointers to member
+> functions, and have to look up an example when they have to write them.
+
+Again, I don't disagree with this at all. But to some extent this
+particular problem is inherently difficult. Your syntax for the above
+example may be easier for you to read because this is the way you have been
+thinking about it. Honestly, I don't find it much easier than the C syntax.
+In either case, I would have to look up an example to write pointers to
+member functions.
+
+But pointers to member functions are nowhere near as common as arrays. And
+the old array syntax:
+ type [ int, int, ...]
+is just much more familiar and clear to people than anything new you
+introduce, no matter how logical it is. Introducing a new syntax that may
+make function pointers easier but makes arrays much more difficult seems
+very risky to me.
+
+> In my opinion, it is critically important to have clear and concise type
+> specifications, because types are going to be all over the programs.
+
+I absolutely agree. But the question is, what is more clear and concise?
+The syntax programmers are used to out of years of experience or a new
+syntax that they have never seen that has a more logical structure. I think
+the answer is the former. Sometimes, you have to give up a better idea
+because you can't overcome sociological barriers to it. Qwerty keyboards
+and Windows are two classic examples of bad technology that are difficult to
+root out.
+
+P.S. Also, while I agree that most your syntax is more logical, there is
+one part that isn't:
+
+Arrays (without and with size):
+type ::= '[' type ']' | '[' INT ',' type ']'.
+
+The arrays with size lists the dimensions and the type in a single list.
+That is just too confusing:
+ [10, 40, int]
+This seems to be a 3-D array where the third dimension is something strange.
+It is too confusing to have a list of 3 things, some of which are dimensions
+and one is a type. Either of the following would be better:
+
+ array [10, 40] of int
+or
+ int [10, 40]
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,53 @@
+Date: Thu, 8 Feb 2001 14:31:05 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Type notation debate...
+
+> Arrays (without and with size):
+> type ::= '[' type ']' | '[' INT ',' type ']'.
+>
+> The arrays with size lists the dimensions and the type in a single list.
+> That is just too confusing:
+
+> [10, 40, int]
+> This seems to be a 3-D array where the third dimension is something strange.
+> It is too confusing to have a list of 3 things, some of which are dimensions
+> and one is a type.
+
+The above grammar indicates that there is only one integer parameter, ie
+the upper bound. The lower bound is always implied to be zero, for
+several reasons:
+
+* As a low level VM, we want to expose addressing computations
+ explicitly. Since the lower bound must always be known in a high level
+ language statically, the language front end can do the translation
+ automatically.
+* This fits more closely with what Java needs, ie what we need in the
+ short term. Java arrays are always zero based.
+
+If a two element list is too confusing, I would recommend an alternate
+syntax of:
+
+type ::= '[' type ']' | '[' INT 'x' type ']'.
+
+For example:
+ [12 x int]
+ [12x int]
+ [ 12 x [ 4x int ]]
+
+Which is syntactically nicer, and more explicit.
+
+> Either of the following would be better:
+> array [10, 40] of int
+
+I considered this approach for arrays in general (ie array of int/ array
+of 12 int), but found that it made declarations WAY too long. Remember
+that because of the nature of llvm, you get a lot of types strewn all over
+the program, and using the 'typedef' like facility is not a wonderful
+option, because then types aren't explicit anymore.
+
+I find this email interesting, because you contradict the previous email
+you sent, where you recommend that we stick to C syntax....
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,89 @@
+> But in fact, if you read the entire answer carefully, he came to the same
+> conclusion I do: that you have to go with familiar syntax over logical
+> syntax because familiarity is such a strong force:
+> "However, familiarity is a strong force. To compare, in English, we
+live
+> more or less happily with the absurd rules for "to be" (am, are, is, been,
+> was, were, ...) and all attempts to simplify are treated with contempt or
+> (preferably) humor. It be a curious world and it always beed."
+
+Although you have to remember that his situation was considerably
+different than ours. He was in a position where he was designing a high
+level language that had to be COMPATIBLE with C. Our language is such
+that a new person would have to learn the new, different, syntax
+anyways. Making them learn about the type system does not seem like much
+of a stretch from learning the opcodes and how SSA form works, and how
+everything ties together...
+
+> > Basically, my argument for this type construction system is that it is
+> > VERY simple to use and understand (although it IS different than C, it is
+> > very simple and straightforward, which C is NOT). In fact, I would assert
+> > that most programmers TODAY do not understand pointers to member
+> > functions, and have to look up an example when they have to write them.
+
+> Again, I don't disagree with this at all. But to some extent this
+> particular problem is inherently difficult. Your syntax for the above
+> example may be easier for you to read because this is the way you have been
+> thinking about it. Honestly, I don't find it much easier than the C syntax.
+> In either case, I would have to look up an example to write pointers to
+> member functions.
+
+I would argue that because the lexical structure of the language is self
+consistent, any person who spent a significant amount of time programming
+in LLVM directly would understand how to do it without looking it up in a
+manual. The reason this does not work for C is because you rarely have to
+declare these pointers, and the syntax is inconsistent with the method
+declaration and calling syntax.
+
+> But pointers to member functions are nowhere near as common as arrays.
+
+Very true. If you're implementing an object oriented language, however,
+remember that you have to do all the pointer to member function stuff
+yourself.... so every time you invoke a virtual method one is involved
+(instead of having C++ hide it for you behind "syntactic sugar").
+
+> And the old array syntax:
+> type [ int, int, ...]
+> is just much more familiar and clear to people than anything new you
+> introduce, no matter how logical it is.
+
+Erm... excuse me but how is this the "old array syntax"? If you are
+arguing for consistency with C, you should be asking for 'type int []',
+which is significantly different than the above (beside the above
+introduces a new operator and duplicates information
+needlessly). Basically what I am suggesting is exactly the above without
+the fluff. So instead of:
+
+ type [ int, int, ...]
+
+you use:
+
+ type [ int ]
+
+> Introducing a new syntax that may
+> make function pointers easier but makes arrays much more difficult seems
+> very risky to me.
+
+This is not about function pointers. This is about consistency in the
+type system, and consistency with the rest of the language. The point
+above does not make arrays any more difficult to use, and makes the
+structure of types much more obvious than the "c way".
+
+> > In my opinion, it is critically important to have clear and concise type
+> > specifications, because types are going to be all over the programs.
+>
+> I absolutely agree. But the question is, what is more clear and concise?
+> The syntax programmers are used to out of years of experience or a new
+> syntax that they have never seen that has a more logical structure. I think
+> the answer is the former. Sometimes, you have to give up a better idea
+> because you can't overcome sociological barriers to it. Qwerty keyboards
+> and Windows are two classic examples of bad technology that are difficult to
+> root out.
+
+Very true, but you seem to be advocating a completely different Type
+system than C has, in addition to it not offering the advantages of clear
+structure that the system I recommended does... so you seem to not have a
+problem with changing this, just with what I change it to. :)
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveComments.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveComments.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveComments.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveComments.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,120 @@
+Ok, here are my comments and suggestions about the LLVM instruction set.
+We should discuss some now, but can discuss many of them later, when we
+revisit synchronization, type inference, and other issues.
+(We have discussed some of the comments already.)
+
+
+o We should consider eliminating the type annotation in cases where it is
+ essentially obvious from the instruction type, e.g., in br, it is obvious
+ that the first arg. should be a bool and the other args should be labels:
+
+ br bool <cond>, label <iftrue>, label <iffalse>
+
+ I think your point was that making all types explicit improves clarity
+ and readability. I agree to some extent, but it also comes at the cost
+ of verbosity. And when the types are obvious from people's experience
+ (e.g., in the br instruction), it doesn't seem to help as much.
+
+
+o On reflection, I really like your idea of having the two different switch
+ types (even though they encode implementation techniques rather than
+ semantics). It should simplify building the CFG and my guess is it could
+ enable some significant optimizations, though we should think about which.
+
+
+o In the lookup-indirect form of the switch, is there a reason not to make
+ the val-type uint? Most HLL switch statements (including Java and C++)
+ require that anyway. And it would also make the val-type uniform
+ in the two forms of the switch.
+
+ I did see the switch-on-bool examples and, while cute, we can just use
+ the branch instructions in that particular case.
+
+
+o I agree with your comment that we don't need 'neg'.
+
+
+o There's a trade-off with the cast instruction:
+ + it avoids having to define all the upcasts and downcasts that are
+ valid for the operands of each instruction (you probably have thought
+ of other benefits also)
+ - it could make the bytecode significantly larger because there could
+ be a lot of cast operations
+
+
+o Making the second arg. to 'shl' a ubyte seems good enough to me.
+ 255 positions seems adequate for several generations of machines
+ and is more compact than uint.
+
+
+o I still have some major concerns about including malloc and free in the
+ language (either as builtin functions or instructions). LLVM must be
+ able to represent code from many different languages. Languages such as
+ C, C++ Java and Fortran 90 would not be able to use our malloc anyway
+ because each of them will want to provide a library implementation of it.
+
+ This gets even worse when code from different languages is linked
+ into a single executable (which is fairly common in large apps).
+ Having a single malloc would just not suffice, and instead would simply
+ complicate the picture further because it adds an extra variant in
+ addition to the one each language provides.
+
+ Instead, providing a default library version of malloc and free
+ (and perhaps a malloc_gc with garbage collection instead of free)
+ would make a good implementation available to anyone who wants it.
+
+ I don't recall all your arguments in favor so let's discuss this again,
+ and soon.
+
+
+o 'alloca' on the other hand sounds like a good idea, and the
+ implementation seems fairly language-independent so it doesn't have the
+ problems with malloc listed above.
+
+
+o About indirect call:
+ Your option #2 sounded good to me. I'm not sure I understand your
+ concern about an explicit 'icall' instruction?
+
+
+o A pair of important synchronization instr'ns to think about:
+ load-linked
+ store-conditional
+
+
+o Other classes of instructions that are valuable for pipeline performance:
+ conditional-move
+ predicated instructions
+
+
+o I believe tail calls are relatively easy to identify; do you know why
+ .NET has a tailcall instruction?
+
+
+o I agree that we need a static data space. Otherwise, emulating global
+ data gets unnecessarily complex.
+
+
+o About explicit parallelism:
+
+ We once talked about adding a symbolic thread-id field to each
+ instruction. (It could be optional so single-threaded codes are
+ not penalized.) This could map well to multi-threaded architectures
+ while providing easy ILP for single-threaded onces. But it is probably
+ too radical an idea to include in a base version of LLVM. Instead, it
+ could a great topic for a separate study.
+
+ What is the semantics of the IA64 stop bit?
+
+
+
+
+o And finally, another thought about the syntax for arrays :-)
+
+ Although this syntax:
+ array <dimension-list> of <type>
+ is verbose, it will be used only in the human-readable assembly code so
+ size should not matter. I think we should consider it because I find it
+ to be the clearest syntax. It could even make arrays of function
+ pointers somewhat readable.
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,245 @@
+From: Chris Lattner <sabre at nondot.org>
+To: "Vikram S. Adve" <vadve at cs.uiuc.edu>
+Subject: Re: LLVM Feedback
+
+I've included your feedback in the /home/vadve/lattner/llvm/docs directory
+so that it will live in CVS eventually with the rest of LLVM. I've
+significantly updated the documentation to reflect the changes you
+suggested, as specified below:
+
+> We should consider eliminating the type annotation in cases where it is
+> essentially obvious from the instruction type:
+> br bool <cond>, label <iftrue>, label <iffalse>
+> I think your point was that making all types explicit improves clarity
+> and readability. I agree to some extent, but it also comes at the
+> cost of verbosity. And when the types are obvious from people's
+> experience (e.g., in the br instruction), it doesn't seem to help as
+> much.
+
+Very true. We should discuss this more, but my reasoning is more of a
+consistency argument. There are VERY few instructions that can have all
+of the types eliminated, and doing so when available unnecessarily makes
+the language more difficult to handle. Especially when you see 'int
+%this' and 'bool %that' all over the place, I think it would be
+disorienting to see:
+
+ br %predicate, %iftrue, %iffalse
+
+for branches. Even just typing that once gives me the creeps. ;) Like I
+said, we should probably discuss this further in person...
+
+> On reflection, I really like your idea of having the two different
+> switch types (even though they encode implementation techniques rather
+> than semantics). It should simplify building the CFG and my guess is it
+> could enable some significant optimizations, though we should think
+> about which.
+
+Great. I added a note to the switch section commenting on how the VM
+should just use the instruction type as a hint, and that the
+implementation may choose altermate representations (such as predicated
+branches).
+
+> In the lookup-indirect form of the switch, is there a reason not to
+> make the val-type uint?
+
+No. This was something I was debating for a while, and didn't really feel
+strongly about either way. It is common to switch on other types in HLL's
+(for example signed int's are particularly common), but in this case, all
+that will be added is an additional 'cast' instruction. I removed that
+from the spec.
+
+> I agree with your comment that we don't need 'neg'
+
+Removed.
+
+> There's a trade-off with the cast instruction:
+> + it avoids having to define all the upcasts and downcasts that are
+> valid for the operands of each instruction (you probably have
+> thought of other benefits also)
+> - it could make the bytecode significantly larger because there could
+> be a lot of cast operations
+
+ + You NEED casts to represent things like:
+ void foo(float);
+ ...
+ int x;
+ ...
+ foo(x);
+ in a language like C. Even in a Java like language, you need upcasts
+ and some way to implement dynamic downcasts.
+ + Not all forms of instructions take every type (for example you can't
+ shift by a floating point number of bits), thus SOME programs will need
+ implicit casts.
+
+To be efficient and to avoid your '-' point above, we just have to be
+careful to specify that the instructions shall operate on all common
+types, therefore casting should be relatively uncommon. For example all
+of the arithmetic operations work on almost all data types.
+
+> Making the second arg. to 'shl' a ubyte seems good enough to me.
+> 255 positions seems adequate for several generations of machines
+
+Okay, that comment is removed.
+
+> and is more compact than uint.
+
+No, it isn't. Remember that the bytecode encoding saves value slots into
+the bytecode instructions themselves, not constant values. This is
+another case where we may introduce more cast instructions (but we will
+also reduce the number of opcode variants that must be supported by a
+virtual machine). Because most shifts are by constant values, I don't
+think that we'll have to cast many shifts. :)
+
+> I still have some major concerns about including malloc and free in the
+> language (either as builtin functions or instructions).
+
+Agreed. How about this proposal:
+
+malloc/free are either built in functions or actual opcodes. They provide
+all of the type safety that the document would indicate, blah blah
+blah. :)
+
+Now, because of all of the excellent points that you raised, an
+implementation may want to override the default malloc/free behavior of
+the program. To do this, they simply implement a "malloc" and
+"free" function. The virtual machine will then be defined to use the user
+defined malloc/free function (which return/take void*'s, not type'd
+pointers like the builtin function would) if one is available, otherwise
+fall back on a system malloc/free.
+
+Does this sound like a good compromise? It would give us all of the
+typesafety/elegance in the language while still allowing the user to do
+all the cool stuff they want to...
+
+> 'alloca' on the other hand sounds like a good idea, and the
+> implementation seems fairly language-independent so it doesn't have the
+> problems with malloc listed above.
+
+Okay, once we get the above stuff figured out, I'll put it all in the
+spec.
+
+> About indirect call:
+> Your option #2 sounded good to me. I'm not sure I understand your
+> concern about an explicit 'icall' instruction?
+
+I worry too much. :) The other alternative has been removed. 'icall' is
+now up in the instruction list next to 'call'.
+
+> I believe tail calls are relatively easy to identify; do you know why
+> .NET has a tailcall instruction?
+
+Although I am just guessing, I believe it probably has to do with the fact
+that they want languages like Haskell and lisp to be efficiently runnable
+on their VM. Of course this means that the VM MUST implement tail calls
+'correctly', or else life will suck. :) I would put this into a future
+feature bin, because it could be pretty handy...
+
+> A pair of important synchronization instr'ns to think about:
+> load-linked
+> store-conditional
+
+What is 'load-linked'? I think that (at least for now) I should add these
+to the 'possible extensions' section, because they are not immediately
+needed...
+
+> Other classes of instructions that are valuable for pipeline
+> performance:
+> conditional-move
+> predicated instructions
+
+Conditional move is effectly a special case of a predicated
+instruction... and I think that all predicated instructions can possibly
+be implemented later in LLVM. It would significantly change things, and
+it doesn't seem to be very necessary right now. It would seem to
+complicate flow control analysis a LOT in the virtual machine. I would
+tend to prefer that a predicated architecture like IA64 convert from a
+"basic block" representation to a predicated rep as part of it's dynamic
+complication phase. Also, if a basic block contains ONLY a move, then
+that can be trivally translated into a conditional move...
+
+> I agree that we need a static data space. Otherwise, emulating global
+> data gets unnecessarily complex.
+
+Definitely. Also a later item though. :)
+
+> We once talked about adding a symbolic thread-id field to each
+> ..
+> Instead, it could a great topic for a separate study.
+
+Agreed. :)
+
+> What is the semantics of the IA64 stop bit?
+
+Basically, the IA64 writes instructions like this:
+mov ...
+add ...
+sub ...
+op xxx
+op xxx
+;;
+mov ...
+add ...
+sub ...
+op xxx
+op xxx
+;;
+
+Where the ;; delimits a group of instruction with no dependencies between
+them, which can all be executed concurrently (to the limits of the
+available functional units). The ;; gets translated into a bit set in one
+of the opcodes.
+
+The advantages of this representation is that you don't have to do some
+kind of 'thread id scheduling' pass by having to specify ahead of time how
+many threads to use, and the representation doesn't have a per instruction
+overhead...
+
+> And finally, another thought about the syntax for arrays :-)
+> Although this syntax:
+> array <dimension-list> of <type>
+> is verbose, it will be used only in the human-readable assembly code so
+> size should not matter. I think we should consider it because I find it
+> to be the clearest syntax. It could even make arrays of function
+> pointers somewhat readable.
+
+My only comment will be to give you an example of why this is a bad
+idea. :)
+
+Here is an example of using the switch statement (with my recommended
+syntax):
+
+switch uint %val, label %otherwise,
+ [%3 x {uint, label}] [ { uint %57, label %l1 },
+ { uint %20, label %l2 },
+ { uint %14, label %l3 } ]
+
+Here it is with the syntax you are proposing:
+
+switch uint %val, label %otherwise,
+ array %3 of {uint, label}
+ array of {uint, label}
+ { uint %57, label %l1 },
+ { uint %20, label %l2 },
+ { uint %14, label %l3 }
+
+Which is ambiguous and very verbose. It would be possible to specify
+constants with [] brackets as in my syntax, which would look like this:
+
+switch uint %val, label %otherwise,
+ array %3 of {uint, label} [ { uint %57, label %l1 },
+ { uint %20, label %l2 },
+ { uint %14, label %l3 } ]
+
+But then the syntax is inconsistent between type definition and constant
+definition (why do []'s enclose the constants but not the types??).
+
+Anyways, I'm sure that there is much debate still to be had over
+this... :)
+
+-Chris
+
+http://www.nondot.org/~sabre/os/
+http://www.nondot.org/MagicStats/
+http://korbit.sourceforge.net/
+
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,39 @@
+Date: Tue, 13 Feb 2001 13:29:52 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: LLVM Concerns...
+
+
+I've updated the documentation to include load store and allocation
+instructions (please take a look and let me know if I'm on the right
+track):
+
+file:/home/vadve/lattner/llvm/docs/LangRef.html#memoryops
+
+I have a couple of concerns I would like to bring up:
+
+1. Reference types
+ Right now, I've spec'd out the language to have a pointer type, which
+ works fine for lots of stuff... except that Java really has
+ references: constrained pointers that cannot be manipulated: added and
+ subtracted, moved, etc... Do we want to have a type like this? It
+ could be very nice for analysis (pointer always points to the start of
+ an object, etc...) and more closely matches Java semantics. The
+ pointer type would be kept for C++ like semantics. Through analysis,
+ C++ pointers could be promoted to references in the LLVM
+ representation.
+
+2. Our "implicit" memory references in assembly language:
+ After thinking about it, this model has two problems:
+ A. If you do pointer analysis and realize that two stores are
+ independent and can share the same memory source object, there is
+ no way to represent this in either the bytecode or assembly.
+ B. When parsing assembly/bytecode, we effectively have to do a full
+ SSA generation/PHI node insertion pass to build the dependencies
+ when we don't want the "pinned" representation. This is not
+ cool.
+ I'm tempted to make memory references explicit in both the assembly and
+ bytecode to get around this... what do you think?
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,47 @@
+Date: Tue, 13 Feb 2001 18:25:42 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <sabre at nondot.org>
+Subject: RE: LLVM Concerns...
+
+> 1. Reference types
+> Right now, I've spec'd out the language to have a pointer type, which
+> works fine for lots of stuff... except that Java really has
+> references: constrained pointers that cannot be manipulated: added and
+> subtracted, moved, etc... Do we want to have a type like this? It
+> could be very nice for analysis (pointer always points to the start of
+> an object, etc...) and more closely matches Java semantics. The
+> pointer type would be kept for C++ like semantics. Through analysis,
+> C++ pointers could be promoted to references in the LLVM
+> representation.
+
+
+You're right, having references would be useful. Even for C++ the *static*
+compiler could generate references instead of pointers with fairly
+straightforward analysis. Let's include a reference type for now. But I'm
+also really concerned that LLVM is becoming big and complex and (perhaps)
+too high-level. After we get some initial performance results, we may have
+a clearer idea of what our goals should be and we should revisit this
+question then.
+
+> 2. Our "implicit" memory references in assembly language:
+> After thinking about it, this model has two problems:
+> A. If you do pointer analysis and realize that two stores are
+> independent and can share the same memory source object,
+
+not sure what you meant by "share the same memory source object"
+
+> there is
+> no way to represent this in either the bytecode or assembly.
+> B. When parsing assembly/bytecode, we effectively have to do a full
+> SSA generation/PHI node insertion pass to build the dependencies
+> when we don't want the "pinned" representation. This is not
+> cool.
+
+I understand the concern. But again, let's focus on the performance first
+and then look at the language design issues. E.g., it would be good to know
+how big the bytecode files are before expanding them further. I am pretty
+keen to explore the implications of LLVM for mobile devices. Both bytecode
+size and power consumption are important to consider there.
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,49 @@
+By Chris:
+
+LLVM has been designed with two primary goals in mind. First we strive to
+enable the best possible division of labor between static and dynamic
+compilers, and second, we need a flexible and powerful interface
+between these two complementary stages of compilation. We feel that
+providing a solution to these two goals will yield an excellent solution
+to the performance problem faced by modern architectures and programming
+languages.
+
+A key insight into current compiler and runtime systems is that a
+compiler may fall in anywhere in a "continuum of compilation" to do its
+job. On one side, scripting languages statically compile nothing and
+dynamically compile (or equivalently, interpret) everything. On the far
+other side, traditional static compilers process everything statically and
+nothing dynamically. These approaches have typically been seen as a
+tradeoff between performance and portability. On a deeper level, however,
+there are two reasons that optimal system performance may be obtained by a
+system somewhere in between these two extremes: Dynamic application
+behavior and social constraints.
+
+From a technical perspective, pure static compilation cannot ever give
+optimal performance in all cases, because applications have varying dynamic
+behavior that the static compiler cannot take into consideration. Even
+compilers that support profile guided optimization generate poor code in
+the real world, because using such optimization tunes that application
+to one particular usage pattern, whereas real programs (as opposed to
+benchmarks) often have several different usage patterns.
+
+On a social level, static compilation is a very shortsighted solution to
+the performance problem. Instruction set architectures (ISAs) continuously
+evolve, and each implementation of an ISA (a processor) must choose a set
+of tradeoffs that make sense in the market context that it is designed for.
+With every new processor introduced, the vendor faces two fundamental
+problems: First, there is a lag time between when a processor is introduced
+to when compilers generate quality code for the architecture. Secondly,
+even when compilers catch up to the new architecture there is often a large
+body of legacy code that was compiled for previous generations and will
+not or can not be upgraded. Thus a large percentage of code running on a
+processor may be compiled quite sub-optimally for the current
+characteristics of the dynamic execution environment.
+
+For these reasons, LLVM has been designed from the beginning as a long-term
+solution to these problems. Its design allows the large body of platform
+independent, static, program optimizations currently in compilers to be
+reused unchanged in their current form. It also provides important static
+type information to enable powerful dynamic and link time optimizations
+to be performed quickly and efficiently. This combination enables an
+increase in effective system performance for real world environments.
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,202 @@
+Meeting notes: Implementation idea: Exception Handling in C++/Java
+
+The 5/18/01 meeting discussed ideas for implementing exceptions in LLVM.
+We decided that the best solution requires a set of library calls provided by
+the VM, as well as an extension to the LLVM function invocation syntax.
+
+The LLVM function invocation instruction previously looks like this (ignoring
+types):
+
+ call func(arg1, arg2, arg3)
+
+The extension discussed today adds an optional "with" clause that
+associates a label with the call site. The new syntax looks like this:
+
+ call func(arg1, arg2, arg3) with funcCleanup
+
+This funcHandler always stays tightly associated with the call site (being
+encoded directly into the call opcode itself), and should be used whenever
+there is cleanup work that needs to be done for the current function if
+an exception is thrown by func (or if we are in a try block).
+
+To support this, the VM/Runtime provide the following simple library
+functions (all syntax in this document is very abstract):
+
+typedef struct { something } %frame;
+ The VM must export a "frame type", that is an opaque structure used to
+ implement different types of stack walking that may be used by various
+ language runtime libraries. We imagine that it would be typical to
+ represent a frame with a PC and frame pointer pair, although that is not
+ required.
+
+%frame getStackCurrentFrame();
+ Get a frame object for the current function. Note that if the current
+ function was inlined into its caller, the "current" frame will belong to
+ the "caller".
+
+bool isFirstFrame(%frame f);
+ Returns true if the specified frame is the top level (first activated) frame
+ for this thread. For the main thread, this corresponds to the main()
+ function, for a spawned thread, it corresponds to the thread function.
+
+%frame getNextFrame(%frame f);
+ Return the previous frame on the stack. This function is undefined if f
+ satisfies the predicate isFirstFrame(f).
+
+Label *getFrameLabel(%frame f);
+ If a label was associated with f (as discussed below), this function returns
+ it. Otherwise, it returns a null pointer.
+
+doNonLocalBranch(Label *L);
+ At this point, it is not clear whether this should be a function or
+ intrinsic. It should probably be an intrinsic in LLVM, but we'll deal with
+ this issue later.
+
+
+Here is a motivating example that illustrates how these facilities could be
+used to implement the C++ exception model:
+
+void TestFunction(...) {
+ A a; B b;
+ foo(); // Any function call may throw
+ bar();
+ C c;
+
+ try {
+ D d;
+ baz();
+ } catch (int) {
+ ...int Stuff...
+ // execution continues after the try block: the exception is consumed
+ } catch (double) {
+ ...double stuff...
+ throw; // Exception is propogated
+ }
+}
+
+This function would compile to approximately the following code (heavy
+pseudo code follows):
+
+Func:
+ %a = alloca A
+ A::A(%a) // These ctors & dtors could throw, but we ignore this
+ %b = alloca B // minor detail for this example
+ B::B(%b)
+
+ call foo() with fooCleanup // An exception in foo is propogated to fooCleanup
+ call bar() with barCleanup // An exception in bar is propogated to barCleanup
+
+ %c = alloca C
+ C::C(c)
+ %d = alloca D
+ D::D(d)
+ call baz() with bazCleanup // An exception in baz is propogated to bazCleanup
+ d->~D();
+EndTry: // This label corresponds to the end of the try block
+ c->~C() // These could also throw, these are also ignored
+ b->~B()
+ a->~A()
+ return
+
+Note that this is a very straight forward and literal translation: exactly
+what we want for zero cost (when unused) exception handling. Especially on
+platforms with many registers (ie, the IA64) setjmp/longjmp style exception
+handling is *very* impractical. Also, the "with" clauses describe the
+control flow paths explicitly so that analysis is not adversly effected.
+
+The foo/barCleanup labels are implemented as:
+
+TryCleanup: // Executed if an exception escapes the try block
+ c->~C()
+barCleanup: // Executed if an exception escapes from bar()
+ // fall through
+fooCleanup: // Executed if an exception escapes from foo()
+ b->~B()
+ a->~A()
+ Exception *E = getThreadLocalException()
+ call throw(E) // Implemented by the C++ runtime, described below
+
+Which does the work one would expect. getThreadLocalException is a function
+implemented by the C++ support library. It returns the current exception
+object for the current thread. Note that we do not attempt to recycle the
+shutdown code from before, because performance of the mainline code is
+critically important. Also, obviously fooCleanup and barCleanup may be
+merged and one of them eliminated. This just shows how the code generator
+would most likely emit code.
+
+The bazCleanup label is more interesting. Because the exception may be caught
+by the try block, we must dispatch to its handler... but it does not exist
+on the call stack (it does not have a VM Call->Label mapping installed), so
+we must dispatch statically with a goto. The bazHandler thus appears as:
+
+bazHandler:
+ d->~D(); // destruct D as it goes out of scope when entering catch clauses
+ goto TryHandler
+
+In general, TryHandler is not the same as bazHandler, because multiple
+function calls could be made from the try block. In this case, trivial
+optimization could merge the two basic blocks. TryHandler is the code
+that actually determines the type of exception, based on the Exception object
+itself. For this discussion, assume that the exception object contains *at
+least*:
+
+1. A pointer to the RTTI info for the contained object
+2. A pointer to the dtor for the contained object
+3. The contained object itself
+
+Note that it is necessary to maintain #1 & #2 in the exception object itself
+because objects without virtual function tables may be thrown (as in this
+example). Assuming this, TryHandler would look something like this:
+
+TryHandler:
+ Exception *E = getThreadLocalException();
+ switch (E->RTTIType) {
+ case IntRTTIInfo:
+ ...int Stuff... // The action to perform from the catch block
+ break;
+ case DoubleRTTIInfo:
+ ...double Stuff... // The action to perform from the catch block
+ goto TryCleanup // This catch block rethrows the exception
+ break; // Redundant, eliminated by the optimizer
+ default:
+ goto TryCleanup // Exception not caught, rethrow
+ }
+
+ // Exception was consumed
+ if (E->dtor)
+ E->dtor(E->object) // Invoke the dtor on the object if it exists
+ goto EndTry // Continue mainline code...
+
+And that is all there is to it.
+
+The throw(E) function would then be implemented like this (which may be
+inlined into the caller through standard optimization):
+
+function throw(Exception *E) {
+ // Get the start of the stack trace...
+ %frame %f = call getStackCurrentFrame()
+
+ // Get the label information that corresponds to it
+ label * %L = call getFrameLabel(%f)
+ while (%L == 0 && !isFirstFrame(%f)) {
+ // Loop until a cleanup handler is found
+ %f = call getNextFrame(%f)
+ %L = call getFrameLabel(%f)
+ }
+
+ if (%L != 0) {
+ call setThreadLocalException(E) // Allow handlers access to this...
+ call doNonLocalBranch(%L)
+ }
+ // No handler found!
+ call BlowUp() // Ends up calling the terminate() method in use
+}
+
+That's a brief rundown of how C++ exception handling could be implemented in
+llvm. Java would be very similar, except it only uses destructors to unlock
+synchronized blocks, not to destroy data. Also, it uses two stack walks: a
+nondestructive walk that builds a stack trace, then a destructive walk that
+unwinds the stack as shown here.
+
+It would be trivial to get exception interoperability between C++ and Java.
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,45 @@
+Date: Sat, 19 May 2001 19:09:13 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Meeting writeup
+
+> I read it through and it looks great!
+
+Thanks!
+
+> The finally clause in Java may need more thought. The code for this clause
+> is like a subroutine because it needs to be entered from many points (end of
+> try block and beginning of each catch block), and then needs to *return to
+> the place from where the code was entered*. That's why JVM has the
+> jsr/jsr_w instruction.
+
+Hrm... I guess that is an implementation decision. It can either be
+modelled as a subroutine (as java bytecodes do), which is really
+gross... or it can be modelled as code duplication (emitted once inline,
+then once in the exception path). Because this could, at worst,
+slightly less than double the amount of code in a function (it is
+bounded) I don't think this is a big deal. One of the really nice things
+about the LLVM representation is that it still allows for runtime code
+generation for exception paths (exceptions paths are not compiled until
+needed). Obviously a static compiler couldn't do this though. :)
+
+In this case, only one copy of the code would be compiled... until the
+other one is needed on demand. Also this strategy fits with the "zero
+cost" exception model... the standard case is not burdened with extra
+branches or "call"s.
+
+> I suppose you could save the return address in a particular register
+> (specific to this finally block), jump to the finally block, and then at the
+> end of the finally block, jump back indirectly through this register. It
+> will complicate building the CFG but I suppose that can be handled. It is
+> also unsafe in terms of checking where control returns (which is I suppose
+> why the JVM doesn't use this).
+
+I think that a code duplication method would be cleaner, and would avoid
+the caveats that you mention. Also, it does not slow down the normal case
+with an indirect branch...
+
+Like everything, we can probably defer a final decision until later. :)
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,63 @@
+Date: Fri, 1 Jun 2001 16:38:17 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Interesting: GCC passes
+
+
+Take a look at this document (which describes the order of optimizations
+that GCC performs):
+
+http://gcc.gnu.org/onlinedocs/gcc_17.html
+
+The rundown is that after RTL generation, the following happens:
+
+1 . [t] jump optimization (jumps to jumps, etc)
+2 . [t] Delete unreachable code
+3 . Compute live ranges for CSE
+4 . [t] Jump threading (jumps to jumps with identical or inverse conditions)
+5 . [t] CSE
+6 . *** Conversion to SSA
+7 . [t] SSA Based DCE
+8 . *** Conversion to LLVM
+9 . UnSSA
+10. GCSE
+11. LICM
+12. Strength Reduction
+13. Loop unrolling
+14. [t] CSE
+15. [t] DCE
+16. Instruction combination, register movement, scheduling... etc.
+
+I've marked optimizations with a [t] to indicate things that I believe to
+be relatively trivial to implement in LLVM itself. The time consuming
+things to reimplement would be SSA based PRE, Strength reduction & loop
+unrolling... these would be the major things we would miss out on if we
+did LLVM creation from tree code [inlining and other high level
+optimizations are done on the tree representation].
+
+Given the lack of "strong" optimizations that would take a long time to
+reimplement, I am leaning a bit more towards creating LLVM from the tree
+code. Especially given that SGI has GPL'd their compiler, including many
+SSA based optimizations that could be adapted (besides the fact that their
+code looks MUCH nicer than GCC :)
+
+Even if we choose to do LLVM code emission from RTL, we will almost
+certainly want to move LLVM emission from step 8 down until at least CSE
+has been rerun... which causes me to wonder if the SSA generation code
+will still work (due to global variable dependencies and stuff). I assume
+that it can be made to work, but might be a little more involved than we
+would like.
+
+I'm continuing to look at the Tree -> RTL code. It is pretty gross
+because they do some of the translation a statement at a time, and some
+of it a function at a time... I'm not quite clear why and how the
+distinction is drawn, but it does not appear that there is a wonderful
+place to attach extra info.
+
+Anyways, I'm proceeding with the RTL -> LLVM conversion phase for now. We
+can talk about this more on Monday.
+
+Wouldn't it be nice if there were a obvious decision to be made? :)
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,71 @@
+Date: Fri, 1 Jun 2001 17:08:44 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Interesting: GCC passes
+
+> That is very interesting. I agree that some of these could be done on LLVM
+> at link-time, but it is the extra time required that concerns me. Link-time
+> optimization is severely time-constrained.
+
+If we were to reimplement any of these optimizations, I assume that we
+could do them a translation unit at a time, just as GCC does now. This
+would lead to a pipeline like this:
+
+Static optimizations, xlation unit at a time:
+.c --GCC--> .llvm --llvmopt--> .llvm
+
+Link time optimizations:
+.llvm --llvm-ld--> .llvm --llvm-link-opt--> .llvm
+
+Of course, many optimizations could be shared between llvmopt and
+llvm-link-opt, but the wouldn't need to be shared... Thus compile time
+could be faster, because we are using a "smarter" IR (SSA based).
+
+> BTW, about SGI, "borrowing" SSA-based optimizations from one compiler and
+> putting it into another is not necessarily easier than re-doing it.
+> Optimization code is usually heavily tied in to the specific IR they use.
+
+Understood. The only reason that I brought this up is because SGI's IR is
+more similar to LLVM than it is different in many respects (SSA based,
+relatively low level, etc), and could be easily adapted. Also their
+optimizations are written in C++ and are actually somewhat
+structured... of course it would be no walk in the park, but it would be
+much less time consuming to adapt, say, SSA-PRE than to rewrite it.
+
+> But your larger point is valid that adding SSA based optimizations is
+> feasible and should be fun. (Again, link time cost is the issue.)
+
+Assuming linktime cost wasn't an issue, the question is:
+Does using GCC's backend buy us anything?
+
+> It also occurs to me that GCC is probably doing quite a bit of back-end
+> optimization (step 16 in your list). Do you have a breakdown of that?
+
+Not really. The irritating part of GCC is that it mixes it all up and
+doesn't have a clean separation of concerns. A lot of the "back end
+optimization" happens right along with other data optimizations (ie, CSE
+of machine specific things).
+
+As far as REAL back end optimizations go, it looks something like this:
+
+1. Instruction combination: try to make CISCy instructions, if available
+2. Register movement: try to get registers in the right places for the
+architecture to avoid register to register moves. For example, try to get
+the first argument of a function to naturally land in %o0 for sparc.
+3. Instruction scheduling: 'nuff said :)
+4. Register class preferencing: ??
+5. Local register allocation
+6. global register allocation
+7. Spilling
+8. Local regalloc
+9. Jump optimization
+10. Delay slot scheduling
+11. Branch shorting for CISC machines
+12. Instruction selection & peephole optimization
+13. Debug info output
+
+But none of this would be usable for LLVM anyways, unless we were using
+GCC as a static compiler.
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,30 @@
+Date: Wed, 20 Jun 2001 12:32:22 -0500
+From: Vikram Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: .NET vs. our VM
+
+One significant difference between .NET CLR and our VM is that the CLR
+includes full information about classes and inheritance. In fact, I just
+sat through the paper on adding templates to .NET CLR, and the speaker
+indicated that the goal seems to be to do simple static compilation (very
+little lowering or optimization). Also, the templates implementation in CLR
+"relies on dynamic class loading and JIT compilation".
+
+This is an important difference because I think there are some significant
+advantages to have a much lower level VM layer, and do significant static
+analysis and optimization.
+
+I also talked to the lead guy for KAI's C++ compiler (Arch Robison) and he
+said that SGI and other commercial compilers have included options to export
+their *IR* next to the object code (i.e., .il files) and use them for
+link-time code generation. In fact, he said that the .o file was nearly
+empty and was entirely generated from the .il at link-time. But he agreed
+that this limited the link-time interprocedural optimization to modules
+compiled by the same compiler, whereas our approach allows us to link and
+optimize modules from multiple different compilers. (Also, of course, they
+don't do anything for runtime optimization).
+
+All issues to bring up in Related Work.
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,31 @@
+Date: Fri, 6 Jul 2001 16:56:56 -0500
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: lowering the IR
+
+BTW, I do think that we should consider lowering the IR as you said. I
+didn't get time to raise it today, but it comes up with the SPARC
+move-conditional instruction. I don't think we want to put that in the core
+VM -- it is a little too specialized. But without a corresponding
+conditional move instruction in the VM, it is pretty difficult to maintain a
+close mapping between VM and machine code. Other architectures may have
+other such instructions.
+
+What I was going to suggest was that for a particular processor, we define
+additional VM instructions that match some of the unusual opcodes on the
+processor but have VM semantics otherwise, i.e., all operands are in SSA
+form and typed. This means that we can re-generate core VM code from the
+more specialized code any time we want (so that portability is not lost).
+
+Typically, a static compiler like gcc would generate just the core VM, which
+is relatively portable. Anyone (an offline tool, the linker, etc., or even
+the static compiler itself if it chooses) can transform that into more
+specialized target-specific VM code for a particular architecture. If the
+linker does it, it can do it after all machine-independent optimizations.
+This would be the most convenient, but not necessary.
+
+The main benefit of lowering will be that we will be able to retain a close
+mapping between VM and machine code.
+
+--Vikram
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,56 @@
+Date: Tue, 18 Sep 2001 00:38:37 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Idea for a simple, useful link time optimization
+
+
+In C++ programs, exceptions suck, and here's why:
+
+1. In virtually all function calls, you must assume that the function
+ throws an exception, unless it is defined as 'nothrow'. This means
+ that every function call has to have code to invoke dtors on objects
+ locally if one is thrown by the function. Most functions don't throw
+ exceptions, so this code is dead [with all the bad effects of dead
+ code, including icache pollution].
+2. Declaring a function nothrow causes catch blocks to be added to every
+ call that isnot provably nothrow. This makes them very slow.
+3. Extra extraneous exception edges reduce the opportunity for code
+ motion.
+4. EH is typically implemented with large lookup tables. Ours is going to
+ be much smaller (than the "standard" way of doing it) to start with,
+ but eliminating it entirely would be nice. :)
+5. It is physically impossible to correctly put (accurate, correct)
+ exception specifications on generic, templated code. But it is trivial
+ to analyze instantiations of said code.
+6. Most large C++ programs throw few exceptions. Most well designed
+ programs only throw exceptions in specific planned portions of the
+ code.
+
+Given our _planned_ model of handling exceptions, all of this would be
+pretty trivial to eliminate through some pretty simplistic interprocedural
+analysis. The DCE factor alone could probably be pretty significant. The
+extra code motion opportunities could also be exploited though...
+
+Additionally, this optimization can be implemented in a straight forward
+conservative manner, allowing libraries to be optimized or individual
+files even (if there are leaf functions visible in the translation unit
+that are called).
+
+I think it's a reasonable optimization that hasn't really been addressed
+(because assembly is way too low level for this), and could have decent
+payoffs... without being a overly complex optimization.
+
+After I wrote all of that, I found this page that is talking about
+basically the same thing I just wrote, except that it is translation unit
+at a time, tree based approach:
+http://www.ocston.org/~jls/ehopt.html
+
+but is very useful from "expected gain" and references perspective. Note
+that their compiler is apparently unable to inline functions that use
+exceptions, so there numbers are pretty worthless... also our results
+would (hopefully) be better because it's interprocedural...
+
+What do you think?
+
+-Chris
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2002-05-12-InstListChange.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2002-05-12-InstListChange.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2002-05-12-InstListChange.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2002-05-12-InstListChange.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,55 @@
+Date: Sun, 12 May 2002 17:12:53 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: "Vikram S. Adve" <vadve at cs.uiuc.edu>
+Subject: LLVM change
+
+There is a fairly fundemental change that I would like to make to the LLVM
+infrastructure, but I'd like to know if you see any drawbacks that I
+don't...
+
+Basically right now at the basic block level, each basic block contains an
+instruction list (returned by getInstList()) that is a ValueHolder of
+instructions. To iterate over instructions, we must actually iterate over
+the instlist, and access the instructions through the instlist.
+
+To add or remove an instruction from a basic block, we need to get an
+iterator to an instruction, which, given just an Instruction*, requires a
+linear search of the basic block the instruction is contained in... just
+to insert an instruction before another instruction, or to delete an
+instruction! This complicates algorithms that should be very simple (like
+simple constant propagation), because they aren't actually sparse anymore,
+they have to traverse basic blocks to remove constant propogated
+instructions.
+
+Additionally, adding or removing instructions to a basic block
+_invalidates all iterators_ pointing into that block, which is really
+irritating.
+
+To fix these problems (and others), I would like to make the ordering of
+the instructions be represented with a doubly linked list in the
+instructions themselves, instead of an external data structure. This is
+how many other representations do it, and frankly I can't remember why I
+originally implemented it the way I did.
+
+Long term, all of the code that depends on the nasty features in the
+instruction list (which can be found by grep'ing for getInstList()) will
+be changed to do nice local transformations. In the short term, I'll
+change the representation, but preserve the interface (including
+getInstList()) so that all of the code doesn't have to change.
+
+Iteration over the instructions in a basic block remains the simple:
+for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) ...
+
+But we will also support:
+for (Instruction *I = BB->front(); I; I = I->getNext()) ...
+
+After converting instructions over, I'll convert basic blocks and
+functions to have a similar interface.
+
+The only negative aspect of this change that I see is that it increases
+the amount of memory consumed by one pointer per instruction. Given the
+benefits, I think this is a very reasonable tradeoff.
+
+What do you think?
+
+-Chris
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,72 @@
+Changes:
+* Change the casting code to be const correct. Now, doing this is invalid:
+ const Value *V = ...;
+ Instruction *I = dyn_cast<Instruction>(V);
+ instead, the second line should be:
+ const Instruction *I = dyn_cast<Instruction>(V);
+
+* Change the casting code to allow casting a reference value thus:
+ const Value &V = ...;
+ Instruction &I = cast<Instruction>(V);
+
+ dyn_cast does not work with references, because it must return a null pointer
+ on failure.
+
+* Fundamentally change how instructions and other values are represented.
+ Before, every llvm container was an instance of the ValueHolder template,
+ instantiated for each container type. This ValueHolder was effectively a
+ wrapper around a vector of pointers to the sub-objects.
+
+ Now, instead of having a vector to pointers of objects, the objects are
+ maintained in a doubly linked list of values (ie each Instruction now has
+ Next & Previous fields). The containers are now instances of ilist (intrusive
+ linked list class), which use the next and previous fields to chain them
+ together. The advantage of this implementation is that iterators can be
+ formed directly from pointers to the LLVM value, and invalidation is much
+ easier to handle.
+
+* As part of the above change, dereferencing an iterator (for example:
+ BasicBlock::iterator) now produces a reference to the underlying type (same
+ example: Instruction&) instead of a pointer to the underlying object. This
+ makes it much easier to write nested loops that iterator over things, changing
+ this:
+
+ for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
+ for (BasicBlock::iterator II = (*BI)->begin(); II != (*BI)->end(); ++II)
+ (*II)->dump();
+
+ into:
+
+ for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
+ for (BasicBlock::iterator II = BI->begin(); II != BI->end(); ++II)
+ II->dump();
+
+ which is much more natural and what users expect.
+
+* Simplification of #include's: Before, it was necessary for a .cpp file to
+ include every .h file that it used. Now things are batched a little bit more
+ to make it easier to use. Specifically, the include graph now includes these
+ edges:
+ Module.h -> Function.h, GlobalVariable.h
+ Function.h -> BasicBlock.h, Argument.h
+ BasicBlock.h -> Instruction.h
+
+ Which means that #including Function.h is usually sufficient for getting the
+ lower level #includes.
+
+* Printing out a Value* has now changed: Printing a Value* will soon print out
+ the address of the value instead of the contents of the Value. To print out
+ the contents, you must convert it to a reference with (for example)
+ 'cout << *I' instead of 'cout << I;'. This conversion is not yet complete,
+ but will be eventually. In the mean time, both forms print out the contents.
+
+* References are used much more throughout the code base. In general, if a
+ pointer is known to never be null, it is passed in as a reference instead of a
+ pointer. For example, the instruction visitor class uses references instead
+ of pointers, and that Pass subclasses now all receive references to Values
+ instead of pointers, because they may never be null.
+
+* The Function class now has helper functions for accessing the Arguments list.
+ Instead of having to go through getArgumentList for simple things like
+ iterator over the arguments, now the a*() methods can be used to access them.
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,28 @@
+Date: Mon, 20 Jan 2003 00:00:28 -0600
+From: Brian R. Gaeke <gaeke at uiuc.edu>
+Subject: windows vs. llvm
+
+If you're interested, here are some of the major problems compiling LLVM
+under Cygwin and/or Mingw.
+
+1. Cygwin doesn't have <inttypes.h> or <stdint.h>, so all the INT*_MAX
+ symbols and standard int*_t types are off in limbo somewhere. Mingw has
+ <stdint.h>, but Cygwin doesn't like it.
+
+2. Mingw doesn't have <dlfcn.h> (because Windows doesn't have it.)
+
+3. SA_SIGINFO and friends are not around; only signal() seems to work.
+
+4. Relink, aka ld -r, doesn't work (probably an ld bug); you need
+ DONT_BUILD_RELINKED. This breaks all the tools makefiles; you just need to
+ change them to have .a's.
+
+5. There isn't a <values.h>.
+
+6. There isn't a mallinfo() (or, at least, it's documented, but it doesn't seem
+ to link).
+
+7. The version of Bison that cygwin (and newer Linux versions) comes with
+ does not like = signs in rules. Burg's gram.yc source file uses them. I think
+ you can just take them out.
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,137 @@
+Wed Jun 25 15:13:51 CDT 2003
+
+First-level instrumentation
+---------------------------
+
+We use opt to do Bytecode-to-bytecode instrumentation. Look at
+back-edges and insert llvm_first_trigger() function call which takes
+no arguments and no return value. This instrumentation is designed to
+be easy to remove, for instance by writing a NOP over the function
+call instruction.
+
+Keep count of every call to llvm_first_trigger(), and maintain
+counters in a map indexed by return address. If the trigger count
+exceeds a threshold, we identify a hot loop and perform second-level
+instrumentation on the hot loop region (the instructions between the
+target of the back-edge and the branch that causes the back-edge). We
+do not move code across basic-block boundaries.
+
+
+Second-level instrumentation
+---------------------------
+
+We remove the first-level instrumentation by overwriting the CALL to
+llvm_first_trigger() with a NOP.
+
+The reoptimizer maintains a map between machine-code basic blocks and
+LLVM BasicBlock*s. We only keep track of paths that start at the
+first machine-code basic block of the hot loop region.
+
+How do we keep track of which edges to instrument, and which edges are
+exits from the hot region? 3 step process.
+
+1) Do a DFS from the first machine-code basic block of the hot loop
+region and mark reachable edges.
+
+2) Do a DFS from the last machine-code basic block of the hot loop
+region IGNORING back edges, and mark the edges which are reachable in
+1) and also in 2) (i.e., must be reachable from both the start BB and
+the end BB of the hot region).
+
+3) Mark BBs which end in edges that exit the hot region; we need to
+instrument these differently.
+
+Assume that there is 1 free register. On SPARC we use %g1, which LLC
+has agreed not to use. Shift a 1 into it at the beginning. At every
+edge which corresponds to a conditional branch, we shift 0 for not
+taken and 1 for taken into a register. This uniquely numbers the paths
+through the hot region. Silently fail if we need more than 64 bits.
+
+At the end BB we call countPath and increment the counter based on %g1
+and the return address of the countPath call. We keep track of the
+number of iterations and the number of paths. We only run this
+version 30 or 40 times.
+
+Find the BBs that total 90% or more of execution, and aggregate them
+together to form our trace. But we do not allow more than 5 paths; if
+we have more than 5 we take the ones that are executed the most. We
+verify our assumption that we picked a hot back-edge in first-level
+instrumentation, by making sure that the number of times we took an
+exit edge from the hot trace is less than 10% of the number of
+iterations.
+
+LLC has been taught to recognize llvm_first_trigger() calls and NOT
+generate saves and restores of caller-saved registers around these
+calls.
+
+
+Phase behavior
+--------------
+
+We turn off llvm_first_trigger() calls with NOPs, but this would hide
+phase behavior from us (when some funcs/traces stop being hot and
+others become hot.)
+
+We have a SIGALRM timer that counts time for us. Every time we get a
+SIGALRM we look at our priority queue of locations where we have
+removed llvm_first_trigger() calls. Each location is inserted along
+with a time when we will next turn instrumentation back on for that
+call site. If the time has arrived for a particular call site, we pop
+that off the prio. queue and turn instrumentation back on for that
+call site.
+
+
+Generating traces
+-----------------
+
+When we finally generate an optimized trace we first copy the code
+into the trace cache. This leaves us with 3 copies of the code: the
+original code, the instrumented code, and the optimized trace. The
+optimized trace does not have instrumentation. The original code and
+the instrumented code are modified to have a branch to the trace
+cache, where the optimized traces are kept.
+
+We copy the code from the original to the instrumentation version
+by tracing the LLVM-to-Machine code basic block map and then copying
+each machine code basic block we think is in the hot region into the
+trace cache. Then we instrument that code. The process is similar for
+generating the final optimized trace; we copy the same basic blocks
+because we might need to put in fixup code for exit BBs.
+
+LLVM basic blocks are not typically used in the Reoptimizer except
+for the mapping information.
+
+We are restricted to using single instructions to branch between the
+original code, trace, and instrumented code. So we have to keep the
+code copies in memory near the original code (they can't be far enough
+away that a single pc-relative branch would not work.) Malloc() or
+data region space is too far away. this impacts the design of the
+trace cache.
+
+We use a dummy function that is full of a bunch of for loops which we
+overwrite with trace-cache code. The trace manager keeps track of
+whether or not we have enough space in the trace cache, etc.
+
+The trace insertion routine takes an original start address, a vector
+of machine instructions representing the trace, index of branches and
+their corresponding absolute targets, and index of calls and their
+corresponding absolute targets.
+
+The trace insertion routine is responsible for inserting branches from
+the beginning of the original code to the beginning of the optimized
+trace. This is because at some point the trace cache may run out of
+space and it may have to evict a trace, at which point the branch to
+the trace would also have to be removed. It uses a round-robin
+replacement policy; we have found that this is almost as good as LRU
+and better than random (especially because of problems fitting the new
+trace in.)
+
+We cannot deal with discontiguous trace cache areas. The trace cache
+is supposed to be cache-line-aligned, but it is not page-aligned.
+
+We generate instrumentation traces and optimized traces into separate
+trace caches. We keep the instrumented code around because you don't
+want to delete a trace when you still might have to return to it
+(i.e., return from a llvm_first_trigger() or countPath() call.)
+
+
Added: www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt?rev=145585&view=auto
==============================================================================
--- www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt (added)
+++ www-releases/trunk/3.0/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt Thu Dec 1 11:03:06 2011
@@ -0,0 +1,110 @@
+Thu Jun 26 14:43:04 CDT 2003
+
+Information about BinInterface
+------------------------------
+
+Take in a set of instructions with some particular register
+allocation. It allows you to add, modify, or delete some instructions,
+in SSA form (kind of like LLVM's MachineInstrs.) Then re-allocate
+registers. It assumes that the transformations you are doing are safe.
+It does not update the mapping information or the LLVM representation
+for the modified trace (so it would not, for instance, support
+multiple optimization passes; passes have to be aware of and update
+manually the mapping information.)
+
+The way you use it is you take the original code and provide it to
+BinInterface; then you do optimizations to it, then you put it in the
+trace cache.
+
+The BinInterface tries to find live-outs for traces so that it can do
+register allocation on just the trace, and stitch the trace back into
+the original code. It has to preserve the live-ins and live-outs when
+it does its register allocation. (On exits from the trace we have
+epilogues that copy live-outs back into the right registers, but
+live-ins have to be in the right registers.)
+
+
+Limitations of BinInterface
+---------------------------
+
+It does copy insertions for PHIs, which it infers from the machine
+code. The mapping info inserted by LLC is not sufficient to determine
+the PHIs.
+
+It does not handle integer or floating-point condition codes and it
+does not handle floating-point register allocation.
+
+It is not aggressively able to use lots of registers.
+
+There is a problem with alloca: we cannot find our spill space for
+spilling registers, normally allocated on the stack, if the trace
+follows an alloca(). What might be an acceptable solution would be to
+disable trace generation on functions that have variable-sized
+alloca()s. Variable-sized allocas in the trace would also probably
+screw things up.
+
+Because of the FP and alloca limitations, the BinInterface is
+completely disabled right now.
+
+
+Demo
+----
+
+This is a demo of the Ball & Larus version that does NOT use 2-level
+profiling.
+
+1. Compile program with llvm-gcc.
+2. Run opt -lowerswitch -paths -emitfuncs on the bytecode.
+ -lowerswitch change switch statements to branches
+ -paths Ball & Larus path-profiling algorithm
+ -emitfuncs emit the table of functions
+3. Run llc to generate SPARC assembly code for the result of step 2.
+4. Use g++ to link the (instrumented) assembly code.
+
+We use a script to do all this:
+------------------------------------------------------------------------------
+#!/bin/sh
+llvm-gcc $1.c -o $1
+opt -lowerswitch -paths -emitfuncs $1.bc > $1.run.bc
+llc -f $1.run.bc
+LIBS=$HOME/llvm_sparc/lib/Debug
+GXX=/usr/dcs/software/evaluation/bin/g++
+$GXX -g -L $LIBS $1.run.s -o $1.run.llc \
+$LIBS/tracecache.o \
+$LIBS/mapinfo.o \
+$LIBS/trigger.o \
+$LIBS/profpaths.o \
+$LIBS/bininterface.o \
+$LIBS/support.o \
+$LIBS/vmcore.o \
+$LIBS/transformutils.o \
+$LIBS/bcreader.o \
+-lscalaropts -lscalaropts -lanalysis \
+-lmalloc -lcpc -lm -ldl
+------------------------------------------------------------------------------
+
+5. Run the resulting binary. You will see output from BinInterface
+(described below) intermixed with the output from the program.
+
+
+Output from BinInterface
+------------------------
+
+BinInterface's debugging code prints out the following stuff in order:
+
+1. Initial code provided to BinInterface with original register
+allocation.
+
+2. Section 0 is the trace prolog, consisting mainly of live-ins and
+register saves which will be restored in epilogs.
+
+3. Section 1 is the trace itself, in SSA form used by BinInterface,
+along with the PHIs that are inserted.
+PHIs are followed by the copies that implement them.
+Each branch (i.e., out of the trace) is annotated with the
+section number that represents the epilog it branches to.
+
+4. All the other sections starting with Section 2 are trace epilogs.
+Every branch from the trace has to go to some epilog.
+
+5. After the last section is the register allocation output.
More information about the llvm-commits
mailing list