[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 Visua