From 8da18e031978bac62ca456b1d592fc1db1e904be Mon Sep 17 00:00:00 2001 From: Strahinja Val Markovic Date: Thu, 5 Jul 2012 20:58:10 -0700 Subject: [PATCH] Removing more llvm cruft files --- cpp/llvm/Makefile | 268 - cpp/llvm/bindings/Makefile | 16 - cpp/llvm/bindings/ocaml/Makefile | 19 - cpp/llvm/bindings/ocaml/analysis/Makefile | 19 - cpp/llvm/bindings/ocaml/bitreader/Makefile | 19 - cpp/llvm/bindings/ocaml/bitwriter/Makefile | 19 - .../bindings/ocaml/executionengine/Makefile | 19 - cpp/llvm/bindings/ocaml/llvm/Makefile | 42 - cpp/llvm/bindings/ocaml/target/Makefile | 19 - cpp/llvm/bindings/ocaml/transforms/Makefile | 18 - .../bindings/ocaml/transforms/ipo/Makefile | 20 - .../bindings/ocaml/transforms/scalar/Makefile | 20 - cpp/llvm/docs/AliasAnalysis.html | 1067 --- cpp/llvm/docs/Atomics.html | 569 -- cpp/llvm/docs/BitCodeFormat.html | 1470 --- cpp/llvm/docs/BranchWeightMetadata.html | 164 - cpp/llvm/docs/Bugpoint.html | 239 - cpp/llvm/docs/CMake.html | 584 -- cpp/llvm/docs/CodeGenerator.html | 3189 ------ cpp/llvm/docs/CodingStandards.html | 1568 --- cpp/llvm/docs/CommandGuide/FileCheck.pod | 245 - cpp/llvm/docs/CommandGuide/Makefile | 103 - cpp/llvm/docs/CommandGuide/bugpoint.pod | 186 - cpp/llvm/docs/CommandGuide/html/manpage.css | 256 - cpp/llvm/docs/CommandGuide/index.html | 142 - cpp/llvm/docs/CommandGuide/lit.pod | 404 - cpp/llvm/docs/CommandGuide/llc.pod | 201 - cpp/llvm/docs/CommandGuide/lli.pod | 219 - cpp/llvm/docs/CommandGuide/llvm-ar.pod | 406 - cpp/llvm/docs/CommandGuide/llvm-as.pod | 77 - .../docs/CommandGuide/llvm-bcanalyzer.pod | 315 - cpp/llvm/docs/CommandGuide/llvm-build.pod | 86 - cpp/llvm/docs/CommandGuide/llvm-config.pod | 131 - cpp/llvm/docs/CommandGuide/llvm-cov.pod | 45 - cpp/llvm/docs/CommandGuide/llvm-diff.pod | 53 - cpp/llvm/docs/CommandGuide/llvm-dis.pod | 60 - cpp/llvm/docs/CommandGuide/llvm-extract.pod | 85 - cpp/llvm/docs/CommandGuide/llvm-ld.pod | 234 - cpp/llvm/docs/CommandGuide/llvm-link.pod | 79 - cpp/llvm/docs/CommandGuide/llvm-nm.pod | 122 - cpp/llvm/docs/CommandGuide/llvm-prof.pod | 57 - cpp/llvm/docs/CommandGuide/llvm-ranlib.pod | 52 - cpp/llvm/docs/CommandGuide/llvm-stress.pod | 42 - cpp/llvm/docs/CommandGuide/manpage.css | 256 - cpp/llvm/docs/CommandGuide/opt.pod | 143 - cpp/llvm/docs/CommandGuide/tblgen.pod | 139 - cpp/llvm/docs/CommandLine.html | 1976 ---- cpp/llvm/docs/CompilerWriterInfo.html | 267 - cpp/llvm/docs/DebuggingJITedCode.html | 184 - cpp/llvm/docs/DeveloperPolicy.html | 642 -- cpp/llvm/docs/ExceptionHandling.html | 563 -- cpp/llvm/docs/ExtendedIntegerResults.txt | 133 - cpp/llvm/docs/ExtendingLLVM.html | 379 - cpp/llvm/docs/FAQ.html | 948 -- cpp/llvm/docs/GCCFEBuildInstrs.html | 279 - cpp/llvm/docs/GarbageCollection.html | 1389 --- cpp/llvm/docs/GetElementPtr.html | 753 -- cpp/llvm/docs/GettingStarted.html | 1763 ---- cpp/llvm/docs/GettingStartedVS.html | 368 - cpp/llvm/docs/GoldPlugin.html | 227 - .../2000-11-18-EarlyDesignIdeas.txt | 74 - .../2000-11-18-EarlyDesignIdeasResp.txt | 199 - .../2000-12-06-EncodingIdea.txt | 30 - .../2000-12-06-MeetingSummary.txt | 83 - .../2001-01-31-UniversalIRIdea.txt | 39 - .../2001-02-06-TypeNotationDebate.txt | 67 - .../2001-02-06-TypeNotationDebateResp1.txt | 75 - .../2001-02-06-TypeNotationDebateResp2.txt | 53 - .../2001-02-06-TypeNotationDebateResp4.txt | 89 - .../2001-02-09-AdveComments.txt | 120 - .../2001-02-09-AdveCommentsResponse.txt | 245 - .../2001-02-13-Reference-Memory.txt | 39 - .../2001-02-13-Reference-MemoryResponse.txt | 47 - .../2001-04-16-DynamicCompilation.txt | 49 - .../2001-05-18-ExceptionHandling.txt | 202 - .../2001-05-19-ExceptionResponse.txt | 45 - .../2001-06-01-GCCOptimizations.txt | 63 - .../2001-06-01-GCCOptimizations2.txt | 71 - .../2001-06-20-.NET-Differences.txt | 30 - .../2001-07-06-LoweringIRForCodeGen.txt | 31 - .../2001-09-18-OptimizeExceptions.txt | 56 - .../2002-05-12-InstListChange.txt | 55 - .../2002-06-25-MegaPatchInfo.txt | 72 - .../2003-01-23-CygwinNotes.txt | 28 - .../2003-06-25-Reoptimizer1.txt | 137 - .../2003-06-26-Reoptimizer2.txt | 110 - .../2007-OriginalClangReadme.txt | 178 - cpp/llvm/docs/HowToAddABuilder.html | 142 - cpp/llvm/docs/HowToReleaseLLVM.html | 581 -- cpp/llvm/docs/HowToSubmitABug.html | 348 - cpp/llvm/docs/LLVMBuild.html | 368 - cpp/llvm/docs/LangRef.html | 8512 ----------------- cpp/llvm/docs/Lexicon.html | 292 - cpp/llvm/docs/LinkTimeOptimization.html | 401 - cpp/llvm/docs/Makefile | 130 - cpp/llvm/docs/MakefileGuide.html | 1039 -- cpp/llvm/docs/Packaging.html | 119 - cpp/llvm/docs/Passes.html | 2067 ---- cpp/llvm/docs/ProgrammersManual.html | 4135 -------- cpp/llvm/docs/Projects.html | 489 - cpp/llvm/docs/ReleaseNotes.html | 897 -- cpp/llvm/docs/SegmentedStacks.html | 93 - cpp/llvm/docs/SourceLevelDebugging.html | 2862 ------ cpp/llvm/docs/SystemLibrary.html | 316 - cpp/llvm/docs/TableGenFundamentals.html | 973 -- cpp/llvm/docs/TestSuiteMakefileGuide.html | 351 - cpp/llvm/docs/TestingGuide.html | 906 -- cpp/llvm/docs/WritingAnLLVMBackend.html | 2533 ----- cpp/llvm/docs/WritingAnLLVMPass.html | 1954 ---- cpp/llvm/docs/doxygen.cfg.in | 1632 ---- cpp/llvm/docs/doxygen.css | 408 - cpp/llvm/docs/doxygen.footer | 13 - cpp/llvm/docs/doxygen.header | 9 - cpp/llvm/docs/doxygen.intro | 18 - cpp/llvm/docs/img/Debugging.gif | Bin 20390 -> 0 bytes cpp/llvm/docs/img/libdeps.gif | Bin 52679 -> 0 bytes cpp/llvm/docs/img/lines.gif | Bin 91 -> 0 bytes cpp/llvm/docs/img/objdeps.gif | Bin 16201 -> 0 bytes cpp/llvm/docs/img/venusflytrap.jpg | Bin 56606 -> 0 bytes cpp/llvm/docs/index.html | 286 - cpp/llvm/docs/llvm.css | 112 - cpp/llvm/docs/re_format.7 | 756 -- cpp/llvm/docs/tutorial/LangImpl1.html | 348 - cpp/llvm/docs/tutorial/LangImpl2.html | 1231 --- cpp/llvm/docs/tutorial/LangImpl3.html | 1268 --- cpp/llvm/docs/tutorial/LangImpl4.html | 1153 --- cpp/llvm/docs/tutorial/LangImpl5-cfg.png | Bin 38586 -> 0 bytes cpp/llvm/docs/tutorial/LangImpl5.html | 1772 ---- cpp/llvm/docs/tutorial/LangImpl6.html | 1829 ---- cpp/llvm/docs/tutorial/LangImpl7.html | 2164 ----- cpp/llvm/docs/tutorial/LangImpl8.html | 359 - cpp/llvm/docs/tutorial/Makefile | 30 - cpp/llvm/docs/tutorial/OCamlLangImpl1.html | 365 - cpp/llvm/docs/tutorial/OCamlLangImpl2.html | 1043 -- cpp/llvm/docs/tutorial/OCamlLangImpl3.html | 1093 --- cpp/llvm/docs/tutorial/OCamlLangImpl4.html | 1027 -- cpp/llvm/docs/tutorial/OCamlLangImpl5.html | 1560 --- cpp/llvm/docs/tutorial/OCamlLangImpl6.html | 1574 --- cpp/llvm/docs/tutorial/OCamlLangImpl7.html | 1904 ---- cpp/llvm/docs/tutorial/OCamlLangImpl8.html | 359 - cpp/llvm/docs/tutorial/index.html | 48 - cpp/llvm/examples/BrainF/Makefile | 15 - cpp/llvm/examples/ExceptionDemo/Makefile | 16 - cpp/llvm/examples/Fibonacci/Makefile | 17 - cpp/llvm/examples/HowToUseJIT/Makefile | 15 - .../examples/Kaleidoscope/Chapter2/Makefile | 13 - .../examples/Kaleidoscope/Chapter3/Makefile | 15 - .../examples/Kaleidoscope/Chapter4/Makefile | 15 - .../examples/Kaleidoscope/Chapter5/Makefile | 15 - .../examples/Kaleidoscope/Chapter6/Makefile | 15 - .../examples/Kaleidoscope/Chapter7/Makefile | 16 - cpp/llvm/examples/Kaleidoscope/Makefile | 15 - cpp/llvm/examples/Makefile | 32 - cpp/llvm/examples/ModuleMaker/Makefile | 14 - .../OCaml-Kaleidoscope/Chapter2/Makefile | 22 - .../OCaml-Kaleidoscope/Chapter3/Makefile | 24 - .../OCaml-Kaleidoscope/Chapter4/Makefile | 25 - .../OCaml-Kaleidoscope/Chapter5/Makefile | 25 - .../OCaml-Kaleidoscope/Chapter6/Makefile | 34 - .../OCaml-Kaleidoscope/Chapter7/Makefile | 34 - cpp/llvm/examples/OCaml-Kaleidoscope/Makefile | 15 - cpp/llvm/examples/ParallelJIT/Makefile | 17 - cpp/llvm/lib/Analysis/IPA/Makefile | 15 - cpp/llvm/lib/Analysis/Makefile | 16 - cpp/llvm/lib/Archive/Makefile | 17 - cpp/llvm/lib/AsmParser/Makefile | 14 - cpp/llvm/lib/Bitcode/Makefile | 14 - cpp/llvm/lib/Bitcode/Reader/Makefile | 15 - cpp/llvm/lib/Bitcode/Writer/Makefile | 15 - cpp/llvm/lib/CodeGen/AsmPrinter/Makefile | 13 - cpp/llvm/lib/CodeGen/Makefile | 22 - cpp/llvm/lib/CodeGen/SelectionDAG/Makefile | 13 - cpp/llvm/lib/DebugInfo/Makefile | 14 - .../ExecutionEngine/IntelJITEvents/Makefile | 17 - .../lib/ExecutionEngine/Interpreter/Makefile | 13 - cpp/llvm/lib/ExecutionEngine/JIT/Makefile | 38 - cpp/llvm/lib/ExecutionEngine/MCJIT/Makefile | 13 - cpp/llvm/lib/ExecutionEngine/Makefile | 24 - .../lib/ExecutionEngine/OProfileJIT/Makefile | 18 - .../lib/ExecutionEngine/RuntimeDyld/Makefile | 13 - cpp/llvm/lib/Linker/Makefile | 15 - cpp/llvm/lib/MC/MCDisassembler/Makefile | 14 - cpp/llvm/lib/MC/MCParser/Makefile | 15 - cpp/llvm/lib/MC/Makefile | 16 - cpp/llvm/lib/Makefile | 17 - cpp/llvm/lib/Object/Makefile | 14 - cpp/llvm/lib/Support/Makefile | 22 - cpp/llvm/lib/TableGen/Makefile | 18 - cpp/llvm/lib/Target/ARM/AsmParser/Makefile | 15 - cpp/llvm/lib/Target/ARM/Disassembler/Makefile | 16 - cpp/llvm/lib/Target/ARM/InstPrinter/Makefile | 15 - cpp/llvm/lib/Target/ARM/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/ARM/Makefile | 24 - cpp/llvm/lib/Target/ARM/TargetInfo/Makefile | 15 - .../lib/Target/CellSPU/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/CellSPU/Makefile | 20 - .../lib/Target/CellSPU/TargetInfo/Makefile | 15 - cpp/llvm/lib/Target/CppBackend/Makefile | 16 - .../lib/Target/CppBackend/TargetInfo/Makefile | 15 - .../lib/Target/Hexagon/InstPrinter/Makefile | 15 - .../lib/Target/Hexagon/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/Hexagon/Makefile | 23 - .../lib/Target/Hexagon/TargetInfo/Makefile | 15 - cpp/llvm/lib/Target/MBlaze/AsmParser/Makefile | 15 - .../lib/Target/MBlaze/Disassembler/Makefile | 16 - .../lib/Target/MBlaze/InstPrinter/Makefile | 16 - .../lib/Target/MBlaze/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/MBlaze/Makefile | 24 - .../lib/Target/MBlaze/TargetInfo/Makefile | 15 - .../lib/Target/MSP430/InstPrinter/Makefile | 15 - .../lib/Target/MSP430/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/MSP430/Makefile | 23 - .../lib/Target/MSP430/TargetInfo/Makefile | 15 - cpp/llvm/lib/Target/Makefile | 20 - cpp/llvm/lib/Target/Mips/AsmParser/Makefile | 15 - .../lib/Target/Mips/Disassembler/Makefile | 16 - cpp/llvm/lib/Target/Mips/InstPrinter/Makefile | 16 - .../lib/Target/Mips/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/Mips/Makefile | 23 - cpp/llvm/lib/Target/Mips/TargetInfo/Makefile | 15 - cpp/llvm/lib/Target/PTX/InstPrinter/Makefile | 16 - cpp/llvm/lib/Target/PTX/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/PTX/Makefile | 23 - cpp/llvm/lib/Target/PTX/TargetInfo/Makefile | 15 - .../lib/Target/PowerPC/InstPrinter/Makefile | 16 - .../lib/Target/PowerPC/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/PowerPC/Makefile | 23 - .../lib/Target/PowerPC/TargetInfo/Makefile | 15 - .../lib/Target/Sparc/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/Sparc/Makefile | 22 - cpp/llvm/lib/Target/Sparc/TargetInfo/Makefile | 15 - cpp/llvm/lib/Target/X86/AsmParser/Makefile | 15 - cpp/llvm/lib/Target/X86/Disassembler/Makefile | 16 - cpp/llvm/lib/Target/X86/InstPrinter/Makefile | 15 - cpp/llvm/lib/Target/X86/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/X86/Makefile | 24 - cpp/llvm/lib/Target/X86/TargetInfo/Makefile | 16 - cpp/llvm/lib/Target/X86/Utils/Makefile | 15 - .../lib/Target/XCore/MCTargetDesc/Makefile | 16 - cpp/llvm/lib/Target/XCore/Makefile | 23 - cpp/llvm/lib/Target/XCore/TargetInfo/Makefile | 16 - cpp/llvm/lib/Transforms/Hello/Makefile | 24 - cpp/llvm/lib/Transforms/IPO/Makefile | 15 - cpp/llvm/lib/Transforms/InstCombine/Makefile | 15 - .../lib/Transforms/Instrumentation/Makefile | 15 - cpp/llvm/lib/Transforms/Makefile | 20 - cpp/llvm/lib/Transforms/Scalar/Makefile | 15 - cpp/llvm/lib/Transforms/Utils/Makefile | 15 - cpp/llvm/lib/Transforms/Vectorize/Makefile | 15 - cpp/llvm/lib/VMCore/Makefile | 34 - cpp/llvm/projects/sample/Makefile | 18 - cpp/llvm/projects/sample/lib/Makefile | 13 - cpp/llvm/projects/sample/lib/sample/Makefile | 16 - cpp/llvm/projects/sample/tools/Makefile | 13 - .../projects/sample/tools/sample/Makefile | 23 - cpp/llvm/runtime/Makefile | 31 - cpp/llvm/runtime/libprofile/Makefile | 51 - cpp/llvm/test/Archive/GNU.a | Bin 4210 -> 0 bytes cpp/llvm/test/Archive/IsNAN.o | Bin 2280 -> 0 bytes cpp/llvm/test/Archive/MacOSX.a | Bin 4166 -> 0 bytes cpp/llvm/test/Archive/SVR4.a | Bin 4214 -> 0 bytes cpp/llvm/test/Archive/xpg4.a | Bin 4214 -> 0 bytes cpp/llvm/test/CodeGen/Generic/Makefile | 23 - cpp/llvm/test/Makefile | 188 - cpp/llvm/tools/Makefile | 74 - cpp/llvm/tools/bugpoint-passes/Makefile | 23 - cpp/llvm/tools/bugpoint/Makefile | 15 - cpp/llvm/tools/clang/Makefile | 111 - cpp/llvm/tools/clang/docs/Makefile | 97 - cpp/llvm/tools/clang/docs/tools/Makefile | 116 - cpp/llvm/tools/clang/examples/Makefile | 14 - .../examples/PrintFunctionNames/Makefile | 28 - .../clang/examples/analyzer-plugin/Makefile | 20 - .../clang/examples/clang-interpreter/Makefile | 26 - cpp/llvm/tools/clang/include/Makefile | 4 - cpp/llvm/tools/clang/include/clang-c/Makefile | 38 - .../tools/clang/include/clang/AST/Makefile | 29 - .../tools/clang/include/clang/Basic/Makefile | 61 - .../tools/clang/include/clang/Driver/Makefile | 18 - .../tools/clang/include/clang/Lex/Makefile | 13 - cpp/llvm/tools/clang/include/clang/Makefile | 44 - .../tools/clang/include/clang/Parse/Makefile | 13 - .../tools/clang/include/clang/Sema/Makefile | 27 - .../include/clang/Serialization/Makefile | 19 - cpp/llvm/tools/clang/lib/ARCMigrate/Makefile | 18 - cpp/llvm/tools/clang/lib/AST/Makefile | 18 - cpp/llvm/tools/clang/lib/Analysis/Makefile | 18 - cpp/llvm/tools/clang/lib/Basic/Makefile | 40 - cpp/llvm/tools/clang/lib/CodeGen/Makefile | 19 - cpp/llvm/tools/clang/lib/Driver/Makefile | 13 - cpp/llvm/tools/clang/lib/Edit/Makefile | 14 - cpp/llvm/tools/clang/lib/Frontend/Makefile | 14 - .../tools/clang/lib/FrontendTool/Makefile | 13 - cpp/llvm/tools/clang/lib/Headers/Makefile | 64 - cpp/llvm/tools/clang/lib/Lex/Makefile | 24 - cpp/llvm/tools/clang/lib/Makefile | 16 - cpp/llvm/tools/clang/lib/Parse/Makefile | 18 - cpp/llvm/tools/clang/lib/Rewrite/Makefile | 18 - cpp/llvm/tools/clang/lib/Sema/Makefile | 19 - .../tools/clang/lib/Serialization/Makefile | 19 - .../lib/StaticAnalyzer/Checkers/Makefile | 24 - .../clang/lib/StaticAnalyzer/Core/Makefile | 17 - .../lib/StaticAnalyzer/Frontend/Makefile | 19 - .../tools/clang/lib/StaticAnalyzer/Makefile | 18 - cpp/llvm/tools/clang/lib/Tooling/Makefile | 13 - cpp/llvm/tools/clang/runtime/Makefile | 22 - .../tools/clang/runtime/compiler-rt/Makefile | 163 - cpp/llvm/tools/clang/runtime/libcxx/Makefile | 31 - .../over.best.ics/over.ics.user/p3-0x.cpp | 14 - .../temp.class/temp.mem.class/p1.cpp | 27 - .../temp.class/temp.mem.enum/p1.cpp | 152 - .../temp.class/temp.mem.func/p1-retmem.cpp | 28 - .../temp.class/temp.mem.func/p1.cpp | 100 - .../temp.class/temp.mem.func/p1inst.cpp | 17 - .../temp.class/temp.mem.func/pr5056.cpp | 17 - .../temp.class/temp.static/p1-inst.cpp | 28 - .../temp.decls/temp.class/temp.static/p1.cpp | 26 - .../Inputs/basic_freebsd64_tree/lib/.keep | 0 .../Inputs/basic_freebsd64_tree/usr/lib/.keep | 0 .../basic_freebsd64_tree/usr/lib/crt1.o | 0 .../basic_freebsd64_tree/usr/lib32/.keep | 0 .../Inputs/basic_freebsd_tree/lib/.keep | 0 .../Inputs/basic_freebsd_tree/usr/lib/.keep | 0 .../Inputs/basic_freebsd_tree/usr/lib/crt1.o | 0 .../Inputs/basic_freebsd_tree/usr/lib32/.keep | 0 .../Driver/Inputs/basic_linux_tree/lib/.keep | 0 .../usr/i386-unknown-linux/lib/.keep | 0 .../Inputs/basic_linux_tree/usr/lib/.keep | 0 .../gcc/i386-unknown-linux/4.6.0/crtbegin.o | 0 .../gcc/x86_64-unknown-linux/4.6.0/crtbegin.o | 0 .../usr/x86_64-unknown-linux/lib/.keep | 0 .../Inputs/debian_multiarch_tree/lib/.keep | 0 .../lib/i386-linux-gnu/.keep | 0 .../lib/powerpc-linux-gnu/.keep | 0 .../lib/powerpc64-linux-gnu/.keep | 0 .../lib/x86_64-linux-gnu/.keep | 0 .../debian_multiarch_tree/usr/include/.keep | 0 .../usr/include/c++/4.5/.keep | 0 .../usr/include/c++/4.5/backward/.keep | 0 .../usr/include/c++/4.5/i686-linux-gnu/.keep | 0 .../include/c++/4.5/powerpc-linux-gnu/.keep | 0 .../include/c++/4.5/powerpc64-linux-gnu/.keep | 0 .../include/c++/4.5/x86_64-linux-gnu/.keep | 0 .../usr/include/i386-linux-gnu/.keep | 0 .../usr/include/powerpc-linux-gnu/.keep | 0 .../usr/include/powerpc64-linux-gnu/.keep | 0 .../usr/include/x86_64-linux-gnu/.keep | 0 .../debian_multiarch_tree/usr/lib/.keep | 0 .../usr/lib/gcc/i686-linux-gnu/4.5/crtbegin.o | 0 .../lib/gcc/powerpc-linux-gnu/4.5/crtbegin.o | 0 .../gcc/powerpc64-linux-gnu/4.5/crtbegin.o | 0 .../lib/gcc/x86_64-linux-gnu/4.5/crtbegin.o | 0 .../usr/lib/i386-linux-gnu/.keep | 0 .../usr/lib/powerpc-linux-gnu/.keep | 0 .../usr/lib/powerpc64-linux-gnu/.keep | 0 .../usr/lib/x86_64-linux-gnu/.keep | 0 .../Driver/Inputs/fake_install_tree/bin/.keep | 0 .../gcc/i386-unknown-linux/4.7.0/crtbegin.o | 0 .../gcc/x86_64-unknown-linux/4.5.0/crtbegin.o | 0 .../Inputs/gcc_version_parsing1/bin/.keep | 0 .../gcc/i386-unknown-linux/4.6.99/crtbegin.o | 0 .../lib/gcc/i386-unknown-linux/4.6/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.0/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.1/crtbegin.o | 0 .../lib/gcc/i386-unknown-linux/4.7/crtbegin.o | 0 .../Inputs/gcc_version_parsing2/bin/.keep | 0 .../gcc/i386-unknown-linux/4.6.99/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.6.x/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.0/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.1/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.x/crtbegin.o | 0 .../Inputs/gcc_version_parsing3/bin/.keep | 0 .../gcc/i386-unknown-linux/4.7.98/crtbegin.o | 0 .../i386-unknown-linux/4.7.99-rc5/crtbegin.o | 0 .../Inputs/gcc_version_parsing4/bin/.keep | 0 .../gcc/i386-unknown-linux/4.7.98/crtbegin.o | 0 .../i386-unknown-linux/4.7.99-rc5/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.7.99/crtbegin.o | 0 .../Inputs/multiarch_freebsd64_tree/lib/.keep | 0 .../multiarch_freebsd64_tree/usr/lib/.keep | 0 .../multiarch_freebsd64_tree/usr/lib/crt1.o | 0 .../multiarch_freebsd64_tree/usr/lib32/.keep | 0 .../multiarch_freebsd64_tree/usr/lib32/crt1.o | 0 .../multilib_32bit_linux_tree/lib/.keep | 0 .../multilib_32bit_linux_tree/lib32/.keep | 0 .../multilib_32bit_linux_tree/lib64/.keep | 0 .../usr/i386-unknown-linux/lib/.keep | 0 .../usr/i386-unknown-linux/lib32/.keep | 0 .../usr/i386-unknown-linux/lib64/.keep | 0 .../multilib_32bit_linux_tree/usr/lib/.keep | 0 .../i386-unknown-linux/4.6.0/64/crtbegin.o | 0 .../gcc/i386-unknown-linux/4.6.0/crtbegin.o | 0 .../multilib_32bit_linux_tree/usr/lib32/.keep | 0 .../multilib_32bit_linux_tree/usr/lib64/.keep | 0 .../multilib_64bit_linux_tree/lib/.keep | 0 .../multilib_64bit_linux_tree/lib32/.keep | 0 .../multilib_64bit_linux_tree/lib64/.keep | 0 .../multilib_64bit_linux_tree/usr/lib/.keep | 0 .../x86_64-unknown-linux/4.6.0/32/crtbegin.o | 0 .../gcc/x86_64-unknown-linux/4.6.0/crtbegin.o | 0 .../multilib_64bit_linux_tree/usr/lib32/.keep | 0 .../multilib_64bit_linux_tree/usr/lib64/.keep | 0 .../usr/x86_64-unknown-linux/lib/.keep | 0 .../usr/x86_64-unknown-linux/lib32/.keep | 0 .../usr/x86_64-unknown-linux/lib64/.keep | 0 .../Inputs/suse_10.3_ppc64_tree/lib/.keep | 0 .../Inputs/suse_10.3_ppc64_tree/lib64/.keep | 0 .../powerpc64-suse-linux/4.1.2/64/crtbegin.o | 0 .../gcc/powerpc64-suse-linux/4.1.2/crtbegin.o | 0 .../suse_10.3_ppc64_tree/usr/lib64/.keep | 0 .../ubuntu_11.04_multiarch_tree/lib/.keep | 0 .../lib/i386-linux-gnu/.keep | 0 .../usr/include/.keep | 0 .../usr/include/c++/4.5/.keep | 0 .../usr/include/c++/4.5/backward/.keep | 0 .../usr/include/c++/4.5/i686-linux-gnu/.keep | 0 .../usr/include/i386-linux-gnu/.keep | 0 .../ubuntu_11.04_multiarch_tree/usr/lib/.keep | 0 .../usr/lib/i386-linux-gnu/.keep | 0 .../gcc/i686-linux-gnu/4.5/crtbegin.o | 0 cpp/llvm/tools/clang/test/Makefile | 71 - .../TestFramework.framework/.system_framework | 0 cpp/llvm/tools/clang/tools/Makefile | 16 - .../tools/clang/tools/arcmt-test/Makefile | 24 - .../tools/clang/tools/c-arcmt-test/Makefile | 25 - .../tools/clang/tools/c-index-test/Makefile | 25 - .../tools/clang/tools/clang-check/Makefile | 24 - cpp/llvm/tools/clang/tools/diagtool/Makefile | 24 - cpp/llvm/tools/clang/tools/driver/Makefile | 69 - cpp/llvm/tools/clang/tools/libclang/Makefile | 53 - cpp/llvm/tools/clang/unittests/Basic/Makefile | 15 - .../tools/clang/unittests/Frontend/Makefile | 19 - cpp/llvm/tools/clang/unittests/Lex/Makefile | 15 - cpp/llvm/tools/clang/unittests/Makefile | 28 - .../tools/clang/unittests/Tooling/Makefile | 17 - .../tools/clang/utils/ABITest/layout/Makefile | 68 - .../utils/ABITest/return-types-32/Makefile | 7 - .../utils/ABITest/return-types-64/Makefile | 7 - .../utils/ABITest/single-args-32/Makefile | 7 - .../utils/ABITest/single-args-64/Makefile | 13 - cpp/llvm/tools/clang/utils/TableGen/Makefile | 19 - .../tools/clang/utils/VtableTest/Makefile | 24 - cpp/llvm/tools/clang/www/OpenProjects.html | 114 - cpp/llvm/tools/clang/www/UniversalDriver.html | 87 - .../tools/clang/www/analyzer/annotations.html | 602 -- .../clang/www/analyzer/available_checks.html | 147 - .../www/analyzer/checker_dev_manual.html | 346 - cpp/llvm/tools/clang/www/analyzer/content.css | 79 - .../tools/clang/www/analyzer/dev_cxx.html | 54 - .../tools/clang/www/analyzer/filing_bugs.html | 62 - .../www/analyzer/images/analyzer_html.png | Bin 63091 -> 0 bytes .../www/analyzer/images/analyzer_xcode.png | Bin 87697 -> 0 bytes .../images/example_attribute_nonnull.png | Bin 25028 -> 0 bytes .../images/example_cf_returns_retained.png | Bin 43528 -> 0 bytes .../images/example_cf_returns_retained_gc.png | Bin 46925 -> 0 bytes .../images/example_ns_returns_retained.png | Bin 40406 -> 0 bytes .../www/analyzer/images/scan_build_cmd.png | Bin 29669 -> 0 bytes .../clang/www/analyzer/images/tree/bullet.gif | Bin 64 -> 0 bytes .../clang/www/analyzer/images/tree/minus.gif | Bin 79 -> 0 bytes .../clang/www/analyzer/images/tree/plus.gif | Bin 83 -> 0 bytes cpp/llvm/tools/clang/www/analyzer/index.html | 224 - .../clang/www/analyzer/installation.html | 114 - .../www/analyzer/latest_checker.html.incl | 1 - cpp/llvm/tools/clang/www/analyzer/menu.css | 52 - .../tools/clang/www/analyzer/menu.html.incl | 41 - .../clang/www/analyzer/release_notes.html | 188 - .../tools/clang/www/analyzer/scan-build.html | 344 - .../clang/www/analyzer/scripts/dbtree.js | 1 - .../tools/clang/www/analyzer/scripts/menu.js | 17 - cpp/llvm/tools/clang/www/analyzer/xcode.html | 143 - cpp/llvm/tools/clang/www/builtins.py | 160 - cpp/llvm/tools/clang/www/carbon-compile.png | Bin 23702 -> 0 bytes .../clang/www/clang_video-05-25-2007.html | 27 - .../clang/www/clang_video-07-25-2007.html | 30 - cpp/llvm/tools/clang/www/comparison.html | 189 - cpp/llvm/tools/clang/www/compatibility.html | 869 -- cpp/llvm/tools/clang/www/content.css | 30 - .../tools/clang/www/cxx_compatibility.html | 27 - cpp/llvm/tools/clang/www/cxx_status.html | 381 - cpp/llvm/tools/clang/www/demo/DemoInfo.html | 83 - cpp/llvm/tools/clang/www/demo/cathead.png | Bin 21602 -> 0 bytes cpp/llvm/tools/clang/www/demo/index.cgi | 461 - cpp/llvm/tools/clang/www/demo/syntax.css | 4 - .../clang/www/demo/what is this directory.txt | 15 - cpp/llvm/tools/clang/www/diagnostics.html | 374 - cpp/llvm/tools/clang/www/favicon.ico | Bin 1150 -> 0 bytes cpp/llvm/tools/clang/www/feature-compile1.png | Bin 91247 -> 0 bytes cpp/llvm/tools/clang/www/feature-compile2.png | Bin 140963 -> 0 bytes cpp/llvm/tools/clang/www/feature-memory1.png | Bin 92680 -> 0 bytes cpp/llvm/tools/clang/www/features.html | 426 - cpp/llvm/tools/clang/www/get_involved.html | 90 - cpp/llvm/tools/clang/www/get_started.html | 306 - cpp/llvm/tools/clang/www/hacking.html | 326 - cpp/llvm/tools/clang/www/index.html | 118 - .../clang/www/libstdc++4.4-clang0x.patch | 608 -- .../clang/www/libstdc++4.7-clang11.patch | 13 - cpp/llvm/tools/clang/www/menu.css | 39 - cpp/llvm/tools/clang/www/menu.html.incl | 61 - .../clang/www/performance-2008-10-31.html | 132 - .../clang/www/performance-2009-03-02.html | 110 - cpp/llvm/tools/clang/www/performance.html | 104 - cpp/llvm/tools/clang/www/related.html | 55 - cpp/llvm/tools/clang/www/robots.txt | 2 - .../www/timing-data/2008-10-31/176.gcc-01.txt | 135 - .../www/timing-data/2008-10-31/176.gcc-02.txt | 135 - .../www/timing-data/2008-10-31/176.gcc.png | Bin 20395 -> 0 bytes .../www/timing-data/2008-10-31/sketch-01.txt | 187 - .../www/timing-data/2008-10-31/sketch-02.txt | 187 - .../www/timing-data/2008-10-31/sketch.png | Bin 23482 -> 0 bytes .../www/timing-data/2009-03-02/176.gcc.pdf | Bin 34547 -> 0 bytes .../www/timing-data/2009-03-02/176.gcc.png | Bin 77003 -> 0 bytes .../www/timing-data/2009-03-02/176.gcc.txt | 1120 --- .../www/timing-data/2009-03-02/sketch.pdf | Bin 36086 -> 0 bytes .../www/timing-data/2009-03-02/sketch.png | Bin 78278 -> 0 bytes .../www/timing-data/2009-03-02/sketch.txt | 2368 ----- .../www/timing-data/2009-06-26/176.gcc.pdf | Bin 33680 -> 0 bytes .../www/timing-data/2009-06-26/176.gcc.png | Bin 61190 -> 0 bytes .../www/timing-data/2009-06-26/176.gcc.txt | 699 -- .../www/timing-data/2009-06-26/sketch.pdf | Bin 34528 -> 0 bytes .../www/timing-data/2009-06-26/sketch.png | Bin 62222 -> 0 bytes .../www/timing-data/2009-06-26/sketch.txt | 803 -- cpp/llvm/tools/gold/Makefile | 29 - cpp/llvm/tools/llc/Makefile | 15 - cpp/llvm/tools/lli/Makefile | 29 - cpp/llvm/tools/llvm-ar/Makefile | 18 - cpp/llvm/tools/llvm-as/Makefile | 17 - cpp/llvm/tools/llvm-bcanalyzer/Makefile | 17 - cpp/llvm/tools/llvm-config/Makefile | 59 - cpp/llvm/tools/llvm-cov/Makefile | 17 - cpp/llvm/tools/llvm-diff/Makefile | 17 - cpp/llvm/tools/llvm-dis/Makefile | 17 - cpp/llvm/tools/llvm-dwarfdump/Makefile | 17 - cpp/llvm/tools/llvm-extract/Makefile | 17 - cpp/llvm/tools/llvm-ld/Makefile | 14 - cpp/llvm/tools/llvm-link/Makefile | 17 - cpp/llvm/tools/llvm-mc/Makefile | 17 - cpp/llvm/tools/llvm-nm/Makefile | 17 - cpp/llvm/tools/llvm-objdump/Makefile | 17 - cpp/llvm/tools/llvm-prof/Makefile | 17 - cpp/llvm/tools/llvm-ranlib/Makefile | 18 - cpp/llvm/tools/llvm-readobj/Makefile | 18 - cpp/llvm/tools/llvm-rtdyld/Makefile | 17 - cpp/llvm/tools/llvm-shlib/Makefile | 126 - cpp/llvm/tools/llvm-size/Makefile | 17 - cpp/llvm/tools/llvm-stress/Makefile | 18 - cpp/llvm/tools/llvm-stub/Makefile | 15 - cpp/llvm/tools/lto/Makefile | 52 - cpp/llvm/tools/macho-dump/Makefile | 17 - cpp/llvm/tools/opt/Makefile | 14 - cpp/llvm/unittests/ADT/Makefile | 23 - cpp/llvm/unittests/Analysis/Makefile | 15 - cpp/llvm/unittests/Bitcode/Makefile | 15 - .../unittests/ExecutionEngine/JIT/Makefile | 42 - cpp/llvm/unittests/ExecutionEngine/Makefile | 16 - cpp/llvm/unittests/Makefile | 17 - cpp/llvm/unittests/Support/Makefile | 15 - cpp/llvm/unittests/Transforms/Makefile | 17 - cpp/llvm/unittests/Transforms/Utils/Makefile | 15 - cpp/llvm/unittests/VMCore/Makefile | 15 - cpp/llvm/utils/FileCheck/Makefile | 21 - cpp/llvm/utils/FileUpdate/Makefile | 21 - cpp/llvm/utils/Makefile | 19 - cpp/llvm/utils/PerfectShuffle/Makefile | 18 - cpp/llvm/utils/TableGen/Makefile | 20 - cpp/llvm/utils/count/Makefile | 20 - cpp/llvm/utils/fpcmp/Makefile | 16 - .../LLVM.OutOfTree/obj/test/Foo/lit.local.cfg | 0 .../LLVM.OutOfTree/obj/test/lit.site.cfg | 11 - .../LLVM.OutOfTree/obj/test/site.exp | 10 - cpp/llvm/utils/llvm-lit/Makefile | 22 - cpp/llvm/utils/not/Makefile | 21 - cpp/llvm/utils/unittest/Makefile | 13 - cpp/llvm/utils/unittest/UnitTestMain/Makefile | 32 - cpp/llvm/utils/unittest/googletest/Makefile | 39 - cpp/llvm/utils/yaml-bench/Makefile | 20 - cpp/ycm/tests/gmock/gtest/make/Makefile | 80 - .../tests/gmock/gtest/scripts/test/Makefile | 59 - cpp/ycm/tests/gmock/make/Makefile | 98 - 578 files changed, 96931 deletions(-) delete mode 100644 cpp/llvm/Makefile delete mode 100644 cpp/llvm/bindings/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/analysis/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/bitreader/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/bitwriter/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/executionengine/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/llvm/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/target/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/transforms/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/transforms/ipo/Makefile delete mode 100644 cpp/llvm/bindings/ocaml/transforms/scalar/Makefile delete mode 100644 cpp/llvm/docs/AliasAnalysis.html delete mode 100644 cpp/llvm/docs/Atomics.html delete mode 100644 cpp/llvm/docs/BitCodeFormat.html delete mode 100644 cpp/llvm/docs/BranchWeightMetadata.html delete mode 100644 cpp/llvm/docs/Bugpoint.html delete mode 100644 cpp/llvm/docs/CMake.html delete mode 100644 cpp/llvm/docs/CodeGenerator.html delete mode 100644 cpp/llvm/docs/CodingStandards.html delete mode 100644 cpp/llvm/docs/CommandGuide/FileCheck.pod delete mode 100644 cpp/llvm/docs/CommandGuide/Makefile delete mode 100644 cpp/llvm/docs/CommandGuide/bugpoint.pod delete mode 100644 cpp/llvm/docs/CommandGuide/html/manpage.css delete mode 100644 cpp/llvm/docs/CommandGuide/index.html delete mode 100644 cpp/llvm/docs/CommandGuide/lit.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llc.pod delete mode 100644 cpp/llvm/docs/CommandGuide/lli.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-ar.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-as.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-bcanalyzer.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-build.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-config.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-cov.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-diff.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-dis.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-extract.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-ld.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-link.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-nm.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-prof.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-ranlib.pod delete mode 100644 cpp/llvm/docs/CommandGuide/llvm-stress.pod delete mode 100644 cpp/llvm/docs/CommandGuide/manpage.css delete mode 100644 cpp/llvm/docs/CommandGuide/opt.pod delete mode 100644 cpp/llvm/docs/CommandGuide/tblgen.pod delete mode 100644 cpp/llvm/docs/CommandLine.html delete mode 100644 cpp/llvm/docs/CompilerWriterInfo.html delete mode 100644 cpp/llvm/docs/DebuggingJITedCode.html delete mode 100644 cpp/llvm/docs/DeveloperPolicy.html delete mode 100644 cpp/llvm/docs/ExceptionHandling.html delete mode 100644 cpp/llvm/docs/ExtendedIntegerResults.txt delete mode 100644 cpp/llvm/docs/ExtendingLLVM.html delete mode 100644 cpp/llvm/docs/FAQ.html delete mode 100644 cpp/llvm/docs/GCCFEBuildInstrs.html delete mode 100644 cpp/llvm/docs/GarbageCollection.html delete mode 100644 cpp/llvm/docs/GetElementPtr.html delete mode 100644 cpp/llvm/docs/GettingStarted.html delete mode 100644 cpp/llvm/docs/GettingStartedVS.html delete mode 100644 cpp/llvm/docs/GoldPlugin.html delete mode 100644 cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveComments.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2002-05-12-InstListChange.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt delete mode 100644 cpp/llvm/docs/HistoricalNotes/2007-OriginalClangReadme.txt delete mode 100644 cpp/llvm/docs/HowToAddABuilder.html delete mode 100644 cpp/llvm/docs/HowToReleaseLLVM.html delete mode 100644 cpp/llvm/docs/HowToSubmitABug.html delete mode 100644 cpp/llvm/docs/LLVMBuild.html delete mode 100644 cpp/llvm/docs/LangRef.html delete mode 100644 cpp/llvm/docs/Lexicon.html delete mode 100644 cpp/llvm/docs/LinkTimeOptimization.html delete mode 100644 cpp/llvm/docs/Makefile delete mode 100644 cpp/llvm/docs/MakefileGuide.html delete mode 100644 cpp/llvm/docs/Packaging.html delete mode 100644 cpp/llvm/docs/Passes.html delete mode 100644 cpp/llvm/docs/ProgrammersManual.html delete mode 100644 cpp/llvm/docs/Projects.html delete mode 100644 cpp/llvm/docs/ReleaseNotes.html delete mode 100644 cpp/llvm/docs/SegmentedStacks.html delete mode 100644 cpp/llvm/docs/SourceLevelDebugging.html delete mode 100644 cpp/llvm/docs/SystemLibrary.html delete mode 100644 cpp/llvm/docs/TableGenFundamentals.html delete mode 100644 cpp/llvm/docs/TestSuiteMakefileGuide.html delete mode 100644 cpp/llvm/docs/TestingGuide.html delete mode 100644 cpp/llvm/docs/WritingAnLLVMBackend.html delete mode 100644 cpp/llvm/docs/WritingAnLLVMPass.html delete mode 100644 cpp/llvm/docs/doxygen.cfg.in delete mode 100644 cpp/llvm/docs/doxygen.css delete mode 100644 cpp/llvm/docs/doxygen.footer delete mode 100644 cpp/llvm/docs/doxygen.header delete mode 100644 cpp/llvm/docs/doxygen.intro delete mode 100644 cpp/llvm/docs/img/Debugging.gif delete mode 100644 cpp/llvm/docs/img/libdeps.gif delete mode 100644 cpp/llvm/docs/img/lines.gif delete mode 100644 cpp/llvm/docs/img/objdeps.gif delete mode 100644 cpp/llvm/docs/img/venusflytrap.jpg delete mode 100644 cpp/llvm/docs/index.html delete mode 100644 cpp/llvm/docs/llvm.css delete mode 100644 cpp/llvm/docs/re_format.7 delete mode 100644 cpp/llvm/docs/tutorial/LangImpl1.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl2.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl3.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl4.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl5-cfg.png delete mode 100644 cpp/llvm/docs/tutorial/LangImpl5.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl6.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl7.html delete mode 100644 cpp/llvm/docs/tutorial/LangImpl8.html delete mode 100644 cpp/llvm/docs/tutorial/Makefile delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl1.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl2.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl3.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl4.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl5.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl6.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl7.html delete mode 100644 cpp/llvm/docs/tutorial/OCamlLangImpl8.html delete mode 100644 cpp/llvm/docs/tutorial/index.html delete mode 100644 cpp/llvm/examples/BrainF/Makefile delete mode 100644 cpp/llvm/examples/ExceptionDemo/Makefile delete mode 100644 cpp/llvm/examples/Fibonacci/Makefile delete mode 100644 cpp/llvm/examples/HowToUseJIT/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter2/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter3/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter4/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter5/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter6/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Chapter7/Makefile delete mode 100644 cpp/llvm/examples/Kaleidoscope/Makefile delete mode 100644 cpp/llvm/examples/Makefile delete mode 100644 cpp/llvm/examples/ModuleMaker/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter2/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter3/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter4/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter5/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter6/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Chapter7/Makefile delete mode 100644 cpp/llvm/examples/OCaml-Kaleidoscope/Makefile delete mode 100644 cpp/llvm/examples/ParallelJIT/Makefile delete mode 100644 cpp/llvm/lib/Analysis/IPA/Makefile delete mode 100644 cpp/llvm/lib/Analysis/Makefile delete mode 100644 cpp/llvm/lib/Archive/Makefile delete mode 100644 cpp/llvm/lib/AsmParser/Makefile delete mode 100644 cpp/llvm/lib/Bitcode/Makefile delete mode 100644 cpp/llvm/lib/Bitcode/Reader/Makefile delete mode 100644 cpp/llvm/lib/Bitcode/Writer/Makefile delete mode 100644 cpp/llvm/lib/CodeGen/AsmPrinter/Makefile delete mode 100644 cpp/llvm/lib/CodeGen/Makefile delete mode 100644 cpp/llvm/lib/CodeGen/SelectionDAG/Makefile delete mode 100644 cpp/llvm/lib/DebugInfo/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/IntelJITEvents/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/Interpreter/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/JIT/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/MCJIT/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/OProfileJIT/Makefile delete mode 100644 cpp/llvm/lib/ExecutionEngine/RuntimeDyld/Makefile delete mode 100644 cpp/llvm/lib/Linker/Makefile delete mode 100644 cpp/llvm/lib/MC/MCDisassembler/Makefile delete mode 100644 cpp/llvm/lib/MC/MCParser/Makefile delete mode 100644 cpp/llvm/lib/MC/Makefile delete mode 100644 cpp/llvm/lib/Makefile delete mode 100644 cpp/llvm/lib/Object/Makefile delete mode 100644 cpp/llvm/lib/Support/Makefile delete mode 100644 cpp/llvm/lib/TableGen/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/AsmParser/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/Disassembler/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/Makefile delete mode 100644 cpp/llvm/lib/Target/ARM/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/CellSPU/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/CellSPU/Makefile delete mode 100644 cpp/llvm/lib/Target/CellSPU/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/CppBackend/Makefile delete mode 100644 cpp/llvm/lib/Target/CppBackend/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/Hexagon/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/Hexagon/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/Hexagon/Makefile delete mode 100644 cpp/llvm/lib/Target/Hexagon/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/AsmParser/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/Disassembler/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/Makefile delete mode 100644 cpp/llvm/lib/Target/MBlaze/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/MSP430/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/MSP430/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/MSP430/Makefile delete mode 100644 cpp/llvm/lib/Target/MSP430/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/AsmParser/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/Disassembler/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/Makefile delete mode 100644 cpp/llvm/lib/Target/Mips/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/PTX/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/PTX/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/PTX/Makefile delete mode 100644 cpp/llvm/lib/Target/PTX/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/PowerPC/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/PowerPC/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/PowerPC/Makefile delete mode 100644 cpp/llvm/lib/Target/PowerPC/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/Sparc/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/Sparc/Makefile delete mode 100644 cpp/llvm/lib/Target/Sparc/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/AsmParser/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/Disassembler/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/InstPrinter/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Target/X86/Utils/Makefile delete mode 100644 cpp/llvm/lib/Target/XCore/MCTargetDesc/Makefile delete mode 100644 cpp/llvm/lib/Target/XCore/Makefile delete mode 100644 cpp/llvm/lib/Target/XCore/TargetInfo/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Hello/Makefile delete mode 100644 cpp/llvm/lib/Transforms/IPO/Makefile delete mode 100644 cpp/llvm/lib/Transforms/InstCombine/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Instrumentation/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Scalar/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Utils/Makefile delete mode 100644 cpp/llvm/lib/Transforms/Vectorize/Makefile delete mode 100644 cpp/llvm/lib/VMCore/Makefile delete mode 100644 cpp/llvm/projects/sample/Makefile delete mode 100644 cpp/llvm/projects/sample/lib/Makefile delete mode 100644 cpp/llvm/projects/sample/lib/sample/Makefile delete mode 100644 cpp/llvm/projects/sample/tools/Makefile delete mode 100644 cpp/llvm/projects/sample/tools/sample/Makefile delete mode 100644 cpp/llvm/runtime/Makefile delete mode 100644 cpp/llvm/runtime/libprofile/Makefile delete mode 100644 cpp/llvm/test/Archive/GNU.a delete mode 100644 cpp/llvm/test/Archive/IsNAN.o delete mode 100644 cpp/llvm/test/Archive/MacOSX.a delete mode 100644 cpp/llvm/test/Archive/SVR4.a delete mode 100644 cpp/llvm/test/Archive/xpg4.a delete mode 100644 cpp/llvm/test/CodeGen/Generic/Makefile delete mode 100644 cpp/llvm/test/Makefile delete mode 100644 cpp/llvm/tools/Makefile delete mode 100644 cpp/llvm/tools/bugpoint-passes/Makefile delete mode 100644 cpp/llvm/tools/bugpoint/Makefile delete mode 100644 cpp/llvm/tools/clang/Makefile delete mode 100644 cpp/llvm/tools/clang/docs/Makefile delete mode 100644 cpp/llvm/tools/clang/docs/tools/Makefile delete mode 100644 cpp/llvm/tools/clang/examples/Makefile delete mode 100644 cpp/llvm/tools/clang/examples/PrintFunctionNames/Makefile delete mode 100644 cpp/llvm/tools/clang/examples/analyzer-plugin/Makefile delete mode 100644 cpp/llvm/tools/clang/examples/clang-interpreter/Makefile delete mode 100644 cpp/llvm/tools/clang/include/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang-c/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/AST/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Basic/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Driver/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Lex/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Parse/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Sema/Makefile delete mode 100644 cpp/llvm/tools/clang/include/clang/Serialization/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/ARCMigrate/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/AST/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Analysis/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Basic/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/CodeGen/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Driver/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Edit/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Frontend/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/FrontendTool/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Headers/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Lex/Makefile delete mode 100755 cpp/llvm/tools/clang/lib/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Parse/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Rewrite/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Sema/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Serialization/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/StaticAnalyzer/Checkers/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/StaticAnalyzer/Core/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/StaticAnalyzer/Frontend/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/StaticAnalyzer/Makefile delete mode 100644 cpp/llvm/tools/clang/lib/Tooling/Makefile delete mode 100644 cpp/llvm/tools/clang/runtime/Makefile delete mode 100644 cpp/llvm/tools/clang/runtime/compiler-rt/Makefile delete mode 100644 cpp/llvm/tools/clang/runtime/libcxx/Makefile delete mode 100644 cpp/llvm/tools/clang/test/CXX/over/over.match/over.match.best/over.best.ics/over.ics.user/p3-0x.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.class/p1.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.enum/p1.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1-retmem.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1inst.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/pr5056.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.static/p1-inst.cpp delete mode 100644 cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.static/p1.cpp delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd64_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd64_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd64_tree/usr/lib/crt1.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd64_tree/usr/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd_tree/usr/lib/crt1.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_freebsd_tree/usr/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/usr/i386-unknown-linux/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/usr/lib/gcc/i386-unknown-linux/4.6.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/usr/lib/gcc/x86_64-unknown-linux/4.6.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/basic_linux_tree/usr/x86_64-unknown-linux/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/lib/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/lib/powerpc-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/lib/powerpc64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/lib/x86_64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/backward/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/i686-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/powerpc-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/powerpc64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/c++/4.5/x86_64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/powerpc-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/powerpc64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/include/x86_64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/gcc/i686-linux-gnu/4.5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/gcc/powerpc-linux-gnu/4.5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/gcc/powerpc64-linux-gnu/4.5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/gcc/x86_64-linux-gnu/4.5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/powerpc-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/powerpc64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/debian_multiarch_tree/usr/lib/x86_64-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/fake_install_tree/bin/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/fake_install_tree/lib/gcc/i386-unknown-linux/4.7.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/fake_install_tree/lib/gcc/x86_64-unknown-linux/4.5.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/bin/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/lib/gcc/i386-unknown-linux/4.6.99/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/lib/gcc/i386-unknown-linux/4.6/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/lib/gcc/i386-unknown-linux/4.7.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/lib/gcc/i386-unknown-linux/4.7.1/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing1/lib/gcc/i386-unknown-linux/4.7/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/bin/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/lib/gcc/i386-unknown-linux/4.6.99/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/lib/gcc/i386-unknown-linux/4.6.x/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/lib/gcc/i386-unknown-linux/4.7.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/lib/gcc/i386-unknown-linux/4.7.1/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing2/lib/gcc/i386-unknown-linux/4.7.x/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing3/bin/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing3/lib/gcc/i386-unknown-linux/4.7.98/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing3/lib/gcc/i386-unknown-linux/4.7.99-rc5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing4/bin/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing4/lib/gcc/i386-unknown-linux/4.7.98/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing4/lib/gcc/i386-unknown-linux/4.7.99-rc5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/gcc_version_parsing4/lib/gcc/i386-unknown-linux/4.7.99/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multiarch_freebsd64_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multiarch_freebsd64_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multiarch_freebsd64_tree/usr/lib/crt1.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multiarch_freebsd64_tree/usr/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multiarch_freebsd64_tree/usr/lib32/crt1.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/lib/gcc/i386-unknown-linux/4.6.0/64/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/lib/gcc/i386-unknown-linux/4.6.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/lib/gcc/x86_64-unknown-linux/4.6.0/32/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/lib/gcc/x86_64-unknown-linux/4.6.0/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/lib32/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/suse_10.3_ppc64_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/suse_10.3_ppc64_tree/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/suse_10.3_ppc64_tree/usr/lib/gcc/powerpc64-suse-linux/4.1.2/64/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/suse_10.3_ppc64_tree/usr/lib/gcc/powerpc64-suse-linux/4.1.2/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/suse_10.3_ppc64_tree/usr/lib64/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/lib/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/include/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/include/c++/4.5/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/include/c++/4.5/backward/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/include/c++/4.5/i686-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/include/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/lib/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/lib/i386-linux-gnu/.keep delete mode 100644 cpp/llvm/tools/clang/test/Driver/Inputs/ubuntu_11.04_multiarch_tree/usr/lib/i386-linux-gnu/gcc/i686-linux-gnu/4.5/crtbegin.o delete mode 100644 cpp/llvm/tools/clang/test/Makefile delete mode 100644 cpp/llvm/tools/clang/test/Preprocessor/Inputs/TestFramework.framework/.system_framework delete mode 100644 cpp/llvm/tools/clang/tools/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/arcmt-test/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/c-arcmt-test/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/c-index-test/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/clang-check/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/diagtool/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/driver/Makefile delete mode 100644 cpp/llvm/tools/clang/tools/libclang/Makefile delete mode 100644 cpp/llvm/tools/clang/unittests/Basic/Makefile delete mode 100644 cpp/llvm/tools/clang/unittests/Frontend/Makefile delete mode 100644 cpp/llvm/tools/clang/unittests/Lex/Makefile delete mode 100644 cpp/llvm/tools/clang/unittests/Makefile delete mode 100644 cpp/llvm/tools/clang/unittests/Tooling/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/ABITest/layout/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/ABITest/return-types-32/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/ABITest/return-types-64/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/ABITest/single-args-32/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/ABITest/single-args-64/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/TableGen/Makefile delete mode 100644 cpp/llvm/tools/clang/utils/VtableTest/Makefile delete mode 100644 cpp/llvm/tools/clang/www/OpenProjects.html delete mode 100644 cpp/llvm/tools/clang/www/UniversalDriver.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/annotations.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/available_checks.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/checker_dev_manual.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/content.css delete mode 100644 cpp/llvm/tools/clang/www/analyzer/dev_cxx.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/filing_bugs.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/analyzer_html.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/analyzer_xcode.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/example_attribute_nonnull.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/example_cf_returns_retained.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/example_cf_returns_retained_gc.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/example_ns_returns_retained.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/scan_build_cmd.png delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/tree/bullet.gif delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/tree/minus.gif delete mode 100644 cpp/llvm/tools/clang/www/analyzer/images/tree/plus.gif delete mode 100644 cpp/llvm/tools/clang/www/analyzer/index.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/installation.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/latest_checker.html.incl delete mode 100644 cpp/llvm/tools/clang/www/analyzer/menu.css delete mode 100644 cpp/llvm/tools/clang/www/analyzer/menu.html.incl delete mode 100644 cpp/llvm/tools/clang/www/analyzer/release_notes.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/scan-build.html delete mode 100644 cpp/llvm/tools/clang/www/analyzer/scripts/dbtree.js delete mode 100644 cpp/llvm/tools/clang/www/analyzer/scripts/menu.js delete mode 100644 cpp/llvm/tools/clang/www/analyzer/xcode.html delete mode 100755 cpp/llvm/tools/clang/www/builtins.py delete mode 100644 cpp/llvm/tools/clang/www/carbon-compile.png delete mode 100644 cpp/llvm/tools/clang/www/clang_video-05-25-2007.html delete mode 100644 cpp/llvm/tools/clang/www/clang_video-07-25-2007.html delete mode 100644 cpp/llvm/tools/clang/www/comparison.html delete mode 100644 cpp/llvm/tools/clang/www/compatibility.html delete mode 100644 cpp/llvm/tools/clang/www/content.css delete mode 100644 cpp/llvm/tools/clang/www/cxx_compatibility.html delete mode 100644 cpp/llvm/tools/clang/www/cxx_status.html delete mode 100644 cpp/llvm/tools/clang/www/demo/DemoInfo.html delete mode 100644 cpp/llvm/tools/clang/www/demo/cathead.png delete mode 100644 cpp/llvm/tools/clang/www/demo/index.cgi delete mode 100644 cpp/llvm/tools/clang/www/demo/syntax.css delete mode 100644 cpp/llvm/tools/clang/www/demo/what is this directory.txt delete mode 100644 cpp/llvm/tools/clang/www/diagnostics.html delete mode 100644 cpp/llvm/tools/clang/www/favicon.ico delete mode 100644 cpp/llvm/tools/clang/www/feature-compile1.png delete mode 100644 cpp/llvm/tools/clang/www/feature-compile2.png delete mode 100644 cpp/llvm/tools/clang/www/feature-memory1.png delete mode 100644 cpp/llvm/tools/clang/www/features.html delete mode 100644 cpp/llvm/tools/clang/www/get_involved.html delete mode 100644 cpp/llvm/tools/clang/www/get_started.html delete mode 100644 cpp/llvm/tools/clang/www/hacking.html delete mode 100644 cpp/llvm/tools/clang/www/index.html delete mode 100644 cpp/llvm/tools/clang/www/libstdc++4.4-clang0x.patch delete mode 100644 cpp/llvm/tools/clang/www/libstdc++4.7-clang11.patch delete mode 100644 cpp/llvm/tools/clang/www/menu.css delete mode 100644 cpp/llvm/tools/clang/www/menu.html.incl delete mode 100644 cpp/llvm/tools/clang/www/performance-2008-10-31.html delete mode 100644 cpp/llvm/tools/clang/www/performance-2009-03-02.html delete mode 100644 cpp/llvm/tools/clang/www/performance.html delete mode 100644 cpp/llvm/tools/clang/www/related.html delete mode 100644 cpp/llvm/tools/clang/www/robots.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/176.gcc-01.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/176.gcc-02.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/176.gcc.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/sketch-01.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/sketch-02.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2008-10-31/sketch.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/176.gcc.pdf delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/176.gcc.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/176.gcc.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/sketch.pdf delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/sketch.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-03-02/sketch.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/176.gcc.pdf delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/176.gcc.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/176.gcc.txt delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/sketch.pdf delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/sketch.png delete mode 100644 cpp/llvm/tools/clang/www/timing-data/2009-06-26/sketch.txt delete mode 100644 cpp/llvm/tools/gold/Makefile delete mode 100644 cpp/llvm/tools/llc/Makefile delete mode 100644 cpp/llvm/tools/lli/Makefile delete mode 100644 cpp/llvm/tools/llvm-ar/Makefile delete mode 100644 cpp/llvm/tools/llvm-as/Makefile delete mode 100644 cpp/llvm/tools/llvm-bcanalyzer/Makefile delete mode 100644 cpp/llvm/tools/llvm-config/Makefile delete mode 100644 cpp/llvm/tools/llvm-cov/Makefile delete mode 100644 cpp/llvm/tools/llvm-diff/Makefile delete mode 100644 cpp/llvm/tools/llvm-dis/Makefile delete mode 100644 cpp/llvm/tools/llvm-dwarfdump/Makefile delete mode 100644 cpp/llvm/tools/llvm-extract/Makefile delete mode 100644 cpp/llvm/tools/llvm-ld/Makefile delete mode 100644 cpp/llvm/tools/llvm-link/Makefile delete mode 100644 cpp/llvm/tools/llvm-mc/Makefile delete mode 100644 cpp/llvm/tools/llvm-nm/Makefile delete mode 100644 cpp/llvm/tools/llvm-objdump/Makefile delete mode 100644 cpp/llvm/tools/llvm-prof/Makefile delete mode 100644 cpp/llvm/tools/llvm-ranlib/Makefile delete mode 100644 cpp/llvm/tools/llvm-readobj/Makefile delete mode 100644 cpp/llvm/tools/llvm-rtdyld/Makefile delete mode 100644 cpp/llvm/tools/llvm-shlib/Makefile delete mode 100644 cpp/llvm/tools/llvm-size/Makefile delete mode 100644 cpp/llvm/tools/llvm-stress/Makefile delete mode 100644 cpp/llvm/tools/llvm-stub/Makefile delete mode 100644 cpp/llvm/tools/lto/Makefile delete mode 100644 cpp/llvm/tools/macho-dump/Makefile delete mode 100644 cpp/llvm/tools/opt/Makefile delete mode 100644 cpp/llvm/unittests/ADT/Makefile delete mode 100644 cpp/llvm/unittests/Analysis/Makefile delete mode 100644 cpp/llvm/unittests/Bitcode/Makefile delete mode 100644 cpp/llvm/unittests/ExecutionEngine/JIT/Makefile delete mode 100644 cpp/llvm/unittests/ExecutionEngine/Makefile delete mode 100644 cpp/llvm/unittests/Makefile delete mode 100644 cpp/llvm/unittests/Support/Makefile delete mode 100644 cpp/llvm/unittests/Transforms/Makefile delete mode 100644 cpp/llvm/unittests/Transforms/Utils/Makefile delete mode 100644 cpp/llvm/unittests/VMCore/Makefile delete mode 100644 cpp/llvm/utils/FileCheck/Makefile delete mode 100644 cpp/llvm/utils/FileUpdate/Makefile delete mode 100644 cpp/llvm/utils/Makefile delete mode 100644 cpp/llvm/utils/PerfectShuffle/Makefile delete mode 100644 cpp/llvm/utils/TableGen/Makefile delete mode 100644 cpp/llvm/utils/count/Makefile delete mode 100644 cpp/llvm/utils/fpcmp/Makefile delete mode 100644 cpp/llvm/utils/lit/lit/ExampleTests/LLVM.OutOfTree/obj/test/Foo/lit.local.cfg delete mode 100644 cpp/llvm/utils/lit/lit/ExampleTests/LLVM.OutOfTree/obj/test/lit.site.cfg delete mode 100644 cpp/llvm/utils/lit/lit/ExampleTests/LLVM.OutOfTree/obj/test/site.exp delete mode 100644 cpp/llvm/utils/llvm-lit/Makefile delete mode 100644 cpp/llvm/utils/not/Makefile delete mode 100644 cpp/llvm/utils/unittest/Makefile delete mode 100644 cpp/llvm/utils/unittest/UnitTestMain/Makefile delete mode 100644 cpp/llvm/utils/unittest/googletest/Makefile delete mode 100644 cpp/llvm/utils/yaml-bench/Makefile delete mode 100644 cpp/ycm/tests/gmock/gtest/make/Makefile delete mode 100644 cpp/ycm/tests/gmock/gtest/scripts/test/Makefile delete mode 100644 cpp/ycm/tests/gmock/make/Makefile diff --git a/cpp/llvm/Makefile b/cpp/llvm/Makefile deleted file mode 100644 index ec24862a..00000000 --- a/cpp/llvm/Makefile +++ /dev/null @@ -1,268 +0,0 @@ -#===- ./Makefile -------------------------------------------*- Makefile -*--===# -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -#===------------------------------------------------------------------------===# - -LEVEL := . - -# Top-Level LLVM Build Stages: -# 1. Build lib/Support and lib/TableGen, which are used by utils (tblgen). -# 2. Build utils, which is used by VMCore. -# 3. Build VMCore, which builds the Intrinsics.inc file used by libs. -# 4. Build libs, which are needed by llvm-config. -# 5. Build llvm-config, which determines inter-lib dependencies for tools. -# 6. Build tools, runtime, docs. -# -# When cross-compiling, there are some things (tablegen) that need to -# be build for the build system first. - -# If "RC_ProjectName" exists in the environment, and its value is -# "llvmCore", then this is an "Apple-style" build; search for -# "Apple-style" in the comments for more info. Anything else is a -# normal build. -ifneq ($(findstring llvmCore, $(RC_ProjectName)),llvmCore) # Normal build (not "Apple-style"). - -ifeq ($(BUILD_DIRS_ONLY),1) - DIRS := lib/Support lib/TableGen utils tools/llvm-config - OPTIONAL_DIRS := tools/clang/utils/TableGen -else - DIRS := lib/Support lib/TableGen utils lib/VMCore lib tools/llvm-shlib \ - tools/llvm-config tools runtime docs unittests - OPTIONAL_DIRS := projects bindings -endif - -ifeq ($(BUILD_EXAMPLES),1) - OPTIONAL_DIRS += examples -endif - -EXTRA_DIST := test unittests llvm.spec include win32 Xcode - -include $(LEVEL)/Makefile.config - -ifneq ($(ENABLE_SHARED),1) - DIRS := $(filter-out tools/llvm-shlib, $(DIRS)) -endif - -ifneq ($(ENABLE_DOCS),1) - DIRS := $(filter-out docs, $(DIRS)) -endif - -ifeq ($(MAKECMDGOALS),libs-only) - DIRS := $(filter-out tools runtime docs, $(DIRS)) - OPTIONAL_DIRS := -endif - -ifeq ($(MAKECMDGOALS),install-libs) - DIRS := $(filter-out tools runtime docs, $(DIRS)) - OPTIONAL_DIRS := $(filter bindings, $(OPTIONAL_DIRS)) -endif - -ifeq ($(MAKECMDGOALS),tools-only) - DIRS := $(filter-out runtime docs, $(DIRS)) - OPTIONAL_DIRS := -endif - -ifeq ($(MAKECMDGOALS),install-clang) - DIRS := tools/clang/tools/driver tools/clang/lib/Headers \ - tools/clang/tools/libclang tools/clang/tools/c-index-test \ - tools/clang/include/clang-c \ - tools/clang/runtime tools/clang/docs \ - tools/lto runtime - OPTIONAL_DIRS := - NO_INSTALL = 1 -endif - -ifeq ($(MAKECMDGOALS),clang-only) - DIRS := $(filter-out tools docs unittests, $(DIRS)) \ - tools/clang tools/lto - OPTIONAL_DIRS := -endif - -ifeq ($(MAKECMDGOALS),unittests) - DIRS := $(filter-out tools runtime docs, $(DIRS)) utils unittests - OPTIONAL_DIRS := -endif - -# Use NO_INSTALL define of the Makefile of each directory for deciding -# if the directory is installed or not -ifeq ($(MAKECMDGOALS),install) - OPTIONAL_DIRS := $(filter bindings, $(OPTIONAL_DIRS)) -endif - -# Don't build unittests when ONLY_TOOLS is set. -ifneq ($(ONLY_TOOLS),) - DIRS := $(filter-out unittests, $(DIRS)) -endif - -# If we're cross-compiling, build the build-hosted tools first -ifeq ($(LLVM_CROSS_COMPILING),1) -all:: cross-compile-build-tools - -clean:: - $(Verb) rm -rf BuildTools - -cross-compile-build-tools: - $(Verb) if [ ! -f BuildTools/Makefile ]; then \ - $(MKDIR) BuildTools; \ - cd BuildTools ; \ - unset CFLAGS ; \ - unset CXXFLAGS ; \ - $(PROJ_SRC_DIR)/configure --build=$(BUILD_TRIPLE) \ - --host=$(BUILD_TRIPLE) --target=$(BUILD_TRIPLE) \ - --disable-polly ; \ - cd .. ; \ - fi; \ - (unset SDKROOT; \ - $(MAKE) -C BuildTools \ - BUILD_DIRS_ONLY=1 \ - UNIVERSAL= \ - TARGET_NATIVE_ARCH="$(TARGET_NATIVE_ARCH)" \ - TARGETS_TO_BUILD="$(TARGETS_TO_BUILD)" \ - ENABLE_OPTIMIZED=$(ENABLE_OPTIMIZED) \ - ENABLE_PROFILING=$(ENABLE_PROFILING) \ - ENABLE_COVERAGE=$(ENABLE_COVERAGE) \ - DISABLE_ASSERTIONS=$(DISABLE_ASSERTIONS) \ - ENABLE_EXPENSIVE_CHECKS=$(ENABLE_EXPENSIVE_CHECKS) \ - ENABLE_LIBCPP=$(ENABLE_LIBCPP) \ - CFLAGS= \ - CXXFLAGS= \ - ) || exit 1; -endif - -# Include the main makefile machinery. -include $(LLVM_SRC_ROOT)/Makefile.rules - -# Specify options to pass to configure script when we're -# running the dist-check target -DIST_CHECK_CONFIG_OPTIONS = --with-llvmgccdir=$(LLVMGCCDIR) - -.PHONY: debug-opt-prof -debug-opt-prof: - $(Echo) Building Debug Version - $(Verb) $(MAKE) - $(Echo) - $(Echo) Building Optimized Version - $(Echo) - $(Verb) $(MAKE) ENABLE_OPTIMIZED=1 - $(Echo) - $(Echo) Building Profiling Version - $(Echo) - $(Verb) $(MAKE) ENABLE_PROFILING=1 - -dist-hook:: - $(Echo) Eliminating files constructed by configure - $(Verb) $(RM) -f \ - $(TopDistDir)/include/llvm/Config/config.h \ - $(TopDistDir)/include/llvm/Support/DataTypes.h - -clang-only: all -tools-only: all -libs-only: all -install-clang: install -install-libs: install - -# If SHOW_DIAGNOSTICS is enabled, clear the diagnostics file first. -ifeq ($(SHOW_DIAGNOSTICS),1) -clean-diagnostics: - $(Verb) rm -f $(LLVM_OBJ_ROOT)/$(BuildMode)/diags -.PHONY: clean-diagnostics - -all-local:: clean-diagnostics -endif - -#------------------------------------------------------------------------ -# Make sure the generated files are up-to-date. This must be kept in -# sync with the AC_CONFIG_HEADER and AC_CONFIG_FILE invocations in -# autoconf/configure.ac. -# Note that Makefile.config is covered by its own separate rule -# in Makefile.rules where it can be reused by sub-projects. -#------------------------------------------------------------------------ -FilesToConfig := \ - bindings/ocaml/llvm/META.llvm \ - docs/doxygen.cfg \ - llvm.spec \ - include/llvm/Config/config.h \ - include/llvm/Config/llvm-config.h \ - include/llvm/Config/Targets.def \ - include/llvm/Config/AsmPrinters.def \ - include/llvm/Config/AsmParsers.def \ - include/llvm/Config/Disassemblers.def \ - include/llvm/Support/DataTypes.h -FilesToConfigPATH := $(addprefix $(LLVM_OBJ_ROOT)/,$(FilesToConfig)) - -all-local:: $(FilesToConfigPATH) -$(FilesToConfigPATH) : $(LLVM_OBJ_ROOT)/% : $(LLVM_SRC_ROOT)/%.in - $(Echo) Regenerating $* - $(Verb) cd $(LLVM_OBJ_ROOT) && $(ConfigStatusScript) $* -.PRECIOUS: $(FilesToConfigPATH) - -# NOTE: This needs to remain as the last target definition in this file so -# that it gets executed last. -ifneq ($(BUILD_DIRS_ONLY),1) -all:: - $(Echo) '*****' Completed $(BuildMode) Build -ifneq ($(ENABLE_OPTIMIZED),1) - $(Echo) '*****' Note: Debug build can be 10 times slower than an - $(Echo) '*****' optimized build. Use 'make ENABLE_OPTIMIZED=1' to - $(Echo) '*****' make an optimized build. Alternatively you can - $(Echo) '*****' configure with --enable-optimized. -ifeq ($(SHOW_DIAGNOSTICS),1) - $(Verb) if test -s $(LLVM_OBJ_ROOT)/$(BuildMode)/diags; then \ - $(LLVM_SRC_ROOT)/utils/clang-parse-diagnostics-file -a \ - $(LLVM_OBJ_ROOT)/$(BuildMode)/diags; \ - fi -endif -endif -endif - -check-llvm2cpp: - $(Verb)$(MAKE) check TESTSUITE=Feature RUNLLVM2CPP=1 - -srpm: $(LLVM_OBJ_ROOT)/llvm.spec - rpmbuild -bs $(LLVM_OBJ_ROOT)/llvm.spec - -rpm: $(LLVM_OBJ_ROOT)/llvm.spec - rpmbuild -bb --target $(TARGET_TRIPLE) $(LLVM_OBJ_ROOT)/llvm.spec - -show-footprint: - $(Verb) du -sk $(LibDir) - $(Verb) du -sk $(ToolDir) - $(Verb) du -sk $(ExmplDir) - $(Verb) du -sk $(ObjDir) - -build-for-llvm-top: - $(Verb) if test ! -f ./config.status ; then \ - ./configure --prefix="$(LLVM_TOP)/install" \ - --with-llvm-gcc="$(LLVM_TOP)/llvm-gcc" ; \ - fi - $(Verb) $(MAKE) tools-only - -SVN = svn -SVN-UPDATE-OPTIONS = -AWK = awk -SUB-SVN-DIRS = $(AWK) '/\?\ \ \ \ \ \ / {print $$2}' \ - | LC_ALL=C xargs $(SVN) info 2>/dev/null \ - | $(AWK) '/^Path:\ / {print $$2}' - -update: - $(SVN) $(SVN-UPDATE-OPTIONS) update $(LLVM_SRC_ROOT) - @ $(SVN) status $(LLVM_SRC_ROOT) | $(SUB-SVN-DIRS) | xargs $(SVN) $(SVN-UPDATE-OPTIONS) update - -happiness: update all check-all - -.PHONY: srpm rpm update happiness - -# declare all targets at this level to be serial: - -.NOTPARALLEL: - -else # Building "Apple-style." -# In an Apple-style build, once configuration is done, lines marked -# "Apple-style" are removed with sed! Please don't remove these! -# Look for the string "Apple-style" in utils/buildit/build_llvm. -include $(shell find . -name GNUmakefile) # Building "Apple-style." -endif # Building "Apple-style." diff --git a/cpp/llvm/bindings/Makefile b/cpp/llvm/bindings/Makefile deleted file mode 100644 index c545b288..00000000 --- a/cpp/llvm/bindings/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- bindings/Makefile -----------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := .. - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS = $(BINDINGS_TO_BUILD) - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/bindings/ocaml/Makefile b/cpp/llvm/bindings/ocaml/Makefile deleted file mode 100644 index a89caefb..00000000 --- a/cpp/llvm/bindings/ocaml/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../.. -DIRS = llvm bitreader bitwriter analysis target executionengine transforms -ExtraMakefiles = $(PROJ_OBJ_DIR)/Makefile.ocaml - -ocamldoc: - $(Verb) for i in $(DIRS) ; do \ - $(MAKE) -C $$i ocamldoc; \ - done - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/bindings/ocaml/analysis/Makefile b/cpp/llvm/bindings/ocaml/analysis/Makefile deleted file mode 100644 index cbfcb246..00000000 --- a/cpp/llvm/bindings/ocaml/analysis/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/analysis/Makefile --------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_analysis interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm_analysis -UsedComponents := analysis -UsedOcamlInterfaces := llvm - -include ../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/bitreader/Makefile b/cpp/llvm/bindings/ocaml/bitreader/Makefile deleted file mode 100644 index a1c7de89..00000000 --- a/cpp/llvm/bindings/ocaml/bitreader/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/bitreader/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_bitreader interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm_bitreader -UsedComponents := bitreader -UsedOcamlInterfaces := llvm - -include ../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/bitwriter/Makefile b/cpp/llvm/bindings/ocaml/bitwriter/Makefile deleted file mode 100644 index cec0a59c..00000000 --- a/cpp/llvm/bindings/ocaml/bitwriter/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/bitwriter/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_bitwriter interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm_bitwriter -UsedComponents := bitwriter -UsedOcamlInterfaces := llvm - -include ../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/executionengine/Makefile b/cpp/llvm/bindings/ocaml/executionengine/Makefile deleted file mode 100644 index 5fa3f220..00000000 --- a/cpp/llvm/bindings/ocaml/executionengine/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/executionengine/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_executionengine interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm_executionengine -UsedComponents := executionengine jit interpreter native -UsedOcamlInterfaces := llvm llvm_target - -include ../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/llvm/Makefile b/cpp/llvm/bindings/ocaml/llvm/Makefile deleted file mode 100644 index 203075a9..00000000 --- a/cpp/llvm/bindings/ocaml/llvm/Makefile +++ /dev/null @@ -1,42 +0,0 @@ -##===- bindings/ocaml/llvm/Makefile ------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm -UsedComponents := core -UsedOcamLibs := llvm - -include ../Makefile.ocaml - -all-local:: copy-meta -install-local:: install-meta -uninstall-local:: uninstall-meta - -DestMETA := $(PROJ_libocamldir)/META.llvm - -# Easy way of generating META in the objdir -copy-meta: $(OcamlDir)/META.llvm - -$(OcamlDir)/META.llvm: META.llvm - $(Verb) $(CP) -f $< $@ - -install-meta:: $(OcamlDir)/META.llvm - $(Echo) "Install $(BuildMode) $(DestMETA)" - $(Verb) $(MKDIR) $(PROJ_libocamldir) - $(Verb) $(DataInstall) $< "$(DestMETA)" - -uninstall-meta:: - $(Echo) "Uninstalling $(DestMETA)" - -$(Verb) $(RM) -f "$(DestMETA)" - -.PHONY: copy-meta install-meta uninstall-meta diff --git a/cpp/llvm/bindings/ocaml/target/Makefile b/cpp/llvm/bindings/ocaml/target/Makefile deleted file mode 100644 index 3c48cd8f..00000000 --- a/cpp/llvm/bindings/ocaml/target/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- bindings/ocaml/target/Makefile ----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_target interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -LIBRARYNAME := llvm_target -UsedComponents := target -UsedOcamlInterfaces := llvm - -include ../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/transforms/Makefile b/cpp/llvm/bindings/ocaml/transforms/Makefile deleted file mode 100644 index 05fcd900..00000000 --- a/cpp/llvm/bindings/ocaml/transforms/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- bindings/ocaml/transforms/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -DIRS = scalar ipo - -ocamldoc: - $(Verb) for i in $(DIRS) ; do \ - $(MAKE) -C $$i ocamldoc; \ - done - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/bindings/ocaml/transforms/ipo/Makefile b/cpp/llvm/bindings/ocaml/transforms/ipo/Makefile deleted file mode 100644 index 130d74c9..00000000 --- a/cpp/llvm/bindings/ocaml/transforms/ipo/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -##===- bindings/ocaml/transforms/scalar/Makefile -----------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_scalar_opts interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../../.. -LIBRARYNAME := llvm_ipo -DONT_BUILD_RELINKED := 1 -UsedComponents := ipo -UsedOcamlInterfaces := llvm - -include ../../Makefile.ocaml diff --git a/cpp/llvm/bindings/ocaml/transforms/scalar/Makefile b/cpp/llvm/bindings/ocaml/transforms/scalar/Makefile deleted file mode 100644 index cbaffa4e..00000000 --- a/cpp/llvm/bindings/ocaml/transforms/scalar/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -##===- bindings/ocaml/transforms/scalar/Makefile -----------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml Llvm_scalar_opts interface. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../../.. -LIBRARYNAME := llvm_scalar_opts -DONT_BUILD_RELINKED := 1 -UsedComponents := scalaropts -UsedOcamlInterfaces := llvm - -include ../../Makefile.ocaml diff --git a/cpp/llvm/docs/AliasAnalysis.html b/cpp/llvm/docs/AliasAnalysis.html deleted file mode 100644 index 92ac6366..00000000 --- a/cpp/llvm/docs/AliasAnalysis.html +++ /dev/null @@ -1,1067 +0,0 @@ - - - - - LLVM Alias Analysis Infrastructure - - - - -

- LLVM Alias Analysis Infrastructure -

- -
    -
  1. Introduction
  2. - -
  3. AliasAnalysis Class Overview - -
  4. - -
  5. Writing a new AliasAnalysis Implementation - -
  6. - -
  7. Using alias analysis results - -
  8. - -
  9. Existing alias analysis implementations and clients - -
  10. -
  11. Memory Dependence Analysis
  12. -
- -
-

Written by Chris Lattner

-
- - -

- Introduction -

- - -
- -

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 Must, May, or No 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.

- -

The LLVM AliasAnalysis -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.

- -

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 let me -know.

- -
- - -

- AliasAnalysis Class Overview -

- - -
- -

The AliasAnalysis -class defines the interface that the various alias analysis implementations -should support. This class exports two important enums: AliasResult -and ModRefResult which represent the result of an alias query or a -mod/ref query, respectively.

- -

The AliasAnalysis 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 call or invoke instructions that performs the -call. The AliasAnalysis interface also exposes some helper methods -which allow you to get mod/ref information for arbitrary instructions.

- -

All AliasAnalysis interfaces require that in queries involving -multiple values, values which are not -constants are all defined within the -same function.

- - -

- Representation of Pointers -

- -
- -

Most importantly, the AliasAnalysis 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 Value*) and a static size.

- -

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:

- -
-
-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 */
-}
-
-
- -

In this case, the basicaa pass will disambiguate the stores to -C[0] and C[1] 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:

- -
-
-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 */
-}
-
-
- -

In this case, the two stores to C do alias each other, because the access to -the &C[0] 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.

- -
- - -

- The alias method -

- -
-

The alias 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.

- -

Like all AliasAnalysis interfaces, the alias method requires -that either the two pointer values be defined within the same function, or at -least one of the values is a constant.

- - -

- Must, May, and No Alias Responses -

- -
-

The NoAlias response may be used when there is never an immediate dependence -between any memory reference based on one pointer and any memory -reference based 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.

- -

As an exception to this is with the -noalias keyword; the "irrelevant" -dependencies are ignored.

- -

The MayAlias response is used whenever the two pointers might refer to the -same object.

- -

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.

- -

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.

- -
- -
- - -

- The getModRefInfo methods -

- -
- -

The getModRefInfo 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 might read or write -a location, ModRef is returned.

- -

The AliasAnalysis class also provides a getModRefInfo -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.

- -
- - - -

- Other useful AliasAnalysis methods -

- -
- -

-Several other tidbits of information are often collected by various alias -analysis implementations and can be put to good use by various clients. -

- - -

- The pointsToConstantMemory method -

- -
- -

The pointsToConstantMemory 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.

- -
- - -

- The doesNotAccessMemory and - onlyReadsMemory methods -

- -
- -

These methods are used to provide very simple mod/ref information for -function calls. The doesNotAccessMemory 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., sin and -cos) but many others do not (e.g., acos, which modifies the -errno variable).

- -

The onlyReadsMemory 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 doesNotAccessMemory method also satisfies -onlyReadsMemory.

- -
- -
- -
- - -

- Writing a new AliasAnalysis Implementation -

- - -
- -

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 various alias analysis -implementations included with LLVM.

- - -

- Different Pass styles -

- -
- -

The first step to determining what type of LLVM pass 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:

- -
    -
  1. If you require interprocedural analysis, it should be a - Pass.
  2. -
  3. If you are a function-local analysis, subclass FunctionPass.
  4. -
  5. If you don't need to look at the program at all, subclass - ImmutablePass.
  6. -
- -

In addition to the pass that you subclass, you should also inherit from the -AliasAnalysis interface, of course, and use the -RegisterAnalysisGroup template to register as an implementation of -AliasAnalysis.

- -
- - -

- Required initialization calls -

- -
- -

Your subclass of AliasAnalysis is required to invoke two methods on -the AliasAnalysis base class: getAnalysisUsage and -InitializeAliasAnalysis. In particular, your implementation of -getAnalysisUsage should explicitly call into the -AliasAnalysis::getAnalysisUsage method in addition to doing any -declaring any pass dependencies your pass has. Thus you should have something -like this:

- -
-
-void getAnalysisUsage(AnalysisUsage &AU) const {
-  AliasAnalysis::getAnalysisUsage(AU);
-  // declare your dependencies here.
-}
-
-
- -

Additionally, your must invoke the InitializeAliasAnalysis method -from your analysis run method (run for a Pass, -runOnFunction for a FunctionPass, or InitializePass -for an ImmutablePass). For example (as part of a Pass):

- -
-
-bool run(Module &M) {
-  InitializeAliasAnalysis(this);
-  // Perform analysis here...
-  return false;
-}
-
-
- -
- - -

- Interfaces which may be specified -

- -
- -

All of the AliasAnalysis -virtual methods default to providing chaining 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.

- -
- - - - -

- AliasAnalysis chaining behavior -

- -
- -

With only one special exception (the no-aa -pass) every alias analysis pass chains to another alias analysis -implementation (for example, the user can specify "-basicaa -ds-aa --licm" 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:

- -
-
-AliasAnalysis::AliasResult alias(const Value *V1, unsigned V1Size,
-                                 const Value *V2, unsigned V2Size) {
-  if (...)
-    return NoAlias;
-  ...
-
-  // Couldn't determine a must or no-alias result.
-  return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
-}
-
-
- -

In addition to analysis queries, you must make sure to unconditionally pass -LLVM update notification methods to the superclass as -well if you override them, which allows all alias analyses in a change to be -updated.

- -
- - - -

- Updating analysis results for transformations -

- -
-

-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. -

- -

-The AliasAnalysis 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. -

- - -

The deleteValue method

- -
-The deleteValue 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. -
- - -

The copyValue method

- -
-The copyValue 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. -
- - -

The replaceWithNewValue method

- -
-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. -
- - -

The addEscapingUse method

- -
-

The addEscapingUse 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.

- -

In general, any new use of a pointer value is considered an escaping use, -and must be reported through this callback, except for the -uses below:

- -
    -
  • A bitcast or getelementptr of the pointer
  • -
  • A store through the pointer (but not a store - of the pointer)
  • -
  • A load through the pointer
  • -
-
- -
- - -

- Efficiency Issues -

- -
- -

From the LLVM perspective, the only thing you need to do to provide an -efficient alias analysis is to make sure that alias analysis queries 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).

- -
- - -

- Limitations -

- -
- -

The AliasAnalysis infrastructure has several limitations which make -writing a new AliasAnalysis implementation difficult.

- -

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.

- -

There is no way for transform passes to declare that they preserve -AliasAnalysis implementations. The AliasAnalysis -interface includes deleteValue and copyValue 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 -getAnalysisUsage that it does so. Some passes attempt to use -AU.addPreserved<AliasAnalysis>, however this doesn't -actually have any effect.

- -

AliasAnalysisCounter (-count-aa) and AliasDebugger -(-debug-aa) are implemented as ModulePass classes, so if your -alias analysis uses FunctionPass, 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 -BasicAliasAnalysis instead.

- -

Similarly, the opt -p option introduces ModulePass -passes between each pass, which prevents the use of FunctionPass -alias analysis passes.

- -

The AliasAnalysis 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 AliasAnalysis -implementations which can not be expressed.

- -

The AliasAnalysisDebugger utility seems to suggest that -AliasAnalysis implementations can expect that they will be -informed of any relevant Value before it appears in an -alias query. However, popular clients such as GVN don't -support this, and are known to trigger errors when run with the -AliasAnalysisDebugger.

- -

Due to several of the above limitations, the most obvious use for -the AliasAnalysisCounter utility, collecting stats on all -alias queries in a compilation, doesn't work, even if the -AliasAnalysis implementations don't use FunctionPass. -There's no way to set a default, much less a default sequence, -and there's no way to preserve it.

- -

The AliasSetTracker class (which is used by LICM -makes a non-deterministic number of alias queries. This can cause stats -collected by AliasAnalysisCounter 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.

- -

Many alias queries can be reformulated in terms of other alias -queries. When multiple AliasAnalysis 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.

- -
- -
- - -

- Using alias analysis results -

- - -
- -

There are several different ways to use alias analysis results. In order of -preference, these are...

- - -

- Using the MemoryDependenceAnalysis Pass -

- -
- -

The memdep 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. -

- -
- - -

- Using the AliasSetTracker class -

- -
- -

Many transformations need information about alias sets that are active -in some scope, rather than information about pairwise aliasing. The AliasSetTracker class -is used to efficiently build these Alias Sets from the pairwise alias analysis -information provided by the AliasAnalysis interface.

- -

First you initialize the AliasSetTracker by using the "add" 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 -AliasSetTracker begin()/end() methods.

- -

The AliasSets formed by the AliasSetTracker 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.

- -

As an example user of this, the Loop -Invariant Code Motion pass uses AliasSetTrackers to calculate alias -sets for each loop nest. If an AliasSet 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 and 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.

- - -

- The AliasSetTracker implementation -

- -
- -

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.

- -

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). -

- -

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.

- -
- -
- - -

- Using the AliasAnalysis interface directly -

- -
- -

If neither of these utility class are what your pass needs, you should use -the interfaces exposed by the AliasAnalysis class directly. Try to use -the higher-level methods when possible (e.g., use mod/ref information instead of -the alias method directly if possible) to get the -best precision and efficiency.

- -
- -
- - -

- Existing alias analysis implementations and clients -

- - -
- -

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 the clients that are useful -for monitoring and evaluating different implementations.

- - -

- Available AliasAnalysis implementations -

- -
- -

This section lists the various implementations of the AliasAnalysis -interface. With the exception of the -no-aa -implementation, all of these chain to other alias -analysis implementations.

- - -

- The -no-aa pass -

- -
- -

The -no-aa 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.

- -
- - -

- The -basicaa pass -

- -
- -

The -basicaa pass is an aggressive local analysis that "knows" -many important facts:

- -
    -
  • Distinct globals, stack allocations, and heap allocations can never - alias.
  • -
  • Globals, stack allocations, and heap allocations never alias the null - pointer.
  • -
  • Different fields of a structure do not alias.
  • -
  • Indexes into arrays with statically differing subscripts cannot alias.
  • -
  • Many common standard C library functions never access memory or only read memory.
  • -
  • Pointers that obviously point to constant globals - "pointToConstantMemory".
  • -
  • 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).
  • -
- -
- - -

- The -globalsmodref-aa pass -

- -
- -

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. -

- -

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.

- -

Note that this pass is somewhat limited in its scope (only support -non-address taken globals), but is very quick analysis.

-
- - -

- The -steens-aa pass -

- -
- -

The -steens-aa 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).

- -

The LLVM -steens-aa pass implements a "speculatively -field-sensitive" 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.

- -

Note that -steens-aa is available in the optional "poolalloc" -module, it is not part of the LLVM core.

- -
- - -

- The -ds-aa pass -

- -
- -

The -ds-aa pass implements the full Data Structure Analysis -algorithm. Data Structure Analysis is a modular unification-based, -flow-insensitive, context-sensitive, and speculatively -field-sensitive alias analysis that is also quite scalable, usually at -O(n*log(n)).

- -

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.

- -

Note that -ds-aa is available in the optional "poolalloc" -module, it is not part of the LLVM core.

- -
- - -

- The -scev-aa pass -

- -
- -

The -scev-aa pass implements AliasAnalysis queries by -translating them into ScalarEvolution queries. This gives it a -more complete understanding of getelementptr instructions -and loop induction variables than other alias analyses have.

- -
- -
- - -

- Alias analysis driven transformations -

- -
-LLVM includes several alias-analysis driven transformations which can be used -with any of the implementations above. - - -

- The -adce pass -

- -
- -

The -adce pass, which implements Aggressive Dead Code Elimination -uses the AliasAnalysis interface to delete calls to functions that do -not have side-effects and are not used.

- -
- - - -

- The -licm pass -

- -
- -

The -licm pass implements various Loop Invariant Code Motion related -transformations. It uses the AliasAnalysis interface for several -different transformations:

- -
    -
  • 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.
  • - -
  • It uses mod/ref information to hoist function calls out of loops that do not -write to memory and are loop-invariant.
  • - -
  • 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.
  • -
- -
- - -

- The -argpromotion pass -

- -
-

-The -argpromotion 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.

-
- - -

- The -gvn, -memcpyopt, and -dse - passes -

- -
- -

These passes use AliasAnalysis information to reason about loads and stores. -

- -
- -
- - -

- Clients for debugging and evaluation of - implementations -

- -
- -

These passes are useful for evaluating the various alias analysis -implementations. You can use them with commands like 'opt -ds-aa --aa-eval foo.bc -disable-output -stats'.

- - -

- The -print-alias-sets pass -

- -
- -

The -print-alias-sets pass is exposed as part of the -opt tool to print out the Alias Sets formed by the AliasSetTracker class. This is useful if you're using -the AliasSetTracker class. To use it, use something like:

- -
-
-% opt -ds-aa -print-alias-sets -disable-output
-
-
- -
- - - -

- The -count-aa pass -

- -
- -

The -count-aa 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,

- -
-
-% opt -basicaa -count-aa -ds-aa -count-aa -licm
-
-
- -

will print out how many queries (and what responses are returned) by the --licm pass (of the -ds-aa pass) and how many queries are made -of the -basicaa pass by the -ds-aa pass. This can be useful -when debugging a transformation or an alias analysis implementation.

- -
- - -

- The -aa-eval pass -

- -
- -

The -aa-eval 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).

- -
- -
- -
- - -

- Memory Dependence Analysis -

- - -
- -

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.

- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-01-30 15:05:41 -0800 (Mon, 30 Jan 2012) $ -
- - - diff --git a/cpp/llvm/docs/Atomics.html b/cpp/llvm/docs/Atomics.html deleted file mode 100644 index fc15e27c..00000000 --- a/cpp/llvm/docs/Atomics.html +++ /dev/null @@ -1,569 +0,0 @@ - - - - LLVM Atomic Instructions and Concurrency Guide - - - - - -

- LLVM Atomic Instructions and Concurrency Guide -

- -
    -
  1. Introduction
  2. -
  3. Optimization outside atomic
  4. -
  5. Atomic instructions
  6. -
  7. Atomic orderings
  8. -
  9. Atomics and IR optimization
  10. -
  11. Atomics and Codegen
  12. -
- -
-

Written by Eli Friedman

-
- - -

- Introduction -

- - -
- -

Historically, LLVM has not had very strong support for concurrency; some -minimal intrinsics were provided, and volatile 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.

- -

The atomic instructions are designed specifically to provide readable IR and - optimized code generation for the following:

- - -

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.

- -

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.

- -
- - -

- Optimization outside atomic -

- - -
- -

The basic 'load' and 'store' allow a variety of - optimizations, but can lead to undefined results in a concurrent environment; - see NonAtomic. 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.

- -

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:

- -
-/* 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;
-  }
-}
-
- -

The following is equivalent in non-concurrent situations:

- -
-int x;
-void f(int* a) {
-  int xtemp = x;
-  for (int i = 0; i < 100; i++) {
-    if (a[i])
-      xtemp += 1;
-  }
-  x = xtemp;
-}
-
- -

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.)

- -

Note that speculative loads are allowed; a load which - is part of a race returns undef, but does not have undefined - behavior.

- - -
- - -

- Atomic instructions -

- - -
- -

For cases where simple loads and stores are not sufficient, LLVM provides - various atomic instructions. The exact guarantees provided depend on the - ordering; see Atomic orderings

- -

load atomic and store atomic provide the same - basic functionality as non-atomic loads and stores, but provide additional - guarantees in situations where threads and signals are involved.

- -

cmpxchg and atomicrmw are essentially like an - atomic load followed by an atomic store (where the store is conditional for - cmpxchg), 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.

- -

A fence 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.

- -

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.

- -
- - -

- Atomic orderings -

- - -
- -

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 LangRef.)

- - -

- NotAtomic -

- -
- -

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.

- -
-
Relevant standard
-
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 - LangRef.) -
Notes for frontends
-
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.) -
Notes for optimizers
-
Introducing loads to shared variables along a codepath where they would - not otherwise exist is allowed; introducing stores to shared variables - is not. See Optimization outside - atomic.
-
Notes for code generation
-
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.)
-
- -
- - - -

- Unordered -

- -
- -

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.

- -
-
Relevant standard
-
This is intended to match the Java memory model for shared - variables.
-
Notes for frontends
-
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.) -
Notes for optimizers
-
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.
-
Notes for code generation
-
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 LDRD on ARM).
-
- -
- - -

- Monotonic -

- -
- -

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. - -

-
Relevant standard
-
This corresponds to the C++0x/C1x memory_order_relaxed; - see those standards for the exact definition. -
Notes for frontends
-
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 fence.
-
Notes for optimizers
-
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.
-
Notes for code generation
-
Code generation is essentially the same as that for unordered for loads - and stores. No fences are required. cmpxchg and - atomicrmw are required to appear as a single operation.
-
- -
- - -

- Acquire -

- -
- -

Acquire provides a barrier of the sort necessary to acquire a lock to access - other memory with normal loads and stores. - -

-
Relevant standard
-
This corresponds to the C++0x/C1x memory_order_acquire. It - should also be used for C++0x/C1x memory_order_consume. -
Notes for frontends
-
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.
-
Notes for optimizers
-
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.
-
Notes for code generation
-
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 (dmb on ARM, - sync on PowerPC, etc.). Putting such a fence after the - equivalent Monotonic operation is sufficient to maintain Acquire - semantics for a memory operation.
-
- -
- - -

- Release -

- -
- -

Release is similar to Acquire, but with a barrier of the sort necessary to - release a lock. - -

-
Relevant standard
-
This corresponds to the C++0x/C1x memory_order_release.
-
Notes for frontends
-
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.
-
Notes for optimizers
-
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.
-
Notes for code generation
-
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.
-
- -
- - -

- AcquireRelease -

- -
- -

AcquireRelease (acq_rel in IR) provides both an Acquire and a - Release barrier (for fences and operations which both read and write memory). - -

-
Relevant standard
-
This corresponds to the C++0x/C1x memory_order_acq_rel. -
Notes for frontends
-
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.
-
Notes for optimizers
-
In general, optimizers should treat this like a nothrow call; the - the possible optimizations are usually not interesting.
-
Notes for code generation
-
This operation has Acquire and Release semantics; see the sections on - Acquire and Release.
-
- -
- - -

- SequentiallyConsistent -

- -
- -

SequentiallyConsistent (seq_cst in IR) provides - Acquire semantics for loads and Release semantics for - stores. Additionally, it guarantees that a total ordering exists - between all SequentiallyConsistent operations. - -

-
Relevant standard
-
This corresponds to the C++0x/C1x memory_order_seq_cst, - Java volatile, and the gcc-compatible __sync_* builtins - which do not specify otherwise. -
Notes for frontends
-
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.
-
Notes for optimizers
-
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.
-
Notes for code generation
-
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.
-
- -
- -
- - -

- Atomics and IR optimization -

- - -
- -

Predicates for optimizer writers to query: -

- -

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.

- -

Some examples of how optimizations interact with various kinds of atomic - operations: -

- -
- - -

- Atomics and Codegen -

- - -
- -

Atomic operations are represented in the SelectionDAG with - ATOMIC_* opcodes. On architectures which use barrier - instructions for all atomic ordering (like ARM), appropriate fences are - split out as the DAG is built.

- -

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.

- -

Common architectures have some way of representing at least a pointer-sized - lock-free cmpxchg; 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.)

- -

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.).

- -

On x86, all atomic loads generate a MOV. - SequentiallyConsistent stores generate an XCHG, other stores - generate a MOV. SequentiallyConsistent fences generate an - MFENCE, other fences do not cause any code to be generated. - cmpxchg uses the LOCK CMPXCHG instruction. - atomicrmw xchg uses XCHG, - atomicrmw add and atomicrmw sub use - XADD, and all other atomicrmw operations generate - a loop with LOCK CMPXCHG. Depending on the users of the - result, some atomicrmw operations can be translated into - operations like LOCK AND, but that does not work in - general.

- -

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. - cmpxchg and atomicrmw can be represented using - a loop with LL/SC-style instructions which take some sort of exclusive - lock on a cache line (LDREX and STREX on - ARM, etc.). At the moment, the IR does not provide any way to represent a - weak cmpxchg which would not require a loop.

-
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2011-08-09 02:07:00 -0700 (Tue, 09 Aug 2011) $ -
- - - diff --git a/cpp/llvm/docs/BitCodeFormat.html b/cpp/llvm/docs/BitCodeFormat.html deleted file mode 100644 index ed039cea..00000000 --- a/cpp/llvm/docs/BitCodeFormat.html +++ /dev/null @@ -1,1470 +0,0 @@ - - - - - LLVM Bitcode File Format - - - -

LLVM Bitcode File Format

-
    -
  1. Abstract
  2. -
  3. Overview
  4. -
  5. Bitstream Format -
      -
    1. Magic Numbers
    2. -
    3. Primitives
    4. -
    5. Abbreviation IDs
    6. -
    7. Blocks
    8. -
    9. Data Records
    10. -
    11. Abbreviations
    12. -
    13. Standard Blocks
    14. -
    -
  6. -
  7. Bitcode Wrapper Format -
  8. -
  9. LLVM IR Encoding -
      -
    1. Basics
    2. -
    3. MODULE_BLOCK Contents
    4. -
    5. PARAMATTR_BLOCK Contents
    6. -
    7. TYPE_BLOCK Contents
    8. -
    9. CONSTANTS_BLOCK Contents
    10. -
    11. FUNCTION_BLOCK Contents
    12. -
    13. TYPE_SYMTAB_BLOCK Contents
    14. -
    15. VALUE_SYMTAB_BLOCK Contents
    16. -
    17. METADATA_BLOCK Contents
    18. -
    19. METADATA_ATTACHMENT Contents
    20. -
    -
  10. -
-
-

Written by Chris Lattner, - Joshua Haberman, - and Peter S. Housel. -

-
- - -

Abstract

- - -
- -

This document describes the LLVM bitstream file format and the encoding of -the LLVM IR into it.

- -
- - -

Overview

- - -
- -

-What is commonly known as the LLVM bitcode file format (also, sometimes -anachronistically known as bytecode) is actually two things: a bitstream container format -and an encoding of LLVM IR into the container format.

- -

-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.

- -

LLVM IR files may be optionally embedded into a wrapper structure that makes it easy to embed extra data -along with LLVM IR files.

- -

This document first describes the LLVM bitstream format, describes the -wrapper format, then describes the record structure used by LLVM IR files. -

- -
- - -

Bitstream Format

- - -
- -

-The bitstream format is literally a stream of bits, with a very simple -structure. This structure consists of the following concepts: -

- - - -

Note that the llvm-bcanalyzer tool can be -used to dump and inspect arbitrary bitstreams, which is very useful for -understanding the encoding.

- - -

- Magic Numbers -

- -
- -

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.

- -
- - -

- Primitives -

- -
- -

-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 Fixed -Width Integers or as Variable Width -Integers. -

- - -

- Fixed Width Integers -

- -
- -

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. -

- -
- - -

- Variable Width Integers -

- -
- -

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.

- -

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. -

- -
- - -

6-bit characters

- -
- -

6-bit characters encode common characters into a fixed 6-bit field. They -represent the following characters with the following 6-bit values:

- -
-
-'a' .. 'z' —  0 .. 25
-'A' .. 'Z' — 26 .. 51
-'0' .. '9' — 52 .. 61
-       '.' — 62
-       '_' — 63
-
-
- -

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.

- -
- - -

Word Alignment

- -
- -

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.

- -
- -
- - -

- Abbreviation IDs -

- -
- -

-A bitstream is a sequential series of Blocks and -Data Records. 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. -

- -

-The set of builtin abbrev IDs is: -

- -
    -
  • 0 - END_BLOCK — This abbrev ID marks - the end of the current block.
  • -
  • 1 - ENTER_SUBBLOCK — This - abbrev ID marks the beginning of a new block.
  • -
  • 2 - DEFINE_ABBREV — This defines - a new abbreviation.
  • -
  • 3 - UNABBREV_RECORD — This ID - specifies the definition of an unabbreviated record.
  • -
- -

Abbreviation IDs 4 and above are defined by the stream itself, and specify -an abbreviated record encoding.

- -
- - -

- Blocks -

- -
- -

-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 standard blocks -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. -

- -

-When reading and encoding the stream, several properties are maintained for the -block. In particular, each block maintains: -

- -
    -
  1. 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.
  2. - -
  3. 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 BLOCKINFO block, in which case - they are defined in all blocks that match the ID that the BLOCKINFO block is - describing. -
  4. -
- -

-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. -

- - -

ENTER_SUBBLOCK Encoding

- -
- -

[ENTER_SUBBLOCK, blockidvbr8, newabbrevlenvbr4, - <align32bits>, blocklen32]

- -

-The ENTER_SUBBLOCK abbreviation ID specifies the start of a new block -record. The blockid value is encoded as an 8-bit VBR identifier, and -indicates the type of block being entered, which can be -a standard block or an application-specific block. -The newabbrevlen value is a 4-bit VBR, which specifies the abbrev id -width for the sub-block. The blocklen 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. -

- -
- - -

END_BLOCK Encoding

- -
- -

[END_BLOCK, <align32bits>]

- -

-The END_BLOCK 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. -

- -
- -
- - -

- Data Records -

- -
-

-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 -MODULE_CODE_TRIPLE, and the values of the record are the -ASCII codes for the characters in the string. -

- - -

UNABBREV_RECORD Encoding

- -
- -

[UNABBREV_RECORD, codevbr6, numopsvbr6, - op0vbr6, op1vbr6, ...]

- -

-An UNABBREV_RECORD 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. -

- -

-For example, emitting an LLVM IR target triple as an unabbreviated record -requires emitting the UNABBREV_RECORD abbrevid, a vbr6 for the -MODULE_CODE_TRIPLE 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. -

- -
- - -

Abbreviated Record Encoding

- -
- -

[<abbrevid>, fields...]

- -

-An abbreviated record is a abbreviation id followed by a set of fields that are -encoded according to the abbreviation definition. -This allows records to be encoded significantly more densely than records -encoded with the UNABBREV_RECORD 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. -

- -

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).

- -
- -
- - -

- Abbreviations -

- -
-

-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. -

- -

-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. -

- - -

DEFINE_ABBREV Encoding

- -
- -

[DEFINE_ABBREV, numabbrevopsvbr5, abbrevop0, abbrevop1, - ...]

- -

-A DEFINE_ABBREV 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 -BLOCKINFO 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. -

- -

-An abbreviation definition consists of the DEFINE_ABBREV 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). -

- -
    -
  1. Literal operands — [11, litvaluevbr8] -— 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.
  2. -
  3. Encoding info without data — [01, - encoding3] — Operand encodings that do not have extra - data are just emitted as their code. -
  4. -
  5. Encoding info with data — [01, encoding3, -valuevbr5] — Operand encodings that do have extra data are -emitted as their code, followed by the extra data. -
  6. -
- -

The possible operand encodings are:

- -
    -
  • Fixed (code 1): The field should be emitted as - a fixed-width value, whose width is specified by - the operand's extra data.
  • -
  • VBR (code 2): The field should be emitted as - a variable-width value, whose width is - specified by the operand's extra data.
  • -
  • 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).
  • -
  • Char6 (code 4): This field should be emitted as - a char6-encoded value. This operand type takes no - extra data. Char6 encoding is normally used as an array element type. -
  • -
  • 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.
  • -
- -

-For example, target triples in LLVM modules are encoded as a record of the -form [TRIPLE, 'a', 'b', 'c', 'd']. Consider if the bitstream emitted -the following abbrev entry: -

- -
-
-[0, Fixed, 4]
-[0, Array]
-[0, Char6]
-
-
- -

-When emitting a record with this abbreviation, the above entry would be emitted -as: -

- -
-

-[4abbrevwidth, 24, 4vbr6, 06, -16, 26, 36] -

-
- -

These values are:

- -
    -
  1. The first value, 4, is the abbreviation ID for this abbreviation.
  2. -
  3. The second value, 2, is the record code for TRIPLE records within LLVM IR file MODULE_BLOCK blocks.
  4. -
  5. The third value, 4, is the length of the array.
  6. -
  7. The rest of the values are the char6 encoded values - for "abcd".
  8. -
- -

-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 TRIPLE value -is not emitted as a literal in the abbreviation, the abbreviation can also be -used for any other string value. -

- -
- -
- - -

- Standard Blocks -

- -
- -

-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. -

- - -

#0 - BLOCKINFO Block

- -
- -

-The BLOCKINFO block allows the description of metadata for other -blocks. The currently specified records are: -

- -
-
-[SETBID (#1), blockid]
-[DEFINE_ABBREV, ...]
-[BLOCKNAME, ...name...]
-[SETRECORDNAME, RecordID, ...name...]
-
-
- -

-The SETBID record (code 1) indicates which block ID is being -described. SETBID records can occur multiple times throughout the -block to change which block ID is being described. There must be -a SETBID record prior to any other records. -

- -

-Standard DEFINE_ABBREV records can occur inside BLOCKINFO -blocks, but unlike their occurrence in normal blocks, the abbreviation is -defined for blocks matching the block ID we are describing, not the -BLOCKINFO block itself. The abbreviations defined -in BLOCKINFO blocks receive abbreviation IDs as described -in DEFINE_ABBREV. -

- -

The BLOCKNAME 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.

- -

The SETRECORDNAME 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.

- -

-Note that although the data in BLOCKINFO 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. -

- -
- -
- -
- - -

Bitcode Wrapper Format

- - -
- -

-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: -

- -
-

-[Magic32, Version32, Offset32, -Size32, CPUType32] -

-
- -

-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 -0x0B17C0DE and the version is currently always 0. 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. -

- -
- - -

LLVM IR Encoding

- - -
- -

-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. -

- - -

- Basics -

- -
- - -

LLVM IR Magic Number

- -
- -

-The magic number for LLVM IR files is: -

- -
-

-[0x04, 0xC4, 0xE4, 0xD4] -

-
- -

-When combined with the bitcode magic number and viewed as bytes, this is -"BC 0xC0DE". -

- -
- - -

Signed VBRs

- -
- -

-Variable Width Integer 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. -

- -

-As such, signed VBR values of a specific width are emitted as follows: -

- -
    -
  • Positive values are emitted as VBRs of the specified width, but with their - value shifted left by one.
  • -
  • 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.
  • -
- -

-With this encoding, small positive and small negative values can both -be emitted efficiently. Signed VBR encoding is used in -CST_CODE_INTEGER and CST_CODE_WIDE_INTEGER records -within CONSTANTS_BLOCK blocks. -

- -
- - - -

LLVM IR Blocks

- -
- -

-LLVM IR is defined with the following blocks: -

- -
    -
  • 8 — MODULE_BLOCK — This is the top-level block that - contains the entire module, and describes a variety of per-module - information.
  • -
  • 9 — PARAMATTR_BLOCK — This enumerates the parameter - attributes.
  • -
  • 10 — TYPE_BLOCK — This describes all of the types in - the module.
  • -
  • 11 — CONSTANTS_BLOCK — This describes constants for a - module or function.
  • -
  • 12 — FUNCTION_BLOCK — This describes a function - body.
  • -
  • 13 — TYPE_SYMTAB_BLOCK — This describes the type symbol - table.
  • -
  • 14 — VALUE_SYMTAB_BLOCK — This describes a value symbol - table.
  • -
  • 15 — METADATA_BLOCK — This describes metadata items.
  • -
  • 16 — METADATA_ATTACHMENT — This contains records associating metadata with function instruction values.
  • -
- -
- -
- - -

- MODULE_BLOCK Contents -

- -
- -

The MODULE_BLOCK 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 MODULE_BLOCK block may contain the -following sub-blocks: -

- - - - -

MODULE_CODE_VERSION Record

- -
- -

[VERSION, version#]

- -

The VERSION record (code 1) contains a single value -indicating the format version. Only version 0 is supported at this -time.

-
- - -

MODULE_CODE_TRIPLE Record

- -
-

[TRIPLE, ...string...]

- -

The TRIPLE record (code 2) contains a variable number of -values representing the bytes of the target triple -specification string.

-
- - -

MODULE_CODE_DATALAYOUT Record

- -
-

[DATALAYOUT, ...string...]

- -

The DATALAYOUT record (code 3) contains a variable number of -values representing the bytes of the target datalayout -specification string.

-
- - -

MODULE_CODE_ASM Record

- -
-

[ASM, ...string...]

- -

The ASM record (code 4) contains a variable number of -values representing the bytes of module asm strings, with -individual assembly blocks separated by newline (ASCII 10) characters.

-
- - -

MODULE_CODE_SECTIONNAME Record

- -
-

[SECTIONNAME, ...string...]

- -

The SECTIONNAME record (code 5) contains a variable number -of values representing the bytes of a single section name -string. There should be one SECTIONNAME record for each -section name referenced (e.g., in global variable or function -section attributes) within the module. These records can be -referenced by the 1-based index in the section fields of -GLOBALVAR or FUNCTION records.

-
- - -

MODULE_CODE_DEPLIB Record

- -
-

[DEPLIB, ...string...]

- -

The DEPLIB 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 deplibs -declaration. There should be one DEPLIB record for each -library name referenced.

-
- - -

MODULE_CODE_GLOBALVAR Record

- -
-

[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]

- -

The GLOBALVAR record (code 7) marks the declaration or -definition of a global variable. The operand fields are:

- -
    -
  • pointer type: The type index of the pointer type used to point to -this global variable
  • - -
  • isconst: Non-zero if the variable is treated as constant within -the module, or zero if it is not
  • - -
  • initid: If non-zero, the value index of the initializer for this -variable, plus 1.
  • - -
  • linkage: An encoding of the linkage -type for this variable: -
      -
    • external: code 0
    • -
    • weak: code 1
    • -
    • appending: code 2
    • -
    • internal: code 3
    • -
    • linkonce: code 4
    • -
    • dllimport: code 5
    • -
    • dllexport: code 6
    • -
    • extern_weak: code 7
    • -
    • common: code 8
    • -
    • private: code 9
    • -
    • weak_odr: code 10
    • -
    • linkonce_odr: code 11
    • -
    • available_externally: code 12
    • -
    • linker_private: code 13
    • -
    -
  • - -
  • alignment: The logarithm base 2 of the variable's requested -alignment, plus 1
  • - -
  • section: If non-zero, the 1-based section index in the -table of MODULE_CODE_SECTIONNAME -entries.
  • - -
  • visibility: If present, an -encoding of the visibility of this variable: -
      -
    • default: code 0
    • -
    • hidden: code 1
    • -
    • protected: code 2
    • -
    -
  • - -
  • threadlocal: If present and non-zero, indicates that the variable -is thread_local
  • - -
  • unnamed_addr: If present and non-zero, indicates that the variable -has unnamed_addr
  • - -
-
- - -

MODULE_CODE_FUNCTION Record

- -
- -

[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]

- -

The FUNCTION record (code 8) marks the declaration or -definition of a function. The operand fields are:

- -
    -
  • type: The type index of the function type describing this function
  • - -
  • callingconv: The calling convention number: -
      -
    • ccc: code 0
    • -
    • fastcc: code 8
    • -
    • coldcc: code 9
    • -
    • x86_stdcallcc: code 64
    • -
    • x86_fastcallcc: code 65
    • -
    • arm_apcscc: code 66
    • -
    • arm_aapcscc: code 67
    • -
    • arm_aapcs_vfpcc: code 68
    • -
    -
  • - -
  • isproto: Non-zero if this entry represents a declaration -rather than a definition
  • - -
  • linkage: An encoding of the linkage type -for this function
  • - -
  • paramattr: If nonzero, the 1-based parameter attribute index -into the table of PARAMATTR_CODE_ENTRY -entries.
  • - -
  • alignment: The logarithm base 2 of the function's requested -alignment, plus 1
  • - -
  • section: If non-zero, the 1-based section index in the -table of MODULE_CODE_SECTIONNAME -entries.
  • - -
  • visibility: An encoding of the visibility - of this function
  • - -
  • gc: If present and nonzero, the 1-based garbage collector -index in the table of -MODULE_CODE_GCNAME entries.
  • - -
  • unnamed_addr: If present and non-zero, indicates that the function -has unnamed_addr
  • - -
-
- - -

MODULE_CODE_ALIAS Record

- -
- -

[ALIAS, alias type, aliasee val#, linkage, visibility]

- -

The ALIAS record (code 9) marks the definition of an -alias. The operand fields are

- -
    -
  • alias type: The type index of the alias
  • - -
  • aliasee val#: The value index of the aliased value
  • - -
  • linkage: An encoding of the linkage type -for this alias
  • - -
  • visibility: If present, an encoding of the -visibility of the alias
  • - -
-
- - -

MODULE_CODE_PURGEVALS Record

- -
-

[PURGEVALS, numvals]

- -

The PURGEVALS 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 GLOBALVAR, FUNCTION, -and ALIAS records. After a PURGEVALS record is seen, -new value indices will start from the given numvals value.

-
- - -

MODULE_CODE_GCNAME Record

- -
-

[GCNAME, ...string...]

- -

The GCNAME record (code 11) contains a variable number of -values representing the bytes of a single garbage collector name -string. There should be one GCNAME record for each garbage -collector name referenced in function gc attributes within -the module. These records can be referenced by 1-based index in the gc -fields of FUNCTION records.

-
- -
- - -

- PARAMATTR_BLOCK Contents -

- -
- -

The PARAMATTR_BLOCK block (id 9) contains a table of -entries describing the attributes of function parameters. These -entries are referenced by 1-based index in the paramattr field -of module block FUNCTION -records, or within the attr field of function block INST_INVOKE and INST_CALL records.

- -

Entries within PARAMATTR_BLOCK are constructed to ensure -that each is unique (i.e., no two indicies represent equivalent -attribute lists).

- - -

PARAMATTR_CODE_ENTRY Record

- -
- -

[ENTRY, paramidx0, attr0, paramidx1, attr1...]

- -

The ENTRY record (code 1) contains an even number of -values describing a unique set of function parameter attributes. Each -paramidx 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 attr value is a -bitmap with the following interpretation: -

- -
    -
  • bit 0: zeroext
  • -
  • bit 1: signext
  • -
  • bit 2: noreturn
  • -
  • bit 3: inreg
  • -
  • bit 4: sret
  • -
  • bit 5: nounwind
  • -
  • bit 6: noalias
  • -
  • bit 7: byval
  • -
  • bit 8: nest
  • -
  • bit 9: readnone
  • -
  • bit 10: readonly
  • -
  • bit 11: noinline
  • -
  • bit 12: alwaysinline
  • -
  • bit 13: optsize
  • -
  • bit 14: ssp
  • -
  • bit 15: sspreq
  • -
  • bits 16–31: align n
  • -
  • bit 32: nocapture
  • -
  • bit 33: noredzone
  • -
  • bit 34: noimplicitfloat
  • -
  • bit 35: naked
  • -
  • bit 36: inlinehint
  • -
  • bits 37–39: alignstack n, represented as -the logarithm base 2 of the requested alignment, plus 1
  • -
-
- -
- - -

- TYPE_BLOCK Contents -

- -
- -

The TYPE_BLOCK 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 -NUMENTRY) 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. -

- -

Entries within TYPE_BLOCK are constructed to ensure that -each entry is unique (i.e., no two indicies represent structurally -equivalent types).

- - -

TYPE_CODE_NUMENTRY Record

- -
- -

[NUMENTRY, numentries]

- -

The NUMENTRY 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, NUMENTRY should be the first record -in the block. -

-
- - -

TYPE_CODE_VOID Record

- -
- -

[VOID]

- -

The VOID record (code 2) adds a void type to the -type table. -

-
- - -

TYPE_CODE_FLOAT Record

- -
- -

[FLOAT]

- -

The FLOAT record (code 3) adds a float (32-bit -floating point) type to the type table. -

-
- - -

TYPE_CODE_DOUBLE Record

- -
- -

[DOUBLE]

- -

The DOUBLE record (code 4) adds a double (64-bit -floating point) type to the type table. -

-
- - -

TYPE_CODE_LABEL Record

- -
- -

[LABEL]

- -

The LABEL record (code 5) adds a label type to -the type table. -

-
- - -

TYPE_CODE_OPAQUE Record

- -
- -

[OPAQUE]

- -

The OPAQUE record (code 6) adds an opaque type to -the type table. Note that distinct opaque types are not -unified. -

-
- - -

TYPE_CODE_INTEGER Record

- -
- -

[INTEGER, width]

- -

The INTEGER record (code 7) adds an integer type to the -type table. The single width field indicates the width of the -integer type. -

-
- - -

TYPE_CODE_POINTER Record

- -
- -

[POINTER, pointee type, address space]

- -

The POINTER record (code 8) adds a pointer type to the -type table. The operand fields are

- -
    -
  • pointee type: The type index of the pointed-to type
  • - -
  • address space: If supplied, the target-specific numbered -address space where the pointed-to object resides. Otherwise, the -default address space is zero. -
  • -
-
- - -

TYPE_CODE_FUNCTION Record

- -
- -

[FUNCTION, vararg, ignored, retty, ...paramty... ]

- -

The FUNCTION record (code 9) adds a function type to the -type table. The operand fields are

- -
    -
  • vararg: Non-zero if the type represents a varargs function
  • - -
  • ignored: This value field is present for backward -compatibility only, and is ignored
  • - -
  • retty: The type index of the function's return type
  • - -
  • paramty: Zero or more type indices representing the -parameter types of the function
  • -
- -
- - -

TYPE_CODE_STRUCT Record

- -
- -

[STRUCT, ispacked, ...eltty...]

- -

The STRUCT record (code 10) adds a struct type to the -type table. The operand fields are

- -
    -
  • ispacked: Non-zero if the type represents a packed structure
  • - -
  • eltty: Zero or more type indices representing the element -types of the structure
  • -
-
- - -

TYPE_CODE_ARRAY Record

- -
- -

[ARRAY, numelts, eltty]

- -

The ARRAY record (code 11) adds an array type to the type -table. The operand fields are

- -
    -
  • numelts: The number of elements in arrays of this type
  • - -
  • eltty: The type index of the array element type
  • -
-
- - -

TYPE_CODE_VECTOR Record

- -
- -

[VECTOR, numelts, eltty]

- -

The VECTOR record (code 12) adds a vector type to the type -table. The operand fields are

- -
    -
  • numelts: The number of elements in vectors of this type
  • - -
  • eltty: The type index of the vector element type
  • -
-
- - -

TYPE_CODE_X86_FP80 Record

- -
- -

[X86_FP80]

- -

The X86_FP80 record (code 13) adds an x86_fp80 (80-bit -floating point) type to the type table. -

-
- - -

TYPE_CODE_FP128 Record

- -
- -

[FP128]

- -

The FP128 record (code 14) adds an fp128 (128-bit -floating point) type to the type table. -

-
- - -

TYPE_CODE_PPC_FP128 Record

- -
- -

[PPC_FP128]

- -

The PPC_FP128 record (code 15) adds a ppc_fp128 -(128-bit floating point) type to the type table. -

-
- - -

TYPE_CODE_METADATA Record

- -
- -

[METADATA]

- -

The METADATA record (code 16) adds a metadata -type to the type table. -

-
- -
- - -

- CONSTANTS_BLOCK Contents -

- -
- -

The CONSTANTS_BLOCK block (id 11) ... -

- -
- - - -

- FUNCTION_BLOCK Contents -

- -
- -

The FUNCTION_BLOCK block (id 12) ... -

- -

In addition to the record types described below, a -FUNCTION_BLOCK block may contain the following sub-blocks: -

- - - -
- - - -

- TYPE_SYMTAB_BLOCK Contents -

- -
- -

The TYPE_SYMTAB_BLOCK block (id 13) contains entries which -map between module-level named types and their corresponding type -indices. -

- - -

TST_CODE_ENTRY Record

- -
- -

[ENTRY, typeid, ...string...]

- -

The ENTRY 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. -

-
- -
- - -

- VALUE_SYMTAB_BLOCK Contents -

- -
- -

The VALUE_SYMTAB_BLOCK block (id 14) ... -

- -
- - - -

- METADATA_BLOCK Contents -

- -
- -

The METADATA_BLOCK block (id 15) ... -

- -
- - - -

- METADATA_ATTACHMENT Contents -

- -
- -

The METADATA_ATTACHMENT block (id 16) ... -

- -
- -
- - -
-
Valid CSS -Valid HTML 4.01 - Chris Lattner
-The LLVM Compiler Infrastructure
-Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/BranchWeightMetadata.html b/cpp/llvm/docs/BranchWeightMetadata.html deleted file mode 100644 index 38b87baa..00000000 --- a/cpp/llvm/docs/BranchWeightMetadata.html +++ /dev/null @@ -1,164 +0,0 @@ - - - - - LLVM Branch Weight Metadata - - - - -

- LLVM Branch Weight Metadata -

- -
    -
  1. Introduction
  2. -
  3. Supported Instructions
  4. -
  5. Built-in "expect" Instruction
  6. -
  7. CFG Modifications
  8. -
- -
-

Written by Jakub Staszak

-
- -

- Introduction -

-
-

Branch Weight Metadata represents branch weights as its likeliness to -be taken. Metadata is assigned to the TerminatorInst as a -MDNode of the MD_prof kind. The first operator is always a -MDString node with the string "branch_weights". Number of operators -depends on the terminator type.

- -

Branch weights might be fetch from the profiling file, or generated based on -__builtin_expect instruction. -

- -

All weights are represented as an unsigned 32-bit values, where higher value -indicates greater chance to be taken.

-
- -

- Supported Instructions -

- -
-

BranchInst

-
-

Metadata is only assign to the conditional branches. There are two extra - operarands, for the true and the false branch.

-
-
-
-!0 = metadata !{
-  metadata !"branch_weights",
-  i32 <TRUE_BRANCH_WEIGHT>,
-  i32 <FALSE_BRANCH_WEIGHT>
-}
-  
-
- -

SwitchInst

-
-

Branch weights are assign to every case (including default case - which is always case #0).

-
-
-
-!0 = metadata !{
-  metadata !"branch_weights",
-  i32 <DEFAULT_BRANCH_WEIGHT>
-  [ , i32 <CASE_BRANCH_WEIGHT> ... ]
-}
-  
-
- -

IndirectBrInst

-
-

Branch weights are assign to every destination.

-
-
-
-!0 = metadata !{
-  metadata !"branch_weights",
-  i32 <LABEL_BRANCH_WEIGHT>
-  [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
-}
-  
-
- -

Other

-
-

Other terminator instructions are not allowed to contain Branch Weight - Metadata.

-
-
- -

- Built-in "expect" Instructions -

-
-

__builtin_expect(long exp, long c) instruction provides branch - prediction information. The return value is the value of exp.

- -

It is especially useful in conditional statements. Currently Clang supports - two conditional statements: -

-

if statement

-
-

The exp parameter is the condition. The c 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: -

-
-
-
-  if (__builtin_expect(x > 0, 1)) {
-    // This block is likely to be taken.
-  }
-  
-
- -

switch statement

-
-

The exp parameter is the value. The c parameter is the - expected value. If the expected value doesn't show on the cases list, the - default case is assumed to be likely taken.

-
-
-
-  switch (__builtin_expect(x, 5)) {
-  default: break;
-  case 0:  // ...
-  case 3:  // ...
-  case 5:  // This case is likely to be taken.
-  }
-  
-
-
- -

- CFG Modifications -

-
-

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.

-
- -
-
- Valid CSS - Valid HTML 4.01 - - Jakub Staszak
- LLVM Compiler Infrastructure
-
- - - diff --git a/cpp/llvm/docs/Bugpoint.html b/cpp/llvm/docs/Bugpoint.html deleted file mode 100644 index 37115080..00000000 --- a/cpp/llvm/docs/Bugpoint.html +++ /dev/null @@ -1,239 +0,0 @@ - - - - - LLVM bugpoint tool: design and usage - - - -

- LLVM bugpoint tool: design and usage -

- - - -
-

Written by Chris Lattner

-
- - -

-Description -

- - -
- -

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 example, if opt 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.

- -

For detailed case scenarios, such as debugging opt, -llvm-ld, or one of the LLVM code generators, see How To Submit a Bug Report document.

- -
- - -

-Design Philosophy -

- - -
- -

bugpoint 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. bugpoint 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 bugpoint is generally very quick unless -debugging a miscompilation where each test of the program (which requires -executing it) takes a long time.

- - -

- Automatic Debugger Selection -

- -
- -

bugpoint reads each .bc or .ll 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), bugpoint starts -the crash debugger.

- -

Otherwise, if the -output option was not specified, -bugpoint runs the test program with the C backend (which is assumed to -generate good code) to generate a reference output. Once bugpoint has -a reference output for the test program, it tries executing it with the -selected code generator. If the selected code generator crashes, -bugpoint starts the crash debugger 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 code generator debugger.

- -

Finally, if the output of the selected code generator matches the reference -output, bugpoint 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 miscompilation debugger. -Otherwise, there is no problem bugpoint can debug.

- -
- - -

- Crash debugger -

- -
- -

If an optimizer or code generator crashes, bugpoint will try as hard -as it can to reduce the list of passes (for optimizer crashes) and the size of -the test program. First, bugpoint figures out which combination of -optimizer passes triggers the bug. This is useful when debugging a problem -exposed by opt, for example, because it runs over 38 passes.

- -

Next, bugpoint 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, -bugpoint deletes any individual LLVM instructions whose absence does -not eliminate the failure. At the end, bugpoint should tell you what -passes crash, give you a bitcode file, and give you instructions on how to -reproduce the failure with opt or llc.

- -
- - -

- Code generator debugger -

- -
- -

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.

- -
- - -

- Miscompilation debugger -

- -
- -

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.

- -
- -
- - -

- Advice for using bugpoint -

- - -
- -bugpoint can be a remarkably useful tool, but it sometimes works in -non-obvious ways. Here are some hints and tips:

- -

    -
  1. In the code generator and miscompilation debuggers, bugpoint only - works with programs that have deterministic output. Thus, if the program - outputs argv[0], the date, time, or any other "random" data, - bugpoint 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. - -
  2. 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. - -
  3. bugpoint is extremely useful when working on a new optimization: - it helps track down regressions quickly. To avoid having to relink - bugpoint every time you change your optimization however, have - bugpoint dynamically load your optimization with the - -load option. - -
  4. bugpoint 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:

    - -
    -

    bugpoint ... |& tee bugpoint.log

    -
    - -

    to get a copy of bugpoint's output in the file - bugpoint.log, as well as on your terminal.

    - -
  5. bugpoint cannot debug problems with the LLVM linker. If - bugpoint crashes before you see its "All input ok" message, - you might try llvm-link -v on the same set of input files. If - that also crashes, you may be experiencing a linker bug. - -
  6. bugpoint is useful for proactively finding bugs in LLVM. - Invoking bugpoint with the -find-bugs 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 bugpoint. -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - - diff --git a/cpp/llvm/docs/CMake.html b/cpp/llvm/docs/CMake.html deleted file mode 100644 index acc7fe9e..00000000 --- a/cpp/llvm/docs/CMake.html +++ /dev/null @@ -1,584 +0,0 @@ - - - - - Building LLVM with CMake - - - -

- Building LLVM with CMake -

- - - -
-

Written by Oscar Fuentes

-
- - -

-Introduction -

- - -
- -

CMake 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.

- -

If you are really anxious about getting a functional LLVM build, - go to the Quick start section. If you - are a CMake novice, start on Basic CMake - usage and then go back to the Quick - start once you know what you are - doing. The Options and variables section - is a reference for customizing your build. If you already have - experience with CMake, this is the recommended starting point. -

- - -

-Quick start -

- - -
- -

We use here the command-line, non-interactive CMake interface

- -
    - -
  1. Download - and install CMake. Version 2.8 is the minimum required.

    - -
  2. Open a shell. Your development tools must be reachable from this - shell through the PATH environment variable.

    - -
  3. Create a directory for containing the build. It is not - supported to build LLVM on the source directory. cd to this - directory:

    -
    -

    mkdir mybuilddir

    -

    cd mybuilddir

    -
    - -
  4. Execute this command on the shell - replacing path/to/llvm/source/root with the path to the - root of your LLVM source tree:

    -
    -

    cmake path/to/llvm/source/root

    -
    - -

    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 Options and variables - section for fine-tuning your build

    - -

    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 Usage section.

    - -
- -
- - -

- Basic CMake usage -

- - -
- -

This section explains basic aspects of CMake, mostly for - explaining those options which you may need on your day-to-day - usage.

- -

CMake comes with extensive documentation in the form of html - files and on the cmake executable itself. Execute cmake - --help for further help options.

- -

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 Generator for creating files for your build - tool. You can explicitly specify the generator with the command - line option -G "Name of the generator". For knowing the - available generators on your platform, execute

- -
-

cmake --help

-
- -

This will list the generator's names at the end of the help - text. Generator's names are case-sensitive. Example:

- -
-

cmake -G "Visual Studio 9 2008" path/to/llvm/source/root

-
- -

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 -G option.

- -

TODO: explain variables and cache. Move explanation here from - #options section.

- -
- - -

- Options and variables -

- - -
- -

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:

- -
-

cmake -DVARIABLE=value path/to/llvm/source

-
- -

You can set a variable after the initial CMake invocation for - changing its value. You can also undefine a variable:

- -
-

cmake -UVARIABLE path/to/llvm/source

-
- -

Variables are stored on the CMake cache. This is a file - named CMakeCache.txt on the root of the build - directory. Do not hand-edit it.

- -

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:

- -
-

cmake -DVARIABLE:TYPE=value path/to/llvm/source

-
- - -

- Frequently-used CMake variables -

- -
- -

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 cmake - --help-variable VARIABLE_NAME.

- -
-
CMAKE_BUILD_TYPE:STRING
- -
Sets the build type for make 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.
- -
CMAKE_INSTALL_PREFIX:PATH
-
Path where LLVM will be installed if "make install" is invoked - or the "INSTALL" target is built.
- -
LLVM_LIBDIR_SUFFIX:STRING
-
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.
- -
CMAKE_C_FLAGS:STRING
-
Extra flags to use when compiling C source files.
- -
CMAKE_CXX_FLAGS:STRING
-
Extra flags to use when compiling C++ source files.
- -
BUILD_SHARED_LIBS:BOOL
-
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.
-
- -
- - -

- LLVM-specific variables -

- -
- -
-
LLVM_TARGETS_TO_BUILD:STRING
-
Semicolon-separated list of targets to build, or all for - building all targets. Case-sensitive. For Visual C++ defaults - to X86. On the other cases defaults to all. Example: - -DLLVM_TARGETS_TO_BUILD="X86;PowerPC".
- -
LLVM_BUILD_TOOLS:BOOL
-
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 llvm-as - with a makefile-based system executing make llvm-as on the - root of your build directory.
- -
LLVM_INCLUDE_TOOLS:BOOL
-
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.
- -
LLVM_BUILD_EXAMPLES:BOOL
-
Build LLVM examples. Defaults to OFF. Targets for building each - example are generated in any case. See documentation - for LLVM_BUILD_TOOLS above for more details.
- -
LLVM_INCLUDE_EXAMPLES:BOOL
-
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.
- -
LLVM_BUILD_TESTS:BOOL
-
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 UnitTestNameTests (where at this - time UnitTestName can be ADT, Analysis, ExecutionEngine, - JIT, Support, Transform, VMCore; see the subdirectories - of unittests for an updated list.) It is possible to build - all unit tests with the target UnitTests.
- -
LLVM_INCLUDE_TESTS:BOOL
-
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.
- -
LLVM_APPEND_VC_REV:BOOL
-
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.
- -
LLVM_ENABLE_THREADS:BOOL
-
Build with threads support, if available. Defaults to ON.
- -
LLVM_ENABLE_ASSERTIONS:BOOL
-
Enables code assertions. Defaults to OFF if and only if - CMAKE_BUILD_TYPE is Release.
- -
LLVM_ENABLE_PIC:BOOL
-
Add the -fPIC flag for the compiler command-line, if the - compiler supports this flag. Some systems, like Windows, do not - need this flag. Defaults to ON.
- -
LLVM_ENABLE_WARNINGS:BOOL
-
Enable all compiler warnings. Defaults to ON.
- -
LLVM_ENABLE_PEDANTIC:BOOL
-
Enable pedantic mode. This disable compiler specific extensions, is - possible. Defaults to ON.
- -
LLVM_ENABLE_WERROR:BOOL
-
Stop and fail build, if a compiler warning is - triggered. Defaults to OFF.
- -
LLVM_BUILD_32_BITS:BOOL
-
Build 32-bits executables and libraries on 64-bits systems. This - option is available only on some 64-bits unix systems. Defaults to - OFF.
- -
LLVM_TARGET_ARCH:STRING
-
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.
- -
LLVM_TABLEGEN:STRING
-
Full path to a native TableGen executable (usually - named tblgen). This is intented for cross-compiling: if the - user sets this variable, no native TableGen will be created.
- -
LLVM_LIT_ARGS:STRING
-
Arguments given to lit. - make check and make clang-test are affected. - By default, "-sv --no-progress-bar" - on Visual C++ and Xcode, - "-sv" on others.
- -
LLVM_LIT_TOOLS_DIR:PATH
-
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%.
- -
LLVM_ENABLE_FFI:BOOL
-
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.
- -
LLVM_CLANG_SOURCE_DIR:PATH
-
Path to Clang's source directory. Defaults to tools/clang. - Clang will not be built when it is empty or it does not point valid - path.
- -
LLVM_USE_OPROFILE:BOOL
-
Enable building OProfile JIT support. Defaults to OFF
- -
LLVM_USE_INTEL_JITEVENTS:BOOL
-
Enable building support for Intel JIT Events API. Defaults to OFF
- -
LLVM_INTEL_JITEVENTS_DIR:PATH
-
Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, - used to locate the jitprofiling library. Default = - %VTUNE_AMPLIFIER_XE_2011_DIR% (Windows) - | /opt/intel/vtune_amplifier_xe_2011 (Linux)
- -
- -
- -
- - -

- Executing the test suite -

- - -
- -

Testing is performed when the check target is built. For - instance, if you are using makefiles, execute this command while on - the top level of your build directory:

- -
-

make check

-
- -

On Visual Studio, you may run tests to build the project "check".

- -
- - -

- Cross compiling -

- - -
- -

See this - wiki page 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 - this - section for a quick solution.

- -

Also see the LLVM-specific variables - section for variables used when cross-compiling.

- -
- - -

- Embedding LLVM in your project -

- - -
- -

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:

- -
-
-    # A convenience variable:
-    set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
-    # A bit of a sanity check:
-    if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
-    message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
-    endif()
-    # We incorporate the CMake features provided by LLVM:
-    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
-    include(LLVMConfig)
-    # Now set the header and library paths:
-    include_directories( ${LLVM_INCLUDE_DIRS} )
-    link_directories( ${LLVM_LIBRARY_DIRS} )
-    add_definitions( ${LLVM_DEFINITIONS} )
-    # Let's suppose we want to build a JIT compiler with support for
-    # binary code (no interpreter):
-    llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
-    # Finally, we link the LLVM libraries to our executable:
-    target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
-    
-
- -

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 include_directories for the location of the - headers on the LLVM source directory (if we are building - out-of-source.)

- -

Alternativaly, you can utilize CMake's find_package - functionality. Here is an equivalent variant of snippet shown above:

- -
-
-    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})
-    
-
- - -

- Developing LLVM pass out of source -

- -
- -

It is possible to develop LLVM passes against installed LLVM. - An example of project layout provided below:

- -
-
-      <project dir>/
-          |
-          CMakeLists.txt
-          <pass name>/
-              |
-              CMakeLists.txt
-              Pass.cpp
-              ...
-    
-
- -

Contents of <project dir>/CMakeLists.txt:

- -
-
-    find_package(LLVM)
-
-    # Define add_llvm_* macro's.
-    include(AddLLVM)
-
-    add_definitions(${LLVM_DEFINITIONS})
-    include_directories(${LLVM_INCLUDE_DIRS})
-    link_directories(${LLVM_LIBRARY_DIRS})
-
-    add_subdirectory(<pass name>)
-    
-
- -

Contents of <project dir>/<pass name>/CMakeLists.txt:

- -
-
-    add_llvm_loadable_module(LLVMPassname
-      Pass.cpp
-      )
-    
-
- -

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:
- 1. Copying <pass name> folder into <LLVM root>/lib/Transform directory.
- 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/lib/Transform/CMakeLists.txt

-
- - -
- - -

- Compiler/Platform specific topics -

- - -
- -

Notes for specific compilers and/or platforms.

- -

- Microsoft Visual C++ -

- -
- -
-
LLVM_COMPILER_JOBS:STRING
-
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.
-
- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Oscar Fuentes
- LLVM Compiler Infrastructure
- Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $ -
- - - diff --git a/cpp/llvm/docs/CodeGenerator.html b/cpp/llvm/docs/CodeGenerator.html deleted file mode 100644 index 235774f5..00000000 --- a/cpp/llvm/docs/CodeGenerator.html +++ /dev/null @@ -1,3189 +0,0 @@ - - - - - The LLVM Target-Independent Code Generator - - - - - - - -

- The LLVM Target-Independent Code Generator -

- -
    -
  1. Introduction - -
  2. -
  3. Target description classes - -
  4. -
  5. The "Machine" Code Generator classes - -
  6. -
  7. The "MC" Layer - -
  8. -
  9. Target-independent code generation algorithms - -
  10. -
  11. Implementing a Native Assembler
  12. - -
  13. Target-specific Implementation Notes -
  14. - -
- -
-

Written by the LLVM Team.

-
- -
-

Warning: This is a work in progress.

-
- - -

- Introduction -

- - -
- -

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:

- -
    -
  1. Abstract target description interfaces which - capture important properties about various aspects of the machine, - independently of how they will be used. These interfaces are defined in - include/llvm/Target/.
  2. - -
  3. Classes used to represent the code being - generated for a target. These classes are intended to be abstract - enough to represent the machine code for any target machine. These - classes are defined in include/llvm/CodeGen/. At this level, - concepts like "constant pool entries" and "jump tables" are explicitly - exposed.
  4. - -
  5. Classes and algorithms used to represent code as the object file level, - the MC Layer. 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.
  6. - -
  7. Target-independent algorithms used to implement - various phases of native code generation (register allocation, scheduling, - stack frame representation, etc). This code lives - in lib/CodeGen/.
  8. - -
  9. Implementations of the abstract target description - interfaces 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 lib/Target/.
  10. - -
  11. The target-independent JIT components. The LLVM JIT is - completely target independent (it uses the TargetJITInfo - structure to interface for target-specific issues. The code for the - target-independent JIT lives in lib/ExecutionEngine/JIT.
  12. -
- -

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 target description - and machine code representation classes. If you - want to add a backend for a new target, you will need - to implement the target description classes for - your new target and understand the LLVM code - representation. If you are interested in implementing a - new code generation algorithm, it should only - depend on the target-description and machine code representation classes, - ensuring that it is portable.

- - -

- Required components in the code generator -

- -
- -

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 - (TargetMachine - and TargetData) 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.

- -

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.

- -

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.

- -
- - -

- The high-level design of the code generator -

- -
- -

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:

- -
    -
  1. Instruction Selection — 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.
  2. - -
  3. Scheduling and Formation — - 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 MachineInstrs with that ordering. - Note that we describe this in the instruction - selection section because it operates on - a SelectionDAG.
  4. - -
  5. SSA-based Machine Code Optimizations — - 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.
  6. - -
  7. Register Allocation — 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.
  8. - -
  9. Prolog/Epilog Code Insertion — 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.
  10. - -
  11. Late Machine Code Optimizations — - Optimizations that operate on "final" machine code can go here, such as - spill code scheduling and peephole optimizations.
  12. - -
  13. Code Emission — The final stage - actually puts out the code for the current function, either in the target - assembler format or in machine code.
  14. -
- -

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.

- -

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.

- -
- - -

- Using TableGen for target description -

- -
- -

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 add instruction is almost identical to a - sub instruction). In order to allow the maximum amount of - commonality to be factored out, the LLVM code generator uses - the TableGen 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.

- -

As LLVM continues to be developed and refined, we plan to move more and more - of the target description to the .td 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 tblgen, we only need a change in one place (tblgen) to - update all of the targets to a new interface.

- -
- -
- - -

- Target description classes -

- - -
- -

The LLVM target description classes (located in the - include/llvm/Target directory) provide an abstract description of - the target machine independent of any particular client. These classes are - designed to capture the abstract properties of the target (such as the - instructions and registers it has), and do not incorporate any particular - pieces of code generation algorithms.

- -

All of the target description classes (except the - TargetData class) are designed to be - subclassed by the concrete target implementation, and have virtual methods - implemented. To get to these implementations, the - TargetMachine class provides accessors - that should be implemented by the target.

- - -

- The TargetMachine class -

- -
- -

The TargetMachine class provides virtual methods that are used to - access the target-specific implementations of the various target description - classes via the get*Info methods (getInstrInfo, - getRegisterInfo, getFrameInfo, etc.). This class is - designed to be specialized by a concrete target implementation - (e.g., X86TargetMachine) which implements the various virtual - methods. The only required target description class is - the TargetData class, but if the code - generator components are to be used, the other interfaces should be - implemented as well.

- -
- - -

- The TargetData class -

- -
- -

The TargetData 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). TargetData 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.

- -
- - -

- The TargetLowering class -

- -
- -

The TargetLowering 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:

- -
    -
  • an initial register class to use for various ValueTypes,
  • - -
  • which operations are natively supported by the target machine,
  • - -
  • the return type of setcc operations,
  • - -
  • the type to use for shift amounts, and
  • - -
  • various high-level characteristics, like whether it is profitable to turn - division by a constant into a multiplication sequence
  • -
- -
- - -

- The TargetRegisterInfo class -

- -
- -

The TargetRegisterInfo class is used to describe the register file - of the target and any interactions between the registers.

- -

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.

- -

Each register in the processor description has an associated - TargetRegisterDesc 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).

- -

In addition to the per-register description, the TargetRegisterInfo - class exposes a set of processor specific register classes (instances of the - TargetRegisterClass 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.

- -

The target-specific implementations of these classes is auto-generated from - a TableGen description of the - register file.

- -
- - -

- The TargetInstrInfo class -

- -
- -

The TargetInstrInfo class is used to describe the machine - instructions supported by the target. It is essentially an array of - TargetInstrDescriptor 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.

- -
- - -

- The TargetFrameInfo class -

- -
- -

The TargetFrameInfo 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.

- -
- - -

- The TargetSubtarget class -

- -
- -

The TargetSubtarget 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.

- -
- - - -

- The TargetJITInfo class -

- -
- -

The TargetJITInfo class exposes an abstract interface used by the - Just-In-Time code generator to perform target-specific activities, such as - emitting stubs. If a TargetMachine supports JIT code generation, it - should provide one of these objects through the getJITInfo - method.

- -
- -
- - -

- Machine code description classes -

- - -
- -

At the high-level, LLVM code is translated to a machine specific - representation formed out of - MachineFunction, - MachineBasicBlock, - and MachineInstr instances (defined - in include/llvm/CodeGen). 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.

- - -

- The MachineInstr class -

- -
- -

Target machine instructions are represented as instances of the - MachineInstr 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.

- -

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 *InstrInfo.td file for the target. The opcode enum values are - auto-generated from this description. The MachineInstr 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 - TargetInstrInfo class.

- -

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).

- -

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: "add %i1, %i2, %i3" 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 "%i3, %i1, %i2": with the - destination first.

- -

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:

- -
-
-%r3 = add %i1, %i2
-
-
- -

Also if the first operand is a def, it is easier to create - instructions whose only def is the first operand.

- - -

- Using the MachineInstrBuilder.h functions -

- -
- -

Machine instructions are created by using the BuildMI functions, - located in the include/llvm/CodeGen/MachineInstrBuilder.h file. The - BuildMI functions make it easy to build arbitrary machine - instructions. Usage of the BuildMI functions look like this:

- -
-
-// 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);
-
-
- -

The key thing to remember with the BuildMI 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:

- -
-
-MI.addReg(Reg, RegState::Define);
-
-
- -
- - -

- Fixed (preassigned) registers -

- -
- -

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 must 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 EAX/EDX 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.

- -

For example, consider this simple LLVM example:

- -
-
-define i32 @test(i32 %X, i32 %Y) {
-  %Z = udiv i32 %X, %Y
-  ret i32 %Z
-}
-
-
- -

The X86 instruction selector produces this machine code for the div - and ret (use "llc X.bc -march=x86 -print-machineinstrs" to - get this):

- -
-
-;; 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
-
-
- -

By the end of code generation, the register allocator has coalesced the - registers and deleted the resultant identity moves producing the following - code:

- -
-
-;; X is in EAX, Y is in ECX
-mov %EAX, %EDX
-sar %EDX, 31
-idiv %ECX
-ret 
-
-
- -

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 must live in a virtual - register.

- -
- - -

- Call-clobbered registers -

- -
- -

Some machine instructions, like calls, clobber a large number of physical - registers. Rather than adding <def,dead> operands for - all of them, it is possible to use an MO_RegisterMask operand - instead. The register mask operand holds a bit mask of preserved registers, - and everything else is considered to be clobbered by the instruction.

- -
- - -

- Machine code in SSA form -

- -
- -

MachineInstr'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.

- -

After register allocation, machine code is no longer in SSA-form because - there are no virtual registers left in the code.

- -
- -
- - -

- The MachineBasicBlock class -

- -
- -

The MachineBasicBlock class contains a list of machine instructions - (MachineInstr 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 MachineBasicBlock class has a - "getBasicBlock" method, which returns the LLVM basic block that it - comes from.

- -
- - -

- The MachineFunction class -

- -
- -

The MachineFunction class contains a list of machine basic blocks - (MachineBasicBlock instances). It - corresponds one-to-one with the LLVM function input to the instruction - selector. In addition to a list of basic blocks, - the MachineFunction contains a a MachineConstantPool, - a MachineFrameInfo, a MachineFunctionInfo, and a - MachineRegisterInfo. See - include/llvm/CodeGen/MachineFunction.h for more information.

- -
- - -

- MachineInstr Bundles -

- -
- -

LLVM code generator can model sequences of instructions as MachineInstr - bundles. A MI bundle can model a VLIW group / pack which contains an - arbitrary number of parallel instructions. It can also be used to model - a sequential list of instructions (potentially with data dependencies) that - cannot be legally separated (e.g. ARM Thumb2 IT blocks).

- -

Conceptually a MI bundle is a MI with a number of other MIs nested within: -

- -
-
---------------
-|   Bundle   | ---------
---------------          \
-       |           ----------------
-       |           |      MI      |
-       |           ----------------
-       |                   |
-       |           ----------------
-       |           |      MI      |
-       |           ----------------
-       |                   |
-       |           ----------------
-       |           |      MI      |
-       |           ----------------
-       |
---------------
-|   Bundle   | --------
---------------         \
-       |           ----------------
-       |           |      MI      |
-       |           ----------------
-       |                   |
-       |           ----------------
-       |           |      MI      |
-       |           ----------------
-       |                   |
-       |                  ...
-       |
---------------
-|   Bundle   | --------
---------------         \
-       |
-      ...
-
-
- -

MI bundle support does not change the physical representations of - MachineBasicBlock and MachineInstr. All the MIs (including top level and - nested ones) are stored as sequential list of MIs. The "bundled" MIs are - marked with the 'InsideBundle' flag. A top level MI with the special BUNDLE - opcode is used to represent the start of a bundle. It's legal to mix BUNDLE - MIs with indiviual MIs that are not inside bundles nor represent bundles. -

- -

MachineInstr passes should operate on a MI bundle as a single unit. Member - methods have been taught to correctly handle bundles and MIs inside bundles. - The MachineBasicBlock iterator has been modified to skip over bundled MIs to - enforce the bundle-as-a-single-unit concept. An alternative iterator - instr_iterator has been added to MachineBasicBlock to allow passes to - iterate over all of the MIs in a MachineBasicBlock, including those which - are nested inside bundles. The top level BUNDLE instruction must have the - correct set of register MachineOperand's that represent the cumulative - inputs and outputs of the bundled MIs.

- -

Packing / bundling of MachineInstr's should be done as part of the register - allocation super-pass. More specifically, the pass which determines what - MIs should be bundled together must be done after code generator exits SSA - form (i.e. after two-address pass, PHI elimination, and copy coalescing). - Bundles should only be finalized (i.e. adding BUNDLE MIs and input and - output register MachineOperands) after virtual registers have been - rewritten into physical registers. This requirement eliminates the need to - add virtual register operands to BUNDLE instructions which would effectively - double the virtual register def and use lists.

- -
- -
- - -

- The "MC" Layer -

- - -
- -

-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. -

- -

-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. -

- - -

- The MCStreamer API -

- -
- -

-MCStreamer is best thought of as an assembler API. It is an abstract API which -is implemented 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. -

- -

-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 Code Emission phase of the code -generator lowers higher level LLVM IR and Machine* constructs down to the MC -layer, emitting directives through MCStreamer.

- -

-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. -

- -
- - -

- The MCContext class -

- -
- -

-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. -

- -
- - -

- The MCSymbol class -

- -
- -

-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. -

- -

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:

- -

-  foo:
-  bar:
-    .byte 4
-
- -

In this case, both the foo and bar symbols will have the same address.

- -
- - -

- The MCSection class -

- -
- -

-The MCSection class represents an object-file specific section. It is subclassed -by object file specific implementations (e.g. MCSectionMachO, -MCSectionCOFF, MCSectionELF) 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). -

- -
- - -

- The MCInst class -

- -
- -

-The MCInst class is a target-independent representation of an instruction. It -is a simple class (much more so than MachineInstr) -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. -

- -

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. -

- -
- -
- - -

- Target-independent code generation algorithms -

- - -
- -

This section documents the phases described in the - high-level design of the code generator. - It explains how they work and some of the rationale behind their design.

- - -

- Instruction Selection -

- -
- -

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.

- -

Portions of the DAG instruction selector are generated from the target - description (*.td) files. Our goal is for the entire instruction - selector to be generated from these .td files, though currently - there are still things that require custom C++ code.

- - -

- Introduction to SelectionDAGs -

- -
- -

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) optimizations may be - performed; ones which require extensive information about the instructions - efficiently supported by the target.

- -

The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the - SDNode class. The primary payload of the SDNode 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 include/llvm/CodeGen/SelectionDAGNodes.h - file.

- -

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 SDValue - class, which is a <SDNode, unsigned> pair, indicating the node - and result value being used, respectively. Each value produced by - an SDNode has an associated MVT (Machine Value Type) - indicating what the type of the value is.

- -

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 MVT::Other. - 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.

- -

A SelectionDAG has designated "Entry" and "Root" nodes. The Entry node is - always a marker node with an Opcode of ISD::EntryToken. 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.

- -

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 - legalize types and - legalize operations phases are - responsible for turning an illegal DAG into a legal DAG.

- -
- - -

- SelectionDAG Instruction Selection Process -

- -
- -

SelectionDAG-based instruction selection consists of the following steps:

- -
    -
  1. Build initial DAG — This stage - performs a simple translation from the input LLVM code to an illegal - SelectionDAG.
  2. - -
  3. Optimize SelectionDAG — This - stage performs simple optimizations on the SelectionDAG to simplify it, - and recognize meta instructions (like rotates - and div/rem pairs) for targets that support these meta - operations. This makes the resultant code more efficient and - the select instructions from DAG phase - (below) simpler.
  4. - -
  5. Legalize SelectionDAG Types - — This stage transforms SelectionDAG nodes to eliminate any types - that are unsupported on the target.
  6. - -
  7. Optimize SelectionDAG — The - SelectionDAG optimizer is run to clean up redundancies exposed by type - legalization.
  8. - -
  9. Legalize SelectionDAG Ops — - This stage transforms SelectionDAG nodes to eliminate any operations - that are unsupported on the target.
  10. - -
  11. Optimize SelectionDAG — The - SelectionDAG optimizer is run to eliminate inefficiencies introduced by - operation legalization.
  12. - -
  13. Select instructions from DAG — - 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.
  14. - -
  15. SelectionDAG Scheduling and Formation - — 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.
  16. -
- -

After all of these steps are complete, the SelectionDAG is destroyed and the - rest of the code generation passes are run.

- -

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 - need to configure your system - to add support for it).

- -
    -
  • -view-dag-combine1-dags displays the DAG after being built, - before the first optimization pass.
  • - -
  • -view-legalize-dags displays the DAG before Legalization.
  • - -
  • -view-dag-combine2-dags displays the DAG before the second - optimization pass.
  • - -
  • -view-isel-dags displays the DAG before the Select phase.
  • - -
  • -view-sched-dags displays the DAG before Scheduling.
  • -
- -

The -view-sunit-dags 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.

- -
- - -

- Initial SelectionDAG Construction -

- -
- -

The initial SelectionDAG is naïvely peephole expanded from the LLVM - input by the SelectionDAGLowering class in the - lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp 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 add turns into an SDNode add while a - getelementptr is expanded into the obvious arithmetic). This pass - requires target-specific hooks to lower calls, returns, varargs, etc. For - these features, the TargetLowering - interface is used.

- -
- - -

- SelectionDAG LegalizeTypes Phase -

- -
- -

The Legalize phase is in charge of converting a DAG to only use the types - that are natively supported by the target.

- -

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.

- -

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").

- -

A target implementation tells the legalizer which types are supported (and - which register class to use for them) by calling the - addRegisterClass method in its TargetLowering constructor.

- -
- - -

- SelectionDAG Legalize Phase -

- -
- -

The Legalize phase is in charge of converting a DAG to only use the - operations that are natively supported by the target.

- -

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").

- -

A target implementation tells the legalizer which operations are not - supported (and which of the above three actions to take) by calling the - setOperationAction method in its TargetLowering - constructor.

- -

Prior to the existence of the Legalize passes, we required that every target - selector 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.

- -
- - -

- - SelectionDAG Optimization Phase: the DAG Combiner - -

- -
- -

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 good and legal code).

- -

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:

- -

"Widening - integer arithmetic"
- Kevin Redwine and Norman Ramsey
- International Conference on Compiler Construction (CC) 2004

- -

"Effective - sign extension elimination"
- Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani
- Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design - and Implementation.

- -
- - -

- SelectionDAG Select Phase -

- -
- -

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:

- -
-
-%t1 = fadd float %W, %X
-%t2 = fmul float %t1, %Y
-%t3 = fadd float %t2, %Z
-
-
- -

This LLVM code corresponds to a SelectionDAG that looks basically like - this:

- -
-
-(fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
-
-
- -

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:

- -
-
-(FMADDS (FADDS W, X), Y, Z)
-
-
- -

The FMADDS instruction is a ternary instruction that multiplies its -first two operands and adds the third (as single-precision floating-point -numbers). The FADDS instruction is a simple binary single-precision -add instruction. To perform this pattern match, the PowerPC backend includes -the following instruction definitions:

- -
-
-def FMADDS : AForm_1<59, 29,
-                    (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
-                    "fmadds $FRT, $FRA, $FRC, $FRB",
-                    [(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
-                                           F4RC:$FRB))]>;
-def FADDS : AForm_2<59, 21,
-                    (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
-                    "fadds $FRT, $FRA, $FRB",
-                    [(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))]>;
-
-
- -

The portion of the instruction definition in bold indicates the pattern used - to match the instruction. The DAG operators - (like fmul/fadd) are defined in - the include/llvm/Target/TargetSelectionDAG.td file. " - F4RC" is the register class of the input and result values.

- -

The TableGen DAG instruction selector generator reads the instruction - patterns in the .td file and automatically builds parts of the - pattern matching code for your target. It has the following strengths:

- -
    -
  • At compiler-compiler time, it analyzes your instruction patterns and tells - you if your patterns make sense or not.
  • - -
  • 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 - immSExt16 and related tblgen classes in the PowerPC - backend.
  • - -
  • It knows several important identities for the patterns defined. For - example, it knows that addition is commutative, so it allows the - FMADDS pattern above to match "(fadd X, (fmul Y, Z))" as - well as "(fadd (fmul X, Y), Z)", without the target author having - to specially handle this case.
  • - -
  • 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 FMADDS case above, we didn't have to tell - tblgen 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 - F4RC has type 'f32'.
  • - -
  • 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 - "(not x)" operation is actually defined as a pattern fragment - that expands as "(xor x, -1)", since the SelectionDAG does not - have a native 'not' operation. Targets can define their own - short-hand fragments as they see fit. See the definition of - 'not' and 'ineg' for examples.
  • - -
  • 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: -
    -
    -
    -
    -// Arbitrary immediate support.  Implement in terms of LIS/ORI.
    -def : Pat<(i32 imm:$imm),
    -          (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
    -
    -
    -
    - 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 ORI ('or a 16-bit immediate') and - an LIS ('load 16-bit immediate, where the immediate is shifted to - the left 16 bits') instruction". To make this work, the - LO16/HI16 node transformations are used to manipulate - the input immediate (in this case, take the high or low 16-bits of the - immediate).
  • - -
  • 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.
  • -
- -

While it has many strengths, the system currently has some limitations, - primarily because it is a work in progress and is not yet finished:

- -
    -
  • Overall, there is no way to define or match SelectionDAG nodes that define - multiple values (e.g. SMUL_LOHI, LOAD, CALL, - etc). This is the biggest reason that you currently still have - to write custom C++ code for your instruction selector.
  • - -
  • 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 X86 - addressing mode, which are currently matched with custom C++ code). - In addition, we'll extend fragments so that a fragment can match multiple - different patterns.
  • - -
  • We don't automatically infer flags like isStore/isLoad yet.
  • - -
  • We don't automatically generate the set of supported registers and - operations for the Legalizer - yet.
  • - -
  • We don't have a way of tying in custom legalized nodes yet.
  • -
- -

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!

- -
- - -

- SelectionDAG Scheduling and Formation Phase -

- -
- -

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 MachineInstrs and the SelectionDAG is - destroyed.

- -

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.

- -
- - -

- Future directions for the SelectionDAG -

- -
- -
    -
  1. Optional function-at-a-time selection.
  2. - -
  3. Auto-generate entire selector from .td file.
  4. -
- -
- -
- - -

- SSA-based Machine Code Optimizations -

-

To Be Written

- - -

- Live Intervals -

- -
- -

Live Intervals are the ranges (intervals) where a variable is live. - They are used by some register allocator 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 spilled.

- - -

- Live Variable Analysis -

- -
- -

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 virtual register and register allocatable 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.

- -

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 return, then it's marked as using all live - out values in the function.

- -

PHI 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 PHI - node is defined before it's used. When a PHI node is encountered, - only the definition is handled, because the uses will be handled in other - basic blocks.

- -

For each PHI 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 PHI node and one of - the PHI node's operands is coming from the current basic block, then - the variable is marked as alive within the current basic block and all - of its predecessor basic blocks, until the basic block with the defining - instruction is encountered.

- -
- - -

- Live Intervals Analysis -

- -
- -

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 [1, N]. A - live interval is an interval [i, j), where 1 <= i <= j - < N, for which a variable is live.

- -

More to come...

- -
- -
- - -

- Register Allocation -

- -
- -

The Register Allocation problem consists in mapping a program - Pv, that can use an unbounded number of virtual registers, - to a program Pp 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 spilled virtuals.

- - - -

- How registers are represented in LLVM -

- -
- -

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 GenRegisterNames.inc file for that - architecture. For instance, by - inspecting lib/Target/X86/X86GenRegisterInfo.inc we see that the - 32-bit register EAX is denoted by 43, and the MMX register - MM0 is mapped to 65.

- -

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 EAX, AX and AL share the first eight - bits. These physical registers are marked as aliased in LLVM. Given a - particular architecture, you can check which registers are aliased by - inspecting its RegisterInfo.td file. Moreover, the method - MCRegisterInfo::getAliasSet(p_reg) returns an array containing - all the physical registers aliased to the register p_reg.

- -

Physical registers, in LLVM, are grouped in Register Classes. - 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 TargetRegisterClass objects. To discover if a virtual - register is compatible with a given physical, this code can be used:

- -
-
-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);
-}
-
-
- -

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 TargetRegsterInfo.td file. Just grep - for RegisterClass, 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 allocation order. See the definition of the GR8 register - class in lib/Target/X86/X86RegisterInfo.td for an example of this. -

- -

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 TargetRegisterInfo.td - 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 MachineRegisterInfo::createVirtualRegister(). This method - will return a new virtual register. Use an IndexedMap<Foo, - VirtReg2IndexFunctor> to hold information per virtual register. If you - need to enumerate all virtual registers, use the function - TargetRegisterInfo::index2VirtReg() to find the virtual register - numbers:

- -
-
-  for (unsigned i = 0, e = MRI->getNumVirtRegs(); i != e; ++i) {
-    unsigned VirtReg = TargetRegisterInfo::index2VirtReg(i);
-    stuff(VirtReg);
-  }
-
-
- -

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 MachineOperand::isRegister(). To obtain the integer code of - a register, use MachineOperand::getReg(). An instruction may define - or use a register. For instance, ADD reg:1026 := reg:1025 reg:1024 - defines the registers 1024, and uses registers 1025 and 1026. Given a - register operand, the method MachineOperand::isUse() informs if that - register is being used by the instruction. The - method MachineOperand::isDef() informs if that registers is being - defined.

- -

We will call physical registers present in the LLVM bitcode before register - allocation pre-colored registers. 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 implicitly defined, and - those explicitly defined. Explicitly defined registers are normal - operands, and can be accessed - with MachineInstr::getOperand(int)::getReg(). In order to check - which registers are implicitly defined by an instruction, use - the TargetInstrInfo::get(opcode)::ImplicitDefs, - where opcode 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 TargetInstrInfo::get(opcode)::ImplicitUses. 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.

- -
- - - -

- Mapping virtual registers to physical registers -

- -
- -

There are two ways to map virtual registers to physical registers (or to - memory slots). The first way, that we will call direct mapping, is - based on the use of methods of the classes TargetRegisterInfo, - and MachineOperand. The second way, that we will call indirect - mapping, relies on the VirtRegMap class in order to insert loads - and stores sending and getting values to and from memory.

- -

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 MachineOperand::setReg(p_reg). To insert a store instruction, - use TargetInstrInfo::storeRegToStackSlot(...), and to insert a - load instruction, use TargetInstrInfo::loadRegFromStackSlot.

- -

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 VirtRegMap::assignVirt2Phys(vreg, preg). In - order to map a certain virtual register to memory, - use VirtRegMap::assignVirt2StackSlot(vreg). This method will return - the stack slot where vreg's value will be located. If it is - necessary to map another virtual register to the same stack slot, - use VirtRegMap::assignVirt2StackSlot(vreg, stack_location). 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.

- -

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 RegAllocLinearScan::runOnMachineFunction - in lib/CodeGen/RegAllocLinearScan.cpp.

- -
- - -

- Handling two address instructions -

- -
- -

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 ADD %EAX, %EBX, in X86 is actually equivalent - to %EAX = %EAX + %EBX.

- -

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 TwoAddressInstructionPass 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 %a = ADD %b %c is converted to two instructions such as:

- -
-
-%a = MOVE %b
-%a = ADD %a %c
-
-
- -

Notice that, internally, the second instruction is represented as - ADD %a[def/use] %c. I.e., the register operand %a is both - used and defined by the instruction.

- -
- - -

- The SSA deconstruction phase -

- -
- -

An important transformation that happens during register allocation is called - the SSA Deconstruction Phase. 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.

- -

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 lib/CodeGen/PHIElimination.cpp. In order to invoke this pass, the - identifier PHIEliminationID must be marked as required in the code - of the register allocator.

- -
- - -

- Instruction folding -

- -
- -

Instruction folding is an optimization performed during register - allocation that removes unnecessary copy instructions. For instance, a - sequence of instructions such as:

- -
-
-%EBX = LOAD %mem_address
-%EAX = COPY %EBX
-
-
- -

can be safely substituted by the single instruction:

- -
-
-%EAX = LOAD %mem_address
-
-
- -

Instructions can be folded with - the TargetRegisterInfo::foldMemoryOperand(...) method. Care must be - taken when folding instructions; a folded instruction can be quite different - from the original - instruction. See LiveIntervals::addIntervalsForSpills - in lib/CodeGen/LiveIntervalAnalysis.cpp for an example of its - use.

- -
- - - -

- Built in register allocators -

- -
- -

The LLVM infrastructure provides the application developer with three - different register allocators:

- -
    -
  • Fast — 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.
  • - -
  • Basic — 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. - -
  • GreedyThe default allocator. This is a - highly tuned implementation of the Basic allocator that - incorporates global live range splitting. This allocator works hard - to minimize the cost of spill code. - -
  • PBQP — 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.
  • -
- -

The type of register allocator used in llc can be chosen with the - command line option -regalloc=...:

- -
-
-$ llc -regalloc=linearscan file.bc -o ln.s;
-$ llc -regalloc=fast file.bc -o fa.s;
-$ llc -regalloc=pbqp file.bc -o pbqp.s;
-
-
- -
- -
- - -

- Prolog/Epilog Code Insertion -

- -
- - -

- Compact Unwind -

- -
- -

Throwing an exception requires unwinding 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 compact unwind and requires just 4-bytes per - function.

- -

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 __TEXT,__unwind_info - 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 __TEXT,__unwind_info section. If we emit DWARF unwind info, - the __TEXT,__unwind_info section will contain the offset of the - FDE in the __TEXT,__eh_frame section in the final linked - image.

- -

For X86, there are three modes for the compact unwind encoding:

- -
-
Function with a Frame Pointer (EBP or RBP)
-

EBP/RBP-based frame, where EBP/RBP is pushed - onto the stack immediately after the return address, - then ESP/RSP is moved to EBP/RBP. Thus to - unwind, ESP/RSP is restored with the - current EBP/RBP value, then EBP/RBP 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 EBP-4 to EBP-1020 (RBP-8 - to RBP-1020). The offset (divided by 4 in 32-bit mode and 8 - in 64-bit mode) is encoded in bits 16-23 (mask: 0x00FF0000). - The registers saved are encoded in bits 0-14 - (mask: 0x00007FFF) as five 3-bit entries from the following - table:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Compact Numberi386 Registerx86-64 Regiser
1EBXRBX
2ECXR12
3EDXR13
4EDIR14
5ESIR15
6EBPRBP
- -
- -
Frameless with a Small Constant Stack Size (EBP - or RBP is not used as a frame pointer)
-

To return, a constant (encoded in the compact unwind encoding) is added - to the ESP/RSP. 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: 0x00FF0000). 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: 0x00001C00). Bits 0-9 - (mask: 0x000003FF) contain which registers were saved and - their order. (See - the encodeCompactUnwindRegistersWithoutFrame() function - in lib/Target/X86FrameLowering.cpp for the encoding - algorithm.)

- -
Frameless with a Large Constant Stack Size (EBP - or RBP is not used as a frame pointer)
-

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 "subl - $nnnnnn, %esp" in its prolog. The compact encoding contains the - offset to the $nnnnnn value in the function in bits 9-12 - (mask: 0x00001C00).

-
- -
- -
- - -

- Late Machine Code Optimizations -

-

To Be Written

- - -

- Code Emission -

- -
- -

The code emission step of code generation is responsible for lowering from -the code generator abstractions (like MachineFunction, MachineInstr, etc) down -to the abstractions used by the MC layer (MCInst, -MCStreamer, 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.

- -

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. -

- -

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:

- -
    -
  1. 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.
  2. - -
  3. Second, you need to implement an instruction printer for your target. The -instruction printer takes an MCInst and renders it to a -raw_ostream as text. Most of this is automatically generated from the .td file -(when you specify something like "add $dst, $src1, $src2" in the -instructions), but you need to implement routines to print operands.
  4. - -
  5. Third, you need to implement code that lowers a MachineInstr 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. -
  6. - -
- -

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.

- -
- - -

- VLIW Packetizer -

- -
- -

In a Very Long Instruction Word (VLIW) architecture, the compiler is - responsible for mapping instructions to functional-units available on - the architecture. To that end, the compiler creates groups of instructions - called packets or bundles. The VLIW packetizer in LLVM is - a target-independent mechanism to enable the packetization of machine - instructions.

- - - -

- Mapping from instructions to functional units -

- -
- -

Instructions in a VLIW target can typically be mapped to multiple functional -units. During the process of packetizing, the compiler must be able to reason -about whether an instruction can be added to a packet. This decision can be -complex since the compiler has to examine all possible mappings of instructions -to functional units. Therefore to alleviate compilation-time complexity, the -VLIW packetizer parses the instruction classes of a target and generates tables -at compiler build time. These tables can then be queried by the provided -machine-independent API to determine if an instruction can be accommodated in a -packet.

-
- - -

- - How the packetization tables are generated and used - -

- -
- -

The packetizer reads instruction classes from a target's itineraries and -creates a deterministic finite automaton (DFA) to represent the state of a -packet. A DFA consists of three major elements: inputs, states, and -transitions. The set of inputs for the generated DFA represents the instruction -being added to a packet. The states represent the possible consumption -of functional units by instructions in a packet. In the DFA, transitions from -one state to another occur on the addition of an instruction to an existing -packet. If there is a legal mapping of functional units to instructions, then -the DFA contains a corresponding transition. The absence of a transition -indicates that a legal mapping does not exist and that the instruction cannot -be added to the packet.

- -

To generate tables for a VLIW target, add TargetGenDFAPacketizer.inc -as a target to the Makefile in the target directory. The exported API provides -three functions: DFAPacketizer::clearResources(), -DFAPacketizer::reserveResources(MachineInstr *MI), and -DFAPacketizer::canReserveResources(MachineInstr *MI). These functions -allow a target packetizer to add an instruction to an existing packet and to -check whether an instruction can be added to a packet. See -llvm/CodeGen/DFAPacketizer.h for more information.

- -
- -
- -
- - -

- Implementing a Native Assembler -

- - -
- -

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.

- - -

Instruction Parsing

- -

To Be Written

- - - -

- Instruction Alias Processing -

- -
-

Once the instruction is parsed, it enters the MatchInstructionImpl function. -The MatchInstructionImpl function performs alias processing and then does -actual matching.

- -

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.

- - -

Mnemonic Aliases

- -
- -

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: -

- -
-
-def : MnemonicAlias<"cbw",     "cbtw">;
-def : MnemonicAlias<"smovq",   "movsq">;
-def : MnemonicAlias<"fldcww",  "fldcw">;
-def : MnemonicAlias<"fucompi", "fucomip">;
-def : MnemonicAlias<"ud2a",    "ud2">;
-
-
- -

... 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:

- -
-
-def : MnemonicAlias<"pushf", "pushfq">, Requires<[In64BitMode]>;
-def : MnemonicAlias<"pushf", "pushfl">, Requires<[In32BitMode]>;
-
-
- -

In this example, the mnemonic gets mapped into different a new one depending -on the current instruction set.

- -
- - -

Instruction Aliases

- -
- -

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: -

- -
-
-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)>;
-
-
- -

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:

- -
-
-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)>;
-
-
- -

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:

- -
-
-// 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)>;
-
-
- - -

Instruction aliases can also have a Requires clause to make them -subtarget specific.

- -

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.

- -
- -
- - -

Instruction Matching

- -

To Be Written

- -
- - -

- Target-specific Implementation Notes -

- - -
- -

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.

- - -

- Target Feature Matrix -

- -
- -

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:

- - - - - - - - - - - - - - - -
UnknownNo supportPartial SupportComplete Support
- -

Here is the table:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Target
FeatureARMCellSPUHexagonMBlazeMSP430MipsPTXPowerPCSparcX86XCore
is generally reliable
assembly parser
disassembler
inline asm
jit*
.o file writing
tail calls
segmented stacks *
- - -

Is Generally Reliable

- -
-

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.

-
- - -

Assembly Parser

- -
-

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.

- -
- - - -

Disassembler

- -
-

This box indicates whether the target supports the MCDisassembler API for -disassembling machine opcode bytes into MCInst's.

- -
- - -

Inline Asm

- -
-

This box indicates whether the target supports most popular inline assembly -constraints and modifiers.

- -
- - -

JIT Support

- -
-

This box indicates whether the target supports the JIT compiler through -the ExecutionEngine interface.

- -

The ARM backend has basic support for integer code -in ARM codegen mode, but lacks NEON and full Thumb support.

- -
- - -

.o File Writing

- -
- -

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.

- -

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).

- -
- - -

Tail Calls

- -
- -

This box indicates whether the target supports guaranteed tail calls. These -are calls marked "tail" and use the fastcc -calling convention. Please see the tail call section -more more details.

- -
- - -

Segmented Stacks

- -
- -

This box indicates whether the target supports segmented stacks. This -replaces the traditional large C stack with many linked segments. It -is compatible with the gcc -implementation used by the Go front end.

- -

Basic support exists on the X86 backend. Currently -vararg doesn't work and the object files are not marked the way the gold -linker expects, but simple Go programs can be built by dragonegg.

- -
- -
- - -

- Tail call optimization -

- -
- -

Tail call optimization, callee reusing the stack of the caller, is currently - supported on x86/x86-64 and PowerPC. It is performed if:

- -
    -
  • Caller and callee have the calling convention fastcc or - cc 10 (GHC call convention).
  • - -
  • The call is a tail call - in tail position (ret immediately follows call - and ret uses value of call or is void).
  • - -
  • Option -tailcallopt is enabled.
  • - -
  • Platform specific constraints are met.
  • -
- -

x86/x86-64 constraints:

- -
    -
  • No variable argument lists are used.
  • - -
  • On x86-64 when generating GOT/PIC code only module-local calls (visibility - = hidden or protected) are supported.
  • -
- -

PowerPC constraints:

- -
    -
  • No variable argument lists are used.
  • - -
  • No byval parameters are used.
  • - -
  • On ppc32/64 GOT/PIC only module-local calls (visibility = hidden or protected) are supported.
  • -
- -

Example:

- -

Call as llc -tailcallopt test.ll.

- -
-
-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
-}
-
-
- -

Implications of -tailcallopt:

- -

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 fastcc 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.

- -
- -

- Sibling call optimization -

- -
- -

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 -tailcallopt option - is not specified.

- -

Sibling call optimization is currently performed on x86/x86-64 when the - following constraints are met:

- -
    -
  • Caller and callee have the same calling convention. It can be either - c or fastcc. - -
  • The call is a tail call - in tail position (ret immediately follows call - and ret uses value of call or is void).
  • - -
  • Caller and callee have matching return type or the callee result is not - used. - -
  • 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. -
- -

Example:

-
-
-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
-}
-
-
- -
- -

- The X86 backend -

- -
- -

The X86 code generator lives in the lib/Target/X86 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.

- - -

- X86 Target Triples supported -

- -
- -

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.

- -
    -
  • i686-pc-linux-gnu — Linux
  • - -
  • i386-unknown-freebsd5.3 — FreeBSD 5.3
  • - -
  • i686-pc-cygwin — Cygwin on Win32
  • - -
  • i686-pc-mingw32 — MingW on Win32
  • - -
  • i386-pc-mingw32msvc — MingW crosscompiler on Linux
  • - -
  • i686-apple-darwin* — Apple Darwin on X86
  • - -
  • x86_64-unknown-linux-gnu — Linux
  • -
- -
- - -

- X86 Calling Conventions supported -

- - -
- -

The following target-specific calling conventions are known to backend:

- -
    -
  • x86_StdCall — stdcall calling convention seen on Microsoft - Windows platform (CC ID = 64).
  • -
  • x86_FastCall — fastcall calling convention seen on Microsoft - Windows platform (CC ID = 65).
  • -
  • x86_ThisCall — 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).
  • -
- -
- - -

- Representing X86 addressing modes in MachineInstrs -

- -
- -

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):

- -
-
-SegmentReg: Base + [1,2,4,8] * IndexReg + Disp32
-
-
- -

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 - 'mov' has the following MachineOperands in this order:

- -
-
-Index:        0     |    1        2       3           4          5
-Meaning:   DestReg, | BaseReg,  Scale, IndexReg, Displacement Segment
-OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg,   SignExtImm  PhysReg
-
-
- -

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.

- -
- - -

- X86 address spaces supported -

- -
- -

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.

- -

While these address spaces may seem similar to TLS via the - thread_local keyword, and often use the same underlying hardware, - there are some fundamental differences.

- -

The thread_local 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 thread_local keyword is target-independent at the LLVM IR - level (though LLVM doesn't yet have implementations of it for some - configurations).

- -

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).

- -

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.

- -
- - -

- Instruction naming -

- -
- -

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:

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

- The PowerPC backend -

- -
- -

The PowerPC code generator lives in the lib/Target/PowerPC directory. The - code generation is retargetable to several variations or subtargets of - the PowerPC ISA; including ppc32, ppc64 and altivec.

- - -

- LLVM PowerPC ABI -

- -
- -

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 PowerPC ABI. 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.

- -
- - -

- Frame Layout -

- -
- -

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.

- -

An invocation frame is laid out as follows (low memory at top);

- - - - - - - - - - - - - - - - - - - - - - - -
Linkage

Parameter area

Dynamic area

Locals area

Saved registers area


Previous Frame

- -

The linkage 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.

- -

32 bit linkage area

- - - - - - - - - - - - - - - - - - - - - - - - - - -
0Saved SP (r1)
4Saved CR
8Saved LR
12Reserved
16Reserved
20Saved FP (r31)
- -

64 bit linkage area

- - - - - - - - - - - - - - - - - - - - - - - - - - -
0Saved SP (r1)
8Saved CR
16Saved LR
24Reserved
32Reserved
40Saved FP (r31)
- -

The parameter area 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.)

- -

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.

- -

The dynamic area 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.

- -

The locals area is where the llvm compiler reserves space for local - variables.

- -

The saved registers area is where the llvm compiler spills callee - saved registers on entry to the callee.

- -
- - -

- Prolog/Epilog -

- -
- -

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.

- -
- - -

- Dynamic Allocation -

- -
- -

TODO - More to come.

- -
- -
- - -

- The PTX backend -

- -
- -

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.

- -

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.

- -

Code Generator Options:

- - - - - - - - - - - - - - - - - -
OptionDescription
doubleIf enabled, the map_f64_to_f32 directive is - disabled in the PTX output, allowing native double-precision - arithmetic
no-fmaDisable generation of Fused-Multiply Add - instructions, which may be beneficial for some devices
smxy / computexySet shader model/compute capability to x.y, - e.g. sm20 or compute13
- -

Working:

-
    -
  • Arithmetic instruction selection (including combo FMA)
  • -
  • Bitwise instruction selection
  • -
  • Control-flow instruction selection
  • -
  • Function calls (only on SM 2.0+ and no return arguments)
  • -
  • Addresses spaces (0 = global, 1 = constant, 2 = local, 4 = - shared)
  • -
  • Thread synchronization (bar.sync)
  • -
  • Special register reads ([N]TID, [N]CTAID, PMx, CLOCK, etc.)
  • -
- -

In Progress:

-
    -
  • Robust call instruction selection
  • -
  • Stack frame allocation
  • -
  • Device-specific instruction scheduling optimizations
  • -
- - -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-15 13:22:36 -0700 (Sun, 15 Apr 2012) $ -
- - - diff --git a/cpp/llvm/docs/CodingStandards.html b/cpp/llvm/docs/CodingStandards.html deleted file mode 100644 index 106973f8..00000000 --- a/cpp/llvm/docs/CodingStandards.html +++ /dev/null @@ -1,1568 +0,0 @@ - - - - - - LLVM Coding Standards - - - -

- LLVM Coding Standards -

- -
    -
  1. Introduction
  2. -
  3. Mechanical Source Issues -
      -
    1. Source Code Formatting -
        -
      1. Commenting
      2. -
      3. Comment Formatting
      4. -
      5. #include Style
      6. -
      7. Source Code Width
      8. -
      9. Use Spaces Instead of Tabs
      10. -
      11. Indent Code Consistently
      12. -
    2. -
    3. Compiler Issues -
        -
      1. Treat Compiler Warnings Like - Errors
      2. -
      3. Write Portable Code
      4. -
      5. Do not use RTTI or Exceptions
      6. -
      7. Do not use Static Constructors
      8. -
      9. Use of class/struct Keywords
      10. -
    4. -
  4. -
  5. Style Issues -
      -
    1. The High-Level Issues -
        -
      1. A Public Header File is a - Module
      2. -
      3. #include as Little as Possible
      4. -
      5. Keep "internal" Headers - Private
      6. -
      7. Use Early Exits and continue to Simplify - Code
      8. -
      9. Don't use else after a - return
      10. -
      11. Turn Predicate Loops into Predicate - Functions
      12. -
    2. -
    3. The Low-Level Issues -
        -
      1. Name Types, Functions, Variables, and Enumerators Properly
      2. -
      3. Assert Liberally
      4. -
      5. Do not use 'using namespace std'
      6. -
      7. Provide a virtual method anchor for - classes in headers
      8. -
      9. Don't evaluate end() every time through a - loop
      10. -
      11. #include <iostream> is - forbidden
      12. -
      13. Use raw_ostream
      14. -
      15. Avoid std::endl
      16. -
    4. - -
    5. Microscopic Details -
        -
      1. Spaces Before Parentheses
      2. -
      3. Prefer Preincrement
      4. -
      5. Namespace Indentation
      6. -
      7. Anonymous Namespaces
      8. -
    6. - - -
  6. -
  7. See Also
  8. -
- -
-

Written by Chris Lattner

-
- - - -

Introduction

- - -
- -

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 are -particularly important for large-scale code bases that follow a library-based -design (like LLVM).

- -

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:

- -
- -

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.

- -
- -

Note that some code bases (e.g. libc++) have really good reasons to deviate -from the coding standards. In the case of libc++, this is because the naming -and other conventions are dictated by the C++ standard. If you think there is -a specific good reason to deviate from the standards here, please bring it up -on the LLVMdev mailing list.

- -

There are some conventions that are not uniformly followed in the code base -(e.g. the naming convention). This is because they are relatively new, and a -lot of code was written before they were put in place. Our long term goal is -for the entire codebase to follow the convention, but we explicitly do -not want patches that do large-scale reformating of existing code. OTOH, -it is reasonable to rename the methods of a class if you're about to change it -in some other way. Just do the reformating as a separate commit from the -functionality change.

- -

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 Chris.

- -
- - -

- Mechanical Source Issues -

- - -
- - -

- Source Code Formatting -

- -
- - -

- Commenting -

- -
- -

Comments are one critical part of readability and maintainability. Everyone -knows they should comment their code, and so should you. When writing comments, -write them as English prose, which means they should use proper capitalization, -punctuation, etc. Aim to describe what a code is trying to do and why, not -"how" it does it at a micro level. Here are a few critical things to -document:

- -
File Headers
- -
- -

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 the tree. The standard header looks like this:

- -
-
-//===-- 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.
-//
-//===----------------------------------------------------------------------===//
-
-
- -

A few things to note about this particular format: The "-*- C++ --*-" string on the first line is there to tell Emacs that the source file -is a C++ file, not a C file (Emacs assumes .h files are C files by default). -Note that this tag is not necessary in .cpp files. The name of the file is also -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.

- -

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.

- -

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.

- -
- -
Class overviews
- -

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 and how it works. Every non-trivial class is expected to have a -doxygen comment block.

- - -
Method information
- -
- -

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.

- -

Good things to talk about here are what happens when something unexpected -happens: does the method return null? Abort? Format your hard disk?

- -
- -
- - -

- Comment Formatting -

- -
- -

In general, prefer C++ style (//) 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 (/* */) comments however:

- -
    -
  1. When writing C code: Obviously if you are writing C code, use C style - comments.
  2. -
  3. When writing a header file that may be #included by a C source - file.
  4. -
  5. When writing a source file that is used by a tool that only accepts C - style comments.
  6. -
- -

To comment out a large block of code, use #if 0 and #endif. -These nest properly and are better behaved in general than C style comments.

- -
- - -

- #include Style -

- -
- -

Immediately after the header file comment (and -include guards if working on a header file), the minimal list of #includes required by the -file should be listed. We prefer these #includes to be listed in this -order:

- -
    -
  1. Main Module Header
  2. -
  3. Local/Private Headers
  4. -
  5. llvm/*
  6. -
  7. llvm/Analysis/*
  8. -
  9. llvm/Assembly/*
  10. -
  11. llvm/Bitcode/*
  12. -
  13. llvm/CodeGen/*
  14. -
  15. ...
  16. -
  17. Support/*
  18. -
  19. Config/*
  20. -
  21. System #includes
  22. -
- -

and each category should be sorted by name.

- -

The "Main Module Header" file applies to .cpp files -which implement an interface defined by a .h file. This #include -should always be included first regardless of where it lives on the file -system. By including a header file first in the .cpp files that implement the -interfaces, we ensure that the header does not have any hidden dependencies -which are not explicitly #included in the header, but should be. It is also a -form of documentation in the .cpp file to indicate where the interfaces it -implements are defined.

- -
- - -

- Source Code Width -

- -
- -

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.

- -

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).

- -

This is one of many contentious issues in coding standards, but it is not up -for debate.

- -
- - -

- Use Spaces Instead of Tabs -

- -
- -

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.

- -

As always, follow the Golden Rule above: follow the -style of existing code if you are modifying and extending it. If you like four -spaces of indentation, DO NOT 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.

- -
- - -

- Indent Code Consistently -

- -
- -

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.

- -
- -
- - -

- Compiler Issues -

- -
- - -

- Treat Compiler Warnings Like Errors -

- -
- -

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.

- -

It is not possible to prevent all warnings from all compilers, nor is it -desirable. Instead, pick a standard compiler (like gcc) that provides -a good thorough set of warnings, and stick to it. At least in the case of -gcc, 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:

- -
-
-if (V = getValue()) {
-  ...
-}
-
-
- -

gcc will warn me that I probably want to use the == -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:

- -
-
-if ((V = getValue())) {
-  ...
-}
-
-
- -

which shuts gcc up. Any gcc warning that annoys you can -be fixed by massaging the code appropriately.

- -
- - -

- Write Portable Code -

- -
- -

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.

- -

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.

- -
- - -

-Do not use RTTI or Exceptions -

-
- -

In an effort to reduce code and executable size, LLVM does not use RTTI -(e.g. dynamic_cast<>) or exceptions. These two language features -violate the general C++ principle of "you only pay for what you use", -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.

- -

That said, LLVM does make extensive use of a hand-rolled form of RTTI that -use templates like isa<>, -cast<>, and dyn_cast<>. This form of RTTI is -opt-in and can be added to any class. It is also substantially more efficient -than dynamic_cast<>.

- -
- - -

-Do not use Static Constructors -

-
- -

Static constructors and destructors (e.g. global variables whose types have -a constructor or destructor) should not be added to the code base, and should be -removed wherever possible. Besides well known problems -where the order of initialization is undefined between globals in different -source files, the entire concept of static constructors is at odds with the -common use case of LLVM as a library linked into a larger application.

- -

Consider the use of LLVM as a JIT linked into another application (perhaps -for OpenGL, custom languages, -shaders in -movies, etc). Due to the design of static constructors, they must be -executed at startup time of the entire application, regardless of whether or -how LLVM is used in that larger application. There are two problems with -this:

- -
    -
  1. The time to run the static constructors impacts startup time of - applications — a critical time for GUI apps, among others.
  2. - -
  3. The static constructors cause the app to pull many extra pages of memory - off the disk: both the code for the constructor in each .o 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.
  4. -
- -

We would really like for there to be zero cost for linking in an additional -LLVM target or other library into an application, but static constructors -violate this goal.

- -

That said, LLVM unfortunately does contain static constructors. It would be -a great project for someone to purge all -static constructors from LLVM, and then enable the --Wglobal-constructors warning flag (when building with Clang) to ensure -we do not regress in the future. -

- -
- - -

-Use of class and struct Keywords -

-
- -

In C++, the class and struct keywords can be used almost -interchangeably. The only difference is when they are used to declare a class: -class makes all members private by default while struct makes -all members public by default.

- -

Unfortunately, not all compilers follow the rules and some will generate -different symbols based on whether class or struct was used to -declare the symbol. This can lead to problems at link time.

- -

So, the rule for LLVM is to always use the class keyword, unless -all members are public and the type is a C++ -POD type, in -which case struct is allowed.

- -
- -
- -
- - -

- Style Issues -

- - -
- - -

- The High-Level Issues -

- - -
- - -

- A Public Header File is a Module -

- -
- -

C++ doesn't do too well in the modularity department. There is no real -encapsulation or data hiding (unless you use expensive protocol classes), but it -is what we have to work with. When you write a public header file (in the LLVM -source tree, they live in the top level "include" directory), you are -defining a module of functionality.

- -

Ideally, modules should be completely independent of each other, and their -header files should only #include the absolute minimum number of -headers possible. A module is not just a class, a function, or a -namespace: it's -a collection of these that defines an interface. This interface may be -several functions, classes, or data structures, but the important issue is how -they work together.

- -

In general, a module should be implemented by one or more .cpp -files. Each of these .cpp 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.

- -
- - -

- #include as Little as Possible -

- -
- -

#include hurts compile time performance. Don't do it unless you -have to, especially in header files.

- -

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 #include 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 -#include'ing speeds up compilation.

- -

It is easy to try to go too overboard on this recommendation, however. You -must 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 first in the -implementation file (as mentioned above). This way there won't be any hidden -dependencies that you'll find out about later.

- -
- - -

- Keep "Internal" Headers Private -

- -
- -

Many modules have a complex implementation that causes them to use more than -one implementation (.cpp) 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!

- -

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.

- -

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.

- -
- - -

- Use Early Exits and continue to Simplify Code -

- -
- -

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 continue keyword in long loops. As an example of using -an early exit from a function, consider this "bad" code:

- -
-
-Value *DoSomething(Instruction *I) {
-  if (!isa<TerminatorInst>(I) &&
-      I->hasOneUse() && SomeOtherThing(I)) {
-    ... some long code ....
-  }
-  
-  return 0;
-}
-
-
- -

This code has several problems if the body of the 'if' is large. -When you're looking at the top of the function, it isn't immediately clear that -this only does interesting things with non-terminator instructions, and -only applies to things with the other predicates. Second, it is relatively -difficult to describe (in comments) why these predicates are important because -the if statement makes it difficult to lay out the comments. Third, -when you're deep within the body of the code, it is indented an extra level. -Finally, when reading the top of the function, it isn't clear what the result is -if the predicate isn't true; you have to read to the end of the function to know -that it returns null.

- -

It is much preferred to format the code like this:

- -
-
-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 ....
-}
-
-
- -

This fixes these problems. A similar problem frequently happens in for -loops. A silly example is something like this:

- -
-
-  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) {
-        ...
-      }
-    }
-  }
-
-
- -

When you have very, very small loops, this sort of structure is fine. But if -it exceeds more than 10-15 lines, it becomes difficult for people to read and -understand at a glance. The problem with this sort of code is that it gets very -nested very quickly. Meaning that the reader of the code has to keep a lot of -context in their brain to remember what is going immediately on in the loop, -because they don't know if/when the if conditions will have elses etc. -It is strongly preferred to structure the loop like this:

- -
-
-  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;
-
-    ...
-  }
-
-
- -

This has all the benefits of using early exits for functions: it reduces -nesting of the loop, it makes it easier to describe why the conditions are true, -and it makes it obvious to the reader that there is no else coming up -that they have to push context into their brain for. If a loop is large, this -can be a big understandability win.

- -
- - -

- Don't use else after a return -

- -
- -

For similar reasons above (reduction of indentation and easier reading), -please do not use 'else' or 'else if' after something that -interrupts control flow — like return, break, -continue, goto, etc. For example, this is bad:

- -
-
-  case 'J': {
-    if (Signed) {
-      Type = Context.getsigjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_sigjmp_buf;
-        return QualType();
-      } else {
-        break;
-      }
-    } else {
-      Type = Context.getjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_jmp_buf;
-        return QualType();
-      } else {
-        break;
-      }
-    }
-  }
-  }
-
-
- -

It is better to write it like this:

- -
-
-  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();
-      }
-    }
-    break;
-
-
- -

Or better yet (in this case) as:

- -
-
-  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();
-    }
-    break;
-
-
- -

The idea is to reduce indentation and the amount of code you have to keep -track of when reading the code.

- -
- - -

- Turn Predicate Loops into Predicate Functions -

- -
- -

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:

- -
-
-  bool FoundFoo = false;
-  for (unsigned i = 0, e = BarList.size(); i != e; ++i)
-    if (BarList[i]->isFoo()) {
-      FoundFoo = true;
-      break;
-    }
-    
-  if (FoundFoo) {
-    ...
-  }
-
-
- -

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 static) that uses -early exits to compute the predicate. We prefer -the code to be structured like this:

- -
-
-/// 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;
-}
-...
-
-  if (ListContainsFoo(BarList)) {
-    ...
-  }
-
-
- -

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 forces you to pick a name 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.

- -
- -
- - -

- The Low-Level Issues -

- - -
- - -

- - Name Types, Functions, Variables, and Enumerators Properly - -

- -
- -

Poorly-chosen names can mislead the reader and cause bugs. We cannot stress -enough how important it is to use descriptive 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.

- -

In general, names should be in camel case (e.g. TextFileReader -and isLValue()). Different kinds of declarations have different -rules:

- -
    -
  • Type names (including classes, structs, enums, typedefs, etc) - should be nouns and start with an upper-case letter (e.g. - TextFileReader).

  • - -
  • Variable names should be nouns (as they represent state). The - name should be camel case, and start with an upper case letter (e.g. - Leader or Boats).

  • - -
  • Function names 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. openFile() - or isFoo()).

  • - -
  • Enum declarations (e.g. enum Foo {...}) 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 Kind suffix - (e.g. ValueKind).

  • - -
  • Enumerators (e.g. enum { Foo, Bar }) and public member - variables 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, enum ValueKind { ... }; may contain - enumerators like VK_Argument, VK_BasicBlock, etc. - Enumerators that are just convenience constants are exempt from the - requirement for a prefix. For instance:

    - -
    -
    -enum {
    -  MaxSize = 42,
    -  Density = 12
    -};
    -
    -
    -
  • - -
- -

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. begin(), -push_back(), and empty()).

- -

Here are some examples of good and bad names:

- -
-
-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.
-  ...
-}
-
-
- -
- - - -

- Assert Liberally -

- -
- -

Use the "assert" 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 "<cassert>" header file is probably already -included by the header files you are using, so it doesn't cost anything to use -it.

- -

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:

- -
-
-inline Value *getOperand(unsigned i) { 
-  assert(i < Operands.size() && "getOperand() out of range!");
-  return Operands[i]; 
-}
-
-
- -

Here are more examples:

- -
-
-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!");
-
-
- -

You get the idea.

- -

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:

- -
-
-assert(0 && "Some helpful error message");
-
-
- -

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.

- -
-
-assert(0 && "Some helpful error message");
-// Not reached
-return 0;
-
-
- -

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:

- -
-
-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");
-
-
- -

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:

- -
-
-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");
-
-
- - -
- - -

- Do Not Use 'using namespace std' -

- -
- -

In LLVM, we prefer to explicitly prefix all identifiers from the standard -namespace with an "std::" prefix, rather than rely on -"using namespace std;".

- -

In header files, adding a 'using namespace XXX' directive pollutes -the namespace of any source file that #includes the header. This is -clearly a bad thing.

- -

In implementation files (e.g. .cpp files), the rule is more of a stylistic -rule, but is still important. Basically, using explicit namespace prefixes -makes the code clearer, because it is immediately obvious what facilities -are being used and where they are coming from. And more portable, 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 std namespace. As -such, we never use 'using namespace std;' in LLVM.

- -

The exception to the general rule (i.e. it's not an exception for -the std namespace) is for implementation files. For example, all of -the code in the LLVM project implements code that lives in the 'llvm' namespace. -As such, it is ok, and actually clearer, for the .cpp files to have a -'using namespace llvm;' directive at the top, after the -#includes. 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 .cpp file that implements -code in any namespace may use that namespace (and its parents'), but should not -use any others.

- -
- - -

- - Provide a Virtual Method Anchor for Classes in Headers - -

- -
- -

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 .o file -that #includes the header, bloating .o file sizes and -increasing link times.

- -
- - -

- Don't evaluate end() every time through a loop -

- -
- -

Because C++ doesn't have a standard "foreach" loop (though it can be -emulated with macros and may be coming in C++'0x) we end up writing a lot of -loops that manually iterate from begin to end on a variety of containers or -through other data structures. One common mistake is to write a loop in this -style:

- -
-
-  BasicBlock *BB = ...
-  for (BasicBlock::iterator I = BB->begin(); I != BB->end(); ++I)
-     ... use I ...
-
-
- -

The problem with this construct is that it evaluates "BB->end()" -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:

- -
-
-  BasicBlock *BB = ...
-  for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I)
-     ... use I ...
-
-
- -

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 -"BB->end()" 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.

- -

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: "SomeMap[x]->end()" 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.

- -

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.

- -

While the second form of the loop is a few extra keystrokes, we do strongly -prefer it.

- -
- - -

- #include <iostream> is Forbidden -

- -
- -

The use of #include <iostream> in library files is -hereby forbidden, because many common implementations -transparently inject a static constructor into -every translation unit that includes it.

- -

Note that using the other stream headers (<sstream> for -example) is not problematic in this regard — -just <iostream>. However, raw_ostream provides various -APIs that are better performing for almost every use than std::ostream -style APIs. Therefore new code should always -use raw_ostream for writing, or -the llvm::MemoryBuffer API for reading files.

- -
- - - -

- Use raw_ostream -

- -
- -

LLVM includes a lightweight, simple, and efficient stream implementation -in llvm/Support/raw_ostream.h, which provides all of the common -features of std::ostream. All new code should use raw_ostream -instead of ostream.

- -

Unlike std::ostream, raw_ostream is not a template and can -be forward declared as class raw_ostream. Public headers should -generally not include the raw_ostream header, but use forward -declarations and constant references to raw_ostream instances.

- -
- - - -

- Avoid std::endl -

- -
- -

The std::endl modifier, when used with iostreams outputs a -newline to the output stream specified. In addition to doing this, however, it -also flushes the output stream. In other words, these are equivalent:

- -
-
-std::cout << std::endl;
-std::cout << '\n' << std::flush;
-
-
- -

Most of the time, you probably have no reason to flush the output stream, so -it's better to use a literal '\n'.

- -
- -
- - -

- Microscopic Details -

- - -
- -

This section describes preferred low-level formatting guidelines along with -reasoning on why we prefer them.

- - -

- Spaces Before Parentheses -

- -
- -

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:

- -
-
-if (x) ...
-for (i = 0; i != 100; ++i) ...
-while (llvm_rocks) ...
-
-somefunc(42);
-assert(3 != 4 && "laws of math are failing me");
-  
-a = foo(42, 92) + bar(x);
-
-
- -

and this is bad:

- -
-
-if(x) ...
-for(i = 0; i != 100; ++i) ...
-while(llvm_rocks) ...
-
-somefunc (42);
-assert (3 != 4 && "laws of math are failing me");
-  
-a = foo (42, 92) + bar (x);
-
-
- -

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:

- -
-
-a = foo ((42, 92) + bar) (x);
-
-
- -

when skimming through the code. By avoiding a space in a function, we avoid -this misinterpretation.

- -
- - -

- Prefer Preincrement -

- -
- -

Hard fast rule: Preincrement (++X) may be no slower than -postincrement (X++) and could very well be a lot faster than it. Use -preincrementation whenever possible.

- -

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.

- -
- - -

- Namespace Indentation -

- -
- -

-In general, we strive to reduce indentation wherever possible. This is useful -because we want code to fit into 80 columns 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. -

- -

-If a namespace definition is small and easily fits on a screen (say, -less than 35 lines of code), then you should indent its body. Here's an -example: -

- -
-
-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
-    };
-  }
-}
-
-
- -

Since the body is small, indenting adds value because it makes it very clear -where the namespace starts and ends, and it is easy to take the whole thing in -in one "gulp" when reading the code. If the blob of code in the namespace is -larger (as it typically is in a header in the llvm or clang namespaces), do not -indent the code, and add a comment indicating what namespace is being closed. -For example:

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

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 not indent -the contents of the namespace.

- -
- - -

- Anonymous Namespaces -

- -
- -

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.

- -

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.

- -

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:

- -
-
-namespace {
-  class StringSort {
-  ...
-  public:
-    StringSort(...)
-    bool operator<(const char *RHS) const;
-  };
-} // end anonymous namespace
-
-static void Helper() { 
-  ... 
-}
-
-bool StringSort::operator<(const char *RHS) const {
-  ...
-}
-
-
-
- -

This is bad:

- - -
-
-namespace {
-class StringSort {
-...
-public:
-  StringSort(...)
-  bool operator<(const char *RHS) const;
-};
-
-void Helper() { 
-  ... 
-}
-
-bool StringSort::operator<(const char *RHS) const {
-  ...
-}
-
-} // end anonymous namespace
-
-
-
- - -

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. -

- -
- -
- -
- - -

- See Also -

- - -
- -

A lot of these comments and recommendations have been culled for other -sources. Two particularly important books for our work are:

- -
    - -
  1. Effective -C++ by Scott Meyers. Also -interesting and useful are "More Effective C++" and "Effective STL" by the same -author.
  2. - -
  3. Large-Scale C++ Software Design by John Lakos
  4. - -
- -

If you get some free time, and you haven't read them: do so, you might learn -something.

- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/CommandGuide/FileCheck.pod b/cpp/llvm/docs/CommandGuide/FileCheck.pod deleted file mode 100644 index 2662cc01..00000000 --- a/cpp/llvm/docs/CommandGuide/FileCheck.pod +++ /dev/null @@ -1,245 +0,0 @@ - -=pod - -=head1 NAME - -FileCheck - Flexible pattern matching file verifier - -=head1 SYNOPSIS - -B I [I<--check-prefix=XXX>] [I<--strict-whitespace>] - -=head1 DESCRIPTION - -B 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 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 - -FileCheck searches the contents of I 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 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, -let's look at the rest of the .ll file (after the RUN line): - - define void @sub1(i32* %p, i32 %v) { - entry: - ; CHECK: sub1: - ; CHECK: subl - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) - ret void - } - - define void @inc4(i64* %p) { - entry: - ; CHECK: inc4: - ; CHECK: incq - %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: | FileCheck %s -check-prefix=X32> - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X64> - - 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 - ; X32: pinsrd_1: - ; X32: pinsrd $1, 4(%esp), %xmm0 - - ; X64: pinsrd_1: - ; X64: 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 "-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 - - ; CHECK: t2: - ; CHECK: movl 8(%esp), %eax - ; CHECK-NEXT: movapd (%eax), %xmm0 - ; CHECK-NEXT: movhpd 12(%esp), %xmm0 - ; CHECK-NEXT: movl 4(%esp), %eax - ; CHECK-NEXT: movapd %xmm0, (%eax) - ; CHECK-NEXT: 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 - ; CHECK: @coerce_offset0 - ; CHECK-NOT: load - ; CHECK: 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 {{[0-9]+}}(%esp), {{%xmm[0-7]}} - -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 [[REGISTER:%[a-z]+]] - ; CHECK: andw {{.*}}[REGISTER]] - -The first check line matches a regex (B<%[a-z]+>) and captures it into -the variable "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 B<[[ ]]> pairs, are named, and their names can be -formed with the regex "B<[a-zA-Z_][a-zA-Z0-9_]*>". 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 -"B", 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). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/Makefile b/cpp/llvm/docs/CommandGuide/Makefile deleted file mode 100644 index 3f9f60b8..00000000 --- a/cpp/llvm/docs/CommandGuide/Makefile +++ /dev/null @@ -1,103 +0,0 @@ -##===- 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 $(DST_MAN_DIR)llvm-build.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)' diff --git a/cpp/llvm/docs/CommandGuide/bugpoint.pod b/cpp/llvm/docs/CommandGuide/bugpoint.pod deleted file mode 100644 index 31db62fe..00000000 --- a/cpp/llvm/docs/CommandGuide/bugpoint.pod +++ /dev/null @@ -1,186 +0,0 @@ -=pod - -=head1 NAME - -bugpoint - automatic test case reduction tool - -=head1 SYNOPSIS - -B [I] [I] [I] B<--args> -I - -=head1 DESCRIPTION - -B 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, as well as -advice for using bugpoint, see F in the LLVM -distribution. - -=head1 OPTIONS - -=over - -=item B<--additional-so> F - -Load the dynamic shared object F 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 - -Pass all arguments specified after -args to the test program whenever it runs. -Note that if any of the I start with a '-', you should use: - - bugpoint [bugpoint args] --args -- [program args] - -The "--" right after the B<--args> option tells B to consider any -options starting with C<-> to be part of the B<--args> option, not as options to -B itself. - -=item B<--tool-args> I - -Pass all arguments specified after --tool-args to the LLVM tool under test -(B, B, 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 to consider any -options starting with C<-> to be part of the B<--tool-args> option, not as -options to B itself. (See B<--args>, above.) - -=item B<--safe-tool-args> I - -Pass all arguments specified after B<--safe-tool-args> to the "safe" execution -tool. - -=item B<--gcc-tool-args> I - -Pass all arguments specified after B<--gcc-tool-args> to the invocation of -B. - -=item B<--opt-args> I - -Pass all arguments specified after B<--opt-args> to the invocation of B. - -=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 uses these passes internally when attempting to -reduce test programs. If you're trying to find a bug in one of these passes, -B 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. - -=item B<-help> - -Print a summary of command line options. - -=item B<--input> F - -Open F and redirect the standard input of the test program, whenever -it runs, to come from that file. - -=item B<--load> F - -Load the dynamic object F into B 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 - -Specifies an upper limit on memory usage of the optimization and codegen. Set -to zero to disable the limit. - -=item B<--output> F - -Whenever the test program produces output on its standard output stream, it -should match the contents of F (the "reference output"). If you -do not use this option, B will attempt to generate a reference output -by compiling the program with the "safe" backend and running it. - -=item B<--profile-info-file> F - -Profile file loaded by B<--profile-loader>. - -=item B<--run-{int,jit,llc,cbe,custom}> - -Whenever the test program is compiled, B 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 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 - -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 - -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 - -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 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 - -=head1 AUTHOR - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/html/manpage.css b/cpp/llvm/docs/CommandGuide/html/manpage.css deleted file mode 100644 index b2003434..00000000 --- a/cpp/llvm/docs/CommandGuide/html/manpage.css +++ /dev/null @@ -1,256 +0,0 @@ -/* Based on http://www.perldoc.com/css/perldoc.css */ - -@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; -} diff --git a/cpp/llvm/docs/CommandGuide/index.html b/cpp/llvm/docs/CommandGuide/index.html deleted file mode 100644 index 64a03a58..00000000 --- a/cpp/llvm/docs/CommandGuide/index.html +++ /dev/null @@ -1,142 +0,0 @@ - - - - LLVM Command Guide - - - - -

- LLVM Command Guide -

- -
- -

These documents are HTML versions of the man pages -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 --help (general options) or -help-hidden (general+debugging -options) arguments to the tool you are interested in.

- -
- - -

- Basic Commands -

- - -
- -
    - -
  • llvm-as - - assemble a human-readable .ll file into bytecode
  • - -
  • llvm-dis - - disassemble a bytecode file into a human-readable .ll file
  • - -
  • opt - - run a series of LLVM-to-LLVM optimizations on a bytecode file
  • - -
  • llc - - generate native machine code for a bytecode file
  • - -
  • lli - - directly run a program compiled to bytecode using a JIT compiler or - interpreter
  • - -
  • llvm-link - - link several bytecode files into one
  • - -
  • llvm-ar - - archive bytecode files
  • - -
  • llvm-ranlib - - create an index for archives made with llvm-ar
  • - -
  • llvm-nm - - print out the names and types of symbols in a bytecode file
  • - -
  • llvm-prof - - format raw `llvmprof.out' data into a human-readable report
  • - -
  • llvm-ld - - general purpose linker with loadable runtime optimization support
  • - -
  • llvm-config - - print out LLVM compilation options, libraries, etc. as configured
  • - -
  • llvm-diff - - structurally compare two modules
  • - -
  • llvm-cov - - emit coverage information
  • - -
  • llvm-stress - - generate random .ll files to fuzz different llvm components
  • - -
- -
- - -

- Debugging Tools -

- - - -
- -
    - -
  • bugpoint - - automatic test-case reducer
  • - -
  • llvm-extract - - extract a function from an LLVM bytecode file
  • - -
  • llvm-bcanalyzer - - bytecode analyzer (analyzes the binary encoding itself, not the program it - represents)
  • - -
-
- - -

- Internal Tools -

- - -
-
    - -
  • FileCheck - - Flexible file verifier used extensively by the testing harness
  • -
  • tblgen - - target description reader and generator
  • -
  • lit - - LLVM Integrated Tester, for running tests
  • - -
-
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2012-02-26 00:35:53 -0800 (Sun, 26 Feb 2012) $ -
- - - diff --git a/cpp/llvm/docs/CommandGuide/lit.pod b/cpp/llvm/docs/CommandGuide/lit.pod deleted file mode 100644 index 81fc2c91..00000000 --- a/cpp/llvm/docs/CommandGuide/lit.pod +++ /dev/null @@ -1,404 +0,0 @@ -=pod - -=head1 NAME - -lit - LLVM Integrated Tester - -=head1 SYNOPSIS - -B [I] [I] - -=head1 DESCRIPTION - -B is a portable tool for executing LLVM and Clang style test suites, -summarizing their results, and providing indication of failures. B is -designed to be a lightweight testing tool with as simple a user interface as -possible. - -B should be run with one or more I 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 will print summary information on the number of tests -which passed or failed (see L<"TEST STATUS RESULTS">). The B program will -execute with a non-zero exit code if any tests fail. - -By default B will use a succinct progress display and will only print -summary information for test failures. See L<"OUTPUT OPTIONS"> for options -controlling the B progress display and output. - -B also includes a number of options for controlling how tests are executed -(specific features may depend on the particular test format). See L<"EXECUTION -OPTIONS"> for more information. - -Finally, B 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 architecture or designing a B testing -implementation should see L<"LIT INFRASTRUCTURE"> - -=head1 GENERAL OPTIONS - -=over - -=item B<-h>, B<--help> - -Show the B help message. - -=item B<-j> I, B<--threads>=I - -Run I tests in parallel. By default, this is automatically chosen to match -the number of detected available CPUs. - -=item B<--config-prefix>=I - -Search for I and I when searching for test suites, -instead of I and I. - -=item B<--param> I, B<--param> I=I - -Add a user defined parameter I with the given I (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 - -Specify an addition I 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 - -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 - -Run at most I tests and then terminate. - -=item B<--max-time>=I - -Spend at most I 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 in debug mode, for debugging configuration issues and B 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 - -Run each test I times. Currently this is primarily useful for timing tests, -other results are not collated in any reasonable fashion. - -=back - -=head1 EXIT STATUS - -B 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 are used -for non-test related failures (for example a user error or an internal program -error). - -=head1 TEST DISCOVERY - -The inputs passed to B can be either individual tests, or entire -directories or hierarchies of tests to run. When B starts up, the first -thing it does is convert the inputs into a complete list of tests to run as part -of I. - -In the B model, every test must exist inside some I. B -resolves the inputs specified on the command line to test suites by searching -upwards from the input path until it finds a I or I -file. These files serve as both a marker of test suites and as configuration -files which B loads in order to understand how to find and run the tests -inside the test suite. - -Once B 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 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 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 - -The test succeeded. - -=item B - -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 - -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 feature they test was broken and has been fixed). - -=item B - -The test failed. - -=item B - -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 - -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 -section for more information. - -=head1 LIT INFRASTRUCTURE - -This section describes the B testing architecture for users interested in -creating a new B testing implementation, or extending an existing one. - -B proper is primarily an infrastructure for discovering and running -arbitrary tests, and to expose a single convenient interface to these -tests. B itself doesn't know how to run tests, rather this logic is -defined by I. - -=head2 TEST SUITES - -As described in L<"TEST DISCOVERY">, tests are always located inside a I. 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 identifies test suites as directories containing I or -I 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 - -The global B configuration object (a I instance), which defines -the builtin test formats, global configuration parameters, and other helper -routines for implementing test configurations. - -=item B - -This is the config object (a I instance) for the test suite, -which the config file is expected to populate. The following variables are also -available on the I object, some of which must be set by the config and -others are optional or predefined: - -B I<[required]> The name of the test suite, for use in reports and -diagnostics. - -B 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 module. - -B The filesystem path to the test suite root. For out-of-dir -builds this is the directory that will be scanned for tests. - -B 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 -placed. - -B A dictionary representing the environment to use when executing -tests in the suite. - -B For B test formats which scan directories for tests, this -variable is a list of suffixes to identify test files. Used by: I, -I. - -B For B test formats which substitute variables into a test -script, the list of substitutions to perform. Used by: I, I. - -B Mark an unsupported directory, all tests within it will be -reported as unsupported. Used by: I, I. - -B The parent configuration, this is the config object for the directory -containing the test suite, or None. - -B The root configuration. This is the top-most B configuration in -the project. - -B The config is actually cloned for every subdirectory inside a test -suite, to allow local configuration on a per-directory basis. The I -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 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 recursively traverses the source directory -(following I) looking for tests. When B enters a -sub-directory, it first checks to see if a nested test suite is defined in that -directory. If so, it loads that test suite recursively, otherwise it -instantiates a local test config for the directory (see L<"LOCAL CONFIGURATION -FILES">). - -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) 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 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 checks for a I 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 TEST RUN OUTPUT FORMAT - -The b output for a test run conforms to the following schema, in both short -and verbose modes (although in short mode no PASS lines will be shown). This -schema has been chosen to be relatively easy to reliably parse by a machine (for -example in buildbot log scraping), and for other tools to generate. - -Each test result is expected to appear on a line that matches: - -: () - -where is a standard test result such as PASS, FAIL, XFAIL, XPASS, -UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and -REGRESSED are also allowed. - -The field can consist of an arbitrary string containing no newline. - -The field can be used to report progress information such as -(1/300) or can be empty, but even when empty the parentheses are required. - -Each test result may include additional (multiline) log information in the -following format. - - TEST '()' -... log message ... - - -where should be the name of a preceeding reported test, is a string of '*' characters I four characters long (the -recommended length is 20), and is an arbitrary (unparsed) -string. - -The following is an example of a test run output which consists of four tests A, -B, C, and D, and a log message for the failing test C. - -=head3 Example Test Run Output Listing - -PASS: A (1 of 4) -PASS: B (2 of 4) -FAIL: C (3 of 4) -******************** TEST 'C' FAILED ******************** -Test 'C' failed as a result of exit code 1. -******************** -PASS: D (4 of 4) - -=back - -=head2 LIT EXAMPLE TESTS - -The B distribution contains several example implementations of test suites -in the I directory. - -=head1 SEE ALSO - -L - -=head1 AUTHOR - -Written by Daniel Dunbar and maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llc.pod b/cpp/llvm/docs/CommandGuide/llc.pod deleted file mode 100644 index 35abdaeb..00000000 --- a/cpp/llvm/docs/CommandGuide/llc.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -llc - LLVM static compiler - -=head1 SYNOPSIS - -B [I] [I] - -=head1 DESCRIPTION - -The B 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 is - or omitted, B reads from standard input. Otherwise, it -will from I. 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 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 creates the output filename by taking the input filename, -removing any existing F<.bc> extension, and adding a F<.s> suffix. - -Other B options are as follows: - -=head2 End-user Options - -=over - -=item B<-help> - -Print a summary of command line options. - -=item B<-O>=I - -Generate code at different optimization levels. These correspond to the I<-O0>, -I<-O1>, I<-O2>, and I<-O3> optimization levels used by B and -B. - -=item B<-mtriple>=I - -Override the target triple specified in the input file with the specified -string. - -=item B<-march>=I - -Specify the architecture for which to generate assembly, overriding the target -encoded in the input file. See the output of B 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 - -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 /dev/null | llc -march=xyz -mcpu=help> - -=item B<-mattr>=I - -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 /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 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 - -Dynamically load F (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 - -Specify the register allocator to use. The default I is I. -Valid register allocators are: - -=over - -=item I - -Very simple "always spill" register allocator - -=item I - -Local register allocator - -=item I - -Linear scan global register allocator - -=item I - -Iterative scan global register allocator - -=back - -=item B<--spiller>=I - -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 is I. Valid spillers are: - -=over - -=item I - -Simple spiller - -=item I - -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 succeeds, it will exit with 0. Otherwise, if an error occurs, -it will exit with a non-zero value. - -=head1 SEE ALSO - -L - -=head1 AUTHORS - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/lli.pod b/cpp/llvm/docs/CommandGuide/lli.pod deleted file mode 100644 index a313a317..00000000 --- a/cpp/llvm/docs/CommandGuide/lli.pod +++ /dev/null @@ -1,219 +0,0 @@ -=pod - -=head1 NAME - -lli - directly execute programs from LLVM bitcode - -=head1 SYNOPSIS - -B [I] [I] [I] - -=head1 DESCRIPTION - -B 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 takes all of -the same code generator options as L, but they are only effective when -B is using the just-in-time compiler. - -If I is not specified, then B reads the LLVM bitcode for the -program from standard input. - -The optional I specified on the command line are passed to the program as -arguments. - -=head1 GENERAL OPTIONS - -=over - -=item B<-fake-argv0>=I - -Override the C 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 - -Causes B to load the plugin (shared object) named I 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 and exit without doing anything else. - -=back - -=head1 TARGET OPTIONS - -=over - -=item B<-mtriple>=I - -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 - -Specify the architecture for which to generate assembly, overriding the target -encoded in the bitcode file. See the output of B 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 - -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 /dev/null | llc -march=xyz -mcpu=help> - -=item B<-mattr>=I - -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 /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 to enable optimizations that may decrease floating point -precision. - -=item B<-soft-float> - -Causes B to generate software floating point library calls instead of -equivalent hardware instructions. - -=back - -=head1 CODE GENERATION OPTIONS - -=over - -=item B<-code-model>=I - -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 - -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 - -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 - -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 - -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 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 - -=head1 AUTHOR - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llvm-ar.pod b/cpp/llvm/docs/CommandGuide/llvm-ar.pod deleted file mode 100644 index a8f01b03..00000000 --- a/cpp/llvm/docs/CommandGuide/llvm-ar.pod +++ /dev/null @@ -1,406 +0,0 @@ -=pod - -=head1 NAME - -llvm-ar - LLVM archiver - -=head1 SYNOPSIS - -B [-]{dmpqrtx}[Rabfikouz] [relpos] [count] [files...] - - -=head1 DESCRIPTION - -The B command is similar to the common Unix utility, C. 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 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 command can be used to I both SVR4 and BSD style archive -files. However, it cannot be used to write them. While the B command -produces files that are I identical to the format used by other C -implementations, it has two significant departures in order to make the -archive appropriate for LLVM. The first departure is that B 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 usually won't be readable or editable with any -C implementation or useful for linking. Using the C modifier to flatten -file names will make the archive readable by other C 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 (replace) or C (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 departs from previous C implementations: - -=over - -=item I - -Since B 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 - -Some C implementations (SVR4) use a separate file member to record long -path names (> 15 characters). B 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 - -B 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 - -Most C implementations do not recurse through directories but simply -ignore directories if they are presented to the program in the F -option. B, however, can recurse through directory structures and -add all the files under a directory, if requested. - -=item I - -When B prints out the verbose table of contents (C 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 are compatible with other C implementations. -However, there are a few modifiers (F) that are not found in other -Cs. The options to B 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 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 comes a list of F that indicate the specific members -of the archive to operate on. If the F 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 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 are specified, the archive is not modified. - -=item m[abi] - -Move files from one location in the archive to another. The F, F, and -F modifiers apply to this operation. The F 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 are specified, the -archive is not modified. - -=item p[k] - -Print files to the standard output. The F modifier applies to this -operation. This operation simply prints the F indicated to the -standard output. If no F are specified, the entire archive is printed. -Printing bitcode files is ill-advised as they might confuse your terminal -settings. The F

operation is used. This modifier defeats the default and allows the -bitcode members to be printed. - -=item [N] - -This option is ignored by B but provided for compatibility. - -=item [o] - -When extracting files, this option will cause B 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 option to recursively process directories. -Without F, directories are ignored and only those F that refer to -files will be added to the archive. When F is used, any directories specified -with F 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 will always create the archive if it doesn't -exist. Normally, B 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 which also creates the symbol table. - -=item [S] - -This modifier is the opposite of the F modifier. It instructs B to -not build the symbol table. If both F and F are used, the last modifier to -occur in the options will prevail. - -=item [v] - -This modifier instructs B 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 utility is intended to provide a superset of the IEEE Std 1003.2 -(POSIX.2) functionality for C. B can read both SVR4 and BSD4.4 (or -Mac OS X) archives. If the C modifier is given to the C or C operations -then B will write SVR4 compatible archives. Without this modifier, -B 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 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 "!\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 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 -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 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. The symbol is not terminated by any character. Its length is provided -by the I 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 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, ar(1) - -=head1 AUTHORS - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llvm-as.pod b/cpp/llvm/docs/CommandGuide/llvm-as.pod deleted file mode 100644 index cc818870..00000000 --- a/cpp/llvm/docs/CommandGuide/llvm-as.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -llvm-as - LLVM assembler - -=head1 SYNOPSIS - -B [I] [I] - -=head1 DESCRIPTION - -B 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 is omitted or is C<->, then B reads its input from -standard input. - -If an output file is not specified with the B<-o> option, then -B 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 will refuse to -write raw bitcode output if the output stream is a terminal. With this option, -B will write raw bitcode regardless of the output device. - -=item B<-help> - -Print a summary of command line options. - -=item B<-o> F - -Specify the output file name. If F is C<->, then B -sends its output to standard output. - -=back - -=head1 EXIT STATUS - -If B succeeds, it will exit with 0. Otherwise, if an error -occurs, it will exit with a non-zero value. - -=head1 SEE ALSO - -L, L - -=head1 AUTHORS - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llvm-bcanalyzer.pod b/cpp/llvm/docs/CommandGuide/llvm-bcanalyzer.pod deleted file mode 100644 index 9c5021b6..00000000 --- a/cpp/llvm/docs/CommandGuide/llvm-bcanalyzer.pod +++ /dev/null @@ -1,315 +0,0 @@ -=pod - -=head1 NAME - -llvm-bcanalyzer - LLVM bitcode analyzer - -=head1 SYNOPSIS - -B [I] [F] - -=head1 DESCRIPTION - -The B command is a small utility for analyzing bitcode files. -The tool reads a bitcode file (such as generated with the B 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 is omitted or is C<->, then B 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 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 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 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 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 - -This just provides the name of the module for which bitcode analysis is being -generated. - -=item B - -The bitcode version (not LLVM version) of the file read by the analyzer. - -=item B - -The size, in bytes, of the entire bitcode file. - -=item B - -The size, in bytes, of the module block. Percentage is relative to File Size. - -=item B - -The size, in bytes, of all the function blocks. Percentage is relative to File -Size. - -=item B - -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 - -The size, in bytes, of the Constant Pool Blocks Percentage is relative to File -Size. - -=item B - -Ths size, in bytes, of the Global Variable Definitions and their initializers. -Percentage is relative to File Size. - -=item B - -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 - -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 - -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 - -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 - -The total number of blocks of any kind in the bitcode file. - -=item B - -The total number of function definitions in the bitcode file. - -=item B - -The total number of types defined in the Global Types Pool. - -=item B - -The total number of constants (of any type) defined in the Constant Pool. - -=item B - -The total number of basic blocks defined in all functions in the bitcode file. - -=item B - -The total number of instructions defined in all functions in the bitcode file. - -=item B - -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 - -The total number of operands used in all instructions in the bitcode file. - -=item B - -The total number of compaction tables in all functions in the bitcode file. - -=item B - -The total number of symbol tables in all functions in the bitcode file. - -=item B - -The total number of dependent libraries found in the bitcode file. - -=item B - -The total size of the instructions in all functions in the bitcode file. - -=item B - -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 - -The maximum value used for a type's slot number. Larger slot number values take -more bytes to encode. - -=item B - -The maximum value used for a value's slot number. Larger slot number values take -more bytes to encode. - -=item B - -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 - -The average size of a global definition (constants and global variables). - -=item B - -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 - -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 - -The type signature of the function. - -=item B - -The total number of bytes in the function's block. - -=item B - -The number of basic blocks defined by the function. - -=item B - -The number of instructions defined by the function. - -=item B - -The number of instructions using the long instruction format in the function. - -=item B - -The number of operands used by all instructions in the function. - -=item B - -The number of bytes consumed by instructions in the function. - -=item B - -The average number of bytes consumed by the instructions in the function. This -value is computed by dividing Instruction Size by Instructions. - -=item B - -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 - -The total number of 32-bit integers found in this function (for any use). - -=item B - -The total number of 64-bit integers found in this function (for any use). - -=item B - -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 - -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 - -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, L - -=head1 AUTHORS - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llvm-build.pod b/cpp/llvm/docs/CommandGuide/llvm-build.pod deleted file mode 100644 index 14e08cb6..00000000 --- a/cpp/llvm/docs/CommandGuide/llvm-build.pod +++ /dev/null @@ -1,86 +0,0 @@ -=pod - -=head1 NAME - -llvm-build - LLVM Project Build Utility - -=head1 SYNOPSIS - -B [I] - -=head1 DESCRIPTION - -B is a tool for working with LLVM projects that use the LLVMBuild -system for describing their components. - -At heart, B is responsible for loading, verifying, and manipulating -the project's component data. The tool is primarily designed for use in -implementing build systems and tools which need access to the project structure -information. - -=head1 OPTIONS - -=over - -=item B<-h>, B<--help> - -Print the builtin program help. - -=item B<--source-root>=I - -If given, load the project at the given source root path. If this option is not -given, the location of the project sources will be inferred from the location of -the B script itself. - -=item B<--print-tree> - -Print the component tree for the project. - -=item B<--write-library-table> - -Write out the C++ fragment which defines the components, library names, and -required libraries. This C++ fragment is built into L -in order to provide clients with the list of required libraries for arbitrary -component combinations. - -=item B<--write-llvmbuild> - -Write out new I files based on the loaded components. This is -useful for auto-upgrading the schema of the files. B will try to a -limited extent to preserve the comments which were written in the original -source file, although at this time it only preserves block comments that preceed -the section names in the I files. - -=item B<--write-cmake-fragment> - -Write out the LLVMBuild in the form of a CMake fragment, so it can easily be -consumed by the CMake based build system. The exact contents and format of this -file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's -top-level CMakeLists.txt. - -=item B<--write-make-fragment> - -Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be -consumed by a Make based build system. The exact contents and format of this -file are closely tied to how LLVMBuild is integrated with the Makefiles, see -LLVM's Makefile.rules. - -=item B<--llvmbuild-source-root>=I - -If given, expect the I files for the project to be rooted at the -given path, instead of inside the source tree itself. This option is primarily -designed for use in conjunction with B<--write-llvmbuild> to test changes to -I schema. - -=back - -=head1 EXIT STATUS - -B exits with 0 if operation was successful. Otherwise, it will exist -with a non-zero value. - -=head1 AUTHOR - -Maintained by the LLVM Team (L). - -=cut diff --git a/cpp/llvm/docs/CommandGuide/llvm-config.pod b/cpp/llvm/docs/CommandGuide/llvm-config.pod deleted file mode 100644 index 7d68564a..00000000 --- a/cpp/llvm/docs/CommandGuide/llvm-config.pod +++ /dev/null @@ -1,131 +0,0 @@ -=pod - -=head1 NAME - -llvm-config - Print LLVM compilation options - -=head1 SYNOPSIS - -B I

- CommandLine 2.0 Library Manual -

- -
    -
  1. Introduction
  2. - -
  3. Quick Start Guide -
      -
    1. Boolean Arguments
    2. -
    3. Argument Aliases
    4. -
    5. Selecting an alternative from a - set of possibilities
    6. -
    7. Named alternatives
    8. -
    9. Parsing a list of options
    10. -
    11. Collecting options as a set of flags
    12. -
    13. Adding freeform text to help output
    14. -
  4. - -
  5. Reference Guide -
      -
    1. Positional Arguments -
    2. - -
    3. Internal vs External Storage
    4. - -
    5. Option Attributes
    6. - -
    7. Option Modifiers -
    8. - -
    9. Top-Level Classes and Functions -
    10. - -
    11. Builtin parsers -
    12. -
  6. -
  7. Extension Guide -
      -
    1. Writing a custom parser
    2. -
    3. Exploiting external storage
    4. -
    5. Dynamically adding command line - options
    6. -
  8. -
- -
-

Written by Chris Lattner

-
- - -

- Introduction -

- - -
- -

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 can be -changed).

- -

Although there are a lot 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:

- -
    -
  1. 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).
  2. - -
  3. 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.
  4. - -
  5. 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 any boilerplate -code.
  6. - -
  7. 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 dynamically -loaded options trivial.
  8. - -
  9. 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.
  10. - -
  11. Powerful: The CommandLine library supports many different types of -arguments, from simple boolean flags to scalars arguments (strings, integers, enums, doubles), to lists of -arguments. This is possible because CommandLine is...
  12. - -
  13. 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. Custom parsers are no problem.
  14. - -
  15. 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 --help option that shows the available command line options for your -tool. Additionally, it does most of the basic correctness checking for -you.
  16. - -
  17. Capable: The CommandLine library can handle lots of different forms of -options often found in real programs. For example, positional arguments, ls style grouping options (to allow processing 'ls --lad' naturally), ld style prefix -options (to parse '-lmalloc -L/usr/lib'), and interpreter style options.
  18. - -
- -

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, Chris Lattner.

- -
- - -

- Quick Start Guide -

- - -
- -

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.

- -

To start out, you need to include the CommandLine header file into your -program:

- -
-  #include "llvm/Support/CommandLine.h"
-
- -

Additionally, you need to add this as the first line of your main -program:

- -
-int main(int argc, char **argv) {
-  cl::ParseCommandLineOptions(argc, argv);
-  ...
-}
-
- -

... which actually parses the arguments and fills in the variable -declarations.

- -

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 '-o <filename>' option -to specify where to put the output. With the CommandLine library, this is -represented like this:

- - -
-cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename"));
-
- -

This declares a global variable "OutputFilename" that is used to -capture the result of the "o" argument (first parameter). We specify -that this is a simple scalar option by using the "cl::opt" template (as opposed to the "cl::list template), and tell the CommandLine library -that the data type that we are parsing is a string.

- -

The second and third parameters (which are optional) are used to specify what -to output for the "-help" option. In this case, we get a line that -looks like this:

- -
-USAGE: compiler [options]
-
-OPTIONS:
-  -help             - display available options (-help-hidden for more)
-  -o <filename>     - Specify output filename
-
- -

Because we specified that the command line option should parse using the -string 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:

- -
-  ...
-  std::ofstream Output(OutputFilename.c_str());
-  if (Output.good()) ...
-  ...
-
- -

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 cl::desc(...), so -there are no positional dependencies to remember. The available options are -discussed in detail in the Reference Guide.

- -

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 -filename.c). To support this -style of argument, the CommandLine library allows for positional 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:

- -
-cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
-
- -

This declaration indicates that the first positional argument should be -treated as the input filename. Here we use the cl::init 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 cl::init 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 cl::Required flag, and we could eliminate the -cl::init modifier, like this:

- -
-cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::Required);
-
- -

Again, the CommandLine library does not require the options to be specified -in any particular order, so the above declaration is equivalent to:

- -
-cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<input file>"));
-
- -

By simply adding the cl::Required 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 -help option synopsis is now -extended to:

- -
-USAGE: compiler [options] <input file>
-
-OPTIONS:
-  -help             - display available options (-help-hidden for more)
-  -o <filename>     - Specify output filename
-
- -

... indicating that an input filename is expected.

- - -

- Boolean Arguments -

- -
- -

In addition to input and output filenames, we would like the compiler example -to support three boolean flags: "-f" to force writing binary output to -a terminal, "--quiet" to enable quiet mode, and "-q" for -backwards compatibility with some of our users. We can support these by -declaring options of boolean type like this:

- -
-cl::opt<bool> Force ("f", cl::desc("Enable binary output on terminals"));
-cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
-cl::opt<bool> Quiet2("q", cl::desc("Don't print informational messages"), cl::Hidden);
-
- -

This does what you would expect: it declares three boolean variables -("Force", "Quiet", and "Quiet2") to recognize these -options. Note that the "-q" option is specified with the "cl::Hidden" flag. This modifier prevents it -from being shown by the standard "-help" output (note that it is still -shown in the "-help-hidden" output).

- -

The CommandLine library uses a different parser -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 -"true" or "false" to be specified, allowing any of the -following inputs:

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

... you get the idea. The bool parser just turns -the string values into boolean values, and rejects things like 'compiler --f=foo'. Similarly, the float, double, and int parsers work -like you would expect, using the 'strtol' and 'strtod' C -library calls to parse the string value into the specified data type.

- -

With the declarations above, "compiler -help" emits this:

- -
-USAGE: compiler [options] <input file>
-
-OPTIONS:
-  -f     - Enable binary output on terminals
-  -o     - Override output filename
-  -quiet - Don't print informational messages
-  -help  - display available options (-help-hidden for more)
-
- -

and "compiler -help-hidden" prints this:

- -
-USAGE: compiler [options] <input file>
-
-OPTIONS:
-  -f     - Enable binary output on terminals
-  -o     - Override output filename
-  -q     - Don't print informational messages
-  -quiet - Don't print informational messages
-  -help  - display available options (-help-hidden for more)
-
- -

This brief example has shown you how to use the 'cl::opt' class to parse simple scalar command line -arguments. In addition to simple scalar arguments, the CommandLine library also -provides primitives to support CommandLine option aliases, -and lists of options.

- -
- - -

- Argument Aliases -

- -
- -

So far, the example works well, except for the fact that we need to check the -quiet condition like this now:

- -
-...
-  if (!Quiet && !Quiet2) printInformationalMessage(...);
-...
-
- -

... which is a real pain! Instead of defining two values for the same -condition, we can use the "cl::alias" class to make the "-q" -option an alias for the "-quiet" option, instead of providing -a value itself:

- -
-cl::opt<bool> Force ("f", cl::desc("Overwrite output files"));
-cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
-cl::alias     QuietA("q", cl::desc("Alias for -quiet"), cl::aliasopt(Quiet));
-
- -

The third line (which is the only one we modified from above) defines a -"-q" alias that updates the "Quiet" variable (as specified by -the cl::aliasopt modifier) whenever it is -specified. Because aliases do not hold state, the only thing the program has to -query is the Quiet variable now. Another nice feature of aliases is -that they automatically hide themselves from the -help output -(although, again, they are still visible in the -help-hidden -output).

- -

Now the application code can simply use:

- -
-...
-  if (!Quiet) printInformationalMessage(...);
-...
-
- -

... which is much nicer! The "cl::alias" -can be used to specify an alternative name for any variable type, and has many -uses.

- -
- - -

- Selecting an alternative from a set of - possibilities -

- -
- -

So far we have seen how the CommandLine library handles builtin types like -std::string, bool and int, but how does it handle -things it doesn't know about, like enums or 'int*'s?

- -

The answer is that it uses a table-driven generic parser (unless you specify -your own parser, as described in the Extension -Guide). This parser maps literal strings to whatever type is required, and -requires you to tell it what this mapping should be.

- -

Let's say that we would like to add four optimization levels to our -optimizer, using the standard flags "-g", "-O0", -"-O1", and "-O2". We could easily implement this with boolean -options like above, but there are several problems with this strategy:

- -
    -
  1. A user could specify more than one of the options at a time, for example, -"compiler -O3 -O2". The CommandLine library would not be able to -catch this erroneous input for us.
  2. - -
  3. We would have to test 4 different variables to see which ones are set.
  4. - -
  5. This doesn't map to the numeric levels that we want... so we cannot easily -see if some level >= "-O1" is enabled.
  6. - -
- -

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:

- -
-enum OptLevel {
-  g, O1, O2, O3
-};
-
-cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
-  cl::values(
-    clEnumVal(g , "No optimizations, enable debugging"),
-    clEnumVal(O1, "Enable trivial optimizations"),
-    clEnumVal(O2, "Enable default optimizations"),
-    clEnumVal(O3, "Enable expensive optimizations"),
-   clEnumValEnd));
-
-...
-  if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
-...
-
- -

This declaration defines a variable "OptimizationLevel" of the -"OptLevel" 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 "clEnumValEnd" 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 "clEnumVal" macros ensure that the -command line arguments matched the enum values. With this option added, our -help output now is:

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

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 "g" -in our program. Because of this, we can alternatively write this example like -this:

- -
-enum OptLevel {
-  Debug, O1, O2, O3
-};
-
-cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
-  cl::values(
-   clEnumValN(Debug, "g", "No optimizations, enable debugging"),
-    clEnumVal(O1        , "Enable trivial optimizations"),
-    clEnumVal(O2        , "Enable default optimizations"),
-    clEnumVal(O3        , "Enable expensive optimizations"),
-   clEnumValEnd));
-
-...
-  if (OptimizationLevel == Debug) outputDebugInfo(...);
-...
-
- -

By using the "clEnumValN" macro instead of "clEnumVal", 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.

- -
- - -

- Named Alternatives -

- -
- -

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: -"--debug-level=none", "--debug-level=quick", -"--debug-level=detailed". 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:

- -
-enum DebugLev {
-  nodebuginfo, quick, detailed
-};
-
-// Enable Debug Options to be specified on the command line
-cl::opt<DebugLev> DebugLevel("debug_level", cl::desc("Set the debugging level:"),
-  cl::values(
-    clEnumValN(nodebuginfo, "none", "disable debug information"),
-     clEnumVal(quick,               "enable quick debug information"),
-     clEnumVal(detailed,            "enable detailed debug information"),
-    clEnumValEnd));
-
- -

This definition defines an enumerated command line variable of type "enum -DebugLev", 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 "-help" option:

- -
-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
-  -debug_level  - Set the debugging level:
-    =none       - disable debug information
-    =quick      - enable quick debug information
-    =detailed   - enable detailed debug information
-  -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
-
- -

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 ("debug_level"), 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.

- -
- - -

- Parsing a list of options -

- -
- -

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 list of optimizations to perform, allowing duplicates. For example, we -might want to run: "compiler -dce -constprop -inline -dce -strip". In -this case, the order of the arguments and the number of appearances is very -important. This is what the "cl::list" -template is for. First, start by defining an enum of the optimizations that you -would like to perform:

- -
-enum Opts {
-  // 'inline' is a C++ keyword, so name it 'inlining'
-  dce, constprop, inlining, strip
-};
-
- -

Then define your "cl::list" variable:

- -
-cl::list<Opts> OptimizationList(cl::desc("Available Optimizations:"),
-  cl::values(
-    clEnumVal(dce               , "Dead Code Elimination"),
-    clEnumVal(constprop         , "Constant Propagation"),
-   clEnumValN(inlining, "inline", "Procedure Integration"),
-    clEnumVal(strip             , "Strip Symbols"),
-  clEnumValEnd));
-
- -

This defines a variable that is conceptually of the type -"std::vector<enum Opts>". Thus, you can access it with standard -vector methods:

- -
-  for (unsigned i = 0; i != OptimizationList.size(); ++i)
-    switch (OptimizationList[i])
-       ...
-
- -

... to iterate through the list of options specified.

- -

Note that the "cl::list" template is -completely general and may be used with any data types or other arguments that -you can use with the "cl::opt" 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 '.o' files, and needs to -capture them into a list. This is naturally specified as:

- -
-...
-cl::list<std::string> InputFilenames(cl::Positional, cl::desc("<Input files>"), cl::OneOrMore);
-...
-
- -

This variable works just like a "vector<string>" object. As -such, accessing the list is simple, just like above. In this example, we used -the cl::OneOrMore modifier to inform the -CommandLine library that it is an error if the user does not specify any -.o files on our command line. Again, this just reduces the amount of -checking we have to do.

- -
- - -

- Collecting options as a set of flags -

- -
- -

Instead of collecting sets of options in a list, it is also possible to -gather information for enum values in a bit vector. The representation used by -the cl::bits class is an unsigned -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:

- -
-  bits |= 1 << (unsigned)enum;
-
- -

Options that are specified multiple times are redundant. Any instances after -the first are discarded.

- -

Reworking the above list example, we could replace -cl::list with cl::bits:

- -
-cl::bits<Opts> OptimizationBits(cl::desc("Available Optimizations:"),
-  cl::values(
-    clEnumVal(dce               , "Dead Code Elimination"),
-    clEnumVal(constprop         , "Constant Propagation"),
-   clEnumValN(inlining, "inline", "Procedure Integration"),
-    clEnumVal(strip             , "Strip Symbols"),
-  clEnumValEnd));
-
- -

To test to see if constprop was specified, we can use the -cl:bits::isSet function:

- -
-  if (OptimizationBits.isSet(constprop)) {
-    ...
-  }
-
- -

It's also possible to get the raw bit vector using the -cl::bits::getBits function:

- -
-  unsigned bits = OptimizationBits.getBits();
-
- -

Finally, if external storage is used, then the location specified must be of -type unsigned. In all other ways a cl::bits option is equivalent to a cl::list option.

- -
- - - -

- Adding freeform text to help output -

- -
- -

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 man page, providing concise information about -a program. Unix man 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 cl::ParseCommandLineOptions -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:

- -
-int main(int argc, char **argv) {
-  cl::ParseCommandLineOptions(argc, argv, " CommandLine compiler example\n\n"
-                              "  This program blah blah blah...\n");
-  ...
-}
-
- -

would yield the help output:

- -
-OVERVIEW: CommandLine compiler example
-
-  This program blah blah blah...
-
-USAGE: compiler [options] <input file>
-
-OPTIONS:
-  ...
-  -help             - display available options (-help-hidden for more)
-  -o <filename>     - Specify output filename
-
- -
- -
- - -

- Reference Guide -

- - -
- -

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.

- - -

- Positional Arguments -

- -
- -

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 grep -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:

- -
-cl::opt<string> Regex   (cl::Positional, cl::desc("<regular expression>"), cl::Required);
-cl::opt<string> Filename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
-
- -

Given these two option declarations, the -help output for our grep -replacement would look like this:

- -
-USAGE: spiffygrep [options] <regular expression> <input file>
-
-OPTIONS:
-  -help - display available options (-help-hidden for more)
-
- -

... and the resultant program could be used just like the standard -grep tool.

- -

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.

- - -

- Specifying positional options with hyphens -

- -
- -

Sometimes you may want to specify a value to your positional argument that -starts with a hyphen (for example, searching for '-foo' in a file). At -first, you will have trouble doing this, because it will try to find an argument -named '-foo', and will fail (and single quotes will not save you). -Note that the system grep has the same problem:

- -
-  $ 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 . . .
-
- -

The solution for this problem is the same for both your tool and the system -version: use the '--' marker. When the user specifies '--' on -the command line, it is telling the program that all options after the -'--' should be treated as positional arguments, not options. Thus, we -can use it like this:

- -
-  $ spiffygrep -- -foo test.txt
-    ...output...
-
- -
- - -

- Determining absolute position with getPosition() -

-
-

Sometimes an option can affect or modify the meaning of another option. For - example, consider gcc's -x LANG option. This tells - gcc to ignore the suffix of subsequent positional arguments and force - the file to be interpreted as if it contained source code in language - LANG. 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 - -llibname which is actually a positional argument that starts with - a dash.

-

So, generally, the problem is that you have two cl::list variables - that interact in some way. To ensure the correct interaction, you can use the - cl::list::getPosition(optnum) method. This method returns the - absolute position (as found on the command line) of the optnum - item in the cl::list.

-

The idiom for usage is like this:

- -
-  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
-    }
-  }
- -

Note that, for compatibility reasons, the cl::opt also supports an - unsigned getPosition() option that will provide the absolute position - of that option. You can apply the same approach as above with a - cl::opt and a cl::list option as you can with two lists.

-
- - -

- The cl::ConsumeAfter modifier -

- -
- -

The cl::ConsumeAfter formatting option 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.

- -

As a concrete example, lets say we are developing a replacement for the -standard Unix Bourne shell (/bin/sh). To run /bin/sh, first -you specify options to the shell itself (like -x 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:

- -
-cl::opt<string> Script(cl::Positional, cl::desc("<input script>"), cl::init("-"));
-cl::list<string>  Argv(cl::ConsumeAfter, cl::desc("<program arguments>..."));
-cl::opt<bool>    Trace("x", cl::desc("Enable trace output"));
-
- -

which automatically provides the help output:

- -
-USAGE: spiffysh [options] <input script> <program arguments>...
-
-OPTIONS:
-  -help - display available options (-help-hidden for more)
-  -x    - Enable trace output
-
- -

At runtime, if we run our new shell replacement as `spiffysh -x test.sh --a -x -y bar', the Trace variable will be set to true, the -Script variable will be set to "test.sh", and the -Argv list will contain ["-a", "-x", "-y", "bar"], because they -were specified after the last positional argument (which is the script -name).

- -

There are several limitations to when cl::ConsumeAfter options can -be specified. For example, only one cl::ConsumeAfter can be specified -per program, there must be at least one positional -argument specified, there must not be any cl::list -positional arguments, and the cl::ConsumeAfter option should be a cl::list option.

- -
- -
- - -

- Internal vs External Storage -

- -
- -

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.

- -

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 -'-debug' 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 -CommandLine.h).

- -

To do this, set up your .h file with your option, like this for example:

- -
-
-// 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.
-//
-extern bool DebugFlag;
-
-// 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.
-#ifdef NDEBUG
-#define DEBUG(X)
-#else
-#define DEBUG(X) do { if (DebugFlag) { X; } } while (0)
-#endif
-
-
- -

This allows clients to blissfully use the DEBUG() macro, or the -DebugFlag explicitly if they want to. Now we just need to be able to -set the DebugFlag 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 cl::location -attribute:

- -
-
-bool DebugFlag;                  // the actual value
-static cl::opt<bool, true>       // The parser
-Debug("debug", cl::desc("Enable debug output"), cl::Hidden, cl::location(DebugFlag));
-
-
- -

In the above example, we specify "true" as the second argument to -the cl::opt template, indicating that the -template should not maintain a copy of the value itself. In addition to this, -we specify the cl::location attribute, so -that DebugFlag is automatically set.

- -
- - -

- Option Attributes -

- -
- -

This section describes the basic attributes that you can specify on -options.

- -
    - -
  • The option name attribute (which is required for all options, except positional options) specifies what the option name is. -This option is specified in simple double quotes: - -
    -cl::opt<bool> Quiet("quiet");
    -
    - -
  • - -
  • The cl::desc attribute specifies a -description for the option to be shown in the -help output for the -program.
  • - -
  • The cl::value_desc attribute -specifies a string that can be used to fine tune the -help output for -a command line option. Look here for an -example.
  • - -
  • The cl::init attribute specifies an -initial value for a scalar 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. Warning: If you specify both -cl::init and cl::location for an option, -you must specify cl::location first, so that when the -command-line parser sees cl::init, 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.)
  • - -
  • The cl::location attribute where -to store the value for a parsed command line option if using external storage. -See the section on Internal vs External Storage for more -information.
  • - -
  • The cl::aliasopt attribute -specifies which option a cl::alias option is -an alias for.
  • - -
  • The cl::values attribute specifies -the string-to-value mapping to be used by the generic parser. It takes a -clEnumValEnd terminated list of (option, value, description) triplets -that -specify the option name, the value mapped to, and the description shown in the --help for the tool. Because the generic parser is used most -frequently with enum values, two macros are often useful: - -
      - -
    1. The clEnumVal 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.
    2. - -
    3. The clEnumValN 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.
    4. - -
    - -You will get a compile time error if you try to use cl::values with a parser -that does not support it.
  • - -
  • The cl::multi_val -attribute specifies that this option takes has multiple values -(example: -sectalign segname sectname sectvalue). This -attribute takes one unsigned argument - the number of values for the -option. This attribute is valid only on cl::list 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 cl::ValueDisallowed, -obviously).
  • - -
- -
- - -

- Option Modifiers -

- -
- -

Option modifiers are the flags and expressions that you pass into the -constructors for cl::opt and cl::list. These modifiers give you the ability to -tweak how options are parsed and how -help output is generated to fit -your application well.

- -

These options fall into five main categories:

- -
    -
  1. Hiding an option from -help output
  2. -
  3. Controlling the number of occurrences - required and allowed
  4. -
  5. Controlling whether or not a value must be - specified
  6. -
  7. Controlling other formatting options
  8. -
  9. Miscellaneous option modifiers
  10. -
- -

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.

- - -

- Hiding an option from -help output -

- -
- -

The cl::NotHidden, cl::Hidden, and -cl::ReallyHidden modifiers are used to control whether or not an option -appears in the -help and -help-hidden output for the -compiled program:

- -
    - -
  • The cl::NotHidden modifier -(which is the default for cl::opt and cl::list options) indicates the option is to appear -in both help listings.
  • - -
  • The cl::Hidden modifier (which is the -default for cl::alias options) indicates that -the option should not appear in the -help output, but should appear in -the -help-hidden output.
  • - -
  • The cl::ReallyHidden modifier -indicates that the option should not appear in any help output.
  • - -
- -
- - -

- Controlling the number of occurrences required and - allowed -

- -
- -

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.

- -

The allowed values for this option group are:

- -
    - -
  • The cl::Optional modifier (which -is the default for the cl::opt and cl::alias classes) indicates that your program will -allow either zero or one occurrence of the option to be specified.
  • - -
  • The cl::ZeroOrMore modifier -(which is the default for the cl::list class) -indicates that your program will allow the option to be specified zero or more -times.
  • - -
  • The cl::Required modifier -indicates that the specified option must be specified exactly one time.
  • - -
  • The cl::OneOrMore modifier -indicates that the option must be specified at least one time.
  • - -
  • The cl::ConsumeAfter modifier is described in the Positional arguments section.
  • - -
- -

If an option is not specified, then the value of the option is equal to the -value specified by the cl::init attribute. If -the cl::init attribute is not specified, the -option value is initialized with the default constructor for the data type.

- -

If an option is specified multiple times for an option of the cl::opt class, only the last value will be -retained.

- -
- - -

- Controlling whether or not a value must be specified -

- -
- -

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. '-index-depth=17') or as a trailing -string (e.g. '-o a.out').

- -

The allowed values for this option group are:

- -
    - -
  • The cl::ValueOptional modifier -(which is the default for bool 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 '-foo=true'. -If an option is specified with this mode, it is illegal for the value to be -provided without the equal sign. Therefore '-foo true' is illegal. To -get this behavior, you must use the cl::ValueRequired modifier.
  • - -
  • The cl::ValueRequired modifier -(which is the default for all other types except for unnamed alternatives using the generic parser) -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 '-o -a.out' to work.
  • - -
  • The cl::ValueDisallowed -modifier (which is the default for unnamed -alternatives using the generic parser) 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 '-foo=true').
  • - -
- -

In general, the default values for this option group work just like you would -want them to. As mentioned above, you can specify the cl::ValueDisallowed modifier to a boolean -argument to restrict your command line parser. These options are mostly useful -when extending the library.

- -
- - -

- Controlling other formatting options -

- -
- -

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.

- -
    - -
  • The cl::NormalFormatting -modifier (which is the default all options) specifies that this option is -"normal".
  • - -
  • The cl::Positional modifier -specifies that this is a positional argument that does not have a command line -option associated with it. See the Positional -Arguments section for more information.
  • - -
  • The cl::ConsumeAfter modifier -specifies that this option is used to capture "interpreter style" arguments. See this section for more information.
  • - -
  • The cl::Prefix 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 -lmalloc and -L/usr/lib in a -linker tool or -DNAME=value in a compiler tool. Here, the -'l', 'D' and 'L' options are normal string (or list) -options, that have the cl::Prefix -modifier added to allow the CommandLine library to recognize them. Note that -cl::Prefix options must not have the -cl::ValueDisallowed modifier -specified.
  • - -
  • The cl::Grouping modifier is used -to implement Unix-style tools (like ls) that have lots of single letter -arguments, but only require a single dash. For example, the 'ls -labF' -command actually enables four different options, all of which are single -letters. Note that cl::Grouping -options cannot have values.
  • - -
- -

The CommandLine library does not restrict how you use the cl::Prefix or cl::Grouping 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.

- -

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:

- -
parse(string OrigInput) { - -
    -
  1. string input = OrigInput; -
  2. if (isOption(input)) return getOption(input).parse();    // Normal option -
  3. while (!isOption(input) && !input.empty()) input.pop_back();    // Remove the last letter -
  4. if (input.empty()) return error();    // No matching option -
  5. if (getOption(input).isPrefix())
    -  return getOption(input).parse(input);
    -
  6. while (!input.empty()) {    // Must be grouping options
    -  getOption(input).parse();
    -  OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
    -  input = OrigInput;
    -  while (!isOption(input) && !input.empty()) input.pop_back();
    -}
    -
  7. if (!OrigInput.empty()) error();
  8. -
- -

}

-
- -
- - -

- Miscellaneous option modifiers -

- -
- -

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.

- -
    - -
  • The cl::CommaSeparated 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 cl::CommaSeparated is specified: -"-foo=a -foo=b -foo=c" and "-foo=a,b,c". 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 cl::list option).
  • - -
  • The -cl::PositionalEatsArgs 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, "pos1" and "pos2", the -string "-pos1 -foo -bar baz -pos2 -bork" would cause the "-foo -bar --baz" strings to be applied to the "-pos1" option and the -"-bork" string to be applied to the "-pos2" option.
  • - -
  • The cl::Sink modifier is -used to handle unknown options. If there is at least one option with -cl::Sink modifier specified, the parser passes -unrecognized option strings to it as values instead of signaling an -error. As with cl::CommaSeparated, this modifier -only makes sense with a cl::list option.
  • - -
- -

So far, these are the only three miscellaneous option modifiers.

- -
- - -

- Response files -

- -
- -

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 -cl::ParseEnvironmentOptions -and -cl::ParseCommandLineOptions. -

- -
- -
- - -

- Top-Level Classes and Functions -

- -
- -

Despite all of the built-in flexibility, the CommandLine option library -really only consists of one function (cl::ParseCommandLineOptions) -and three main classes: cl::opt, cl::list, and cl::alias. This section describes these three -classes in detail.

- - -

- The cl::ParseCommandLineOptions - function -

- -
- -

The cl::ParseCommandLineOptions function is designed to be called -directly from main, and is used to fill in the values of all of the -command line option variables once argc and argv are -available.

- -

The cl::ParseCommandLineOptions function requires two parameters -(argc and argv), but may also take an optional third parameter -which holds additional extra text to emit when the --help option is invoked, and a fourth boolean parameter that enables -response files.

- -
- - -

- The cl::ParseEnvironmentOptions - function -

- -
- -

The cl::ParseEnvironmentOptions function has mostly the same effects -as cl::ParseCommandLineOptions, -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 cl::ParseCommandLineOptions -does.

- -

It takes four parameters: the name of the program (since argv may -not be available, it can't just look in argv[0]), the name of the -environment variable to examine, the optional -additional extra text to emit when the --help option is invoked, and the boolean -switch that controls whether response files -should be read.

- -

cl::ParseEnvironmentOptions will break the environment -variable's value up into words and then process them using -cl::ParseCommandLineOptions. -Note: Currently cl::ParseEnvironmentOptions does not support -quoting, so an environment variable containing -option "foo bar" will -be parsed as three words, -option, "foo, and bar", -which is different from what you would get from the shell with the same -input.

- -
- - -

- The cl::SetVersionPrinter - function -

- -
- -

The cl::SetVersionPrinter function is designed to be called -directly from main and before -cl::ParseCommandLineOptions. Its use is optional. It simply arranges -for a function to be called in response to the --version option instead -of having the CommandLine 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 CommandLine facilities. Such programs should just define a small -function that takes no arguments and returns void and that prints out -whatever version information is appropriate for the program. Pass the address -of that function to cl::SetVersionPrinter to arrange for it to be -called when the --version option is given by the user.

- -
- -

- The cl::opt class -

- -
- -

The cl::opt 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):

- -
-namespace cl {
-  template <class DataType, bool ExternalStorage = false,
-            class ParserClass = parser<DataType> >
-  class opt;
-}
-
- -

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 Internal -vs External Storage for more information).

- -

The third template argument specifies which parser to use. The default value -selects an instantiation of the parser 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 custom parser.

- -
- - -

- The cl::list class -

- -
- -

The cl::list 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:

- -
-namespace cl {
-  template <class DataType, class Storage = bool,
-            class ParserClass = parser<DataType> >
-  class list;
-}
-
- -

This class works the exact same as the cl::opt class, except that the second argument is -the type of the external storage, not a boolean value. For this class, -the marker type 'bool' is used to indicate that internal storage should -be used.

- -
- - -

- The cl::bits class -

- -
- -

The cl::bits 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:

- -
-namespace cl {
-  template <class DataType, class Storage = bool,
-            class ParserClass = parser<DataType> >
-  class bits;
-}
-
- -

This class works the exact same as the cl::lists class, except that the second argument -must be of type unsigned if external storage is used.

- -
- - -

- The cl::alias class -

- -
- -

The cl::alias class is a nontemplated class that is used to form -aliases for other arguments.

- -
-namespace cl {
-  class alias;
-}
-
- -

The cl::aliasopt attribute should be -used to specify which option this is an alias for. Alias arguments default to -being Hidden, and use the aliased options parser to do -the conversion from string to data.

- -
- - -

- The cl::extrahelp class -

- -
- -

The cl::extrahelp class is a nontemplated class that allows extra -help text to be printed out for the -help option.

- -
-namespace cl {
-  struct extrahelp;
-}
-
- -

To use the extrahelp, simply construct one with a const char* -parameter to the constructor. The text passed to the constructor will be printed -at the bottom of the help message, verbatim. Note that multiple -cl::extrahelp can be used, but this practice is discouraged. If -your tool needs to print additional help information, put all that help into a -single cl::extrahelp instance.

-

For example:

-
-  cl::extrahelp("\nADDITIONAL HELP:\n\n  This is the extra help\n");
-
-
- -
- - -

- Builtin parsers -

- -
- -

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 parser<type> if the -command line option specifies that it uses values of type 'type'. -Because of this, custom option processing is specified with specializations of -the 'parser' class.

- -

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 Writing a Custom Parser for more -details on this type of library extension.

- -
    - -
  • The generic parser<t> parser -can be used to map strings values to any data type, through the use of the cl::values 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.
  • - -
  • The parser<bool> specialization -is used to convert boolean strings to a boolean value. Currently accepted -strings are "true", "TRUE", "True", "1", -"false", "FALSE", "False", and "0".
  • - -
  • The parser<boolOrDefault> - specialization 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 parser<bool>.
  • - -
  • The parser<string> -specialization simply stores the parsed string into the string value -specified. No conversion or modification of the data is performed.
  • - -
  • The parser<int> specialization -uses the C strtol 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 -'0' prefix digit, and hexadecimal numbers with a prefix of -'0x' or '0X'.
  • - -
  • The parser<double> and -parser<float> specializations use the standard C -strtod function to convert floating point strings into floating point -values. As such, a broad range of string formats is supported, including -exponential notation (ex: 1.7e15) and properly supports locales. -
  • - -
- -
- -
- - -

- Extension Guide -

- - -
- -

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.

- - -

- Writing a custom parser -

- -
- -

One of the simplest and most common extensions is the use of a custom parser. -As discussed previously, 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.

- -

There are two ways to use a new parser:

- -
    - -
  1. - -

    Specialize the cl::parser template for -your custom data type.

    - -

    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.

    - -
  2. - -
  3. - -

    Write an independent class, using it explicitly from options that need -it.

    - -

    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.

    - -
  4. - -
- -

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 -'unsigned'. We choose approach #2 above because we don't want to make -this the default for all unsigned options.

- -

To start out, we declare our new FileSizeParser class:

- -
-struct FileSizeParser : public cl::basic_parser<unsigned> {
-  // parse - Return true on error.
-  bool parse(cl::Option &O, const char *ArgName, const std::string &ArgValue,
-             unsigned &Val);
-};
-
- -

Our new class inherits from the cl::basic_parser 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 parse 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 'unsigned' variables.)

- -

For most purposes, the only method that must be implemented in a custom -parser is the parse method. The parse 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 'Val' to the parsed value. In -our example, we implement parse as:

- -
-bool FileSizeParser::parse(cl::Option &O, const char *ArgName,
-                           const std::string &Arg, unsigned &Val) {
-  const char *ArgStart = Arg.c_str();
-  char *End;
-
-  // Parse integer part, leaving 'End' pointing to the first non-integer char
-  Val = (unsigned)strtol(ArgStart, &End, 0);
-
-  while (1) {
-    switch (*End++) {
-    case 0: return false;   // No error
-    case 'i':               // Ignore the 'i' in KiB if people use that
-    case 'b': case 'B':     // Ignore B suffix
-      break;
-
-    case 'g': case 'G': Val *= 1024*1024*1024; break;
-    case 'm': case 'M': Val *= 1024*1024;      break;
-    case 'k': case 'K': Val *= 1024;           break;
-
-    default:
-      // Print an error message if unrecognized character!
-      return O.error("'" + Arg + "' value invalid for file size argument!");
-    }
-  }
-}
-
- -

This function implements a very simple parser for the kinds of strings we are -interested in. Although it has some holes (it allows "123KKK" for -example), it is good enough for this example. Note that we use the option -itself to print out the error message (the error 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:

- -
-static cl::opt<unsigned, false, FileSizeParser>
-MFS("max-file-size", cl::desc("Maximum file size to accept"),
-    cl::value_desc("size"));
-
- -

Which adds this to the output of our program:

- -
-OPTIONS:
-  -help                 - display available options (-help-hidden for more)
-  ...
-  -max-file-size=<size> - Maximum file size to accept
-
- -

And we can test that our parse works correctly now (the test program just -prints out the max-file-size argument value):

- -
-$ ./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!
-
- -

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.

- -
- - -

- Exploiting external storage -

- -
-

Several of the LLVM libraries define static cl::opt 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 llvm::DebugFlag exported by the - lib/Support/Debug.cpp file and the llvm::TimePassesIsEnabled - flag exported by the lib/VMCore/Pass.cpp file.

- -

TODO: complete this section

- -
- - -

- Dynamically adding command line options -

- -
- -

TODO: fill in this section

- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - - diff --git a/cpp/llvm/docs/CompilerWriterInfo.html b/cpp/llvm/docs/CompilerWriterInfo.html deleted file mode 100644 index 3ba88c92..00000000 --- a/cpp/llvm/docs/CompilerWriterInfo.html +++ /dev/null @@ -1,267 +0,0 @@ - - - - - Architecture/platform information for compiler writers - - - - - -

- Architecture/platform information for compiler writers -

- -
-

Note: This document is a work-in-progress. Additions and clarifications - are welcome.

-
- -
    -
  1. Hardware -
      -
    1. ARM
    2. -
    3. Itanium
    4. -
    5. MIPS
    6. -
    7. PowerPC
    8. -
    9. SPARC
    10. -
    11. X86
    12. -
    13. Other lists
    14. -
  2. -
  3. Application Binary Interface (ABI) -
      -
    1. Linux
    2. -
    3. OS X
    4. -
  4. -
  5. Miscellaneous resources
  6. -
- -
-

Compiled by Misha Brukman

-
- - -

Hardware

- - -
- - -

ARM

- - - - -

Itanium (ia64)

- - - - -

MIPS

- - - - -

PowerPC

- - - - -

SPARC

- - - - -

X86

- -
- - -

AMD - Official manuals and docs

- - - - -

Intel - Official manuals and docs

- - - - -

Other x86-specific information

- - - -
- - -

Other relevant lists

- -
- - - -
- -
- - -

ABI

- - - - - -

Miscellaneous resources

- - - - - - -
-
- Valid CSS - Valid HTML 4.01 - - Misha Brukman
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-27 15:56:32 -0700 (Thu, 27 Oct 2011) $ -
- - - diff --git a/cpp/llvm/docs/DebuggingJITedCode.html b/cpp/llvm/docs/DebuggingJITedCode.html deleted file mode 100644 index 43e06f20..00000000 --- a/cpp/llvm/docs/DebuggingJITedCode.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - Debugging JITed Code With GDB - - - - -

Debugging JIT-ed Code With GDB

-
    -
  1. Background
  2. -
  3. GDB Version
  4. -
  5. Debugging MCJIT-ed code
  6. - -
-
Written by Reid Kleckner and Eli Bendersky
- - -

Background

- -
- -

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. -

- -

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 MCJIT. At a high level, whenever MCJIT generates new machine code, -it does so in an in-memory object file that contains the debug information in -DWARF format. MCJIT then adds this in-memory object file to a global list of -dynamically generated 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 MCJIT calls the registration -function, GDB catches the breakpoint signal, loads the new object file from -the inferior's memory, and resumes the execution. In this way, GDB can get the -necessary debug information. -

-
- - -

GDB Version

- - -

In order to debug code JIT-ed 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 JIT-ed code on Mac OS X. -

- - - -

Debugging MCJIT-ed code

- -
- -

The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with -GDB. This is due to MCJIT's ability to use the MC emitter to provide full -DWARF debugging information to GDB.

- -

Note that lli has to be passed the -use-mcjit flag to JIT the code -with MCJIT instead of the old JIT.

- -

Example

- -
- -

Consider the following C code (with line numbers added to make the example -easier to follow):

- -
-1   int compute_factorial(int n)
-2   {
-3       if (n <= 1)
-4           return 1;
-5
-6       int f = n;
-7       while (--n > 1) 
-8           f *= n;
-9       return f;
-10  }
-11
-12
-13  int main(int argc, char** argv)
-14  {
-15      if (argc < 2)
-16          return -1;
-17      char firstletter = argv[1][0];
-18      int result = compute_factorial(firstletter - '0');
-19  
-20      // Returned result is clipped at 255...
-21      return result;
-22  }
-
- -

Here is a sample command line session that shows how to build and run this -code via lli inside GDB: -

- -
-$ $BINPATH/clang -cc1 -O0 -g -emit-llvm showdebug.c
-$ gdb --quiet --args $BINPATH/lli -use-mcjit showdebug.ll 5
-Reading symbols from $BINPATH/lli...done.
-(gdb) b showdebug.c:6
-No source file named showdebug.c.
-Make breakpoint pending on future shared library load? (y or [n]) y
-Breakpoint 1 (showdebug.c:6) pending.
-(gdb) r
-Starting program: $BINPATH/lli -use-mcjit showdebug.ll 5
-[Thread debugging using libthread_db enabled]
-
-Breakpoint 1, compute_factorial (n=5) at showdebug.c:6
-6	    int f = n;
-(gdb) p n
-$1 = 5
-(gdb) p f
-$2 = 0
-(gdb) n
-7	    while (--n > 1) 
-(gdb) p f
-$3 = 5
-(gdb) b showdebug.c:9
-Breakpoint 2 at 0x7ffff7ed404c: file showdebug.c, line 9.
-(gdb) c
-Continuing.
-
-Breakpoint 2, compute_factorial (n=1) at showdebug.c:9
-9	    return f;
-(gdb) p f
-$4 = 120
-(gdb) bt
-#0  compute_factorial (n=1) at showdebug.c:9
-#1  0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
-#2  0x3500000001652748 in ?? ()
-#3  0x00000000016677e0 in ?? ()
-#4  0x0000000000000002 in ?? ()
-#5  0x0000000000d953b3 in llvm::MCJIT::runFunction (this=0x16151f0, F=0x1603020, ArgValues=...) at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/MCJIT/MCJIT.cpp:161
-#6  0x0000000000dc8872 in llvm::ExecutionEngine::runFunctionAsMain (this=0x16151f0, Fn=0x1603020, argv=..., envp=0x7fffffffe040)
-    at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/ExecutionEngine.cpp:397
-#7  0x000000000059c583 in main (argc=4, argv=0x7fffffffe018, envp=0x7fffffffe040) at /home/ebenders_test/llvm_svn_rw/tools/lli/lli.cpp:324
-(gdb) finish
-Run till exit from #0  compute_factorial (n=1) at showdebug.c:9
-0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
-18	    int result = compute_factorial(firstletter - '0');
-Value returned is $5 = 120
-(gdb) p result
-$6 = 23406408
-(gdb) n
-21	    return result;
-(gdb) p result
-$7 = 120
-(gdb) c
-Continuing.
-
-Program exited with code 0170.
-(gdb) 
-
-
- -
-
- - - -
-
- Valid CSS - Valid HTML 4.01 - Reid Kleckner, - Eli Bendersky
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-05-01 00:58:54 -0700 (Tue, 01 May 2012) $ -
- - diff --git a/cpp/llvm/docs/DeveloperPolicy.html b/cpp/llvm/docs/DeveloperPolicy.html deleted file mode 100644 index cc7f67a0..00000000 --- a/cpp/llvm/docs/DeveloperPolicy.html +++ /dev/null @@ -1,642 +0,0 @@ - - - - - LLVM Developer Policy - - - - -

LLVM Developer Policy

-
    -
  1. Introduction
  2. -
  3. Developer Policies -
      -
    1. Stay Informed
    2. -
    3. Making a Patch
    4. -
    5. Code Reviews
    6. -
    7. Code Owners
    8. -
    9. Test Cases
    10. -
    11. Quality
    12. -
    13. Obtaining Commit Access
    14. -
    15. Making a Major Change
    16. -
    17. Incremental Development
    18. -
    19. Attribution of Changes
    20. -
  4. -
  5. Copyright, License, and Patents -
      -
    1. Copyright
    2. -
    3. License
    4. -
    5. Patents
    6. -
  6. -
-
Written by the LLVM Oversight Team
- - -

Introduction

- -
-

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, libc++, etc.

-

This policy is also designed to accomplish the following objectives:

- -
    -
  1. Attract both users and developers to the LLVM project.
  2. - -
  3. Make life as simple and easy for contributors as possible.
  4. - -
  5. Keep the top of Subversion trees as stable as possible.
  6. - -
  7. Establish awareness of the project's copyright, - license, and patent policies with contributors to the project.
  8. -
- -

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 - llvm-commits - mailing list and engaging another developer to see it through the - process.

-
- - -

Developer Policies

- -
-

This section contains policies that pertain to frequent LLVM developers. We - always welcome one-off patches 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.

- - -

Stay Informed

-
-

Developers should stay informed by reading at least the "dev" mailing list - for the projects you are interested in, such as - llvmdev for - LLVM, cfe-dev - for Clang, or lldb-dev - 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 - llvm-commits, - cfe-commits, - or lldb-commits. - 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.

- -

We recommend that active developers register an email account with - LLVM Bugzilla and preferably subscribe to - the llvm-bugs - 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.

-
- - -

Making a Patch

- -
-

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:

- -
    -
  1. 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 Getting Started Guide.
  2. - -
  3. 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.
  4. - -
  5. Patches should be made with svn diff, or similar. If you use - a different tool, make sure it uses the diff -u format and - that it doesn't contain clutter which makes it hard to read.
  6. - -
  7. If you are modifying generated files, such as the top-level - configure script, please separate out those changes into - a separate patch from the rest of your changes.
  8. -
- -

When sending a patch to a mailing list, it is a good idea to send it as an - attachment 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).

- -

For Thunderbird users: Before submitting a patch, please open - Preferences → Advanced → General → Config Editor, - find the key mail.content_disposition_type, and set its value to - 1. Without this setting, Thunderbird sends your attachment using - Content-Disposition: inline rather than Content-Disposition: - attachment. Apple Mail gamely displays such a file inline, making it - difficult to work with for reviewers using that program.

-
- - -

Code Reviews

-
-

LLVM has a code review policy. Code review is one way to increase the quality - of software. We generally follow these policies:

- -
    -
  1. All developers are required to have significant changes reviewed before - they are committed to the repository.
  2. - -
  3. Code reviews are conducted by email, usually on the llvm-commits - list.
  4. - -
  5. 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.
  6. - -
  7. The developer responsible for a code change is also responsible for making - all necessary review-related changes.
  8. - -
  9. Code review can be an iterative process, which continues until the patch - is ready to be committed.
  10. -
- -

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.

-
- - -

Code Owners

-
- -

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.

- -

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:

- -
    -
  1. Evan Cheng: Code generator and all targets.
  2. - -
  3. Greg Clayton: LLDB.
  4. - -
  5. Doug Gregor: Clang Frontend Libraries.
  6. - -
  7. Howard Hinnant: libc++.
  8. - -
  9. Anton Korobeynikov: Exception handling, debug information, and - Windows codegen.
  10. - -
  11. Ted Kremenek: Clang Static Analyzer.
  12. - -
  13. Chris Lattner: Everything not covered by someone else.
  14. - -
  15. John McCall: Clang LLVM IR generation.
  16. - -
  17. Jakob Olesen: Register allocators and TableGen.
  18. - -
  19. Duncan Sands: dragonegg and llvm-gcc 4.2.
  20. - -
  21. Peter Collingbourne: libclc.
  22. - -
  23. Tobias Grosser: polly.
  24. -
- -

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.

- -

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.

-
- - -

Test Cases

-
-

Developers are required to create test cases for any bugs fixed and any new - features added. Some tips for getting your testcase approved:

- -
    -
  1. All feature and regression test cases are added to the - llvm/test directory. The appropriate sub-directory should be - selected (see the Testing Guide for - details).
  2. - -
  3. Test cases should be written in LLVM assembly - language 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++).
  4. - -
  5. Test cases, especially for regressions, should be reduced as much as - possible, by bugpoint or manually. It is - unacceptable to place an entire failing program into llvm/test as - this creates a time-to-test burden on all developers. Please keep - them short.
  6. -
- -

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 llvm-test test suite. The llvm-test suite is - for coverage (correctness, performance, etc) testing, not feature or - regression testing.

-
- - -

Quality

-
-

The minimum quality standards that any change must satisfy before being - committed to the main development branch are:

- -
    -
  1. Code must adhere to the LLVM Coding - Standards.
  2. - -
  3. Code must compile cleanly (no errors, no warnings) on at least one - platform.
  4. - -
  5. Bug fixes and new features should include a - testcase so we know if the fix/feature ever regresses in the - future.
  6. - -
  7. Code must pass the llvm/test test suite.
  8. - -
  9. 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 - "llvm-test/MultiSource/Benchmarks".
  10. -
- -

Additionally, the committer is responsible for addressing any problems found - in the future that the change is responsible for. For example:

- -
    -
  • The code should compile cleanly on all supported platforms.
  • - -
  • The changes should not cause any correctness regressions in the - llvm-test suite and must not cause any major performance - regressions.
  • - -
  • The change set should not cause performance or correctness regressions for - the LLVM tools.
  • - -
  • The changes should not cause performance or correctness regressions in - code compiled by LLVM on all applicable targets.
  • - -
  • You are expected to address any bugzilla - bugs that result from your change.
  • -
- -

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.

- -

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.

-
- - -

Obtaining Commit Access

-
- -

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 - Chris with the following - information:

- -
    -
  1. The user name you want to commit with, e.g. "hacker".
  2. - -
  3. The full name and email address you want message to llvm-commits to come - from, e.g. "J. Random Hacker <hacker@yoyodyne.com>".
  4. - -
  5. 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.
  6. -
- -

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.

- -

If you have recently been granted commit access, these policies apply:

- -
    -
  1. You are granted commit-after-approval to all parts of LLVM. To get - approval, submit a patch to - llvm-commits. - When approved you may commit it yourself.
  2. - -
  3. 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.
  4. - -
  5. 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.
  6. - -
  7. Multiple violations of these policies or a single egregious violation may - cause commit access to be revoked.
  8. -
- -

In any case, your changes are still subject to code - review (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.

-
- - -

Making a Major Change

-
-

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 llvmdev - email list, to the extent possible. The reason for this is to: - -

    -
  1. keep the community informed about future changes to LLVM,
  2. - -
  3. avoid duplication of effort by preventing multiple parties working on the - same thing and not knowing about it, and
  4. - -
  5. ensure that any technical issues around the proposed work are discussed - and resolved before any significant work is done.
  6. -
- -

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.

- -

Once the design of the new feature is finalized, the work itself should be - done as a series of incremental changes, not as a - long-term development branch.

-
- - -

Incremental Development

-
-

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:

- -
    -
  1. 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.
  2. - -
  3. Other people in the community tend to ignore work on branches.
  4. - -
  5. Huge changes (produced when a branch is merged back onto mainline) are - extremely difficult to code review.
  6. - -
  7. Branches are not routinely tested by our nightly tester - infrastructure.
  8. - -
  9. 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.
  10. -
- -

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:

- -
    -
  • 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.
  • - -
  • 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.
  • - -
  • 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.
  • - -
  • 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.
  • - -
  • 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.
  • -
- -

If you are interested in making a large change, and this scares you, please - make sure to first discuss the change/gather consensus - then ask about the best way to go about making the change.

-
- - -

Attribution of Changes

-
-

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.

- -

Overall, please do not add contributor names to the source code.

-
- -
- - -

- Copyright, License, and Patents -

- - -
- -
-

NOTE: This section deals with - legal matters but does not provide legal advice. We are not lawyers — - please seek legal counsel from an attorney.

-
- -
-

This section addresses the issues of copyright, license and patents for the - LLVM project. The copyright for the code is held by the individual - contributors of the code and the terms of its license to LLVM users and - developers is the - University of - Illinois/NCSA Open Source License (with portions dual licensed under the - MIT License, - see below). As contributor to the LLVM project, you agree to allow any - contributions to the project to licensed under these terms.

- - - -

Copyright

-
- -

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 - LLVM License.

- -

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.

- -

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.

- -
- - -

License

-
-

We intend to keep LLVM perpetually open source and to use a liberal open - source license. As a contributor to the project, you agree that any - contributions be licensed under the terms of the corresponding - subproject. - All of the code in LLVM is available under the - University of - Illinois/NCSA Open Source License, which boils down to this:

- -
    -
  • You can freely distribute LLVM.
  • -
  • You must retain the copyright notice if you redistribute LLVM.
  • -
  • Binaries derived from LLVM must reproduce the copyright notice (e.g. in an - included readme file).
  • -
  • You can't use our names to promote your LLVM derived products.
  • -
  • There's no warranty on LLVM at all.
  • -
- -

We believe this fosters the widest adoption of LLVM because it allows - commercial products to be derived from LLVM 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 License - if further clarification is needed.

- -

In addition to the UIUC license, the runtime library components of LLVM - (compiler_rt, libc++, and libclc) are also licensed under the MIT license, - 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. -

- -

Note that the LLVM Project does distribute llvm-gcc and dragonegg, which - are GPL. - 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 any code linked into llvm-gcc and distributed to others may - be subject to the viral aspects of the GPL (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 GPL-containing subprojects are kept - in separate SVN repositories whose LICENSE.txt files specifically indicate - that they contain GPL code.

- -

We have no plans to change the license of LLVM. If you have questions or - comments about the license, please contact the - LLVM Developer's Mailing List.

-
- - -

Patents

-
-

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).

- -

When contributing code, we expect contributors to notify us of any potential - for patent-related trouble with their changes (including from third parties). - If you or your employer own - the rights to a patent and would like to contribute code to LLVM that relies - on it, we require that the copyright owner sign an agreement that allows any - other user of LLVM to freely use your patent. Please contact - the oversight group for more - details.

-
- -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - Written by the - LLVM Oversight Group
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - diff --git a/cpp/llvm/docs/ExceptionHandling.html b/cpp/llvm/docs/ExceptionHandling.html deleted file mode 100644 index b1cc23db..00000000 --- a/cpp/llvm/docs/ExceptionHandling.html +++ /dev/null @@ -1,563 +0,0 @@ - - - - Exception Handling in LLVM - - - - - - - -

Exception Handling in LLVM

- - - - -
- -
- -
-

Written by the LLVM Team

-
- - - -

Introduction

- - -
- -

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++.

- - -

- Itanium ABI Zero-cost Exception Handling -

- -
- -

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.

- -

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.

- -

A more complete description of the Itanium ABI exception handling runtime - support of can be found at - Itanium C++ ABI: - Exception Handling. A description of the exception frame format can be - found at - Exception - Frames, with details of the DWARF 4 specification at - DWARF 4 Standard. - A description for the C++ exception table formats can be found at - Exception Handling - Tables.

- -
- - -

- Setjmp/Longjmp Exception Handling -

- -
- -

Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics - llvm.eh.sjlj.setjmp and - llvm.eh.sjlj.longjmp to - handle control flow for exception handling.

- -

For each function which does exception processing — be - it try/catch 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.

- -

Landing pad selection is encoded in the call site entry of the function - context. The runtime returns to the function via - llvm.eh.sjlj.longjmp, where - a switch table transfers control to the appropriate landing pad based on - the index stored in the function context.

- -

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.

- -
- - -

- Overview -

- -
- -

When an exception is thrown in LLVM code, the runtime does its best to find a - handler suited to processing the circumstance.

- -

The runtime first attempts to find an exception frame 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.

- -

Because different programming languages have different behaviors when - handling exceptions, the exception handling ABI provides a mechanism for - supplying personalities. An exception handling personality is defined - by way of a personality function (e.g. __gxx_personality_v0 - in C++), which receives the context of the exception, an exception - structure 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 common exception - frame.

- -

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++ type - info) that are handled in that range, and an associated action that - should take place. Actions typically pass control to a landing - pad.

- -

A landing pad corresponds roughly to the code found in the catch - portion of a try/catch sequence. When execution resumes at - a landing pad, it receives an exception structure and a - selector value corresponding to the type of exception - thrown. The selector is then used to determine which catch should - actually process the exception.

- -
- -
- - -

- LLVM Code Generation -

- -
- -

From a C++ developer's perspective, exceptions are defined in terms of the - throw and try/catch statements. In this section - we will describe the implementation of LLVM exception handling in terms of - C++ examples.

- - -

- Throw -

- -
- -

Languages that support exception handling typically provide a throw - operation to initiate the exception process. Internally, a throw - operation breaks down into two steps.

- -
    -
  1. 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.
  2. - -
  3. A call is made to the runtime to raise the exception, passing the - exception structure as an argument.
  4. -
- -

In C++, the allocation of the exception structure is done by the - __cxa_allocate_exception runtime function. The exception raising is - handled by __cxa_throw. The type of the exception is represented - using a C++ RTTI structure.

- -
- - -

- Try/Catch -

- -
- -

A call within the scope of a try statement can potentially raise an - exception. In those circumstances, the LLVM C++ front-end replaces the call - with an invoke instruction. Unlike a call, the invoke has - two potential continuation points:

- -
    -
  1. where to continue when the call succeeds as per normal, and
  2. - -
  3. where to continue if the call raises an exception, either by a throw or - the unwinding of a throw
  4. -
- -

The term used to define a the place where an invoke continues after - an exception is called a landing pad. 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.

- -

The LLVM landingpad - instruction is used to convey information about the landing pad to the - back end. For C++, the landingpad instruction returns a pointer and - integer pair corresponding to the pointer to the exception structure - and the selector value respectively.

- -

The landingpad instruction takes a reference to the personality - function to be used for this try/catch sequence. The - remainder of the instruction is a list of cleanup, catch, - and filter 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 undefined. 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 - llvm.eh.typeid.for intrinsic.

- -

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 - llvm.eh.typeid.for 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.

- -

Finally, the entry and exit of catch code is bracketed with calls to - __cxa_begin_catch and __cxa_end_catch.

- -
    -
  • __cxa_begin_catch takes an exception structure reference as an - argument and returns the value of the exception object.
  • - -
  • __cxa_end_catch takes no arguments. This function:

    -
      -
    1. Locates the most recently caught exception and decrements its handler - count,
    2. -
    3. Removes the exception from the caught stack if the handler - count goes to zero, and
    4. -
    5. Destroys the exception if the handler count goes to zero and the - exception was not re-thrown by throw.
    6. -
    -

    Note: a rethrow from within the catch may replace this call with - a __cxa_rethrow.

  • -
- -
- - -

- Cleanups -

- -
- -

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 - landingpad instruction - should have a cleanup clause. Otherwise, the unwinder will not stop at - the landing pad if there are no catches or filters that require it to.

- -

Note: 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.

- -

When all cleanups are finished, if the exception is not handled by the - current function, resume unwinding by calling the - resume instruction, passing in - the result of the landingpad instruction for the original landing - pad.

- -
- - -

- Throw Filters -

- -
- -

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 - landingpad instruction will - have a filter clause. The clause consists of an array of type infos. - landingpad 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 __cxa_call_unexpected should be made, otherwise - _Unwind_Resume. Each of these functions requires a reference to the - exception structure. Note that the most general form of a - landingpad instruction 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 - landingpad instructions due - to inlining creating nested exception handling scopes.

- -
- - -

- Restrictions -

- -
- -

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.

- -

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 A, and it's inlined into a - function that catches exceptions of type B. The inliner will update - the landingpad instruction for the inlined landing pad to include - the fact that B is also caught. If that landing pad assumes that it - will only be entered to catch an A, 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 - resume instruction if none of - the conditions match.

- -
- -
- - -

- Exception Handling Intrinsics -

- -
- -

In addition to the - landingpad and - resume instructions, LLVM uses - several intrinsic functions (name prefixed with llvm.eh) to - provide exception handling information at various points in generated - code.

- - -

- llvm.eh.typeid.for -

- -
- -
-  i32 @llvm.eh.typeid.for(i8* %type_info)
-
- -

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 landingpad instruction. - The single argument is a reference to a type info.

- -
- - -

- llvm.eh.sjlj.setjmp -

- -
- -
-  i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
-
- -

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 llvm.eh.sjlj.longjmp. The - buffer format and the overall functioning of this intrinsic is compatible - with the GCC __builtin_setjmp implementation allowing code built - with the clang and GCC to interoperate.

- -

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 - llvm.eh.sjlj.longjmp in the - second word. The following three words are available for use in a - target-specific manner.

- -
- - -

- llvm.eh.sjlj.longjmp -

- -
- -
-  void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
-
- -

For SJLJ based exception handling, the llvm.eh.sjlj.longjmp - intrinsic is used to implement __builtin_longjmp(). The single - parameter is a pointer to a buffer populated - by llvm.eh.sjlj.setjmp. The frame - pointer and stack pointer are restored from the buffer, then control is - transferred to the destination address.

- -
- -

- llvm.eh.sjlj.lsda -

- -
- -
-  i8* @llvm.eh.sjlj.lsda()
-
- -

For SJLJ based exception handling, the llvm.eh.sjlj.lsda 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.

- -
- - -

- llvm.eh.sjlj.callsite -

- -
- -
-  void @llvm.eh.sjlj.callsite(i32 %call_site_num)
-
- -

For SJLJ based exception handling, the llvm.eh.sjlj.callsite - intrinsic identifies the callsite value associated with the - following invoke instruction. This is used to ensure that landing - pad entries in the LSDA are generated in matching order.

- -
- -
- - -

- Asm Table Formats -

- -
- -

There are two tables that are used by the exception handling runtime to - determine which actions should be taken when an exception is thrown.

- - -

- Exception Handling Frame -

- -
- -

An exception handling frame eh_frame 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.

- - - -
- - -

- Exception Tables -

- -
- -

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.

- - - -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/ExtendedIntegerResults.txt b/cpp/llvm/docs/ExtendedIntegerResults.txt deleted file mode 100644 index 44e9fbf0..00000000 --- a/cpp/llvm/docs/ExtendedIntegerResults.txt +++ /dev/null @@ -1,133 +0,0 @@ -//===----------------------------------------------------------------------===// -// 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 ; [#uses=1] - %retval12 = trunc i32 %0 to 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. - diff --git a/cpp/llvm/docs/ExtendingLLVM.html b/cpp/llvm/docs/ExtendingLLVM.html deleted file mode 100644 index fb5175b8..00000000 --- a/cpp/llvm/docs/ExtendingLLVM.html +++ /dev/null @@ -1,379 +0,0 @@ - - - - - Extending LLVM: Adding instructions, intrinsics, types, etc. - - - - - -

- Extending LLVM: Adding instructions, intrinsics, types, etc. -

- -
    -
  1. Introduction and Warning
  2. -
  3. Adding a new intrinsic function
  4. -
  5. Adding a new instruction
  6. -
  7. Adding a new SelectionDAG node
  8. -
  9. Adding a new type -
      -
    1. Adding a new fundamental type
    2. -
    3. Adding a new derived type
    4. -
  10. -
- -
-

Written by Misha Brukman, - Brad Jones, Nate Begeman, - and Chris Lattner

-
- - -

- Introduction and Warning -

- - -
- -

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.

- -

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 LLVM-dev 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 -many LLVM analyses and transformations, so it may be quite a bit of -work.

- -

Adding an intrinsic function 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.

- -

Before you invest a significant amount of effort into a non-trivial -extension, ask on the list 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.

- -
- - -

- Adding a new intrinsic function -

- - -
- -

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.

- -
    -
  1. llvm/docs/LangRef.html: - 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.
  2. - -
  3. llvm/include/llvm/Intrinsics*.td: - 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 llvm_int_ty type for an argument will - be deemed by tblgen as overloaded and the corresponding suffix - will be required on the intrinsic's name.
  4. - -
  5. llvm/lib/Analysis/ConstantFolding.cpp: If it is possible to - constant fold your intrinsic, add support to it in the - canConstantFoldCallTo and ConstantFoldCall functions.
  6. - -
  7. llvm/test/Regression/*: Add test cases for your test cases to the - test suite
  8. -
- -

Once the intrinsic has been added to the system, you must add code generator -support for it. Generally you must do the following steps:

- -
- -
Add support to the .td file for the target(s) of your choice in - lib/Target/*/*.td.
- -
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.
-
- -
- - -

- Adding a new SelectionDAG node -

- - -
- -

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).

- -
    -
  1. include/llvm/CodeGen/ISDOpcodes.h: - Add an enum value for the new SelectionDAG node.
  2. -
  3. lib/CodeGen/SelectionDAG/SelectionDAG.cpp: - Add code to print the node to getOperationName. 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 getNode 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.
  4. -
  5. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: - Add code to legalize, - promote, and expand the node as necessary. At a minimum, you will need - to add a case statement for your node in LegalizeOp 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 LegalizeOp to Expand your node into simpler, legal - operations. The case for ISD::UREM for expanding a remainder into - a divide, multiply, and a subtract is a good example.
  6. -
  7. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: - 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 - LegalizeOp to Promote your node's operands to a larger size, and - perform the correct operation. You will also need to add code to - PromoteOp to do this as well. For a good example, see - ISD::BSWAP, - 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.
  8. -
  9. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: - Add a case for your node in ExpandOp 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.
  10. -
  11. lib/CodeGen/SelectionDAG/DAGCombiner.cpp: - 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 . There are several good examples for simple combines you - can do; visitFABS and visitSRL are good starting places. -
  12. -
  13. lib/Target/PowerPC/PPCISelLowering.cpp: - Each target has an implementation of the TargetLowering 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 - LegalizeOp above to decompose your new node into other legal - nodes for this target.
  14. -
  15. lib/Target/TargetSelectionDAG.td: - 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 - add, bswap, and fadd for examples.
  16. -
  17. lib/Target/PowerPC/PPCInstrInfo.td: - 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 rotl in - PPCInstrInfo.td.
  18. -
  19. TODO: document complex patterns.
  20. -
  21. llvm/test/Regression/CodeGen/*: Add test cases for your new node - to the test suite. llvm/test/Regression/CodeGen/X86/bswap.ll is - a good example.
  22. -
- -
- - -

- Adding a new instruction -

- - -
- -

WARNING: adding instructions changes the bitcode -format, and it will take some effort to maintain compatibility with -the previous version. Only add an instruction if it is absolutely -necessary.

- -
    - -
  1. llvm/include/llvm/Instruction.def: - add a number for your instruction and an enum name
  2. - -
  3. llvm/include/llvm/Instructions.h: - add a definition for the class that will represent your instruction
  4. - -
  5. llvm/include/llvm/Support/InstVisitor.h: - add a prototype for a visitor to your new instruction type
  6. - -
  7. llvm/lib/AsmParser/Lexer.l: - add a new token to parse your instruction from assembly text file
  8. - -
  9. llvm/lib/AsmParser/llvmAsmParser.y: - add the grammar on how your instruction can be read and what it will - construct as a result
  10. - -
  11. llvm/lib/Bitcode/Reader/Reader.cpp: - add a case for your instruction and how it will be parsed from bitcode
  12. - -
  13. llvm/lib/VMCore/Instruction.cpp: - add a case for how your instruction will be printed out to assembly
  14. - -
  15. llvm/lib/VMCore/Instructions.cpp: - implement the class you defined in - llvm/include/llvm/Instructions.h
  16. - -
  17. Test your instruction
  18. - -
  19. llvm/lib/Target/*: - Add support for your instruction to code generators, or add a lowering - pass.
  20. - -
  21. llvm/test/Regression/*: add your test cases to the test suite.
  22. - -
- -

Also, you need to implement (or modify) any analyses or passes that you want -to understand this new instruction.

- -
- - - -

- Adding a new type -

- - -
- -

WARNING: adding new types changes the bitcode -format, and will break compatibility with currently-existing LLVM -installations. Only add new types if it is absolutely necessary.

- - -

- Adding a fundamental type -

- -
- -
    - -
  1. llvm/include/llvm/Type.h: - add enum for the new type; add static Type* for this type
  2. - -
  3. llvm/lib/VMCore/Type.cpp: - add mapping from TypeID => Type*; - initialize the static Type*
  4. - -
  5. llvm/lib/AsmReader/Lexer.l: - add ability to parse in the type from text assembly
  6. - -
  7. llvm/lib/AsmReader/llvmAsmParser.y: - add a token for that type
  8. - -
- -
- - -

- Adding a derived type -

- -
- -
    -
  1. llvm/include/llvm/Type.h: - add enum for the new type; add a forward declaration of the type - also
  2. - -
  3. llvm/include/llvm/DerivedTypes.h: - add new class to represent new class in the hierarchy; add forward - declaration to the TypeMap value type
  4. - -
  5. llvm/lib/VMCore/Type.cpp: - add support for derived type to: -
    -
    -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)
    -
    -
    - add necessary member functions for type, and factory methods
  6. - -
  7. llvm/lib/AsmReader/Lexer.l: - add ability to parse in the type from text assembly
  8. - -
  9. llvm/lib/BitCode/Writer/Writer.cpp: - modify void BitcodeWriter::outputType(const Type *T) to serialize - your type
  10. - -
  11. llvm/lib/BitCode/Reader/Reader.cpp: - modify const Type *BitcodeReader::ParseType() to read your data - type
  12. - -
  13. llvm/lib/VMCore/AsmWriter.cpp: - modify -
    -
    -void calcTypeName(const Type *Ty,
    -                  std::vector<const Type*> &TypeStack,
    -                  std::map<const Type*,std::string> &TypeNames,
    -                  std::string & Result)
    -
    -
    - to output the new derived type -
  14. - - -
- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - The LLVM Compiler Infrastructure -
- Last modified: $Date: 2012-03-22 22:50:46 -0700 (Thu, 22 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/FAQ.html b/cpp/llvm/docs/FAQ.html deleted file mode 100644 index a365082a..00000000 --- a/cpp/llvm/docs/FAQ.html +++ /dev/null @@ -1,948 +0,0 @@ - - - - - LLVM: Frequently Asked Questions - - - - -

- LLVM: Frequently Asked Questions -

- -
    -
  1. License -
      -
    1. Why are the LLVM source code and the front-end distributed under - different licenses?
    2. - -
    3. Does the University of Illinois Open Source License really qualify as an - "open source" license?
    4. - -
    5. Can I modify LLVM source code and redistribute the modified source?
    6. - -
    7. Can I modify LLVM source code and redistribute binaries or other tools - based on it, without redistributing the source?
    8. -
  2. - -
  3. Source code -
      -
    1. In what language is LLVM written?
    2. - -
    3. How portable is the LLVM source code?
    4. -
  4. - -
  5. Build Problems -
      -
    1. When I run configure, it finds the wrong C compiler.
    2. - -
    3. The configure script finds the right C compiler, but it uses - the LLVM linker from a previous build. What do I do?
    4. - -
    5. When creating a dynamic library, I get a strange GLIBC error.
    6. - -
    7. I've updated my source tree from Subversion, and now my build is trying - to use a file/directory that doesn't exist.
    8. - -
    9. I've modified a Makefile in my source tree, but my build tree keeps - using the old version. What do I do?
    10. - -
    11. I've upgraded to a new version of LLVM, and I get strange build - errors.
    12. - -
    13. I've built LLVM and am testing it, but the tests freeze.
    14. - -
    15. Why do test results differ when I perform different types of - builds?
    16. - -
    17. Compiling LLVM with GCC 3.3.2 fails, what should I do?
    18. - -
    19. Compiling LLVM with GCC succeeds, but the resulting tools do not work, - what can be wrong?
    20. - -
    21. When I use the test suite, all of the C Backend tests fail. What is - wrong?
    22. - -
    23. After Subversion update, rebuilding gives the error "No rule to make - target".
    24. - -
    25. When I compile LLVM-GCC with srcdir == objdir, - it fails. Why?
    26. -
  6. - -
  7. Source Languages -
      -
    1. What source languages are supported?
    2. - -
    3. 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?
    4. - -
    5. What support is there for higher level source - language constructs for building a compiler?
    6. - -
    7. I don't understand the GetElementPtr - instruction. Help!
    8. -
    - -
  8. Using the GCC Front End -
      -
    1. 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?
    2. - -
    3. When I compile code using the LLVM GCC front end, it complains that it - cannot find libcrtend.a?
    4. - -
    5. How can I disable all optimizations when compiling code using the LLVM - GCC front end?
    6. - -
    7. Can I use LLVM to convert C++ code to C - code?
    8. - -
    9. Can I compile C or C++ code to - platform-independent LLVM bitcode?
    10. -
    -
  9. - -
  10. Questions about code generated by the GCC front-end -
      -
    1. What is this llvm.global_ctors and - _GLOBAL__I__tmp_webcompile... stuff that happens when I - #include <iostream>?
    2. - -
    3. Where did all of my code go??
    4. - -
    5. What is this "undef" thing that shows up in - my code?
    6. - -
    7. Why does instcombine + simplifycfg turn - a call to a function with a mismatched calling convention into "unreachable"? - Why not make the verifier reject it?
    8. -
    -
  11. -
- -
-

Written by The LLVM Team

-
- - - -

- License -

- - -
- -
-

Why are the LLVM source code and the front-end distributed under different - licenses?

-
- -
-

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 much less - restrictive 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.

-
- -
-

Does the University of Illinois Open Source License really qualify as an - "open source" license?

-
- -
-

Yes, the license - is certified by - the Open Source Initiative (OSI).

-
- -
-

Can I modify LLVM source code and redistribute the modified source?

-
- -
-

Yes. The modified source distribution must retain the copyright notice and - follow the three bulletted conditions listed in - the LLVM - license.

-
- -
-

Can I modify LLVM source code and redistribute binaries or other tools based - on it, without redistributing the source?

-
- -
-

Yes. This is why we distribute LLVM under a less restrictive license than - GPL, as explained in the first question above.

-
- -
- - -

- Source Code -

- - -
- -
-

In what language is LLVM written?

-
- -
-

All of the LLVM tools and libraries are written in C++ with extensive use of - the STL.

-
- -
-

How portable is the LLVM source code?

-
- -
-

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.

- -

Some porting problems may exist in the following areas:

- -
    -
  • The GCC front end code is not as portable as the LLVM suite, so it may not - compile as well on unsupported platforms.
  • - -
  • 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.
  • -
- -
- -
- - -

- Build Problems -

- - -
- -
-

When I run configure, it finds the wrong C compiler.

-
- -
-

The configure script attempts to locate first gcc and then - cc, unless it finds compiler paths set in CC - and CXX for the C and C++ compiler, respectively.

- -

If configure finds the wrong compiler, either adjust your - PATH environment variable or set CC and CXX - explicitly.

- -
- -
-

The configure script finds the right C compiler, but it uses the - LLVM linker from a previous build. What do I do?

-
- -
-

The configure script uses the PATH to find executables, so - if it's grabbing the wrong linker/assembler/etc, there are two ways to fix - it:

- -
    -
  1. Adjust your PATH environment variable so that the correct - program appears first in the PATH. This may work, but may not be - convenient when you want them first in your path for other - work.

  2. - -
  3. Run configure with an alternative PATH that is - correct. In a Borne compatible shell, the syntax would be:

    - -
    -% PATH=[the path without the bad program] ./configure ...
    -
    - -

    This is still somewhat inconvenient, but it allows configure - to do its work without having to adjust your PATH - permanently.

  4. -
-
- -
-

When creating a dynamic library, I get a strange GLIBC error.

-
- -
-

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.

-
- -
-

I've updated my source tree from Subversion, and now my build is trying to - use a file/directory that doesn't exist.

-
- -
-

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.

-
- -
-

I've modified a Makefile in my source tree, but my build tree keeps using the - old version. What do I do?

-
- -
-

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:

- -
-% ./config.status <relative path to Makefile>
-
- -

If the Makefile is new, you will have to modify the configure script to copy - it over.

-
- -
-

I've upgraded to a new version of LLVM, and I get strange build errors.

-
- -
- -

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.

- -

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 make - clean and then make in the directory that fails to build.

-
- -
-

I've built LLVM and am testing it, but the tests freeze.

-
- -
-

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 - gmake command line.

- -

For example, if you built LLVM with the command:

- -
-% gmake ENABLE_PROFILING=1
-
- -

...then you must run the tests with the following commands:

- -
-% cd llvm/test
-% gmake ENABLE_PROFILING=1
-
-
- -
-

Why do test results differ when I perform different types of builds?

-
- -
-

The LLVM test suite is dependent upon several features of the LLVM tools and - libraries.

- -

First, the debugging assertions in code are not enabled in optimized or - profiling builds. Hence, tests that used to fail may pass.

- -

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.

-
- -
-

Compiling LLVM with GCC 3.3.2 fails, what should I do?

-
- -
-

This is a bug in - GCC, and affects projects other than LLVM. Try upgrading or downgrading - your GCC.

-
- -
-

Compiling LLVM with GCC succeeds, but the resulting tools do not work, what - can be wrong?

-
- -
-

Several versions of GCC have shown a weakness in miscompiling the LLVM - codebase. Please consult your compiler version (gcc --version) to - find out whether it is broken. - If so, your only option is to upgrade GCC to a known good version.

-
- -
-

After Subversion update, rebuilding gives the error "No rule to make - target".

-
- -
-

If the error is of the form:

- -
-gmake[2]: *** No rule to make target `/path/to/somefile', needed by
-`/path/to/another/file.d'.
-Stop. -
- -

This may occur anytime files are moved within the Subversion repository or - removed entirely. In this case, the best solution is to erase all - .d files, which list dependencies for source files, and rebuild:

- -
-% cd $LLVM_OBJ_DIR
-% rm -f `find . -name \*\.d` 
-% gmake 
-
- -

In other cases, it may be necessary to run make clean before - rebuilding.

-
- - - -
-

The GNUmakefile in the top-level directory of LLVM-GCC is a special - Makefile used by Apple to invoke the build_gcc 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 GNUmakefile instead of Makefile. Because the - environment isn't set up correctly to do this, the build fails.

- -

People not building LLVM-GCC the "Apple way" need to build LLVM-GCC with - srcdir != objdir, or simply remove the GNUmakefile entirely.

- -

We regret the inconvenience.

-
- -
- - -

- Source Languages -

- -
- - - -
-

LLVM currently has full support for C and C++ source languages. These are - available through a special version of GCC that LLVM calls the - C Front End

- -

There is an incomplete version of a Java front end available in the - java module. There is no documentation on this yet so you'll need to - download the code, compile it, and try it.

- -

The PyPy developers are working on integrating LLVM into the PyPy backend so - that PyPy language can translate to LLVM.

-
- - - -
-

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:

- -
    -
  • Call into the LLVM libraries code using your language's FFI - (foreign function interface). - -
      -
    • for: best tracks changes to the LLVM IR, .ll syntax, and .bc - format
    • - -
    • for: enables running LLVM optimization passes without a - emit/parse overhead
    • - -
    • for: adapts well to a JIT context
    • - -
    • against: lots of ugly glue code to write
    • -
  • - -
  • Emit LLVM assembly from your compiler's native language. -
      -
    • for: very straightforward to get started
    • - -
    • against: the .ll parser is slower than the bitcode reader - when interfacing to the middle end
    • - -
    • against: you'll have to re-engineer the LLVM IR object model - and asm writer in your language
    • - -
    • against: it may be harder to track changes to the IR
    • -
  • - -
  • Emit LLVM bitcode from your compiler's native language. - -
      -
    • for: can use the more-efficient bitcode reader when - interfacing to the middle end
    • - -
    • against: you'll have to re-engineer the LLVM IR object - model and bitcode writer in your language
    • - -
    • against: it may be harder to track changes to the IR
    • -
  • -
- -

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.

-
- - - -
-

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.

-
- - - - - -
- - -

- Using the GCC Front End -

- -
- -
-

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?

-
- -
-

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."

- -

To work around this, perform the following steps:

- -
    -
  1. Make sure the CC and CXX environment variables contains the full path to - the LLVM GCC front end.
  2. - -
  3. Make sure that the regular C compiler is first in your PATH.
  4. - -
  5. Add the string "-Wl,-native" to your CFLAGS environment variable.
  6. -
- -

This will allow the llvm-ld 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.

-
- -
-

When I compile code using the LLVM GCC front end, it complains that it cannot - find libcrtend.a. -

-
- -
-

The only way this can happen is if you haven't installed the runtime - library. To correct this, do:

- -
-% cd llvm/runtime
-% make clean ; make install-bytecode
-
-
- -
-

How can I disable all optimizations when compiling code using the LLVM GCC - front end?

-
- -
-

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.

-
- - - - -
-

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.

- -

Use commands like this:

- -
    -
  1. Compile your program with llvm-g++:

    - -
    -% llvm-g++ -emit-llvm x.cpp -o program.bc -c
    -
    - -

    or:

    - -
    -% llvm-g++ a.cpp -c -emit-llvm
    -% llvm-g++ b.cpp -c -emit-llvm
    -% llvm-ld a.o b.o -o program
    -
    - -

    This will generate program and program.bc. The .bc - file is the LLVM version of the program all linked together.

  2. - -
  3. Convert the LLVM code to C code, using the LLC tool with the C - backend:

    - -
    -% llc -march=c program.bc -o program.c
    -
  4. - -
  5. Finally, compile the C file:

    - -
    -% cc x.c -lstdc++
    -
  6. - -
- -

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.

- -

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.

- -

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.

- -

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.

-
- - - -
-

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.

- -

Another example is sizeof. It's common for sizeof(long) to - vary between platforms. In most C front-ends, sizeof is expanded to - a constant immediately, thus hard-wiring a platform-specific detail.

- -

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.

-
- -
- - -

- Questions about code generated by the GCC front-end -

- -
- - - -
-

If you #include the <iostream> header into a C++ - translation unit, the file will probably use - the std::cin/std::cout/... 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 std::cout, for example, the object would not necessarily be - automatically initialized before your use.

- -

To make std::cout 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 <iostream>. 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. -

- -

If you would like to make it easier to understand the LLVM code - generated by the compiler in the demo page, consider using printf() - instead of iostreams to print values.

-
- - - - - -
-

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.

- -

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 volatile global - variables.

-
- - - - - -
-

undef 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:

- -
-int X() { int i; return i; }
-
- -

Is compiled to "ret i32 undef" because "i" never has a - value specified for it.

-
- - - - - -
-

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:

- -
-define fastcc void @foo() {
-        ret void
-}
-define void @bar() {
-        call void @foo()
-        ret void
-}
-
- -

Is optimized to:

- -
-define fastcc void @foo() {
-	ret void
-}
-define void @bar() {
-	unreachable
-}
-
- -

... 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.

- -

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:

- -
-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
-} 
-
- -

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): -

- -
-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
-}
-
- -

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: -

- -
-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
-}
-
- -

The interesting thing about this is that %X must 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:

- -
-define fastcc void @foo() {
-	ret void
-}
-define void @test(i1 %X) {
-F.i:
-	call fastcc void @foo()
-	ret void
-}
-
- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/GCCFEBuildInstrs.html b/cpp/llvm/docs/GCCFEBuildInstrs.html deleted file mode 100644 index 8d734659..00000000 --- a/cpp/llvm/docs/GCCFEBuildInstrs.html +++ /dev/null @@ -1,279 +0,0 @@ - - - - - - Building the LLVM GCC Front-End - - - -

- Building the LLVM GCC Front-End -

- -
    -
  1. Building llvm-gcc from Source
  2. -
  3. Building the Ada front-end
  4. -
  5. Building the Fortran front-end
  6. -
  7. License Information
  8. -
- -
-

Written by the LLVM Team

-
- - -

Building llvm-gcc from Source

- - -
- -

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.

- -
    -
  1. Retrieve the appropriate llvm-gcc-4.2-version.source.tar.gz - archive from the LLVM web - site.

    - -

    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:

    - -
    -
    -svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk dst-directory
    -
    -
    - -

    After that, the code can be be updated in the destination directory - using:

    - -
    -
    svn update
    -
    - -

    The mirror is brought up to date every evening.

  2. - -
  3. Follow the directions in the top-level README.LLVM file for - up-to-date instructions on how to build llvm-gcc. See below for building - with support for Ada or Fortran. -
- -
- - -

Building the Ada front-end

- - -
-

Building with support for Ada amounts to following the directions in the -top-level README.LLVM file, adding ",ada" to EXTRALANGS, for example: -EXTRALANGS=,ada

- -

There are some complications however:

- -
    -
  1. 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.

  2. -
  3. 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 - LLVM 2.7 release - are gcc-4.2 and the - 2005, 2006 and 2007 versions of the - GNAT GPL Edition. - GNAT GPL 2008, gcc-4.3 and later will not work. - 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 - 2007 GNAT GPL Edition) - and another which supports C++, see below.

  4. -
  5. 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 - LLVM bugzilla).

  6. -
  7. The Ada front-end fails to - bootstrap, due to lack of LLVM support for - setjmp/longjmp style exception handling (used - internally by the compiler), so you must specify - --disable-bootstrap.

  8. -
- -

Supposing appropriate compilers are available, llvm-gcc with Ada support can - be built on an x86-32 linux box using the following recipe:

- -
    -
  1. Download the LLVM source - and unpack it:

    - -
    -wget http://llvm.org/releases/2.7/llvm-2.7.tgz
    -tar xzf llvm-2.7.tgz
    -mv llvm-2.7 llvm
    -
    - -

    or check out the - latest version from subversion:

    - -
    svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
    - -
  2. - -
  3. Download the - llvm-gcc-4.2 source - and unpack it:

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

    or check out the - latest version from subversion:

    - -
    -svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk llvm-gcc-4.2
    -
    -
  4. - -
  5. Make a build directory llvm-objects for llvm and make it the - current directory:

    - -
    -mkdir llvm-objects
    -cd llvm-objects
    -
    -
  6. - -
  7. Configure LLVM (here it is configured to install into /usr/local):

    - -
    -../llvm/configure --prefix=/usr/local --enable-optimized --enable-assertions
    -
    - -

    If you have a multi-compiler setup and the C++ compiler is not the - default, then you can configure like this:

    - -
    -CXX=PATH_TO_C++_COMPILER ../llvm/configure --prefix=/usr/local --enable-optimized --enable-assertions
    -
    - -

    To compile without checking (not recommended), replace - --enable-assertions with --disable-assertions.

    - -
  8. - -
  9. Build LLVM:

    - -
    -make
    -
    -
  10. - -
  11. Install LLVM (optional):

    - -
    -make install
    -
    -
  12. - -
  13. Make a build directory llvm-gcc-4.2-objects for llvm-gcc and make it the - current directory:

    - -
    -cd ..
    -mkdir llvm-gcc-4.2-objects
    -cd llvm-gcc-4.2-objects
    -
    -
  14. - -
  15. Configure llvm-gcc (here it is configured to install into /usr/local). - The --enable-checking flag turns on sanity checks inside the compiler. - To turn off these checks (not recommended), replace --enable-checking - with --disable-checking. - Additional languages can be appended to the --enable-languages switch, - for example --enable-languages=ada,c,c++.

    - -
    -../llvm-gcc-4.2/configure --prefix=/usr/local --enable-languages=ada,c \
    -                          --enable-checking --enable-llvm=$PWD/../llvm-objects \
    -			  --disable-bootstrap --disable-multilib
    -
    - -

    If you have a multi-compiler setup, then you can configure like this:

    - -
    -export CC=PATH_TO_C_AND_ADA_COMPILER
    -export CXX=PATH_TO_C++_COMPILER
    -../llvm-gcc-4.2/configure --prefix=/usr/local --enable-languages=ada,c \
    -                          --enable-checking --enable-llvm=$PWD/../llvm-objects \
    -			  --disable-bootstrap --disable-multilib
    -
    -
  16. - -
  17. Build and install the compiler:

    - -
    -make
    -make install
    -
    -
  18. -
- -
- - -

Building the Fortran front-end

- - -
-

To build with support for Fortran, follow the directions in the top-level -README.LLVM file, adding ",fortran" to EXTRALANGS, for example:

- -
-EXTRALANGS=,fortran
-
- -
- - -

License Information

- - -
-

-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. -

- -

-More information is available in the FAQ. -

-
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - - diff --git a/cpp/llvm/docs/GarbageCollection.html b/cpp/llvm/docs/GarbageCollection.html deleted file mode 100644 index 777ee86c..00000000 --- a/cpp/llvm/docs/GarbageCollection.html +++ /dev/null @@ -1,1389 +0,0 @@ - - - - - Accurate Garbage Collection with LLVM - - - - - -

- Accurate Garbage Collection with LLVM -

- -
    -
  1. Introduction - -
  2. - -
  3. Getting started - -
  4. - -
  5. Core support - -
  6. - -
  7. Compiler plugin interface - -
  8. - -
  9. Implementing a collector runtime - -
  10. - -
  11. References
  12. - -
- -
-

Written by Chris Lattner and - Gordon Henriksen

-
- - -

- Introduction -

- - -
- -

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.

- -

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 -Boehm collector is -an example of a state-of-the-art conservative collector.

- -

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 -processor stack and registers.

- -

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 know 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).

- -

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.

- -

This document describes the mechanisms and interfaces provided by LLVM to -support accurate garbage collection.

- - -

- Goals and non-goals -

- -
- -

LLVM's intermediate representation provides garbage -collection intrinsics that offer support for a broad class of -collector models. For instance, the intrinsics permit:

- -
    -
  • semi-space collectors
  • -
  • mark-sweep collectors
  • -
  • generational collectors
  • -
  • reference counting
  • -
  • incremental collectors
  • -
  • concurrent collectors
  • -
  • cooperative collectors
  • -
- -

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.

- -

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 code generation plugins. The role of these -plugins is to generate code and data structures which conforms to the binary -interface specified by the runtime library. 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.

- -

The aspects of the binary interface with which LLVM's GC support is -concerned are:

- -
    -
  • Creation of GC-safe points within code where collection is allowed to - execute safely.
  • -
  • 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.
  • -
  • Write barriers when storing object references to the heap. These are - commonly used to optimize incremental scans in generational - collectors.
  • -
  • Emission of read barriers when loading object references. These are - useful for interoperating with concurrent collectors.
  • -
- -

There are additional areas that LLVM does not directly address:

- -
    -
  • Registration of global roots with the runtime.
  • -
  • Registration of stack map entries with the runtime.
  • -
  • The functions used by the program to allocate memory, trigger a - collection, etc.
  • -
  • Computation or compilation of type maps, or registration of them with - the runtime. These are used to crawl the heap for object - references.
  • -
- -

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.

- -
- -
- - -

- Getting started -

- - -
- -

Using a GC with LLVM implies many things, for example:

- -
    -
  • Write a runtime library or find an existing one which implements a GC - heap.
      -
    1. Implement a memory allocator.
    2. -
    3. Design a binary interface for the stack map, used to identify - references within a stack frame on the machine stack.*
    4. -
    5. Implement a stack crawler to discover functions on the call stack.*
    6. -
    7. Implement a registry for global roots.
    8. -
    9. Design a binary interface for type maps, used to identify references - within heap objects.
    10. -
    11. Implement a collection routine bringing together all of the above.
    12. -
  • -
  • Emit compatible code from your compiler.
      -
    • Initialization in the main function.
    • -
    • Use the gc "..." attribute to enable GC code generation - (or F.setGC("...")).
    • -
    • Use @llvm.gcroot to mark stack roots.
    • -
    • Use @llvm.gcread and/or @llvm.gcwrite to - manipulate GC references, if necessary.
    • -
    • Allocate memory using the GC allocation routine provided by the - runtime library.
    • -
    • Generate type maps according to your runtime's binary interface.
    • -
  • -
  • Write a compiler plugin to interface LLVM with the runtime library.*
      -
    • Lower @llvm.gcread and @llvm.gcwrite to appropriate - code sequences.*
    • -
    • Compile LLVM's stack map to the binary form expected by the - runtime.
    • -
  • -
  • Load the plugin into the compiler. Use llc -load or link the - plugin statically with your language's compiler.*
  • -
  • Link program executables with the runtime.
  • -
- -

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 llc and works even with the interpreter and C backends.

- - -

- In your compiler -

- -
- -

To turn the shadow stack on for your functions, first call:

- -
F.setGC("shadow-stack");
- -

for each function your compiler emits. Since the shadow stack is built into -LLVM, you do not need to load a plugin.

- -

Your compiler must also use @llvm.gcroot as documented. -Don't forget to create a root for each intermediate value that is generated -when evaluating an expression. In h(f(), g()), the result of -f() could easily be collected if evaluating g() triggers a -collection.

- -

There's no need to use @llvm.gcread and @llvm.gcwrite over -plain load and store for now. You will need them when -switching to a more advanced GC.

- -
- - -

- In your runtime -

- -
- -

The shadow stack doesn't imply a memory allocation algorithm. A semispace -collector or building atop malloc are great places to start, and can -be implemented with very little code.

- -

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.)

- -
-/// @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
-///        @llvm.gcroot.
-/// 
-/// 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);
-  }
-}
- -
- - -

- About the shadow stack -

- -
- -

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 [Henderson2002]. 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.

- -

The tradeoff for this simplicity and portability is:

- -
    -
  • High overhead per function call.
  • -
  • Not thread-safe.
  • -
- -

Still, it's an easy way to get started. After your compiler and runtime are -up and running, writing a plugin will allow you to take -advantage of more advanced GC features of LLVM -in order to improve performance.

- -
- -
- - -

- IR features -

- - -
- -

This section describes the garbage collection facilities provided by the -LLVM intermediate representation. The exact behavior -of these IR features is specified by the binary interface implemented by a -code generation plugin, not by this document.

- -

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.

- - -

- Specifying GC code generation: gc "..." -

- -
- -
- define ty @name(...) gc "name" { ... -
- -

The gc function attribute is used to specify the desired GC style -to the compiler. Its programmatic equivalent is the setGC method of -Function.

- -

Setting gc "name" on a function triggers a search for a -matching code generation plugin "name"; 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.

- -

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).

- -
- - -

- Identifying GC roots on the stack: llvm.gcroot -

- -
- -
- void @llvm.gcroot(i8** %ptrloc, i8* %metadata) -
- -

The llvm.gcroot 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 compiler plugin. All calls to llvm.gcroot must reside - inside the first basic block.

- -

A compiler which uses mem2reg to raise imperative code using alloca -into SSA form need only add a call to @llvm.gcroot for those variables -which a pointers into the GC heap.

- -

It is also important to mark intermediate values with llvm.gcroot. -For example, consider h(f(), g()). Beware leaking the result of -f() in the case that g() triggers a collection. Note, that -stack variables must be initialized and marked with llvm.gcroot in -function's prologue.

- -

The first argument must 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 must be a constant or global -value address. If your target collector uses tags, use a null pointer for -metadata.

- -

The %metadata argument can be used to avoid requiring heap objects -to have 'isa' pointers or tag bits. [Appel89, Goldberg91, Tolmach94] If -specified, its value will be tracked along with the location of the pointer in -the stack frame.

- -

Consider the following fragment of Java code:

- -
-       {
-         Object X;   // A null-initialized reference to an object
-         ...
-       }
-
- -

This block (which may be located in the middle of a function or in a loop -nest), could be compiled to this LLVM 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
-   ...
-
- -
- - -

- Reading and writing references in the heap -

- -
- -

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 -read barriers and write barriers, 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.

- -

Barriers often require access to the object pointer rather than the -derived pointer (which is a pointer to the field within the -object). Accordingly, these intrinsics take both pointers as separate arguments -for completeness. In this snippet, %object is the object pointer, and -%derived is the derived pointer:

- -
-    ;; 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
- -

LLVM does not enforce this relationship between the object and derived -pointer (although a plugin might). However, it would be -an unusual collector that violated it.

- -

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 load or store instruction if they -are used.

- - -

- Write barrier: llvm.gcwrite -

- -
- -
-void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived) -
- -

For write barriers, LLVM provides the llvm.gcwrite intrinsic -function. It has exactly the same semantics as a non-volatile store to -the derived pointer (the third argument). The exact code generated is specified -by a compiler plugin.

- -

Many important algorithms require write barriers, including generational -and concurrent collectors. Additionally, write barriers could be used to -implement reference counting.

- -
- - -

- Read barrier: llvm.gcread -

- -
- -
-i8* @llvm.gcread(i8* %object, i8** %derived)
-
- -

For read barriers, LLVM provides the llvm.gcread intrinsic function. -It has exactly the same semantics as a non-volatile load from the -derived pointer (the second argument). The exact code generated is specified by -a compiler plugin.

- -

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.

- -
- -
- -
- - -

- Implementing a collector plugin -

- - -
- -

User code specifies which GC code generation to use with the gc -function attribute or, equivalently, with the setGC method of -Function.

- -

To implement a GC plugin, it is necessary to subclass -llvm::GCStrategy, 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.

- -

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 -stack map.

- -

To subclass llvm::GCStrategy and register it with the compiler:

- -
// 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.");
-}
- -

This boilerplate collector does nothing. More specifically:

- -
    -
  • llvm.gcread calls are replaced with the corresponding - load instruction.
  • -
  • llvm.gcwrite calls are replaced with the corresponding - store instruction.
  • -
  • No safe points are added to the code.
  • -
  • The stack map is not compiled into the executable.
  • -
- -

Using the LLVM makefiles (like the sample -project), this code can be compiled as a plugin using a simple -makefile:

- -
# lib/MyGC/Makefile
-
-LEVEL := ../..
-LIBRARYNAME = MyGC
-LOADABLE_MODULE = 1
-
-include $(LEVEL)/Makefile.common
- -

Once the plugin is compiled, code using it may be compiled using llc --load=MyGC.so (though MyGC.so may have some other -platform-specific extension):

- -
$ cat sample.ll
-define void @f() gc "mygc" {
-entry:
-        ret void
-}
-$ llvm-as < sample.ll | llc -load=MyGC.so
- -

It is also possible to statically link the collector plugin into tools, such -as a language-specific compiler front-end.

- - -

- Overview of available features -

- -
- -

GCStrategy 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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AlgorithmDoneshadow stackrefcountmark-sweepcopyingincrementalthreadedconcurrent
stack map
initialize roots
derived pointersNO✘*✘*
custom lowering
gcroot
gcwrite
gcread
safe points
in calls
before calls
for loopsNO
before escape
emit code at safe pointsNO
output
assembly
JITNO
objNO
live analysisNO
register mapNO
-
* Derived pointers only pose a - hazard to copying collectors.
-
in gray denotes a feature which - could be utilized if available.
-
- -

To be clear, the collection techniques above are defined as:

- -
-
Shadow Stack
-
The mutator carefully maintains a linked list of stack roots.
-
Reference Counting
-
The mutator maintains a reference count for each object and frees an - object when its count falls to zero.
-
Mark-Sweep
-
When the heap is exhausted, the collector marks reachable objects starting - from the roots, then deallocates unreachable objects in a sweep - phase.
-
Copying
-
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.
-
Incremental
-
(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.
-
Threaded
-
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.
-
Concurrent
-
In this technique, the mutator and the collector run concurrently, with - the goal of eliminating pause times. In a cooperative 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.
-
- -

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.

- -
- - -

- Computing stack maps -

- -
- -

LLVM automatically computes a stack map. One of the most important features -of a GCStrategy is to compile this information into the executable in -the binary representation expected by the runtime library.

- -

The stack map consists of the location and identity of each GC root in the -each function in the module. For each root:

- -
    -
  • RootNum: The index of the root.
  • -
  • StackOffset: The offset of the object relative to the frame - pointer.
  • -
  • RootMetadata: The value passed as the %metadata - parameter to the @llvm.gcroot intrinsic.
  • -
- -

Also, for the function as a whole:

- -
    -
  • getFrameSize(): The overall size of the function's initial - stack frame, not accounting for any dynamic allocation.
  • -
  • roots_size(): The count of roots in the function.
  • -
- -

To access the stack map, use GCFunctionMetadata::roots_begin() and --end() from the GCMetadataPrinter:

- -
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;
-  }
-}
- -

If the llvm.gcroot 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.

- -
- - - -

- Initializing roots to null: InitRoots -

- -
- -
MyGC::MyGC() {
-  InitRoots = true;
-}
- -

When set, LLVM will automatically initialize each root to null 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.

- -

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.

- -
- - - -

- Custom lowering of intrinsics: CustomRoots, - CustomReadBarriers, and CustomWriteBarriers -

- -
- -

For GCs which use barriers or unusual treatment of stack roots, these -flags allow the collector to perform arbitrary transformations of the LLVM -IR:

- -
class MyGC : public GCStrategy {
-public:
-  MyGC() {
-    CustomRoots = true;
-    CustomReadBarriers = true;
-    CustomWriteBarriers = true;
-  }
-  
-  virtual bool initializeCustomLowering(Module &M);
-  virtual bool performCustomLowering(Function &F);
-};
- -

If any of these flags are set, then LLVM suppresses its default lowering for -the corresponding intrinsics and instead calls -performCustomLowering.

- -

LLVM's default action for each intrinsic is as follows:

- -
    -
  • llvm.gcroot: Leave it alone. The code generator must see it - or the stack map will not be computed.
  • -
  • llvm.gcread: Substitute a load instruction.
  • -
  • llvm.gcwrite: Substitute a store instruction.
  • -
- -

If CustomReadBarriers or CustomWriteBarriers are specified, -then performCustomLowering must eliminate the -corresponding barriers.

- -

performCustomLowering must comply with the same restrictions as FunctionPass::runOnFunction. -Likewise, initializeCustomLowering has the same semantics as Pass::doInitialization(Module&).

- -

The following can be used as a template:

- -
#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;
-}
- -
- - - -

- Generating safe points: NeededSafePoints -

- -
- -

LLVM can compute four kinds of safe points:

- -
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.
-  };
-}
- -

A collector can request any combination of the four by setting the -NeededSafePoints mask:

- -
MyGC::MyGC() {
-  NeededSafePoints = 1 << GC::Loop
-                   | 1 << GC::Return
-                   | 1 << GC::PreCall
-                   | 1 << GC::PostCall;
-}
- -

It can then use the following routines to access safe points.

- -
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;
-  }
-}
-
- -

Almost every collector requires PostCall safe points, since these -correspond to the moments when the function is suspended during a call to a -subroutine.

- -

Threaded programs generally require Loop 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.

- -

Threaded collectors may also require Return and PreCall -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).

- -
- - - -

- Emitting assembly code: GCMetadataPrinter -

- -
- -

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.)

- -

Since AsmWriter and CodeGen are separate components of LLVM, a separate -abstract base class and registry is provided for printing assembly code, the -GCMetadaPrinter and GCMetadataPrinterRegistry. The AsmWriter -will look for such a subclass if the GCStrategy sets -UsesMetadata:

- -
MyGC::MyGC() {
-  UsesMetadata = true;
-}
- -

This separation allows JIT-only clients to be smaller.

- -

Note that LLVM does not currently have analogous APIs to support code -generation in the JIT, nor using the object writers.

- -
// 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.");
-}
- -

The collector should use AsmPrinter and TargetAsmInfo to -print portable assembly code to the std::ostream. The collector itself -contains the stack map for the entire module, and may access the -GCFunctionInfo using its own begin() and end() -methods. Here's a realistic example:

- -
#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");
-      }
-    }
-  }
-}
-
- -
- -
- - -

- References -

- - -
- -

[Appel89] Runtime Tags Aren't Necessary. Andrew -W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.

- -

[Goldberg91] Tag-free garbage collection for -strongly typed programming languages. Benjamin Goldberg. ACM SIGPLAN -PLDI'91.

- -

[Tolmach94] Tag-free garbage collection using -explicit type parameters. Andrew Tolmach. Proceedings of the 1994 ACM -conference on LISP and functional programming.

- -

[Henderson2002] -Accurate Garbage Collection in an Uncooperative Environment. -Fergus Henderson. International Symposium on Memory Management 2002.

- -
- - - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-02 20:32:33 -0800 (Fri, 02 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/GetElementPtr.html b/cpp/llvm/docs/GetElementPtr.html deleted file mode 100644 index f32e7810..00000000 --- a/cpp/llvm/docs/GetElementPtr.html +++ /dev/null @@ -1,753 +0,0 @@ - - - - - The Often Misunderstood GEP Instruction - - - - - -

- The Often Misunderstood GEP Instruction -

- -
    -
  1. Introduction
  2. -
  3. Address Computation -
      -
    1. Why is the extra 0 index required?
    2. -
    3. What is dereferenced by GEP?
    4. -
    5. Why can you index through the first pointer but not - subsequent ones?
    6. -
    7. Why don't GEP x,0,0,1 and GEP x,1 alias?
    8. -
    9. Why do GEP x,1,0,0 and GEP x,1 alias?
    10. -
    11. Can GEP index into vector elements? -
    12. What effect do address spaces have on GEPs? -
    13. How is GEP different from ptrtoint, arithmetic, and inttoptr?
    14. -
    15. I'm writing a backend for a target which needs custom lowering for GEP. How do I do this? -
    16. How does VLA addressing work with GEPs? -
  4. -
  5. Rules -
      -
    1. What happens if an array index is out of bounds? -
    2. Can array indices be negative? -
    3. Can I compare two values computed with GEPs? -
    4. Can I do GEP with a different pointer type than the type of the underlying object? -
    5. Can I cast an object's address to integer and add it to null? -
    6. Can I compute the distance between two objects, and add that value to one address to compute the other address? -
    7. Can I do type-based alias analysis on LLVM IR? -
    8. What happens if a GEP computation overflows? -
    9. How can I tell if my front-end is following the rules? -
  6. -
  7. Rationale -
      -
    1. Why is GEP designed this way?
    2. -
    3. Why do struct member indices always use i32?
    4. -
    5. What's an uglygep? -
  8. -
  9. Summary
  10. -
- -
-

Written by: Reid Spencer.

-
- - - -

Introduction

- - -
-

This document seeks to dispel the mystery and confusion surrounding LLVM's - GetElementPtr (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. -

-
- - -

Address Computation

- -
-

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.

- - -

- What is the first index of the GEP instruction? -

-
-

Quick answer: The index stepping through the first operand.

-

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":

- -
-
-AType *Foo;
-...
-X = &Foo->F;
-
-
- -

it is natural to think that there is only one index, the selection of the - field F. However, in this example, Foo 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 F of the structure, just as if you wrote:

- -
-
-X = &Foo[0].F;
-
-
- -

Sometimes this question gets rephrased as:

-

Why is it okay to index through the first pointer, but - subsequent pointers won't be dereferenced?

-

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:

- -
-
-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);
-
-
- -

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 P 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 - struct munger_struct type, for either the f1 or - f2 field. So, in LLVM assembly the munge function looks - like:

- -
-
-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
-}
-
-
- -

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.

-

To make this clear, let's consider a more obtuse example:

- -
-
-%MyVar = uninitialized global i32
-...
-%idx1 = getelementptr i32* %MyVar, i64 0
-%idx2 = getelementptr i32* %MyVar, i64 1
-%idx3 = getelementptr i32* %MyVar, i64 2
-
-
- -

These GEP instructions are simply making address computations from the - base address of MyVar. They compute, as follows (using C syntax): -

- -
-
-idx1 = (char*) &MyVar + 0
-idx2 = (char*) &MyVar + 4
-idx3 = (char*) &MyVar + 8
-
-
- -

Since the type i32 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 - %MyVar is passed directly to the GEP instructions.

-

The obtuse part of this example is in the cases of %idx2 and - %idx3. They result in the computation of addresses that point to - memory past the end of the %MyVar global, which is only one - i32 long, not three i32s 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.

-
- - -

- Why is the extra 0 index required? -

- -
-

Quick answer: there are no superfluous indices.

-

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:

- -
-
-%MyStruct = uninitialized global { float*, i32 }
-...
-%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
-
-
- -

The GEP above yields an i32* by indexing the i32 typed - field of the structure %MyStruct. When people first look at it, they - wonder why the i64 0 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:

-
    -
  1. The type of %MyStruct is not { float*, i32 } - but rather { float*, i32 }*. That is, %MyStruct is a - pointer to a structure containing a pointer to a float and an - i32.
  2. -
  3. Point #1 is evidenced by noticing the type of the first operand of - the GEP instruction (%MyStruct) which is - { float*, i32 }*.
  4. -
  5. The first index, i64 0 is required to step over the global - variable %MyStruct. 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.
  6. -
  7. The second index, i32 1 selects the second field of the - structure (the i32).
  8. -
-
- - -

- What is dereferenced by GEP? -

-
-

Quick answer: nothing.

-

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:

- -
-
-%MyVar = uninitialized global { [40 x i32 ]* }
-...
-%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
-
-
- -

In this example, we have a global variable, %MyVar 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 must - be dereferenced in order to index into the array of 40 ints. Since the - GEP instruction never accesses memory, it is illegal.

-

In order to access the 18th integer in the array, you would need to do the - following:

- -
-
-%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
-
-
- -

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:

- -
-
-%MyVar = uninitialized global { [40 x i32 ] }
-...
-%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
-
-
- -

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 i32 in the - array there.

-
- - -

- Why don't GEP x,0,0,1 and GEP x,1 alias? -

-
-

Quick Answer: They compute different address locations.

-

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:

- -
-
-%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
-
-
- -

In this example, idx1 computes the address of the second integer - in the array that is in the structure in %MyVar, that is - MyVar+4. The type of idx1 is i32*. However, - idx2 computes the address of the next structure after - %MyVar. The type of idx2 is { [10 x i32] }* and its - value is equivalent to MyVar + 40 because it indexes past the ten - 4-byte integers in MyVar. Obviously, in such a situation, the - pointers don't alias.

- -
- - -

- Why do GEP x,1,0,0 and GEP x,1 alias? -

-
-

Quick Answer: They compute the same address location.

-

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:

- -
-
-%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
-
-
- -

In this example, the value of %idx1 is %MyVar+40 and - its type is i32*. The value of %idx2 is also - MyVar+40 but its type is { [10 x i32] }*.

-
- - - -

- Can GEP index into vector elements? -

-
-

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.

- -
- - - -

- What effect do address spaces have on GEPs? -

-
-

None, except that the address space qualifier on the first operand pointer - type always matches the address space qualifier on the result type.

- -
- - - -

- - How is GEP different from ptrtoint, arithmetic, and inttoptr? - -

-
-

It's very similar; there are only subtle differences.

- -

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. - -

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 Rules section for more - information.

- -

And, GEP is more concise in common cases.

- -

However, for the underlying integer computation implied, there - is no difference.

- -
- - - -

- - I'm writing a backend for a target which needs custom lowering for GEP. - How do I do this? - -

-
-

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.

- -

GEP does use target-dependent parameters for the size and layout of data - types, which targets can customize.

- -

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.

- -
- - - -

- How does VLA addressing work with GEPs? -

-
-

GEPs don't natively support VLAs. LLVM's type system is entirely static, - and GEP address computations are guided by an LLVM type.

- -

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.

- -

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.

-
- -
- - -

Rules

- -
- - -

- What happens if an array index is out of bounds? -

-
-

There are two senses in which an array index can be out of bounds.

- -

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.

- -

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.

- -

This sense is unconnected with inbounds keyword. The - inbounds keyword is designed to describe low-level pointer - arithmetic overflow conditions, rather than high-level array - indexing rules. - -

Analysis passes which wish to understand array indexing should not - assume that the static array type bounds are respected.

- -

The second sense of being out of bounds is computing an address that's - beyond the actual underlying allocated object.

- -

With the inbounds 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.

- -

Without the inbounds 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.

- -
- - -

- Can array indices be negative? -

-
-

Yes. This is basically a special case of array indices being out - of bounds.

- -
- - -

- Can I compare two values computed with GEPs? -

-
-

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.

- -
- - -

- - Can I do GEP with a different pointer type than the type of - the underlying object? - -

-
-

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.

- -

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.

- -
- - -

- - Can I cast an object's address to integer and add it to null? - -

-
-

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.

- -

The underlying integer computation is sufficiently defined; null has a - defined value -- zero -- and you can add whatever value you want to it.

- -

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.

- -

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.

- -
- - -

- - Can I compute the distance between two objects, and add - that value to one address to compute the other address? - -

-
-

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.

- -

Also as above, ptrtoint and inttoptr provide an alternative way to do this - which do not have this restriction.

- -
- - -

- Can I do type-based alias analysis on LLVM IR? -

-
-

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.

- -

LLVM's type-based alias analysis pass uses metadata to describe a different - type system (such as the C type system), and performs type-based aliasing - on top of that. Further details are in the - language reference.

- -
- - - -

- What happens if a GEP computation overflows? -

-
-

If the GEP lacks the inbounds 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.

- -

If the GEP has the inbounds keyword, the result value is - undefined (a "trap value") if the GEP - overflows (i.e. wraps around the end of the address space).

- -

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. -

- - -
- - - -

- - How can I tell if my front-end is following the rules? - -

-
-

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.

- -

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.

- -
- -
- - -

Rationale

- -
- - -

- Why is GEP designed this way? -

-
-

The design of GEP has the following goals, in rough unofficial - order of priority:

-
    -
  • Support C, C-like languages, and languages which can be - conceptually lowered into C (this covers a lot).
  • -
  • Support optimizations such as those that are common in - C compilers. In particular, GEP is a cornerstone of LLVM's - pointer aliasing model.
  • -
  • 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.
  • -
  • Support non-C-like languages, to the extent that it doesn't - interfere with other goals.
  • -
  • Minimize target-specific information in the IR.
  • -
-
- - -

- Why do struct member indices always use i32? -

-
-

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.

- -
- - - -

- What's an uglygep? -

-
-

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.

- -
- -
- - -

Summary

- - -
-

In summary, here's some things to always remember about the GetElementPtr - instruction:

-
    -
  1. The GEP instruction never accesses memory, it only provides pointer - computations.
  2. -
  3. The first operand to the GEP instruction is always a pointer and it must - be indexed.
  4. -
  5. There are no superfluous indices for the GEP instruction.
  6. -
  7. Trailing zero indices are superfluous for pointer aliasing, but not for - the types of the pointers.
  8. -
  9. Leading zero indices are not superfluous for pointer aliasing nor the - types of the pointers.
  10. -
-
- - - -
-
- Valid CSS - Valid HTML 4.01 - The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-31 06:04:26 -0700 (Mon, 31 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/GettingStarted.html b/cpp/llvm/docs/GettingStarted.html deleted file mode 100644 index 02a1f2c9..00000000 --- a/cpp/llvm/docs/GettingStarted.html +++ /dev/null @@ -1,1763 +0,0 @@ - - - - - Getting Started with LLVM System - - - - -

- Getting Started with the LLVM System -

- - - -
-

Written by: - John Criswell, - Chris Lattner, - Misha Brukman, - Vikram Adve, and - Guochun Shi. -

-
- - - -

- Overview -

- - -
- -

Welcome to LLVM! In order to get started, you first need to know some -basic information.

- -

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 LLVM. It contains an assembler, disassembler, bitcode -analyzer and bitcode optimizer. It also contains basic regression tests that -can be used to test the LLVM tools and the Clang front end.

- -

The second piece is the Clang front end. -This component compiles C, C++, Objective C, and Objective C++ code into LLVM -bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the -LLVM tools from the LLVM suite. -

- -

-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. -

- -
- - -

- Getting Started Quickly (A Summary) -

- - -
- -

The LLVM Getting Started documentation may be out of date. So, the Clang -Getting Started page might -also be a good place to start.

- -

Here's the short story for getting up and running quickly with LLVM:

- -
    -
  1. Read the documentation.
  2. -
  3. Read the documentation.
  4. -
  5. Remember that you were warned twice about reading the documentation.
  6. - -
  7. Checkout LLVM: -
      -
    • cd where-you-want-llvm-to-live -
    • svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
    • -
    -
  8. - -
  9. Checkout Clang: -
      -
    • cd where-you-want-llvm-to-live -
    • cd llvm/tools -
    • svn co http://llvm.org/svn/llvm-project/cfe/trunk clang
    • -
    -
  10. - -
  11. Checkout Compiler-RT: -
      -
    • cd where-you-want-llvm-to-live -
    • cd llvm/projects -
    • svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk - compiler-rt
    • -
    -
  12. - -
  13. Get the Test Suite Source Code [Optional] -
      -
    • cd where-you-want-llvm-to-live -
    • cd llvm/projects -
    • svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
    • -
    -
  14. - -
  15. Configure and build LLVM and Clang: -
      -
    • cd where-you-want-to-build-llvm
    • -
    • mkdir build (for building without polluting the source dir)
    • -
    • cd build
    • -
    • ../llvm/configure [options] -
      Some common options: - -
        -
      • --prefix=directory - - Specify for directory the full pathname of where you - want the LLVM tools and libraries to be installed (default - /usr/local).
      • -
      - -
        -
      • --enable-optimized - - Compile with optimizations enabled (default is NO).
      • -
      - -
        -
      • --enable-assertions - - Compile with assertion checks enabled (default is YES).
      • -
      -
    • -
    • make [-j] - The -j specifies the number of jobs (commands) to - run simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. - The --enabled-optimized configure option is used to specify a Release build.
    • -
    • make check-all - - This run the regression tests to ensure everything is in working order.
    • -
    • make update - - This command is used to update all the svn repositories at once, rather then - having to cd into the individual repositories and running - svn update.
    • -
    • It is also possible to use CMake instead of the makefiles. With CMake - it is also possible to generate project files for several IDEs: Eclipse - CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.
    • -
    • If you get an "internal compiler error (ICE)" or test failures, see - below.
    • - -
    -
  16. - -
- -

Consult the Getting Started with LLVM section for -detailed information on configuring and compiling LLVM. See Setting Up Your Environment for tips that simplify -working with the Clang front end and LLVM tools. Go to Program -Layout to learn about the layout of the source code tree.

- -
- - -

- Requirements -

- - -
- -

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.

- - -

- Hardware -

- -
- -

LLVM is known to work on the following platforms:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OSArchCompilers
AuroraUXx861GCC
Linuxx861GCC
Linuxamd64GCC
SolarisV9 (Ultrasparc)GCC
FreeBSDx861GCC
FreeBSDamd64GCC
MacOS X2PowerPCGCC
MacOS X2,9x86GCC
Cygwin/Win32x861,8, - 11GCC 3.4.X, binutils 2.20
MinGW/Win32x861,6, - 8, 10, - 11GCC 3.4.X, binutils 2.20
- -

LLVM has partial support for the following platforms:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OSArchCompilers
Windowsx861Visual Studio 2008 or higher4,5
AIX3,4PowerPCGCC
Linux3,5PowerPCGCC
Linux7AlphaGCC
Linux7Itanium (IA-64)GCC
HP-UX7Itanium (IA-64)HP aCC
Windows x64x86-64mingw-w64's GCC-4.5.x12
- -

Notes:

- - - -

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 ONLY_TOOLS="tools you need" to make. The Release build -requires considerably less space.

- -

The LLVM suite may 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.

- -
- - -

- Software -

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PackageVersionNotes
GNU Make3.79, 3.79.1Makefile/build processor
GCC3.4.2C/C++ compiler1
TeXinfo4.5For building the CFE
SVN≥1.3Subversion access to LLVM2
DejaGnu1.4.2Automated test suite3
tcl8.3, 8.4Automated test suite3
expect5.38.0Automated test suite3
perl≥5.6.0Utilities
GNU M4 - 1.4Macro processor for configuration4
GNU Autoconf2.60Configuration script builder4
GNU Automake1.9.6aclocal macro generator4
libtool1.5.22Shared library manager4
- -

Notes:

- - -

Additionally, your compilation host is expected to have the usual - plethora of Unix utilities. Specifically:

-
    -
  • ar - archive library builder
  • -
  • bzip2* - bzip2 command for distribution generation
  • -
  • bunzip2* - bunzip2 command for distribution checking
  • -
  • chmod - change permissions on a file
  • -
  • cat - output concatenation utility
  • -
  • cp - copy files
  • -
  • date - print the current date/time
  • -
  • echo - print to standard output
  • -
  • egrep - extended regular expression search utility
  • -
  • find - find files/dirs in a file system
  • -
  • grep - regular expression search utility
  • -
  • gzip* - gzip command for distribution generation
  • -
  • gunzip* - gunzip command for distribution checking
  • -
  • install - install directories/files
  • -
  • mkdir - create a directory
  • -
  • mv - move (rename) files
  • -
  • ranlib - symbol table builder for archive libraries
  • -
  • rm - remove (delete) files and directories
  • -
  • sed - stream editor for transforming output
  • -
  • sh - Bourne shell for make build scripts
  • -
  • tar - tape archive for distribution generation
  • -
  • test - test things in file system
  • -
  • unzip* - unzip command for distribution checking
  • -
  • zip* - zip command for distribution generation
  • -
-
- - -

- Broken versions of GCC and other tools -

- -
- -

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 4.2 (and higher) or Clang. -Other versions of GCC will probably work as well. GCC versions listed -here are known to not work. If you are using one of these versions, please try -to upgrade your GCC to something more recent. If you run into a problem with a -version of GCC not listed here, please let -us know. Please use the "gcc -v" command to find out which version -of GCC you are using. -

- -

GCC versions prior to 3.0: GCC 2.96.x and before had several -problems in the STL that effectively prevent it from compiling LLVM. -

- -

GCC 3.2.2 and 3.2.3: These versions of GCC fails to compile LLVM with -a bogus template error. This was fixed in later GCCs.

- -

GCC 3.3.2: This version of GCC suffered from a serious bug which causes it to crash in -the "convert_from_eh_region_ranges_1" GCC function.

- -

Cygwin GCC 3.3.3: The version of GCC 3.3.3 commonly shipped with - Cygwin does not work.

-

SuSE GCC 3.3.3: 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.

-

GCC 3.4.0 on linux/x86 (32-bit): 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).

-

GCC 3.4.2 on linux/x86 (32-bit): 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 ..."

-

GCC 3.4.x on X86-64/amd64: GCC - miscompiles portions of LLVM.

-

GCC 3.4.4 (CodeSourcery ARM 2005q3-2): this compiler miscompiles LLVM - when building with optimizations enabled. It appears to work with - "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1" or build a debug - build.

-

IA-64 GCC 4.0.0: The IA-64 version of GCC 4.0.0 is known to - miscompile LLVM.

-

Apple Xcode 2.3: 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".

-

GCC 4.1.1: 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.

-

GCC 4.1.1 on X86-64/amd64: GCC - miscompiles portions of LLVM 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.

-

GCC 4.1.2 on OpenSUSE: Seg faults during libstdc++ build and on x86_64 -platforms compiling md5.c gets a mangled constant.

-

GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian: Appears -to miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining -about symbols remaining in the table on destruction.

-

GCC 4.1.2 20071124 (Red Hat 4.1.2-42): Suffers from the same symptoms -as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).

-

Cygwin GCC 4.3.2 20080827 (beta) 2: - Users reported various problems related - with link errors when using this GCC version.

-

Debian GCC 4.3.2 on X86: Crashes building some files in LLVM 2.6.

-

GCC 4.3.3 (Debian 4.3.3-10) on ARM: 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.

-

GCC 4.3.5 and GCC 4.4.5 on ARM: These can miscompile value >> -1 even at -O0. A test failure in test/Assembler/alignstack.ll is -one symptom of the problem. -

GNU ld 2.16.X. 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.

- -

GNU binutils 2.17: Binutils 2.17 contains a bug 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).

- -

GNU Binutils 2.19.1 Gold: This version of Gold contained -a bug -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.

- -
- -
- - -

- Getting Started with LLVM -

- - -
- -

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.

- -

The later sections of this guide describe the general layout of the the LLVM source tree, a simple example using the LLVM tool chain, and links to find more information about LLVM or to get -help via e-mail.

- - -

- Terminology and Notation -

- -
- -

Throughout this manual, the following names are used to denote paths -specific to the local system and working environment. These are not -environment variables you need to set but just strings used in the rest -of this document below. 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:

- -
-
SRC_ROOT -
- This is the top level directory of the LLVM source tree. -

- -
OBJ_ROOT -
- 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). -

- -
- -
- - -

- Setting Up Your Environment -

- -
- -

-In order to compile and use LLVM, you may need to set some environment -variables. - -

-
LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs
-
[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 - lib directory.
-
- -
- - -

- Unpacking the LLVM Archives -

- -
- -

-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. -

- -

The files are as follows, with x.y marking the version number: -

-
llvm-x.y.tar.gz
-
Source release for the LLVM libraries and tools.
- -
llvm-test-x.y.tar.gz
-
Source release for the LLVM test-suite.
- -
llvm-gcc-4.2-x.y.source.tar.gz
-
Source release of the llvm-gcc-4.2 front end. See README.LLVM in the root - directory for build instructions.
- -
llvm-gcc-4.2-x.y-platform.tar.gz
-
Binary release of the llvm-gcc-4.2 front end for a specific platform.
- -
- -
- - -

- Checkout LLVM from Subversion -

- -
- -

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:

- -
    -
  • cd where-you-want-llvm-to-live
  • -
  • Read-Only: svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
  • -
  • Read-Write:svn co https://user@llvm.org/svn/llvm-project/llvm/trunk - llvm
  • -
- - -

This will create an 'llvm' directory in the current -directory and fully populate it with the LLVM source code, Makefiles, -test directories, and local copies of documentation files.

- -

If you want to get a specific release (as opposed to the most recent -revision), you can checkout it from the 'tags' directory (instead of -'trunk'). The following releases are located in the following -subdirectories of the 'tags' directory:

- -
    -
  • Release 2.9: RELEASE_29/final
  • -
  • Release 2.8: RELEASE_28
  • -
  • Release 2.7: RELEASE_27
  • -
  • Release 2.6: RELEASE_26
  • -
  • Release 2.5: RELEASE_25
  • -
  • Release 2.4: RELEASE_24
  • -
  • Release 2.3: RELEASE_23
  • -
  • Release 2.2: RELEASE_22
  • -
  • Release 2.1: RELEASE_21
  • -
  • Release 2.0: RELEASE_20
  • -
  • Release 1.9: RELEASE_19
  • -
  • Release 1.8: RELEASE_18
  • -
  • Release 1.7: RELEASE_17
  • -
  • Release 1.6: RELEASE_16
  • -
  • Release 1.5: RELEASE_15
  • -
  • Release 1.4: RELEASE_14
  • -
  • Release 1.3: RELEASE_13
  • -
  • Release 1.2: RELEASE_12
  • -
  • Release 1.1: RELEASE_11
  • -
  • Release 1.0: RELEASE_1
  • -
- -

If you would like to get the LLVM test suite (a separate package as of 1.4), -you get it from the Subversion repository:

- -
-
-% cd llvm/projects
-% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
-
-
- -

By placing it in the llvm/projects, it will be automatically -configured by the LLVM configure script as well as automatically updated when -you run svn update.

- -
- - -

- GIT mirror -

- -
- -

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 trunk for each project. You can do the - read-only GIT clone of LLVM via:

- -
-git clone http://llvm.org/git/llvm.git
-
- -

If you want to check out clang too, run:

- -
-git clone http://llvm.org/git/llvm.git
-cd llvm/tools
-git clone http://llvm.org/git/clang.git
-
- -

-Since the upstream repository is in Subversion, you should use -"git pull --rebase" -instead of "git pull" to avoid generating a non-linear -history in your clone. -To configure "git pull" to pass --rebase by default -on the master branch, run the following command: -

- -
-git config branch.master.rebase true
-
- -

Sending patches with Git

-
-

-Please read Developer Policy, too. -

- -

-Assume master points the upstream and mybranch points your -working branch, and mybranch is rebased onto master. -At first you may check sanity of whitespaces: -

- -
-git diff --check master..mybranch
-
- -

-The easiest way to generate a patch is as below: -

- -
-git diff master..mybranch > /path/to/mybranch.diff
-
- -

-It is a little different from svn-generated diff. git-diff-generated diff has -prefixes like a/ and b/. Don't worry, most developers might -know it could be accepted with patch -p1 -N. -

- -

-But you may generate patchset with git-format-patch. It generates -by-each-commit patchset. To generate patch files to attach to your article: -

- -
-git format-patch --no-attach master..mybranch -o /path/to/your/patchset
-
- -

-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]. -

- -
-git format-patch --attach master..mybranch --stdout | git imap-send
-
- -

-Then, your .git/config should have [imap] sections. -

- -
-[imap]
-        host = imaps://imap.gmail.com
-        user = your.gmail.account@gmail.com
-        pass = himitsu!
-        port = 993
-        sslverify = false
-; in English
-        folder = "[Gmail]/Drafts"
-; example for Japanese, "Modified UTF-7" encoded.
-        folder = "[Gmail]/&Tgtm+DBN-"
-; example for Traditional Chinese
-        folder = "[Gmail]/&g0l6Pw-"
-
- -
- -

For developers to work with git-svn

-
- -

To set up clone from which you can submit code using - git-svn, run:

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

To update this clone without generating git-svn tags that conflict -with the upstream git repo, run:

- -
-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)
-
- -

This leaves your working directories on their master branches, so -you'll need to checkout each working branch individually and -rebase 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.)

- -

The git-svn metadata can get out of sync after you mess around with -branches and dcommit. When that happens, git svn -dcommit stops working, complaining about files with uncommitted -changes. The fix is to rebuild the metadata:

- -
-rm -rf .git/svn
-git svn rebase -l
-
- -
- -
- - -

- Local LLVM Configuration -

- -
- -

Once checked out from the Subversion repository, the LLVM suite source - code must be -configured via the configure script. This script sets variables in the -various *.in files, most notably llvm/Makefile.config and -llvm/include/Config/config.h. It also populates OBJ_ROOT with -the Makefiles needed to begin building LLVM.

- -

The following environment variables are used by the configure -script to configure the build system:

- - - - - - - - - - - -
VariablePurpose
CCTells configure which C compiler to use. By default, - configure will look for the first GCC C compiler in - PATH. Use this variable to override - configure's default behavior.
CXXTells configure which C++ compiler to use. By default, - configure will look for the first GCC C++ compiler in - PATH. Use this variable to override - configure's default behavior.
- -

The following options can be used to set or enable LLVM specific options:

- -
-
--enable-optimized
-
- 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). -

-
-
--enable-debug-runtime
-
- Enables debug symbols in the runtime libraries. The default is to strip - debug symbols from the runtime libraries. -
-
--enable-jit
-
- 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. -

-
-
--enable-targets=target-option
-
Controls which targets will be built and linked into llc. The default - value for target_options 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:
- arm, cbe, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu, x86, x86_64, xcore. -

-
--enable-doxygen
-
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.
-
--with-udis86
-
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 udis86 x86 (both 32 and 64 - bits) disassembler library.
-
- -

To configure LLVM, follow these steps:

- -
    -
  1. Change directory into the object root directory:

    - -
    % cd OBJ_ROOT
  2. - -
  3. Run the configure script located in the LLVM source - tree:

    - -
    -
    % SRC_ROOT/configure --prefix=/install/path [other options]
    -
  4. -
- -
- - -

- Compiling the LLVM Suite Source Code -

- -
- -

Once you have configured LLVM, you can build it. There are three types of -builds:

- -
-
Debug Builds -
- These builds are the default when one is using an Subversion checkout and - types gmake (unless the --enable-optimized 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 --disable-optimized option must be passed - to configure. -

- -
Release (Optimized) Builds -
- These builds are enabled with the --enable-optimized option to - configure or by specifying ENABLE_OPTIMIZED=1 on the - gmake 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. -

- -
Profile Builds -
- These builds are for use with profiling. They compile profiling - information into the code for use with programs like gprof. - Profile builds must be started by specifying ENABLE_PROFILING=1 - on the gmake command line. -
- -

Once you have LLVM configured, you can build it by entering the -OBJ_ROOT directory and issuing the following command:

- -
% gmake
- -

If the build fails, please check here to see if you -are using a version of GCC that is known not to compile LLVM.

- -

-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:

- -
% gmake -j2
- -

There are several special targets which are useful when working with the LLVM -source code:

- -
-
gmake clean -
- Removes all files generated by the build. This includes object files, - generated C/C++ files, libraries, and executables. -

- -
gmake dist-clean -
- Removes everything that gmake clean does, but also removes files - generated by configure. It attempts to return the source tree to the - original state in which it was shipped. -

- -
gmake install -
- Installs LLVM header files, libraries, tools, and documentation in a - hierarchy - under $PREFIX, specified with ./configure --prefix=[dir], which - defaults to /usr/local. -

- -
gmake -C runtime install-bytecode -
- 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. -

-
- -

Please see the Makefile Guide for further -details on these make targets and descriptions of other targets -available.

- -

It is also possible to override default values from configure by -declaring variables on the command line. The following are some examples:

- -
-
gmake ENABLE_OPTIMIZED=1 -
- Perform a Release (Optimized) build. -

- -
gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1 -
- Perform a Release (Optimized) build without assertions enabled. -

- -
gmake ENABLE_OPTIMIZED=0 -
- Perform a Debug build. -

- -
gmake ENABLE_PROFILING=1 -
- Perform a Profiling build. -

- -
gmake VERBOSE=1 -
- Print what gmake is doing on standard output. -

- -
gmake TOOL_VERBOSE=1
-
Ask each tool invoked by the makefiles to print out what it is doing on - the standard output. This also implies VERBOSE=1. -

-
- -

Every directory in the LLVM object tree includes a Makefile to build -it and any subdirectories that it contains. Entering any directory inside the -LLVM object tree and typing gmake should rebuild anything in or below -that directory that is out of date.

- -
- - -

- Cross-Compiling LLVM -

- -
-

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 --build and - --host options that are different. The values of these options must - be legal target triples that your GCC compiler supports.

- -

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).

-
- - -

- The Location of LLVM Object Files -

- -
- -

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.

- -

This is accomplished in the typical autoconf manner:

- -
    -
  • Change directory to where the LLVM object files should live:

    - -
    % cd OBJ_ROOT
  • - -
  • Run the configure script found in the LLVM source - directory:

    - -
    % SRC_ROOT/configure
  • -
- -

The LLVM build will place files underneath OBJ_ROOT in directories -named after the build type:

- -
-
Debug Builds with assertions enabled (the default) -
-
-
Tools -
OBJ_ROOT/Debug+Asserts/bin -
Libraries -
OBJ_ROOT/Debug+Asserts/lib -
-

- -
Release Builds -
-
-
Tools -
OBJ_ROOT/Release/bin -
Libraries -
OBJ_ROOT/Release/lib -
-

- -
Profile Builds -
-
-
Tools -
OBJ_ROOT/Profile/bin -
Libraries -
OBJ_ROOT/Profile/lib -
-
- -
- - -

- Optional Configuration Items -

- -
- -

-If you're running on a Linux system that supports the "binfmt_misc" -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):

- -
-
-$ 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
-
-
- -

-This allows you to execute LLVM bitcode files directly. On Debian, you -can also use this command instead of the 'echo' command above: -

- -
-
-$ sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
-
-
- -
- -
- - -

- Program Layout -

- - -
- -

One useful source of information about the LLVM source base is the LLVM doxygen documentation available at http://llvm.org/doxygen/. -The following is a brief introduction to code layout:

- - -

- llvm/examples -

- -
-

This directory contains some simple examples of how to use the LLVM IR and - JIT.

-
- - -

- llvm/include -

- -
- -

This directory contains public header files exported from the LLVM -library. The three main subdirectories of this directory are:

- -
-
llvm/include/llvm
-
This directory contains all of the LLVM specific header files. This - directory also has subdirectories for different portions of LLVM: - Analysis, CodeGen, Target, Transforms, - etc...
- -
llvm/include/llvm/Support
-
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. -
- -
llvm/include/llvm/Config
-
This directory contains header files configured by the configure - 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 configure script generates.
-
-
- - -

- llvm/lib -

- -
- -

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 tools.

- -
-
llvm/lib/VMCore/
-
This directory holds the core LLVM source files that implement core - classes like Instruction and BasicBlock.
- -
llvm/lib/AsmParser/
-
This directory holds the source code for the LLVM assembly language parser - library.
- -
llvm/lib/BitCode/
-
This directory holds code for reading and write LLVM bitcode.
- -
llvm/lib/Analysis/
This directory contains a variety of - different program analyses, such as Dominator Information, Call Graphs, - Induction Variables, Interval Identification, Natural Loop Identification, - etc.
- -
llvm/lib/Transforms/
-
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.
- -
llvm/lib/Target/
-
This directory contains files that describe various target architectures - for code generation. For example, the llvm/lib/Target/X86 - directory holds the X86 machine description while - llvm/lib/Target/ARM implements the ARM backend.
- -
llvm/lib/CodeGen/
-
This directory contains the major parts of the code generator: Instruction - Selector, Instruction Scheduling, and Register Allocation.
- -
llvm/lib/MC/
-
(FIXME: T.B.D.)
- - -
llvm/lib/Debugger/
-
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.
- -
llvm/lib/ExecutionEngine/
-
This directory contains libraries for executing LLVM bitcode directly - at runtime in both interpreted and JIT compiled fashions.
- -
llvm/lib/Support/
-
This directory contains the source code that corresponds to the header - files located in llvm/include/ADT/ - and llvm/include/Support/.
-
- -
- - -

- llvm/projects -

- -
-

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 llvm/projects/sample for an example of how - to set up your own project.

-
- - -

- llvm/runtime -

- -
- -

This directory contains libraries which are compiled into LLVM bitcode and -used when linking programs with the Clang front end. Most of these libraries are -skeleton versions of real libraries; for example, libc is a stripped down -version of glibc.

- -

Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front -end to compile.

- -
- - -

- llvm/test -

- -
-

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.

-
- - -

- test-suite -

- -
-

This is not a directory in the normal llvm module; it is a separate - Subversion - module that must be checked out (usually to projects/test-suite). - 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 - Testing Guide document.

-
- - -

- llvm/tools -

- -
- -

The tools 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 tool_name -help. The -following is a brief introduction to the most important tools. More detailed -information is in the Command Guide.

- -
- -
bugpoint
-
bugpoint 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 HowToSubmitABug.html for more information - on using bugpoint.
- -
llvm-ar
-
The archiver produces an archive containing - the given LLVM bitcode files, optionally with an index for faster - lookup.
- -
llvm-as
-
The assembler transforms the human readable LLVM assembly to LLVM - bitcode.
- -
llvm-dis
-
The disassembler transforms the LLVM bitcode to human readable - LLVM assembly.
- -
llvm-ld
-
llvm-ld 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.
- -
llvm-link
-
llvm-link, not surprisingly, links multiple LLVM modules into - a single program.
- -
lli
-
lli 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, lli - will function as a Just-In-Time compiler (if the functionality was compiled - in), and will execute the code much faster than the interpreter.
- -
llc
-
llc is the LLVM backend compiler, which - translates LLVM bitcode to a native code assembly file or to C code (with - the -march=c option).
- -
llvm-gcc
-
llvm-gcc 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 -emit-llvm option) instead of the - usual machine code output. It works just like any other GCC compiler, - taking the typical -c, -S, -E, -o options that are typically used. - Additionally, the the source code for llvm-gcc is available as a - separate Subversion module.
- -
opt
-
opt 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 'opt -help' command is a good way to - get a list of the program transformations available in LLVM.
-
opt 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.
-
-
- - -

- llvm/utils -

- -
- -

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.

- -
-
codegen-diff
codegen-diff 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 `perldoc codegen-diff'.

- -
emacs/
The emacs 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 README file in that directory.

- -
getsrcs.sh
The getsrcs.sh 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: - xemacs `utils/getsources.sh` from the top of your LLVM source - tree.

- -
llvmgrep
-
This little tool performs an "egrep -H -n" on each source file in LLVM and - passes to it a regular expression provided on llvmgrep's command - line. This is a very efficient way of searching the source base for a - particular regular expression.
- -
makellvm
The makellvm 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 - llvm/lib/Target/Sparc, if makellvm is in your path, - simply running makellvm llc will make a build of the current - directory, switch to directory llvm/tools/llc and build it, - causing a re-linking of LLC.

- -
TableGen/
The TableGen directory contains - the tool used to generate register descriptions, instruction set - descriptions, and even assemblers from common TableGen description - files.

- -
vim/
The vim 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 README file in that directory.

- -
- -
- -
- - -

- An Example Using the LLVM Tool Chain -

- - -
-

This section gives an example of using LLVM with the Clang front end.

- - -

- Example with clang -

- -
- -
    -
  1. First, create a simple C file, name it 'hello.c':

    - -
    -
    -#include <stdio.h>
    -
    -int main() {
    -  printf("hello world\n");
    -  return 0;
    -}
    -
  2. - -
  3. Next, compile the C file into a native executable:

    - -
    % clang hello.c -o hello
    - -

    Note that clang works just like GCC by default. The standard -S and - -c arguments work as usual (producing a native .s or .o file, - respectively).

  4. - -
  5. Next, compile the C file into a LLVM bitcode file:

    - -
    -
    % clang -O3 -emit-llvm hello.c -c -o hello.bc
    - -

    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 standard LLVM tools on - the bitcode file.

  6. - -
  7. Run the program in both forms. To run the program, use:

    - -
    % ./hello
    - -

    and

    - -
    % lli hello.bc
    - -

    The second examples shows how to invoke the LLVM JIT, lli.

  8. - -
  9. Use the llvm-dis utility to take a look at the LLVM assembly - code:

    - -
    -
    llvm-dis < hello.bc | less
    -
  10. - -
  11. Compile the program to native assembly using the LLC code - generator:

    - -
    % llc hello.bc -o hello.s
  12. - -
  13. Assemble the native assembly language file into a program:

    - -
    -
    -Solaris: % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
    -
    -Others:  % gcc hello.s -o hello.native
    -
    -
  14. - -
  15. Execute the native code program:

    - -
    % ./hello.native
    - -

    Note that using clang to compile directly to native code (i.e. when - the -emit-llvm option is not present) does steps 6/7/8 for you.

    -
  16. - -
- -
- -
- - -

- Common Problems -

- - -
- -

If you are having problems building or using LLVM, or if you have any other -general questions about LLVM, please consult the Frequently -Asked Questions page.

- -
- - -

- Links -

- - -
- -

This document is just an introduction 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:

- - - -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- Reid Spencer
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - diff --git a/cpp/llvm/docs/GettingStartedVS.html b/cpp/llvm/docs/GettingStartedVS.html deleted file mode 100644 index 2125a737..00000000 --- a/cpp/llvm/docs/GettingStartedVS.html +++ /dev/null @@ -1,368 +0,0 @@ - - - - - Getting Started with LLVM System for Microsoft Visual Studio - - - - -

- Getting Started with the LLVM System using Microsoft Visual Studio -

- - - -
-

Written by: The LLVM Team

-
- - - -

- Overview -

- - -
- -

Welcome to LLVM on Windows! This document only covers LLVM on Windows using - Visual Studio, not mingw or cygwin. In order to get started, you first need to - know some basic information.

- -

There are many different projects that compose LLVM. The first is the LLVM - suite. This contains all of the tools, libraries, and header files needed to - use LLVM. It contains an assembler, disassembler, - bitcode analyzer and bitcode optimizer. It also contains a test suite that can - be used to test the LLVM tools.

- -

Another useful project on Windows is - clang. Clang is a C family - ([Objective]C/C++) compiler. Clang mostly works on Windows, but does not - currently understand all of the Microsoft extensions to C and C++. Because of - this, clang cannot parse the C++ standard library included with Visual Studio, - nor parts of the Windows Platform SDK. However, most standard C programs do - compile. Clang can be used to emit bitcode, directly emit object files or - even linked executables using Visual Studio's link.exe

- -

The large LLVM test suite cannot be run on the Visual Studio port at this - time.

- -

Most of the tools build and work. bugpoint does build, but does - not work.

- -

Additional information about the LLVM directory structure and tool chain - can be found on the main Getting Started - page.

- -
- - -

- Requirements -

- - -
- -

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.

- - -

- Hardware -

- -
- -

Any system that can adequately run Visual Studio 2008 is fine. The LLVM - source tree and object files, libraries and executables will consume - approximately 3GB.

- -
- - -

Software

-
- -

You will need Visual Studio 2008 or higher. Earlier versions of Visual - Studio have bugs, are not completely compatible, or do not support the C++ - standard well enough.

- -

You will also need the CMake build - system since it generates the project files you will use to build with.

- -

If you would like to run the LLVM tests you will need - Python. Versions 2.4-2.7 are known to - work. You will need "GnuWin32" - tools, too.

- -

Do not install the LLVM directory tree into a path containing spaces (e.g. - C:\Documents and Settings\...) as the configure step will fail.

- -
- -
- - -

- Getting Started -

- - -
- -

Here's the short story for getting up and running quickly with LLVM:

- -
    -
  1. Read the documentation.
  2. -
  3. Seriously, read the documentation.
  4. -
  5. Remember that you were warned twice about reading the documentation.
  6. - -
  7. Get the Source Code -
      -
    • With the distributed files: -
        -
      1. cd where-you-want-llvm-to-live -
      2. gunzip --stdout llvm-version.tar.gz | tar -xvf - -       or use WinZip -
      3. cd llvm
      4. -
    • - -
    • With anonymous Subversion access: -
        -
      1. cd where-you-want-llvm-to-live
      2. -
      3. svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
      4. -
      5. cd llvm
      6. -
    • -
  8. - -
  9. Use CMake to generate up-to-date - project files: -
      -
    • Once CMake is installed then the simplest way is to just start the - CMake GUI, select the directory where you have LLVM extracted to, and the - default options should all be fine. One option you may really want to - change, regardless of anything else, might be the CMAKE_INSTALL_PREFIX - setting to select a directory to INSTALL to once compiling is complete, - although installation is not mandatory for using LLVM. Another important - option is LLVM_TARGETS_TO_BUILD, which controls the LLVM target - architectures that are included on the build. -
    • See the LLVM CMake guide for - detailed information about how to configure the LLVM - build.
    • -
    -
  10. - -
  11. Start Visual Studio -
      -
    • In the directory you created the project files will have - an llvm.sln file, just double-click on that to open - Visual Studio.
    • -
  12. - -
  13. Build the LLVM Suite: -
      -
    • The projects may still be built individually, but - to build them all do not just select all of them in batch build (as some - are meant as configuration projects), but rather select and build just - the ALL_BUILD project to build everything, or the INSTALL project, which - first builds the ALL_BUILD project, then installs the LLVM headers, libs, - and other useful things to the directory set by the CMAKE_INSTALL_PREFIX - setting when you first configured CMake.
    • -
    • The Fibonacci project is a sample program that uses the JIT. - Modify the project's debugging properties to provide a numeric - command line argument or run it from the command line. The - program will print the corresponding fibonacci value.
    • -
  14. - -
  15. Test LLVM on Visual Studio: -
      -
    • If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR - on CMake for the path to GnuWin32.
    • -
    • You can run LLVM tests by merely building the project - "check". The test results will be shown in the VS output - window.
    • -
    -
  16. - - -
  17. Test LLVM: -
      -
    • The LLVM tests can be run by cding to the llvm source directory - and running: - -
      -
      -% llvm-lit test
      -
      -
      - -

      Note that quite a few of these test will fail.

      -
    • - -
    • A specific test or test directory can be run with: - -
      -
      -% llvm-lit test/path/to/test
      -
      -
      -
    • -
    -
- -
- - -

- An Example Using the LLVM Tool Chain -

- - -
- -
    -
  1. First, create a simple C file, name it 'hello.c':

    - -
    -
    -#include <stdio.h>
    -int main() {
    -  printf("hello world\n");
    -  return 0;
    -}
    -
  2. - -
  3. Next, compile the C file into a LLVM bitcode file:

    - -
    -
    -% clang -c hello.c -emit-llvm -o hello.bc
    -
    -
    - -

    This will create the result file hello.bc which is the LLVM - bitcode that corresponds the the compiled program and the library - facilities that it required. You can execute this file directly using - lli tool, compile it to native assembly with the llc, - optimize or analyze it further with the opt tool, etc.

    - -

    Alternatively you can directly output an executable with clang with: -

    - -
    -
    -% clang hello.c -o hello.exe
    -
    -
    - -

    The -o hello.exe is required because clang currently outputs - a.out when neither -o nor -c are given.

    - -
  4. Run the program using the just-in-time compiler:

    - -
    -
    -% lli hello.bc
    -
    -
    - -
  5. Use the llvm-dis utility to take a look at the LLVM assembly - code:

    - -
    -
    -% llvm-dis < hello.bc | more
    -
    -
  6. - -
  7. Compile the program to object code using the LLC code generator:

    - -
    -
    -% llc -filetype=obj hello.bc
    -
    -
  8. - -
  9. Link to binary using Microsoft link:

    - -
    -
    -% link hello.obj -defaultlib:libcmt
    -
    -
    - -
  10. Execute the native code program:

    - -
    -
    -% hello.exe
    -
    -
  11. -
- -
- - -

- Common Problems -

- - -
- -

If you are having problems building or using LLVM, or if you have any other -general questions about LLVM, please consult the Frequently -Asked Questions page.

- -
- - -

- Links -

- - -
- -

This document is just an introduction to how to use LLVM to do -some simple things... there are many more interesting and complicated things -that you can do that aren't documented here (but we'll gladly accept a patch -if you want to write something up!). For more information about LLVM, check -out:

- - - -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-01-25 14:00:23 -0800 (Wed, 25 Jan 2012) $ -
- - diff --git a/cpp/llvm/docs/GoldPlugin.html b/cpp/llvm/docs/GoldPlugin.html deleted file mode 100644 index 2c08bd03..00000000 --- a/cpp/llvm/docs/GoldPlugin.html +++ /dev/null @@ -1,227 +0,0 @@ - - - - - LLVM gold plugin - - - - -

LLVM gold plugin

-
    -
  1. Introduction
  2. -
  3. How to build it
  4. -
  5. Usage -
  6. -
  7. Licensing
  8. -
-
Written by Nick Lewycky
- - -

Introduction

- -
-

Building with link time optimization requires cooperation from the -system linker. LTO support on Linux systems requires that you use -the gold linker which supports -LTO via plugins. This is the same mechanism used by the -GCC LTO -project.

-

The LLVM gold plugin implements the -gold plugin interface -on top of -libLTO. -The same plugin can also be used by other tools such as ar and -nm. -

- -

How to build it

- -
-

You need to have gold with plugin support and build the LLVMgold -plugin. Check whether you have gold running /usr/bin/ld -v. It will -report “GNU gold” or else “GNU ld” if not. If you have -gold, check for plugin support by running /usr/bin/ld -plugin. If it -complains “missing argument” then you have plugin support. If not, -such as an “unknown option” error then you will either need to -build gold or install a version with plugin support.

-
    -
  • To build gold with plugin support: -
    -mkdir binutils
    -cd binutils
    -cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
    -{enter "anoncvs" as the password}
    -cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
    -mkdir build
    -cd build
    -../src/configure --enable-gold --enable-plugins
    -make all-gold
    -
    - That should leave you with binutils/build/gold/ld-new which supports the -plugin option. It also built would have -binutils/build/binutils/ar and nm-new which support plugins -but don't have a visible -plugin option, instead relying on the gold plugin -being present in ../lib/bfd-plugins relative to where the binaries are -placed. -
  • Build the LLVMgold plugin: Configure LLVM with - --with-binutils-include=/path/to/binutils/src/include and run - make. -
-
- -

Usage

- -
- -

The linker takes a -plugin option that points to the path of - the plugin .so file. To find out what link command gcc - would run in a given situation, run gcc -v [...] and look - for the line where it runs collect2. Replace that with - ld-new -plugin /path/to/LLVMgold.so to test it out. Once you're - ready to switch to using gold, backup your existing /usr/bin/ld - then replace it with ld-new.

- -

You can produce bitcode files from clang using - -emit-llvm or -flto, or the -O4 flag which is - synonymous with -O3 -flto.

- -

Any of these flags will also cause clang to look for the - gold plugin in the lib directory under its prefix and pass the - -plugin option to ld. It will not look for an alternate - linker, which is why you need gold to be the installed system linker in - your path.

- -

If you want ar and nm to work seamlessly as well, install - LLVMgold.so to /usr/lib/bfd-plugins. If you built your - own gold, be sure to install the ar and nm-new you built to - /usr/bin.

- - -

- Example of link time optimization -

- -
-

The following example shows a worked example of the gold plugin mixing - LLVM bitcode and native code. -

---- a.c ---
-#include <stdio.h>
-
-extern void foo1(void);
-extern void foo4(void);
-
-void foo2(void) {
-  printf("Foo2\n");
-}
-
-void foo3(void) {
-  foo4();
-}
-
-int main(void) {
-  foo1();
-}
-
---- b.c ---
-#include <stdio.h>
-
-extern void foo2(void);
-
-void foo1(void) {
-  foo2();
-}
-
-void foo4(void) {
-  printf("Foo4");
-}
-
---- command lines ---
-$ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
-$ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
-$ clang b.c -c -o b.o            # <-- b.o is native object file
-$ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
-
- -

Gold informs the plugin that foo3 is never referenced outside the IR, - leading LLVM to delete that function. However, unlike in the - libLTO - example gold does not currently eliminate foo4.

-
- -
- - -

- - Quickstart for using LTO with autotooled projects - -

- -
-

Once your system ld, ar, and nm all support LLVM - bitcode, everything is in place for an easy to use LTO build of autotooled - projects:

- -
    -
  • Follow the instructions on how to build LLVMgold.so.
  • -
  • Install the newly built binutils to $PREFIX
  • -
  • Copy Release/lib/LLVMgold.so to - $PREFIX/lib/bfd-plugins/
  • -
  • Set environment variables ($PREFIX is where you installed clang and - binutils): -
    -export CC="$PREFIX/bin/clang -flto"
    -export CXX="$PREFIX/bin/clang++ -flto"
    -export AR="$PREFIX/bin/ar"
    -export NM="$PREFIX/bin/nm"
    -export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
    -export CFLAGS="-O4"
    -
    -
  • -
  • Or you can just set your path: -
    -export PATH="$PREFIX/bin:$PATH"
    -export CC="clang -flto"
    -export CXX="clang++ -flto"
    -export RANLIB=/bin/true
    -export CFLAGS="-O4"
    -
  • -
  • Configure & build the project as usual: -
    -% ./configure && make && make check
    -
  • -
- -

The environment variable settings may work for non-autotooled projects - too, but you may need to set the LD environment variable as - well.

-
- - -

Licensing

- -
-

Gold is licensed under the GPLv3. LLVMgold uses the interface file -plugin-api.h from gold which means that the resulting LLVMgold.so -binary is also GPLv3. This can still be used to link non-GPLv3 programs just -as much as gold could without the plugin.

-
- - -
-
- Valid CSS - Valid HTML 4.01 - Nick Lewycky
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2010-04-16 23:58:21 -0800 (Fri, 16 Apr 2010) $ -
- - diff --git a/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt b/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt deleted file mode 100644 index f0861811..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt +++ /dev/null @@ -1,74 +0,0 @@ -Date: Sat, 18 Nov 2000 09:19:35 -0600 (CST) -From: Vikram Adve -To: Chris Lattner -Subject: a few thoughts - -I've been mulling over the virtual machine problem and I had some -thoughts about some things for us to think about discuss: - -1. We need to be clear on our goals for the VM. Do we want to emphasize - portability and safety like the Java VM? Or shall we focus on the - architecture interface first (i.e., consider the code generation and - processor issues), since the architecture interface question is also - important for portable Java-type VMs? - - This is important because the audiences for these two goals are very - different. Architects and many compiler people care much more about - the second question. The Java compiler and OS community care much more - about the first one. - - Also, while the architecture interface question is important for - Java-type VMs, the design constraints are very different. - - -2. Design issues to consider (an initial list that we should continue - to modify). Note that I'm not trying to suggest actual solutions here, - but just various directions we can pursue: - - a. A single-assignment VM, which we've both already been thinking about. - - b. A strongly-typed VM. One question is do we need the types to be - explicitly declared or should they be inferred by the dynamic compiler? - - c. How do we get more high-level information into the VM while keeping - to a low-level VM design? - - o Explicit array references as operands? An alternative is - to have just an array type, and let the index computations be - separate 3-operand instructions. - - o Explicit instructions to handle aliasing, e.g.s: - -- an instruction to say "I speculate that these two values are not - aliased, but check at runtime", like speculative execution in - EPIC? - -- or an instruction to check whether two values are aliased and - execute different code depending on the answer, somewhat like - predicated code in EPIC - - o (This one is a difficult but powerful idea.) - A "thread-id" field on every instruction that allows the static - compiler to generate a set of parallel threads, and then have - the runtime compiler and hardware do what they please with it. - This has very powerful uses, but thread-id on every instruction - is expensive in terms of instruction size and code size. - We would need to compactly encode it somehow. - - Also, this will require some reading on at least two other - projects: - -- Multiscalar architecture from Wisconsin - -- Simultaneous multithreading architecture from Washington - - o Or forget all this and stick to a traditional instruction set? - - -BTW, on an unrelated note, after the meeting yesterday, I did remember -that you had suggested doing instruction scheduling on SSA form instead -of a dependence DAG earlier in the semester. When we talked about -it yesterday, I didn't remember where the idea had come from but I -remembered later. Just giving credit where its due... - -Perhaps you can save the above as a file under RCS so you and I can -continue to expand on this. - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt b/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt deleted file mode 100644 index 81ca5391..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt +++ /dev/null @@ -1,199 +0,0 @@ -Date: Sun, 19 Nov 2000 16:23:57 -0600 (CST) -From: Chris Lattner -To: Vikram Adve -Subject: Re: a few thoughts - -Okay... here are a few of my thoughts on this (it's good to know that we -think so alike!): - -> 1. We need to be clear on our goals for the VM. Do we want to emphasize -> portability and safety like the Java VM? Or shall we focus on the -> architecture interface first (i.e., consider the code generation and -> processor issues), since the architecture interface question is also -> important for portable Java-type VMs? - -I forsee the architecture looking kinda like this: (which is completely -subject to change) - -1. The VM code is NOT guaranteed safe in a java sense. Doing so makes it - basically impossible to support C like languages. Besides that, - certifying a register based language as safe at run time would be a - pretty expensive operation to have to do. Additionally, we would like - to be able to statically eliminate many bounds checks in Java - programs... for example. - - 2. Instead, we can do the following (eventually): - * Java bytecode is used as our "safe" representation (to avoid - reinventing something that we don't add much value to). When the - user chooses to execute Java bytecodes directly (ie, not - precompiled) the runtime compiler can do some very simple - transformations (JIT style) to convert it into valid input for our - VM. Performance is not wonderful, but it works right. - * The file is scheduled to be compiled (rigorously) at a later - time. This could be done by some background process or by a second - processor in the system during idle time or something... - * To keep things "safe" ie to enforce a sandbox on Java/foreign code, - we could sign the generated VM code with a host specific private - key. Then before the code is executed/loaded, we can check to see if - the trusted compiler generated the code. This would be much quicker - than having to validate consistency (especially if bounds checks have - been removed, for example) - -> This is important because the audiences for these two goals are very -> different. Architects and many compiler people care much more about -> the second question. The Java compiler and OS community care much more -> about the first one. - -3. By focusing on a more low level virtual machine, we have much more room - for value add. The nice safe "sandbox" VM can be provided as a layer - on top of it. It also lets us focus on the more interesting compilers - related projects. - -> 2. Design issues to consider (an initial list that we should continue -> to modify). Note that I'm not trying to suggest actual solutions here, -> but just various directions we can pursue: - -Understood. :) - -> a. A single-assignment VM, which we've both already been thinking -> about. - -Yup, I think that this makes a lot of sense. I am still intrigued, -however, by the prospect of a minimally allocated VM representation... I -think that it could have definite advantages for certain applications -(think very small machines, like PDAs). I don't, however, think that our -initial implementations should focus on this. :) - -Here are some other auxiliary goals that I think we should consider: - -1. Primary goal: Support a high performance dynamic compilation - system. This means that we have an "ideal" division of labor between - the runtime and static compilers. Of course, the other goals of the - system somewhat reduce the importance of this point (f.e. portability - reduces performance, but hopefully not much) -2. Portability to different processors. Since we are most familiar with - x86 and solaris, I think that these two are excellent candidates when - we get that far... -3. Support for all languages & styles of programming (general purpose - VM). This is the point that disallows java style bytecodes, where all - array refs are checked for bounds, etc... -4. Support linking between different language families. For example, call - C functions directly from Java without using the nasty/slow/gross JNI - layer. This involves several subpoints: - A. Support for languages that require garbage collectors and integration - with languages that don't. As a base point, we could insist on - always using a conservative GC, but implement free as a noop, f.e. - -> b. A strongly-typed VM. One question is do we need the types to be -> explicitly declared or should they be inferred by the dynamic -> compiler? - - B. This is kind of similar to another idea that I have: make OOP - constructs (virtual function tables, class heirarchies, etc) explicit - in the VM representation. I believe that the number of additional - constructs would be fairly low, but would give us lots of important - information... something else that would/could be important is to - have exceptions as first class types so that they would be handled in - a uniform way for the entire VM... so that C functions can call Java - functions for example... - -> c. How do we get more high-level information into the VM while keeping -> to a low-level VM design? -> o Explicit array references as operands? An alternative is -> to have just an array type, and let the index computations be -> separate 3-operand instructions. - - C. In the model I was thinking of (subject to change of course), we - would just have an array type (distinct from the pointer - types). This would allow us to have arbitrarily complex index - expressions, while still distinguishing "load" from "Array load", - for example. Perhaps also, switch jump tables would be first class - types as well? This would allow better reasoning about the program. - -5. Support dynamic loading of code from various sources. Already - mentioned above was the example of loading java bytecodes, but we want - to support dynamic loading of VM code as well. This makes the job of - the runtime compiler much more interesting: it can do interprocedural - optimizations that the static compiler can't do, because it doesn't - have all of the required information (for example, inlining from - shared libraries, etc...) - -6. Define a set of generally useful annotations to add to the VM - representation. For example, a function can be analysed to see if it - has any sideeffects when run... also, the MOD/REF sets could be - calculated, etc... we would have to determine what is reasonable. This - would generally be used to make IP optimizations cheaper for the - runtime compiler... - -> o Explicit instructions to handle aliasing, e.g.s: -> -- an instruction to say "I speculate that these two values are not -> aliased, but check at runtime", like speculative execution in -> EPIC? -> -- or an instruction to check whether two values are aliased and -> execute different code depending on the answer, somewhat like -> predicated code in EPIC - -These are also very good points... if this can be determined at compile -time. I think that an epic style of representation (not the instruction -packing, just the information presented) could be a very interesting model -to use... more later... - -> o (This one is a difficult but powerful idea.) -> A "thread-id" field on every instruction that allows the static -> compiler to generate a set of parallel threads, and then have -> the runtime compiler and hardware do what they please with it. -> This has very powerful uses, but thread-id on every instruction -> is expensive in terms of instruction size and code size. -> We would need to compactly encode it somehow. - -Yes yes yes! :) I think it would be *VERY* useful to include this kind -of information (which EPIC architectures *implicitly* encode. The trend -that we are seeing supports this greatly: - -1. Commodity processors are getting massive SIMD support: - * Intel/Amd MMX/MMX2 - * AMD's 3Dnow! - * Intel's SSE/SSE2 - * Sun's VIS -2. SMP is becoming much more common, especially in the server space. -3. Multiple processors on a die are right around the corner. - -If nothing else, not designing this in would severely limit our future -expansion of the project... - -> Also, this will require some reading on at least two other -> projects: -> -- Multiscalar architecture from Wisconsin -> -- Simultaneous multithreading architecture from Washington -> -> o Or forget all this and stick to a traditional instruction set? - -Heh... :) Well, from a pure research point of view, it is almost more -attactive to go with the most extreme/different ISA possible. On one axis -you get safety and conservatism, and on the other you get degree of -influence that the results have. Of course the problem with pure research -is that often times there is no concrete product of the research... :) - -> BTW, on an unrelated note, after the meeting yesterday, I did remember -> that you had suggested doing instruction scheduling on SSA form instead -> of a dependence DAG earlier in the semester. When we talked about -> it yesterday, I didn't remember where the idea had come from but I -> remembered later. Just giving credit where its due... - -:) Thanks. - -> Perhaps you can save the above as a file under RCS so you and I can -> continue to expand on this. - -I think it makes sense to do so when we get our ideas more formalized and -bounce it back and forth a couple of times... then I'll do a more formal -writeup of our goals and ideas. Obviously our first implementation will -not want to do all of the stuff that I pointed out above... be we will -want to design the project so that we do not artificially limit ourselves -at sometime in the future... - -Anyways, let me know what you think about these ideas... and if they sound -reasonable... - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt b/cpp/llvm/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt deleted file mode 100644 index 8c452924..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt +++ /dev/null @@ -1,30 +0,0 @@ -From: Chris Lattner [mailto:sabre@nondot.org] -Sent: Wednesday, December 06, 2000 6:41 PM -To: Vikram S. Adve -Subject: Additional idea with respect to encoding - -Here's another idea with respect to keeping the common case instruction -size down (less than 32 bits ideally): - -Instead of encoding an instruction to operate on two register numbers, -have it operate on two negative offsets based on the current register -number. Therefore, instead of using: - -r57 = add r55, r56 (r57 is the implicit dest register, of course) - -We could use: - -r57 = add -2, -1 - -My guess is that most SSA references are to recent values (especially if -they correspond to expressions like (x+y*z+p*q/ ...), so the negative -numbers would tend to stay small, even at the end of the procedure (where -the implicit register destination number could be quite large). Of course -the negative sign is reduntant, so you would be storing small integers -almost all of the time, and 5-6 bits worth of register number would be -plenty for most cases... - -What do you think? - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt b/cpp/llvm/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt deleted file mode 100644 index 01b644b3..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt +++ /dev/null @@ -1,83 +0,0 @@ -SUMMARY -------- - -We met to discuss the LLVM instruction format and bytecode representation: - -ISSUES RESOLVED ---------------- - -1. We decided that we shall use a flat namespace to represent our - variables in SSA form, as opposed to having a two dimensional namespace - of the original variable and the SSA instance subscript. - -ARGUMENT AGAINST: - * A two dimensional namespace would be valuable when doing alias - analysis because the extra information can help limit the scope of - analysis. - -ARGUMENT FOR: - * Including this information would require that all users of the LLVM - bytecode would have to parse and handle it. This would slow down the - common case and inflate the instruction representation with another - infinite variable space. - -REASONING: - * It was decided that because original variable sources could be - reconstructed from SSA form in linear time, that it would be an - unjustified expense for the common case to include the extra - information for one optimization. Alias analysis itself is typically - greater than linear in asymptotic complexity, so this extra analaysis - would not affect the runtime of the optimization in a significant - way. Additionally, this would be an unlikely optimization to do at - runtime. - - -IDEAS TO CONSIDER ------------------ - -1. Including dominator information in the LLVM bytecode - representation. This is one example of an analysis result that may be - packaged with the bytecodes themselves. As a conceptual implementation - idea, we could include an immediate dominator number for each basic block - in the LLVM bytecode program. Basic blocks could be numbered according - to the order of occurrence in the bytecode representation. - -2. Including loop header and body information. This would facilitate - detection of intervals and natural loops. - -UNRESOLVED ISSUES ------------------ - -1. Will oSUIF provide enough of an infrastructure to support the research - that we will be doing? We know that it has less than stellar - performance, but hope that this will be of little importance for our - static compiler. This could affect us if we decided to do some IP - research. Also we do not yet understand the level of exception support - currently implemented. - -2. Should we consider the requirements of a direct hardware implementation - of the LLVM when we design it? If so, several design issues should - have their priorities shifted. The other option is to focus on a - software layer interpreting the LLVM in all cases. - -3. Should we use some form of packetized format to improve forward - compatibility? For example, we could design the system to encode a - packet type and length field before analysis information, to allow a - runtime to skip information that it didn't understand in a bytecode - stream. The obvious benefit would be for compatibility, the drawback - is that it would tend to splinter that 'standard' LLVM definition. - -4. Should we use fixed length instructions or variable length - instructions? Fetching variable length instructions is expensive (for - either hardware or software based LLVM runtimes), but we have several - 'infinite' spaces that instructions operate in (SSA register numbers, - type spaces, or packet length [if packets were implemented]). Several - options were mentioned including: - A. Using 16 or 32 bit numbers, which would be 'big enough' - B. A scheme similar to how UTF-8 works, to encode infinite numbers - while keeping small number small. - C. Use something similar to Huffman encoding, so that the most common - numbers are the smallest. - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt b/cpp/llvm/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt deleted file mode 100644 index 111706a3..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt +++ /dev/null @@ -1,39 +0,0 @@ -Date: Wed, 31 Jan 2001 12:04:33 -0600 -From: Vikram S. Adve -To: Chris Lattner -Subject: another thought - -I have a budding idea about making LLVM a little more ambitious: a -customizable runtime system that can be used to implement language-specific -virtual machines for many different languages. E.g., a C vm, a C++ vm, a -Java vm, a Lisp vm, .. - -The idea would be that LLVM would provide a standard set of runtime features -(some low-level like standard assembly instructions with code generation and -static and runtime optimization; some higher-level like type-safety and -perhaps a garbage collection library). Each language vm would select the -runtime features needed for that language, extending or customizing them as -needed. Most of the machine-dependent code-generation and optimization -features as well as low-level machine-independent optimizations (like PRE) -could be provided by LLVM and should be sufficient for any language, -simplifying the language compiler. (This would also help interoperability -between languages.) Also, some or most of the higher-level -machine-independent features like type-safety and access safety should be -reusable by different languages, with minor extensions. The language -compiler could then focus on language-specific analyses and optimizations. - -The risk is that this sounds like a universal IR -- something that the -compiler community has tried and failed to develop for decades, and is -universally skeptical about. No matter what we say, we won't be able to -convince anyone that we have a universal IR that will work. We need to -think about whether LLVM is different or if has something novel that might -convince people. E.g., the idea of providing a package of separable -features that different languages select from. Also, using SSA with or -without type-safety as the intermediate representation. - -One interesting starting point would be to discuss how a JVM would be -implemented on top of LLVM a bit more. That might give us clues on how to -structure LLVM to support one or more language VMs. - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt deleted file mode 100644 index c09cf1f0..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt +++ /dev/null @@ -1,67 +0,0 @@ -Date: Tue, 6 Feb 2001 20:27:37 -0600 (CST) -From: Chris Lattner -To: Vikram S. Adve -Subject: Type notation debate... - -This is the way that I am currently planning on implementing types: - -Primitive Types: -type ::= void|bool|sbyte|ubyte|short|ushort|int|uint|long|ulong - -Method: -typelist ::= typelisth | /*empty*/ -typelisth ::= type | typelisth ',' type -type ::= type (typelist) - -Arrays (without and with size): -type ::= '[' type ']' | '[' INT ',' type ']' - -Pointer: -type ::= type '*' - -Structure: -type ::= '{' typelist '}' - -Packed: -type ::= '<' INT ',' type '>' - -Simple examples: - -[[ %4, int ]] - array of (array of 4 (int)) -[ { int, int } ] - Array of structure -[ < %4, int > ] - Array of 128 bit SIMD packets -int (int, [[int, %4]]) - Method taking a 2d array and int, returning int - - -Okay before you comment, please look at: - -http://www.research.att.com/~bs/devXinterview.html - -Search for "In another interview, you defined the C declarator syntax as -an experiment that failed. However, this syntactic construct has been -around for 27 years and perhaps more; why do you consider it problematic -(except for its cumbersome syntax)?" and read that response for me. :) - -Now with this syntax, his example would be represented as: - -[ %10, bool (int, int) * ] * - -vs - -bool (*(*)[10])(int, int) - -in C. - -Basically, my argument for this type construction system is that it is -VERY simple to use and understand (although it IS different than C, it is -very simple and straightforward, which C is NOT). In fact, I would assert -that most programmers TODAY do not understand pointers to member -functions, and have to look up an example when they have to write them. - -In my opinion, it is critically important to have clear and concise type -specifications, because types are going to be all over the programs. - -Let me know your thoughts on this. :) - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt deleted file mode 100644 index 8bfefbf6..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt +++ /dev/null @@ -1,75 +0,0 @@ -Date: Thu, 8 Feb 2001 08:42:04 -0600 -From: Vikram S. Adve -To: Chris Lattner -Subject: RE: Type notation debate... - -Chris, - -> Okay before you comment, please look at: -> -> http://www.research.att.com/~bs/devXinterview.html - -I read this argument. Even before that, I was already in agreement with you -and him that the C declarator syntax is difficult and confusing. - -But in fact, if you read the entire answer carefully, he came to the same -conclusion I do: that you have to go with familiar syntax over logical -syntax because familiarity is such a strong force: - - "However, familiarity is a strong force. To compare, in English, we -live -more or less happily with the absurd rules for "to be" (am, are, is, been, -was, were, ...) and all attempts to simplify are treated with contempt or -(preferably) humor. It be a curious world and it always beed." - -> Basically, my argument for this type construction system is that it is -> VERY simple to use and understand (although it IS different than C, it is -> very simple and straightforward, which C is NOT). In fact, I would assert -> that most programmers TODAY do not understand pointers to member -> functions, and have to look up an example when they have to write them. - -Again, I don't disagree with this at all. But to some extent this -particular problem is inherently difficult. Your syntax for the above -example may be easier for you to read because this is the way you have been -thinking about it. Honestly, I don't find it much easier than the C syntax. -In either case, I would have to look up an example to write pointers to -member functions. - -But pointers to member functions are nowhere near as common as arrays. And -the old array syntax: - type [ int, int, ...] -is just much more familiar and clear to people than anything new you -introduce, no matter how logical it is. Introducing a new syntax that may -make function pointers easier but makes arrays much more difficult seems -very risky to me. - -> In my opinion, it is critically important to have clear and concise type -> specifications, because types are going to be all over the programs. - -I absolutely agree. But the question is, what is more clear and concise? -The syntax programmers are used to out of years of experience or a new -syntax that they have never seen that has a more logical structure. I think -the answer is the former. Sometimes, you have to give up a better idea -because you can't overcome sociological barriers to it. Qwerty keyboards -and Windows are two classic examples of bad technology that are difficult to -root out. - -P.S. Also, while I agree that most your syntax is more logical, there is -one part that isn't: - -Arrays (without and with size): -type ::= '[' type ']' | '[' INT ',' type ']'. - -The arrays with size lists the dimensions and the type in a single list. -That is just too confusing: - [10, 40, int] -This seems to be a 3-D array where the third dimension is something strange. -It is too confusing to have a list of 3 things, some of which are dimensions -and one is a type. Either of the following would be better: - - array [10, 40] of int -or - int [10, 40] - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt deleted file mode 100644 index 6e978415..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt +++ /dev/null @@ -1,53 +0,0 @@ -Date: Thu, 8 Feb 2001 14:31:05 -0600 (CST) -From: Chris Lattner -To: Vikram S. Adve -Subject: RE: Type notation debate... - -> Arrays (without and with size): -> type ::= '[' type ']' | '[' INT ',' type ']'. -> -> The arrays with size lists the dimensions and the type in a single list. -> That is just too confusing: - -> [10, 40, int] -> This seems to be a 3-D array where the third dimension is something strange. -> It is too confusing to have a list of 3 things, some of which are dimensions -> and one is a type. - -The above grammar indicates that there is only one integer parameter, ie -the upper bound. The lower bound is always implied to be zero, for -several reasons: - -* As a low level VM, we want to expose addressing computations - explicitly. Since the lower bound must always be known in a high level - language statically, the language front end can do the translation - automatically. -* This fits more closely with what Java needs, ie what we need in the - short term. Java arrays are always zero based. - -If a two element list is too confusing, I would recommend an alternate -syntax of: - -type ::= '[' type ']' | '[' INT 'x' type ']'. - -For example: - [12 x int] - [12x int] - [ 12 x [ 4x int ]] - -Which is syntactically nicer, and more explicit. - -> Either of the following would be better: -> array [10, 40] of int - -I considered this approach for arrays in general (ie array of int/ array -of 12 int), but found that it made declarations WAY too long. Remember -that because of the nature of llvm, you get a lot of types strewn all over -the program, and using the 'typedef' like facility is not a wonderful -option, because then types aren't explicit anymore. - -I find this email interesting, because you contradict the previous email -you sent, where you recommend that we stick to C syntax.... - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt deleted file mode 100644 index 83973244..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt +++ /dev/null @@ -1,89 +0,0 @@ -> But in fact, if you read the entire answer carefully, he came to the same -> conclusion I do: that you have to go with familiar syntax over logical -> syntax because familiarity is such a strong force: -> "However, familiarity is a strong force. To compare, in English, we -live -> more or less happily with the absurd rules for "to be" (am, are, is, been, -> was, were, ...) and all attempts to simplify are treated with contempt or -> (preferably) humor. It be a curious world and it always beed." - -Although you have to remember that his situation was considerably -different than ours. He was in a position where he was designing a high -level language that had to be COMPATIBLE with C. Our language is such -that a new person would have to learn the new, different, syntax -anyways. Making them learn about the type system does not seem like much -of a stretch from learning the opcodes and how SSA form works, and how -everything ties together... - -> > Basically, my argument for this type construction system is that it is -> > VERY simple to use and understand (although it IS different than C, it is -> > very simple and straightforward, which C is NOT). In fact, I would assert -> > that most programmers TODAY do not understand pointers to member -> > functions, and have to look up an example when they have to write them. - -> Again, I don't disagree with this at all. But to some extent this -> particular problem is inherently difficult. Your syntax for the above -> example may be easier for you to read because this is the way you have been -> thinking about it. Honestly, I don't find it much easier than the C syntax. -> In either case, I would have to look up an example to write pointers to -> member functions. - -I would argue that because the lexical structure of the language is self -consistent, any person who spent a significant amount of time programming -in LLVM directly would understand how to do it without looking it up in a -manual. The reason this does not work for C is because you rarely have to -declare these pointers, and the syntax is inconsistent with the method -declaration and calling syntax. - -> But pointers to member functions are nowhere near as common as arrays. - -Very true. If you're implementing an object oriented language, however, -remember that you have to do all the pointer to member function stuff -yourself.... so every time you invoke a virtual method one is involved -(instead of having C++ hide it for you behind "syntactic sugar"). - -> And the old array syntax: -> type [ int, int, ...] -> is just much more familiar and clear to people than anything new you -> introduce, no matter how logical it is. - -Erm... excuse me but how is this the "old array syntax"? If you are -arguing for consistency with C, you should be asking for 'type int []', -which is significantly different than the above (beside the above -introduces a new operator and duplicates information -needlessly). Basically what I am suggesting is exactly the above without -the fluff. So instead of: - - type [ int, int, ...] - -you use: - - type [ int ] - -> Introducing a new syntax that may -> make function pointers easier but makes arrays much more difficult seems -> very risky to me. - -This is not about function pointers. This is about consistency in the -type system, and consistency with the rest of the language. The point -above does not make arrays any more difficult to use, and makes the -structure of types much more obvious than the "c way". - -> > In my opinion, it is critically important to have clear and concise type -> > specifications, because types are going to be all over the programs. -> -> I absolutely agree. But the question is, what is more clear and concise? -> The syntax programmers are used to out of years of experience or a new -> syntax that they have never seen that has a more logical structure. I think -> the answer is the former. Sometimes, you have to give up a better idea -> because you can't overcome sociological barriers to it. Qwerty keyboards -> and Windows are two classic examples of bad technology that are difficult to -> root out. - -Very true, but you seem to be advocating a completely different Type -system than C has, in addition to it not offering the advantages of clear -structure that the system I recommended does... so you seem to not have a -problem with changing this, just with what I change it to. :) - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveComments.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveComments.txt deleted file mode 100644 index 5503233c..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveComments.txt +++ /dev/null @@ -1,120 +0,0 @@ -Ok, here are my comments and suggestions about the LLVM instruction set. -We should discuss some now, but can discuss many of them later, when we -revisit synchronization, type inference, and other issues. -(We have discussed some of the comments already.) - - -o We should consider eliminating the type annotation in cases where it is - essentially obvious from the instruction type, e.g., in br, it is obvious - that the first arg. should be a bool and the other args should be labels: - - br bool , label , label - - I think your point was that making all types explicit improves clarity - and readability. I agree to some extent, but it also comes at the cost - of verbosity. And when the types are obvious from people's experience - (e.g., in the br instruction), it doesn't seem to help as much. - - -o On reflection, I really like your idea of having the two different switch - types (even though they encode implementation techniques rather than - semantics). It should simplify building the CFG and my guess is it could - enable some significant optimizations, though we should think about which. - - -o In the lookup-indirect form of the switch, is there a reason not to make - the val-type uint? Most HLL switch statements (including Java and C++) - require that anyway. And it would also make the val-type uniform - in the two forms of the switch. - - I did see the switch-on-bool examples and, while cute, we can just use - the branch instructions in that particular case. - - -o I agree with your comment that we don't need 'neg'. - - -o There's a trade-off with the cast instruction: - + it avoids having to define all the upcasts and downcasts that are - valid for the operands of each instruction (you probably have thought - of other benefits also) - - it could make the bytecode significantly larger because there could - be a lot of cast operations - - -o Making the second arg. to 'shl' a ubyte seems good enough to me. - 255 positions seems adequate for several generations of machines - and is more compact than uint. - - -o I still have some major concerns about including malloc and free in the - language (either as builtin functions or instructions). LLVM must be - able to represent code from many different languages. Languages such as - C, C++ Java and Fortran 90 would not be able to use our malloc anyway - because each of them will want to provide a library implementation of it. - - This gets even worse when code from different languages is linked - into a single executable (which is fairly common in large apps). - Having a single malloc would just not suffice, and instead would simply - complicate the picture further because it adds an extra variant in - addition to the one each language provides. - - Instead, providing a default library version of malloc and free - (and perhaps a malloc_gc with garbage collection instead of free) - would make a good implementation available to anyone who wants it. - - I don't recall all your arguments in favor so let's discuss this again, - and soon. - - -o 'alloca' on the other hand sounds like a good idea, and the - implementation seems fairly language-independent so it doesn't have the - problems with malloc listed above. - - -o About indirect call: - Your option #2 sounded good to me. I'm not sure I understand your - concern about an explicit 'icall' instruction? - - -o A pair of important synchronization instr'ns to think about: - load-linked - store-conditional - - -o Other classes of instructions that are valuable for pipeline performance: - conditional-move - predicated instructions - - -o I believe tail calls are relatively easy to identify; do you know why - .NET has a tailcall instruction? - - -o I agree that we need a static data space. Otherwise, emulating global - data gets unnecessarily complex. - - -o About explicit parallelism: - - We once talked about adding a symbolic thread-id field to each - instruction. (It could be optional so single-threaded codes are - not penalized.) This could map well to multi-threaded architectures - while providing easy ILP for single-threaded onces. But it is probably - too radical an idea to include in a base version of LLVM. Instead, it - could a great topic for a separate study. - - What is the semantics of the IA64 stop bit? - - - - -o And finally, another thought about the syntax for arrays :-) - - Although this syntax: - array of - is verbose, it will be used only in the human-readable assembly code so - size should not matter. I think we should consider it because I find it - to be the clearest syntax. It could even make arrays of function - pointers somewhat readable. - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt deleted file mode 100644 index da502636..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt +++ /dev/null @@ -1,245 +0,0 @@ -From: Chris Lattner -To: "Vikram S. Adve" -Subject: Re: LLVM Feedback - -I've included your feedback in the /home/vadve/lattner/llvm/docs directory -so that it will live in CVS eventually with the rest of LLVM. I've -significantly updated the documentation to reflect the changes you -suggested, as specified below: - -> We should consider eliminating the type annotation in cases where it is -> essentially obvious from the instruction type: -> br bool , label , label -> I think your point was that making all types explicit improves clarity -> and readability. I agree to some extent, but it also comes at the -> cost of verbosity. And when the types are obvious from people's -> experience (e.g., in the br instruction), it doesn't seem to help as -> much. - -Very true. We should discuss this more, but my reasoning is more of a -consistency argument. There are VERY few instructions that can have all -of the types eliminated, and doing so when available unnecessarily makes -the language more difficult to handle. Especially when you see 'int -%this' and 'bool %that' all over the place, I think it would be -disorienting to see: - - br %predicate, %iftrue, %iffalse - -for branches. Even just typing that once gives me the creeps. ;) Like I -said, we should probably discuss this further in person... - -> On reflection, I really like your idea of having the two different -> switch types (even though they encode implementation techniques rather -> than semantics). It should simplify building the CFG and my guess is it -> could enable some significant optimizations, though we should think -> about which. - -Great. I added a note to the switch section commenting on how the VM -should just use the instruction type as a hint, and that the -implementation may choose altermate representations (such as predicated -branches). - -> In the lookup-indirect form of the switch, is there a reason not to -> make the val-type uint? - -No. This was something I was debating for a while, and didn't really feel -strongly about either way. It is common to switch on other types in HLL's -(for example signed int's are particularly common), but in this case, all -that will be added is an additional 'cast' instruction. I removed that -from the spec. - -> I agree with your comment that we don't need 'neg' - -Removed. - -> There's a trade-off with the cast instruction: -> + it avoids having to define all the upcasts and downcasts that are -> valid for the operands of each instruction (you probably have -> thought of other benefits also) -> - it could make the bytecode significantly larger because there could -> be a lot of cast operations - - + You NEED casts to represent things like: - void foo(float); - ... - int x; - ... - foo(x); - in a language like C. Even in a Java like language, you need upcasts - and some way to implement dynamic downcasts. - + Not all forms of instructions take every type (for example you can't - shift by a floating point number of bits), thus SOME programs will need - implicit casts. - -To be efficient and to avoid your '-' point above, we just have to be -careful to specify that the instructions shall operate on all common -types, therefore casting should be relatively uncommon. For example all -of the arithmetic operations work on almost all data types. - -> Making the second arg. to 'shl' a ubyte seems good enough to me. -> 255 positions seems adequate for several generations of machines - -Okay, that comment is removed. - -> and is more compact than uint. - -No, it isn't. Remember that the bytecode encoding saves value slots into -the bytecode instructions themselves, not constant values. This is -another case where we may introduce more cast instructions (but we will -also reduce the number of opcode variants that must be supported by a -virtual machine). Because most shifts are by constant values, I don't -think that we'll have to cast many shifts. :) - -> I still have some major concerns about including malloc and free in the -> language (either as builtin functions or instructions). - -Agreed. How about this proposal: - -malloc/free are either built in functions or actual opcodes. They provide -all of the type safety that the document would indicate, blah blah -blah. :) - -Now, because of all of the excellent points that you raised, an -implementation may want to override the default malloc/free behavior of -the program. To do this, they simply implement a "malloc" and -"free" function. The virtual machine will then be defined to use the user -defined malloc/free function (which return/take void*'s, not type'd -pointers like the builtin function would) if one is available, otherwise -fall back on a system malloc/free. - -Does this sound like a good compromise? It would give us all of the -typesafety/elegance in the language while still allowing the user to do -all the cool stuff they want to... - -> 'alloca' on the other hand sounds like a good idea, and the -> implementation seems fairly language-independent so it doesn't have the -> problems with malloc listed above. - -Okay, once we get the above stuff figured out, I'll put it all in the -spec. - -> About indirect call: -> Your option #2 sounded good to me. I'm not sure I understand your -> concern about an explicit 'icall' instruction? - -I worry too much. :) The other alternative has been removed. 'icall' is -now up in the instruction list next to 'call'. - -> I believe tail calls are relatively easy to identify; do you know why -> .NET has a tailcall instruction? - -Although I am just guessing, I believe it probably has to do with the fact -that they want languages like Haskell and lisp to be efficiently runnable -on their VM. Of course this means that the VM MUST implement tail calls -'correctly', or else life will suck. :) I would put this into a future -feature bin, because it could be pretty handy... - -> A pair of important synchronization instr'ns to think about: -> load-linked -> store-conditional - -What is 'load-linked'? I think that (at least for now) I should add these -to the 'possible extensions' section, because they are not immediately -needed... - -> Other classes of instructions that are valuable for pipeline -> performance: -> conditional-move -> predicated instructions - -Conditional move is effectly a special case of a predicated -instruction... and I think that all predicated instructions can possibly -be implemented later in LLVM. It would significantly change things, and -it doesn't seem to be very necessary right now. It would seem to -complicate flow control analysis a LOT in the virtual machine. I would -tend to prefer that a predicated architecture like IA64 convert from a -"basic block" representation to a predicated rep as part of it's dynamic -complication phase. Also, if a basic block contains ONLY a move, then -that can be trivally translated into a conditional move... - -> I agree that we need a static data space. Otherwise, emulating global -> data gets unnecessarily complex. - -Definitely. Also a later item though. :) - -> We once talked about adding a symbolic thread-id field to each -> .. -> Instead, it could a great topic for a separate study. - -Agreed. :) - -> What is the semantics of the IA64 stop bit? - -Basically, the IA64 writes instructions like this: -mov ... -add ... -sub ... -op xxx -op xxx -;; -mov ... -add ... -sub ... -op xxx -op xxx -;; - -Where the ;; delimits a group of instruction with no dependencies between -them, which can all be executed concurrently (to the limits of the -available functional units). The ;; gets translated into a bit set in one -of the opcodes. - -The advantages of this representation is that you don't have to do some -kind of 'thread id scheduling' pass by having to specify ahead of time how -many threads to use, and the representation doesn't have a per instruction -overhead... - -> And finally, another thought about the syntax for arrays :-) -> Although this syntax: -> array of -> is verbose, it will be used only in the human-readable assembly code so -> size should not matter. I think we should consider it because I find it -> to be the clearest syntax. It could even make arrays of function -> pointers somewhat readable. - -My only comment will be to give you an example of why this is a bad -idea. :) - -Here is an example of using the switch statement (with my recommended -syntax): - -switch uint %val, label %otherwise, - [%3 x {uint, label}] [ { uint %57, label %l1 }, - { uint %20, label %l2 }, - { uint %14, label %l3 } ] - -Here it is with the syntax you are proposing: - -switch uint %val, label %otherwise, - array %3 of {uint, label} - array of {uint, label} - { uint %57, label %l1 }, - { uint %20, label %l2 }, - { uint %14, label %l3 } - -Which is ambiguous and very verbose. It would be possible to specify -constants with [] brackets as in my syntax, which would look like this: - -switch uint %val, label %otherwise, - array %3 of {uint, label} [ { uint %57, label %l1 }, - { uint %20, label %l2 }, - { uint %14, label %l3 } ] - -But then the syntax is inconsistent between type definition and constant -definition (why do []'s enclose the constants but not the types??). - -Anyways, I'm sure that there is much debate still to be had over -this... :) - --Chris - -http://www.nondot.org/~sabre/os/ -http://www.nondot.org/MagicStats/ -http://korbit.sourceforge.net/ - - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt deleted file mode 100644 index 2c7534d9..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt +++ /dev/null @@ -1,39 +0,0 @@ -Date: Tue, 13 Feb 2001 13:29:52 -0600 (CST) -From: Chris Lattner -To: Vikram S. Adve -Subject: LLVM Concerns... - - -I've updated the documentation to include load store and allocation -instructions (please take a look and let me know if I'm on the right -track): - -file:/home/vadve/lattner/llvm/docs/LangRef.html#memoryops - -I have a couple of concerns I would like to bring up: - -1. Reference types - Right now, I've spec'd out the language to have a pointer type, which - works fine for lots of stuff... except that Java really has - references: constrained pointers that cannot be manipulated: added and - subtracted, moved, etc... Do we want to have a type like this? It - could be very nice for analysis (pointer always points to the start of - an object, etc...) and more closely matches Java semantics. The - pointer type would be kept for C++ like semantics. Through analysis, - C++ pointers could be promoted to references in the LLVM - representation. - -2. Our "implicit" memory references in assembly language: - After thinking about it, this model has two problems: - A. If you do pointer analysis and realize that two stores are - independent and can share the same memory source object, there is - no way to represent this in either the bytecode or assembly. - B. When parsing assembly/bytecode, we effectively have to do a full - SSA generation/PHI node insertion pass to build the dependencies - when we don't want the "pinned" representation. This is not - cool. - I'm tempted to make memory references explicit in both the assembly and - bytecode to get around this... what do you think? - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt b/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt deleted file mode 100644 index 50534337..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt +++ /dev/null @@ -1,47 +0,0 @@ -Date: Tue, 13 Feb 2001 18:25:42 -0600 -From: Vikram S. Adve -To: Chris Lattner -Subject: RE: LLVM Concerns... - -> 1. Reference types -> Right now, I've spec'd out the language to have a pointer type, which -> works fine for lots of stuff... except that Java really has -> references: constrained pointers that cannot be manipulated: added and -> subtracted, moved, etc... Do we want to have a type like this? It -> could be very nice for analysis (pointer always points to the start of -> an object, etc...) and more closely matches Java semantics. The -> pointer type would be kept for C++ like semantics. Through analysis, -> C++ pointers could be promoted to references in the LLVM -> representation. - - -You're right, having references would be useful. Even for C++ the *static* -compiler could generate references instead of pointers with fairly -straightforward analysis. Let's include a reference type for now. But I'm -also really concerned that LLVM is becoming big and complex and (perhaps) -too high-level. After we get some initial performance results, we may have -a clearer idea of what our goals should be and we should revisit this -question then. - -> 2. Our "implicit" memory references in assembly language: -> After thinking about it, this model has two problems: -> A. If you do pointer analysis and realize that two stores are -> independent and can share the same memory source object, - -not sure what you meant by "share the same memory source object" - -> there is -> no way to represent this in either the bytecode or assembly. -> B. When parsing assembly/bytecode, we effectively have to do a full -> SSA generation/PHI node insertion pass to build the dependencies -> when we don't want the "pinned" representation. This is not -> cool. - -I understand the concern. But again, let's focus on the performance first -and then look at the language design issues. E.g., it would be good to know -how big the bytecode files are before expanding them further. I am pretty -keen to explore the implications of LLVM for mobile devices. Both bytecode -size and power consumption are important to consider there. - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt b/cpp/llvm/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt deleted file mode 100644 index 5f7843ab..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt +++ /dev/null @@ -1,49 +0,0 @@ -By Chris: - -LLVM has been designed with two primary goals in mind. First we strive to -enable the best possible division of labor between static and dynamic -compilers, and second, we need a flexible and powerful interface -between these two complementary stages of compilation. We feel that -providing a solution to these two goals will yield an excellent solution -to the performance problem faced by modern architectures and programming -languages. - -A key insight into current compiler and runtime systems is that a -compiler may fall in anywhere in a "continuum of compilation" to do its -job. On one side, scripting languages statically compile nothing and -dynamically compile (or equivalently, interpret) everything. On the far -other side, traditional static compilers process everything statically and -nothing dynamically. These approaches have typically been seen as a -tradeoff between performance and portability. On a deeper level, however, -there are two reasons that optimal system performance may be obtained by a -system somewhere in between these two extremes: Dynamic application -behavior and social constraints. - -From a technical perspective, pure static compilation cannot ever give -optimal performance in all cases, because applications have varying dynamic -behavior that the static compiler cannot take into consideration. Even -compilers that support profile guided optimization generate poor code in -the real world, because using such optimization tunes that application -to one particular usage pattern, whereas real programs (as opposed to -benchmarks) often have several different usage patterns. - -On a social level, static compilation is a very shortsighted solution to -the performance problem. Instruction set architectures (ISAs) continuously -evolve, and each implementation of an ISA (a processor) must choose a set -of tradeoffs that make sense in the market context that it is designed for. -With every new processor introduced, the vendor faces two fundamental -problems: First, there is a lag time between when a processor is introduced -to when compilers generate quality code for the architecture. Secondly, -even when compilers catch up to the new architecture there is often a large -body of legacy code that was compiled for previous generations and will -not or can not be upgraded. Thus a large percentage of code running on a -processor may be compiled quite sub-optimally for the current -characteristics of the dynamic execution environment. - -For these reasons, LLVM has been designed from the beginning as a long-term -solution to these problems. Its design allows the large body of platform -independent, static, program optimizations currently in compilers to be -reused unchanged in their current form. It also provides important static -type information to enable powerful dynamic and link time optimizations -to be performed quickly and efficiently. This combination enables an -increase in effective system performance for real world environments. diff --git a/cpp/llvm/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt b/cpp/llvm/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt deleted file mode 100644 index b546301d..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt +++ /dev/null @@ -1,202 +0,0 @@ -Meeting notes: Implementation idea: Exception Handling in C++/Java - -The 5/18/01 meeting discussed ideas for implementing exceptions in LLVM. -We decided that the best solution requires a set of library calls provided by -the VM, as well as an extension to the LLVM function invocation syntax. - -The LLVM function invocation instruction previously looks like this (ignoring -types): - - call func(arg1, arg2, arg3) - -The extension discussed today adds an optional "with" clause that -associates a label with the call site. The new syntax looks like this: - - call func(arg1, arg2, arg3) with funcCleanup - -This funcHandler always stays tightly associated with the call site (being -encoded directly into the call opcode itself), and should be used whenever -there is cleanup work that needs to be done for the current function if -an exception is thrown by func (or if we are in a try block). - -To support this, the VM/Runtime provide the following simple library -functions (all syntax in this document is very abstract): - -typedef struct { something } %frame; - The VM must export a "frame type", that is an opaque structure used to - implement different types of stack walking that may be used by various - language runtime libraries. We imagine that it would be typical to - represent a frame with a PC and frame pointer pair, although that is not - required. - -%frame getStackCurrentFrame(); - Get a frame object for the current function. Note that if the current - function was inlined into its caller, the "current" frame will belong to - the "caller". - -bool isFirstFrame(%frame f); - Returns true if the specified frame is the top level (first activated) frame - for this thread. For the main thread, this corresponds to the main() - function, for a spawned thread, it corresponds to the thread function. - -%frame getNextFrame(%frame f); - Return the previous frame on the stack. This function is undefined if f - satisfies the predicate isFirstFrame(f). - -Label *getFrameLabel(%frame f); - If a label was associated with f (as discussed below), this function returns - it. Otherwise, it returns a null pointer. - -doNonLocalBranch(Label *L); - At this point, it is not clear whether this should be a function or - intrinsic. It should probably be an intrinsic in LLVM, but we'll deal with - this issue later. - - -Here is a motivating example that illustrates how these facilities could be -used to implement the C++ exception model: - -void TestFunction(...) { - A a; B b; - foo(); // Any function call may throw - bar(); - C c; - - try { - D d; - baz(); - } catch (int) { - ...int Stuff... - // execution continues after the try block: the exception is consumed - } catch (double) { - ...double stuff... - throw; // Exception is propogated - } -} - -This function would compile to approximately the following code (heavy -pseudo code follows): - -Func: - %a = alloca A - A::A(%a) // These ctors & dtors could throw, but we ignore this - %b = alloca B // minor detail for this example - B::B(%b) - - call foo() with fooCleanup // An exception in foo is propogated to fooCleanup - call bar() with barCleanup // An exception in bar is propogated to barCleanup - - %c = alloca C - C::C(c) - %d = alloca D - D::D(d) - call baz() with bazCleanup // An exception in baz is propogated to bazCleanup - d->~D(); -EndTry: // This label corresponds to the end of the try block - c->~C() // These could also throw, these are also ignored - b->~B() - a->~A() - return - -Note that this is a very straight forward and literal translation: exactly -what we want for zero cost (when unused) exception handling. Especially on -platforms with many registers (ie, the IA64) setjmp/longjmp style exception -handling is *very* impractical. Also, the "with" clauses describe the -control flow paths explicitly so that analysis is not adversly effected. - -The foo/barCleanup labels are implemented as: - -TryCleanup: // Executed if an exception escapes the try block - c->~C() -barCleanup: // Executed if an exception escapes from bar() - // fall through -fooCleanup: // Executed if an exception escapes from foo() - b->~B() - a->~A() - Exception *E = getThreadLocalException() - call throw(E) // Implemented by the C++ runtime, described below - -Which does the work one would expect. getThreadLocalException is a function -implemented by the C++ support library. It returns the current exception -object for the current thread. Note that we do not attempt to recycle the -shutdown code from before, because performance of the mainline code is -critically important. Also, obviously fooCleanup and barCleanup may be -merged and one of them eliminated. This just shows how the code generator -would most likely emit code. - -The bazCleanup label is more interesting. Because the exception may be caught -by the try block, we must dispatch to its handler... but it does not exist -on the call stack (it does not have a VM Call->Label mapping installed), so -we must dispatch statically with a goto. The bazHandler thus appears as: - -bazHandler: - d->~D(); // destruct D as it goes out of scope when entering catch clauses - goto TryHandler - -In general, TryHandler is not the same as bazHandler, because multiple -function calls could be made from the try block. In this case, trivial -optimization could merge the two basic blocks. TryHandler is the code -that actually determines the type of exception, based on the Exception object -itself. For this discussion, assume that the exception object contains *at -least*: - -1. A pointer to the RTTI info for the contained object -2. A pointer to the dtor for the contained object -3. The contained object itself - -Note that it is necessary to maintain #1 & #2 in the exception object itself -because objects without virtual function tables may be thrown (as in this -example). Assuming this, TryHandler would look something like this: - -TryHandler: - Exception *E = getThreadLocalException(); - switch (E->RTTIType) { - case IntRTTIInfo: - ...int Stuff... // The action to perform from the catch block - break; - case DoubleRTTIInfo: - ...double Stuff... // The action to perform from the catch block - goto TryCleanup // This catch block rethrows the exception - break; // Redundant, eliminated by the optimizer - default: - goto TryCleanup // Exception not caught, rethrow - } - - // Exception was consumed - if (E->dtor) - E->dtor(E->object) // Invoke the dtor on the object if it exists - goto EndTry // Continue mainline code... - -And that is all there is to it. - -The throw(E) function would then be implemented like this (which may be -inlined into the caller through standard optimization): - -function throw(Exception *E) { - // Get the start of the stack trace... - %frame %f = call getStackCurrentFrame() - - // Get the label information that corresponds to it - label * %L = call getFrameLabel(%f) - while (%L == 0 && !isFirstFrame(%f)) { - // Loop until a cleanup handler is found - %f = call getNextFrame(%f) - %L = call getFrameLabel(%f) - } - - if (%L != 0) { - call setThreadLocalException(E) // Allow handlers access to this... - call doNonLocalBranch(%L) - } - // No handler found! - call BlowUp() // Ends up calling the terminate() method in use -} - -That's a brief rundown of how C++ exception handling could be implemented in -llvm. Java would be very similar, except it only uses destructors to unlock -synchronized blocks, not to destroy data. Also, it uses two stack walks: a -nondestructive walk that builds a stack trace, then a destructive walk that -unwinds the stack as shown here. - -It would be trivial to get exception interoperability between C++ and Java. - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt b/cpp/llvm/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt deleted file mode 100644 index 3375365f..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt +++ /dev/null @@ -1,45 +0,0 @@ -Date: Sat, 19 May 2001 19:09:13 -0500 (CDT) -From: Chris Lattner -To: Vikram S. Adve -Subject: RE: Meeting writeup - -> I read it through and it looks great! - -Thanks! - -> The finally clause in Java may need more thought. The code for this clause -> is like a subroutine because it needs to be entered from many points (end of -> try block and beginning of each catch block), and then needs to *return to -> the place from where the code was entered*. That's why JVM has the -> jsr/jsr_w instruction. - -Hrm... I guess that is an implementation decision. It can either be -modelled as a subroutine (as java bytecodes do), which is really -gross... or it can be modelled as code duplication (emitted once inline, -then once in the exception path). Because this could, at worst, -slightly less than double the amount of code in a function (it is -bounded) I don't think this is a big deal. One of the really nice things -about the LLVM representation is that it still allows for runtime code -generation for exception paths (exceptions paths are not compiled until -needed). Obviously a static compiler couldn't do this though. :) - -In this case, only one copy of the code would be compiled... until the -other one is needed on demand. Also this strategy fits with the "zero -cost" exception model... the standard case is not burdened with extra -branches or "call"s. - -> I suppose you could save the return address in a particular register -> (specific to this finally block), jump to the finally block, and then at the -> end of the finally block, jump back indirectly through this register. It -> will complicate building the CFG but I suppose that can be handled. It is -> also unsafe in terms of checking where control returns (which is I suppose -> why the JVM doesn't use this). - -I think that a code duplication method would be cleaner, and would avoid -the caveats that you mention. Also, it does not slow down the normal case -with an indirect branch... - -Like everything, we can probably defer a final decision until later. :) - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt b/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt deleted file mode 100644 index 97af16a2..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt +++ /dev/null @@ -1,63 +0,0 @@ -Date: Fri, 1 Jun 2001 16:38:17 -0500 (CDT) -From: Chris Lattner -To: Vikram S. Adve -Subject: Interesting: GCC passes - - -Take a look at this document (which describes the order of optimizations -that GCC performs): - -http://gcc.gnu.org/onlinedocs/gcc_17.html - -The rundown is that after RTL generation, the following happens: - -1 . [t] jump optimization (jumps to jumps, etc) -2 . [t] Delete unreachable code -3 . Compute live ranges for CSE -4 . [t] Jump threading (jumps to jumps with identical or inverse conditions) -5 . [t] CSE -6 . *** Conversion to SSA -7 . [t] SSA Based DCE -8 . *** Conversion to LLVM -9 . UnSSA -10. GCSE -11. LICM -12. Strength Reduction -13. Loop unrolling -14. [t] CSE -15. [t] DCE -16. Instruction combination, register movement, scheduling... etc. - -I've marked optimizations with a [t] to indicate things that I believe to -be relatively trivial to implement in LLVM itself. The time consuming -things to reimplement would be SSA based PRE, Strength reduction & loop -unrolling... these would be the major things we would miss out on if we -did LLVM creation from tree code [inlining and other high level -optimizations are done on the tree representation]. - -Given the lack of "strong" optimizations that would take a long time to -reimplement, I am leaning a bit more towards creating LLVM from the tree -code. Especially given that SGI has GPL'd their compiler, including many -SSA based optimizations that could be adapted (besides the fact that their -code looks MUCH nicer than GCC :) - -Even if we choose to do LLVM code emission from RTL, we will almost -certainly want to move LLVM emission from step 8 down until at least CSE -has been rerun... which causes me to wonder if the SSA generation code -will still work (due to global variable dependencies and stuff). I assume -that it can be made to work, but might be a little more involved than we -would like. - -I'm continuing to look at the Tree -> RTL code. It is pretty gross -because they do some of the translation a statement at a time, and some -of it a function at a time... I'm not quite clear why and how the -distinction is drawn, but it does not appear that there is a wonderful -place to attach extra info. - -Anyways, I'm proceeding with the RTL -> LLVM conversion phase for now. We -can talk about this more on Monday. - -Wouldn't it be nice if there were a obvious decision to be made? :) - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt b/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt deleted file mode 100644 index e61042fd..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt +++ /dev/null @@ -1,71 +0,0 @@ -Date: Fri, 1 Jun 2001 17:08:44 -0500 (CDT) -From: Chris Lattner -To: Vikram S. Adve -Subject: RE: Interesting: GCC passes - -> That is very interesting. I agree that some of these could be done on LLVM -> at link-time, but it is the extra time required that concerns me. Link-time -> optimization is severely time-constrained. - -If we were to reimplement any of these optimizations, I assume that we -could do them a translation unit at a time, just as GCC does now. This -would lead to a pipeline like this: - -Static optimizations, xlation unit at a time: -.c --GCC--> .llvm --llvmopt--> .llvm - -Link time optimizations: -.llvm --llvm-ld--> .llvm --llvm-link-opt--> .llvm - -Of course, many optimizations could be shared between llvmopt and -llvm-link-opt, but the wouldn't need to be shared... Thus compile time -could be faster, because we are using a "smarter" IR (SSA based). - -> BTW, about SGI, "borrowing" SSA-based optimizations from one compiler and -> putting it into another is not necessarily easier than re-doing it. -> Optimization code is usually heavily tied in to the specific IR they use. - -Understood. The only reason that I brought this up is because SGI's IR is -more similar to LLVM than it is different in many respects (SSA based, -relatively low level, etc), and could be easily adapted. Also their -optimizations are written in C++ and are actually somewhat -structured... of course it would be no walk in the park, but it would be -much less time consuming to adapt, say, SSA-PRE than to rewrite it. - -> But your larger point is valid that adding SSA based optimizations is -> feasible and should be fun. (Again, link time cost is the issue.) - -Assuming linktime cost wasn't an issue, the question is: -Does using GCC's backend buy us anything? - -> It also occurs to me that GCC is probably doing quite a bit of back-end -> optimization (step 16 in your list). Do you have a breakdown of that? - -Not really. The irritating part of GCC is that it mixes it all up and -doesn't have a clean separation of concerns. A lot of the "back end -optimization" happens right along with other data optimizations (ie, CSE -of machine specific things). - -As far as REAL back end optimizations go, it looks something like this: - -1. Instruction combination: try to make CISCy instructions, if available -2. Register movement: try to get registers in the right places for the -architecture to avoid register to register moves. For example, try to get -the first argument of a function to naturally land in %o0 for sparc. -3. Instruction scheduling: 'nuff said :) -4. Register class preferencing: ?? -5. Local register allocation -6. global register allocation -7. Spilling -8. Local regalloc -9. Jump optimization -10. Delay slot scheduling -11. Branch shorting for CISC machines -12. Instruction selection & peephole optimization -13. Debug info output - -But none of this would be usable for LLVM anyways, unless we were using -GCC as a static compiler. - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt b/cpp/llvm/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt deleted file mode 100644 index 1bc2eae7..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt +++ /dev/null @@ -1,30 +0,0 @@ -Date: Wed, 20 Jun 2001 12:32:22 -0500 -From: Vikram Adve -To: Chris Lattner -Subject: .NET vs. our VM - -One significant difference between .NET CLR and our VM is that the CLR -includes full information about classes and inheritance. In fact, I just -sat through the paper on adding templates to .NET CLR, and the speaker -indicated that the goal seems to be to do simple static compilation (very -little lowering or optimization). Also, the templates implementation in CLR -"relies on dynamic class loading and JIT compilation". - -This is an important difference because I think there are some significant -advantages to have a much lower level VM layer, and do significant static -analysis and optimization. - -I also talked to the lead guy for KAI's C++ compiler (Arch Robison) and he -said that SGI and other commercial compilers have included options to export -their *IR* next to the object code (i.e., .il files) and use them for -link-time code generation. In fact, he said that the .o file was nearly -empty and was entirely generated from the .il at link-time. But he agreed -that this limited the link-time interprocedural optimization to modules -compiled by the same compiler, whereas our approach allows us to link and -optimize modules from multiple different compilers. (Also, of course, they -don't do anything for runtime optimization). - -All issues to bring up in Related Work. - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt b/cpp/llvm/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt deleted file mode 100644 index 3e10416f..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt +++ /dev/null @@ -1,31 +0,0 @@ -Date: Fri, 6 Jul 2001 16:56:56 -0500 -From: Vikram S. Adve -To: Chris Lattner -Subject: lowering the IR - -BTW, I do think that we should consider lowering the IR as you said. I -didn't get time to raise it today, but it comes up with the SPARC -move-conditional instruction. I don't think we want to put that in the core -VM -- it is a little too specialized. But without a corresponding -conditional move instruction in the VM, it is pretty difficult to maintain a -close mapping between VM and machine code. Other architectures may have -other such instructions. - -What I was going to suggest was that for a particular processor, we define -additional VM instructions that match some of the unusual opcodes on the -processor but have VM semantics otherwise, i.e., all operands are in SSA -form and typed. This means that we can re-generate core VM code from the -more specialized code any time we want (so that portability is not lost). - -Typically, a static compiler like gcc would generate just the core VM, which -is relatively portable. Anyone (an offline tool, the linker, etc., or even -the static compiler itself if it chooses) can transform that into more -specialized target-specific VM code for a particular architecture. If the -linker does it, it can do it after all machine-independent optimizations. -This would be the most convenient, but not necessary. - -The main benefit of lowering will be that we will be able to retain a close -mapping between VM and machine code. - ---Vikram - diff --git a/cpp/llvm/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt b/cpp/llvm/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt deleted file mode 100644 index 93790810..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt +++ /dev/null @@ -1,56 +0,0 @@ -Date: Tue, 18 Sep 2001 00:38:37 -0500 (CDT) -From: Chris Lattner -To: Vikram S. Adve -Subject: Idea for a simple, useful link time optimization - - -In C++ programs, exceptions suck, and here's why: - -1. In virtually all function calls, you must assume that the function - throws an exception, unless it is defined as 'nothrow'. This means - that every function call has to have code to invoke dtors on objects - locally if one is thrown by the function. Most functions don't throw - exceptions, so this code is dead [with all the bad effects of dead - code, including icache pollution]. -2. Declaring a function nothrow causes catch blocks to be added to every - call that isnot provably nothrow. This makes them very slow. -3. Extra extraneous exception edges reduce the opportunity for code - motion. -4. EH is typically implemented with large lookup tables. Ours is going to - be much smaller (than the "standard" way of doing it) to start with, - but eliminating it entirely would be nice. :) -5. It is physically impossible to correctly put (accurate, correct) - exception specifications on generic, templated code. But it is trivial - to analyze instantiations of said code. -6. Most large C++ programs throw few exceptions. Most well designed - programs only throw exceptions in specific planned portions of the - code. - -Given our _planned_ model of handling exceptions, all of this would be -pretty trivial to eliminate through some pretty simplistic interprocedural -analysis. The DCE factor alone could probably be pretty significant. The -extra code motion opportunities could also be exploited though... - -Additionally, this optimization can be implemented in a straight forward -conservative manner, allowing libraries to be optimized or individual -files even (if there are leaf functions visible in the translation unit -that are called). - -I think it's a reasonable optimization that hasn't really been addressed -(because assembly is way too low level for this), and could have decent -payoffs... without being a overly complex optimization. - -After I wrote all of that, I found this page that is talking about -basically the same thing I just wrote, except that it is translation unit -at a time, tree based approach: -http://www.ocston.org/~jls/ehopt.html - -but is very useful from "expected gain" and references perspective. Note -that their compiler is apparently unable to inline functions that use -exceptions, so there numbers are pretty worthless... also our results -would (hopefully) be better because it's interprocedural... - -What do you think? - --Chris - diff --git a/cpp/llvm/docs/HistoricalNotes/2002-05-12-InstListChange.txt b/cpp/llvm/docs/HistoricalNotes/2002-05-12-InstListChange.txt deleted file mode 100644 index 638682b4..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2002-05-12-InstListChange.txt +++ /dev/null @@ -1,55 +0,0 @@ -Date: Sun, 12 May 2002 17:12:53 -0500 (CDT) -From: Chris Lattner -To: "Vikram S. Adve" -Subject: LLVM change - -There is a fairly fundemental change that I would like to make to the LLVM -infrastructure, but I'd like to know if you see any drawbacks that I -don't... - -Basically right now at the basic block level, each basic block contains an -instruction list (returned by getInstList()) that is a ValueHolder of -instructions. To iterate over instructions, we must actually iterate over -the instlist, and access the instructions through the instlist. - -To add or remove an instruction from a basic block, we need to get an -iterator to an instruction, which, given just an Instruction*, requires a -linear search of the basic block the instruction is contained in... just -to insert an instruction before another instruction, or to delete an -instruction! This complicates algorithms that should be very simple (like -simple constant propagation), because they aren't actually sparse anymore, -they have to traverse basic blocks to remove constant propogated -instructions. - -Additionally, adding or removing instructions to a basic block -_invalidates all iterators_ pointing into that block, which is really -irritating. - -To fix these problems (and others), I would like to make the ordering of -the instructions be represented with a doubly linked list in the -instructions themselves, instead of an external data structure. This is -how many other representations do it, and frankly I can't remember why I -originally implemented it the way I did. - -Long term, all of the code that depends on the nasty features in the -instruction list (which can be found by grep'ing for getInstList()) will -be changed to do nice local transformations. In the short term, I'll -change the representation, but preserve the interface (including -getInstList()) so that all of the code doesn't have to change. - -Iteration over the instructions in a basic block remains the simple: -for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) ... - -But we will also support: -for (Instruction *I = BB->front(); I; I = I->getNext()) ... - -After converting instructions over, I'll convert basic blocks and -functions to have a similar interface. - -The only negative aspect of this change that I see is that it increases -the amount of memory consumed by one pointer per instruction. Given the -benefits, I think this is a very reasonable tradeoff. - -What do you think? - --Chris diff --git a/cpp/llvm/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt b/cpp/llvm/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt deleted file mode 100644 index 2ca46117..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt +++ /dev/null @@ -1,72 +0,0 @@ -Changes: -* Change the casting code to be const correct. Now, doing this is invalid: - const Value *V = ...; - Instruction *I = dyn_cast(V); - instead, the second line should be: - const Instruction *I = dyn_cast(V); - -* Change the casting code to allow casting a reference value thus: - const Value &V = ...; - Instruction &I = cast(V); - - dyn_cast does not work with references, because it must return a null pointer - on failure. - -* Fundamentally change how instructions and other values are represented. - Before, every llvm container was an instance of the ValueHolder template, - instantiated for each container type. This ValueHolder was effectively a - wrapper around a vector of pointers to the sub-objects. - - Now, instead of having a vector to pointers of objects, the objects are - maintained in a doubly linked list of values (ie each Instruction now has - Next & Previous fields). The containers are now instances of ilist (intrusive - linked list class), which use the next and previous fields to chain them - together. The advantage of this implementation is that iterators can be - formed directly from pointers to the LLVM value, and invalidation is much - easier to handle. - -* As part of the above change, dereferencing an iterator (for example: - BasicBlock::iterator) now produces a reference to the underlying type (same - example: Instruction&) instead of a pointer to the underlying object. This - makes it much easier to write nested loops that iterator over things, changing - this: - - for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI) - for (BasicBlock::iterator II = (*BI)->begin(); II != (*BI)->end(); ++II) - (*II)->dump(); - - into: - - for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI) - for (BasicBlock::iterator II = BI->begin(); II != BI->end(); ++II) - II->dump(); - - which is much more natural and what users expect. - -* Simplification of #include's: Before, it was necessary for a .cpp file to - include every .h file that it used. Now things are batched a little bit more - to make it easier to use. Specifically, the include graph now includes these - edges: - Module.h -> Function.h, GlobalVariable.h - Function.h -> BasicBlock.h, Argument.h - BasicBlock.h -> Instruction.h - - Which means that #including Function.h is usually sufficient for getting the - lower level #includes. - -* Printing out a Value* has now changed: Printing a Value* will soon print out - the address of the value instead of the contents of the Value. To print out - the contents, you must convert it to a reference with (for example) - 'cout << *I' instead of 'cout << I;'. This conversion is not yet complete, - but will be eventually. In the mean time, both forms print out the contents. - -* References are used much more throughout the code base. In general, if a - pointer is known to never be null, it is passed in as a reference instead of a - pointer. For example, the instruction visitor class uses references instead - of pointers, and that Pass subclasses now all receive references to Values - instead of pointers, because they may never be null. - -* The Function class now has helper functions for accessing the Arguments list. - Instead of having to go through getArgumentList for simple things like - iterator over the arguments, now the a*() methods can be used to access them. - diff --git a/cpp/llvm/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt b/cpp/llvm/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt deleted file mode 100644 index fbe811d6..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt +++ /dev/null @@ -1,28 +0,0 @@ -Date: Mon, 20 Jan 2003 00:00:28 -0600 -From: Brian R. Gaeke -Subject: windows vs. llvm - -If you're interested, here are some of the major problems compiling LLVM -under Cygwin and/or Mingw. - -1. Cygwin doesn't have or , so all the INT*_MAX - symbols and standard int*_t types are off in limbo somewhere. Mingw has - , but Cygwin doesn't like it. - -2. Mingw doesn't have (because Windows doesn't have it.) - -3. SA_SIGINFO and friends are not around; only signal() seems to work. - -4. Relink, aka ld -r, doesn't work (probably an ld bug); you need - DONT_BUILD_RELINKED. This breaks all the tools makefiles; you just need to - change them to have .a's. - -5. There isn't a . - -6. There isn't a mallinfo() (or, at least, it's documented, but it doesn't seem - to link). - -7. The version of Bison that cygwin (and newer Linux versions) comes with - does not like = signs in rules. Burg's gram.yc source file uses them. I think - you can just take them out. - diff --git a/cpp/llvm/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt b/cpp/llvm/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt deleted file mode 100644 index a7457846..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt +++ /dev/null @@ -1,137 +0,0 @@ -Wed Jun 25 15:13:51 CDT 2003 - -First-level instrumentation ---------------------------- - -We use opt to do Bytecode-to-bytecode instrumentation. Look at -back-edges and insert llvm_first_trigger() function call which takes -no arguments and no return value. This instrumentation is designed to -be easy to remove, for instance by writing a NOP over the function -call instruction. - -Keep count of every call to llvm_first_trigger(), and maintain -counters in a map indexed by return address. If the trigger count -exceeds a threshold, we identify a hot loop and perform second-level -instrumentation on the hot loop region (the instructions between the -target of the back-edge and the branch that causes the back-edge). We -do not move code across basic-block boundaries. - - -Second-level instrumentation ---------------------------- - -We remove the first-level instrumentation by overwriting the CALL to -llvm_first_trigger() with a NOP. - -The reoptimizer maintains a map between machine-code basic blocks and -LLVM BasicBlock*s. We only keep track of paths that start at the -first machine-code basic block of the hot loop region. - -How do we keep track of which edges to instrument, and which edges are -exits from the hot region? 3 step process. - -1) Do a DFS from the first machine-code basic block of the hot loop -region and mark reachable edges. - -2) Do a DFS from the last machine-code basic block of the hot loop -region IGNORING back edges, and mark the edges which are reachable in -1) and also in 2) (i.e., must be reachable from both the start BB and -the end BB of the hot region). - -3) Mark BBs which end in edges that exit the hot region; we need to -instrument these differently. - -Assume that there is 1 free register. On SPARC we use %g1, which LLC -has agreed not to use. Shift a 1 into it at the beginning. At every -edge which corresponds to a conditional branch, we shift 0 for not -taken and 1 for taken into a register. This uniquely numbers the paths -through the hot region. Silently fail if we need more than 64 bits. - -At the end BB we call countPath and increment the counter based on %g1 -and the return address of the countPath call. We keep track of the -number of iterations and the number of paths. We only run this -version 30 or 40 times. - -Find the BBs that total 90% or more of execution, and aggregate them -together to form our trace. But we do not allow more than 5 paths; if -we have more than 5 we take the ones that are executed the most. We -verify our assumption that we picked a hot back-edge in first-level -instrumentation, by making sure that the number of times we took an -exit edge from the hot trace is less than 10% of the number of -iterations. - -LLC has been taught to recognize llvm_first_trigger() calls and NOT -generate saves and restores of caller-saved registers around these -calls. - - -Phase behavior --------------- - -We turn off llvm_first_trigger() calls with NOPs, but this would hide -phase behavior from us (when some funcs/traces stop being hot and -others become hot.) - -We have a SIGALRM timer that counts time for us. Every time we get a -SIGALRM we look at our priority queue of locations where we have -removed llvm_first_trigger() calls. Each location is inserted along -with a time when we will next turn instrumentation back on for that -call site. If the time has arrived for a particular call site, we pop -that off the prio. queue and turn instrumentation back on for that -call site. - - -Generating traces ------------------ - -When we finally generate an optimized trace we first copy the code -into the trace cache. This leaves us with 3 copies of the code: the -original code, the instrumented code, and the optimized trace. The -optimized trace does not have instrumentation. The original code and -the instrumented code are modified to have a branch to the trace -cache, where the optimized traces are kept. - -We copy the code from the original to the instrumentation version -by tracing the LLVM-to-Machine code basic block map and then copying -each machine code basic block we think is in the hot region into the -trace cache. Then we instrument that code. The process is similar for -generating the final optimized trace; we copy the same basic blocks -because we might need to put in fixup code for exit BBs. - -LLVM basic blocks are not typically used in the Reoptimizer except -for the mapping information. - -We are restricted to using single instructions to branch between the -original code, trace, and instrumented code. So we have to keep the -code copies in memory near the original code (they can't be far enough -away that a single pc-relative branch would not work.) Malloc() or -data region space is too far away. this impacts the design of the -trace cache. - -We use a dummy function that is full of a bunch of for loops which we -overwrite with trace-cache code. The trace manager keeps track of -whether or not we have enough space in the trace cache, etc. - -The trace insertion routine takes an original start address, a vector -of machine instructions representing the trace, index of branches and -their corresponding absolute targets, and index of calls and their -corresponding absolute targets. - -The trace insertion routine is responsible for inserting branches from -the beginning of the original code to the beginning of the optimized -trace. This is because at some point the trace cache may run out of -space and it may have to evict a trace, at which point the branch to -the trace would also have to be removed. It uses a round-robin -replacement policy; we have found that this is almost as good as LRU -and better than random (especially because of problems fitting the new -trace in.) - -We cannot deal with discontiguous trace cache areas. The trace cache -is supposed to be cache-line-aligned, but it is not page-aligned. - -We generate instrumentation traces and optimized traces into separate -trace caches. We keep the instrumented code around because you don't -want to delete a trace when you still might have to return to it -(i.e., return from a llvm_first_trigger() or countPath() call.) - - diff --git a/cpp/llvm/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt b/cpp/llvm/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt deleted file mode 100644 index ec4b93fe..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt +++ /dev/null @@ -1,110 +0,0 @@ -Thu Jun 26 14:43:04 CDT 2003 - -Information about BinInterface ------------------------------- - -Take in a set of instructions with some particular register -allocation. It allows you to add, modify, or delete some instructions, -in SSA form (kind of like LLVM's MachineInstrs.) Then re-allocate -registers. It assumes that the transformations you are doing are safe. -It does not update the mapping information or the LLVM representation -for the modified trace (so it would not, for instance, support -multiple optimization passes; passes have to be aware of and update -manually the mapping information.) - -The way you use it is you take the original code and provide it to -BinInterface; then you do optimizations to it, then you put it in the -trace cache. - -The BinInterface tries to find live-outs for traces so that it can do -register allocation on just the trace, and stitch the trace back into -the original code. It has to preserve the live-ins and live-outs when -it does its register allocation. (On exits from the trace we have -epilogues that copy live-outs back into the right registers, but -live-ins have to be in the right registers.) - - -Limitations of BinInterface ---------------------------- - -It does copy insertions for PHIs, which it infers from the machine -code. The mapping info inserted by LLC is not sufficient to determine -the PHIs. - -It does not handle integer or floating-point condition codes and it -does not handle floating-point register allocation. - -It is not aggressively able to use lots of registers. - -There is a problem with alloca: we cannot find our spill space for -spilling registers, normally allocated on the stack, if the trace -follows an alloca(). What might be an acceptable solution would be to -disable trace generation on functions that have variable-sized -alloca()s. Variable-sized allocas in the trace would also probably -screw things up. - -Because of the FP and alloca limitations, the BinInterface is -completely disabled right now. - - -Demo ----- - -This is a demo of the Ball & Larus version that does NOT use 2-level -profiling. - -1. Compile program with llvm-gcc. -2. Run opt -lowerswitch -paths -emitfuncs on the bytecode. - -lowerswitch change switch statements to branches - -paths Ball & Larus path-profiling algorithm - -emitfuncs emit the table of functions -3. Run llc to generate SPARC assembly code for the result of step 2. -4. Use g++ to link the (instrumented) assembly code. - -We use a script to do all this: ------------------------------------------------------------------------------- -#!/bin/sh -llvm-gcc $1.c -o $1 -opt -lowerswitch -paths -emitfuncs $1.bc > $1.run.bc -llc -f $1.run.bc -LIBS=$HOME/llvm_sparc/lib/Debug -GXX=/usr/dcs/software/evaluation/bin/g++ -$GXX -g -L $LIBS $1.run.s -o $1.run.llc \ -$LIBS/tracecache.o \ -$LIBS/mapinfo.o \ -$LIBS/trigger.o \ -$LIBS/profpaths.o \ -$LIBS/bininterface.o \ -$LIBS/support.o \ -$LIBS/vmcore.o \ -$LIBS/transformutils.o \ -$LIBS/bcreader.o \ --lscalaropts -lscalaropts -lanalysis \ --lmalloc -lcpc -lm -ldl ------------------------------------------------------------------------------- - -5. Run the resulting binary. You will see output from BinInterface -(described below) intermixed with the output from the program. - - -Output from BinInterface ------------------------- - -BinInterface's debugging code prints out the following stuff in order: - -1. Initial code provided to BinInterface with original register -allocation. - -2. Section 0 is the trace prolog, consisting mainly of live-ins and -register saves which will be restored in epilogs. - -3. Section 1 is the trace itself, in SSA form used by BinInterface, -along with the PHIs that are inserted. -PHIs are followed by the copies that implement them. -Each branch (i.e., out of the trace) is annotated with the -section number that represents the epilog it branches to. - -4. All the other sections starting with Section 2 are trace epilogs. -Every branch from the trace has to go to some epilog. - -5. After the last section is the register allocation output. diff --git a/cpp/llvm/docs/HistoricalNotes/2007-OriginalClangReadme.txt b/cpp/llvm/docs/HistoricalNotes/2007-OriginalClangReadme.txt deleted file mode 100644 index 611dc9d2..00000000 --- a/cpp/llvm/docs/HistoricalNotes/2007-OriginalClangReadme.txt +++ /dev/null @@ -1,178 +0,0 @@ -//===----------------------------------------------------------------------===// -// C Language Family Front-end -//===----------------------------------------------------------------------===// - Chris Lattner - -I. Introduction: - - clang: noun - 1. A loud, resonant, metallic sound. - 2. The strident call of a crane or goose. - 3. C-language family front-end toolkit. - - The world needs better compiler tools, tools which are built as libraries. This - design point allows reuse of the tools in new and novel ways. However, building - the tools as libraries isn't enough: they must have clean APIs, be as - decoupled from each other as possible, and be easy to modify/extend. This - requires clean layering, decent design, and avoiding tying the libraries to a - specific use. Oh yeah, did I mention that we want the resultant libraries to - be as fast as possible? :) - - This front-end is built as a component of the LLVM toolkit that can be used - with the LLVM backend or independently of it. In this spirit, the API has been - carefully designed as the following components: - - libsupport - Basic support library, reused from LLVM. - - libsystem - System abstraction library, reused from LLVM. - - libbasic - Diagnostics, SourceLocations, SourceBuffer abstraction, - file system caching for input source files. This depends on - libsupport and libsystem. - - libast - Provides classes to represent the C AST, the C type system, - builtin functions, and various helpers for analyzing and - manipulating the AST (visitors, pretty printers, etc). This - library depends on libbasic. - - - liblex - C/C++/ObjC lexing and preprocessing, identifier hash table, - pragma handling, tokens, and macros. This depends on libbasic. - - libparse - C (for now) parsing and local semantic analysis. This library - invokes coarse-grained 'Actions' provided by the client to do - stuff (e.g. libsema builds ASTs). This depends on liblex. - - libsema - Provides a set of parser actions to build a standardized AST - for programs. AST's are 'streamed' out a top-level declaration - at a time, allowing clients to use decl-at-a-time processing, - build up entire translation units, or even build 'whole - program' ASTs depending on how they use the APIs. This depends - on libast and libparse. - - librewrite - Fast, scalable rewriting of source code. This operates on - the raw syntactic text of source code, allowing a client - to insert and delete text in very large source files using - the same source location information embedded in ASTs. This - is intended to be a low-level API that is useful for - higher-level clients and libraries such as code refactoring. - - libanalysis - Source-level dataflow analysis useful for performing analyses - such as computing live variables. It also includes a - path-sensitive "graph-reachability" engine for writing - analyses that reason about different possible paths of - execution through source code. This is currently being - employed to write a set of checks for finding bugs in software. - - libcodegen - Lower the AST to LLVM IR for optimization & codegen. Depends - on libast. - - clang - An example driver, client of the libraries at various levels. - This depends on all these libraries, and on LLVM VMCore. - - This front-end has been intentionally built as a DAG of libraries, making it - easy to reuse individual parts or replace pieces if desired. For example, to - build a preprocessor, you take the Basic and Lexer libraries. If you want an - indexer, you take those plus the Parser library and provide some actions for - indexing. If you want a refactoring, static analysis, or source-to-source - compiler tool, it makes sense to take those plus the AST building and semantic - analyzer library. Finally, if you want to use this with the LLVM backend, - you'd take these components plus the AST to LLVM lowering code. - - In the future I hope this toolkit will grow to include new and interesting - components, including a C++ front-end, ObjC support, and a whole lot of other - things. - - Finally, it should be pointed out that the goal here is to build something that - is high-quality and industrial-strength: all the obnoxious features of the C - family must be correctly supported (trigraphs, preprocessor arcana, K&R-style - prototypes, GCC/MS extensions, etc). It cannot be used if it is not 'real'. - - -II. Usage of clang driver: - - * Basic Command-Line Options: - - Help: clang --help - - Standard GCC options accepted: -E, -I*, -i*, -pedantic, -std=c90, etc. - - To make diagnostics more gcc-like: -fno-caret-diagnostics -fno-show-column - - Enable metric printing: -stats - - * -fsyntax-only is currently the default mode. - - * -E mode works the same way as GCC. - - * -Eonly mode does all preprocessing, but does not print the output, - useful for timing the preprocessor. - - * -fsyntax-only is currently partially implemented, lacking some - semantic analysis (some errors and warnings are not produced). - - * -parse-noop parses code without building an AST. This is useful - for timing the cost of the parser without including AST building - time. - - * -parse-ast builds ASTs, but doesn't print them. This is most - useful for timing AST building vs -parse-noop. - - * -parse-ast-print pretty prints most expression and statements nodes. - - * -parse-ast-check checks that diagnostic messages that are expected - are reported and that those which are reported are expected. - - * -dump-cfg builds ASTs and then CFGs. CFGs are then pretty-printed. - - * -view-cfg builds ASTs and then CFGs. CFGs are then visualized by - invoking Graphviz. - - For more information on getting Graphviz to work with clang/LLVM, - see: http://llvm.org/docs/ProgrammersManual.html#ViewGraph - - -III. Current advantages over GCC: - - * Column numbers are fully tracked (no 256 col limit, no GCC-style pruning). - * All diagnostics have column numbers, includes 'caret diagnostics', and they - highlight regions of interesting code (e.g. the LHS and RHS of a binop). - * Full diagnostic customization by client (can format diagnostics however they - like, e.g. in an IDE or refactoring tool) through DiagnosticClient interface. - * Built as a framework, can be reused by multiple tools. - * All languages supported linked into same library (no cc1,cc1obj, ...). - * mmap's code in read-only, does not dirty the pages like GCC (mem footprint). - * LLVM License, can be linked into non-GPL projects. - * Full diagnostic control, per diagnostic. Diagnostics are identified by ID. - * Significantly faster than GCC at semantic analysis, parsing, preprocessing - and lexing. - * Defers exposing platform-specific stuff to as late as possible, tracks use of - platform-specific features (e.g. #ifdef PPC) to allow 'portable bytecodes'. - * The lexer doesn't rely on the "lexer hack": it has no notion of scope and - does not categorize identifiers as types or variables -- this is up to the - parser to decide. - -Potential Future Features: - - * Fine grained diag control within the source (#pragma enable/disable warning). - * Better token tracking within macros? (Token came from this line, which is - a macro argument instantiated here, recursively instantiated here). - * Fast #import with a module system. - * Dependency tracking: change to header file doesn't recompile every function - that texually depends on it: recompile only those functions that need it. - This is aka 'incremental parsing'. - - -IV. Missing Functionality / Improvements - -Lexer: - * Source character mapping. GCC supports ASCII and UTF-8. - See GCC options: -ftarget-charset and -ftarget-wide-charset. - * Universal character support. Experimental in GCC, enabled with - -fextended-identifiers. - * -fpreprocessed mode. - -Preprocessor: - * #assert/#unassert - * MSExtension: "L#param" stringizes to a wide string literal. - * Add support for -M* - -Traditional Preprocessor: - * Currently, we have none. :) - diff --git a/cpp/llvm/docs/HowToAddABuilder.html b/cpp/llvm/docs/HowToAddABuilder.html deleted file mode 100644 index 0de2dace..00000000 --- a/cpp/llvm/docs/HowToAddABuilder.html +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - How To Add Your Build Configuration To LLVM Buildbot Infrastructure - - - - - -

How To Add Your Build Configuration To LLVM Buildbot Infrastructure

-
    -
  1. Introduction
  2. -
  3. Steps To Add Builder To LLVM Buildbot
  4. -
-
-

Written by Galina Kistanova

-
- - -

Introduction

- - -
- -

This document contains information about adding a build configuration and - buildslave to private slave builder to LLVM Buildbot Infrastructure - http://lab.llvm.org:8011

- -
- - -

Steps To Add Builder To LLVM Buildbot

- - -
- -

Volunteers can provide their build machines to work as build slaves to - public LLVM Buildbot.

- -

Here are the steps you can follow to do so:

- -
    -
  1. Check the existing build configurations to make sure the one you are - interested in is not covered yet or gets built on your computer much - faster than on the existing one. We prefer faster builds so developers - will get feedback sooner after changes get committed.

  2. - -
  3. The computer you will be registering with the LLVM buildbot - infrastructure should have all dependencies installed and you can - actually build your configuration successfully. Please check what degree - of parallelism (-j param) would give the fastest build. - You can build multiple configurations on one computer.

  4. - -
  5. Install buildslave (currently we are using buildbot version 0.8.5). - Depending on the platform, buildslave could be available to download and - install with your packet manager, or you can download it directly from - http://trac.buildbot.net and - install it manually.

  6. - -
  7. Create a designated user account, your buildslave will be running - under, and set appropriate permissions.

  8. - -
  9. Choose the buildslave root directory (all builds will be placed under - it), buildslave access name and password the build master will be using - to authenticate your buildslave.

  10. - -
  11. Create a buildslave in context of that buildslave account. - Point it to the lab.llvm.org port 9990 (see - - Buildbot documentation, Creating a slave - for more details) by running the following command:

    - -
    -
    -$ buildslave create-slave buildslave-root-directory \
    -             lab.llvm.org:9990 \
    -             buildslave-access-name buildslave-access-password
    -
    -
  12. - -
  13. Fill the buildslave description and admin name/e-mail. - Here is an example of the buildslave description:

    - -
    -
    -Windows 7 x64
    -Core i7 (2.66GHz), 16GB of RAM
    -
    -g++.exe (TDM-1 mingw32) 4.4.0
    -GNU Binutils 2.19.1
    -cmake version 2.8.4
    -Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
    -
    -
  14. - -
  15. Make sure you can actually start the buildslave successfully. Then set - up your buildslave to start automatically at the start up time. - See the buildbot documentation for help. - You may want to restart your computer to see if it works.

  16. - -
  17. Send a patch which adds your build slave and your builder to zorg.

    -
      -
    • slaves are added to - buildbot/osuosl/master/config/slaves.py
    • -
    • builders are added to - buildbot/osuosl/master/config/builders.py
    • -
  18. - -
  19. Send the buildslave access name and the access password directly - to Galina Kistanova, and wait - till she will let you know that your changes are applied and buildmaster - is reconfigured.

    - -
  20. Check the status of your buildslave on the - Waterfall Display - to make sure it is connected, and - - http://lab.llvm.org:8011/buildslaves/<your-buildslave-name> - to see if administrator contact and slave information are correct.

    -
  21. - -
  22. Wait for the first build to succeed and enjoy.

  23. -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - The LLVM Compiler Infrastructure -
- Last modified: $Date: 2011-10-31 12:50:0 -0700 (Mon, 31 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/HowToReleaseLLVM.html b/cpp/llvm/docs/HowToReleaseLLVM.html deleted file mode 100644 index 56ddbfbd..00000000 --- a/cpp/llvm/docs/HowToReleaseLLVM.html +++ /dev/null @@ -1,581 +0,0 @@ - - - - - How To Release LLVM To The Public - - - - -

How To Release LLVM To The Public

-
    -
  1. Introduction
  2. -
  3. Qualification Criteria
  4. -
  5. Release Timeline
  6. -
  7. Release Process
  8. -
- - - -

Introduction

- - -
- -

This document contains information about successfully releasing LLVM — - including subprojects: e.g., clang and dragonegg — to - the public. It is the Release Manager's responsibility to ensure that a high - quality build of LLVM is released.

- -
- - -

Release Timeline

- -
- -

LLVM is released on a time based schedule — roughly every 6 months. We - do not normally have dot releases because of the nature of LLVM's incremental - development philosophy. That said, the only thing preventing dot releases for - critical bug fixes from happening is a lack of resources — testers, - machines, time, etc. And, because of the high quality we desire for LLVM - releases, we cannot allow for a truncated form of release qualification.

- -

The release process is roughly as follows:

- -
    -
  • Set code freeze and branch creation date for 6 months after last code - freeze date. Announce release schedule to the LLVM community and update - the website.

  • - -
  • Create release branch and begin release process.

  • - -
  • Send out release candidate sources for first round of testing. Testing - lasts 7-10 days. During the first round of testing, any regressions found - should be fixed. Patches are merged from mainline into the release - branch. Also, all features need to be completed during this time. Any - features not completed at the end of the first round of testing will be - removed or disabled for the release.

  • - -
  • Generate and send out the second release candidate sources. Only - critial bugs found during this testing phase will be fixed. Any - bugs introduced by merged patches will be fixed. If so a third round of - testing is needed.

  • - -
  • The release notes are updated.

  • - -
  • Finally, release!

  • -
- -
- - -

Release Process

- - -
- -
    -
  1. Release Administrative Tasks -
      -
    1. Create Release Branch
    2. -
    3. Update Version Numbers
    4. -
    -
  2. -
  3. Building the Release -
      -
    1. Build the LLVM Source Distributions
    2. -
    3. Build LLVM
    4. -
    5. Build the Clang Binary Distribution
    6. -
    7. Target Specific Build Details
    8. -
    -
  4. -
  5. Release Qualification Criteria -
      -
    1. Qualify LLVM
    2. -
    3. Qualify Clang
    4. -
    5. Specific Target Qualification Details
    6. -
    -
  6. - -
  7. Community Testing
  8. -
  9. Release Patch Rules
  10. -
  11. Release final tasks -
      -
    1. Update Documentation
    2. -
    3. Tag the LLVM Final Release
    4. -
    5. Update the LLVM Demo Page
    6. -
    7. Update the LLVM Website
    8. -
    9. Announce the Release
    10. -
    -
  12. -
- - -

Release Administrative Tasks

- -
- -

This section describes a few administrative tasks that need to be done for - the release process to begin. Specifically, it involves:

- -
    -
  • Creating the release branch,
  • -
  • Setting version numbers, and
  • -
  • Tagging release candidates for the release team to begin testing
  • -
- - -

Create Release Branch

- -
- -

Branch the Subversion trunk using the following procedure:

- -
    -
  1. Remind developers that the release branching is imminent and to refrain - from committing patches that might break the build. E.g., new features, - large patches for works in progress, an overhaul of the type system, an - exciting new TableGen feature, etc.

  2. - -
  3. Verify that the current Subversion trunk is in decent shape by - examining nightly tester and buildbot results.

  4. - -
  5. Create the release branch for llvm, clang, - the test-suite, and dragonegg from the last known good - revision. The branch's name is release_XY, - where X is the major and Y the minor release - numbers. The branches should be created using the following commands:

    - -
    -
    -$ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
    -           https://llvm.org/svn/llvm-project/llvm/branches/release_XY
    -
    -$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
    -           https://llvm.org/svn/llvm-project/cfe/branches/release_XY
    -
    -$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
    -           https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
    -
    -$ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
    -           https://llvm.org/svn/llvm-project/test-suite/branches/release_XY
    -
    -
  6. - -
  7. Advise developers that they may now check their patches into the - Subversion tree again.

  8. - -
  9. The Release Manager should switch to the release branch, because all - changes to the release will now be done in the branch. The easiest way to - do this is to grab a working copy using the following commands:

    - -
    -
    -$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
    -
    -$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
    -
    -$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
    -
    -$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
    -
    -
  10. -
- -
- - -

Update LLVM Version

- -
- -

After creating the LLVM release branch, update the release branches' - autoconf and configure.ac versions from 'X.Ysvn' - to 'X.Y'. Update it on mainline as well to be the next version - ('X.Y+1svn'). Regenerate the configure scripts for both - llvm and the test-suite.

- -

In addition, the version numbers of all the Bugzilla components must be - updated for the next release.

- -
- - -

Build the LLVM Release Candidates

- -
- -

Create release candidates for llvm, clang, - dragonegg, and the LLVM test-suite by tagging the branch - with the respective release candidate number. For instance, to - create Release Candidate 1 you would issue the following commands:

- -
-
-$ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY
-$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
-           https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY
-$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
-           https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY
-$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
-           https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1
-
-$ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY
-$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
-           https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1
-
-
- -

Similarly, Release Candidate 2 would be named RC2 and so - on. This keeps a permanent copy of the release candidate around for people to - export and build as they wish. The final released sources will be tagged in - the RELEASE_XY directory as Final - (c.f. Tag the LLVM Final Release).

- -

The Release Manager may supply pre-packaged source tarballs for users. This - can be done with the following commands:

- -
-
-$ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1 llvm-X.Yrc1
-$ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1 clang-X.Yrc1
-$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1 dragonegg-X.Yrc1
-$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1 llvm-test-X.Yrc1
-
-$ tar -cvf - llvm-X.Yrc1        | gzip > llvm-X.Yrc1.src.tar.gz
-$ tar -cvf - clang-X.Yrc1       | gzip > clang-X.Yrc1.src.tar.gz
-$ tar -cvf - dragonegg-X.Yrc1   | gzip > dragonegg-X.Yrc1.src.tar.gz
-$ tar -cvf - llvm-test-X.Yrc1   | gzip > llvm-test-X.Yrc1.src.tar.gz
-
-
- -
- -
- - -

Building the Release

- -
- -

The builds of llvm, clang, and dragonegg - must be free of errors and warnings in Debug, Release+Asserts, and - Release builds. If all builds are clean, then the release passes Build - Qualification.

- -

The make options for building the different modes:

- - - - - - -
ModeOptions
DebugENABLE_OPTIMIZED=0
Release+AssertsENABLE_OPTIMIZED=1
ReleaseENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1
- - -

Build LLVM

- -
- -

Build Debug, Release+Asserts, and Release versions - of llvm on all supported platforms. Directions to build - llvm are here.

- -
- - -

Build Clang Binary Distribution

- -
- -

Creating the clang binary distribution - (Debug/Release+Asserts/Release) requires performing the following steps for - each supported platform:

- -
    -
  1. Build clang according to the directions - here.
  2. - -
  3. Build both a Debug and Release version of clang. The binary will be the - Release build.
  4. - -
  5. Package clang (details to follow).
  6. -
- -
- - -

Target Specific Build Details

- -
- -

The table below specifies which compilers are used for each Arch/OS - combination when qualifying the build of llvm, clang, - and dragonegg.

- - - - - - - - - - -
Architecture OS compiler
x86-32 Mac OS 10.5 gcc 4.0.1
x86-32 Linux gcc 4.2.X, gcc 4.3.X
x86-32 FreeBSD gcc 4.2.X
x86-32 mingw gcc 3.4.5
x86-64 Mac OS 10.5 gcc 4.0.1
x86-64 Linux gcc 4.2.X, gcc 4.3.X
x86-64 FreeBSD gcc 4.2.X
- -
- -
- - -

Building the Release

- -
- -

A release is qualified when it has no regressions from the previous release - (or baseline). Regressions are related to correctness first and performance - second. (We may tolerate some minor performance regressions if they are - deemed necessary for the general quality of the compiler.)

- -

Regressions are new failures in the set of tests that are used to qualify - each product and only include things on the list. Every release will have - some bugs in it. It is the reality of developing a complex piece of - software. We need a very concrete and definitive release criteria that - ensures we have monotonically improving quality on some metric. The metric we - use is described below. This doesn't mean that we don't care about other - criteria, but these are the criteria which we found to be most important and - which must be satisfied before a release can go out

- - -

Qualify LLVM

- -
- -

LLVM is qualified when it has a clean test run without a front-end. And it - has no regressions when using either clang or dragonegg - with the test-suite from the previous release.

- -
- - -

Qualify Clang

- -
- -

Clang is qualified when front-end specific tests in the - llvm dejagnu test suite all pass, clang's own test suite passes - cleanly, and there are no regressions in the test-suite.

- -
- - -

Specific Target Qualification Details

- -
- - - - - - - - - -
Architecture OS clang baseline tests
x86-32 Linux last release llvm dejagnu, clang tests, test-suite (including spec)
x86-32 FreeBSD last release llvm dejagnu, clang tests, test-suite
x86-32 mingw none QT
x86-64 Mac OS 10.X last release llvm dejagnu, clang tests, test-suite (including spec)
x86-64 Linux last release llvm dejagnu, clang tests, test-suite (including spec)
x86-64 FreeBSD last release llvm dejagnu, clang tests, test-suite
- -
- -
- - -

Community Testing

-
- -

Once all testing has been completed and appropriate bugs filed, the release - candidate tarballs are put on the website and the LLVM community is - notified. Ask that all LLVM developers test the release in 2 ways:

- -
    -
  1. Download llvm-X.Y, llvm-test-X.Y, and the - appropriate clang binary. Build LLVM. Run make check and - the full LLVM test suite (make TEST=nightly report).
  2. - -
  3. Download llvm-X.Y, llvm-test-X.Y, and the - clang sources. Compile everything. Run make check and - the full LLVM test suite (make TEST=nightly report).
  4. -
- -

Ask LLVM developers to submit the test suite report and make check - results to the list. Verify that there are no regressions from the previous - release. The results are not used to qualify a release, but to spot other - potential problems. For unsupported targets, verify that make check - is at least clean.

- -

During the first round of testing, all regressions must be fixed before the - second release candidate is tagged.

- -

If this is the second round of testing, the testing is only to ensure that - bug fixes previously merged in have not created new major problems. This - is not the time to solve additional and unrelated bugs! If no patches are - merged in, the release is determined to be ready and the release manager may - move onto the next stage.

- -
- - -

Release Patch Rules

- -
- -

Below are the rules regarding patching the release branch:

- -
    -
  1. Patches applied to the release branch may only be applied by the - release manager.

  2. - -
  3. During the first round of testing, patches that fix regressions or that - are small and relatively risk free (verified by the appropriate code - owner) are applied to the branch. Code owners are asked to be very - conservative in approving patches for the branch. We reserve the right to - reject any patch that does not fix a regression as previously - defined.

  4. - -
  5. During the remaining rounds of testing, only patches that fix critical - regressions may be applied.

  6. -
- -
- - -

Release Final Tasks

- -
- -

The final stages of the release process involves tagging the "final" release - branch, updating documentation that refers to the release, and updating the - demo page.

- - -

Update Documentation

- -
- -

Review the documentation and ensure that it is up to date. The "Release - Notes" must be updated to reflect new features, bug fixes, new known issues, - and changes in the list of supported platforms. The "Getting Started Guide" - should be updated to reflect the new release version number tag avaiable from - Subversion and changes in basic system requirements. Merge both changes from - mainline into the release branch.

- -
- - -

Tag the LLVM Final Release

- -
- -

Tag the final release sources using the following procedure:

- -
-
-$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
-           https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
-           https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
-           https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/Final
-
-$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
-           https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/Final
-
-
- -
- -
- - -

Update the LLVM Demo Page

- -
- -

The LLVM demo page must be updated to use the new release. This consists of - using the new clang binary and building LLVM.

- - -

Update the LLVM Website

- -
- -

The website must be updated before the release announcement is sent out. Here - is what to do:

- -
    -
  1. Check out the www module from Subversion.
  2. - -
  3. Create a new subdirectory X.Y in the releases directory.
  4. - -
  5. Commit the llvm, test-suite, clang source, - clang binaries, dragonegg source, and dragonegg - binaries in this new directory.
  6. - -
  7. Copy and commit the llvm/docs and LICENSE.txt files - into this new directory. The docs should be built with - BUILD_FOR_WEBSITE=1.
  8. - -
  9. Commit the index.html to the release/X.Y directory to - redirect (use from previous release.
  10. - -
  11. Update the releases/download.html file with the new release.
  12. - -
  13. Update the releases/index.html with the new release and link to - release documentation.
  14. - -
  15. Finally, update the main page (index.html and sidebar) to point - to the new release and release announcement. Make sure this all gets - committed back into Subversion.
  16. -
- -
- - -

Announce the Release

- -
- -

Have Chris send out the release announcement when everything is finished.

- -
- -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - The LLVM Compiler Infrastructure -
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/HowToSubmitABug.html b/cpp/llvm/docs/HowToSubmitABug.html deleted file mode 100644 index ab3f646a..00000000 --- a/cpp/llvm/docs/HowToSubmitABug.html +++ /dev/null @@ -1,348 +0,0 @@ - - - - - How to submit an LLVM bug report - - - - -

- How to submit an LLVM bug report -

- - - - - - -
-
    -
  1. Introduction - Got bugs?
  2. -
  3. Crashing Bugs -
  4. -
  5. Miscompilations
  6. -
  7. Incorrect code generation (JIT and LLC)
  8. -
-
-

Written by Chris Lattner and - Misha Brukman

-
-
- Debugging -
- - -

- Introduction - Got bugs? -

- - -
- -

If you're working with LLVM and run into a bug, we definitely want to know -about it. This document describes what you can do to increase the odds of -getting it fixed quickly.

- -

Basically you have to do two things at a minimum. First, decide whether the -bug crashes the compiler (or an LLVM pass), or if the -compiler is miscompiling the program (i.e., the -compiler successfully produces an executable, but it doesn't run right). Based -on -what type of bug it is, follow the instructions in the linked section to narrow -down the bug so that the person who fixes it will be able to find the problem -more easily.

- -

Once you have a reduced test-case, go to the LLVM Bug Tracking -System and fill out the form with the necessary details (note that you don't -need to pick a category, just use the "new-bugs" category if you're not sure). -The bug description should contain the following -information:

- -
    -
  • All information necessary to reproduce the problem.
  • -
  • The reduced test-case that triggers the bug.
  • -
  • The location where you obtained LLVM (if not from our Subversion - repository).
  • -
- -

Thanks for helping us make LLVM better!

- -
- - -

- Crashing Bugs -

- - -
- -

More often than not, bugs in the compiler cause it to crash—often due -to an assertion failure of some sort. The most important -piece of the puzzle is to figure out if it is crashing in the GCC front-end -or if it is one of the LLVM libraries (e.g. the optimizer or code generator) -that has problems.

- -

To figure out which component is crashing (the front-end, -optimizer or code generator), run the -llvm-gcc command line as you were when the crash occurred, but -with the following extra command line options:

- -
    -
  • -O0 -emit-llvm: If llvm-gcc still crashes when - passed these options (which disable the optimizer and code generator), then - the crash is in the front-end. Jump ahead to the section on front-end bugs.
  • - -
  • -emit-llvm: If llvm-gcc crashes with this option - (which disables the code generator), you found an optimizer bug. Jump ahead - to compile-time optimization bugs.
  • - -
  • Otherwise, you have a code generator crash. Jump ahead to code generator bugs.
  • - -
- - -

- Front-end bugs -

- -
- -

If the problem is in the front-end, you should re-run the same -llvm-gcc command that resulted in the crash, but add the --save-temps option. The compiler will crash again, but it will leave -behind a foo.i file (containing preprocessed C source code) and -possibly foo.s for each -compiled foo.c file. Send us the foo.i file, -along with the options you passed to llvm-gcc, and a brief description of the -error it caused.

- -

The delta tool helps to reduce the -preprocessed file down to the smallest amount of code that still replicates the -problem. You're encouraged to use delta to reduce the code to make the -developers' lives easier. This website -has instructions on the best way to use delta.

- -
- - -

- Compile-time optimization bugs -

- -
- -

If you find that a bug crashes in the optimizer, compile your test-case to a -.bc file by passing "-emit-llvm -O0 -c -o foo.bc". -Then run:

- -
-

opt -std-compile-opts -debug-pass=Arguments foo.bc - -disable-output

-
- -

This command should do two things: it should print out a list of passes, and -then it should crash in the same way as llvm-gcc. If it doesn't crash, please -follow the instructions for a front-end bug.

- -

If this does crash, then you should be able to debug this with the following -bugpoint command:

- -
-

bugpoint foo.bc <list of passes printed by -opt>

-
- -

Please run this, then file a bug with the instructions and reduced .bc files -that bugpoint emits. If something goes wrong with bugpoint, please submit the -"foo.bc" file and the list of passes printed by opt.

- -
- - -

- Code generator bugs -

- -
- -

If you find a bug that crashes llvm-gcc in the code generator, compile your -source file to a .bc file by passing "-emit-llvm -c -o foo.bc" -to llvm-gcc (in addition to the options you already pass). Once your have -foo.bc, one of the following commands should fail:

- -
    -
  1. llc foo.bc
  2. -
  3. llc foo.bc -relocation-model=pic
  4. -
  5. llc foo.bc -relocation-model=static
  6. -
- -

If none of these crash, please follow the instructions for a -front-end bug. If one of these do crash, you should -be able to reduce this with one of the following bugpoint command lines (use -the one corresponding to the command above that failed):

- -
    -
  1. bugpoint -run-llc foo.bc
  2. -
  3. bugpoint -run-llc foo.bc --tool-args - -relocation-model=pic
  4. -
  5. bugpoint -run-llc foo.bc --tool-args - -relocation-model=static
  6. -
- -

Please run this, then file a bug with the instructions and reduced .bc file -that bugpoint emits. If something goes wrong with bugpoint, please submit the -"foo.bc" file and the option that llc crashes with.

- -
- -
- - -

- Miscompilations -

- - -
- -

If llvm-gcc successfully produces an executable, but that executable doesn't -run right, this is either a bug in the code or a bug in the -compiler. The first thing to check is to make sure it is not using undefined -behavior (e.g. reading a variable before it is defined). In particular, check -to see if the program valgrinds clean, -passes purify, or some other memory checker tool. Many of the "LLVM bugs" that -we have chased down ended up being bugs in the program being compiled, not - LLVM.

- -

Once you determine that the program itself is not buggy, you should choose -which code generator you wish to compile the program with (e.g. C backend, the -JIT, or LLC) and optionally a series of LLVM passes to run. For example:

- -
-

-bugpoint -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]

-
- -

bugpoint will try to narrow down your list of passes to the one pass -that causes an error, and simplify the bitcode file as much as it can to assist -you. It will print a message letting you know how to reproduce the resulting -error.

- -
- - -

- Incorrect code generation -

- - -
- -

Similarly to debugging incorrect compilation by mis-behaving passes, you can -debug incorrect code generation by either LLC or the JIT, using -bugpoint. The process bugpoint follows in this case is to try -to narrow the code down to a function that is miscompiled by one or the other -method, but since for correctness, the entire program must be run, -bugpoint will compile the code it deems to not be affected with the C -Backend, and then link in the shared object it generates.

- -

To debug the JIT:

- -
-
-bugpoint -run-jit -output=[correct output file] [bitcode file]  \
-         --tool-args -- [arguments to pass to lli]              \
-         --args -- [program arguments]
-
-
- -

Similarly, to debug the LLC, one would run:

- -
-
-bugpoint -run-llc -output=[correct output file] [bitcode file]  \
-         --tool-args -- [arguments to pass to llc]              \
-         --args -- [program arguments]
-
-
- -

Special note: if you are debugging MultiSource or SPEC tests that -already exist in the llvm/test hierarchy, there is an easier way to -debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which -will pass the program options specified in the Makefiles:

- -
-

-cd llvm/test/../../program
-make bugpoint-jit -

-
- -

At the end of a successful bugpoint run, you will be presented -with two bitcode files: a safe file which can be compiled with the C -backend and the test file which either LLC or the JIT -mis-codegenerates, and thus causes the error.

- -

To reproduce the error that bugpoint found, it is sufficient to do -the following:

- -
    - -
  1. Regenerate the shared object from the safe bitcode file:

    - -
    -

    -llc -march=c safe.bc -o safe.c
    -gcc -shared safe.c -o safe.so -

    -
  2. - -
  3. If debugging LLC, compile test bitcode native and link with the shared - object:

    - -
    -

    -llc test.bc -o test.s
    -gcc test.s safe.so -o test.llc
    -./test.llc [program options] -

    -
  4. - -
  5. If debugging the JIT, load the shared object and supply the test - bitcode:

    - -
    -

    lli -load=safe.so test.bc [program options]

    -
  6. - -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- The LLVM Compiler Infrastructure -
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - - diff --git a/cpp/llvm/docs/LLVMBuild.html b/cpp/llvm/docs/LLVMBuild.html deleted file mode 100644 index a8420dd5..00000000 --- a/cpp/llvm/docs/LLVMBuild.html +++ /dev/null @@ -1,368 +0,0 @@ - - - - - LLVMBuild Documentation - - - - -

LLVMBuild Guide

- -
    -
  1. Introduction
  2. -
  3. Project Organization
  4. -
  5. Build Integration
  6. -
  7. Component Overview
  8. -
  9. Format Reference
  10. -
- - -

Introduction

- - -
-

This document describes the LLVMBuild organization and files which - we use to describe parts of the LLVM ecosystem. For description of specific - LLVMBuild related tools, please see the command guide.

- -

LLVM is designed to be a modular set of libraries which can be flexibly - mixed together in order to build a variety of tools, like compilers, JITs, - custom code generators, optimization passes, interpreters, and so on. Related - projects in the LLVM system like Clang and LLDB also tend to follow this - philosophy.

- -

In order to support this usage style, LLVM has a fairly strict structure as - to how the source code and various components are organized. The - LLVMBuild.txt files are the explicit specification of that structure, - and are used by the build systems and other tools in order to develop the LLVM - project.

-
- - -

Project Organization

- - - - -
-

The source code for LLVM projects using the LLVMBuild system (LLVM, Clang, - and LLDB) is organized into components, which define the separate - pieces of functionality that make up the project. These projects may consist - of many libraries, associated tools, build tools, or other utility tools (for - example, testing tools).

- -

For the most part, the project contents are organized around defining one - main component per each subdirectory. Each such directory contains - an LLVMBuild.txt which contains the component definitions.

- -

The component descriptions for the project as a whole are automatically - gathered by the LLVMBuild tools. The tools automatically traverse the source - directory structure to find all of the component description files. NOTE: For - performance/sanity reasons, we only traverse into subdirectories when the - parent itself contains an LLVMBuild.txt description file.

-
- - -

Build Integration

- - -
-

The LLVMBuild files themselves are just a declarative way to describe the - project structure. The actual building of the LLVM project is handled by - another build system (currently we support - both Makefiles - and CMake.

- -

The build system implementation will load the relevant contents of the - LLVMBuild files and use that to drive the actual project build. Typically, the - build system will only need to load this information at "configure" time, and - use it to generative native information. Build systems will also handle - automatically reconfiguring their information when the contents of - the LLVMBuild.txt files change.

- -

Developers generally are not expected to need to be aware of the details of - how the LLVMBuild system is integrated into their build. Ideally, LLVM - developers who are not working on the build system would only ever need to - modify the contents of the LLVMBuild.txt description files (although we - have not reached this goal yet).

- -

For more information on the utility tool we provide to help interfacing - with the build system, please see - the llvm-build - documentation.

-
- - -

Component Overview

- - -
-

As mentioned earlier, LLVM projects are organized into - logical components. Every component is typically grouped into its - own subdirectory. Generally, a component is organized around a coherent group - of sources which have some kind of clear API separation from other parts of - the code.

- -

LLVM primarily uses the following types of components:

-
    -
  • Libraries - Library components define a distinct API which can - be independently linked into LLVM client applications. Libraries typically - have private and public header files, and may specify a link of required - libraries that they build on top of.
  • - -
  • Build Tools - Build tools are applications which are designed - to be run as part of the build process (typically to generate other source - files). Currently, LLVM uses one main build tool - called TableGen to generate a - variety of source files.
  • - -
  • Tools - Command line applications which are built using the - LLVM component libraries. Most LLVM tools are small and are primarily - frontends to the library interfaces.
  • - - -
- -

Components are described using LLVMBuild.txt files in the - directories that define the component. See - the Format Reference section for information on - the exact format of these files.

-
- - -

LLVMBuild Format Reference

- - -
-

LLVMBuild files are written in a simple variant of the INI or configuration - file format (Wikipedia - entry). The format defines a list of sections each of which may contain - some number of properties. A simple example of the file format is below:

-
-
-; Comments start with a semi-colon.
-
-; Sections are declared using square brackets.
-[component_0]
-
-; Properties are declared using '=' and are contained in the previous section.
-;
-; We support simple string and boolean scalar values and list values, where
-; items are separated by spaces. There is no support for quoting, and so
-; property values may not contain spaces.
-property_name = property_value
-list_property_name = value_1 value_2 ... value_n
-boolean_property_name = 1 (or 0)
-
-
- -

LLVMBuild files are expected to define a strict set of sections and - properties. An typical component description file for a library - component would look typically look like the following example:

-
-
-[component_0]
-type = Library
-name = Linker
-parent = Libraries
-required_libraries = Archive BitReader Core Support TransformUtils
-
-
- -

A full description of the exact sections and properties which are allowed - follows.

- -

Each file may define exactly one common component, named "common". The - common component may define the following properties:

-
    -
  • subdirectories [optional] -

    If given, a list of the names of the subdirectories from the current - subpath to search for additional LLVMBuild files.

  • -
- -

Each file may define multiple components. Each component is described by a - section who name starts with "component". The remainder of the section name is - ignored, but each section name must be unique. Typically components are just - number in order for files with multiple components ("component_0", - "component_1", and so on).

- -

Section names not matching this format (or the "common" section) are - currently unused and are disallowed.

- -

Every component is defined by the properties in the section. The exact list - of properties that are allowed depends on the component - type. Components may not define any properties other than those - expected by the component type.

- -

Every component must define the following properties:

-
    -
  • type [required] -

    The type of the component. Supported component types are - detailed below. Most components will define additional properties which - may be required or optional.

  • - -
  • name [required] -

    The name of the component. Names are required to be unique - across the entire project.

  • - -
  • parent [required] -

    The name of the logical parent of the component. Components are - organized into a logical tree to make it easier to navigate and organize - groups of components. The parents have no semantics as far as the project - build is concerned, however. Typically, the parent will be the main - component of the parent directory.

    - - - -

    Components may reference the root pseudo component using '$ROOT' to - indicate they should logically be grouped at the top-level.

    -
  • -
- -

Components may define the following properties:

-
    -
  • dependencies [optional] -

    If specified, a list of names of components which must be built - prior to this one. This should only be exactly those components which - produce some tool or source code required for building the - component.

    - -

    NOTE: Group and LibraryGroup components have no semantics for - the actual build, and are not allowed to specify dependencies.

  • -
- -

The following section lists the available component types, as well as the - properties which are associated with that component.

- -
    -
  • type = Group -

    Group components exist purely to allow additional arbitrary structuring - of the logical components tree. For example, one might define a - "Libraries" group to hold all of the root library components.

    - -

    Group components have no additionally properties.

    -
  • - -
  • type = Library -

    Library components define an individual library which should be built - from the source code in the component directory.

    - -

    Components with this type use the following properties:

    -
      -
    • library_name [optional] -

      If given, the name to use for the actual library file on disk. If - not given, the name is derived from the component name - itself.

    • - -
    • required_libraries [optional] -

      If given, a list of the names of Library or LibraryGroup components - which must also be linked in whenever this library is used. That is, - the link time dependencies for this component. When tools are built, - the build system will include the transitive closure of - all required_libraries for the components the tool needs.

    • - -
    • add_to_library_groups [optional] -

      If given, a list of the names of LibraryGroup components which this - component is also part of. This allows nesting groups of - components. For example, the X86 target might define a library - group for all of the X86 components. That library group might - then be included in the all-targets library group.

    • - -
    • installed [optional] [boolean] -

      Whether this library is installed. Libraries that are not installed - are only reported by llvm-config when it is run as part of a - development directory.

    • -
    -
  • - -
  • type = LibraryGroup -

    LibraryGroup components are a mechanism to allow easy definition of - useful sets of related components. In particular, we use them to easily - specify things like "all targets", or "all assembly printers".

    - -

    Components with this type use the following properties:

    -
      -
    • required_libraries [optional] -

      See the Library type for a description of this property.

    • - -
    • add_to_library_groups [optional] -

      See the Library type for a description of this property.

    • -
    -
  • - -
  • type = TargetGroup -

    TargetGroup components are an extension of LibraryGroups, specifically - for defining LLVM targets (which are handled specially in a few - places).

    - -

    The name of the component should always be the name of the target.

    - -

    Components with this type use the LibraryGroup properties in addition - to:

    -
      -
    • has_asmparser [optional] [boolean] -

      Whether this target defines an assembly parser.

    • -
    • has_asmprinter [optional] [boolean] -

      Whether this target defines an assembly printer.

    • -
    • has_disassembler [optional] [boolean] -

      Whether this target defines a disassembler.

    • -
    • has_jit [optional] [boolean] -

      Whether this target supports JIT compilation.

    • -
    -
  • - -
  • type = Tool -

    Tool components define standalone command line tools which should be - built from the source code in the component directory and linked.

    - -

    Components with this type use the following properties:

    -
      -
    • required_libraries [optional] - -

      If given, a list of the names of Library or LibraryGroup components - which this tool is required to be linked with. NOTE: The values - should be the component names, which may not always match up with the - actual library names on disk.

      - -

      Build systems are expected to properly include all of the libraries - required by the linked components (i.e., the transitive closer - of required_libraries).

      - -

      Build systems are also expected to understand that those library - components must be built prior to linking -- they do not also need to - be listed under dependencies.

    • -
    -
  • - -
  • type = BuildTool -

    BuildTool components are like Tool components, except that the tool is - supposed to be built for the platform where the build is running (instead - of that platform being targetted). Build systems are expected to handle - the fact that required libraries may need to be built for multiple - platforms in order to be able to link this tool.

    - -

    BuildTool components currently use the exact same properties as Tool - components, the type distinction is only used to differentiate what the - tool is built for.

    -
  • -
-
- - -
-
- Valid CSS - Valid HTML 4.01 - - The LLVM Compiler Infrastructure
- Last modified: $Date$ -
- - diff --git a/cpp/llvm/docs/LangRef.html b/cpp/llvm/docs/LangRef.html deleted file mode 100644 index 36deee58..00000000 --- a/cpp/llvm/docs/LangRef.html +++ /dev/null @@ -1,8512 +0,0 @@ - - - - LLVM Assembly Language Reference Manual - - - - - - - - -

LLVM Language Reference Manual

-
    -
  1. Abstract
  2. -
  3. Introduction
  4. -
  5. Identifiers
  6. -
  7. High Level Structure -
      -
    1. Module Structure
    2. -
    3. Linkage Types -
        -
      1. 'private' Linkage
      2. -
      3. 'linker_private' Linkage
      4. -
      5. 'linker_private_weak' Linkage
      6. -
      7. 'linker_private_weak_def_auto' Linkage
      8. -
      9. 'internal' Linkage
      10. -
      11. 'available_externally' Linkage
      12. -
      13. 'linkonce' Linkage
      14. -
      15. 'common' Linkage
      16. -
      17. 'weak' Linkage
      18. -
      19. 'appending' Linkage
      20. -
      21. 'extern_weak' Linkage
      22. -
      23. 'linkonce_odr' Linkage
      24. -
      25. 'weak_odr' Linkage
      26. -
      27. 'external' Linkage
      28. -
      29. 'dllimport' Linkage
      30. -
      31. 'dllexport' Linkage
      32. -
      -
    4. -
    5. Calling Conventions
    6. -
    7. Named Types
    8. -
    9. Global Variables
    10. -
    11. Functions
    12. -
    13. Aliases
    14. -
    15. Named Metadata
    16. -
    17. Parameter Attributes
    18. -
    19. Function Attributes
    20. -
    21. Garbage Collector Names
    22. -
    23. Module-Level Inline Assembly
    24. -
    25. Data Layout
    26. -
    27. Pointer Aliasing Rules
    28. -
    29. Volatile Memory Accesses
    30. -
    31. Memory Model for Concurrent Operations
    32. -
    33. Atomic Memory Ordering Constraints
    34. -
    -
  8. -
  9. Type System -
      -
    1. Type Classifications
    2. -
    3. Primitive Types -
        -
      1. Integer Type
      2. -
      3. Floating Point Types
      4. -
      5. X86mmx Type
      6. -
      7. Void Type
      8. -
      9. Label Type
      10. -
      11. Metadata Type
      12. -
      -
    4. -
    5. Derived Types -
        -
      1. Aggregate Types -
          -
        1. Array Type
        2. -
        3. Structure Type
        4. -
        5. Opaque Structure Types
        6. -
        7. Vector Type
        8. -
        -
      2. -
      3. Function Type
      4. -
      5. Pointer Type
      6. -
      -
    6. -
    -
  10. -
  11. Constants -
      -
    1. Simple Constants
    2. -
    3. Complex Constants
    4. -
    5. Global Variable and Function Addresses
    6. -
    7. Undefined Values
    8. -
    9. Poison Values
    10. -
    11. Addresses of Basic Blocks
    12. -
    13. Constant Expressions
    14. -
    -
  12. -
  13. Other Values -
      -
    1. Inline Assembler Expressions
    2. -
    3. Metadata Nodes and Metadata Strings -
        -
      1. 'tbaa' Metadata
      2. -
      3. 'fpmath' Metadata
      4. -
      5. 'range' Metadata
      6. -
      -
    4. -
    -
  14. -
  15. Module Flags Metadata -
      -
    1. Objective-C Garbage Collection Module Flags Metadata
    2. -
    -
  16. -
  17. Intrinsic Global Variables -
      -
    1. The 'llvm.used' Global Variable
    2. -
    3. The 'llvm.compiler.used' - Global Variable
    4. -
    5. The 'llvm.global_ctors' - Global Variable
    6. -
    7. The 'llvm.global_dtors' - Global Variable
    8. -
    -
  18. -
  19. Instruction Reference -
      -
    1. Terminator Instructions -
        -
      1. 'ret' Instruction
      2. -
      3. 'br' Instruction
      4. -
      5. 'switch' Instruction
      6. -
      7. 'indirectbr' Instruction
      8. -
      9. 'invoke' Instruction
      10. -
      11. 'resume' Instruction
      12. -
      13. 'unreachable' Instruction
      14. -
      -
    2. -
    3. Binary Operations -
        -
      1. 'add' Instruction
      2. -
      3. 'fadd' Instruction
      4. -
      5. 'sub' Instruction
      6. -
      7. 'fsub' Instruction
      8. -
      9. 'mul' Instruction
      10. -
      11. 'fmul' Instruction
      12. -
      13. 'udiv' Instruction
      14. -
      15. 'sdiv' Instruction
      16. -
      17. 'fdiv' Instruction
      18. -
      19. 'urem' Instruction
      20. -
      21. 'srem' Instruction
      22. -
      23. 'frem' Instruction
      24. -
      -
    4. -
    5. Bitwise Binary Operations -
        -
      1. 'shl' Instruction
      2. -
      3. 'lshr' Instruction
      4. -
      5. 'ashr' Instruction
      6. -
      7. 'and' Instruction
      8. -
      9. 'or' Instruction
      10. -
      11. 'xor' Instruction
      12. -
      -
    6. -
    7. Vector Operations -
        -
      1. 'extractelement' Instruction
      2. -
      3. 'insertelement' Instruction
      4. -
      5. 'shufflevector' Instruction
      6. -
      -
    8. -
    9. Aggregate Operations -
        -
      1. 'extractvalue' Instruction
      2. -
      3. 'insertvalue' Instruction
      4. -
      -
    10. -
    11. Memory Access and Addressing Operations -
        -
      1. 'alloca' Instruction
      2. -
      3. 'load' Instruction
      4. -
      5. 'store' Instruction
      6. -
      7. 'fence' Instruction
      8. -
      9. 'cmpxchg' Instruction
      10. -
      11. 'atomicrmw' Instruction
      12. -
      13. 'getelementptr' Instruction
      14. -
      -
    12. -
    13. Conversion Operations -
        -
      1. 'trunc .. to' Instruction
      2. -
      3. 'zext .. to' Instruction
      4. -
      5. 'sext .. to' Instruction
      6. -
      7. 'fptrunc .. to' Instruction
      8. -
      9. 'fpext .. to' Instruction
      10. -
      11. 'fptoui .. to' Instruction
      12. -
      13. 'fptosi .. to' Instruction
      14. -
      15. 'uitofp .. to' Instruction
      16. -
      17. 'sitofp .. to' Instruction
      18. -
      19. 'ptrtoint .. to' Instruction
      20. -
      21. 'inttoptr .. to' Instruction
      22. -
      23. 'bitcast .. to' Instruction
      24. -
      -
    14. -
    15. Other Operations -
        -
      1. 'icmp' Instruction
      2. -
      3. 'fcmp' Instruction
      4. -
      5. 'phi' Instruction
      6. -
      7. 'select' Instruction
      8. -
      9. 'call' Instruction
      10. -
      11. 'va_arg' Instruction
      12. -
      13. 'landingpad' Instruction
      14. -
      -
    16. -
    -
  20. -
  21. Intrinsic Functions -
      -
    1. Variable Argument Handling Intrinsics -
        -
      1. 'llvm.va_start' Intrinsic
      2. -
      3. 'llvm.va_end' Intrinsic
      4. -
      5. 'llvm.va_copy' Intrinsic
      6. -
      -
    2. -
    3. Accurate Garbage Collection Intrinsics -
        -
      1. 'llvm.gcroot' Intrinsic
      2. -
      3. 'llvm.gcread' Intrinsic
      4. -
      5. 'llvm.gcwrite' Intrinsic
      6. -
      -
    4. -
    5. Code Generator Intrinsics -
        -
      1. 'llvm.returnaddress' Intrinsic
      2. -
      3. 'llvm.frameaddress' Intrinsic
      4. -
      5. 'llvm.stacksave' Intrinsic
      6. -
      7. 'llvm.stackrestore' Intrinsic
      8. -
      9. 'llvm.prefetch' Intrinsic
      10. -
      11. 'llvm.pcmarker' Intrinsic
      12. -
      13. 'llvm.readcyclecounter' Intrinsic
      14. -
      -
    6. -
    7. Standard C Library Intrinsics -
        -
      1. 'llvm.memcpy.*' Intrinsic
      2. -
      3. 'llvm.memmove.*' Intrinsic
      4. -
      5. 'llvm.memset.*' Intrinsic
      6. -
      7. 'llvm.sqrt.*' Intrinsic
      8. -
      9. 'llvm.powi.*' Intrinsic
      10. -
      11. 'llvm.sin.*' Intrinsic
      12. -
      13. 'llvm.cos.*' Intrinsic
      14. -
      15. 'llvm.pow.*' Intrinsic
      16. -
      17. 'llvm.exp.*' Intrinsic
      18. -
      19. 'llvm.log.*' Intrinsic
      20. -
      21. 'llvm.fma.*' Intrinsic
      22. -
      -
    8. -
    9. Bit Manipulation Intrinsics -
        -
      1. 'llvm.bswap.*' Intrinsics
      2. -
      3. 'llvm.ctpop.*' Intrinsic
      4. -
      5. 'llvm.ctlz.*' Intrinsic
      6. -
      7. 'llvm.cttz.*' Intrinsic
      8. -
      -
    10. -
    11. Arithmetic with Overflow Intrinsics -
        -
      1. 'llvm.sadd.with.overflow.* Intrinsics
      2. -
      3. 'llvm.uadd.with.overflow.* Intrinsics
      4. -
      5. 'llvm.ssub.with.overflow.* Intrinsics
      6. -
      7. 'llvm.usub.with.overflow.* Intrinsics
      8. -
      9. 'llvm.smul.with.overflow.* Intrinsics
      10. -
      11. 'llvm.umul.with.overflow.* Intrinsics
      12. -
      -
    12. -
    13. Half Precision Floating Point Intrinsics -
        -
      1. 'llvm.convert.to.fp16' Intrinsic
      2. -
      3. 'llvm.convert.from.fp16' Intrinsic
      4. -
      -
    14. -
    15. Debugger intrinsics
    16. -
    17. Exception Handling intrinsics
    18. -
    19. Trampoline Intrinsics -
        -
      1. 'llvm.init.trampoline' Intrinsic
      2. -
      3. 'llvm.adjust.trampoline' Intrinsic
      4. -
      -
    20. -
    21. Memory Use Markers -
        -
      1. 'llvm.lifetime.start' Intrinsic
      2. -
      3. 'llvm.lifetime.end' Intrinsic
      4. -
      5. 'llvm.invariant.start' Intrinsic
      6. -
      7. 'llvm.invariant.end' Intrinsic
      8. -
      -
    22. -
    23. General intrinsics -
        -
      1. - 'llvm.var.annotation' Intrinsic
      2. -
      3. - 'llvm.annotation.*' Intrinsic
      4. -
      5. - 'llvm.trap' Intrinsic
      6. -
      7. - 'llvm.stackprotector' Intrinsic
      8. -
      9. - 'llvm.objectsize' Intrinsic
      10. -
      11. - 'llvm.expect' Intrinsic
      12. -
      -
    24. -
    -
  22. -
- -
-

Written by Chris Lattner - and Vikram Adve

-
- - -

Abstract

- - -
- -

This document is a reference manual for the LLVM assembly language. LLVM is - a Static Single Assignment (SSA) based representation that provides type - safety, low-level operations, flexibility, and the capability of representing - 'all' high-level languages cleanly. It is the common code representation - used throughout all phases of the LLVM compilation strategy.

- -
- - -

Introduction

- - -
- -

The LLVM code representation is designed to be used in three different forms: - as an in-memory compiler IR, as an on-disk bitcode representation (suitable - for fast loading by a Just-In-Time compiler), and as a human readable - assembly language representation. This allows LLVM to provide a powerful - intermediate representation for efficient compiler transformations and - analysis, while providing a natural means to debug and visualize the - transformations. The three different forms of LLVM are all equivalent. This - document describes the human readable representation and notation.

- -

The LLVM representation aims to be light-weight and low-level while being - expressive, typed, and extensible at the same time. It aims to be a - "universal IR" of sorts, by being at a low enough level that high-level ideas - may be cleanly mapped to it (similar to how microprocessors are "universal - IR's", allowing many source languages to be mapped to them). By providing - type information, LLVM can be used as the target of optimizations: for - example, through pointer analysis, it can be proven that a C automatic - variable is never accessed outside of the current function, allowing it to - be promoted to a simple SSA value instead of a memory location.

- - -

- Well-Formedness -

- -
- -

It is important to note that this document describes 'well formed' LLVM - assembly language. There is a difference between what the parser accepts and - what is considered 'well formed'. For example, the following instruction is - syntactically okay, but not well formed:

- -
-%x = add i32 1, %x
-
- -

because the definition of %x does not dominate all of its uses. The - LLVM infrastructure provides a verification pass that may be used to verify - that an LLVM module is well formed. This pass is automatically run by the - parser after parsing input assembly and by the optimizer before it outputs - bitcode. The violations pointed out by the verifier pass indicate bugs in - transformation passes or input to the parser.

- -
- -
- - - - -

Identifiers

- - -
- -

LLVM identifiers come in two basic types: global and local. Global - identifiers (functions, global variables) begin with the '@' - character. Local identifiers (register names, types) begin with - the '%' character. Additionally, there are three different formats - for identifiers, for different purposes:

- -
    -
  1. Named values are represented as a string of characters with their prefix. - For example, %foo, @DivisionByZero, - %a.really.long.identifier. The actual regular expression used is - '[%@][a-zA-Z$._][a-zA-Z$._0-9]*'. Identifiers which require - other characters in their names can be surrounded with quotes. Special - characters may be escaped using "\xx" where xx is the - ASCII code for the character in hexadecimal. In this way, any character - can be used in a name value, even quotes themselves.
  2. - -
  3. Unnamed values are represented as an unsigned numeric value with their - prefix. For example, %12, @2, %44.
  4. - -
  5. Constants, which are described in a section about - constants, below.
  6. -
- -

LLVM requires that values start with a prefix for two reasons: Compilers - don't need to worry about name clashes with reserved words, and the set of - reserved words may be expanded in the future without penalty. Additionally, - unnamed identifiers allow a compiler to quickly come up with a temporary - variable without having to avoid symbol table conflicts.

- -

Reserved words in LLVM are very similar to reserved words in other - languages. There are keywords for different opcodes - ('add', - 'bitcast', - 'ret', etc...), for primitive type names - ('void', - 'i32', etc...), and others. These - reserved words cannot conflict with variable names, because none of them - start with a prefix character ('%' or '@').

- -

Here is an example of LLVM code to multiply the integer variable - '%X' by 8:

- -

The easy way:

- -
-%result = mul i32 %X, 8
-
- -

After strength reduction:

- -
-%result = shl i32 %X, i8 3
-
- -

And the hard way:

- -
-%0 = add i32 %X, %X           ; yields {i32}:%0
-%1 = add i32 %0, %0           ; yields {i32}:%1
-%result = add i32 %1, %1
-
- -

This last way of multiplying %X by 8 illustrates several important - lexical features of LLVM:

- -
    -
  1. Comments are delimited with a ';' and go until the end of - line.
  2. - -
  3. Unnamed temporaries are created when the result of a computation is not - assigned to a named value.
  4. - -
  5. Unnamed temporaries are numbered sequentially
  6. -
- -

It also shows a convention that we follow in this document. When - demonstrating instructions, we will follow an instruction with a comment that - defines the type and name of value produced. Comments are shown in italic - text.

- -
- - -

High Level Structure

- -
- -

- Module Structure -

- -
- -

LLVM programs are composed of Modules, each of which is a - translation unit of the input programs. Each module consists of functions, - global variables, and symbol table entries. Modules may be combined together - with the LLVM linker, which merges function (and global variable) - definitions, resolves forward declarations, and merges symbol table - entries. Here is an example of the "hello world" module:

- -
-; Declare the string constant as a global constant. 
-@.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" 
-
-; External declaration of the puts function 
-declare i32 @puts(i8* nocapture) nounwind 
-
-; Definition of main function
-define i32 @main() {   ; i32()*  
-  ; Convert [13 x i8]* to i8  *... 
-  %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
-
-  ; Call puts function to write out the string to stdout. 
-  call i32 @puts(i8* %cast210)
-  ret i32 0 
-}
-
-; Named metadata
-!1 = metadata !{i32 42}
-!foo = !{!1, null}
-
- -

This example is made up of a global variable named - ".str", an external declaration of the "puts" function, - a function definition for - "main" and named metadata - "foo".

- -

In general, a module is made up of a list of global values (where both - functions and global variables are global values). Global values are - represented by a pointer to a memory location (in this case, a pointer to an - array of char, and a pointer to a function), and have one of the - following linkage types.

- -
- - -

- Linkage Types -

- -
- -

All Global Variables and Functions have one of the following types of - linkage:

- -
-
private
-
Global values with "private" linkage are only directly accessible - by objects in the current module. In particular, linking code into a - module with an private global value may cause the private to be renamed as - necessary to avoid collisions. Because the symbol is private to the - module, all references can be updated. This doesn't show up in any symbol - table in the object file.
- -
linker_private
-
Similar to private, but the symbol is passed through the - assembler and evaluated by the linker. Unlike normal strong symbols, they - are removed by the linker from the final linked image (executable or - dynamic library).
- -
linker_private_weak
-
Similar to "linker_private", but the symbol is weak. Note that - linker_private_weak symbols are subject to coalescing by the - linker. The symbols are removed by the linker from the final linked image - (executable or dynamic library).
- -
linker_private_weak_def_auto
-
Similar to "linker_private_weak", but it's known that the address - of the object is not taken. For instance, functions that had an inline - definition, but the compiler decided not to inline it. Note, - unlike linker_private and linker_private_weak, - linker_private_weak_def_auto may have only default - visibility. The symbols are removed by the linker from the final linked - image (executable or dynamic library).
- -
internal
-
Similar to private, but the value shows as a local symbol - (STB_LOCAL in the case of ELF) in the object file. This - corresponds to the notion of the 'static' keyword in C.
- -
available_externally
-
Globals with "available_externally" linkage are never emitted - into the object file corresponding to the LLVM module. They exist to - allow inlining and other optimizations to take place given knowledge of - the definition of the global, which is known to be somewhere outside the - module. Globals with available_externally linkage are allowed to - be discarded at will, and are otherwise the same as linkonce_odr. - This linkage type is only allowed on definitions, not declarations.
- -
linkonce
-
Globals with "linkonce" linkage are merged with other globals of - the same name when linkage occurs. This can be used to implement - some forms of inline functions, templates, or other code which must be - generated in each translation unit that uses it, but where the body may - be overridden with a more definitive definition later. Unreferenced - linkonce globals are allowed to be discarded. Note that - linkonce linkage does not actually allow the optimizer to - inline the body of this function into callers because it doesn't know if - this definition of the function is the definitive definition within the - program or whether it will be overridden by a stronger definition. - To enable inlining and other optimizations, use "linkonce_odr" - linkage.
- -
weak
-
"weak" linkage has the same merging semantics as - linkonce linkage, except that unreferenced globals with - weak linkage may not be discarded. This is used for globals that - are declared "weak" in C source code.
- -
common
-
"common" linkage is most similar to "weak" linkage, but - they are used for tentative definitions in C, such as "int X;" at - global scope. - Symbols with "common" linkage are merged in the same way as - weak symbols, and they may not be deleted if unreferenced. - common symbols may not have an explicit section, - must have a zero initializer, and may not be marked 'constant'. Functions and aliases may not - have common linkage.
- - -
appending
-
"appending" linkage may only be applied to global variables of - pointer to array type. When two global variables with appending linkage - are linked together, the two global arrays are appended together. This is - the LLVM, typesafe, equivalent of having the system linker append together - "sections" with identical names when .o files are linked.
- -
extern_weak
-
The semantics of this linkage follow the ELF object file model: the symbol - is weak until linked, if not linked, the symbol becomes null instead of - being an undefined reference.
- -
linkonce_odr
-
weak_odr
-
Some languages allow differing globals to be merged, such as two functions - with different semantics. Other languages, such as C++, ensure - that only equivalent globals are ever merged (the "one definition rule" - — "ODR"). Such languages can use the linkonce_odr - and weak_odr linkage types to indicate that the global will only - be merged with equivalent globals. These linkage types are otherwise the - same as their non-odr versions.
- -
external
-
If none of the above identifiers are used, the global is externally - visible, meaning that it participates in linkage and can be used to - resolve external symbol references.
-
- -

The next two types of linkage are targeted for Microsoft Windows platform - only. They are designed to support importing (exporting) symbols from (to) - DLLs (Dynamic Link Libraries).

- -
-
dllimport
-
"dllimport" linkage causes the compiler to reference a function - or variable via a global pointer to a pointer that is set up by the DLL - exporting the symbol. On Microsoft Windows targets, the pointer name is - formed by combining __imp_ and the function or variable - name.
- -
dllexport
-
"dllexport" linkage causes the compiler to provide a global - pointer to a pointer in a DLL, so that it can be referenced with the - dllimport attribute. On Microsoft Windows targets, the pointer - name is formed by combining __imp_ and the function or - variable name.
-
- -

For example, since the ".LC0" variable is defined to be internal, if - another module defined a ".LC0" variable and was linked with this - one, one of the two would be renamed, preventing a collision. Since - "main" and "puts" are external (i.e., lacking any linkage - declarations), they are accessible outside of the current module.

- -

It is illegal for a function declaration to have any linkage type - other than external, dllimport - or extern_weak.

- -

Aliases can have only external, internal, weak - or weak_odr linkages.

- -
- - -

- Calling Conventions -

- -
- -

LLVM functions, calls - and invokes can all have an optional calling - convention specified for the call. The calling convention of any pair of - dynamic caller/callee must match, or the behavior of the program is - undefined. The following calling conventions are supported by LLVM, and more - may be added in the future:

- -
-
"ccc" - The C calling convention:
-
This calling convention (the default if no other calling convention is - specified) matches the target C calling conventions. This calling - convention supports varargs function calls and tolerates some mismatch in - the declared prototype and implemented declaration of the function (as - does normal C).
- -
"fastcc" - The fast calling convention:
-
This calling convention attempts to make calls as fast as possible - (e.g. by passing things in registers). This calling convention allows the - target to use whatever tricks it wants to produce fast code for the - target, without having to conform to an externally specified ABI - (Application Binary Interface). - Tail calls can only be optimized - when this or the GHC convention is used. This calling convention - does not support varargs and requires the prototype of all callees to - exactly match the prototype of the function definition.
- -
"coldcc" - The cold calling convention:
-
This calling convention attempts to make code in the caller as efficient - as possible under the assumption that the call is not commonly executed. - As such, these calls often preserve all registers so that the call does - not break any live ranges in the caller side. This calling convention - does not support varargs and requires the prototype of all callees to - exactly match the prototype of the function definition.
- -
"cc 10" - GHC convention:
-
This calling convention has been implemented specifically for use by the - Glasgow Haskell Compiler (GHC). - It passes everything in registers, going to extremes to achieve this by - disabling callee save registers. This calling convention should not be - used lightly but only for specific situations such as an alternative to - the register pinning performance technique often used when - implementing functional programming languages.At the moment only X86 - supports this convention and it has the following limitations: -
    -
  • On X86-32 only supports up to 4 bit type parameters. No - floating point types are supported.
  • -
  • On X86-64 only supports up to 10 bit type parameters and - 6 floating point parameters.
  • -
- This calling convention supports - tail call optimization but - requires both the caller and callee are using it. -
- -
"cc <n>" - Numbered convention:
-
Any calling convention may be specified by number, allowing - target-specific calling conventions to be used. Target specific calling - conventions start at 64.
-
- -

More calling conventions can be added/defined on an as-needed basis, to - support Pascal conventions or any other well-known target-independent - convention.

- -
- - -

- Visibility Styles -

- -
- -

All Global Variables and Functions have one of the following visibility - styles:

- -
-
"default" - Default style:
-
On targets that use the ELF object file format, default visibility means - that the declaration is visible to other modules and, in shared libraries, - means that the declared entity may be overridden. On Darwin, default - visibility means that the declaration is visible to other modules. Default - visibility corresponds to "external linkage" in the language.
- -
"hidden" - Hidden style:
-
Two declarations of an object with hidden visibility refer to the same - object if they are in the same shared object. Usually, hidden visibility - indicates that the symbol will not be placed into the dynamic symbol - table, so no other module (executable or shared library) can reference it - directly.
- -
"protected" - Protected style:
-
On ELF, protected visibility indicates that the symbol will be placed in - the dynamic symbol table, but that references within the defining module - will bind to the local symbol. That is, the symbol cannot be overridden by - another module.
-
- -
- - -

- Named Types -

- -
- -

LLVM IR allows you to specify name aliases for certain types. This can make - it easier to read the IR and make the IR more condensed (particularly when - recursive types are involved). An example of a name specification is:

- -
-%mytype = type { %mytype*, i32 }
-
- -

You may give a name to any type except - "void". Type name aliases may be used anywhere a type - is expected with the syntax "%mytype".

- -

Note that type names are aliases for the structural type that they indicate, - and that you can therefore specify multiple names for the same type. This - often leads to confusing behavior when dumping out a .ll file. Since LLVM IR - uses structural typing, the name is not part of the type. When printing out - LLVM IR, the printer will pick one name to render all types of a - particular shape. This means that if you have code where two different - source types end up having the same LLVM type, that the dumper will sometimes - print the "wrong" or unexpected type. This is an important design point and - isn't going to change.

- -
- - -

- Global Variables -

- -
- -

Global variables define regions of memory allocated at compilation time - instead of run-time. Global variables may optionally be initialized, may - have an explicit section to be placed in, and may have an optional explicit - alignment specified. A variable may be defined as "thread_local", which - means that it will not be shared by threads (each thread will have a - separated copy of the variable). A variable may be defined as a global - "constant," which indicates that the contents of the variable - will never be modified (enabling better optimization, allowing the - global data to be placed in the read-only section of an executable, etc). - Note that variables that need runtime initialization cannot be marked - "constant" as there is a store to the variable.

- -

LLVM explicitly allows declarations of global variables to be marked - constant, even if the final definition of the global is not. This capability - can be used to enable slightly better optimization of the program, but - requires the language definition to guarantee that optimizations based on the - 'constantness' are valid for the translation units that do not include the - definition.

- -

As SSA values, global variables define pointer values that are in scope - (i.e. they dominate) all basic blocks in the program. Global variables - always define a pointer to their "content" type because they describe a - region of memory, and all memory objects in LLVM are accessed through - pointers.

- -

Global variables can be marked with unnamed_addr which indicates - that the address is not significant, only the content. Constants marked - like this can be merged with other constants if they have the same - initializer. Note that a constant with significant address can - be merged with a unnamed_addr constant, the result being a - constant whose address is significant.

- -

A global variable may be declared to reside in a target-specific numbered - address space. For targets that support them, address spaces may affect how - optimizations are performed and/or what target instructions are used to - access the variable. The default address space is zero. The address space - qualifier must precede any other attributes.

- -

LLVM allows an explicit section to be specified for globals. If the target - supports it, it will emit globals to the section specified.

- -

An explicit alignment may be specified for a global, which must be a power - of 2. If not present, or if the alignment is set to zero, the alignment of - the global is set by the target to whatever it feels convenient. If an - explicit alignment is specified, the global is forced to have exactly that - alignment. Targets and optimizers are not allowed to over-align the global - if the global has an assigned section. In this case, the extra alignment - could be observable: for example, code could assume that the globals are - densely packed in their section and try to iterate over them as an array, - alignment padding would break this iteration.

- -

For example, the following defines a global in a numbered address space with - an initializer, section, and alignment:

- -
-@G = addrspace(5) constant float 1.0, section "foo", align 4
-
- -
- - - -

- Functions -

- -
- -

LLVM function definitions consist of the "define" keyword, an - optional linkage type, an optional - visibility style, an optional - calling convention, - an optional unnamed_addr attribute, a return type, an optional - parameter attribute for the return type, a function - name, a (possibly empty) argument list (each with optional - parameter attributes), optional - function attributes, an optional section, an optional - alignment, an optional garbage collector name, an opening - curly brace, a list of basic blocks, and a closing curly brace.

- -

LLVM function declarations consist of the "declare" keyword, an - optional linkage type, an optional - visibility style, an optional - calling convention, - an optional unnamed_addr attribute, a return type, an optional - parameter attribute for the return type, a function - name, a possibly empty list of arguments, an optional alignment, and an - optional garbage collector name.

- -

A function definition contains a list of basic blocks, forming the CFG - (Control Flow Graph) for the function. Each basic block may optionally start - with a label (giving the basic block a symbol table entry), contains a list - of instructions, and ends with a terminator - instruction (such as a branch or function return).

- -

The first basic block in a function is special in two ways: it is immediately - executed on entrance to the function, and it is not allowed to have - predecessor basic blocks (i.e. there can not be any branches to the entry - block of a function). Because the block can have no predecessors, it also - cannot have any PHI nodes.

- -

LLVM allows an explicit section to be specified for functions. If the target - supports it, it will emit functions to the section specified.

- -

An explicit alignment may be specified for a function. If not present, or if - the alignment is set to zero, the alignment of the function is set by the - target to whatever it feels convenient. If an explicit alignment is - specified, the function is forced to have at least that much alignment. All - alignments must be a power of 2.

- -

If the unnamed_addr attribute is given, the address is know to not - be significant and two identical functions can be merged.

- -
Syntax:
-
-define [linkage] [visibility]
-       [cconv] [ret attrs]
-       <ResultType> @<FunctionName> ([argument list])
-       [fn Attrs] [section "name"] [align N]
-       [gc] { ... }
-
- -
- - -

- Aliases -

- -
- -

Aliases act as "second name" for the aliasee value (which can be either - function, global variable, another alias or bitcast of global value). Aliases - may have an optional linkage type, and an - optional visibility style.

- -
Syntax:
-
-@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
-
- -
- - -

- Named Metadata -

- -
- -

Named metadata is a collection of metadata. Metadata - nodes (but not metadata strings) are the only valid operands for - a named metadata.

- -
Syntax:
-
-; Some unnamed metadata nodes, which are referenced by the named metadata.
-!0 = metadata !{metadata !"zero"}
-!1 = metadata !{metadata !"one"}
-!2 = metadata !{metadata !"two"}
-; A named metadata.
-!name = !{!0, !1, !2}
-
- -
- - -

- Parameter Attributes -

- -
- -

The return type and each parameter of a function type may have a set of - parameter attributes associated with them. Parameter attributes are - used to communicate additional information about the result or parameters of - a function. Parameter attributes are considered to be part of the function, - not of the function type, so functions with different parameter attributes - can have the same function type.

- -

Parameter attributes are simple keywords that follow the type specified. If - multiple parameter attributes are needed, they are space separated. For - example:

- -
-declare i32 @printf(i8* noalias nocapture, ...)
-declare i32 @atoi(i8 zeroext)
-declare signext i8 @returns_signed_char()
-
- -

Note that any attributes for the function result (nounwind, - readonly) come immediately after the argument list.

- -

Currently, only the following parameter attributes are defined:

- -
-
zeroext
-
This indicates to the code generator that the parameter or return value - should be zero-extended to the extent required by the target's ABI (which - is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a - parameter) or the callee (for a return value).
- -
signext
-
This indicates to the code generator that the parameter or return value - should be sign-extended to the extent required by the target's ABI (which - is usually 32-bits) by the caller (for a parameter) or the callee (for a - return value).
- -
inreg
-
This indicates that this parameter or return value should be treated in a - special target-dependent fashion during while emitting code for a function - call or return (usually, by putting it in a register as opposed to memory, - though some targets use it to distinguish between two different kinds of - registers). Use of this attribute is target-specific.
- -
byval
-

This indicates that the pointer parameter should really be passed by - value to the function. The attribute implies that a hidden copy of the - pointee - is made between the caller and the callee, so the callee is unable to - modify the value in the callee. This attribute is only valid on LLVM - pointer arguments. It is generally used to pass structs and arrays by - value, but is also valid on pointers to scalars. The copy is considered - to belong to the caller not the callee (for example, - readonly functions should not write to - byval parameters). This is not a valid attribute for return - values.

- -

The byval attribute also supports specifying an alignment with - the align attribute. It indicates the alignment of the stack slot to - form and the known alignment of the pointer specified to the call site. If - the alignment is not specified, then the code generator makes a - target-specific assumption.

- -
sret
-
This indicates that the pointer parameter specifies the address of a - structure that is the return value of the function in the source program. - This pointer must be guaranteed by the caller to be valid: loads and - stores to the structure may be assumed by the callee to not to trap. This - may only be applied to the first parameter. This is not a valid attribute - for return values.
- -
noalias
-
This indicates that pointer values - based on the argument or return - value do not alias pointer values which are not based on it, - ignoring certain "irrelevant" dependencies. - For a call to the parent function, dependencies between memory - references from before or after the call and from those during the call - are "irrelevant" to the noalias keyword for the arguments and - return value used in that call. - The caller shares the responsibility with the callee for ensuring that - these requirements are met. - For further details, please see the discussion of the NoAlias response in - alias analysis.
-
- Note that this definition of noalias is intentionally - similar to the definition of restrict in C99 for function - arguments, though it is slightly weaker. -
- For function return values, C99's restrict is not meaningful, - while LLVM's noalias is. -
- -
nocapture
-
This indicates that the callee does not make any copies of the pointer - that outlive the callee itself. This is not a valid attribute for return - values.
- -
nest
-
This indicates that the pointer parameter can be excised using the - trampoline intrinsics. This is not a valid - attribute for return values.
-
- -
- - -

- Garbage Collector Names -

- -
- -

Each function may specify a garbage collector name, which is simply a - string:

- -
-define void @f() gc "name" { ... }
-
- -

The compiler declares the supported values of name. Specifying a - collector which will cause the compiler to alter its output in order to - support the named garbage collection algorithm.

- -
- - -

- Function Attributes -

- -
- -

Function attributes are set to communicate additional information about a - function. Function attributes are considered to be part of the function, not - of the function type, so functions with different parameter attributes can - have the same function type.

- -

Function attributes are simple keywords that follow the type specified. If - multiple attributes are needed, they are space separated. For example:

- -
-define void @f() noinline { ... }
-define void @f() alwaysinline { ... }
-define void @f() alwaysinline optsize { ... }
-define void @f() optsize { ... }
-
- -
-
address_safety
-
This attribute indicates that the address safety analysis - is enabled for this function.
- -
alignstack(<n>)
-
This attribute indicates that, when emitting the prologue and epilogue, - the backend should forcibly align the stack pointer. Specify the - desired alignment, which must be a power of two, in parentheses. - -
alwaysinline
-
This attribute indicates that the inliner should attempt to inline this - function into callers whenever possible, ignoring any active inlining size - threshold for this caller.
- -
nonlazybind
-
This attribute suppresses lazy symbol binding for the function. This - may make calls to the function faster, at the cost of extra program - startup time if the function is not called during program startup.
- -
inlinehint
-
This attribute indicates that the source code contained a hint that inlining - this function is desirable (such as the "inline" keyword in C/C++). It - is just a hint; it imposes no requirements on the inliner.
- -
naked
-
This attribute disables prologue / epilogue emission for the function. - This can have very system-specific consequences.
- -
noimplicitfloat
-
This attributes disables implicit floating point instructions.
- -
noinline
-
This attribute indicates that the inliner should never inline this - function in any situation. This attribute may not be used together with - the alwaysinline attribute.
- -
noredzone
-
This attribute indicates that the code generator should not use a red - zone, even if the target-specific ABI normally permits it.
- -
noreturn
-
This function attribute indicates that the function never returns - normally. This produces undefined behavior at runtime if the function - ever does dynamically return.
- -
nounwind
-
This function attribute indicates that the function never returns with an - unwind or exceptional control flow. If the function does unwind, its - runtime behavior is undefined.
- -
optsize
-
This attribute suggests that optimization passes and code generator passes - make choices that keep the code size of this function low, and otherwise - do optimizations specifically to reduce code size.
- -
readnone
-
This attribute indicates that the function computes its result (or decides - to unwind an exception) based strictly on its arguments, without - dereferencing any pointer arguments or otherwise accessing any mutable - state (e.g. memory, control registers, etc) visible to caller functions. - It does not write through any pointer arguments - (including byval arguments) and never - changes any state visible to callers. This means that it cannot unwind - exceptions by calling the C++ exception throwing methods.
- -
readonly
-
This attribute indicates that the function does not write through any - pointer arguments (including byval - arguments) or otherwise modify any state (e.g. memory, control registers, - etc) visible to caller functions. It may dereference pointer arguments - and read state that may be set in the caller. A readonly function always - returns the same value (or unwinds an exception identically) when called - with the same set of arguments and global state. It cannot unwind an - exception by calling the C++ exception throwing methods.
- -
returns_twice
-
This attribute indicates that this function can return twice. The - C setjmp is an example of such a function. The compiler - disables some optimizations (like tail calls) in the caller of these - functions.
- -
ssp
-
This attribute indicates that the function should emit a stack smashing - protector. It is in the form of a "canary"—a random value placed on - the stack before the local variables that's checked upon return from the - function to see if it has been overwritten. A heuristic is used to - determine if a function needs stack protectors or not.
-
- If a function that has an ssp attribute is inlined into a - function that doesn't have an ssp attribute, then the resulting - function will have an ssp attribute.
- -
sspreq
-
This attribute indicates that the function should always emit a - stack smashing protector. This overrides - the ssp function attribute.
-
- If a function that has an sspreq attribute is inlined into a - function that doesn't have an sspreq attribute or which has - an ssp attribute, then the resulting function will have - an sspreq attribute.
- -
uwtable
-
This attribute indicates that the ABI being targeted requires that - an unwind table entry be produce for this function even if we can - show that no exceptions passes by it. This is normally the case for - the ELF x86-64 abi, but it can be disabled for some compilation - units.
-
- -
- - -

- Module-Level Inline Assembly -

- -
- -

Modules may contain "module-level inline asm" blocks, which corresponds to - the GCC "file scope inline asm" blocks. These blocks are internally - concatenated by LLVM and treated as a single unit, but may be separated in - the .ll file if desired. The syntax is very simple:

- -
-module asm "inline asm code goes here"
-module asm "more can go here"
-
- -

The strings can contain any character by escaping non-printable characters. - The escape sequence used is simply "\xx" where "xx" is the two digit hex code - for the number.

- -

The inline asm code is simply printed to the machine code .s file when - assembly code is generated.

- -
- - -

- Data Layout -

- -
- -

A module may specify a target specific data layout string that specifies how - data is to be laid out in memory. The syntax for the data layout is - simply:

- -
-target datalayout = "layout specification"
-
- -

The layout specification consists of a list of specifications - separated by the minus sign character ('-'). Each specification starts with - a letter and may include other information after the letter to define some - aspect of the data layout. The specifications accepted are as follows:

- -
-
E
-
Specifies that the target lays out data in big-endian form. That is, the - bits with the most significance have the lowest address location.
- -
e
-
Specifies that the target lays out data in little-endian form. That is, - the bits with the least significance have the lowest address - location.
- -
Ssize
-
Specifies the natural alignment of the stack in bits. Alignment promotion - of stack variables is limited to the natural stack alignment to avoid - dynamic stack realignment. The stack alignment must be a multiple of - 8-bits. If omitted, the natural stack alignment defaults to "unspecified", - which does not prevent any alignment promotions.
- -
p:size:abi:pref
-
This specifies the size of a pointer and its abi and - preferred alignments. All sizes are in bits. Specifying - the pref alignment is optional. If omitted, the - preceding : should be omitted too.
- -
isize:abi:pref
-
This specifies the alignment for an integer type of a given bit - size. The value of size must be in the range [1,2^23).
- -
vsize:abi:pref
-
This specifies the alignment for a vector type of a given bit - size.
- -
fsize:abi:pref
-
This specifies the alignment for a floating point type of a given bit - size. Only values of size that are supported by the target - will work. 32 (float) and 64 (double) are supported on all targets; - 80 or 128 (different flavors of long double) are also supported on some - targets. - -
asize:abi:pref
-
This specifies the alignment for an aggregate type of a given bit - size.
- -
ssize:abi:pref
-
This specifies the alignment for a stack object of a given bit - size.
- -
nsize1:size2:size3...
-
This specifies a set of native integer widths for the target CPU - in bits. For example, it might contain "n32" for 32-bit PowerPC, - "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64. Elements of - this set are considered to support most general arithmetic - operations efficiently.
-
- -

When constructing the data layout for a given target, LLVM starts with a - default set of specifications which are then (possibly) overridden by the - specifications in the datalayout keyword. The default specifications - are given in this list:

- -
    -
  • E - big endian
  • -
  • p:64:64:64 - 64-bit pointers with 64-bit alignment
  • -
  • i1:8:8 - i1 is 8-bit (byte) aligned
  • -
  • i8:8:8 - i8 is 8-bit (byte) aligned
  • -
  • i16:16:16 - i16 is 16-bit aligned
  • -
  • i32:32:32 - i32 is 32-bit aligned
  • -
  • i64:32:64 - i64 has ABI alignment of 32-bits but preferred - alignment of 64-bits
  • -
  • f32:32:32 - float is 32-bit aligned
  • -
  • f64:64:64 - double is 64-bit aligned
  • -
  • v64:64:64 - 64-bit vector is 64-bit aligned
  • -
  • v128:128:128 - 128-bit vector is 128-bit aligned
  • -
  • a0:0:1 - aggregates are 8-bit aligned
  • -
  • s0:64:64 - stack objects are 64-bit aligned
  • -
- -

When LLVM is determining the alignment for a given type, it uses the - following rules:

- -
    -
  1. If the type sought is an exact match for one of the specifications, that - specification is used.
  2. - -
  3. If no match is found, and the type sought is an integer type, then the - smallest integer type that is larger than the bitwidth of the sought type - is used. If none of the specifications are larger than the bitwidth then - the the largest integer type is used. For example, given the default - specifications above, the i7 type will use the alignment of i8 (next - largest) while both i65 and i256 will use the alignment of i64 (largest - specified).
  4. - -
  5. If no match is found, and the type sought is a vector type, then the - largest vector type that is smaller than the sought vector type will be - used as a fall back. This happens because <128 x double> can be - implemented in terms of 64 <2 x double>, for example.
  6. -
- -

The function of the data layout string may not be what you expect. Notably, - this is not a specification from the frontend of what alignment the code - generator should use.

- -

Instead, if specified, the target data layout is required to match what the - ultimate code generator expects. This string is used by the - mid-level optimizers to - improve code, and this only works if it matches what the ultimate code - generator uses. If you would like to generate IR that does not embed this - target-specific detail into the IR, then you don't have to specify the - string. This will disable some optimizations that require precise layout - information, but this also prevents those optimizations from introducing - target specificity into the IR.

- - - -
- - -

- Pointer Aliasing Rules -

- -
- -

Any memory access must be done through a pointer value associated -with an address range of the memory access, otherwise the behavior -is undefined. Pointer values are associated with address ranges -according to the following rules:

- -
    -
  • A pointer value is associated with the addresses associated with - any value it is based on. -
  • An address of a global variable is associated with the address - range of the variable's storage.
  • -
  • The result value of an allocation instruction is associated with - the address range of the allocated storage.
  • -
  • A null pointer in the default address-space is associated with - no address.
  • -
  • An integer constant other than zero or a pointer value returned - from a function not defined within LLVM may be associated with address - ranges allocated through mechanisms other than those provided by - LLVM. Such ranges shall not overlap with any ranges of addresses - allocated by mechanisms provided by LLVM.
  • -
- -

A pointer value is based on another pointer value according - to the following rules:

- -
    -
  • A pointer value formed from a - getelementptr operation - is based on the first operand of the getelementptr.
  • -
  • The result value of a - bitcast is based on the operand - of the bitcast.
  • -
  • A pointer value formed by an - inttoptr is based on all - pointer values that contribute (directly or indirectly) to the - computation of the pointer's value.
  • -
  • The "based on" relationship is transitive.
  • -
- -

Note that this definition of "based" is intentionally - similar to the definition of "based" in C99, though it is - slightly weaker.

- -

LLVM IR does not associate types with memory. The result type of a -load merely indicates the size and -alignment of the memory from which to load, as well as the -interpretation of the value. The first operand type of a -store similarly only indicates the size -and alignment of the store.

- -

Consequently, type-based alias analysis, aka TBAA, aka --fstrict-aliasing, is not applicable to general unadorned -LLVM IR. Metadata may be used to encode -additional information which specialized optimization passes may use -to implement type-based alias analysis.

- -
- - -

- Volatile Memory Accesses -

- -
- -

Certain memory accesses, such as loads, stores, and llvm.memcpys may be marked volatile. -The optimizers must not change the number of volatile operations or change their -order of execution relative to other volatile operations. The optimizers -may change the order of volatile operations relative to non-volatile -operations. This is not Java's "volatile" and has no cross-thread -synchronization behavior.

- -
- - -

- Memory Model for Concurrent Operations -

- -
- -

The LLVM IR does not define any way to start parallel threads of execution -or to register signal handlers. Nonetheless, there are platform-specific -ways to create them, and we define LLVM IR's behavior in their presence. This -model is inspired by the C++0x memory model.

- -

For a more informal introduction to this model, see the -LLVM Atomic Instructions and Concurrency Guide. - -

We define a happens-before partial order as the least partial order -that

-
    -
  • Is a superset of single-thread program order, and
  • -
  • When a synchronizes-with b, includes an edge from - a to b. Synchronizes-with pairs are introduced - by platform-specific techniques, like pthread locks, thread - creation, thread joining, etc., and by atomic instructions. - (See also Atomic Memory Ordering Constraints). -
  • -
- -

Note that program order does not introduce happens-before edges -between a thread and signals executing inside that thread.

- -

Every (defined) read operation (load instructions, memcpy, atomic -loads/read-modify-writes, etc.) R reads a series of bytes written by -(defined) write operations (store instructions, atomic -stores/read-modify-writes, memcpy, etc.). For the purposes of this section, -initialized globals are considered to have a write of the initializer which is -atomic and happens before any other read or write of the memory in question. -For each byte of a read R, Rbyte may see -any write to the same byte, except:

- -
    -
  • If write1 happens before - write2, and write2 happens - before Rbyte, then Rbyte - does not see write1. -
  • If Rbyte happens before - write3, then Rbyte does not - see write3. -
- -

Given that definition, Rbyte is defined as follows: -

    -
  • If R is volatile, the result is target-dependent. (Volatile - is supposed to give guarantees which can support - sig_atomic_t in C/C++, and may be used for accesses to - addresses which do not behave like normal memory. It does not generally - provide cross-thread synchronization.) -
  • Otherwise, if there is no write to the same byte that happens before - Rbyte, Rbyte returns - undef for that byte. -
  • Otherwise, if Rbyte may see exactly one write, - Rbyte returns the value written by that - write.
  • -
  • Otherwise, if R is atomic, and all the writes - Rbyte may see are atomic, it chooses one of the - values written. See the Atomic Memory Ordering - Constraints section for additional constraints on how the choice - is made. -
  • Otherwise Rbyte returns undef.
  • -
- -

R returns the value composed of the series of bytes it read. -This implies that some bytes within the value may be undef -without the entire value being undef. Note that this only -defines the semantics of the operation; it doesn't mean that targets will -emit more than one instruction to read the series of bytes.

- -

Note that in cases where none of the atomic intrinsics are used, this model -places only one restriction on IR transformations on top of what is required -for single-threaded execution: introducing a store to a byte which might not -otherwise be stored is not allowed in general. (Specifically, in the case -where another thread might write to and read from an address, introducing a -store can change a load that may see exactly one write into a load that may -see multiple writes.)

- - - -
- - -

- Atomic Memory Ordering Constraints -

- -
- -

Atomic instructions (cmpxchg, -atomicrmw, -fence, -atomic load, and -atomic store) take an ordering parameter -that determines which other atomic instructions on the same address they -synchronize with. These semantics are borrowed from Java and C++0x, -but are somewhat more colloquial. If these descriptions aren't precise enough, -check those specs (see spec references in the -atomics guide). -fence instructions -treat these orderings somewhat differently since they don't take an address. -See that instruction's documentation for details.

- -

For a simpler introduction to the ordering constraints, see the -LLVM Atomic Instructions and Concurrency Guide.

- -
-
unordered
-
The set of values that can be read is governed by the happens-before -partial order. A value cannot be read unless some operation wrote it. -This is intended to provide a guarantee strong enough to model Java's -non-volatile shared variables. This ordering cannot be specified for -read-modify-write operations; it is not strong enough to make them atomic -in any interesting way.
-
monotonic
-
In addition to the guarantees of unordered, there is a single -total order for modifications by monotonic operations on each -address. All modification orders must be compatible with the happens-before -order. There is no guarantee that the modification orders can be combined to -a global total order for the whole program (and this often will not be -possible). The read in an atomic read-modify-write operation -(cmpxchg and -atomicrmw) -reads the value in the modification order immediately before the value it -writes. If one atomic read happens before another atomic read of the same -address, the later read must see the same value or a later value in the -address's modification order. This disallows reordering of -monotonic (or stronger) operations on the same address. If an -address is written monotonically by one thread, and other threads -monotonically read that address repeatedly, the other threads must -eventually see the write. This corresponds to the C++0x/C1x -memory_order_relaxed.
-
acquire
-
In addition to the guarantees of monotonic, -a synchronizes-with edge may be formed with a release -operation. This is intended to model C++'s memory_order_acquire.
-
release
-
In addition to the guarantees of monotonic, if this operation -writes a value which is subsequently read by an acquire operation, -it synchronizes-with that operation. (This isn't a complete -description; see the C++0x definition of a release sequence.) This corresponds -to the C++0x/C1x memory_order_release.
-
acq_rel (acquire+release)
Acts as both an -acquire and release operation on its address. -This corresponds to the C++0x/C1x memory_order_acq_rel.
-
seq_cst (sequentially consistent)
-
In addition to the guarantees of acq_rel -(acquire for an operation which only reads, release -for an operation which only writes), there is a global total order on all -sequentially-consistent operations on all addresses, which is consistent with -the happens-before partial order and with the modification orders of -all the affected addresses. Each sequentially-consistent read sees the last -preceding write to the same address in this global order. This corresponds -to the C++0x/C1x memory_order_seq_cst and Java volatile.
-
- -

If an atomic operation is marked singlethread, -it only synchronizes with or participates in modification and seq_cst -total orderings with other operations running in the same thread (for example, -in signal handlers).

- -
- -
- - -

Type System

- - -
- -

The LLVM type system is one of the most important features of the - intermediate representation. Being typed enables a number of optimizations - to be performed on the intermediate representation directly, without having - to do extra analyses on the side before the transformation. A strong type - system makes it easier to read the generated code and enables novel analyses - and transformations that are not feasible to perform on normal three address - code representations.

- - -

- Type Classifications -

- -
- -

The types fall into a few useful classifications:

- - - - - - - - - - - - - - - - - - - - - - - - - -
ClassificationTypes
integeri1, i2, i3, ... i8, ... i16, ... i32, ... i64, ...
floating pointhalf, float, double, x86_fp80, fp128, ppc_fp128
first classinteger, - floating point, - pointer, - vector, - structure, - array, - label, - metadata. -
primitivelabel, - void, - integer, - floating point, - x86mmx, - metadata.
derivedarray, - function, - pointer, - structure, - vector, - opaque. -
- -

The first class types are perhaps the most - important. Values of these types are the only ones which can be produced by - instructions.

- -
- - -

- Primitive Types -

- -
- -

The primitive types are the fundamental building blocks of the LLVM - system.

- - -

- Integer Type -

- -
- -
Overview:
-

The integer type is a very simple type that simply specifies an arbitrary - bit width for the integer type desired. Any bit width from 1 bit to - 223-1 (about 8 million) can be specified.

- -
Syntax:
-
-  iN
-
- -

The number of bits the integer will occupy is specified by the N - value.

- -
Examples:
- - - - - - - - - - - - - -
i1a single-bit integer.
i32a 32-bit integer.
i1942652a really big integer of over 1 million bits.
- -
- - -

- Floating Point Types -

- -
- - - - - - - - - - - -
TypeDescription
half16-bit floating point value
float32-bit floating point value
double64-bit floating point value
fp128128-bit floating point value (112-bit mantissa)
x86_fp8080-bit floating point value (X87)
ppc_fp128128-bit floating point value (two 64-bits)
- -
- - -

- X86mmx Type -

- -
- -
Overview:
-

The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.

- -
Syntax:
-
-  x86mmx
-
- -
- - -

- Void Type -

- -
- -
Overview:
-

The void type does not represent any value and has no size.

- -
Syntax:
-
-  void
-
- -
- - -

- Label Type -

- -
- -
Overview:
-

The label type represents code labels.

- -
Syntax:
-
-  label
-
- -
- - -

- Metadata Type -

- -
- -
Overview:
-

The metadata type represents embedded metadata. No derived types may be - created from metadata except for function - arguments. - -

Syntax:
-
-  metadata
-
- -
- -
- - -

- Derived Types -

- -
- -

The real power in LLVM comes from the derived types in the system. This is - what allows a programmer to represent arrays, functions, pointers, and other - useful types. Each of these types contain one or more element types which - may be a primitive type, or another derived type. For example, it is - possible to have a two dimensional array, using an array as the element type - of another array.

- - -

- Aggregate Types -

- -
- -

Aggregate Types are a subset of derived types that can contain multiple - member types. Arrays and - structs are aggregate types. - Vectors are not considered to be aggregate types.

- -
- - -

- Array Type -

- -
- -
Overview:
-

The array type is a very simple derived type that arranges elements - sequentially in memory. The array type requires a size (number of elements) - and an underlying data type.

- -
Syntax:
-
-  [<# elements> x <elementtype>]
-
- -

The number of elements is a constant integer value; elementtype may - be any type with a size.

- -
Examples:
- - - - - - - - - - - - - -
[40 x i32]Array of 40 32-bit integer values.
[41 x i32]Array of 41 32-bit integer values.
[4 x i8]Array of 4 8-bit integer values.
-

Here are some examples of multidimensional arrays:

- - - - - - - - - - - - - -
[3 x [4 x i32]]3x4 array of 32-bit integer values.
[12 x [10 x float]]12x10 array of single precision floating point values.
[2 x [3 x [4 x i16]]]2x3x4 array of 16-bit integer values.
- -

There is no restriction on indexing beyond the end of the array implied by - a static type (though there are restrictions on indexing beyond the bounds - of an allocated object in some cases). This means that single-dimension - 'variable sized array' addressing can be implemented in LLVM with a zero - length array type. An implementation of 'pascal style arrays' in LLVM could - use the type "{ i32, [0 x float]}", for example.

- -
- - -

- Function Type -

- -
- -
Overview:
-

The function type can be thought of as a function signature. It consists of - a return type and a list of formal parameter types. The return type of a - function type is a first class type or a void type.

- -
Syntax:
-
-  <returntype> (<parameter list>)
-
- -

...where '<parameter list>' is a comma-separated list of type - specifiers. Optionally, the parameter list may include a type ..., - which indicates that the function takes a variable number of arguments. - Variable argument functions can access their arguments with - the variable argument handling intrinsic - functions. '<returntype>' is any type except - label.

- -
Examples:
- - - - - - - - - - - - - - -
i32 (i32)function taking an i32, returning an i32 -
float (i16, i32 *) * - Pointer to a function that takes - an i16 and a pointer to i32, - returning float. -
i32 (i8*, ...)A vararg function that takes at least one - pointer to i8 (char in C), - which returns an integer. This is the signature for printf in - LLVM. -
{i32, i32} (i32)A function taking an i32, returning a - structure containing two i32 values -
- -
- - -

- Structure Type -

- -
- -
Overview:
-

The structure type is used to represent a collection of data members together - in memory. The elements of a structure may be any type that has a size.

- -

Structures in memory are accessed using 'load' - and 'store' by getting a pointer to a field - with the 'getelementptr' instruction. - Structures in registers are accessed using the - 'extractvalue' and - 'insertvalue' instructions.

- -

Structures may optionally be "packed" structures, which indicate that the - alignment of the struct is one byte, and that there is no padding between - the elements. In non-packed structs, padding between field types is inserted - as defined by the TargetData string in the module, which is required to match - what the underlying code generator expects.

- -

Structures can either be "literal" or "identified". A literal structure is - defined inline with other types (e.g. {i32, i32}*) whereas identified - types are always defined at the top level with a name. Literal types are - uniqued by their contents and can never be recursive or opaque since there is - no way to write one. Identified types can be recursive, can be opaqued, and are - never uniqued. -

- -
Syntax:
-
-  %T1 = type { <type list> }     ; Identified normal struct type
-  %T2 = type <{ <type list> }>   ; Identified packed struct type
-
- -
Examples:
- - - - - - - - - - - - - -
{ i32, i32, i32 }A triple of three i32 values
{ float, i32 (i32) * }A pair, where the first element is a float and the - second element is a pointer to a - function that takes an i32, returning - an i32.
<{ i8, i32 }>A packed struct known to be 5 bytes in size.
- -
- - -

- Opaque Structure Types -

- -
- -
Overview:
-

Opaque structure types are used to represent named structure types that do - not have a body specified. This corresponds (for example) to the C notion of - a forward declared structure.

- -
Syntax:
-
-  %X = type opaque
-  %52 = type opaque
-
- -
Examples:
- - - - - -
opaqueAn opaque type.
- -
- - - - -

- Pointer Type -

- -
- -
Overview:
-

The pointer type is used to specify memory locations. - Pointers are commonly used to reference objects in memory.

- -

Pointer types may have an optional address space attribute defining the - numbered address space where the pointed-to object resides. The default - address space is number zero. The semantics of non-zero address - spaces are target-specific.

- -

Note that LLVM does not permit pointers to void (void*) nor does it - permit pointers to labels (label*). Use i8* instead.

- -
Syntax:
-
-  <type> *
-
- -
Examples:
- - - - - - - - - - - - - -
[4 x i32]*A pointer to array of four i32 values.
i32 (i32*) * A pointer to a function that takes an i32*, returning an - i32.
i32 addrspace(5)*A pointer to an i32 value - that resides in address space #5.
- -
- - -

- Vector Type -

- -
- -
Overview:
-

A vector type is a simple derived type that represents a vector of elements. - Vector types are used when multiple primitive data are operated in parallel - using a single instruction (SIMD). A vector type requires a size (number of - elements) and an underlying primitive data type. Vector types are considered - first class.

- -
Syntax:
-
-  < <# elements> x <elementtype> >
-
- -

The number of elements is a constant integer value larger than 0; elementtype - may be any integer or floating point type, or a pointer to these types. - Vectors of size zero are not allowed.

- -
Examples:
- - - - - - - - - - - - - - - - - -
<4 x i32>Vector of 4 32-bit integer values.
<8 x float>Vector of 8 32-bit floating-point values.
<2 x i64>Vector of 2 64-bit integer values.
<4 x i64*>Vector of 4 pointers to 64-bit integer values.
- -
- -
- -
- - -

Constants

- - -
- -

LLVM has several different basic types of constants. This section describes - them all and their syntax.

- - -

- Simple Constants -

- -
- -
-
Boolean constants
-
The two strings 'true' and 'false' are both valid - constants of the i1 type.
- -
Integer constants
-
Standard integers (such as '4') are constants of - the integer type. Negative numbers may be used - with integer types.
- -
Floating point constants
-
Floating point constants use standard decimal notation (e.g. 123.421), - exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal - notation (see below). The assembler requires the exact decimal value of a - floating-point constant. For example, the assembler accepts 1.25 but - rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point - constants must have a floating point type.
- -
Null pointer constants
-
The identifier 'null' is recognized as a null pointer constant - and must be of pointer type.
-
- -

The one non-intuitive notation for constants is the hexadecimal form of - floating point constants. For example, the form 'double - 0x432ff973cafa8000' is equivalent to (but harder to read than) - 'double 4.5e+15'. The only time hexadecimal floating point - constants are required (and the only time that they are generated by the - disassembler) is when a floating point constant must be emitted but it cannot - be represented as a decimal floating point number in a reasonable number of - digits. For example, NaN's, infinities, and other special values are - represented in their IEEE hexadecimal format so that assembly and disassembly - do not cause any bits to change in the constants.

- -

When using the hexadecimal form, constants of types half, float, and double are - represented using the 16-digit form shown above (which matches the IEEE754 - representation for double); half and float values must, however, be exactly - representable as IEE754 half and single precision, respectively. - Hexadecimal format is always used - for long double, and there are three forms of long double. The 80-bit format - used by x86 is represented as 0xK followed by 20 hexadecimal digits. - The 128-bit format used by PowerPC (two adjacent doubles) is represented - by 0xM followed by 32 hexadecimal digits. The IEEE 128-bit format - is represented by 0xL followed by 32 hexadecimal digits; no - currently supported target uses this format. Long doubles will only work if - they match the long double format on your target. All hexadecimal formats - are big-endian (sign bit at the left).

- -

There are no constants of type x86mmx.

-
- - -

- -Complex Constants -

- -
- -

Complex constants are a (potentially recursive) combination of simple - constants and smaller complex constants.

- -
-
Structure constants
-
Structure constants are represented with notation similar to structure - type definitions (a comma separated list of elements, surrounded by braces - ({})). For example: "{ i32 4, float 17.0, i32* @G }", - where "@G" is declared as "@G = external global i32". - Structure constants must have structure type, and - the number and types of elements must match those specified by the - type.
- -
Array constants
-
Array constants are represented with notation similar to array type - definitions (a comma separated list of elements, surrounded by square - brackets ([])). For example: "[ i32 42, i32 11, i32 74 - ]". Array constants must have array type, and - the number and types of elements must match those specified by the - type.
- -
Vector constants
-
Vector constants are represented with notation similar to vector type - definitions (a comma separated list of elements, surrounded by - less-than/greater-than's (<>)). For example: "< i32 - 42, i32 11, i32 74, i32 100 >". Vector constants must - have vector type, and the number and types of - elements must match those specified by the type.
- -
Zero initialization
-
The string 'zeroinitializer' can be used to zero initialize a - value to zero of any type, including scalar and - aggregate types. - This is often used to avoid having to print large zero initializers - (e.g. for large arrays) and is always exactly equivalent to using explicit - zero initializers.
- -
Metadata node
-
A metadata node is a structure-like constant with - metadata type. For example: "metadata !{ - i32 0, metadata !"test" }". Unlike other constants that are meant to - be interpreted as part of the instruction stream, metadata is a place to - attach additional information such as debug info.
-
- -
- - -

- Global Variable and Function Addresses -

- -
- -

The addresses of global variables - and functions are always implicitly valid - (link-time) constants. These constants are explicitly referenced when - the identifier for the global is used and always - have pointer type. For example, the following is a - legal LLVM file:

- -
-@X = global i32 17
-@Y = global i32 42
-@Z = global [2 x i32*] [ i32* @X, i32* @Y ]
-
- -
- - -

- Undefined Values -

- -
- -

The string 'undef' can be used anywhere a constant is expected, and - indicates that the user of the value may receive an unspecified bit-pattern. - Undefined values may be of any type (other than 'label' - or 'void') and be used anywhere a constant is permitted.

- -

Undefined values are useful because they indicate to the compiler that the - program is well defined no matter what value is used. This gives the - compiler more freedom to optimize. Here are some examples of (potentially - surprising) transformations that are valid (in pseudo IR):

- - -
-  %A = add %X, undef
-  %B = sub %X, undef
-  %C = xor %X, undef
-Safe:
-  %A = undef
-  %B = undef
-  %C = undef
-
- -

This is safe because all of the output bits are affected by the undef bits. - Any output bit can have a zero or one depending on the input bits.

- -
-  %A = or %X, undef
-  %B = and %X, undef
-Safe:
-  %A = -1
-  %B = 0
-Unsafe:
-  %A = undef
-  %B = undef
-
- -

These logical operations have bits that are not always affected by the input. - For example, if %X has a zero bit, then the output of the - 'and' operation will always be a zero for that bit, no matter what - the corresponding bit from the 'undef' is. As such, it is unsafe to - optimize or assume that the result of the 'and' is 'undef'. - However, it is safe to assume that all bits of the 'undef' could be - 0, and optimize the 'and' to 0. Likewise, it is safe to assume that - all the bits of the 'undef' operand to the 'or' could be - set, allowing the 'or' to be folded to -1.

- -
-  %A = select undef, %X, %Y
-  %B = select undef, 42, %Y
-  %C = select %X, %Y, undef
-Safe:
-  %A = %X     (or %Y)
-  %B = 42     (or %Y)
-  %C = %Y
-Unsafe:
-  %A = undef
-  %B = undef
-  %C = undef
-
- -

This set of examples shows that undefined 'select' (and conditional - branch) conditions can go either way, but they have to come from one - of the two operands. In the %A example, if %X and - %Y were both known to have a clear low bit, then %A would - have to have a cleared low bit. However, in the %C example, the - optimizer is allowed to assume that the 'undef' operand could be the - same as %Y, allowing the whole 'select' to be - eliminated.

- -
-  %A = xor undef, undef
-
-  %B = undef
-  %C = xor %B, %B
-
-  %D = undef
-  %E = icmp lt %D, 4
-  %F = icmp gte %D, 4
-
-Safe:
-  %A = undef
-  %B = undef
-  %C = undef
-  %D = undef
-  %E = undef
-  %F = undef
-
- -

This example points out that two 'undef' operands are not - necessarily the same. This can be surprising to people (and also matches C - semantics) where they assume that "X^X" is always zero, even - if X is undefined. This isn't true for a number of reasons, but the - short answer is that an 'undef' "variable" can arbitrarily change - its value over its "live range". This is true because the variable doesn't - actually have a live range. Instead, the value is logically read - from arbitrary registers that happen to be around when needed, so the value - is not necessarily consistent over time. In fact, %A and %C - need to have the same semantics or the core LLVM "replace all uses with" - concept would not hold.

- -
-  %A = fdiv undef, %X
-  %B = fdiv %X, undef
-Safe:
-  %A = undef
-b: unreachable
-
- -

These examples show the crucial difference between an undefined - value and undefined behavior. An undefined value (like - 'undef') is allowed to have an arbitrary bit-pattern. This means that - the %A operation can be constant folded to 'undef', because - the 'undef' could be an SNaN, and fdiv is not (currently) - defined on SNaN's. However, in the second example, we can make a more - aggressive assumption: because the undef is allowed to be an - arbitrary value, we are allowed to assume that it could be zero. Since a - divide by zero has undefined behavior, we are allowed to assume that - the operation does not execute at all. This allows us to delete the divide and - all code after it. Because the undefined operation "can't happen", the - optimizer can assume that it occurs in dead code.

- -
-a:  store undef -> %X
-b:  store %X -> undef
-Safe:
-a: <deleted>
-b: unreachable
-
- -

These examples reiterate the fdiv example: a store of an - undefined value can be assumed to not have any effect; we can assume that the - value is overwritten with bits that happen to match what was already there. - However, a store to an undefined location could clobber arbitrary - memory, therefore, it has undefined behavior.

- -
- - -

- Poison Values -

- -
- -

Poison values are similar to undef values, however - they also represent the fact that an instruction or constant expression which - cannot evoke side effects has nevertheless detected a condition which results - in undefined behavior.

- -

There is currently no way of representing a poison value in the IR; they - only exist when produced by operations such as - add with the nsw flag.

- -

Poison value behavior is defined in terms of value dependence:

- -
    -
  • Values other than phi nodes depend on - their operands.
  • - -
  • Phi nodes depend on the operand corresponding - to their dynamic predecessor basic block.
  • - -
  • Function arguments depend on the corresponding actual argument values in - the dynamic callers of their functions.
  • - -
  • Call instructions depend on the - ret instructions that dynamically transfer - control back to them.
  • - -
  • Invoke instructions depend on the - ret, resume, - or exception-throwing call instructions that dynamically transfer control - back to them.
  • - -
  • Non-volatile loads and stores depend on the most recent stores to all of the - referenced memory addresses, following the order in the IR - (including loads and stores implied by intrinsics such as - @llvm.memcpy.)
  • - - - - - -
  • An instruction with externally visible side effects depends on the most - recent preceding instruction with externally visible side effects, following - the order in the IR. (This includes - volatile operations.)
  • - -
  • An instruction control-depends on a - terminator instruction - if the terminator instruction has multiple successors and the instruction - is always executed when control transfers to one of the successors, and - may not be executed when control is transferred to another.
  • - -
  • Additionally, an instruction also control-depends on a terminator - instruction if the set of instructions it otherwise depends on would be - different if the terminator had transferred control to a different - successor.
  • - -
  • Dependence is transitive.
  • - -
- -

Poison Values have the same behavior as undef values, - with the additional affect that any instruction which has a dependence - on a poison value has undefined behavior.

- -

Here are some examples:

- -
-entry:
-  %poison = sub nuw i32 0, 1           ; Results in a poison value.
-  %still_poison = and i32 %poison, 0   ; 0, but also poison.
-  %poison_yet_again = getelementptr i32* @h, i32 %still_poison
-  store i32 0, i32* %poison_yet_again  ; memory at @h[0] is poisoned
-
-  store i32 %poison, i32* @g           ; Poison value stored to memory.
-  %poison2 = load i32* @g              ; Poison value loaded back from memory.
-
-  store volatile i32 %poison, i32* @g  ; External observation; undefined behavior.
-
-  %narrowaddr = bitcast i32* @g to i16*
-  %wideaddr = bitcast i32* @g to i64*
-  %poison3 = load i16* %narrowaddr     ; Returns a poison value.
-  %poison4 = load i64* %wideaddr       ; Returns a poison value.
-
-  %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
-  br i1 %cmp, label %true, label %end  ; Branch to either destination.
-
-true:
-  store volatile i32 0, i32* @g        ; This is control-dependent on %cmp, so
-                                       ; it has undefined behavior.
-  br label %end
-
-end:
-  %p = phi i32 [ 0, %entry ], [ 1, %true ]
-                                       ; Both edges into this PHI are
-                                       ; control-dependent on %cmp, so this
-                                       ; always results in a poison value.
-
-  store volatile i32 0, i32* @g        ; This would depend on the store in %true
-                                       ; if %cmp is true, or the store in %entry
-                                       ; otherwise, so this is undefined behavior.
-
-  br i1 %cmp, label %second_true, label %second_end
-                                       ; The same branch again, but this time the
-                                       ; true block doesn't have side effects.
-
-second_true:
-  ; No side effects!
-  ret void
-
-second_end:
-  store volatile i32 0, i32* @g        ; This time, the instruction always depends
-                                       ; on the store in %end. Also, it is
-                                       ; control-equivalent to %end, so this is
-                                       ; well-defined (ignoring earlier undefined
-                                       ; behavior in this example).
-
- -
- - -

- Addresses of Basic Blocks -

- -
- -

blockaddress(@function, %block)

- -

The 'blockaddress' constant computes the address of the specified - basic block in the specified function, and always has an i8* type. Taking - the address of the entry block is illegal.

- -

This value only has defined behavior when used as an operand to the - 'indirectbr' instruction, or for - comparisons against null. Pointer equality tests between labels addresses - results in undefined behavior — though, again, comparison against null - is ok, and no label is equal to the null pointer. This may be passed around - as an opaque pointer sized value as long as the bits are not inspected. This - allows ptrtoint and arithmetic to be performed on these values so - long as the original value is reconstituted before the indirectbr - instruction.

- -

Finally, some targets may provide defined semantics when using the value as - the operand to an inline assembly, but that is target specific.

- -
- - - -

- Constant Expressions -

- -
- -

Constant expressions are used to allow expressions involving other constants - to be used as constants. Constant expressions may be of - any first class type and may involve any LLVM - operation that does not have side effects (e.g. load and call are not - supported). The following is the syntax for constant expressions:

- -
-
trunc (CST to TYPE)
-
Truncate a constant to another type. The bit size of CST must be larger - than the bit size of TYPE. Both types must be integers.
- -
zext (CST to TYPE)
-
Zero extend a constant to another type. The bit size of CST must be - smaller than the bit size of TYPE. Both types must be integers.
- -
sext (CST to TYPE)
-
Sign extend a constant to another type. The bit size of CST must be - smaller than the bit size of TYPE. Both types must be integers.
- -
fptrunc (CST to TYPE)
-
Truncate a floating point constant to another floating point type. The - size of CST must be larger than the size of TYPE. Both types must be - floating point.
- -
fpext (CST to TYPE)
-
Floating point extend a constant to another type. The size of CST must be - smaller or equal to the size of TYPE. Both types must be floating - point.
- -
fptoui (CST to TYPE)
-
Convert a floating point constant to the corresponding unsigned integer - constant. TYPE must be a scalar or vector integer type. CST must be of - scalar or vector floating point type. Both CST and TYPE must be scalars, - or vectors of the same number of elements. If the value won't fit in the - integer type, the results are undefined.
- -
fptosi (CST to TYPE)
-
Convert a floating point constant to the corresponding signed integer - constant. TYPE must be a scalar or vector integer type. CST must be of - scalar or vector floating point type. Both CST and TYPE must be scalars, - or vectors of the same number of elements. If the value won't fit in the - integer type, the results are undefined.
- -
uitofp (CST to TYPE)
-
Convert an unsigned integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be - of scalar or vector integer type. Both CST and TYPE must be scalars, or - vectors of the same number of elements. If the value won't fit in the - floating point type, the results are undefined.
- -
sitofp (CST to TYPE)
-
Convert a signed integer constant to the corresponding floating point - constant. TYPE must be a scalar or vector floating point type. CST must be - of scalar or vector integer type. Both CST and TYPE must be scalars, or - vectors of the same number of elements. If the value won't fit in the - floating point type, the results are undefined.
- -
ptrtoint (CST to TYPE)
-
Convert a pointer typed constant to the corresponding integer constant - TYPE must be an integer type. CST must be of pointer - type. The CST value is zero extended, truncated, or unchanged to - make it fit in TYPE.
- -
inttoptr (CST to TYPE)
-
Convert a integer constant to a pointer constant. TYPE must be a pointer - type. CST must be of integer type. The CST value is zero extended, - truncated, or unchanged to make it fit in a pointer size. This one is - really dangerous!
- -
bitcast (CST to TYPE)
-
Convert a constant, CST, to another TYPE. The constraints of the operands - are the same as those for the bitcast - instruction.
- -
getelementptr (CSTPTR, IDX0, IDX1, ...)
-
getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)
-
Perform the getelementptr operation on - constants. As with the getelementptr - instruction, the index list may have zero or more indexes, which are - required to make sense for the type of "CSTPTR".
- -
select (COND, VAL1, VAL2)
-
Perform the select operation on constants.
- -
icmp COND (VAL1, VAL2)
-
Performs the icmp operation on constants.
- -
fcmp COND (VAL1, VAL2)
-
Performs the fcmp operation on constants.
- -
extractelement (VAL, IDX)
-
Perform the extractelement operation on - constants.
- -
insertelement (VAL, ELT, IDX)
-
Perform the insertelement operation on - constants.
- -
shufflevector (VEC1, VEC2, IDXMASK)
-
Perform the shufflevector operation on - constants.
- -
extractvalue (VAL, IDX0, IDX1, ...)
-
Perform the extractvalue operation on - constants. The index list is interpreted in a similar manner as indices in - a 'getelementptr' operation. At least one - index value must be specified.
- -
insertvalue (VAL, ELT, IDX0, IDX1, ...)
-
Perform the insertvalue operation on - constants. The index list is interpreted in a similar manner as indices in - a 'getelementptr' operation. At least one - index value must be specified.
- -
OPCODE (LHS, RHS)
-
Perform the specified operation of the LHS and RHS constants. OPCODE may - be any of the binary - or bitwise binary operations. The constraints - on operands are the same as those for the corresponding instruction - (e.g. no bitwise operations on floating point values are allowed).
-
- -
- -
- - -

Other Values

- -
- -

-Inline Assembler Expressions -

- -
- -

LLVM supports inline assembler expressions (as opposed - to Module-Level Inline Assembly) through the use of - a special value. This value represents the inline assembler as a string - (containing the instructions to emit), a list of operand constraints (stored - as a string), a flag that indicates whether or not the inline asm - expression has side effects, and a flag indicating whether the function - containing the asm needs to align its stack conservatively. An example - inline assembler expression is:

- -
-i32 (i32) asm "bswap $0", "=r,r"
-
- -

Inline assembler expressions may only be used as the callee operand of - a call instruction. Thus, typically we - have:

- -
-%X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
-
- -

Inline asms with side effects not visible in the constraint list must be - marked as having side effects. This is done through the use of the - 'sideeffect' keyword, like so:

- -
-call void asm sideeffect "eieio", ""()
-
- -

In some cases inline asms will contain code that will not work unless the - stack is aligned in some way, such as calls or SSE instructions on x86, - yet will not contain code that does that alignment within the asm. - The compiler should make conservative assumptions about what the asm might - contain and should generate its usual stack alignment code in the prologue - if the 'alignstack' keyword is present:

- -
-call void asm alignstack "eieio", ""()
-
- -

If both keywords appear the 'sideeffect' keyword must come - first.

- - - - -

- Inline Asm Metadata -

- -
- -

The call instructions that wrap inline asm nodes may have a - "!srcloc" MDNode attached to it that contains a list of constant - integers. If present, the code generator will use the integer as the - location cookie value when report errors through the LLVMContext - error reporting mechanisms. This allows a front-end to correlate backend - errors that occur with inline asm back to the source code that produced it. - For example:

- -
-call void asm sideeffect "something bad", ""(), !srcloc !42
-...
-!42 = !{ i32 1234567 }
-
- -

It is up to the front-end to make sense of the magic numbers it places in the - IR. If the MDNode contains multiple constants, the code generator will use - the one that corresponds to the line of the asm that the error occurs on.

- -
- -
- - -

- Metadata Nodes and Metadata Strings -

- -
- -

LLVM IR allows metadata to be attached to instructions in the program that - can convey extra information about the code to the optimizers and code - generator. One example application of metadata is source-level debug - information. There are two metadata primitives: strings and nodes. All - metadata has the metadata type and is identified in syntax by a - preceding exclamation point ('!').

- -

A metadata string is a string surrounded by double quotes. It can contain - any character by escaping non-printable characters with "\xx" where - "xx" is the two digit hex code. For example: - "!"test\00"".

- -

Metadata nodes are represented with notation similar to structure constants - (a comma separated list of elements, surrounded by braces and preceded by an - exclamation point). Metadata nodes can have any values as their operand. For - example:

- -
-
-!{ metadata !"test\00", i32 10}
-
-
- -

A named metadata is a collection of - metadata nodes, which can be looked up in the module symbol table. For - example:

- -
-
-!foo =  metadata !{!4, !3}
-
-
- -

Metadata can be used as function arguments. Here llvm.dbg.value - function is using two metadata arguments:

- -
-
-call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
-
-
- -

Metadata can be attached with an instruction. Here metadata !21 is - attached to the add instruction using the !dbg - identifier:

- -
-
-%indvar.next = add i64 %indvar, 1, !dbg !21
-
-
- -

More information about specific metadata nodes recognized by the optimizers - and code generator is found below.

- - -

- 'tbaa' Metadata -

- -
- -

In LLVM IR, memory does not have types, so LLVM's own type system is not - suitable for doing TBAA. Instead, metadata is added to the IR to describe - a type system of a higher level language. This can be used to implement - typical C/C++ TBAA, but it can also be used to implement custom alias - analysis behavior for other languages.

- -

The current metadata format is very simple. TBAA metadata nodes have up to - three fields, e.g.:

- -
-
-!0 = metadata !{ metadata !"an example type tree" }
-!1 = metadata !{ metadata !"int", metadata !0 }
-!2 = metadata !{ metadata !"float", metadata !0 }
-!3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
-
-
- -

The first field is an identity field. It can be any value, usually - a metadata string, which uniquely identifies the type. The most important - name in the tree is the name of the root node. Two trees with - different root node names are entirely disjoint, even if they - have leaves with common names.

- -

The second field identifies the type's parent node in the tree, or - is null or omitted for a root node. A type is considered to alias - all of its descendants and all of its ancestors in the tree. Also, - a type is considered to alias all types in other trees, so that - bitcode produced from multiple front-ends is handled conservatively.

- -

If the third field is present, it's an integer which if equal to 1 - indicates that the type is "constant" (meaning - pointsToConstantMemory should return true; see - other useful - AliasAnalysis methods).

- -
- - -

- 'fpmath' Metadata -

- -
- -

fpmath metadata may be attached to any instruction of floating point - type. It can be used to express the maximum acceptable error in the result of - that instruction, in ULPs, thus potentially allowing the compiler to use a - more efficient but less accurate method of computing it. ULP is defined as - follows:

- -
- -

If x is a real number that lies between two finite consecutive - floating-point numbers a and b, without being equal to one - of them, then ulp(x) = |b - a|, otherwise ulp(x) is the - distance between the two non-equal finite floating-point numbers nearest - x. Moreover, ulp(NaN) is NaN.

- -
- -

The metadata node shall consist of a single positive floating point number - representing the maximum relative error, for example:

- -
-
-!0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
-
-
- -
- - -

- 'range' Metadata -

- -
-

range metadata may be attached only to loads of integer types. It - expresses the possible ranges the loaded value is in. The ranges are - represented with a flattened list of integers. The loaded value is known to - be in the union of the ranges defined by each consecutive pair. Each pair - has the following properties:

-
    -
  • The type must match the type loaded by the instruction.
  • -
  • The pair a,b represents the range [a,b).
  • -
  • Both a and b are constants.
  • -
  • The range is allowed to wrap.
  • -
  • The range should not represent the full or empty set. That is, - a!=b.
  • -
- -

Examples:

-
-
-  %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
-  %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
-  %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
-...
-!0 = metadata !{ i8 0, i8 2 }
-!1 = metadata !{ i8 255, i8 2 }
-!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
-
-
-
-
- -
- - -

- Module Flags Metadata -

- - -
- -

Information about the module as a whole is difficult to convey to LLVM's - subsystems. The LLVM IR isn't sufficient to transmit this - information. The llvm.module.flags named metadata exists in order to - facilitate this. These flags are in the form of key / value pairs — - much like a dictionary — making it easy for any subsystem who cares - about a flag to look it up.

- -

The llvm.module.flags metadata contains a list of metadata - triplets. Each triplet has the following form:

- -
    -
  • The first element is a behavior flag, which specifies the behavior - when two (or more) modules are merged together, and it encounters two (or - more) metadata with the same ID. The supported behaviors are described - below.
  • - -
  • The second element is a metadata string that is a unique ID for the - metadata. How each ID is interpreted is documented below.
  • - -
  • The third element is the value of the flag.
  • -
- -

When two (or more) modules are merged together, the resulting - llvm.module.flags metadata is the union of the - modules' llvm.module.flags metadata. The only exception being a flag - with the Override behavior, which may override another flag's value - (see below).

- -

The following behaviors are supported:

- - - - - - - - - - - - - - - - - - - - - - - - -
ValueBehavior
1 -
-
Error
-
Emits an error if two values disagree. It is an error to have an ID - with both an Error and a Warning behavior.
-
-
2 -
-
Warning
-
Emits a warning if two values disagree.
-
-
3 -
-
Require
-
Emits an error when the specified value is not present or doesn't - have the specified value. It is an error for two (or more) - llvm.module.flags with the same ID to have the Require - behavior but different values. There may be multiple Require flags - per ID.
-
-
4 -
-
Override
-
Uses the specified value if the two values disagree. It is an - error for two (or more) llvm.module.flags with the same - ID to have the Override behavior but different values.
-
-
- -

An example of module flags:

- -
-!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
-!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
-!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
-!3 = metadata !{ i32 3, metadata !"qux",
-  metadata !{
-    metadata !"foo", i32 1
-  }
-}
-!llvm.module.flags = !{ !0, !1, !2, !3 }
-
- -
    -
  • Metadata !0 has the ID !"foo" and the value '1'. The - behavior if two or more !"foo" flags are seen is to emit an - error if their values are not equal.

  • - -
  • Metadata !1 has the ID !"bar" and the value '37'. The - behavior if two or more !"bar" flags are seen is to use the - value '37' if their values are not equal.

  • - -
  • Metadata !2 has the ID !"qux" and the value '42'. The - behavior if two or more !"qux" flags are seen is to emit a - warning if their values are not equal.

  • - -
  • Metadata !3 has the ID !"qux" and the value:

    - -
    -metadata !{ metadata !"foo", i32 1 }
    -
    - -

    The behavior is to emit an error if the llvm.module.flags does - not contain a flag with the ID !"foo" that has the value - '1'. If two or more !"qux" flags exist, then they must have - the same value or an error will be issued.

  • -
- - - -

-Objective-C Garbage Collection Module Flags Metadata -

- -
- -

On the Mach-O platform, Objective-C stores metadata about garbage collection - in a special section called "image info". The metadata consists of a version - number and a bitmask specifying what types of garbage collection are - supported (if any) by the file. If two or more modules are linked together - their garbage collection metadata needs to be merged rather than appended - together.

- -

The Objective-C garbage collection module flags metadata consists of the - following key-value pairs:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyValue
Objective-C Version[Required] — The Objective-C ABI - version. Valid values are 1 and 2.
Objective-C Image Info Version[Required] — The version of the image info - section. Currently always 0.
Objective-C Image Info Section[Required] — The section to place the - metadata. Valid values are "__OBJC, __image_info, regular" for - Objective-C ABI version 1, and "__DATA,__objc_imageinfo, regular, - no_dead_strip" for Objective-C ABI version 2.
Objective-C Garbage Collection[Required] — Specifies whether garbage - collection is supported or not. Valid values are 0, for no garbage - collection, and 2, for garbage collection supported.
Objective-C GC Only[Optional] — Specifies that only garbage - collection is supported. If present, its value must be 6. This flag - requires that the Objective-C Garbage Collection flag have the - value 2.
- -

Some important flag interactions:

- -
    -
  • If a module with Objective-C Garbage Collection set to 0 is - merged with a module with Objective-C Garbage Collection set to - 2, then the resulting module has the Objective-C Garbage - Collection flag set to 0.
  • - -
  • A module with Objective-C Garbage Collection set to 0 cannot be - merged with a module with Objective-C GC Only set to 6.
  • -
- -
- -
- - -

- Intrinsic Global Variables -

- -
-

LLVM has a number of "magic" global variables that contain data that affect -code generation or other IR semantics. These are documented here. All globals -of this sort should have a section specified as "llvm.metadata". This -section and all globals that start with "llvm." are reserved for use -by LLVM.

- - -

-The 'llvm.used' Global Variable -

- -
- -

The @llvm.used global is an array with i8* element type which has appending linkage. This array contains a list of -pointers to global variables and functions which may optionally have a pointer -cast formed of bitcast or getelementptr. For example, a legal use of it is:

- -
-
-@X = global i8 4
-@Y = global i32 123
-
-@llvm.used = appending global [2 x i8*] [
-   i8* @X,
-   i8* bitcast (i32* @Y to i8*)
-], section "llvm.metadata"
-
-
- -

If a global variable appears in the @llvm.used list, then the - compiler, assembler, and linker are required to treat the symbol as if there - is a reference to the global that it cannot see. For example, if a variable - has internal linkage and no references other than that from - the @llvm.used list, it cannot be deleted. This is commonly used to - represent references from inline asms and other things the compiler cannot - "see", and corresponds to "attribute((used))" in GNU C.

- -

On some targets, the code generator must emit a directive to the assembler or - object file to prevent the assembler and linker from molesting the - symbol.

- -
- - -

- - The 'llvm.compiler.used' Global Variable - -

- -
- -

The @llvm.compiler.used directive is the same as the - @llvm.used directive, except that it only prevents the compiler from - touching the symbol. On targets that support it, this allows an intelligent - linker to optimize references to the symbol without being impeded as it would - be by @llvm.used.

- -

This is a rare construct that should only be used in rare circumstances, and - should not be exposed to source languages.

- -
- - -

-The 'llvm.global_ctors' Global Variable -

- -
- -
-
-%0 = type { i32, void ()* }
-@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
-
-
- -

The @llvm.global_ctors array contains a list of constructor - functions and associated priorities. The functions referenced by this array - will be called in ascending order of priority (i.e. lowest first) when the - module is loaded. The order of functions with the same priority is not - defined.

- -
- - -

-The 'llvm.global_dtors' Global Variable -

- -
- -
-
-%0 = type { i32, void ()* }
-@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
-
-
- -

The @llvm.global_dtors array contains a list of destructor functions - and associated priorities. The functions referenced by this array will be - called in descending order of priority (i.e. highest first) when the module - is loaded. The order of functions with the same priority is not defined.

- -
- -
- - -

Instruction Reference

- - -
- -

The LLVM instruction set consists of several different classifications of - instructions: terminator - instructions, binary instructions, - bitwise binary instructions, - memory instructions, and - other instructions.

- - -

- Terminator Instructions -

- -
- -

As mentioned previously, every basic block - in a program ends with a "Terminator" instruction, which indicates which - block should be executed after the current block is finished. These - terminator instructions typically yield a 'void' value: they produce - control flow, not values (the one exception being the - 'invoke' instruction).

- -

The terminator instructions are: - 'ret', - 'br', - 'switch', - 'indirectbr', - 'invoke', - 'resume', and - 'unreachable'.

- - -

- 'ret' Instruction -

- -
- -
Syntax:
-
-  ret <type> <value>       ; Return a value from a non-void function
-  ret void                 ; Return from void function
-
- -
Overview:
-

The 'ret' instruction is used to return control flow (and optionally - a value) from a function back to the caller.

- -

There are two forms of the 'ret' instruction: one that returns a - value and then causes control flow, and one that just causes control flow to - occur.

- -
Arguments:
-

The 'ret' instruction optionally accepts a single argument, the - return value. The type of the return value must be a - 'first class' type.

- -

A function is not well formed if it it has a - non-void return type and contains a 'ret' instruction with no return - value or a return value with a type that does not match its type, or if it - has a void return type and contains a 'ret' instruction with a - return value.

- -
Semantics:
-

When the 'ret' instruction is executed, control flow returns back to - the calling function's context. If the caller is a - "call" instruction, execution continues at the - instruction after the call. If the caller was an - "invoke" instruction, execution continues at - the beginning of the "normal" destination block. If the instruction returns - a value, that value shall set the call or invoke instruction's return - value.

- -
Example:
-
-  ret i32 5                       ; Return an integer value of 5
-  ret void                        ; Return from a void function
-  ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
-
- -
- -

- 'br' Instruction -

- -
- -
Syntax:
-
-  br i1 <cond>, label <iftrue>, label <iffalse>
-  br label <dest>          ; Unconditional branch
-
- -
Overview:
-

The 'br' instruction is used to cause control flow to transfer to a - different basic block in the current function. There are two forms of this - instruction, corresponding to a conditional branch and an unconditional - branch.

- -
Arguments:
-

The conditional branch form of the 'br' instruction takes a single - 'i1' value and two 'label' values. The unconditional form - of the 'br' instruction takes a single 'label' value as a - target.

- -
Semantics:
-

Upon execution of a conditional 'br' instruction, the 'i1' - argument is evaluated. If the value is true, control flows to the - 'iftrue' label argument. If "cond" is false, - control flows to the 'iffalse' label argument.

- -
Example:
-
-Test:
-  %cond = icmp eq i32 %a, %b
-  br i1 %cond, label %IfEqual, label %IfUnequal
-IfEqual:
-  ret i32 1
-IfUnequal:
-  ret i32 0
-
- -
- - -

- 'switch' Instruction -

- -
- -
Syntax:
-
-  switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
-
- -
Overview:
-

The 'switch' instruction is used to transfer control flow to one of - several different places. It is a generalization of the 'br' - instruction, allowing a branch to occur to one of many possible - destinations.

- -
Arguments:
-

The 'switch' instruction uses three parameters: an integer - comparison value 'value', a default 'label' destination, - and an array of pairs of comparison value constants and 'label's. - The table is not allowed to contain duplicate constant entries.

- -
Semantics:
-

The switch instruction specifies a table of values and - destinations. When the 'switch' instruction is executed, this table - is searched for the given value. If the value is found, control flow is - transferred to the corresponding destination; otherwise, control flow is - transferred to the default destination.

- -
Implementation:
-

Depending on properties of the target machine and the particular - switch instruction, this instruction may be code generated in - different ways. For example, it could be generated as a series of chained - conditional branches or with a lookup table.

- -
Example:
-
- ; Emulate a conditional br instruction
- %Val = zext i1 %value to i32
- switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
-
- ; Emulate an unconditional br instruction
- switch i32 0, label %dest [ ]
-
- ; Implement a jump table:
- switch i32 %val, label %otherwise [ i32 0, label %onzero
-                                     i32 1, label %onone
-                                     i32 2, label %ontwo ]
-
- -
- - - -

- 'indirectbr' Instruction -

- -
- -
Syntax:
-
-  indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
-
- -
Overview:
- -

The 'indirectbr' instruction implements an indirect branch to a label - within the current function, whose address is specified by - "address". Address must be derived from a blockaddress constant.

- -
Arguments:
- -

The 'address' argument is the address of the label to jump to. The - rest of the arguments indicate the full set of possible destinations that the - address may point to. Blocks are allowed to occur multiple times in the - destination list, though this isn't particularly useful.

- -

This destination list is required so that dataflow analysis has an accurate - understanding of the CFG.

- -
Semantics:
- -

Control transfers to the block specified in the address argument. All - possible destination blocks must be listed in the label list, otherwise this - instruction has undefined behavior. This implies that jumps to labels - defined in other functions have undefined behavior as well.

- -
Implementation:
- -

This is typically implemented with a jump through a register.

- -
Example:
-
- indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
-
- -
- - - -

- 'invoke' Instruction -

- -
- -
Syntax:
-
-  <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
-                to label <normal label> unwind label <exception label>
-
- -
Overview:
-

The 'invoke' instruction causes control to transfer to a specified - function, with the possibility of control flow transfer to either the - 'normal' label or the 'exception' label. If the callee - function returns with the "ret" instruction, - control flow will return to the "normal" label. If the callee (or any - indirect callees) returns via the "resume" - instruction or other exception handling mechanism, control is interrupted and - continued at the dynamically nearest "exception" label.

- -

The 'exception' label is a - landing pad for the - exception. As such, 'exception' label is required to have the - "landingpad" instruction, which contains - the information about the behavior of the program after unwinding - happens, as its first non-PHI instruction. The restrictions on the - "landingpad" instruction's tightly couples it to the - "invoke" instruction, so that the important information contained - within the "landingpad" instruction can't be lost through normal - code motion.

- -
Arguments:
-

This instruction requires several arguments:

- -
    -
  1. The optional "cconv" marker indicates which calling - convention the call should use. If none is specified, the call - defaults to using C calling conventions.
  2. - -
  3. The optional Parameter Attributes list for - return values. Only 'zeroext', 'signext', and - 'inreg' attributes are valid here.
  4. - -
  5. 'ptr to function ty': shall be the signature of the pointer to - function value being invoked. In most cases, this is a direct function - invocation, but indirect invokes are just as possible, branching - off an arbitrary pointer to function value.
  6. - -
  7. 'function ptr val': An LLVM value containing a pointer to a - function to be invoked.
  8. - -
  9. 'function args': argument list whose types match the function - signature argument types and parameter attributes. All arguments must be - of first class type. If the function - signature indicates the function accepts a variable number of arguments, - the extra arguments can be specified.
  10. - -
  11. 'normal label': the label reached when the called function - executes a 'ret' instruction.
  12. - -
  13. 'exception label': the label reached when a callee returns via - the resume instruction or other exception - handling mechanism.
  14. - -
  15. The optional function attributes list. Only - 'noreturn', 'nounwind', 'readonly' and - 'readnone' attributes are valid here.
  16. -
- -
Semantics:
-

This instruction is designed to operate as a standard - 'call' instruction in most regards. The - primary difference is that it establishes an association with a label, which - is used by the runtime library to unwind the stack.

- -

This instruction is used in languages with destructors to ensure that proper - cleanup is performed in the case of either a longjmp or a thrown - exception. Additionally, this is important for implementation of - 'catch' clauses in high-level languages that support them.

- -

For the purposes of the SSA form, the definition of the value returned by the - 'invoke' instruction is deemed to occur on the edge from the current - block to the "normal" label. If the callee unwinds then no return value is - available.

- -
Example:
-
-  %retval = invoke i32 @Test(i32 15) to label %Continue
-              unwind label %TestCleanup              ; {i32}:retval set
-  %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
-              unwind label %TestCleanup              ; {i32}:retval set
-
- -
- - - -

- 'resume' Instruction -

- -
- -
Syntax:
-
-  resume <type> <value>
-
- -
Overview:
-

The 'resume' instruction is a terminator instruction that has no - successors.

- -
Arguments:
-

The 'resume' instruction requires one argument, which must have the - same type as the result of any 'landingpad' instruction in the same - function.

- -
Semantics:
-

The 'resume' instruction resumes propagation of an existing - (in-flight) exception whose unwinding was interrupted with - a landingpad instruction.

- -
Example:
-
-  resume { i8*, i32 } %exn
-
- -
- - - -

- 'unreachable' Instruction -

- -
- -
Syntax:
-
-  unreachable
-
- -
Overview:
-

The 'unreachable' instruction has no defined semantics. This - instruction is used to inform the optimizer that a particular portion of the - code is not reachable. This can be used to indicate that the code after a - no-return function cannot be reached, and other facts.

- -
Semantics:
-

The 'unreachable' instruction has no defined semantics.

- -
- -
- - -

- Binary Operations -

- -
- -

Binary operators are used to do most of the computation in a program. They - require two operands of the same type, execute an operation on them, and - produce a single value. The operands might represent multiple data, as is - the case with the vector data type. The result value - has the same type as its operands.

- -

There are several different binary operators:

- - -

- 'add' Instruction -

- -
- -
Syntax:
-
-  <result> = add <ty> <op1>, <op2>          ; yields {ty}:result
-  <result> = add nuw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = add nsw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = add nuw nsw <ty> <op1>, <op2>  ; yields {ty}:result
-
- -
Overview:
-

The 'add' instruction returns the sum of its two operands.

- -
Arguments:
-

The two arguments to the 'add' instruction must - be integer or vector of - integer values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the integer sum of the two operands.

- -

If the sum has unsigned overflow, the result returned is the mathematical - result modulo 2n, where n is the bit width of the result.

- -

Because LLVM integers use a two's complement representation, this instruction - is appropriate for both signed and unsigned integers.

- -

nuw and nsw stand for "No Unsigned Wrap" - and "No Signed Wrap", respectively. If the nuw and/or - nsw keywords are present, the result value of the add - is a poison value if unsigned and/or signed overflow, - respectively, occurs.

- -
Example:
-
-  <result> = add i32 4, %var          ; yields {i32}:result = 4 + %var
-
- -
- - -

- 'fadd' Instruction -

- -
- -
Syntax:
-
-  <result> = fadd <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'fadd' instruction returns the sum of its two operands.

- -
Arguments:
-

The two arguments to the 'fadd' instruction must be - floating point or vector of - floating point values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the floating point sum of the two operands.

- -
Example:
-
-  <result> = fadd float 4.0, %var          ; yields {float}:result = 4.0 + %var
-
- -
- - -

- 'sub' Instruction -

- -
- -
Syntax:
-
-  <result> = sub <ty> <op1>, <op2>          ; yields {ty}:result
-  <result> = sub nuw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = sub nsw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = sub nuw nsw <ty> <op1>, <op2>  ; yields {ty}:result
-
- -
Overview:
-

The 'sub' instruction returns the difference of its two - operands.

- -

Note that the 'sub' instruction is used to represent the - 'neg' instruction present in most other intermediate - representations.

- -
Arguments:
-

The two arguments to the 'sub' instruction must - be integer or vector of - integer values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the integer difference of the two operands.

- -

If the difference has unsigned overflow, the result returned is the - mathematical result modulo 2n, where n is the bit width of the - result.

- -

Because LLVM integers use a two's complement representation, this instruction - is appropriate for both signed and unsigned integers.

- -

nuw and nsw stand for "No Unsigned Wrap" - and "No Signed Wrap", respectively. If the nuw and/or - nsw keywords are present, the result value of the sub - is a poison value if unsigned and/or signed overflow, - respectively, occurs.

- -
Example:
-
-  <result> = sub i32 4, %var          ; yields {i32}:result = 4 - %var
-  <result> = sub i32 0, %val          ; yields {i32}:result = -%var
-
- -
- - -

- 'fsub' Instruction -

- -
- -
Syntax:
-
-  <result> = fsub <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'fsub' instruction returns the difference of its two - operands.

- -

Note that the 'fsub' instruction is used to represent the - 'fneg' instruction present in most other intermediate - representations.

- -
Arguments:
-

The two arguments to the 'fsub' instruction must be - floating point or vector of - floating point values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the floating point difference of the two operands.

- -
Example:
-
-  <result> = fsub float 4.0, %var           ; yields {float}:result = 4.0 - %var
-  <result> = fsub float -0.0, %val          ; yields {float}:result = -%var
-
- -
- - -

- 'mul' Instruction -

- -
- -
Syntax:
-
-  <result> = mul <ty> <op1>, <op2>          ; yields {ty}:result
-  <result> = mul nuw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = mul nsw <ty> <op1>, <op2>      ; yields {ty}:result
-  <result> = mul nuw nsw <ty> <op1>, <op2>  ; yields {ty}:result
-
- -
Overview:
-

The 'mul' instruction returns the product of its two operands.

- -
Arguments:
-

The two arguments to the 'mul' instruction must - be integer or vector of - integer values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the integer product of the two operands.

- -

If the result of the multiplication has unsigned overflow, the result - returned is the mathematical result modulo 2n, where n is the bit - width of the result.

- -

Because LLVM integers use a two's complement representation, and the result - is the same width as the operands, this instruction returns the correct - result for both signed and unsigned integers. If a full product - (e.g. i32xi32->i64) is needed, the operands should - be sign-extended or zero-extended as appropriate to the width of the full - product.

- -

nuw and nsw stand for "No Unsigned Wrap" - and "No Signed Wrap", respectively. If the nuw and/or - nsw keywords are present, the result value of the mul - is a poison value if unsigned and/or signed overflow, - respectively, occurs.

- -
Example:
-
-  <result> = mul i32 4, %var          ; yields {i32}:result = 4 * %var
-
- -
- - -

- 'fmul' Instruction -

- -
- -
Syntax:
-
-  <result> = fmul <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'fmul' instruction returns the product of its two operands.

- -
Arguments:
-

The two arguments to the 'fmul' instruction must be - floating point or vector of - floating point values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the floating point product of the two operands.

- -
Example:
-
-  <result> = fmul float 4.0, %var          ; yields {float}:result = 4.0 * %var
-
- -
- - -

- 'udiv' Instruction -

- -
- -
Syntax:
-
-  <result> = udiv <ty> <op1>, <op2>         ; yields {ty}:result
-  <result> = udiv exact <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'udiv' instruction returns the quotient of its two operands.

- -
Arguments:
-

The two arguments to the 'udiv' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the unsigned integer quotient of the two operands.

- -

Note that unsigned integer division and signed integer division are distinct - operations; for signed integer division, use 'sdiv'.

- -

Division by zero leads to undefined behavior.

- -

If the exact keyword is present, the result value of the - udiv is a poison value if %op1 is not a - multiple of %op2 (as such, "((a udiv exact b) mul b) == a").

- - -
Example:
-
-  <result> = udiv i32 4, %var          ; yields {i32}:result = 4 / %var
-
- -
- - -

- 'sdiv' Instruction -

- -
- -
Syntax:
-
-  <result> = sdiv <ty> <op1>, <op2>         ; yields {ty}:result
-  <result> = sdiv exact <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'sdiv' instruction returns the quotient of its two operands.

- -
Arguments:
-

The two arguments to the 'sdiv' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the signed integer quotient of the two operands rounded - towards zero.

- -

Note that signed integer division and unsigned integer division are distinct - operations; for unsigned integer division, use 'udiv'.

- -

Division by zero leads to undefined behavior. Overflow also leads to - undefined behavior; this is a rare case, but can occur, for example, by doing - a 32-bit division of -2147483648 by -1.

- -

If the exact keyword is present, the result value of the - sdiv is a poison value if the result would - be rounded.

- -
Example:
-
-  <result> = sdiv i32 4, %var          ; yields {i32}:result = 4 / %var
-
- -
- - -

- 'fdiv' Instruction -

- -
- -
Syntax:
-
-  <result> = fdiv <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'fdiv' instruction returns the quotient of its two operands.

- -
Arguments:
-

The two arguments to the 'fdiv' instruction must be - floating point or vector of - floating point values. Both arguments must have identical types.

- -
Semantics:
-

The value produced is the floating point quotient of the two operands.

- -
Example:
-
-  <result> = fdiv float 4.0, %var          ; yields {float}:result = 4.0 / %var
-
- -
- - -

- 'urem' Instruction -

- -
- -
Syntax:
-
-  <result> = urem <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'urem' instruction returns the remainder from the unsigned - division of its two arguments.

- -
Arguments:
-

The two arguments to the 'urem' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

This instruction returns the unsigned integer remainder of a division. - This instruction always performs an unsigned division to get the - remainder.

- -

Note that unsigned integer remainder and signed integer remainder are - distinct operations; for signed integer remainder, use 'srem'.

- -

Taking the remainder of a division by zero leads to undefined behavior.

- -
Example:
-
-  <result> = urem i32 4, %var          ; yields {i32}:result = 4 % %var
-
- -
- - -

- 'srem' Instruction -

- -
- -
Syntax:
-
-  <result> = srem <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'srem' instruction returns the remainder from the signed - division of its two operands. This instruction can also take - vector versions of the values in which case the - elements must be integers.

- -
Arguments:
-

The two arguments to the 'srem' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

This instruction returns the remainder of a division (where the result - is either zero or has the same sign as the dividend, op1), not the - modulo operator (where the result is either zero or has the same sign - as the divisor, op2) of a value. - For more information about the difference, - see The - Math Forum. For a table of how this is implemented in various languages, - please see - Wikipedia: modulo operation.

- -

Note that signed integer remainder and unsigned integer remainder are - distinct operations; for unsigned integer remainder, use 'urem'.

- -

Taking the remainder of a division by zero leads to undefined behavior. - Overflow also leads to undefined behavior; this is a rare case, but can - occur, for example, by taking the remainder of a 32-bit division of - -2147483648 by -1. (The remainder doesn't actually overflow, but this rule - lets srem be implemented using instructions that return both the result of - the division and the remainder.)

- -
Example:
-
-  <result> = srem i32 4, %var          ; yields {i32}:result = 4 % %var
-
- -
- - -

- 'frem' Instruction -

- -
- -
Syntax:
-
-  <result> = frem <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'frem' instruction returns the remainder from the division of - its two operands.

- -
Arguments:
-

The two arguments to the 'frem' instruction must be - floating point or vector of - floating point values. Both arguments must have identical types.

- -
Semantics:
-

This instruction returns the remainder of a division. The remainder - has the same sign as the dividend.

- -
Example:
-
-  <result> = frem float 4.0, %var          ; yields {float}:result = 4.0 % %var
-
- -
- -
- - -

- Bitwise Binary Operations -

- -
- -

Bitwise binary operators are used to do various forms of bit-twiddling in a - program. They are generally very efficient instructions and can commonly be - strength reduced from other instructions. They require two operands of the - same type, execute an operation on them, and produce a single value. The - resulting value is the same type as its operands.

- - -

- 'shl' Instruction -

- -
- -
Syntax:
-
-  <result> = shl <ty> <op1>, <op2>           ; yields {ty}:result
-  <result> = shl nuw <ty> <op1>, <op2>       ; yields {ty}:result
-  <result> = shl nsw <ty> <op1>, <op2>       ; yields {ty}:result
-  <result> = shl nuw nsw <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'shl' instruction returns the first operand shifted to the left - a specified number of bits.

- -
Arguments:
-

Both arguments to the 'shl' instruction must be the - same integer or vector of - integer type. 'op2' is treated as an unsigned value.

- -
Semantics:
-

The value produced is op1 * 2op2 mod - 2n, where n is the width of the result. If op2 - is (statically or dynamically) negative or equal to or larger than the number - of bits in op1, the result is undefined. If the arguments are - vectors, each vector element of op1 is shifted by the corresponding - shift amount in op2.

- -

If the nuw keyword is present, then the shift produces a - poison value if it shifts out any non-zero bits. If - the nsw keyword is present, then the shift produces a - poison value if it shifts out any bits that disagree - with the resultant sign bit. As such, NUW/NSW have the same semantics as - they would if the shift were expressed as a mul instruction with the same - nsw/nuw bits in (mul %op1, (shl 1, %op2)).

- -
Example:
-
-  <result> = shl i32 4, %var   ; yields {i32}: 4 << %var
-  <result> = shl i32 4, 2      ; yields {i32}: 16
-  <result> = shl i32 1, 10     ; yields {i32}: 1024
-  <result> = shl i32 1, 32     ; undefined
-  <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 2, i32 4>
-
- -
- - -

- 'lshr' Instruction -

- -
- -
Syntax:
-
-  <result> = lshr <ty> <op1>, <op2>         ; yields {ty}:result
-  <result> = lshr exact <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'lshr' instruction (logical shift right) returns the first - operand shifted to the right a specified number of bits with zero fill.

- -
Arguments:
-

Both arguments to the 'lshr' instruction must be the same - integer or vector of integer - type. 'op2' is treated as an unsigned value.

- -
Semantics:
-

This instruction always performs a logical shift right operation. The most - significant bits of the result will be filled with zero bits after the shift. - If op2 is (statically or dynamically) equal to or larger than the - number of bits in op1, the result is undefined. If the arguments are - vectors, each vector element of op1 is shifted by the corresponding - shift amount in op2.

- -

If the exact keyword is present, the result value of the - lshr is a poison value if any of the bits - shifted out are non-zero.

- - -
Example:
-
-  <result> = lshr i32 4, 1   ; yields {i32}:result = 2
-  <result> = lshr i32 4, 2   ; yields {i32}:result = 1
-  <result> = lshr i8  4, 3   ; yields {i8}:result = 0
-  <result> = lshr i8 -2, 1   ; yields {i8}:result = 0x7FFFFFFF 
-  <result> = lshr i32 1, 32  ; undefined
-  <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2>   ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
-
- -
- - -

- 'ashr' Instruction -

- -
- -
Syntax:
-
-  <result> = ashr <ty> <op1>, <op2>         ; yields {ty}:result
-  <result> = ashr exact <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'ashr' instruction (arithmetic shift right) returns the first - operand shifted to the right a specified number of bits with sign - extension.

- -
Arguments:
-

Both arguments to the 'ashr' instruction must be the same - integer or vector of integer - type. 'op2' is treated as an unsigned value.

- -
Semantics:
-

This instruction always performs an arithmetic shift right operation, The - most significant bits of the result will be filled with the sign bit - of op1. If op2 is (statically or dynamically) equal to or - larger than the number of bits in op1, the result is undefined. If - the arguments are vectors, each vector element of op1 is shifted by - the corresponding shift amount in op2.

- -

If the exact keyword is present, the result value of the - ashr is a poison value if any of the bits - shifted out are non-zero.

- -
Example:
-
-  <result> = ashr i32 4, 1   ; yields {i32}:result = 2
-  <result> = ashr i32 4, 2   ; yields {i32}:result = 1
-  <result> = ashr i8  4, 3   ; yields {i8}:result = 0
-  <result> = ashr i8 -2, 1   ; yields {i8}:result = -1
-  <result> = ashr i32 1, 32  ; undefined
-  <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3>   ; yields: result=<2 x i32> < i32 -1, i32 0>
-
- -
- - -

- 'and' Instruction -

- -
- -
Syntax:
-
-  <result> = and <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'and' instruction returns the bitwise logical and of its two - operands.

- -
Arguments:
-

The two arguments to the 'and' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

The truth table used for the 'and' instruction is:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
In0In1Out
000
010
100
111
- -
Example:
-
-  <result> = and i32 4, %var         ; yields {i32}:result = 4 & %var
-  <result> = and i32 15, 40          ; yields {i32}:result = 8
-  <result> = and i32 4, 8            ; yields {i32}:result = 0
-
-
- -

- 'or' Instruction -

- -
- -
Syntax:
-
-  <result> = or <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'or' instruction returns the bitwise logical inclusive or of its - two operands.

- -
Arguments:
-

The two arguments to the 'or' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

The truth table used for the 'or' instruction is:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
In0In1Out
000
011
101
111
- -
Example:
-
-  <result> = or i32 4, %var         ; yields {i32}:result = 4 | %var
-  <result> = or i32 15, 40          ; yields {i32}:result = 47
-  <result> = or i32 4, 8            ; yields {i32}:result = 12
-
- -
- - -

- 'xor' Instruction -

- -
- -
Syntax:
-
-  <result> = xor <ty> <op1>, <op2>   ; yields {ty}:result
-
- -
Overview:
-

The 'xor' instruction returns the bitwise logical exclusive or of - its two operands. The xor is used to implement the "one's - complement" operation, which is the "~" operator in C.

- -
Arguments:
-

The two arguments to the 'xor' instruction must be - integer or vector of integer - values. Both arguments must have identical types.

- -
Semantics:
-

The truth table used for the 'xor' instruction is:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
In0In1Out
000
011
101
110
- -
Example:
-
-  <result> = xor i32 4, %var         ; yields {i32}:result = 4 ^ %var
-  <result> = xor i32 15, 40          ; yields {i32}:result = 39
-  <result> = xor i32 4, 8            ; yields {i32}:result = 12
-  <result> = xor i32 %V, -1          ; yields {i32}:result = ~%V
-
- -
- -
- - -

- Vector Operations -

- -
- -

LLVM supports several instructions to represent vector operations in a - target-independent manner. These instructions cover the element-access and - vector-specific operations needed to process vectors effectively. While LLVM - does directly support these vector operations, many sophisticated algorithms - will want to use target-specific intrinsics to take full advantage of a - specific target.

- - -

- 'extractelement' Instruction -

- -
- -
Syntax:
-
-  <result> = extractelement <n x <ty>> <val>, i32 <idx>    ; yields <ty>
-
- -
Overview:
-

The 'extractelement' instruction extracts a single scalar element - from a vector at a specified index.

- - -
Arguments:
-

The first operand of an 'extractelement' instruction is a value - of vector type. The second operand is an index - indicating the position from which to extract the element. The index may be - a variable.

- -
Semantics:
-

The result is a scalar of the same type as the element type of - val. Its value is the value at position idx of - val. If idx exceeds the length of val, the - results are undefined.

- -
Example:
-
-  <result> = extractelement <4 x i32> %vec, i32 0    ; yields i32
-
- -
- - -

- 'insertelement' Instruction -

- -
- -
Syntax:
-
-  <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx>    ; yields <n x <ty>>
-
- -
Overview:
-

The 'insertelement' instruction inserts a scalar element into a - vector at a specified index.

- -
Arguments:
-

The first operand of an 'insertelement' instruction is a value - of vector type. The second operand is a scalar value - whose type must equal the element type of the first operand. The third - operand is an index indicating the position at which to insert the value. - The index may be a variable.

- -
Semantics:
-

The result is a vector of the same type as val. Its element values - are those of val except at position idx, where it gets the - value elt. If idx exceeds the length of val, the - results are undefined.

- -
Example:
-
-  <result> = insertelement <4 x i32> %vec, i32 1, i32 0    ; yields <4 x i32>
-
- -
- - -

- 'shufflevector' Instruction -

- -
- -
Syntax:
-
-  <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    ; yields <m x <ty>>
-
- -
Overview:
-

The 'shufflevector' instruction constructs a permutation of elements - from two input vectors, returning a vector with the same element type as the - input and length that is the same as the shuffle mask.

- -
Arguments:
-

The first two operands of a 'shufflevector' instruction are vectors - with types that match each other. The third argument is a shuffle mask whose - element type is always 'i32'. The result of the instruction is a vector - whose length is the same as the shuffle mask and whose element type is the - same as the element type of the first two operands.

- -

The shuffle mask operand is required to be a constant vector with either - constant integer or undef values.

- -
Semantics:
-

The elements of the two input vectors are numbered from left to right across - both of the vectors. The shuffle mask operand specifies, for each element of - the result vector, which element of the two input vectors the result element - gets. The element selector may be undef (meaning "don't care") and the - second operand may be undef if performing a shuffle from only one vector.

- -
Example:
-
-  <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
-                          <4 x i32> <i32 0, i32 4, i32 1, i32 5>  ; yields <4 x i32>
-  <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
-                          <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32> - Identity shuffle.
-  <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
-                          <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32>
-  <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
-                          <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 >  ; yields <8 x i32>
-
- -
- -
- - -

- Aggregate Operations -

- -
- -

LLVM supports several instructions for working with - aggregate values.

- - -

- 'extractvalue' Instruction -

- -
- -
Syntax:
-
-  <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
-
- -
Overview:
-

The 'extractvalue' instruction extracts the value of a member field - from an aggregate value.

- -
Arguments:
-

The first operand of an 'extractvalue' instruction is a value - of struct or - array type. The operands are constant indices to - specify which value to extract in a similar manner as indices in a - 'getelementptr' instruction.

-

The major differences to getelementptr indexing are:

-
    -
  • Since the value being indexed is not a pointer, the first index is - omitted and assumed to be zero.
  • -
  • At least one index must be specified.
  • -
  • Not only struct indices but also array indices must be in - bounds.
  • -
- -
Semantics:
-

The result is the value at the position in the aggregate specified by the - index operands.

- -
Example:
-
-  <result> = extractvalue {i32, float} %agg, 0    ; yields i32
-
- -
- - -

- 'insertvalue' Instruction -

- -
- -
Syntax:
-
-  <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}*    ; yields <aggregate type>
-
- -
Overview:
-

The 'insertvalue' instruction inserts a value into a member field - in an aggregate value.

- -
Arguments:
-

The first operand of an 'insertvalue' instruction is a value - of struct or - array type. The second operand is a first-class - value to insert. The following operands are constant indices indicating - the position at which to insert the value in a similar manner as indices in a - 'extractvalue' instruction. The - value to insert must have the same type as the value identified by the - indices.

- -
Semantics:
-

The result is an aggregate of the same type as val. Its value is - that of val except that the value at the position specified by the - indices is that of elt.

- -
Example:
-
-  %agg1 = insertvalue {i32, float} undef, i32 1, 0              ; yields {i32 1, float undef}
-  %agg2 = insertvalue {i32, float} %agg1, float %val, 1         ; yields {i32 1, float %val}
-  %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0    ; yields {i32 1, float %val}
-
- -
- -
- - -

- Memory Access and Addressing Operations -

- -
- -

A key design point of an SSA-based representation is how it represents - memory. In LLVM, no memory locations are in SSA form, which makes things - very simple. This section describes how to read, write, and allocate - memory in LLVM.

- - -

- 'alloca' Instruction -

- -
- -
Syntax:
-
-  <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>]     ; yields {type*}:result
-
- -
Overview:
-

The 'alloca' instruction allocates memory on the stack frame of the - currently executing function, to be automatically released when this function - returns to its caller. The object is always allocated in the generic address - space (address space zero).

- -
Arguments:
-

The 'alloca' instruction - allocates sizeof(<type>)*NumElements bytes of memory on the - runtime stack, returning a pointer of the appropriate type to the program. - If "NumElements" is specified, it is the number of elements allocated, - otherwise "NumElements" is defaulted to be one. If a constant alignment is - specified, the value result of the allocation is guaranteed to be aligned to - at least that boundary. If not specified, or if zero, the target can choose - to align the allocation on any convenient boundary compatible with the - type.

- -

'type' may be any sized type.

- -
Semantics:
-

Memory is allocated; a pointer is returned. The operation is undefined if - there is insufficient stack space for the allocation. 'alloca'd - memory is automatically released when the function returns. The - 'alloca' instruction is commonly used to represent automatic - variables that must have an address available. When the function returns - (either with the ret - or resume instructions), the memory is - reclaimed. Allocating zero bytes is legal, but the result is undefined. - The order in which memory is allocated (ie., which way the stack grows) is - not specified.

- -

- -

Example:
-
-  %ptr = alloca i32                             ; yields {i32*}:ptr
-  %ptr = alloca i32, i32 4                      ; yields {i32*}:ptr
-  %ptr = alloca i32, i32 4, align 1024          ; yields {i32*}:ptr
-  %ptr = alloca i32, align 1024                 ; yields {i32*}:ptr
-
- -
- - -

- 'load' Instruction -

- -
- -
Syntax:
-
-  <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>]
-  <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
-  !<index> = !{ i32 1 }
-
- -
Overview:
-

The 'load' instruction is used to read from memory.

- -
Arguments:
-

The argument to the 'load' instruction specifies the memory address - from which to load. The pointer must point to - a first class type. If the load is - marked as volatile, then the optimizer is not allowed to modify the - number or order of execution of this load with other volatile operations.

- -

If the load is marked as atomic, it takes an extra - ordering and optional singlethread - argument. The release and acq_rel orderings are - not valid on load instructions. Atomic loads produce defined results when they may see multiple atomic - stores. The type of the pointee must be an integer type whose bit width - is a power of two greater than or equal to eight and less than or equal - to a target-specific size limit. align must be explicitly - specified on atomic loads, and the load has undefined behavior if the - alignment is not set to a value which is at least the size in bytes of - the pointee. !nontemporal does not have any defined semantics - for atomic loads.

- -

The optional constant align argument specifies the alignment of the - operation (that is, the alignment of the memory address). A value of 0 or an - omitted align argument means that the operation has the preferential - alignment for the target. It is the responsibility of the code emitter to - ensure that the alignment information is correct. Overestimating the - alignment results in undefined behavior. Underestimating the alignment may - produce less efficient code. An alignment of 1 is always safe.

- -

The optional !nontemporal metadata must reference a single - metatadata name <index> corresponding to a metadata node with - one i32 entry of value 1. The existence of - the !nontemporal metatadata on the instruction tells the optimizer - and code generator that this load is not expected to be reused in the cache. - The code generator may select special instructions to save cache bandwidth, - such as the MOVNT instruction on x86.

- -

The optional !invariant.load metadata must reference a single - metatadata name <index> corresponding to a metadata node with no - entries. The existence of the !invariant.load metatadata on the - instruction tells the optimizer and code generator that this load address - points to memory which does not change value during program execution. - The optimizer may then move this load around, for example, by hoisting it - out of loops using loop invariant code motion.

- -
Semantics:
-

The location of memory pointed to is loaded. If the value being loaded is of - scalar type then the number of bytes read does not exceed the minimum number - of bytes needed to hold all bits of the type. For example, loading an - i24 reads at most three bytes. When loading a value of a type like - i20 with a size that is not an integral number of bytes, the result - is undefined if the value was not originally written using a store of the - same type.

- -
Examples:
-
-  %ptr = alloca i32                               ; yields {i32*}:ptr
-  store i32 3, i32* %ptr                          ; yields {void}
-  %val = load i32* %ptr                           ; yields {i32}:val = i32 3
-
- -
- - -

- 'store' Instruction -

- -
- -
Syntax:
-
-  store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]        ; yields {void}
-  store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment>  ; yields {void}
-
- -
Overview:
-

The 'store' instruction is used to write to memory.

- -
Arguments:
-

There are two arguments to the 'store' instruction: a value to store - and an address at which to store it. The type of the - '<pointer>' operand must be a pointer to - the first class type of the - '<value>' operand. If the store is marked as - volatile, then the optimizer is not allowed to modify the number or - order of execution of this store with other volatile operations.

- -

If the store is marked as atomic, it takes an extra - ordering and optional singlethread - argument. The acquire and acq_rel orderings aren't - valid on store instructions. Atomic loads produce defined results when they may see multiple atomic - stores. The type of the pointee must be an integer type whose bit width - is a power of two greater than or equal to eight and less than or equal - to a target-specific size limit. align must be explicitly - specified on atomic stores, and the store has undefined behavior if the - alignment is not set to a value which is at least the size in bytes of - the pointee. !nontemporal does not have any defined semantics - for atomic stores.

- -

The optional constant "align" argument specifies the alignment of the - operation (that is, the alignment of the memory address). A value of 0 or an - omitted "align" argument means that the operation has the preferential - alignment for the target. It is the responsibility of the code emitter to - ensure that the alignment information is correct. Overestimating the - alignment results in an undefined behavior. Underestimating the alignment may - produce less efficient code. An alignment of 1 is always safe.

- -

The optional !nontemporal metadata must reference a single metatadata - name <index> corresponding to a metadata node with one i32 entry of - value 1. The existence of the !nontemporal metatadata on the - instruction tells the optimizer and code generator that this load is - not expected to be reused in the cache. The code generator may - select special instructions to save cache bandwidth, such as the - MOVNT instruction on x86.

- - -
Semantics:
-

The contents of memory are updated to contain '<value>' at the - location specified by the '<pointer>' operand. If - '<value>' is of scalar type then the number of bytes written - does not exceed the minimum number of bytes needed to hold all bits of the - type. For example, storing an i24 writes at most three bytes. When - writing a value of a type like i20 with a size that is not an - integral number of bytes, it is unspecified what happens to the extra bits - that do not belong to the type, but they will typically be overwritten.

- -
Example:
-
-  %ptr = alloca i32                               ; yields {i32*}:ptr
-  store i32 3, i32* %ptr                          ; yields {void}
-  %val = load i32* %ptr                           ; yields {i32}:val = i32 3
-
- -
- - -

-'fence' Instruction -

- -
- -
Syntax:
-
-  fence [singlethread] <ordering>                   ; yields {void}
-
- -
Overview:
-

The 'fence' instruction is used to introduce happens-before edges -between operations.

- -
Arguments:

'fence' instructions take an ordering argument which defines what -synchronizes-with edges they add. They can only be given -acquire, release, acq_rel, and -seq_cst orderings.

- -
Semantics:
-

A fence A which has (at least) release ordering -semantics synchronizes with a fence B with (at least) -acquire ordering semantics if and only if there exist atomic -operations X and Y, both operating on some atomic object -M, such that A is sequenced before X, -X modifies M (either directly or through some side effect -of a sequence headed by X), Y is sequenced before -B, and Y observes M. This provides a -happens-before dependency between A and B. Rather -than an explicit fence, one (but not both) of the atomic operations -X or Y might provide a release or -acquire (resp.) ordering constraint and still -synchronize-with the explicit fence and establish the -happens-before edge.

- -

A fence which has seq_cst ordering, in addition to -having both acquire and release semantics specified -above, participates in the global program order of other seq_cst -operations and/or fences.

- -

The optional "singlethread" argument -specifies that the fence only synchronizes with other fences in the same -thread. (This is useful for interacting with signal handlers.)

- -
Example:
-
-  fence acquire                          ; yields {void}
-  fence singlethread seq_cst             ; yields {void}
-
- -
- - -

-'cmpxchg' Instruction -

- -
- -
Syntax:
-
-  cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering>  ; yields {ty}
-
- -
Overview:
-

The 'cmpxchg' instruction is used to atomically modify memory. -It loads a value in memory and compares it to a given value. If they are -equal, it stores a new value into the memory.

- -
Arguments:
-

There are three arguments to the 'cmpxchg' instruction: an -address to operate on, a value to compare to the value currently be at that -address, and a new value to place at that address if the compared values are -equal. The type of '<cmp>' must be an integer type whose -bit width is a power of two greater than or equal to eight and less than -or equal to a target-specific size limit. '<cmp>' and -'<new>' must have the same type, and the type of -'<pointer>' must be a pointer to that type. If the -cmpxchg is marked as volatile, then the -optimizer is not allowed to modify the number or order of execution -of this cmpxchg with other volatile -operations.

- - - -

The ordering argument specifies how this -cmpxchg synchronizes with other atomic operations.

- -

The optional "singlethread" argument declares that the -cmpxchg is only atomic with respect to code (usually signal -handlers) running in the same thread as the cmpxchg. Otherwise the -cmpxchg is atomic with respect to all other code in the system.

- -

The pointer passed into cmpxchg must have alignment greater than or equal to -the size in memory of the operand. - -

Semantics:
-

The contents of memory at the location specified by the -'<pointer>' operand is read and compared to -'<cmp>'; if the read value is the equal, -'<new>' is written. The original value at the location -is returned. - -

A successful cmpxchg is a read-modify-write instruction for the -purpose of identifying release sequences. A -failed cmpxchg is equivalent to an atomic load with an ordering -parameter determined by dropping any release part of the -cmpxchg's ordering.

- - - -
Example:
-
-entry:
-  %orig = atomic load i32* %ptr unordered                   ; yields {i32}
-  br label %loop
-
-loop:
-  %cmp = phi i32 [ %orig, %entry ], [%old, %loop]
-  %squared = mul i32 %cmp, %cmp
-  %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared          ; yields {i32}
-  %success = icmp eq i32 %cmp, %old
-  br i1 %success, label %done, label %loop
-
-done:
-  ...
-
- -
- - -

-'atomicrmw' Instruction -

- -
- -
Syntax:
-
-  atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering>                   ; yields {ty}
-
- -
Overview:
-

The 'atomicrmw' instruction is used to atomically modify memory.

- -
Arguments:
-

There are three arguments to the 'atomicrmw' instruction: an -operation to apply, an address whose value to modify, an argument to the -operation. The operation must be one of the following keywords:

-
    -
  • xchg
  • -
  • add
  • -
  • sub
  • -
  • and
  • -
  • nand
  • -
  • or
  • -
  • xor
  • -
  • max
  • -
  • min
  • -
  • umax
  • -
  • umin
  • -
- -

The type of '<value>' must be an integer type whose -bit width is a power of two greater than or equal to eight and less than -or equal to a target-specific size limit. The type of the -'<pointer>' operand must be a pointer to that type. -If the atomicrmw is marked as volatile, then the -optimizer is not allowed to modify the number or order of execution of this -atomicrmw with other volatile - operations.

- - - -
Semantics:
-

The contents of memory at the location specified by the -'<pointer>' operand are atomically read, modified, and written -back. The original value at the location is returned. The modification is -specified by the operation argument:

- -
    -
  • xchg: *ptr = val
  • -
  • add: *ptr = *ptr + val
  • -
  • sub: *ptr = *ptr - val
  • -
  • and: *ptr = *ptr & val
  • -
  • nand: *ptr = ~(*ptr & val)
  • -
  • or: *ptr = *ptr | val
  • -
  • xor: *ptr = *ptr ^ val
  • -
  • max: *ptr = *ptr > val ? *ptr : val (using a signed comparison)
  • -
  • min: *ptr = *ptr < val ? *ptr : val (using a signed comparison)
  • -
  • umax: *ptr = *ptr > val ? *ptr : val (using an unsigned comparison)
  • -
  • umin: *ptr = *ptr < val ? *ptr : val (using an unsigned comparison)
  • -
- -
Example:
-
-  %old = atomicrmw add i32* %ptr, i32 1 acquire                        ; yields {i32}
-
- -
- - -

- 'getelementptr' Instruction -

- -
- -
Syntax:
-
-  <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
-  <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
-  <result> = getelementptr <ptr vector> ptrval, <vector index type> idx 
-
- -
Overview:
-

The 'getelementptr' instruction is used to get the address of a - subelement of an aggregate data structure. - It performs address calculation only and does not access memory.

- -
Arguments:
-

The first argument is always a pointer or a vector of pointers, - and forms the basis of the - calculation. The remaining arguments are indices that indicate which of the - elements of the aggregate object are indexed. The interpretation of each - index is dependent on the type being indexed into. The first index always - indexes the pointer value given as the first argument, the second index - indexes a value of the type pointed to (not necessarily the value directly - pointed to, since the first index can be non-zero), etc. The first type - indexed into must be a pointer value, subsequent types can be arrays, - vectors, and structs. Note that subsequent types being indexed into - can never be pointers, since that would require loading the pointer before - continuing calculation.

- -

The type of each index argument depends on the type it is indexing into. - When indexing into a (optionally packed) structure, only i32 - integer constants are allowed. When indexing into an array, pointer - or vector, integers of any width are allowed, and they are not required to be - constant. These integers are treated as signed values where relevant.

- -

For example, let's consider a C code fragment and how it gets compiled to - LLVM:

- -
-struct RT {
-  char A;
-  int B[10][20];
-  char C;
-};
-struct ST {
-  int X;
-  double Y;
-  struct RT Z;
-};
-
-int *foo(struct ST *s) {
-  return &s[1].Z.B[5][13];
-}
-
- -

The LLVM code generated by Clang is:

- -
-%struct.RT = type { i8, [10 x [20 x i32]], i8 }
-%struct.ST = type { i32, double, %struct.RT }
-
-define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
-entry:
-  %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
-  ret i32* %arrayidx
-}
-
- -
Semantics:
-

In the example above, the first index is indexing into the - '%struct.ST*' type, which is a pointer, yielding a - '%struct.ST' = '{ i32, double, %struct.RT }' type, a - structure. The second index indexes into the third element of the structure, - yielding a '%struct.RT' = '{ i8 , [10 x [20 x i32]], i8 }' - type, another structure. The third index indexes into the second element of - the structure, yielding a '[10 x [20 x i32]]' type, an array. The - two dimensions of the array are subscripted into, yielding an 'i32' - type. The 'getelementptr' instruction returns a pointer to this - element, thus computing a value of 'i32*' type.

- -

Note that it is perfectly legal to index partially through a structure, - returning a pointer to an inner element. Because of this, the LLVM code for - the given testcase is equivalent to:

- -
-define i32* @foo(%struct.ST* %s) {
-  %t1 = getelementptr %struct.ST* %s, i32 1                 ; yields %struct.ST*:%t1
-  %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2         ; yields %struct.RT*:%t2
-  %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1         ; yields [10 x [20 x i32]]*:%t3
-  %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  ; yields [20 x i32]*:%t4
-  %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        ; yields i32*:%t5
-  ret i32* %t5
-}
-
- -

If the inbounds keyword is present, the result value of the - getelementptr is a poison value if the - base pointer is not an in bounds address of an allocated object, - or if any of the addresses that would be formed by successive addition of - the offsets implied by the indices to the base address with infinitely - precise signed arithmetic are not an in bounds address of that - allocated object. The in bounds addresses for an allocated object - are all the addresses that point into the object, plus the address one - byte past the end. - In cases where the base is a vector of pointers the inbounds keyword - applies to each of the computations element-wise.

- -

If the inbounds keyword is not present, the offsets are added to - the base address with silently-wrapping two's complement arithmetic. If the - offsets have a different width from the pointer, they are sign-extended or - truncated to the width of the pointer. The result value of the - getelementptr may be outside the object pointed to by the base - pointer. The result value may not necessarily be used to access memory - though, even if it happens to point into allocated storage. See the - Pointer Aliasing Rules section for more - information.

- -

The getelementptr instruction is often confusing. For some more insight into - how it works, see the getelementptr FAQ.

- -
Example:
-
-    ; yields [12 x i8]*:aptr
-    %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
-    ; yields i8*:vptr
-    %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
-    ; yields i8*:eptr
-    %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
-    ; yields i32*:iptr
-    %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
-
- -

In cases where the pointer argument is a vector of pointers, only a - single index may be used, and the number of vector elements has to be - the same. For example:

-
- %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets,
-
- -
- -
- - -

- Conversion Operations -

- -
- -

The instructions in this category are the conversion instructions (casting) - which all take a single operand and a type. They perform various bit - conversions on the operand.

- - -

- 'trunc .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = trunc <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'trunc' instruction truncates its operand to the - type ty2.

- -
Arguments:
-

The 'trunc' instruction takes a value to trunc, and a type to trunc it to. - Both types must be of integer types, or vectors - of the same number of integers. - The bit size of the value must be larger than - the bit size of the destination type, ty2. - Equal sized types are not allowed.

- -
Semantics:
-

The 'trunc' instruction truncates the high order bits - in value and converts the remaining bits to ty2. Since the - source size must be larger than the destination size, trunc cannot - be a no-op cast. It will always truncate bits.

- -
Example:
-
-  %X = trunc i32 257 to i8                        ; yields i8:1
-  %Y = trunc i32 123 to i1                        ; yields i1:true
-  %Z = trunc i32 122 to i1                        ; yields i1:false
-  %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
-
- -
- - -

- 'zext .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = zext <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'zext' instruction zero extends its operand to type - ty2.

- - -
Arguments:
-

The 'zext' instruction takes a value to cast, and a type to cast it to. - Both types must be of integer types, or vectors - of the same number of integers. - The bit size of the value must be smaller than - the bit size of the destination type, - ty2.

- -
Semantics:
-

The zext fills the high order bits of the value with zero - bits until it reaches the size of the destination type, ty2.

- -

When zero extending from i1, the result will always be either 0 or 1.

- -
Example:
-
-  %X = zext i32 257 to i64              ; yields i64:257
-  %Y = zext i1 true to i32              ; yields i32:1
-  %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
-
- -
- - -

- 'sext .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = sext <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'sext' sign extends value to the type ty2.

- -
Arguments:
-

The 'sext' instruction takes a value to cast, and a type to cast it to. - Both types must be of integer types, or vectors - of the same number of integers. - The bit size of the value must be smaller than - the bit size of the destination type, - ty2.

- -
Semantics:
-

The 'sext' instruction performs a sign extension by copying the sign - bit (highest order bit) of the value until it reaches the bit size - of the type ty2.

- -

When sign extending from i1, the extension always results in -1 or 0.

- -
Example:
-
-  %X = sext i8  -1 to i16              ; yields i16   :65535
-  %Y = sext i1 true to i32             ; yields i32:-1
-  %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
-
- -
- - -

- 'fptrunc .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = fptrunc <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'fptrunc' instruction truncates value to type - ty2.

- -
Arguments:
-

The 'fptrunc' instruction takes a floating - point value to cast and a floating point type - to cast it to. The size of value must be larger than the size of - ty2. This implies that fptrunc cannot be used to make a - no-op cast.

- -
Semantics:
-

The 'fptrunc' instruction truncates a value from a larger - floating point type to a smaller - floating point type. If the value cannot fit - within the destination type, ty2, then the results are - undefined.

- -
Example:
-
-  %X = fptrunc double 123.0 to float         ; yields float:123.0
-  %Y = fptrunc double 1.0E+300 to float      ; yields undefined
-
- -
- - -

- 'fpext .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = fpext <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'fpext' extends a floating point value to a larger - floating point value.

- -
Arguments:
-

The 'fpext' instruction takes a - floating point value to cast, and - a floating point type to cast it to. The source - type must be smaller than the destination type.

- -
Semantics:
-

The 'fpext' instruction extends the value from a smaller - floating point type to a larger - floating point type. The fpext cannot be - used to make a no-op cast because it always changes bits. Use - bitcast to make a no-op cast for a floating point cast.

- -
Example:
-
-  %X = fpext float 3.125 to double         ; yields double:3.125000e+00
-  %Y = fpext double %X to fp128            ; yields fp128:0xL00000000000000004000900000000000
-
- -
- - -

- 'fptoui .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = fptoui <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'fptoui' converts a floating point value to its - unsigned integer equivalent of type ty2.

- -
Arguments:
-

The 'fptoui' instruction takes a value to cast, which must be a - scalar or vector floating point value, and a type - to cast it to ty2, which must be an integer - type. If ty is a vector floating point type, ty2 must be a - vector integer type with the same number of elements as ty

- -
Semantics:
-

The 'fptoui' instruction converts its - floating point operand into the nearest (rounding - towards zero) unsigned integer value. If the value cannot fit - in ty2, the results are undefined.

- -
Example:
-
-  %X = fptoui double 123.0 to i32      ; yields i32:123
-  %Y = fptoui float 1.0E+300 to i1     ; yields undefined:1
-  %Z = fptoui float 1.04E+17 to i8     ; yields undefined:1
-
- -
- - -

- 'fptosi .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = fptosi <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'fptosi' instruction converts - floating point value to - type ty2.

- -
Arguments:
-

The 'fptosi' instruction takes a value to cast, which must be a - scalar or vector floating point value, and a type - to cast it to ty2, which must be an integer - type. If ty is a vector floating point type, ty2 must be a - vector integer type with the same number of elements as ty

- -
Semantics:
-

The 'fptosi' instruction converts its - floating point operand into the nearest (rounding - towards zero) signed integer value. If the value cannot fit in ty2, - the results are undefined.

- -
Example:
-
-  %X = fptosi double -123.0 to i32      ; yields i32:-123
-  %Y = fptosi float 1.0E-247 to i1      ; yields undefined:1
-  %Z = fptosi float 1.04E+17 to i8      ; yields undefined:1
-
- -
- - -

- 'uitofp .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = uitofp <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'uitofp' instruction regards value as an unsigned - integer and converts that value to the ty2 type.

- -
Arguments:
-

The 'uitofp' instruction takes a value to cast, which must be a - scalar or vector integer value, and a type to cast - it to ty2, which must be an floating point - type. If ty is a vector integer type, ty2 must be a vector - floating point type with the same number of elements as ty

- -
Semantics:
-

The 'uitofp' instruction interprets its operand as an unsigned - integer quantity and converts it to the corresponding floating point - value. If the value cannot fit in the floating point value, the results are - undefined.

- -
Example:
-
-  %X = uitofp i32 257 to float         ; yields float:257.0
-  %Y = uitofp i8 -1 to double          ; yields double:255.0
-
- -
- - -

- 'sitofp .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = sitofp <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'sitofp' instruction regards value as a signed integer - and converts that value to the ty2 type.

- -
Arguments:
-

The 'sitofp' instruction takes a value to cast, which must be a - scalar or vector integer value, and a type to cast - it to ty2, which must be an floating point - type. If ty is a vector integer type, ty2 must be a vector - floating point type with the same number of elements as ty

- -
Semantics:
-

The 'sitofp' instruction interprets its operand as a signed integer - quantity and converts it to the corresponding floating point value. If the - value cannot fit in the floating point value, the results are undefined.

- -
Example:
-
-  %X = sitofp i32 257 to float         ; yields float:257.0
-  %Y = sitofp i8 -1 to double          ; yields double:-1.0
-
- -
- - -

- 'ptrtoint .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = ptrtoint <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'ptrtoint' instruction converts the pointer or a vector of - pointers value to - the integer (or vector of integers) type ty2.

- -
Arguments:
-

The 'ptrtoint' instruction takes a value to cast, which - must be a a value of type pointer or a vector of - pointers, and a type to cast it to - ty2, which must be an integer or a vector - of integers type.

- -
Semantics:
-

The 'ptrtoint' instruction converts value to integer type - ty2 by interpreting the pointer value as an integer and either - truncating or zero extending that value to the size of the integer type. If - value is smaller than ty2 then a zero extension is done. If - value is larger than ty2 then a truncation is done. If they - are the same size, then nothing is done (no-op cast) other than a type - change.

- -
Example:
-
-  %X = ptrtoint i32* %P to i8                         ; yields truncation on 32-bit architecture
-  %Y = ptrtoint i32* %P to i64                        ; yields zero extension on 32-bit architecture
-  %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
-
- -
- - -

- 'inttoptr .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = inttoptr <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'inttoptr' instruction converts an integer value to a - pointer type, ty2.

- -
Arguments:
-

The 'inttoptr' instruction takes an integer - value to cast, and a type to cast it to, which must be a - pointer type.

- -
Semantics:
-

The 'inttoptr' instruction converts value to type - ty2 by applying either a zero extension or a truncation depending on - the size of the integer value. If value is larger than the - size of a pointer then a truncation is done. If value is smaller - than the size of a pointer then a zero extension is done. If they are the - same size, nothing is done (no-op cast).

- -
Example:
-
-  %X = inttoptr i32 255 to i32*          ; yields zero extension on 64-bit architecture
-  %Y = inttoptr i32 255 to i32*          ; yields no-op on 32-bit architecture
-  %Z = inttoptr i64 0 to i32*            ; yields truncation on 32-bit architecture
-  %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers
-
- -
- - -

- 'bitcast .. to' Instruction -

- -
- -
Syntax:
-
-  <result> = bitcast <ty> <value> to <ty2>             ; yields ty2
-
- -
Overview:
-

The 'bitcast' instruction converts value to type - ty2 without changing any bits.

- -
Arguments:
-

The 'bitcast' instruction takes a value to cast, which must be a - non-aggregate first class value, and a type to cast it to, which must also be - a non-aggregate first class type. The bit sizes - of value and the destination type, ty2, must be - identical. If the source type is a pointer, the destination type must also be - a pointer. This instruction supports bitwise conversion of vectors to - integers and to vectors of other types (as long as they have the same - size).

- -
Semantics:
-

The 'bitcast' instruction converts value to type - ty2. It is always a no-op cast because no bits change with - this conversion. The conversion is done as if the value had been - stored to memory and read back as type ty2. - Pointer (or vector of pointers) types may only be converted to other pointer - (or vector of pointers) types with this instruction. To convert - pointers to other types, use the inttoptr or - ptrtoint instructions first.

- -
Example:
-
-  %X = bitcast i8 255 to i8              ; yields i8 :-1
-  %Y = bitcast i32* %x to sint*          ; yields sint*:%x
-  %Z = bitcast <2 x int> %V to i64;        ; yields i64: %V
-  %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
-
- -
- -
- - -

- Other Operations -

- -
- -

The instructions in this category are the "miscellaneous" instructions, which - defy better classification.

- - -

- 'icmp' Instruction -

- -
- -
Syntax:
-
-  <result> = icmp <cond> <ty> <op1>, <op2>   ; yields {i1} or {<N x i1>}:result
-
- -
Overview:
-

The 'icmp' instruction returns a boolean value or a vector of - boolean values based on comparison of its two integer, integer vector, - pointer, or pointer vector operands.

- -
Arguments:
-

The 'icmp' instruction takes three operands. The first operand is - the condition code indicating the kind of comparison to perform. It is not a - value, just a keyword. The possible condition code are:

- -
    -
  1. eq: equal
  2. -
  3. ne: not equal
  4. -
  5. ugt: unsigned greater than
  6. -
  7. uge: unsigned greater or equal
  8. -
  9. ult: unsigned less than
  10. -
  11. ule: unsigned less or equal
  12. -
  13. sgt: signed greater than
  14. -
  15. sge: signed greater or equal
  16. -
  17. slt: signed less than
  18. -
  19. sle: signed less or equal
  20. -
- -

The remaining two arguments must be integer or - pointer or integer vector - typed. They must also be identical types.

- -
Semantics:
-

The 'icmp' compares op1 and op2 according to the - condition code given as cond. The comparison performed always yields - either an i1 or vector of i1 - result, as follows:

- -
    -
  1. eq: yields true if the operands are equal, - false otherwise. No sign interpretation is necessary or - performed.
  2. - -
  3. ne: yields true if the operands are unequal, - false otherwise. No sign interpretation is necessary or - performed.
  4. - -
  5. ugt: interprets the operands as unsigned values and yields - true if op1 is greater than op2.
  6. - -
  7. uge: interprets the operands as unsigned values and yields - true if op1 is greater than or equal - to op2.
  8. - -
  9. ult: interprets the operands as unsigned values and yields - true if op1 is less than op2.
  10. - -
  11. ule: interprets the operands as unsigned values and yields - true if op1 is less than or equal to op2.
  12. - -
  13. sgt: interprets the operands as signed values and yields - true if op1 is greater than op2.
  14. - -
  15. sge: interprets the operands as signed values and yields - true if op1 is greater than or equal - to op2.
  16. - -
  17. slt: interprets the operands as signed values and yields - true if op1 is less than op2.
  18. - -
  19. sle: interprets the operands as signed values and yields - true if op1 is less than or equal to op2.
  20. -
- -

If the operands are pointer typed, the pointer - values are compared as if they were integers.

- -

If the operands are integer vectors, then they are compared element by - element. The result is an i1 vector with the same number of elements - as the values being compared. Otherwise, the result is an i1.

- -
Example:
-
-  <result> = icmp eq i32 4, 5          ; yields: result=false
-  <result> = icmp ne float* %X, %X     ; yields: result=false
-  <result> = icmp ult i16  4, 5        ; yields: result=true
-  <result> = icmp sgt i16  4, 5        ; yields: result=false
-  <result> = icmp ule i16 -4, 5        ; yields: result=false
-  <result> = icmp sge i16  4, 5        ; yields: result=false
-
- -

Note that the code generator does not yet support vector types with - the icmp instruction.

- -
- - -

- 'fcmp' Instruction -

- -
- -
Syntax:
-
-  <result> = fcmp <cond> <ty> <op1>, <op2>     ; yields {i1} or {<N x i1>}:result
-
- -
Overview:
-

The 'fcmp' instruction returns a boolean value or vector of boolean - values based on comparison of its operands.

- -

If the operands are floating point scalars, then the result type is a boolean -(i1).

- -

If the operands are floating point vectors, then the result type is a vector - of boolean with the same number of elements as the operands being - compared.

- -
Arguments:
-

The 'fcmp' instruction takes three operands. The first operand is - the condition code indicating the kind of comparison to perform. It is not a - value, just a keyword. The possible condition code are:

- -
    -
  1. false: no comparison, always returns false
  2. -
  3. oeq: ordered and equal
  4. -
  5. ogt: ordered and greater than
  6. -
  7. oge: ordered and greater than or equal
  8. -
  9. olt: ordered and less than
  10. -
  11. ole: ordered and less than or equal
  12. -
  13. one: ordered and not equal
  14. -
  15. ord: ordered (no nans)
  16. -
  17. ueq: unordered or equal
  18. -
  19. ugt: unordered or greater than
  20. -
  21. uge: unordered or greater than or equal
  22. -
  23. ult: unordered or less than
  24. -
  25. ule: unordered or less than or equal
  26. -
  27. une: unordered or not equal
  28. -
  29. uno: unordered (either nans)
  30. -
  31. true: no comparison, always returns true
  32. -
- -

Ordered means that neither operand is a QNAN while - unordered means that either operand may be a QNAN.

- -

Each of val1 and val2 arguments must be either - a floating point type or - a vector of floating point type. They must have - identical types.

- -
Semantics:
-

The 'fcmp' instruction compares op1 and op2 - according to the condition code given as cond. If the operands are - vectors, then the vectors are compared element by element. Each comparison - performed always yields an i1 result, as - follows:

- -
    -
  1. false: always yields false, regardless of operands.
  2. - -
  3. oeq: yields true if both operands are not a QNAN and - op1 is equal to op2.
  4. - -
  5. ogt: yields true if both operands are not a QNAN and - op1 is greater than op2.
  6. - -
  7. oge: yields true if both operands are not a QNAN and - op1 is greater than or equal to op2.
  8. - -
  9. olt: yields true if both operands are not a QNAN and - op1 is less than op2.
  10. - -
  11. ole: yields true if both operands are not a QNAN and - op1 is less than or equal to op2.
  12. - -
  13. one: yields true if both operands are not a QNAN and - op1 is not equal to op2.
  14. - -
  15. ord: yields true if both operands are not a QNAN.
  16. - -
  17. ueq: yields true if either operand is a QNAN or - op1 is equal to op2.
  18. - -
  19. ugt: yields true if either operand is a QNAN or - op1 is greater than op2.
  20. - -
  21. uge: yields true if either operand is a QNAN or - op1 is greater than or equal to op2.
  22. - -
  23. ult: yields true if either operand is a QNAN or - op1 is less than op2.
  24. - -
  25. ule: yields true if either operand is a QNAN or - op1 is less than or equal to op2.
  26. - -
  27. une: yields true if either operand is a QNAN or - op1 is not equal to op2.
  28. - -
  29. uno: yields true if either operand is a QNAN.
  30. - -
  31. true: always yields true, regardless of operands.
  32. -
- -
Example:
-
-  <result> = fcmp oeq float 4.0, 5.0    ; yields: result=false
-  <result> = fcmp one float 4.0, 5.0    ; yields: result=true
-  <result> = fcmp olt float 4.0, 5.0    ; yields: result=true
-  <result> = fcmp ueq double 1.0, 2.0   ; yields: result=false
-
- -

Note that the code generator does not yet support vector types with - the fcmp instruction.

- -
- - -

- 'phi' Instruction -

- -
- -
Syntax:
-
-  <result> = phi <ty> [ <val0>, <label0>], ...
-
- -
Overview:
-

The 'phi' instruction is used to implement the φ node in the - SSA graph representing the function.

- -
Arguments:
-

The type of the incoming values is specified with the first type field. After - this, the 'phi' instruction takes a list of pairs as arguments, with - one pair for each predecessor basic block of the current block. Only values - of first class type may be used as the value - arguments to the PHI node. Only labels may be used as the label - arguments.

- -

There must be no non-phi instructions between the start of a basic block and - the PHI instructions: i.e. PHI instructions must be first in a basic - block.

- -

For the purposes of the SSA form, the use of each incoming value is deemed to - occur on the edge from the corresponding predecessor block to the current - block (but after any definition of an 'invoke' instruction's return - value on the same edge).

- -
Semantics:
-

At runtime, the 'phi' instruction logically takes on the value - specified by the pair corresponding to the predecessor basic block that - executed just prior to the current block.

- -
Example:
-
-Loop:       ; Infinite loop that counts from 0 on up...
-  %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
-  %nextindvar = add i32 %indvar, 1
-  br label %Loop
-
- -
- - -

- 'select' Instruction -

- -
- -
Syntax:
-
-  <result> = select selty <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
-
-  selty is either i1 or {<N x i1>}
-
- -
Overview:
-

The 'select' instruction is used to choose one value based on a - condition, without branching.

- - -
Arguments:
-

The 'select' instruction requires an 'i1' value or a vector of 'i1' - values indicating the condition, and two values of the - same first class type. If the val1/val2 are - vectors and the condition is a scalar, then entire vectors are selected, not - individual elements.

- -
Semantics:
-

If the condition is an i1 and it evaluates to 1, the instruction returns the - first value argument; otherwise, it returns the second value argument.

- -

If the condition is a vector of i1, then the value arguments must be vectors - of the same size, and the selection is done element by element.

- -
Example:
-
-  %X = select i1 true, i8 17, i8 42          ; yields i8:17
-
- -
- - -

- 'call' Instruction -

- -
- -
Syntax:
-
-  <result> = [tail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
-
- -
Overview:
-

The 'call' instruction represents a simple function call.

- -
Arguments:
-

This instruction requires several arguments:

- -
    -
  1. The optional "tail" marker indicates that the callee function does not - access any allocas or varargs in the caller. Note that calls may be - marked "tail" even if they do not occur before - a ret instruction. If the "tail" marker is - present, the function call is eligible for tail call optimization, - but might not in fact be - optimized into a jump. The code generator may optimize calls marked - "tail" with either 1) automatic - sibling call optimization when the caller and callee have - matching signatures, or 2) forced tail call optimization when the - following extra requirements are met: -
      -
    • Caller and callee both have the calling - convention fastcc.
    • -
    • The call is in tail position (ret immediately follows call and ret - uses value of call or is void).
    • -
    • Option -tailcallopt is enabled, - or llvm::GuaranteedTailCallOpt is true.
    • -
    • Platform specific - constraints are met.
    • -
    -
  2. - -
  3. The optional "cconv" marker indicates which calling - convention the call should use. If none is specified, the call - defaults to using C calling conventions. The calling convention of the - call must match the calling convention of the target function, or else the - behavior is undefined.
  4. - -
  5. The optional Parameter Attributes list for - return values. Only 'zeroext', 'signext', and - 'inreg' attributes are valid here.
  6. - -
  7. 'ty': the type of the call instruction itself which is also the - type of the return value. Functions that return no value are marked - void.
  8. - -
  9. 'fnty': shall be the signature of the pointer to function value - being invoked. The argument types must match the types implied by this - signature. This type can be omitted if the function is not varargs and if - the function type does not return a pointer to a function.
  10. - -
  11. 'fnptrval': An LLVM value containing a pointer to a function to - be invoked. In most cases, this is a direct function invocation, but - indirect calls are just as possible, calling an arbitrary pointer - to function value.
  12. - -
  13. 'function args': argument list whose types match the function - signature argument types and parameter attributes. All arguments must be - of first class type. If the function - signature indicates the function accepts a variable number of arguments, - the extra arguments can be specified.
  14. - -
  15. The optional function attributes list. Only - 'noreturn', 'nounwind', 'readonly' and - 'readnone' attributes are valid here.
  16. -
- -
Semantics:
-

The 'call' instruction is used to cause control flow to transfer to - a specified function, with its incoming arguments bound to the specified - values. Upon a 'ret' instruction in the called - function, control flow continues with the instruction after the function - call, and the return value of the function is bound to the result - argument.

- -
Example:
-
-  %retval = call i32 @test(i32 %argc)
-  call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42)        ; yields i32
-  %X = tail call i32 @foo()                                    ; yields i32
-  %Y = tail call fastcc i32 @foo()  ; yields i32
-  call void %foo(i8 97 signext)
-
-  %struct.A = type { i32, i8 }
-  %r = call %struct.A @foo()                        ; yields { 32, i8 }
-  %gr = extractvalue %struct.A %r, 0                ; yields i32
-  %gr1 = extractvalue %struct.A %r, 1               ; yields i8
-  %Z = call void @foo() noreturn                    ; indicates that %foo never returns normally
-  %ZZ = call zeroext i32 @bar()                     ; Return value is %zero extended
-
- -

llvm treats calls to some functions with names and arguments that match the -standard C99 library as being the C99 library functions, and may perform -optimizations or generate code for them under that assumption. This is -something we'd like to change in the future to provide better support for -freestanding environments and non-C-based languages.

- -
- - -

- 'va_arg' Instruction -

- -
- -
Syntax:
-
-  <resultval> = va_arg <va_list*> <arglist>, <argty>
-
- -
Overview:
-

The 'va_arg' instruction is used to access arguments passed through - the "variable argument" area of a function call. It is used to implement the - va_arg macro in C.

- -
Arguments:
-

This instruction takes a va_list* value and the type of the - argument. It returns a value of the specified argument type and increments - the va_list to point to the next argument. The actual type - of va_list is target specific.

- -
Semantics:
-

The 'va_arg' instruction loads an argument of the specified type - from the specified va_list and causes the va_list to point - to the next argument. For more information, see the variable argument - handling Intrinsic Functions.

- -

It is legal for this instruction to be called in a function which does not - take a variable number of arguments, for example, the vfprintf - function.

- -

va_arg is an LLVM instruction instead of - an intrinsic function because it takes a type as an - argument.

- -
Example:
-

See the variable argument processing section.

- -

Note that the code generator does not yet fully support va_arg on many - targets. Also, it does not currently support va_arg with aggregate types on - any target.

- -
- - -

- 'landingpad' Instruction -

- -
- -
Syntax:
-
-  <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
-  <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*
-
-  <clause> := catch <type> <value>
-  <clause> := filter <array constant type> <array constant>
-
- -
Overview:
-

The 'landingpad' instruction is used by - LLVM's exception handling - system to specify that a basic block is a landing pad — one where - the exception lands, and corresponds to the code found in the - catch portion of a try/catch sequence. It - defines values supplied by the personality function (pers_fn) upon - re-entry to the function. The resultval has the - type resultty.

- -
Arguments:
-

This instruction takes a pers_fn value. This is the personality - function associated with the unwinding mechanism. The optional - cleanup flag indicates that the landing pad block is a cleanup.

- -

A clause begins with the clause type — catch - or filter — and contains the global variable representing the - "type" that may be caught or filtered respectively. Unlike the - catch clause, the filter clause takes an array constant as - its argument. Use "[0 x i8**] undef" for a filter which cannot - throw. The 'landingpad' instruction must contain at least - one clause or the cleanup flag.

- -
Semantics:
-

The 'landingpad' instruction defines the values which are set by the - personality function (pers_fn) upon re-entry to the function, and - therefore the "result type" of the landingpad instruction. As with - calling conventions, how the personality function results are represented in - LLVM IR is target specific.

- -

The clauses are applied in order from top to bottom. If two - landingpad instructions are merged together through inlining, the - clauses from the calling function are appended to the list of clauses. - When the call stack is being unwound due to an exception being thrown, the - exception is compared against each clause in turn. If it doesn't - match any of the clauses, and the cleanup flag is not set, then - unwinding continues further up the call stack.

- -

The landingpad instruction has several restrictions:

- -
    -
  • A landing pad block is a basic block which is the unwind destination of an - 'invoke' instruction.
  • -
  • A landing pad block must have a 'landingpad' instruction as its - first non-PHI instruction.
  • -
  • There can be only one 'landingpad' instruction within the landing - pad block.
  • -
  • A basic block that is not a landing pad block may not include a - 'landingpad' instruction.
  • -
  • All 'landingpad' instructions in a function must have the same - personality function.
  • -
- -
Example:
-
-  ;; A landing pad which can catch an integer.
-  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
-           catch i8** @_ZTIi
-  ;; A landing pad that is a cleanup.
-  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
-           cleanup
-  ;; A landing pad which can catch an integer and can only throw a double.
-  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
-           catch i8** @_ZTIi
-           filter [1 x i8**] [@_ZTId]
-
- -
- -
- -
- - -

Intrinsic Functions

- - -
- -

LLVM supports the notion of an "intrinsic function". These functions have - well known names and semantics and are required to follow certain - restrictions. Overall, these intrinsics represent an extension mechanism for - the LLVM language that does not require changing all of the transformations - in LLVM when adding to the language (or the bitcode reader/writer, the - parser, etc...).

- -

Intrinsic function names must all start with an "llvm." prefix. This - prefix is reserved in LLVM for intrinsic names; thus, function names may not - begin with this prefix. Intrinsic functions must always be external - functions: you cannot define the body of intrinsic functions. Intrinsic - functions may only be used in call or invoke instructions: it is illegal to - take the address of an intrinsic function. Additionally, because intrinsic - functions are part of the LLVM language, it is required if any are added that - they be documented here.

- -

Some intrinsic functions can be overloaded, i.e., the intrinsic represents a - family of functions that perform the same operation but on different data - types. Because LLVM can represent over 8 million different integer types, - overloading is used commonly to allow an intrinsic function to operate on any - integer type. One or more of the argument types or the result type can be - overloaded to accept any integer type. Argument types may also be defined as - exactly matching a previous argument's type or the result type. This allows - an intrinsic function which accepts multiple arguments, but needs all of them - to be of the same type, to only be overloaded with respect to a single - argument or the result.

- -

Overloaded intrinsics will have the names of its overloaded argument types - encoded into its function name, each preceded by a period. Only those types - which are overloaded result in a name suffix. Arguments whose type is matched - against another type do not. For example, the llvm.ctpop function - can take an integer of any width and returns an integer of exactly the same - integer width. This leads to a family of functions such as - i8 @llvm.ctpop.i8(i8 %val) and i29 @llvm.ctpop.i29(i29 - %val). Only one type, the return type, is overloaded, and only one type - suffix is required. Because the argument's type is matched against the return - type, it does not require its own name suffix.

- -

To learn how to add an intrinsic function, please see the - Extending LLVM Guide.

- - -

- Variable Argument Handling Intrinsics -

- -
- -

Variable argument support is defined in LLVM with - the va_arg instruction and these three - intrinsic functions. These functions are related to the similarly named - macros defined in the <stdarg.h> header file.

- -

All of these functions operate on arguments that use a target-specific value - type "va_list". The LLVM assembly language reference manual does - not define what this type is, so all transformations should be prepared to - handle these functions regardless of the type used.

- -

This example shows how the va_arg - instruction and the variable argument handling intrinsic functions are - used.

- -
-define i32 @test(i32 %X, ...) {
-  ; Initialize variable argument processing
-  %ap = alloca i8*
-  %ap2 = bitcast i8** %ap to i8*
-  call void @llvm.va_start(i8* %ap2)
-
-  ; Read a single integer argument
-  %tmp = va_arg i8** %ap, i32
-
-  ; Demonstrate usage of llvm.va_copy and llvm.va_end
-  %aq = alloca i8*
-  %aq2 = bitcast i8** %aq to i8*
-  call void @llvm.va_copy(i8* %aq2, i8* %ap2)
-  call void @llvm.va_end(i8* %aq2)
-
-  ; Stop processing of arguments.
-  call void @llvm.va_end(i8* %ap2)
-  ret i32 %tmp
-}
-
-declare void @llvm.va_start(i8*)
-declare void @llvm.va_copy(i8*, i8*)
-declare void @llvm.va_end(i8*)
-
- - -

- 'llvm.va_start' Intrinsic -

- - -
- -
Syntax:
-
-  declare void %llvm.va_start(i8* <arglist>)
-
- -
Overview:
-

The 'llvm.va_start' intrinsic initializes *<arglist> - for subsequent use by va_arg.

- -
Arguments:
-

The argument is a pointer to a va_list element to initialize.

- -
Semantics:
-

The 'llvm.va_start' intrinsic works just like the va_start - macro available in C. In a target-dependent way, it initializes - the va_list element to which the argument points, so that the next - call to va_arg will produce the first variable argument passed to - the function. Unlike the C va_start macro, this intrinsic does not - need to know the last argument of the function as the compiler can figure - that out.

- -
- - -

- 'llvm.va_end' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.va_end(i8* <arglist>)
-
- -
Overview:
-

The 'llvm.va_end' intrinsic destroys *<arglist>, - which has been initialized previously - with llvm.va_start - or llvm.va_copy.

- -
Arguments:
-

The argument is a pointer to a va_list to destroy.

- -
Semantics:
-

The 'llvm.va_end' intrinsic works just like the va_end - macro available in C. In a target-dependent way, it destroys - the va_list element to which the argument points. Calls - to llvm.va_start - and llvm.va_copy must be matched exactly - with calls to llvm.va_end.

- -
- - -

- 'llvm.va_copy' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
-
- -
Overview:
-

The 'llvm.va_copy' intrinsic copies the current argument position - from the source argument list to the destination argument list.

- -
Arguments:
-

The first argument is a pointer to a va_list element to initialize. - The second argument is a pointer to a va_list element to copy - from.

- -
Semantics:
-

The 'llvm.va_copy' intrinsic works just like the va_copy - macro available in C. In a target-dependent way, it copies the - source va_list element into the destination va_list - element. This intrinsic is necessary because - the llvm.va_start intrinsic may be - arbitrarily complex and require, for example, memory allocation.

- -
- -
- - -

- Accurate Garbage Collection Intrinsics -

- -
- -

LLVM support for Accurate Garbage -Collection (GC) requires the implementation and generation of these -intrinsics. These intrinsics allow identification of GC -roots on the stack, as well as garbage collector implementations that -require read and write -barriers. Front-ends for type-safe garbage collected languages should generate -these intrinsics to make use of the LLVM garbage collectors. For more details, -see Accurate Garbage Collection with -LLVM.

- -

The garbage collection intrinsics only operate on objects in the generic - address space (address space zero).

- - -

- 'llvm.gcroot' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
-
- -
Overview:
-

The 'llvm.gcroot' intrinsic declares the existence of a GC root to - the code generator, and allows some metadata to be associated with it.

- -
Arguments:
-

The first argument specifies the address of a stack object that contains the - root pointer. The second pointer (which must be either a constant or a - global value address) contains the meta-data to be associated with the - root.

- -
Semantics:
-

At runtime, a call to this intrinsic stores a null pointer into the "ptrloc" - location. At compile-time, the code generator generates information to allow - the runtime to find the pointer at GC safe points. The 'llvm.gcroot' - intrinsic may only be used in a function which specifies a GC - algorithm.

- -
- - -

- 'llvm.gcread' Intrinsic -

- -
- -
Syntax:
-
-  declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
-
- -
Overview:
-

The 'llvm.gcread' intrinsic identifies reads of references from heap - locations, allowing garbage collector implementations that require read - barriers.

- -
Arguments:
-

The second argument is the address to read from, which should be an address - allocated from the garbage collector. The first object is a pointer to the - start of the referenced object, if needed by the language runtime (otherwise - null).

- -
Semantics:
-

The 'llvm.gcread' intrinsic has the same semantics as a load - instruction, but may be replaced with substantially more complex code by the - garbage collector runtime, as needed. The 'llvm.gcread' intrinsic - may only be used in a function which specifies a GC - algorithm.

- -
- - -

- 'llvm.gcwrite' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
-
- -
Overview:
-

The 'llvm.gcwrite' intrinsic identifies writes of references to heap - locations, allowing garbage collector implementations that require write - barriers (such as generational or reference counting collectors).

- -
Arguments:
-

The first argument is the reference to store, the second is the start of the - object to store it to, and the third is the address of the field of Obj to - store to. If the runtime does not require a pointer to the object, Obj may - be null.

- -
Semantics:
-

The 'llvm.gcwrite' intrinsic has the same semantics as a store - instruction, but may be replaced with substantially more complex code by the - garbage collector runtime, as needed. The 'llvm.gcwrite' intrinsic - may only be used in a function which specifies a GC - algorithm.

- -
- -
- - -

- Code Generator Intrinsics -

- -
- -

These intrinsics are provided by LLVM to expose special features that may - only be implemented with code generator support.

- - -

- 'llvm.returnaddress' Intrinsic -

- -
- -
Syntax:
-
-  declare i8  *@llvm.returnaddress(i32 <level>)
-
- -
Overview:
-

The 'llvm.returnaddress' intrinsic attempts to compute a - target-specific value indicating the return address of the current function - or one of its callers.

- -
Arguments:
-

The argument to this intrinsic indicates which function to return the address - for. Zero indicates the calling function, one indicates its caller, etc. - The argument is required to be a constant integer value.

- -
Semantics:
-

The 'llvm.returnaddress' intrinsic either returns a pointer - indicating the return address of the specified call frame, or zero if it - cannot be identified. The value returned by this intrinsic is likely to be - incorrect or 0 for arguments other than zero, so it should only be used for - debugging purposes.

- -

Note that calling this intrinsic does not prevent function inlining or other - aggressive transformations, so the value returned may not be that of the - obvious source-language caller.

- -
- - -

- 'llvm.frameaddress' Intrinsic -

- -
- -
Syntax:
-
-  declare i8* @llvm.frameaddress(i32 <level>)
-
- -
Overview:
-

The 'llvm.frameaddress' intrinsic attempts to return the - target-specific frame pointer value for the specified stack frame.

- -
Arguments:
-

The argument to this intrinsic indicates which function to return the frame - pointer for. Zero indicates the calling function, one indicates its caller, - etc. The argument is required to be a constant integer value.

- -
Semantics:
-

The 'llvm.frameaddress' intrinsic either returns a pointer - indicating the frame address of the specified call frame, or zero if it - cannot be identified. The value returned by this intrinsic is likely to be - incorrect or 0 for arguments other than zero, so it should only be used for - debugging purposes.

- -

Note that calling this intrinsic does not prevent function inlining or other - aggressive transformations, so the value returned may not be that of the - obvious source-language caller.

- -
- - -

- 'llvm.stacksave' Intrinsic -

- -
- -
Syntax:
-
-  declare i8* @llvm.stacksave()
-
- -
Overview:
-

The 'llvm.stacksave' intrinsic is used to remember the current state - of the function stack, for use - with llvm.stackrestore. This is - useful for implementing language features like scoped automatic variable - sized arrays in C99.

- -
Semantics:
-

This intrinsic returns a opaque pointer value that can be passed - to llvm.stackrestore. When - an llvm.stackrestore intrinsic is executed with a value saved - from llvm.stacksave, it effectively restores the state of the stack - to the state it was in when the llvm.stacksave intrinsic executed. - In practice, this pops any alloca blocks from the - stack that were allocated after the llvm.stacksave was executed.

- -
- - -

- 'llvm.stackrestore' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.stackrestore(i8* %ptr)
-
- -
Overview:
-

The 'llvm.stackrestore' intrinsic is used to restore the state of - the function stack to the state it was in when the - corresponding llvm.stacksave intrinsic - executed. This is useful for implementing language features like scoped - automatic variable sized arrays in C99.

- -
Semantics:
-

See the description - for llvm.stacksave.

- -
- - -

- 'llvm.prefetch' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
-
- -
Overview:
-

The 'llvm.prefetch' intrinsic is a hint to the code generator to - insert a prefetch instruction if supported; otherwise, it is a noop. - Prefetches have no effect on the behavior of the program but can change its - performance characteristics.

- -
Arguments:
-

address is the address to be prefetched, rw is the - specifier determining if the fetch should be for a read (0) or write (1), - and locality is a temporal locality specifier ranging from (0) - no - locality, to (3) - extremely local keep in cache. The cache type - specifies whether the prefetch is performed on the data (1) or instruction (0) - cache. The rw, locality and cache type arguments - must be constant integers.

- -
Semantics:
-

This intrinsic does not modify the behavior of the program. In particular, - prefetches cannot trap and do not produce a value. On targets that support - this intrinsic, the prefetch can provide hints to the processor cache for - better performance.

- -
- - -

- 'llvm.pcmarker' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.pcmarker(i32 <id>)
-
- -
Overview:
-

The 'llvm.pcmarker' intrinsic is a method to export a Program - Counter (PC) in a region of code to simulators and other tools. The method - is target specific, but it is expected that the marker will use exported - symbols to transmit the PC of the marker. The marker makes no guarantees - that it will remain with any specific instruction after optimizations. It is - possible that the presence of a marker will inhibit optimizations. The - intended use is to be inserted after optimizations to allow correlations of - simulation runs.

- -
Arguments:
-

id is a numerical id identifying the marker.

- -
Semantics:
-

This intrinsic does not modify the behavior of the program. Backends that do - not support this intrinsic may ignore it.

- -
- - -

- 'llvm.readcyclecounter' Intrinsic -

- -
- -
Syntax:
-
-  declare i64 @llvm.readcyclecounter()
-
- -
Overview:
-

The 'llvm.readcyclecounter' intrinsic provides access to the cycle - counter register (or similar low latency, high accuracy clocks) on those - targets that support it. On X86, it should map to RDTSC. On Alpha, it - should map to RPCC. As the backing counters overflow quickly (on the order - of 9 seconds on alpha), this should only be used for small timings.

- -
Semantics:
-

When directly supported, reading the cycle counter should not modify any - memory. Implementations are allowed to either return a application specific - value or a system wide value. On backends without support, this is lowered - to a constant 0.

- -
- -
- - -

- Standard C Library Intrinsics -

- -
- -

LLVM provides intrinsics for a few important standard C library functions. - These intrinsics allow source-language front-ends to pass information about - the alignment of the pointer arguments to the code generator, providing - opportunity for more efficient code generation.

- - -

- 'llvm.memcpy' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.memcpy on any - integer bit width and for different address spaces. Not all targets support - all bit widths however.

- -
-  declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
-                                          i32 <len>, i32 <align>, i1 <isvolatile>)
-  declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
-                                          i64 <len>, i32 <align>, i1 <isvolatile>)
-
- -
Overview:
-

The 'llvm.memcpy.*' intrinsics copy a block of memory from the - source location to the destination location.

- -

Note that, unlike the standard libc function, the llvm.memcpy.* - intrinsics do not return a value, takes extra alignment/isvolatile arguments - and the pointers can be in specified address spaces.

- -
Arguments:
- -

The first argument is a pointer to the destination, the second is a pointer - to the source. The third argument is an integer argument specifying the - number of bytes to copy, the fourth argument is the alignment of the - source and destination locations, and the fifth is a boolean indicating a - volatile access.

- -

If the call to this intrinsic has an alignment value that is not 0 or 1, - then the caller guarantees that both the source and destination pointers are - aligned to that boundary.

- -

If the isvolatile parameter is true, the - llvm.memcpy call is a volatile operation. - The detailed access behavior is not very cleanly specified and it is unwise - to depend on it.

- -
Semantics:
- -

The 'llvm.memcpy.*' intrinsics copy a block of memory from the - source location to the destination location, which are not allowed to - overlap. It copies "len" bytes of memory over. If the argument is known to - be aligned to some boundary, this can be specified as the fourth argument, - otherwise it should be set to 0 or 1.

- -
- - -

- 'llvm.memmove' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.memmove on any integer bit - width and for different address space. Not all targets support all bit - widths however.

- -
-  declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
-                                           i32 <len>, i32 <align>, i1 <isvolatile>)
-  declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
-                                           i64 <len>, i32 <align>, i1 <isvolatile>)
-
- -
Overview:
-

The 'llvm.memmove.*' intrinsics move a block of memory from the - source location to the destination location. It is similar to the - 'llvm.memcpy' intrinsic but allows the two memory locations to - overlap.

- -

Note that, unlike the standard libc function, the llvm.memmove.* - intrinsics do not return a value, takes extra alignment/isvolatile arguments - and the pointers can be in specified address spaces.

- -
Arguments:
- -

The first argument is a pointer to the destination, the second is a pointer - to the source. The third argument is an integer argument specifying the - number of bytes to copy, the fourth argument is the alignment of the - source and destination locations, and the fifth is a boolean indicating a - volatile access.

- -

If the call to this intrinsic has an alignment value that is not 0 or 1, - then the caller guarantees that the source and destination pointers are - aligned to that boundary.

- -

If the isvolatile parameter is true, the - llvm.memmove call is a volatile operation. - The detailed access behavior is not very cleanly specified and it is unwise - to depend on it.

- -
Semantics:
- -

The 'llvm.memmove.*' intrinsics copy a block of memory from the - source location to the destination location, which may overlap. It copies - "len" bytes of memory over. If the argument is known to be aligned to some - boundary, this can be specified as the fourth argument, otherwise it should - be set to 0 or 1.

- -
- - -

- 'llvm.memset.*' Intrinsics -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.memset on any integer bit - width and for different address spaces. However, not all targets support all - bit widths.

- -
-  declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
-                                     i32 <len>, i32 <align>, i1 <isvolatile>)
-  declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
-                                     i64 <len>, i32 <align>, i1 <isvolatile>)
-
- -
Overview:
-

The 'llvm.memset.*' intrinsics fill a block of memory with a - particular byte value.

- -

Note that, unlike the standard libc function, the llvm.memset - intrinsic does not return a value and takes extra alignment/volatile - arguments. Also, the destination can be in an arbitrary address space.

- -
Arguments:
-

The first argument is a pointer to the destination to fill, the second is the - byte value with which to fill it, the third argument is an integer argument - specifying the number of bytes to fill, and the fourth argument is the known - alignment of the destination location.

- -

If the call to this intrinsic has an alignment value that is not 0 or 1, - then the caller guarantees that the destination pointer is aligned to that - boundary.

- -

If the isvolatile parameter is true, the - llvm.memset call is a volatile operation. - The detailed access behavior is not very cleanly specified and it is unwise - to depend on it.

- -
Semantics:
-

The 'llvm.memset.*' intrinsics fill "len" bytes of memory starting - at the destination location. If the argument is known to be aligned to some - boundary, this can be specified as the fourth argument, otherwise it should - be set to 0 or 1.

- -
- - -

- 'llvm.sqrt.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.sqrt on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.sqrt.f32(float %Val)
-  declare double    @llvm.sqrt.f64(double %Val)
-  declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
-  declare fp128     @llvm.sqrt.f128(fp128 %Val)
-  declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
-
- -
Overview:
-

The 'llvm.sqrt' intrinsics return the sqrt of the specified operand, - returning the same value as the libm 'sqrt' functions would. - Unlike sqrt in libm, however, llvm.sqrt has undefined - behavior for negative numbers other than -0.0 (which allows for better - optimization, because there is no need to worry about errno being - set). llvm.sqrt(-0.0) is defined to return -0.0 like IEEE sqrt.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the sqrt of the specified operand if it is a - nonnegative floating point number.

- -
- - -

- 'llvm.powi.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.powi on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.powi.f32(float  %Val, i32 %power)
-  declare double    @llvm.powi.f64(double %Val, i32 %power)
-  declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
-  declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
-  declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
-
- -
Overview:
-

The 'llvm.powi.*' intrinsics return the first operand raised to the - specified (positive or negative) power. The order of evaluation of - multiplications is not defined. When a vector of floating point type is - used, the second argument remains a scalar integer value.

- -
Arguments:
-

The second argument is an integer power, and the first is a value to raise to - that power.

- -
Semantics:
-

This function returns the first value raised to the second power with an - unspecified sequence of rounding operations.

- -
- - -

- 'llvm.sin.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.sin on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.sin.f32(float  %Val)
-  declare double    @llvm.sin.f64(double %Val)
-  declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
-  declare fp128     @llvm.sin.f128(fp128 %Val)
-  declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
-
- -
Overview:
-

The 'llvm.sin.*' intrinsics return the sine of the operand.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the sine of the specified operand, returning the same - values as the libm sin functions would, and handles error conditions - in the same way.

- -
- - -

- 'llvm.cos.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.cos on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.cos.f32(float  %Val)
-  declare double    @llvm.cos.f64(double %Val)
-  declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
-  declare fp128     @llvm.cos.f128(fp128 %Val)
-  declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
-
- -
Overview:
-

The 'llvm.cos.*' intrinsics return the cosine of the operand.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the cosine of the specified operand, returning the same - values as the libm cos functions would, and handles error conditions - in the same way.

- -
- - -

- 'llvm.pow.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.pow on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.pow.f32(float  %Val, float %Power)
-  declare double    @llvm.pow.f64(double %Val, double %Power)
-  declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
-  declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
-  declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
-
- -
Overview:
-

The 'llvm.pow.*' intrinsics return the first operand raised to the - specified (positive or negative) power.

- -
Arguments:
-

The second argument is a floating point power, and the first is a value to - raise to that power.

- -
Semantics:
-

This function returns the first value raised to the second power, returning - the same values as the libm pow functions would, and handles error - conditions in the same way.

- -
- - -

- 'llvm.exp.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.exp on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.exp.f32(float  %Val)
-  declare double    @llvm.exp.f64(double %Val)
-  declare x86_fp80  @llvm.exp.f80(x86_fp80  %Val)
-  declare fp128     @llvm.exp.f128(fp128 %Val)
-  declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128  %Val)
-
- -
Overview:
-

The 'llvm.exp.*' intrinsics perform the exp function.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the same values as the libm exp functions - would, and handles error conditions in the same way.

- -
- - -

- 'llvm.log.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.log on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.log.f32(float  %Val)
-  declare double    @llvm.log.f64(double %Val)
-  declare x86_fp80  @llvm.log.f80(x86_fp80  %Val)
-  declare fp128     @llvm.log.f128(fp128 %Val)
-  declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128  %Val)
-
- -
Overview:
-

The 'llvm.log.*' intrinsics perform the log function.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the same values as the libm log functions - would, and handles error conditions in the same way.

- -
- - -

- 'llvm.fma.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.fma on any - floating point or vector of floating point type. Not all targets support all - types however.

- -
-  declare float     @llvm.fma.f32(float  %a, float  %b, float  %c)
-  declare double    @llvm.fma.f64(double %a, double %b, double %c)
-  declare x86_fp80  @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
-  declare fp128     @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
-  declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
-
- -
Overview:
-

The 'llvm.fma.*' intrinsics perform the fused multiply-add - operation.

- -
Arguments:
-

The argument and return value are floating point numbers of the same - type.

- -
Semantics:
-

This function returns the same values as the libm fma functions - would.

- -
- -
- - -

- Bit Manipulation Intrinsics -

- -
- -

LLVM provides intrinsics for a few important bit manipulation operations. - These allow efficient code generation for some algorithms.

- - -

- 'llvm.bswap.*' Intrinsics -

- -
- -
Syntax:
-

This is an overloaded intrinsic function. You can use bswap on any integer - type that is an even number of bytes (i.e. BitWidth % 16 == 0).

- -
-  declare i16 @llvm.bswap.i16(i16 <id>)
-  declare i32 @llvm.bswap.i32(i32 <id>)
-  declare i64 @llvm.bswap.i64(i64 <id>)
-
- -
Overview:
-

The 'llvm.bswap' family of intrinsics is used to byte swap integer - values with an even number of bytes (positive multiple of 16 bits). These - are useful for performing operations on data that is not in the target's - native byte order.

- -
Semantics:
-

The llvm.bswap.i16 intrinsic returns an i16 value that has the high - and low byte of the input i16 swapped. Similarly, - the llvm.bswap.i32 intrinsic returns an i32 value that has the four - bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1, - 2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order. - The llvm.bswap.i48, llvm.bswap.i64 and other intrinsics - extend this concept to additional even-byte lengths (6 bytes, 8 bytes and - more, respectively).

- -
- - -

- 'llvm.ctpop.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit - width, or on any vector with integer elements. Not all targets support all - bit widths or vector types, however.

- -
-  declare i8 @llvm.ctpop.i8(i8  <src>)
-  declare i16 @llvm.ctpop.i16(i16 <src>)
-  declare i32 @llvm.ctpop.i32(i32 <src>)
-  declare i64 @llvm.ctpop.i64(i64 <src>)
-  declare i256 @llvm.ctpop.i256(i256 <src>)
-  declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
-
- -
Overview:
-

The 'llvm.ctpop' family of intrinsics counts the number of bits set - in a value.

- -
Arguments:
-

The only argument is the value to be counted. The argument may be of any - integer type, or a vector with integer elements. - The return type must match the argument type.

- -
Semantics:
-

The 'llvm.ctpop' intrinsic counts the 1's in a variable, or within each - element of a vector.

- -
- - -

- 'llvm.ctlz.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.ctlz on any - integer bit width, or any vector whose elements are integers. Not all - targets support all bit widths or vector types, however.

- -
-  declare i8   @llvm.ctlz.i8  (i8   <src>, i1 <is_zero_undef>)
-  declare i16  @llvm.ctlz.i16 (i16  <src>, i1 <is_zero_undef>)
-  declare i32  @llvm.ctlz.i32 (i32  <src>, i1 <is_zero_undef>)
-  declare i64  @llvm.ctlz.i64 (i64  <src>, i1 <is_zero_undef>)
-  declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
-  declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
-
- -
Overview:
-

The 'llvm.ctlz' family of intrinsic functions counts the number of - leading zeros in a variable.

- -
Arguments:
-

The first argument is the value to be counted. This argument may be of any - integer type, or a vectory with integer element type. The return type - must match the first argument type.

- -

The second argument must be a constant and is a flag to indicate whether the - intrinsic should ensure that a zero as the first argument produces a defined - result. Historically some architectures did not provide a defined result for - zero values as efficiently, and many algorithms are now predicated on - avoiding zero-value inputs.

- -
Semantics:
-

The 'llvm.ctlz' intrinsic counts the leading (most significant) - zeros in a variable, or within each element of the vector. - If src == 0 then the result is the size in bits of the type of - src if is_zero_undef == 0 and undef otherwise. - For example, llvm.ctlz(i32 2) = 30.

- -
- - -

- 'llvm.cttz.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.cttz on any - integer bit width, or any vector of integer elements. Not all targets - support all bit widths or vector types, however.

- -
-  declare i8   @llvm.cttz.i8  (i8   <src>, i1 <is_zero_undef>)
-  declare i16  @llvm.cttz.i16 (i16  <src>, i1 <is_zero_undef>)
-  declare i32  @llvm.cttz.i32 (i32  <src>, i1 <is_zero_undef>)
-  declare i64  @llvm.cttz.i64 (i64  <src>, i1 <is_zero_undef>)
-  declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
-  declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
-
- -
Overview:
-

The 'llvm.cttz' family of intrinsic functions counts the number of - trailing zeros.

- -
Arguments:
-

The first argument is the value to be counted. This argument may be of any - integer type, or a vectory with integer element type. The return type - must match the first argument type.

- -

The second argument must be a constant and is a flag to indicate whether the - intrinsic should ensure that a zero as the first argument produces a defined - result. Historically some architectures did not provide a defined result for - zero values as efficiently, and many algorithms are now predicated on - avoiding zero-value inputs.

- -
Semantics:
-

The 'llvm.cttz' intrinsic counts the trailing (least significant) - zeros in a variable, or within each element of a vector. - If src == 0 then the result is the size in bits of the type of - src if is_zero_undef == 0 and undef otherwise. - For example, llvm.cttz(2) = 1.

- -
- -
- - -

- Arithmetic with Overflow Intrinsics -

- -
- -

LLVM provides intrinsics for some arithmetic with overflow operations.

- - -

- - 'llvm.sadd.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.sadd.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
-

The 'llvm.sadd.with.overflow' family of intrinsic functions perform - a signed addition of the two arguments, and indicate whether an overflow - occurred during the signed summation.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo signed addition.

- -
Semantics:
-

The 'llvm.sadd.with.overflow' family of intrinsic functions perform - a signed addition of the two variables. They return a structure — the - first element of which is the signed summation, and the second element of - which is a bit specifying if the signed summation resulted in an - overflow.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %overflow, label %normal
-
- -
- - -

- - 'llvm.uadd.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.uadd.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
-

The 'llvm.uadd.with.overflow' family of intrinsic functions perform - an unsigned addition of the two arguments, and indicate whether a carry - occurred during the unsigned summation.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo unsigned addition.

- -
Semantics:
-

The 'llvm.uadd.with.overflow' family of intrinsic functions perform - an unsigned addition of the two arguments. They return a structure — - the first element of which is the sum, and the second element of which is a - bit specifying if the unsigned summation resulted in a carry.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %carry, label %normal
-
- -
- - -

- - 'llvm.ssub.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.ssub.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
-

The 'llvm.ssub.with.overflow' family of intrinsic functions perform - a signed subtraction of the two arguments, and indicate whether an overflow - occurred during the signed subtraction.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo signed subtraction.

- -
Semantics:
-

The 'llvm.ssub.with.overflow' family of intrinsic functions perform - a signed subtraction of the two arguments. They return a structure — - the first element of which is the subtraction, and the second element of - which is a bit specifying if the signed subtraction resulted in an - overflow.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %overflow, label %normal
-
- -
- - -

- - 'llvm.usub.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.usub.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
-

The 'llvm.usub.with.overflow' family of intrinsic functions perform - an unsigned subtraction of the two arguments, and indicate whether an - overflow occurred during the unsigned subtraction.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo unsigned subtraction.

- -
Semantics:
-

The 'llvm.usub.with.overflow' family of intrinsic functions perform - an unsigned subtraction of the two arguments. They return a structure — - the first element of which is the subtraction, and the second element of - which is a bit specifying if the unsigned subtraction resulted in an - overflow.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %overflow, label %normal
-
- -
- - -

- - 'llvm.smul.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.smul.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
- -

The 'llvm.smul.with.overflow' family of intrinsic functions perform - a signed multiplication of the two arguments, and indicate whether an - overflow occurred during the signed multiplication.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo signed multiplication.

- -
Semantics:
-

The 'llvm.smul.with.overflow' family of intrinsic functions perform - a signed multiplication of the two arguments. They return a structure — - the first element of which is the multiplication, and the second element of - which is a bit specifying if the signed multiplication resulted in an - overflow.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %overflow, label %normal
-
- -
- - -

- - 'llvm.umul.with.overflow.*' Intrinsics - -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use llvm.umul.with.overflow - on any integer bit width.

- -
-  declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
-  declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
-  declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
-
- -
Overview:
-

The 'llvm.umul.with.overflow' family of intrinsic functions perform - a unsigned multiplication of the two arguments, and indicate whether an - overflow occurred during the unsigned multiplication.

- -
Arguments:
-

The arguments (%a and %b) and the first element of the result structure may - be of integer types of any bit width, but they must have the same bit - width. The second element of the result structure must be of - type i1. %a and %b are the two values that will - undergo unsigned multiplication.

- -
Semantics:
-

The 'llvm.umul.with.overflow' family of intrinsic functions perform - an unsigned multiplication of the two arguments. They return a structure - — the first element of which is the multiplication, and the second - element of which is a bit specifying if the unsigned multiplication resulted - in an overflow.

- -
Examples:
-
-  %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
-  %sum = extractvalue {i32, i1} %res, 0
-  %obit = extractvalue {i32, i1} %res, 1
-  br i1 %obit, label %overflow, label %normal
-
- -
- -
- - -

- Half Precision Floating Point Intrinsics -

- -
- -

Half precision floating point is a storage-only format. This means that it is - a dense encoding (in memory) but does not support computation in the - format.

- -

This means that code must first load the half-precision floating point - value as an i16, then convert it to float with llvm.convert.from.fp16. - Computation can then be performed on the float value (including extending to - double etc). To store the value back to memory, it is first converted to - float if needed, then converted to i16 with - llvm.convert.to.fp16, then - storing as an i16 value.

- - -

- - 'llvm.convert.to.fp16' Intrinsic - -

- -
- -
Syntax:
-
-  declare i16 @llvm.convert.to.fp16(f32 %a)
-
- -
Overview:
-

The 'llvm.convert.to.fp16' intrinsic function performs - a conversion from single precision floating point format to half precision - floating point format.

- -
Arguments:
-

The intrinsic function contains single argument - the value to be - converted.

- -
Semantics:
-

The 'llvm.convert.to.fp16' intrinsic function performs - a conversion from single precision floating point format to half precision - floating point format. The return value is an i16 which - contains the converted number.

- -
Examples:
-
-  %res = call i16 @llvm.convert.to.fp16(f32 %a)
-  store i16 %res, i16* @x, align 2
-
- -
- - -

- - 'llvm.convert.from.fp16' Intrinsic - -

- -
- -
Syntax:
-
-  declare f32 @llvm.convert.from.fp16(i16 %a)
-
- -
Overview:
-

The 'llvm.convert.from.fp16' intrinsic function performs - a conversion from half precision floating point format to single precision - floating point format.

- -
Arguments:
-

The intrinsic function contains single argument - the value to be - converted.

- -
Semantics:
-

The 'llvm.convert.from.fp16' intrinsic function performs a - conversion from half single precision floating point format to single - precision floating point format. The input half-float value is represented by - an i16 value.

- -
Examples:
-
-  %a = load i16* @x, align 2
-  %res = call f32 @llvm.convert.from.fp16(i16 %a)
-
- -
- -
- - -

- Debugger Intrinsics -

- -
- -

The LLVM debugger intrinsics (which all start with llvm.dbg. - prefix), are described in - the LLVM Source - Level Debugging document.

- -
- - -

- Exception Handling Intrinsics -

- -
- -

The LLVM exception handling intrinsics (which all start with - llvm.eh. prefix), are described in - the LLVM Exception - Handling document.

- -
- - -

- Trampoline Intrinsics -

- -
- -

These intrinsics make it possible to excise one parameter, marked with - the nest attribute, from a function. - The result is a callable - function pointer lacking the nest parameter - the caller does not need to - provide a value for it. Instead, the value to use is stored in advance in a - "trampoline", a block of memory usually allocated on the stack, which also - contains code to splice the nest value into the argument list. This is used - to implement the GCC nested function address extension.

- -

For example, if the function is - i32 f(i8* nest %c, i32 %x, i32 %y) then the resulting function - pointer has signature i32 (i32, i32)*. It can be created as - follows:

- -
-  %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
-  %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
-  call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
-  %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
-  %fp = bitcast i8* %p to i32 (i32, i32)*
-
- -

The call %val = call i32 %fp(i32 %x, i32 %y) is then equivalent - to %val = call i32 %f(i8* %nval, i32 %x, i32 %y).

- - -

- - 'llvm.init.trampoline' Intrinsic - -

- -
- -
Syntax:
-
-  declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
-
- -
Overview:
-

This fills the memory pointed to by tramp with executable code, - turning it into a trampoline.

- -
Arguments:
-

The llvm.init.trampoline intrinsic takes three arguments, all - pointers. The tramp argument must point to a sufficiently large and - sufficiently aligned block of memory; this memory is written to by the - intrinsic. Note that the size and the alignment are target-specific - LLVM - currently provides no portable way of determining them, so a front-end that - generates this intrinsic needs to have some target-specific knowledge. - The func argument must hold a function bitcast to - an i8*.

- -
Semantics:
-

The block of memory pointed to by tramp is filled with target - dependent code, turning it into a function. Then tramp needs to be - passed to llvm.adjust.trampoline to get a pointer - which can be bitcast (to a new function) and - called. The new function's signature is the same as that of - func with any arguments marked with the nest attribute - removed. At most one such nest argument is allowed, and it must be of - pointer type. Calling the new function is equivalent to calling func - with the same argument list, but with nval used for the missing - nest argument. If, after calling llvm.init.trampoline, the - memory pointed to by tramp is modified, then the effect of any later call - to the returned function pointer is undefined.

-
- - -

- - 'llvm.adjust.trampoline' Intrinsic - -

- -
- -
Syntax:
-
-  declare i8* @llvm.adjust.trampoline(i8* <tramp>)
-
- -
Overview:
-

This performs any required machine-specific adjustment to the address of a - trampoline (passed as tramp).

- -
Arguments:
-

tramp must point to a block of memory which already has trampoline code - filled in by a previous call to llvm.init.trampoline - .

- -
Semantics:
-

On some architectures the address of the code to be executed needs to be - different to the address where the trampoline is actually stored. This - intrinsic returns the executable address corresponding to tramp - after performing the required machine specific adjustments. - The pointer returned can then be bitcast and - executed. -

- -
- -
- - -

- Memory Use Markers -

- -
- -

This class of intrinsics exists to information about the lifetime of memory - objects and ranges where variables are immutable.

- - -

- 'llvm.lifetime.start' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
-
- -
Overview:
-

The 'llvm.lifetime.start' intrinsic specifies the start of a memory - object's lifetime.

- -
Arguments:
-

The first argument is a constant integer representing the size of the - object, or -1 if it is variable sized. The second argument is a pointer to - the object.

- -
Semantics:
-

This intrinsic indicates that before this point in the code, the value of the - memory pointed to by ptr is dead. This means that it is known to - never be used and has an undefined value. A load from the pointer that - precedes this intrinsic can be replaced with - 'undef'.

- -
- - -

- 'llvm.lifetime.end' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
-
- -
Overview:
-

The 'llvm.lifetime.end' intrinsic specifies the end of a memory - object's lifetime.

- -
Arguments:
-

The first argument is a constant integer representing the size of the - object, or -1 if it is variable sized. The second argument is a pointer to - the object.

- -
Semantics:
-

This intrinsic indicates that after this point in the code, the value of the - memory pointed to by ptr is dead. This means that it is known to - never be used and has an undefined value. Any stores into the memory object - following this intrinsic may be removed as dead. - -

- - -

- 'llvm.invariant.start' Intrinsic -

- -
- -
Syntax:
-
-  declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
-
- -
Overview:
-

The 'llvm.invariant.start' intrinsic specifies that the contents of - a memory object will not change.

- -
Arguments:
-

The first argument is a constant integer representing the size of the - object, or -1 if it is variable sized. The second argument is a pointer to - the object.

- -
Semantics:
-

This intrinsic indicates that until an llvm.invariant.end that uses - the return value, the referenced memory location is constant and - unchanging.

- -
- - -

- 'llvm.invariant.end' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
-
- -
Overview:
-

The 'llvm.invariant.end' intrinsic specifies that the contents of - a memory object are mutable.

- -
Arguments:
-

The first argument is the matching llvm.invariant.start intrinsic. - The second argument is a constant integer representing the size of the - object, or -1 if it is variable sized and the third argument is a pointer - to the object.

- -
Semantics:
-

This intrinsic indicates that the memory is mutable again.

- -
- -
- - -

- General Intrinsics -

- -
- -

This class of intrinsics is designed to be generic and has no specific - purpose.

- - -

- 'llvm.var.annotation' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
-
- -
Overview:
-

The 'llvm.var.annotation' intrinsic.

- -
Arguments:
-

The first argument is a pointer to a value, the second is a pointer to a - global string, the third is a pointer to a global string which is the source - file name, and the last argument is the line number.

- -
Semantics:
-

This intrinsic allows annotation of local variables with arbitrary strings. - This can be useful for special purpose optimizations that want to look for - these annotations. These have no other defined use; they are ignored by code - generation and optimization.

- -
- - -

- 'llvm.annotation.*' Intrinsic -

- -
- -
Syntax:
-

This is an overloaded intrinsic. You can use 'llvm.annotation' on - any integer bit width.

- -
-  declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32  <int>)
-  declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32  <int>)
-  declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32  <int>)
-  declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32  <int>)
-  declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32  <int>)
-
- -
Overview:
-

The 'llvm.annotation' intrinsic.

- -
Arguments:
-

The first argument is an integer value (result of some expression), the - second is a pointer to a global string, the third is a pointer to a global - string which is the source file name, and the last argument is the line - number. It returns the value of the first argument.

- -
Semantics:
-

This intrinsic allows annotations to be put on arbitrary expressions with - arbitrary strings. This can be useful for special purpose optimizations that - want to look for these annotations. These have no other defined use; they - are ignored by code generation and optimization.

- -
- - -

- 'llvm.trap' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.trap()
-
- -
Overview:
-

The 'llvm.trap' intrinsic.

- -
Arguments:
-

None.

- -
Semantics:
-

This intrinsics is lowered to the target dependent trap instruction. If the - target does not have a trap instruction, this intrinsic will be lowered to - the call of the abort() function.

- -
- - -

- 'llvm.stackprotector' Intrinsic -

- -
- -
Syntax:
-
-  declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
-
- -
Overview:
-

The llvm.stackprotector intrinsic takes the guard and - stores it onto the stack at slot. The stack slot is adjusted to - ensure that it is placed on the stack before local variables.

- -
Arguments:
-

The llvm.stackprotector intrinsic requires two pointer - arguments. The first argument is the value loaded from the stack - guard @__stack_chk_guard. The second variable is an alloca - that has enough space to hold the value of the guard.

- -
Semantics:
-

This intrinsic causes the prologue/epilogue inserter to force the position of - the AllocaInst stack slot to be before local variables on the - stack. This is to ensure that if a local variable on the stack is - overwritten, it will destroy the value of the guard. When the function exits, - the guard on the stack is checked against the original guard. If they are - different, then the program aborts by calling the __stack_chk_fail() - function.

- -
- - -

- 'llvm.objectsize' Intrinsic -

- -
- -
Syntax:
-
-  declare i32 @llvm.objectsize.i32(i8* <object>, i1 <type>)
-  declare i64 @llvm.objectsize.i64(i8* <object>, i1 <type>)
-
- -
Overview:
-

The llvm.objectsize intrinsic is designed to provide information to - the optimizers to determine at compile time whether a) an operation (like - memcpy) will overflow a buffer that corresponds to an object, or b) that a - runtime check for overflow isn't necessary. An object in this context means - an allocation of a specific class, structure, array, or other object.

- -
Arguments:
-

The llvm.objectsize intrinsic takes two arguments. The first - argument is a pointer to or into the object. The second argument - is a boolean 0 or 1. This argument determines whether you want the - maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or - 1, variables are not allowed.

- -
Semantics:
-

The llvm.objectsize intrinsic is lowered to either a constant - representing the size of the object concerned, or i32/i64 -1 or 0, - depending on the type argument, if the size cannot be determined at - compile time.

- -
- -

- 'llvm.expect' Intrinsic -

- -
- -
Syntax:
-
-  declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
-  declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
-
- -
Overview:
-

The llvm.expect intrinsic provides information about expected (the - most probable) value of val, which can be used by optimizers.

- -
Arguments:
-

The llvm.expect intrinsic takes two arguments. The first - argument is a value. The second argument is an expected value, this needs to - be a constant value, variables are not allowed.

- -
Semantics:
-

This intrinsic is lowered to the val.

-
- -
- -
- -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-16 12:39:33 -0700 (Mon, 16 Apr 2012) $ -
- - - diff --git a/cpp/llvm/docs/Lexicon.html b/cpp/llvm/docs/Lexicon.html deleted file mode 100644 index 81fbd90f..00000000 --- a/cpp/llvm/docs/Lexicon.html +++ /dev/null @@ -1,292 +0,0 @@ - - - - - The LLVM Lexicon - - - - - -

The LLVM Lexicon

-

NOTE: This document is a work in progress!

- -

Table Of Contents

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- A -
ADCE
- B -
BURS
- C -
CSE
- D -
DAGDerived PointerDSADSE
- F -
FCA
- G -
GC
- I -
IPAIPOISel
- L -
LCSSALICMLoad-VNLTO
- M -
MC
- O -
Object Pointer
- P -
PRE
- R -
RAUWReassociationRoot
- S -
Safe PointSCCSCCPSDISelSRoAStack Map
-
- - -

Definitions

- -
- -

- A -

-
-
-
ADCE
-
Aggressive Dead Code Elimination
-
-
- -

- B -

-
-
-
BURS
-
Bottom Up Rewriting System—A method of instruction selection for - code generation. An example is the BURG tool.
-
-
- -

- C -

-
-
-
CSE
-
Common Subexpression Elimination. An optimization that removes common - subexpression compuation. For example (a+b)*(a+b) has two - subexpressions that are the same: (a+b). This optimization would - perform the addition only once and then perform the multiply (but only if - it's compulationally correct/safe). -
-
- -

- D -

-
-
-
DAG
-
Directed Acyclic Graph
-
Derived Pointer
-
A pointer to the interior of an object, such that a garbage collector - is unable to use the pointer for reachability analysis. While a derived - pointer is live, the corresponding object pointer must be kept in a root, - otherwise the collector might free the referenced object. With copying - collectors, derived pointers pose an additional hazard that they may be - invalidated at any safe point. This term is used in - opposition to object pointer.
-
DSA
-
Data Structure Analysis
-
DSE
-
Dead Store Elimination
-
-
- -

- F -

-
-
-
FCA
-
First Class Aggregate
-
-
- -

- G -

-
-
-
GC
-
Garbage Collection. The practice of using reachability analysis instead - of explicit memory management to reclaim unused memory.
-
-
- -

- H -

-
-
-
Heap
-
In garbage collection, the region of memory which is managed using - reachability analysis.
-
-
- -

- I -

-
-
-
IPA
-
Inter-Procedural Analysis. Refers to any variety of code analysis that - occurs between procedures, functions or compilation units (modules).
-
IPO
-
Inter-Procedural Optimization. Refers to any variety of code - optimization that occurs between procedures, functions or compilation units - (modules).
-
ISel
-
Instruction Selection.
-
-
- -

- L -

-
-
-
LCSSA
-
Loop-Closed Static Single Assignment Form
-
LICM
-
Loop Invariant Code Motion
-
Load-VN
-
Load Value Numbering
-
LTO
-
Link-Time Optimization
-
-
- -

- M -

-
-
-
MC
-
Machine Code
-
-
- -

- O -

-
-
-
Object Pointer
-
A pointer to an object such that the garbage collector is able to trace - references contained within the object. This term is used in opposition to - derived pointer.
-
-
- - -

- P -

-
-
-
PRE
-
Partial Redundancy Elimination
-
-
- - -

- R -

-
-
-
RAUW
An abbreviation for Replace - All Uses With. The functions User::replaceUsesOfWith(), - Value::replaceAllUsesWith(), and Constant::replaceUsesOfWithOnConstant() - implement the replacement of one Value with another by iterating over its - def/use chain and fixing up all of the pointers to point to the new value. - See also def/use chains. -
-
Reassociation
Rearranging - associative expressions to promote better redundancy elimination and other - optimization. For example, changing (A+B-A) into (B+A-A), permitting it to - be optimized into (B+0) then (B).
-
Root
In garbage collection, a - pointer variable lying outside of the heap from which - the collector begins its reachability analysis. In the context of code - generation, "root" almost always refers to a "stack root" -- a local or - temporary variable within an executing function.
-
-
- - -

- S -

-
-
-
Safe Point
-
In garbage collection, it is necessary to identify stack - roots so that reachability analysis may proceed. It may be infeasible to - provide this information for every instruction, so instead the information - may is calculated only at designated safe points. With a copying collector, - derived pointers must not be retained across - safe points and object pointers must be - reloaded from stack roots.
-
SDISel
-
Selection DAG Instruction Selection.
-
SCC
-
Strongly Connected Component
-
SCCP
-
Sparse Conditional Constant Propagation
-
SRoA
-
Scalar Replacement of Aggregates
-
SSA
-
Static Single Assignment
-
Stack Map
-
In garbage collection, metadata emitted by the code generator which - identifies roots within the stack frame of an executing - function.
-
-
- -
- -
-
Valid CSSValid HTML 4.01The LLVM Team
-The LLVM Compiler Infrastructure
-Last modified: $Date: 2012-01-05 00:18:41 -0800 (Thu, 05 Jan 2012) $ -
- - - diff --git a/cpp/llvm/docs/LinkTimeOptimization.html b/cpp/llvm/docs/LinkTimeOptimization.html deleted file mode 100644 index 7d064e7c..00000000 --- a/cpp/llvm/docs/LinkTimeOptimization.html +++ /dev/null @@ -1,401 +0,0 @@ - - - - - LLVM Link Time Optimization: Design and Implementation - - - -

- LLVM Link Time Optimization: Design and Implementation -

- - - -
-

Written by Devang Patel and Nick Kledzik

-
- - -

-Description -

- - -
-

-LLVM features powerful intermodular optimizations which can be used at link -time. Link Time Optimization (LTO) is another name for intermodular optimization -when performed during the link stage. This document describes the interface -and design between the LTO optimizer and the linker.

-
- - -

-Design Philosophy -

- - -
-

-The LLVM Link Time Optimizer provides complete transparency, while doing -intermodular optimization, in the compiler tool chain. Its main goal is to let -the developer take advantage of intermodular optimizations without making any -significant changes to the developer's makefiles or build system. This is -achieved through tight integration with the linker. In this model, the linker -treates LLVM bitcode files like native object files and allows mixing and -matching among them. The linker uses libLTO, a shared -object, to handle LLVM bitcode files. This tight integration between -the linker and LLVM optimizer helps to do optimizations that are not possible -in other models. The linker input allows the optimizer to avoid relying on -conservative escape analysis. -

- - -

- Example of link time optimization -

- -
-

The following example illustrates the advantages of LTO's integrated - approach and clean interface. This example requires a system linker which - supports LTO through the interface described in this document. Here, - clang transparently invokes system linker.

-
    -
  • Input source file a.c is compiled into LLVM bitcode form. -
  • Input source file main.c is compiled into native object code. -
-
---- a.h ---
-extern int foo1(void);
-extern void foo2(void);
-extern void foo4(void);
-
---- a.c ---
-#include "a.h"
-
-static signed int i = 0;
-
-void foo2(void) {
-  i = -1;
-}
-
-static int foo3() {
-  foo4();
-  return 10;
-}
-
-int foo1(void) {
-  int data = 0;
-
-  if (i < 0) 
-    data = foo3();
-
-  data = data + 42;
-  return data;
-}
-
---- main.c ---
-#include <stdio.h>
-#include "a.h"
-
-void foo4(void) {
-  printf("Hi\n");
-}
-
-int main() {
-  return foo1();
-}
-
---- command lines ---
-$ clang -emit-llvm -c a.c -o a.o   # <-- a.o is LLVM bitcode file
-$ clang -c main.c -o main.o        # <-- main.o is native object file
-$ clang a.o main.o -o main         # <-- standard link command without any modifications
-
- -
    -
  • In this example, the linker recognizes that foo2() is an - externally visible symbol defined in LLVM bitcode file. The linker - completes its usual symbol resolution pass and finds that foo2() - is not used anywhere. This information is used by the LLVM optimizer and - it removes foo2().
  • -
  • As soon as foo2() is removed, the optimizer recognizes that condition - i < 0 is always false, which means foo3() is never - used. Hence, the optimizer also removes foo3().
  • -
  • And this in turn, enables linker to remove foo4().
  • -
- -

This example illustrates the advantage of tight integration with the - linker. Here, the optimizer can not remove foo3() without the - linker's input.

- -
- - -

- Alternative Approaches -

- -
-
-
Compiler driver invokes link time optimizer separately.
-
In this model the link time optimizer is not able to take advantage of - information collected during the linker's normal symbol resolution phase. - In the above example, the optimizer can not remove foo2() without - the linker's input because it is externally visible. This in turn prohibits - the optimizer from removing foo3().
-
Use separate tool to collect symbol information from all object - files.
-
In this model, a new, separate, tool or library replicates the linker's - capability to collect information for link time optimization. Not only is - this code duplication difficult to justify, but it also has several other - disadvantages. For example, the linking semantics and the features - provided by the linker on various platform are not unique. This means, - this new tool needs to support all such features and platforms in one - super tool or a separate tool per platform is required. This increases - maintenance cost for link time optimizer significantly, which is not - necessary. This approach also requires staying synchronized with linker - developements on various platforms, which is not the main focus of the link - time optimizer. Finally, this approach increases end user's build time due - to the duplication of work done by this separate tool and the linker itself. -
-
-
- -
- - -

- Multi-phase communication between libLTO and linker -

- -
-

The linker collects information about symbol defininitions and uses in - various link objects which is more accurate than any information collected - by other tools during typical build cycles. The linker collects this - information by looking at the definitions and uses of symbols in native .o - files and using symbol visibility information. The linker also uses - user-supplied information, such as a list of exported symbols. LLVM - optimizer collects control flow information, data flow information and knows - much more about program structure from the optimizer's point of view. - Our goal is to take advantage of tight integration between the linker and - the optimizer by sharing this information during various linking phases. -

- - -

- Phase 1 : Read LLVM Bitcode Files -

- -
-

The linker first reads all object files in natural order and collects - symbol information. This includes native object files as well as LLVM bitcode - files. To minimize the cost to the linker in the case that all .o files - are native object files, the linker only calls lto_module_create() - when a supplied object file is found to not be a native object file. If - lto_module_create() returns that the file is an LLVM bitcode file, - the linker - then iterates over the module using lto_module_get_symbol_name() and - lto_module_get_symbol_attribute() to get all symbols defined and - referenced. - This information is added to the linker's global symbol table. -

-

The lto* functions are all implemented in a shared object libLTO. This - allows the LLVM LTO code to be updated independently of the linker tool. - On platforms that support it, the shared object is lazily loaded. -

-
- - -

- Phase 2 : Symbol Resolution -

- -
-

In this stage, the linker resolves symbols using global symbol table. - It may report undefined symbol errors, read archive members, replace - weak symbols, etc. The linker is able to do this seamlessly even though it - does not know the exact content of input LLVM bitcode files. If dead code - stripping is enabled then the linker collects the list of live symbols. -

-
- - -

- Phase 3 : Optimize Bitcode Files -

-
-

After symbol resolution, the linker tells the LTO shared object which - symbols are needed by native object files. In the example above, the linker - reports that only foo1() is used by native object files using - lto_codegen_add_must_preserve_symbol(). Next the linker invokes - the LLVM optimizer and code generators using lto_codegen_compile() - which returns a native object file creating by merging the LLVM bitcode files - and applying various optimization passes. -

-
- - -

- Phase 4 : Symbol Resolution after optimization -

- -
-

In this phase, the linker reads optimized a native object file and - updates the internal global symbol table to reflect any changes. The linker - also collects information about any changes in use of external symbols by - LLVM bitcode files. In the example above, the linker notes that - foo4() is not used any more. If dead code stripping is enabled then - the linker refreshes the live symbol information appropriately and performs - dead code stripping.

-

After this phase, the linker continues linking as if it never saw LLVM - bitcode files.

-
- -
- - -

-libLTO -

- -
-

libLTO is a shared object that is part of the LLVM tools, and - is intended for use by a linker. libLTO provides an abstract C - interface to use the LLVM interprocedural optimizer without exposing details - of LLVM's internals. The intention is to keep the interface as stable as - possible even when the LLVM optimizer continues to evolve. It should even - be possible for a completely different compilation technology to provide - a different libLTO that works with their object files and the standard - linker tool.

- - -

- lto_module_t -

- -
- -

A non-native object file is handled via an lto_module_t. -The following functions allow the linker to check if a file (on disk -or in a memory buffer) is a file which libLTO can process:

- -
-lto_module_is_object_file(const char*)
-lto_module_is_object_file_for_target(const char*, const char*)
-lto_module_is_object_file_in_memory(const void*, size_t)
-lto_module_is_object_file_in_memory_for_target(const void*, size_t, const char*)
-
- -

If the object file can be processed by libLTO, the linker creates a -lto_module_t by using one of

- -
-lto_module_create(const char*)
-lto_module_create_from_memory(const void*, size_t)
-
- -

and when done, the handle is released via

- -
-lto_module_dispose(lto_module_t)
-
- -

The linker can introspect the non-native object file by getting the number of -symbols and getting the name and attributes of each symbol via:

- -
-lto_module_get_num_symbols(lto_module_t)
-lto_module_get_symbol_name(lto_module_t, unsigned int)
-lto_module_get_symbol_attribute(lto_module_t, unsigned int)
-
- -

The attributes of a symbol include the alignment, visibility, and kind.

-
- - -

- lto_code_gen_t -

- -
- -

Once the linker has loaded each non-native object files into an -lto_module_t, it can request libLTO to process them all and -generate a native object file. This is done in a couple of steps. -First, a code generator is created with:

- -
lto_codegen_create()
- -

Then, each non-native object file is added to the code generator with:

- -
-lto_codegen_add_module(lto_code_gen_t, lto_module_t)
-
- -

The linker then has the option of setting some codegen options. Whether or -not to generate DWARF debug info is set with:

- -
lto_codegen_set_debug_model(lto_code_gen_t)
- -

Which kind of position independence is set with:

- -
lto_codegen_set_pic_model(lto_code_gen_t) 
- -

And each symbol that is referenced by a native object file or otherwise must -not be optimized away is set with:

- -
-lto_codegen_add_must_preserve_symbol(lto_code_gen_t, const char*)
-
- -

After all these settings are done, the linker requests that a native object -file be created from the modules with the settings using:

- -
lto_codegen_compile(lto_code_gen_t, size*)
- -

which returns a pointer to a buffer containing the generated native -object file. The linker then parses that and links it with the rest -of the native object files.

- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Devang Patel and Nick Kledzik
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - - - diff --git a/cpp/llvm/docs/Makefile b/cpp/llvm/docs/Makefile deleted file mode 100644 index 389fd90a..00000000 --- a/cpp/llvm/docs/Makefile +++ /dev/null @@ -1,130 +0,0 @@ -##===- docs/Makefile ---------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := .. -DIRS := CommandGuide tutorial - -ifdef BUILD_FOR_WEBSITE -PROJ_OBJ_DIR = . -DOXYGEN = doxygen - -$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in - cat $< | sed \ - -e 's/@abs_top_srcdir@/../g' \ - -e 's/@DOT@/dot/g' \ - -e 's/@PACKAGE_VERSION@/mainline/' \ - -e 's/@abs_top_builddir@/../g' > $@ -endif - -include $(LEVEL)/Makefile.common - -HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \ - $(wildcard $(PROJ_SRC_DIR)/*.css) -IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*) -DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \ - doxygen.intro -EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img - -.PHONY: install-html install-doxygen doxygen install-ocamldoc ocamldoc generated - -install_targets := install-html -ifeq ($(ENABLE_DOXYGEN),1) -install_targets += install-doxygen -endif -ifdef OCAMLDOC -ifneq (,$(filter ocaml,$(BINDINGS_TO_BUILD))) -install_targets += install-ocamldoc -endif -endif -install-local:: $(install_targets) - -generated_targets := doxygen -ifdef OCAMLDOC -generated_targets += ocamldoc -endif - -# Live documentation is generated for the web site using this target: -# 'make generated BUILD_FOR_WEBSITE=1' -generated:: $(generated_targets) - -install-html: $(PROJ_OBJ_DIR)/html.tar.gz - $(Echo) Installing HTML documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html - $(Verb) $(DataInstall) $(IMAGES) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir) - -$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) - $(Echo) Packaging HTML documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar - $(Verb) cd $(PROJ_SRC_DIR) && \ - $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html - $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar - -install-doxygen: doxygen - $(Echo) Installing doxygen documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir) - $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \ - $(FIND) . -type f -exec \ - $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \; - -doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz - -regendoc: - $(Echo) Building doxygen documentation - $(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \ - $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \ - fi - $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg - -$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg - $(Echo) Packaging doxygen documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen - $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/ - -userloc: $(LLVM_SRC_ROOT)/docs/userloc.html - -$(LLVM_SRC_ROOT)/docs/userloc.html: - $(Echo) Making User LOC Table - $(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \ - -html lib include tools runtime utils examples autoconf test > docs/userloc.html - -install-ocamldoc: ocamldoc - $(Echo) Installing ocamldoc documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(DESTDIR)$(PROJ_docsdir) - $(Verb) cd $(PROJ_OBJ_DIR)/ocamldoc && \ - $(FIND) . -type f -exec \ - $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html \; - -ocamldoc: regen-ocamldoc - $(Echo) Packaging ocamldoc documentation - $(Verb) $(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc.tar* - $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/ocamldoc.tar ocamldoc - $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/ocamldoc.tar - $(Verb) $(CP) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(PROJ_OBJ_DIR)/ocamldoc/html/ - -regen-ocamldoc: - $(Echo) Building ocamldoc documentation - $(Verb) if test -e $(PROJ_OBJ_DIR)/ocamldoc ; then \ - $(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc ; \ - fi - $(Verb) $(MAKE) -C $(LEVEL)/bindings/ocaml ocamldoc - $(Verb) $(MKDIR) $(PROJ_OBJ_DIR)/ocamldoc/html - $(Verb) \ - $(OCAMLDOC) -d $(PROJ_OBJ_DIR)/ocamldoc/html -sort -colorize-code -html \ - `$(FIND) $(LEVEL)/bindings/ocaml -name "*.odoc" -exec echo -load '{}' ';'` - -uninstall-local:: - $(Echo) Uninstalling Documentation - $(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir) diff --git a/cpp/llvm/docs/MakefileGuide.html b/cpp/llvm/docs/MakefileGuide.html deleted file mode 100644 index 16663d29..00000000 --- a/cpp/llvm/docs/MakefileGuide.html +++ /dev/null @@ -1,1039 +0,0 @@ - - - - - LLVM Makefile Guide - - - - -

LLVM Makefile Guide

- -
    -
  1. Introduction
  2. -
  3. General Concepts -
      -
    1. Projects
    2. -
    3. Variable Values
    4. -
    5. Including Makefiles -
        -
      1. Makefile
      2. -
      3. Makefile.common
      4. -
      5. Makefile.config
      6. -
      7. Makefile.rules
      8. -
      -
    6. -
    7. Comments
    8. -
    -
  4. -
  5. Tutorial -
      -
    1. Libraries -
        -
      1. Bitcode Modules
      2. -
      3. Loadable Modules
      4. -
      -
    2. -
    3. Tools -
        -
      1. JIT Tools
      2. -
      -
    4. -
    5. Projects
    6. -
    -
  6. -
  7. Targets Supported -
      -
    1. all
    2. -
    3. all-local
    4. -
    5. check
    6. -
    7. check-local
    8. -
    9. clean
    10. -
    11. clean-local
    12. -
    13. dist
    14. -
    15. dist-check
    16. -
    17. dist-clean
    18. -
    19. install
    20. -
    21. preconditions
    22. -
    23. printvars
    24. -
    25. reconfigure
    26. -
    27. spotless
    28. -
    29. tags
    30. -
    31. uninstall
    32. -
    -
  8. -
  9. Using Variables -
      -
    1. Control Variables
    2. -
    3. Override Variables
    4. -
    5. Readable Variables
    6. -
    7. Internal Variables
    8. -
    -
  10. -
- -
-

Written by Reid Spencer

-
- - -

Introduction

- - -
-

This document provides usage information about the LLVM makefile - system. While loosely patterned after the BSD makefile system, LLVM has taken - a departure from BSD in order to implement additional features needed by LLVM. - Although makefile systems such as automake were attempted at one point, it - has become clear that the features needed by LLVM and the Makefile norm are - too great to use a more limited tool. Consequently, LLVM requires simply GNU - Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy - use of the features of GNU Make so the dependency on GNU Make is firm. If - you're not familiar with make, it is recommended that you read the - GNU Makefile - Manual.

-

While this document is rightly part of the - LLVM Programmer's Manual, it is treated - separately here because of the volume of content and because it is often an - early source of bewilderment for new developers.

-
- - -

General Concepts

- - -
-

The LLVM Makefile System is the component of LLVM that is responsible for - building the software, testing it, generating distributions, checking those - distributions, installing and uninstalling, etc. It consists of a several - files throughout the source tree. These files and other general concepts are - described in this section.

- - -

Projects

-
-

The LLVM Makefile System is quite generous. It not only builds its own - software, but it can build yours too. Built into the system is knowledge of - the llvm/projects directory. Any directory under projects - that has both a configure script and a Makefile is assumed - to be a project that uses the LLVM Makefile system. Building software that - uses LLVM does not require the LLVM Makefile System nor even placement in the - llvm/projects directory. However, doing so will allow your project - to get up and running quickly by utilizing the built-in features that are used - to compile LLVM. LLVM compiles itself using the same features of the makefile - system as used for projects.

-

For complete details on setting up your projects configuration, simply - mimic the llvm/projects/sample project or for further details, - consult the Projects.html page.

-
- - -

Variable Values

-
-

To use the makefile system, you simply create a file named - Makefile in your directory and declare values for certain variables. - The variables and values that you select determine what the makefile system - will do. These variables enable rules and processing in the makefile system - that automatically Do The Right Thing™. -

- - -

Including Makefiles

-
-

Setting variables alone is not enough. You must include into your Makefile - additional files that provide the rules of the LLVM Makefile system. The - various files involved are described in the sections that follow.

- - -

Makefile

-
-

Each directory to participate in the build needs to have a file named - Makefile. This is the file first read by make. It has three - sections:

-
    -
  1. Settable Variables - Required that must be set - first.
  2. -
  3. include $(LEVEL)/Makefile.common - - include the LLVM Makefile system. -
  4. Override Variables - Override variables set by - the LLVM Makefile system. -
-
- - -

Makefile.common

-
-

Every project must have a Makefile.common file at its top source - directory. This file serves three purposes:

-
    -
  1. It includes the project's configuration makefile to obtain values - determined by the configure script. This is done by including the - $(LEVEL)/Makefile.config file.
  2. -
  3. It specifies any other (static) values that are needed throughout the - project. Only values that are used in all or a large proportion of the - project's directories should be placed here.
  4. -
  5. It includes the standard rules for the LLVM Makefile system, - $(LLVM_SRC_ROOT)/Makefile.rules. - This file is the "guts" of the LLVM Makefile system.
  6. -
-
- - -

Makefile.config

-
-

Every project must have a Makefile.config at the top of its - build directory. This file is generated by the - configure script from the pattern provided by the - Makefile.config.in file located at the top of the project's - source directory. The contents of this file depend largely on what - configuration items the project uses, however most projects can get what they - need by just relying on LLVM's configuration found in - $(LLVM_OBJ_ROOT)/Makefile.config. -

- - -

Makefile.rules

-
-

This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart - of the LLVM Makefile System. It provides all the logic, dependencies, and - rules for building the targets supported by the system. What it does largely - depends on the values of make variables that - have been set before Makefile.rules is included. -

- -
- - -

Comments

-
-

User Makefiles need not have comments in them unless the construction is - unusual or it does not strictly follow the rules and patterns of the LLVM - makefile system. Makefile comments are invoked with the pound (#) character. - The # character and any text following it, to the end of the line, are ignored - by make.

-
- -
- - -

Tutorial

- -
-

This section provides some examples of the different kinds of modules you - can build with the LLVM makefile system. In general, each directory you - provide will build a single object although that object may be composed of - additionally compiled components.

- - -

Libraries

-
-

Only a few variable definitions are needed to build a regular library. - Normally, the makefile system will build all the software into a single - libname.o (pre-linked) object. This means the library is not - searchable and that the distinction between compilation units has been - dissolved. Optionally, you can ask for a shared library (.so) or archive - library (.a) built. Archive libraries are the default. For example:

-

-      LIBRARYNAME = mylib
-      SHARED_LIBRARY = 1
-      ARCHIVE_LIBRARY = 1
-  
-

says to build a library named "mylib" with both a shared library - (mylib.so) and an archive library (mylib.a) version. The - contents of all the - libraries produced will be the same, they are just constructed differently. - Note that you normally do not need to specify the sources involved. The LLVM - Makefile system will infer the source files from the contents of the source - directory.

-

The LOADABLE_MODULE=1 directive can be used in conjunction with - SHARED_LIBRARY=1 to indicate that the resulting shared library should - be openable with the dlopen function and searchable with the - dlsym function (or your operating system's equivalents). While this - isn't strictly necessary on Linux and a few other platforms, it is required - on systems like HP-UX and Darwin. You should use LOADABLE_MODULE for - any shared library that you intend to be loaded into an tool via the - -load option. See the - WritingAnLLVMPass.html document - for an example of why you might want to do this. - - -

Bitcode Modules

-
-

In some situations, it is desirable to build a single bitcode module from - a variety of sources, instead of an archive, shared library, or bitcode - library. Bitcode modules can be specified in addition to any of the other - types of libraries by defining the MODULE_NAME - variable. For example:

-

-      LIBRARYNAME = mylib
-      BYTECODE_LIBRARY = 1
-      MODULE_NAME = mymod
-  
-

will build a module named mymod.bc from the sources in the - directory. This module will be an aggregation of all the bitcode modules - derived from the sources. The example will also build a bitcode archive - containing a bitcode module for each compiled source file. The difference is - subtle, but important depending on how the module or library is to be linked. -

-
- - -

- Loadable Modules -

-
-

In some situations, you need to create a loadable module. Loadable modules - can be loaded into programs like opt or llc to specify - additional passes to run or targets to support. Loadable modules are also - useful for debugging a pass or providing a pass with another package if that - pass can't be included in LLVM.

-

LLVM provides complete support for building such a module. All you need to - do is use the LOADABLE_MODULE variable in your Makefile. For example, to - build a loadable module named MyMod that uses the LLVM libraries - LLVMSupport.a and LLVMSystem.a, you would specify:

-

-     LIBRARYNAME := MyMod
-     LOADABLE_MODULE := 1
-     LINK_COMPONENTS := support system
-  
-

Use of the LOADABLE_MODULE facility implies several things:

-
    -
  1. There will be no "lib" prefix on the module. This differentiates it from - a standard shared library of the same name.
  2. -
  3. The SHARED_LIBRARY variable is turned - on.
  4. -
  5. The LINK_LIBS_IN_SHARED variable - is turned on.
  6. -
-

A loadable module is loaded by LLVM via the facilities of libtool's libltdl - library which is part of lib/System implementation.

-
- -
- - -

Tools

-
-

For building executable programs (tools), you must provide the name of the - tool and the names of the libraries you wish to link with the tool. For - example:

-

-      TOOLNAME = mytool
-      USEDLIBS = mylib
-      LINK_COMPONENTS = support system
-  
-

says that we are to build a tool name mytool and that it requires - three libraries: mylib, LLVMSupport.a and - LLVMSystem.a.

-

Note that two different variables are use to indicate which libraries are - linked: USEDLIBS and LLVMLIBS. This distinction is necessary - to support projects. LLVMLIBS refers to the LLVM libraries found in - the LLVM object directory. USEDLIBS refers to the libraries built by - your project. In the case of building LLVM tools, USEDLIBS and - LLVMLIBS can be used interchangeably since the "project" is LLVM - itself and USEDLIBS refers to the same place as LLVMLIBS. -

-

Also note that there are two different ways of specifying a library: with a - .a suffix and without. Without the suffix, the entry refers to the - re-linked (.o) file which will include all symbols of the library. - This is useful, for example, to include all passes from a library of passes. - If the .a suffix is used then the library is linked as a searchable - library (with the -l option). In this case, only the symbols that are - unresolved at that point will be resolved from the library, if they - exist. Other (unreferenced) symbols will not be included when the .a - syntax is used. Note that in order to use the .a suffix, the library - in question must have been built with the ARCHIVE_LIBRARY option set. -

- - -

JIT Tools

-
-

Many tools will want to use the JIT features of LLVM. To do this, you - simply specify that you want an execution 'engine', and the makefiles will - automatically link in the appropriate JIT for the host or an interpreter - if none is available:

-

-      TOOLNAME = my_jit_tool
-      USEDLIBS = mylib
-      LINK_COMPONENTS = engine
-  
-

Of course, any additional libraries may be listed as other components. To - get a full understanding of how this changes the linker command, it is - recommended that you:

-

-      cd examples/Fibonacci
-      make VERBOSE=1
-  
-
- -
- -
- - -

Targets Supported

- - -
-

This section describes each of the targets that can be built using the LLVM - Makefile system. Any target can be invoked from any directory but not all are - applicable to a given directory (e.g. "check", "dist" and "install" will - always operate as if invoked from the top level directory).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Target NameImplied TargetsTarget Description
allCompile the software recursively. Default target. -
all-localCompile the software in the local directory only. -
checkChange to the test directory in a project and run the - test suite there. -
check-localRun a local test suite. Generally this is only defined in the - Makefile of the project's test directory. -
cleanRemove built objects recursively. -
clean-localRemove built objects from the local directory only. -
distallPrepare a source distribution tarball. -
dist-checkallPrepare a source distribution tarball and check that it builds. -
dist-cleancleanClean source distribution tarball temporary files. -
installallCopy built objects to installation directory. -
preconditionsallCheck to make sure configuration and makefiles are up to date. -
printvarsallPrints variables defined by the makefile system (for debugging). -
tagsMake C and C++ tags files for emacs and vi. -
uninstallRemove built objects from installation directory. -
- - -

all (default)

-
-

When you invoke make with no arguments, you are implicitly - instructing it to seek the "all" target (goal). This target is used for - building the software recursively and will do different things in different - directories. For example, in a lib directory, the "all" target will - compile source files and generate libraries. But, in a tools - directory, it will link libraries and generate executables.

-
- - -

all-local

-
-

This target is the same as all but it operates only on - the current directory instead of recursively.

-
- - -

check

-
-

This target can be invoked from anywhere within a project's directories - but always invokes the check-local target - in the project's test directory, if it exists and has a - Makefile. A warning is produced otherwise. If - TESTSUITE is defined on the make - command line, it will be passed down to the invocation of - make check-local in the test directory. The intended usage - for this is to assist in running specific suites of tests. If - TESTSUITE is not set, the implementation of check-local - should run all normal tests. It is up to the project to define what - different values for TESTSUTE will do. See the - TestingGuide for further details.

-
- - -

check-local

-
-

This target should be implemented by the Makefile in the project's - test directory. It is invoked by the check target elsewhere. - Each project is free to define the actions of check-local as - appropriate for that project. The LLVM project itself uses dejagnu to run a - suite of feature and regresson tests. Other projects may choose to use - dejagnu or any other testing mechanism.

-
- - -

clean

-
-

This target cleans the build directory, recursively removing all things - that the Makefile builds. The cleaning rules have been made guarded so they - shouldn't go awry (via rm -f $(UNSET_VARIABLE)/* which will attempt - to erase the entire directory structure.

-
- - -

clean-local

-
-

This target does the same thing as clean but only for the current - (local) directory.

-
- - -

dist

-
-

This target builds a distribution tarball. It first builds the entire - project using the all target and then tars up the necessary files and - compresses it. The generated tarball is sufficient for a casual source - distribution, but probably not for a release (see dist-check).

-
- - -

dist-check

-
-

This target does the same thing as the dist target but also checks - the distribution tarball. The check is made by unpacking the tarball to a new - directory, configuring it, building it, installing it, and then verifying that - the installation results are correct (by comparing to the original build). - This target can take a long time to run but should be done before a release - goes out to make sure that the distributed tarball can actually be built into - a working release.

-
- - -

dist-clean

-
-

This is a special form of the clean clean target. It performs a - normal clean but also removes things pertaining to building the - distribution.

-
- - -

install

-
-

This target finalizes shared objects and executables and copies all - libraries, headers, executables and documentation to the directory given - with the --prefix option to configure. When completed, - the prefix directory will have everything needed to use LLVM.

-

The LLVM makefiles can generate complete internal documentation - for all the classes by using doxygen. By default, this feature is - not enabled because it takes a long time and generates a massive - amount of data (>100MB). If you want this feature, you must configure LLVM - with the --enable-doxygen switch and ensure that a modern version of doxygen - (1.3.7 or later) is available in your PATH. You can download - doxygen from - - here. -

- - -

preconditions

-
-

This utility target checks to see if the Makefile in the object - directory is older than the Makefile in the source directory and - copies it if so. It also reruns the configure script if that needs to - be done and rebuilds the Makefile.config file similarly. Users may - overload this target to ensure that sanity checks are run before any - building of targets as all the targets depend on preconditions.

-
- - -

printvars

-
-

This utility target just causes the LLVM makefiles to print out some of - the makefile variables so that you can double check how things are set.

-
- - -

reconfigure

-
-

This utility target will force a reconfigure of LLVM or your project. It - simply runs $(PROJ_OBJ_ROOT)/config.status --recheck to rerun the - configuration tests and rebuild the configured files. This isn't generally - useful as the makefiles will reconfigure themselves whenever its necessary. -

-
- - -

spotless

-
-

This utility target, only available when $(PROJ_OBJ_ROOT) is not - the same as $(PROJ_SRC_ROOT), will completely clean the - $(PROJ_OBJ_ROOT) directory by removing its content entirely and - reconfiguring the directory. This returns the $(PROJ_OBJ_ROOT) - directory to a completely fresh state. All content in the directory except - configured files and top-level makefiles will be lost.

-

Use with caution.

-
- - -

tags

-
-

This target will generate a TAGS file in the top-level source - directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file - provides an index of symbol definitions so that the editor can jump you to the - definition quickly.

-
- - -

uninstall

-
-

This target is the opposite of the install target. It removes the - header, library and executable files from the installation directories. Note - that the directories themselves are not removed because it is not guaranteed - that LLVM is the only thing installing there (e.g. --prefix=/usr).

-
- -
- - -

Variables

- -
-

Variables are used to tell the LLVM Makefile System what to do and to - obtain information from it. Variables are also used internally by the LLVM - Makefile System. Variable names that contain only the upper case alphabetic - letters and underscore are intended for use by the end user. All other - variables are internal to the LLVM Makefile System and should not be relied - upon nor modified. The sections below describe how to use the LLVM Makefile - variables.

- - -

Control Variables

-
-

Variables listed in the table below should be set before the - inclusion of $(LEVEL)/Makefile.common. - These variables provide input to the LLVM make system that tell it what to do - for the current directory.

-
-
BUILD_ARCHIVE
-
If set to any value, causes an archive (.a) library to be built.
-
BUILT_SOURCES
-
Specifies a set of source files that are generated from other source - files. These sources will be built before any other target processing to - ensure they are present.
-
BYTECODE_LIBRARY
-
If set to any value, causes a bitcode library (.bc) to be built.
-
CONFIG_FILES
-
Specifies a set of configuration files to be installed.
-
DEBUG_SYMBOLS
-
If set to any value, causes the build to include debugging - symbols even in optimized objects, libraries and executables. This - alters the flags specified to the compilers and linkers. Debugging - isn't fun in an optimized build, but it is possible.
-
DIRS
-
Specifies a set of directories, usually children of the current - directory, that should also be made using the same goal. These directories - will be built serially.
-
DISABLE_AUTO_DEPENDENCIES
-
If set to any value, causes the makefiles to not automatically - generate dependencies when running the compiler. Use of this feature is - discouraged and it may be removed at a later date.
-
ENABLE_OPTIMIZED
-
If set to 1, causes the build to generate optimized objects, - libraries and executables. This alters the flags specified to the compilers - and linkers. Generally debugging won't be a fun experience with an optimized - build.
-
ENABLE_PROFILING
-
If set to 1, causes the build to generate both optimized and - profiled objects, libraries and executables. This alters the flags specified - to the compilers and linkers to ensure that profile data can be collected - from the tools built. Use the gprof tool to analyze the output from - the profiled tools (gmon.out).
-
DISABLE_ASSERTIONS
-
If set to 1, causes the build to disable assertions, even if - building a debug or profile build. This will exclude all assertion check - code from the build. LLVM will execute faster, but with little help when - things go wrong.
-
EXPERIMENTAL_DIRS
-
Specify a set of directories that should be built, but if they fail, it - should not cause the build to fail. Note that this should only be used - temporarily while code is being written.
-
EXPORTED_SYMBOL_FILE
-
Specifies the name of a single file that contains a list of the - symbols to be exported by the linker. One symbol per line.
-
EXPORTED_SYMBOL_LIST
-
Specifies a set of symbols to be exported by the linker.
-
EXTRA_DIST
-
Specifies additional files that should be distributed with LLVM. All - source files, all built sources, all Makefiles, and most documentation files - will be automatically distributed. Use this variable to distribute any - files that are not automatically distributed.
-
KEEP_SYMBOLS
-
If set to any value, specifies that when linking executables the - makefiles should retain debug symbols in the executable. Normally, symbols - are stripped from the executable.
-
LEVEL(required)
-
Specify the level of nesting from the top level. This variable must be - set in each makefile as it is used to find the top level and thus the other - makefiles.
-
LIBRARYNAME
-
Specify the name of the library to be built. (Required For - Libraries)
-
LINK_COMPONENTS
-
When specified for building a tool, the value of this variable will be - passed to the llvm-config tool to generate a link line for the - tool. Unlike USEDLIBS and LLVMLIBS, not all libraries need - to be specified. The llvm-config tool will figure out the library - dependencies and add any libraries that are needed. The USEDLIBS - variable can still be used in conjunction with LINK_COMPONENTS so - that additional project-specific libraries can be linked with the LLVM - libraries specified by LINK_COMPONENTS
-
LINK_LIBS_IN_SHARED
-
By default, shared library linking will ignore any libraries specified - with the LLVMLIBS or USEDLIBS. - This prevents shared libs from including things that will be in the LLVM - tool the shared library will be loaded into. However, sometimes it is useful - to link certain libraries into your shared library and this option enables - that feature.
-
LLVMLIBS
-
Specifies the set of libraries from the LLVM $(ObjDir) that will be - linked into the tool or library.
-
LOADABLE_MODULE
-
If set to any value, causes the shared library being built to also be - a loadable module. Loadable modules can be opened with the dlopen() function - and searched with dlsym (or the operating system's equivalent). Note that - setting this variable without also setting SHARED_LIBRARY will have - no effect.
-
MODULE_NAME
-
Specifies the name of a bitcode module to be created. A bitcode - module can be specified in conjunction with other kinds of library builds - or by itself. It constructs from the sources a single linked bitcode - file.
-
NO_INSTALL
-
Specifies that the build products of the directory should not be - installed but should be built even if the install target is given. - This is handy for directories that build libraries or tools that are only - used as part of the build process, such as code generators (e.g. - tblgen).
-
OPTIONAL_DIRS
-
Specify a set of directories that may be built, if they exist, but its - not an error for them not to exist.
-
PARALLEL_DIRS
-
Specify a set of directories to build recursively and in parallel if - the -j option was used with make.
-
SHARED_LIBRARY
-
If set to any value, causes a shared library (.so) to be built in - addition to any other kinds of libraries. Note that this option will cause - all source files to be built twice: once with options for position - independent code and once without. Use it only where you really need a - shared library.
-
SOURCES(optional)
-
Specifies the list of source files in the current directory to be - built. Source files of any type may be specified (programs, documentation, - config files, etc.). If not specified, the makefile system will infer the - set of source files from the files present in the current directory.
-
SUFFIXES
-
Specifies a set of filename suffixes that occur in suffix match rules. - Only set this if your local Makefile specifies additional suffix - match rules.
-
TARGET
-
Specifies the name of the LLVM code generation target that the - current directory builds. Setting this variable enables additional rules to - build .inc files from .td files.
-
TESTSUITE
-
Specifies the directory of tests to run in llvm/test.
-
TOOLNAME
-
Specifies the name of the tool that the current directory should - build.
-
TOOL_VERBOSE
-
Implies VERBOSE and also tells each tool invoked to be verbose. This is - handy when you're trying to see the sub-tools invoked by each tool invoked - by the makefile. For example, this will pass -v to the GCC - compilers which causes it to print out the command lines it uses to invoke - sub-tools (compiler, assembler, linker).
-
USEDLIBS
-
Specifies the list of project libraries that will be linked into the - tool or library.
-
VERBOSE
-
Tells the Makefile system to produce detailed output of what it is doing - instead of just summary comments. This will generate a LOT of output.
-
-
- - -

Override Variables

-
-

Override variables can be used to override the default - values provided by the LLVM makefile system. These variables can be set in - several ways:

-
    -
  • In the environment (e.g. setenv, export) -- not recommended.
  • -
  • On the make command line -- recommended.
  • -
  • On the configure command line
  • -
  • In the Makefile (only after the inclusion of $(LEVEL)/Makefile.common).
  • -
-

The override variables are given below:

-
-
AR (defaulted)
-
Specifies the path to the ar tool.
-
PROJ_OBJ_DIR
-
The directory into which the products of build rules will be placed. - This might be the same as - PROJ_SRC_DIR but typically is - not.
-
PROJ_SRC_DIR
-
The directory which contains the source files to be built.
-
BUILD_EXAMPLES
-
If set to 1, build examples in examples and (if building - Clang) tools/clang/examples directories.
-
BZIP2(configured)
-
The path to the bzip2 tool.
-
CC(configured)
-
The path to the 'C' compiler.
-
CFLAGS
-
Additional flags to be passed to the 'C' compiler.
-
CXX
-
Specifies the path to the C++ compiler.
-
CXXFLAGS
-
Additional flags to be passed to the C++ compiler.
-
DATE(configured)
-
Specifies the path to the date program or any program that can - generate the current date and time on its standard output
-
DOT(configured)
-
Specifies the path to the dot tool or false if there - isn't one.
-
ECHO(configured)
-
Specifies the path to the echo tool for printing output.
-
EXEEXT(configured)
-
Provides the extension to be used on executables built by the makefiles. - The value may be empty on platforms that do not use file extensions for - executables (e.g. Unix).
-
INSTALL(configured)
-
Specifies the path to the install tool.
-
LDFLAGS(configured)
-
Allows users to specify additional flags to pass to the linker.
-
LIBS(configured)
-
The list of libraries that should be linked with each tool.
-
LIBTOOL(configured)
-
Specifies the path to the libtool tool. This tool is renamed - mklib by the configure script and always located in the -
LLVMAS(defaulted)
-
Specifies the path to the llvm-as tool.
-
LLVMCC
-
Specifies the path to the LLVM capable compiler.
-
LLVMCXX
-
Specifies the path to the LLVM C++ capable compiler.
-
LLVMGCC(defaulted)
-
Specifies the path to the LLVM version of the GCC 'C' Compiler
-
LLVMGXX(defaulted)
-
Specifies the path to the LLVM version of the GCC C++ Compiler
-
LLVMLD(defaulted)
-
Specifies the path to the LLVM bitcode linker tool
-
LLVM_OBJ_ROOT(configured) -
-
Specifies the top directory into which the output of the build is - placed.
-
LLVM_SRC_ROOT(configured) -
-
Specifies the top directory in which the sources are found.
-
LLVM_TARBALL_NAME - (configured)
-
Specifies the name of the distribution tarball to create. This is - configured from the name of the project and its version number.
-
MKDIR(defaulted)
-
Specifies the path to the mkdir tool that creates - directories.
-
ONLY_TOOLS
-
If set, specifies the list of tools to build.
-
PLATFORMSTRIPOPTS
-
The options to provide to the linker to specify that a stripped (no - symbols) executable should be built.
-
RANLIB(defaulted)
-
Specifies the path to the ranlib tool.
-
RM(defaulted)
-
Specifies the path to the rm tool.
-
SED(defaulted)
-
Specifies the path to the sed tool.
-
SHLIBEXT(configured)
-
Provides the filename extension to use for shared libraries.
-
TBLGEN(defaulted)
-
Specifies the path to the tblgen tool.
-
TAR(defaulted)
-
Specifies the path to the tar tool.
-
ZIP(defaulted)
-
Specifies the path to the zip tool.
-
-
- - -

Readable Variables

-
-

Variables listed in the table below can be used by the user's Makefile but - should not be changed. Changing the value will generally cause the build to go - wrong, so don't do it.

-
-
bindir
-
The directory into which executables will ultimately be installed. This - value is derived from the --prefix option given to - configure.
-
BuildMode
-
The name of the type of build being performed: Debug, Release, or - Profile
-
bytecode_libdir
-
The directory into which bitcode libraries will ultimately be - installed. This value is derived from the --prefix option given to - configure.
-
ConfigureScriptFLAGS
-
Additional flags given to the configure script when - reconfiguring.
-
DistDir
-
The current directory for which a distribution copy is being - made.
-
Echo
-
The LLVM Makefile System output command. This provides the - llvm[n] prefix and starts with @ so the command itself is not - printed by make.
-
EchoCmd
-
Same as Echo but without the leading @. -
-
includedir
-
The directory into which include files will ultimately be installed. - This value is derived from the --prefix option given to - configure.
-
libdir
-
The directory into which native libraries will ultimately be installed. - This value is derived from the --prefix option given to - configure.
-
LibDir
-
The configuration specific directory into which libraries are placed - before installation.
-
MakefileConfig
-
Full path of the Makefile.config file.
-
MakefileConfigIn
-
Full path of the Makefile.config.in file.
-
ObjDir
-
The configuration and directory specific directory where build objects - (compilation results) are placed.
-
SubDirs
-
The complete list of sub-directories of the current directory as - specified by other variables.
-
Sources
-
The complete list of source files.
-
sysconfdir
-
The directory into which configuration files will ultimately be - installed. This value is derived from the --prefix option given to - configure.
-
ToolDir
-
The configuration specific directory into which executables are placed - before they are installed.
-
TopDistDir
-
The top most directory into which the distribution files are copied. -
-
Verb
-
Use this as the first thing on your build script lines to enable or - disable verbose mode. It expands to either an @ (quiet mode) or nothing - (verbose mode).
-
-
- - -

Internal Variables

-
-

Variables listed below are used by the LLVM Makefile System - and considered internal. You should not use these variables under any - circumstances.

-

- Archive - AR.Flags - BaseNameSources - BCCompile.C - BCCompile.CXX - BCLinkLib - C.Flags - Compile.C - CompileCommonOpts - Compile.CXX - ConfigStatusScript - ConfigureScript - CPP.Flags - CPP.Flags - CXX.Flags - DependFiles - DestArchiveLib - DestBitcodeLib - DestModule - DestSharedLib - DestTool - DistAlways - DistCheckDir - DistCheckTop - DistFiles - DistName - DistOther - DistSources - DistSubDirs - DistTarBZ2 - DistTarGZip - DistZip - ExtraLibs - FakeSources - INCFiles - InternalTargets - LD.Flags - LibName.A - LibName.BC - LibName.LA - LibName.O - LibTool.Flags - Link - LinkModule - LLVMLibDir - LLVMLibsOptions - LLVMLibsPaths - LLVMToolDir - LLVMUsedLibs - LocalTargets - Module - ObjectsBC - ObjectsLO - ObjectsO - ObjMakefiles - ParallelTargets - PreConditions - ProjLibsOptions - ProjLibsPaths - ProjUsedLibs - Ranlib - RecursiveTargets - SrcMakefiles - Strip - StripWarnMsg - TableGen - TDFiles - ToolBuildPath - TopLevelTargets - UserTargets -

-
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - - Reid Spencer
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/Packaging.html b/cpp/llvm/docs/Packaging.html deleted file mode 100644 index afd53775..00000000 --- a/cpp/llvm/docs/Packaging.html +++ /dev/null @@ -1,119 +0,0 @@ - - - - - Advice on Packaging LLVM - - - - -

Advice on Packaging LLVM

-
    -
  1. Overview
  2. -
  3. Compile Flags
  4. -
  5. C++ Features
  6. -
  7. Shared Library
  8. -
  9. Dependencies
  10. -
- - -

Overview

- -
- -

LLVM sets certain default configure options to make sure our developers don't -break things for constrained platforms. These settings are not optimal for most -desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts, -etc.) will tweak them. This document lists settings we suggest you tweak. -

- -

LLVM's API changes with each release, so users are likely to want, for -example, both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps -developed against each. -

-
- - -

Compile Flags

- -
- -

LLVM runs much more quickly when it's optimized and assertions are removed. -However, such a build is currently incompatible with users who build without -defining NDEBUG, and the lack of assertions makes it hard to debug problems in -user code. We recommend allowing users to install both optimized and debug -versions of LLVM in parallel. The following configure flags are relevant: -

- -
-
--disable-assertions
Builds LLVM with NDEBUG - defined. Changes the LLVM ABI. Also available by setting - DISABLE_ASSERTIONS=0|1 in make's environment. This defaults - to enabled regardless of the optimization setting, but it slows things - down.
- -
--enable-debug-symbols
Builds LLVM with -g. - Also available by setting DEBUG_SYMBOLS=0|1 in make's - environment. This defaults to disabled when optimizing, so you should turn it - back on to let users debug their programs.
- -
--enable-optimized
(For svn checkouts) Builds LLVM with - -O2 and, by default, turns off debug symbols. Also available by - setting ENABLE_OPTIMIZED=0|1 in make's environment. This - defaults to enabled when not in a checkout.
-
-
- - -

C++ Features

- -
- -
-
RTTI
LLVM disables RTTI by default. Add REQUIRES_RTTI=1 - to your environment while running make to re-enable it. This will - allow users to build with RTTI enabled and still inherit from LLVM - classes.
-
-
- - -

Shared Library

- -
- -

Configure with --enable-shared to build -libLLVM-major.minor.(so|dylib) and link the tools -against it. This saves lots of binary size at the cost of some startup time. -

-
- - -

Dependencies

- -
- -
-
--enable-libffi
Depend on libffi to allow the LLVM -interpreter to call external functions.
-
--with-oprofile
Depend on libopagent -(>=version 0.9.4) to let the LLVM JIT tell oprofile about function addresses and -line numbers.
-
-
- - -
-
- Valid CSS - Valid HTML 4.01 - The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/Passes.html b/cpp/llvm/docs/Passes.html deleted file mode 100644 index 9a615dae..00000000 --- a/cpp/llvm/docs/Passes.html +++ /dev/null @@ -1,2067 +0,0 @@ - - - - LLVM's Analysis and Transform Passes - - - - - - - -

LLVM's Analysis and Transform Passes

- -
    -
  1. Introduction
  2. -
  3. Analysis Passes -
  4. Transform Passes
  5. -
  6. Utility Passes
  7. -
- -
-

Written by Reid Spencer - and Gordon Henriksen

-
- - -

Introduction

-
-

This document serves as a high level summary of the optimization features - that LLVM provides. Optimizations are implemented as Passes that traverse some - portion of a program to either collect information or transform the program. - The table below divides the passes that LLVM provides into three categories. - Analysis passes compute information that other passes can use or for debugging - or program visualization purposes. Transform passes can use (or invalidate) - the analysis passes. Transform passes all mutate the program in some way. - Utility passes provides some utility but don't otherwise fit categorization. - For example passes to extract functions to bitcode or write a module to - bitcode are neither analysis nor transform passes. -

The table below provides a quick summary of each pass and links to the more - complete pass description later in the document.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ANALYSIS PASSES
OptionName
-aa-evalExhaustive Alias Analysis Precision Evaluator
-basicaaBasic Alias Analysis (stateless AA impl)
-basiccgBasic CallGraph Construction
-count-aaCount Alias Analysis Query Responses
-debug-aaAA use debugger
-domfrontierDominance Frontier Construction
-domtreeDominator Tree Construction
-dot-callgraphPrint Call Graph to 'dot' file
-dot-cfgPrint CFG of function to 'dot' file
-dot-cfg-onlyPrint CFG of function to 'dot' file (with no function bodies)
-dot-domPrint dominance tree of function to 'dot' file
-dot-dom-onlyPrint dominance tree of function to 'dot' file (with no function bodies)
-dot-postdomPrint postdominance tree of function to 'dot' file
-dot-postdom-onlyPrint postdominance tree of function to 'dot' file (with no function bodies)
-globalsmodref-aaSimple mod/ref analysis for globals
-instcountCounts the various types of Instructions
-intervalsInterval Partition Construction
-iv-usersInduction Variable Users
-lazy-value-infoLazy Value Information Analysis
-ldaLoop Dependence Analysis
-libcall-aaLibCall Alias Analysis
-lintStatically lint-checks LLVM IR
-loopsNatural Loop Information
-memdepMemory Dependence Analysis
-module-debuginfoDecodes module-level debug info
-no-aaNo Alias Analysis (always returns 'may' alias)
-no-profileNo Profile Information
-postdomfrontierPost-Dominance Frontier Construction
-postdomtreePost-Dominator Tree Construction
-print-alias-setsAlias Set Printer
-print-callgraphPrint a call graph
-print-callgraph-sccsPrint SCCs of the Call Graph
-print-cfg-sccsPrint SCCs of each function CFG
-print-dbginfoPrint debug info in human readable form
-print-dom-infoDominator Info Printer
-print-externalfnconstantsPrint external fn callsites passed constants
-print-functionPrint function to stderr
-print-modulePrint module to stderr
-print-used-typesFind Used Types
-profile-estimatorEstimate profiling information
-profile-loaderLoad profile information from llvmprof.out
-profile-verifierVerify profiling information
-regionsDetect single entry single exit regions
-scalar-evolutionScalar Evolution Analysis
-scev-aaScalarEvolution-based Alias Analysis
-targetdataTarget Data Layout
TRANSFORM PASSES
OptionName
-adceAggressive Dead Code Elimination
-always-inlineInliner for always_inline functions
-argpromotionPromote 'by reference' arguments to scalars
-bb-vectorizeCombine instructions to form vector instructions within basic blocks
-block-placementProfile Guided Basic Block Placement
-break-crit-edgesBreak critical edges in CFG
-codegenprepareOptimize for code generation
-constmergeMerge Duplicate Global Constants
-constpropSimple constant propagation
-dceDead Code Elimination
-deadargelimDead Argument Elimination
-deadtypeelimDead Type Elimination
-dieDead Instruction Elimination
-dseDead Store Elimination
-functionattrsDeduce function attributes
-globaldceDead Global Elimination
-globaloptGlobal Variable Optimizer
-gvnGlobal Value Numbering
-indvarsCanonicalize Induction Variables
-inlineFunction Integration/Inlining
-insert-edge-profilingInsert instrumentation for edge profiling
-insert-optimal-edge-profilingInsert optimal instrumentation for edge profiling
-instcombineCombine redundant instructions
-internalizeInternalize Global Symbols
-ipconstpropInterprocedural constant propagation
-ipsccpInterprocedural Sparse Conditional Constant Propagation
-jump-threadingJump Threading
-lcssaLoop-Closed SSA Form Pass
-licmLoop Invariant Code Motion
-loop-deletionDelete dead loops
-loop-extractExtract loops into new functions
-loop-extract-singleExtract at most one loop into a new function
-loop-reduceLoop Strength Reduction
-loop-rotateRotate Loops
-loop-simplifyCanonicalize natural loops
-loop-unrollUnroll loops
-loop-unswitchUnswitch loops
-loweratomicLower atomic intrinsics to non-atomic form
-lowerinvokeLower invoke and unwind, for unwindless code generators
-lowerswitchLower SwitchInst's to branches
-mem2regPromote Memory to Register
-memcpyoptMemCpy Optimization
-mergefuncMerge Functions
-mergereturnUnify function exit nodes
-partial-inlinerPartial Inliner
-prune-ehRemove unused exception handling info
-reassociateReassociate expressions
-reg2memDemote all values to stack slots
-scalarreplScalar Replacement of Aggregates (DT)
-sccpSparse Conditional Constant Propagation
-simplify-libcallsSimplify well-known library calls
-simplifycfgSimplify the CFG
-sinkCode sinking
-sretpromotionPromote sret arguments to multiple ret values
-stripStrip all symbols from a module
-strip-dead-debug-infoStrip debug info for unused symbols
-strip-dead-prototypesStrip Unused Function Prototypes
-strip-debug-declareStrip all llvm.dbg.declare intrinsics
-strip-nondebugStrip all symbols, except dbg symbols, from a module
-tailcallelimTail Call Elimination
-tailduplicateTail Duplication
UTILITY PASSES
OptionName
-deadarghaX0rDead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)
-extract-blocksExtract Basic Blocks From Module (for bugpoint use)
-instnamerAssign names to anonymous instructions
-preverifyPreliminary module verification
-verifyModule Verifier
-view-cfgView CFG of function
-view-cfg-onlyView CFG of function (with no function bodies)
-view-domView dominance tree of function
-view-dom-onlyView dominance tree of function (with no function bodies)
-view-postdomView postdominance tree of function
-view-postdom-onlyView postdominance tree of function (with no function bodies)
- -
- - -

Analysis Passes

-
-

This section describes the LLVM Analysis Passes.

- - -

- -aa-eval: Exhaustive Alias Analysis Precision Evaluator -

-
-

This is a simple N^2 alias analysis accuracy evaluator. - Basically, for each function in the program, it simply queries to see how the - alias analysis implementation answers alias queries between each pair of - pointers in the function.

- -

This is inspired and adapted from code by: Naveen Neelakantam, Francesco - Spadini, and Wojciech Stryjewski.

-
- - -

- -basicaa: Basic Alias Analysis (stateless AA impl) -

-
-

A basic alias analysis pass that implements identities (two different - globals cannot alias, etc), but does no stateful analysis.

-
- - -

- -basiccg: Basic CallGraph Construction -

-
-

Yet to be written.

-
- - -

- -count-aa: Count Alias Analysis Query Responses -

-
-

- A pass which can be used to count how many alias queries - are being made and how the alias analysis implementation being used responds. -

-
- - -

- -debug-aa: AA use debugger -

-
-

- This simple pass checks alias analysis users to ensure that if they - create a new value, they do not query AA without informing it of the value. - It acts as a shim over any other AA pass you want. -

- -

- Yes keeping track of every value in the program is expensive, but this is - a debugging pass. -

-
- - -

- -domfrontier: Dominance Frontier Construction -

-
-

- This pass is a simple dominator construction algorithm for finding forward - dominator frontiers. -

-
- - -

- -domtree: Dominator Tree Construction -

-
-

- This pass is a simple dominator construction algorithm for finding forward - dominators. -

-
- - -

- -dot-callgraph: Print Call Graph to 'dot' file -

-
-

- This pass, only available in opt, prints the call graph into a - .dot graph. This graph can then be processed with the "dot" tool - to convert it to postscript or some other suitable format. -

-
- - -

- -dot-cfg: Print CFG of function to 'dot' file -

-
-

- This pass, only available in opt, prints the control flow graph - into a .dot graph. This graph can then be processed with the - "dot" tool to convert it to postscript or some other suitable format. -

-
- - -

- -dot-cfg-only: Print CFG of function to 'dot' file (with no function bodies) -

-
-

- This pass, only available in opt, prints the control flow graph - into a .dot graph, omitting the function bodies. This graph can - then be processed with the "dot" tool to convert it to postscript or some - other suitable format. -

-
- - -

- -dot-dom: Print dominance tree of function to 'dot' file -

-
-

- This pass, only available in opt, prints the dominator tree - into a .dot graph. This graph can then be processed with the - "dot" tool to convert it to postscript or some other suitable format. -

-
- - -

- -dot-dom-only: Print dominance tree of function to 'dot' file (with no function bodies) -

-
-

- This pass, only available in opt, prints the dominator tree - into a .dot graph, omitting the function bodies. This graph can - then be processed with the "dot" tool to convert it to postscript or some - other suitable format. -

-
- - -

- -dot-postdom: Print postdominance tree of function to 'dot' file -

-
-

- This pass, only available in opt, prints the post dominator tree - into a .dot graph. This graph can then be processed with the - "dot" tool to convert it to postscript or some other suitable format. -

-
- - -

- -dot-postdom-only: Print postdominance tree of function to 'dot' file (with no function bodies) -

-
-

- This pass, only available in opt, prints the post dominator tree - into a .dot graph, omitting the function bodies. This graph can - then be processed with the "dot" tool to convert it to postscript or some - other suitable format. -

-
- - -

- -globalsmodref-aa: Simple mod/ref analysis for globals -

-
-

- This simple pass provides alias and mod/ref information for global values - that do not have their address taken, and keeps track of whether functions - read or write memory (are "pure"). For this simple (but very common) case, - we can provide pretty accurate and useful information. -

-
- - -

- -instcount: Counts the various types of Instructions -

-
-

- This pass collects the count of all instructions and reports them -

-
- - -

- -intervals: Interval Partition Construction -

-
-

- This analysis calculates and represents the interval partition of a function, - or a preexisting interval partition. -

- -

- In this way, the interval partition may be used to reduce a flow graph down - to its degenerate single node interval partition (unless it is irreducible). -

-
- - -

- -iv-users: Induction Variable Users -

-
-

Bookkeeping for "interesting" users of expressions computed from - induction variables.

-
- - -

- -lazy-value-info: Lazy Value Information Analysis -

-
-

Interface for lazy computation of value constraint information.

-
- - -

- -lda: Loop Dependence Analysis -

-
-

Loop dependence analysis framework, which is used to detect dependences in - memory accesses in loops.

-
- - -

- -libcall-aa: LibCall Alias Analysis -

-
-

LibCall Alias Analysis.

-
- - -

- -lint: Statically lint-checks LLVM IR -

-
-

This pass statically checks for common and easily-identified constructs - which produce undefined or likely unintended behavior in LLVM IR.

- -

It is not a guarantee of correctness, in two ways. First, it isn't - comprehensive. There are checks which could be done statically which are - not yet implemented. Some of these are indicated by TODO comments, but - those aren't comprehensive either. Second, many conditions cannot be - checked statically. This pass does no dynamic instrumentation, so it - can't check for all possible problems.

- -

Another limitation is that it assumes all code will be executed. A store - through a null pointer in a basic block which is never reached is harmless, - but this pass will warn about it anyway.

- -

Optimization passes may make conditions that this pass checks for more or - less obvious. If an optimization pass appears to be introducing a warning, - it may be that the optimization pass is merely exposing an existing - condition in the code.

- -

This code may be run before instcombine. In many cases, instcombine checks - for the same kinds of things and turns instructions with undefined behavior - into unreachable (or equivalent). Because of this, this pass makes some - effort to look through bitcasts and so on. -

-
- - -

- -loops: Natural Loop Information -

-
-

- This analysis is used to identify natural loops and determine the loop depth - of various nodes of the CFG. Note that the loops identified may actually be - several natural loops that share the same header node... not just a single - natural loop. -

-
- - -

- -memdep: Memory Dependence Analysis -

-
-

- An analysis that determines, for a given memory operation, what preceding - memory operations it depends on. It builds on alias analysis information, and - tries to provide a lazy, caching interface to a common kind of alias - information query. -

-
- - -

- -module-debuginfo: Decodes module-level debug info -

-
-

This pass decodes the debug info metadata in a module and prints in a - (sufficiently-prepared-) human-readable form. - - For example, run this pass from opt along with the -analyze option, and - it'll print to standard output. -

-
- - -

- -no-aa: No Alias Analysis (always returns 'may' alias) -

-
-

- This is the default implementation of the Alias Analysis interface. It always - returns "I don't know" for alias queries. NoAA is unlike other alias analysis - implementations, in that it does not chain to a previous analysis. As such it - doesn't follow many of the rules that other alias analyses must. -

-
- - -

- -no-profile: No Profile Information -

-
-

- The default "no profile" implementation of the abstract - ProfileInfo interface. -

-
- - -

- -postdomfrontier: Post-Dominance Frontier Construction -

-
-

- This pass is a simple post-dominator construction algorithm for finding - post-dominator frontiers. -

-
- - -

- -postdomtree: Post-Dominator Tree Construction -

-
-

- This pass is a simple post-dominator construction algorithm for finding - post-dominators. -

-
- - -

- -print-alias-sets: Alias Set Printer -

-
-

Yet to be written.

-
- - -

- -print-callgraph: Print a call graph -

-
-

- This pass, only available in opt, prints the call graph to - standard error in a human-readable form. -

-
- - -

- -print-callgraph-sccs: Print SCCs of the Call Graph -

-
-

- This pass, only available in opt, prints the SCCs of the call - graph to standard error in a human-readable form. -

-
- - -

- -print-cfg-sccs: Print SCCs of each function CFG -

-
-

- This pass, only available in opt, prints the SCCs of each - function CFG to standard error in a human-readable form. -

-
- - -

- -print-dbginfo: Print debug info in human readable form -

-
-

Pass that prints instructions, and associated debug info:

-
    - -
  • source/line/col information
  • -
  • original variable name
  • -
  • original type name
  • -
-
- - -

- -print-dom-info: Dominator Info Printer -

-
-

Dominator Info Printer.

-
- - -

- -print-externalfnconstants: Print external fn callsites passed constants -

-
-

- This pass, only available in opt, prints out call sites to - external functions that are called with constant arguments. This can be - useful when looking for standard library functions we should constant fold - or handle in alias analyses. -

-
- - -

- -print-function: Print function to stderr -

-
-

- The PrintFunctionPass class is designed to be pipelined with - other FunctionPasses, and prints out the functions of the module - as they are processed. -

-
- - -

- -print-module: Print module to stderr -

-
-

- This pass simply prints out the entire module when it is executed. -

-
- - -

- -print-used-types: Find Used Types -

-
-

- This pass is used to seek out all of the types in use by the program. Note - that this analysis explicitly does not include types only used by the symbol - table. -

- - -

- -profile-estimator: Estimate profiling information -

-
-

Profiling information that estimates the profiling information - in a very crude and unimaginative way. -

-
- - -

- -profile-loader: Load profile information from llvmprof.out -

-
-

- A concrete implementation of profiling information that loads the information - from a profile dump file. -

-
- - -

- -profile-verifier: Verify profiling information -

-
-

Pass that checks profiling information for plausibility.

-
-

- -regions: Detect single entry single exit regions -

-
-

- The RegionInfo pass detects single entry single exit regions in a - function, where a region is defined as any subgraph that is connected to the - remaining graph at only two spots. Furthermore, an hierarchical region tree is - built. -

-
- - -

- -scalar-evolution: Scalar Evolution Analysis -

-
-

- The ScalarEvolution analysis can be used to analyze and - catagorize scalar expressions in loops. It specializes in recognizing general - induction variables, representing them with the abstract and opaque - SCEV class. Given this analysis, trip counts of loops and other - important properties can be obtained. -

- -

- This analysis is primarily useful for induction variable substitution and - strength reduction. -

-
- - -

- -scev-aa: ScalarEvolution-based Alias Analysis -

-
-

Simple alias analysis implemented in terms of ScalarEvolution queries. - - This differs from traditional loop dependence analysis in that it tests - for dependencies within a single iteration of a loop, rather than - dependencies between different iterations. - - ScalarEvolution has a more complete understanding of pointer arithmetic - than BasicAliasAnalysis' collection of ad-hoc analyses. -

-
- - -

- -targetdata: Target Data Layout -

-
-

Provides other passes access to information on how the size and alignment - required by the the target ABI for various data types.

-
- -
- - -

Transform Passes

-
-

This section describes the LLVM Transform Passes.

- - -

- -adce: Aggressive Dead Code Elimination -

-
-

ADCE aggressively tries to eliminate code. This pass is similar to - DCE but it assumes that values are dead until proven - otherwise. This is similar to SCCP, except applied to - the liveness of values.

-
- - -

- -always-inline: Inliner for always_inline functions -

-
-

A custom inliner that handles only functions that are marked as - "always inline".

-
- - -

- -argpromotion: Promote 'by reference' arguments to scalars -

-
-

- This pass promotes "by reference" arguments to be "by value" arguments. In - practice, this means looking for internal functions that have pointer - arguments. If it can prove, through the use of alias analysis, that an - argument is *only* loaded, then it can pass the value into the function - instead of the address of the value. This can cause recursive simplification - of code and lead to the elimination of allocas (especially in C++ template - code like the STL). -

- -

- This pass also handles aggregate arguments that are passed into a function, - scalarizing them if the elements of the aggregate are only loaded. Note that - it refuses to scalarize aggregates which would require passing in more than - three operands to the function, because passing thousands of operands for a - large array or structure is unprofitable! -

- -

- Note that this transformation could also be done for arguments that are only - stored to (returning the value instead), but does not currently. This case - would be best handled when and if LLVM starts supporting multiple return - values from functions. -

-
- - -

- -bb-vectorize: Basic-Block Vectorization -

-
-

This pass combines instructions inside basic blocks to form vector - instructions. It iterates over each basic block, attempting to pair - compatible instructions, repeating this process until no additional - pairs are selected for vectorization. When the outputs of some pair - of compatible instructions are used as inputs by some other pair of - compatible instructions, those pairs are part of a potential - vectorization chain. Instruction pairs are only fused into vector - instructions when they are part of a chain longer than some - threshold length. Moreover, the pass attempts to find the best - possible chain for each pair of compatible instructions. These - heuristics are intended to prevent vectorization in cases where - it would not yield a performance increase of the resulting code. -

-
- - -

- -block-placement: Profile Guided Basic Block Placement -

-
-

This pass is a very simple profile guided basic block placement algorithm. - The idea is to put frequently executed blocks together at the start of the - function and hopefully increase the number of fall-through conditional - branches. If there is no profile information for a particular function, this - pass basically orders blocks in depth-first order.

-
- - -

- -break-crit-edges: Break critical edges in CFG -

-
-

- Break all of the critical edges in the CFG by inserting a dummy basic block. - It may be "required" by passes that cannot deal with critical edges. This - transformation obviously invalidates the CFG, but can update forward dominator - (set, immediate dominators, tree, and frontier) information. -

-
- - -

- -codegenprepare: Optimize for code generation -

-
- This pass munges the code in the input function to better prepare it for - SelectionDAG-based code generation. This works around limitations in it's - basic-block-at-a-time approach. It should eventually be removed. -
- - -

- -constmerge: Merge Duplicate Global Constants -

-
-

- Merges duplicate global constants together into a single constant that is - shared. This is useful because some passes (ie TraceValues) insert a lot of - string constants into the program, regardless of whether or not an existing - string is available. -

-
- - -

- -constprop: Simple constant propagation -

-
-

This file implements constant propagation and merging. It looks for - instructions involving only constant operands and replaces them with a - constant value instead of an instruction. For example:

-
add i32 1, 2
-

becomes

-
i32 3
-

NOTE: this pass has a habit of making definitions be dead. It is a good - idea to to run a DIE (Dead Instruction Elimination) pass - sometime after running this pass.

-
- - -

- -dce: Dead Code Elimination -

-
-

- Dead code elimination is similar to dead instruction - elimination, but it rechecks instructions that were used by removed - instructions to see if they are newly dead. -

-
- - -

- -deadargelim: Dead Argument Elimination -

-
-

- This pass deletes dead arguments from internal functions. Dead argument - elimination removes arguments which are directly dead, as well as arguments - only passed into function calls as dead arguments of other functions. This - pass also deletes dead arguments in a similar way. -

- -

- This pass is often useful as a cleanup pass to run after aggressive - interprocedural passes, which add possibly-dead arguments. -

-
- - -

- -deadtypeelim: Dead Type Elimination -

-
-

- This pass is used to cleanup the output of GCC. It eliminate names for types - that are unused in the entire translation unit, using the find used types pass. -

-
- - -

- -die: Dead Instruction Elimination -

-
-

- Dead instruction elimination performs a single pass over the function, - removing instructions that are obviously dead. -

-
- - -

- -dse: Dead Store Elimination -

-
-

- A trivial dead store elimination that only considers basic-block local - redundant stores. -

-
- - -

- -functionattrs: Deduce function attributes -

-
-

A simple interprocedural pass which walks the call-graph, looking for - functions which do not access or only read non-local memory, and marking them - readnone/readonly. In addition, it marks function arguments (of pointer type) - 'nocapture' if a call to the function does not create any copies of the pointer - value that outlive the call. This more or less means that the pointer is only - dereferenced, and not returned from the function or stored in a global. - This pass is implemented as a bottom-up traversal of the call-graph. -

-
- - -

- -globaldce: Dead Global Elimination -

-
-

- This transform is designed to eliminate unreachable internal globals from the - program. It uses an aggressive algorithm, searching out globals that are - known to be alive. After it finds all of the globals which are needed, it - deletes whatever is left over. This allows it to delete recursive chunks of - the program which are unreachable. -

-
- - -

- -globalopt: Global Variable Optimizer -

-
-

- This pass transforms simple global variables that never have their address - taken. If obviously true, it marks read/write globals as constant, deletes - variables only stored to, etc. -

-
- - -

- -gvn: Global Value Numbering -

-
-

- This pass performs global value numbering to eliminate fully and partially - redundant instructions. It also performs redundant load elimination. -

-
- - -

- -indvars: Canonicalize Induction Variables -

-
-

- This transformation analyzes and transforms the induction variables (and - computations derived from them) into simpler forms suitable for subsequent - analysis and transformation. -

- -

- This transformation makes the following changes to each loop with an - identifiable induction variable: -

- -
    -
  1. All loops are transformed to have a single canonical - induction variable which starts at zero and steps by one.
  2. -
  3. The canonical induction variable is guaranteed to be the first PHI node - in the loop header block.
  4. -
  5. Any pointer arithmetic recurrences are raised to use array - subscripts.
  6. -
- -

- If the trip count of a loop is computable, this pass also makes the following - changes: -

- -
    -
  1. The exit condition for the loop is canonicalized to compare the - induction value against the exit value. This turns loops like: -
    for (i = 7; i*i < 1000; ++i)
    - into -
    for (i = 0; i != 25; ++i)
  2. -
  3. Any use outside of the loop of an expression derived from the indvar - is changed to compute the derived value outside of the loop, eliminating - the dependence on the exit value of the induction variable. If the only - purpose of the loop is to compute the exit value of some derived - expression, this transformation will make the loop dead.
  4. -
- -

- This transformation should be followed by strength reduction after all of the - desired loop transformations have been performed. Additionally, on targets - where it is profitable, the loop could be transformed to count down to zero - (the "do loop" optimization). -

-
- - -

- -inline: Function Integration/Inlining -

-
-

- Bottom-up inlining of functions into callees. -

-
- - -

- -insert-edge-profiling: Insert instrumentation for edge profiling -

-
-

- This pass instruments the specified program with counters for edge profiling. - Edge profiling can give a reasonable approximation of the hot paths through a - program, and is used for a wide variety of program transformations. -

- -

- Note that this implementation is very naïve. It inserts a counter for - every edge in the program, instead of using control flow information - to prune the number of counters inserted. -

-
- - -

- -insert-optimal-edge-profiling: Insert optimal instrumentation for edge profiling -

-
-

This pass instruments the specified program with counters for edge profiling. - Edge profiling can give a reasonable approximation of the hot paths through a - program, and is used for a wide variety of program transformations. -

-
- - -

- -instcombine: Combine redundant instructions -

-
-

- Combine instructions to form fewer, simple - instructions. This pass does not modify the CFG This pass is where algebraic - simplification happens. -

- -

- This pass combines things like: -

- -
%Y = add i32 %X, 1
-%Z = add i32 %Y, 1
- -

- into: -

- -
%Z = add i32 %X, 2
- -

- This is a simple worklist driven algorithm. -

- -

- This pass guarantees that the following canonicalizations are performed on - the program: -

- -
    -
  • If a binary operator has a constant operand, it is moved to the right- - hand side.
  • -
  • Bitwise operators with constant operands are always grouped so that - shifts are performed first, then ors, then - ands, then xors.
  • -
  • Compare instructions are converted from <, - >, ≤, or ≥ to - = or ≠ if possible.
  • -
  • All cmp instructions on boolean values are replaced with - logical operations.
  • -
  • add X, X is represented as - mul X, 2 ⇒ shl X, 1
  • -
  • Multiplies with a constant power-of-two argument are transformed into - shifts.
  • -
  • … etc.
  • -
-
- - -

- -internalize: Internalize Global Symbols -

-
-

- This pass loops over all of the functions in the input module, looking for a - main function. If a main function is found, all other functions and all - global variables with initializers are marked as internal. -

-
- - -

- -ipconstprop: Interprocedural constant propagation -

-
-

- This pass implements an extremely simple interprocedural constant - propagation pass. It could certainly be improved in many different ways, - like using a worklist. This pass makes arguments dead, but does not remove - them. The existing dead argument elimination pass should be run after this - to clean up the mess. -

-
- - -

- -ipsccp: Interprocedural Sparse Conditional Constant Propagation -

-
-

- An interprocedural variant of Sparse Conditional Constant - Propagation. -

-
- - -

- -jump-threading: Jump Threading -

-
-

- Jump threading tries to find distinct threads of control flow running through - a basic block. This pass looks at blocks that have multiple predecessors and - multiple successors. If one or more of the predecessors of the block can be - proven to always cause a jump to one of the successors, we forward the edge - from the predecessor to the successor by duplicating the contents of this - block. -

-

- An example of when this can occur is code like this: -

- -
if () { ...
-  X = 4;
-}
-if (X < 3) {
- -

- In this case, the unconditional branch at the end of the first if can be - revectored to the false side of the second if. -

-
- - -

- -lcssa: Loop-Closed SSA Form Pass -

-
-

- This pass transforms loops by placing phi nodes at the end of the loops for - all values that are live across the loop boundary. For example, it turns - the left into the right code: -

- -
for (...)                for (...)
-  if (c)                   if (c)
-    X1 = ...                 X1 = ...
-  else                     else
-    X2 = ...                 X2 = ...
-  X3 = phi(X1, X2)         X3 = phi(X1, X2)
-... = X3 + 4              X4 = phi(X3)
-                          ... = X4 + 4
- -

- This is still valid LLVM; the extra phi nodes are purely redundant, and will - be trivially eliminated by InstCombine. The major benefit of - this transformation is that it makes many other loop optimizations, such as - LoopUnswitching, simpler. -

-
- - -

- -licm: Loop Invariant Code Motion -

-
-

- This pass performs loop invariant code motion, attempting to remove as much - code from the body of a loop as possible. It does this by either hoisting - code into the preheader block, or by sinking code to the exit blocks if it is - safe. This pass also promotes must-aliased memory locations in the loop to - live in registers, thus hoisting and sinking "invariant" loads and stores. -

- -

- This pass uses alias analysis for two purposes: -

- -
    -
  • Moving loop invariant loads and calls out of loops. If we can determine - that a load or call inside of a loop never aliases anything stored to, - we can hoist it or sink it like any other instruction.
  • -
  • Scalar Promotion of Memory - If there is a store instruction inside of - the loop, we try to move the store to happen AFTER the loop instead of - inside of the loop. This can only happen if a few conditions are true: -
      -
    • The pointer stored through is loop invariant.
    • -
    • There are no stores or loads in the loop which may alias - the pointer. There are no calls in the loop which mod/ref the - pointer.
    • -
    - If these conditions are true, we can promote the loads and stores in the - loop of the pointer to use a temporary alloca'd variable. We then use - the mem2reg functionality to construct the appropriate SSA form for the - variable.
  • -
-
- - -

- -loop-deletion: Delete dead loops -

-
-

- This file implements the Dead Loop Deletion Pass. This pass is responsible - for eliminating loops with non-infinite computable trip counts that have no - side effects or volatile instructions, and do not contribute to the - computation of the function's return value. -

-
- - -

- -loop-extract: Extract loops into new functions -

-
-

- A pass wrapper around the ExtractLoop() scalar transformation to - extract each top-level loop into its own new function. If the loop is the - only loop in a given function, it is not touched. This is a pass most - useful for debugging via bugpoint. -

-
- - -

- -loop-extract-single: Extract at most one loop into a new function -

-
-

- Similar to Extract loops into new functions, - this pass extracts one natural loop from the program into a function if it - can. This is used by bugpoint. -

-
- - -

- -loop-reduce: Loop Strength Reduction -

-
-

- This pass performs a strength reduction on array references inside loops that - have as one or more of their components the loop induction variable. This is - accomplished by creating a new value to hold the initial value of the array - access for the first iteration, and then creating a new GEP instruction in - the loop to increment the value by the appropriate amount. -

-
- - -

- -loop-rotate: Rotate Loops -

-
-

A simple loop rotation transformation.

-
- - -

- -loop-simplify: Canonicalize natural loops -

-
-

- This pass performs several transformations to transform natural loops into a - simpler form, which makes subsequent analyses and transformations simpler and - more effective. -

- -

- Loop pre-header insertion guarantees that there is a single, non-critical - entry edge from outside of the loop to the loop header. This simplifies a - number of analyses and transformations, such as LICM. -

- -

- Loop exit-block insertion guarantees that all exit blocks from the loop - (blocks which are outside of the loop that have predecessors inside of the - loop) only have predecessors from inside of the loop (and are thus dominated - by the loop header). This simplifies transformations such as store-sinking - that are built into LICM. -

- -

- This pass also guarantees that loops will have exactly one backedge. -

- -

- Note that the simplifycfg pass will clean up blocks which are split out but - end up being unnecessary, so usage of this pass should not pessimize - generated code. -

- -

- This pass obviously modifies the CFG, but updates loop information and - dominator information. -

-
- - -

- -loop-unroll: Unroll loops -

-
-

- This pass implements a simple loop unroller. It works best when loops have - been canonicalized by the -indvars pass, - allowing it to determine the trip counts of loops easily. -

-
- - -

- -loop-unswitch: Unswitch loops -

-
-

- This pass transforms loops that contain branches on loop-invariant conditions - to have multiple loops. For example, it turns the left into the right code: -

- -
for (...)                  if (lic)
-  A                          for (...)
-  if (lic)                     A; B; C
-    B                      else
-  C                          for (...)
-                               A; C
- -

- This can increase the size of the code exponentially (doubling it every time - a loop is unswitched) so we only unswitch if the resultant code will be - smaller than a threshold. -

- -

- This pass expects LICM to be run before it to hoist invariant conditions out - of the loop, to make the unswitching opportunity obvious. -

-
- - -

- -loweratomic: Lower atomic intrinsics to non-atomic form -

-
-

- This pass lowers atomic intrinsics to non-atomic form for use in a known - non-preemptible environment. -

- -

- The pass does not verify that the environment is non-preemptible (in - general this would require knowledge of the entire call graph of the - program including any libraries which may not be available in bitcode form); - it simply lowers every atomic intrinsic. -

-
- - -

- -lowerinvoke: Lower invoke and unwind, for unwindless code generators -

-
-

- This transformation is designed for use by code generators which do not yet - support stack unwinding. This pass supports two models of exception handling - lowering, the 'cheap' support and the 'expensive' support. -

- -

- 'Cheap' exception handling support gives the program the ability to execute - any program which does not "throw an exception", by turning 'invoke' - instructions into calls and by turning 'unwind' instructions into calls to - abort(). If the program does dynamically use the unwind instruction, the - program will print a message then abort. -

- -

- 'Expensive' exception handling support gives the full exception handling - support to the program at the cost of making the 'invoke' instruction - really expensive. It basically inserts setjmp/longjmp calls to emulate the - exception handling as necessary. -

- -

- Because the 'expensive' support slows down programs a lot, and EH is only - used for a subset of the programs, it must be specifically enabled by the - -enable-correct-eh-support option. -

- -

- Note that after this pass runs the CFG is not entirely accurate (exceptional - control flow edges are not correct anymore) so only very simple things should - be done after the lowerinvoke pass has run (like generation of native code). - This should not be used as a general purpose "my LLVM-to-LLVM pass doesn't - support the invoke instruction yet" lowering pass. -

-
- - -

- -lowerswitch: Lower SwitchInst's to branches -

-
-

- Rewrites switch instructions with a sequence of branches, which - allows targets to get away with not implementing the switch instruction until - it is convenient. -

-
- - -

- -mem2reg: Promote Memory to Register -

-
-

- This file promotes memory references to be register references. It promotes - alloca instructions which only have loads and - stores as uses. An alloca is transformed by using dominator - frontiers to place phi nodes, then traversing the function in - depth-first order to rewrite loads and stores as - appropriate. This is just the standard SSA construction algorithm to construct - "pruned" SSA form. -

-
- - -

- -memcpyopt: MemCpy Optimization -

-
-

- This pass performs various transformations related to eliminating memcpy - calls, or transforming sets of stores into memset's. -

-
- - -

- -mergefunc: Merge Functions -

-
-

This pass looks for equivalent functions that are mergable and folds them. - - A hash is computed from the function, based on its type and number of - basic blocks. - - Once all hashes are computed, we perform an expensive equality comparison - on each function pair. This takes n^2/2 comparisons per bucket, so it's - important that the hash function be high quality. The equality comparison - iterates through each instruction in each basic block. - - When a match is found the functions are folded. If both functions are - overridable, we move the functionality into a new internal function and - leave two overridable thunks to it. -

-
- - -

- -mergereturn: Unify function exit nodes -

-
-

- Ensure that functions have at most one ret instruction in them. - Additionally, it keeps track of which node is the new exit node of the CFG. -

-
- - -

- -partial-inliner: Partial Inliner -

-
-

This pass performs partial inlining, typically by inlining an if - statement that surrounds the body of the function. -

-
- - -

- -prune-eh: Remove unused exception handling info -

-
-

- This file implements a simple interprocedural pass which walks the call-graph, - turning invoke instructions into call instructions if and - only if the callee cannot throw an exception. It implements this as a - bottom-up traversal of the call-graph. -

-
- - -

- -reassociate: Reassociate expressions -

-
-

- This pass reassociates commutative expressions in an order that is designed - to promote better constant propagation, GCSE, LICM, PRE, etc. -

- -

- For example: 4 + (x + 5) ⇒ x + (4 + 5) -

- -

- In the implementation of this algorithm, constants are assigned rank = 0, - function arguments are rank = 1, and other values are assigned ranks - corresponding to the reverse post order traversal of current function - (starting at 2), which effectively gives values in deep loops higher rank - than values not in loops. -

-
- - -

- -reg2mem: Demote all values to stack slots -

-
-

- This file demotes all registers to memory references. It is intented to be - the inverse of -mem2reg. By converting to - load instructions, the only values live across basic blocks are - alloca instructions and load instructions before - phi nodes. It is intended that this should make CFG hacking much - easier. To make later hacking easier, the entry block is split into two, such - that all introduced alloca instructions (and nothing else) are in the - entry block. -

-
- - -

- -scalarrepl: Scalar Replacement of Aggregates (DT) -

-
-

- The well-known scalar replacement of aggregates transformation. This - transform breaks up alloca instructions of aggregate type (structure - or array) into individual alloca instructions for each member if - possible. Then, if possible, it transforms the individual alloca - instructions into nice clean scalar SSA form. -

- -

- This combines a simple scalar replacement of aggregates algorithm with the mem2reg algorithm because often interact, - especially for C++ programs. As such, iterating between scalarrepl, - then mem2reg until we run out of things to - promote works well. -

-
- - -

- -sccp: Sparse Conditional Constant Propagation -

-
-

- Sparse conditional constant propagation and merging, which can be summarized - as: -

- -
    -
  1. Assumes values are constant unless proven otherwise
  2. -
  3. Assumes BasicBlocks are dead unless proven otherwise
  4. -
  5. Proves values to be constant, and replaces them with constants
  6. -
  7. Proves conditional branches to be unconditional
  8. -
- -

- Note that this pass has a habit of making definitions be dead. It is a good - idea to to run a DCE pass sometime after running this pass. -

-
- - -

- -simplify-libcalls: Simplify well-known library calls -

-
-

- Applies a variety of small optimizations for calls to specific well-known - function calls (e.g. runtime library functions). For example, a call - exit(3) that occurs within the main() function can be - transformed into simply return 3. -

-
- - -

- -simplifycfg: Simplify the CFG -

-
-

- Performs dead code elimination and basic block merging. Specifically: -

- -
    -
  1. Removes basic blocks with no predecessors.
  2. -
  3. Merges a basic block into its predecessor if there is only one and the - predecessor only has one successor.
  4. -
  5. Eliminates PHI nodes for basic blocks with a single predecessor.
  6. -
  7. Eliminates a basic block that only contains an unconditional - branch.
  8. -
-
- - -

- -sink: Code sinking -

-
-

This pass moves instructions into successor blocks, when possible, so that - they aren't executed on paths where their results aren't needed. -

-
- - -

- -sretpromotion: Promote sret arguments to multiple ret values -

-
-

- This pass finds functions that return a struct (using a pointer to the struct - as the first argument of the function, marked with the 'sret' attribute) and - replaces them with a new function that simply returns each of the elements of - that struct (using multiple return values). -

- -

- This pass works under a number of conditions: -

- -
    -
  • The returned struct must not contain other structs
  • -
  • The returned struct must only be used to load values from
  • -
  • The placeholder struct passed in is the result of an alloca
  • -
-
- - -

- -strip: Strip all symbols from a module -

-
-

- performs code stripping. this transformation can delete: -

- -
    -
  1. names for virtual registers
  2. -
  3. symbols for internal globals and functions
  4. -
  5. debug information
  6. -
- -

- note that this transformation makes code much less readable, so it should - only be used in situations where the strip utility would be used, - such as reducing code size or making it harder to reverse engineer code. -

-
- - -

- -strip-dead-debug-info: Strip debug info for unused symbols -

-
-

- performs code stripping. this transformation can delete: -

- -
    -
  1. names for virtual registers
  2. -
  3. symbols for internal globals and functions
  4. -
  5. debug information
  6. -
- -

- note that this transformation makes code much less readable, so it should - only be used in situations where the strip utility would be used, - such as reducing code size or making it harder to reverse engineer code. -

-
- - -

- -strip-dead-prototypes: Strip Unused Function Prototypes -

-
-

- This pass loops over all of the functions in the input module, looking for - dead declarations and removes them. Dead declarations are declarations of - functions for which no implementation is available (i.e., declarations for - unused library functions). -

-
- - -

- -strip-debug-declare: Strip all llvm.dbg.declare intrinsics -

-
-

This pass implements code stripping. Specifically, it can delete:

-
    -
  • names for virtual registers
  • -
  • symbols for internal globals and functions
  • -
  • debug information
  • -
-

- Note that this transformation makes code much less readable, so it should - only be used in situations where the 'strip' utility would be used, such as - reducing code size or making it harder to reverse engineer code. -

-
- - -

- -strip-nondebug: Strip all symbols, except dbg symbols, from a module -

-
-

This pass implements code stripping. Specifically, it can delete:

-
    -
  • names for virtual registers
  • -
  • symbols for internal globals and functions
  • -
  • debug information
  • -
-

- Note that this transformation makes code much less readable, so it should - only be used in situations where the 'strip' utility would be used, such as - reducing code size or making it harder to reverse engineer code. -

-
- - -

- -tailcallelim: Tail Call Elimination -

-
-

- This file transforms calls of the current function (self recursion) followed - by a return instruction with a branch to the entry of the function, creating - a loop. This pass also implements the following extensions to the basic - algorithm: -

- -
    -
  • Trivial instructions between the call and return do not prevent the - transformation from taking place, though currently the analysis cannot - support moving any really useful instructions (only dead ones). -
  • This pass transforms functions that are prevented from being tail - recursive by an associative expression to use an accumulator variable, - thus compiling the typical naive factorial or fib implementation - into efficient code. -
  • TRE is performed if the function returns void, if the return - returns the result returned by the call, or if the function returns a - run-time constant on all exits from the function. It is possible, though - unlikely, that the return returns something else (like constant 0), and - can still be TRE'd. It can be TRE'd if all other return - instructions in the function return the exact same value. -
  • If it can prove that callees do not access theier caller stack frame, - they are marked as eligible for tail call elimination (by the code - generator). -
-
- - -

- -tailduplicate: Tail Duplication -

-
-

- This pass performs a limited form of tail duplication, intended to simplify - CFGs by removing some unconditional branches. This pass is necessary to - straighten out loops created by the C front-end, but also is capable of - making other code nicer. After this pass is run, the CFG simplify pass - should be run to clean up the mess. -

-
- -
- - -

Utility Passes

-
-

This section describes the LLVM Utility Passes.

- - -

- -deadarghaX0r: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE) -

-
-

- Same as dead argument elimination, but deletes arguments to functions which - are external. This is only for use by bugpoint.

-
- - -

- -extract-blocks: Extract Basic Blocks From Module (for bugpoint use) -

-
-

- This pass is used by bugpoint to extract all blocks from the module into their - own functions.

-
- - -

- -instnamer: Assign names to anonymous instructions -

-
-

This is a little utility pass that gives instructions names, this is mostly - useful when diffing the effect of an optimization because deleting an - unnamed instruction can change all other instruction numbering, making the - diff very noisy. -

-
- - -

- -preverify: Preliminary module verification -

-
-

- Ensures that the module is in the form required by the Module Verifier pass. -

- -

- Running the verifier runs this pass automatically, so there should be no need - to use it directly. -

-
- - -

- -verify: Module Verifier -

-
-

- Verifies an LLVM IR code. This is useful to run after an optimization which is - undergoing testing. Note that llvm-as verifies its input before - emitting bitcode, and also that malformed bitcode is likely to make LLVM - crash. All language front-ends are therefore encouraged to verify their output - before performing optimizing transformations. -

- -
    -
  • Both of a binary operator's parameters are of the same type.
  • -
  • Verify that the indices of mem access instructions match other - operands.
  • -
  • Verify that arithmetic and other things are only performed on - first-class types. Verify that shifts and logicals only happen on - integrals f.e.
  • -
  • All of the constants in a switch statement are of the correct type.
  • -
  • The code is in valid SSA form.
  • -
  • It is illegal to put a label into any other type (like a structure) or - to return one.
  • -
  • Only phi nodes can be self referential: %x = add i32 %x, %x is - invalid.
  • -
  • PHI nodes must have an entry for each predecessor, with no extras.
  • -
  • PHI nodes must be the first thing in a basic block, all grouped - together.
  • -
  • PHI nodes must have at least one entry.
  • -
  • All basic blocks should only end with terminator insts, not contain - them.
  • -
  • The entry node to a function must not have predecessors.
  • -
  • All Instructions must be embedded into a basic block.
  • -
  • Functions cannot take a void-typed parameter.
  • -
  • Verify that a function's argument list agrees with its declared - type.
  • -
  • It is illegal to specify a name for a void value.
  • -
  • It is illegal to have a internal global value with no initializer.
  • -
  • It is illegal to have a ret instruction that returns a value that does - not agree with the function return value type.
  • -
  • Function call argument types match the function prototype.
  • -
  • All other things that are tested by asserts spread about the code.
  • -
- -

- Note that this does not provide full security verification (like Java), but - instead just tries to ensure that code is well-formed. -

-
- - -

- -view-cfg: View CFG of function -

-
-

- Displays the control flow graph using the GraphViz tool. -

-
- - -

- -view-cfg-only: View CFG of function (with no function bodies) -

-
-

- Displays the control flow graph using the GraphViz tool, but omitting function - bodies. -

-
- - -

- -view-dom: View dominance tree of function -

-
-

- Displays the dominator tree using the GraphViz tool. -

-
- - -

- -view-dom-only: View dominance tree of function (with no function bodies) -

-
-

- Displays the dominator tree using the GraphViz tool, but omitting function - bodies. -

-
- - -

- -view-postdom: View postdominance tree of function -

-
-

- Displays the post dominator tree using the GraphViz tool. -

-
- - -

- -view-postdom-only: View postdominance tree of function (with no function bodies) -

-
-

- Displays the post dominator tree using the GraphViz tool, but omitting - function bodies. -

-
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Reid Spencer
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-01-31 19:51:43 -0800 (Tue, 31 Jan 2012) $ -
- - - diff --git a/cpp/llvm/docs/ProgrammersManual.html b/cpp/llvm/docs/ProgrammersManual.html deleted file mode 100644 index 7f3b166d..00000000 --- a/cpp/llvm/docs/ProgrammersManual.html +++ /dev/null @@ -1,4135 +0,0 @@ - - - - - LLVM Programmer's Manual - - - - -

- LLVM Programmer's Manual -

- -
    -
  1. Introduction
  2. -
  3. General Information - -
  4. -
  5. Important and useful LLVM APIs - -
  6. -
  7. Picking the Right Data Structure for a Task - -
  8. -
  9. Helpful Hints for Common Operations - -
  10. - -
  11. Threads and LLVM - -
  12. - -
  13. Advanced Topics -
  14. - -
  15. The Core LLVM Class Hierarchy Reference - -
  16. -
- - - - -

- Introduction -

- - -
- -

This document is meant to highlight some of the important classes and -interfaces available in the LLVM source-base. This manual is not -intended to explain what LLVM is, how it works, and what LLVM code looks -like. It assumes that you know the basics of LLVM and are interested -in writing transformations or otherwise analyzing or manipulating the -code.

- -

This document should get you oriented so that you can find your -way in the continuously growing source code that makes up the LLVM -infrastructure. Note that this manual is not intended to serve as a -replacement for reading the source code, so if you think there should be -a method in one of these classes to do something, but it's not listed, -check the source. Links to the doxygen sources -are provided to make this as easy as possible.

- -

The first section of this document describes general information that is -useful to know when working in the LLVM infrastructure, and the second describes -the Core LLVM classes. In the future this manual will be extended with -information describing how to use extension libraries, such as dominator -information, CFG traversal routines, and useful utilities like the InstVisitor template.

- -
- - -

- General Information -

- - -
- -

This section contains general information that is useful if you are working -in the LLVM source-base, but that isn't specific to any particular API.

- - -

- The C++ Standard Template Library -

- -
- -

LLVM makes heavy use of the C++ Standard Template Library (STL), -perhaps much more than you are used to, or have seen before. Because of -this, you might want to do a little background reading in the -techniques used and capabilities of the library. There are many good -pages that discuss the STL, and several books on the subject that you -can get, so it will not be discussed in this document.

- -

Here are some useful links:

- -
    - -
  1. Dinkumware -C++ Library reference - an excellent reference for the STL and other parts -of the standard C++ library.
  2. - -
  3. C++ In a Nutshell - This is an -O'Reilly book in the making. It has a decent Standard Library -Reference that rivals Dinkumware's, and is unfortunately no longer free since the -book has been published.
  4. - -
  5. C++ Frequently Asked -Questions
  6. - -
  7. SGI's STL Programmer's Guide - -Contains a useful Introduction to the -STL.
  8. - -
  9. Bjarne Stroustrup's C++ -Page
  10. - -
  11. -Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get -the book).
  12. - -
- -

You are also encouraged to take a look at the LLVM Coding Standards guide which focuses on how -to write maintainable code more than where to put your curly braces.

- -
- - -

- Other useful references -

- - - -
- - -

- Important and useful LLVM APIs -

- - -
- -

Here we highlight some LLVM APIs that are generally useful and good to -know about when writing transformations.

- - -

- The isa<>, cast<> and - dyn_cast<> templates -

- -
- -

The LLVM source-base makes extensive use of a custom form of RTTI. -These templates have many similarities to the C++ dynamic_cast<> -operator, but they don't have some drawbacks (primarily stemming from -the fact that dynamic_cast<> only works on classes that -have a v-table). Because they are used so often, you must know what they -do and how they work. All of these templates are defined in the llvm/Support/Casting.h -file (note that you very rarely have to include this file directly).

- -
-
isa<>:
- -

The isa<> operator works exactly like the Java - "instanceof" operator. It returns true or false depending on whether - a reference or pointer points to an instance of the specified class. This can - be very useful for constraint checking of various sorts (example below).

-
- -
cast<>:
- -

The cast<> operator is a "checked cast" operation. It - converts a pointer or reference from a base class to a derived class, causing - an assertion failure if it is not really an instance of the right type. This - should be used in cases where you have some information that makes you believe - that something is of the right type. An example of the isa<> - and cast<> template is:

- -
-
-static bool isLoopInvariant(const Value *V, const Loop *L) {
-  if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V))
-    return true;
-
-  // Otherwise, it must be an instruction...
-  return !L->contains(cast<Instruction>(V)->getParent());
-}
-
-
- -

Note that you should not use an isa<> test followed - by a cast<>, for that use the dyn_cast<> - operator.

- -
- -
dyn_cast<>:
- -

The dyn_cast<> operator is a "checking cast" operation. - It checks to see if the operand is of the specified type, and if so, returns a - pointer to it (this operator does not work with references). If the operand is - not of the correct type, a null pointer is returned. Thus, this works very - much like the dynamic_cast<> operator in C++, and should be - used in the same circumstances. Typically, the dyn_cast<> - operator is used in an if statement or some other flow control - statement like this:

- -
-
-if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
-  // ...
-}
-
-
- -

This form of the if statement effectively combines together a call - to isa<> and a call to cast<> into one - statement, which is very convenient.

- -

Note that the dyn_cast<> operator, like C++'s - dynamic_cast<> or Java's instanceof operator, can be - abused. In particular, you should not use big chained if/then/else - blocks to check for lots of different variants of classes. If you find - yourself wanting to do this, it is much cleaner and more efficient to use the - InstVisitor class to dispatch over the instruction type directly.

- -
- -
cast_or_null<>:
- -

The cast_or_null<> operator works just like the - cast<> operator, except that it allows for a null pointer as an - argument (which it then propagates). This can sometimes be useful, allowing - you to combine several null checks into one.

- -
dyn_cast_or_null<>:
- -

The dyn_cast_or_null<> operator works just like the - dyn_cast<> operator, except that it allows for a null pointer - as an argument (which it then propagates). This can sometimes be useful, - allowing you to combine several null checks into one.

- -
- -

These five templates can be used with any classes, whether they have a -v-table or not. To add support for these templates, you simply need to add -classof static methods to the class you are interested casting -to. Describing this is currently outside the scope of this document, but there -are lots of examples in the LLVM source base.

- -
- - - -

- Passing strings (the StringRef -and Twine classes) -

- -
- -

Although LLVM generally does not do much string manipulation, we do have -several important APIs which take strings. Two important examples are the -Value class -- which has names for instructions, functions, etc. -- and the -StringMap class which is used extensively in LLVM and Clang.

- -

These are generic classes, and they need to be able to accept strings which -may have embedded null characters. Therefore, they cannot simply take -a const char *, and taking a const std::string& requires -clients to perform a heap allocation which is usually unnecessary. Instead, -many LLVM APIs use a StringRef or a const Twine& for -passing strings efficiently.

- - -

- The StringRef class -

- -
- -

The StringRef data type represents a reference to a constant string -(a character array and a length) and supports the common operations available -on std:string, but does not require heap allocation.

- -

It can be implicitly constructed using a C style null-terminated string, -an std::string, or explicitly with a character pointer and length. -For example, the StringRef find function is declared as:

- -
-  iterator find(StringRef Key);
-
- -

and clients can call it using any one of:

- -
-  Map.find("foo");                 // Lookup "foo"
-  Map.find(std::string("bar"));    // Lookup "bar"
-  Map.find(StringRef("\0baz", 4)); // Lookup "\0baz"
-
- -

Similarly, APIs which need to return a string may return a StringRef -instance, which can be used directly or converted to an std::string -using the str member function. See -"llvm/ADT/StringRef.h" -for more information.

- -

You should rarely use the StringRef class directly, because it contains -pointers to external memory it is not generally safe to store an instance of the -class (unless you know that the external storage will not be freed). StringRef is -small and pervasive enough in LLVM that it should always be passed by value.

- -
- - -

- The Twine class -

- -
- -

The Twine class is an efficient way for APIs to accept concatenated -strings. For example, a common LLVM paradigm is to name one instruction based on -the name of another instruction with a suffix, for example:

- -
-
-    New = CmpInst::Create(..., SO->getName() + ".cmp");
-
-
- -

The Twine class is effectively a -lightweight rope -which points to temporary (stack allocated) objects. Twines can be implicitly -constructed as the result of the plus operator applied to strings (i.e., a C -strings, an std::string, or a StringRef). The twine delays the -actual concatenation of strings until it is actually required, at which point -it can be efficiently rendered directly into a character array. This avoids -unnecessary heap allocation involved in constructing the temporary results of -string concatenation. See -"llvm/ADT/Twine.h" -for more information.

- -

As with a StringRef, Twine objects point to external memory -and should almost never be stored or mentioned directly. They are intended -solely for use when defining a function which should be able to efficiently -accept concatenated strings.

- -
- -
- - -

- The DEBUG() macro and -debug option -

- -
- -

Often when working on your pass you will put a bunch of debugging printouts -and other code into your pass. After you get it working, you want to remove -it, but you may need it again in the future (to work out new bugs that you run -across).

- -

Naturally, because of this, you don't want to delete the debug printouts, -but you don't want them to always be noisy. A standard compromise is to comment -them out, allowing you to enable them if you need them in the future.

- -

The "llvm/Support/Debug.h" -file provides a macro named DEBUG() that is a much nicer solution to -this problem. Basically, you can put arbitrary code into the argument of the -DEBUG macro, and it is only executed if 'opt' (or any other -tool) is run with the '-debug' command line argument:

- -
-
-DEBUG(errs() << "I am here!\n");
-
-
- -

Then you can run your pass like this:

- -
-
-$ opt < a.bc > /dev/null -mypass
-<no output>
-$ opt < a.bc > /dev/null -mypass -debug
-I am here!
-
-
- -

Using the DEBUG() macro instead of a home-brewed solution allows you -to not have to create "yet another" command line option for the debug output for -your pass. Note that DEBUG() macros are disabled for optimized builds, -so they do not cause a performance impact at all (for the same reason, they -should also not contain side-effects!).

- -

One additional nice thing about the DEBUG() macro is that you can -enable or disable it directly in gdb. Just use "set DebugFlag=0" or -"set DebugFlag=1" from the gdb if the program is running. If the -program hasn't been started yet, you can always just run it with --debug.

- - -

- Fine grained debug info with DEBUG_TYPE and - the -debug-only option -

- -
- -

Sometimes you may find yourself in a situation where enabling -debug -just turns on too much information (such as when working on the code -generator). If you want to enable debug information with more fine-grained -control, you define the DEBUG_TYPE macro and the -debug only -option as follows:

- -
-
-#undef  DEBUG_TYPE
-DEBUG(errs() << "No debug type\n");
-#define DEBUG_TYPE "foo"
-DEBUG(errs() << "'foo' debug type\n");
-#undef  DEBUG_TYPE
-#define DEBUG_TYPE "bar"
-DEBUG(errs() << "'bar' debug type\n"));
-#undef  DEBUG_TYPE
-#define DEBUG_TYPE ""
-DEBUG(errs() << "No debug type (2)\n");
-
-
- -

Then you can run your pass like this:

- -
-
-$ opt < a.bc > /dev/null -mypass
-<no output>
-$ opt < a.bc > /dev/null -mypass -debug
-No debug type
-'foo' debug type
-'bar' debug type
-No debug type (2)
-$ opt < a.bc > /dev/null -mypass -debug-only=foo
-'foo' debug type
-$ opt < a.bc > /dev/null -mypass -debug-only=bar
-'bar' debug type
-
-
- -

Of course, in practice, you should only set DEBUG_TYPE at the top of -a file, to specify the debug type for the entire module (if you do this before -you #include "llvm/Support/Debug.h", you don't have to insert the ugly -#undef's). Also, you should use names more meaningful than "foo" and -"bar", because there is no system in place to ensure that names do not -conflict. If two different modules use the same string, they will all be turned -on when the name is specified. This allows, for example, all debug information -for instruction scheduling to be enabled with -debug-type=InstrSched, -even if the source lives in multiple files.

- -

The DEBUG_WITH_TYPE macro is also available for situations where you -would like to set DEBUG_TYPE, but only for one specific DEBUG -statement. It takes an additional first parameter, which is the type to use. For -example, the preceding example could be written as:

- - -
-
-DEBUG_WITH_TYPE("", errs() << "No debug type\n");
-DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type\n");
-DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type\n"));
-DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n");
-
-
- -
- -
- - -

- The Statistic class & -stats - option -

- -
- -

The "llvm/ADT/Statistic.h" file -provides a class named Statistic that is used as a unified way to -keep track of what the LLVM compiler is doing and how effective various -optimizations are. It is useful to see what optimizations are contributing to -making a particular program run faster.

- -

Often you may run your pass on some big program, and you're interested to see -how many times it makes a certain transformation. Although you can do this with -hand inspection, or some ad-hoc method, this is a real pain and not very useful -for big programs. Using the Statistic class makes it very easy to -keep track of this information, and the calculated information is presented in a -uniform manner with the rest of the passes being executed.

- -

There are many examples of Statistic uses, but the basics of using -it are as follows:

- -
    -
  1. Define your statistic like this:

    - -
    -
    -#define DEBUG_TYPE "mypassname"   // This goes before any #includes.
    -STATISTIC(NumXForms, "The # of times I did stuff");
    -
    -
    - -

    The STATISTIC macro defines a static variable, whose name is - specified by the first argument. The pass name is taken from the DEBUG_TYPE - macro, and the description is taken from the second argument. The variable - defined ("NumXForms" in this case) acts like an unsigned integer.

  2. - -
  3. Whenever you make a transformation, bump the counter:

    - -
    -
    -++NumXForms;   // I did stuff!
    -
    -
    - -
  4. -
- -

That's all you have to do. To get 'opt' to print out the - statistics gathered, use the '-stats' option:

- -
-
-$ opt -stats -mypassname < program.bc > /dev/null
-... statistics output ...
-
-
- -

When running opt on a C file from the SPEC benchmark -suite, it gives a report that looks like this:

- -
-
-   7646 bitcodewriter   - Number of normal instructions
-    725 bitcodewriter   - Number of oversized instructions
- 129996 bitcodewriter   - Number of bitcode bytes written
-   2817 raise           - Number of insts DCEd or constprop'd
-   3213 raise           - Number of cast-of-self removed
-   5046 raise           - Number of expression trees converted
-     75 raise           - Number of other getelementptr's formed
-    138 raise           - Number of load/store peepholes
-     42 deadtypeelim    - Number of unused typenames removed from symtab
-    392 funcresolve     - Number of varargs functions resolved
-     27 globaldce       - Number of global variables removed
-      2 adce            - Number of basic blocks removed
-    134 cee             - Number of branches revectored
-     49 cee             - Number of setcc instruction eliminated
-    532 gcse            - Number of loads removed
-   2919 gcse            - Number of instructions removed
-     86 indvars         - Number of canonical indvars added
-     87 indvars         - Number of aux indvars removed
-     25 instcombine     - Number of dead inst eliminate
-    434 instcombine     - Number of insts combined
-    248 licm            - Number of load insts hoisted
-   1298 licm            - Number of insts hoisted to a loop pre-header
-      3 licm            - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
-     75 mem2reg         - Number of alloca's promoted
-   1444 cfgsimplify     - Number of blocks simplified
-
-
- -

Obviously, with so many optimizations, having a unified framework for this -stuff is very nice. Making your pass fit well into the framework makes it more -maintainable and useful.

- -
- - -

- Viewing graphs while debugging code -

- -
- -

Several of the important data structures in LLVM are graphs: for example -CFGs made out of LLVM BasicBlocks, CFGs made out of -LLVM MachineBasicBlocks, and -Instruction Selection -DAGs. In many cases, while debugging various parts of the compiler, it is -nice to instantly visualize these graphs.

- -

LLVM provides several callbacks that are available in a debug build to do -exactly that. If you call the Function::viewCFG() method, for example, -the current LLVM tool will pop up a window containing the CFG for the function -where each basic block is a node in the graph, and each node contains the -instructions in the block. Similarly, there also exists -Function::viewCFGOnly() (does not include the instructions), the -MachineFunction::viewCFG() and MachineFunction::viewCFGOnly(), -and the SelectionDAG::viewGraph() methods. Within GDB, for example, -you can usually use something like call DAG.viewGraph() to pop -up a window. Alternatively, you can sprinkle calls to these functions in your -code in places you want to debug.

- -

Getting this to work requires a small amount of configuration. On Unix -systems with X11, install the graphviz -toolkit, and make sure 'dot' and 'gv' are in your path. If you are running on -Mac OS/X, download and install the Mac OS/X Graphviz program, and add -/Applications/Graphviz.app/Contents/MacOS/ (or wherever you install -it) to your path. Once in your system and path are set up, rerun the LLVM -configure script and rebuild LLVM to enable this functionality.

- -

SelectionDAG has been extended to make it easier to locate -interesting nodes in large complex graphs. From gdb, if you -call DAG.setGraphColor(node, "color"), then the -next call DAG.viewGraph() would highlight the node in the -specified color (choices of colors can be found at colors.) More -complex node attributes can be provided with call -DAG.setGraphAttrs(node, "attributes") (choices can be -found at Graph -Attributes.) If you want to restart and clear all the current graph -attributes, then you can call DAG.clearGraphAttrs().

- -

Note that graph visualization features are compiled out of Release builds -to reduce file size. This means that you need a Debug+Asserts or -Release+Asserts build to use these features.

- -
- -
- - -

- Picking the Right Data Structure for a Task -

- - -
- -

LLVM has a plethora of data structures in the llvm/ADT/ directory, - and we commonly use STL data structures. This section describes the trade-offs - you should consider when you pick one.

- -

-The first step is a choose your own adventure: do you want a sequential -container, a set-like container, or a map-like container? The most important -thing when choosing a container is the algorithmic properties of how you plan to -access the container. Based on that, you should use:

- -
    -
  • a map-like container if you need efficient look-up - of an value based on another value. Map-like containers also support - efficient queries for containment (whether a key is in the map). Map-like - containers generally do not support efficient reverse mapping (values to - keys). If you need that, use two maps. Some map-like containers also - support efficient iteration through the keys in sorted order. Map-like - containers are the most expensive sort, only use them if you need one of - these capabilities.
  • - -
  • a set-like container if you need to put a bunch of - stuff into a container that automatically eliminates duplicates. Some - set-like containers support efficient iteration through the elements in - sorted order. Set-like containers are more expensive than sequential - containers. -
  • - -
  • a sequential container provides - the most efficient way to add elements and keeps track of the order they are - added to the collection. They permit duplicates and support efficient - iteration, but do not support efficient look-up based on a key. -
  • - -
  • a string container is a specialized sequential - container or reference structure that is used for character or byte - arrays.
  • - -
  • a bit container provides an efficient way to store and - perform set operations on sets of numeric id's, while automatically - eliminating duplicates. Bit containers require a maximum of 1 bit for each - identifier you want to store. -
  • -
- -

-Once the proper category of container is determined, you can fine tune the -memory use, constant factors, and cache behaviors of access by intelligently -picking a member of the category. Note that constant factors and cache behavior -can be a big deal. If you have a vector that usually only contains a few -elements (but could contain many), for example, it's much better to use -SmallVector than vector -. Doing so avoids (relatively) expensive malloc/free calls, which dwarf the -cost of adding the elements to the container.

- - -

- Sequential Containers (std::vector, std::list, etc) -

- -
-There are a variety of sequential containers available for you, based on your -needs. Pick the first in this section that will do what you want. - - -

- llvm/ADT/ArrayRef.h -

- -
-

The llvm::ArrayRef class is the preferred class to use in an interface that - accepts a sequential list of elements in memory and just reads from them. By - taking an ArrayRef, the API can be passed a fixed size array, an std::vector, - an llvm::SmallVector and anything else that is contiguous in memory. -

-
- - - - -

- Fixed Size Arrays -

- -
-

Fixed size arrays are very simple and very fast. They are good if you know -exactly how many elements you have, or you have a (low) upper bound on how many -you have.

-
- - -

- Heap Allocated Arrays -

- -
-

Heap allocated arrays (new[] + delete[]) are also simple. They are good if -the number of elements is variable, if you know how many elements you will need -before the array is allocated, and if the array is usually large (if not, -consider a SmallVector). The cost of a heap -allocated array is the cost of the new/delete (aka malloc/free). Also note that -if you are allocating an array of a type with a constructor, the constructor and -destructors will be run for every element in the array (re-sizable vectors only -construct those elements actually used).

-
- - -

- "llvm/ADT/TinyPtrVector.h" -

- - -
-

TinyPtrVector<Type> is a highly specialized collection class -that is optimized to avoid allocation in the case when a vector has zero or one -elements. It has two major restrictions: 1) it can only hold values of pointer -type, and 2) it cannot hold a null pointer.

- -

Since this container is highly specialized, it is rarely used.

- -
- - -

- "llvm/ADT/SmallVector.h" -

- -
-

SmallVector<Type, N> is a simple class that looks and smells -just like vector<Type>: -it supports efficient iteration, lays out elements in memory order (so you can -do pointer arithmetic between elements), supports efficient push_back/pop_back -operations, supports efficient random access to its elements, etc.

- -

The advantage of SmallVector is that it allocates space for -some number of elements (N) in the object itself. Because of this, if -the SmallVector is dynamically smaller than N, no malloc is performed. This can -be a big win in cases where the malloc/free call is far more expensive than the -code that fiddles around with the elements.

- -

This is good for vectors that are "usually small" (e.g. the number of -predecessors/successors of a block is usually less than 8). On the other hand, -this makes the size of the SmallVector itself large, so you don't want to -allocate lots of them (doing so will waste a lot of space). As such, -SmallVectors are most useful when on the stack.

- -

SmallVector also provides a nice portable and efficient replacement for -alloca.

- -
- - -

- <vector> -

- -
-

-std::vector is well loved and respected. It is useful when SmallVector isn't: -when the size of the vector is often large (thus the small optimization will -rarely be a benefit) or if you will be allocating many instances of the vector -itself (which would waste space for elements that aren't in the container). -vector is also useful when interfacing with code that expects vectors :). -

- -

One worthwhile note about std::vector: avoid code like this:

- -
-
-for ( ... ) {
-   std::vector<foo> V;
-   // make use of V.
-}
-
-
- -

Instead, write this as:

- -
-
-std::vector<foo> V;
-for ( ... ) {
-   // make use of V.
-   V.clear();
-}
-
-
- -

Doing so will save (at least) one heap allocation and free per iteration of -the loop.

- -
- - -

- <deque> -

- -
-

std::deque is, in some senses, a generalized version of std::vector. Like -std::vector, it provides constant time random access and other similar -properties, but it also provides efficient access to the front of the list. It -does not guarantee continuity of elements within memory.

- -

In exchange for this extra flexibility, std::deque has significantly higher -constant factor costs than std::vector. If possible, use std::vector or -something cheaper.

-
- - -

- <list> -

- -
-

std::list is an extremely inefficient class that is rarely useful. -It performs a heap allocation for every element inserted into it, thus having an -extremely high constant factor, particularly for small data types. std::list -also only supports bidirectional iteration, not random access iteration.

- -

In exchange for this high cost, std::list supports efficient access to both -ends of the list (like std::deque, but unlike std::vector or SmallVector). In -addition, the iterator invalidation characteristics of std::list are stronger -than that of a vector class: inserting or removing an element into the list does -not invalidate iterator or pointers to other elements in the list.

-
- - -

- llvm/ADT/ilist.h -

- -
-

ilist<T> implements an 'intrusive' doubly-linked list. It is -intrusive, because it requires the element to store and provide access to the -prev/next pointers for the list.

- -

ilist has the same drawbacks as std::list, and additionally -requires an ilist_traits implementation for the element type, but it -provides some novel characteristics. In particular, it can efficiently store -polymorphic objects, the traits class is informed when an element is inserted or -removed from the list, and ilists are guaranteed to support a -constant-time splice operation.

- -

These properties are exactly what we want for things like -Instructions and basic blocks, which is why these are implemented with -ilists.

- -Related classes of interest are explained in the following subsections: - -
- - -

- llvm/ADT/PackedVector.h -

- -
-

-Useful for storing a vector of values using only a few number of bits for each -value. Apart from the standard operations of a vector-like container, it can -also perform an 'or' set operation. -

- -

For example:

- -
-
-enum State {
-    None = 0x0,
-    FirstCondition = 0x1,
-    SecondCondition = 0x2,
-    Both = 0x3
-};
-
-State get() {
-    PackedVector<State, 2> Vec1;
-    Vec1.push_back(FirstCondition);
-
-    PackedVector<State, 2> Vec2;
-    Vec2.push_back(SecondCondition);
-
-    Vec1 |= Vec2;
-    return Vec1[0]; // returns 'Both'.
-}
-
-
- -
- - -

- ilist_traits -

- -
-

ilist_traits<T> is ilist<T>'s customization -mechanism. iplist<T> (and consequently ilist<T>) -publicly derive from this traits class.

-
- - -

- iplist -

- -
-

iplist<T> is ilist<T>'s base and as such -supports a slightly narrower interface. Notably, inserters from -T& are absent.

- -

ilist_traits<T> is a public base of this class and can be -used for a wide variety of customizations.

-
- - -

- llvm/ADT/ilist_node.h -

- -
-

ilist_node<T> implements a the forward and backward links -that are expected by the ilist<T> (and analogous containers) -in the default manner.

- -

ilist_node<T>s are meant to be embedded in the node type -T, usually T publicly derives from -ilist_node<T>.

-
- - -

- Sentinels -

- -
-

ilists have another specialty that must be considered. To be a good -citizen in the C++ ecosystem, it needs to support the standard container -operations, such as begin and end iterators, etc. Also, the -operator-- must work correctly on the end iterator in the -case of non-empty ilists.

- -

The only sensible solution to this problem is to allocate a so-called -sentinel along with the intrusive list, which serves as the end -iterator, providing the back-link to the last element. However conforming to the -C++ convention it is illegal to operator++ beyond the sentinel and it -also must not be dereferenced.

- -

These constraints allow for some implementation freedom to the ilist -how to allocate and store the sentinel. The corresponding policy is dictated -by ilist_traits<T>. By default a T gets heap-allocated -whenever the need for a sentinel arises.

- -

While the default policy is sufficient in most cases, it may break down when -T does not provide a default constructor. Also, in the case of many -instances of ilists, the memory overhead of the associated sentinels -is wasted. To alleviate the situation with numerous and voluminous -T-sentinels, sometimes a trick is employed, leading to ghostly -sentinels.

- -

Ghostly sentinels are obtained by specially-crafted ilist_traits<T> -which superpose the sentinel with the ilist instance in memory. Pointer -arithmetic is used to obtain the sentinel, which is relative to the -ilist's this pointer. The ilist is augmented by an -extra pointer, which serves as the back-link of the sentinel. This is the only -field in the ghostly sentinel which can be legally accessed.

-
- - -

- Other Sequential Container options -

- -
-

Other STL containers are available, such as std::string.

- -

There are also various STL adapter classes such as std::queue, -std::priority_queue, std::stack, etc. These provide simplified access to an -underlying container but don't affect the cost of the container itself.

- -
-
- - -

- String-like containers -

- -
- -

-There are a variety of ways to pass around and use strings in C and C++, and -LLVM adds a few new options to choose from. Pick the first option on this list -that will do what you need, they are ordered according to their relative cost. -

-

-Note that is is generally preferred to not pass strings around as -"const char*"'s. These have a number of problems, including the fact -that they cannot represent embedded nul ("\0") characters, and do not have a -length available efficiently. The general replacement for 'const -char*' is StringRef. -

- -

For more information on choosing string containers for APIs, please see -Passing strings.

- - - -

- llvm/ADT/StringRef.h -

- -
-

-The StringRef class is a simple value class that contains a pointer to a -character and a length, and is quite related to the ArrayRef class (but specialized for arrays of -characters). Because StringRef carries a length with it, it safely handles -strings with embedded nul characters in it, getting the length does not require -a strlen call, and it even has very convenient APIs for slicing and dicing the -character range that it represents. -

- -

-StringRef is ideal for passing simple strings around that are known to be live, -either because they are C string literals, std::string, a C array, or a -SmallVector. Each of these cases has an efficient implicit conversion to -StringRef, which doesn't result in a dynamic strlen being executed. -

- -

StringRef has a few major limitations which make more powerful string -containers useful:

- -
    -
  1. You cannot directly convert a StringRef to a 'const char*' because there is -no way to add a trailing nul (unlike the .c_str() method on various stronger -classes).
  2. - - -
  3. StringRef doesn't own or keep alive the underlying string bytes. -As such it can easily lead to dangling pointers, and is not suitable for -embedding in datastructures in most cases (instead, use an std::string or -something like that).
  4. - -
  5. For the same reason, StringRef cannot be used as the return value of a -method if the method "computes" the result string. Instead, use -std::string.
  6. - -
  7. StringRef's do not allow you to mutate the pointed-to string bytes and it -doesn't allow you to insert or remove bytes from the range. For editing -operations like this, it interoperates with the Twine class.
  8. -
- -

Because of its strengths and limitations, it is very common for a function to -take a StringRef and for a method on an object to return a StringRef that -points into some string that it owns.

- -
- - -

- llvm/ADT/Twine.h -

- -
-

- The Twine class is used as an intermediary datatype for APIs that want to take - a string that can be constructed inline with a series of concatenations. - Twine works by forming recursive instances of the Twine datatype (a simple - value object) on the stack as temporary objects, linking them together into a - tree which is then linearized when the Twine is consumed. Twine is only safe - to use as the argument to a function, and should always be a const reference, - e.g.: -

- -
-    void foo(const Twine &T);
-    ...
-    StringRef X = ...
-    unsigned i = ...
-    foo(X + "." + Twine(i));
-  
- -

This example forms a string like "blarg.42" by concatenating the values - together, and does not form intermediate strings containing "blarg" or - "blarg.". -

- -

Because Twine is constructed with temporary objects on the stack, and - because these instances are destroyed at the end of the current statement, - it is an inherently dangerous API. For example, this simple variant contains - undefined behavior and will probably crash:

- -
-    void foo(const Twine &T);
-    ...
-    StringRef X = ...
-    unsigned i = ...
-    const Twine &Tmp = X + "." + Twine(i);
-    foo(Tmp);
-  
- -

... because the temporaries are destroyed before the call. That said, - Twine's are much more efficient than intermediate std::string temporaries, and - they work really well with StringRef. Just be aware of their limitations.

- -
- - - -

- llvm/ADT/SmallString.h -

- -
- -

SmallString is a subclass of SmallVector that -adds some convenience APIs like += that takes StringRef's. SmallString avoids -allocating memory in the case when the preallocated space is enough to hold its -data, and it calls back to general heap allocation when required. Since it owns -its data, it is very safe to use and supports full mutation of the string.

- -

Like SmallVector's, the big downside to SmallString is their sizeof. While -they are optimized for small strings, they themselves are not particularly -small. This means that they work great for temporary scratch buffers on the -stack, but should not generally be put into the heap: it is very rare to -see a SmallString as the member of a frequently-allocated heap data structure -or returned by-value. -

- -
- - -

- std::string -

- -
- -

The standard C++ std::string class is a very general class that (like - SmallString) owns its underlying data. sizeof(std::string) is very reasonable - so it can be embedded into heap data structures and returned by-value. - On the other hand, std::string is highly inefficient for inline editing (e.g. - concatenating a bunch of stuff together) and because it is provided by the - standard library, its performance characteristics depend a lot of the host - standard library (e.g. libc++ and MSVC provide a highly optimized string - class, GCC contains a really slow implementation). -

- -

The major disadvantage of std::string is that almost every operation that - makes them larger can allocate memory, which is slow. As such, it is better - to use SmallVector or Twine as a scratch buffer, but then use std::string to - persist the result.

- - -
- - -
- - - -

- Set-Like Containers (std::set, SmallSet, SetVector, etc) -

- -
- -

Set-like containers are useful when you need to canonicalize multiple values -into a single representation. There are several different choices for how to do -this, providing various trade-offs.

- - -

- A sorted 'vector' -

- -
- -

If you intend to insert a lot of elements, then do a lot of queries, a -great approach is to use a vector (or other sequential container) with -std::sort+std::unique to remove duplicates. This approach works really well if -your usage pattern has these two distinct phases (insert then query), and can be -coupled with a good choice of sequential container. -

- -

-This combination provides the several nice properties: the result data is -contiguous in memory (good for cache locality), has few allocations, is easy to -address (iterators in the final vector are just indices or pointers), and can be -efficiently queried with a standard binary or radix search.

- -
- - -

- "llvm/ADT/SmallSet.h" -

- -
- -

If you have a set-like data structure that is usually small and whose elements -are reasonably small, a SmallSet<Type, N> is a good choice. This set -has space for N elements in place (thus, if the set is dynamically smaller than -N, no malloc traffic is required) and accesses them with a simple linear search. -When the set grows beyond 'N' elements, it allocates a more expensive representation that -guarantees efficient access (for most types, it falls back to std::set, but for -pointers it uses something far better, SmallPtrSet).

- -

The magic of this class is that it handles small sets extremely efficiently, -but gracefully handles extremely large sets without loss of efficiency. The -drawback is that the interface is quite small: it supports insertion, queries -and erasing, but does not support iteration.

- -
- - -

- "llvm/ADT/SmallPtrSet.h" -

- -
- -

SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is -transparently implemented with a SmallPtrSet), but also supports iterators. If -more than 'N' insertions are performed, a single quadratically -probed hash table is allocated and grows as needed, providing extremely -efficient access (constant time insertion/deleting/queries with low constant -factors) and is very stingy with malloc traffic.

- -

Note that, unlike std::set, the iterators of SmallPtrSet are invalidated -whenever an insertion occurs. Also, the values visited by the iterators are not -visited in sorted order.

- -
- - -

- "llvm/ADT/DenseSet.h" -

- -
- -

-DenseSet is a simple quadratically probed hash table. It excels at supporting -small values: it uses a single allocation to hold all of the pairs that -are currently inserted in the set. DenseSet is a great way to unique small -values that are not simple pointers (use SmallPtrSet for pointers). Note that DenseSet has -the same requirements for the value type that DenseMap has. -

- -
- - -

- "llvm/ADT/SparseSet.h" -

- -
- -

SparseSet holds a small number of objects identified by unsigned keys of -moderate size. It uses a lot of memory, but provides operations that are -almost as fast as a vector. Typical keys are physical registers, virtual -registers, or numbered basic blocks.

- -

SparseSet is useful for algorithms that need very fast clear/find/insert/erase -and fast iteration over small sets. It is not intended for building composite -data structures.

- -
- - -

- "llvm/ADT/FoldingSet.h" -

- -
- -

-FoldingSet is an aggregate class that is really good at uniquing -expensive-to-create or polymorphic objects. It is a combination of a chained -hash table with intrusive links (uniqued objects are required to inherit from -FoldingSetNode) that uses SmallVector as part of -its ID process.

- -

Consider a case where you want to implement a "getOrCreateFoo" method for -a complex object (for example, a node in the code generator). The client has a -description of *what* it wants to generate (it knows the opcode and all the -operands), but we don't want to 'new' a node, then try inserting it into a set -only to find out it already exists, at which point we would have to delete it -and return the node that already exists. -

- -

To support this style of client, FoldingSet perform a query with a -FoldingSetNodeID (which wraps SmallVector) that can be used to describe the -element that we want to query for. The query either returns the element -matching the ID or it returns an opaque ID that indicates where insertion should -take place. Construction of the ID usually does not require heap traffic.

- -

Because FoldingSet uses intrusive links, it can support polymorphic objects -in the set (for example, you can have SDNode instances mixed with LoadSDNodes). -Because the elements are individually allocated, pointers to the elements are -stable: inserting or removing elements does not invalidate any pointers to other -elements. -

- -
- - -

- <set> -

- -
- -

std::set is a reasonable all-around set class, which is decent at -many things but great at nothing. std::set allocates memory for each element -inserted (thus it is very malloc intensive) and typically stores three pointers -per element in the set (thus adding a large amount of per-element space -overhead). It offers guaranteed log(n) performance, which is not particularly -fast from a complexity standpoint (particularly if the elements of the set are -expensive to compare, like strings), and has extremely high constant factors for -lookup, insertion and removal.

- -

The advantages of std::set are that its iterators are stable (deleting or -inserting an element from the set does not affect iterators or pointers to other -elements) and that iteration over the set is guaranteed to be in sorted order. -If the elements in the set are large, then the relative overhead of the pointers -and malloc traffic is not a big deal, but if the elements of the set are small, -std::set is almost never a good choice.

- -
- - -

- "llvm/ADT/SetVector.h" -

- -
-

LLVM's SetVector<Type> is an adapter class that combines your choice of -a set-like container along with a Sequential -Container. The important property -that this provides is efficient insertion with uniquing (duplicate elements are -ignored) with iteration support. It implements this by inserting elements into -both a set-like container and the sequential container, using the set-like -container for uniquing and the sequential container for iteration. -

- -

The difference between SetVector and other sets is that the order of -iteration is guaranteed to match the order of insertion into the SetVector. -This property is really important for things like sets of pointers. Because -pointer values are non-deterministic (e.g. vary across runs of the program on -different machines), iterating over the pointers in the set will -not be in a well-defined order.

- -

-The drawback of SetVector is that it requires twice as much space as a normal -set and has the sum of constant factors from the set-like container and the -sequential container that it uses. Use it *only* if you need to iterate over -the elements in a deterministic order. SetVector is also expensive to delete -elements out of (linear time), unless you use it's "pop_back" method, which is -faster. -

- -

SetVector is an adapter class that defaults to - using std::vector and a size 16 SmallSet for the underlying - containers, so it is quite expensive. However, - "llvm/ADT/SetVector.h" also provides a SmallSetVector - class, which defaults to using a SmallVector and SmallSet - of a specified size. If you use this, and if your sets are dynamically - smaller than N, you will save a lot of heap traffic.

- -
- - -

- "llvm/ADT/UniqueVector.h" -

- -
- -

-UniqueVector is similar to SetVector, but it -retains a unique ID for each element inserted into the set. It internally -contains a map and a vector, and it assigns a unique ID for each value inserted -into the set.

- -

UniqueVector is very expensive: its cost is the sum of the cost of -maintaining both the map and vector, it has high complexity, high constant -factors, and produces a lot of malloc traffic. It should be avoided.

- -
- - -

- "llvm/ADT/ImmutableSet.h" -

- -
- -

-ImmutableSet is an immutable (functional) set implementation based on an AVL -tree. -Adding or removing elements is done through a Factory object and results in the -creation of a new ImmutableSet object. -If an ImmutableSet already exists with the given contents, then the existing one -is returned; equality is compared with a FoldingSetNodeID. -The time and space complexity of add or remove operations is logarithmic in the -size of the original set. - -

-There is no method for returning an element of the set, you can only check for -membership. - -

- - - -

- Other Set-Like Container Options -

- -
- -

-The STL provides several other options, such as std::multiset and the various -"hash_set" like containers (whether from C++ TR1 or from the SGI library). We -never use hash_set and unordered_set because they are generally very expensive -(each insertion requires a malloc) and very non-portable. -

- -

std::multiset is useful if you're not interested in elimination of -duplicates, but has all the drawbacks of std::set. A sorted vector (where you -don't delete duplicate entries) or some other approach is almost always -better.

- -
- -
- - -

- Map-Like Containers (std::map, DenseMap, etc) -

- -
-Map-like containers are useful when you want to associate data to a key. As -usual, there are a lot of different ways to do this. :) - - -

- A sorted 'vector' -

- -
- -

-If your usage pattern follows a strict insert-then-query approach, you can -trivially use the same approach as sorted vectors -for set-like containers. The only difference is that your query function -(which uses std::lower_bound to get efficient log(n) lookup) should only compare -the key, not both the key and value. This yields the same advantages as sorted -vectors for sets. -

-
- - -

- "llvm/ADT/StringMap.h" -

- -
- -

-Strings are commonly used as keys in maps, and they are difficult to support -efficiently: they are variable length, inefficient to hash and compare when -long, expensive to copy, etc. StringMap is a specialized container designed to -cope with these issues. It supports mapping an arbitrary range of bytes to an -arbitrary other object.

- -

The StringMap implementation uses a quadratically-probed hash table, where -the buckets store a pointer to the heap allocated entries (and some other -stuff). The entries in the map must be heap allocated because the strings are -variable length. The string data (key) and the element object (value) are -stored in the same allocation with the string data immediately after the element -object. This container guarantees the "(char*)(&Value+1)" points -to the key string for a value.

- -

The StringMap is very fast for several reasons: quadratic probing is very -cache efficient for lookups, the hash value of strings in buckets is not -recomputed when looking up an element, StringMap rarely has to touch the -memory for unrelated objects when looking up a value (even when hash collisions -happen), hash table growth does not recompute the hash values for strings -already in the table, and each pair in the map is store in a single allocation -(the string data is stored in the same allocation as the Value of a pair).

- -

StringMap also provides query methods that take byte ranges, so it only ever -copies a string if a value is inserted into the table.

- -

StringMap iteratation order, however, is not guaranteed to be deterministic, -so any uses which require that should instead use a std::map.

-
- - -

- "llvm/ADT/IndexedMap.h" -

- -
-

-IndexedMap is a specialized container for mapping small dense integers (or -values that can be mapped to small dense integers) to some other type. It is -internally implemented as a vector with a mapping function that maps the keys to -the dense integer range. -

- -

-This is useful for cases like virtual registers in the LLVM code generator: they -have a dense mapping that is offset by a compile-time constant (the first -virtual register ID).

- -
- - -

- "llvm/ADT/DenseMap.h" -

- -
- -

-DenseMap is a simple quadratically probed hash table. It excels at supporting -small keys and values: it uses a single allocation to hold all of the pairs that -are currently inserted in the map. DenseMap is a great way to map pointers to -pointers, or map other small types to each other. -

- -

-There are several aspects of DenseMap that you should be aware of, however. The -iterators in a DenseMap are invalidated whenever an insertion occurs, unlike -map. Also, because DenseMap allocates space for a large number of key/value -pairs (it starts with 64 by default), it will waste a lot of space if your keys -or values are large. Finally, you must implement a partial specialization of -DenseMapInfo for the key that you want, if it isn't already supported. This -is required to tell DenseMap about two special marker values (which can never be -inserted into the map) that it needs internally.

- -

-DenseMap's find_as() method supports lookup operations using an alternate key -type. This is useful in cases where the normal key type is expensive to -construct, but cheap to compare against. The DenseMapInfo is responsible for -defining the appropriate comparison and hashing methods for each alternate -key type used. -

- -
- - -

- "llvm/ADT/ValueMap.h" -

- -
- -

-ValueMap is a wrapper around a DenseMap mapping -Value*s (or subclasses) to another type. When a Value is deleted or RAUW'ed, -ValueMap will update itself so the new version of the key is mapped to the same -value, just as if the key were a WeakVH. You can configure exactly how this -happens, and what else happens on these two events, by passing -a Config parameter to the ValueMap template.

- -
- - -

- "llvm/ADT/IntervalMap.h" -

- -
- -

IntervalMap is a compact map for small keys and values. It maps key -intervals instead of single keys, and it will automatically coalesce adjacent -intervals. When then map only contains a few intervals, they are stored in the -map object itself to avoid allocations.

- -

The IntervalMap iterators are quite big, so they should not be passed around -as STL iterators. The heavyweight iterators allow a smaller data structure.

- -
- - -

- <map> -

- -
- -

-std::map has similar characteristics to std::set: it uses -a single allocation per pair inserted into the map, it offers log(n) lookup with -an extremely large constant factor, imposes a space penalty of 3 pointers per -pair in the map, etc.

- -

std::map is most useful when your keys or values are very large, if you need -to iterate over the collection in sorted order, or if you need stable iterators -into the map (i.e. they don't get invalidated if an insertion or deletion of -another element takes place).

- -
- - -

- "llvm/ADT/IntEqClasses.h" -

- -
- -

IntEqClasses provides a compact representation of equivalence classes of -small integers. Initially, each integer in the range 0..n-1 has its own -equivalence class. Classes can be joined by passing two class representatives to -the join(a, b) method. Two integers are in the same class when findLeader() -returns the same representative.

- -

Once all equivalence classes are formed, the map can be compressed so each -integer 0..n-1 maps to an equivalence class number in the range 0..m-1, where m -is the total number of equivalence classes. The map must be uncompressed before -it can be edited again.

- -
- - -

- "llvm/ADT/ImmutableMap.h" -

- -
- -

-ImmutableMap is an immutable (functional) map implementation based on an AVL -tree. -Adding or removing elements is done through a Factory object and results in the -creation of a new ImmutableMap object. -If an ImmutableMap already exists with the given key set, then the existing one -is returned; equality is compared with a FoldingSetNodeID. -The time and space complexity of add or remove operations is logarithmic in the -size of the original map. - -

- - -

- Other Map-Like Container Options -

- -
- -

-The STL provides several other options, such as std::multimap and the various -"hash_map" like containers (whether from C++ TR1 or from the SGI library). We -never use hash_set and unordered_set because they are generally very expensive -(each insertion requires a malloc) and very non-portable.

- -

std::multimap is useful if you want to map a key to multiple values, but has -all the drawbacks of std::map. A sorted vector or some other approach is almost -always better.

- -
- -
- - -

- Bit storage containers (BitVector, SparseBitVector) -

- -
-

Unlike the other containers, there are only two bit storage containers, and -choosing when to use each is relatively straightforward.

- -

One additional option is -std::vector<bool>: we discourage its use for two reasons 1) the -implementation in many common compilers (e.g. commonly available versions of -GCC) is extremely inefficient and 2) the C++ standards committee is likely to -deprecate this container and/or change it significantly somehow. In any case, -please don't use it.

- - -

- BitVector -

- -
-

The BitVector container provides a dynamic size set of bits for manipulation. -It supports individual bit setting/testing, as well as set operations. The set -operations take time O(size of bitvector), but operations are performed one word -at a time, instead of one bit at a time. This makes the BitVector very fast for -set operations compared to other containers. Use the BitVector when you expect -the number of set bits to be high (IE a dense set). -

-
- - -

- SmallBitVector -

- -
-

The SmallBitVector container provides the same interface as BitVector, but -it is optimized for the case where only a small number of bits, less than -25 or so, are needed. It also transparently supports larger bit counts, but -slightly less efficiently than a plain BitVector, so SmallBitVector should -only be used when larger counts are rare. -

- -

-At this time, SmallBitVector does not support set operations (and, or, xor), -and its operator[] does not provide an assignable lvalue. -

-
- - -

- SparseBitVector -

- -
-

The SparseBitVector container is much like BitVector, with one major -difference: Only the bits that are set, are stored. This makes the -SparseBitVector much more space efficient than BitVector when the set is sparse, -as well as making set operations O(number of set bits) instead of O(size of -universe). The downside to the SparseBitVector is that setting and testing of random bits is O(N), and on large SparseBitVectors, this can be slower than BitVector. In our implementation, setting or testing bits in sorted order -(either forwards or reverse) is O(1) worst case. Testing and setting bits within 128 bits (depends on size) of the current bit is also O(1). As a general statement, testing/setting bits in a SparseBitVector is O(distance away from last set bit). -

-
- -
- -
- - -

- Helpful Hints for Common Operations -

- - -
- -

This section describes how to perform some very simple transformations of -LLVM code. This is meant to give examples of common idioms used, showing the -practical side of LLVM transformations.

Because this is a "how-to" section, -you should also read about the main classes that you will be working with. The -Core LLVM Class Hierarchy Reference contains details -and descriptions of the main classes that you should know about.

- - - -

- Basic Inspection and Traversal Routines -

- -
- -

The LLVM compiler infrastructure have many different data structures that may -be traversed. Following the example of the C++ standard template library, the -techniques used to traverse these various data structures are all basically the -same. For a enumerable sequence of values, the XXXbegin() function (or -method) returns an iterator to the start of the sequence, the XXXend() -function returns an iterator pointing to one past the last valid element of the -sequence, and there is some XXXiterator data type that is common -between the two operations.

- -

Because the pattern for iteration is common across many different aspects of -the program representation, the standard template library algorithms may be used -on them, and it is easier to remember how to iterate. First we show a few common -examples of the data structures that need to be traversed. Other data -structures are traversed in very similar ways.

- - -

- Iterating over the BasicBlocks in a Function -

- -
- -

It's quite common to have a Function instance that you'd like to -transform in some way; in particular, you'd like to manipulate its -BasicBlocks. To facilitate this, you'll need to iterate over all of -the BasicBlocks that constitute the Function. The following is -an example that prints the name of a BasicBlock and the number of -Instructions it contains:

- -
-
-// func is a pointer to a Function instance
-for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
-  // Print out the name of the basic block if it has one, and then the
-  // number of instructions that it contains
-  errs() << "Basic block (name=" << i->getName() << ") has "
-             << i->size() << " instructions.\n";
-
-
- -

Note that i can be used as if it were a pointer for the purposes of -invoking member functions of the Instruction class. This is -because the indirection operator is overloaded for the iterator -classes. In the above code, the expression i->size() is -exactly equivalent to (*i).size() just like you'd expect.

- -
- - -

- Iterating over the Instructions in a BasicBlock -

- -
- -

Just like when dealing with BasicBlocks in Functions, it's -easy to iterate over the individual instructions that make up -BasicBlocks. Here's a code snippet that prints out each instruction in -a BasicBlock:

- -
-
-// blk is a pointer to a BasicBlock instance
-for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
-   // The next statement works since operator<<(ostream&,...)
-   // is overloaded for Instruction&
-   errs() << *i << "\n";
-
-
- -

However, this isn't really the best way to print out the contents of a -BasicBlock! Since the ostream operators are overloaded for virtually -anything you'll care about, you could have just invoked the print routine on the -basic block itself: errs() << *blk << "\n";.

- -
- - -

- Iterating over the Instructions in a Function -

- -
- -

If you're finding that you commonly iterate over a Function's -BasicBlocks and then that BasicBlock's Instructions, -InstIterator should be used instead. You'll need to include llvm/Support/InstIterator.h, -and then instantiate InstIterators explicitly in your code. Here's a -small example that shows how to dump all instructions in a function to the standard error stream:

- -

-
-#include "llvm/Support/InstIterator.h"
-
-// F is a pointer to a Function instance
-for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
-  errs() << *I << "\n";
-
-
- -

Easy, isn't it? You can also use InstIterators to fill a -work list with its initial contents. For example, if you wanted to -initialize a work list to contain all instructions in a Function -F, all you would need to do is something like:

- -
-
-std::set<Instruction*> worklist;
-// or better yet, SmallPtrSet<Instruction*, 64> worklist;
-
-for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
-   worklist.insert(&*I);
-
-
- -

The STL set worklist would now contain all instructions in the -Function pointed to by F.

- -
- - -

- Turning an iterator into a class pointer (and - vice-versa) -

- -
- -

Sometimes, it'll be useful to grab a reference (or pointer) to a class -instance when all you've got at hand is an iterator. Well, extracting -a reference or a pointer from an iterator is very straight-forward. -Assuming that i is a BasicBlock::iterator and j -is a BasicBlock::const_iterator:

- -
-
-Instruction& inst = *i;   // Grab reference to instruction reference
-Instruction* pinst = &*i; // Grab pointer to instruction reference
-const Instruction& inst = *j;
-
-
- -

However, the iterators you'll be working with in the LLVM framework are -special: they will automatically convert to a ptr-to-instance type whenever they -need to. Instead of dereferencing the iterator and then taking the address of -the result, you can simply assign the iterator to the proper pointer type and -you get the dereference and address-of operation as a result of the assignment -(behind the scenes, this is a result of overloading casting mechanisms). Thus -the last line of the last example,

- -
-
-Instruction *pinst = &*i;
-
-
- -

is semantically equivalent to

- -
-
-Instruction *pinst = i;
-
-
- -

It's also possible to turn a class pointer into the corresponding iterator, -and this is a constant time operation (very efficient). The following code -snippet illustrates use of the conversion constructors provided by LLVM -iterators. By using these, you can explicitly grab the iterator of something -without actually obtaining it via iteration over some structure:

- -
-
-void printNextInstruction(Instruction* inst) {
-  BasicBlock::iterator it(inst);
-  ++it; // After this line, it refers to the instruction after *inst
-  if (it != inst->getParent()->end()) errs() << *it << "\n";
-}
-
-
- -

Unfortunately, these implicit conversions come at a cost; they prevent -these iterators from conforming to standard iterator conventions, and thus -from being usable with standard algorithms and containers. For example, they -prevent the following code, where B is a BasicBlock, -from compiling:

- -
-
-  llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
-
-
- -

Because of this, these implicit conversions may be removed some day, -and operator* changed to return a pointer instead of a reference.

- -
- - -

- Finding call sites: a slightly more complex - example -

- -
- -

Say that you're writing a FunctionPass and would like to count all the -locations in the entire module (that is, across every Function) where a -certain function (i.e., some Function*) is already in scope. As you'll -learn later, you may want to use an InstVisitor to accomplish this in a -much more straight-forward manner, but this example will allow us to explore how -you'd do it if you didn't have InstVisitor around. In pseudo-code, this -is what we want to do:

- -
-
-initialize callCounter to zero
-for each Function f in the Module
-  for each BasicBlock b in f
-    for each Instruction i in b
-      if (i is a CallInst and calls the given function)
-        increment callCounter
-
-
- -

And the actual code is (remember, because we're writing a -FunctionPass, our FunctionPass-derived class simply has to -override the runOnFunction method):

- -
-
-Function* targetFunc = ...;
-
-class OurFunctionPass : public FunctionPass {
-  public:
-    OurFunctionPass(): callCounter(0) { }
-
-    virtual runOnFunction(Function& F) {
-      for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
-        for (BasicBlock::iterator i = b->begin(), ie = b->end(); i != ie; ++i) {
-          if (CallInst* callInst = dyn_cast<CallInst>(&*i)) {
-            // We know we've encountered a call instruction, so we
-            // need to determine if it's a call to the
-            // function pointed to by m_func or not.
-            if (callInst->getCalledFunction() == targetFunc)
-              ++callCounter;
-          }
-        }
-      }
-    }
-
-  private:
-    unsigned callCounter;
-};
-
-
- -
- - -

- Treating calls and invokes the same way -

- -
- -

You may have noticed that the previous example was a bit oversimplified in -that it did not deal with call sites generated by 'invoke' instructions. In -this, and in other situations, you may find that you want to treat -CallInsts and InvokeInsts the same way, even though their -most-specific common base class is Instruction, which includes lots of -less closely-related things. For these cases, LLVM provides a handy wrapper -class called CallSite. -It is essentially a wrapper around an Instruction pointer, with some -methods that provide functionality common to CallInsts and -InvokeInsts.

- -

This class has "value semantics": it should be passed by value, not by -reference and it should not be dynamically allocated or deallocated using -operator new or operator delete. It is efficiently copyable, -assignable and constructable, with costs equivalents to that of a bare pointer. -If you look at its definition, it has only a single pointer member.

- -
- - -

- Iterating over def-use & use-def chains -

- -
- -

Frequently, we might have an instance of the Value Class and we want to -determine which Users use the Value. The list of all -Users of a particular Value is called a def-use chain. -For example, let's say we have a Function* named F to a -particular function foo. Finding all of the instructions that -use foo is as simple as iterating over the def-use chain -of F:

- -
-
-Function *F = ...;
-
-for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
-  if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
-    errs() << "F is used in instruction:\n";
-    errs() << *Inst << "\n";
-  }
-
-
- -

Note that dereferencing a Value::use_iterator is not a very cheap -operation. Instead of performing *i above several times, consider -doing it only once in the loop body and reusing its result.

- -

Alternatively, it's common to have an instance of the User Class and need to know what -Values are used by it. The list of all Values used by a -User is known as a use-def chain. Instances of class -Instruction are common Users, so we might want to iterate over -all of the values that a particular instruction uses (that is, the operands of -the particular Instruction):

- -
-
-Instruction *pi = ...;
-
-for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
-  Value *v = *i;
-  // ...
-}
-
-
- -

Declaring objects as const is an important tool of enforcing -mutation free algorithms (such as analyses, etc.). For this purpose above -iterators come in constant flavors as Value::const_use_iterator -and Value::const_op_iterator. They automatically arise when -calling use/op_begin() on const Value*s or -const User*s respectively. Upon dereferencing, they return -const Use*s. Otherwise the above patterns remain unchanged.

- -
- - -

- Iterating over predecessors & -successors of blocks -

- -
- -

Iterating over the predecessors and successors of a block is quite easy -with the routines defined in "llvm/Support/CFG.h". Just use code like -this to iterate over all predecessors of BB:

- -
-
-#include "llvm/Support/CFG.h"
-BasicBlock *BB = ...;
-
-for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
-  BasicBlock *Pred = *PI;
-  // ...
-}
-
-
- -

Similarly, to iterate over successors use -succ_iterator/succ_begin/succ_end.

- -
- -
- - -

- Making simple changes -

- -
- -

There are some primitive transformation operations present in the LLVM -infrastructure that are worth knowing about. When performing -transformations, it's fairly common to manipulate the contents of basic -blocks. This section describes some of the common methods for doing so -and gives example code.

- - -

- Creating and inserting new - Instructions -

- -
- -

Instantiating Instructions

- -

Creation of Instructions is straight-forward: simply call the -constructor for the kind of instruction to instantiate and provide the necessary -parameters. For example, an AllocaInst only requires a -(const-ptr-to) Type. Thus:

- -
-
-AllocaInst* ai = new AllocaInst(Type::Int32Ty);
-
-
- -

will create an AllocaInst instance that represents the allocation of -one integer in the current stack frame, at run time. Each Instruction -subclass is likely to have varying default parameters which change the semantics -of the instruction, so refer to the doxygen documentation for the subclass of -Instruction that you're interested in instantiating.

- -

Naming values

- -

It is very useful to name the values of instructions when you're able to, as -this facilitates the debugging of your transformations. If you end up looking -at generated LLVM machine code, you definitely want to have logical names -associated with the results of instructions! By supplying a value for the -Name (default) parameter of the Instruction constructor, you -associate a logical name with the result of the instruction's execution at -run time. For example, say that I'm writing a transformation that dynamically -allocates space for an integer on the stack, and that integer is going to be -used as some kind of index by some other code. To accomplish this, I place an -AllocaInst at the first point in the first BasicBlock of some -Function, and I'm intending to use it within the same -Function. I might do:

- -
-
-AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
-
-
- -

where indexLoc is now the logical name of the instruction's -execution value, which is a pointer to an integer on the run time stack.

- -

Inserting instructions

- -

There are essentially two ways to insert an Instruction -into an existing sequence of instructions that form a BasicBlock:

- -
    -
  • Insertion into an explicit instruction list - -

    Given a BasicBlock* pb, an Instruction* pi within that - BasicBlock, and a newly-created instruction we wish to insert - before *pi, we do the following:

    - -
    -
    -BasicBlock *pb = ...;
    -Instruction *pi = ...;
    -Instruction *newInst = new Instruction(...);
    -
    -pb->getInstList().insert(pi, newInst); // Inserts newInst before pi in pb
    -
    -
    - -

    Appending to the end of a BasicBlock is so common that - the Instruction class and Instruction-derived - classes provide constructors which take a pointer to a - BasicBlock to be appended to. For example code that - looked like:

    - -
    -
    -BasicBlock *pb = ...;
    -Instruction *newInst = new Instruction(...);
    -
    -pb->getInstList().push_back(newInst); // Appends newInst to pb
    -
    -
    - -

    becomes:

    - -
    -
    -BasicBlock *pb = ...;
    -Instruction *newInst = new Instruction(..., pb);
    -
    -
    - -

    which is much cleaner, especially if you are creating - long instruction streams.

  • - -
  • Insertion into an implicit instruction list - -

    Instruction instances that are already in BasicBlocks - are implicitly associated with an existing instruction list: the instruction - list of the enclosing basic block. Thus, we could have accomplished the same - thing as the above code without being given a BasicBlock by doing: -

    - -
    -
    -Instruction *pi = ...;
    -Instruction *newInst = new Instruction(...);
    -
    -pi->getParent()->getInstList().insert(pi, newInst);
    -
    -
    - -

    In fact, this sequence of steps occurs so frequently that the - Instruction class and Instruction-derived classes provide - constructors which take (as a default parameter) a pointer to an - Instruction which the newly-created Instruction should - precede. That is, Instruction constructors are capable of - inserting the newly-created instance into the BasicBlock of a - provided instruction, immediately before that instruction. Using an - Instruction constructor with a insertBefore (default) - parameter, the above code becomes:

    - -
    -
    -Instruction* pi = ...;
    -Instruction* newInst = new Instruction(..., pi);
    -
    -
    - -

    which is much cleaner, especially if you're creating a lot of - instructions and adding them to BasicBlocks.

  • -
- -
- - -

- Deleting Instructions -

- -
- -

Deleting an instruction from an existing sequence of instructions that form a -BasicBlock is very straight-forward: just -call the instruction's eraseFromParent() method. For example:

- -
-
-Instruction *I = .. ;
-I->eraseFromParent();
-
-
- -

This unlinks the instruction from its containing basic block and deletes -it. If you'd just like to unlink the instruction from its containing basic -block but not delete it, you can use the removeFromParent() method.

- -
- - -

- Replacing an Instruction with another - Value -

- -
- -
Replacing individual instructions
- -

Including "llvm/Transforms/Utils/BasicBlockUtils.h" -permits use of two very useful replace functions: ReplaceInstWithValue -and ReplaceInstWithInst.

- -
Deleting Instructions
- -
-
    -
  • ReplaceInstWithValue - -

    This function replaces all uses of a given instruction with a value, - and then removes the original instruction. The following example - illustrates the replacement of the result of a particular - AllocaInst that allocates memory for a single integer with a null - pointer to an integer.

    - -
    -
    -AllocaInst* instToReplace = ...;
    -BasicBlock::iterator ii(instToReplace);
    -
    -ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
    -                     Constant::getNullValue(PointerType::getUnqual(Type::Int32Ty)));
    -
  • - -
  • ReplaceInstWithInst - -

    This function replaces a particular instruction with another - instruction, inserting the new instruction into the basic block at the - location where the old instruction was, and replacing any uses of the old - instruction with the new instruction. The following example illustrates - the replacement of one AllocaInst with another.

    - -
    -
    -AllocaInst* instToReplace = ...;
    -BasicBlock::iterator ii(instToReplace);
    -
    -ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
    -                    new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
    -
  • -
- -
- -
Replacing multiple uses of Users and Values
- -

You can use Value::replaceAllUsesWith and -User::replaceUsesOfWith to change more than one use at a time. See the -doxygen documentation for the Value Class -and User Class, respectively, for more -information.

- - - -
- - -

- Deleting GlobalVariables -

- -
- -

Deleting a global variable from a module is just as easy as deleting an -Instruction. First, you must have a pointer to the global variable that you wish - to delete. You use this pointer to erase it from its parent, the module. - For example:

- -
-
-GlobalVariable *GV = .. ;
-
-GV->eraseFromParent();
-
-
- -
- -
- - -

- How to Create Types -

- -
- -

In generating IR, you may need some complex types. If you know these types -statically, you can use TypeBuilder<...>::get(), defined -in llvm/Support/TypeBuilder.h, to retrieve them. TypeBuilder -has two forms depending on whether you're building types for cross-compilation -or native library use. TypeBuilder<T, true> requires -that T be independent of the host environment, meaning that it's built -out of types from -the llvm::types -namespace and pointers, functions, arrays, etc. built of -those. TypeBuilder<T, false> additionally allows native C types -whose size may depend on the host compiler. For example,

- -
-
-FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
-
-
- -

is easier to read and write than the equivalent

- -
-
-std::vector<const Type*> params;
-params.push_back(PointerType::getUnqual(Type::Int32Ty));
-FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
-
-
- -

See the class -comment for more details.

- -
- -
- - -

- Threads and LLVM -

- - -
-

-This section describes the interaction of the LLVM APIs with multithreading, -both on the part of client applications, and in the JIT, in the hosted -application. -

- -

-Note that LLVM's support for multithreading is still relatively young. Up -through version 2.5, the execution of threaded hosted applications was -supported, but not threaded client access to the APIs. While this use case is -now supported, clients must adhere to the guidelines specified below to -ensure proper operation in multithreaded mode. -

- -

-Note that, on Unix-like platforms, LLVM requires the presence of GCC's atomic -intrinsics in order to support threaded operation. If you need a -multhreading-capable LLVM on a platform without a suitably modern system -compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and -using the resultant compiler to build a copy of LLVM with multithreading -support. -

- - -

- Entering and Exiting Multithreaded Mode -

- -
- -

-In order to properly protect its internal data structures while avoiding -excessive locking overhead in the single-threaded case, the LLVM must intialize -certain data structures necessary to provide guards around its internals. To do -so, the client program must invoke llvm_start_multithreaded() before -making any concurrent LLVM API calls. To subsequently tear down these -structures, use the llvm_stop_multithreaded() call. You can also use -the llvm_is_multithreaded() call to check the status of multithreaded -mode. -

- -

-Note that both of these calls must be made in isolation. That is to -say that no other LLVM API calls may be executing at any time during the -execution of llvm_start_multithreaded() or llvm_stop_multithreaded -. It's is the client's responsibility to enforce this isolation. -

- -

-The return value of llvm_start_multithreaded() indicates the success or -failure of the initialization. Failure typically indicates that your copy of -LLVM was built without multithreading support, typically because GCC atomic -intrinsics were not found in your system compiler. In this case, the LLVM API -will not be safe for concurrent calls. However, it will be safe for -hosting threaded applications in the JIT, though care -must be taken to ensure that side exits and the like do not accidentally -result in concurrent LLVM API calls. -

-
- - -

- Ending Execution with llvm_shutdown() -

- -
-

-When you are done using the LLVM APIs, you should call llvm_shutdown() -to deallocate memory used for internal structures. This will also invoke -llvm_stop_multithreaded() if LLVM is operating in multithreaded mode. -As such, llvm_shutdown() requires the same isolation guarantees as -llvm_stop_multithreaded(). -

- -

-Note that, if you use scope-based shutdown, you can use the -llvm_shutdown_obj class, which calls llvm_shutdown() in its -destructor. -

- - -

- Lazy Initialization with ManagedStatic -

- -
-

-ManagedStatic is a utility class in LLVM used to implement static -initialization of static resources, such as the global type tables. Before the -invocation of llvm_shutdown(), it implements a simple lazy -initialization scheme. Once llvm_start_multithreaded() returns, -however, it uses double-checked locking to implement thread-safe lazy -initialization. -

- -

-Note that, because no other threads are allowed to issue LLVM API calls before -llvm_start_multithreaded() returns, it is possible to have -ManagedStatics of llvm::sys::Mutexs. -

- -

-The llvm_acquire_global_lock() and llvm_release_global_lock -APIs provide access to the global lock used to implement the double-checked -locking for lazy initialization. These should only be used internally to LLVM, -and only if you know what you're doing! -

-
- - -

- Achieving Isolation with LLVMContext -

- -
-

-LLVMContext is an opaque class in the LLVM API which clients can use -to operate multiple, isolated instances of LLVM concurrently within the same -address space. For instance, in a hypothetical compile-server, the compilation -of an individual translation unit is conceptually independent from all the -others, and it would be desirable to be able to compile incoming translation -units concurrently on independent server threads. Fortunately, -LLVMContext exists to enable just this kind of scenario! -

- -

-Conceptually, LLVMContext provides isolation. Every LLVM entity -(Modules, Values, Types, Constants, etc.) -in LLVM's in-memory IR belongs to an LLVMContext. Entities in -different contexts cannot interact with each other: Modules in -different contexts cannot be linked together, Functions cannot be added -to Modules in different contexts, etc. What this means is that is is -safe to compile on multiple threads simultaneously, as long as no two threads -operate on entities within the same context. -

- -

-In practice, very few places in the API require the explicit specification of a -LLVMContext, other than the Type creation/lookup APIs. -Because every Type carries a reference to its owning context, most -other entities can determine what context they belong to by looking at their -own Type. If you are adding new entities to LLVM IR, please try to -maintain this interface design. -

- -

-For clients that do not require the benefits of isolation, LLVM -provides a convenience API getGlobalContext(). This returns a global, -lazily initialized LLVMContext that may be used in situations where -isolation is not a concern. -

-
- - -

- Threads and the JIT -

- -
-

-LLVM's "eager" JIT compiler is safe to use in threaded programs. Multiple -threads can call ExecutionEngine::getPointerToFunction() or -ExecutionEngine::runFunction() concurrently, and multiple threads can -run code output by the JIT concurrently. The user must still ensure that only -one thread accesses IR in a given LLVMContext while another thread -might be modifying it. One way to do that is to always hold the JIT lock while -accessing IR outside the JIT (the JIT modifies the IR by adding -CallbackVHs). Another way is to only -call getPointerToFunction() from the LLVMContext's thread. -

- -

When the JIT is configured to compile lazily (using -ExecutionEngine::DisableLazyCompilation(false)), there is currently a -race condition in -updating call sites after a function is lazily-jitted. It's still possible to -use the lazy JIT in a threaded program if you ensure that only one thread at a -time can call any particular lazy stub and that the JIT lock guards any IR -access, but we suggest using only the eager JIT in threaded programs. -

-
- -
- - -

- Advanced Topics -

- - -
-

-This section describes some of the advanced or obscure API's that most clients -do not need to be aware of. These API's tend manage the inner workings of the -LLVM system, and only need to be accessed in unusual circumstances. -

- - - -

- The ValueSymbolTable class -

- -
-

The -ValueSymbolTable class provides a symbol table that the Function and -Module classes use for naming value definitions. The symbol table -can provide a name for any Value. -

- -

Note that the SymbolTable class should not be directly accessed -by most clients. It should only be used when iteration over the symbol table -names themselves are required, which is very special purpose. Note that not -all LLVM -Values have names, and those without names (i.e. they have -an empty name) do not exist in the symbol table. -

- -

Symbol tables support iteration over the values in the symbol -table with begin/end/iterator and supports querying to see if a -specific name is in the symbol table (with lookup). The -ValueSymbolTable class exposes no public mutator methods, instead, -simply call setName on a value, which will autoinsert it into the -appropriate symbol table.

- -
- - - - -

- The User and owned Use classes' memory layout -

- -
-

The -User class provides a basis for expressing the ownership of User -towards other -Values. The -Use helper class is employed to do the bookkeeping and to facilitate O(1) -addition and removal.

- - -

- - Interaction and relationship between User and Use objects - -

- -
-

-A subclass of User can choose between incorporating its Use objects -or refer to them out-of-line by means of a pointer. A mixed variant -(some Uses inline others hung off) is impractical and breaks the invariant -that the Use objects belonging to the same User form a contiguous array. -

- -

-We have 2 different layouts in the User (sub)classes: -

    -
  • Layout a) -The Use object(s) are inside (resp. at fixed offset) of the User -object and there are a fixed number of them.

    - -
  • Layout b) -The Use object(s) are referenced by a pointer to an -array from the User object and there may be a variable -number of them.

    -
-

-As of v2.4 each layout still possesses a direct pointer to the -start of the array of Uses. Though not mandatory for layout a), -we stick to this redundancy for the sake of simplicity. -The User object also stores the number of Use objects it -has. (Theoretically this information can also be calculated -given the scheme presented below.)

-

-Special forms of allocation operators (operator new) -enforce the following memory layouts:

- -
    -
  • Layout a) is modelled by prepending the User object by the Use[] array.

    - -
    -...---.---.---.---.-------...
    -  | P | P | P | P | User
    -'''---'---'---'---'-------'''
    -
    - -
  • Layout b) is modelled by pointing at the Use[] array.

    -
    -.-------...
    -| User
    -'-------'''
    -    |
    -    v
    -    .---.---.---.---...
    -    | P | P | P | P |
    -    '---'---'---'---'''
    -
    -
-(In the above figures 'P' stands for the Use** that - is stored in each Use object in the member Use::Prev) - -
- - -

- The waymarking algorithm -

- -
-

-Since the Use objects are deprived of the direct (back)pointer to -their User objects, there must be a fast and exact method to -recover it. This is accomplished by the following scheme:

- -A bit-encoding in the 2 LSBits (least significant bits) of the Use::Prev allows to find the -start of the User object: -
    -
  • 00 —> binary digit 0
  • -
  • 01 —> binary digit 1
  • -
  • 10 —> stop and calculate (s)
  • -
  • 11 —> full stop (S)
  • -
-

-Given a Use*, all we have to do is to walk till we get -a stop and we either have a User immediately behind or -we have to walk to the next stop picking up digits -and calculating the offset:

-
-.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
-| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
-'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
-    |+15                |+10            |+6         |+3     |+1
-    |                   |               |           |       |__>
-    |                   |               |           |__________>
-    |                   |               |______________________>
-    |                   |______________________________________>
-    |__________________________________________________________>
-
-

-Only the significant number of bits need to be stored between the -stops, so that the worst case is 20 memory accesses when there are -1000 Use objects associated with a User.

- -
- - -

- Reference implementation -

- -
-

-The following literate Haskell fragment demonstrates the concept:

- -
-
-> import Test.QuickCheck
-> 
-> digits :: Int -> [Char] -> [Char]
-> digits 0 acc = '0' : acc
-> digits 1 acc = '1' : acc
-> digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
-> 
-> dist :: Int -> [Char] -> [Char]
-> dist 0 [] = ['S']
-> dist 0 acc = acc
-> dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
-> dist n acc = dist (n - 1) $ dist 1 acc
-> 
-> takeLast n ss = reverse $ take n $ reverse ss
-> 
-> test = takeLast 40 $ dist 20 []
-> 
-
-
-

-Printing <test> gives: "1s100000s11010s10100s1111s1010s110s11s1S"

-

-The reverse algorithm computes the length of the string just by examining -a certain prefix:

- -
-
-> pref :: [Char] -> Int
-> pref "S" = 1
-> pref ('s':'1':rest) = decode 2 1 rest
-> pref (_:rest) = 1 + pref rest
-> 
-> decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
-> decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
-> decode walk acc _ = walk + acc
-> 
-
-
-

-Now, as expected, printing <pref test> gives 40.

-

-We can quickCheck this with following property:

- -
-
-> testcase = dist 2000 []
-> testcaseLength = length testcase
-> 
-> identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
->     where arr = takeLast n testcase
-> 
-
-
-

-As expected <quickCheck identityProp> gives:

- -
-*Main> quickCheck identityProp
-OK, passed 100 tests.
-
-

-Let's be a bit more exhaustive:

- -
-
-> 
-> deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
-> 
-
-
-

-And here is the result of <deepCheck identityProp>:

- -
-*Main> deepCheck identityProp
-OK, passed 500 tests.
-
- -
- - -

- Tagging considerations -

- -
- -

-To maintain the invariant that the 2 LSBits of each Use** in Use -never change after being set up, setters of Use::Prev must re-tag the -new Use** on every modification. Accordingly getters must strip the -tag bits.

-

-For layout b) instead of the User we find a pointer (User* with LSBit set). -Following this pointer brings us to the User. A portable trick ensures -that the first bytes of User (if interpreted as a pointer) never has -the LSBit set. (Portability is relying on the fact that all known compilers place the -vptr in the first word of the instances.)

- -
- -
- -
- - -

- The Core LLVM Class Hierarchy Reference -

- - -
-

#include "llvm/Type.h" -
doxygen info: Type Class

- -

The Core LLVM classes are the primary means of representing the program -being inspected or transformed. The core LLVM classes are defined in -header files in the include/llvm/ directory, and implemented in -the lib/VMCore directory.

- - -

- The Type class and Derived Types -

- -
- -

Type is a superclass of all type classes. Every Value has - a Type. Type cannot be instantiated directly but only - through its subclasses. Certain primitive types (VoidType, - LabelType, FloatType and DoubleType) have hidden - subclasses. They are hidden because they offer no useful functionality beyond - what the Type class offers except to distinguish themselves from - other subclasses of Type.

-

All other types are subclasses of DerivedType. Types can be - named, but this is not a requirement. There exists exactly - one instance of a given shape at any one time. This allows type equality to - be performed with address equality of the Type Instance. That is, given two - Type* values, the types are identical if the pointers are identical. -

- - -

- Important Public Methods -

- -
- -
    -
  • bool isIntegerTy() const: Returns true for any integer type.
  • - -
  • bool isFloatingPointTy(): Return true if this is one of the five - floating point types.
  • - -
  • bool isSized(): Return true if the type has known size. Things - that don't have a size are abstract types, labels and void.
  • - -
-
- - -

- Important Derived Types -

-
-
-
IntegerType
-
Subclass of DerivedType that represents integer types of any bit width. - Any bit width between IntegerType::MIN_INT_BITS (1) and - IntegerType::MAX_INT_BITS (~8 million) can be represented. -
    -
  • static const IntegerType* get(unsigned NumBits): get an integer - type of a specific bit width.
  • -
  • unsigned getBitWidth() const: Get the bit width of an integer - type.
  • -
-
-
SequentialType
-
This is subclassed by ArrayType, PointerType and VectorType. -
    -
  • const Type * getElementType() const: Returns the type of each - of the elements in the sequential type.
  • -
-
-
ArrayType
-
This is a subclass of SequentialType and defines the interface for array - types. -
    -
  • unsigned getNumElements() const: Returns the number of - elements in the array.
  • -
-
-
PointerType
-
Subclass of SequentialType for pointer types.
-
VectorType
-
Subclass of SequentialType for vector types. A - vector type is similar to an ArrayType but is distinguished because it is - a first class type whereas ArrayType is not. Vector types are used for - vector operations and are usually small vectors of of an integer or floating - point type.
-
StructType
-
Subclass of DerivedTypes for struct types.
-
FunctionType
-
Subclass of DerivedTypes for function types. -
    -
  • bool isVarArg() const: Returns true if it's a vararg - function
  • -
  • const Type * getReturnType() const: Returns the - return type of the function.
  • -
  • const Type * getParamType (unsigned i): Returns - the type of the ith parameter.
  • -
  • const unsigned getNumParams() const: Returns the - number of formal parameters.
  • -
-
-
-
- -
- - -

- The Module class -

- -
- -

#include "llvm/Module.h"
doxygen info: -Module Class

- -

The Module class represents the top level structure present in LLVM -programs. An LLVM module is effectively either a translation unit of the -original program or a combination of several translation units merged by the -linker. The Module class keeps track of a list of Functions, a list of GlobalVariables, and a SymbolTable. Additionally, it contains a few -helpful member functions that try to make common operations easy.

- - -

- Important Public Members of the Module class -

- -
- -
    -
  • Module::Module(std::string name = "") - -

    Constructing a Module is easy. You can optionally -provide a name for it (probably based on the name of the translation unit).

    -
  • - -
  • Module::iterator - Typedef for function list iterator
    - Module::const_iterator - Typedef for const_iterator.
    - - begin(), end() - size(), empty() - -

    These are forwarding methods that make it easy to access the contents of - a Module object's Function - list.

  • - -
  • Module::FunctionListType &getFunctionList() - -

    Returns the list of Functions. This is - necessary to use when you need to update the list or perform a complex - action that doesn't have a forwarding method.

    - -

  • -
- -
- -
    -
  • Module::global_iterator - Typedef for global variable list iterator
    - - Module::const_global_iterator - Typedef for const_iterator.
    - - global_begin(), global_end() - global_size(), global_empty() - -

    These are forwarding methods that make it easy to access the contents of - a Module object's GlobalVariable list.

  • - -
  • Module::GlobalListType &getGlobalList() - -

    Returns the list of GlobalVariables. This is necessary to - use when you need to update the list or perform a complex action that - doesn't have a forwarding method.

    - -

  • -
- -
- - - -
- -
    -
  • Function *getFunction(const std::string - &Name, const FunctionType *Ty) - -

    Look up the specified function in the Module SymbolTable. If it does not exist, return - null.

  • - -
  • Function *getOrInsertFunction(const - std::string &Name, const FunctionType *T) - -

    Look up the specified function in the Module SymbolTable. If it does not exist, add an - external declaration for the function and return it.

  • - -
  • std::string getTypeName(const Type *Ty) - -

    If there is at least one entry in the SymbolTable for the specified Type, return it. Otherwise return the empty - string.

  • - -
  • bool addTypeName(const std::string &Name, const Type *Ty) - -

    Insert an entry in the SymbolTable - mapping Name to Ty. If there is already an entry for this - name, true is returned and the SymbolTable is not modified.

  • -
- -
- -
- - -

- The Value class -

- -
- -

#include "llvm/Value.h" -
-doxygen info: Value Class

- -

The Value class is the most important class in the LLVM Source -base. It represents a typed value that may be used (among other things) as an -operand to an instruction. There are many different types of Values, -such as Constants,Arguments. Even Instructions and Functions are Values.

- -

A particular Value may be used many times in the LLVM representation -for a program. For example, an incoming argument to a function (represented -with an instance of the Argument class) is "used" by -every instruction in the function that references the argument. To keep track -of this relationship, the Value class keeps a list of all of the Users that is using it (the User class is a base class for all nodes in the LLVM -graph that can refer to Values). This use list is how LLVM represents -def-use information in the program, and is accessible through the use_* -methods, shown below.

- -

Because LLVM is a typed representation, every LLVM Value is typed, -and this Type is available through the getType() -method. In addition, all LLVM values can be named. The "name" of the -Value is a symbolic string printed in the LLVM code:

- -
-
-%foo = add i32 1, 2
-
-
- -

The name of this instruction is "foo". NOTE -that the name of any value may be missing (an empty string), so names should -ONLY be used for debugging (making the source code easier to read, -debugging printouts), they should not be used to keep track of values or map -between them. For this purpose, use a std::map of pointers to the -Value itself instead.

- -

One important aspect of LLVM is that there is no distinction between an SSA -variable and the operation that produces it. Because of this, any reference to -the value produced by an instruction (or the value available as an incoming -argument, for example) is represented as a direct pointer to the instance of -the class that -represents this value. Although this may take some getting used to, it -simplifies the representation and makes it easier to manipulate.

- - -

- Important Public Members of the Value class -

- -
- -
    -
  • Value::use_iterator - Typedef for iterator over the -use-list
    - Value::const_use_iterator - Typedef for const_iterator over -the use-list
    - unsigned use_size() - Returns the number of users of the -value.
    - bool use_empty() - Returns true if there are no users.
    - use_iterator use_begin() - Get an iterator to the start of -the use-list.
    - use_iterator use_end() - Get an iterator to the end of the -use-list.
    - User *use_back() - Returns the last -element in the list. -

    These methods are the interface to access the def-use -information in LLVM. As with all other iterators in LLVM, the naming -conventions follow the conventions defined by the STL.

    -
  • -
  • Type *getType() const -

    This method returns the Type of the Value.

    -
  • -
  • bool hasName() const
    - std::string getName() const
    - void setName(const std::string &Name) -

    This family of methods is used to access and assign a name to a Value, -be aware of the precaution above.

    -
  • -
  • void replaceAllUsesWith(Value *V) - -

    This method traverses the use list of a Value changing all Users of the current value to refer to - "V" instead. For example, if you detect that an instruction always - produces a constant value (for example through constant folding), you can - replace all uses of the instruction with the constant like this:

    - -
    -
    -Inst->replaceAllUsesWith(ConstVal);
    -
    -
    - -
- -
- -
- - -

- The User class -

- -
- -

-#include "llvm/User.h"
-doxygen info: User Class
-Superclass: Value

- -

The User class is the common base class of all LLVM nodes that may -refer to Values. It exposes a list of "Operands" -that are all of the Values that the User is -referring to. The User class itself is a subclass of -Value.

- -

The operands of a User point directly to the LLVM Value that it refers to. Because LLVM uses Static -Single Assignment (SSA) form, there can only be one definition referred to, -allowing this direct connection. This connection provides the use-def -information in LLVM.

- - -

- Important Public Members of the User class -

- -
- -

The User class exposes the operand list in two ways: through -an index access interface and through an iterator based interface.

- -
    -
  • Value *getOperand(unsigned i)
    - unsigned getNumOperands() -

    These two methods expose the operands of the User in a -convenient form for direct access.

  • - -
  • User::op_iterator - Typedef for iterator over the operand -list
    - op_iterator op_begin() - Get an iterator to the start of -the operand list.
    - op_iterator op_end() - Get an iterator to the end of the -operand list. -

    Together, these methods make up the iterator based interface to -the operands of a User.

  • -
- -
- -
- - -

- The Instruction class -

- -
- -

#include "llvm/Instruction.h"
-doxygen info: Instruction Class
-Superclasses: User, Value

- -

The Instruction class is the common base class for all LLVM -instructions. It provides only a few methods, but is a very commonly used -class. The primary data tracked by the Instruction class itself is the -opcode (instruction type) and the parent BasicBlock the Instruction is embedded -into. To represent a specific type of instruction, one of many subclasses of -Instruction are used.

- -

Because the Instruction class subclasses the User class, its operands can be accessed in the same -way as for other Users (with the -getOperand()/getNumOperands() and -op_begin()/op_end() methods).

An important file for -the Instruction class is the llvm/Instruction.def file. This -file contains some meta-data about the various different types of instructions -in LLVM. It describes the enum values that are used as opcodes (for example -Instruction::Add and Instruction::ICmp), as well as the -concrete sub-classes of Instruction that implement the instruction (for -example BinaryOperator and CmpInst). Unfortunately, the use of macros in -this file confuses doxygen, so these enum values don't show up correctly in the -doxygen output.

- - -

- - Important Subclasses of the Instruction class - -

-
-
    -
  • BinaryOperator -

    This subclasses represents all two operand instructions whose operands - must be the same type, except for the comparison instructions.

  • -
  • CastInst -

    This subclass is the parent of the 12 casting instructions. It provides - common operations on cast instructions.

    -
  • CmpInst -

    This subclass respresents the two comparison instructions, - ICmpInst (integer opreands), and - FCmpInst (floating point operands).

    -
  • TerminatorInst -

    This subclass is the parent of all terminator instructions (those which - can terminate a block).

    -
-
- - -

- - Important Public Members of the Instruction class - -

- -
- -
    -
  • BasicBlock *getParent() -

    Returns the BasicBlock that -this Instruction is embedded into.

  • -
  • bool mayWriteToMemory() -

    Returns true if the instruction writes to memory, i.e. it is a - call,free,invoke, or store.

  • -
  • unsigned getOpcode() -

    Returns the opcode for the Instruction.

  • -
  • Instruction *clone() const -

    Returns another instance of the specified instruction, identical -in all ways to the original except that the instruction has no parent -(ie it's not embedded into a BasicBlock), -and it has no name

  • -
- -
- -
- - -

- The Constant class and subclasses -

- -
- -

Constant represents a base class for different types of constants. It -is subclassed by ConstantInt, ConstantArray, etc. for representing -the various types of Constants. GlobalValue is also -a subclass, which represents the address of a global variable or function. -

- - -

Important Subclasses of Constant

-
-
    -
  • ConstantInt : This subclass of Constant represents an integer constant of - any width. -
      -
    • const APInt& getValue() const: Returns the underlying - value of this constant, an APInt value.
    • -
    • int64_t getSExtValue() const: Converts the underlying APInt - value to an int64_t via sign extension. If the value (not the bit width) - of the APInt is too large to fit in an int64_t, an assertion will result. - For this reason, use of this method is discouraged.
    • -
    • uint64_t getZExtValue() const: Converts the underlying APInt - value to a uint64_t via zero extension. IF the value (not the bit width) - of the APInt is too large to fit in a uint64_t, an assertion will result. - For this reason, use of this method is discouraged.
    • -
    • static ConstantInt* get(const APInt& Val): Returns the - ConstantInt object that represents the value provided by Val. - The type is implied as the IntegerType that corresponds to the bit width - of Val.
    • -
    • static ConstantInt* get(const Type *Ty, uint64_t Val): - Returns the ConstantInt object that represents the value provided by - Val for integer type Ty.
    • -
    -
  • -
  • ConstantFP : This class represents a floating point constant. -
      -
    • double getValue() const: Returns the underlying value of - this constant.
    • -
    -
  • -
  • ConstantArray : This represents a constant array. -
      -
    • const std::vector<Use> &getValues() const: Returns - a vector of component constants that makeup this array.
    • -
    -
  • -
  • ConstantStruct : This represents a constant struct. -
      -
    • const std::vector<Use> &getValues() const: Returns - a vector of component constants that makeup this array.
    • -
    -
  • -
  • GlobalValue : This represents either a global variable or a function. In - either case, the value is a constant fixed address (after linking). -
  • -
-
- -
- - -

- The GlobalValue class -

- -
- -

#include "llvm/GlobalValue.h"
-doxygen info: GlobalValue -Class
-Superclasses: Constant, -User, Value

- -

Global values (GlobalVariables or Functions) are the only LLVM values that are -visible in the bodies of all Functions. -Because they are visible at global scope, they are also subject to linking with -other globals defined in different translation units. To control the linking -process, GlobalValues know their linkage rules. Specifically, -GlobalValues know whether they have internal or external linkage, as -defined by the LinkageTypes enumeration.

- -

If a GlobalValue has internal linkage (equivalent to being -static in C), it is not visible to code outside the current translation -unit, and does not participate in linking. If it has external linkage, it is -visible to external code, and does participate in linking. In addition to -linkage information, GlobalValues keep track of which Module they are currently part of.

- -

Because GlobalValues are memory objects, they are always referred to -by their address. As such, the Type of a -global is always a pointer to its contents. It is important to remember this -when using the GetElementPtrInst instruction because this pointer must -be dereferenced first. For example, if you have a GlobalVariable (a -subclass of GlobalValue) that is an array of 24 ints, type [24 x -i32], then the GlobalVariable is a pointer to that array. Although -the address of the first element of this array and the value of the -GlobalVariable are the same, they have different types. The -GlobalVariable's type is [24 x i32]. The first element's type -is i32. Because of this, accessing a global value requires you to -dereference the pointer with GetElementPtrInst first, then its elements -can be accessed. This is explained in the LLVM -Language Reference Manual.

- - -

- - Important Public Members of the GlobalValue class - -

- -
- -
    -
  • bool hasInternalLinkage() const
    - bool hasExternalLinkage() const
    - void setInternalLinkage(bool HasInternalLinkage) -

    These methods manipulate the linkage characteristics of the GlobalValue.

    -

    -
  • -
  • Module *getParent() -

    This returns the Module that the -GlobalValue is currently embedded into.

  • -
- -
- -
- - -

- The Function class -

- -
- -

#include "llvm/Function.h"
doxygen -info: Function Class
-Superclasses: GlobalValue, -Constant, -User, -Value

- -

The Function class represents a single procedure in LLVM. It is -actually one of the more complex classes in the LLVM hierarchy because it must -keep track of a large amount of data. The Function class keeps track -of a list of BasicBlocks, a list of formal -Arguments, and a -SymbolTable.

- -

The list of BasicBlocks is the most -commonly used part of Function objects. The list imposes an implicit -ordering of the blocks in the function, which indicate how the code will be -laid out by the backend. Additionally, the first BasicBlock is the implicit entry node for the -Function. It is not legal in LLVM to explicitly branch to this initial -block. There are no implicit exit nodes, and in fact there may be multiple exit -nodes from a single Function. If the BasicBlock list is empty, this indicates that -the Function is actually a function declaration: the actual body of the -function hasn't been linked in yet.

- -

In addition to a list of BasicBlocks, the -Function class also keeps track of the list of formal Arguments that the function receives. This -container manages the lifetime of the Argument -nodes, just like the BasicBlock list does for -the BasicBlocks.

- -

The SymbolTable is a very rarely used -LLVM feature that is only used when you have to look up a value by name. Aside -from that, the SymbolTable is used -internally to make sure that there are not conflicts between the names of Instructions, BasicBlocks, or Arguments in the function body.

- -

Note that Function is a GlobalValue -and therefore also a Constant. The value of the function -is its address (after linking) which is guaranteed to be constant.

- - -

- - Important Public Members of the Function class - -

- -
- -
    -
  • Function(const FunctionType - *Ty, LinkageTypes Linkage, const std::string &N = "", Module* Parent = 0) - -

    Constructor used when you need to create new Functions to add - the the program. The constructor must specify the type of the function to - create and what type of linkage the function should have. The FunctionType argument - specifies the formal arguments and return value for the function. The same - FunctionType value can be used to - create multiple functions. The Parent argument specifies the Module - in which the function is defined. If this argument is provided, the function - will automatically be inserted into that module's list of - functions.

  • - -
  • bool isDeclaration() - -

    Return whether or not the Function has a body defined. If the - function is "external", it does not have a body, and thus must be resolved - by linking with a function defined in a different translation unit.

  • - -
  • Function::iterator - Typedef for basic block list iterator
    - Function::const_iterator - Typedef for const_iterator.
    - - begin(), end() - size(), empty() - -

    These are forwarding methods that make it easy to access the contents of - a Function object's BasicBlock - list.

  • - -
  • Function::BasicBlockListType &getBasicBlockList() - -

    Returns the list of BasicBlocks. This - is necessary to use when you need to update the list or perform a complex - action that doesn't have a forwarding method.

  • - -
  • Function::arg_iterator - Typedef for the argument list -iterator
    - Function::const_arg_iterator - Typedef for const_iterator.
    - - arg_begin(), arg_end() - arg_size(), arg_empty() - -

    These are forwarding methods that make it easy to access the contents of - a Function object's Argument - list.

  • - -
  • Function::ArgumentListType &getArgumentList() - -

    Returns the list of Arguments. This is - necessary to use when you need to update the list or perform a complex - action that doesn't have a forwarding method.

  • - -
  • BasicBlock &getEntryBlock() - -

    Returns the entry BasicBlock for the - function. Because the entry block for the function is always the first - block, this returns the first block of the Function.

  • - -
  • Type *getReturnType()
    - FunctionType *getFunctionType() - -

    This traverses the Type of the - Function and returns the return type of the function, or the FunctionType of the actual - function.

  • - -
  • SymbolTable *getSymbolTable() - -

    Return a pointer to the SymbolTable - for this Function.

  • -
- -
- -
- - -

- The GlobalVariable class -

- -
- -

#include "llvm/GlobalVariable.h" -
-doxygen info: GlobalVariable - Class
-Superclasses: GlobalValue, -Constant, -User, -Value

- -

Global variables are represented with the (surprise surprise) -GlobalVariable class. Like functions, GlobalVariables are also -subclasses of GlobalValue, and as such are -always referenced by their address (global values must live in memory, so their -"name" refers to their constant address). See -GlobalValue for more on this. Global -variables may have an initial value (which must be a -Constant), and if they have an initializer, -they may be marked as "constant" themselves (indicating that their contents -never change at runtime).

- - -

- - Important Public Members of the GlobalVariable class - -

- -
- -
    -
  • GlobalVariable(const Type *Ty, bool - isConstant, LinkageTypes& Linkage, Constant - *Initializer = 0, const std::string &Name = "", Module* Parent = 0) - -

    Create a new global variable of the specified type. If - isConstant is true then the global variable will be marked as - unchanging for the program. The Linkage parameter specifies the type of - linkage (internal, external, weak, linkonce, appending) for the variable. - If the linkage is InternalLinkage, WeakAnyLinkage, WeakODRLinkage, - LinkOnceAnyLinkage or LinkOnceODRLinkage,  then the resultant - global variable will have internal linkage. AppendingLinkage concatenates - together all instances (in different translation units) of the variable - into a single variable but is only applicable to arrays.  See - the LLVM Language Reference for - further details on linkage types. Optionally an initializer, a name, and the - module to put the variable into may be specified for the global variable as - well.

  • - -
  • bool isConstant() const - -

    Returns true if this is a global variable that is known not to - be modified at runtime.

  • - -
  • bool hasInitializer() - -

    Returns true if this GlobalVariable has an intializer.

  • - -
  • Constant *getInitializer() - -

    Returns the initial value for a GlobalVariable. It is not legal - to call this method if there is no initializer.

  • -
- -
- -
- - -

- The BasicBlock class -

- -
- -

#include "llvm/BasicBlock.h"
-doxygen info: BasicBlock -Class
-Superclass: Value

- -

This class represents a single entry single exit section of the code, -commonly known as a basic block by the compiler community. The -BasicBlock class maintains a list of Instructions, which form the body of the block. -Matching the language definition, the last element of this list of instructions -is always a terminator instruction (a subclass of the TerminatorInst class).

- -

In addition to tracking the list of instructions that make up the block, the -BasicBlock class also keeps track of the Function that it is embedded into.

- -

Note that BasicBlocks themselves are Values, because they are referenced by instructions -like branches and can go in the switch tables. BasicBlocks have type -label.

- - -

- - Important Public Members of the BasicBlock class - -

- -
-
    - -
  • BasicBlock(const std::string &Name = "", Function *Parent = 0) - -

    The BasicBlock constructor is used to create new basic blocks for -insertion into a function. The constructor optionally takes a name for the new -block, and a Function to insert it into. If -the Parent parameter is specified, the new BasicBlock is -automatically inserted at the end of the specified Function, if not specified, the BasicBlock must be -manually inserted into the Function.

  • - -
  • BasicBlock::iterator - Typedef for instruction list iterator
    -BasicBlock::const_iterator - Typedef for const_iterator.
    -begin(), end(), front(), back(), -size(), empty() -STL-style functions for accessing the instruction list. - -

    These methods and typedefs are forwarding functions that have the same -semantics as the standard library methods of the same names. These methods -expose the underlying instruction list of a basic block in a way that is easy to -manipulate. To get the full complement of container operations (including -operations to update the list), you must use the getInstList() -method.

  • - -
  • BasicBlock::InstListType &getInstList() - -

    This method is used to get access to the underlying container that actually -holds the Instructions. This method must be used when there isn't a forwarding -function in the BasicBlock class for the operation that you would like -to perform. Because there are no forwarding functions for "updating" -operations, you need to use this if you want to update the contents of a -BasicBlock.

  • - -
  • Function *getParent() - -

    Returns a pointer to Function the block is -embedded into, or a null pointer if it is homeless.

  • - -
  • TerminatorInst *getTerminator() - -

    Returns a pointer to the terminator instruction that appears at the end of -the BasicBlock. If there is no terminator instruction, or if the last -instruction in the block is not a terminator, then a null pointer is -returned.

  • - -
- -
- -
- - -

- The Argument class -

- -
- -

This subclass of Value defines the interface for incoming formal -arguments to a function. A Function maintains a list of its formal -arguments. An argument has a pointer to the parent Function.

- -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 Strict - - Dinakar Dhurjati and - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-18 13:28:55 -0700 (Wed, 18 Apr 2012) $ -
- - - diff --git a/cpp/llvm/docs/Projects.html b/cpp/llvm/docs/Projects.html deleted file mode 100644 index e9b8968d..00000000 --- a/cpp/llvm/docs/Projects.html +++ /dev/null @@ -1,489 +0,0 @@ - - - - - Creating an LLVM Project - - - - -

Creating an LLVM Project

- -
    -
  1. Overview
  2. -
  3. Create a project from the Sample Project
  4. -
  5. Source tree layout
  6. -
  7. Writing LLVM-style Makefiles -
      -
    1. Required Variables
    2. -
    3. Variables for Building Subdirectories
    4. -
    5. Variables for Building Libraries
    6. -
    7. Variables for Building Programs
    8. -
    9. Miscellaneous Variables
    10. -
  8. -
  9. Placement of object code
  10. -
  11. Further help
  12. -
- -
-

Written by John Criswell

-
- - -

Overview

- - -
- -

The LLVM build system is designed to facilitate the building of third party -projects that use LLVM header files, libraries, and tools. In order to use -these facilities, a Makefile from a project must do the following things:

- -
    -
  1. Set make variables. There are several variables that a Makefile - needs to set to use the LLVM build system: -
      -
    • PROJECT_NAME - The name by which your project is known.
    • -
    • LLVM_SRC_ROOT - The root of the LLVM source tree.
    • -
    • LLVM_OBJ_ROOT - The root of the LLVM object tree.
    • -
    • PROJ_SRC_ROOT - The root of the project's source tree.
    • -
    • PROJ_OBJ_ROOT - The root of the project's object tree.
    • -
    • PROJ_INSTALL_ROOT - The root installation directory.
    • -
    • LEVEL - The relative path from the current directory to the - project's root ($PROJ_OBJ_ROOT).
    • -
  2. -
  3. Include Makefile.config from $(LLVM_OBJ_ROOT).
  4. -
  5. Include Makefile.rules from $(LLVM_SRC_ROOT).
  6. -
- -

There are two ways that you can set all of these variables:

-
    -
  1. You can write your own Makefiles which hard-code these values.
  2. -
  3. You can use the pre-made LLVM sample project. This sample project - includes Makefiles, a configure script that can be used to configure the - location of LLVM, and the ability to support multiple object directories - from a single source directory.
  4. -
- -

This document assumes that you will base your project on the LLVM sample -project found in llvm/projects/sample. If you want to devise your own -build system, studying the sample project and LLVM Makefiles will probably -provide enough information on how to write your own Makefiles.

- -
- - -

- Create a Project from the Sample Project -

- - -
- -

Follow these simple steps to start your project:

- -
    -
  1. Copy the llvm/projects/sample directory to any place of your -choosing. You can place it anywhere you like. Rename the directory to match -the name of your project.
  2. - -
  3. -If you downloaded LLVM using Subversion, remove all the directories named .svn -(and all the files therein) from your project's new source tree. This will -keep Subversion from thinking that your project is inside -llvm/trunk/projects/sample.
  4. - -
  5. Add your source code and Makefiles to your source tree.
  6. - -
  7. If you want your project to be configured with the configure script -then you need to edit autoconf/configure.ac as follows: -
      -
    • AC_INIT. Place the name of your project, its version number and - a contact email address for your project as the arguments to this macro
    • -
    • AC_CONFIG_AUX_DIR. If your project isn't in the - llvm/projects directory then you might need to adjust this so that - it specifies a relative path to the llvm/autoconf directory.
    • -
    • LLVM_CONFIG_PROJECT. Just leave this alone.
    • -
    • AC_CONFIG_SRCDIR. Specify a path to a file name that identifies - your project; or just leave it at Makefile.common.in
    • -
    • AC_CONFIG_FILES. Do not change.
    • -
    • AC_CONFIG_MAKEFILE. Use one of these macros for each Makefile - that your project uses. This macro arranges for your makefiles to be copied - from the source directory, unmodified, to the build directory.
    • -
    -
  8. - -
  9. After updating autoconf/configure.ac, regenerate the -configure script with these commands: - -
    -

    % cd autoconf
    - % ./AutoRegen.sh

    -
    - -

    You must be using Autoconf version 2.59 or later and your aclocal version -should be 1.9 or later.

  10. - -
  11. Run configure in the directory in which you want to place -object code. Use the following options to tell your project where it -can find LLVM: - -
    -
    --with-llvmsrc=<directory>
    -
    Tell your project where the LLVM source tree is located.
    -

    --with-llvmobj=<directory>
    -
    Tell your project where the LLVM object tree is located.
    -

    --prefix=<directory>
    -
    Tell your project where it should get installed.
    -
    -
- -

That's it! Now all you have to do is type gmake (or make -if your on a GNU/Linux system) in the root of your object directory, and your -project should build.

- -
- - -

- Source Tree Layout -

- - -
- -

In order to use the LLVM build system, you will want to organize your -source code so that it can benefit from the build system's features. -Mainly, you want your source tree layout to look similar to the LLVM -source tree layout. The best way to do this is to just copy the -project tree from llvm/projects/sample and modify it to meet -your needs, but you can certainly add to it if you want.

- -

Underneath your top level directory, you should have the following -directories:

- -
-
lib -
- This subdirectory should contain all of your library source - code. For each library that you build, you will have one - directory in lib that will contain that library's source - code. - -

- Libraries can be object files, archives, or dynamic libraries. - The lib directory is just a convenient place for libraries - as it places them all in a directory from which they can be linked - later. - -

include -
- This subdirectory should contain any header files that are - global to your project. By global, we mean that they are used - by more than one library or executable of your project. -

- By placing your header files in include, they will be - found automatically by the LLVM build system. For example, if - you have a file include/jazz/note.h, then your source - files can include it simply with #include "jazz/note.h". - -

tools -
- This subdirectory should contain all of your source - code for executables. For each program that you build, you - will have one directory in tools that will contain that - program's source code. -

- -

test -
- This subdirectory should contain tests that verify that your code - works correctly. Automated tests are especially useful. -

- Currently, the LLVM build system provides basic support for tests. - The LLVM system provides the following: -

    -
  • - LLVM provides a tcl procedure that is used by Dejagnu to run - tests. It can be found in llvm/lib/llvm-dg.exp. This - test procedure uses RUN lines in the actual test case to determine - how to run the test. See the TestingGuide for more details. You - can easily write Makefile support similar to the Makefiles in - llvm/test to use Dejagnu to run your project's tests.
  • -
  • - LLVM contains an optional package called llvm-test - which provides benchmarks and programs that are known to compile with the - LLVM GCC front ends. You can use these - programs to test your code, gather statistics information, and - compare it to the current LLVM performance statistics. -
    Currently, there is no way to hook your tests directly into the - llvm/test testing harness. You will simply - need to find a way to use the source provided within that directory - on your own. -
-
- -

Typically, you will want to build your lib directory first followed by -your tools directory.

- -
- - -

- Writing LLVM Style Makefiles -

- - -
- -

The LLVM build system provides a convenient way to build libraries and -executables. Most of your project Makefiles will only need to define a few -variables. Below is a list of the variables one can set and what they can -do:

- - -

- Required Variables -

- -
- -
-
LEVEL -
- This variable is the relative path from this Makefile to the - top directory of your project's source code. For example, if - your source code is in /tmp/src, then the Makefile in - /tmp/src/jump/high would set LEVEL to "../..". -
- -
- - -

- Variables for Building Subdirectories -

- -
- -
-
DIRS -
- This is a space separated list of subdirectories that should be - built. They will be built, one at a time, in the order - specified. -

- -

PARALLEL_DIRS -
- This is a list of directories that can be built in parallel. - These will be built after the directories in DIRS have been - built. -

- -

OPTIONAL_DIRS -
- This is a list of directories that can be built if they exist, - but will not cause an error if they do not exist. They are - built serially in the order in which they are listed. -
- -
- - -

- Variables for Building Libraries -

- -
- -
-
LIBRARYNAME -
- This variable contains the base name of the library that will - be built. For example, to build a library named - libsample.a, LIBRARYNAME should be set to - sample. -

- -

BUILD_ARCHIVE -
- By default, a library is a .o file that is linked - directly into a program. To build an archive (also known as - a static library), set the BUILD_ARCHIVE variable. -

- -

SHARED_LIBRARY -
- If SHARED_LIBRARY is defined in your Makefile, a shared - (or dynamic) library will be built. -
- -
- - -

- Variables for Building Programs -

- -
- -
-
TOOLNAME -
- This variable contains the name of the program that will - be built. For example, to build an executable named - sample, TOOLNAME should be set to sample. -

- -

USEDLIBS -
- This variable holds a space separated list of libraries that should - be linked into the program. These libraries must be libraries that - come from your lib directory. The libraries must be - specified without their "lib" prefix. For example, to link - libsample.a, you would set USEDLIBS to - sample.a. -

- Note that this works only for statically linked libraries. -

- -

LLVMLIBS -
- This variable holds a space separated list of libraries that should - be linked into the program. These libraries must be LLVM libraries. - The libraries must be specified without their "lib" prefix. For - example, to link with a driver that performs an IR transformation - you might set LLVMLIBS to this minimal set of libraries - LLVMSupport.a LLVMCore.a LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a LLVMScalarOpts.a LLVMTarget.a. -

- Note that this works only for statically linked libraries. LLVM is - split into a large number of static libraries, and the list of libraries you - require may be much longer than the list above. To see a full list - of libraries use: - llvm-config --libs all. - Using LINK_COMPONENTS as described below, obviates the need to set LLVMLIBS. -

- -

LINK_COMPONENTS -
This variable holds a space separated list of components that - the LLVM Makefiles pass to the llvm-config tool to generate - a link line for the program. For example, to link with all LLVM - libraries use - LINK_COMPONENTS = all. -

- -

LIBS -
- To link dynamic libraries, add -l<library base name> to - the LIBS variable. The LLVM build system will look in the same places - for dynamic libraries as it does for static libraries. -

- For example, to link libsample.so, you would have the - following line in your Makefile: -

- - LIBS += -lsample - -

- Note that LIBS must occur in the Makefile after the inclusion of Makefile.common. -

-

- -
- - -

- Miscellaneous Variables -

- -
- -
-
ExtraSource -
- This variable contains a space separated list of extra source - files that need to be built. It is useful for including the - output of Lex and Yacc programs. -

- -

CFLAGS -
CPPFLAGS -
- This variable can be used to add options to the C and C++ - compiler, respectively. It is typically used to add options - that tell the compiler the location of additional directories - to search for header files. -

- It is highly suggested that you append to CFLAGS and CPPFLAGS as - opposed to overwriting them. The master Makefiles may already - have useful options in them that you may not want to overwrite. -

-

- -
- -
- - -

- Placement of Object Code -

- - -
- -

The final location of built libraries and executables will depend upon -whether you do a Debug, Release, or Profile build.

- -
-
Libraries -
- All libraries (static and dynamic) will be stored in - PROJ_OBJ_ROOT/<type>/lib, where type is Debug, - Release, or Profile for a debug, optimized, or - profiled build, respectively.

- -

Executables -
All executables will be stored in - PROJ_OBJ_ROOT/<type>/bin, where type is Debug, - Release, or Profile for a debug, optimized, or profiled - build, respectively. -
- -
- - -

- Further Help -

- - -
- -

If you have any questions or need any help creating an LLVM project, -the LLVM team would be more than happy to help. You can always post your -questions to the LLVM Developers -Mailing List.

- -
- - -
-
- Valid CSS - Valid HTML 4.01 - - John Criswell
- The LLVM Compiler Infrastructure -
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - - diff --git a/cpp/llvm/docs/ReleaseNotes.html b/cpp/llvm/docs/ReleaseNotes.html deleted file mode 100644 index eb58a1ef..00000000 --- a/cpp/llvm/docs/ReleaseNotes.html +++ /dev/null @@ -1,897 +0,0 @@ - - - - - - LLVM 3.1 Release Notes - - - -

LLVM 3.1 Release Notes

- -
-LLVM Dragon Logo -
- -
    -
  1. Introduction
  2. -
  3. Sub-project Status Update
  4. -
  5. External Projects Using LLVM 3.1
  6. -
  7. What's New in LLVM?
  8. -
  9. Installation Instructions
  10. -
  11. Known Problems
  12. -
  13. Additional Information
  14. -
- -
-

Written by the LLVM Team

-
- - -

- Introduction -

- - -
- -

This document contains the release notes for the LLVM Compiler - Infrastructure, release 3.1. Here we describe the status of LLVM, including - major improvements from the previous release, improvements in various - subprojects of LLVM, and some of the current users of the code. - All LLVM releases may be downloaded from - the LLVM releases web site.

- -

For more information about LLVM, including information about the latest - release, please check out the main LLVM web - site. If you have questions or comments, - the LLVM - Developer's Mailing List is a good place to send them.

- -

Note that if you are reading this file from a Subversion checkout or the main - LLVM web page, this document applies to the next release, not the - current one. To see the release notes for a specific release, please see the - releases page.

- -
- - - -

- Sub-project Status Update -

- - -
- -

The LLVM 3.1 distribution currently consists of code from the core LLVM - repository (which roughly includes the LLVM optimizers, code generators and - supporting tools), and the Clang repository. In addition to this code, the - LLVM Project includes other sub-projects that are in development. Here we - include updates on these subprojects.

- - -

-Clang: C/C++/Objective-C Frontend Toolkit -

- -
- -

Clang is an LLVM front end for the C, - C++, and Objective-C languages. Clang aims to provide a better user - experience through expressive diagnostics, a high level of conformance to - language standards, fast compilation, and low memory use. Like LLVM, Clang - provides a modular, library-based architecture that makes it suitable for - creating or integrating with other development tools. Clang is considered a - production-quality compiler for C, Objective-C, C++ and Objective-C++ on x86 - (32- and 64-bit), and for Darwin/ARM targets.

- -

In the LLVM 3.1 time-frame, the Clang team has made many improvements. - Highlights include:

-
    -
  • Greatly expanded C++11 - support including lambdas, initializer lists, constexpr, user-defined - literals, and atomics.
  • -
  • A new tooling - library to ease building of clang-based standalone tools.
  • -
  • Extended support for - literals in - Objective C.
  • -
- -

For more details about the changes to Clang since the 3.0 release, see the - Clang release - notes.

- -

If Clang rejects your code but another compiler accepts it, please take a - look at the language - compatibility guide to make sure this is not intentional or a known - issue.

- -
- - -

-DragonEgg: GCC front-ends, LLVM back-end -

- -
- -

DragonEgg is a - gcc plugin that replaces GCC's - optimizers and code generators with LLVM's. It works with gcc-4.5 and gcc-4.6 - (and partially with gcc-4.7), can target the x86-32/x86-64 and ARM processor - families, and has been successfully used on the Darwin, FreeBSD, KFreeBSD, - Linux and OpenBSD platforms. It fully supports Ada, C, C++ and Fortran. It - has partial support for Go, Java, Obj-C and Obj-C++.

- -

The 3.1 release has the following notable changes:

- -
    -
  • Partial support for gcc-4.7. Ada support is poor, but other languages work - fairly well.
  • - -
  • Support for ARM processors. Some essential gcc headers that are needed to - build DragonEgg for ARM are not installed by gcc. To work around this, - copy the missing headers from the gcc source tree.
  • - -
  • Better optimization for Fortran by exploiting the fact that Fortran scalar - arguments have 'restrict' semantics.
  • - -
  • Better optimization for all languages by passing information about type - aliasing and type ranges to the LLVM optimizers.
  • - -
  • A regression test-suite was added.
  • -
- -
- - -

-compiler-rt: Compiler Runtime Library -

- -
- -

The new LLVM compiler-rt project - is a simple library that provides an implementation of the low-level - target-specific hooks required by code generation and other runtime - components. For example, when compiling for a 32-bit target, converting a - double to a 64-bit unsigned integer is compiled into a runtime call to the - "__fixunsdfdi" function. The compiler-rt library provides highly optimized - implementations of this and other low-level routines (some are 3x faster than - the equivalent libgcc routines).

- -

As of 3.1, compiler-rt includes the helper functions for atomic operations, - allowing atomic operations on arbitrary-sized quantities to work. These - functions follow the specification defined by gcc and are used by clang.

- -
- - -

-LLDB: Low Level Debugger -

- -
- -

LLDB is a ground-up implementation of a - command line debugger, as well as a debugger API that can be used from other - applications. LLDB makes use of the Clang parser to provide high-fidelity - expression parsing (particularly for C++) and uses the LLVM JIT for target - support.

- -
- - -

-libc++: C++ Standard Library -

- -
- -

Like compiler_rt, libc++ is now dual - licensed under the MIT and UIUC license, allowing it to be used more - permissively.

- -

Within the LLVM 3.1 time-frame there were the following highlights:

- -
    -
  • The <atomic> header is now passing all tests, when - compiling with clang and linking against the support code from - compiler-rt.
  • -
  • FreeBSD now includes libc++ as part of the base system.
  • -
  • libc++ has been ported to Solaris and, in combination with libcxxrt and - clang, is working with a large body of existing code.
  • -
- -
- - -

-VMKit -

- -
- -

The VMKit project is an implementation - of a Java Virtual Machine (Java VM or JVM) that uses LLVM for static and - just-in-time compilation.

- -

In the LLVM 3.1 time-frame, VMKit has had significant improvements on both - runtime and startup performance.

- -
- - - -

-Polly: Polyhedral Optimizer -

- -
- -

Polly is an experimental - optimizer for data locality and parallelism. It currently provides high-level - loop optimizations and automatic parallelisation (using the OpenMP run time). - Work in the area of automatic SIMD and accelerator code generation was - started.

- -

Within the LLVM 3.1 time-frame there were the following highlights:

- -
    -
  • Polly became an official LLVM project
  • -
  • Polly can be loaded directly into clang (enabled by '-O3 -mllvm -polly')
  • -
  • An automatic scheduling optimizer (derived - from Pluto) was - integrated. It performs loop transformations to optimize for data-locality - and parallelism. The transformations include, but are not limited to - interchange, fusion, fission, skewing and tiling.
  • -
- -
- -
- - -

- External Open Source Projects Using LLVM 3.1 -

- - -
- -

An exciting aspect of LLVM is that it is used as an enabling technology for - a lot of other language and tools projects. This section lists some of the - projects that have already been updated to work with LLVM 3.1.

- -

Crack

- -
- -

Crack aims to provide - the ease of development of a scripting language with the performance of a - compiled language. The language derives concepts from C++, Java and Python, - incorporating object-oriented programming, operator overloading and strong - typing.

- -
- -

FAUST

- -
- -

FAUST is a compiled language for - real-time audio signal processing. The name FAUST stands for Functional - AUdio STream. Its programming model combines two approaches: functional - programming and block diagram composition. In addition with the C, C++, Java, - JavaScript output formats, the Faust compiler can generate LLVM bitcode, and - works with LLVM 2.7-3.1.

- -
- -

Glasgow Haskell Compiler (GHC)

- -
- -

GHC is an open source compiler and - programming suite for Haskell, a lazy functional programming language. It - includes an optimizing static compiler generating good code for a variety of - platforms, together with an interactive system for convenient, quick - development.

- -

GHC 7.0 and onwards include an LLVM code generator, supporting LLVM 2.8 and - later.

- -
- -

Julia

- -
- -

Julia is a high-level, - high-performance dynamic language for technical computing. It provides a - sophisticated compiler, distributed parallel execution, numerical accuracy, - and an extensive mathematical function library. The compiler uses type - inference to generate fast code without any type declarations, and uses - LLVM's optimization passes and JIT compiler. The - Julia Language is designed - around multiple dispatch, giving programs a large degree of flexibility. It - is ready for use on many kinds of problems.

- -
- -

LLVM D Compiler

- -
- -

LLVM D Compiler (LDC) is - a compiler for the D programming Language. It is based on the DMD frontend - and uses LLVM as backend.

- -
- -

Open Shading Language

- -
- -

Open Shading - Language (OSL) is a small but rich language for programmable shading in - advanced global illumination renderers and other applications, ideal for - describing materials, lights, displacement, and pattern generation. It uses - LLVM to JIT complex shader networks to x86 code at runtime.

- -

OSL was developed by Sony Pictures Imageworks for use in its in-house - renderer used for feature film animation and visual effects, and is - distributed as open source software with the "New BSD" license.

- -
- -

Portable OpenCL (pocl)

- -
- -

In addition to producing an easily portable open source OpenCL - implementation, another major goal of - pocl is improving performance portability of OpenCL programs with - compiler optimizations, reducing the need for target-dependent manual - optimizations. An important part of pocl is a set of LLVM passes used to - statically parallelize multiple work-items with the kernel compiler, even in - the presence of work-group barriers. This enables static parallelization of - the fine-grained static concurrency in the work groups in multiple ways - (SIMD, VLIW, superscalar,...).

- -
- -

Pure

- -
- -

Pure is an - algebraic/functional programming language based on term rewriting. Programs - are collections of equations which are used to evaluate expressions in a - symbolic fashion. The interpreter uses LLVM as a backend to JIT-compile Pure - programs to fast native code. Pure offers dynamic typing, eager and lazy - evaluation, lexical closures, a hygienic macro system (also based on term - rewriting), built-in list and matrix support (including list and matrix - comprehensions) and an easy-to-use interface to C and other programming - languages (including the ability to load LLVM bitcode modules, and inline C, - C++, Fortran and Faust code in Pure programs if the corresponding - LLVM-enabled compilers are installed).

- -

Pure version 0.54 has been tested and is known to work with LLVM 3.1 (and - continues to work with older LLVM releases >= 2.5).

- -
- -

TTA-based Co-design Environment (TCE)

- -
- -

TCE is a toolset for designing - application-specific processors (ASP) based on the Transport triggered - architecture (TTA). The toolset provides a complete co-design flow from C/C++ - programs down to synthesizable VHDL/Verilog and parallel program binaries. - Processor customization points include the register files, function units, - supported operations, and the interconnection network.

- -

TCE uses Clang and LLVM for C/C++ language support, target independent - optimizations and also for parts of code generation. It generates new - LLVM-based code generators "on the fly" for the designed TTA processors and - loads them in to the compiler backend as runtime libraries to avoid - per-target recompilation of larger parts of the compiler chain.

- -
- -
- - -

- What's New in LLVM 3.1? -

- - -
- -

This release includes a huge number of bug fixes, performance tweaks and - minor improvements. Some of the major improvements and new features are - listed in this section.

- - -

-Major New Features -

- -
- - - - - -

LLVM 3.1 includes several major changes and big features:

- - - -
- - - -

-LLVM IR and Core Improvements -

- -
- -

LLVM IR has several new features for better support of new targets and that - expose new optimization opportunities:

- -
    -
  • A new type representing 16 bit half floating point values has - been added.
  • -
  • IR now supports vectors of pointers, including vector GEPs.
  • -
  • Module flags have been introduced. They convey information about the - module as a whole to LLVM subsystems. This is currently used to encode - Objective C ABI information.
  • -
  • Loads can now have range metadata attached to them to describe the - possible values being loaded.
  • -
  • The llvm.ctlz and llvm.cttz intrinsics now have an - additional argument which indicates whether the behavior of the intrinsic - is undefined on a zero input. This can be used to generate more efficient - code on platforms that only have instructions which don't return the type - size when counting bits in 0.
  • -
- -
- - -

-Optimizer Improvements -

- -
- -

In addition to many minor performance tweaks and bug fixes, this - release includes a few major enhancements and additions to the - optimizers:

- -
    -
  • The loop unroll pass now is able to unroll loops with run-time trip counts. - This feature is turned off by default, and is enabled with the - -unroll-runtime flag.
  • -
  • A new basic-block autovectorization pass is available. Pass - -vectorize to run this pass along with some associated - post-vectorization cleanup passes. For more information, see the EuroLLVM - 2012 slides: - Autovectorization with LLVM.
  • -
  • Inline cost heuristics have been completely overhauled and now closely - model constant propagation through call sites, disregard trivially dead - code costs, and can model C++ STL iterator patterns.
  • -
- -
- - -

-MC Level Improvements -

- -
- -

The LLVM Machine Code (aka MC) subsystem was created to solve a number of - problems in the realm of assembly, disassembly, object file format handling, - and a number of other related areas that CPU instruction-set level tools work - in. For more information, please see - the Intro - to the LLVM MC Project Blog Post.

- -
    -
  • The integrated assembler can optionally emit debug information when - assembling a .s file. It can be enabled by passing the - -g option to llvm-mc.
  • -
- -
- - -

-Target Independent Code Generator Improvements -

- -
- -

We have changed the way that the Type Legalizer legalizes vectors. The type - legalizer now attempts to promote integer elements. This enabled the - implementation of vector-select. Additionally, we see a performance boost on - workloads which use vectors of chars and shorts, since they are now promoted - to 32-bit types, which are better supported by the SIMD instruction set. - Floating point types are still widened as before.

- - -

We have put a significant amount of work into the code generator - infrastructure, which allows us to implement more aggressive algorithms and - make it run faster:

- -
    -
  • TableGen can now synthesize register classes that are only needed to - represent combinations of constraints from instructions and sub-registers. - The synthetic register classes inherit most of their properties form their - closest user-defined super-class.
  • -
  • MachineRegisterInfo now allows the reserved registers to be - frozen when register allocation starts. Target hooks should use the - MRI->canReserveReg(FramePtr) method to avoid accidentally - disabling frame pointer elimination during register allocation.
  • -
  • A new kind of MachineOperand provides a compact - representation of large clobber lists on call instructions. The register - mask operand references a bit mask of preserved registers. Everything else - is clobbered.
  • -
  • The DWARF debug info writer gained support for emitting data for the - name accelerator tables - DWARF extension. It is used by LLDB to speed up name lookup.
  • -
- -

We added new TableGen infrastructure to support bundling for - Very Long Instruction Word (VLIW) architectures. TableGen can now - automatically generate a deterministic finite automaton from a VLIW - target's schedule description which can be queried to determine - legal groupings of instructions in a bundle.

- -

We have added a new target independent VLIW packetizer based on the - DFA infrastructure to group machine instructions into bundles.

- -
- -

-Basic Block Placement -

-
-

A probability based block placement and code layout algorithm was added to -LLVM's code generator. This layout pass supports probabilities derived from -static heuristics as well as source code annotations such as -__builtin_expect.

-
- - -

-X86-32 and X86-64 Target Improvements -

- -
- -

New features and major changes in the X86 target include:

- -
    -
  • Greatly improved support for AVX2.
  • -
  • Lots of bug fixes and improvements for AVX1.
  • -
  • Support for the FMA4 and XOP instruction set extensions.
  • -
  • Call instructions use the new register mask operands for faster compile - times and better support for different calling conventions. The old WINCALL - instructions are no longer needed.
  • -
  • DW2 Exception Handling is enabled on Cygwin and MinGW.
  • -
  • Support for implicit TLS model used with MSVC runtime.
  • -
- -
- - -

-ARM Target Improvements -

- -
- -

New features of the ARM target include:

- -
    -
  • The constant island pass now supports basic block and constant pool entry - alignments greater than 4 bytes.
  • -
  • On Darwin, the ARM target now has a full-featured integrated assembler. -
  • -
- -

-ARM Integrated Assembler -

-
-

The ARM target now includes a full featured macro assembler, including -direct-to-object module support for clang. The assembler is currently enabled -by default for Darwin only pending testing and any additional necessary -platform specific support for Linux.

- -

Full support is included for Thumb1, Thumb2 and ARM modes, along with -subtarget and CPU specific extensions for VFP2, VFP3 and NEON.

- -

The assembler is Unified Syntax only (see ARM Architecural Reference Manual -for details). While there is some, and growing, support for pre-unfied (divided) -syntax, there are still significant gaps in that support.

-
- -
- -

-MIPS Target Improvements -

- -
-New features and major changes in the MIPS target include:

- -
    -
  • MIPS32 little-endian direct object code emission is functional.
  • -
  • MIPS64 little-endian code generation is largely functional for N64 ABI in assembly printing mode with the exception of handling of long double (f128) type.
  • -
  • Support for new instructions has been added, which includes swap-bytes - instructions (WSBH and DSBH), floating point multiply-add/subtract and - negative multiply-add/subtract instructions, and floating - point load/store instructions with reg+reg addressing (LWXC1, etc.)
  • -
  • Various fixes to improve performance have been implemented.
  • -
  • Post-RA scheduling is now enabled at -O3.
  • -
  • Support for soft-float code generation has been added.
  • -
  • clang driver's support for MIPS 64-bits targets.
  • -
  • Support for MIPS floating point ABI option in clang driver.
  • -
-
- - -

-PTX Target Improvements -

- -
- -

An outstanding conditional inversion bug was fixed in this release.

- -

NOTE: LLVM 3.1 marks the last release of the PTX back-end, in its - current form. The back-end is currently being replaced by the NVPTX - back-end, currently in SVN ToT.

- -
- - -

-Other Target Specific Improvements -

- -
- -
    -
  • Support for Qualcomm's Hexagon VLIW processor has been added.
  • -
- -
- - -

-Major Changes and Removed Features -

- -
- -

If you're already an LLVM user or developer with out-of-tree changes based on - LLVM 3.1, this section lists some "gotchas" that you may run into upgrading - from the previous release.

- -
    -
  • LLVM's build system now requires a python 2 interpreter to be present at - build time. A perl interpreter is no longer required.
  • -
  • The C backend has been removed. It had numerous problems, to the point of - not being able to compile any nontrivial program.
  • -
  • The Alpha, Blackfin and SystemZ targets have been removed due to lack of - maintenance.
  • -
  • LLVM 3.1 removes support for reading LLVM 2.9 bitcode files. Going - forward, we aim for all future versions of LLVM to read bitcode files and - .ll files produced by LLVM 3.0 and later.
  • -
  • The unwind instruction is now gone. With the introduction of the - new exception handling system in LLVM 3.0, the unwind instruction - became obsolete.
  • -
  • LLVM 3.0 and earlier automatically added the returns_twice fo functions - like setjmp based on the name. This functionality was removed in 3.1. - This affects Clang users, if -ffreestanding is used.
  • -
- -
- - -

-Internal API Changes -

- -
- -

In addition, many APIs have changed in this release. Some of the major - LLVM API changes are:

- -
    -
  • Target specific options have been moved from global variables to members - on the new TargetOptions class, which is local to each - TargetMachine. As a consequence, the associated flags will - no longer be accepted by clang -mllvm. This includes: -
      -
    • llvm::PrintMachineCode
    • -
    • llvm::NoFramePointerElim
    • -
    • llvm::NoFramePointerElimNonLeaf
    • -
    • llvm::DisableFramePointerElim(const MachineFunction &)
    • -
    • llvm::LessPreciseFPMADOption
    • -
    • llvm::LessPrecideFPMAD()
    • -
    • llvm::NoExcessFPPrecision
    • -
    • llvm::UnsafeFPMath
    • -
    • llvm::NoInfsFPMath
    • -
    • llvm::NoNaNsFPMath
    • -
    • llvm::HonorSignDependentRoundingFPMathOption
    • -
    • llvm::HonorSignDependentRoundingFPMath()
    • -
    • llvm::UseSoftFloat
    • -
    • llvm::FloatABIType
    • -
    • llvm::NoZerosInBSS
    • -
    • llvm::JITExceptionHandling
    • -
    • llvm::JITEmitDebugInfo
    • -
    • llvm::JITEmitDebugInfoToDisk
    • -
    • llvm::GuaranteedTailCallOpt
    • -
    • llvm::StackAlignmentOverride
    • -
    • llvm::RealignStack
    • -
    • llvm::DisableJumpTables
    • -
    • llvm::EnableFastISel
    • -
    • llvm::getTrapFunctionName()
    • -
    • llvm::EnableSegmentedStacks
    • -
  • - -
  • The MDBuilder class has been added to simplify the creation - of metadata.
  • -
- -
- - -

-Tools Changes -

- -
- -

In addition, some tools have changed in this release. Some of the changes - are:

- - -
    -
  • llvm-stress is a command line tool for generating random - .ll files to fuzz different LLVM components.
  • -
  • The llvm-ld tool has been removed. The clang driver provides a - more reliable solution for turning a set of bitcode files into a binary. - To merge bitcode files llvm-link can be used instead.
  • -
- -
- - - -

-Python Bindings -

- -
- -

Officially supported Python bindings have been added! Feature support is far -from complete. The current bindings support interfaces to:

-
    -
  • Object File Interface
  • -
  • Disassembler
  • -
- -

Using the Object File Interface, it is possible to inspect binary object files. -Think of it as a Python version of readelf or llvm-objdump.

- -

Support for additional features is currently being developed by community -contributors. If you are interested in shaping the direction of the Python -bindings, please express your intent on IRC or the developers list.

- -
- -
- - -

- Known Problems -

- - -
- -

LLVM is generally a production quality compiler, and is used by a broad range - of applications and shipping in many products. That said, not every - subsystem is as mature as the aggregate, particularly the more obscure - targets. If you run into a problem, please check the LLVM bug database and submit a bug if - there isn't already one or ask on the LLVMdev - list.

- -

Known problem areas include:

- -
    -
  • The CellSPU, MSP430, PTX and XCore backends are experimental.
  • - -
  • The integrated assembler, disassembler, and JIT is not supported by - several targets. If an integrated assembler is not supported, then a - system assembler is required. For more details, see the Target Features Matrix. -
  • -
- -
- - -

- Additional Information -

- - -
- -

A wide variety of additional information is available on - the LLVM web page, in particular in - the documentation section. The web page - also contains versions of the API documentation which is up-to-date with the - Subversion version of the source code. You can access versions of these - documents specific to this release by going into the "llvm/doc/" - directory in the LLVM tree.

- -

If you have any questions or comments about LLVM, please feel free to contact - us via the mailing lists.

- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2012-05-15 14:58:06 -0700 (Tue, 15 May 2012) $ -
- - - diff --git a/cpp/llvm/docs/SegmentedStacks.html b/cpp/llvm/docs/SegmentedStacks.html deleted file mode 100644 index 16f55074..00000000 --- a/cpp/llvm/docs/SegmentedStacks.html +++ /dev/null @@ -1,93 +0,0 @@ - - - - Segmented Stacks in LLVM - - - - - -

Segmented Stacks in LLVM

-
-

Written by Sanjoy Das

-
- -
    -
  1. Introduction
  2. -
  3. Implementation Details -
      -
    1. Allocating Stacklets
    2. -
    3. Variable Sized Allocas
    4. -
    -
  4. -
- -

Introduction

-
-

- Segmented stack allows stack space to be allocated incrementally than as a monolithic chunk (of some worst case size) at thread initialization. This is done by allocating stack blocks (henceforth called stacklets) and linking them into a doubly linked list. The function prologue is responsible for checking if the current stacklet has enough space for the function to execute; and if not, call into the libgcc runtime to allocate more stack space. When using llc, segmented stacks can be enabled by adding -segmented-stacks to the command line. -

-

- The runtime functionality is already there in libgcc. -

-
- -

Implementation Details

-
-

Allocating Stacklets

-
-

- As mentioned above, the function prologue checks if the current stacklet has enough space. The current approach is to use a slot in the TCB to store the current stack limit (minus the amount of space needed to allocate a new block) - this slot's offset is again dictated by libgcc. The generated assembly looks like this on x86-64: -

-
-	          leaq	-8(%rsp), %r10
-	          cmpq	%fs:112,  %r10
-	          jg	.LBB0_2
-
-            # More stack space needs to be allocated
-	          movabsq	$8, %r10 # The amount of space needed
-	          movabsq	$0, %r11 # The total size of arguments passed on stack
-	          callq	__morestack
-	          ret # The reason for this extra return is explained below
-            .LBB0_2:
-            # Usual prologue continues here
-            
-

- The size of function arguments on the stack needs to be passed to __morestack (this function is implemented in libgcc) since that number of bytes has to be copied from the previous stacklet to the current one. This is so that SP (and FP) relative addressing of function arguments work as expected. -

-

- The unusual ret is needed to have the function which made a call to __morestack return correctly. __morestack, instead of returning, calls into .LBB0_2. This is possible since both, the size of the ret instruction and the PC of call to __morestack are known. When the function body returns, control is transferred back to __morestack. __morestack then de-allocates the new stacklet, restores the correct SP value, and does a second return, which returns control to the correct caller. -

-
- -

Variable Sized Allocas

-
-

- The section on allocating stacklets automatically assumes that every stack frame will be of fixed size. However, LLVM allows the use of the llvm.alloca intrinsic to allocate dynamically sized blocks of memory on the stack. When faced with such a variable-sized alloca, code is generated to -

-
    -
  • Check if the current stacklet has enough space. If yes, just bump the SP, like in the normal case.
  • -
  • If not, generate a call to libgcc, which allocates the memory from the heap.
  • -
-

- The memory allocated from the heap is linked into a list in the current stacklet, and freed along with the same. This prevents a memory leak. -

-
- -
- -
-
- - Valid CSS - - - Valid HTML 4.01 - - Sanjoy Das
- LLVM Compiler Infrastructure
- Last modified: $Date$ -
- - - diff --git a/cpp/llvm/docs/SourceLevelDebugging.html b/cpp/llvm/docs/SourceLevelDebugging.html deleted file mode 100644 index 630be370..00000000 --- a/cpp/llvm/docs/SourceLevelDebugging.html +++ /dev/null @@ -1,2862 +0,0 @@ - - - - - Source Level Debugging with LLVM - - - - -

Source Level Debugging with LLVM

- - - - - -
- - -A leafy and green bug eater -
- -
-

Written by Chris Lattner - and Jim Laskey

-
- - - -

Introduction

- - -
- -

This document is the central repository for all information pertaining to - debug information in LLVM. It describes the actual format - that the LLVM debug 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 debug information - for C/C++ looks like.

- - -

- Philosophy behind LLVM debugging information -

- -
- -

The idea of the LLVM debugging information is to capture how the important - pieces of the source-language's Abstract Syntax Tree map onto LLVM code. - Several design aspects have shaped the solution that appears here. The - important ones are:

- -
    -
  • Debugging information should have very little impact on the rest of the - compiler. No transformations, analyses, or code generators should need to - be modified because of debugging information.
  • - -
  • LLVM optimizations should interact in well-defined and - easily described ways with the debugging information.
  • - -
  • Because LLVM is designed to support arbitrary programming languages, - LLVM-to-LLVM tools should not need to know anything about the semantics of - the source-level-language.
  • - -
  • Source-level languages are often widely different from one another. - LLVM should not put any restrictions of the flavor of the source-language, - and the debugging information should work with any language.
  • - -
  • With code generator support, it should be possible to use an LLVM compiler - to compile a program to native machine code and standard debugging - formats. This allows compatibility with traditional machine-code level - debuggers, like GDB or DBX.
  • -
- -

The approach used by the LLVM implementation is to use a small set - of intrinsic functions to define a - mapping between LLVM program objects and the source-level objects. The - description of the source-level program is maintained in LLVM metadata - in an implementation-defined format - (the C/C++ front-end currently uses working draft 7 of - the DWARF 3 - standard).

- -

When a program is being debugged, a debugger interacts with the user and - turns the stored debug information into source-language specific information. - As such, a debugger must be aware of the source-language, and is thus tied to - a specific language or family of languages.

- -
- - -

- Debug information consumers -

- -
- -

The role of debug information is to provide meta information normally - stripped away during the compilation process. This meta information provides - an LLVM user a relationship between generated code and the original program - source code.

- -

Currently, debug information is consumed by DwarfDebug to produce dwarf - information used by the gdb debugger. Other targets could use the same - information to produce stabs or other debug forms.

- -

It would also be reasonable to use debug information to feed profiling tools - for analysis of generated code, or, tools for reconstructing the original - source from generated code.

- -

TODO - expound a bit more.

- -
- - -

- Debugging optimized code -

- -
- -

An extremely high priority of LLVM debugging information is to make it - interact well with optimizations and analysis. In particular, the LLVM debug - information provides the following guarantees:

- -
    -
  • LLVM debug information always provides information to accurately read - the source-level state of the program, regardless of which LLVM - optimizations have been run, and without any modification to the - optimizations themselves. However, some optimizations may impact the - ability to modify the current state of the program with a debugger, such - as setting program variables, or calling functions that have been - deleted.
  • - -
  • As desired, LLVM optimizations can be upgraded to be aware of the LLVM - debugging information, allowing them to update the debugging information - as they perform aggressive optimizations. This means that, with effort, - the LLVM optimizers could optimize debug code just as well as non-debug - code.
  • - -
  • LLVM debug information does not prevent optimizations from - happening (for example inlining, basic block reordering/merging/cleanup, - tail duplication, etc).
  • - -
  • LLVM debug information is automatically optimized along with the rest of - the program, using existing facilities. For example, duplicate - information is automatically merged by the linker, and unused information - is automatically removed.
  • -
- -

Basically, the debug information allows you to compile a program with - "-O0 -g" and get full debug information, allowing you to arbitrarily - modify the program as it executes from a debugger. Compiling a program with - "-O3 -g" gives you full debug information that is always available - and accurate for reading (e.g., you get accurate stack traces despite tail - call elimination and inlining), but you might lose the ability to modify the - program and call functions where were optimized out of the program, or - inlined away completely.

- -

LLVM test suite provides a - framework to test optimizer's handling of debugging information. It can be - run like this:

- -
-
-% cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
-% make TEST=dbgopt
-
-
- -

This will test impact of debugging information on optimization passes. If - debugging information influences optimization passes then it will be reported - as a failure. See TestingGuide for more - information on LLVM test infrastructure and how to run various tests.

- -
- -
- - -

- Debugging information format -

- - -
- -

LLVM debugging information has been carefully designed to make it possible - for the optimizer to optimize the program and debugging information without - necessarily having to know anything about debugging information. In - particular, the use of metadata avoids duplicated debugging information from - the beginning, and the global dead code elimination pass automatically - deletes debugging information for a function if it decides to delete the - function.

- -

To do this, most of the debugging information (descriptors for types, - variables, functions, source files, etc) is inserted by the language - front-end in the form of LLVM metadata.

- -

Debug information is designed to be agnostic about the target debugger and - debugging information representation (e.g. DWARF/Stabs/etc). It uses a - generic pass to decode the information that represents variables, types, - functions, namespaces, etc: this allows for arbitrary source-language - semantics and type-systems to be used, as long as there is a module - written for the target debugger to interpret the information.

- -

To provide basic functionality, the LLVM debugger does have to make some - assumptions about the source-level language being debugged, though it keeps - these to a minimum. The only common features that the LLVM debugger assumes - exist are source files, - and program objects. These abstract - objects are used by a debugger to form stack traces, show information about - local variables, etc.

- -

This section of the documentation first describes the representation aspects - common to any source-language. The next section - describes the data layout conventions used by the C and C++ front-ends.

- - -

- Debug information descriptors -

- -
- -

In consideration of the complexity and volume of debug information, LLVM - provides a specification for well formed debug descriptors.

- -

Consumers of LLVM debug information expect the descriptors for program - objects to start in a canonical format, but the descriptors can include - additional information appended at the end that is source-language - specific. All LLVM debugging information is versioned, allowing backwards - compatibility in the case that the core structures need to change in some - way. Also, all debugging information objects start with a tag to indicate - what type of object it is. The source-language is allowed to define its own - objects, by using unreserved tag numbers. We recommend using with tags in - the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base = - 0x1000.)

- -

The fields of debug descriptors used internally by LLVM - are restricted to only the simple data types i32, i1, - float, double, mdstring and mdnode.

- -
-
-!1 = metadata !{
-  i32,   ;; A tag
-  ...
-}
-
-
- -

The first field of a descriptor is always an - i32 containing a tag value identifying the content of the - descriptor. The remaining fields are specific to the descriptor. The values - of tags are loosely bound to the tag values of DWARF information entries. - However, that does not restrict the use of the information supplied to DWARF - targets. To facilitate versioning of debug information, the tag is augmented - with the current debug version (LLVMDebugVersion = 8 << 16 or - 0x80000 or 524288.)

- -

The details of the various descriptors follow.

- - -

- Compile unit descriptors -

- -
- -
-
-!0 = metadata !{
-  i32,       ;; Tag = 17 + LLVMDebugVersion
-             ;; (DW_TAG_compile_unit)
-  i32,       ;; Unused field.
-  i32,       ;; DWARF language identifier (ex. DW_LANG_C89)
-  metadata,  ;; Source file name
-  metadata,  ;; Source file directory (includes trailing slash)
-  metadata   ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
-  i1,        ;; True if this is a main compile unit.
-  i1,        ;; True if this is optimized.
-  metadata,  ;; Flags
-  i32        ;; Runtime version
-  metadata   ;; List of enums types
-  metadata   ;; List of retained types
-  metadata   ;; List of subprograms
-  metadata   ;; List of global variables
-}
-
-
- -

These descriptors contain a source language ID for the file (we use the DWARF - 3.0 ID numbers, such as DW_LANG_C89, DW_LANG_C_plus_plus, - DW_LANG_Cobol74, etc), three strings describing the filename, - working directory of the compiler, and an identifier string for the compiler - that produced it.

- -

Compile unit descriptors provide the root context for objects declared in a - specific compilation unit. File descriptors are defined using this context. - These descriptors are collected by a named metadata - !llvm.dbg.cu. Compile unit descriptor keeps track of subprograms, - global variables and type information. - -

- - -

- File descriptors -

- -
- -
-
-!0 = metadata !{
-  i32,       ;; Tag = 41 + LLVMDebugVersion
-             ;; (DW_TAG_file_type)
-  metadata,  ;; Source file name
-  metadata,  ;; Source file directory (includes trailing slash)
-  metadata   ;; Unused
-}
-
-
- -

These descriptors contain information for a file. Global variables and top - level functions would be defined using this context.k File descriptors also - provide context for source line correspondence.

- -

Each input file is encoded as a separate file descriptor in LLVM debugging - information output.

- -
- - -

- Global variable descriptors -

- -
- -
-
-!1 = metadata !{
-  i32,      ;; Tag = 52 + LLVMDebugVersion
-            ;; (DW_TAG_variable)
-  i32,      ;; Unused field.
-  metadata, ;; Reference to context descriptor
-  metadata, ;; Name
-  metadata, ;; Display name (fully qualified C++ name)
-  metadata, ;; MIPS linkage name (for C++)
-  metadata, ;; Reference to file where defined
-  i32,      ;; Line number where defined
-  metadata, ;; Reference to type descriptor
-  i1,       ;; True if the global is local to compile unit (static)
-  i1,       ;; True if the global is defined in the compile unit (not extern)
-  {}*       ;; Reference to the global variable
-}
-
-
- -

These descriptors provide debug information about globals variables. The -provide details such as name, type and where the variable is defined. All -global variables are collected inside the named metadata -!llvm.dbg.cu.

- -
- - -

- Subprogram descriptors -

- -
- -
-
-!2 = metadata !{
-  i32,      ;; Tag = 46 + LLVMDebugVersion
-            ;; (DW_TAG_subprogram)
-  i32,      ;; Unused field.
-  metadata, ;; Reference to context descriptor
-  metadata, ;; Name
-  metadata, ;; Display name (fully qualified C++ name)
-  metadata, ;; MIPS linkage name (for C++)
-  metadata, ;; Reference to file where defined
-  i32,      ;; Line number where defined
-  metadata, ;; Reference to type descriptor
-  i1,       ;; True if the global is local to compile unit (static)
-  i1,       ;; True if the global is defined in the compile unit (not extern)
-  i32,      ;; Line number where the scope of the subprogram begins
-  i32,      ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
-  i32,      ;; Index into a virtual function
-  metadata, ;; indicates which base type contains the vtable pointer for the
-            ;; derived class
-  i32,      ;; Flags - Artifical, Private, Protected, Explicit, Prototyped.
-  i1,       ;; isOptimized
-  Function *,;; Pointer to LLVM function
-  metadata, ;; Lists function template parameters
-  metadata  ;; Function declaration descriptor
-  metadata  ;; List of function variables
-}
-
-
- -

These descriptors provide debug information about functions, methods and - subprograms. They provide details such as name, return types and the source - location where the subprogram is defined. -

- -
- - -

- Block descriptors -

- -
- -
-
-!3 = metadata !{
-  i32,     ;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block)
-  metadata,;; Reference to context descriptor
-  i32,     ;; Line number
-  i32,     ;; Column number
-  metadata,;; Reference to source file
-  i32      ;; Unique ID to identify blocks from a template function
-}
-
-
- -

This descriptor provides debug information about nested blocks within a - subprogram. The line number and column numbers are used to dinstinguish - two lexical blocks at same depth.

- -
-
-!3 = metadata !{
-  i32,     ;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block)
-  metadata ;; Reference to the scope we're annotating with a file change
-  metadata,;; Reference to the file the scope is enclosed in.
-}
-
-
- -

This descriptor provides a wrapper around a lexical scope to handle file - changes in the middle of a lexical block.

- -
- - -

- Basic type descriptors -

- -
- -
-
-!4 = metadata !{
-  i32,      ;; Tag = 36 + LLVMDebugVersion
-            ;; (DW_TAG_base_type)
-  metadata, ;; Reference to context
-  metadata, ;; Name (may be "" for anonymous types)
-  metadata, ;; Reference to file where defined (may be NULL)
-  i32,      ;; Line number where defined (may be 0)
-  i64,      ;; Size in bits
-  i64,      ;; Alignment in bits
-  i64,      ;; Offset in bits
-  i32,      ;; Flags
-  i32       ;; DWARF type encoding
-}
-
-
- -

These descriptors define primitive types used in the code. Example int, bool - and float. The context provides the scope of the type, which is usually the - top level. Since basic types are not usually user defined the context - and line number can be left as NULL and 0. The size, alignment and offset - are expressed in bits and can be 64 bit values. The alignment is used to - round the offset when embedded in a - composite type (example to keep float - doubles on 64 bit boundaries.) The offset is the bit offset if embedded in - a composite type.

- -

The type encoding provides the details of the type. The values are typically - one of the following:

- -
-
-DW_ATE_address       = 1
-DW_ATE_boolean       = 2
-DW_ATE_float         = 4
-DW_ATE_signed        = 5
-DW_ATE_signed_char   = 6
-DW_ATE_unsigned      = 7
-DW_ATE_unsigned_char = 8
-
-
- -
- - -

- Derived type descriptors -

- -
- -
-
-!5 = metadata !{
-  i32,      ;; Tag (see below)
-  metadata, ;; Reference to context
-  metadata, ;; Name (may be "" for anonymous types)
-  metadata, ;; Reference to file where defined (may be NULL)
-  i32,      ;; Line number where defined (may be 0)
-  i64,      ;; Size in bits
-  i64,      ;; Alignment in bits
-  i64,      ;; Offset in bits
-  i32,      ;; Flags to encode attributes, e.g. private
-  metadata, ;; Reference to type derived from
-  metadata, ;; (optional) Name of the Objective C property associated with
-            ;; Objective-C an ivar
-  metadata, ;; (optional) Name of the Objective C property getter selector.
-  metadata, ;; (optional) Name of the Objective C property setter selector.
-  i32       ;; (optional) Objective C property attributes.
-}
-
-
- -

These descriptors are used to define types derived from other types. The -value of the tag varies depending on the meaning. The following are possible -tag values:

- -
-
-DW_TAG_formal_parameter = 5
-DW_TAG_member           = 13
-DW_TAG_pointer_type     = 15
-DW_TAG_reference_type   = 16
-DW_TAG_typedef          = 22
-DW_TAG_const_type       = 38
-DW_TAG_volatile_type    = 53
-DW_TAG_restrict_type    = 55
-
-
- -

DW_TAG_member is used to define a member of - a composite type - or subprogram. The type of the member is - the derived - type. DW_TAG_formal_parameter is used to define a member which - is a formal argument of a subprogram.

- -

DW_TAG_typedef is used to provide a name for the derived type.

- -

DW_TAG_pointer_type, DW_TAG_reference_type, - DW_TAG_const_type, DW_TAG_volatile_type and - DW_TAG_restrict_type are used to qualify - the derived type.

- -

Derived type location can be determined - from the context and line number. The size, alignment and offset are - expressed in bits and can be 64 bit values. The alignment is used to round - the offset when embedded in a composite - type (example to keep float doubles on 64 bit boundaries.) The offset is - the bit offset if embedded in a composite - type.

- -

Note that the void * type is expressed as a type derived from NULL. -

- -
- - -

- Composite type descriptors -

- -
- -
-
-!6 = metadata !{
-  i32,      ;; Tag (see below)
-  metadata, ;; Reference to context
-  metadata, ;; Name (may be "" for anonymous types)
-  metadata, ;; Reference to file where defined (may be NULL)
-  i32,      ;; Line number where defined (may be 0)
-  i64,      ;; Size in bits
-  i64,      ;; Alignment in bits
-  i64,      ;; Offset in bits
-  i32,      ;; Flags
-  metadata, ;; Reference to type derived from
-  metadata, ;; Reference to array of member descriptors
-  i32       ;; Runtime languages
-}
-
-
- -

These descriptors are used to define types that are composed of 0 or more -elements. The value of the tag varies depending on the meaning. The following -are possible tag values:

- -
-
-DW_TAG_array_type       = 1
-DW_TAG_enumeration_type = 4
-DW_TAG_structure_type   = 19
-DW_TAG_union_type       = 23
-DW_TAG_vector_type      = 259
-DW_TAG_subroutine_type  = 21
-DW_TAG_inheritance      = 28
-
-
- -

The vector flag indicates that an array type is a native packed vector.

- -

The members of array types (tag = DW_TAG_array_type) or vector types - (tag = DW_TAG_vector_type) are subrange - descriptors, each representing the range of subscripts at that level of - indexing.

- -

The members of enumeration types (tag = DW_TAG_enumeration_type) are - enumerator descriptors, each representing - the definition of enumeration value for the set. All enumeration type - descriptors are collected inside the named metadata - !llvm.dbg.cu.

- -

The members of structure (tag = DW_TAG_structure_type) or union (tag - = DW_TAG_union_type) types are any one of - the basic, - derived - or composite type descriptors, each - representing a field member of the structure or union.

- -

For C++ classes (tag = DW_TAG_structure_type), member descriptors - provide information about base classes, static members and member - functions. If a member is a derived type - descriptor and has a tag of DW_TAG_inheritance, then the type - represents a base class. If the member of is - a global variable descriptor then it - represents a static member. And, if the member is - a subprogram descriptor then it represents - a member function. For static members and member - functions, getName() returns the members link or the C++ mangled - name. getDisplayName() the simplied version of the name.

- -

The first member of subroutine (tag = DW_TAG_subroutine_type) type - elements is the return type for the subroutine. The remaining elements are - the formal arguments to the subroutine.

- -

Composite type location can be - determined from the context and line number. The size, alignment and - offset are expressed in bits and can be 64 bit values. The alignment is used - to round the offset when embedded in - a composite type (as an example, to keep - float doubles on 64 bit boundaries.) The offset is the bit offset if embedded - in a composite type.

- -
- - -

- Subrange descriptors -

- -
- -
-
-!42 = metadata !{
-  i32,    ;; Tag = 33 + LLVMDebugVersion (DW_TAG_subrange_type)
-  i64,    ;; Low value
-  i64     ;; High value
-}
-
-
- -

These descriptors are used to define ranges of array subscripts for an array - composite type. The low value defines - the lower bounds typically zero for C/C++. The high value is the upper - bounds. Values are 64 bit. High - low + 1 is the size of the array. If low - > high the array bounds are not included in generated debugging information. -

- -
- - -

- Enumerator descriptors -

- -
- -
-
-!6 = metadata !{
-  i32,      ;; Tag = 40 + LLVMDebugVersion
-            ;; (DW_TAG_enumerator)
-  metadata, ;; Name
-  i64       ;; Value
-}
-
-
- -

These descriptors are used to define members of an - enumeration composite type, it - associates the name to the value.

- -
- - -

- Local variables -

- -
- -
-
-!7 = metadata !{
-  i32,      ;; Tag (see below)
-  metadata, ;; Context
-  metadata, ;; Name
-  metadata, ;; Reference to file where defined
-  i32,      ;; 24 bit - Line number where defined
-            ;; 8 bit - Argument number. 1 indicates 1st argument.
-  metadata, ;; Type descriptor
-  i32,      ;; flags
-  metadata  ;; (optional) Reference to inline location
-}
-
-
- -

These descriptors are used to define variables local to a sub program. The - value of the tag depends on the usage of the variable:

- -
-
-DW_TAG_auto_variable   = 256
-DW_TAG_arg_variable    = 257
-DW_TAG_return_variable = 258
-
-
- -

An auto variable is any variable declared in the body of the function. An - argument variable is any variable that appears as a formal argument to the - function. A return variable is used to track the result of a function and - has no source correspondent.

- -

The context is either the subprogram or block where the variable is defined. - Name the source variable name. Context and line indicate where the - variable was defined. Type descriptor defines the declared type of the - variable.

- -
- -
- - -

- Debugger intrinsic functions -

- -
- -

LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to - provide debug information at various points in generated code.

- - -

- llvm.dbg.declare -

- -
-
-  void %llvm.dbg.declare(metadata, metadata)
-
- -

This intrinsic provides information about a local element (e.g., variable). The - first argument is metadata holding the alloca for the variable. The - second argument is metadata containing a description of the variable.

-
- - -

- llvm.dbg.value -

- -
-
-  void %llvm.dbg.value(metadata, i64, metadata)
-
- -

This intrinsic provides information when a user source variable is set to a - new value. The first argument is the new value (wrapped as metadata). The - second argument is the offset in the user source variable where the new value - is written. The third argument is metadata containing a description of the - user source variable.

-
- -
- - -

- Object lifetimes and scoping -

- -
-

In many languages, the local variables in functions can have their lifetimes - or scopes limited to a subset of a function. In the C family of languages, - for example, variables are only live (readable and writable) within the - source block that they are defined in. In functional languages, values are - only readable after they have been defined. Though this is a very obvious - concept, it is non-trivial to model in LLVM, because it has no notion of - scoping in this sense, and does not want to be tied to a language's scoping - rules.

- -

In order to handle this, the LLVM debug format uses the metadata attached to - llvm instructions to encode line number and scoping information. Consider - the following C fragment, for example:

- -
-
-1.  void foo() {
-2.    int X = 21;
-3.    int Y = 22;
-4.    {
-5.      int Z = 23;
-6.      Z = X;
-7.    }
-8.    X = Y;
-9.  }
-
-
- -

Compiled to LLVM, this function would be represented like this:

- -
-
-define void @foo() nounwind ssp {
-entry:
-  %X = alloca i32, align 4                        ; <i32*> [#uses=4]
-  %Y = alloca i32, align 4                        ; <i32*> [#uses=4]
-  %Z = alloca i32, align 4                        ; <i32*> [#uses=3]
-  %0 = bitcast i32* %X to {}*                     ; <{}*> [#uses=1]
-  call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
-  store i32 21, i32* %X, !dbg !8
-  %1 = bitcast i32* %Y to {}*                     ; <{}*> [#uses=1]
-  call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
-  store i32 22, i32* %Y, !dbg !11
-  %2 = bitcast i32* %Z to {}*                     ; <{}*> [#uses=1]
-  call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
-  store i32 23, i32* %Z, !dbg !15
-  %tmp = load i32* %X, !dbg !16                   ; <i32> [#uses=1]
-  %tmp1 = load i32* %Y, !dbg !16                  ; <i32> [#uses=1]
-  %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; <i32> [#uses=1]
-  store i32 %add, i32* %Z, !dbg !16
-  %tmp2 = load i32* %Y, !dbg !17                  ; <i32> [#uses=1]
-  store i32 %tmp2, i32* %X, !dbg !17
-  ret void, !dbg !18
-}
-
-declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
-
-!0 = metadata !{i32 459008, metadata !1, metadata !"X",
-                metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
-!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
-!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
-               metadata !"foo", metadata !3, i32 1, metadata !4,
-               i1 false, i1 true}; [DW_TAG_subprogram ]
-!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
-                metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
-                i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
-!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
-                i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
-!5 = metadata !{null}
-!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
-                i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
-!7 = metadata !{i32 2, i32 7, metadata !1, null}
-!8 = metadata !{i32 2, i32 3, metadata !1, null}
-!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
-                metadata !6}; [ DW_TAG_auto_variable ]
-!10 = metadata !{i32 3, i32 7, metadata !1, null}
-!11 = metadata !{i32 3, i32 3, metadata !1, null}
-!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
-                 metadata !6}; [ DW_TAG_auto_variable ]
-!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
-!14 = metadata !{i32 5, i32 9, metadata !13, null}
-!15 = metadata !{i32 5, i32 5, metadata !13, null}
-!16 = metadata !{i32 6, i32 5, metadata !13, null}
-!17 = metadata !{i32 8, i32 3, metadata !1, null}
-!18 = metadata !{i32 9, i32 1, metadata !2, null}
-
-
- -

This example illustrates a few important details about LLVM debugging - information. In particular, it shows how the llvm.dbg.declare - intrinsic and location information, which are attached to an instruction, - are applied together to allow a debugger to analyze the relationship between - statements, variable definitions, and the code used to implement the - function.

- -
-
-call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
-
-
- -

The first intrinsic - %llvm.dbg.declare - encodes debugging information for the variable X. The metadata - !dbg !7 attached to the intrinsic provides scope information for the - variable X.

- -
-
-!7 = metadata !{i32 2, i32 7, metadata !1, null}
-!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
-!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
-                metadata !"foo", metadata !"foo", metadata !3, i32 1,
-                metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
-
-
- -

Here !7 is metadata providing location information. It has four - fields: line number, column number, scope, and original scope. The original - scope represents inline location if this instruction is inlined inside a - caller, and is null otherwise. In this example, scope is encoded by - !1. !1 represents a lexical block inside the scope - !2, where !2 is a - subprogram descriptor. This way the - location information attached to the intrinsics indicates that the - variable X is declared at line number 2 at a function level scope in - function foo.

- -

Now lets take another example.

- -
-
-call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
-
-
- -

The second intrinsic - %llvm.dbg.declare - encodes debugging information for variable Z. The metadata - !dbg !14 attached to the intrinsic provides scope information for - the variable Z.

- -
-
-!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
-!14 = metadata !{i32 5, i32 9, metadata !13, null}
-
-
- -

Here !14 indicates that Z is declared at line number 5 and - column number 9 inside of lexical scope !13. The lexical scope - itself resides inside of lexical scope !1 described above.

- -

The scope information attached with each instruction provides a - straightforward way to find instructions covered by a scope.

- -
- -
- - -

- C/C++ front-end specific debug information -

- - -
- -

The C and C++ front-ends represent information about the program in a format - that is effectively identical - to DWARF 3.0 in - terms of information content. This allows code generators to trivially - support native debuggers by generating standard dwarf information, and - contains enough information for non-dwarf targets to translate it as - needed.

- -

This section describes the forms used to represent C and C++ programs. Other - languages could pattern themselves after this (which itself is tuned to - representing programs in the same way that DWARF 3 does), or they could - choose to provide completely different forms if they don't fit into the DWARF - model. As support for debugging information gets added to the various LLVM - source-language front-ends, the information used should be documented - here.

- -

The following sections provide examples of various C/C++ constructs and the - debug information that would best describe those constructs.

- - -

- C/C++ source file information -

- -
- -

Given the source files MySource.cpp and MyHeader.h located - in the directory /Users/mine/sources, the following code:

- -
-
-#include "MyHeader.h"
-
-int main(int argc, char *argv[]) {
-  return 0;
-}
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-...
-;;
-;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
-;;
-!2 = metadata !{
-  i32 524305,    ;; Tag
-  i32 0,         ;; Unused
-  i32 4,         ;; Language Id
-  metadata !"MySource.cpp",
-  metadata !"/Users/mine/sources",
-  metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
-  i1 true,       ;; Main Compile Unit
-  i1 false,      ;; Optimized compile unit
-  metadata !"",  ;; Compiler flags
-  i32 0}         ;; Runtime version
-
-;;
-;; Define the file for the file "/Users/mine/sources/MySource.cpp".
-;;
-!1 = metadata !{
-  i32 524329,    ;; Tag
-  metadata !"MySource.cpp",
-  metadata !"/Users/mine/sources",
-  metadata !2    ;; Compile unit
-}
-
-;;
-;; Define the file for the file "/Users/mine/sources/Myheader.h"
-;;
-!3 = metadata !{
-  i32 524329,    ;; Tag
-  metadata !"Myheader.h"
-  metadata !"/Users/mine/sources",
-  metadata !2    ;; Compile unit
-}
-
-...
-
-
- -

llvm::Instruction provides easy access to metadata attached with an -instruction. One can extract line number information encoded in LLVM IR -using Instruction::getMetadata() and -DILocation::getLineNumber(). -

- if (MDNode *N = I->getMetadata("dbg")) {  // Here I is an LLVM instruction
-   DILocation Loc(N);                      // DILocation is in DebugInfo.h
-   unsigned Line = Loc.getLineNumber();
-   StringRef File = Loc.getFilename();
-   StringRef Dir = Loc.getDirectory();
- }
-
-
- - -

- C/C++ global variable information -

- -
- -

Given an integer global variable declared as follows:

- -
-
-int MyGlobal = 100;
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-;;
-;; Define the global itself.
-;;
-%MyGlobal = global int 100
-...
-;;
-;; List of debug info of globals
-;;
-!llvm.dbg.cu = !{!0}
-
-;; Define the compile unit.
-!0 = metadata !{
-  i32 786449,                       ;; Tag
-  i32 0,                            ;; Context
-  i32 4,                            ;; Language
-  metadata !"foo.cpp",              ;; File
-  metadata !"/Volumes/Data/tmp",    ;; Directory
-  metadata !"clang version 3.1 ",   ;; Producer
-  i1 true,                          ;; Deprecated field
-  i1 false,                         ;; "isOptimized"?
-  metadata !"",                     ;; Flags
-  i32 0,                            ;; Runtime Version
-  metadata !1,                      ;; Enum Types
-  metadata !1,                      ;; Retained Types
-  metadata !1,                      ;; Subprograms
-  metadata !3                       ;; Global Variables
-} ; [ DW_TAG_compile_unit ]
-
-;; The Array of Global Variables
-!3 = metadata !{
-  metadata !4
-}
-
-!4 = metadata !{
-  metadata !5
-}
-
-;;
-;; Define the global variable itself.
-;;
-!5 = metadata !{
-  i32 786484,                        ;; Tag
-  i32 0,                             ;; Unused
-  null,                              ;; Unused
-  metadata !"MyGlobal",              ;; Name
-  metadata !"MyGlobal",              ;; Display Name
-  metadata !"",                      ;; Linkage Name
-  metadata !6,                       ;; File
-  i32 1,                             ;; Line
-  metadata !7,                       ;; Type
-  i32 0,                             ;; IsLocalToUnit
-  i32 1,                             ;; IsDefinition
-  i32* @MyGlobal                     ;; LLVM-IR Value
-} ; [ DW_TAG_variable ]
-
-;;
-;; Define the file
-;;
-!6 = metadata !{
-  i32 786473,                        ;; Tag
-  metadata !"foo.cpp",               ;; File
-  metadata !"/Volumes/Data/tmp",     ;; Directory
-  null                               ;; Unused
-} ; [ DW_TAG_file_type ]
-
-;;
-;; Define the type
-;;
-!7 = metadata !{
-  i32 786468,                         ;; Tag
-  null,                               ;; Unused
-  metadata !"int",                    ;; Name
-  null,                               ;; Unused
-  i32 0,                              ;; Line
-  i64 32,                             ;; Size in Bits
-  i64 32,                             ;; Align in Bits
-  i64 0,                              ;; Offset
-  i32 0,                              ;; Flags
-  i32 5                               ;; Encoding
-} ; [ DW_TAG_base_type ]
-
-
-
- -
- - -

- C/C++ function information -

- -
- -

Given a function declared as follows:

- -
-
-int main(int argc, char *argv[]) {
-  return 0;
-}
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-;;
-;; Define the anchor for subprograms.  Note that the second field of the
-;; anchor is 46, which is the same as the tag for subprograms
-;; (46 = DW_TAG_subprogram.)
-;;
-!6 = metadata !{
-  i32 524334,        ;; Tag
-  i32 0,             ;; Unused
-  metadata !1,       ;; Context
-  metadata !"main",  ;; Name
-  metadata !"main",  ;; Display name
-  metadata !"main",  ;; Linkage name
-  metadata !1,       ;; File
-  i32 1,             ;; Line number
-  metadata !4,       ;; Type
-  i1 false,          ;; Is local
-  i1 true,           ;; Is definition
-  i32 0,             ;; Virtuality attribute, e.g. pure virtual function
-  i32 0,             ;; Index into virtual table for C++ methods
-  i32 0,             ;; Type that holds virtual table.
-  i32 0,             ;; Flags
-  i1 false,          ;; True if this function is optimized
-  Function *,        ;; Pointer to llvm::Function
-  null               ;; Function template parameters
-}
-;;
-;; Define the subprogram itself.
-;;
-define i32 @main(i32 %argc, i8** %argv) {
-...
-}
-
-
- -
- - -

- C/C++ basic types -

- -
- -

The following are the basic type descriptors for C/C++ core types:

- - -

- bool -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"bool",  ;; Name
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 8,             ;; Size in Bits
-  i64 8,             ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 2              ;; Encoding
-}
-
-
- -
- - -

- char -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"char",  ;; Name
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 8,             ;; Size in Bits
-  i64 8,             ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 6              ;; Encoding
-}
-
-
- -
- - -

- unsigned char -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"unsigned char",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 8,             ;; Size in Bits
-  i64 8,             ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 8              ;; Encoding
-}
-
-
- -
- - -

- short -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"short int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 16,            ;; Size in Bits
-  i64 16,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 5              ;; Encoding
-}
-
-
- -
- - -

- unsigned short -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"short unsigned int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 16,            ;; Size in Bits
-  i64 16,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 7              ;; Encoding
-}
-
-
- -
- - -

- int -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"int",   ;; Name
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 32,            ;; Size in Bits
-  i64 32,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 5              ;; Encoding
-}
-
- -
- - -

- unsigned int -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"unsigned int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 32,            ;; Size in Bits
-  i64 32,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 7              ;; Encoding
-}
-
-
- -
- - -

- long long -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"long long int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 64,            ;; Size in Bits
-  i64 64,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 5              ;; Encoding
-}
-
-
- -
- - -

- unsigned long long -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"long long unsigned int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 64,            ;; Size in Bits
-  i64 64,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 7              ;; Encoding
-}
-
-
- -
- - -

- float -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"float",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 32,            ;; Size in Bits
-  i64 32,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 4              ;; Encoding
-}
-
-
- -
- - -

- double -

- -
- -
-
-!2 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"double",;; Name
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 64,            ;; Size in Bits
-  i64 64,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 4              ;; Encoding
-}
-
-
- -
- -
- - -

- C/C++ derived types -

- -
- -

Given the following as an example of C/C++ derived type:

- -
-
-typedef const int *IntPtr;
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-;;
-;; Define the typedef "IntPtr".
-;;
-!2 = metadata !{
-  i32 524310,          ;; Tag
-  metadata !1,         ;; Context
-  metadata !"IntPtr",  ;; Name
-  metadata !3,         ;; File
-  i32 0,               ;; Line number
-  i64 0,               ;; Size in bits
-  i64 0,               ;; Align in bits
-  i64 0,               ;; Offset in bits
-  i32 0,               ;; Flags
-  metadata !4          ;; Derived From type
-}
-
-;;
-;; Define the pointer type.
-;;
-!4 = metadata !{
-  i32 524303,          ;; Tag
-  metadata !1,         ;; Context
-  metadata !"",        ;; Name
-  metadata !1,         ;; File
-  i32 0,               ;; Line number
-  i64 64,              ;; Size in bits
-  i64 64,              ;; Align in bits
-  i64 0,               ;; Offset in bits
-  i32 0,               ;; Flags
-  metadata !5          ;; Derived From type
-}
-;;
-;; Define the const type.
-;;
-!5 = metadata !{
-  i32 524326,          ;; Tag
-  metadata !1,         ;; Context
-  metadata !"",        ;; Name
-  metadata !1,         ;; File
-  i32 0,               ;; Line number
-  i64 32,              ;; Size in bits
-  i64 32,              ;; Align in bits
-  i64 0,               ;; Offset in bits
-  i32 0,               ;; Flags
-  metadata !6          ;; Derived From type
-}
-;;
-;; Define the int type.
-;;
-!6 = metadata !{
-  i32 524324,          ;; Tag
-  metadata !1,         ;; Context
-  metadata !"int",     ;; Name
-  metadata !1,         ;; File
-  i32 0,               ;; Line number
-  i64 32,              ;; Size in bits
-  i64 32,              ;; Align in bits
-  i64 0,               ;; Offset in bits
-  i32 0,               ;; Flags
-  5                    ;; Encoding
-}
-
-
- -
- - -

- C/C++ struct/union types -

- -
- -

Given the following as an example of C/C++ struct type:

- -
-
-struct Color {
-  unsigned Red;
-  unsigned Green;
-  unsigned Blue;
-};
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-;;
-;; Define basic type for unsigned int.
-;;
-!5 = metadata !{
-  i32 524324,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"unsigned int",
-  metadata !1,       ;; File
-  i32 0,             ;; Line number
-  i64 32,            ;; Size in Bits
-  i64 32,            ;; Align in Bits
-  i64 0,             ;; Offset in Bits
-  i32 0,             ;; Flags
-  i32 7              ;; Encoding
-}
-;;
-;; Define composite type for struct Color.
-;;
-!2 = metadata !{
-  i32 524307,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"Color", ;; Name
-  metadata !1,       ;; Compile unit
-  i32 1,             ;; Line number
-  i64 96,            ;; Size in bits
-  i64 32,            ;; Align in bits
-  i64 0,             ;; Offset in bits
-  i32 0,             ;; Flags
-  null,              ;; Derived From
-  metadata !3,       ;; Elements
-  i32 0              ;; Runtime Language
-}
-
-;;
-;; Define the Red field.
-;;
-!4 = metadata !{
-  i32 524301,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"Red",   ;; Name
-  metadata !1,       ;; File
-  i32 2,             ;; Line number
-  i64 32,            ;; Size in bits
-  i64 32,            ;; Align in bits
-  i64 0,             ;; Offset in bits
-  i32 0,             ;; Flags
-  metadata !5        ;; Derived From type
-}
-
-;;
-;; Define the Green field.
-;;
-!6 = metadata !{
-  i32 524301,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"Green", ;; Name
-  metadata !1,       ;; File
-  i32 3,             ;; Line number
-  i64 32,            ;; Size in bits
-  i64 32,            ;; Align in bits
-  i64 32,             ;; Offset in bits
-  i32 0,             ;; Flags
-  metadata !5        ;; Derived From type
-}
-
-;;
-;; Define the Blue field.
-;;
-!7 = metadata !{
-  i32 524301,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"Blue",  ;; Name
-  metadata !1,       ;; File
-  i32 4,             ;; Line number
-  i64 32,            ;; Size in bits
-  i64 32,            ;; Align in bits
-  i64 64,             ;; Offset in bits
-  i32 0,             ;; Flags
-  metadata !5        ;; Derived From type
-}
-
-;;
-;; Define the array of fields used by the composite type Color.
-;;
-!3 = metadata !{metadata !4, metadata !6, metadata !7}
-
-
- -
- - -

- C/C++ enumeration types -

- -
- -

Given the following as an example of C/C++ enumeration type:

- -
-
-enum Trees {
-  Spruce = 100,
-  Oak = 200,
-  Maple = 300
-};
-
-
- -

a C/C++ front-end would generate the following descriptors:

- -
-
-;;
-;; Define composite type for enum Trees
-;;
-!2 = metadata !{
-  i32 524292,        ;; Tag
-  metadata !1,       ;; Context
-  metadata !"Trees", ;; Name
-  metadata !1,       ;; File
-  i32 1,             ;; Line number
-  i64 32,            ;; Size in bits
-  i64 32,            ;; Align in bits
-  i64 0,             ;; Offset in bits
-  i32 0,             ;; Flags
-  null,              ;; Derived From type
-  metadata !3,       ;; Elements
-  i32 0              ;; Runtime language
-}
-
-;;
-;; Define the array of enumerators used by composite type Trees.
-;;
-!3 = metadata !{metadata !4, metadata !5, metadata !6}
-
-;;
-;; Define Spruce enumerator.
-;;
-!4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
-
-;;
-;; Define Oak enumerator.
-;;
-!5 = metadata !{i32 524328, metadata !"Oak", i64 200}
-
-;;
-;; Define Maple enumerator.
-;;
-!6 = metadata !{i32 524328, metadata !"Maple", i64 300}
-
-
-
- -
- -
- - - -

- Debugging information format -

- -
- -

- Debugging Information Extension for Objective C Properties -

-
- -

- Introduction -

- - -
-

Objective C provides a simpler way to declare and define accessor methods -using declared properties. The language provides features to declare a -property and to let compiler synthesize accessor methods. -

- -

The debugger lets developer inspect Objective C interfaces and their -instance variables and class variables. However, the debugger does not know -anything about the properties defined in Objective C interfaces. The debugger -consumes information generated by compiler in DWARF format. The format does -not support encoding of Objective C properties. This proposal describes DWARF -extensions to encode Objective C properties, which the debugger can use to let -developers inspect Objective C properties. -

- -
- - - -

- Proposal -

- - -
-

Objective C properties exist separately from class members. A property -can be defined only by "setter" and "getter" selectors, and -be calculated anew on each access. Or a property can just be a direct access -to some declared ivar. Finally it can have an ivar "automatically -synthesized" for it by the compiler, in which case the property can be -referred to in user code directly using the standard C dereference syntax as -well as through the property "dot" syntax, but there is no entry in -the @interface declaration corresponding to this ivar. -

-

-To facilitate debugging, these properties we will add a new DWARF TAG into the -DW_TAG_structure_type definition for the class to hold the description of a -given property, and a set of DWARF attributes that provide said description. -The property tag will also contain the name and declared type of the property. -

-

-If there is a related ivar, there will also be a DWARF property attribute placed -in the DW_TAG_member DIE for that ivar referring back to the property TAG for -that property. And in the case where the compiler synthesizes the ivar directly, -the compiler is expected to generate a DW_TAG_member for that ivar (with the -DW_AT_artificial set to 1), whose name will be the name used to access this -ivar directly in code, and with the property attribute pointing back to the -property it is backing. -

-

-The following examples will serve as illustration for our discussion: -

- -
-
-@interface I1 {
-  int n2;
-}
-
-@property int p1;
-@property int p2;
-@end
-
-@implementation I1
-@synthesize p1;
-@synthesize p2 = n2;
-@end
-
-
- -

-This produces the following DWARF (this is a "pseudo dwarfdump" output): -

-
-
-0x00000100:  TAG_structure_type [7] *
-               AT_APPLE_runtime_class( 0x10 )
-               AT_name( "I1" )
-               AT_decl_file( "Objc_Property.m" )
-               AT_decl_line( 3 )
-
-0x00000110    TAG_APPLE_property
-                AT_name ( "p1" )
-                AT_type ( {0x00000150} ( int ) )
-
-0x00000120:   TAG_APPLE_property
-                AT_name ( "p2" )
-                AT_type ( {0x00000150} ( int ) )
-
-0x00000130:   TAG_member [8]
-                AT_name( "_p1" )
-                AT_APPLE_property ( {0x00000110} "p1" )
-                AT_type( {0x00000150} ( int ) )
-                AT_artificial ( 0x1 )
-
-0x00000140:    TAG_member [8]
-                 AT_name( "n2" )
-                 AT_APPLE_property ( {0x00000120} "p2" )
-                 AT_type( {0x00000150} ( int ) )
-
-0x00000150:  AT_type( ( int ) )
-
-
- -

Note, the current convention is that the name of the ivar for an -auto-synthesized property is the name of the property from which it derives with -an underscore prepended, as is shown in the example. -But we actually don't need to know this convention, since we are given the name -of the ivar directly. -

- -

-Also, it is common practice in ObjC to have different property declarations in -the @interface and @implementation - e.g. to provide a read-only property in -the interface,and a read-write interface in the implementation. In that case, -the compiler should emit whichever property declaration will be in force in the -current translation unit. -

- -

Developers can decorate a property with attributes which are encoded using -DW_AT_APPLE_property_attribute. -

- -
-
-@property (readonly, nonatomic) int pr;
-
-
-

-Which produces a property tag: -

-

-
-TAG_APPLE_property [8]
-  AT_name( "pr" )
-  AT_type ( {0x00000147} (int) )
-  AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
-
-
- -

The setter and getter method names are attached to the property using -DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes. -

-
-
-@interface I1
-@property (setter=myOwnP3Setter:) int p3;
--(void)myOwnP3Setter:(int)a;
-@end
-
-@implementation I1
-@synthesize p3;
--(void)myOwnP3Setter:(int)a{ }
-@end
-
-
- -

-The DWARF for this would be: -

-
-
-0x000003bd: TAG_structure_type [7] *
-              AT_APPLE_runtime_class( 0x10 )
-              AT_name( "I1" )
-              AT_decl_file( "Objc_Property.m" )
-              AT_decl_line( 3 )
-
-0x000003cd      TAG_APPLE_property
-                  AT_name ( "p3" )
-                  AT_APPLE_property_setter ( "myOwnP3Setter:" )
-                  AT_type( {0x00000147} ( int ) )
-
-0x000003f3:     TAG_member [8]
-                  AT_name( "_p3" )
-                  AT_type ( {0x00000147} ( int ) )
-                  AT_APPLE_property ( {0x000003cd} )
-                  AT_artificial ( 0x1 )
-
-
- -
- - -

- New DWARF Tags -

- - -
- - - - - - - - - - - -
TAGValue
DW_TAG_APPLE_property0x4200
- -
- - -

- New DWARF Attributes -

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeValueClasses
DW_AT_APPLE_property0x3fedReference
DW_AT_APPLE_property_getter0x3fe9String
DW_AT_APPLE_property_setter0x3feaString
DW_AT_APPLE_property_attribute0x3febConstant
- -
- - -

- New DWARF Constants -

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameValue
DW_AT_APPLE_PROPERTY_readonly0x1
DW_AT_APPLE_PROPERTY_readwrite0x2
DW_AT_APPLE_PROPERTY_assign0x4
DW_AT_APPLE_PROPERTY_retain0x8
DW_AT_APPLE_PROPERTY_copy0x10
DW_AT_APPLE_PROPERTY_nonatomic0x20
- -
-
- - -

- Name Accelerator Tables -

- -
- -

- Introduction -

- -
-

The .debug_pubnames and .debug_pubtypes formats are not what a debugger - needs. The "pub" in the section name indicates that the entries in the - table are publicly visible names only. This means no static or hidden - functions show up in the .debug_pubnames. No static variables or private class - variables are in the .debug_pubtypes. Many compilers add different things to - these tables, so we can't rely upon the contents between gcc, icc, or clang.

- -

The typical query given by users tends not to match up with the contents of - these tables. For example, the DWARF spec states that "In the case of the - name of a function member or static data member of a C++ structure, class or - union, the name presented in the .debug_pubnames section is not the simple - name given by the DW_AT_name attribute of the referenced debugging information - entry, but rather the fully qualified name of the data or function member." - So the only names in these tables for complex C++ entries is a fully - qualified name. Debugger users tend not to enter their search strings as - "a::b::c(int,const Foo&) const", but rather as "c", "b::c" , or "a::b::c". So - the name entered in the name table must be demangled in order to chop it up - appropriately and additional names must be manually entered into the table - to make it effective as a name lookup table for debuggers to use.

- -

All debuggers currently ignore the .debug_pubnames table as a result of - its inconsistent and useless public-only name content making it a waste of - space in the object file. These tables, when they are written to disk, are - not sorted in any way, leaving every debugger to do its own parsing - and sorting. These tables also include an inlined copy of the string values - in the table itself making the tables much larger than they need to be on - disk, especially for large C++ programs.

- -

Can't we just fix the sections by adding all of the names we need to this - table? No, because that is not what the tables are defined to contain and we - won't know the difference between the old bad tables and the new good tables. - At best we could make our own renamed sections that contain all of the data - we need.

- -

These tables are also insufficient for what a debugger like LLDB needs. - LLDB uses clang for its expression parsing where LLDB acts as a PCH. LLDB is - then often asked to look for type "foo" or namespace "bar", or list items in - namespace "baz". Namespaces are not included in the pubnames or pubtypes - tables. Since clang asks a lot of questions when it is parsing an expression, - we need to be very fast when looking up names, as it happens a lot. Having new - accelerator tables that are optimized for very quick lookups will benefit - this type of debugging experience greatly.

- -

We would like to generate name lookup tables that can be mapped into - memory from disk, and used as is, with little or no up-front parsing. We would - also be able to control the exact content of these different tables so they - contain exactly what we need. The Name Accelerator Tables were designed - to fix these issues. In order to solve these issues we need to:

- -
    -
  • Have a format that can be mapped into memory from disk and used as is
  • -
  • Lookups should be very fast
  • -
  • Extensible table format so these tables can be made by many producers
  • -
  • Contain all of the names needed for typical lookups out of the box
  • -
  • Strict rules for the contents of tables
  • -
- -

Table size is important and the accelerator table format should allow the - reuse of strings from common string tables so the strings for the names are - not duplicated. We also want to make sure the table is ready to be used as-is - by simply mapping the table into memory with minimal header parsing.

- -

The name lookups need to be fast and optimized for the kinds of lookups - that debuggers tend to do. Optimally we would like to touch as few parts of - the mapped table as possible when doing a name lookup and be able to quickly - find the name entry we are looking for, or discover there are no matches. In - the case of debuggers we optimized for lookups that fail most of the time.

- -

Each table that is defined should have strict rules on exactly what is in - the accelerator tables and documented so clients can rely on the content.

- -
- - -

- Hash Tables -

- - -
-
Standard Hash Tables
- -

Typical hash tables have a header, buckets, and each bucket points to the -bucket contents: -

- -
-
-.------------.
-|  HEADER    |
-|------------|
-|  BUCKETS   |
-|------------|
-|  DATA      |
-`------------'
-
-
- -

The BUCKETS are an array of offsets to DATA for each hash:

- -
-
-.------------.
-| 0x00001000 | BUCKETS[0]
-| 0x00002000 | BUCKETS[1]
-| 0x00002200 | BUCKETS[2]
-| 0x000034f0 | BUCKETS[3]
-|            | ...
-| 0xXXXXXXXX | BUCKETS[n_buckets]
-'------------'
-
-
- -

So for bucket[3] in the example above, we have an offset into the table - 0x000034f0 which points to a chain of entries for the bucket. Each bucket - must contain a next pointer, full 32 bit hash value, the string itself, - and the data for the current string value.

- -
-
-            .------------.
-0x000034f0: | 0x00003500 | next pointer
-            | 0x12345678 | 32 bit hash
-            | "erase"    | string value
-            | data[n]    | HashData for this bucket
-            |------------|
-0x00003500: | 0x00003550 | next pointer
-            | 0x29273623 | 32 bit hash
-            | "dump"     | string value
-            | data[n]    | HashData for this bucket
-            |------------|
-0x00003550: | 0x00000000 | next pointer
-            | 0x82638293 | 32 bit hash
-            | "main"     | string value
-            | data[n]    | HashData for this bucket
-            `------------'
-
-
- -

The problem with this layout for debuggers is that we need to optimize for - the negative lookup case where the symbol we're searching for is not present. - So if we were to lookup "printf" in the table above, we would make a 32 hash - for "printf", it might match bucket[3]. We would need to go to the offset - 0x000034f0 and start looking to see if our 32 bit hash matches. To do so, we - need to read the next pointer, then read the hash, compare it, and skip to - the next bucket. Each time we are skipping many bytes in memory and touching - new cache pages just to do the compare on the full 32 bit hash. All of these - accesses then tell us that we didn't have a match.

- -
Name Hash Tables
- -

To solve the issues mentioned above we have structured the hash tables - a bit differently: a header, buckets, an array of all unique 32 bit hash - values, followed by an array of hash value data offsets, one for each hash - value, then the data for all hash values:

- -
-
-.-------------.
-|  HEADER     |
-|-------------|
-|  BUCKETS    |
-|-------------|
-|  HASHES     |
-|-------------|
-|  OFFSETS    |
-|-------------|
-|  DATA       |
-`-------------'
-
-
- -

The BUCKETS in the name tables are an index into the HASHES array. By - making all of the full 32 bit hash values contiguous in memory, we allow - ourselves to efficiently check for a match while touching as little - memory as possible. Most often checking the 32 bit hash values is as far as - the lookup goes. If it does match, it usually is a match with no collisions. - So for a table with "n_buckets" buckets, and "n_hashes" unique 32 bit hash - values, we can clarify the contents of the BUCKETS, HASHES and OFFSETS as:

- -
-
-.-------------------------.
-|  HEADER.magic           | uint32_t
-|  HEADER.version         | uint16_t
-|  HEADER.hash_function   | uint16_t
-|  HEADER.bucket_count    | uint32_t
-|  HEADER.hashes_count    | uint32_t
-|  HEADER.header_data_len | uint32_t
-|  HEADER_DATA            | HeaderData
-|-------------------------|
-|  BUCKETS                | uint32_t[n_buckets] // 32 bit hash indexes
-|-------------------------|
-|  HASHES                 | uint32_t[n_buckets] // 32 bit hash values
-|-------------------------|
-|  OFFSETS                | uint32_t[n_buckets] // 32 bit offsets to hash value data
-|-------------------------|
-|  ALL HASH DATA          |
-`-------------------------'
-
-
- -

So taking the exact same data from the standard hash example above we end up - with:

- -
-
-            .------------.
-            | HEADER     |
-            |------------|
-            |          0 | BUCKETS[0]
-            |          2 | BUCKETS[1]
-            |          5 | BUCKETS[2]
-            |          6 | BUCKETS[3]
-            |            | ...
-            |        ... | BUCKETS[n_buckets]
-            |------------|
-            | 0x........ | HASHES[0]
-            | 0x........ | HASHES[1]
-            | 0x........ | HASHES[2]
-            | 0x........ | HASHES[3]
-            | 0x........ | HASHES[4]
-            | 0x........ | HASHES[5]
-            | 0x12345678 | HASHES[6]    hash for BUCKETS[3]
-            | 0x29273623 | HASHES[7]    hash for BUCKETS[3]
-            | 0x82638293 | HASHES[8]    hash for BUCKETS[3]
-            | 0x........ | HASHES[9]
-            | 0x........ | HASHES[10]
-            | 0x........ | HASHES[11]
-            | 0x........ | HASHES[12]
-            | 0x........ | HASHES[13]
-            | 0x........ | HASHES[n_hashes]
-            |------------|
-            | 0x........ | OFFSETS[0]
-            | 0x........ | OFFSETS[1]
-            | 0x........ | OFFSETS[2]
-            | 0x........ | OFFSETS[3]
-            | 0x........ | OFFSETS[4]
-            | 0x........ | OFFSETS[5]
-            | 0x000034f0 | OFFSETS[6]   offset for BUCKETS[3]
-            | 0x00003500 | OFFSETS[7]   offset for BUCKETS[3]
-            | 0x00003550 | OFFSETS[8]   offset for BUCKETS[3]
-            | 0x........ | OFFSETS[9]
-            | 0x........ | OFFSETS[10]
-            | 0x........ | OFFSETS[11]
-            | 0x........ | OFFSETS[12]
-            | 0x........ | OFFSETS[13]
-            | 0x........ | OFFSETS[n_hashes]
-            |------------|
-            |            |
-            |            |
-            |            |
-            |            |
-            |            |
-            |------------|
-0x000034f0: | 0x00001203 | .debug_str ("erase")
-            | 0x00000004 | A 32 bit array count - number of HashData with name "erase"
-            | 0x........ | HashData[0]
-            | 0x........ | HashData[1]
-            | 0x........ | HashData[2]
-            | 0x........ | HashData[3]
-            | 0x00000000 | String offset into .debug_str (terminate data for hash)
-            |------------|
-0x00003500: | 0x00001203 | String offset into .debug_str ("collision")
-            | 0x00000002 | A 32 bit array count - number of HashData with name "collision"
-            | 0x........ | HashData[0]
-            | 0x........ | HashData[1]
-            | 0x00001203 | String offset into .debug_str ("dump")
-            | 0x00000003 | A 32 bit array count - number of HashData with name "dump"
-            | 0x........ | HashData[0]
-            | 0x........ | HashData[1]
-            | 0x........ | HashData[2]
-            | 0x00000000 | String offset into .debug_str (terminate data for hash)
-            |------------|
-0x00003550: | 0x00001203 | String offset into .debug_str ("main")
-            | 0x00000009 | A 32 bit array count - number of HashData with name "main"
-            | 0x........ | HashData[0]
-            | 0x........ | HashData[1]
-            | 0x........ | HashData[2]
-            | 0x........ | HashData[3]
-            | 0x........ | HashData[4]
-            | 0x........ | HashData[5]
-            | 0x........ | HashData[6]
-            | 0x........ | HashData[7]
-            | 0x........ | HashData[8]
-            | 0x00000000 | String offset into .debug_str (terminate data for hash)
-            `------------'
-
-
- -

So we still have all of the same data, we just organize it more efficiently - for debugger lookup. If we repeat the same "printf" lookup from above, we - would hash "printf" and find it matches BUCKETS[3] by taking the 32 bit hash - value and modulo it by n_buckets. BUCKETS[3] contains "6" which is the index - into the HASHES table. We would then compare any consecutive 32 bit hashes - values in the HASHES array as long as the hashes would be in BUCKETS[3]. We - do this by verifying that each subsequent hash value modulo n_buckets is still - 3. In the case of a failed lookup we would access the memory for BUCKETS[3], and - then compare a few consecutive 32 bit hashes before we know that we have no match. - We don't end up marching through multiple words of memory and we really keep the - number of processor data cache lines being accessed as small as possible.

- -

The string hash that is used for these lookup tables is the Daniel J. - Bernstein hash which is also used in the ELF GNU_HASH sections. It is a very - good hash for all kinds of names in programs with very few hash collisions.

- -

Empty buckets are designated by using an invalid hash index of UINT32_MAX.

-
- - -

- Details -

- -
-

These name hash tables are designed to be generic where specializations of - the table get to define additional data that goes into the header - ("HeaderData"), how the string value is stored ("KeyType") and the content - of the data for each hash value.

- -
Header Layout
-

The header has a fixed part, and the specialized part. The exact format of - the header is:

-
-
-struct Header
-{
-  uint32_t   magic;           // 'HASH' magic value to allow endian detection
-  uint16_t   version;         // Version number
-  uint16_t   hash_function;   // The hash function enumeration that was used
-  uint32_t   bucket_count;    // The number of buckets in this hash table
-  uint32_t   hashes_count;    // The total number of unique hash values and hash data offsets in this table
-  uint32_t   header_data_len; // The bytes to skip to get to the hash indexes (buckets) for correct alignment
-                              // Specifically the length of the following HeaderData field - this does not
-                              // include the size of the preceding fields
-  HeaderData header_data;     // Implementation specific header data
-};
-
-
-

The header starts with a 32 bit "magic" value which must be 'HASH' encoded as - an ASCII integer. This allows the detection of the start of the hash table and - also allows the table's byte order to be determined so the table can be - correctly extracted. The "magic" value is followed by a 16 bit version number - which allows the table to be revised and modified in the future. The current - version number is 1. "hash_function" is a uint16_t enumeration that specifies - which hash function was used to produce this table. The current values for the - hash function enumerations include:

-
-
-enum HashFunctionType
-{
-  eHashFunctionDJB = 0u, // Daniel J Bernstein hash function
-};
-
-
-

"bucket_count" is a 32 bit unsigned integer that represents how many buckets - are in the BUCKETS array. "hashes_count" is the number of unique 32 bit hash - values that are in the HASHES array, and is the same number of offsets are - contained in the OFFSETS array. "header_data_len" specifies the size in - bytes of the HeaderData that is filled in by specialized versions of this - table.

- -
Fixed Lookup
-

The header is followed by the buckets, hashes, offsets, and hash value - data. -

-
-struct FixedTable
-{
-  uint32_t buckets[Header.bucket_count];  // An array of hash indexes into the "hashes[]" array below
-  uint32_t hashes [Header.hashes_count];  // Every unique 32 bit hash for the entire table is in this table
-  uint32_t offsets[Header.hashes_count];  // An offset that corresponds to each item in the "hashes[]" array above
-};
-
-
-

"buckets" is an array of 32 bit indexes into the "hashes" array. The - "hashes" array contains all of the 32 bit hash values for all names in the - hash table. Each hash in the "hashes" table has an offset in the "offsets" - array that points to the data for the hash value.

- -

This table setup makes it very easy to repurpose these tables to contain - different data, while keeping the lookup mechanism the same for all tables. - This layout also makes it possible to save the table to disk and map it in - later and do very efficient name lookups with little or no parsing.

- -

DWARF lookup tables can be implemented in a variety of ways and can store - a lot of information for each name. We want to make the DWARF tables - extensible and able to store the data efficiently so we have used some of the - DWARF features that enable efficient data storage to define exactly what kind - of data we store for each name.

- -

The "HeaderData" contains a definition of the contents of each HashData - chunk. We might want to store an offset to all of the debug information - entries (DIEs) for each name. To keep things extensible, we create a list of - items, or Atoms, that are contained in the data for each name. First comes the - type of the data in each atom:

-
-
-enum AtomType
-{
-  eAtomTypeNULL       = 0u,
-  eAtomTypeDIEOffset  = 1u,   // DIE offset, check form for encoding
-  eAtomTypeCUOffset   = 2u,   // DIE offset of the compiler unit header that contains the item in question
-  eAtomTypeTag        = 3u,   // DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2
-  eAtomTypeNameFlags  = 4u,   // Flags from enum NameFlags
-  eAtomTypeTypeFlags  = 5u,   // Flags from enum TypeFlags
-};
-
-
-

The enumeration values and their meanings are:

-
-
-  eAtomTypeNULL       - a termination atom that specifies the end of the atom list
-  eAtomTypeDIEOffset  - an offset into the .debug_info section for the DWARF DIE for this name
-  eAtomTypeCUOffset   - an offset into the .debug_info section for the CU that contains the DIE
-  eAtomTypeDIETag     - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is
-  eAtomTypeNameFlags  - Flags for functions and global variables (isFunction, isInlined, isExternal...)
-  eAtomTypeTypeFlags  - Flags for types (isCXXClass, isObjCClass, ...)
-
-
-

Then we allow each atom type to define the atom type and how the data for - each atom type data is encoded:

-
-
-struct Atom
-{
-  uint16_t type;  // AtomType enum value
-  uint16_t form;  // DWARF DW_FORM_XXX defines
-};
-
-
-

The "form" type above is from the DWARF specification and defines the - exact encoding of the data for the Atom type. See the DWARF specification for - the DW_FORM_ definitions.

-
-
-struct HeaderData
-{
-  uint32_t die_offset_base;
-  uint32_t atom_count;
-  Atoms    atoms[atom_count0];
-};
-
-
-

"HeaderData" defines the base DIE offset that should be added to any atoms - that are encoded using the DW_FORM_ref1, DW_FORM_ref2, DW_FORM_ref4, - DW_FORM_ref8 or DW_FORM_ref_udata. It also defines what is contained in - each "HashData" object -- Atom.form tells us how large each field will be in - the HashData and the Atom.type tells us how this data should be interpreted.

- -

For the current implementations of the ".apple_names" (all functions + globals), - the ".apple_types" (names of all types that are defined), and the - ".apple_namespaces" (all namespaces), we currently set the Atom array to be:

-
-
-HeaderData.atom_count = 1;
-HeaderData.atoms[0].type = eAtomTypeDIEOffset;
-HeaderData.atoms[0].form = DW_FORM_data4;
-
-
-

This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is - encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have - multiple matching DIEs in a single file, which could come up with an inlined - function for instance. Future tables could include more information about the - DIE such as flags indicating if the DIE is a function, method, block, - or inlined.

- -

The KeyType for the DWARF table is a 32 bit string table offset into the - ".debug_str" table. The ".debug_str" is the string table for the DWARF which - may already contain copies of all of the strings. This helps make sure, with - help from the compiler, that we reuse the strings between all of the DWARF - sections and keeps the hash table size down. Another benefit to having the - compiler generate all strings as DW_FORM_strp in the debug info, is that - DWARF parsing can be made much faster.

- -

After a lookup is made, we get an offset into the hash data. The hash data - needs to be able to deal with 32 bit hash collisions, so the chunk of data - at the offset in the hash data consists of a triple:

-
-
-uint32_t str_offset
-uint32_t hash_data_count
-HashData[hash_data_count]
-
-
-

If "str_offset" is zero, then the bucket contents are done. 99.9% of the - hash data chunks contain a single item (no 32 bit hash collision):

-
-
-.------------.
-| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
-| 0x00000004 | uint32_t HashData count
-| 0x........ | uint32_t HashData[0] DIE offset
-| 0x........ | uint32_t HashData[1] DIE offset
-| 0x........ | uint32_t HashData[2] DIE offset
-| 0x........ | uint32_t HashData[3] DIE offset
-| 0x00000000 | uint32_t KeyType (end of hash chain)
-`------------'
-
-
-

If there are collisions, you will have multiple valid string offsets:

-
-
-.------------.
-| 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
-| 0x00000004 | uint32_t HashData count
-| 0x........ | uint32_t HashData[0] DIE offset
-| 0x........ | uint32_t HashData[1] DIE offset
-| 0x........ | uint32_t HashData[2] DIE offset
-| 0x........ | uint32_t HashData[3] DIE offset
-| 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print")
-| 0x00000002 | uint32_t HashData count
-| 0x........ | uint32_t HashData[0] DIE offset
-| 0x........ | uint32_t HashData[1] DIE offset
-| 0x00000000 | uint32_t KeyType (end of hash chain)
-`------------'
-
-
-

Current testing with real world C++ binaries has shown that there is around 1 - 32 bit hash collision per 100,000 name entries.

-
- -

- Contents -

- -
-

As we said, we want to strictly define exactly what is included in the - different tables. For DWARF, we have 3 tables: ".apple_names", ".apple_types", - and ".apple_namespaces".

- -

".apple_names" sections should contain an entry for each DWARF DIE whose - DW_TAG is a DW_TAG_label, DW_TAG_inlined_subroutine, or DW_TAG_subprogram that - has address attributes: DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges or - DW_AT_entry_pc. It also contains DW_TAG_variable DIEs that have a DW_OP_addr - in the location (global and static variables). All global and static variables - should be included, including those scoped withing functions and classes. For - example using the following code:

-
-
-static int var = 0;
-
-void f ()
-{
-  static int var = 0;
-}
-
-
-

Both of the static "var" variables would be included in the table. All - functions should emit both their full names and their basenames. For C or C++, - the full name is the mangled name (if available) which is usually in the - DW_AT_MIPS_linkage_name attribute, and the DW_AT_name contains the function - basename. If global or static variables have a mangled name in a - DW_AT_MIPS_linkage_name attribute, this should be emitted along with the - simple name found in the DW_AT_name attribute.

- -

".apple_types" sections should contain an entry for each DWARF DIE whose - tag is one of:

-
    -
  • DW_TAG_array_type
  • -
  • DW_TAG_class_type
  • -
  • DW_TAG_enumeration_type
  • -
  • DW_TAG_pointer_type
  • -
  • DW_TAG_reference_type
  • -
  • DW_TAG_string_type
  • -
  • DW_TAG_structure_type
  • -
  • DW_TAG_subroutine_type
  • -
  • DW_TAG_typedef
  • -
  • DW_TAG_union_type
  • -
  • DW_TAG_ptr_to_member_type
  • -
  • DW_TAG_set_type
  • -
  • DW_TAG_subrange_type
  • -
  • DW_TAG_base_type
  • -
  • DW_TAG_const_type
  • -
  • DW_TAG_constant
  • -
  • DW_TAG_file_type
  • -
  • DW_TAG_namelist
  • -
  • DW_TAG_packed_type
  • -
  • DW_TAG_volatile_type
  • -
  • DW_TAG_restrict_type
  • -
  • DW_TAG_interface_type
  • -
  • DW_TAG_unspecified_type
  • -
  • DW_TAG_shared_type
  • -
-

Only entries with a DW_AT_name attribute are included, and the entry must - not be a forward declaration (DW_AT_declaration attribute with a non-zero value). - For example, using the following code:

-
-
-int main ()
-{
-  int *b = 0;
-  return *b;
-}
-
-
-

We get a few type DIEs:

-
-
-0x00000067:     TAG_base_type [5]
-                AT_encoding( DW_ATE_signed )
-                AT_name( "int" )
-                AT_byte_size( 0x04 )
-
-0x0000006e:     TAG_pointer_type [6]
-                AT_type( {0x00000067} ( int ) )
-                AT_byte_size( 0x08 )
-
-
-

The DW_TAG_pointer_type is not included because it does not have a DW_AT_name.

- -

".apple_namespaces" section should contain all DW_TAG_namespace DIEs. If - we run into a namespace that has no name this is an anonymous namespace, - and the name should be output as "(anonymous namespace)" (without the quotes). - Why? This matches the output of the abi::cxa_demangle() that is in the standard - C++ library that demangles mangled names.

-
- - -

- Language Extensions and File Format Changes -

- -
-
Objective-C Extensions
-

".apple_objc" section should contain all DW_TAG_subprogram DIEs for an - Objective-C class. The name used in the hash table is the name of the - Objective-C class itself. If the Objective-C class has a category, then an - entry is made for both the class name without the category, and for the class - name with the category. So if we have a DIE at offset 0x1234 with a name - of method "-[NSString(my_additions) stringWithSpecialString:]", we would add - an entry for "NSString" that points to DIE 0x1234, and an entry for - "NSString(my_additions)" that points to 0x1234. This allows us to quickly - track down all Objective-C methods for an Objective-C class when doing - expressions. It is needed because of the dynamic nature of Objective-C where - anyone can add methods to a class. The DWARF for Objective-C methods is also - emitted differently from C++ classes where the methods are not usually - contained in the class definition, they are scattered about across one or more - compile units. Categories can also be defined in different shared libraries. - So we need to be able to quickly find all of the methods and class functions - given the Objective-C class name, or quickly find all methods and class - functions for a class + category name. This table does not contain any selector - names, it just maps Objective-C class names (or class names + category) to all - of the methods and class functions. The selectors are added as function - basenames in the .debug_names section.

- -

In the ".apple_names" section for Objective-C functions, the full name is the - entire function name with the brackets ("-[NSString stringWithCString:]") and the - basename is the selector only ("stringWithCString:").

- -
Mach-O Changes
-

The sections names for the apple hash tables are for non mach-o files. For - mach-o files, the sections should be contained in the "__DWARF" segment with - names as follows:

-
    -
  • ".apple_names" -> "__apple_names"
  • -
  • ".apple_types" -> "__apple_types"
  • -
  • ".apple_namespaces" -> "__apple_namespac" (16 character limit)
  • -
  • ".apple_objc" -> "__apple_objc"
  • -
-
-
-
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-02 17:43:49 -0700 (Mon, 02 Apr 2012) $ -
- - - diff --git a/cpp/llvm/docs/SystemLibrary.html b/cpp/llvm/docs/SystemLibrary.html deleted file mode 100644 index 1ab7fd68..00000000 --- a/cpp/llvm/docs/SystemLibrary.html +++ /dev/null @@ -1,316 +0,0 @@ - - - - - System Library - - - - -

System Library

- - -
-

Written by Reid Spencer

-
- - - -

Abstract

-
-

This document provides some details on LLVM's System Library, located in - the source at lib/System and include/llvm/System. The - library's purpose is to shield LLVM from the differences between operating - systems for the few services LLVM needs from the operating system. Much of - LLVM is written using portability features of standard C++. However, in a few - areas, system dependent facilities are needed and the System Library is the - wrapper around those system calls.

-

By centralizing LLVM's use of operating system interfaces, we make it - possible for the LLVM tool chain and runtime libraries to be more easily - ported to new platforms since (theoretically) only lib/System needs - to be ported. This library also unclutters the rest of LLVM from #ifdef use - and special cases for specific operating systems. Such uses are replaced - with simple calls to the interfaces provided in include/llvm/System. -

-

Note that the System Library is not intended to be a complete operating - system wrapper (such as the Adaptive Communications Environment (ACE) or - Apache Portable Runtime (APR)), but only provides the functionality necessary - to support LLVM. -

The System Library was written by Reid Spencer who formulated the - design based on similar work originating from the eXtensible Programming - System (XPS). Several people helped with the effort; especially, - Jeff Cohen and Henrik Bach on the Win32 port.

-
- - -

- Keeping LLVM Portable -

-
-

In order to keep LLVM portable, LLVM developers should adhere to a set of - portability rules associated with the System Library. Adherence to these rules - should help the System Library achieve its goal of shielding LLVM from the - variations in operating system interfaces and doing so efficiently. The - following sections define the rules needed to fulfill this objective.

- - -

Don't Include System Headers

-
-

Except in lib/System, no LLVM source code should directly - #include a system header. Care has been taken to remove all such - #includes from LLVM while lib/System was being - developed. Specifically this means that header files like "unistd.h", - "windows.h", "stdio.h", and "string.h" are forbidden to be included by LLVM - source code outside the implementation of lib/System.

-

To obtain system-dependent functionality, existing interfaces to the system - found in include/llvm/System should be used. If an appropriate - interface is not available, it should be added to include/llvm/System - and implemented in lib/System for all supported platforms.

-
- - -

Don't Expose System Headers

-
-

The System Library must shield LLVM from all system headers. To - obtain system level functionality, LLVM source must - #include "llvm/System/Thing.h" and nothing else. This means that - Thing.h cannot expose any system header files. This protects LLVM - from accidentally using system specific functionality and only allows it - via the lib/System interface.

-
- - -

Use Standard C Headers

-
-

The standard C headers (the ones beginning with "c") are allowed - to be exposed through the lib/System interface. These headers and - the things they declare are considered to be platform agnostic. LLVM source - files may include them directly or obtain their inclusion through - lib/System interfaces.

-
- - -

Use Standard C++ Headers

-
-

The standard C++ headers from the standard C++ library and - standard template library may be exposed through the lib/System - interface. These headers and the things they declare are considered to be - platform agnostic. LLVM source files may include them or obtain their - inclusion through lib/System interfaces.

-
- - -

High Level Interface

-
-

The entry points specified in the interface of lib/System must be aimed at - completing some reasonably high level task needed by LLVM. We do not want to - simply wrap each operating system call. It would be preferable to wrap several - operating system calls that are always used in conjunction with one another by - LLVM.

-

For example, consider what is needed to execute a program, wait for it to - complete, and return its result code. On Unix, this involves the following - operating system calls: getenv, fork, execve, and wait. The - correct thing for lib/System to provide is a function, say - ExecuteProgramAndWait, that implements the functionality completely. - what we don't want is wrappers for the operating system calls involved.

-

There must not be a one-to-one relationship between operating - system calls and the System library's interface. Any such interface function - will be suspicious.

-
- - -

No Unused Functionality

-
-

There must be no functionality specified in the interface of lib/System - that isn't actually used by LLVM. We're not writing a general purpose - operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM - doesn't need much. This design goal aims to keep the lib/System interface - small and understandable which should foster its actual use and adoption.

-
- - -

No Duplicate Implementations

-
-

The implementation of a function for a given platform must be written - exactly once. This implies that it must be possible to apply a function's - implementation to multiple operating systems if those operating systems can - share the same implementation. This rule applies to the set of operating - systems supported for a given class of operating system (e.g. Unix, Win32). -

-
- - -

No Virtual Methods

-
-

The System Library interfaces can be called quite frequently by LLVM. In - order to make those calls as efficient as possible, we discourage the use of - virtual methods. There is no need to use inheritance for implementation - differences, it just adds complexity. The #include mechanism works - just fine.

-
- - -

No Exposed Functions

-
-

Any functions defined by system libraries (i.e. not defined by lib/System) - must not be exposed through the lib/System interface, even if the header file - for that function is not exposed. This prevents inadvertent use of system - specific functionality.

-

For example, the stat system call is notorious for having - variations in the data it provides. lib/System must not declare - stat nor allow it to be declared. Instead it should provide its own - interface to discovering information about files and directories. Those - interfaces may be implemented in terms of stat but that is strictly - an implementation detail. The interface provided by the System Library must - be implemented on all platforms (even those without stat).

-
- - -

No Exposed Data

-
-

Any data defined by system libraries (i.e. not defined by lib/System) must - not be exposed through the lib/System interface, even if the header file for - that function is not exposed. As with functions, this prevents inadvertent use - of data that might not exist on all platforms.

-
- - -

Minimize Soft Errors

-
-

Operating system interfaces will generally provide error results for every - little thing that could go wrong. In almost all cases, you can divide these - error results into two groups: normal/good/soft and abnormal/bad/hard. That - is, some of the errors are simply information like "file not found", - "insufficient privileges", etc. while other errors are much harder like - "out of space", "bad disk sector", or "system call interrupted". We'll call - the first group "soft" errors and the second group "hard" - errors.

-

lib/System must always attempt to minimize soft errors. - This is a design requirement because the - minimization of soft errors can affect the granularity and the nature of the - interface. In general, if you find that you're wanting to throw soft errors, - you must review the granularity of the interface because it is likely you're - trying to implement something that is too low level. The rule of thumb is to - provide interface functions that can't fail, except when faced with - hard errors.

-

For a trivial example, suppose we wanted to add an "OpenFileForWriting" - function. For many operating systems, if the file doesn't exist, attempting - to open the file will produce an error. However, lib/System should not - simply throw that error if it occurs because its a soft error. The problem - is that the interface function, OpenFileForWriting is too low level. It should - be OpenOrCreateFileForWriting. In the case of the soft "doesn't exist" error, - this function would just create it and then open it for writing.

-

This design principle needs to be maintained in lib/System because it - avoids the propagation of soft error handling throughout the rest of LLVM. - Hard errors will generally just cause a termination for an LLVM tool so don't - be bashful about throwing them.

-

Rules of thumb:

-
    -
  1. Don't throw soft errors, only hard errors.
  2. -
  3. If you're tempted to throw a soft error, re-think the interface.
  4. -
  5. Handle internally the most common normal/good/soft error conditions - so the rest of LLVM doesn't have to.
  6. -
-
- - -

No throw Specifications

-
-

None of the lib/System interface functions may be declared with C++ - throw() specifications on them. This requirement makes sure that the - compiler does not insert additional exception handling code into the interface - functions. This is a performance consideration: lib/System functions are at - the bottom of many call chains and as such can be frequently called. We - need them to be as efficient as possible. However, no routines in the - system library should actually throw exceptions.

-
- - -

Code Organization

-
-

Implementations of the System Library interface are separated by their - general class of operating system. Currently only Unix and Win32 classes are - defined but more could be added for other operating system classifications. - To distinguish which implementation to compile, the code in lib/System uses - the LLVM_ON_UNIX and LLVM_ON_WIN32 #defines provided via configure through the - llvm/Config/config.h file. Each source file in lib/System, after implementing - the generic (operating system independent) functionality needs to include the - correct implementation using a set of #if defined(LLVM_ON_XYZ) - directives. For example, if we had lib/System/File.cpp, we'd expect to see in - that file:

-

-  #if defined(LLVM_ON_UNIX)
-  #include "Unix/File.cpp"
-  #endif
-  #if defined(LLVM_ON_WIN32)
-  #include "Win32/File.cpp"
-  #endif
-  
-

The implementation in lib/System/Unix/File.cpp should handle all Unix - variants. The implementation in lib/System/Win32/File.cpp should handle all - Win32 variants. What this does is quickly differentiate the basic class of - operating system that will provide the implementation. The specific details - for a given platform must still be determined through the use of - #ifdef.

-
- - -

Consistent Semantics

-
-

The implementation of a lib/System interface can vary drastically between - platforms. That's okay as long as the end result of the interface function - is the same. For example, a function to create a directory is pretty straight - forward on all operating system. System V IPC on the other hand isn't even - supported on all platforms. Instead of "supporting" System V IPC, lib/System - should provide an interface to the basic concept of inter-process - communications. The implementations might use System V IPC if that was - available or named pipes, or whatever gets the job done effectively for a - given operating system. In all cases, the interface and the implementation - must be semantically consistent.

-
- - -

Bug 351

-
-

See bug 351 - for further details on the progress of this work

-
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Reid Spencer
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/TableGenFundamentals.html b/cpp/llvm/docs/TableGenFundamentals.html deleted file mode 100644 index ea9e917b..00000000 --- a/cpp/llvm/docs/TableGenFundamentals.html +++ /dev/null @@ -1,973 +0,0 @@ - - - - - TableGen Fundamentals - - - - -

TableGen Fundamentals

- - - -
-

Written by Chris Lattner

-
- - -

Introduction

- - -
- -

TableGen's purpose is to help a human develop and maintain records of -domain-specific information. Because there may be a large number of these -records, it is specifically designed to allow writing flexible descriptions and -for common features of these records to be factored out. This reduces the -amount of duplication in the description, reduces the chance of error, and -makes it easier to structure domain specific information.

- -

The core part of TableGen parses a file, instantiates -the declarations, and hands the result off to a domain-specific "TableGen backend" for processing. The current major user -of TableGen is the LLVM code generator.

- -

Note that if you work on TableGen much, and use emacs or vim, that you can -find an emacs "TableGen mode" and a vim language file in the -llvm/utils/emacs and llvm/utils/vim directories of your LLVM -distribution, respectively.

- - -

Basic concepts

- -
- -

TableGen files consist of two key parts: 'classes' and 'definitions', both -of which are considered 'records'.

- -

TableGen records have a unique name, a list of values, and a list of -superclasses. The list of values is the main data that TableGen builds for each -record; it is this that holds the domain specific information for the -application. The interpretation of this data is left to a specific TableGen backend, but the structure and format rules are -taken care of and are fixed by TableGen.

- -

TableGen definitions are the concrete form of 'records'. These -generally do not have any undefined values, and are marked with the -'def' keyword.

- -

TableGen classes are abstract records that are used to build and -describe other records. These 'classes' allow the end-user to build -abstractions for either the domain they are targeting (such as "Register", -"RegisterClass", and "Instruction" in the LLVM code generator) or for the -implementor to help factor out common properties of records (such as "FPInst", -which is used to represent floating point instructions in the X86 backend). -TableGen keeps track of all of the classes that are used to build up a -definition, so the backend can find all definitions of a particular class, such -as "Instruction".

- -

TableGen multiclasses are groups of abstract records that are -instantiated all at once. Each instantiation can result in multiple -TableGen definitions. If a multiclass inherits from another multiclass, -the definitions in the sub-multiclass become part of the current -multiclass, as if they were declared in the current multiclass.

- -
- - -

An example record

- -
- -

With no other arguments, TableGen parses the specified file and prints out -all of the classes, then all of the definitions. This is a good way to see what -the various definitions expand to fully. Running this on the X86.td -file prints this (at the time of this writing):

- -
-
-...
-def ADD32rr {   // Instruction X86Inst I
-  string Namespace = "X86";
-  dag OutOperandList = (outs GR32:$dst);
-  dag InOperandList = (ins GR32:$src1, GR32:$src2);
-  string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
-  list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
-  list<Register> Uses = [];
-  list<Register> Defs = [EFLAGS];
-  list<Predicate> Predicates = [];
-  int CodeSize = 3;
-  int AddedComplexity = 0;
-  bit isReturn = 0;
-  bit isBranch = 0;
-  bit isIndirectBranch = 0;
-  bit isBarrier = 0;
-  bit isCall = 0;
-  bit canFoldAsLoad = 0;
-  bit mayLoad = 0;
-  bit mayStore = 0;
-  bit isImplicitDef = 0;
-  bit isConvertibleToThreeAddress = 1;
-  bit isCommutable = 1;
-  bit isTerminator = 0;
-  bit isReMaterializable = 0;
-  bit isPredicable = 0;
-  bit hasDelaySlot = 0;
-  bit usesCustomInserter = 0;
-  bit hasCtrlDep = 0;
-  bit isNotDuplicable = 0;
-  bit hasSideEffects = 0;
-  bit neverHasSideEffects = 0;
-  InstrItinClass Itinerary = NoItinerary;
-  string Constraints = "";
-  string DisableEncoding = "";
-  bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
-  Format Form = MRMDestReg;
-  bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
-  ImmType ImmT = NoImm;
-  bits<3> ImmTypeBits = { 0, 0, 0 };
-  bit hasOpSizePrefix = 0;
-  bit hasAdSizePrefix = 0;
-  bits<4> Prefix = { 0, 0, 0, 0 };
-  bit hasREX_WPrefix = 0;
-  FPFormat FPForm = ?;
-  bits<3> FPFormBits = { 0, 0, 0 };
-}
-...
-
-
- -

This definition corresponds to a 32-bit register-register add instruction in -the X86. The string after the 'def' string indicates the name of the -record—"ADD32rr" in this case—and the comment at the end of -the line indicates the superclasses of the definition. The body of the record -contains all of the data that TableGen assembled for the record, indicating that -the instruction is part of the "X86" namespace, the pattern indicating how the -the instruction should be emitted into the assembly file, that it is a -two-address instruction, has a particular encoding, etc. The contents and -semantics of the information in the record is specific to the needs of the X86 -backend, and is only shown as an example.

- -

As you can see, a lot of information is needed for every instruction -supported by the code generator, and specifying it all manually would be -unmaintainable, prone to bugs, and tiring to do in the first place. Because we -are using TableGen, all of the information was derived from the following -definition:

- -
-
-let Defs = [EFLAGS],
-    isCommutable = 1,                  // X = ADD Y,Z --> X = ADD Z,Y
-    isConvertibleToThreeAddress = 1 in // Can transform into LEA.
-def ADD32rr  : I<0x01, MRMDestReg, (outs GR32:$dst),
-                                   (ins GR32:$src1, GR32:$src2),
-                 "add{l}\t{$src2, $dst|$dst, $src2}",
-                 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
-
-
- -

This definition makes use of the custom class I (extended from the -custom class X86Inst), which is defined in the X86-specific TableGen -file, to factor out the common features that instructions of its class share. A -key feature of TableGen is that it allows the end-user to define the -abstractions they prefer to use when describing their information.

- -

Each def record has a special entry called "NAME." This is the -name of the def ("ADD32rr" above). In the general case def names can -be formed from various kinds of string processing expressions and NAME -resolves to the final value obtained after resolving all of those -expressions. The user may refer to NAME anywhere she desires to use -the ultimate name of the def. NAME should not be defined anywhere -else in user code to avoid conflict problems.

- -
- - -

Running TableGen

- -
- -

TableGen runs just like any other LLVM tool. The first (optional) argument -specifies the file to read. If a filename is not specified, tblgen -reads from standard input.

- -

To be useful, one of the TableGen backends must be -used. These backends are selectable on the command line (type 'tblgen --help' for a list). For example, to get a list of all of the definitions -that subclass a particular type (which can be useful for building up an enum -list of these records), use the -print-enums option:

- -
-
-$ tblgen X86.td -print-enums -class=Register
-AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
-ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
-MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
-R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
-R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
-RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
-XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
-XMM6, XMM7, XMM8, XMM9,
-
-$ tblgen X86.td -print-enums -class=Instruction 
-ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
-ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
-ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
-ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
-ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
-
-
- -

The default backend prints out all of the records, as described above.

- -

If you plan to use TableGen, you will most likely have to write a backend that extracts the information specific to -what you need and formats it in the appropriate way.

- -
- -
- - -

TableGen syntax

- - -
- -

TableGen doesn't care about the meaning of data (that is up to the backend to -define), but it does care about syntax, and it enforces a simple type system. -This section describes the syntax and the constructs allowed in a TableGen file. -

- - -

TableGen primitives

- -
- - -

TableGen comments

- -
- -

TableGen supports BCPL style "//" comments, which run to the end of -the line, and it also supports nestable "/* */" comments.

- -
- - -

- The TableGen type system -

- -
- -

TableGen files are strongly typed, in a simple (but complete) type-system. -These types are used to perform automatic conversions, check for errors, and to -help interface designers constrain the input that they allow. Every value definition is required to have an associated type. -

- -

TableGen supports a mixture of very low-level types (such as bit) -and very high-level types (such as dag). This flexibility is what -allows it to describe a wide range of information conveniently and compactly. -The TableGen types are:

- -
-
bit
-
A 'bit' is a boolean value that can hold either 0 or 1.
- -
int
-
The 'int' type represents a simple 32-bit integer value, such as 5.
- -
string
-
The 'string' type represents an ordered sequence of characters of - arbitrary length.
- -
bits<n>
-
A 'bits' type is an arbitrary, but fixed, size integer that is broken up - into individual bits. This type is useful because it can handle some bits - being defined while others are undefined.
- -
list<ty>
-
This type represents a list whose elements are some other type. The - contained type is arbitrary: it can even be another list type.
- -
Class type
-
Specifying a class name in a type context means that the defined value - must be a subclass of the specified class. This is useful in conjunction with - the list type, for example, to constrain the elements of the - list to a common base class (e.g., a list<Register> can - only contain definitions derived from the "Register" class).
- -
dag
-
This type represents a nestable directed graph of elements.
- -
code
-
This represents a big hunk of text. This is lexically distinct from - string values because it doesn't require escapeing double quotes and other - common characters that occur in code.
-
- -

To date, these types have been sufficient for describing things that -TableGen has been used for, but it is straight-forward to extend this list if -needed.

- -
- - -

- TableGen values and expressions -

- -
- -

TableGen allows for a pretty reasonable number of different expression forms -when building up values. These forms allow the TableGen file to be written in a -natural syntax and flavor for the application. The current expression forms -supported include:

- -
-
?
-
uninitialized field
-
0b1001011
-
binary integer value
-
07654321
-
octal integer value (indicated by a leading 0)
-
7
-
decimal integer value
-
0x7F
-
hexadecimal integer value
-
"foo"
-
string value
-
[{ ... }]
-
code fragment
-
[ X, Y, Z ]<type>
-
list value. <type> is the type of the list -element and is usually optional. In rare cases, -TableGen is unable to deduce the element type in -which case the user must specify it explicitly.
-
{ a, b, c }
-
initializer for a "bits<3>" value
-
value
-
value reference
-
value{17}
-
access to one bit of a value
-
value{15-17}
-
access to multiple bits of a value
-
DEF
-
reference to a record definition
-
CLASS<val list>
-
reference to a new anonymous definition of CLASS with the specified - template arguments.
-
X.Y
-
reference to the subfield of a value
-
list[4-7,17,2-3]
-
A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from - it. Elements may be included multiple times.
-
foreach <var> = <list> in { <body> }
-
foreach <var> = <list> in <def>
-
Replicate <body> or <def>, replacing instances of - <var> with each value in <list>. <var> is scoped at the - level of the foreach loop and must not conflict with any other object - introduced in <body> or <def>. Currently only defs are - expanded within <body>. -
-
(DEF a, b)
-
a dag value. The first element is required to be a record definition, the - remaining elements in the list may be arbitrary other values, including nested - `dag' values.
-
!strconcat(a, b)
-
A string value that is the result of concatenating the 'a' and 'b' - strings.
-
str1#str2
-
"#" (paste) is a shorthand for !strconcat. It may concatenate - things that are not quoted strings, in which case an implicit - !cast<string> is done on the operand of the paste.
-
!cast<type>(a)
-
A symbol of type type obtained by looking up the string 'a' in -the symbol table. If the type of 'a' does not match type, TableGen -aborts with an error. !cast<string> is a special case in that the argument must -be an object defined by a 'def' construct.
-
!subst(a, b, c)
-
If 'a' and 'b' are of string type or are symbol references, substitute -'b' for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
-
!foreach(a, b, c)
-
For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a -dummy variable that should be declared as a member variable of an instantiated -class. This operation is analogous to $(foreach) in GNU make.
-
!head(a)
-
The first element of list 'a.'
-
!tail(a)
-
The 2nd-N elements of list 'a.'
-
!empty(a)
-
An integer {0,1} indicating whether list 'a' is empty.
-
!if(a,b,c)
-
'b' if the result of 'int' or 'bit' operator 'a' is nonzero, - 'c' otherwise.
-
!eq(a,b)
-
'bit 1' if string a is equal to string b, 0 otherwise. This - only operates on string, int and bit objects. Use !cast<string> to - compare other types of objects.
-
- -

Note that all of the values have rules specifying how they convert to values -for different types. These rules allow you to assign a value like "7" -to a "bits<4>" value, for example.

- -
- -
- - -

- Classes and definitions -

- -
- -

As mentioned in the intro, classes and definitions -(collectively known as 'records') in TableGen are the main high-level unit of -information that TableGen collects. Records are defined with a def or -class keyword, the record name, and an optional list of "template arguments". If the record has superclasses, -they are specified as a comma separated list that starts with a colon character -(":"). If value definitions or let expressions are needed for the class, they are -enclosed in curly braces ("{}"); otherwise, the record ends with a -semicolon.

- -

Here is a simple TableGen file:

- -
-
-class C { bit V = 1; }
-def X : C;
-def Y : C {
-  string Greeting = "hello";
-}
-
-
- -

This example defines two definitions, X and Y, both of -which derive from the C class. Because of this, they both get the -V bit value. The Y definition also gets the Greeting member -as well.

- -

In general, classes are useful for collecting together the commonality -between a group of records and isolating it in a single place. Also, classes -permit the specification of default values for their subclasses, allowing the -subclasses to override them as they wish.

- - -

- Value definitions -

- -
- -

Value definitions define named entries in records. A value must be defined -before it can be referred to as the operand for another value definition or -before the value is reset with a let expression. A -value is defined by specifying a TableGen type and a name. -If an initial value is available, it may be specified after the type with an -equal sign. Value definitions require terminating semicolons.

- -
- - -

- 'let' expressions -

- -
- -

A record-level let expression is used to change the value of a value -definition in a record. This is primarily useful when a superclass defines a -value that a derived class or definition wants to override. Let expressions -consist of the 'let' keyword followed by a value name, an equal sign -("="), and a new value. For example, a new class could be added to the -example above, redefining the V field for all of its subclasses:

- -
-
-class D : C { let V = 0; }
-def Z : D;
-
-
- -

In this case, the Z definition will have a zero value for its "V" -value, despite the fact that it derives (indirectly) from the C class, -because the D class overrode its value.

- -
- - -

- Class template arguments -

- -
- -

TableGen permits the definition of parameterized classes as well as normal -concrete classes. Parameterized TableGen classes specify a list of variable -bindings (which may optionally have defaults) that are bound when used. Here is -a simple example:

- -
-
-class FPFormat<bits<3> val> {
-  bits<3> Value = val;
-}
-def NotFP      : FPFormat<0>;
-def ZeroArgFP  : FPFormat<1>;
-def OneArgFP   : FPFormat<2>;
-def OneArgFPRW : FPFormat<3>;
-def TwoArgFP   : FPFormat<4>;
-def CompareFP  : FPFormat<5>;
-def CondMovFP  : FPFormat<6>;
-def SpecialFP  : FPFormat<7>;
-
-
- -

In this case, template arguments are used as a space efficient way to specify -a list of "enumeration values", each with a "Value" field set to the -specified integer.

- -

The more esoteric forms of TableGen expressions are -useful in conjunction with template arguments. As an example:

- -
-
-class ModRefVal<bits<2> val> {
-  bits<2> Value = val;
-}
-
-def None   : ModRefVal<0>;
-def Mod    : ModRefVal<1>;
-def Ref    : ModRefVal<2>;
-def ModRef : ModRefVal<3>;
-
-class Value<ModRefVal MR> {
-  // Decode some information into a more convenient format, while providing
-  // a nice interface to the user of the "Value" class.
-  bit isMod = MR.Value{0};
-  bit isRef = MR.Value{1};
-
-  // other stuff...
-}
-
-// Example uses
-def bork : Value<Mod>;
-def zork : Value<Ref>;
-def hork : Value<ModRef>;
-
-
- -

This is obviously a contrived example, but it shows how template arguments -can be used to decouple the interface provided to the user of the class from the -actual internal data representation expected by the class. In this case, -running tblgen on the example prints the following definitions:

- -
-
-def bork {      // Value
-  bit isMod = 1;
-  bit isRef = 0;
-}
-def hork {      // Value
-  bit isMod = 1;
-  bit isRef = 1;
-}
-def zork {      // Value
-  bit isMod = 0;
-  bit isRef = 1;
-}
-
-
- -

This shows that TableGen was able to dig into the argument and extract a -piece of information that was requested by the designer of the "Value" class. -For more realistic examples, please see existing users of TableGen, such as the -X86 backend.

- -
- - -

- Multiclass definitions and instances -

- -
- -

-While classes with template arguments are a good way to factor commonality -between two instances of a definition, multiclasses allow a convenient notation -for defining multiple definitions at once (instances of implicitly constructed -classes). For example, consider an 3-address instruction set whose instructions -come in two forms: "reg = reg op reg" and "reg = reg op imm" -(e.g. SPARC). In this case, you'd like to specify in one place that this -commonality exists, then in a separate place indicate what all the ops are. -

- -

-Here is an example TableGen fragment that shows this idea: -

- -
-
-def ops;
-def GPR;
-def Imm;
-class inst<int opc, string asmstr, dag operandlist>;
-
-multiclass ri_inst<int opc, string asmstr> {
-  def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-                 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
-  def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-                 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
-}
-
-// Instantiations of the ri_inst multiclass.
-defm ADD : ri_inst<0b111, "add">;
-defm SUB : ri_inst<0b101, "sub">;
-defm MUL : ri_inst<0b100, "mul">;
-...
-
-
- -

The name of the resultant definitions has the multidef fragment names - appended to them, so this defines ADD_rr, ADD_ri, - SUB_rr, etc. A defm may inherit from multiple multiclasses, - instantiating definitions from each multiclass. Using a multiclass - this way is exactly equivalent to instantiating the classes multiple - times yourself, e.g. by writing:

- -
-
-def ops;
-def GPR;
-def Imm;
-class inst<int opc, string asmstr, dag operandlist>;
-
-class rrinst<int opc, string asmstr>
-  : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-         (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
-
-class riinst<int opc, string asmstr>
-  : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
-         (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
-
-// Instantiations of the ri_inst multiclass.
-def ADD_rr : rrinst<0b111, "add">;
-def ADD_ri : riinst<0b111, "add">;
-def SUB_rr : rrinst<0b101, "sub">;
-def SUB_ri : riinst<0b101, "sub">;
-def MUL_rr : rrinst<0b100, "mul">;
-def MUL_ri : riinst<0b100, "mul">;
-...
-
-
- -

-A defm can also be used inside a multiclass providing several levels of -multiclass instanciations. -

- -
-
-class Instruction<bits<4> opc, string Name> {
-  bits<4> opcode = opc;
-  string name = Name;
-}
-
-multiclass basic_r<bits<4> opc> {
-  def rr : Instruction<opc, "rr">;
-  def rm : Instruction<opc, "rm">;
-}
-
-multiclass basic_s<bits<4> opc> {
-  defm SS : basic_r<opc>;
-  defm SD : basic_r<opc>;
-  def X : Instruction<opc, "x">;
-}
-
-multiclass basic_p<bits<4> opc> {
-  defm PS : basic_r<opc>;
-  defm PD : basic_r<opc>;
-  def Y : Instruction<opc, "y">;
-}
-
-defm ADD : basic_s<0xf>, basic_p<0xf>;
-...
-
-// Results
-def ADDPDrm { ...
-def ADDPDrr { ...
-def ADDPSrm { ...
-def ADDPSrr { ...
-def ADDSDrm { ...
-def ADDSDrr { ...
-def ADDY { ...
-def ADDX { ...
-
-
- -

-defm declarations can inherit from classes too, the -rule to follow is that the class list must start after the -last multiclass, and there must be at least one multiclass -before them. -

- -
-
-class XD { bits<4> Prefix = 11; }
-class XS { bits<4> Prefix = 12; }
-
-class I<bits<4> op> {
-  bits<4> opcode = op;
-}
-
-multiclass R {
-  def rr : I<4>;
-  def rm : I<2>;
-}
-
-multiclass Y {
-  defm SS : R, XD;
-  defm SD : R, XS;
-}
-
-defm Instr : Y;
-
-// Results
-def InstrSDrm {
-  bits<4> opcode = { 0, 0, 1, 0 };
-  bits<4> Prefix = { 1, 1, 0, 0 };
-}
-...
-def InstrSSrr {
-  bits<4> opcode = { 0, 1, 0, 0 };
-  bits<4> Prefix = { 1, 0, 1, 1 };
-}
-
-
- -
- -
- - -

- File scope entities -

- -
- - -

- File inclusion -

- -
-

TableGen supports the 'include' token, which textually substitutes -the specified file in place of the include directive. The filename should be -specified as a double quoted string immediately after the 'include' -keyword. Example:

- -
-
-include "foo.td"
-
-
- -
- - -

- 'let' expressions -

- -
- -

"Let" expressions at file scope are similar to "let" -expressions within a record, except they can specify a value binding for -multiple records at a time, and may be useful in certain other cases. -File-scope let expressions are really just another way that TableGen allows the -end-user to factor out commonality from the records.

- -

File-scope "let" expressions take a comma-separated list of bindings to -apply, and one or more records to bind the values in. Here are some -examples:

- -
-
-let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
-  def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
-
-let isCall = 1 in
-  // All calls clobber the non-callee saved registers...
-  let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
-              MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
-              XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
-    def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
-                           "call\t${dst:call}", []>;
-    def CALL32r     : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
-                        "call\t{*}$dst", [(X86call GR32:$dst)]>;
-    def CALL32m     : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
-                        "call\t{*}$dst", []>;
-  }
-
-
- -

File-scope "let" expressions are often useful when a couple of definitions -need to be added to several records, and the records do not otherwise need to be -opened, as in the case with the CALL* instructions above.

- -

It's also possible to use "let" expressions inside multiclasses, providing -more ways to factor out commonality from the records, specially if using -several levels of multiclass instanciations. This also avoids the need of using -"let" expressions within subsequent records inside a multiclass.

- -
-multiclass basic_r<bits<4> opc> {
-  let Predicates = [HasSSE2] in {
-    def rr : Instruction<opc, "rr">;
-    def rm : Instruction<opc, "rm">;
-  }
-  let Predicates = [HasSSE3] in
-    def rx : Instruction<opc, "rx">;
-}
-
-multiclass basic_ss<bits<4> opc> {
-  let IsDouble = 0 in
-    defm SS : basic_r<opc>;
-
-  let IsDouble = 1 in
-    defm SD : basic_r<opc>;
-}
-
-defm ADD : basic_ss<0xf>;
-
-
- - -

- Looping -

- -
-

TableGen supports the 'foreach' block, which textually replicates -the loop body, substituting iterator values for iterator references in the -body. Example:

- -
-
-foreach i = [0, 1, 2, 3] in {
-  def R#i : Register<...>;
-  def F#i : Register<...>;
-}
-
-
- -

This will create objects R0, R1, R2 and -R3. foreach blocks may be nested. If there is only -one item in the body the braces may be elided:

- -
-
-foreach i = [0, 1, 2, 3] in
-  def R#i : Register<...>;
-
-
-
- -
- -
- -
- - -

Code Generator backend info

- - -
- -

Expressions used by code generator to describe instructions and isel -patterns:

- -
-
(implicit a)
-
an implicitly defined physical register. This tells the dag instruction - selection emitter the input pattern's extra definitions matches implicit - physical register definitions.
-
-
- - -

TableGen backends

- - -
- -

TODO: How they work, how to write one. This section should not contain -details about any particular backend, except maybe -print-enums as an example. -This should highlight the APIs in TableGen/Record.h.

- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/TestSuiteMakefileGuide.html b/cpp/llvm/docs/TestSuiteMakefileGuide.html deleted file mode 100644 index 876fe426..00000000 --- a/cpp/llvm/docs/TestSuiteMakefileGuide.html +++ /dev/null @@ -1,351 +0,0 @@ - - - - - LLVM test-suite Makefile Guide - - - - -

- LLVM test-suite Makefile Guide -

- -
    -
  1. Overview
  2. -
  3. Test suite structure
  4. -
  5. Running the test suite - -
  6. -
- -
-

Written by John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner

-
- - -

Overview

- - -
- -

This document describes the features of the Makefile-based LLVM -test-suite. This way of interacting with the test-suite is deprecated in favor -of running the test-suite using LNT, but may continue to prove useful for some -users. See the Testing -Guide's test-suite -Quickstart section for more information.

- -
- - -

Test suite Structure

- - -
- -

The test-suite module contains a number of programs that can be compiled -with LLVM and executed. These programs are compiled using the native compiler -and various LLVM backends. The output from the program compiled with the -native compiler is assumed correct; the results from the other programs are -compared to the native program output and pass if they match.

- -

When executing tests, it is usually a good idea to start out with a subset of -the available tests or programs. This makes test run times smaller at first and -later on this is useful to investigate individual test failures. To run some -test only on a subset of programs, simply change directory to the programs you -want tested and run gmake there. Alternatively, you can run a different -test using the TEST variable to change what tests or run on the -selected programs (see below for more info).

- -

In addition for testing correctness, the test-suite directory also -performs timing tests of various LLVM optimizations. It also records -compilation times for the compilers and the JIT. This information can be -used to compare the effectiveness of LLVM's optimizations and code -generation.

- -

test-suite tests are divided into three types of tests: MultiSource, -SingleSource, and External.

- -
    -
  • test-suite/SingleSource -

    The SingleSource directory contains test programs that are only a single -source file in size. These are usually small benchmark programs or small -programs that calculate a particular value. Several such programs are grouped -together in each directory.

  • - -
  • test-suite/MultiSource -

    The MultiSource directory contains subdirectories which contain entire -programs with multiple source files. Large benchmarks and whole applications -go here.

  • - -
  • test-suite/External -

    The External directory contains Makefiles for building code that is external -to (i.e., not distributed with) LLVM. The most prominent members of this -directory are the SPEC 95 and SPEC 2000 benchmark suites. The External -directory does not contain these actual tests, but only the Makefiles that know -how to properly compile these programs from somewhere else. The presence and -location of these external programs is configured by the test-suite -configure script.

  • -
- -

Each tree is then subdivided into several categories, including applications, -benchmarks, regression tests, code that is strange grammatically, etc. These -organizations should be relatively self explanatory.

- -

Some tests are known to fail. Some are bugs that we have not fixed yet; -others are features that we haven't added yet (or may never add). In the -regression tests, the result for such tests will be XFAIL (eXpected FAILure). -In this way, you can tell the difference between an expected and unexpected -failure.

- -

The tests in the test suite have no such feature at this time. If the -test passes, only warnings and other miscellaneous output will be generated. If -a test fails, a large <program> FAILED message will be displayed. This -will help you separate benign warnings from actual test failures.

- -
- - -

Running the test suite

- - -
- -

First, all tests are executed within the LLVM object directory tree. They -are not executed inside of the LLVM source tree. This is because the -test suite creates temporary files during execution.

- -

To run the test suite, you need to use the following steps:

- -
    -
  1. cd into the llvm/projects directory in your source tree. -
  2. - -
  3. Check out the test-suite module with:

    - -
    -
    -% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
    -
    -
    -

    This will get the test suite into llvm/projects/test-suite.

    -
  4. -
  5. Configure and build llvm.

  6. -
  7. Configure and build llvm-gcc.

  8. -
  9. Install llvm-gcc somewhere.

  10. -
  11. Re-configure llvm from the top level of - each build tree (LLVM object directory tree) in which you want - to run the test suite, just as you do before building LLVM.

    -

    During the re-configuration, you must either: (1) - have llvm-gcc you just built in your path, or (2) - specify the directory where your just-built llvm-gcc is - installed using --with-llvmgccdir=$LLVM_GCC_DIR.

    -

    You must also tell the configure machinery that the test suite - is available so it can be configured for your build tree:

    -
    -
    -% cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure [--with-llvmgccdir=$LLVM_GCC_DIR]
    -
    -
    -

    [Remember that $LLVM_GCC_DIR is the directory where you - installed llvm-gcc, not its src or obj directory.]

    -
  12. - -
  13. You can now run the test suite from your build tree as follows:

    -
    -
    -% cd $LLVM_OBJ_ROOT/projects/test-suite
    -% make
    -
    -
    -
  14. -
-

Note that the second and third steps only need to be done once. After you -have the suite checked out and configured, you don't need to do it again (unless -the test code or configure script changes).

- - -

- Configuring External Tests -

- - -
-

In order to run the External tests in the test-suite - module, you must specify --with-externals. This - must be done during the re-configuration step (see above), - and the llvm re-configuration must recognize the - previously-built llvm-gcc. If any of these is missing or - neglected, the External tests won't work.

-
-
--with-externals
-
--with-externals=<directory>
-
- This tells LLVM where to find any external tests. They are expected to be - in specifically named subdirectories of <directory>. - If directory is left unspecified, - configure uses the default value - /home/vadve/shared/benchmarks/speccpu2000/benchspec. - Subdirectory names known to LLVM include: -
-
spec95
-
speccpu2000
-
speccpu2006
-
povray31
-
- Others are added from time to time, and can be determined from - configure. -
- - -

- Running different tests -

- -
-

In addition to the regular "whole program" tests, the test-suite -module also provides a mechanism for compiling the programs in different ways. -If the variable TEST is defined on the gmake command line, the test system will -include a Makefile named TEST.<value of TEST variable>.Makefile. -This Makefile can modify build rules to yield different results.

- -

For example, the LLVM nightly tester uses TEST.nightly.Makefile to -create the nightly test reports. To run the nightly tests, run gmake -TEST=nightly.

- -

There are several TEST Makefiles available in the tree. Some of them are -designed for internal LLVM research and will not work outside of the LLVM -research group. They may still be valuable, however, as a guide to writing your -own TEST Makefile for any optimization or analysis passes that you develop with -LLVM.

- -
- - -

- Generating test output -

- -
-

There are a number of ways to run the tests and generate output. The most - simple one is simply running gmake with no arguments. This will - compile and run all programs in the tree using a number of different methods - and compare results. Any failures are reported in the output, but are likely - drowned in the other output. Passes are not reported explicitely.

- -

Somewhat better is running gmake TEST=sometest test, which runs - the specified test and usually adds per-program summaries to the output - (depending on which sometest you use). For example, the nightly test - explicitely outputs TEST-PASS or TEST-FAIL for every test after each program. - Though these lines are still drowned in the output, it's easy to grep the - output logs in the Output directories.

- -

Even better are the report and report.format targets - (where format is one of html, csv, text or - graphs). The exact contents of the report are dependent on which - TEST you are running, but the text results are always shown at the - end of the run and the results are always stored in the - report.<type>.format file (when running with - TEST=<type>). - - The report also generate a file called - report.<type>.raw.out containing the output of the entire test - run. -

- - -

- Writing custom tests for the test suite -

- - -
- -

Assuming you can run the test suite, (e.g. "gmake TEST=nightly report" -should work), it is really easy to run optimizations or code generator -components against every program in the tree, collecting statistics or running -custom checks for correctness. At base, this is how the nightly tester works, -it's just one example of a general framework.

- -

Lets say that you have an LLVM optimization pass, and you want to see how -many times it triggers. First thing you should do is add an LLVM -statistic to your pass, which -will tally counts of things you care about.

- -

Following this, you can set up a test and a report that collects these and -formats them for easy viewing. This consists of two files, a -"test-suite/TEST.XXX.Makefile" fragment (where XXX is the name of your -test) and a "test-suite/TEST.XXX.report" file that indicates how to -format the output into a table. There are many example reports of various -levels of sophistication included with the test suite, and the framework is very -general.

- -

If you are interested in testing an optimization pass, check out the -"libcalls" test as an example. It can be run like this:

- -

-
-% cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
-% make TEST=libcalls report
-
-
- -

This will do a bunch of stuff, then eventually print a table like this:

- -
-
-Name                                  | total | #exit |
-...
-FreeBench/analyzer/analyzer           | 51    | 6     | 
-FreeBench/fourinarow/fourinarow       | 1     | 1     | 
-FreeBench/neural/neural               | 19    | 9     | 
-FreeBench/pifft/pifft                 | 5     | 3     | 
-MallocBench/cfrac/cfrac               | 1     | *     | 
-MallocBench/espresso/espresso         | 52    | 12    | 
-MallocBench/gs/gs                     | 4     | *     | 
-Prolangs-C/TimberWolfMC/timberwolfmc  | 302   | *     | 
-Prolangs-C/agrep/agrep                | 33    | 12    | 
-Prolangs-C/allroots/allroots          | *     | *     | 
-Prolangs-C/assembler/assembler        | 47    | *     | 
-Prolangs-C/bison/mybison              | 74    | *     | 
-...
-
-
- -

This basically is grepping the -stats output and displaying it in a table. -You can also use the "TEST=libcalls report.html" target to get the table in HTML -form, similarly for report.csv and report.tex.

- -

The source for this is in test-suite/TEST.libcalls.*. The format is pretty -simple: the Makefile indicates how to run the test (in this case, -"opt -simplify-libcalls -stats"), and the report contains one line for -each column of the output. The first value is the header for the column and the -second is the regex to grep the output of the command for. There are lots of -example reports that can do fancy stuff.

- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date$ -
- - diff --git a/cpp/llvm/docs/TestingGuide.html b/cpp/llvm/docs/TestingGuide.html deleted file mode 100644 index 036a1772..00000000 --- a/cpp/llvm/docs/TestingGuide.html +++ /dev/null @@ -1,906 +0,0 @@ - - - - - LLVM Testing Infrastructure Guide - - - - -

- LLVM Testing Infrastructure Guide -

- -
    -
  1. Overview
  2. -
  3. Requirements
  4. -
  5. LLVM testing infrastructure organization - -
  6. -
  7. Quick start - -
  8. -
  9. Regression test structure - -
  10. -
  11. test-suite Overview - -
  12. -
- -
-

Written by John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner

-
- - -

Overview

- - -
- -

This document is the reference manual for the LLVM testing infrastructure. It -documents the structure of the LLVM testing infrastructure, the tools needed to -use it, and how to add and run tests.

- -
- - -

Requirements

- - -
- -

In order to use the LLVM testing infrastructure, you will need all of the -software required to build LLVM, as well -as Python 2.4 or later.

- -
- - -

LLVM testing infrastructure organization

- - -
- -

The LLVM testing infrastructure contains two major categories of tests: -regression tests and whole programs. The regression tests are contained inside -the LLVM repository itself under llvm/test and are expected to always -pass -- they should be run before every commit.

- -

The whole programs tests are referred to as the "LLVM test suite" (or -"test-suite") and are in the test-suite module in subversion. For -historical reasons, these tests are also referred to as the "nightly tests" in -places, which is less ambiguous than "test-suite" and remains in use although we -run them much more often than nightly.

- - -

Regression tests

- - -
- -

The regression tests are small pieces of code that test a specific feature of -LLVM or trigger a specific bug in LLVM. They are usually written in LLVM -assembly language, but can be written in other languages if the test targets a -particular language front end (and the appropriate --with-llvmgcc -options were used at configure time of the llvm module). These -tests are driven by the 'lit' testing tool, which is part of LLVM.

- -

These code fragments are not complete programs. The code generated -from them is never executed to determine correct behavior.

- -

These code fragment tests are located in the llvm/test -directory.

- -

Typically when a bug is found in LLVM, a regression test containing -just enough code to reproduce the problem should be written and placed -somewhere underneath this directory. In most cases, this will be a small -piece of LLVM assembly language code, often distilled from an actual -application or benchmark.

- -
- - -

test-suite

- - -
- -

The test suite contains whole programs, which are pieces of code which can be -compiled and linked into a stand-alone program that can be executed. These -programs are generally written in high level languages such as C or C++.

- -

These programs are compiled using a user specified compiler and set of flags, -and then executed to capture the program output and timing information. The -output of these programs is compared to a reference output to ensure that the -program is being compiled correctly.

- -

In addition to compiling and executing programs, whole program tests serve as -a way of benchmarking LLVM performance, both in terms of the efficiency of the -programs generated as well as the speed with which LLVM compiles, optimizes, and -generates code.

- -

The test-suite is located in the test-suite Subversion module.

- -
- - -

Debugging Information tests

- - -
- -

The test suite contains tests to check quality of debugging information. -The test are written in C based languages or in LLVM assembly language.

- -

These tests are compiled and run under a debugger. The debugger output -is checked to validate of debugging information. See README.txt in the -test suite for more information . This test suite is located in the -debuginfo-tests Subversion module.

- -
- -
- - -

Quick start

- - -
- -

The tests are located in two separate Subversion modules. The regressions - tests are in the main "llvm" module under the directory - llvm/test (so you get these tests for free with the main llvm - tree). Use "make check-all" to run the regression tests after building - LLVM.

- -

The more comprehensive test suite that includes whole programs in C and C++ - is in the test-suite - module. See test-suite Quickstart - for more information on running these tests.

- - -

Regression tests

-
- -

To run all of the LLVM regression tests, use master Makefile in - the llvm/test directory:

- -
-
-% gmake -C llvm/test
-
-
- -

or

- -
-
-% gmake check
-
-
- -

If you have Clang checked out and built, -you can run the LLVM and Clang tests simultaneously using:

- -

or

- -
-
-% gmake check-all
-
-
- -

To run the tests with Valgrind (Memcheck by default), just append -VG=1 to the commands above, e.g.:

- -
-
-% gmake check VG=1
-
-
- -

To run individual tests or subsets of tests, you can use the 'llvm-lit' -script which is built as part of LLVM. For example, to run the -'Integer/BitCast.ll' test by itself you can run:

- -
-
-% llvm-lit ~/llvm/test/Integer/BitCast.ll 
-
-
- -

or to run all of the ARM CodeGen tests:

- -
-
-% llvm-lit ~/llvm/test/CodeGen/ARM
-
-
- -

For more information on using the 'lit' tool, see 'llvm-lit --help' or the -'lit' man page.

- -
- - -

Debugging Information tests

-
- -
- -

To run debugging information tests simply checkout the tests inside -clang/test directory.

- -
-
-%cd clang/test
-% svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests
-
-
- -

These tests are already set up to run as part of clang regression tests.

- -
- -
- -
- - -

Regression test structure

- -
-

The LLVM regression tests are driven by 'lit' and are located in - the llvm/test directory. - -

This directory contains a large array of small tests - that exercise various features of LLVM and to ensure that regressions do not - occur. The directory is broken into several sub-directories, each focused on - a particular area of LLVM. A few of the important ones are:

- -
    -
  • Analysis: checks Analysis passes.
  • -
  • Archive: checks the Archive library.
  • -
  • Assembler: checks Assembly reader/writer functionality.
  • -
  • Bitcode: checks Bitcode reader/writer functionality.
  • -
  • CodeGen: checks code generation and each target.
  • -
  • Features: checks various features of the LLVM language.
  • -
  • Linker: tests bitcode linking.
  • -
  • Transforms: tests each of the scalar, IPO, and utility - transforms to ensure they make the right transformations.
  • -
  • Verifier: tests the IR verifier.
  • -
- - -

Writing new regression tests

- -
-

The regression test structure is very simple, but does require some - information to be set. This information is gathered via configure and - is written to a file, lit.site.cfg - in llvm/test. The llvm/test Makefile does this work for - you.

- -

In order for the regression tests to work, each directory of tests must - have a lit.local.cfg file. Lit looks for this file to determine how - to run the tests. This file is just Python code and thus is very flexible, - but we've standardized it for the LLVM regression tests. If you're adding a - directory of tests, just copy lit.local.cfg from another directory to - get running. The standard lit.local.cfg simply specifies which files - to look in for tests. Any directory that contains only directories does not - need the lit.local.cfg file. Read the - Lit documentation for more - information.

- -

The llvm-runtests function looks at each file that is passed to - it and gathers any lines together that match "RUN:". These are the "RUN" lines - that specify how the test is to be run. So, each test script must contain - RUN lines if it is to do anything. If there are no RUN lines, the - llvm-runtests function will issue an error and the test will - fail.

- -

RUN lines are specified in the comments of the test program using the - keyword RUN followed by a colon, and lastly the command (pipeline) - to execute. Together, these lines form the "script" that - llvm-runtests executes to run the test case. The syntax of the - RUN lines is similar to a shell's syntax for pipelines including I/O - redirection and variable substitution. However, even though these lines - may look like a shell script, they are not. RUN lines are interpreted - directly by the Tcl exec command. They are never executed by a - shell. Consequently the syntax differs from normal shell script syntax in a - few ways. You can specify as many RUN lines as needed.

- -

lit performs substitution on each RUN line to replace LLVM tool - names with the full paths to the executable built for each tool (in - $(LLVM_OBJ_ROOT)/$(BuildMode)/bin). This ensures that lit does not - invoke any stray LLVM tools in the user's path during testing.

- -

Each RUN line is executed on its own, distinct from other lines unless - its last character is \. This continuation character causes the RUN - line to be concatenated with the next one. In this way you can build up long - pipelines of commands without making huge line lengths. The lines ending in - \ are concatenated until a RUN line that doesn't end in \ is - found. This concatenated set of RUN lines then constitutes one execution. - Tcl will substitute variables and arrange for the pipeline to be executed. If - any process in the pipeline fails, the entire line (and test case) fails too. -

- -

Below is an example of legal RUN lines in a .ll file:

- -
-
-; RUN: llvm-as < %s | llvm-dis > %t1
-; RUN: llvm-dis < %s.bc-13 > %t2
-; RUN: diff %t1 %t2
-
-
- -

As with a Unix shell, the RUN: lines permit pipelines and I/O redirection - to be used. However, the usage is slightly different than for Bash. To check - what's legal, see the documentation for the - Tcl exec - command and the - tutorial. - The major differences are:

-
    -
  • You can't do 2>&1. That will cause Tcl to write to a - file named &1. Usually this is done to get stderr to go through - a pipe. You can do that in tcl with |& so replace this idiom: - ... 2>&1 | grep with ... |& grep
  • -
  • You can only redirect to a file, not to another descriptor and not from - a here document.
  • -
  • tcl supports redirecting to open files with the @ syntax but you - shouldn't use that here.
  • -
- -

There are some quoting rules that you must pay attention to when writing - your RUN lines. In general nothing needs to be quoted. Tcl won't strip off any - quote characters so they will get passed to the invoked program. For - example:

- -
-
-... | grep 'find this string'
-
-
- -

This will fail because the ' characters are passed to grep. This would - instruction grep to look for 'find in the files this and - string'. To avoid this use curly braces to tell Tcl that it should - treat everything enclosed as one value. So our example would become:

- -
-
-... | grep {find this string}
-
-
- -

Additionally, the characters [ and ] are treated - specially by Tcl. They tell Tcl to interpret the content as a command to - execute. Since these characters are often used in regular expressions this can - have disastrous results and cause the entire test run in a directory to fail. - For example, a common idiom is to look for some basicblock number:

- -
-
-... | grep bb[2-8]
-
-
- -

This, however, will cause Tcl to fail because its going to try to execute - a program named "2-8". Instead, what you want is this:

- -
-
-... | grep {bb\[2-8\]}
-
-
- -

Finally, if you need to pass the \ character down to a program, - then it must be doubled. This is another Tcl special character. So, suppose - you had: - -

-
-... | grep 'i32\*'
-
-
- -

This will fail to match what you want (a pointer to i32). First, the - ' do not get stripped off. Second, the \ gets stripped off - by Tcl so what grep sees is: 'i32*'. That's not likely to match - anything. To resolve this you must use \\ and the {}, like - this:

- -
-
-... | grep {i32\\*}
-
-
- -

If your system includes GNU grep, make sure -that GREP_OPTIONS is not set in your environment. Otherwise, -you may get invalid results (both false positives and false -negatives).

- -
- - -

The FileCheck utility

- - -
- -

A powerful feature of the RUN: lines is that it allows any arbitrary commands - to be executed as part of the test harness. While standard (portable) unix - tools like 'grep' work fine on run lines, as you see above, there are a lot - of caveats due to interaction with Tcl syntax, and we want to make sure the - run lines are portable to a wide range of systems. Another major problem is - that grep is not very good at checking to verify that the output of a tools - contains a series of different output in a specific order. The FileCheck - tool was designed to help with these problems.

- -

FileCheck (whose basic command line arguments are described in the FileCheck man page is - designed to read a file to check from standard input, and the set of things - to verify from a file specified as a command line argument. 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, -let's look at the rest of the .ll file (after the RUN line):

- -
-
-define void @sub1(i32* %p, i32 %v) {
-entry:
-; CHECK: sub1:
-; CHECK: subl
-        %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
-        ret void
-}
-
-define void @inc4(i64* %p) {
-entry:
-; CHECK: inc4:
-; CHECK: incq
-        %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.

- - -

- 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:              | FileCheck %s -check-prefix=X32
-; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
-; RUN:              | FileCheck %s -check-prefix=X64
-
-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
-; X32: pinsrd_1:
-; X32:    pinsrd $1, 4(%esp), %xmm0
-
-; X64: pinsrd_1:
-; X64:    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.

- -
- - -

- 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
-        
-; CHECK: t2:
-; CHECK: 	movl	8(%esp), %eax
-; CHECK-NEXT: 	movapd	(%eax), %xmm0
-; CHECK-NEXT: 	movhpd	12(%esp), %xmm0
-; CHECK-NEXT: 	movl	4(%esp), %eax
-; CHECK-NEXT: 	movapd	%xmm0, (%eax)
-; CHECK-NEXT: 	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.

- -
- - -

- The "CHECK-NOT:" directive -

- -
- -

The CHECK-NOT: directive is used to verify that a string doesn't occur -between two matches (or the first match and the beginning of the file). For -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
-; CHECK: @coerce_offset0
-; CHECK-NOT: load
-; CHECK: ret i8
-}
-
-
- -
- - -

- 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: {{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	{{[0-9]+}}(%esp), {{%xmm[0-7]}}
-
-
- -

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 -{{[{][{]}} as your pattern.

- -
- - -

- 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	[[REGISTER:%[a-z]+]]
-; CHECK:    andw	{{.*}}[[REGISTER]]
-
-
- -

The first check line matches a regex (%[a-z]+) 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 [[ ]] pairs, are named, and their names can be -formed with the regex "[a-zA-Z][a-zA-Z0-9]*". 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 -"CHECK: [[XYZ:.*]]x[[XYZ]]" 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. -

- -
- -
- - -

Variables and substitutions

- -
-

With a RUN line there are a number of substitutions that are permitted. In - general, any Tcl variable that is available in the substitute - function (in test/lib/llvm.exp) can be substituted into a RUN line. - To make a substitution just write the variable's name preceded by a $. - Additionally, for compatibility reasons with previous versions of the test - library, certain names can be accessed with an alternate syntax: a % prefix. - These alternates are deprecated and may go away in a future version. -

-

Here are the available variable names. The alternate syntax is listed in - parentheses.

- -
-
$test (%s)
-
The full path to the test case's source. This is suitable for passing - on the command line as the input to an llvm tool.
- -
$srcdir
-
The source directory from where the "make check" was run.
- -
objdir
-
The object directory that corresponds to the $srcdir.
- -
subdir
-
A partial path from the test directory that contains the - sub-directory that contains the test source being executed.
- -
srcroot
-
The root directory of the LLVM src tree.
- -
objroot
-
The root directory of the LLVM object tree. This could be the same - as the srcroot.
- -
path
-
The path to the directory that contains the test case source. This is - for locating any supporting files that are not generated by the test, but - used by the test.
- -
tmp
-
The path to a temporary file name that could be used for this test case. - The file name won't conflict with other test cases. You can append to it if - you need multiple temporaries. This is useful as the destination of some - redirected output.
- -
target_triplet (%target_triplet)
-
The target triplet that corresponds to the current host machine (the one - running the test cases). This should probably be called "host".
- -
link (%link)
-
This full link command used to link LLVM executables. This has all the - configured -I, -L and -l options.
- -
shlibext (%shlibext)
-
The suffix for the host platforms share library (dll) files. This - includes the period as the first character.
-
-

To add more variables, two things need to be changed. First, add a line in - the test/Makefile that creates the site.exp file. This will - "set" the variable as a global in the site.exp file. Second, in the - test/lib/llvm.exp file, in the substitute proc, add the variable name - to the list of "global" declarations at the beginning of the proc. That's it, - the variable can then be used in test scripts.

-
- - -

Other Features

- -
-

To make RUN line writing easier, there are several shell scripts located - in the llvm/test/Scripts directory. This directory is in the PATH - when running tests, so you can just call these scripts using their name. For - example:

-
-
ignore
-
This script runs its arguments and then always returns 0. This is useful - in cases where the test needs to cause a tool to generate an error (e.g. to - check the error output). However, any program in a pipeline that returns a - non-zero result will cause the test to fail. This script overcomes that - issue and nicely documents that the test case is purposefully ignoring the - result code of the tool
- -
not
-
This script runs its arguments and then inverts the result code from - it. Zero result codes become 1. Non-zero result codes become 0. This is - useful to invert the result of a grep. For example "not grep X" means - succeed only if you don't find X in the input.
-
- -

Sometimes it is necessary to mark a test case as "expected fail" or XFAIL. - You can easily mark a test as XFAIL just by including XFAIL: on a - line near the top of the file. This signals that the test case should succeed - if the test fails. Such test cases are counted separately by the testing tool. To - specify an expected fail, use the XFAIL keyword in the comments of the test - program followed by a colon and one or more regular expressions (separated by - a comma). The regular expressions allow you to XFAIL the test conditionally by - host platform. The regular expressions following the : are matched against the - target triplet for the host machine. If there is a match, the test is expected - to fail. If not, the test is expected to succeed. To XFAIL everywhere just - specify XFAIL: *. Here is an example of an XFAIL line:

- -
-
-; XFAIL: darwin,sun
-
-
- -

To make the output more useful, the llvm_runtest function wil - scan the lines of the test case for ones that contain a pattern that matches - PR[0-9]+. This is the syntax for specifying a PR (Problem Report) number that - is related to the test case. The number after "PR" specifies the LLVM bugzilla - number. When a PR number is specified, it will be used in the pass/fail - reporting. This is useful to quickly get some context when a test fails.

- -

Finally, any line that contains "END." will cause the special - interpretation of lines to terminate. This is generally done right after the - last RUN: line. This has two side effects: (a) it prevents special - interpretation of lines that are part of the test program, not the - instructions to the test case, and (b) it speeds things up for really big test - cases by avoiding interpretation of the remainder of the file.

- -
- -
- - -

test-suite Overview

- - -
- -

The test-suite module contains a number of programs that can be -compiled and executed. The test-suite includes reference outputs for -all of the programs, so that the output of the executed program can be checked -for correctness.

- -

test-suite tests are divided into three types of tests: MultiSource, -SingleSource, and External.

- -
    -
  • test-suite/SingleSource -

    The SingleSource directory contains test programs that are only a single -source file in size. These are usually small benchmark programs or small -programs that calculate a particular value. Several such programs are grouped -together in each directory.

  • - -
  • test-suite/MultiSource -

    The MultiSource directory contains subdirectories which contain entire -programs with multiple source files. Large benchmarks and whole applications -go here.

  • - -
  • test-suite/External -

    The External directory contains Makefiles for building code that is external -to (i.e., not distributed with) LLVM. The most prominent members of this -directory are the SPEC 95 and SPEC 2000 benchmark suites. The External -directory does not contain these actual tests, but only the Makefiles that know -how to properly compile these programs from somewhere else. When -using LNT, use the --test-externals option to include these -tests in the results.

  • -
-
- - -

test-suite Quickstart

- - -
-

The modern way of running the test-suite is focused on testing and -benchmarking complete compilers using -the LNT testing infrastructure.

- -

For more information on using LNT to execute the test-suite, please -see the LNT Quickstart -documentation.

-
- - -

test-suite Makefiles

- - -
-

Historically, the test-suite was executed using a complicated setup -of Makefiles. The LNT based approach above is recommended for most users, but -there are some testing scenarios which are not supported by the LNT approach. In -addition, LNT currently uses the Makefile setup under the covers and so -developers who are interested in how LNT works under the hood may want to -understand the Makefile based setup.

- -

For more information on the test-suite Makefile setup, please see -the Test Suite Makefile Guide.

-
- - - -
-
- Valid CSS - Valid HTML 4.01 - - John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-18 01:02:25 -0700 (Wed, 18 Apr 2012) $ -
- - diff --git a/cpp/llvm/docs/WritingAnLLVMBackend.html b/cpp/llvm/docs/WritingAnLLVMBackend.html deleted file mode 100644 index f387b001..00000000 --- a/cpp/llvm/docs/WritingAnLLVMBackend.html +++ /dev/null @@ -1,2533 +0,0 @@ - - - - - Writing an LLVM Compiler Backend - - - - - -

- Writing an LLVM Compiler Backend -

- -
    -
  1. Introduction - -
  2. Target Machine
  3. -
  4. Target Registration
  5. -
  6. Register Set and Register Classes -
  7. -
  8. Instruction Set -
  9. -
  10. Instruction Selector -
  11. -
  12. Assembly Printer
  13. -
  14. Subtarget Support
  15. -
  16. JIT Support -
  17. -
- -
-

Written by Mason Woo and - Misha Brukman

-
- - -

- Introduction -

- - -
- -

-This document describes techniques for writing compiler backends that convert -the LLVM Intermediate Representation (IR) to code for a specified machine or -other languages. Code intended for a specific machine can take the form of -either assembly code or binary code (usable for a JIT compiler). -

- -

-The backend of LLVM features a target-independent code generator that may create -output for several types of target CPUs — including X86, PowerPC, ARM, -and SPARC. The backend may also be used to generate code targeted at SPUs of the -Cell processor or GPUs to support the execution of compute kernels. -

- -

-The document focuses on existing examples found in subdirectories -of llvm/lib/Target in a downloaded LLVM release. In particular, this -document focuses on the example of creating a static compiler (one that emits -text assembly) for a SPARC target, because SPARC has fairly standard -characteristics, such as a RISC instruction set and straightforward calling -conventions. -

- -

- Audience -

- -
- -

-The audience for this document is anyone who needs to write an LLVM backend to -generate code for a specific hardware or software target. -

- -
- -

- Prerequisite Reading -

- -
- -

-These essential documents must be read before reading this document: -

- -
    -
  • LLVM Language Reference - Manual — a reference manual for the LLVM assembly language.
  • - -
  • The LLVM - Target-Independent Code Generator — a guide to the components - (classes and code generation algorithms) for translating the LLVM internal - representation into machine code for a specified target. Pay particular - attention to the descriptions of code generation stages: Instruction - Selection, Scheduling and Formation, SSA-based Optimization, Register - Allocation, Prolog/Epilog Code Insertion, Late Machine Code Optimizations, - and Code Emission.
  • - -
  • TableGen - Fundamentals —a document that describes the TableGen - (tblgen) application that manages domain-specific information to - support LLVM code generation. TableGen processes input from a target - description file (.td suffix) and generates C++ code that can be - used for code generation.
  • - -
  • Writing an LLVM - Pass — The assembly printer is a FunctionPass, as are - several SelectionDAG processing steps.
  • -
- -

-To follow the SPARC examples in this document, have a copy of -The SPARC Architecture -Manual, Version 8 for reference. For details about the ARM instruction -set, refer to the ARM Architecture -Reference Manual. For more about the GNU Assembler format -(GAS), see -Using As, -especially for the assembly printer. Using As contains a list of target -machine dependent features. -

- -
- -

- Basic Steps -

- -
- -

-To write a compiler backend for LLVM that converts the LLVM IR to code for a -specified target (machine or other language), follow these steps: -

- -
    -
  • Create a subclass of the TargetMachine class that describes characteristics - of your target machine. Copy existing examples of specific TargetMachine - class and header files; for example, start with - SparcTargetMachine.cpp and SparcTargetMachine.h, but - change the file names for your target. Similarly, change code that - references "Sparc" to reference your target.
  • - -
  • Describe the register set of the target. Use TableGen to generate code for - register definition, register aliases, and register classes from a - target-specific RegisterInfo.td input file. You should also write - additional code for a subclass of the TargetRegisterInfo class that - represents the class register file data used for register allocation and - also describes the interactions between registers.
  • - -
  • Describe the instruction set of the target. Use TableGen to generate code - for target-specific instructions from target-specific versions of - TargetInstrFormats.td and TargetInstrInfo.td. You should - write additional code for a subclass of the TargetInstrInfo class to - represent machine instructions supported by the target machine.
  • - -
  • Describe the selection and conversion of the LLVM IR from a Directed Acyclic - Graph (DAG) representation of instructions to native target-specific - instructions. Use TableGen to generate code that matches patterns and - selects instructions based on additional information in a target-specific - version of TargetInstrInfo.td. Write code - for XXXISelDAGToDAG.cpp, where XXX identifies the specific target, - to perform pattern matching and DAG-to-DAG instruction selection. Also write - code in XXXISelLowering.cpp to replace or remove operations and - data types that are not supported natively in a SelectionDAG.
  • - -
  • Write code for an assembly printer that converts LLVM IR to a GAS format for - your target machine. You should add assembly strings to the instructions - defined in your target-specific version of TargetInstrInfo.td. You - should also write code for a subclass of AsmPrinter that performs the - LLVM-to-assembly conversion and a trivial subclass of TargetAsmInfo.
  • - -
  • Optionally, add support for subtargets (i.e., variants with different - capabilities). You should also write code for a subclass of the - TargetSubtarget class, which allows you to use the -mcpu= - and -mattr= command-line options.
  • - -
  • Optionally, add JIT support and create a machine code emitter (subclass of - TargetJITInfo) that is used to emit binary code directly into memory.
  • -
- -

-In the .cpp and .h. files, initially stub up these methods and -then implement them later. Initially, you may not know which private members -that the class will need and which components will need to be subclassed. -

- -
- -

- Preliminaries -

- -
- -

-To actually create your compiler backend, you need to create and modify a few -files. The absolute minimum is discussed here. But to actually use the LLVM -target-independent code generator, you must perform the steps described in -the LLVM -Target-Independent Code Generator document. -

- -

-First, you should create a subdirectory under lib/Target to hold all -the files related to your target. If your target is called "Dummy," create the -directory lib/Target/Dummy. -

- -

-In this new -directory, create a Makefile. It is easiest to copy a -Makefile of another target and modify it. It should at least contain -the LEVEL, LIBRARYNAME and TARGET variables, and then -include $(LEVEL)/Makefile.common. The library can be -named LLVMDummy (for example, see the MIPS target). Alternatively, you -can split the library into LLVMDummyCodeGen -and LLVMDummyAsmPrinter, the latter of which should be implemented in a -subdirectory below lib/Target/Dummy (for example, see the PowerPC -target). -

- -

-Note that these two naming schemes are hardcoded into llvm-config. -Using any other naming scheme will confuse llvm-config and produce a -lot of (seemingly unrelated) linker errors when linking llc. -

- -

-To make your target actually do something, you need to implement a subclass of -TargetMachine. This implementation should typically be in the file -lib/Target/DummyTargetMachine.cpp, but any file in -the lib/Target directory will be built and should work. To use LLVM's -target independent code generator, you should do what all current machine -backends do: create a subclass of LLVMTargetMachine. (To create a -target from scratch, create a subclass of TargetMachine.) -

- -

-To get LLVM to actually build and link your target, you need to add it to -the TARGETS_TO_BUILD variable. To do this, you modify the configure -script to know about your target when parsing the --enable-targets -option. Search the configure script for TARGETS_TO_BUILD, add your -target to the lists there (some creativity required), and then -reconfigure. Alternatively, you can change autotools/configure.ac and -regenerate configure by running ./autoconf/AutoRegen.sh. -

- -
- -
- - -

- Target Machine -

- - -
- -

-LLVMTargetMachine is designed as a base class for targets implemented -with the LLVM target-independent code generator. The LLVMTargetMachine -class should be specialized by a concrete target class that implements the -various virtual methods. LLVMTargetMachine is defined as a subclass of -TargetMachine in include/llvm/Target/TargetMachine.h. The -TargetMachine class implementation (TargetMachine.cpp) also -processes numerous command-line options. -

- -

-To create a concrete target-specific subclass of LLVMTargetMachine, -start by copying an existing TargetMachine class and header. You -should name the files that you create to reflect your specific target. For -instance, for the SPARC target, name the files SparcTargetMachine.h and -SparcTargetMachine.cpp. -

- -

-For a target machine XXX, the implementation of -XXXTargetMachine must have access methods to obtain objects that -represent target components. These methods are named get*Info, and are -intended to obtain the instruction set (getInstrInfo), register set -(getRegisterInfo), stack frame layout (getFrameInfo), and -similar information. XXXTargetMachine must also implement the -getTargetData method to access an object with target-specific data -characteristics, such as data type size and alignment requirements. -

- -

-For instance, for the SPARC target, the header file -SparcTargetMachine.h declares prototypes for several get*Info -and getTargetData methods that simply return a class member. -

- -
-
-namespace llvm {
-
-class Module;
-
-class SparcTargetMachine : public LLVMTargetMachine {
-  const TargetData DataLayout;       // Calculates type size & alignment
-  SparcSubtarget Subtarget;
-  SparcInstrInfo InstrInfo;
-  TargetFrameInfo FrameInfo;
-  
-protected:
-  virtual const TargetAsmInfo *createTargetAsmInfo() const;
-  
-public:
-  SparcTargetMachine(const Module &M, const std::string &FS);
-
-  virtual const SparcInstrInfo *getInstrInfo() const {return &InstrInfo; }
-  virtual const TargetFrameInfo *getFrameInfo() const {return &FrameInfo; }
-  virtual const TargetSubtarget *getSubtargetImpl() const{return &Subtarget; }
-  virtual const TargetRegisterInfo *getRegisterInfo() const {
-    return &InstrInfo.getRegisterInfo();
-  }
-  virtual const TargetData *getTargetData() const { return &DataLayout; }
-  static unsigned getModuleMatchQuality(const Module &M);
-
-  // Pass Pipeline Configuration
-  virtual bool addInstSelector(PassManagerBase &PM, bool Fast);
-  virtual bool addPreEmitPass(PassManagerBase &PM, bool Fast);
-};
-
-} // end namespace llvm
-
-
- -
    -
  • getInstrInfo()
  • -
  • getRegisterInfo()
  • -
  • getFrameInfo()
  • -
  • getTargetData()
  • -
  • getSubtargetImpl()
  • -
- -

For some targets, you also need to support the following methods:

- -
    -
  • getTargetLowering()
  • -
  • getJITInfo()
  • -
- -

-In addition, the XXXTargetMachine constructor should specify a -TargetDescription string that determines the data layout for the target -machine, including characteristics such as pointer size, alignment, and -endianness. For example, the constructor for SparcTargetMachine contains the -following: -

- -
-
-SparcTargetMachine::SparcTargetMachine(const Module &M, const std::string &FS)
-  : DataLayout("E-p:32:32-f128:128:128"),
-    Subtarget(M, FS), InstrInfo(Subtarget),
-    FrameInfo(TargetFrameInfo::StackGrowsDown, 8, 0) {
-}
-
-
- -

Hyphens separate portions of the TargetDescription string.

- -
    -
  • An upper-case "E" in the string indicates a big-endian target data - model. a lower-case "e" indicates little-endian.
  • - -
  • "p:" is followed by pointer information: size, ABI alignment, and - preferred alignment. If only two figures follow "p:", then the - first value is pointer size, and the second value is both ABI and preferred - alignment.
  • - -
  • Then a letter for numeric type alignment: "i", "f", - "v", or "a" (corresponding to integer, floating point, - vector, or aggregate). "i", "v", or "a" are - followed by ABI alignment and preferred alignment. "f" is followed - by three values: the first indicates the size of a long double, then ABI - alignment, and then ABI preferred alignment.
  • -
- -
- - -

- Target Registration -

- - -
- -

-You must also register your target with the TargetRegistry, which is -what other LLVM tools use to be able to lookup and use your target at -runtime. The TargetRegistry can be used directly, but for most targets -there are helper templates which should take care of the work for you.

- -

-All targets should declare a global Target object which is used to -represent the target during registration. Then, in the target's TargetInfo -library, the target should define that object and use -the RegisterTarget template to register the target. For example, the Sparc registration code looks like this: -

- -
-
-Target llvm::TheSparcTarget;
-
-extern "C" void LLVMInitializeSparcTargetInfo() { 
-  RegisterTarget<Triple::sparc, /*HasJIT=*/false>
-    X(TheSparcTarget, "sparc", "Sparc");
-}
-
-
- -

-This allows the TargetRegistry to look up the target by name or by -target triple. In addition, most targets will also register additional features -which are available in separate libraries. These registration steps are -separate, because some clients may wish to only link in some parts of the target --- the JIT code generator does not require the use of the assembler printer, for -example. Here is an example of registering the Sparc assembly printer: -

- -
-
-extern "C" void LLVMInitializeSparcAsmPrinter() { 
-  RegisterAsmPrinter<SparcAsmPrinter> X(TheSparcTarget);
-}
-
-
- -

-For more information, see -"llvm/Target/TargetRegistry.h". -

- -
- - -

- Register Set and Register Classes -

- - -
- -

-You should describe a concrete target-specific class that represents the -register file of a target machine. This class is called XXXRegisterInfo -(where XXX identifies the target) and represents the class register -file data that is used for register allocation. It also describes the -interactions between registers. -

- -

-You also need to define register classes to categorize related registers. A -register class should be added for groups of registers that are all treated the -same way for some instruction. Typical examples are register classes for -integer, floating-point, or vector registers. A register allocator allows an -instruction to use any register in a specified register class to perform the -instruction in a similar manner. Register classes allocate virtual registers to -instructions from these sets, and register classes let the target-independent -register allocator automatically choose the actual registers. -

- -

-Much of the code for registers, including register definition, register aliases, -and register classes, is generated by TableGen from XXXRegisterInfo.td -input files and placed in XXXGenRegisterInfo.h.inc and -XXXGenRegisterInfo.inc output files. Some of the code in the -implementation of XXXRegisterInfo requires hand-coding. -

- - -

- Defining a Register -

- -
- -

-The XXXRegisterInfo.td file typically starts with register definitions -for a target machine. The Register class (specified -in Target.td) is used to define an object for each register. The -specified string n becomes the Name of the register. The -basic Register object does not have any subregisters and does not -specify any aliases. -

- -
-
-class Register<string n> {
-  string Namespace = "";
-  string AsmName = n;
-  string Name = n;
-  int SpillSize = 0;
-  int SpillAlignment = 0;
-  list<Register> Aliases = [];
-  list<Register> SubRegs = [];
-  list<int> DwarfNumbers = [];
-}
-
-
- -

-For example, in the X86RegisterInfo.td file, there are register -definitions that utilize the Register class, such as: -

- -
-
-def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>;
-
-
- -

-This defines the register AL and assigns it values (with -DwarfRegNum) that are used by gcc, gdb, or a debug -information writer to identify a register. For register -AL, DwarfRegNum takes an array of 3 values representing 3 -different modes: the first element is for X86-64, the second for exception -handling (EH) on X86-32, and the third is generic. -1 is a special Dwarf number -that indicates the gcc number is undefined, and -2 indicates the register number -is invalid for this mode. -

- -

-From the previously described line in the X86RegisterInfo.td file, -TableGen generates this code in the X86GenRegisterInfo.inc file: -

- -
-
-static const unsigned GR8[] = { X86::AL, ... };
-
-const unsigned AL_AliasSet[] = { X86::AX, X86::EAX, X86::RAX, 0 };
-
-const TargetRegisterDesc RegisterDescriptors[] = { 
-  ...
-{ "AL", "AL", AL_AliasSet, Empty_SubRegsSet, Empty_SubRegsSet, AL_SuperRegsSet }, ...
-
-
- -

-From the register info file, TableGen generates a TargetRegisterDesc -object for each register. TargetRegisterDesc is defined in -include/llvm/Target/TargetRegisterInfo.h with the following fields: -

- -
-
-struct TargetRegisterDesc {
-  const char     *AsmName;      // Assembly language name for the register
-  const char     *Name;         // Printable name for the reg (for debugging)
-  const unsigned *AliasSet;     // Register Alias Set
-  const unsigned *SubRegs;      // Sub-register set
-  const unsigned *ImmSubRegs;   // Immediate sub-register set
-  const unsigned *SuperRegs;    // Super-register set
-};
-
- -

-TableGen uses the entire target description file (.td) to determine -text names for the register (in the AsmName and Name fields of -TargetRegisterDesc) and the relationships of other registers to the -defined register (in the other TargetRegisterDesc fields). In this -example, other definitions establish the registers "AX", -"EAX", and "RAX" as aliases for one another, so TableGen -generates a null-terminated array (AL_AliasSet) for this register alias -set. -

- -

-The Register class is commonly used as a base class for more complex -classes. In Target.td, the Register class is the base for the -RegisterWithSubRegs class that is used to define registers that need to -specify subregisters in the SubRegs list, as shown here: -

- -
-
-class RegisterWithSubRegs<string n,
-list<Register> subregs> : Register<n> {
-  let SubRegs = subregs;
-}
-
-
- -

-In SparcRegisterInfo.td, additional register classes are defined for -SPARC: a Register subclass, SparcReg, and further subclasses: Ri, -Rf, and Rd. SPARC registers are identified by 5-bit ID -numbers, which is a feature common to these subclasses. Note the use of -'let' expressions to override values that are initially defined in a -superclass (such as SubRegs field in the Rd class). -

- -
-
-class SparcReg<string n> : Register<n> {
-  field bits<5> Num;
-  let Namespace = "SP";
-}
-// Ri - 32-bit integer registers
-class Ri<bits<5> num, string n> :
-SparcReg<n> {
-  let Num = num;
-}
-// Rf - 32-bit floating-point registers
-class Rf<bits<5> num, string n> :
-SparcReg<n> {
-  let Num = num;
-}
-// Rd - Slots in the FP register file for 64-bit
-floating-point values.
-class Rd<bits<5> num, string n,
-list<Register> subregs> : SparcReg<n> {
-  let Num = num;
-  let SubRegs = subregs;
-}
-
-
- -

-In the SparcRegisterInfo.td file, there are register definitions that -utilize these subclasses of Register, such as: -

- -
-
-def G0 : Ri< 0, "G0">,
-DwarfRegNum<[0]>;
-def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>;
-...
-def F0 : Rf< 0, "F0">,
-DwarfRegNum<[32]>;
-def F1 : Rf< 1, "F1">,
-DwarfRegNum<[33]>;
-...
-def D0 : Rd< 0, "F0", [F0, F1]>,
-DwarfRegNum<[32]>;
-def D1 : Rd< 2, "F2", [F2, F3]>,
-DwarfRegNum<[34]>;
-
-
- -

-The last two registers shown above (D0 and D1) are -double-precision floating-point registers that are aliases for pairs of -single-precision floating-point sub-registers. In addition to aliases, the -sub-register and super-register relationships of the defined register are in -fields of a register's TargetRegisterDesc. -

- -
- - -

- Defining a Register Class -

- -
- -

-The RegisterClass class (specified in Target.td) is used to -define an object that represents a group of related registers and also defines -the default allocation order of the registers. A target description file -XXXRegisterInfo.td that uses Target.td can construct register -classes using the following class: -

- -
-
-class RegisterClass<string namespace,
-list<ValueType> regTypes, int alignment, dag regList> {
-  string Namespace = namespace;
-  list<ValueType> RegTypes = regTypes;
-  int Size = 0;  // spill size, in bits; zero lets tblgen pick the size
-  int Alignment = alignment;
-
-  // CopyCost is the cost of copying a value between two registers
-  // default value 1 means a single instruction
-  // A negative value means copying is extremely expensive or impossible
-  int CopyCost = 1;  
-  dag MemberList = regList;
-  
-  // for register classes that are subregisters of this class
-  list<RegisterClass> SubRegClassList = [];  
-  
-  code MethodProtos = [{}];  // to insert arbitrary code
-  code MethodBodies = [{}];
-}
-
-
- -

To define a RegisterClass, use the following 4 arguments:

- -
    -
  • The first argument of the definition is the name of the namespace.
  • - -
  • The second argument is a list of ValueType register type values - that are defined in include/llvm/CodeGen/ValueTypes.td. Defined - values include integer types (such as i16, i32, - and i1 for Boolean), floating-point types - (f32, f64), and vector types (for example, v8i16 - for an 8 x i16 vector). All registers in a RegisterClass - must have the same ValueType, but some registers may store vector - data in different configurations. For example a register that can process a - 128-bit vector may be able to handle 16 8-bit integer elements, 8 16-bit - integers, 4 32-bit integers, and so on.
  • - -
  • The third argument of the RegisterClass definition specifies the - alignment required of the registers when they are stored or loaded to - memory.
  • - -
  • The final argument, regList, specifies which registers are in this - class. If an alternative allocation order method is not specified, then - regList also defines the order of allocation used by the register - allocator. Besides simply listing registers with (add R0, R1, ...), - more advanced set operators are available. See - include/llvm/Target/Target.td for more information.
  • -
- -

-In SparcRegisterInfo.td, three RegisterClass objects are defined: -FPRegs, DFPRegs, and IntRegs. For all three register -classes, the first argument defines the namespace with the string -'SP'. FPRegs defines a group of 32 single-precision -floating-point registers (F0 to F31); DFPRegs defines -a group of 16 double-precision registers -(D0-D15). -

- -
-
-// F0, F1, F2, ..., F31
-def FPRegs : RegisterClass<"SP", [f32], 32, (sequence "F%u", 0, 31)>;
-
-def DFPRegs : RegisterClass<"SP", [f64], 64,
-                            (add D0, D1, D2, D3, D4, D5, D6, D7, D8,
-                                 D9, D10, D11, D12, D13, D14, D15)>;
- 
-def IntRegs : RegisterClass<"SP", [i32], 32,
-    (add L0, L1, L2, L3, L4, L5, L6, L7,
-         I0, I1, I2, I3, I4, I5,
-         O0, O1, O2, O3, O4, O5, O7,
-         G1,
-         // Non-allocatable regs:
-         G2, G3, G4,
-         O6,        // stack ptr
-         I6,        // frame ptr
-         I7,        // return address
-         G0,        // constant zero
-         G5, G6, G7 // reserved for kernel
-    )>;
-
-
- -

-Using SparcRegisterInfo.td with TableGen generates several output files -that are intended for inclusion in other source code that you write. -SparcRegisterInfo.td generates SparcGenRegisterInfo.h.inc, -which should be included in the header file for the implementation of the SPARC -register implementation that you write (SparcRegisterInfo.h). In -SparcGenRegisterInfo.h.inc a new structure is defined called -SparcGenRegisterInfo that uses TargetRegisterInfo as its -base. It also specifies types, based upon the defined register -classes: DFPRegsClass, FPRegsClass, and IntRegsClass. -

- -

-SparcRegisterInfo.td also generates SparcGenRegisterInfo.inc, -which is included at the bottom of SparcRegisterInfo.cpp, the SPARC -register implementation. The code below shows only the generated integer -registers and associated register classes. The order of registers -in IntRegs reflects the order in the definition of IntRegs in -the target description file. -

- -
-
  // IntRegs Register Class...
-  static const unsigned IntRegs[] = {
-    SP::L0, SP::L1, SP::L2, SP::L3, SP::L4, SP::L5,
-    SP::L6, SP::L7, SP::I0, SP::I1, SP::I2, SP::I3,
-    SP::I4, SP::I5, SP::O0, SP::O1, SP::O2, SP::O3,
-    SP::O4, SP::O5, SP::O7, SP::G1, SP::G2, SP::G3,
-    SP::G4, SP::O6, SP::I6, SP::I7, SP::G0, SP::G5,
-    SP::G6, SP::G7, 
-  };
-
-  // IntRegsVTs Register Class Value Types...
-  static const MVT::ValueType IntRegsVTs[] = {
-    MVT::i32, MVT::Other
-  };
-
-namespace SP {   // Register class instances
-  DFPRegsClass    DFPRegsRegClass;
-  FPRegsClass     FPRegsRegClass;
-  IntRegsClass    IntRegsRegClass;
-...
-  // IntRegs Sub-register Classess...
-  static const TargetRegisterClass* const IntRegsSubRegClasses [] = {
-    NULL
-  };
-...
-  // IntRegs Super-register Classess...
-  static const TargetRegisterClass* const IntRegsSuperRegClasses [] = {
-    NULL
-  };
-...
-  // IntRegs Register Class sub-classes...
-  static const TargetRegisterClass* const IntRegsSubclasses [] = {
-    NULL
-  };
-...
-  // IntRegs Register Class super-classes...
-  static const TargetRegisterClass* const IntRegsSuperclasses [] = {
-    NULL
-  };
-
-  IntRegsClass::IntRegsClass() : TargetRegisterClass(IntRegsRegClassID, 
-    IntRegsVTs, IntRegsSubclasses, IntRegsSuperclasses, IntRegsSubRegClasses, 
-    IntRegsSuperRegClasses, 4, 4, 1, IntRegs, IntRegs + 32) {}
-}
-
-
- -

-The register allocators will avoid using reserved registers, and callee saved -registers are not used until all the volatile registers have been used. That -is usually good enough, but in some cases it may be necessary to provide custom -allocation orders. -

- -
- - -

- Implement a subclass of - TargetRegisterInfo -

- -
- -

-The final step is to hand code portions of XXXRegisterInfo, which -implements the interface described in TargetRegisterInfo.h. These -functions return 0, NULL, or false, unless -overridden. Here is a list of functions that are overridden for the SPARC -implementation in SparcRegisterInfo.cpp: -

- -
    -
  • getCalleeSavedRegs — Returns a list of callee-saved registers - in the order of the desired callee-save stack frame offset.
  • - -
  • getReservedRegs — Returns a bitset indexed by physical - register numbers, indicating if a particular register is unavailable.
  • - -
  • hasFP — Return a Boolean indicating if a function should have - a dedicated frame pointer register.
  • - -
  • eliminateCallFramePseudoInstr — If call frame setup or - destroy pseudo instructions are used, this can be called to eliminate - them.
  • - -
  • eliminateFrameIndex — Eliminate abstract frame indices from - instructions that may use them.
  • - -
  • emitPrologue — Insert prologue code into the function.
  • - -
  • emitEpilogue — Insert epilogue code into the function.
  • -
- -
- -
- - -

- Instruction Set -

- - -
- -

-During the early stages of code generation, the LLVM IR code is converted to a -SelectionDAG with nodes that are instances of the SDNode class -containing target instructions. An SDNode has an opcode, operands, type -requirements, and operation properties. For example, is an operation -commutative, does an operation load from memory. The various operation node -types are described in the include/llvm/CodeGen/SelectionDAGNodes.h -file (values of the NodeType enum in the ISD namespace). -

- -

-TableGen uses the following target description (.td) input files to -generate much of the code for instruction definition: -

- -
    -
  • Target.td — Where the Instruction, Operand, - InstrInfo, and other fundamental classes are defined.
  • - -
  • TargetSelectionDAG.td— Used by SelectionDAG - instruction selection generators, contains SDTC* classes (selection - DAG type constraint), definitions of SelectionDAG nodes (such as - imm, cond, bb, add, fadd, - sub), and pattern support (Pattern, Pat, - PatFrag, PatLeaf, ComplexPattern.
  • - -
  • XXXInstrFormats.td — Patterns for definitions of - target-specific instructions.
  • - -
  • XXXInstrInfo.td — Target-specific definitions of instruction - templates, condition codes, and instructions of an instruction set. For - architecture modifications, a different file name may be used. For example, - for Pentium with SSE instruction, this file is X86InstrSSE.td, and - for Pentium with MMX, this file is X86InstrMMX.td.
  • -
- -

-There is also a target-specific XXX.td file, where XXX is the -name of the target. The XXX.td file includes the other .td -input files, but its contents are only directly important for subtargets. -

- -

-You should describe a concrete target-specific class XXXInstrInfo that -represents machine instructions supported by a target machine. -XXXInstrInfo contains an array of XXXInstrDescriptor objects, -each of which describes one instruction. An instruction descriptor defines:

- -
    -
  • Opcode mnemonic
  • - -
  • Number of operands
  • - -
  • List of implicit register definitions and uses
  • - -
  • Target-independent properties (such as memory access, is commutable)
  • - -
  • Target-specific flags
  • -
- -

-The Instruction class (defined in Target.td) is mostly used as a base -for more complex instruction classes. -

- -
-
class Instruction {
-  string Namespace = "";
-  dag OutOperandList;       // An dag containing the MI def operand list.
-  dag InOperandList;        // An dag containing the MI use operand list.
-  string AsmString = "";    // The .s format to print the instruction with.
-  list<dag> Pattern;  // Set to the DAG pattern for this instruction
-  list<Register> Uses = []; 
-  list<Register> Defs = [];
-  list<Predicate> Predicates = [];  // predicates turned into isel match code
-  ... remainder not shown for space ...
-}
-
-
- -

-A SelectionDAG node (SDNode) should contain an object -representing a target-specific instruction that is defined -in XXXInstrInfo.td. The instruction objects should represent -instructions from the architecture manual of the target machine (such as the -SPARC Architecture Manual for the SPARC target). -

- -

-A single instruction from the architecture manual is often modeled as multiple -target instructions, depending upon its operands. For example, a manual might -describe an add instruction that takes a register or an immediate operand. An -LLVM target could model this with two instructions named ADDri and -ADDrr. -

- -

-You should define a class for each instruction category and define each opcode -as a subclass of the category with appropriate parameters such as the fixed -binary encoding of opcodes and extended opcodes. You should map the register -bits to the bits of the instruction in which they are encoded (for the -JIT). Also you should specify how the instruction should be printed when the -automatic assembly printer is used. -

- -

-As is described in the SPARC Architecture Manual, Version 8, there are three -major 32-bit formats for instructions. Format 1 is only for the CALL -instruction. Format 2 is for branch on condition codes and SETHI (set -high bits of a register) instructions. Format 3 is for other instructions. -

- -

-Each of these formats has corresponding classes in SparcInstrFormat.td. -InstSP is a base class for other instruction classes. Additional base -classes are specified for more precise formats: for example -in SparcInstrFormat.td, F2_1 is for SETHI, -and F2_2 is for branches. There are three other base -classes: F3_1 for register/register operations, F3_2 for -register/immediate operations, and F3_3 for floating-point -operations. SparcInstrInfo.td also adds the base class Pseudo for -synthetic SPARC instructions. -

- -

-SparcInstrInfo.td largely consists of operand and instruction -definitions for the SPARC target. In SparcInstrInfo.td, the following -target description file entry, LDrr, defines the Load Integer -instruction for a Word (the LD SPARC opcode) from a memory address to a -register. The first parameter, the value 3 (112), is the -operation value for this category of operation. The second parameter -(0000002) is the specific operation value -for LD/Load Word. The third parameter is the output destination, which -is a register operand and defined in the Register target description -file (IntRegs). -

- -
-
def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
-                 "ld [$addr], $dst",
-                 [(set IntRegs:$dst, (load ADDRrr:$addr))]>;
-
-
- -

-The fourth parameter is the input source, which uses the address -operand MEMrr that is defined earlier in SparcInstrInfo.td: -

- -
-
def MEMrr : Operand<i32> {
-  let PrintMethod = "printMemOperand";
-  let MIOperandInfo = (ops IntRegs, IntRegs);
-}
-
-
- -

-The fifth parameter is a string that is used by the assembly printer and can be -left as an empty string until the assembly printer interface is implemented. The -sixth and final parameter is the pattern used to match the instruction during -the SelectionDAG Select Phase described in -(The LLVM -Target-Independent Code Generator). This parameter is detailed in the next -section, Instruction Selector. -

- -

-Instruction class definitions are not overloaded for different operand types, so -separate versions of instructions are needed for register, memory, or immediate -value operands. For example, to perform a Load Integer instruction for a Word -from an immediate operand to a register, the following instruction class is -defined: -

- -
-
def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
-                 "ld [$addr], $dst",
-                 [(set IntRegs:$dst, (load ADDRri:$addr))]>;
-
-
- -

-Writing these definitions for so many similar instructions can involve a lot of -cut and paste. In td files, the multiclass directive enables the -creation of templates to define several instruction classes at once (using -the defm directive). For example in SparcInstrInfo.td, the -multiclass pattern F3_12 is defined to create 2 instruction -classes each time F3_12 is invoked: -

- -
-
multiclass F3_12 <string OpcStr, bits<6> Op3Val, SDNode OpNode> {
-  def rr  : F3_1 <2, Op3Val, 
-                 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
-                 !strconcat(OpcStr, " $b, $c, $dst"),
-                 [(set IntRegs:$dst, (OpNode IntRegs:$b, IntRegs:$c))]>;
-  def ri  : F3_2 <2, Op3Val,
-                 (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
-                 !strconcat(OpcStr, " $b, $c, $dst"),
-                 [(set IntRegs:$dst, (OpNode IntRegs:$b, simm13:$c))]>;
-}
-
-
- -

-So when the defm directive is used for the XOR -and ADD instructions, as seen below, it creates four instruction -objects: XORrr, XORri, ADDrr, and ADDri. -

- -
-
-defm XOR   : F3_12<"xor", 0b000011, xor>;
-defm ADD   : F3_12<"add", 0b000000, add>;
-
-
- -

-SparcInstrInfo.td also includes definitions for condition codes that -are referenced by branch instructions. The following definitions -in SparcInstrInfo.td indicate the bit location of the SPARC condition -code. For example, the 10th bit represents the 'greater than' -condition for integers, and the 22nd bit represents the 'greater -than' condition for floats. -

- -
-
-def ICC_NE  : ICC_VAL< 9>;  // Not Equal
-def ICC_E   : ICC_VAL< 1>;  // Equal
-def ICC_G   : ICC_VAL<10>;  // Greater
-...
-def FCC_U   : FCC_VAL<23>;  // Unordered
-def FCC_G   : FCC_VAL<22>;  // Greater
-def FCC_UG  : FCC_VAL<21>;  // Unordered or Greater
-...
-
-
- -

-(Note that Sparc.h also defines enums that correspond to the same SPARC -condition codes. Care must be taken to ensure the values in Sparc.h -correspond to the values in SparcInstrInfo.td. I.e., -SPCC::ICC_NE = 9, SPCC::FCC_U = 23 and so on.) -

- - -

- Instruction Operand Mapping -

- -
- -

-The code generator backend maps instruction operands to fields in the -instruction. Operands are assigned to unbound fields in the instruction in the -order they are defined. Fields are bound when they are assigned a value. For -example, the Sparc target defines the XNORrr instruction as -a F3_1 format instruction having three operands. -

- -
-
-def XNORrr  : F3_1<2, 0b000111,
-                   (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
-                   "xnor $b, $c, $dst",
-                   [(set IntRegs:$dst, (not (xor IntRegs:$b, IntRegs:$c)))]>;
-
-
- -

-The instruction templates in SparcInstrFormats.td show the base class -for F3_1 is InstSP. -

- -
-
-class InstSP<dag outs, dag ins, string asmstr, list<dag> pattern> : Instruction {
-  field bits<32> Inst;
-  let Namespace = "SP";
-  bits<2> op;
-  let Inst{31-30} = op;       
-  dag OutOperandList = outs;
-  dag InOperandList = ins;
-  let AsmString   = asmstr;
-  let Pattern = pattern;
-}
-
-
- -

InstSP leaves the op field unbound.

- -
-
-class F3<dag outs, dag ins, string asmstr, list<dag> pattern>
-    : InstSP<outs, ins, asmstr, pattern> {
-  bits<5> rd;
-  bits<6> op3;
-  bits<5> rs1;
-  let op{1} = 1;   // Op = 2 or 3
-  let Inst{29-25} = rd;
-  let Inst{24-19} = op3;
-  let Inst{18-14} = rs1;
-}
-
-
- -

-F3 binds the op field and defines the rd, -op3, and rs1 fields. F3 format instructions will -bind the operands rd, op3, and rs1 fields. -

- -
-
-class F3_1<bits<2> opVal, bits<6> op3val, dag outs, dag ins,
-           string asmstr, list<dag> pattern> : F3<outs, ins, asmstr, pattern> {
-  bits<8> asi = 0; // asi not currently used
-  bits<5> rs2;
-  let op         = opVal;
-  let op3        = op3val;
-  let Inst{13}   = 0;     // i field = 0
-  let Inst{12-5} = asi;   // address space identifier
-  let Inst{4-0}  = rs2;
-}
-
-
- -

-F3_1 binds the op3 field and defines the rs2 -fields. F3_1 format instructions will bind the operands to the rd, -rs1, and rs2 fields. This results in the XNORrr -instruction binding $dst, $b, and $c operands to -the rd, rs1, and rs2 fields respectively. -

- -
- - -

- Implement a subclass of - TargetInstrInfo -

- -
- -

-The final step is to hand code portions of XXXInstrInfo, which -implements the interface described in TargetInstrInfo.h. These -functions return 0 or a Boolean or they assert, unless -overridden. Here's a list of functions that are overridden for the SPARC -implementation in SparcInstrInfo.cpp: -

- -
    -
  • isLoadFromStackSlot — If the specified machine instruction is - a direct load from a stack slot, return the register number of the - destination and the FrameIndex of the stack slot.
  • - -
  • isStoreToStackSlot — If the specified machine instruction is - a direct store to a stack slot, return the register number of the - destination and the FrameIndex of the stack slot.
  • - -
  • copyPhysReg — Copy values between a pair of physical - registers.
  • - -
  • storeRegToStackSlot — Store a register value to a stack - slot.
  • - -
  • loadRegFromStackSlot — Load a register value from a stack - slot.
  • - -
  • storeRegToAddr — Store a register value to memory.
  • - -
  • loadRegFromAddr — Load a register value from memory.
  • - -
  • foldMemoryOperand — Attempt to combine instructions of any - load or store instruction for the specified operand(s).
  • -
- -
- - -

- Branch Folding and If Conversion -

-
- -

-Performance can be improved by combining instructions or by eliminating -instructions that are never reached. The AnalyzeBranch method -in XXXInstrInfo may be implemented to examine conditional instructions -and remove unnecessary instructions. AnalyzeBranch looks at the end of -a machine basic block (MBB) for opportunities for improvement, such as branch -folding and if conversion. The BranchFolder and IfConverter -machine function passes (see the source files BranchFolding.cpp and -IfConversion.cpp in the lib/CodeGen directory) call -AnalyzeBranch to improve the control flow graph that represents the -instructions. -

- -

-Several implementations of AnalyzeBranch (for ARM, Alpha, and X86) can -be examined as models for your own AnalyzeBranch implementation. Since -SPARC does not implement a useful AnalyzeBranch, the ARM target -implementation is shown below. -

- -

AnalyzeBranch returns a Boolean value and takes four parameters:

- -
    -
  • MachineBasicBlock &MBB — The incoming block to be - examined.
  • - -
  • MachineBasicBlock *&TBB — A destination block that is - returned. For a conditional branch that evaluates to true, TBB is - the destination.
  • - -
  • MachineBasicBlock *&FBB — For a conditional branch that - evaluates to false, FBB is returned as the destination.
  • - -
  • std::vector<MachineOperand> &Cond — List of - operands to evaluate a condition for a conditional branch.
  • -
- -

-In the simplest case, if a block ends without a branch, then it falls through to -the successor block. No destination blocks are specified for either TBB -or FBB, so both parameters return NULL. The start of -the AnalyzeBranch (see code below for the ARM target) shows the -function parameters and the code for the simplest case. -

- -
-
bool ARMInstrInfo::AnalyzeBranch(MachineBasicBlock &MBB,
-        MachineBasicBlock *&TBB, MachineBasicBlock *&FBB,
-        std::vector<MachineOperand> &Cond) const
-{
-  MachineBasicBlock::iterator I = MBB.end();
-  if (I == MBB.begin() || !isUnpredicatedTerminator(--I))
-    return false;
-
-
- -

-If a block ends with a single unconditional branch instruction, then -AnalyzeBranch (shown below) should return the destination of that -branch in the TBB parameter. -

- -
-
-  if (LastOpc == ARM::B || LastOpc == ARM::tB) {
-    TBB = LastInst->getOperand(0).getMBB();
-    return false;
-  }
-
-
- -

-If a block ends with two unconditional branches, then the second branch is never -reached. In that situation, as shown below, remove the last branch instruction -and return the penultimate branch in the TBB parameter. -

- -
-
-  if ((SecondLastOpc == ARM::B || SecondLastOpc==ARM::tB) &&
-      (LastOpc == ARM::B || LastOpc == ARM::tB)) {
-    TBB = SecondLastInst->getOperand(0).getMBB();
-    I = LastInst;
-    I->eraseFromParent();
-    return false;
-  }
-
-
- -

-A block may end with a single conditional branch instruction that falls through -to successor block if the condition evaluates to false. In that case, -AnalyzeBranch (shown below) should return the destination of that -conditional branch in the TBB parameter and a list of operands in -the Cond parameter to evaluate the condition. -

- -
-
-  if (LastOpc == ARM::Bcc || LastOpc == ARM::tBcc) {
-    // Block ends with fall-through condbranch.
-    TBB = LastInst->getOperand(0).getMBB();
-    Cond.push_back(LastInst->getOperand(1));
-    Cond.push_back(LastInst->getOperand(2));
-    return false;
-  }
-
-
- -

-If a block ends with both a conditional branch and an ensuing unconditional -branch, then AnalyzeBranch (shown below) should return the conditional -branch destination (assuming it corresponds to a conditional evaluation of -'true') in the TBB parameter and the unconditional branch -destination in the FBB (corresponding to a conditional evaluation of -'false'). A list of operands to evaluate the condition should be -returned in the Cond parameter. -

- -
-
-  unsigned SecondLastOpc = SecondLastInst->getOpcode();
-
-  if ((SecondLastOpc == ARM::Bcc && LastOpc == ARM::B) ||
-      (SecondLastOpc == ARM::tBcc && LastOpc == ARM::tB)) {
-    TBB =  SecondLastInst->getOperand(0).getMBB();
-    Cond.push_back(SecondLastInst->getOperand(1));
-    Cond.push_back(SecondLastInst->getOperand(2));
-    FBB = LastInst->getOperand(0).getMBB();
-    return false;
-  }
-
-
- -

-For the last two cases (ending with a single conditional branch or ending with -one conditional and one unconditional branch), the operands returned in -the Cond parameter can be passed to methods of other instructions to -create new branches or perform other operations. An implementation -of AnalyzeBranch requires the helper methods RemoveBranch -and InsertBranch to manage subsequent operations. -

- -

-AnalyzeBranch should return false indicating success in most circumstances. -AnalyzeBranch should only return true when the method is stumped about what to -do, for example, if a block has three terminating branches. AnalyzeBranch may -return true if it encounters a terminator it cannot handle, such as an indirect -branch. -

- -
- -
- - -

- Instruction Selector -

- - -
- -

-LLVM uses a SelectionDAG to represent LLVM IR instructions, and nodes -of the SelectionDAG ideally represent native target -instructions. During code generation, instruction selection passes are performed -to convert non-native DAG instructions into native target-specific -instructions. The pass described in XXXISelDAGToDAG.cpp is used to -match patterns and perform DAG-to-DAG instruction selection. Optionally, a pass -may be defined (in XXXBranchSelector.cpp) to perform similar DAG-to-DAG -operations for branch instructions. Later, the code in -XXXISelLowering.cpp replaces or removes operations and data types not -supported natively (legalizes) in a SelectionDAG. -

- -

-TableGen generates code for instruction selection using the following target -description input files: -

- -
    -
  • XXXInstrInfo.td — Contains definitions of instructions in a - target-specific instruction set, generates XXXGenDAGISel.inc, which - is included in XXXISelDAGToDAG.cpp.
  • - -
  • XXXCallingConv.td — Contains the calling and return value - conventions for the target architecture, and it generates - XXXGenCallingConv.inc, which is included in - XXXISelLowering.cpp.
  • -
- -

-The implementation of an instruction selection pass must include a header that -declares the FunctionPass class or a subclass of FunctionPass. In -XXXTargetMachine.cpp, a Pass Manager (PM) should add each instruction -selection pass into the queue of passes to run. -

- -

-The LLVM static compiler (llc) is an excellent tool for visualizing the -contents of DAGs. To display the SelectionDAG before or after specific -processing phases, use the command line options for llc, described -at -SelectionDAG Instruction Selection Process. -

- -

-To describe instruction selector behavior, you should add patterns for lowering -LLVM code into a SelectionDAG as the last parameter of the instruction -definitions in XXXInstrInfo.td. For example, in -SparcInstrInfo.td, this entry defines a register store operation, and -the last parameter describes a pattern with the store DAG operator. -

- -
-
-def STrr  : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
-                 "st $src, [$addr]", [(store IntRegs:$src, ADDRrr:$addr)]>;
-
-
- -

-ADDRrr is a memory mode that is also defined in -SparcInstrInfo.td: -

- -
-
-def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>;
-
-
- -

-The definition of ADDRrr refers to SelectADDRrr, which is a -function defined in an implementation of the Instructor Selector (such -as SparcISelDAGToDAG.cpp). -

- -

-In lib/Target/TargetSelectionDAG.td, the DAG operator for store is -defined below: -

- -
-
-def store : PatFrag<(ops node:$val, node:$ptr),
-                    (st node:$val, node:$ptr), [{
-  if (StoreSDNode *ST = dyn_cast<StoreSDNode>(N))
-    return !ST->isTruncatingStore() && 
-           ST->getAddressingMode() == ISD::UNINDEXED;
-  return false;
-}]>;
-
-
- -

-XXXInstrInfo.td also generates (in XXXGenDAGISel.inc) the -SelectCode method that is used to call the appropriate processing -method for an instruction. In this example, SelectCode -calls Select_ISD_STORE for the ISD::STORE opcode. -

- -
-
-SDNode *SelectCode(SDValue N) {
-  ... 
-  MVT::ValueType NVT = N.getNode()->getValueType(0);
-  switch (N.getOpcode()) {
-  case ISD::STORE: {
-    switch (NVT) {
-    default:
-      return Select_ISD_STORE(N);
-      break;
-    }
-    break;
-  }
-  ...
-
-
- -

-The pattern for STrr is matched, so elsewhere in -XXXGenDAGISel.inc, code for STrr is created for -Select_ISD_STORE. The Emit_22 method is also generated -in XXXGenDAGISel.inc to complete the processing of this -instruction. -

- -
-
-SDNode *Select_ISD_STORE(const SDValue &N) {
-  SDValue Chain = N.getOperand(0);
-  if (Predicate_store(N.getNode())) {
-    SDValue N1 = N.getOperand(1);
-    SDValue N2 = N.getOperand(2);
-    SDValue CPTmp0;
-    SDValue CPTmp1;
-
-    // Pattern: (st:void IntRegs:i32:$src, 
-    //           ADDRrr:i32:$addr)<<P:Predicate_store>>
-    // Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)
-    // Pattern complexity = 13  cost = 1  size = 0
-    if (SelectADDRrr(N, N2, CPTmp0, CPTmp1) &&
-        N1.getNode()->getValueType(0) == MVT::i32 &&
-        N2.getNode()->getValueType(0) == MVT::i32) {
-      return Emit_22(N, SP::STrr, CPTmp0, CPTmp1);
-    }
-...
-
-
- - -

- The SelectionDAG Legalize Phase -

- -
- -

-The Legalize phase converts a DAG to use types and operations that are natively -supported by the target. For natively unsupported types and operations, you need -to add code to the target-specific XXXTargetLowering implementation to convert -unsupported types and operations to supported ones. -

- -

-In the constructor for the XXXTargetLowering class, first use the -addRegisterClass method to specify which types are supports and which -register classes are associated with them. The code for the register classes are -generated by TableGen from XXXRegisterInfo.td and placed -in XXXGenRegisterInfo.h.inc. For example, the implementation of the -constructor for the SparcTargetLowering class (in -SparcISelLowering.cpp) starts with the following code: -

- -
-
-addRegisterClass(MVT::i32, SP::IntRegsRegisterClass);
-addRegisterClass(MVT::f32, SP::FPRegsRegisterClass);
-addRegisterClass(MVT::f64, SP::DFPRegsRegisterClass); 
-
-
- -

-You should examine the node types in the ISD namespace -(include/llvm/CodeGen/SelectionDAGNodes.h) and determine which -operations the target natively supports. For operations that do not have -native support, add a callback to the constructor for the XXXTargetLowering -class, so the instruction selection process knows what to do. The TargetLowering -class callback methods (declared in llvm/Target/TargetLowering.h) are: -

- -
    -
  • setOperationAction — General operation.
  • - -
  • setLoadExtAction — Load with extension.
  • - -
  • setTruncStoreAction — Truncating store.
  • - -
  • setIndexedLoadAction — Indexed load.
  • - -
  • setIndexedStoreAction — Indexed store.
  • - -
  • setConvertAction — Type conversion.
  • - -
  • setCondCodeAction — Support for a given condition code.
  • -
- -

-Note: on older releases, setLoadXAction is used instead -of setLoadExtAction. Also, on older releases, -setCondCodeAction may not be supported. Examine your release -to see what methods are specifically supported. -

- -

-These callbacks are used to determine that an operation does or does not work -with a specified type (or types). And in all cases, the third parameter is -a LegalAction type enum value: Promote, Expand, -Custom, or Legal. SparcISelLowering.cpp -contains examples of all four LegalAction values. -

- - -

- Promote -

- -
- -

-For an operation without native support for a given type, the specified type may -be promoted to a larger type that is supported. For example, SPARC does not -support a sign-extending load for Boolean values (i1 type), so -in SparcISelLowering.cpp the third parameter below, Promote, -changes i1 type values to a large type before loading. -

- -
-
-setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote);
-
-
- -
- - -

- Expand -

- -
- -

-For a type without native support, a value may need to be broken down further, -rather than promoted. For an operation without native support, a combination of -other operations may be used to similar effect. In SPARC, the floating-point -sine and cosine trig operations are supported by expansion to other operations, -as indicated by the third parameter, Expand, to -setOperationAction: -

- -
-
-setOperationAction(ISD::FSIN, MVT::f32, Expand);
-setOperationAction(ISD::FCOS, MVT::f32, Expand);
-
-
- -
- - -

- Custom -

- -
- -

-For some operations, simple type promotion or operation expansion may be -insufficient. In some cases, a special intrinsic function must be implemented. -

- -

-For example, a constant value may require special treatment, or an operation may -require spilling and restoring registers in the stack and working with register -allocators. -

- -

-As seen in SparcISelLowering.cpp code below, to perform a type -conversion from a floating point value to a signed integer, first the -setOperationAction should be called with Custom as the third -parameter: -

- -
-
-setOperationAction(ISD::FP_TO_SINT, MVT::i32, Custom);
-
-
- -

-In the LowerOperation method, for each Custom operation, a -case statement should be added to indicate what function to call. In the -following code, an FP_TO_SINT opcode will call -the LowerFP_TO_SINT method: -

- -
-
-SDValue SparcTargetLowering::LowerOperation(SDValue Op, SelectionDAG &DAG) {
-  switch (Op.getOpcode()) {
-  case ISD::FP_TO_SINT: return LowerFP_TO_SINT(Op, DAG);
-  ...
-  }
-}
-
-
- -

-Finally, the LowerFP_TO_SINT method is implemented, using an FP -register to convert the floating-point value to an integer. -

- -
-
-static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &DAG) {
-  assert(Op.getValueType() == MVT::i32);
-  Op = DAG.getNode(SPISD::FTOI, MVT::f32, Op.getOperand(0));
-  return DAG.getNode(ISD::BITCAST, MVT::i32, Op);
-}
-
-
- -
- - -

- Legal -

- -
- -

-The Legal LegalizeAction enum value simply indicates that an -operation is natively supported. Legal represents the default -condition, so it is rarely used. In SparcISelLowering.cpp, the action -for CTPOP (an operation to count the bits set in an integer) is -natively supported only for SPARC v9. The following code enables -the Expand conversion technique for non-v9 SPARC implementations. -

- -
-
-setOperationAction(ISD::CTPOP, MVT::i32, Expand);
-...
-if (TM.getSubtarget<SparcSubtarget>().isV9())
-  setOperationAction(ISD::CTPOP, MVT::i32, Legal);
-  case ISD::SETULT: return SPCC::ICC_CS;
-  case ISD::SETULE: return SPCC::ICC_LEU;
-  case ISD::SETUGT: return SPCC::ICC_GU;
-  case ISD::SETUGE: return SPCC::ICC_CC;
-  }
-}
-
-
- -
- -
- - -

- Calling Conventions -

- -
- -

-To support target-specific calling conventions, XXXGenCallingConv.td -uses interfaces (such as CCIfType and CCAssignToReg) that are defined in -lib/Target/TargetCallingConv.td. TableGen can take the target -descriptor file XXXGenCallingConv.td and generate the header -file XXXGenCallingConv.inc, which is typically included -in XXXISelLowering.cpp. You can use the interfaces in -TargetCallingConv.td to specify: -

- -
    -
  • The order of parameter allocation.
  • - -
  • Where parameters and return values are placed (that is, on the stack or in - registers).
  • - -
  • Which registers may be used.
  • - -
  • Whether the caller or callee unwinds the stack.
  • -
- -

-The following example demonstrates the use of the CCIfType and -CCAssignToReg interfaces. If the CCIfType predicate is true -(that is, if the current argument is of type f32 or f64), then -the action is performed. In this case, the CCAssignToReg action assigns -the argument value to the first available register: either R0 -or R1. -

- -
-
-CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>>
-
-
- -

-SparcCallingConv.td contains definitions for a target-specific -return-value calling convention (RetCC_Sparc32) and a basic 32-bit C calling -convention (CC_Sparc32). The definition of RetCC_Sparc32 -(shown below) indicates which registers are used for specified scalar return -types. A single-precision float is returned to register F0, and a -double-precision float goes to register D0. A 32-bit integer is -returned in register I0 or I1. -

- -
-
-def RetCC_Sparc32 : CallingConv<[
-  CCIfType<[i32], CCAssignToReg<[I0, I1]>>,
-  CCIfType<[f32], CCAssignToReg<[F0]>>,
-  CCIfType<[f64], CCAssignToReg<[D0]>>
-]>;
-
-
- -

-The definition of CC_Sparc32 in SparcCallingConv.td introduces -CCAssignToStack, which assigns the value to a stack slot with the -specified size and alignment. In the example below, the first parameter, 4, -indicates the size of the slot, and the second parameter, also 4, indicates the -stack alignment along 4-byte units. (Special cases: if size is zero, then the -ABI size is used; if alignment is zero, then the ABI alignment is used.) -

- -
-
-def CC_Sparc32 : CallingConv<[
-  // All arguments get passed in integer registers if there is space.
-  CCIfType<[i32, f32, f64], CCAssignToReg<[I0, I1, I2, I3, I4, I5]>>,
-  CCAssignToStack<4, 4>
-]>;
-
-
- -

-CCDelegateTo is another commonly used interface, which tries to find a -specified sub-calling convention, and, if a match is found, it is invoked. In -the following example (in X86CallingConv.td), the definition of -RetCC_X86_32_C ends with CCDelegateTo. After the current value -is assigned to the register ST0 or ST1, -the RetCC_X86Common is invoked. -

- -
-
-def RetCC_X86_32_C : CallingConv<[
-  CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>,
-  CCIfType<[f64], CCAssignToReg<[ST0, ST1]>>,
-  CCDelegateTo<RetCC_X86Common>
-]>;
-
-
- -

-CCIfCC is an interface that attempts to match the given name to the -current calling convention. If the name identifies the current calling -convention, then a specified action is invoked. In the following example (in -X86CallingConv.td), if the Fast calling convention is in use, -then RetCC_X86_32_Fast is invoked. If the SSECall calling -convention is in use, then RetCC_X86_32_SSE is invoked. -

- -
-
-def RetCC_X86_32 : CallingConv<[
-  CCIfCC<"CallingConv::Fast", CCDelegateTo<RetCC_X86_32_Fast>>,
-  CCIfCC<"CallingConv::X86_SSECall", CCDelegateTo<RetCC_X86_32_SSE>>,
-  CCDelegateTo<RetCC_X86_32_C>
-]>;
-
-
- -

Other calling convention interfaces include:

- -
    -
  • CCIf <predicate, action> — If the predicate matches, - apply the action.
  • - -
  • CCIfInReg <action> — If the argument is marked with the - 'inreg' attribute, then apply the action.
  • - -
  • CCIfNest <action> — Inf the argument is marked with the - 'nest' attribute, then apply the action.
  • - -
  • CCIfNotVarArg <action> — If the current function does - not take a variable number of arguments, apply the action.
  • - -
  • CCAssignToRegWithShadow <registerList, shadowList> — - similar to CCAssignToReg, but with a shadow list of registers.
  • - -
  • CCPassByVal <size, align> — Assign value to a stack - slot with the minimum specified size and alignment.
  • - -
  • CCPromoteToType <type> — Promote the current value to - the specified type.
  • - -
  • CallingConv <[actions]> — Define each calling - convention that is supported.
  • -
- -
- -
- - -

- Assembly Printer -

- - -
- -

-During the code emission stage, the code generator may utilize an LLVM pass to -produce assembly output. To do this, you want to implement the code for a -printer that converts LLVM IR to a GAS-format assembly language for your target -machine, using the following steps: -

- -
    -
  • Define all the assembly strings for your target, adding them to the - instructions defined in the XXXInstrInfo.td file. - (See Instruction Set.) TableGen will produce - an output file (XXXGenAsmWriter.inc) with an implementation of - the printInstruction method for the XXXAsmPrinter class.
  • - -
  • Write XXXTargetAsmInfo.h, which contains the bare-bones declaration - of the XXXTargetAsmInfo class (a subclass - of TargetAsmInfo).
  • - -
  • Write XXXTargetAsmInfo.cpp, which contains target-specific values - for TargetAsmInfo properties and sometimes new implementations for - methods.
  • - -
  • Write XXXAsmPrinter.cpp, which implements the AsmPrinter - class that performs the LLVM-to-assembly conversion.
  • -
- -

-The code in XXXTargetAsmInfo.h is usually a trivial declaration of the -XXXTargetAsmInfo class for use in XXXTargetAsmInfo.cpp. -Similarly, XXXTargetAsmInfo.cpp usually has a few declarations of -XXXTargetAsmInfo replacement values that override the default values -in TargetAsmInfo.cpp. For example in SparcTargetAsmInfo.cpp: -

- -
-
-SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &TM) {
-  Data16bitsDirective = "\t.half\t";
-  Data32bitsDirective = "\t.word\t";
-  Data64bitsDirective = 0;  // .xword is only supported by V9.
-  ZeroDirective = "\t.skip\t";
-  CommentString = "!";
-  ConstantPoolSection = "\t.section \".rodata\",#alloc\n";
-}
-
-
- -

-The X86 assembly printer implementation (X86TargetAsmInfo) is an -example where the target specific TargetAsmInfo class uses an -overridden methods: ExpandInlineAsm. -

- -

-A target-specific implementation of AsmPrinter is written in -XXXAsmPrinter.cpp, which implements the AsmPrinter class that -converts the LLVM to printable assembly. The implementation must include the -following headers that have declarations for the AsmPrinter and -MachineFunctionPass classes. The MachineFunctionPass is a -subclass of FunctionPass. -

- -
-
-#include "llvm/CodeGen/AsmPrinter.h"
-#include "llvm/CodeGen/MachineFunctionPass.h" 
-
-
- -

-As a FunctionPass, AsmPrinter first -calls doInitialization to set up the AsmPrinter. In -SparcAsmPrinter, a Mangler object is instantiated to process -variable names. -

- -

-In XXXAsmPrinter.cpp, the runOnMachineFunction method -(declared in MachineFunctionPass) must be implemented -for XXXAsmPrinter. In MachineFunctionPass, -the runOnFunction method invokes runOnMachineFunction. -Target-specific implementations of runOnMachineFunction differ, but -generally do the following to process each machine function: -

- -
    -
  • Call SetupMachineFunction to perform initialization.
  • - -
  • Call EmitConstantPool to print out (to the output stream) constants - which have been spilled to memory.
  • - -
  • Call EmitJumpTableInfo to print out jump tables used by the current - function.
  • - -
  • Print out the label for the current function.
  • - -
  • Print out the code for the function, including basic block labels and the - assembly for the instruction (using printInstruction)
  • -
- -

-The XXXAsmPrinter implementation must also include the code generated -by TableGen that is output in the XXXGenAsmWriter.inc file. The code -in XXXGenAsmWriter.inc contains an implementation of the -printInstruction method that may call these methods: -

- -
    -
  • printOperand
  • - -
  • printMemOperand
  • - -
  • printCCOperand (for conditional statements)
  • - -
  • printDataDirective
  • - -
  • printDeclare
  • - -
  • printImplicitDef
  • - -
  • printInlineAsm
  • -
- -

-The implementations of printDeclare, printImplicitDef, -printInlineAsm, and printLabel in AsmPrinter.cpp are -generally adequate for printing assembly and do not need to be -overridden. -

- -

-The printOperand method is implemented with a long switch/case -statement for the type of operand: register, immediate, basic block, external -symbol, global address, constant pool index, or jump table index. For an -instruction with a memory address operand, the printMemOperand method -should be implemented to generate the proper output. Similarly, -printCCOperand should be used to print a conditional operand. -

- -

doFinalization should be overridden in XXXAsmPrinter, and -it should be called to shut down the assembly printer. During -doFinalization, global variables and constants are printed to -output. -

- -
- - -

- Subtarget Support -

- - -
- -

-Subtarget support is used to inform the code generation process of instruction -set variations for a given chip set. For example, the LLVM SPARC implementation -provided covers three major versions of the SPARC microprocessor architecture: -Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a 64-bit -architecture), and the UltraSPARC architecture. V8 has 16 double-precision -floating-point registers that are also usable as either 32 single-precision or 8 -quad-precision registers. V8 is also purely big-endian. V9 has 32 -double-precision floating-point registers that are also usable as 16 -quad-precision registers, but cannot be used as single-precision registers. The -UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set -extensions. -

- -

-If subtarget support is needed, you should implement a target-specific -XXXSubtarget class for your architecture. This class should process the -command-line options -mcpu= and -mattr=. -

- -

-TableGen uses definitions in the Target.td and Sparc.td files -to generate code in SparcGenSubtarget.inc. In Target.td, shown -below, the SubtargetFeature interface is defined. The first 4 string -parameters of the SubtargetFeature interface are a feature name, an -attribute set by the feature, the value of the attribute, and a description of -the feature. (The fifth parameter is a list of features whose presence is -implied, and its default value is an empty array.) -

- -
-
-class SubtargetFeature<string n, string a,  string v, string d,
-                       list<SubtargetFeature> i = []> {
-  string Name = n;
-  string Attribute = a;
-  string Value = v;
-  string Desc = d;
-  list<SubtargetFeature> Implies = i;
-}
-
-
- -

-In the Sparc.td file, the SubtargetFeature is used to define the -following features. -

- -
-
-def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true",
-                     "Enable SPARC-V9 instructions">;
-def FeatureV8Deprecated : SubtargetFeature<"deprecated-v8", 
-                     "V8DeprecatedInsts", "true",
-                     "Enable deprecated V8 instructions in V9 mode">;
-def FeatureVIS : SubtargetFeature<"vis", "IsVIS", "true",
-                     "Enable UltraSPARC Visual Instruction Set extensions">;
-
-
- -

-Elsewhere in Sparc.td, the Proc class is defined and then is used to -define particular SPARC processor subtypes that may have the previously -described features. -

- -
-
-class Proc<string Name, list<SubtargetFeature> Features>
-  : Processor<Name, NoItineraries, Features>;
- 
-def : Proc<"generic",         []>;
-def : Proc<"v8",              []>;
-def : Proc<"supersparc",      []>;
-def : Proc<"sparclite",       []>;
-def : Proc<"f934",            []>;
-def : Proc<"hypersparc",      []>;
-def : Proc<"sparclite86x",    []>;
-def : Proc<"sparclet",        []>;
-def : Proc<"tsc701",          []>;
-def : Proc<"v9",              [FeatureV9]>;
-def : Proc<"ultrasparc",      [FeatureV9, FeatureV8Deprecated]>;
-def : Proc<"ultrasparc3",     [FeatureV9, FeatureV8Deprecated]>;
-def : Proc<"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]>;
-
-
- -

-From Target.td and Sparc.td files, the resulting -SparcGenSubtarget.inc specifies enum values to identify the features, arrays of -constants to represent the CPU features and CPU subtypes, and the -ParseSubtargetFeatures method that parses the features string that sets -specified subtarget options. The generated SparcGenSubtarget.inc file -should be included in the SparcSubtarget.cpp. The target-specific -implementation of the XXXSubtarget method should follow this pseudocode: -

- -
-
-XXXSubtarget::XXXSubtarget(const Module &M, const std::string &FS) {
-  // Set the default features
-  // Determine default and user specified characteristics of the CPU
-  // Call ParseSubtargetFeatures(FS, CPU) to parse the features string
-  // Perform any additional operations
-}
-
-
- -
- - -

- JIT Support -

- - -
- -

-The implementation of a target machine optionally includes a Just-In-Time (JIT) -code generator that emits machine code and auxiliary structures as binary output -that can be written directly to memory. To do this, implement JIT code -generation by performing the following steps: -

- -
    -
  • Write an XXXCodeEmitter.cpp file that contains a machine function - pass that transforms target-machine instructions into relocatable machine - code.
  • - -
  • Write an XXXJITInfo.cpp file that implements the JIT interfaces for - target-specific code-generation activities, such as emitting machine code - and stubs.
  • - -
  • Modify XXXTargetMachine so that it provides a - TargetJITInfo object through its getJITInfo method.
  • -
- -

-There are several different approaches to writing the JIT support code. For -instance, TableGen and target descriptor files may be used for creating a JIT -code generator, but are not mandatory. For the Alpha and PowerPC target -machines, TableGen is used to generate XXXGenCodeEmitter.inc, which -contains the binary coding of machine instructions and the -getBinaryCodeForInstr method to access those codes. Other JIT -implementations do not. -

- -

-Both XXXJITInfo.cpp and XXXCodeEmitter.cpp must include the -llvm/CodeGen/MachineCodeEmitter.h header file that defines the -MachineCodeEmitter class containing code for several callback functions -that write data (in bytes, words, strings, etc.) to the output stream. -

- - -

- Machine Code Emitter -

- -
- -

-In XXXCodeEmitter.cpp, a target-specific of the Emitter class -is implemented as a function pass (subclass -of MachineFunctionPass). The target-specific implementation -of runOnMachineFunction (invoked by -runOnFunction in MachineFunctionPass) iterates through the -MachineBasicBlock calls emitInstruction to process each -instruction and emit binary code. emitInstruction is largely -implemented with case statements on the instruction types defined in -XXXInstrInfo.h. For example, in X86CodeEmitter.cpp, -the emitInstruction method is built around the following switch/case -statements: -

- -
-
-switch (Desc->TSFlags & X86::FormMask) {
-case X86II::Pseudo:  // for not yet implemented instructions 
-   ...               // or pseudo-instructions
-   break;
-case X86II::RawFrm:  // for instructions with a fixed opcode value
-   ...
-   break;
-case X86II::AddRegFrm: // for instructions that have one register operand 
-   ...                 // added to their opcode
-   break;
-case X86II::MRMDestReg:// for instructions that use the Mod/RM byte
-   ...                 // to specify a destination (register)
-   break;
-case X86II::MRMDestMem:// for instructions that use the Mod/RM byte
-   ...                 // to specify a destination (memory)
-   break;
-case X86II::MRMSrcReg: // for instructions that use the Mod/RM byte
-   ...                 // to specify a source (register)
-   break;
-case X86II::MRMSrcMem: // for instructions that use the Mod/RM byte
-   ...                 // to specify a source (memory)
-   break;
-case X86II::MRM0r: case X86II::MRM1r:  // for instructions that operate on 
-case X86II::MRM2r: case X86II::MRM3r:  // a REGISTER r/m operand and
-case X86II::MRM4r: case X86II::MRM5r:  // use the Mod/RM byte and a field
-case X86II::MRM6r: case X86II::MRM7r:  // to hold extended opcode data
-   ...  
-   break;
-case X86II::MRM0m: case X86II::MRM1m:  // for instructions that operate on
-case X86II::MRM2m: case X86II::MRM3m:  // a MEMORY r/m operand and
-case X86II::MRM4m: case X86II::MRM5m:  // use the Mod/RM byte and a field
-case X86II::MRM6m: case X86II::MRM7m:  // to hold extended opcode data
-   ...  
-   break;
-case X86II::MRMInitReg: // for instructions whose source and
-   ...                  // destination are the same register
-   break;
-}
-
-
- -

-The implementations of these case statements often first emit the opcode and -then get the operand(s). Then depending upon the operand, helper methods may be -called to process the operand(s). For example, in X86CodeEmitter.cpp, -for the X86II::AddRegFrm case, the first data emitted -(by emitByte) is the opcode added to the register operand. Then an -object representing the machine operand, MO1, is extracted. The helper -methods such as isImmediate, -isGlobalAddress, isExternalSymbol, isConstantPoolIndex, and -isJumpTableIndex determine the operand -type. (X86CodeEmitter.cpp also has private methods such -as emitConstant, emitGlobalAddress, -emitExternalSymbolAddress, emitConstPoolAddress, -and emitJumpTableAddress that emit the data into the output stream.) -

- -
-
-case X86II::AddRegFrm:
-  MCE.emitByte(BaseOpcode + getX86RegNum(MI.getOperand(CurOp++).getReg()));
-  
-  if (CurOp != NumOps) {
-    const MachineOperand &MO1 = MI.getOperand(CurOp++);
-    unsigned Size = X86InstrInfo::sizeOfImm(Desc);
-    if (MO1.isImmediate())
-      emitConstant(MO1.getImm(), Size);
-    else {
-      unsigned rt = Is64BitMode ? X86::reloc_pcrel_word
-        : (IsPIC ? X86::reloc_picrel_word : X86::reloc_absolute_word);
-      if (Opcode == X86::MOV64ri) 
-        rt = X86::reloc_absolute_dword;  // FIXME: add X86II flag?
-      if (MO1.isGlobalAddress()) {
-        bool NeedStub = isa<Function>(MO1.getGlobal());
-        bool isLazy = gvNeedsLazyPtr(MO1.getGlobal());
-        emitGlobalAddress(MO1.getGlobal(), rt, MO1.getOffset(), 0,
-                          NeedStub, isLazy);
-      } else if (MO1.isExternalSymbol())
-        emitExternalSymbolAddress(MO1.getSymbolName(), rt);
-      else if (MO1.isConstantPoolIndex())
-        emitConstPoolAddress(MO1.getIndex(), rt);
-      else if (MO1.isJumpTableIndex())
-        emitJumpTableAddress(MO1.getIndex(), rt);
-    }
-  }
-  break;
-
-
- -

-In the previous example, XXXCodeEmitter.cpp uses the -variable rt, which is a RelocationType enum that may be used to -relocate addresses (for example, a global address with a PIC base offset). The -RelocationType enum for that target is defined in the short -target-specific XXXRelocations.h file. The RelocationType is used by -the relocate method defined in XXXJITInfo.cpp to rewrite -addresses for referenced global symbols. -

- -

-For example, X86Relocations.h specifies the following relocation types -for the X86 addresses. In all four cases, the relocated value is added to the -value already in memory. For reloc_pcrel_word -and reloc_picrel_word, there is an additional initial adjustment. -

- -
-
-enum RelocationType {
-  reloc_pcrel_word = 0,    // add reloc value after adjusting for the PC loc
-  reloc_picrel_word = 1,   // add reloc value after adjusting for the PIC base
-  reloc_absolute_word = 2, // absolute relocation; no additional adjustment 
-  reloc_absolute_dword = 3 // absolute relocation; no additional adjustment
-};
-
-
- -
- - -

- Target JIT Info -

- -
- -

-XXXJITInfo.cpp implements the JIT interfaces for target-specific -code-generation activities, such as emitting machine code and stubs. At minimum, -a target-specific version of XXXJITInfo implements the following: -

- -
    -
  • getLazyResolverFunction — Initializes the JIT, gives the - target a function that is used for compilation.
  • - -
  • emitFunctionStub — Returns a native function with a specified - address for a callback function.
  • - -
  • relocate — Changes the addresses of referenced globals, based - on relocation types.
  • - -
  • Callback function that are wrappers to a function stub that is used when the - real target is not initially known.
  • -
- -

-getLazyResolverFunction is generally trivial to implement. It makes the -incoming parameter as the global JITCompilerFunction and returns the -callback function that will be used a function wrapper. For the Alpha target -(in AlphaJITInfo.cpp), the getLazyResolverFunction -implementation is simply: -

- -
-
-TargetJITInfo::LazyResolverFn AlphaJITInfo::getLazyResolverFunction(  
-                                            JITCompilerFn F) {
-  JITCompilerFunction = F;
-  return AlphaCompilationCallback;
-}
-
-
- -

-For the X86 target, the getLazyResolverFunction implementation is a -little more complication, because it returns a different callback function for -processors with SSE instructions and XMM registers. -

- -

-The callback function initially saves and later restores the callee register -values, incoming arguments, and frame and return address. The callback function -needs low-level access to the registers or stack, so it is typically implemented -with assembler. -

- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Mason Woo and Misha Brukman
- The LLVM Compiler Infrastructure -
- Last modified: $Date: 2012-03-01 07:14:19 -0800 (Thu, 01 Mar 2012) $ -
- - - diff --git a/cpp/llvm/docs/WritingAnLLVMPass.html b/cpp/llvm/docs/WritingAnLLVMPass.html deleted file mode 100644 index 4553f259..00000000 --- a/cpp/llvm/docs/WritingAnLLVMPass.html +++ /dev/null @@ -1,1954 +0,0 @@ - - - - - Writing an LLVM Pass - - - - -

- Writing an LLVM Pass -

- -
    -
  1. Introduction - What is a pass?
  2. -
  3. Quick Start - Writing hello world -
  4. -
  5. Pass classes and requirements - -
  6. Pass Registration -
  7. -
  8. Specifying interactions between passes -
  9. -
  10. Implementing Analysis Groups -
  11. -
  12. Pass Statistics -
  13. What PassManager does -
  14. -
  15. Registering dynamically loaded passes -
  16. -
  17. Using GDB with dynamically loaded passes -
  18. -
  19. Future extensions planned -
  20. -
- -
-

Written by Chris Lattner and - Jim Laskey

-
- - -

- Introduction - What is a pass? -

- - -
- -

The LLVM Pass Framework is an important part of the LLVM system, because LLVM -passes are where most of the interesting parts of the compiler exist. Passes -perform the transformations and optimizations that make up the compiler, they -build the analysis results that are used by these transformations, and they are, -above all, a structuring technique for compiler code.

- -

All LLVM passes are subclasses of the Pass -class, which implement functionality by overriding virtual methods inherited -from Pass. Depending on how your pass works, you should inherit from -the ModulePass, CallGraphSCCPass, FunctionPass, or LoopPass, or RegionPass, or BasicBlockPass classes, which gives the system -more information about what your pass does, and how it can be combined with -other passes. One of the main features of the LLVM Pass Framework is that it -schedules passes to run in an efficient way based on the constraints that your -pass meets (which are indicated by which class they derive from).

- -

We start by showing you how to construct a pass, everything from setting up -the code, to compiling, loading, and executing it. After the basics are down, -more advanced features are discussed.

- -
- - -

- Quick Start - Writing hello world -

- - -
- -

Here we describe how to write the "hello world" of passes. The "Hello" pass -is designed to simply print out the name of non-external functions that exist in -the program being compiled. It does not modify the program at all, it just -inspects it. The source code and files for this pass are available in the LLVM -source tree in the lib/Transforms/Hello directory.

- - -

- Setting up the build environment -

- -
- -

First, configure and build LLVM. This needs to be done directly inside the - LLVM source tree rather than in a separate objects directory. - Next, you need to create a new directory somewhere in the LLVM source - base. For this example, we'll assume that you made - lib/Transforms/Hello. Finally, you must set up a build script - (Makefile) that will compile the source code for the new pass. To do this, - copy the following into Makefile:

-
- -
-# Makefile for hello pass
-
-# Path to top level of LLVM hierarchy
-LEVEL = ../../..
-
-# Name of the library to build
-LIBRARYNAME = Hello
-
-# Make the shared library become a loadable module so the tools can 
-# dlopen/dlsym on the resulting library.
-LOADABLE_MODULE = 1
-
-# Include the makefile implementation stuff
-include $(LEVEL)/Makefile.common
-
- -

This makefile specifies that all of the .cpp files in the current -directory are to be compiled and linked together into a shared object -$(LEVEL)/Debug+Asserts/lib/Hello.so that can be dynamically loaded by -the opt or bugpoint tools via their -load options. -If your operating system uses a suffix other than .so (such as windows or -Mac OS/X), the appropriate extension will be used.

- -

If you are used CMake to build LLVM, see -Developing an LLVM pass with CMake.

- -

Now that we have the build scripts set up, we just need to write the code for -the pass itself.

- -
- - -

- Basic code required -

- -
- -

Now that we have a way to compile our new pass, we just have to write it. -Start out with:

- -
-
-#include "llvm/Pass.h"
-#include "llvm/Function.h"
-#include "llvm/Support/raw_ostream.h"
-
-
- -

Which are needed because we are writing a Pass, -we are operating on Function's, -and we will be doing some printing.

- -

Next we have:

- -
-
-using namespace llvm;
-
-
- -

... which is required because the functions from the include files -live in the llvm namespace.

- -

Next we have:

- -
-
-namespace {
-
-
- -

... which starts out an anonymous namespace. Anonymous namespaces are to C++ -what the "static" keyword is to C (at global scope). It makes the -things declared inside of the anonymous namespace visible only to the current -file. If you're not familiar with them, consult a decent C++ book for more -information.

- -

Next, we declare our pass itself:

- -
-
-  struct Hello : public FunctionPass {
-
-
- -

This declares a "Hello" class that is a subclass of FunctionPass. -The different builtin pass subclasses are described in detail later, but for now, know that FunctionPass's operate on a function at a -time.

- -
-
-    static char ID;
-    Hello() : FunctionPass(ID) {}
-
-
- -

This declares pass identifier used by LLVM to identify pass. This allows LLVM -to avoid using expensive C++ runtime information.

- -
-
-    virtual bool runOnFunction(Function &F) {
-      errs() << "Hello: ";
-      errs().write_escaped(F.getName()) << "\n";
-      return false;
-    }
-  };  // end of struct Hello
-}  // end of anonymous namespace
-
-
- -

We declare a "runOnFunction" method, -which overloads an abstract virtual method inherited from FunctionPass. This is where we are supposed -to do our thing, so we just print out our message with the name of each -function.

- -
-
-char Hello::ID = 0;
-
-
- -

We initialize pass ID here. LLVM uses ID's address to identify a pass, so -initialization value is not important.

- -
-
-static RegisterPass<Hello> X("hello", "Hello World Pass",
-                             false /* Only looks at CFG */,
-                             false /* Analysis Pass */);
-
-
- -

Lastly, we register our class Hello, -giving it a command line argument "hello", and a name "Hello World -Pass". The last two arguments describe its behavior: if a pass walks CFG -without modifying it then the third argument is set to true; if a pass -is an analysis pass, for example dominator tree pass, then true is -supplied as the fourth argument.

- -

As a whole, the .cpp file looks like:

- -
-
-#include "llvm/Pass.h"
-#include "llvm/Function.h"
-#include "llvm/Support/raw_ostream.h"
-
-using namespace llvm;
-
-namespace {
-  struct Hello : public FunctionPass {
-    
-    static char ID;
-    Hello() : FunctionPass(ID) {}
-
-    virtual bool runOnFunction(Function &F) {
-      errs() << "Hello: ";
-      errs().write_escaped(F.getName()) << '\n';
-      return false;
-    }
-
-  };
-}
-  
-char Hello::ID = 0;
-static RegisterPass<Hello> X("hello", "Hello World Pass", false, false);
-
-
- -

Now that it's all together, compile the file with a simple "gmake" -command in the local directory and you should get a new file -"Debug+Asserts/lib/Hello.so" under the top level directory of the LLVM -source tree (not in the local directory). Note that everything in this file is -contained in an anonymous namespace — this reflects the fact that passes -are self contained units that do not need external interfaces (although they can -have them) to be useful.

- -
- - -

- Running a pass with opt -

- -
- -

Now that you have a brand new shiny shared object file, we can use the -opt command to run an LLVM program through your pass. Because you -registered your pass with RegisterPass, you will be able to -use the opt tool to access it, once loaded.

- -

To test it, follow the example at the end of the Getting Started Guide to compile "Hello World" to -LLVM. We can now run the bitcode file (hello.bc) for the program -through our transformation like this (or course, any bitcode file will -work):

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello < hello.bc > /dev/null
-Hello: __main
-Hello: puts
-Hello: main
-
- -

The '-load' option specifies that 'opt' should load your -pass as a shared object, which makes '-hello' a valid command line -argument (which is one reason you need to register your -pass). Because the hello pass does not modify the program in any -interesting way, we just throw away the result of opt (sending it to -/dev/null).

- -

To see what happened to the other string you registered, try running -opt with the -help option:

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -help
-OVERVIEW: llvm .bc -> .bc modular optimizer
-
-USAGE: opt [options] <input bitcode>
-
-OPTIONS:
-  Optimizations available:
-...
-    -globalopt                - Global Variable Optimizer
-    -globalsmodref-aa         - Simple mod/ref analysis for globals
-    -gvn                      - Global Value Numbering
-    -hello                    - Hello World Pass
-    -indvars                  - Induction Variable Simplification
-    -inline                   - Function Integration/Inlining
-    -insert-edge-profiling    - Insert instrumentation for edge profiling
-...
-
- -

The pass name gets added as the information string for your pass, giving some -documentation to users of opt. Now that you have a working pass, you -would go ahead and make it do the cool transformations you want. Once you get -it all working and tested, it may become useful to find out how fast your pass -is. The PassManager provides a nice command -line option (--time-passes) that allows you to get information about -the execution time of your pass along with the other passes you queue up. For -example:

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello -time-passes < hello.bc > /dev/null
-Hello: __main
-Hello: puts
-Hello: main
-===============================================================================
-                      ... Pass execution timing report ...
-===============================================================================
-  Total Execution Time: 0.02 seconds (0.0479059 wall clock)
-
-   ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Pass Name ---
-   0.0100 (100.0%)   0.0000 (  0.0%)   0.0100 ( 50.0%)   0.0402 ( 84.0%)  Bitcode Writer
-   0.0000 (  0.0%)   0.0100 (100.0%)   0.0100 ( 50.0%)   0.0031 (  6.4%)  Dominator Set Construction
-   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0013 (  2.7%)  Module Verifier
-   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0033 (  6.9%)  Hello World Pass
-   0.0100 (100.0%)   0.0100 (100.0%)   0.0200 (100.0%)   0.0479 (100.0%)  TOTAL
-
- -

As you can see, our implementation above is pretty fast :). The additional -passes listed are automatically inserted by the 'opt' tool to verify -that the LLVM emitted by your pass is still valid and well formed LLVM, which -hasn't been broken somehow.

- -

Now that you have seen the basics of the mechanics behind passes, we can talk -about some more details of how they work and how to use them.

- -
- -
- - -

- Pass classes and requirements -

- - -
- -

One of the first things that you should do when designing a new pass is to -decide what class you should subclass for your pass. The Hello World example uses the FunctionPass class for its implementation, but we -did not discuss why or when this should occur. Here we talk about the classes -available, from the most general to the most specific.

- -

When choosing a superclass for your Pass, you should choose the most -specific class possible, while still being able to meet the requirements -listed. This gives the LLVM Pass Infrastructure information necessary to -optimize how passes are run, so that the resultant compiler isn't unnecessarily -slow.

- - -

- The ImmutablePass class -

- -
- -

The most plain and boring type of pass is the "ImmutablePass" -class. This pass type is used for passes that do not have to be run, do not -change state, and never need to be updated. This is not a normal type of -transformation or analysis, but can provide information about the current -compiler configuration.

- -

Although this pass class is very infrequently used, it is important for -providing information about the current target machine being compiled for, and -other static information that can affect the various transformations.

- -

ImmutablePasses never invalidate other transformations, are never -invalidated, and are never "run".

- -
- - -

- The ModulePass class -

- -
- -

The "ModulePass" -class is the most general of all superclasses that you can use. Deriving from -ModulePass indicates that your pass uses the entire program as a unit, -referring to function bodies in no predictable order, or adding and removing -functions. Because nothing is known about the behavior of ModulePass -subclasses, no optimization can be done for their execution.

- -

A module pass can use function level passes (e.g. dominators) using -the getAnalysis interface -getAnalysis<DominatorTree>(llvm::Function *) to provide the -function to retrieve analysis result for, if the function pass does not require -any module or immutable passes. Note that this can only be done for functions for which the -analysis ran, e.g. in the case of dominators you should only ask for the -DominatorTree for function definitions, not declarations.

- -

To write a correct ModulePass subclass, derive from -ModulePass and overload the runOnModule method with the -following signature:

- - -

- The runOnModule method -

- -
- -
-virtual bool runOnModule(Module &M) = 0;
-
- -

The runOnModule method performs the interesting work of the pass. -It should return true if the module was modified by the transformation and -false otherwise.

- -
- -
- - -

- The CallGraphSCCPass class -

- -
- -

The "CallGraphSCCPass" -is used by passes that need to traverse the program bottom-up on the call graph -(callees before callers). Deriving from CallGraphSCCPass provides some -mechanics for building and traversing the CallGraph, but also allows the system -to optimize execution of CallGraphSCCPass's. If your pass meets the -requirements outlined below, and doesn't meet the requirements of a FunctionPass or BasicBlockPass, you should derive from -CallGraphSCCPass.

- -

TODO: explain briefly what SCC, Tarjan's algo, and B-U mean.

- -

To be explicit, CallGraphSCCPass subclasses are:

- -
    - -
  1. ... not allowed to inspect or modify any Functions other -than those in the current SCC and the direct callers and direct callees of the -SCC.
  2. - -
  3. ... required to preserve the current CallGraph object, updating it -to reflect any changes made to the program.
  4. - -
  5. ... not allowed to add or remove SCC's from the current Module, -though they may change the contents of an SCC.
  6. - -
  7. ... allowed to add or remove global variables from the current -Module.
  8. - -
  9. ... allowed to maintain state across invocations of - runOnSCC (including global data).
  10. -
- -

Implementing a CallGraphSCCPass is slightly tricky in some cases -because it has to handle SCCs with more than one node in it. All of the virtual -methods described below should return true if they modified the program, or -false if they didn't.

- - -

- - The doInitialization(CallGraph &) method - -

- -
- -
-virtual bool doInitialization(CallGraph &CG);
-
- -

The doIninitialize method is allowed to do most of the things that -CallGraphSCCPass's are not allowed to do. They can add and remove -functions, get pointers to functions, etc. The doInitialization method -is designed to do simple initialization type of stuff that does not depend on -the SCCs being processed. The doInitialization method call is not -scheduled to overlap with any other pass executions (thus it should be very -fast).

- -
- - -

- The runOnSCC method -

- -
- -
-virtual bool runOnSCC(CallGraphSCC &SCC) = 0;
-
- -

The runOnSCC method performs the interesting work of the pass, and -should return true if the module was modified by the transformation, false -otherwise.

- -
- - -

- - The doFinalization(CallGraph &) method - -

- -
- -
-virtual bool doFinalization(CallGraph &CG);
-
- -

The doFinalization method is an infrequently used method that is -called when the pass framework has finished calling runOnFunction for every function in the -program being compiled.

- -
- -
- - -

- The FunctionPass class -

- -
- -

In contrast to ModulePass subclasses, FunctionPass -subclasses do have a predictable, local behavior that can be expected by the -system. All FunctionPass execute on each function in the program -independent of all of the other functions in the program. -FunctionPass's do not require that they are executed in a particular -order, and FunctionPass's do not modify external functions.

- -

To be explicit, FunctionPass subclasses are not allowed to:

- -
    -
  1. Modify a Function other than the one currently being processed.
  2. -
  3. Add or remove Function's from the current Module.
  4. -
  5. Add or remove global variables from the current Module.
  6. -
  7. Maintain state across invocations of - runOnFunction (including global data)
  8. -
- -

Implementing a FunctionPass is usually straightforward (See the Hello World pass for example). FunctionPass's -may overload three virtual methods to do their work. All of these methods -should return true if they modified the program, or false if they didn't.

- - -

- - The doInitialization(Module &) method - -

- -
- -
-virtual bool doInitialization(Module &M);
-
- -

The doIninitialize method is allowed to do most of the things that -FunctionPass's are not allowed to do. They can add and remove -functions, get pointers to functions, etc. The doInitialization method -is designed to do simple initialization type of stuff that does not depend on -the functions being processed. The doInitialization method call is not -scheduled to overlap with any other pass executions (thus it should be very -fast).

- -

A good example of how this method should be used is the LowerAllocations -pass. This pass converts malloc and free instructions into -platform dependent malloc() and free() function calls. It -uses the doInitialization method to get a reference to the malloc and -free functions that it needs, adding prototypes to the module if necessary.

- -
- - -

- The runOnFunction method -

- -
- -
-virtual bool runOnFunction(Function &F) = 0;
-

- -

The runOnFunction method must be implemented by your subclass to do -the transformation or analysis work of your pass. As usual, a true value should -be returned if the function is modified.

- -
- - -

- - The doFinalization(Module &) method - -

- -
- -
-virtual bool doFinalization(Module &M);
-
- -

The doFinalization method is an infrequently used method that is -called when the pass framework has finished calling runOnFunction for every function in the -program being compiled.

- -
- -
- - -

- The LoopPass class -

- -
- -

All LoopPass execute on each loop in the function independent of -all of the other loops in the function. LoopPass processes loops in -loop nest order such that outer most loop is processed last.

- -

LoopPass subclasses are allowed to update loop nest using -LPPassManager interface. Implementing a loop pass is usually -straightforward. LoopPass's may overload three virtual methods to -do their work. All these methods should return true if they modified the -program, or false if they didn't.

- - -

- - The doInitialization(Loop *,LPPassManager &) method - -

- -
- -
-virtual bool doInitialization(Loop *, LPPassManager &LPM);
-
- -

The doInitialization method is designed to do simple initialization -type of stuff that does not depend on the functions being processed. The -doInitialization method call is not scheduled to overlap with any -other pass executions (thus it should be very fast). LPPassManager -interface should be used to access Function or Module level analysis -information.

- -
- - - -

- The runOnLoop method -

- -
- -
-virtual bool runOnLoop(Loop *, LPPassManager &LPM) = 0;
-

- -

The runOnLoop method must be implemented by your subclass to do -the transformation or analysis work of your pass. As usual, a true value should -be returned if the function is modified. LPPassManager interface -should be used to update loop nest.

- -
- - -

- The doFinalization() method -

- -
- -
-virtual bool doFinalization();
-
- -

The doFinalization method is an infrequently used method that is -called when the pass framework has finished calling runOnLoop for every loop in the -program being compiled.

- -
- -
- - -

- The RegionPass class -

- -
- -

RegionPass is similar to LoopPass, -but executes on each single entry single exit region in the function. -RegionPass processes regions in nested order such that the outer most -region is processed last.

- -

RegionPass subclasses are allowed to update the region tree by using -the RGPassManager interface. You may overload three virtual methods of -RegionPass to implement your own region pass. All these -methods should return true if they modified the program, or false if they didn not. -

- - -

- - The doInitialization(Region *, RGPassManager &) method - -

- -
- -
-virtual bool doInitialization(Region *, RGPassManager &RGM);
-
- -

The doInitialization method is designed to do simple initialization -type of stuff that does not depend on the functions being processed. The -doInitialization method call is not scheduled to overlap with any -other pass executions (thus it should be very fast). RPPassManager -interface should be used to access Function or Module level analysis -information.

- -
- - - -

- The runOnRegion method -

- -
- -
-virtual bool runOnRegion(Region *, RGPassManager &RGM) = 0;
-

- -

The runOnRegion method must be implemented by your subclass to do -the transformation or analysis work of your pass. As usual, a true value should -be returned if the region is modified. RGPassManager interface -should be used to update region tree.

- -
- - -

- The doFinalization() method -

- -
- -
-virtual bool doFinalization();
-
- -

The doFinalization method is an infrequently used method that is -called when the pass framework has finished calling runOnRegion for every region in the -program being compiled.

- -
- -
- - -

- The BasicBlockPass class -

- -
- -

BasicBlockPass's are just like FunctionPass's, except that they must limit -their scope of inspection and modification to a single basic block at a time. -As such, they are not allowed to do any of the following:

- -
    -
  1. Modify or inspect any basic blocks outside of the current one
  2. -
  3. Maintain state across invocations of - runOnBasicBlock
  4. -
  5. Modify the control flow graph (by altering terminator instructions)
  6. -
  7. Any of the things forbidden for - FunctionPasses.
  8. -
- -

BasicBlockPasses are useful for traditional local and "peephole" -optimizations. They may override the same doInitialization(Module &) and doFinalization(Module &) methods that FunctionPass's have, but also have the following virtual methods that may also be implemented:

- - -

- - The doInitialization(Function &) method - -

- -
- -
-virtual bool doInitialization(Function &F);
-
- -

The doIninitialize method is allowed to do most of the things that -BasicBlockPass's are not allowed to do, but that -FunctionPass's can. The doInitialization method is designed -to do simple initialization that does not depend on the -BasicBlocks being processed. The doInitialization method call is not -scheduled to overlap with any other pass executions (thus it should be very -fast).

- -
- - -

- The runOnBasicBlock method -

- -
- -
-virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
-
- -

Override this function to do the work of the BasicBlockPass. This -function is not allowed to inspect or modify basic blocks other than the -parameter, and are not allowed to modify the CFG. A true value must be returned -if the basic block is modified.

- -
- - -

- - The doFinalization(Function &) method - -

- -
- -
-virtual bool doFinalization(Function &F);
-
- -

The doFinalization method is an infrequently used method that is -called when the pass framework has finished calling runOnBasicBlock for every BasicBlock in the -program being compiled. This can be used to perform per-function -finalization.

- -
- -
- - -

- The MachineFunctionPass class -

- -
- -

A MachineFunctionPass is a part of the LLVM code generator that -executes on the machine-dependent representation of each LLVM function in the -program.

- -

Code generator passes are registered and initialized specially by -TargetMachine::addPassesToEmitFile and similar routines, so they -cannot generally be run from the opt or bugpoint -commands.

- -

A MachineFunctionPass is also a FunctionPass, so all -the restrictions that apply to a FunctionPass also apply to it. -MachineFunctionPasses also have additional restrictions. In particular, -MachineFunctionPasses are not allowed to do any of the following:

- -
    -
  1. Modify or create any LLVM IR Instructions, BasicBlocks, Arguments, - Functions, GlobalVariables, GlobalAliases, or Modules.
  2. -
  3. Modify a MachineFunction other than the one currently being processed.
  4. -
  5. Maintain state across invocations of runOnMachineFunction (including global -data)
  6. -
- - -

- - The runOnMachineFunction(MachineFunction &MF) method - -

- -
- -
-virtual bool runOnMachineFunction(MachineFunction &MF) = 0;
-
- -

runOnMachineFunction can be considered the main entry point of a -MachineFunctionPass; that is, you should override this method to do the -work of your MachineFunctionPass.

- -

The runOnMachineFunction method is called on every -MachineFunction in a Module, so that the -MachineFunctionPass may perform optimizations on the machine-dependent -representation of the function. If you want to get at the LLVM Function -for the MachineFunction you're working on, use -MachineFunction's getFunction() accessor method -- but -remember, you may not modify the LLVM Function or its contents from a -MachineFunctionPass.

- -
- -
- -
- - -

- Pass registration -

- - -
- -

In the Hello World example pass we illustrated how -pass registration works, and discussed some of the reasons that it is used and -what it does. Here we discuss how and why passes are registered.

- -

As we saw above, passes are registered with the RegisterPass -template. The template parameter is the name of the pass that is to be used on -the command line to specify that the pass should be added to a program (for -example, with opt or bugpoint). The first argument is the -name of the pass, which is to be used for the -help output of -programs, as -well as for debug output generated by the --debug-pass option.

- -

If you want your pass to be easily dumpable, you should -implement the virtual print method:

- - -

- The print method -

- -
- -
-virtual void print(std::ostream &O, const Module *M) const;
-
- -

The print method must be implemented by "analyses" in order to print -a human readable version of the analysis results. This is useful for debugging -an analysis itself, as well as for other people to figure out how an analysis -works. Use the opt -analyze argument to invoke this method.

- -

The llvm::OStream parameter specifies the stream to write the results on, -and the Module parameter gives a pointer to the top level module of the -program that has been analyzed. Note however that this pointer may be null in -certain circumstances (such as calling the Pass::dump() from a -debugger), so it should only be used to enhance debug output, it should not be -depended on.

- -
- -
- - -

- Specifying interactions between passes -

- - -
- -

One of the main responsibilities of the PassManager is to make sure -that passes interact with each other correctly. Because PassManager -tries to optimize the execution of passes it must -know how the passes interact with each other and what dependencies exist between -the various passes. To track this, each pass can declare the set of passes that -are required to be executed before the current pass, and the passes which are -invalidated by the current pass.

- -

Typically this functionality is used to require that analysis results are -computed before your pass is run. Running arbitrary transformation passes can -invalidate the computed analysis results, which is what the invalidation set -specifies. If a pass does not implement the getAnalysisUsage method, it defaults to not -having any prerequisite passes, and invalidating all other passes.

- - -

- The getAnalysisUsage method -

- -
- -
-virtual void getAnalysisUsage(AnalysisUsage &Info) const;
-
- -

By implementing the getAnalysisUsage method, the required and -invalidated sets may be specified for your transformation. The implementation -should fill in the AnalysisUsage -object with information about which passes are required and not invalidated. To -do this, a pass may call any of the following methods on the AnalysisUsage -object:

-
- - -

- - The AnalysisUsage::addRequired<> - and AnalysisUsage::addRequiredTransitive<> methods - -

- -
-

-If your pass requires a previous pass to be executed (an analysis for example), -it can use one of these methods to arrange for it to be run before your pass. -LLVM has many different types of analyses and passes that can be required, -spanning the range from DominatorSet to BreakCriticalEdges. -Requiring BreakCriticalEdges, for example, guarantees that there will -be no critical edges in the CFG when your pass has been run. -

- -

-Some analyses chain to other analyses to do their job. For example, an AliasAnalysis implementation is required to chain to other alias analysis passes. In -cases where analyses chain, the addRequiredTransitive method should be -used instead of the addRequired method. This informs the PassManager -that the transitively required pass should be alive as long as the requiring -pass is. -

-
- - -

- - The AnalysisUsage::addPreserved<> method - -

- -
-

-One of the jobs of the PassManager is to optimize how and when analyses are run. -In particular, it attempts to avoid recomputing data unless it needs to. For -this reason, passes are allowed to declare that they preserve (i.e., they don't -invalidate) an existing analysis if it's available. For example, a simple -constant folding pass would not modify the CFG, so it can't possibly affect the -results of dominator analysis. By default, all passes are assumed to invalidate -all others. -

- -

-The AnalysisUsage class provides several methods which are useful in -certain circumstances that are related to addPreserved. In particular, -the setPreservesAll method can be called to indicate that the pass does -not modify the LLVM program at all (which is true for analyses), and the -setPreservesCFG method can be used by transformations that change -instructions in the program but do not modify the CFG or terminator instructions -(note that this property is implicitly set for BasicBlockPass's). -

- -

-addPreserved is particularly useful for transformations like -BreakCriticalEdges. This pass knows how to update a small set of loop -and dominator related analyses if they exist, so it can preserve them, despite -the fact that it hacks on the CFG. -

-
- - -

- - Example implementations of getAnalysisUsage - -

- -
- -
-// This example modifies the program, but does not modify the CFG
-void LICM::getAnalysisUsage(AnalysisUsage &AU) const {
-  AU.setPreservesCFG();
-  AU.addRequired<LoopInfo>();
-}
-
- -
- - -

- - The getAnalysis<> and - getAnalysisIfAvailable<> methods - -

- -
- -

The Pass::getAnalysis<> method is automatically inherited by -your class, providing you with access to the passes that you declared that you -required with the getAnalysisUsage -method. It takes a single template argument that specifies which pass class you -want, and returns a reference to that pass. For example:

- -
-bool LICM::runOnFunction(Function &F) {
-  LoopInfo &LI = getAnalysis<LoopInfo>();
-  ...
-}
-
- -

This method call returns a reference to the pass desired. You may get a -runtime assertion failure if you attempt to get an analysis that you did not -declare as required in your getAnalysisUsage implementation. This -method can be called by your run* method implementation, or by any -other local method invoked by your run* method. - -A module level pass can use function level analysis info using this interface. -For example:

- -
-bool ModuleLevelPass::runOnModule(Module &M) {
-  ...
-  DominatorTree &DT = getAnalysis<DominatorTree>(Func);
-  ...
-}
-
- -

In above example, runOnFunction for DominatorTree is called by pass manager -before returning a reference to the desired pass.

- -

-If your pass is capable of updating analyses if they exist (e.g., -BreakCriticalEdges, as described above), you can use the -getAnalysisIfAvailable method, which returns a pointer to the analysis -if it is active. For example:

- -
-...
-if (DominatorSet *DS = getAnalysisIfAvailable<DominatorSet>()) {
-  // A DominatorSet is active.  This code will update it.
-}
-...
-
- -
- -
- - -

- Implementing Analysis Groups -

- - -
- -

Now that we understand the basics of how passes are defined, how they are -used, and how they are required from other passes, it's time to get a little bit -fancier. All of the pass relationships that we have seen so far are very -simple: one pass depends on one other specific pass to be run before it can run. -For many applications, this is great, for others, more flexibility is -required.

- -

In particular, some analyses are defined such that there is a single simple -interface to the analysis results, but multiple ways of calculating them. -Consider alias analysis for example. The most trivial alias analysis returns -"may alias" for any alias query. The most sophisticated analysis a -flow-sensitive, context-sensitive interprocedural analysis that can take a -significant amount of time to execute (and obviously, there is a lot of room -between these two extremes for other implementations). To cleanly support -situations like this, the LLVM Pass Infrastructure supports the notion of -Analysis Groups.

- - -

- Analysis Group Concepts -

- -
- -

An Analysis Group is a single simple interface that may be implemented by -multiple different passes. Analysis Groups can be given human readable names -just like passes, but unlike passes, they need not derive from the Pass -class. An analysis group may have one or more implementations, one of which is -the "default" implementation.

- -

Analysis groups are used by client passes just like other passes are: the -AnalysisUsage::addRequired() and Pass::getAnalysis() methods. -In order to resolve this requirement, the PassManager -scans the available passes to see if any implementations of the analysis group -are available. If none is available, the default implementation is created for -the pass to use. All standard rules for interaction -between passes still apply.

- -

Although Pass Registration is optional for normal -passes, all analysis group implementations must be registered, and must use the -INITIALIZE_AG_PASS template to join the -implementation pool. Also, a default implementation of the interface -must be registered with RegisterAnalysisGroup.

- -

As a concrete example of an Analysis Group in action, consider the AliasAnalysis -analysis group. The default implementation of the alias analysis interface (the -basicaa -pass) just does a few simple checks that don't require significant analysis to -compute (such as: two different globals can never alias each other, etc). -Passes that use the AliasAnalysis -interface (for example the gcse pass), do -not care which implementation of alias analysis is actually provided, they just -use the designated interface.

- -

From the user's perspective, commands work just like normal. Issuing the -command 'opt -gcse ...' will cause the basicaa class to be -instantiated and added to the pass sequence. Issuing the command 'opt --somefancyaa -gcse ...' will cause the gcse pass to use the -somefancyaa alias analysis (which doesn't actually exist, it's just a -hypothetical example) instead.

- -
- - -

- Using RegisterAnalysisGroup -

- -
- -

The RegisterAnalysisGroup template is used to register the analysis -group itself, while the INITIALIZE_AG_PASS is used to add pass -implementations to the analysis group. First, -an analysis group should be registered, with a human readable name -provided for it. -Unlike registration of passes, there is no command line argument to be specified -for the Analysis Group Interface itself, because it is "abstract":

- -
-static RegisterAnalysisGroup<AliasAnalysis> A("Alias Analysis");
-
- -

Once the analysis is registered, passes can declare that they are valid -implementations of the interface by using the following code:

- -
-namespace {
-  // Declare that we implement the AliasAnalysis interface
-  INITIALIZE_AG_PASS(FancyAA, AliasAnalysis, "somefancyaa",
-                     "A more complex alias analysis implementation",
-                     false,  // Is CFG Only?
-                     true,   // Is Analysis?
-                     false); // Is default Analysis Group implementation?
-}
-
- -

This just shows a class FancyAA that -uses the INITIALIZE_AG_PASS macro both to register and -to "join" the AliasAnalysis -analysis group. Every implementation of an analysis group should join using -this macro.

- -
-namespace {
-  // Declare that we implement the AliasAnalysis interface
-  INITIALIZE_AG_PASS(BasicAA, AliasAnalysis, "basicaa",
-                     "Basic Alias Analysis (default AA impl)",
-                     false, // Is CFG Only?
-                     true,  // Is Analysis?
-                     true); // Is default Analysis Group implementation?
-}
-
- -

Here we show how the default implementation is specified (using the final -argument to the INITIALIZE_AG_PASS template). There must be exactly -one default implementation available at all times for an Analysis Group to be -used. Only default implementation can derive from ImmutablePass. -Here we declare that the - BasicAliasAnalysis -pass is the default implementation for the interface.

- -
- -
- - -

- Pass Statistics -

- - -
-

The Statistic -class is designed to be an easy way to expose various success -metrics from passes. These statistics are printed at the end of a -run, when the -stats command line option is enabled on the command -line. See the Statistics section in the Programmer's Manual for details. - -

- - - -

- What PassManager does -

- - -
- -

The PassManager -class -takes a list of passes, ensures their prerequisites -are set up correctly, and then schedules passes to run efficiently. All of the -LLVM tools that run passes use the PassManager for execution of these -passes.

- -

The PassManager does two main things to try to reduce the execution -time of a series of passes:

- -
    -
  1. Share analysis results - The PassManager attempts to avoid -recomputing analysis results as much as possible. This means keeping track of -which analyses are available already, which analyses get invalidated, and which -analyses are needed to be run for a pass. An important part of work is that the -PassManager tracks the exact lifetime of all analysis results, allowing -it to free memory allocated to holding analysis -results as soon as they are no longer needed.
  2. - -
  3. Pipeline the execution of passes on the program - The -PassManager attempts to get better cache and memory usage behavior out -of a series of passes by pipelining the passes together. This means that, given -a series of consecutive FunctionPass's, it -will execute all of the FunctionPass's on -the first function, then all of the FunctionPasses on the second function, -etc... until the entire program has been run through the passes. - -

    This improves the cache behavior of the compiler, because it is only touching -the LLVM program representation for a single function at a time, instead of -traversing the entire program. It reduces the memory consumption of compiler, -because, for example, only one DominatorSet -needs to be calculated at a time. This also makes it possible to implement -some interesting enhancements in the future.

  4. - -
- -

The effectiveness of the PassManager is influenced directly by how -much information it has about the behaviors of the passes it is scheduling. For -example, the "preserved" set is intentionally conservative in the face of an -unimplemented getAnalysisUsage method. -Not implementing when it should be implemented will have the effect of not -allowing any analysis results to live across the execution of your pass.

- -

The PassManager class exposes a --debug-pass command line -options that is useful for debugging pass execution, seeing how things work, and -diagnosing when you should be preserving more analyses than you currently are -(To get information about all of the variants of the --debug-pass -option, just type 'opt -help-hidden').

- -

By using the --debug-pass=Structure option, for example, we can see -how our Hello World pass interacts with other passes. -Lets try it out with the gcse and licm passes:

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
-Module Pass Manager
-  Function Pass Manager
-    Dominator Set Construction
-    Immediate Dominators Construction
-    Global Common Subexpression Elimination
---  Immediate Dominators Construction
---  Global Common Subexpression Elimination
-    Natural Loop Construction
-    Loop Invariant Code Motion
---  Natural Loop Construction
---  Loop Invariant Code Motion
-    Module Verifier
---  Dominator Set Construction
---  Module Verifier
-  Bitcode Writer
---Bitcode Writer
-
- -

This output shows us when passes are constructed and when the analysis -results are known to be dead (prefixed with '--'). Here we see that -GCSE uses dominator and immediate dominator information to do its job. The LICM -pass uses natural loop information, which uses dominator sets, but not immediate -dominators. Because immediate dominators are no longer useful after the GCSE -pass, it is immediately destroyed. The dominator sets are then reused to -compute natural loop information, which is then used by the LICM pass.

- -

After the LICM pass, the module verifier runs (which is automatically added -by the 'opt' tool), which uses the dominator set to check that the -resultant LLVM code is well formed. After it finishes, the dominator set -information is destroyed, after being computed once, and shared by three -passes.

- -

Lets see how this changes when we run the Hello -World pass in between the two passes:

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
-Module Pass Manager
-  Function Pass Manager
-    Dominator Set Construction
-    Immediate Dominators Construction
-    Global Common Subexpression Elimination
---  Dominator Set Construction
---  Immediate Dominators Construction
---  Global Common Subexpression Elimination
-    Hello World Pass
---  Hello World Pass
-    Dominator Set Construction
-    Natural Loop Construction
-    Loop Invariant Code Motion
---  Natural Loop Construction
---  Loop Invariant Code Motion
-    Module Verifier
---  Dominator Set Construction
---  Module Verifier
-  Bitcode Writer
---Bitcode Writer
-Hello: __main
-Hello: puts
-Hello: main
-
- -

Here we see that the Hello World pass has killed the -Dominator Set pass, even though it doesn't modify the code at all! To fix this, -we need to add the following getAnalysisUsage method to our pass:

- -
-// We don't modify the program, so we preserve all analyses
-virtual void getAnalysisUsage(AnalysisUsage &AU) const {
-  AU.setPreservesAll();
-}
-
- -

Now when we run our pass, we get this output:

- -
-$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
-Pass Arguments:  -gcse -hello -licm
-Module Pass Manager
-  Function Pass Manager
-    Dominator Set Construction
-    Immediate Dominators Construction
-    Global Common Subexpression Elimination
---  Immediate Dominators Construction
---  Global Common Subexpression Elimination
-    Hello World Pass
---  Hello World Pass
-    Natural Loop Construction
-    Loop Invariant Code Motion
---  Loop Invariant Code Motion
---  Natural Loop Construction
-    Module Verifier
---  Dominator Set Construction
---  Module Verifier
-  Bitcode Writer
---Bitcode Writer
-Hello: __main
-Hello: puts
-Hello: main
-
- -

Which shows that we don't accidentally invalidate dominator information -anymore, and therefore do not have to compute it twice.

- - -

- The releaseMemory method -

- -
- -
-  virtual void releaseMemory();
-
- -

The PassManager automatically determines when to compute analysis -results, and how long to keep them around for. Because the lifetime of the pass -object itself is effectively the entire duration of the compilation process, we -need some way to free analysis results when they are no longer useful. The -releaseMemory virtual method is the way to do this.

- -

If you are writing an analysis or any other pass that retains a significant -amount of state (for use by another pass which "requires" your pass and uses the -getAnalysis method) you should implement -releaseMemory to, well, release the memory allocated to maintain this -internal state. This method is called after the run* method for the -class, before the next call of run* in your pass.

- -
- -
- - -

- Registering dynamically loaded passes -

- - -
- -

Size matters when constructing production quality tools using llvm, -both for the purposes of distribution, and for regulating the resident code size -when running on the target system. Therefore, it becomes desirable to -selectively use some passes, while omitting others and maintain the flexibility -to change configurations later on. You want to be able to do all this, and, -provide feedback to the user. This is where pass registration comes into -play.

- -

The fundamental mechanisms for pass registration are the -MachinePassRegistry class and subclasses of -MachinePassRegistryNode.

- -

An instance of MachinePassRegistry is used to maintain a list of -MachinePassRegistryNode objects. This instance maintains the list and -communicates additions and deletions to the command line interface.

- -

An instance of MachinePassRegistryNode subclass is used to maintain -information provided about a particular pass. This information includes the -command line name, the command help string and the address of the function used -to create an instance of the pass. A global static constructor of one of these -instances registers with a corresponding MachinePassRegistry, -the static destructor unregisters. Thus a pass that is statically linked -in the tool will be registered at start up. A dynamically loaded pass will -register on load and unregister at unload.

- - -

- Using existing registries -

- -
- -

There are predefined registries to track instruction scheduling -(RegisterScheduler) and register allocation (RegisterRegAlloc) -machine passes. Here we will describe how to register a register -allocator machine pass.

- -

Implement your register allocator machine pass. In your register allocator -.cpp file add the following include;

- -
-#include "llvm/CodeGen/RegAllocRegistry.h"
-
- -

Also in your register allocator .cpp file, define a creator function in the -form;

- -
-FunctionPass *createMyRegisterAllocator() {
-  return new MyRegisterAllocator();
-}
-
- -

Note that the signature of this function should match the type of -RegisterRegAlloc::FunctionPassCtor. In the same file add the -"installing" declaration, in the form;

- -
-static RegisterRegAlloc myRegAlloc("myregalloc",
-                                   "my register allocator help string",
-                                   createMyRegisterAllocator);
-
- -

Note the two spaces prior to the help string produces a tidy result on the --help query.

- -
-$ llc -help
-  ...
-  -regalloc                    - Register allocator to use (default=linearscan)
-    =linearscan                -   linear scan register allocator
-    =local                     -   local register allocator
-    =simple                    -   simple register allocator
-    =myregalloc                -   my register allocator help string
-  ...
-
- -

And that's it. The user is now free to use -regalloc=myregalloc as -an option. Registering instruction schedulers is similar except use the -RegisterScheduler class. Note that the -RegisterScheduler::FunctionPassCtor is significantly different from -RegisterRegAlloc::FunctionPassCtor.

- -

To force the load/linking of your register allocator into the llc/lli tools, -add your creator function's global declaration to "Passes.h" and add a "pseudo" -call line to llvm/Codegen/LinkAllCodegenComponents.h.

- -
- - - -

- Creating new registries -

- -
- -

The easiest way to get started is to clone one of the existing registries; we -recommend llvm/CodeGen/RegAllocRegistry.h. The key things to modify -are the class name and the FunctionPassCtor type.

- -

Then you need to declare the registry. Example: if your pass registry is -RegisterMyPasses then define;

- -
-MachinePassRegistry RegisterMyPasses::Registry;
-
- -

And finally, declare the command line option for your passes. Example:

- -
-cl::opt<RegisterMyPasses::FunctionPassCtor, false,
-        RegisterPassParser<RegisterMyPasses> >
-MyPassOpt("mypass",
-          cl::init(&createDefaultMyPass),
-          cl::desc("my pass option help")); 
-
- -

Here the command option is "mypass", with createDefaultMyPass as the default -creator.

- -
- -
- - -

- Using GDB with dynamically loaded passes -

- - -
- -

Unfortunately, using GDB with dynamically loaded passes is not as easy as it -should be. First of all, you can't set a breakpoint in a shared object that has -not been loaded yet, and second of all there are problems with inlined functions -in shared objects. Here are some suggestions to debugging your pass with -GDB.

- -

For sake of discussion, I'm going to assume that you are debugging a -transformation invoked by opt, although nothing described here depends -on that.

- - -

- Setting a breakpoint in your pass -

- -
- -

First thing you do is start gdb on the opt process:

- -
-$ gdb opt
-GNU gdb 5.0
-Copyright 2000 Free Software Foundation, Inc.
-GDB is free software, covered by the GNU General Public License, and you are
-welcome to change it and/or distribute copies of it under certain conditions.
-Type "show copying" to see the conditions.
-There is absolutely no warranty for GDB.  Type "show warranty" for details.
-This GDB was configured as "sparc-sun-solaris2.6"...
-(gdb)
-
- -

Note that opt has a lot of debugging information in it, so it takes -time to load. Be patient. Since we cannot set a breakpoint in our pass yet -(the shared object isn't loaded until runtime), we must execute the process, and -have it stop before it invokes our pass, but after it has loaded the shared -object. The most foolproof way of doing this is to set a breakpoint in -PassManager::run and then run the process with the arguments you -want:

- -
-(gdb) break llvm::PassManager::run
-Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
-(gdb) run test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]
-Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]
-Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
-70      bool PassManager::run(Module &M) { return PM->run(M); }
-(gdb)
-
- -

Once the opt stops in the PassManager::run method you are -now free to set breakpoints in your pass so that you can trace through execution -or do other standard debugging stuff.

- -
- - -

- Miscellaneous Problems -

- -
- -

Once you have the basics down, there are a couple of problems that GDB has, -some with solutions, some without.

- -
    -
  • Inline functions have bogus stack information. In general, GDB does a -pretty good job getting stack traces and stepping through inline functions. -When a pass is dynamically loaded however, it somehow completely loses this -capability. The only solution I know of is to de-inline a function (move it -from the body of a class to a .cpp file).
  • - -
  • Restarting the program breaks breakpoints. After following the information -above, you have succeeded in getting some breakpoints planted in your pass. Nex -thing you know, you restart the program (i.e., you type 'run' again), -and you start getting errors about breakpoints being unsettable. The only way I -have found to "fix" this problem is to delete the breakpoints that are -already set in your pass, run the program, and re-set the breakpoints once -execution stops in PassManager::run.
  • - -
- -

Hopefully these tips will help with common case debugging situations. If -you'd like to contribute some tips of your own, just contact Chris.

- -
- -
- - -

- Future extensions planned -

- - -
- -

Although the LLVM Pass Infrastructure is very capable as it stands, and does -some nifty stuff, there are things we'd like to add in the future. Here is -where we are going:

- - -

- Multithreaded LLVM -

- -
- -

Multiple CPU machines are becoming more common and compilation can never be -fast enough: obviously we should allow for a multithreaded compiler. Because of -the semantics defined for passes above (specifically they cannot maintain state -across invocations of their run* methods), a nice clean way to -implement a multithreaded compiler would be for the PassManager class -to create multiple instances of each pass object, and allow the separate -instances to be hacking on different parts of the program at the same time.

- -

This implementation would prevent each of the passes from having to implement -multithreaded constructs, requiring only the LLVM core to have locking in a few -places (for global resources). Although this is a simple extension, we simply -haven't had time (or multiprocessor machines, thus a reason) to implement this. -Despite that, we have kept the LLVM passes SMP ready, and you should too.

- -
- -
- - -
-
- Valid CSS - Valid HTML 4.01 - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2012-04-08 04:52:52 -0700 (Sun, 08 Apr 2012) $ -
- - - diff --git a/cpp/llvm/docs/doxygen.cfg.in b/cpp/llvm/docs/doxygen.cfg.in deleted file mode 100644 index 20de0773..00000000 --- a/cpp/llvm/docs/doxygen.cfg.in +++ /dev/null @@ -1,1632 +0,0 @@ -# Doxyfile 1.7.1 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all -# text before the first occurrence of this tag. Doxygen uses libiconv (or the -# iconv built into libc) for the transcoding. See -# http://www.gnu.org/software/libiconv for the list of possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = LLVM - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = @PACKAGE_VERSION@ - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = @abs_top_builddir@/docs/doxygen - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, -# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English -# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, -# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, -# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = NO - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = ../.. - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = NO - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified -# scopes will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for -# Fortran. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for -# VHDL. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen to replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the -# methods anyway, you should set this option to NO. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. - -TYPEDEF_HIDES_STRUCT = NO - -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penality. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will rougly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols - -SYMBOL_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default -# anonymous namespace are hidden. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen -# will list include files with double quotes in the documentation -# rather than with sharp brackets. - -FORCE_LOCAL_INCLUDES = NO - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen -# will sort the (brief and detailed) documentation of class members so that -# constructors and destructors are listed first. If set to NO (the default) -# the constructors will appear in the respective orders defined by -# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. -# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO -# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. - -SORT_MEMBERS_CTORS_1ST = NO - -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) -# the group names will appear in their defined order. - -SORT_GROUP_NAMES = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = YES - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the -# Folder Tree View (if specified). The default is YES. - -SHOW_FILES = YES - -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. -# This will remove the Namespaces entry from the Quick Index -# and from the Folder Tree View (if specified). The default is YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. -# You can optionally specify a file name after the option, if omitted -# DoxygenLayout.xml will be used as the name of the layout file. - -LAYOUT_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = NO - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = NO - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = @abs_top_srcdir@/include \ - @abs_top_srcdir@/lib \ - @abs_top_srcdir@/docs/doxygen.intro - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for -# the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = @abs_top_srcdir@/examples - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = YES - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = @abs_top_srcdir@/docs/img - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. -# If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. -# Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. -# The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = NO - -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. -# Otherwise they will link to the documentation. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 4 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = llvm:: - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = @abs_top_srcdir@/docs/doxygen.header - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = @abs_top_srcdir@/docs/doxygen.footer - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = @abs_top_srcdir@/docs/doxygen.css - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. -# Doxygen will adjust the colors in the stylesheet and background images -# according to this color. Hue is specified as an angle on a colorwheel, -# see http://en.wikipedia.org/wiki/Hue for more information. -# For instance the value 0 represents red, 60 is yellow, 120 is green, -# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. -# The allowed range is 0 to 359. - -HTML_COLORSTYLE_HUE = 220 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of -# the colors in the HTML output. For a value of 0 the output will use -# grayscales only. A value of 255 will produce the most vivid colors. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to -# the luminance component of the colors in the HTML output. Values below -# 100 gradually make the output lighter, whereas values above 100 make -# the output darker. The value divided by 100 is the actual gamma applied, -# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, -# and 100 does not change the gamma. - -HTML_COLORSTYLE_GAMMA = 80 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting -# this to NO can help when comparing the output of multiple runs. - -HTML_TIMESTAMP = YES - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = NO - -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find -# it at startup. -# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. - -GENERATE_DOCSET = NO - -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) -# can be grouped. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen -# will append .docset to the name. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING -# is used to encode HtmlHelp index (hhk), content (hhc) and project file -# content. - -CHM_INDEX_ENCODING = - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated -# that can be used as input for Qt's qhelpgenerator to generate a -# Qt Compressed Help (.qch) of the generated HTML documentation. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can -# be used to specify the file name of the resulting .qch file. -# The path specified is relative to the HTML output folder. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#namespace - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#virtual-folders - -QHP_VIRTUAL_FOLDER = doc - -# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to -# add. For more information please see -# http://doc.trolltech.com/qthelpproject.html#custom-filters - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see -# -# Qt Help Project / Custom Filters. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's -# filter section matches. -# -# Qt Help Project / Filter Attributes. - -QHP_SECT_FILTER_ATTRS = - -# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can -# be used to specify the location of Qt's qhelpgenerator. -# If non-empty doxygen will try to run qhelpgenerator on the generated -# .qhp file. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files -# will be generated, which together with the HTML files, form an Eclipse help -# plugin. To install this plugin and make it available under the help contents -# menu in Eclipse, the contents of the directory containing the HTML and XML -# files needs to be copied into the plugins directory of eclipse. The name of -# the directory within the plugins directory should be the same as -# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before -# the help appears. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have -# this name. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. -# If the tag value is set to YES, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). -# Windows users are probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, -# and Class Hierarchy pages using a tree view instead of an ordered list. - -USE_INLINE_TREES = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open -# links to external symbols imported via tag files in a separate window. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory -# to force them to be regenerated. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are -# not supported properly for IE 6.0, but are supported on all modern browsers. -# Note that when changing this option you need to delete any form_*.png files -# in the HTML output before the changes have effect. - -FORMULA_TRANSPARENT = YES - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box -# for the HTML output. The underlying search engine uses javascript -# and DHTML and should work on any modern browser. Note that when using -# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets -# (GENERATE_DOCSET) there is already a search function so this one should -# typically be disabled. For large projects the javascript based search engine -# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. - -SEARCHENGINE = NO - -# When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a PHP enabled web server instead of at the web client -# using Javascript. Doxygen will generate the search PHP script and index -# file to put on the web server. The advantage of the server -# based approach is that it scales better to large projects and allows -# full text search. The disadvances is that it is more difficult to setup -# and does not have live searching capabilities. - -SERVER_BASED_SEARCH = NO - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. -# Note that when enabling USE_PDFLATEX this option is only used for -# generating bitmaps for formulas in the HTML output, but not in the -# Makefile that is written to the output directory. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = letter - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -# If LATEX_SOURCE_CODE is set to YES then doxygen will include -# source code with syntax highlighting in the LaTeX output. -# Note that which sources are shown also depends on other settings -# such as SOURCE_BROWSER. - -LATEX_SOURCE_CODE = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. -# This is useful -# if you want to understand what is going on. -# On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = ../include - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = YES - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see -# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = NO - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is -# allowed to run in parallel. When set to 0 (the default) doxygen will -# base this on the number of processors available in the system. You can set it -# explicitly to a value larger than 0 to get control over the balance -# between CPU load and processing speed. - -DOT_NUM_THREADS = 0 - -# By default doxygen will write a font called FreeSans.ttf to the output -# directory and reference it in all dot files that doxygen generates. This -# font does not include all possible unicode characters however, so when you need -# these (or just want a differently looking font) you can specify the font name -# using DOT_FONTNAME. You need need to make sure dot is able to find the font, -# which can be done by putting it in a standard location or by setting the -# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory -# containing the font. - -DOT_FONTNAME = FreeSans - -# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. -# The default size is 10pt. - -DOT_FONTSIZE = 10 - -# By default doxygen will tell dot to use the output directory to look for the -# FreeSans.ttf font (which doxygen will put there itself). If you specify a -# different font using DOT_FONTNAME you can set the path where dot -# can find it using this tag. - -DOT_FONTPATH = - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT options are set to YES then -# doxygen will generate a call dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable call graphs -# for selected functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then -# doxygen will generate a caller dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable caller -# graphs for selected functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = @DOT@ - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the -# number of direct children of the root node in a graph is already larger than -# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not -# seem to support this out of the box. Warning: Depending on the platform used, -# enabling this option may lead to badly anti-aliased labels on the edges of -# a graph (i.e. they become hard to read). - -DOT_TRANSPARENT = YES - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES diff --git a/cpp/llvm/docs/doxygen.css b/cpp/llvm/docs/doxygen.css deleted file mode 100644 index 80c6cad5..00000000 --- a/cpp/llvm/docs/doxygen.css +++ /dev/null @@ -1,408 +0,0 @@ -BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { - font-family: Verdana,Geneva,Arial,Helvetica,sans-serif; -} -BODY,TD { - font-size: 90%; -} -H1 { - text-align: center; - font-size: 140%; - font-weight: bold; -} -H2 { - font-size: 120%; - font-style: italic; -} -H3 { - font-size: 100%; -} -CAPTION { font-weight: bold } -DIV.qindex { - width: 100%; - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - padding: 2px; - line-height: 140%; -} -DIV.nav { - width: 100%; - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - padding: 2px; - line-height: 140%; -} -DIV.navtab { - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} -TD.navtab { - font-size: 70%; -} -A.qindex { - text-decoration: none; - font-weight: bold; - color: #1A419D; -} -A.qindex:visited { - text-decoration: none; - font-weight: bold; - color: #1A419D -} -A.qindex:hover { - text-decoration: none; - background-color: #ddddff; -} -A.qindexHL { - text-decoration: none; - font-weight: bold; - background-color: #6666cc; - color: #ffffff; - border: 1px double #9295C2; -} -A.qindexHL:hover { - text-decoration: none; - background-color: #6666cc; - color: #ffffff; -} -A.qindexHL:visited { - text-decoration: none; background-color: #6666cc; color: #ffffff } -A.el { text-decoration: none; font-weight: bold } -A.elRef { font-weight: bold } -A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} -A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} -A.codeRef:link { font-weight: normal; color: #0000FF} -A.codeRef:visited { font-weight: normal; color: #0000FF} -A:hover { text-decoration: none; background-color: #f2f2ff } -DL.el { margin-left: -1cm } -.fragment { - font-family: Fixed, monospace; - font-size: 95%; -} -PRE.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - margin-top: 4px; - margin-bottom: 4px; - margin-left: 2px; - margin-right: 8px; - padding-left: 6px; - padding-right: 6px; - padding-top: 4px; - padding-bottom: 4px; -} -DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } -TD.md { background-color: #F4F4FB; font-weight: bold; } -TD.mdPrefix { - background-color: #F4F4FB; - color: #606060; - font-size: 80%; -} -TD.mdname1 { background-color: #F4F4FB; font-weight: bold; color: #602020; } -TD.mdname { background-color: #F4F4FB; font-weight: bold; color: #602020; width: 600px; } -DIV.groupHeader { - margin-left: 16px; - margin-top: 12px; - margin-bottom: 6px; - font-weight: bold; -} -DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } -BODY { - background: white; - color: black; - margin-right: 20px; - margin-left: 20px; -} -TD.indexkey { - background-color: #eeeeff; - font-weight: bold; - padding-right : 10px; - padding-top : 2px; - padding-left : 10px; - padding-bottom : 2px; - margin-left : 0px; - margin-right : 0px; - margin-top : 2px; - margin-bottom : 2px; - border: 1px solid #CCCCCC; -} -TD.indexvalue { - background-color: #eeeeff; - font-style: italic; - padding-right : 10px; - padding-top : 2px; - padding-left : 10px; - padding-bottom : 2px; - margin-left : 0px; - margin-right : 0px; - margin-top : 2px; - margin-bottom : 2px; - border: 1px solid #CCCCCC; -} -TR.memlist { - background-color: #f0f0f0; -} -P.formulaDsp { text-align: center; } -IMG.formulaDsp { } -IMG.formulaInl { vertical-align: middle; } -SPAN.keyword { color: #008000 } -SPAN.keywordtype { color: #604020 } -SPAN.keywordflow { color: #e08000 } -SPAN.comment { color: #800000 } -SPAN.preprocessor { color: #806020 } -SPAN.stringliteral { color: #002080 } -SPAN.charliteral { color: #008080 } -.mdTable { - border: 1px solid #868686; - background-color: #F4F4FB; -} -.mdRow { - padding: 8px 10px; -} -.mdescLeft { - padding: 0px 8px 4px 8px; - font-size: 80%; - font-style: italic; - background-color: #FAFAFA; - border-top: 1px none #E0E0E0; - border-right: 1px none #E0E0E0; - border-bottom: 1px none #E0E0E0; - border-left: 1px none #E0E0E0; - margin: 0px; -} -.mdescRight { - padding: 0px 8px 4px 8px; - font-size: 80%; - font-style: italic; - background-color: #FAFAFA; - border-top: 1px none #E0E0E0; - border-right: 1px none #E0E0E0; - border-bottom: 1px none #E0E0E0; - border-left: 1px none #E0E0E0; - margin: 0px; -} -.memItemLeft { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memItemRight { - padding: 1px 8px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplItemLeft { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: none; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplItemRight { - padding: 1px 8px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: none; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplParams { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - color: #606060; - background-color: #FAFAFA; - font-size: 80%; -} -.search { color: #003399; - font-weight: bold; -} -FORM.search { - margin-bottom: 0px; - margin-top: 0px; -} -INPUT.search { font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #eeeeff; -} -TD.tiny { font-size: 75%; -} -a { - color: #252E78; -} -a:visited { - color: #3D2185; -} -.dirtab { padding: 4px; - border-collapse: collapse; - border: 1px solid #b0b0b0; -} -TH.dirtab { background: #eeeeff; - font-weight: bold; -} -HR { height: 1px; - border: none; - border-top: 1px solid black; -} - -/* - * LLVM Modifications. - * Note: Everything above here is generated with "doxygen -w htlm" command. See - * "doxygen --help" for details. What follows are CSS overrides for LLVM - * specific formatting. We want to keep the above so it can be replaced with - * subsequent doxygen upgrades. - */ - -.footer { - font-size: 80%; - font-weight: bold; - text-align: center; - vertical-align: middle; -} -.title { - font-size: 25pt; - color: black; background: url("../img/lines.gif"); - font-weight: bold; - border-width: 1px; - border-style: solid none solid none; - text-align: center; - vertical-align: middle; - padding-left: 8pt; - padding-top: 1px; - padding-bottom: 2px -} -A:link { - cursor: pointer; - text-decoration: none; - font-weight: bolder; -} -A:visited { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; -} -A:hover { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; -} -A:active { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; - font-style: italic; -} -H1 { - text-align: center; - font-size: 140%; - font-weight: bold; -} -H2 { - font-size: 120%; - font-style: italic; -} -H3 { - font-size: 100%; -} - -H2, H3 { - border-bottom: 2px solid; - margin-top: 2em; -} - -A.qindex {} -A.qindexRef {} -A.el { text-decoration: none; font-weight: bold } -A.elRef { font-weight: bold } -A.code { text-decoration: none; font-weight: normal; color: #4444ee } -A.codeRef { font-weight: normal; color: #4444ee } - -div.memitem { - border: 1px solid #999999; - margin-top: 1.0em; - margin-bottom: 1.0em; - -webkit-border-radius: 0.5em; - -webkit-box-shadow: 3px 3px 6px #777777; - -moz-border-radius: 0.5em; - -moz-box-shadow: black 3px 3px 3px; -} - -div.memproto { - background-color: #E3E4E5; - padding: 0.25em 0.5em; - -webkit-border-top-left-radius: 0.5em; - -webkit-border-top-right-radius: 0.5em; - -moz-border-radius-topleft: 0.5em; - -moz-border-radius-topright: 0.5em; -} - -div.memdoc { - padding-left: 1em; - padding-right: 1em; -} diff --git a/cpp/llvm/docs/doxygen.footer b/cpp/llvm/docs/doxygen.footer deleted file mode 100644 index c492e7df..00000000 --- a/cpp/llvm/docs/doxygen.footer +++ /dev/null @@ -1,13 +0,0 @@ -
- - -
- - - - diff --git a/cpp/llvm/docs/doxygen.header b/cpp/llvm/docs/doxygen.header deleted file mode 100644 index 56fb77fa..00000000 --- a/cpp/llvm/docs/doxygen.header +++ /dev/null @@ -1,9 +0,0 @@ - - - - - -LLVM: $title - - -

LLVM API Documentation

diff --git a/cpp/llvm/docs/doxygen.intro b/cpp/llvm/docs/doxygen.intro deleted file mode 100644 index 699dadc2..00000000 --- a/cpp/llvm/docs/doxygen.intro +++ /dev/null @@ -1,18 +0,0 @@ -/// @mainpage LLVM -/// -/// @section main_intro Introduction -/// Welcome to LLVM. -/// -/// This documentation describes the @b internal software that makes -/// up LLVM, not the @b external use of LLVM. There are no instructions -/// here on how to use LLVM, only the APIs that make up the software. For usage -/// instructions, please see the programmer's guide or reference manual. -/// -/// @section main_caveat Caveat -/// This documentation is generated directly from the source code with doxygen. -/// Since LLVM is constantly under active development, what you're about to -/// read is out of date! However, it may still be useful since certain portions -/// of LLVM are very stable. -/// -/// @section main_changelog Change Log -/// - Original content written 12/30/2003 by Reid Spencer diff --git a/cpp/llvm/docs/img/Debugging.gif b/cpp/llvm/docs/img/Debugging.gif deleted file mode 100644 index 662d35a6735d811a4145592e9514c7cf06e66935..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20390 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 VCW1z2P8!DRv4Vn1s0)Pv06T`D|5^Y5 diff --git a/cpp/llvm/docs/img/libdeps.gif b/cpp/llvm/docs/img/libdeps.gif deleted file mode 100644 index c5c0ed4c403f7c33c261fb7808c65833c63a9e18..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 52679 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 Y5-xP3E8Xc*x4PE7E_Smk+7JK$I|6Cq9{>OV diff --git a/cpp/llvm/docs/img/lines.gif b/cpp/llvm/docs/img/lines.gif deleted file mode 100644 index 88f491edc302684624036548ce3910f32cd4514f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 91 zcmZ?wbhEHb6kw2JSj4~}!yWbi|Nq;!Zv#mNB%lLggVZoEYe?+6^Uvpm=jsLv^V7@! jMO<%uq861ZHD`s_rm4RV&HHn4>)eNv)_rVZVXy`Ob}}Q< diff --git a/cpp/llvm/docs/img/objdeps.gif b/cpp/llvm/docs/img/objdeps.gif deleted file mode 100644 index 57c3e2e60d4edc6fec37f766f077c6ed3aae4c20..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 16201 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 - - - - Documentation for the LLVM System at SVN head - - - - -

Documentation for the LLVM System at SVN head

- -

If you are using a released version of LLVM, -see the download page to find -your documentation.

- -
- - -
-

- -
- -

-
-
- -
-

Written by The LLVM Team

-
- - -

LLVM Design & Overview

- - - - - -

LLVM User Guides

- - - - - - -

LLVM Programming Documentation

- - - - - -

LLVM Subsystem Documentation

- - - - - -

LLVM Development Process Documentation

- - -
    - -
  • LLVM Project Guide - How-to guide and -templates for new projects that use the LLVM infrastructure. The -templates (directory organization, Makefiles, and test tree) allow the project -code to be located outside (or inside) the llvm/ tree, while using LLVM -header files and libraries.
  • - -
  • LLVMBuild Documentation - Describes the -LLVMBuild organization and files used by LLVM to specify component -descriptions.
  • - -
  • LLVM Makefile Guide - Describes how the -LLVM makefiles work and how to use them.
  • - -
  • How To Release LLVM To The Public - This -is a guide to preparing LLVM releases. Most developers can ignore it.
  • - -
- - -

LLVM Mailing Lists

- - -
    -
  • The -LLVM Announcements List: This is a low volume list that provides important -announcements regarding LLVM. It gets email about once a month.
  • - -
  • The Developer's -List: This list is for people who want to be included in technical -discussions of LLVM. People post to this list when they have questions about -writing code for or using the LLVM tools. It is relatively low volume.
  • - -
  • The Bugs & -Patches Archive: This list gets emailed every time a bug is opened and -closed, and when people submit patches to be included in LLVM. It is higher -volume than the LLVMdev list.
  • - -
  • The Commits -Archive: This list contains all commit messages that are made when LLVM -developers commit code changes to the repository. It is useful for those who -want to stay on the bleeding edge of LLVM development. This list is very high -volume.
  • - -
  • The -Test Results Archive: A message is automatically sent to this list by every -active nightly tester when it completes. As such, this list gets email several -times each day, making it a high volume list.
  • - -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - LLVM Compiler Infrastructure
- Last modified: $Date: 2012-02-26 14:26:37 -0800 (Sun, 26 Feb 2012) $ -
- diff --git a/cpp/llvm/docs/llvm.css b/cpp/llvm/docs/llvm.css deleted file mode 100644 index e3e6351a..00000000 --- a/cpp/llvm/docs/llvm.css +++ /dev/null @@ -1,112 +0,0 @@ -/* - * LLVM documentation style sheet - */ - -/* Common styles */ -.body { color: black; background: white; margin: 0 0 0 0 } - -/* No borders on image links */ -a:link img, a:visited img { border-style: none } - -address img { float: right; width: 88px; height: 31px; } -address { clear: right; } - -table { text-align: center; border: 2px solid black; - border-collapse: collapse; margin-top: 1em; margin-left: 1em; - margin-right: 1em; margin-bottom: 1em; } -tr, td { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; } -th { border: 2px solid gray; font-weight: bold; font-size: 105%; - background: url("img/lines.gif"); - font-family: "Georgia,Palatino,Times,Roman,SanSerif"; - text-align: center; vertical-align: middle; } -/* - * Documentation - */ -/* Common for title and header */ -.doc_title, .doc_section, .doc_subsection, h1, h2, h3 { - color: black; background: url("img/lines.gif"); - font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold; - border-width: 1px; - border-style: solid none solid none; - text-align: center; - vertical-align: middle; - padding-left: 8pt; - padding-top: 1px; - padding-bottom: 2px -} - -h1, .doc_title, .title { text-align: left; font-size: 25pt } - -h2, .doc_section { text-align: center; font-size: 22pt; - margin: 20pt 0pt 5pt 0pt; } - -h3, .doc_subsection { width: 75%; - text-align: left; font-size: 12pt; - padding: 4pt 4pt 4pt 4pt; - margin: 1.5em 0.5em 0.5em 0.5em } - -h4, .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em; - font-weight: bold; font-style: oblique; - border-bottom: 1px solid #999999; font-size: 12pt; - width: 75%; } - -.doc_author { text-align: left; font-weight: bold; padding-left: 20pt } -.doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt } - -.doc_footer { text-align: left; padding: 0 0 0 0 } - -.doc_hilite { color: blue; font-weight: bold; } - -.doc_table { text-align: center; width: 90%; - padding: 1px 1px 1px 1px; border: 1px; } - -.doc_warning { color: red; font-weight: bold } - -/*
would use this class, and
adds more padding */ -.doc_code, .literal-block - { border: solid 1px gray; background: #eeeeee; - margin: 0 1em 0 1em; - padding: 0 1em 0 1em; - display: table; - } - -blockquote pre { - padding: 1em 2em 1em 1em; - border: solid 1px gray; - background: #eeeeee; - margin: 0 1em 0 1em; - display: table; -} - -h2+div, h2+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} -h3+div, h3+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} -h4+div, h4+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} - -/* It is preferrable to use
 everywhere instead of the
- * 
...
construct. - * - * Once all docs use
 for code regions, this style can  be merged with the
- * one above, and we can drop the [pre] qualifier.
- */
-pre.doc_code, .literal-block { padding: 1em 2em 1em 1em }
-
-.doc_notes      { background: #fafafa; border: 1px solid #cecece;
-                  display: table; padding: 0 1em 0 .1em }
-
-table.layout    { text-align: left; border: none; border-collapse: collapse;
-                  padding: 4px 4px 4px 4px; }
-tr.layout, td.layout, td.left, td.right
-                { border: none; padding: 4pt 4pt 2pt 2pt; vertical-align: top; }
-td.left         { text-align: left }
-td.right        { text-align: right }
-th.layout       { border: none; font-weight: bold; font-size: 105%;
-                  text-align: center; vertical-align: middle; }
-
-/* Left align table cell */
-.td_left        { border: 2px solid gray; text-align: left; }
-
-/* ReST-specific */
-.title { margin-top: 0 }
-.topic-title{ display: none }
-div.contents ul { list-style-type: decimal }
-.toc-backref    { color: black; text-decoration: none; }
diff --git a/cpp/llvm/docs/re_format.7 b/cpp/llvm/docs/re_format.7
deleted file mode 100644
index 0c092871..00000000
--- a/cpp/llvm/docs/re_format.7
+++ /dev/null
@@ -1,756 +0,0 @@
-.\"	$OpenBSD: re_format.7,v 1.14 2007/05/31 19:19:30 jmc Exp $
-.\"
-.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
-.\"
-.\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
-.\" Copyright (c) 1992, 1993, 1994
-.\"	The Regents of the University of California.  All rights reserved.
-.\"
-.\" This code is derived from software contributed to Berkeley by
-.\" Henry Spencer.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of the University nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\"	@(#)re_format.7	8.3 (Berkeley) 3/20/94
-.\"
-.Dd $Mdocdate: May 31 2007 $
-.Dt RE_FORMAT 7
-.Os
-.Sh NAME
-.Nm re_format
-.Nd POSIX regular expressions
-.Sh DESCRIPTION
-Regular expressions (REs),
-as defined in
-.St -p1003.1-2004 ,
-come in two forms:
-basic regular expressions
-(BREs)
-and extended regular expressions
-(EREs).
-Both forms of regular expressions are supported
-by the interfaces described in
-.Xr regex 3 .
-Applications dealing with regular expressions
-may use one or the other form
-(or indeed both).
-For example,
-.Xr ed 1
-uses BREs,
-whilst
-.Xr egrep 1
-talks EREs.
-Consult the manual page for the specific application to find out which
-it uses.
-.Pp
-POSIX leaves some aspects of RE syntax and semantics open;
-.Sq **
-marks decisions on these aspects that
-may not be fully portable to other POSIX implementations.
-.Pp
-This manual page first describes regular expressions in general,
-specifically extended regular expressions,
-and then discusses differences between them and basic regular expressions.
-.Sh EXTENDED REGULAR EXPRESSIONS
-An ERE is one** or more non-empty**
-.Em branches ,
-separated by
-.Sq \*(Ba .
-It matches anything that matches one of the branches.
-.Pp
-A branch is one** or more
-.Em pieces ,
-concatenated.
-It matches a match for the first, followed by a match for the second, etc.
-.Pp
-A piece is an
-.Em atom
-possibly followed by a single**
-.Sq * ,
-.Sq + ,
-.Sq ?\& ,
-or
-.Em bound .
-An atom followed by
-.Sq *
-matches a sequence of 0 or more matches of the atom.
-An atom followed by
-.Sq +
-matches a sequence of 1 or more matches of the atom.
-An atom followed by
-.Sq ?\&
-matches a sequence of 0 or 1 matches of the atom.
-.Pp
-A bound is
-.Sq {
-followed by an unsigned decimal integer,
-possibly followed by
-.Sq ,\&
-possibly followed by another unsigned decimal integer,
-always followed by
-.Sq } .
-The integers must lie between 0 and
-.Dv RE_DUP_MAX
-(255**) inclusive,
-and if there are two of them, the first may not exceed the second.
-An atom followed by a bound containing one integer
-.Ar i
-and no comma matches
-a sequence of exactly
-.Ar i
-matches of the atom.
-An atom followed by a bound
-containing one integer
-.Ar i
-and a comma matches
-a sequence of
-.Ar i
-or more matches of the atom.
-An atom followed by a bound
-containing two integers
-.Ar i
-and
-.Ar j
-matches a sequence of
-.Ar i
-through
-.Ar j
-(inclusive) matches of the atom.
-.Pp
-An atom is a regular expression enclosed in
-.Sq ()
-(matching a part of the regular expression),
-an empty set of
-.Sq ()
-(matching the null string)**,
-a
-.Em bracket expression
-(see below),
-.Sq .\&
-(matching any single character),
-.Sq ^
-(matching the null string at the beginning of a line),
-.Sq $
-(matching the null string at the end of a line),
-a
-.Sq \e
-followed by one of the characters
-.Sq ^.[$()|*+?{\e
-(matching that character taken as an ordinary character),
-a
-.Sq \e
-followed by any other character**
-(matching that character taken as an ordinary character,
-as if the
-.Sq \e
-had not been present**),
-or a single character with no other significance (matching that character).
-A
-.Sq {
-followed by a character other than a digit is an ordinary character,
-not the beginning of a bound**.
-It is illegal to end an RE with
-.Sq \e .
-.Pp
-A bracket expression is a list of characters enclosed in
-.Sq [] .
-It normally matches any single character from the list (but see below).
-If the list begins with
-.Sq ^ ,
-it matches any single character
-.Em not
-from the rest of the list
-(but see below).
-If two characters in the list are separated by
-.Sq - ,
-this is shorthand for the full
-.Em range
-of characters between those two (inclusive) in the
-collating sequence, e.g.\&
-.Sq [0-9]
-in ASCII matches any decimal digit.
-It is illegal** for two ranges to share an endpoint, e.g.\&
-.Sq a-c-e .
-Ranges are very collating-sequence-dependent,
-and portable programs should avoid relying on them.
-.Pp
-To include a literal
-.Sq ]\&
-in the list, make it the first character
-(following a possible
-.Sq ^ ) .
-To include a literal
-.Sq - ,
-make it the first or last character,
-or the second endpoint of a range.
-To use a literal
-.Sq -
-as the first endpoint of a range,
-enclose it in
-.Sq [.
-and
-.Sq .]
-to make it a collating element (see below).
-With the exception of these and some combinations using
-.Sq [
-(see next paragraphs),
-all other special characters, including
-.Sq \e ,
-lose their special significance within a bracket expression.
-.Pp
-Within a bracket expression, a collating element
-(a character,
-a multi-character sequence that collates as if it were a single character,
-or a collating-sequence name for either)
-enclosed in
-.Sq [.
-and
-.Sq .]
-stands for the sequence of characters of that collating element.
-The sequence is a single element of the bracket expression's list.
-A bracket expression containing a multi-character collating element
-can thus match more than one character,
-e.g. if the collating sequence includes a
-.Sq ch
-collating element,
-then the RE
-.Sq [[.ch.]]*c
-matches the first five characters of
-.Sq chchcc .
-.Pp
-Within a bracket expression, a collating element enclosed in
-.Sq [=
-and
-.Sq =]
-is an equivalence class, standing for the sequences of characters
-of all collating elements equivalent to that one, including itself.
-(If there are no other equivalent collating elements,
-the treatment is as if the enclosing delimiters were
-.Sq [.
-and
-.Sq .] . )
-For example, if
-.Sq x
-and
-.Sq y
-are the members of an equivalence class,
-then
-.Sq [[=x=]] ,
-.Sq [[=y=]] ,
-and
-.Sq [xy]
-are all synonymous.
-An equivalence class may not** be an endpoint of a range.
-.Pp
-Within a bracket expression, the name of a
-.Em character class
-enclosed
-in
-.Sq [:
-and
-.Sq :]
-stands for the list of all characters belonging to that class.
-Standard character class names are:
-.Bd -literal -offset indent
-alnum	digit	punct
-alpha	graph	space
-blank	lower	upper
-cntrl	print	xdigit
-.Ed
-.Pp
-These stand for the character classes defined in
-.Xr ctype 3 .
-A locale may provide others.
-A character class may not be used as an endpoint of a range.
-.Pp
-There are two special cases** of bracket expressions:
-the bracket expressions
-.Sq [[:<:]]
-and
-.Sq [[:>:]]
-match the null string at the beginning and end of a word, respectively.
-A word is defined as a sequence of
-characters starting and ending with a word character
-which is neither preceded nor followed by
-word characters.
-A word character is an
-.Em alnum
-character (as defined by
-.Xr ctype 3 )
-or an underscore.
-This is an extension,
-compatible with but not specified by POSIX,
-and should be used with
-caution in software intended to be portable to other systems.
-.Pp
-In the event that an RE could match more than one substring of a given
-string,
-the RE matches the one starting earliest in the string.
-If the RE could match more than one substring starting at that point,
-it matches the longest.
-Subexpressions also match the longest possible substrings, subject to
-the constraint that the whole match be as long as possible,
-with subexpressions starting earlier in the RE taking priority over
-ones starting later.
-Note that higher-level subexpressions thus take priority over
-their lower-level component subexpressions.
-.Pp
-Match lengths are measured in characters, not collating elements.
-A null string is considered longer than no match at all.
-For example,
-.Sq bb*
-matches the three middle characters of
-.Sq abbbc ;
-.Sq (wee|week)(knights|nights)
-matches all ten characters of
-.Sq weeknights ;
-when
-.Sq (.*).*
-is matched against
-.Sq abc ,
-the parenthesized subexpression matches all three characters;
-and when
-.Sq (a*)*
-is matched against
-.Sq bc ,
-both the whole RE and the parenthesized subexpression match the null string.
-.Pp
-If case-independent matching is specified,
-the effect is much as if all case distinctions had vanished from the
-alphabet.
-When an alphabetic that exists in multiple cases appears as an
-ordinary character outside a bracket expression, it is effectively
-transformed into a bracket expression containing both cases,
-e.g.\&
-.Sq x
-becomes
-.Sq [xX] .
-When it appears inside a bracket expression,
-all case counterparts of it are added to the bracket expression,
-so that, for example,
-.Sq [x]
-becomes
-.Sq [xX]
-and
-.Sq [^x]
-becomes
-.Sq [^xX] .
-.Pp
-No particular limit is imposed on the length of REs**.
-Programs intended to be portable should not employ REs longer
-than 256 bytes,
-as an implementation can refuse to accept such REs and remain
-POSIX-compliant.
-.Pp
-The following is a list of extended regular expressions:
-.Bl -tag -width Ds
-.It Ar c
-Any character
-.Ar c
-not listed below matches itself.
-.It \e Ns Ar c
-Any backslash-escaped character
-.Ar c
-matches itself.
-.It \&.
-Matches any single character that is not a newline
-.Pq Sq \en .
-.It Bq Ar char-class
-Matches any single character in
-.Ar char-class .
-To include a
-.Ql \&]
-in
-.Ar char-class ,
-it must be the first character.
-A range of characters may be specified by separating the end characters
-of the range with a
-.Ql - ;
-e.g.\&
-.Ar a-z
-specifies the lower case characters.
-The following literal expressions can also be used in
-.Ar char-class
-to specify sets of characters:
-.Bd -unfilled -offset indent
-[:alnum:] [:cntrl:] [:lower:] [:space:]
-[:alpha:] [:digit:] [:print:] [:upper:]
-[:blank:] [:graph:] [:punct:] [:xdigit:]
-.Ed
-.Pp
-If
-.Ql -
-appears as the first or last character of
-.Ar char-class ,
-then it matches itself.
-All other characters in
-.Ar char-class
-match themselves.
-.Pp
-Patterns in
-.Ar char-class
-of the form
-.Eo [.
-.Ar col-elm
-.Ec .]\&
-or
-.Eo [=
-.Ar col-elm
-.Ec =]\& ,
-where
-.Ar col-elm
-is a collating element, are interpreted according to
-.Xr setlocale 3
-.Pq not currently supported .
-.It Bq ^ Ns Ar char-class
-Matches any single character, other than newline, not in
-.Ar char-class .
-.Ar char-class
-is defined as above.
-.It ^
-If
-.Sq ^
-is the first character of a regular expression, then it
-anchors the regular expression to the beginning of a line.
-Otherwise, it matches itself.
-.It $
-If
-.Sq $
-is the last character of a regular expression,
-it anchors the regular expression to the end of a line.
-Otherwise, it matches itself.
-.It [[:<:]]
-Anchors the single character regular expression or subexpression
-immediately following it to the beginning of a word.
-.It [[:>:]]
-Anchors the single character regular expression or subexpression
-immediately following it to the end of a word.
-.It Pq Ar re
-Defines a subexpression
-.Ar re .
-Any set of characters enclosed in parentheses
-matches whatever the set of characters without parentheses matches
-(that is a long-winded way of saying the constructs
-.Sq (re)
-and
-.Sq re
-match identically).
-.It *
-Matches the single character regular expression or subexpression
-immediately preceding it zero or more times.
-If
-.Sq *
-is the first character of a regular expression or subexpression,
-then it matches itself.
-The
-.Sq *
-operator sometimes yields unexpected results.
-For example, the regular expression
-.Ar b*
-matches the beginning of the string
-.Qq abbb
-(as opposed to the substring
-.Qq bbb ) ,
-since a null match is the only leftmost match.
-.It +
-Matches the singular character regular expression
-or subexpression immediately preceding it
-one or more times.
-.It ?
-Matches the singular character regular expression
-or subexpression immediately preceding it
-0 or 1 times.
-.Sm off
-.It Xo
-.Pf { Ar n , m No }\ \&
-.Pf { Ar n , No }\ \&
-.Pf { Ar n No }
-.Xc
-.Sm on
-Matches the single character regular expression or subexpression
-immediately preceding it at least
-.Ar n
-and at most
-.Ar m
-times.
-If
-.Ar m
-is omitted, then it matches at least
-.Ar n
-times.
-If the comma is also omitted, then it matches exactly
-.Ar n
-times.
-.It \*(Ba
-Used to separate patterns.
-For example,
-the pattern
-.Sq cat\*(Badog
-matches either
-.Sq cat
-or
-.Sq dog .
-.El
-.Sh BASIC REGULAR EXPRESSIONS
-Basic regular expressions differ in several respects:
-.Bl -bullet -offset 3n
-.It
-.Sq \*(Ba ,
-.Sq + ,
-and
-.Sq ?\&
-are ordinary characters and there is no equivalent
-for their functionality.
-.It
-The delimiters for bounds are
-.Sq \e{
-and
-.Sq \e} ,
-with
-.Sq {
-and
-.Sq }
-by themselves ordinary characters.
-.It
-The parentheses for nested subexpressions are
-.Sq \e(
-and
-.Sq \e) ,
-with
-.Sq (
-and
-.Sq )\&
-by themselves ordinary characters.
-.It
-.Sq ^
-is an ordinary character except at the beginning of the
-RE or** the beginning of a parenthesized subexpression.
-.It
-.Sq $
-is an ordinary character except at the end of the
-RE or** the end of a parenthesized subexpression.
-.It
-.Sq *
-is an ordinary character if it appears at the beginning of the
-RE or the beginning of a parenthesized subexpression
-(after a possible leading
-.Sq ^ ) .
-.It
-Finally, there is one new type of atom, a
-.Em back-reference :
-.Sq \e
-followed by a non-zero decimal digit
-.Ar d
-matches the same sequence of characters matched by the
-.Ar d Ns th
-parenthesized subexpression
-(numbering subexpressions by the positions of their opening parentheses,
-left to right),
-so that, for example,
-.Sq \e([bc]\e)\e1
-matches
-.Sq bb\&
-or
-.Sq cc
-but not
-.Sq bc .
-.El
-.Pp
-The following is a list of basic regular expressions:
-.Bl -tag -width Ds
-.It Ar c
-Any character
-.Ar c
-not listed below matches itself.
-.It \e Ns Ar c
-Any backslash-escaped character
-.Ar c ,
-except for
-.Sq { ,
-.Sq } ,
-.Sq \&( ,
-and
-.Sq \&) ,
-matches itself.
-.It \&.
-Matches any single character that is not a newline
-.Pq Sq \en .
-.It Bq Ar char-class
-Matches any single character in
-.Ar char-class .
-To include a
-.Ql \&]
-in
-.Ar char-class ,
-it must be the first character.
-A range of characters may be specified by separating the end characters
-of the range with a
-.Ql - ;
-e.g.\&
-.Ar a-z
-specifies the lower case characters.
-The following literal expressions can also be used in
-.Ar char-class
-to specify sets of characters:
-.Bd -unfilled -offset indent
-[:alnum:] [:cntrl:] [:lower:] [:space:]
-[:alpha:] [:digit:] [:print:] [:upper:]
-[:blank:] [:graph:] [:punct:] [:xdigit:]
-.Ed
-.Pp
-If
-.Ql -
-appears as the first or last character of
-.Ar char-class ,
-then it matches itself.
-All other characters in
-.Ar char-class
-match themselves.
-.Pp
-Patterns in
-.Ar char-class
-of the form
-.Eo [.
-.Ar col-elm
-.Ec .]\&
-or
-.Eo [=
-.Ar col-elm
-.Ec =]\& ,
-where
-.Ar col-elm
-is a collating element, are interpreted according to
-.Xr setlocale 3
-.Pq not currently supported .
-.It Bq ^ Ns Ar char-class
-Matches any single character, other than newline, not in
-.Ar char-class .
-.Ar char-class
-is defined as above.
-.It ^
-If
-.Sq ^
-is the first character of a regular expression, then it
-anchors the regular expression to the beginning of a line.
-Otherwise, it matches itself.
-.It $
-If
-.Sq $
-is the last character of a regular expression,
-it anchors the regular expression to the end of a line.
-Otherwise, it matches itself.
-.It [[:<:]]
-Anchors the single character regular expression or subexpression
-immediately following it to the beginning of a word.
-.It [[:>:]]
-Anchors the single character regular expression or subexpression
-immediately following it to the end of a word.
-.It \e( Ns Ar re Ns \e)
-Defines a subexpression
-.Ar re .
-Subexpressions may be nested.
-A subsequent backreference of the form
-.Pf \e Ns Ar n ,
-where
-.Ar n
-is a number in the range [1,9], expands to the text matched by the
-.Ar n Ns th
-subexpression.
-For example, the regular expression
-.Ar \e(.*\e)\e1
-matches any string consisting of identical adjacent substrings.
-Subexpressions are ordered relative to their left delimiter.
-.It *
-Matches the single character regular expression or subexpression
-immediately preceding it zero or more times.
-If
-.Sq *
-is the first character of a regular expression or subexpression,
-then it matches itself.
-The
-.Sq *
-operator sometimes yields unexpected results.
-For example, the regular expression
-.Ar b*
-matches the beginning of the string
-.Qq abbb
-(as opposed to the substring
-.Qq bbb ) ,
-since a null match is the only leftmost match.
-.Sm off
-.It Xo
-.Pf \e{ Ar n , m No \e}\ \&
-.Pf \e{ Ar n , No \e}\ \&
-.Pf \e{ Ar n No \e}
-.Xc
-.Sm on
-Matches the single character regular expression or subexpression
-immediately preceding it at least
-.Ar n
-and at most
-.Ar m
-times.
-If
-.Ar m
-is omitted, then it matches at least
-.Ar n
-times.
-If the comma is also omitted, then it matches exactly
-.Ar n
-times.
-.El
-.Sh SEE ALSO
-.Xr ctype 3 ,
-.Xr regex 3
-.Sh STANDARDS
-.St -p1003.1-2004 :
-Base Definitions, Chapter 9 (Regular Expressions).
-.Sh BUGS
-Having two kinds of REs is a botch.
-.Pp
-The current POSIX spec says that
-.Sq )\&
-is an ordinary character in the absence of an unmatched
-.Sq ( ;
-this was an unintentional result of a wording error,
-and change is likely.
-Avoid relying on it.
-.Pp
-Back-references are a dreadful botch,
-posing major problems for efficient implementations.
-They are also somewhat vaguely defined
-(does
-.Sq a\e(\e(b\e)*\e2\e)*d
-match
-.Sq abbbd ? ) .
-Avoid using them.
-.Pp
-POSIX's specification of case-independent matching is vague.
-The
-.Dq one case implies all cases
-definition given above
-is the current consensus among implementors as to the right interpretation.
-.Pp
-The syntax for word boundaries is incredibly ugly.
diff --git a/cpp/llvm/docs/tutorial/LangImpl1.html b/cpp/llvm/docs/tutorial/LangImpl1.html
deleted file mode 100644
index e617b86a..00000000
--- a/cpp/llvm/docs/tutorial/LangImpl1.html
+++ /dev/null
@@ -1,348 +0,0 @@
-
-
-
-
-  Kaleidoscope: Tutorial Introduction and the Lexer
-  
-  
-  
-
-
-
-
-

Kaleidoscope: Tutorial Introduction and the Lexer

- - - -
-

Written by Chris Lattner

-
- - -

Tutorial Introduction

- - -
- -

Welcome to the "Implementing a language with LLVM" tutorial. This tutorial -runs through the implementation of a simple language, showing how fun and -easy it can be. This tutorial will get you up and started as well as help to -build a framework you can extend to other languages. The code in this tutorial -can also be used as a playground to hack on other LLVM specific things. -

- -

-The goal of this tutorial is to progressively unveil our language, describing -how it is built up over time. This will let us cover a fairly broad range of -language design and LLVM-specific usage issues, showing and explaining the code -for it all along the way, without overwhelming you with tons of details up -front.

- -

It is useful to point out ahead of time that this tutorial is really about -teaching compiler techniques and LLVM specifically, not about teaching -modern and sane software engineering principles. In practice, this means that -we'll take a number of shortcuts to simplify the exposition. For example, the -code leaks memory, uses global variables all over the place, doesn't use nice -design patterns like visitors, etc... but it -is very simple. If you dig in and use the code as a basis for future projects, -fixing these deficiencies shouldn't be hard.

- -

I've tried to put this tutorial together in a way that makes chapters easy to -skip over if you are already familiar with or are uninterested in the various -pieces. The structure of the tutorial is: -

- -
    -
  • Chapter #1: Introduction to the Kaleidoscope -language, and the definition of its Lexer - This shows where we are going -and the basic functionality that we want it to do. In order to make this -tutorial maximally understandable and hackable, we choose to implement -everything in C++ instead of using lexer and parser generators. LLVM obviously -works just fine with such tools, feel free to use one if you prefer.
  • -
  • Chapter #2: Implementing a Parser and -AST - With the lexer in place, we can talk about parsing techniques and -basic AST construction. This tutorial describes recursive descent parsing and -operator precedence parsing. Nothing in Chapters 1 or 2 is LLVM-specific, -the code doesn't even link in LLVM at this point. :)
  • -
  • Chapter #3: Code generation to LLVM IR - -With the AST ready, we can show off how easy generation of LLVM IR really -is.
  • -
  • Chapter #4: Adding JIT and Optimizer -Support - Because a lot of people are interested in using LLVM as a JIT, -we'll dive right into it and show you the 3 lines it takes to add JIT support. -LLVM is also useful in many other ways, but this is one simple and "sexy" way -to shows off its power. :)
  • -
  • Chapter #5: Extending the Language: Control -Flow - With the language up and running, we show how to extend it with -control flow operations (if/then/else and a 'for' loop). This gives us a chance -to talk about simple SSA construction and control flow.
  • -
  • Chapter #6: Extending the Language: -User-defined Operators - This is a silly but fun chapter that talks about -extending the language to let the user program define their own arbitrary -unary and binary operators (with assignable precedence!). This lets us build a -significant piece of the "language" as library routines.
  • -
  • Chapter #7: Extending the Language: Mutable -Variables - This chapter talks about adding user-defined local variables -along with an assignment operator. The interesting part about this is how -easy and trivial it is to construct SSA form in LLVM: no, LLVM does not -require your front-end to construct SSA form!
  • -
  • Chapter #8: Conclusion and other useful LLVM -tidbits - This chapter wraps up the series by talking about potential -ways to extend the language, but also includes a bunch of pointers to info about -"special topics" like adding garbage collection support, exceptions, debugging, -support for "spaghetti stacks", and a bunch of other tips and tricks.
  • - -
- -

By the end of the tutorial, we'll have written a bit less than 700 lines of -non-comment, non-blank, lines of code. With this small amount of code, we'll -have built up a very reasonable compiler for a non-trivial language including -a hand-written lexer, parser, AST, as well as code generation support with a JIT -compiler. While other systems may have interesting "hello world" tutorials, -I think the breadth of this tutorial is a great testament to the strengths of -LLVM and why you should consider it if you're interested in language or compiler -design.

- -

A note about this tutorial: we expect you to extend the language and play -with it on your own. Take the code and go crazy hacking away at it, compilers -don't need to be scary creatures - it can be a lot of fun to play with -languages!

- -
- - -

The Basic Language

- - -
- -

This tutorial will be illustrated with a toy language that we'll call -"Kaleidoscope" (derived -from "meaning beautiful, form, and view"). -Kaleidoscope is a procedural language that allows you to define functions, use -conditionals, math, etc. Over the course of the tutorial, we'll extend -Kaleidoscope to support the if/then/else construct, a for loop, user defined -operators, JIT compilation with a simple command line interface, etc.

- -

Because we want to keep things simple, the only datatype in Kaleidoscope is a -64-bit floating point type (aka 'double' in C parlance). As such, all values -are implicitly double precision and the language doesn't require type -declarations. This gives the language a very nice and simple syntax. For -example, the following simple example computes Fibonacci numbers:

- -
-
-# Compute the x'th fibonacci number.
-def fib(x)
-  if x < 3 then
-    1
-  else
-    fib(x-1)+fib(x-2)
-
-# This expression will compute the 40th number.
-fib(40)
-
-
- -

We also allow Kaleidoscope to call into standard library functions (the LLVM -JIT makes this completely trivial). This means that you can use the 'extern' -keyword to define a function before you use it (this is also useful for mutually -recursive functions). For example:

- -
-
-extern sin(arg);
-extern cos(arg);
-extern atan2(arg1 arg2);
-
-atan2(sin(.4), cos(42))
-
-
- -

A more interesting example is included in Chapter 6 where we write a little -Kaleidoscope application that displays -a Mandelbrot Set at various levels of magnification.

- -

Lets dive into the implementation of this language!

- -
- - -

The Lexer

- - -
- -

When it comes to implementing a language, the first thing needed is -the ability to process a text file and recognize what it says. The traditional -way to do this is to use a "lexer" (aka 'scanner') -to break the input up into "tokens". Each token returned by the lexer includes -a token code and potentially some metadata (e.g. the numeric value of a number). -First, we define the possibilities: -

- -
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5,
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-
- -

Each token returned by our lexer will either be one of the Token enum values -or it will be an 'unknown' character like '+', which is returned as its ASCII -value. If the current token is an identifier, the IdentifierStr -global variable holds the name of the identifier. If the current token is a -numeric literal (like 1.0), NumVal holds its value. Note that we use -global variables for simplicity, this is not the best choice for a real language -implementation :). -

- -

The actual implementation of the lexer is a single function named -gettok. The gettok function is called to return the next token -from standard input. Its definition starts as:

- -
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-
- -

-gettok works by calling the C getchar() function to read -characters one at a time from standard input. It eats them as it recognizes -them and stores the last character read, but not processed, in LastChar. The -first thing that it has to do is ignore whitespace between tokens. This is -accomplished with the loop above.

- -

The next thing gettok needs to do is recognize identifiers and -specific keywords like "def". Kaleidoscope does this with this simple loop:

- -
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    return tok_identifier;
-  }
-
-
- -

Note that this code sets the 'IdentifierStr' global whenever it -lexes an identifier. Also, since language keywords are matched by the same -loop, we handle them here inline. Numeric values are similar:

- -
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-
- -

This is all pretty straight-forward code for processing input. When reading -a numeric value from input, we use the C strtod function to convert it -to a numeric value that we store in NumVal. Note that this isn't doing -sufficient error checking: it will incorrectly read "1.23.45.67" and handle it as -if you typed in "1.23". Feel free to extend it :). Next we handle comments: -

- -
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-
-
- -

We handle comments by skipping to the end of the line and then return the -next token. Finally, if the input doesn't match one of the above cases, it is -either an operator character like '+' or the end of the file. These are handled -with this code:

- -
-
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-  
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-
- -

With this, we have the complete lexer for the basic Kaleidoscope language -(the full code listing for the Lexer is -available in the next chapter of the tutorial). -Next we'll build a simple parser that uses this to -build an Abstract Syntax Tree. When we have that, we'll include a driver -so that you can use the lexer and parser together. -

- -Next: Implementing a Parser and AST -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl2.html b/cpp/llvm/docs/tutorial/LangImpl2.html deleted file mode 100644 index 142301ac..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl2.html +++ /dev/null @@ -1,1231 +0,0 @@ - - - - - Kaleidoscope: Implementing a Parser and AST - - - - - - - -

Kaleidoscope: Implementing a Parser and AST

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 2 Introduction

- - -
- -

Welcome to Chapter 2 of the "Implementing a language -with LLVM" tutorial. This chapter shows you how to use the lexer, built in -Chapter 1, to build a full parser for -our Kaleidoscope language. Once we have a parser, we'll define and build an Abstract Syntax -Tree (AST).

- -

The parser we will build uses a combination of Recursive Descent -Parsing and Operator-Precedence -Parsing to parse the Kaleidoscope language (the latter for -binary expressions and the former for everything else). Before we get to -parsing though, lets talk about the output of the parser: the Abstract Syntax -Tree.

- -
- - -

The Abstract Syntax Tree (AST)

- - -
- -

The AST for a program captures its behavior in such a way that it is easy for -later stages of the compiler (e.g. code generation) to interpret. We basically -want one object for each construct in the language, and the AST should closely -model the language. In Kaleidoscope, we have expressions, a prototype, and a -function object. We'll start with expressions first:

- -
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-};
-
-
- -

The code above shows the definition of the base ExprAST class and one -subclass which we use for numeric literals. The important thing to note about -this code is that the NumberExprAST class captures the numeric value of the -literal as an instance variable. This allows later phases of the compiler to -know what the stored numeric value is.

- -

Right now we only create the AST, so there are no useful accessor methods on -them. It would be very easy to add a virtual method to pretty print the code, -for example. Here are the other expression AST node definitions that we'll use -in the basic form of the Kaleidoscope language: -

- -
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-};
-
-
- -

This is all (intentionally) rather straight-forward: variables capture the -variable name, binary operators capture their opcode (e.g. '+'), and calls -capture a function name as well as a list of any argument expressions. One thing -that is nice about our AST is that it captures the language features without -talking about the syntax of the language. Note that there is no discussion about -precedence of binary operators, lexical structure, etc.

- -

For our basic language, these are all of the expression nodes we'll define. -Because it doesn't have conditional control flow, it isn't Turing-complete; -we'll fix that in a later installment. The two things we need next are a way -to talk about the interface to a function, and a way to talk about functions -themselves:

- -
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes).
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args)
-    : Name(name), Args(args) {}
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-};
-
-
- -

In Kaleidoscope, functions are typed with just a count of their arguments. -Since all values are double precision floating point, the type of each argument -doesn't need to be stored anywhere. In a more aggressive and realistic -language, the "ExprAST" class would probably have a type field.

- -

With this scaffolding, we can now talk about parsing expressions and function -bodies in Kaleidoscope.

- -
- - -

Parser Basics

- - -
- -

Now that we have an AST to build, we need to define the parser code to build -it. The idea here is that we want to parse something like "x+y" (which is -returned as three tokens by the lexer) into an AST that could be generated with -calls like this:

- -
-
-  ExprAST *X = new VariableExprAST("x");
-  ExprAST *Y = new VariableExprAST("y");
-  ExprAST *Result = new BinaryExprAST('+', X, Y);
-
-
- -

In order to do this, we'll start by defining some basic helper routines:

- -
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-
- -

-This implements a simple token buffer around the lexer. This allows -us to look one token ahead at what the lexer is returning. Every function in -our parser will assume that CurTok is the current token that needs to be -parsed.

- -
-
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-
- -

-The Error routines are simple helper routines that our parser will use -to handle errors. The error recovery in our parser will not be the best and -is not particular user-friendly, but it will be enough for our tutorial. These -routines make it easier to handle errors in routines that have various return -types: they always return null.

- -

With these basic helper functions, we can implement the first -piece of our grammar: numeric literals.

- -
- - -

Basic Expression Parsing

- - -
- -

We start with numeric literals, because they are the simplest to process. -For each production in our grammar, we'll define a function which parses that -production. For numeric literals, we have: -

- -
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-
- -

This routine is very simple: it expects to be called when the current token -is a tok_number token. It takes the current number value, creates -a NumberExprAST node, advances the lexer to the next token, and finally -returns.

- -

There are some interesting aspects to this. The most important one is that -this routine eats all of the tokens that correspond to the production and -returns the lexer buffer with the next token (which is not part of the grammar -production) ready to go. This is a fairly standard way to go for recursive -descent parsers. For a better example, the parenthesis operator is defined like -this:

- -
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-
- -

This function illustrates a number of interesting things about the -parser:

- -

-1) It shows how we use the Error routines. When called, this function expects -that the current token is a '(' token, but after parsing the subexpression, it -is possible that there is no ')' waiting. For example, if the user types in -"(4 x" instead of "(4)", the parser should emit an error. Because errors can -occur, the parser needs a way to indicate that they happened: in our parser, we -return null on an error.

- -

2) Another interesting aspect of this function is that it uses recursion by -calling ParseExpression (we will soon see that ParseExpression can call -ParseParenExpr). This is powerful because it allows us to handle -recursive grammars, and keeps each production very simple. Note that -parentheses do not cause construction of AST nodes themselves. While we could -do it this way, the most important role of parentheses are to guide the parser -and provide grouping. Once the parser constructs the AST, parentheses are not -needed.

- -

The next simple production is for handling variable references and function -calls:

- -
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-
- -

This routine follows the same style as the other routines. (It expects to be -called if the current token is a tok_identifier token). It also has -recursion and error handling. One interesting aspect of this is that it uses -look-ahead to determine if the current identifier is a stand alone -variable reference or if it is a function call expression. It handles this by -checking to see if the token after the identifier is a '(' token, constructing -either a VariableExprAST or CallExprAST node as appropriate. -

- -

Now that we have all of our simple expression-parsing logic in place, we can -define a helper function to wrap it together into one entry point. We call this -class of expressions "primary" expressions, for reasons that will become more -clear later in the tutorial. In order to -parse an arbitrary primary expression, we need to determine what sort of -expression it is:

- -
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  }
-}
-
-
- -

Now that you see the definition of this function, it is more obvious why we -can assume the state of CurTok in the various functions. This uses look-ahead -to determine which sort of expression is being inspected, and then parses it -with a function call.

- -

Now that basic expressions are handled, we need to handle binary expressions. -They are a bit more complex.

- -
- - -

Binary Expression Parsing

- - -
- -

Binary expressions are significantly harder to parse because they are often -ambiguous. For example, when given the string "x+y*z", the parser can choose -to parse it as either "(x+y)*z" or "x+(y*z)". With common definitions from -mathematics, we expect the later parse, because "*" (multiplication) has -higher precedence than "+" (addition).

- -

There are many ways to handle this, but an elegant and efficient way is to -use Operator-Precedence -Parsing. This parsing technique uses the precedence of binary operators to -guide recursion. To start with, we need a table of precedences:

- -
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-    
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-int main() {
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-  ...
-}
-
-
- -

For the basic form of Kaleidoscope, we will only support 4 binary operators -(this can obviously be extended by you, our brave and intrepid reader). The -GetTokPrecedence function returns the precedence for the current token, -or -1 if the token is not a binary operator. Having a map makes it easy to add -new operators and makes it clear that the algorithm doesn't depend on the -specific operators involved, but it would be easy enough to eliminate the map -and do the comparisons in the GetTokPrecedence function. (Or just use -a fixed-size array).

- -

With the helper above defined, we can now start parsing binary expressions. -The basic idea of operator precedence parsing is to break down an expression -with potentially ambiguous binary operators into pieces. Consider ,for example, -the expression "a+b+(c+d)*e*f+g". Operator precedence parsing considers this -as a stream of primary expressions separated by binary operators. As such, -it will first parse the leading primary expression "a", then it will see the -pairs [+, b] [+, (c+d)] [*, e] [*, f] and [+, g]. Note that because parentheses -are primary expressions, the binary expression parser doesn't need to worry -about nested subexpressions like (c+d) at all. -

- -

-To start, an expression is a primary expression potentially followed by a -sequence of [binop,primaryexpr] pairs:

- -
-
-/// expression
-///   ::= primary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParsePrimary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-
- -

ParseBinOpRHS is the function that parses the sequence of pairs for -us. It takes a precedence and a pointer to an expression for the part that has been -parsed so far. Note that "x" is a perfectly valid expression: As such, "binoprhs" is -allowed to be empty, in which case it returns the expression that is passed into -it. In our example above, the code passes the expression for "a" into -ParseBinOpRHS and the current token is "+".

- -

The precedence value passed into ParseBinOpRHS indicates the -minimal operator precedence that the function is allowed to eat. For -example, if the current pair stream is [+, x] and ParseBinOpRHS is -passed in a precedence of 40, it will not consume any tokens (because the -precedence of '+' is only 20). With this in mind, ParseBinOpRHS starts -with:

- -
-
-/// binoprhs
-///   ::= ('+' primary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-
-
- -

This code gets the precedence of the current token and checks to see if if is -too low. Because we defined invalid tokens to have a precedence of -1, this -check implicitly knows that the pair-stream ends when the token stream runs out -of binary operators. If this check succeeds, we know that the token is a binary -operator and that it will be included in this expression:

- -
-
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the primary expression after the binary operator.
-    ExprAST *RHS = ParsePrimary();
-    if (!RHS) return 0;
-
-
- -

As such, this code eats (and remembers) the binary operator and then parses -the primary expression that follows. This builds up the whole pair, the first of -which is [+, b] for the running example.

- -

Now that we parsed the left-hand side of an expression and one pair of the -RHS sequence, we have to decide which way the expression associates. In -particular, we could have "(a+b) binop unparsed" or "a + (b binop unparsed)". -To determine this, we look ahead at "binop" to determine its precedence and -compare it to BinOp's precedence (which is '+' in this case):

- -
-
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-
-
- -

If the precedence of the binop to the right of "RHS" is lower or equal to the -precedence of our current operator, then we know that the parentheses associate -as "(a+b) binop ...". In our example, the current operator is "+" and the next -operator is "+", we know that they have the same precedence. In this case we'll -create the AST node for "a+b", and then continue parsing:

- -
-
-      ... if body omitted ...
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }  // loop around to the top of the while loop.
-}
-
-
- -

In our example above, this will turn "a+b+" into "(a+b)" and execute the next -iteration of the loop, with "+" as the current token. The code above will eat, -remember, and parse "(c+d)" as the primary expression, which makes the -current pair equal to [+, (c+d)]. It will then evaluate the 'if' conditional above with -"*" as the binop to the right of the primary. In this case, the precedence of "*" is -higher than the precedence of "+" so the if condition will be entered.

- -

The critical question left here is "how can the if condition parse the right -hand side in full"? In particular, to build the AST correctly for our example, -it needs to get all of "(c+d)*e*f" as the RHS expression variable. The code to -do this is surprisingly simple (code from the above two blocks duplicated for -context):

- -
-
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }  // loop around to the top of the while loop.
-}
-
-
- -

At this point, we know that the binary operator to the RHS of our primary -has higher precedence than the binop we are currently parsing. As such, we know -that any sequence of pairs whose operators are all higher precedence than "+" -should be parsed together and returned as "RHS". To do this, we recursively -invoke the ParseBinOpRHS function specifying "TokPrec+1" as the minimum -precedence required for it to continue. In our example above, this will cause -it to return the AST node for "(c+d)*e*f" as RHS, which is then set as the RHS -of the '+' expression.

- -

Finally, on the next iteration of the while loop, the "+g" piece is parsed -and added to the AST. With this little bit of code (14 non-trivial lines), we -correctly handle fully general binary expression parsing in a very elegant way. -This was a whirlwind tour of this code, and it is somewhat subtle. I recommend -running through it with a few tough examples to see how it works. -

- -

This wraps up handling of expressions. At this point, we can point the -parser at an arbitrary token stream and build an expression from it, stopping -at the first token that is not part of the expression. Next up we need to -handle function definitions, etc.

- -
- - -

Parsing the Rest

- - -
- -

-The next thing missing is handling of function prototypes. In Kaleidoscope, -these are used both for 'extern' function declarations as well as function body -definitions. The code to do this is straight-forward and not very interesting -(once you've survived expressions): -

- -
-
-/// prototype
-///   ::= id '(' id* ')'
-static PrototypeAST *ParsePrototype() {
-  if (CurTok != tok_identifier)
-    return ErrorP("Expected function name in prototype");
-
-  std::string FnName = IdentifierStr;
-  getNextToken();
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  // Read the list of argument names.
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  return new PrototypeAST(FnName, ArgNames);
-}
-
-
- -

Given this, a function definition is very simple, just a prototype plus -an expression to implement the body:

- -
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-
- -

In addition, we support 'extern' to declare functions like 'sin' and 'cos' as -well as to support forward declaration of user functions. These 'extern's are just -prototypes with no body:

- -
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-
- -

Finally, we'll also let the user type in arbitrary top-level expressions and -evaluate them on the fly. We will handle this by defining anonymous nullary -(zero argument) functions for them:

- -
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-
- -

Now that we have all the pieces, let's build a little driver that will let us -actually execute this code we've built!

- -
- - -

The Driver

- - -
- -

The driver for this simply invokes all of the parsing pieces with a top-level -dispatch loop. There isn't much interesting here, so I'll just include the -top-level loop. See below for full code in the "Top-Level -Parsing" section.

- -
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-
- -

The most interesting part of this is that we ignore top-level semicolons. -Why is this, you ask? The basic reason is that if you type "4 + 5" at the -command line, the parser doesn't know whether that is the end of what you will type -or not. For example, on the next line you could type "def foo..." in which case -4+5 is the end of a top-level expression. Alternatively you could type "* 6", -which would continue the expression. Having top-level semicolons allows you to -type "4+5;", and the parser will know you are done.

- -
- - -

Conclusions

- - -
- -

With just under 400 lines of commented code (240 lines of non-comment, -non-blank code), we fully defined our minimal language, including a lexer, -parser, and AST builder. With this done, the executable will validate -Kaleidoscope code and tell us if it is grammatically invalid. For -example, here is a sample interaction:

- -
-
-$ ./a.out
-ready> def foo(x y) x+foo(y, 4.0);
-Parsed a function definition.
-ready> def foo(x y) x+y y;
-Parsed a function definition.
-Parsed a top-level expr
-ready> def foo(x y) x+y );
-Parsed a function definition.
-Error: unknown token when expecting an expression
-ready> extern sin(a);
-ready> Parsed an extern
-ready> ^D
-$ 
-
-
- -

There is a lot of room for extension here. You can define new AST nodes, -extend the language in many ways, etc. In the next -installment, we will describe how to generate LLVM Intermediate -Representation (IR) from the AST.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for this and the previous chapter. -Note that it is fully self-contained: you don't need LLVM or any external -libraries at all for this. (Besides the C and C++ standard libraries, of -course.) To build this, just compile with:

- -
-
-# Compile
-clang++ -g -O3 toy.cpp
-# Run
-./a.out 
-
-
- -

Here is the code:

- -
-
-#include <cstdio>
-#include <cstdlib>
-#include <string>
-#include <map>
-#include <vector>
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes).
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args)
-    : Name(name), Args(args) {}
-  
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  }
-}
-
-/// binoprhs
-///   ::= ('+' primary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the primary expression after the binary operator.
-    ExprAST *RHS = ParsePrimary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= primary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParsePrimary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-static PrototypeAST *ParsePrototype() {
-  if (CurTok != tok_identifier)
-    return ErrorP("Expected function name in prototype");
-
-  std::string FnName = IdentifierStr;
-  getNextToken();
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  return new PrototypeAST(FnName, ArgNames);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing
-//===----------------------------------------------------------------------===//
-
-static void HandleDefinition() {
-  if (ParseDefinition()) {
-    fprintf(stderr, "Parsed a function definition.\n");
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (ParseExtern()) {
-    fprintf(stderr, "Parsed an extern\n");
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (ParseTopLevelExpr()) {
-    fprintf(stderr, "Parsed a top-level expr\n");
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  return 0;
-}
-
-
-Next: Implementing Code Generation to LLVM IR -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl3.html b/cpp/llvm/docs/tutorial/LangImpl3.html deleted file mode 100644 index d453c612..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl3.html +++ /dev/null @@ -1,1268 +0,0 @@ - - - - - Kaleidoscope: Implementing code generation to LLVM IR - - - - - - - -

Kaleidoscope: Code generation to LLVM IR

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 3 Introduction

- - -
- -

Welcome to Chapter 3 of the "Implementing a language -with LLVM" tutorial. This chapter shows you how to transform the Abstract Syntax Tree, built in Chapter 2, into LLVM IR. -This will teach you a little bit about how LLVM does things, as well as -demonstrate how easy it is to use. It's much more work to build a lexer and -parser than it is to generate LLVM IR code. :) -

- -

Please note: the code in this chapter and later require LLVM 2.2 or -later. LLVM 2.1 and before will not work with it. Also note that you need -to use a version of this tutorial that matches your LLVM release: If you are -using an official LLVM release, use the version of the documentation included -with your release or on the llvm.org -releases page.

- -
- - -

Code Generation Setup

- - -
- -

-In order to generate LLVM IR, we want some simple setup to get started. First -we define virtual code generation (codegen) methods in each AST class:

- -
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-...
-
-
- -

The Codegen() method says to emit IR for that AST node along with all the things it -depends on, and they all return an LLVM Value object. -"Value" is the class used to represent a "Static Single -Assignment (SSA) register" or "SSA value" in LLVM. The most distinct aspect -of SSA values is that their value is computed as the related instruction -executes, and it does not get a new value until (and if) the instruction -re-executes. In other words, there is no way to "change" an SSA value. For -more information, please read up on Static Single -Assignment - the concepts are really quite natural once you grok them.

- -

Note that instead of adding virtual methods to the ExprAST class hierarchy, -it could also make sense to use a visitor pattern or some -other way to model this. Again, this tutorial won't dwell on good software -engineering practices: for our purposes, adding a virtual method is -simplest.

- -

The -second thing we want is an "Error" method like we used for the parser, which will -be used to report errors found during code generation (for example, use of an -undeclared parameter):

- -
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, Value*> NamedValues;
-
-
- -

The static variables will be used during code generation. TheModule -is the LLVM construct that contains all of the functions and global variables in -a chunk of code. In many ways, it is the top-level structure that the LLVM IR -uses to contain code.

- -

The Builder object is a helper object that makes it easy to generate -LLVM instructions. Instances of the IRBuilder -class template keep track of the current place to insert instructions and has -methods to create new instructions.

- -

The NamedValues map keeps track of which values are defined in the -current scope and what their LLVM representation is. (In other words, it is a -symbol table for the code). In this form of Kaleidoscope, the only things that -can be referenced are function parameters. As such, function parameters will -be in this map when generating code for their function body.

- -

-With these basics in place, we can start talking about how to generate code for -each expression. Note that this assumes that the Builder has been set -up to generate code into something. For now, we'll assume that this -has already been done, and we'll just use it to emit code. -

- -
- - -

Expression Code Generation

- - -
- -

Generating LLVM code for expression nodes is very straightforward: less -than 45 lines of commented code for all four of our expression nodes. First -we'll do numeric literals:

- -
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-
- -

In the LLVM IR, numeric constants are represented with the -ConstantFP class, which holds the numeric value in an APFloat -internally (APFloat has the capability of holding floating point -constants of Arbitrary Precision). This code basically just -creates and returns a ConstantFP. Note that in the LLVM IR -that constants are all uniqued together and shared. For this reason, the API -uses the "foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".

- -
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  return V ? V : ErrorV("Unknown variable name");
-}
-
-
- -

References to variables are also quite simple using LLVM. In the simple version -of Kaleidoscope, we assume that the variable has already been emitted somewhere -and its value is available. In practice, the only values that can be in the -NamedValues map are function arguments. This -code simply checks to see that the specified name is in the map (if not, an -unknown variable is being referenced) and returns the value for it. In future -chapters, we'll add support for loop induction -variables in the symbol table, and for local variables.

- -
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: return ErrorV("invalid binary operator");
-  }
-}
-
-
- -

Binary operators start to get more interesting. The basic idea here is that -we recursively emit code for the left-hand side of the expression, then the -right-hand side, then we compute the result of the binary expression. In this -code, we do a simple switch on the opcode to create the right LLVM instruction. -

- -

In the example above, the LLVM builder class is starting to show its value. -IRBuilder knows where to insert the newly created instruction, all you have to -do is specify what instruction to create (e.g. with CreateFAdd), which -operands to use (L and R here) and optionally provide a name -for the generated instruction.

- -

One nice thing about LLVM is that the name is just a hint. For instance, if -the code above emits multiple "addtmp" variables, LLVM will automatically -provide each one with an increasing, unique numeric suffix. Local value names -for instructions are purely optional, but it makes it much easier to read the -IR dumps.

- -

LLVM instructions are constrained by -strict rules: for example, the Left and Right operators of -an add instruction must have the same -type, and the result type of the add must match the operand types. Because -all values in Kaleidoscope are doubles, this makes for very simple code for add, -sub and mul.

- -

On the other hand, LLVM specifies that the fcmp instruction always returns an 'i1' value -(a one bit integer). The problem with this is that Kaleidoscope wants the value to be a 0.0 or 1.0 value. In order to get these semantics, we combine the fcmp instruction with -a uitofp instruction. This instruction -converts its input integer into a floating point value by treating the input -as an unsigned value. In contrast, if we used the sitofp instruction, the Kaleidoscope '<' -operator would return 0.0 and -1.0, depending on the input value.

- -
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-
- -

Code generation for function calls is quite straightforward with LLVM. The -code above initially does a function name lookup in the LLVM Module's symbol -table. Recall that the LLVM Module is the container that holds all of the -functions we are JIT'ing. By giving each function the same name as what the -user specifies, we can use the LLVM symbol table to resolve function names for -us.

- -

Once we have the function to call, we recursively codegen each argument that -is to be passed in, and create an LLVM call -instruction. Note that LLVM uses the native C calling conventions by -default, allowing these calls to also call into standard library functions like -"sin" and "cos", with no additional effort.

- -

This wraps up our handling of the four basic expressions that we have so far -in Kaleidoscope. Feel free to go in and add some more. For example, by -browsing the LLVM language reference you'll find -several other interesting instructions that are really easy to plug into our -basic framework.

- -
- - -

Function Code Generation

- - -
- -

Code generation for prototypes and functions must handle a number of -details, which make their code less beautiful than expression code -generation, but allows us to illustrate some important points. First, lets -talk about code generation for prototypes: they are used both for function -bodies and external function declarations. The code starts with:

- -
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-
-
- -

This code packs a lot of power into a few lines. Note first that this -function returns a "Function*" instead of a "Value*". Because a "prototype" -really talks about the external interface for a function (not the value computed -by an expression), it makes sense for it to return the LLVM Function it -corresponds to when codegen'd.

- -

The call to FunctionType::get creates -the FunctionType that should be used for a given Prototype. Since all -function arguments in Kaleidoscope are of type double, the first line creates -a vector of "N" LLVM double types. It then uses the Functiontype::get -method to create a function type that takes "N" doubles as arguments, returns -one double as a result, and that is not vararg (the false parameter indicates -this). Note that Types in LLVM are uniqued just like Constants are, so you -don't "new" a type, you "get" it.

- -

The final line above actually creates the function that the prototype will -correspond to. This indicates the type, linkage and name to use, as well as which -module to insert into. "external linkage" -means that the function may be defined outside the current module and/or that it -is callable by functions outside the module. The Name passed in is the name the -user specified: since "TheModule" is specified, this name is registered -in "TheModule"s symbol table, which is used by the function call code -above.

- -
-
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-
-
- -

The Module symbol table works just like the Function symbol table when it -comes to name conflicts: if a new function is created with a name that was previously -added to the symbol table, the new function will get implicitly renamed when added to the -Module. The code above exploits this fact to determine if there was a previous -definition of this function.

- -

In Kaleidoscope, I choose to allow redefinitions of functions in two cases: -first, we want to allow 'extern'ing a function more than once, as long as the -prototypes for the externs match (since all arguments have the same type, we -just have to check that the number of arguments match). Second, we want to -allow 'extern'ing a function and then defining a body for it. This is useful -when defining mutually recursive functions.

- -

In order to implement this, the code above first checks to see if there is -a collision on the name of the function. If so, it deletes the function we just -created (by calling eraseFromParent) and then calling -getFunction to get the existing function with the specified name. Note -that many APIs in LLVM have "erase" forms and "remove" forms. The "remove" form -unlinks the object from its parent (e.g. a Function from a Module) and returns -it. The "erase" form unlinks the object and then deletes it.

- -
-
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-
-
- -

In order to verify the logic above, we first check to see if the pre-existing -function is "empty". In this case, empty means that it has no basic blocks in -it, which means it has no body. If it has no body, it is a forward -declaration. Since we don't allow anything after a full definition of the -function, the code rejects this case. If the previous reference to a function -was an 'extern', we simply verify that the number of arguments for that -definition and this one match up. If not, we emit an error.

- -
-
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx) {
-    AI->setName(Args[Idx]);
-    
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = AI;
-  }
-  return F;
-}
-
-
- -

The last bit of code for prototypes loops over all of the arguments in the -function, setting the name of the LLVM Argument objects to match, and registering -the arguments in the NamedValues map for future use by the -VariableExprAST AST node. Once this is set up, it returns the Function -object to the caller. Note that we don't check for conflicting -argument names here (e.g. "extern foo(a b a)"). Doing so would be very -straight-forward with the mechanics we have already used above.

- -
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-
-
- -

Code generation for function definitions starts out simply enough: we just -codegen the prototype (Proto) and verify that it is ok. We then clear out the -NamedValues map to make sure that there isn't anything in it from the -last function we compiled. Code generation of the prototype ensures that there -is an LLVM Function object that is ready to go for us.

- -
-
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-
-
- -

Now we get to the point where the Builder is set up. The first -line creates a new basic -block (named "entry"), which is inserted into TheFunction. The -second line then tells the builder that new instructions should be inserted into -the end of the new basic block. Basic blocks in LLVM are an important part -of functions that define the Control Flow Graph. -Since we don't have any control flow, our functions will only contain one -block at this point. We'll fix this in Chapter 5 :).

- -
-
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    return TheFunction;
-  }
-
-
- -

Once the insertion point is set up, we call the CodeGen() method for -the root expression of the function. If no error happens, this emits code to -compute the expression into the entry block and returns the value that was -computed. Assuming no error, we then create an LLVM ret instruction, which completes the function. -Once the function is built, we call verifyFunction, which -is provided by LLVM. This function does a variety of consistency checks on the -generated code, to determine if our compiler is doing everything right. Using -this is important: it can catch a lot of bugs. Once the function is finished -and validated, we return it.

- -
-
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-  return 0;
-}
-
-
- -

The only piece left here is handling of the error case. For simplicity, we -handle this by merely deleting the function we produced with the -eraseFromParent method. This allows the user to redefine a function -that they incorrectly typed in before: if we didn't delete it, it would live in -the symbol table, with a body, preventing future redefinition.

- -

This code does have a bug, though. Since the PrototypeAST::Codegen -can return a previously defined forward declaration, our code can actually delete -a forward declaration. There are a number of ways to fix this bug, see what you -can come up with! Here is a testcase:

- -
-
-extern foo(a b);     # ok, defines foo.
-def foo(a b) c;      # error, 'c' is invalid.
-def bar() foo(1, 2); # error, unknown function "foo"
-
-
- -
- - -

Driver Changes and Closing Thoughts

- - -
- -

-For now, code generation to LLVM doesn't really get us much, except that we can -look at the pretty IR calls. The sample code inserts calls to Codegen into the -"HandleDefinition", "HandleExtern" etc functions, and then -dumps out the LLVM IR. This gives a nice way to look at the LLVM IR for simple -functions. For example: -

- -
-
-ready> 4+5;
-Read top-level expression:
-define double @0() {
-entry:
-  ret double 9.000000e+00
-}
-
-
- -

Note how the parser turns the top-level expression into anonymous functions -for us. This will be handy when we add JIT -support in the next chapter. Also note that the code is very literally -transcribed, no optimizations are being performed except simple constant -folding done by IRBuilder. We will -add optimizations explicitly in -the next chapter.

- -
-
-ready> def foo(a b) a*a + 2*a*b + b*b;
-Read function definition:
-define double @foo(double %a, double %b) {
-entry:
-  %multmp = fmul double %a, %a
-  %multmp1 = fmul double 2.000000e+00, %a
-  %multmp2 = fmul double %multmp1, %b
-  %addtmp = fadd double %multmp, %multmp2
-  %multmp3 = fmul double %b, %b
-  %addtmp4 = fadd double %addtmp, %multmp3
-  ret double %addtmp4
-}
-
-
- -

This shows some simple arithmetic. Notice the striking similarity to the -LLVM builder calls that we use to create the instructions.

- -
-
-ready> def bar(a) foo(a, 4.0) + bar(31337);
-Read function definition:
-define double @bar(double %a) {
-entry:
-  %calltmp = call double @foo(double %a, double 4.000000e+00)
-  %calltmp1 = call double @bar(double 3.133700e+04)
-  %addtmp = fadd double %calltmp, %calltmp1
-  ret double %addtmp
-}
-
-
- -

This shows some function calls. Note that this function will take a long -time to execute if you call it. In the future we'll add conditional control -flow to actually make recursion useful :).

- -
-
-ready> extern cos(x);
-Read extern: 
-declare double @cos(double)
-
-ready> cos(1.234);
-Read top-level expression:
-define double @1() {
-entry:
-  %calltmp = call double @cos(double 1.234000e+00)
-  ret double %calltmp
-}
-
-
- -

This shows an extern for the libm "cos" function, and a call to it.

- - -
-
-ready> ^D
-; ModuleID = 'my cool jit'
-
-define double @0() {
-entry:
-  %addtmp = fadd double 4.000000e+00, 5.000000e+00
-  ret double %addtmp
-}
-
-define double @foo(double %a, double %b) {
-entry:
-  %multmp = fmul double %a, %a
-  %multmp1 = fmul double 2.000000e+00, %a
-  %multmp2 = fmul double %multmp1, %b
-  %addtmp = fadd double %multmp, %multmp2
-  %multmp3 = fmul double %b, %b
-  %addtmp4 = fadd double %addtmp, %multmp3
-  ret double %addtmp4
-}
-
-define double @bar(double %a) {
-entry:
-  %calltmp = call double @foo(double %a, double 4.000000e+00)
-  %calltmp1 = call double @bar(double 3.133700e+04)
-  %addtmp = fadd double %calltmp, %calltmp1
-  ret double %addtmp
-}
-
-declare double @cos(double)
-
-define double @1() {
-entry:
-  %calltmp = call double @cos(double 1.234000e+00)
-  ret double %calltmp
-}
-
-
- -

When you quit the current demo, it dumps out the IR for the entire module -generated. Here you can see the big picture with all the functions referencing -each other.

- -

This wraps up the third chapter of the Kaleidoscope tutorial. Up next, we'll -describe how to add JIT codegen and optimizer -support to this so we can actually start running code!

- -
- - - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -LLVM code generator. Because this uses the LLVM libraries, we need to link -them in. To do this, we use the llvm-config tool to inform -our makefile/command line about which options to use:

- -
-
-# Compile
-clang++ -g -O3 toy.cpp `llvm-config --cppflags --ldflags --libs core` -o toy
-# Run
-./toy
-
-
- -

Here is the code:

- -
-
-// To build this:
-// See example below.
-
-#include "llvm/DerivedTypes.h"
-#include "llvm/LLVMContext.h"
-#include "llvm/Module.h"
-#include "llvm/Analysis/Verifier.h"
-#include "llvm/Support/IRBuilder.h"
-#include <cstdio>
-#include <string>
-#include <map>
-#include <vector>
-using namespace llvm;
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-  virtual Value *Codegen();
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-  virtual Value *Codegen();
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-  virtual Value *Codegen();
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes).
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args)
-    : Name(name), Args(args) {}
-  
-  Function *Codegen();
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-  Function *Codegen();
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  }
-}
-
-/// binoprhs
-///   ::= ('+' primary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the primary expression after the binary operator.
-    ExprAST *RHS = ParsePrimary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= primary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParsePrimary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-static PrototypeAST *ParsePrototype() {
-  if (CurTok != tok_identifier)
-    return ErrorP("Expected function name in prototype");
-
-  std::string FnName = IdentifierStr;
-  getNextToken();
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  return new PrototypeAST(FnName, ArgNames);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Code Generation
-//===----------------------------------------------------------------------===//
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, Value*> NamedValues;
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  return V ? V : ErrorV("Unknown variable name");
-}
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: return ErrorV("invalid binary operator");
-  }
-}
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-  
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-  
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-    
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-  
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx) {
-    AI->setName(Args[Idx]);
-    
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = AI;
-  }
-  
-  return F;
-}
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    return TheFunction;
-  }
-  
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing and JIT Driver
-//===----------------------------------------------------------------------===//
-
-static void HandleDefinition() {
-  if (FunctionAST *F = ParseDefinition()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read function definition:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (PrototypeAST *P = ParseExtern()) {
-    if (Function *F = P->Codegen()) {
-      fprintf(stderr, "Read extern: ");
-      F->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read top-level expression:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// "Library" functions that can be "extern'd" from user code.
-//===----------------------------------------------------------------------===//
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  LLVMContext &Context = getGlobalContext();
-
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Make the module, which holds all the code.
-  TheModule = new Module("my cool jit", Context);
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  // Print out all of the generated code.
-  TheModule->dump();
-
-  return 0;
-}
-
-
-Next: Adding JIT and Optimizer Support -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl4.html b/cpp/llvm/docs/tutorial/LangImpl4.html deleted file mode 100644 index 84331d45..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl4.html +++ /dev/null @@ -1,1153 +0,0 @@ - - - - - Kaleidoscope: Adding JIT and Optimizer Support - - - - - - - -

Kaleidoscope: Adding JIT and Optimizer Support

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 4 Introduction

- - -
- -

Welcome to Chapter 4 of the "Implementing a language -with LLVM" tutorial. Chapters 1-3 described the implementation of a simple -language and added support for generating LLVM IR. This chapter describes -two new techniques: adding optimizer support to your language, and adding JIT -compiler support. These additions will demonstrate how to get nice, efficient code -for the Kaleidoscope language.

- -
- - -

Trivial Constant Folding

- - -
- -

-Our demonstration for Chapter 3 is elegant and easy to extend. Unfortunately, -it does not produce wonderful code. The IRBuilder, however, does give us -obvious optimizations when compiling simple code:

- -
-
-ready> def test(x) 1+2+x;
-Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 3.000000e+00, %x
-        ret double %addtmp
-}
-
-
- -

This code is not a literal transcription of the AST built by parsing the -input. That would be: - -

-
-ready> def test(x) 1+2+x;
-Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 2.000000e+00, 1.000000e+00
-        %addtmp1 = fadd double %addtmp, %x
-        ret double %addtmp1
-}
-
-
- -

Constant folding, as seen above, in particular, is a very common and very -important optimization: so much so that many language implementors implement -constant folding support in their AST representation.

- -

With LLVM, you don't need this support in the AST. Since all calls to build -LLVM IR go through the LLVM IR builder, the builder itself checked to see if -there was a constant folding opportunity when you call it. If so, it just does -the constant fold and return the constant instead of creating an instruction. - -

Well, that was easy :). In practice, we recommend always using -IRBuilder when generating code like this. It has no -"syntactic overhead" for its use (you don't have to uglify your compiler with -constant checks everywhere) and it can dramatically reduce the amount of -LLVM IR that is generated in some cases (particular for languages with a macro -preprocessor or that use a lot of constants).

- -

On the other hand, the IRBuilder is limited by the fact -that it does all of its analysis inline with the code as it is built. If you -take a slightly more complex example:

- -
-
-ready> def test(x) (1+2+x)*(x+(1+2));
-ready> Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 3.000000e+00, %x
-        %addtmp1 = fadd double %x, 3.000000e+00
-        %multmp = fmul double %addtmp, %addtmp1
-        ret double %multmp
-}
-
-
- -

In this case, the LHS and RHS of the multiplication are the same value. We'd -really like to see this generate "tmp = x+3; result = tmp*tmp;" instead -of computing "x+3" twice.

- -

Unfortunately, no amount of local analysis will be able to detect and correct -this. This requires two transformations: reassociation of expressions (to -make the add's lexically identical) and Common Subexpression Elimination (CSE) -to delete the redundant add instruction. Fortunately, LLVM provides a broad -range of optimizations that you can use, in the form of "passes".

- -
- - -

LLVM Optimization Passes

- - -
- -

LLVM provides many optimization passes, which do many different sorts of -things and have different tradeoffs. Unlike other systems, LLVM doesn't hold -to the mistaken notion that one set of optimizations is right for all languages -and for all situations. LLVM allows a compiler implementor to make complete -decisions about what optimizations to use, in which order, and in what -situation.

- -

As a concrete example, LLVM supports both "whole module" passes, which look -across as large of body of code as they can (often a whole file, but if run -at link time, this can be a substantial portion of the whole program). It also -supports and includes "per-function" passes which just operate on a single -function at a time, without looking at other functions. For more information -on passes and how they are run, see the How -to Write a Pass document and the List of LLVM -Passes.

- -

For Kaleidoscope, we are currently generating functions on the fly, one at -a time, as the user types them in. We aren't shooting for the ultimate -optimization experience in this setting, but we also want to catch the easy and -quick stuff where possible. As such, we will choose to run a few per-function -optimizations as the user types the function in. If we wanted to make a "static -Kaleidoscope compiler", we would use exactly the code we have now, except that -we would defer running the optimizer until the entire file has been parsed.

- -

In order to get per-function optimizations going, we need to set up a -FunctionPassManager to hold and -organize the LLVM optimizations that we want to run. Once we have that, we can -add a set of optimizations to run. The code looks like this:

- -
-
-  FunctionPassManager OurFPM(TheModule);
-
-  // Set up the optimizer pipeline.  Start with registering info about how the
-  // target lays out data structures.
-  OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-  // Provide basic AliasAnalysis support for GVN.
-  OurFPM.add(createBasicAliasAnalysisPass());
-  // Do simple "peephole" optimizations and bit-twiddling optzns.
-  OurFPM.add(createInstructionCombiningPass());
-  // Reassociate expressions.
-  OurFPM.add(createReassociatePass());
-  // Eliminate Common SubExpressions.
-  OurFPM.add(createGVNPass());
-  // Simplify the control flow graph (deleting unreachable blocks, etc).
-  OurFPM.add(createCFGSimplificationPass());
-
-  OurFPM.doInitialization();
-
-  // Set the global so the code gen can use this.
-  TheFPM = &OurFPM;
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-
- -

This code defines a FunctionPassManager, "OurFPM". It -requires a pointer to the Module to construct itself. Once it is set -up, we use a series of "add" calls to add a bunch of LLVM passes. The first -pass is basically boilerplate, it adds a pass so that later optimizations know -how the data structures in the program are laid out. The -"TheExecutionEngine" variable is related to the JIT, which we will get -to in the next section.

- -

In this case, we choose to add 4 optimization passes. The passes we chose -here are a pretty standard set of "cleanup" optimizations that are useful for -a wide variety of code. I won't delve into what they do but, believe me, -they are a good starting place :).

- -

Once the PassManager is set up, we need to make use of it. We do this by -running it after our newly created function is constructed (in -FunctionAST::Codegen), but before it is returned to the client:

- -
-
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    // Optimize the function.
-    TheFPM->run(*TheFunction);
-    
-    return TheFunction;
-  }
-
-
- -

As you can see, this is pretty straightforward. The -FunctionPassManager optimizes and updates the LLVM Function* in place, -improving (hopefully) its body. With this in place, we can try our test above -again:

- -
-
-ready> def test(x) (1+2+x)*(x+(1+2));
-ready> Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double %x, 3.000000e+00
-        %multmp = fmul double %addtmp, %addtmp
-        ret double %multmp
-}
-
-
- -

As expected, we now get our nicely optimized code, saving a floating point -add instruction from every execution of this function.

- -

LLVM provides a wide variety of optimizations that can be used in certain -circumstances. Some documentation about the various -passes is available, but it isn't very complete. Another good source of -ideas can come from looking at the passes that llvm-gcc or -llvm-ld run to get started. The "opt" tool allows you to -experiment with passes from the command line, so you can see if they do -anything.

- -

Now that we have reasonable code coming out of our front-end, lets talk about -executing it!

- -
- - -

Adding a JIT Compiler

- - -
- -

Code that is available in LLVM IR can have a wide variety of tools -applied to it. For example, you can run optimizations on it (as we did above), -you can dump it out in textual or binary forms, you can compile the code to an -assembly file (.s) for some target, or you can JIT compile it. The nice thing -about the LLVM IR representation is that it is the "common currency" between -many different parts of the compiler. -

- -

In this section, we'll add JIT compiler support to our interpreter. The -basic idea that we want for Kaleidoscope is to have the user enter function -bodies as they do now, but immediately evaluate the top-level expressions they -type in. For example, if they type in "1 + 2;", we should evaluate and print -out 3. If they define a function, they should be able to call it from the -command line.

- -

In order to do this, we first declare and initialize the JIT. This is done -by adding a global variable and a call in main:

- -
-
-static ExecutionEngine *TheExecutionEngine;
-...
-int main() {
-  ..
-  // Create the JIT.  This takes ownership of the module.
-  TheExecutionEngine = EngineBuilder(TheModule).create();
-  ..
-}
-
-
- -

This creates an abstract "Execution Engine" which can be either a JIT -compiler or the LLVM interpreter. LLVM will automatically pick a JIT compiler -for you if one is available for your platform, otherwise it will fall back to -the interpreter.

- -

Once the ExecutionEngine is created, the JIT is ready to be used. -There are a variety of APIs that are useful, but the simplest one is the -"getPointerToFunction(F)" method. This method JIT compiles the -specified LLVM Function and returns a function pointer to the generated machine -code. In our case, this means that we can change the code that parses a -top-level expression to look like this:

- -
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      LF->dump();  // Dump the function for exposition purposes.
-    
-      // JIT the function, returning a function pointer.
-      void *FPtr = TheExecutionEngine->getPointerToFunction(LF);
-      
-      // Cast it to the right type (takes no arguments, returns a double) so we
-      // can call it as a native function.
-      double (*FP)() = (double (*)())(intptr_t)FPtr;
-      fprintf(stderr, "Evaluated to %f\n", FP());
-    }
-
-
- -

Recall that we compile top-level expressions into a self-contained LLVM -function that takes no arguments and returns the computed double. Because the -LLVM JIT compiler matches the native platform ABI, this means that you can just -cast the result pointer to a function pointer of that type and call it directly. -This means, there is no difference between JIT compiled code and native machine -code that is statically linked into your application.

- -

With just these two changes, lets see how Kaleidoscope works now!

- -
-
-ready> 4+5;
-Read top-level expression:
-define double @0() {
-entry:
-  ret double 9.000000e+00
-}
-
-Evaluated to 9.000000
-
-
- -

Well this looks like it is basically working. The dump of the function -shows the "no argument function that always returns double" that we synthesize -for each top-level expression that is typed in. This demonstrates very basic -functionality, but can we do more?

- -
-
-ready> def testfunc(x y) x + y*2;  
-Read function definition:
-define double @testfunc(double %x, double %y) {
-entry:
-  %multmp = fmul double %y, 2.000000e+00
-  %addtmp = fadd double %multmp, %x
-  ret double %addtmp
-}
-
-ready> testfunc(4, 10);
-Read top-level expression:
-define double @1() {
-entry:
-  %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
-  ret double %calltmp
-}
-
-Evaluated to 24.000000
-
-
- -

This illustrates that we can now call user code, but there is something a bit -subtle going on here. Note that we only invoke the JIT on the anonymous -functions that call testfunc, but we never invoked it -on testfunc itself. What actually happened here is that the JIT -scanned for all non-JIT'd functions transitively called from the anonymous -function and compiled all of them before returning -from getPointerToFunction().

- -

The JIT provides a number of other more advanced interfaces for things like -freeing allocated machine code, rejit'ing functions to update them, etc. -However, even with this simple code, we get some surprisingly powerful -capabilities - check this out (I removed the dump of the anonymous functions, -you should get the idea by now :) :

- -
-
-ready> extern sin(x);
-Read extern: 
-declare double @sin(double)
-
-ready> extern cos(x);
-Read extern: 
-declare double @cos(double)
-
-ready> sin(1.0);
-Read top-level expression:
-define double @2() {
-entry:
-  ret double 0x3FEAED548F090CEE
-}
-
-Evaluated to 0.841471
-
-ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
-Read function definition:
-define double @foo(double %x) {
-entry:
-  %calltmp = call double @sin(double %x)
-  %multmp = fmul double %calltmp, %calltmp
-  %calltmp2 = call double @cos(double %x)
-  %multmp4 = fmul double %calltmp2, %calltmp2
-  %addtmp = fadd double %multmp, %multmp4
-  ret double %addtmp
-}
-
-ready> foo(4.0);
-Read top-level expression:
-define double @3() {
-entry:
-  %calltmp = call double @foo(double 4.000000e+00)
-  ret double %calltmp
-}
-
-Evaluated to 1.000000
-
-
- -

Whoa, how does the JIT know about sin and cos? The answer is surprisingly -simple: in this -example, the JIT started execution of a function and got to a function call. It -realized that the function was not yet JIT compiled and invoked the standard set -of routines to resolve the function. In this case, there is no body defined -for the function, so the JIT ended up calling "dlsym("sin")" on the -Kaleidoscope process itself. -Since "sin" is defined within the JIT's address space, it simply -patches up calls in the module to call the libm version of sin -directly.

- -

The LLVM JIT provides a number of interfaces (look in the -ExecutionEngine.h file) for controlling how unknown functions get -resolved. It allows you to establish explicit mappings between IR objects and -addresses (useful for LLVM global variables that you want to map to static -tables, for example), allows you to dynamically decide on the fly based on the -function name, and even allows you to have the JIT compile functions lazily the -first time they're called.

- -

One interesting application of this is that we can now extend the language -by writing arbitrary C++ code to implement operations. For example, if we add: -

- -
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-
- -

Now we can produce simple output to the console by using things like: -"extern putchard(x); putchard(120);", which prints a lowercase 'x' on -the console (120 is the ASCII code for 'x'). Similar code could be used to -implement file I/O, console input, and many other capabilities in -Kaleidoscope.

- -

This completes the JIT and optimizer chapter of the Kaleidoscope tutorial. At -this point, we can compile a non-Turing-complete programming language, optimize -and JIT compile it in a user-driven way. Next up we'll look into extending the language with control flow constructs, -tackling some interesting LLVM IR issues along the way.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -LLVM JIT and optimizer. To build this example, use: -

- -
-
-# Compile
-clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy
-# Run
-./toy
-
-
- -

-If you are compiling this on Linux, make sure to add the "-rdynamic" option -as well. This makes sure that the external functions are resolved properly -at runtime.

- -

Here is the code:

- -
-
-#include "llvm/DerivedTypes.h"
-#include "llvm/ExecutionEngine/ExecutionEngine.h"
-#include "llvm/ExecutionEngine/JIT.h"
-#include "llvm/LLVMContext.h"
-#include "llvm/Module.h"
-#include "llvm/PassManager.h"
-#include "llvm/Analysis/Verifier.h"
-#include "llvm/Analysis/Passes.h"
-#include "llvm/Target/TargetData.h"
-#include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/IRBuilder.h"
-#include "llvm/Support/TargetSelect.h"
-#include <cstdio>
-#include <string>
-#include <map>
-#include <vector>
-using namespace llvm;
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-  virtual Value *Codegen();
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-  virtual Value *Codegen();
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-  virtual Value *Codegen();
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes).
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args)
-    : Name(name), Args(args) {}
-  
-  Function *Codegen();
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-  Function *Codegen();
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  }
-}
-
-/// binoprhs
-///   ::= ('+' primary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the primary expression after the binary operator.
-    ExprAST *RHS = ParsePrimary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= primary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParsePrimary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-static PrototypeAST *ParsePrototype() {
-  if (CurTok != tok_identifier)
-    return ErrorP("Expected function name in prototype");
-
-  std::string FnName = IdentifierStr;
-  getNextToken();
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  return new PrototypeAST(FnName, ArgNames);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Code Generation
-//===----------------------------------------------------------------------===//
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, Value*> NamedValues;
-static FunctionPassManager *TheFPM;
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  return V ? V : ErrorV("Unknown variable name");
-}
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: return ErrorV("invalid binary operator");
-  }
-}
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-  
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-  
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-    
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-  
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx) {
-    AI->setName(Args[Idx]);
-    
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = AI;
-  }
-  
-  return F;
-}
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    // Optimize the function.
-    TheFPM->run(*TheFunction);
-    
-    return TheFunction;
-  }
-  
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing and JIT Driver
-//===----------------------------------------------------------------------===//
-
-static ExecutionEngine *TheExecutionEngine;
-
-static void HandleDefinition() {
-  if (FunctionAST *F = ParseDefinition()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read function definition:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (PrototypeAST *P = ParseExtern()) {
-    if (Function *F = P->Codegen()) {
-      fprintf(stderr, "Read extern: ");
-      F->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read top-level expression:");
-      LF->dump();
-
-      // JIT the function, returning a function pointer.
-      void *FPtr = TheExecutionEngine->getPointerToFunction(LF);
-      
-      // Cast it to the right type (takes no arguments, returns a double) so we
-      // can call it as a native function.
-      double (*FP)() = (double (*)())(intptr_t)FPtr;
-      fprintf(stderr, "Evaluated to %f\n", FP());
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// "Library" functions that can be "extern'd" from user code.
-//===----------------------------------------------------------------------===//
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  InitializeNativeTarget();
-  LLVMContext &Context = getGlobalContext();
-
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Make the module, which holds all the code.
-  TheModule = new Module("my cool jit", Context);
-
-  // Create the JIT.  This takes ownership of the module.
-  std::string ErrStr;
-  TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create();
-  if (!TheExecutionEngine) {
-    fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str());
-    exit(1);
-  }
-
-  FunctionPassManager OurFPM(TheModule);
-
-  // Set up the optimizer pipeline.  Start with registering info about how the
-  // target lays out data structures.
-  OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-  // Provide basic AliasAnalysis support for GVN.
-  OurFPM.add(createBasicAliasAnalysisPass());
-  // Do simple "peephole" optimizations and bit-twiddling optzns.
-  OurFPM.add(createInstructionCombiningPass());
-  // Reassociate expressions.
-  OurFPM.add(createReassociatePass());
-  // Eliminate Common SubExpressions.
-  OurFPM.add(createGVNPass());
-  // Simplify the control flow graph (deleting unreachable blocks, etc).
-  OurFPM.add(createCFGSimplificationPass());
-
-  OurFPM.doInitialization();
-
-  // Set the global so the code gen can use this.
-  TheFPM = &OurFPM;
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  TheFPM = 0;
-
-  // Print out all of the generated code.
-  TheModule->dump();
-
-  return 0;
-}
-
-
- -Next: Extending the language: control flow -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl5-cfg.png b/cpp/llvm/docs/tutorial/LangImpl5-cfg.png deleted file mode 100644 index cdba92ff6c5c95b142bd928971bcdd560117028c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 38586 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 E01+e^=Kufz diff --git a/cpp/llvm/docs/tutorial/LangImpl5.html b/cpp/llvm/docs/tutorial/LangImpl5.html deleted file mode 100644 index d98e9592..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl5.html +++ /dev/null @@ -1,1772 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: Control Flow - - - - - - - -

Kaleidoscope: Extending the Language: Control Flow

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 5 Introduction

- - -
- -

Welcome to Chapter 5 of the "Implementing a language -with LLVM" tutorial. Parts 1-4 described the implementation of the simple -Kaleidoscope language and included support for generating LLVM IR, followed by -optimizations and a JIT compiler. Unfortunately, as presented, Kaleidoscope is -mostly useless: it has no control flow other than call and return. This means -that you can't have conditional branches in the code, significantly limiting its -power. In this episode of "build that compiler", we'll extend Kaleidoscope to -have an if/then/else expression plus a simple 'for' loop.

- -
- - -

If/Then/Else

- - -
- -

-Extending Kaleidoscope to support if/then/else is quite straightforward. It -basically requires adding support for this "new" concept to the lexer, -parser, AST, and LLVM code emitter. This example is nice, because it shows how -easy it is to "grow" a language over time, incrementally extending it as new -ideas are discovered.

- -

Before we get going on "how" we add this extension, lets talk about "what" we -want. The basic idea is that we want to be able to write this sort of thing: -

- -
-
-def fib(x)
-  if x < 3 then
-    1
-  else
-    fib(x-1)+fib(x-2);
-
-
- -

In Kaleidoscope, every construct is an expression: there are no statements. -As such, the if/then/else expression needs to return a value like any other. -Since we're using a mostly functional form, we'll have it evaluate its -conditional, then return the 'then' or 'else' value based on how the condition -was resolved. This is very similar to the C "?:" expression.

- -

The semantics of the if/then/else expression is that it evaluates the -condition to a boolean equality value: 0.0 is considered to be false and -everything else is considered to be true. -If the condition is true, the first subexpression is evaluated and returned, if -the condition is false, the second subexpression is evaluated and returned. -Since Kaleidoscope allows side-effects, this behavior is important to nail down. -

- -

Now that we know what we "want", lets break this down into its constituent -pieces.

- - -

Lexer Extensions for If/Then/Else

- - - -
- -

The lexer extensions are straightforward. First we add new enum values -for the relevant tokens:

- -
-
-  // control
-  tok_if = -6, tok_then = -7, tok_else = -8,
-
-
- -

Once we have that, we recognize the new keywords in the lexer. This is pretty simple -stuff:

- -
-
-    ...
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    if (IdentifierStr == "if") return tok_if;
-    if (IdentifierStr == "then") return tok_then;
-    if (IdentifierStr == "else") return tok_else;
-    return tok_identifier;
-
-
- -
- - -

AST Extensions for If/Then/Else

- - -
- -

To represent the new expression we add a new AST node for it:

- -
-
-/// IfExprAST - Expression class for if/then/else.
-class IfExprAST : public ExprAST {
-  ExprAST *Cond, *Then, *Else;
-public:
-  IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else)
-    : Cond(cond), Then(then), Else(_else) {}
-  virtual Value *Codegen();
-};
-
-
- -

The AST node just has pointers to the various subexpressions.

- -
- - -

Parser Extensions for If/Then/Else

- - -
- -

Now that we have the relevant tokens coming from the lexer and we have the -AST node to build, our parsing logic is relatively straightforward. First we -define a new parsing function:

- -
-
-/// ifexpr ::= 'if' expression 'then' expression 'else' expression
-static ExprAST *ParseIfExpr() {
-  getNextToken();  // eat the if.
-  
-  // condition.
-  ExprAST *Cond = ParseExpression();
-  if (!Cond) return 0;
-  
-  if (CurTok != tok_then)
-    return Error("expected then");
-  getNextToken();  // eat the then
-  
-  ExprAST *Then = ParseExpression();
-  if (Then == 0) return 0;
-  
-  if (CurTok != tok_else)
-    return Error("expected else");
-  
-  getNextToken();
-  
-  ExprAST *Else = ParseExpression();
-  if (!Else) return 0;
-  
-  return new IfExprAST(Cond, Then, Else);
-}
-
-
- -

Next we hook it up as a primary expression:

- -
-
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  case tok_if:         return ParseIfExpr();
-  }
-}
-
-
- -
- - -

LLVM IR for If/Then/Else

- - -
- -

Now that we have it parsing and building the AST, the final piece is adding -LLVM code generation support. This is the most interesting part of the -if/then/else example, because this is where it starts to introduce new concepts. -All of the code above has been thoroughly described in previous chapters. -

- -

To motivate the code we want to produce, lets take a look at a simple -example. Consider:

- -
-
-extern foo();
-extern bar();
-def baz(x) if x then foo() else bar();
-
-
- -

If you disable optimizations, the code you'll (soon) get from Kaleidoscope -looks like this:

- -
-
-declare double @foo()
-
-declare double @bar()
-
-define double @baz(double %x) {
-entry:
-  %ifcond = fcmp one double %x, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:		; preds = %entry
-  %calltmp = call double @foo()
-  br label %ifcont
-
-else:		; preds = %entry
-  %calltmp1 = call double @bar()
-  br label %ifcont
-
-ifcont:		; preds = %else, %then
-  %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
-  ret double %iftmp
-}
-
-
- -

To visualize the control flow graph, you can use a nifty feature of the LLVM -'opt' tool. If you put this LLVM IR -into "t.ll" and run "llvm-as < t.ll | opt -analyze -view-cfg", a window will pop up and you'll -see this graph:

- -
Example CFG
- -

Another way to get this is to call "F->viewCFG()" or -"F->viewCFGOnly()" (where F is a "Function*") either by -inserting actual calls into the code and recompiling or by calling these in the -debugger. LLVM has many nice features for visualizing various graphs.

- -

Getting back to the generated code, it is fairly simple: the entry block -evaluates the conditional expression ("x" in our case here) and compares the -result to 0.0 with the "fcmp one" -instruction ('one' is "Ordered and Not Equal"). Based on the result of this -expression, the code jumps to either the "then" or "else" blocks, which contain -the expressions for the true/false cases.

- -

Once the then/else blocks are finished executing, they both branch back to the -'ifcont' block to execute the code that happens after the if/then/else. In this -case the only thing left to do is to return to the caller of the function. The -question then becomes: how does the code know which expression to return?

- -

The answer to this question involves an important SSA operation: the -Phi -operation. If you're not familiar with SSA, the wikipedia -article is a good introduction and there are various other introductions to -it available on your favorite search engine. The short version is that -"execution" of the Phi operation requires "remembering" which block control came -from. The Phi operation takes on the value corresponding to the input control -block. In this case, if control comes in from the "then" block, it gets the -value of "calltmp". If control comes from the "else" block, it gets the value -of "calltmp1".

- -

At this point, you are probably starting to think "Oh no! This means my -simple and elegant front-end will have to start generating SSA form in order to -use LLVM!". Fortunately, this is not the case, and we strongly advise -not implementing an SSA construction algorithm in your front-end -unless there is an amazingly good reason to do so. In practice, there are two -sorts of values that float around in code written for your average imperative -programming language that might need Phi nodes:

- -
    -
  1. Code that involves user variables: x = 1; x = x + 1;
  2. -
  3. Values that are implicit in the structure of your AST, such as the Phi node -in this case.
  4. -
- -

In Chapter 7 of this tutorial ("mutable -variables"), we'll talk about #1 -in depth. For now, just believe me that you don't need SSA construction to -handle this case. For #2, you have the choice of using the techniques that we will -describe for #1, or you can insert Phi nodes directly, if convenient. In this -case, it is really really easy to generate the Phi node, so we choose to do it -directly.

- -

Okay, enough of the motivation and overview, lets generate code!

- -
- - -

Code Generation for If/Then/Else

- - -
- -

In order to generate code for this, we implement the Codegen method -for IfExprAST:

- -
-
-Value *IfExprAST::Codegen() {
-  Value *CondV = Cond->Codegen();
-  if (CondV == 0) return 0;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  CondV = Builder.CreateFCmpONE(CondV, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                "ifcond");
-
-
- -

This code is straightforward and similar to what we saw before. We emit the -expression for the condition, then compare that value to zero to get a truth -value as a 1-bit (bool) value.

- -
-
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
-  // end of the function.
-  BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else");
-  BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont");
-
-  Builder.CreateCondBr(CondV, ThenBB, ElseBB);
-
-
- -

This code creates the basic blocks that are related to the if/then/else -statement, and correspond directly to the blocks in the example above. The -first line gets the current Function object that is being built. It -gets this by asking the builder for the current BasicBlock, and asking that -block for its "parent" (the function it is currently embedded into).

- -

Once it has that, it creates three blocks. Note that it passes "TheFunction" -into the constructor for the "then" block. This causes the constructor to -automatically insert the new block into the end of the specified function. The -other two blocks are created, but aren't yet inserted into the function.

- -

Once the blocks are created, we can emit the conditional branch that chooses -between them. Note that creating new blocks does not implicitly affect the -IRBuilder, so it is still inserting into the block that the condition -went into. Also note that it is creating a branch to the "then" block and the -"else" block, even though the "else" block isn't inserted into the function yet. -This is all ok: it is the standard way that LLVM supports forward -references.

- -
-
-  // Emit then value.
-  Builder.SetInsertPoint(ThenBB);
-  
-  Value *ThenV = Then->Codegen();
-  if (ThenV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
-  ThenBB = Builder.GetInsertBlock();
-
-
- -

After the conditional branch is inserted, we move the builder to start -inserting into the "then" block. Strictly speaking, this call moves the -insertion point to be at the end of the specified block. However, since the -"then" block is empty, it also starts out by inserting at the beginning of the -block. :)

- -

Once the insertion point is set, we recursively codegen the "then" expression -from the AST. To finish off the "then" block, we create an unconditional branch -to the merge block. One interesting (and very important) aspect of the LLVM IR -is that it requires all basic blocks -to be "terminated" with a control flow -instruction such as return or branch. This means that all control flow, -including fall throughs must be made explicit in the LLVM IR. If you -violate this rule, the verifier will emit an error.

- -

The final line here is quite subtle, but is very important. The basic issue -is that when we create the Phi node in the merge block, we need to set up the -block/value pairs that indicate how the Phi will work. Importantly, the Phi -node expects to have an entry for each predecessor of the block in the CFG. Why -then, are we getting the current block when we just set it to ThenBB 5 lines -above? The problem is that the "Then" expression may actually itself change the -block that the Builder is emitting into if, for example, it contains a nested -"if/then/else" expression. Because calling Codegen recursively could -arbitrarily change the notion of the current block, we are required to get an -up-to-date value for code that will set up the Phi node.

- -
-
-  // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
-  Builder.SetInsertPoint(ElseBB);
-  
-  Value *ElseV = Else->Codegen();
-  if (ElseV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
-  ElseBB = Builder.GetInsertBlock();
-
-
- -

Code generation for the 'else' block is basically identical to codegen for -the 'then' block. The only significant difference is the first line, which adds -the 'else' block to the function. Recall previously that the 'else' block was -created, but not added to the function. Now that the 'then' and 'else' blocks -are emitted, we can finish up with the merge code:

- -
-
-  // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
-  Builder.SetInsertPoint(MergeBB);
-  PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2,
-                                  "iftmp");
-  
-  PN->addIncoming(ThenV, ThenBB);
-  PN->addIncoming(ElseV, ElseBB);
-  return PN;
-}
-
-
- -

The first two lines here are now familiar: the first adds the "merge" block -to the Function object (it was previously floating, like the else block above). -The second block changes the insertion point so that newly created code will go -into the "merge" block. Once that is done, we need to create the PHI node and -set up the block/value pairs for the PHI.

- -

Finally, the CodeGen function returns the phi node as the value computed by -the if/then/else expression. In our example above, this returned value will -feed into the code for the top-level function, which will create the return -instruction.

- -

Overall, we now have the ability to execute conditional code in -Kaleidoscope. With this extension, Kaleidoscope is a fairly complete language -that can calculate a wide variety of numeric functions. Next up we'll add -another useful expression that is familiar from non-functional languages...

- -
- -
- - -

'for' Loop Expression

- - -
- -

Now that we know how to add basic control flow constructs to the language, -we have the tools to add more powerful things. Lets add something more -aggressive, a 'for' expression:

- -
-
- extern putchard(char)
- def printstar(n)
-   for i = 1, i < n, 1.0 in
-     putchard(42);  # ascii 42 = '*'
-     
- # print 100 '*' characters
- printstar(100);
-
-
- -

This expression defines a new variable ("i" in this case) which iterates from -a starting value, while the condition ("i < n" in this case) is true, -incrementing by an optional step value ("1.0" in this case). If the step value -is omitted, it defaults to 1.0. While the loop is true, it executes its -body expression. Because we don't have anything better to return, we'll just -define the loop as always returning 0.0. In the future when we have mutable -variables, it will get more useful.

- -

As before, lets talk about the changes that we need to Kaleidoscope to -support this.

- - -

Lexer Extensions for the 'for' Loop

- - -
- -

The lexer extensions are the same sort of thing as for if/then/else:

- -
-
-  ... in enum Token ...
-  // control
-  tok_if = -6, tok_then = -7, tok_else = -8,
-  tok_for = -9, tok_in = -10
-
-  ... in gettok ...
-  if (IdentifierStr == "def") return tok_def;
-  if (IdentifierStr == "extern") return tok_extern;
-  if (IdentifierStr == "if") return tok_if;
-  if (IdentifierStr == "then") return tok_then;
-  if (IdentifierStr == "else") return tok_else;
-  if (IdentifierStr == "for") return tok_for;
-  if (IdentifierStr == "in") return tok_in;
-  return tok_identifier;
-
-
- -
- - -

AST Extensions for the 'for' Loop

- - -
- -

The AST node is just as simple. It basically boils down to capturing -the variable name and the constituent expressions in the node.

- -
-
-/// ForExprAST - Expression class for for/in.
-class ForExprAST : public ExprAST {
-  std::string VarName;
-  ExprAST *Start, *End, *Step, *Body;
-public:
-  ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end,
-             ExprAST *step, ExprAST *body)
-    : VarName(varname), Start(start), End(end), Step(step), Body(body) {}
-  virtual Value *Codegen();
-};
-
-
- -
- - -

Parser Extensions for the 'for' Loop

- - -
- -

The parser code is also fairly standard. The only interesting thing here is -handling of the optional step value. The parser code handles it by checking to -see if the second comma is present. If not, it sets the step value to null in -the AST node:

- -
-
-/// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
-static ExprAST *ParseForExpr() {
-  getNextToken();  // eat the for.
-
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after for");
-  
-  std::string IdName = IdentifierStr;
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '=')
-    return Error("expected '=' after for");
-  getNextToken();  // eat '='.
-  
-  
-  ExprAST *Start = ParseExpression();
-  if (Start == 0) return 0;
-  if (CurTok != ',')
-    return Error("expected ',' after for start value");
-  getNextToken();
-  
-  ExprAST *End = ParseExpression();
-  if (End == 0) return 0;
-  
-  // The step value is optional.
-  ExprAST *Step = 0;
-  if (CurTok == ',') {
-    getNextToken();
-    Step = ParseExpression();
-    if (Step == 0) return 0;
-  }
-  
-  if (CurTok != tok_in)
-    return Error("expected 'in' after for");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-
-  return new ForExprAST(IdName, Start, End, Step, Body);
-}
-
-
- -
- - -

LLVM IR for the 'for' Loop

- - -
- -

Now we get to the good part: the LLVM IR we want to generate for this thing. -With the simple example above, we get this LLVM IR (note that this dump is -generated with optimizations disabled for clarity): -

- -
-
-declare double @putchard(double)
-
-define double @printstar(double %n) {
-entry:
-  ; initial value = 1.0 (inlined into phi)
-  br label %loop
-
-loop:		; preds = %loop, %entry
-  %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
-  ; body
-  %calltmp = call double @putchard(double 4.200000e+01)
-  ; increment
-  %nextvar = fadd double %i, 1.000000e+00
-
-  ; termination test
-  %cmptmp = fcmp ult double %i, %n
-  %booltmp = uitofp i1 %cmptmp to double
-  %loopcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %loopcond, label %loop, label %afterloop
-
-afterloop:		; preds = %loop
-  ; loop always returns 0.0
-  ret double 0.000000e+00
-}
-
-
- -

This loop contains all the same constructs we saw before: a phi node, several -expressions, and some basic blocks. Lets see how this fits together.

- -
- - -

Code Generation for the 'for' Loop

- - -
- -

The first part of Codegen is very simple: we just output the start expression -for the loop value:

- -
-
-Value *ForExprAST::Codegen() {
-  // Emit the start code first, without 'variable' in scope.
-  Value *StartVal = Start->Codegen();
-  if (StartVal == 0) return 0;
-
-
- -

With this out of the way, the next step is to set up the LLVM basic block -for the start of the loop body. In the case above, the whole loop body is one -block, but remember that the body code itself could consist of multiple blocks -(e.g. if it contains an if/then/else or a for/in expression).

- -
-
-  // Make the new basic block for the loop header, inserting after current
-  // block.
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  BasicBlock *PreheaderBB = Builder.GetInsertBlock();
-  BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction);
-  
-  // Insert an explicit fall through from the current block to the LoopBB.
-  Builder.CreateBr(LoopBB);
-
-
- -

This code is similar to what we saw for if/then/else. Because we will need -it to create the Phi node, we remember the block that falls through into the -loop. Once we have that, we create the actual block that starts the loop and -create an unconditional branch for the fall-through between the two blocks.

- -
-
-  // Start insertion in LoopBB.
-  Builder.SetInsertPoint(LoopBB);
-  
-  // Start the PHI node with an entry for Start.
-  PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, VarName.c_str());
-  Variable->addIncoming(StartVal, PreheaderBB);
-
-
- -

Now that the "preheader" for the loop is set up, we switch to emitting code -for the loop body. To begin with, we move the insertion point and create the -PHI node for the loop induction variable. Since we already know the incoming -value for the starting value, we add it to the Phi node. Note that the Phi will -eventually get a second value for the backedge, but we can't set it up yet -(because it doesn't exist!).

- -
-
-  // Within the loop, the variable is defined equal to the PHI node.  If it
-  // shadows an existing variable, we have to restore it, so save it now.
-  Value *OldVal = NamedValues[VarName];
-  NamedValues[VarName] = Variable;
-  
-  // Emit the body of the loop.  This, like any other expr, can change the
-  // current BB.  Note that we ignore the value computed by the body, but don't
-  // allow an error.
-  if (Body->Codegen() == 0)
-    return 0;
-
-
- -

Now the code starts to get more interesting. Our 'for' loop introduces a new -variable to the symbol table. This means that our symbol table can now contain -either function arguments or loop variables. To handle this, before we codegen -the body of the loop, we add the loop variable as the current value for its -name. Note that it is possible that there is a variable of the same name in the -outer scope. It would be easy to make this an error (emit an error and return -null if there is already an entry for VarName) but we choose to allow shadowing -of variables. In order to handle this correctly, we remember the Value that -we are potentially shadowing in OldVal (which will be null if there is -no shadowed variable).

- -

Once the loop variable is set into the symbol table, the code recursively -codegen's the body. This allows the body to use the loop variable: any -references to it will naturally find it in the symbol table.

- -
-
-  // Emit the step value.
-  Value *StepVal;
-  if (Step) {
-    StepVal = Step->Codegen();
-    if (StepVal == 0) return 0;
-  } else {
-    // If not specified, use 1.0.
-    StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0));
-  }
-  
-  Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
-
-
- -

Now that the body is emitted, we compute the next value of the iteration -variable by adding the step value, or 1.0 if it isn't present. 'NextVar' -will be the value of the loop variable on the next iteration of the loop.

- -
-
-  // Compute the end condition.
-  Value *EndCond = End->Codegen();
-  if (EndCond == 0) return EndCond;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  EndCond = Builder.CreateFCmpONE(EndCond, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                  "loopcond");
-
-
- -

Finally, we evaluate the exit value of the loop, to determine whether the -loop should exit. This mirrors the condition evaluation for the if/then/else -statement.

- -
-
-  // Create the "after loop" block and insert it.
-  BasicBlock *LoopEndBB = Builder.GetInsertBlock();
-  BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction);
-  
-  // Insert the conditional branch into the end of LoopEndBB.
-  Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-  
-  // Any new code will be inserted in AfterBB.
-  Builder.SetInsertPoint(AfterBB);
-
-
- -

With the code for the body of the loop complete, we just need to finish up -the control flow for it. This code remembers the end block (for the phi node), -then creates the block for the loop exit ("afterloop"). Based on the value of -the exit condition, it creates a conditional branch that chooses between -executing the loop again and exiting the loop. Any future code is emitted in -the "afterloop" block, so it sets the insertion position to it.

- -
-
-  // Add a new entry to the PHI node for the backedge.
-  Variable->addIncoming(NextVar, LoopEndBB);
-  
-  // Restore the unshadowed variable.
-  if (OldVal)
-    NamedValues[VarName] = OldVal;
-  else
-    NamedValues.erase(VarName);
-  
-  // for expr always returns 0.0.
-  return Constant::getNullValue(Type::getDoubleTy(getGlobalContext()));
-}
-
-
- -

The final code handles various cleanups: now that we have the "NextVar" -value, we can add the incoming value to the loop PHI node. After that, we -remove the loop variable from the symbol table, so that it isn't in scope after -the for loop. Finally, code generation of the for loop always returns 0.0, so -that is what we return from ForExprAST::Codegen.

- -

With this, we conclude the "adding control flow to Kaleidoscope" chapter of -the tutorial. In this chapter we added two control flow constructs, and used them to motivate a couple of aspects of the LLVM IR that are important for front-end implementors -to know. In the next chapter of our saga, we will get a bit crazier and add -user-defined operators to our poor innocent -language.

- -
- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -if/then/else and for expressions.. To build this example, use: -

- -
-
-# Compile
-clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy
-# Run
-./toy
-
-
- -

Here is the code:

- -
-
-#include "llvm/DerivedTypes.h"
-#include "llvm/ExecutionEngine/ExecutionEngine.h"
-#include "llvm/ExecutionEngine/JIT.h"
-#include "llvm/LLVMContext.h"
-#include "llvm/Module.h"
-#include "llvm/PassManager.h"
-#include "llvm/Analysis/Verifier.h"
-#include "llvm/Analysis/Passes.h"
-#include "llvm/Target/TargetData.h"
-#include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/IRBuilder.h"
-#include "llvm/Support/TargetSelect.h"
-#include <cstdio>
-#include <string>
-#include <map>
-#include <vector>
-using namespace llvm;
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5,
-  
-  // control
-  tok_if = -6, tok_then = -7, tok_else = -8,
-  tok_for = -9, tok_in = -10
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    if (IdentifierStr == "if") return tok_if;
-    if (IdentifierStr == "then") return tok_then;
-    if (IdentifierStr == "else") return tok_else;
-    if (IdentifierStr == "for") return tok_for;
-    if (IdentifierStr == "in") return tok_in;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-  virtual Value *Codegen();
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-  virtual Value *Codegen();
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-  virtual Value *Codegen();
-};
-
-/// IfExprAST - Expression class for if/then/else.
-class IfExprAST : public ExprAST {
-  ExprAST *Cond, *Then, *Else;
-public:
-  IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else)
-  : Cond(cond), Then(then), Else(_else) {}
-  virtual Value *Codegen();
-};
-
-/// ForExprAST - Expression class for for/in.
-class ForExprAST : public ExprAST {
-  std::string VarName;
-  ExprAST *Start, *End, *Step, *Body;
-public:
-  ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end,
-             ExprAST *step, ExprAST *body)
-    : VarName(varname), Start(start), End(end), Step(step), Body(body) {}
-  virtual Value *Codegen();
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes).
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args)
-    : Name(name), Args(args) {}
-  
-  Function *Codegen();
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-  Function *Codegen();
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// ifexpr ::= 'if' expression 'then' expression 'else' expression
-static ExprAST *ParseIfExpr() {
-  getNextToken();  // eat the if.
-  
-  // condition.
-  ExprAST *Cond = ParseExpression();
-  if (!Cond) return 0;
-  
-  if (CurTok != tok_then)
-    return Error("expected then");
-  getNextToken();  // eat the then
-  
-  ExprAST *Then = ParseExpression();
-  if (Then == 0) return 0;
-  
-  if (CurTok != tok_else)
-    return Error("expected else");
-  
-  getNextToken();
-  
-  ExprAST *Else = ParseExpression();
-  if (!Else) return 0;
-  
-  return new IfExprAST(Cond, Then, Else);
-}
-
-/// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
-static ExprAST *ParseForExpr() {
-  getNextToken();  // eat the for.
-
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after for");
-  
-  std::string IdName = IdentifierStr;
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '=')
-    return Error("expected '=' after for");
-  getNextToken();  // eat '='.
-  
-  
-  ExprAST *Start = ParseExpression();
-  if (Start == 0) return 0;
-  if (CurTok != ',')
-    return Error("expected ',' after for start value");
-  getNextToken();
-  
-  ExprAST *End = ParseExpression();
-  if (End == 0) return 0;
-  
-  // The step value is optional.
-  ExprAST *Step = 0;
-  if (CurTok == ',') {
-    getNextToken();
-    Step = ParseExpression();
-    if (Step == 0) return 0;
-  }
-  
-  if (CurTok != tok_in)
-    return Error("expected 'in' after for");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-
-  return new ForExprAST(IdName, Start, End, Step, Body);
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-///   ::= ifexpr
-///   ::= forexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  case tok_if:         return ParseIfExpr();
-  case tok_for:        return ParseForExpr();
-  }
-}
-
-/// binoprhs
-///   ::= ('+' primary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the primary expression after the binary operator.
-    ExprAST *RHS = ParsePrimary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= primary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParsePrimary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-static PrototypeAST *ParsePrototype() {
-  if (CurTok != tok_identifier)
-    return ErrorP("Expected function name in prototype");
-
-  std::string FnName = IdentifierStr;
-  getNextToken();
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  return new PrototypeAST(FnName, ArgNames);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Code Generation
-//===----------------------------------------------------------------------===//
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, Value*> NamedValues;
-static FunctionPassManager *TheFPM;
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  return V ? V : ErrorV("Unknown variable name");
-}
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: return ErrorV("invalid binary operator");
-  }
-}
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-Value *IfExprAST::Codegen() {
-  Value *CondV = Cond->Codegen();
-  if (CondV == 0) return 0;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  CondV = Builder.CreateFCmpONE(CondV, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                "ifcond");
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
-  // end of the function.
-  BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else");
-  BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont");
-  
-  Builder.CreateCondBr(CondV, ThenBB, ElseBB);
-  
-  // Emit then value.
-  Builder.SetInsertPoint(ThenBB);
-  
-  Value *ThenV = Then->Codegen();
-  if (ThenV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
-  ThenBB = Builder.GetInsertBlock();
-  
-  // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
-  Builder.SetInsertPoint(ElseBB);
-  
-  Value *ElseV = Else->Codegen();
-  if (ElseV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
-  ElseBB = Builder.GetInsertBlock();
-  
-  // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
-  Builder.SetInsertPoint(MergeBB);
-  PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2,
-                                  "iftmp");
-  
-  PN->addIncoming(ThenV, ThenBB);
-  PN->addIncoming(ElseV, ElseBB);
-  return PN;
-}
-
-Value *ForExprAST::Codegen() {
-  // Output this as:
-  //   ...
-  //   start = startexpr
-  //   goto loop
-  // loop: 
-  //   variable = phi [start, loopheader], [nextvariable, loopend]
-  //   ...
-  //   bodyexpr
-  //   ...
-  // loopend:
-  //   step = stepexpr
-  //   nextvariable = variable + step
-  //   endcond = endexpr
-  //   br endcond, loop, endloop
-  // outloop:
-  
-  // Emit the start code first, without 'variable' in scope.
-  Value *StartVal = Start->Codegen();
-  if (StartVal == 0) return 0;
-  
-  // Make the new basic block for the loop header, inserting after current
-  // block.
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  BasicBlock *PreheaderBB = Builder.GetInsertBlock();
-  BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction);
-  
-  // Insert an explicit fall through from the current block to the LoopBB.
-  Builder.CreateBr(LoopBB);
-
-  // Start insertion in LoopBB.
-  Builder.SetInsertPoint(LoopBB);
-  
-  // Start the PHI node with an entry for Start.
-  PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, VarName.c_str());
-  Variable->addIncoming(StartVal, PreheaderBB);
-  
-  // Within the loop, the variable is defined equal to the PHI node.  If it
-  // shadows an existing variable, we have to restore it, so save it now.
-  Value *OldVal = NamedValues[VarName];
-  NamedValues[VarName] = Variable;
-  
-  // Emit the body of the loop.  This, like any other expr, can change the
-  // current BB.  Note that we ignore the value computed by the body, but don't
-  // allow an error.
-  if (Body->Codegen() == 0)
-    return 0;
-  
-  // Emit the step value.
-  Value *StepVal;
-  if (Step) {
-    StepVal = Step->Codegen();
-    if (StepVal == 0) return 0;
-  } else {
-    // If not specified, use 1.0.
-    StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0));
-  }
-  
-  Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
-
-  // Compute the end condition.
-  Value *EndCond = End->Codegen();
-  if (EndCond == 0) return EndCond;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  EndCond = Builder.CreateFCmpONE(EndCond, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                  "loopcond");
-  
-  // Create the "after loop" block and insert it.
-  BasicBlock *LoopEndBB = Builder.GetInsertBlock();
-  BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction);
-  
-  // Insert the conditional branch into the end of LoopEndBB.
-  Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-  
-  // Any new code will be inserted in AfterBB.
-  Builder.SetInsertPoint(AfterBB);
-  
-  // Add a new entry to the PHI node for the backedge.
-  Variable->addIncoming(NextVar, LoopEndBB);
-  
-  // Restore the unshadowed variable.
-  if (OldVal)
-    NamedValues[VarName] = OldVal;
-  else
-    NamedValues.erase(VarName);
-
-  
-  // for expr always returns 0.0.
-  return Constant::getNullValue(Type::getDoubleTy(getGlobalContext()));
-}
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-  
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-  
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-    
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-  
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx) {
-    AI->setName(Args[Idx]);
-    
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = AI;
-  }
-  
-  return F;
-}
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    // Optimize the function.
-    TheFPM->run(*TheFunction);
-    
-    return TheFunction;
-  }
-  
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing and JIT Driver
-//===----------------------------------------------------------------------===//
-
-static ExecutionEngine *TheExecutionEngine;
-
-static void HandleDefinition() {
-  if (FunctionAST *F = ParseDefinition()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read function definition:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (PrototypeAST *P = ParseExtern()) {
-    if (Function *F = P->Codegen()) {
-      fprintf(stderr, "Read extern: ");
-      F->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      // JIT the function, returning a function pointer.
-      void *FPtr = TheExecutionEngine->getPointerToFunction(LF);
-      
-      // Cast it to the right type (takes no arguments, returns a double) so we
-      // can call it as a native function.
-      double (*FP)() = (double (*)())(intptr_t)FPtr;
-      fprintf(stderr, "Evaluated to %f\n", FP());
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// "Library" functions that can be "extern'd" from user code.
-//===----------------------------------------------------------------------===//
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  InitializeNativeTarget();
-  LLVMContext &Context = getGlobalContext();
-
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Make the module, which holds all the code.
-  TheModule = new Module("my cool jit", Context);
-
-  // Create the JIT.  This takes ownership of the module.
-  std::string ErrStr;
-  TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create();
-  if (!TheExecutionEngine) {
-    fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str());
-    exit(1);
-  }
-
-  FunctionPassManager OurFPM(TheModule);
-
-  // Set up the optimizer pipeline.  Start with registering info about how the
-  // target lays out data structures.
-  OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-  // Provide basic AliasAnalysis support for GVN.
-  OurFPM.add(createBasicAliasAnalysisPass());
-  // Do simple "peephole" optimizations and bit-twiddling optzns.
-  OurFPM.add(createInstructionCombiningPass());
-  // Reassociate expressions.
-  OurFPM.add(createReassociatePass());
-  // Eliminate Common SubExpressions.
-  OurFPM.add(createGVNPass());
-  // Simplify the control flow graph (deleting unreachable blocks, etc).
-  OurFPM.add(createCFGSimplificationPass());
-
-  OurFPM.doInitialization();
-
-  // Set the global so the code gen can use this.
-  TheFPM = &OurFPM;
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  TheFPM = 0;
-
-  // Print out all of the generated code.
-  TheModule->dump();
-
-  return 0;
-}
-
-
- -Next: Extending the language: user-defined operators -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl6.html b/cpp/llvm/docs/tutorial/LangImpl6.html deleted file mode 100644 index 6fb9bc6c..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl6.html +++ /dev/null @@ -1,1829 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: User-defined Operators - - - - - - - -

Kaleidoscope: Extending the Language: User-defined Operators

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 6 Introduction

- - -
- -

Welcome to Chapter 6 of the "Implementing a language -with LLVM" tutorial. At this point in our tutorial, we now have a fully -functional language that is fairly minimal, but also useful. There -is still one big problem with it, however. Our language doesn't have many -useful operators (like division, logical negation, or even any comparisons -besides less-than).

- -

This chapter of the tutorial takes a wild digression into adding user-defined -operators to the simple and beautiful Kaleidoscope language. This digression now gives -us a simple and ugly language in some ways, but also a powerful one at the same time. -One of the great things about creating your own language is that you get to -decide what is good or bad. In this tutorial we'll assume that it is okay to -use this as a way to show some interesting parsing techniques.

- -

At the end of this tutorial, we'll run through an example Kaleidoscope -application that renders the Mandelbrot set. This gives -an example of what you can build with Kaleidoscope and its feature set.

- -
- - -

User-defined Operators: the Idea

- - -
- -

-The "operator overloading" that we will add to Kaleidoscope is more general than -languages like C++. In C++, you are only allowed to redefine existing -operators: you can't programatically change the grammar, introduce new -operators, change precedence levels, etc. In this chapter, we will add this -capability to Kaleidoscope, which will let the user round out the set of -operators that are supported.

- -

The point of going into user-defined operators in a tutorial like this is to -show the power and flexibility of using a hand-written parser. Thus far, the parser -we have been implementing uses recursive descent for most parts of the grammar and -operator precedence parsing for the expressions. See Chapter 2 for details. Without using operator -precedence parsing, it would be very difficult to allow the programmer to -introduce new operators into the grammar: the grammar is dynamically extensible -as the JIT runs.

- -

The two specific features we'll add are programmable unary operators (right -now, Kaleidoscope has no unary operators at all) as well as binary operators. -An example of this is:

- -
-
-# Logical unary not.
-def unary!(v)
-  if v then
-    0
-  else
-    1;
-
-# Define > with the same precedence as <.
-def binary> 10 (LHS RHS)
-  RHS < LHS;
-
-# Binary "logical or", (note that it does not "short circuit")
-def binary| 5 (LHS RHS)
-  if LHS then
-    1
-  else if RHS then
-    1
-  else
-    0;
-
-# Define = with slightly lower precedence than relationals.
-def binary= 9 (LHS RHS)
-  !(LHS < RHS | LHS > RHS);
-
-
- -

Many languages aspire to being able to implement their standard runtime -library in the language itself. In Kaleidoscope, we can implement significant -parts of the language in the library!

- -

We will break down implementation of these features into two parts: -implementing support for user-defined binary operators and adding unary -operators.

- -
- - -

User-defined Binary Operators

- - -
- -

Adding support for user-defined binary operators is pretty simple with our -current framework. We'll first add support for the unary/binary keywords:

- -
-
-enum Token {
-  ...
-  // operators
-  tok_binary = -11, tok_unary = -12
-};
-...
-static int gettok() {
-...
-    if (IdentifierStr == "for") return tok_for;
-    if (IdentifierStr == "in") return tok_in;
-    if (IdentifierStr == "binary") return tok_binary;
-    if (IdentifierStr == "unary") return tok_unary;
-    return tok_identifier;
-
-
- -

This just adds lexer support for the unary and binary keywords, like we -did in previous chapters. One nice thing -about our current AST, is that we represent binary operators with full generalisation -by using their ASCII code as the opcode. For our extended operators, we'll use this -same representation, so we don't need any new AST or parser support.

- -

On the other hand, we have to be able to represent the definitions of these -new operators, in the "def binary| 5" part of the function definition. In our -grammar so far, the "name" for the function definition is parsed as the -"prototype" production and into the PrototypeAST AST node. To -represent our new user-defined operators as prototypes, we have to extend -the PrototypeAST AST node like this:

- -
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its argument names as well as if it is an operator.
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-  bool isOperator;
-  unsigned Precedence;  // Precedence if a binary op.
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args,
-               bool isoperator = false, unsigned prec = 0)
-  : Name(name), Args(args), isOperator(isoperator), Precedence(prec) {}
-  
-  bool isUnaryOp() const { return isOperator && Args.size() == 1; }
-  bool isBinaryOp() const { return isOperator && Args.size() == 2; }
-  
-  char getOperatorName() const {
-    assert(isUnaryOp() || isBinaryOp());
-    return Name[Name.size()-1];
-  }
-  
-  unsigned getBinaryPrecedence() const { return Precedence; }
-  
-  Function *Codegen();
-};
-
-
- -

Basically, in addition to knowing a name for the prototype, we now keep track -of whether it was an operator, and if it was, what precedence level the operator -is at. The precedence is only used for binary operators (as you'll see below, -it just doesn't apply for unary operators). Now that we have a way to represent -the prototype for a user-defined operator, we need to parse it:

- -
-
-/// prototype
-///   ::= id '(' id* ')'
-///   ::= binary LETTER number? (id, id)
-static PrototypeAST *ParsePrototype() {
-  std::string FnName;
-  
-  unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.
-  unsigned BinaryPrecedence = 30;
-  
-  switch (CurTok) {
-  default:
-    return ErrorP("Expected function name in prototype");
-  case tok_identifier:
-    FnName = IdentifierStr;
-    Kind = 0;
-    getNextToken();
-    break;
-  case tok_binary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected binary operator");
-    FnName = "binary";
-    FnName += (char)CurTok;
-    Kind = 2;
-    getNextToken();
-    
-    // Read the precedence if present.
-    if (CurTok == tok_number) {
-      if (NumVal < 1 || NumVal > 100)
-        return ErrorP("Invalid precedecnce: must be 1..100");
-      BinaryPrecedence = (unsigned)NumVal;
-      getNextToken();
-    }
-    break;
-  }
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  // Verify right number of names for operator.
-  if (Kind && ArgNames.size() != Kind)
-    return ErrorP("Invalid number of operands for operator");
-  
-  return new PrototypeAST(FnName, ArgNames, Kind != 0, BinaryPrecedence);
-}
-
-
- -

This is all fairly straightforward parsing code, and we have already seen -a lot of similar code in the past. One interesting part about the code above is -the couple lines that set up FnName for binary operators. This builds names -like "binary@" for a newly defined "@" operator. This then takes advantage of the -fact that symbol names in the LLVM symbol table are allowed to have any character in -them, including embedded nul characters.

- -

The next interesting thing to add, is codegen support for these binary operators. -Given our current structure, this is a simple addition of a default case for our -existing binary operator node:

- -
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: break;
-  }
-  
-  // If it wasn't a builtin binary operator, it must be a user defined one. Emit
-  // a call to it.
-  Function *F = TheModule->getFunction(std::string("binary")+Op);
-  assert(F && "binary operator not found!");
-  
-  Value *Ops[2] = { L, R };
-  return Builder.CreateCall(F, Ops, "binop");
-}
-
-
-
- -

As you can see above, the new code is actually really simple. It just does -a lookup for the appropriate operator in the symbol table and generates a -function call to it. Since user-defined operators are just built as normal -functions (because the "prototype" boils down to a function with the right -name) everything falls into place.

- -

The final piece of code we are missing, is a bit of top-level magic:

- -
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // If this is an operator, install it.
-  if (Proto->isBinaryOp())
-    BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-    ...
-
-
- -

Basically, before codegening a function, if it is a user-defined operator, we -register it in the precedence table. This allows the binary operator parsing -logic we already have in place to handle it. Since we are working on a fully-general operator precedence parser, this is all we need to do to "extend the grammar".

- -

Now we have useful user-defined binary operators. This builds a lot -on the previous framework we built for other operators. Adding unary operators -is a bit more challenging, because we don't have any framework for it yet - lets -see what it takes.

- -
- - -

User-defined Unary Operators

- - -
- -

Since we don't currently support unary operators in the Kaleidoscope -language, we'll need to add everything to support them. Above, we added simple -support for the 'unary' keyword to the lexer. In addition to that, we need an -AST node:

- -
-
-/// UnaryExprAST - Expression class for a unary operator.
-class UnaryExprAST : public ExprAST {
-  char Opcode;
-  ExprAST *Operand;
-public:
-  UnaryExprAST(char opcode, ExprAST *operand) 
-    : Opcode(opcode), Operand(operand) {}
-  virtual Value *Codegen();
-};
-
-
- -

This AST node is very simple and obvious by now. It directly mirrors the -binary operator AST node, except that it only has one child. With this, we -need to add the parsing logic. Parsing a unary operator is pretty simple: we'll -add a new function to do it:

- -
-
-/// unary
-///   ::= primary
-///   ::= '!' unary
-static ExprAST *ParseUnary() {
-  // If the current token is not an operator, it must be a primary expr.
-  if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
-    return ParsePrimary();
-  
-  // If this is a unary operator, read it.
-  int Opc = CurTok;
-  getNextToken();
-  if (ExprAST *Operand = ParseUnary())
-    return new UnaryExprAST(Opc, Operand);
-  return 0;
-}
-
-
- -

The grammar we add is pretty straightforward here. If we see a unary -operator when parsing a primary operator, we eat the operator as a prefix and -parse the remaining piece as another unary operator. This allows us to handle -multiple unary operators (e.g. "!!x"). Note that unary operators can't have -ambiguous parses like binary operators can, so there is no need for precedence -information.

- -

The problem with this function, is that we need to call ParseUnary from somewhere. -To do this, we change previous callers of ParsePrimary to call ParseUnary -instead:

- -
-
-/// binoprhs
-///   ::= ('+' unary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  ...
-    // Parse the unary expression after the binary operator.
-    ExprAST *RHS = ParseUnary();
-    if (!RHS) return 0;
-  ...
-}
-/// expression
-///   ::= unary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParseUnary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-
- -

With these two simple changes, we are now able to parse unary operators and build the -AST for them. Next up, we need to add parser support for prototypes, to parse -the unary operator prototype. We extend the binary operator code above -with:

- -
-
-/// prototype
-///   ::= id '(' id* ')'
-///   ::= binary LETTER number? (id, id)
-///   ::= unary LETTER (id)
-static PrototypeAST *ParsePrototype() {
-  std::string FnName;
-  
-  unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.
-  unsigned BinaryPrecedence = 30;
-  
-  switch (CurTok) {
-  default:
-    return ErrorP("Expected function name in prototype");
-  case tok_identifier:
-    FnName = IdentifierStr;
-    Kind = 0;
-    getNextToken();
-    break;
-  case tok_unary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected unary operator");
-    FnName = "unary";
-    FnName += (char)CurTok;
-    Kind = 1;
-    getNextToken();
-    break;
-  case tok_binary:
-    ...
-
-
- -

As with binary operators, we name unary operators with a name that includes -the operator character. This assists us at code generation time. Speaking of, -the final piece we need to add is codegen support for unary operators. It looks -like this:

- -
-
-Value *UnaryExprAST::Codegen() {
-  Value *OperandV = Operand->Codegen();
-  if (OperandV == 0) return 0;
-  
-  Function *F = TheModule->getFunction(std::string("unary")+Opcode);
-  if (F == 0)
-    return ErrorV("Unknown unary operator");
-  
-  return Builder.CreateCall(F, OperandV, "unop");
-}
-
-
- -

This code is similar to, but simpler than, the code for binary operators. It -is simpler primarily because it doesn't need to handle any predefined operators. -

- -
- - -

Kicking the Tires

- - -
- -

It is somewhat hard to believe, but with a few simple extensions we've -covered in the last chapters, we have grown a real-ish language. With this, we -can do a lot of interesting things, including I/O, math, and a bunch of other -things. For example, we can now add a nice sequencing operator (printd is -defined to print out the specified value and a newline):

- -
-
-ready> extern printd(x);
-Read extern:
-declare double @printd(double)
-
-ready> def binary : 1 (x y) 0;  # Low-precedence operator that ignores operands.
-..
-ready> printd(123) : printd(456) : printd(789);
-123.000000
-456.000000
-789.000000
-Evaluated to 0.000000
-
-
- -

We can also define a bunch of other "primitive" operations, such as:

- -
-
-# Logical unary not.
-def unary!(v)
-  if v then
-    0
-  else
-    1;
-    
-# Unary negate.
-def unary-(v)
-  0-v;
-
-# Define > with the same precedence as <.
-def binary> 10 (LHS RHS)
-  RHS < LHS;
-
-# Binary logical or, which does not short circuit. 
-def binary| 5 (LHS RHS)
-  if LHS then
-    1
-  else if RHS then
-    1
-  else
-    0;
-
-# Binary logical and, which does not short circuit. 
-def binary& 6 (LHS RHS)
-  if !LHS then
-    0
-  else
-    !!RHS;
-
-# Define = with slightly lower precedence than relationals.
-def binary = 9 (LHS RHS)
-  !(LHS < RHS | LHS > RHS);
-
-# Define ':' for sequencing: as a low-precedence operator that ignores operands
-# and just returns the RHS.
-def binary : 1 (x y) y;
-
-
- - -

Given the previous if/then/else support, we can also define interesting -functions for I/O. For example, the following prints out a character whose -"density" reflects the value passed in: the lower the value, the denser the -character:

- -
-
-ready>
-
-extern putchard(char)
-def printdensity(d)
-  if d > 8 then
-    putchard(32)  # ' '
-  else if d > 4 then
-    putchard(46)  # '.'
-  else if d > 2 then
-    putchard(43)  # '+'
-  else
-    putchard(42); # '*'
-...
-ready> printdensity(1): printdensity(2): printdensity(3):
-       printdensity(4): printdensity(5): printdensity(9):
-       putchard(10);
-**++.
-Evaluated to 0.000000
-
-
- -

Based on these simple primitive operations, we can start to define more -interesting things. For example, here's a little function that solves for the -number of iterations it takes a function in the complex plane to -converge:

- -
-
-# Determine whether the specific location diverges.
-# Solve for z = z^2 + c in the complex plane.
-def mandleconverger(real imag iters creal cimag)
-  if iters > 255 | (real*real + imag*imag > 4) then
-    iters
-  else
-    mandleconverger(real*real - imag*imag + creal,
-                    2*real*imag + cimag,
-                    iters+1, creal, cimag);
-
-# Return the number of iterations required for the iteration to escape
-def mandleconverge(real imag)
-  mandleconverger(real, imag, 0, real, imag);
-
-
- -

This "z = z2 + c" function is a beautiful little -creature that is the basis for computation of -the Mandelbrot Set. -Our mandelconverge function returns the number of iterations that it -takes for a complex orbit to escape, saturating to 255. This is not a very -useful function by itself, but if you plot its value over a two-dimensional -plane, you can see the Mandelbrot set. Given that we are limited to using -putchard here, our amazing graphical output is limited, but we can whip together -something using the density plotter above:

- -
-
-# Compute and plot the mandlebrot set with the specified 2 dimensional range
-# info.
-def mandelhelp(xmin xmax xstep   ymin ymax ystep)
-  for y = ymin, y < ymax, ystep in (
-    (for x = xmin, x < xmax, xstep in
-       printdensity(mandleconverge(x,y)))
-    : putchard(10)
-  )
- 
-# mandel - This is a convenient helper function for ploting the mandelbrot set
-# from the specified position with the specified Magnification.
-def mandel(realstart imagstart realmag imagmag) 
-  mandelhelp(realstart, realstart+realmag*78, realmag,
-             imagstart, imagstart+imagmag*40, imagmag);
-
-
- -

Given this, we can try plotting out the mandlebrot set! Lets try it out:

- -
-
-ready> mandel(-2.3, -1.3, 0.05, 0.07);
-*******************************+++++++++++*************************************
-*************************+++++++++++++++++++++++*******************************
-**********************+++++++++++++++++++++++++++++****************************
-*******************+++++++++++++++++++++.. ...++++++++*************************
-*****************++++++++++++++++++++++.... ...+++++++++***********************
-***************+++++++++++++++++++++++.....   ...+++++++++*********************
-**************+++++++++++++++++++++++....     ....+++++++++********************
-*************++++++++++++++++++++++......      .....++++++++*******************
-************+++++++++++++++++++++.......       .......+++++++******************
-***********+++++++++++++++++++....                ... .+++++++*****************
-**********+++++++++++++++++.......                     .+++++++****************
-*********++++++++++++++...........                    ...+++++++***************
-********++++++++++++............                      ...++++++++**************
-********++++++++++... ..........                        .++++++++**************
-*******+++++++++.....                                   .+++++++++*************
-*******++++++++......                                  ..+++++++++*************
-*******++++++.......                                   ..+++++++++*************
-*******+++++......                                     ..+++++++++*************
-*******.... ....                                      ...+++++++++*************
-*******.... .                                         ...+++++++++*************
-*******+++++......                                    ...+++++++++*************
-*******++++++.......                                   ..+++++++++*************
-*******++++++++......                                   .+++++++++*************
-*******+++++++++.....                                  ..+++++++++*************
-********++++++++++... ..........                        .++++++++**************
-********++++++++++++............                      ...++++++++**************
-*********++++++++++++++..........                     ...+++++++***************
-**********++++++++++++++++........                     .+++++++****************
-**********++++++++++++++++++++....                ... ..+++++++****************
-***********++++++++++++++++++++++.......       .......++++++++*****************
-************+++++++++++++++++++++++......      ......++++++++******************
-**************+++++++++++++++++++++++....      ....++++++++********************
-***************+++++++++++++++++++++++.....   ...+++++++++*********************
-*****************++++++++++++++++++++++....  ...++++++++***********************
-*******************+++++++++++++++++++++......++++++++*************************
-*********************++++++++++++++++++++++.++++++++***************************
-*************************+++++++++++++++++++++++*******************************
-******************************+++++++++++++************************************
-*******************************************************************************
-*******************************************************************************
-*******************************************************************************
-Evaluated to 0.000000
-ready> mandel(-2, -1, 0.02, 0.04);
-**************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
-***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-*********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
-*******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
-*****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
-***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
-**************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
-************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
-***********++++++++++++++++++++++++++++++++++++++++++++++++++........        . 
-**********++++++++++++++++++++++++++++++++++++++++++++++.............          
-********+++++++++++++++++++++++++++++++++++++++++++..................          
-*******+++++++++++++++++++++++++++++++++++++++.......................          
-******+++++++++++++++++++++++++++++++++++...........................           
-*****++++++++++++++++++++++++++++++++............................              
-*****++++++++++++++++++++++++++++...............................               
-****++++++++++++++++++++++++++......   .........................               
-***++++++++++++++++++++++++.........     ......    ...........                 
-***++++++++++++++++++++++............                                          
-**+++++++++++++++++++++..............                                          
-**+++++++++++++++++++................                                          
-*++++++++++++++++++.................                                           
-*++++++++++++++++............ ...                                              
-*++++++++++++++..............                                                  
-*+++....++++................                                                   
-*..........  ...........                                                       
-*                                                                              
-*..........  ...........                                                       
-*+++....++++................                                                   
-*++++++++++++++..............                                                  
-*++++++++++++++++............ ...                                              
-*++++++++++++++++++.................                                           
-**+++++++++++++++++++................                                          
-**+++++++++++++++++++++..............                                          
-***++++++++++++++++++++++............                                          
-***++++++++++++++++++++++++.........     ......    ...........                 
-****++++++++++++++++++++++++++......   .........................               
-*****++++++++++++++++++++++++++++...............................               
-*****++++++++++++++++++++++++++++++++............................              
-******+++++++++++++++++++++++++++++++++++...........................           
-*******+++++++++++++++++++++++++++++++++++++++.......................          
-********+++++++++++++++++++++++++++++++++++++++++++..................          
-Evaluated to 0.000000
-ready> mandel(-0.9, -1.4, 0.02, 0.03);
-*******************************************************************************
-*******************************************************************************
-*******************************************************************************
-**********+++++++++++++++++++++************************************************
-*+++++++++++++++++++++++++++++++++++++++***************************************
-+++++++++++++++++++++++++++++++++++++++++++++**********************************
-++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
-++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
-+++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
-+++++++++++++++++++++++++++++++....   ......+++++++++++++++++++****************
-+++++++++++++++++++++++++++++.......  ........+++++++++++++++++++**************
-++++++++++++++++++++++++++++........   ........++++++++++++++++++++************
-+++++++++++++++++++++++++++.........     ..  ...+++++++++++++++++++++**********
-++++++++++++++++++++++++++...........        ....++++++++++++++++++++++********
-++++++++++++++++++++++++.............       .......++++++++++++++++++++++******
-+++++++++++++++++++++++.............        ........+++++++++++++++++++++++****
-++++++++++++++++++++++...........           ..........++++++++++++++++++++++***
-++++++++++++++++++++...........                .........++++++++++++++++++++++*
-++++++++++++++++++............                  ...........++++++++++++++++++++
-++++++++++++++++...............                 .............++++++++++++++++++
-++++++++++++++.................                 ...............++++++++++++++++
-++++++++++++..................                  .................++++++++++++++
-+++++++++..................                      .................+++++++++++++
-++++++........        .                               .........  ..++++++++++++
-++............                                         ......    ....++++++++++
-..............                                                    ...++++++++++
-..............                                                    ....+++++++++
-..............                                                    .....++++++++
-.............                                                    ......++++++++
-...........                                                     .......++++++++
-.........                                                       ........+++++++
-.........                                                       ........+++++++
-.........                                                           ....+++++++
-........                                                             ...+++++++
-.......                                                              ...+++++++
-                                                                    ....+++++++
-                                                                   .....+++++++
-                                                                    ....+++++++
-                                                                    ....+++++++
-                                                                    ....+++++++
-Evaluated to 0.000000
-ready> ^D
-
-
- -

At this point, you may be starting to realize that Kaleidoscope is a real -and powerful language. It may not be self-similar :), but it can be used to -plot things that are!

- -

With this, we conclude the "adding user-defined operators" chapter of the -tutorial. We have successfully augmented our language, adding the ability to extend the -language in the library, and we have shown how this can be used to build a simple but -interesting end-user application in Kaleidoscope. At this point, Kaleidoscope -can build a variety of applications that are functional and can call functions -with side-effects, but it can't actually define and mutate a variable itself. -

- -

Strikingly, variable mutation is an important feature of some -languages, and it is not at all obvious how to add -support for mutable variables without having to add an "SSA construction" -phase to your front-end. In the next chapter, we will describe how you can -add variable mutation without building SSA in your front-end.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -if/then/else and for expressions.. To build this example, use: -

- -
-
-# Compile
-clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy
-# Run
-./toy
-
-
- -

On some platforms, you will need to specify -rdynamic or -Wl,--export-dynamic -when linking. This ensures that symbols defined in the main executable are -exported to the dynamic linker and so are available for symbol resolution at -run time. This is not needed if you compile your support code into a shared -library, although doing that will cause problems on Windows.

- -

Here is the code:

- -
-
-#include "llvm/DerivedTypes.h"
-#include "llvm/ExecutionEngine/ExecutionEngine.h"
-#include "llvm/ExecutionEngine/JIT.h"
-#include "llvm/LLVMContext.h"
-#include "llvm/Module.h"
-#include "llvm/PassManager.h"
-#include "llvm/Analysis/Verifier.h"
-#include "llvm/Analysis/Passes.h"
-#include "llvm/Target/TargetData.h"
-#include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/IRBuilder.h"
-#include "llvm/Support/TargetSelect.h"
-#include <cstdio>
-#include <string>
-#include <map>
-#include <vector>
-using namespace llvm;
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5,
-  
-  // control
-  tok_if = -6, tok_then = -7, tok_else = -8,
-  tok_for = -9, tok_in = -10,
-  
-  // operators
-  tok_binary = -11, tok_unary = -12
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    if (IdentifierStr == "if") return tok_if;
-    if (IdentifierStr == "then") return tok_then;
-    if (IdentifierStr == "else") return tok_else;
-    if (IdentifierStr == "for") return tok_for;
-    if (IdentifierStr == "in") return tok_in;
-    if (IdentifierStr == "binary") return tok_binary;
-    if (IdentifierStr == "unary") return tok_unary;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-  virtual Value *Codegen();
-};
-
-/// UnaryExprAST - Expression class for a unary operator.
-class UnaryExprAST : public ExprAST {
-  char Opcode;
-  ExprAST *Operand;
-public:
-  UnaryExprAST(char opcode, ExprAST *operand) 
-    : Opcode(opcode), Operand(operand) {}
-  virtual Value *Codegen();
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-  virtual Value *Codegen();
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-  virtual Value *Codegen();
-};
-
-/// IfExprAST - Expression class for if/then/else.
-class IfExprAST : public ExprAST {
-  ExprAST *Cond, *Then, *Else;
-public:
-  IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else)
-  : Cond(cond), Then(then), Else(_else) {}
-  virtual Value *Codegen();
-};
-
-/// ForExprAST - Expression class for for/in.
-class ForExprAST : public ExprAST {
-  std::string VarName;
-  ExprAST *Start, *End, *Step, *Body;
-public:
-  ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end,
-             ExprAST *step, ExprAST *body)
-    : VarName(varname), Start(start), End(end), Step(step), Body(body) {}
-  virtual Value *Codegen();
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes), as well as if it is an operator.
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-  bool isOperator;
-  unsigned Precedence;  // Precedence if a binary op.
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args,
-               bool isoperator = false, unsigned prec = 0)
-  : Name(name), Args(args), isOperator(isoperator), Precedence(prec) {}
-  
-  bool isUnaryOp() const { return isOperator && Args.size() == 1; }
-  bool isBinaryOp() const { return isOperator && Args.size() == 2; }
-  
-  char getOperatorName() const {
-    assert(isUnaryOp() || isBinaryOp());
-    return Name[Name.size()-1];
-  }
-  
-  unsigned getBinaryPrecedence() const { return Precedence; }
-  
-  Function *Codegen();
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-  Function *Codegen();
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// ifexpr ::= 'if' expression 'then' expression 'else' expression
-static ExprAST *ParseIfExpr() {
-  getNextToken();  // eat the if.
-  
-  // condition.
-  ExprAST *Cond = ParseExpression();
-  if (!Cond) return 0;
-  
-  if (CurTok != tok_then)
-    return Error("expected then");
-  getNextToken();  // eat the then
-  
-  ExprAST *Then = ParseExpression();
-  if (Then == 0) return 0;
-  
-  if (CurTok != tok_else)
-    return Error("expected else");
-  
-  getNextToken();
-  
-  ExprAST *Else = ParseExpression();
-  if (!Else) return 0;
-  
-  return new IfExprAST(Cond, Then, Else);
-}
-
-/// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
-static ExprAST *ParseForExpr() {
-  getNextToken();  // eat the for.
-
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after for");
-  
-  std::string IdName = IdentifierStr;
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '=')
-    return Error("expected '=' after for");
-  getNextToken();  // eat '='.
-  
-  
-  ExprAST *Start = ParseExpression();
-  if (Start == 0) return 0;
-  if (CurTok != ',')
-    return Error("expected ',' after for start value");
-  getNextToken();
-  
-  ExprAST *End = ParseExpression();
-  if (End == 0) return 0;
-  
-  // The step value is optional.
-  ExprAST *Step = 0;
-  if (CurTok == ',') {
-    getNextToken();
-    Step = ParseExpression();
-    if (Step == 0) return 0;
-  }
-  
-  if (CurTok != tok_in)
-    return Error("expected 'in' after for");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-
-  return new ForExprAST(IdName, Start, End, Step, Body);
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-///   ::= ifexpr
-///   ::= forexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  case tok_if:         return ParseIfExpr();
-  case tok_for:        return ParseForExpr();
-  }
-}
-
-/// unary
-///   ::= primary
-///   ::= '!' unary
-static ExprAST *ParseUnary() {
-  // If the current token is not an operator, it must be a primary expr.
-  if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
-    return ParsePrimary();
-  
-  // If this is a unary operator, read it.
-  int Opc = CurTok;
-  getNextToken();
-  if (ExprAST *Operand = ParseUnary())
-    return new UnaryExprAST(Opc, Operand);
-  return 0;
-}
-
-/// binoprhs
-///   ::= ('+' unary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the unary expression after the binary operator.
-    ExprAST *RHS = ParseUnary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= unary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParseUnary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-///   ::= binary LETTER number? (id, id)
-///   ::= unary LETTER (id)
-static PrototypeAST *ParsePrototype() {
-  std::string FnName;
-  
-  unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
-  unsigned BinaryPrecedence = 30;
-  
-  switch (CurTok) {
-  default:
-    return ErrorP("Expected function name in prototype");
-  case tok_identifier:
-    FnName = IdentifierStr;
-    Kind = 0;
-    getNextToken();
-    break;
-  case tok_unary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected unary operator");
-    FnName = "unary";
-    FnName += (char)CurTok;
-    Kind = 1;
-    getNextToken();
-    break;
-  case tok_binary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected binary operator");
-    FnName = "binary";
-    FnName += (char)CurTok;
-    Kind = 2;
-    getNextToken();
-    
-    // Read the precedence if present.
-    if (CurTok == tok_number) {
-      if (NumVal < 1 || NumVal > 100)
-        return ErrorP("Invalid precedecnce: must be 1..100");
-      BinaryPrecedence = (unsigned)NumVal;
-      getNextToken();
-    }
-    break;
-  }
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  // Verify right number of names for operator.
-  if (Kind && ArgNames.size() != Kind)
-    return ErrorP("Invalid number of operands for operator");
-  
-  return new PrototypeAST(FnName, ArgNames, Kind != 0, BinaryPrecedence);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Code Generation
-//===----------------------------------------------------------------------===//
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, Value*> NamedValues;
-static FunctionPassManager *TheFPM;
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  return V ? V : ErrorV("Unknown variable name");
-}
-
-Value *UnaryExprAST::Codegen() {
-  Value *OperandV = Operand->Codegen();
-  if (OperandV == 0) return 0;
-  
-  Function *F = TheModule->getFunction(std::string("unary")+Opcode);
-  if (F == 0)
-    return ErrorV("Unknown unary operator");
-  
-  return Builder.CreateCall(F, OperandV, "unop");
-}
-
-Value *BinaryExprAST::Codegen() {
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: break;
-  }
-  
-  // If it wasn't a builtin binary operator, it must be a user defined one. Emit
-  // a call to it.
-  Function *F = TheModule->getFunction(std::string("binary")+Op);
-  assert(F && "binary operator not found!");
-  
-  Value *Ops[2] = { L, R };
-  return Builder.CreateCall(F, Ops, "binop");
-}
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-Value *IfExprAST::Codegen() {
-  Value *CondV = Cond->Codegen();
-  if (CondV == 0) return 0;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  CondV = Builder.CreateFCmpONE(CondV, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                "ifcond");
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
-  // end of the function.
-  BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else");
-  BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont");
-  
-  Builder.CreateCondBr(CondV, ThenBB, ElseBB);
-  
-  // Emit then value.
-  Builder.SetInsertPoint(ThenBB);
-  
-  Value *ThenV = Then->Codegen();
-  if (ThenV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
-  ThenBB = Builder.GetInsertBlock();
-  
-  // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
-  Builder.SetInsertPoint(ElseBB);
-  
-  Value *ElseV = Else->Codegen();
-  if (ElseV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
-  ElseBB = Builder.GetInsertBlock();
-  
-  // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
-  Builder.SetInsertPoint(MergeBB);
-  PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2,
-                                  "iftmp");
-  
-  PN->addIncoming(ThenV, ThenBB);
-  PN->addIncoming(ElseV, ElseBB);
-  return PN;
-}
-
-Value *ForExprAST::Codegen() {
-  // Output this as:
-  //   ...
-  //   start = startexpr
-  //   goto loop
-  // loop: 
-  //   variable = phi [start, loopheader], [nextvariable, loopend]
-  //   ...
-  //   bodyexpr
-  //   ...
-  // loopend:
-  //   step = stepexpr
-  //   nextvariable = variable + step
-  //   endcond = endexpr
-  //   br endcond, loop, endloop
-  // outloop:
-  
-  // Emit the start code first, without 'variable' in scope.
-  Value *StartVal = Start->Codegen();
-  if (StartVal == 0) return 0;
-  
-  // Make the new basic block for the loop header, inserting after current
-  // block.
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  BasicBlock *PreheaderBB = Builder.GetInsertBlock();
-  BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction);
-  
-  // Insert an explicit fall through from the current block to the LoopBB.
-  Builder.CreateBr(LoopBB);
-
-  // Start insertion in LoopBB.
-  Builder.SetInsertPoint(LoopBB);
-  
-  // Start the PHI node with an entry for Start.
-  PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, VarName.c_str());
-  Variable->addIncoming(StartVal, PreheaderBB);
-  
-  // Within the loop, the variable is defined equal to the PHI node.  If it
-  // shadows an existing variable, we have to restore it, so save it now.
-  Value *OldVal = NamedValues[VarName];
-  NamedValues[VarName] = Variable;
-  
-  // Emit the body of the loop.  This, like any other expr, can change the
-  // current BB.  Note that we ignore the value computed by the body, but don't
-  // allow an error.
-  if (Body->Codegen() == 0)
-    return 0;
-  
-  // Emit the step value.
-  Value *StepVal;
-  if (Step) {
-    StepVal = Step->Codegen();
-    if (StepVal == 0) return 0;
-  } else {
-    // If not specified, use 1.0.
-    StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0));
-  }
-  
-  Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
-
-  // Compute the end condition.
-  Value *EndCond = End->Codegen();
-  if (EndCond == 0) return EndCond;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  EndCond = Builder.CreateFCmpONE(EndCond, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                  "loopcond");
-  
-  // Create the "after loop" block and insert it.
-  BasicBlock *LoopEndBB = Builder.GetInsertBlock();
-  BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction);
-  
-  // Insert the conditional branch into the end of LoopEndBB.
-  Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-  
-  // Any new code will be inserted in AfterBB.
-  Builder.SetInsertPoint(AfterBB);
-  
-  // Add a new entry to the PHI node for the backedge.
-  Variable->addIncoming(NextVar, LoopEndBB);
-  
-  // Restore the unshadowed variable.
-  if (OldVal)
-    NamedValues[VarName] = OldVal;
-  else
-    NamedValues.erase(VarName);
-
-  
-  // for expr always returns 0.0.
-  return Constant::getNullValue(Type::getDoubleTy(getGlobalContext()));
-}
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-  
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-  
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-    
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-  
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx) {
-    AI->setName(Args[Idx]);
-    
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = AI;
-  }
-  
-  return F;
-}
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // If this is an operator, install it.
-  if (Proto->isBinaryOp())
-    BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    // Optimize the function.
-    TheFPM->run(*TheFunction);
-    
-    return TheFunction;
-  }
-  
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-
-  if (Proto->isBinaryOp())
-    BinopPrecedence.erase(Proto->getOperatorName());
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing and JIT Driver
-//===----------------------------------------------------------------------===//
-
-static ExecutionEngine *TheExecutionEngine;
-
-static void HandleDefinition() {
-  if (FunctionAST *F = ParseDefinition()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read function definition:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (PrototypeAST *P = ParseExtern()) {
-    if (Function *F = P->Codegen()) {
-      fprintf(stderr, "Read extern: ");
-      F->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      // JIT the function, returning a function pointer.
-      void *FPtr = TheExecutionEngine->getPointerToFunction(LF);
-      
-      // Cast it to the right type (takes no arguments, returns a double) so we
-      // can call it as a native function.
-      double (*FP)() = (double (*)())(intptr_t)FPtr;
-      fprintf(stderr, "Evaluated to %f\n", FP());
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// "Library" functions that can be "extern'd" from user code.
-//===----------------------------------------------------------------------===//
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-/// printd - printf that takes a double prints it as "%f\n", returning 0.
-extern "C" 
-double printd(double X) {
-  printf("%f\n", X);
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  InitializeNativeTarget();
-  LLVMContext &Context = getGlobalContext();
-
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Make the module, which holds all the code.
-  TheModule = new Module("my cool jit", Context);
-
-  // Create the JIT.  This takes ownership of the module.
-  std::string ErrStr;
-  TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create();
-  if (!TheExecutionEngine) {
-    fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str());
-    exit(1);
-  }
-
-  FunctionPassManager OurFPM(TheModule);
-
-  // Set up the optimizer pipeline.  Start with registering info about how the
-  // target lays out data structures.
-  OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-  // Provide basic AliasAnalysis support for GVN.
-  OurFPM.add(createBasicAliasAnalysisPass());
-  // Do simple "peephole" optimizations and bit-twiddling optzns.
-  OurFPM.add(createInstructionCombiningPass());
-  // Reassociate expressions.
-  OurFPM.add(createReassociatePass());
-  // Eliminate Common SubExpressions.
-  OurFPM.add(createGVNPass());
-  // Simplify the control flow graph (deleting unreachable blocks, etc).
-  OurFPM.add(createCFGSimplificationPass());
-
-  OurFPM.doInitialization();
-
-  // Set the global so the code gen can use this.
-  TheFPM = &OurFPM;
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  TheFPM = 0;
-
-  // Print out all of the generated code.
-  TheModule->dump();
-
-  return 0;
-}
-
-
- -Next: Extending the language: mutable variables / SSA construction -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl7.html b/cpp/llvm/docs/tutorial/LangImpl7.html deleted file mode 100644 index 4b04824c..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl7.html +++ /dev/null @@ -1,2164 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: Mutable Variables / SSA - construction - - - - - - - -

Kaleidoscope: Extending the Language: Mutable Variables

- - - -
-

Written by Chris Lattner

-
- - -

Chapter 7 Introduction

- - -
- -

Welcome to Chapter 7 of the "Implementing a language -with LLVM" tutorial. In chapters 1 through 6, we've built a very -respectable, albeit simple, functional -programming language. In our journey, we learned some parsing techniques, -how to build and represent an AST, how to build LLVM IR, and how to optimize -the resultant code as well as JIT compile it.

- -

While Kaleidoscope is interesting as a functional language, the fact that it -is functional makes it "too easy" to generate LLVM IR for it. In particular, a -functional language makes it very easy to build LLVM IR directly in SSA form. -Since LLVM requires that the input code be in SSA form, this is a very nice -property and it is often unclear to newcomers how to generate code for an -imperative language with mutable variables.

- -

The short (and happy) summary of this chapter is that there is no need for -your front-end to build SSA form: LLVM provides highly tuned and well tested -support for this, though the way it works is a bit unexpected for some.

- -
- - -

Why is this a hard problem?

- - -
- -

-To understand why mutable variables cause complexities in SSA construction, -consider this extremely simple C example: -

- -
-
-int G, H;
-int test(_Bool Condition) {
-  int X;
-  if (Condition)
-    X = G;
-  else
-    X = H;
-  return X;
-}
-
-
- -

In this case, we have the variable "X", whose value depends on the path -executed in the program. Because there are two different possible values for X -before the return instruction, a PHI node is inserted to merge the two values. -The LLVM IR that we want for this example looks like this:

- -
-
-@G = weak global i32 0   ; type of @G is i32*
-@H = weak global i32 0   ; type of @H is i32*
-
-define i32 @test(i1 %Condition) {
-entry:
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-  br label %cond_next
-
-cond_next:
-  %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
-  ret i32 %X.2
-}
-
-
- -

In this example, the loads from the G and H global variables are explicit in -the LLVM IR, and they live in the then/else branches of the if statement -(cond_true/cond_false). In order to merge the incoming values, the X.2 phi node -in the cond_next block selects the right value to use based on where control -flow is coming from: if control flow comes from the cond_false block, X.2 gets -the value of X.1. Alternatively, if control flow comes from cond_true, it gets -the value of X.0. The intent of this chapter is not to explain the details of -SSA form. For more information, see one of the many online -references.

- -

The question for this article is "who places the phi nodes when lowering -assignments to mutable variables?". The issue here is that LLVM -requires that its IR be in SSA form: there is no "non-ssa" mode for it. -However, SSA construction requires non-trivial algorithms and data structures, -so it is inconvenient and wasteful for every front-end to have to reproduce this -logic.

- -
- - -

Memory in LLVM

- - -
- -

The 'trick' here is that while LLVM does require all register values to be -in SSA form, it does not require (or permit) memory objects to be in SSA form. -In the example above, note that the loads from G and H are direct accesses to -G and H: they are not renamed or versioned. This differs from some other -compiler systems, which do try to version memory objects. In LLVM, instead of -encoding dataflow analysis of memory into the LLVM IR, it is handled with Analysis Passes which are computed on -demand.

- -

-With this in mind, the high-level idea is that we want to make a stack variable -(which lives in memory, because it is on the stack) for each mutable object in -a function. To take advantage of this trick, we need to talk about how LLVM -represents stack variables. -

- -

In LLVM, all memory accesses are explicit with load/store instructions, and -it is carefully designed not to have (or need) an "address-of" operator. Notice -how the type of the @G/@H global variables is actually "i32*" even though the -variable is defined as "i32". What this means is that @G defines space -for an i32 in the global data area, but its name actually refers to the -address for that space. Stack variables work the same way, except that instead of -being declared with global variable definitions, they are declared with the -LLVM alloca instruction:

- -
-
-define i32 @example() {
-entry:
-  %X = alloca i32           ; type of %X is i32*.
-  ...
-  %tmp = load i32* %X       ; load the stack value %X from the stack.
-  %tmp2 = add i32 %tmp, 1   ; increment it
-  store i32 %tmp2, i32* %X  ; store it back
-  ...
-
-
- -

This code shows an example of how you can declare and manipulate a stack -variable in the LLVM IR. Stack memory allocated with the alloca instruction is -fully general: you can pass the address of the stack slot to functions, you can -store it in other variables, etc. In our example above, we could rewrite the -example to use the alloca technique to avoid using a PHI node:

- -
-
-@G = weak global i32 0   ; type of @G is i32*
-@H = weak global i32 0   ; type of @H is i32*
-
-define i32 @test(i1 %Condition) {
-entry:
-  %X = alloca i32           ; type of %X is i32*.
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-  store i32 %X.0, i32* %X   ; Update X
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-  store i32 %X.1, i32* %X   ; Update X
-  br label %cond_next
-
-cond_next:
-  %X.2 = load i32* %X       ; Read X
-  ret i32 %X.2
-}
-
-
- -

With this, we have discovered a way to handle arbitrary mutable variables -without the need to create Phi nodes at all:

- -
    -
  1. Each mutable variable becomes a stack allocation.
  2. -
  3. Each read of the variable becomes a load from the stack.
  4. -
  5. Each update of the variable becomes a store to the stack.
  6. -
  7. Taking the address of a variable just uses the stack address directly.
  8. -
- -

While this solution has solved our immediate problem, it introduced another -one: we have now apparently introduced a lot of stack traffic for very simple -and common operations, a major performance problem. Fortunately for us, the -LLVM optimizer has a highly-tuned optimization pass named "mem2reg" that handles -this case, promoting allocas like this into SSA registers, inserting Phi nodes -as appropriate. If you run this example through the pass, for example, you'll -get:

- -
-
-$ llvm-as < example.ll | opt -mem2reg | llvm-dis
-@G = weak global i32 0
-@H = weak global i32 0
-
-define i32 @test(i1 %Condition) {
-entry:
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-  br label %cond_next
-
-cond_next:
-  %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
-  ret i32 %X.01
-}
-
-
- -

The mem2reg pass implements the standard "iterated dominance frontier" -algorithm for constructing SSA form and has a number of optimizations that speed -up (very common) degenerate cases. The mem2reg optimization pass is the answer to dealing -with mutable variables, and we highly recommend that you depend on it. Note that -mem2reg only works on variables in certain circumstances:

- -
    -
  1. mem2reg is alloca-driven: it looks for allocas and if it can handle them, it -promotes them. It does not apply to global variables or heap allocations.
  2. - -
  3. mem2reg only looks for alloca instructions in the entry block of the -function. Being in the entry block guarantees that the alloca is only executed -once, which makes analysis simpler.
  4. - -
  5. mem2reg only promotes allocas whose uses are direct loads and stores. If -the address of the stack object is passed to a function, or if any funny pointer -arithmetic is involved, the alloca will not be promoted.
  6. - -
  7. mem2reg only works on allocas of first class -values (such as pointers, scalars and vectors), and only if the array size -of the allocation is 1 (or missing in the .ll file). mem2reg is not capable of -promoting structs or arrays to registers. Note that the "scalarrepl" pass is -more powerful and can promote structs, "unions", and arrays in many cases.
  8. - -
- -

-All of these properties are easy to satisfy for most imperative languages, and -we'll illustrate it below with Kaleidoscope. The final question you may be -asking is: should I bother with this nonsense for my front-end? Wouldn't it be -better if I just did SSA construction directly, avoiding use of the mem2reg -optimization pass? In short, we strongly recommend that you use this technique -for building SSA form, unless there is an extremely good reason not to. Using -this technique is:

- -
    -
  • Proven and well tested: llvm-gcc and clang both use this technique for local -mutable variables. As such, the most common clients of LLVM are using this to -handle a bulk of their variables. You can be sure that bugs are found fast and -fixed early.
  • - -
  • Extremely Fast: mem2reg has a number of special cases that make it fast in -common cases as well as fully general. For example, it has fast-paths for -variables that are only used in a single block, variables that only have one -assignment point, good heuristics to avoid insertion of unneeded phi nodes, etc. -
  • - -
  • Needed for debug info generation: -Debug information in LLVM relies on having the address of the variable -exposed so that debug info can be attached to it. This technique dovetails -very naturally with this style of debug info.
  • -
- -

If nothing else, this makes it much easier to get your front-end up and -running, and is very simple to implement. Lets extend Kaleidoscope with mutable -variables now! -

- -
- - -

Mutable Variables in Kaleidoscope

- - -
- -

Now that we know the sort of problem we want to tackle, lets see what this -looks like in the context of our little Kaleidoscope language. We're going to -add two features:

- -
    -
  1. The ability to mutate variables with the '=' operator.
  2. -
  3. The ability to define new variables.
  4. -
- -

While the first item is really what this is about, we only have variables -for incoming arguments as well as for induction variables, and redefining those only -goes so far :). Also, the ability to define new variables is a -useful thing regardless of whether you will be mutating them. Here's a -motivating example that shows how we could use these:

- -
-
-# Define ':' for sequencing: as a low-precedence operator that ignores operands
-# and just returns the RHS.
-def binary : 1 (x y) y;
-
-# Recursive fib, we could do this before.
-def fib(x)
-  if (x < 3) then
-    1
-  else
-    fib(x-1)+fib(x-2);
-
-# Iterative fib.
-def fibi(x)
-  var a = 1, b = 1, c in
-  (for i = 3, i < x in 
-     c = a + b :
-     a = b :
-     b = c) :
-  b;
-
-# Call it. 
-fibi(10);
-
-
- -

-In order to mutate variables, we have to change our existing variables to use -the "alloca trick". Once we have that, we'll add our new operator, then extend -Kaleidoscope to support new variable definitions. -

- -
- - -

Adjusting Existing Variables for Mutation

- - -
- -

-The symbol table in Kaleidoscope is managed at code generation time by the -'NamedValues' map. This map currently keeps track of the LLVM "Value*" -that holds the double value for the named variable. In order to support -mutation, we need to change this slightly, so that it NamedValues holds -the memory location of the variable in question. Note that this -change is a refactoring: it changes the structure of the code, but does not -(by itself) change the behavior of the compiler. All of these changes are -isolated in the Kaleidoscope code generator.

- -

-At this point in Kaleidoscope's development, it only supports variables for two -things: incoming arguments to functions and the induction variable of 'for' -loops. For consistency, we'll allow mutation of these variables in addition to -other user-defined variables. This means that these will both need memory -locations. -

- -

To start our transformation of Kaleidoscope, we'll change the NamedValues -map so that it maps to AllocaInst* instead of Value*. Once we do this, the C++ -compiler will tell us what parts of the code we need to update:

- -
-
-static std::map<std::string, AllocaInst*> NamedValues;
-
-
- -

Also, since we will need to create these alloca's, we'll use a helper -function that ensures that the allocas are created in the entry block of the -function:

- -
-
-/// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
-/// the function.  This is used for mutable variables etc.
-static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
-                                          const std::string &VarName) {
-  IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
-                 TheFunction->getEntryBlock().begin());
-  return TmpB.CreateAlloca(Type::getDoubleTy(getGlobalContext()), 0,
-                           VarName.c_str());
-}
-
-
- -

This funny looking code creates an IRBuilder object that is pointing at -the first instruction (.begin()) of the entry block. It then creates an alloca -with the expected name and returns it. Because all values in Kaleidoscope are -doubles, there is no need to pass in a type to use.

- -

With this in place, the first functionality change we want to make is to -variable references. In our new scheme, variables live on the stack, so code -generating a reference to them actually needs to produce a load from the stack -slot:

- -
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  if (V == 0) return ErrorV("Unknown variable name");
-
-  // Load the value.
-  return Builder.CreateLoad(V, Name.c_str());
-}
-
-
- -

As you can see, this is pretty straightforward. Now we need to update the -things that define the variables to set up the alloca. We'll start with -ForExprAST::Codegen (see the full code listing for -the unabridged code):

- -
-
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-  // Create an alloca for the variable in the entry block.
-  AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-  
-    // Emit the start code first, without 'variable' in scope.
-  Value *StartVal = Start->Codegen();
-  if (StartVal == 0) return 0;
-  
-  // Store the value into the alloca.
-  Builder.CreateStore(StartVal, Alloca);
-  ...
-
-  // Compute the end condition.
-  Value *EndCond = End->Codegen();
-  if (EndCond == 0) return EndCond;
-  
-  // Reload, increment, and restore the alloca.  This handles the case where
-  // the body of the loop mutates the variable.
-  Value *CurVar = Builder.CreateLoad(Alloca);
-  Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
-  Builder.CreateStore(NextVar, Alloca);
-  ...
-
-
- -

This code is virtually identical to the code before we allowed mutable variables. The -big difference is that we no longer have to construct a PHI node, and we use -load/store to access the variable as needed.

- -

To support mutable argument variables, we need to also make allocas for them. -The code for this is also pretty simple:

- -
-
-/// CreateArgumentAllocas - Create an alloca for each argument and register the
-/// argument in the symbol table so that references to it will succeed.
-void PrototypeAST::CreateArgumentAllocas(Function *F) {
-  Function::arg_iterator AI = F->arg_begin();
-  for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {
-    // Create an alloca for this variable.
-    AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);
-
-    // Store the initial value into the alloca.
-    Builder.CreateStore(AI, Alloca);
-
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = Alloca;
-  }
-}
-
-
- -

For each argument, we make an alloca, store the input value to the function -into the alloca, and register the alloca as the memory location for the -argument. This method gets invoked by FunctionAST::Codegen right after -it sets up the entry block for the function.

- -

The final missing piece is adding the mem2reg pass, which allows us to get -good codegen once again:

- -
-
-    // Set up the optimizer pipeline.  Start with registering info about how the
-    // target lays out data structures.
-    OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-    // Promote allocas to registers.
-    OurFPM.add(createPromoteMemoryToRegisterPass());
-    // Do simple "peephole" optimizations and bit-twiddling optzns.
-    OurFPM.add(createInstructionCombiningPass());
-    // Reassociate expressions.
-    OurFPM.add(createReassociatePass());
-
-
- -

It is interesting to see what the code looks like before and after the -mem2reg optimization runs. For example, this is the before/after code for our -recursive fib function. Before the optimization:

- -
-
-define double @fib(double %x) {
-entry:
-  %x1 = alloca double
-  store double %x, double* %x1
-  %x2 = load double* %x1
-  %cmptmp = fcmp ult double %x2, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:		; preds = %entry
-  br label %ifcont
-
-else:		; preds = %entry
-  %x3 = load double* %x1
-  %subtmp = fsub double %x3, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %x4 = load double* %x1
-  %subtmp5 = fsub double %x4, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  br label %ifcont
-
-ifcont:		; preds = %else, %then
-  %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
-  ret double %iftmp
-}
-
-
- -

Here there is only one variable (x, the input argument) but you can still -see the extremely simple-minded code generation strategy we are using. In the -entry block, an alloca is created, and the initial input value is stored into -it. Each reference to the variable does a reload from the stack. Also, note -that we didn't modify the if/then/else expression, so it still inserts a PHI -node. While we could make an alloca for it, it is actually easier to create a -PHI node for it, so we still just make the PHI.

- -

Here is the code after the mem2reg pass runs:

- -
-
-define double @fib(double %x) {
-entry:
-  %cmptmp = fcmp ult double %x, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:
-  br label %ifcont
-
-else:
-  %subtmp = fsub double %x, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %subtmp5 = fsub double %x, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  br label %ifcont
-
-ifcont:		; preds = %else, %then
-  %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
-  ret double %iftmp
-}
-
-
- -

This is a trivial case for mem2reg, since there are no redefinitions of the -variable. The point of showing this is to calm your tension about inserting -such blatent inefficiencies :).

- -

After the rest of the optimizers run, we get:

- -
-
-define double @fib(double %x) {
-entry:
-  %cmptmp = fcmp ult double %x, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp ueq double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %else, label %ifcont
-
-else:
-  %subtmp = fsub double %x, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %subtmp5 = fsub double %x, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  ret double %addtmp
-
-ifcont:
-  ret double 1.000000e+00
-}
-
-
- -

Here we see that the simplifycfg pass decided to clone the return instruction -into the end of the 'else' block. This allowed it to eliminate some branches -and the PHI node.

- -

Now that all symbol table references are updated to use stack variables, -we'll add the assignment operator.

- -
- - -

New Assignment Operator

- - -
- -

With our current framework, adding a new assignment operator is really -simple. We will parse it just like any other binary operator, but handle it -internally (instead of allowing the user to define it). The first step is to -set a precedence:

- -
-
- int main() {
-   // Install standard binary operators.
-   // 1 is lowest precedence.
-   BinopPrecedence['='] = 2;
-   BinopPrecedence['<'] = 10;
-   BinopPrecedence['+'] = 20;
-   BinopPrecedence['-'] = 20;
-
-
- -

Now that the parser knows the precedence of the binary operator, it takes -care of all the parsing and AST generation. We just need to implement codegen -for the assignment operator. This looks like:

- -
-
-Value *BinaryExprAST::Codegen() {
-  // Special case '=' because we don't want to emit the LHS as an expression.
-  if (Op == '=') {
-    // Assignment requires the LHS to be an identifier.
-    VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS);
-    if (!LHSE)
-      return ErrorV("destination of '=' must be a variable");
-
-
- -

Unlike the rest of the binary operators, our assignment operator doesn't -follow the "emit LHS, emit RHS, do computation" model. As such, it is handled -as a special case before the other binary operators are handled. The other -strange thing is that it requires the LHS to be a variable. It is invalid to -have "(x+1) = expr" - only things like "x = expr" are allowed. -

- -
-
-    // Codegen the RHS.
-    Value *Val = RHS->Codegen();
-    if (Val == 0) return 0;
-
-    // Look up the name.
-    Value *Variable = NamedValues[LHSE->getName()];
-    if (Variable == 0) return ErrorV("Unknown variable name");
-
-    Builder.CreateStore(Val, Variable);
-    return Val;
-  }
-  ...  
-
-
- -

Once we have the variable, codegen'ing the assignment is straightforward: -we emit the RHS of the assignment, create a store, and return the computed -value. Returning a value allows for chained assignments like "X = (Y = Z)".

- -

Now that we have an assignment operator, we can mutate loop variables and -arguments. For example, we can now run code like this:

- -
-
-# Function to print a double.
-extern printd(x);
-
-# Define ':' for sequencing: as a low-precedence operator that ignores operands
-# and just returns the RHS.
-def binary : 1 (x y) y;
-
-def test(x)
-  printd(x) :
-  x = 4 :
-  printd(x);
-
-test(123);
-
-
- -

When run, this example prints "123" and then "4", showing that we did -actually mutate the value! Okay, we have now officially implemented our goal: -getting this to work requires SSA construction in the general case. However, -to be really useful, we want the ability to define our own local variables, lets -add this next! -

- -
- - -

User-defined Local Variables

- - -
- -

Adding var/in is just like any other other extensions we made to -Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. -The first step for adding our new 'var/in' construct is to extend the lexer. -As before, this is pretty trivial, the code looks like this:

- -
-
-enum Token {
-  ...
-  // var definition
-  tok_var = -13
-...
-}
-...
-static int gettok() {
-...
-    if (IdentifierStr == "in") return tok_in;
-    if (IdentifierStr == "binary") return tok_binary;
-    if (IdentifierStr == "unary") return tok_unary;
-    if (IdentifierStr == "var") return tok_var;
-    return tok_identifier;
-...
-
-
- -

The next step is to define the AST node that we will construct. For var/in, -it looks like this:

- -
-
-/// VarExprAST - Expression class for var/in
-class VarExprAST : public ExprAST {
-  std::vector<std::pair<std::string, ExprAST*> > VarNames;
-  ExprAST *Body;
-public:
-  VarExprAST(const std::vector<std::pair<std::string, ExprAST*> > &varnames,
-             ExprAST *body)
-  : VarNames(varnames), Body(body) {}
-  
-  virtual Value *Codegen();
-};
-
-
- -

var/in allows a list of names to be defined all at once, and each name can -optionally have an initializer value. As such, we capture this information in -the VarNames vector. Also, var/in has a body, this body is allowed to access -the variables defined by the var/in.

- -

With this in place, we can define the parser pieces. The first thing we do is add -it as a primary expression:

- -
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-///   ::= ifexpr
-///   ::= forexpr
-///   ::= varexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  case tok_if:         return ParseIfExpr();
-  case tok_for:        return ParseForExpr();
-  case tok_var:        return ParseVarExpr();
-  }
-}
-
-
- -

Next we define ParseVarExpr:

- -
-
-/// varexpr ::= 'var' identifier ('=' expression)? 
-//                    (',' identifier ('=' expression)?)* 'in' expression
-static ExprAST *ParseVarExpr() {
-  getNextToken();  // eat the var.
-
-  std::vector<std::pair<std::string, ExprAST*> > VarNames;
-
-  // At least one variable name is required.
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after var");
-
-
- -

The first part of this code parses the list of identifier/expr pairs into the -local VarNames vector. - -

-
-  while (1) {
-    std::string Name = IdentifierStr;
-    getNextToken();  // eat identifier.
-
-    // Read the optional initializer.
-    ExprAST *Init = 0;
-    if (CurTok == '=') {
-      getNextToken(); // eat the '='.
-      
-      Init = ParseExpression();
-      if (Init == 0) return 0;
-    }
-    
-    VarNames.push_back(std::make_pair(Name, Init));
-    
-    // End of var list, exit loop.
-    if (CurTok != ',') break;
-    getNextToken(); // eat the ','.
-    
-    if (CurTok != tok_identifier)
-      return Error("expected identifier list after var");
-  }
-
-
- -

Once all the variables are parsed, we then parse the body and create the -AST node:

- -
-
-  // At this point, we have to have 'in'.
-  if (CurTok != tok_in)
-    return Error("expected 'in' keyword after 'var'");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-  
-  return new VarExprAST(VarNames, Body);
-}
-
-
- -

Now that we can parse and represent the code, we need to support emission of -LLVM IR for it. This code starts out with:

- -
-
-Value *VarExprAST::Codegen() {
-  std::vector<AllocaInst *> OldBindings;
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-  // Register all variables and emit their initializer.
-  for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
-    const std::string &VarName = VarNames[i].first;
-    ExprAST *Init = VarNames[i].second;
-
-
- -

Basically it loops over all the variables, installing them one at a time. -For each variable we put into the symbol table, we remember the previous value -that we replace in OldBindings.

- -
-
-    // Emit the initializer before adding the variable to scope, this prevents
-    // the initializer from referencing the variable itself, and permits stuff
-    // like this:
-    //  var a = 1 in
-    //    var a = a in ...   # refers to outer 'a'.
-    Value *InitVal;
-    if (Init) {
-      InitVal = Init->Codegen();
-      if (InitVal == 0) return 0;
-    } else { // If not specified, use 0.0.
-      InitVal = ConstantFP::get(getGlobalContext(), APFloat(0.0));
-    }
-    
-    AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-    Builder.CreateStore(InitVal, Alloca);
-
-    // Remember the old variable binding so that we can restore the binding when
-    // we unrecurse.
-    OldBindings.push_back(NamedValues[VarName]);
-    
-    // Remember this binding.
-    NamedValues[VarName] = Alloca;
-  }
-
-
- -

There are more comments here than code. The basic idea is that we emit the -initializer, create the alloca, then update the symbol table to point to it. -Once all the variables are installed in the symbol table, we evaluate the body -of the var/in expression:

- -
-
-  // Codegen the body, now that all vars are in scope.
-  Value *BodyVal = Body->Codegen();
-  if (BodyVal == 0) return 0;
-
-
- -

Finally, before returning, we restore the previous variable bindings:

- -
-
-  // Pop all our variables from scope.
-  for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
-    NamedValues[VarNames[i].first] = OldBindings[i];
-
-  // Return the body computation.
-  return BodyVal;
-}
-
-
- -

The end result of all of this is that we get properly scoped variable -definitions, and we even (trivially) allow mutation of them :).

- -

With this, we completed what we set out to do. Our nice iterative fib -example from the intro compiles and runs just fine. The mem2reg pass optimizes -all of our stack variables into SSA registers, inserting PHI nodes where needed, -and our front-end remains simple: no "iterated dominance frontier" computation -anywhere in sight.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with mutable -variables and var/in support. To build this example, use: -

- -
-
-# Compile
-clang++ -g toy.cpp `llvm-config --cppflags --ldflags --libs core jit native` -O3 -o toy
-# Run
-./toy
-
-
- -

Here is the code:

- -
-
-#include "llvm/DerivedTypes.h"
-#include "llvm/ExecutionEngine/ExecutionEngine.h"
-#include "llvm/ExecutionEngine/JIT.h"
-#include "llvm/LLVMContext.h"
-#include "llvm/Module.h"
-#include "llvm/PassManager.h"
-#include "llvm/Analysis/Verifier.h"
-#include "llvm/Analysis/Passes.h"
-#include "llvm/Target/TargetData.h"
-#include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/IRBuilder.h"
-#include "llvm/Support/TargetSelect.h"
-#include <cstdio>
-#include <string>
-#include <map>
-#include <vector>
-using namespace llvm;
-
-//===----------------------------------------------------------------------===//
-// Lexer
-//===----------------------------------------------------------------------===//
-
-// The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-// of these for known things.
-enum Token {
-  tok_eof = -1,
-
-  // commands
-  tok_def = -2, tok_extern = -3,
-
-  // primary
-  tok_identifier = -4, tok_number = -5,
-  
-  // control
-  tok_if = -6, tok_then = -7, tok_else = -8,
-  tok_for = -9, tok_in = -10,
-  
-  // operators
-  tok_binary = -11, tok_unary = -12,
-  
-  // var definition
-  tok_var = -13
-};
-
-static std::string IdentifierStr;  // Filled in if tok_identifier
-static double NumVal;              // Filled in if tok_number
-
-/// gettok - Return the next token from standard input.
-static int gettok() {
-  static int LastChar = ' ';
-
-  // Skip any whitespace.
-  while (isspace(LastChar))
-    LastChar = getchar();
-
-  if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-    IdentifierStr = LastChar;
-    while (isalnum((LastChar = getchar())))
-      IdentifierStr += LastChar;
-
-    if (IdentifierStr == "def") return tok_def;
-    if (IdentifierStr == "extern") return tok_extern;
-    if (IdentifierStr == "if") return tok_if;
-    if (IdentifierStr == "then") return tok_then;
-    if (IdentifierStr == "else") return tok_else;
-    if (IdentifierStr == "for") return tok_for;
-    if (IdentifierStr == "in") return tok_in;
-    if (IdentifierStr == "binary") return tok_binary;
-    if (IdentifierStr == "unary") return tok_unary;
-    if (IdentifierStr == "var") return tok_var;
-    return tok_identifier;
-  }
-
-  if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-    std::string NumStr;
-    do {
-      NumStr += LastChar;
-      LastChar = getchar();
-    } while (isdigit(LastChar) || LastChar == '.');
-
-    NumVal = strtod(NumStr.c_str(), 0);
-    return tok_number;
-  }
-
-  if (LastChar == '#') {
-    // Comment until end of line.
-    do LastChar = getchar();
-    while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-    
-    if (LastChar != EOF)
-      return gettok();
-  }
-  
-  // Check for end of file.  Don't eat the EOF.
-  if (LastChar == EOF)
-    return tok_eof;
-
-  // Otherwise, just return the character as its ascii value.
-  int ThisChar = LastChar;
-  LastChar = getchar();
-  return ThisChar;
-}
-
-//===----------------------------------------------------------------------===//
-// Abstract Syntax Tree (aka Parse Tree)
-//===----------------------------------------------------------------------===//
-
-/// ExprAST - Base class for all expression nodes.
-class ExprAST {
-public:
-  virtual ~ExprAST() {}
-  virtual Value *Codegen() = 0;
-};
-
-/// NumberExprAST - Expression class for numeric literals like "1.0".
-class NumberExprAST : public ExprAST {
-  double Val;
-public:
-  NumberExprAST(double val) : Val(val) {}
-  virtual Value *Codegen();
-};
-
-/// VariableExprAST - Expression class for referencing a variable, like "a".
-class VariableExprAST : public ExprAST {
-  std::string Name;
-public:
-  VariableExprAST(const std::string &name) : Name(name) {}
-  const std::string &getName() const { return Name; }
-  virtual Value *Codegen();
-};
-
-/// UnaryExprAST - Expression class for a unary operator.
-class UnaryExprAST : public ExprAST {
-  char Opcode;
-  ExprAST *Operand;
-public:
-  UnaryExprAST(char opcode, ExprAST *operand) 
-    : Opcode(opcode), Operand(operand) {}
-  virtual Value *Codegen();
-};
-
-/// BinaryExprAST - Expression class for a binary operator.
-class BinaryExprAST : public ExprAST {
-  char Op;
-  ExprAST *LHS, *RHS;
-public:
-  BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) 
-    : Op(op), LHS(lhs), RHS(rhs) {}
-  virtual Value *Codegen();
-};
-
-/// CallExprAST - Expression class for function calls.
-class CallExprAST : public ExprAST {
-  std::string Callee;
-  std::vector<ExprAST*> Args;
-public:
-  CallExprAST(const std::string &callee, std::vector<ExprAST*> &args)
-    : Callee(callee), Args(args) {}
-  virtual Value *Codegen();
-};
-
-/// IfExprAST - Expression class for if/then/else.
-class IfExprAST : public ExprAST {
-  ExprAST *Cond, *Then, *Else;
-public:
-  IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else)
-  : Cond(cond), Then(then), Else(_else) {}
-  virtual Value *Codegen();
-};
-
-/// ForExprAST - Expression class for for/in.
-class ForExprAST : public ExprAST {
-  std::string VarName;
-  ExprAST *Start, *End, *Step, *Body;
-public:
-  ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end,
-             ExprAST *step, ExprAST *body)
-    : VarName(varname), Start(start), End(end), Step(step), Body(body) {}
-  virtual Value *Codegen();
-};
-
-/// VarExprAST - Expression class for var/in
-class VarExprAST : public ExprAST {
-  std::vector<std::pair<std::string, ExprAST*> > VarNames;
-  ExprAST *Body;
-public:
-  VarExprAST(const std::vector<std::pair<std::string, ExprAST*> > &varnames,
-             ExprAST *body)
-  : VarNames(varnames), Body(body) {}
-  
-  virtual Value *Codegen();
-};
-
-/// PrototypeAST - This class represents the "prototype" for a function,
-/// which captures its name, and its argument names (thus implicitly the number
-/// of arguments the function takes), as well as if it is an operator.
-class PrototypeAST {
-  std::string Name;
-  std::vector<std::string> Args;
-  bool isOperator;
-  unsigned Precedence;  // Precedence if a binary op.
-public:
-  PrototypeAST(const std::string &name, const std::vector<std::string> &args,
-               bool isoperator = false, unsigned prec = 0)
-  : Name(name), Args(args), isOperator(isoperator), Precedence(prec) {}
-  
-  bool isUnaryOp() const { return isOperator && Args.size() == 1; }
-  bool isBinaryOp() const { return isOperator && Args.size() == 2; }
-  
-  char getOperatorName() const {
-    assert(isUnaryOp() || isBinaryOp());
-    return Name[Name.size()-1];
-  }
-  
-  unsigned getBinaryPrecedence() const { return Precedence; }
-  
-  Function *Codegen();
-  
-  void CreateArgumentAllocas(Function *F);
-};
-
-/// FunctionAST - This class represents a function definition itself.
-class FunctionAST {
-  PrototypeAST *Proto;
-  ExprAST *Body;
-public:
-  FunctionAST(PrototypeAST *proto, ExprAST *body)
-    : Proto(proto), Body(body) {}
-  
-  Function *Codegen();
-};
-
-//===----------------------------------------------------------------------===//
-// Parser
-//===----------------------------------------------------------------------===//
-
-/// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-/// token the parser is looking at.  getNextToken reads another token from the
-/// lexer and updates CurTok with its results.
-static int CurTok;
-static int getNextToken() {
-  return CurTok = gettok();
-}
-
-/// BinopPrecedence - This holds the precedence for each binary operator that is
-/// defined.
-static std::map<char, int> BinopPrecedence;
-
-/// GetTokPrecedence - Get the precedence of the pending binary operator token.
-static int GetTokPrecedence() {
-  if (!isascii(CurTok))
-    return -1;
-  
-  // Make sure it's a declared binop.
-  int TokPrec = BinopPrecedence[CurTok];
-  if (TokPrec <= 0) return -1;
-  return TokPrec;
-}
-
-/// Error* - These are little helper functions for error handling.
-ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;}
-PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; }
-FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; }
-
-static ExprAST *ParseExpression();
-
-/// identifierexpr
-///   ::= identifier
-///   ::= identifier '(' expression* ')'
-static ExprAST *ParseIdentifierExpr() {
-  std::string IdName = IdentifierStr;
-  
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '(') // Simple variable ref.
-    return new VariableExprAST(IdName);
-  
-  // Call.
-  getNextToken();  // eat (
-  std::vector<ExprAST*> Args;
-  if (CurTok != ')') {
-    while (1) {
-      ExprAST *Arg = ParseExpression();
-      if (!Arg) return 0;
-      Args.push_back(Arg);
-
-      if (CurTok == ')') break;
-
-      if (CurTok != ',')
-        return Error("Expected ')' or ',' in argument list");
-      getNextToken();
-    }
-  }
-
-  // Eat the ')'.
-  getNextToken();
-  
-  return new CallExprAST(IdName, Args);
-}
-
-/// numberexpr ::= number
-static ExprAST *ParseNumberExpr() {
-  ExprAST *Result = new NumberExprAST(NumVal);
-  getNextToken(); // consume the number
-  return Result;
-}
-
-/// parenexpr ::= '(' expression ')'
-static ExprAST *ParseParenExpr() {
-  getNextToken();  // eat (.
-  ExprAST *V = ParseExpression();
-  if (!V) return 0;
-  
-  if (CurTok != ')')
-    return Error("expected ')'");
-  getNextToken();  // eat ).
-  return V;
-}
-
-/// ifexpr ::= 'if' expression 'then' expression 'else' expression
-static ExprAST *ParseIfExpr() {
-  getNextToken();  // eat the if.
-  
-  // condition.
-  ExprAST *Cond = ParseExpression();
-  if (!Cond) return 0;
-  
-  if (CurTok != tok_then)
-    return Error("expected then");
-  getNextToken();  // eat the then
-  
-  ExprAST *Then = ParseExpression();
-  if (Then == 0) return 0;
-  
-  if (CurTok != tok_else)
-    return Error("expected else");
-  
-  getNextToken();
-  
-  ExprAST *Else = ParseExpression();
-  if (!Else) return 0;
-  
-  return new IfExprAST(Cond, Then, Else);
-}
-
-/// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
-static ExprAST *ParseForExpr() {
-  getNextToken();  // eat the for.
-
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after for");
-  
-  std::string IdName = IdentifierStr;
-  getNextToken();  // eat identifier.
-  
-  if (CurTok != '=')
-    return Error("expected '=' after for");
-  getNextToken();  // eat '='.
-  
-  
-  ExprAST *Start = ParseExpression();
-  if (Start == 0) return 0;
-  if (CurTok != ',')
-    return Error("expected ',' after for start value");
-  getNextToken();
-  
-  ExprAST *End = ParseExpression();
-  if (End == 0) return 0;
-  
-  // The step value is optional.
-  ExprAST *Step = 0;
-  if (CurTok == ',') {
-    getNextToken();
-    Step = ParseExpression();
-    if (Step == 0) return 0;
-  }
-  
-  if (CurTok != tok_in)
-    return Error("expected 'in' after for");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-
-  return new ForExprAST(IdName, Start, End, Step, Body);
-}
-
-/// varexpr ::= 'var' identifier ('=' expression)? 
-//                    (',' identifier ('=' expression)?)* 'in' expression
-static ExprAST *ParseVarExpr() {
-  getNextToken();  // eat the var.
-
-  std::vector<std::pair<std::string, ExprAST*> > VarNames;
-
-  // At least one variable name is required.
-  if (CurTok != tok_identifier)
-    return Error("expected identifier after var");
-  
-  while (1) {
-    std::string Name = IdentifierStr;
-    getNextToken();  // eat identifier.
-
-    // Read the optional initializer.
-    ExprAST *Init = 0;
-    if (CurTok == '=') {
-      getNextToken(); // eat the '='.
-      
-      Init = ParseExpression();
-      if (Init == 0) return 0;
-    }
-    
-    VarNames.push_back(std::make_pair(Name, Init));
-    
-    // End of var list, exit loop.
-    if (CurTok != ',') break;
-    getNextToken(); // eat the ','.
-    
-    if (CurTok != tok_identifier)
-      return Error("expected identifier list after var");
-  }
-  
-  // At this point, we have to have 'in'.
-  if (CurTok != tok_in)
-    return Error("expected 'in' keyword after 'var'");
-  getNextToken();  // eat 'in'.
-  
-  ExprAST *Body = ParseExpression();
-  if (Body == 0) return 0;
-  
-  return new VarExprAST(VarNames, Body);
-}
-
-/// primary
-///   ::= identifierexpr
-///   ::= numberexpr
-///   ::= parenexpr
-///   ::= ifexpr
-///   ::= forexpr
-///   ::= varexpr
-static ExprAST *ParsePrimary() {
-  switch (CurTok) {
-  default: return Error("unknown token when expecting an expression");
-  case tok_identifier: return ParseIdentifierExpr();
-  case tok_number:     return ParseNumberExpr();
-  case '(':            return ParseParenExpr();
-  case tok_if:         return ParseIfExpr();
-  case tok_for:        return ParseForExpr();
-  case tok_var:        return ParseVarExpr();
-  }
-}
-
-/// unary
-///   ::= primary
-///   ::= '!' unary
-static ExprAST *ParseUnary() {
-  // If the current token is not an operator, it must be a primary expr.
-  if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
-    return ParsePrimary();
-  
-  // If this is a unary operator, read it.
-  int Opc = CurTok;
-  getNextToken();
-  if (ExprAST *Operand = ParseUnary())
-    return new UnaryExprAST(Opc, Operand);
-  return 0;
-}
-
-/// binoprhs
-///   ::= ('+' unary)*
-static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) {
-  // If this is a binop, find its precedence.
-  while (1) {
-    int TokPrec = GetTokPrecedence();
-    
-    // If this is a binop that binds at least as tightly as the current binop,
-    // consume it, otherwise we are done.
-    if (TokPrec < ExprPrec)
-      return LHS;
-    
-    // Okay, we know this is a binop.
-    int BinOp = CurTok;
-    getNextToken();  // eat binop
-    
-    // Parse the unary expression after the binary operator.
-    ExprAST *RHS = ParseUnary();
-    if (!RHS) return 0;
-    
-    // If BinOp binds less tightly with RHS than the operator after RHS, let
-    // the pending operator take RHS as its LHS.
-    int NextPrec = GetTokPrecedence();
-    if (TokPrec < NextPrec) {
-      RHS = ParseBinOpRHS(TokPrec+1, RHS);
-      if (RHS == 0) return 0;
-    }
-    
-    // Merge LHS/RHS.
-    LHS = new BinaryExprAST(BinOp, LHS, RHS);
-  }
-}
-
-/// expression
-///   ::= unary binoprhs
-///
-static ExprAST *ParseExpression() {
-  ExprAST *LHS = ParseUnary();
-  if (!LHS) return 0;
-  
-  return ParseBinOpRHS(0, LHS);
-}
-
-/// prototype
-///   ::= id '(' id* ')'
-///   ::= binary LETTER number? (id, id)
-///   ::= unary LETTER (id)
-static PrototypeAST *ParsePrototype() {
-  std::string FnName;
-  
-  unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
-  unsigned BinaryPrecedence = 30;
-  
-  switch (CurTok) {
-  default:
-    return ErrorP("Expected function name in prototype");
-  case tok_identifier:
-    FnName = IdentifierStr;
-    Kind = 0;
-    getNextToken();
-    break;
-  case tok_unary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected unary operator");
-    FnName = "unary";
-    FnName += (char)CurTok;
-    Kind = 1;
-    getNextToken();
-    break;
-  case tok_binary:
-    getNextToken();
-    if (!isascii(CurTok))
-      return ErrorP("Expected binary operator");
-    FnName = "binary";
-    FnName += (char)CurTok;
-    Kind = 2;
-    getNextToken();
-    
-    // Read the precedence if present.
-    if (CurTok == tok_number) {
-      if (NumVal < 1 || NumVal > 100)
-        return ErrorP("Invalid precedecnce: must be 1..100");
-      BinaryPrecedence = (unsigned)NumVal;
-      getNextToken();
-    }
-    break;
-  }
-  
-  if (CurTok != '(')
-    return ErrorP("Expected '(' in prototype");
-  
-  std::vector<std::string> ArgNames;
-  while (getNextToken() == tok_identifier)
-    ArgNames.push_back(IdentifierStr);
-  if (CurTok != ')')
-    return ErrorP("Expected ')' in prototype");
-  
-  // success.
-  getNextToken();  // eat ')'.
-  
-  // Verify right number of names for operator.
-  if (Kind && ArgNames.size() != Kind)
-    return ErrorP("Invalid number of operands for operator");
-  
-  return new PrototypeAST(FnName, ArgNames, Kind != 0, BinaryPrecedence);
-}
-
-/// definition ::= 'def' prototype expression
-static FunctionAST *ParseDefinition() {
-  getNextToken();  // eat def.
-  PrototypeAST *Proto = ParsePrototype();
-  if (Proto == 0) return 0;
-
-  if (ExprAST *E = ParseExpression())
-    return new FunctionAST(Proto, E);
-  return 0;
-}
-
-/// toplevelexpr ::= expression
-static FunctionAST *ParseTopLevelExpr() {
-  if (ExprAST *E = ParseExpression()) {
-    // Make an anonymous proto.
-    PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>());
-    return new FunctionAST(Proto, E);
-  }
-  return 0;
-}
-
-/// external ::= 'extern' prototype
-static PrototypeAST *ParseExtern() {
-  getNextToken();  // eat extern.
-  return ParsePrototype();
-}
-
-//===----------------------------------------------------------------------===//
-// Code Generation
-//===----------------------------------------------------------------------===//
-
-static Module *TheModule;
-static IRBuilder<> Builder(getGlobalContext());
-static std::map<std::string, AllocaInst*> NamedValues;
-static FunctionPassManager *TheFPM;
-
-Value *ErrorV(const char *Str) { Error(Str); return 0; }
-
-/// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
-/// the function.  This is used for mutable variables etc.
-static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
-                                          const std::string &VarName) {
-  IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
-                 TheFunction->getEntryBlock().begin());
-  return TmpB.CreateAlloca(Type::getDoubleTy(getGlobalContext()), 0,
-                           VarName.c_str());
-}
-
-Value *NumberExprAST::Codegen() {
-  return ConstantFP::get(getGlobalContext(), APFloat(Val));
-}
-
-Value *VariableExprAST::Codegen() {
-  // Look this variable up in the function.
-  Value *V = NamedValues[Name];
-  if (V == 0) return ErrorV("Unknown variable name");
-
-  // Load the value.
-  return Builder.CreateLoad(V, Name.c_str());
-}
-
-Value *UnaryExprAST::Codegen() {
-  Value *OperandV = Operand->Codegen();
-  if (OperandV == 0) return 0;
-  
-  Function *F = TheModule->getFunction(std::string("unary")+Opcode);
-  if (F == 0)
-    return ErrorV("Unknown unary operator");
-  
-  return Builder.CreateCall(F, OperandV, "unop");
-}
-
-Value *BinaryExprAST::Codegen() {
-  // Special case '=' because we don't want to emit the LHS as an expression.
-  if (Op == '=') {
-    // Assignment requires the LHS to be an identifier.
-    VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS);
-    if (!LHSE)
-      return ErrorV("destination of '=' must be a variable");
-    // Codegen the RHS.
-    Value *Val = RHS->Codegen();
-    if (Val == 0) return 0;
-
-    // Look up the name.
-    Value *Variable = NamedValues[LHSE->getName()];
-    if (Variable == 0) return ErrorV("Unknown variable name");
-
-    Builder.CreateStore(Val, Variable);
-    return Val;
-  }
-  
-  Value *L = LHS->Codegen();
-  Value *R = RHS->Codegen();
-  if (L == 0 || R == 0) return 0;
-  
-  switch (Op) {
-  case '+': return Builder.CreateFAdd(L, R, "addtmp");
-  case '-': return Builder.CreateFSub(L, R, "subtmp");
-  case '*': return Builder.CreateFMul(L, R, "multmp");
-  case '<':
-    L = Builder.CreateFCmpULT(L, R, "cmptmp");
-    // Convert bool 0/1 to double 0.0 or 1.0
-    return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()),
-                                "booltmp");
-  default: break;
-  }
-  
-  // If it wasn't a builtin binary operator, it must be a user defined one. Emit
-  // a call to it.
-  Function *F = TheModule->getFunction(std::string("binary")+Op);
-  assert(F && "binary operator not found!");
-  
-  Value *Ops[2] = { L, R };
-  return Builder.CreateCall(F, Ops, "binop");
-}
-
-Value *CallExprAST::Codegen() {
-  // Look up the name in the global module table.
-  Function *CalleeF = TheModule->getFunction(Callee);
-  if (CalleeF == 0)
-    return ErrorV("Unknown function referenced");
-  
-  // If argument mismatch error.
-  if (CalleeF->arg_size() != Args.size())
-    return ErrorV("Incorrect # arguments passed");
-
-  std::vector<Value*> ArgsV;
-  for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-    ArgsV.push_back(Args[i]->Codegen());
-    if (ArgsV.back() == 0) return 0;
-  }
-  
-  return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-}
-
-Value *IfExprAST::Codegen() {
-  Value *CondV = Cond->Codegen();
-  if (CondV == 0) return 0;
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  CondV = Builder.CreateFCmpONE(CondV, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                "ifcond");
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-  
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
-  // end of the function.
-  BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else");
-  BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont");
-  
-  Builder.CreateCondBr(CondV, ThenBB, ElseBB);
-  
-  // Emit then value.
-  Builder.SetInsertPoint(ThenBB);
-  
-  Value *ThenV = Then->Codegen();
-  if (ThenV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
-  ThenBB = Builder.GetInsertBlock();
-  
-  // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
-  Builder.SetInsertPoint(ElseBB);
-  
-  Value *ElseV = Else->Codegen();
-  if (ElseV == 0) return 0;
-  
-  Builder.CreateBr(MergeBB);
-  // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
-  ElseBB = Builder.GetInsertBlock();
-  
-  // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
-  Builder.SetInsertPoint(MergeBB);
-  PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2,
-                                  "iftmp");
-  
-  PN->addIncoming(ThenV, ThenBB);
-  PN->addIncoming(ElseV, ElseBB);
-  return PN;
-}
-
-Value *ForExprAST::Codegen() {
-  // Output this as:
-  //   var = alloca double
-  //   ...
-  //   start = startexpr
-  //   store start -> var
-  //   goto loop
-  // loop: 
-  //   ...
-  //   bodyexpr
-  //   ...
-  // loopend:
-  //   step = stepexpr
-  //   endcond = endexpr
-  //
-  //   curvar = load var
-  //   nextvar = curvar + step
-  //   store nextvar -> var
-  //   br endcond, loop, endloop
-  // outloop:
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-  // Create an alloca for the variable in the entry block.
-  AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-  
-  // Emit the start code first, without 'variable' in scope.
-  Value *StartVal = Start->Codegen();
-  if (StartVal == 0) return 0;
-  
-  // Store the value into the alloca.
-  Builder.CreateStore(StartVal, Alloca);
-  
-  // Make the new basic block for the loop header, inserting after current
-  // block.
-  BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction);
-  
-  // Insert an explicit fall through from the current block to the LoopBB.
-  Builder.CreateBr(LoopBB);
-
-  // Start insertion in LoopBB.
-  Builder.SetInsertPoint(LoopBB);
-  
-  // Within the loop, the variable is defined equal to the PHI node.  If it
-  // shadows an existing variable, we have to restore it, so save it now.
-  AllocaInst *OldVal = NamedValues[VarName];
-  NamedValues[VarName] = Alloca;
-  
-  // Emit the body of the loop.  This, like any other expr, can change the
-  // current BB.  Note that we ignore the value computed by the body, but don't
-  // allow an error.
-  if (Body->Codegen() == 0)
-    return 0;
-  
-  // Emit the step value.
-  Value *StepVal;
-  if (Step) {
-    StepVal = Step->Codegen();
-    if (StepVal == 0) return 0;
-  } else {
-    // If not specified, use 1.0.
-    StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0));
-  }
-  
-  // Compute the end condition.
-  Value *EndCond = End->Codegen();
-  if (EndCond == 0) return EndCond;
-  
-  // Reload, increment, and restore the alloca.  This handles the case where
-  // the body of the loop mutates the variable.
-  Value *CurVar = Builder.CreateLoad(Alloca, VarName.c_str());
-  Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
-  Builder.CreateStore(NextVar, Alloca);
-  
-  // Convert condition to a bool by comparing equal to 0.0.
-  EndCond = Builder.CreateFCmpONE(EndCond, 
-                              ConstantFP::get(getGlobalContext(), APFloat(0.0)),
-                                  "loopcond");
-  
-  // Create the "after loop" block and insert it.
-  BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction);
-  
-  // Insert the conditional branch into the end of LoopEndBB.
-  Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-  
-  // Any new code will be inserted in AfterBB.
-  Builder.SetInsertPoint(AfterBB);
-  
-  // Restore the unshadowed variable.
-  if (OldVal)
-    NamedValues[VarName] = OldVal;
-  else
-    NamedValues.erase(VarName);
-
-  
-  // for expr always returns 0.0.
-  return Constant::getNullValue(Type::getDoubleTy(getGlobalContext()));
-}
-
-Value *VarExprAST::Codegen() {
-  std::vector<AllocaInst *> OldBindings;
-  
-  Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-  // Register all variables and emit their initializer.
-  for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
-    const std::string &VarName = VarNames[i].first;
-    ExprAST *Init = VarNames[i].second;
-    
-    // Emit the initializer before adding the variable to scope, this prevents
-    // the initializer from referencing the variable itself, and permits stuff
-    // like this:
-    //  var a = 1 in
-    //    var a = a in ...   # refers to outer 'a'.
-    Value *InitVal;
-    if (Init) {
-      InitVal = Init->Codegen();
-      if (InitVal == 0) return 0;
-    } else { // If not specified, use 0.0.
-      InitVal = ConstantFP::get(getGlobalContext(), APFloat(0.0));
-    }
-    
-    AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-    Builder.CreateStore(InitVal, Alloca);
-
-    // Remember the old variable binding so that we can restore the binding when
-    // we unrecurse.
-    OldBindings.push_back(NamedValues[VarName]);
-    
-    // Remember this binding.
-    NamedValues[VarName] = Alloca;
-  }
-  
-  // Codegen the body, now that all vars are in scope.
-  Value *BodyVal = Body->Codegen();
-  if (BodyVal == 0) return 0;
-  
-  // Pop all our variables from scope.
-  for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
-    NamedValues[VarNames[i].first] = OldBindings[i];
-
-  // Return the body computation.
-  return BodyVal;
-}
-
-Function *PrototypeAST::Codegen() {
-  // Make the function type:  double(double,double) etc.
-  std::vector<Type*> Doubles(Args.size(),
-                             Type::getDoubleTy(getGlobalContext()));
-  FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()),
-                                       Doubles, false);
-  
-  Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
-  
-  // If F conflicted, there was already something named 'Name'.  If it has a
-  // body, don't allow redefinition or reextern.
-  if (F->getName() != Name) {
-    // Delete the one we just made and get the existing one.
-    F->eraseFromParent();
-    F = TheModule->getFunction(Name);
-    
-    // If F already has a body, reject this.
-    if (!F->empty()) {
-      ErrorF("redefinition of function");
-      return 0;
-    }
-    
-    // If F took a different number of args, reject.
-    if (F->arg_size() != Args.size()) {
-      ErrorF("redefinition of function with different # args");
-      return 0;
-    }
-  }
-  
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size();
-       ++AI, ++Idx)
-    AI->setName(Args[Idx]);
-    
-  return F;
-}
-
-/// CreateArgumentAllocas - Create an alloca for each argument and register the
-/// argument in the symbol table so that references to it will succeed.
-void PrototypeAST::CreateArgumentAllocas(Function *F) {
-  Function::arg_iterator AI = F->arg_begin();
-  for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) {
-    // Create an alloca for this variable.
-    AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]);
-
-    // Store the initial value into the alloca.
-    Builder.CreateStore(AI, Alloca);
-
-    // Add arguments to variable symbol table.
-    NamedValues[Args[Idx]] = Alloca;
-  }
-}
-
-Function *FunctionAST::Codegen() {
-  NamedValues.clear();
-  
-  Function *TheFunction = Proto->Codegen();
-  if (TheFunction == 0)
-    return 0;
-  
-  // If this is an operator, install it.
-  if (Proto->isBinaryOp())
-    BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence();
-  
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-  
-  // Add all arguments to the symbol table and create their allocas.
-  Proto->CreateArgumentAllocas(TheFunction);
-
-  if (Value *RetVal = Body->Codegen()) {
-    // Finish off the function.
-    Builder.CreateRet(RetVal);
-
-    // Validate the generated code, checking for consistency.
-    verifyFunction(*TheFunction);
-
-    // Optimize the function.
-    TheFPM->run(*TheFunction);
-    
-    return TheFunction;
-  }
-  
-  // Error reading body, remove function.
-  TheFunction->eraseFromParent();
-
-  if (Proto->isBinaryOp())
-    BinopPrecedence.erase(Proto->getOperatorName());
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Top-Level parsing and JIT Driver
-//===----------------------------------------------------------------------===//
-
-static ExecutionEngine *TheExecutionEngine;
-
-static void HandleDefinition() {
-  if (FunctionAST *F = ParseDefinition()) {
-    if (Function *LF = F->Codegen()) {
-      fprintf(stderr, "Read function definition:");
-      LF->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleExtern() {
-  if (PrototypeAST *P = ParseExtern()) {
-    if (Function *F = P->Codegen()) {
-      fprintf(stderr, "Read extern: ");
-      F->dump();
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-static void HandleTopLevelExpression() {
-  // Evaluate a top-level expression into an anonymous function.
-  if (FunctionAST *F = ParseTopLevelExpr()) {
-    if (Function *LF = F->Codegen()) {
-      // JIT the function, returning a function pointer.
-      void *FPtr = TheExecutionEngine->getPointerToFunction(LF);
-      
-      // Cast it to the right type (takes no arguments, returns a double) so we
-      // can call it as a native function.
-      double (*FP)() = (double (*)())(intptr_t)FPtr;
-      fprintf(stderr, "Evaluated to %f\n", FP());
-    }
-  } else {
-    // Skip token for error recovery.
-    getNextToken();
-  }
-}
-
-/// top ::= definition | external | expression | ';'
-static void MainLoop() {
-  while (1) {
-    fprintf(stderr, "ready> ");
-    switch (CurTok) {
-    case tok_eof:    return;
-    case ';':        getNextToken(); break;  // ignore top-level semicolons.
-    case tok_def:    HandleDefinition(); break;
-    case tok_extern: HandleExtern(); break;
-    default:         HandleTopLevelExpression(); break;
-    }
-  }
-}
-
-//===----------------------------------------------------------------------===//
-// "Library" functions that can be "extern'd" from user code.
-//===----------------------------------------------------------------------===//
-
-/// putchard - putchar that takes a double and returns 0.
-extern "C" 
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-/// printd - printf that takes a double prints it as "%f\n", returning 0.
-extern "C" 
-double printd(double X) {
-  printf("%f\n", X);
-  return 0;
-}
-
-//===----------------------------------------------------------------------===//
-// Main driver code.
-//===----------------------------------------------------------------------===//
-
-int main() {
-  InitializeNativeTarget();
-  LLVMContext &Context = getGlobalContext();
-
-  // Install standard binary operators.
-  // 1 is lowest precedence.
-  BinopPrecedence['='] = 2;
-  BinopPrecedence['<'] = 10;
-  BinopPrecedence['+'] = 20;
-  BinopPrecedence['-'] = 20;
-  BinopPrecedence['*'] = 40;  // highest.
-
-  // Prime the first token.
-  fprintf(stderr, "ready> ");
-  getNextToken();
-
-  // Make the module, which holds all the code.
-  TheModule = new Module("my cool jit", Context);
-
-  // Create the JIT.  This takes ownership of the module.
-  std::string ErrStr;
-  TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create();
-  if (!TheExecutionEngine) {
-    fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str());
-    exit(1);
-  }
-
-  FunctionPassManager OurFPM(TheModule);
-
-  // Set up the optimizer pipeline.  Start with registering info about how the
-  // target lays out data structures.
-  OurFPM.add(new TargetData(*TheExecutionEngine->getTargetData()));
-  // Provide basic AliasAnalysis support for GVN.
-  OurFPM.add(createBasicAliasAnalysisPass());
-  // Promote allocas to registers.
-  OurFPM.add(createPromoteMemoryToRegisterPass());
-  // Do simple "peephole" optimizations and bit-twiddling optzns.
-  OurFPM.add(createInstructionCombiningPass());
-  // Reassociate expressions.
-  OurFPM.add(createReassociatePass());
-  // Eliminate Common SubExpressions.
-  OurFPM.add(createGVNPass());
-  // Simplify the control flow graph (deleting unreachable blocks, etc).
-  OurFPM.add(createCFGSimplificationPass());
-
-  OurFPM.doInitialization();
-
-  // Set the global so the code gen can use this.
-  TheFPM = &OurFPM;
-
-  // Run the main "interpreter loop" now.
-  MainLoop();
-
-  TheFPM = 0;
-
-  // Print out all of the generated code.
-  TheModule->dump();
-
-  return 0;
-}
-
-
- -Next: Conclusion and other useful LLVM tidbits -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-10-16 01:06:54 -0700 (Sun, 16 Oct 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/LangImpl8.html b/cpp/llvm/docs/tutorial/LangImpl8.html deleted file mode 100644 index f62165dd..00000000 --- a/cpp/llvm/docs/tutorial/LangImpl8.html +++ /dev/null @@ -1,359 +0,0 @@ - - - - - Kaleidoscope: Conclusion and other useful LLVM tidbits - - - - - - - -

Kaleidoscope: Conclusion and other useful LLVM tidbits

- - - - -
-

Written by Chris Lattner

-
- - -

Tutorial Conclusion

- - -
- -

Welcome to the the final chapter of the "Implementing a -language with LLVM" tutorial. In the course of this tutorial, we have grown -our little Kaleidoscope language from being a useless toy, to being a -semi-interesting (but probably still useless) toy. :)

- -

It is interesting to see how far we've come, and how little code it has -taken. We built the entire lexer, parser, AST, code generator, and an -interactive run-loop (with a JIT!) by-hand in under 700 lines of -(non-comment/non-blank) code.

- -

Our little language supports a couple of interesting features: it supports -user defined binary and unary operators, it uses JIT compilation for immediate -evaluation, and it supports a few control flow constructs with SSA construction. -

- -

Part of the idea of this tutorial was to show you how easy and fun it can be -to define, build, and play with languages. Building a compiler need not be a -scary or mystical process! Now that you've seen some of the basics, I strongly -encourage you to take the code and hack on it. For example, try adding:

- -
    -
  • global variables - While global variables have questional value in -modern software engineering, they are often useful when putting together quick -little hacks like the Kaleidoscope compiler itself. Fortunately, our current -setup makes it very easy to add global variables: just have value lookup check -to see if an unresolved variable is in the global variable symbol table before -rejecting it. To create a new global variable, make an instance of the LLVM -GlobalVariable class.
  • - -
  • typed variables - Kaleidoscope currently only supports variables of -type double. This gives the language a very nice elegance, because only -supporting one type means that you never have to specify types. Different -languages have different ways of handling this. The easiest way is to require -the user to specify types for every variable definition, and record the type -of the variable in the symbol table along with its Value*.
  • - -
  • arrays, structs, vectors, etc - Once you add types, you can start -extending the type system in all sorts of interesting ways. Simple arrays are -very easy and are quite useful for many different applications. Adding them is -mostly an exercise in learning how the LLVM getelementptr instruction works: it -is so nifty/unconventional, it has its own FAQ! If you add support -for recursive types (e.g. linked lists), make sure to read the section in the LLVM -Programmer's Manual that describes how to construct them.
  • - -
  • standard runtime - Our current language allows the user to access -arbitrary external functions, and we use it for things like "printd" and -"putchard". As you extend the language to add higher-level constructs, often -these constructs make the most sense if they are lowered to calls into a -language-supplied runtime. For example, if you add hash tables to the language, -it would probably make sense to add the routines to a runtime, instead of -inlining them all the way.
  • - -
  • memory management - Currently we can only access the stack in -Kaleidoscope. It would also be useful to be able to allocate heap memory, -either with calls to the standard libc malloc/free interface or with a garbage -collector. If you would like to use garbage collection, note that LLVM fully -supports Accurate Garbage Collection -including algorithms that move objects and need to scan/update the stack.
  • - -
  • debugger support - LLVM supports generation of DWARF Debug info which is understood by -common debuggers like GDB. Adding support for debug info is fairly -straightforward. The best way to understand it is to compile some C/C++ code -with "llvm-gcc -g -O0" and taking a look at what it produces.
  • - -
  • exception handling support - LLVM supports generation of zero cost exceptions which interoperate -with code compiled in other languages. You could also generate code by -implicitly making every function return an error value and checking it. You -could also make explicit use of setjmp/longjmp. There are many different ways -to go here.
  • - -
  • object orientation, generics, database access, complex numbers, -geometric programming, ... - Really, there is -no end of crazy features that you can add to the language.
  • - -
  • unusual domains - We've been talking about applying LLVM to a domain -that many people are interested in: building a compiler for a specific language. -However, there are many other domains that can use compiler technology that are -not typically considered. For example, LLVM has been used to implement OpenGL -graphics acceleration, translate C++ code to ActionScript, and many other -cute and clever things. Maybe you will be the first to JIT compile a regular -expression interpreter into native code with LLVM?
  • - -
- -

-Have fun - try doing something crazy and unusual. Building a language like -everyone else always has, is much less fun than trying something a little crazy -or off the wall and seeing how it turns out. If you get stuck or want to talk -about it, feel free to email the llvmdev mailing -list: it has lots of people who are interested in languages and are often -willing to help out. -

- -

Before we end this tutorial, I want to talk about some "tips and tricks" for generating -LLVM IR. These are some of the more subtle things that may not be obvious, but -are very useful if you want to take advantage of LLVM's capabilities.

- -
- - -

Properties of the LLVM IR

- - -
- -

We have a couple common questions about code in the LLVM IR form - lets just -get these out of the way right now, shall we?

- - -

Target Independence

- - -
- -

Kaleidoscope is an example of a "portable language": any program written in -Kaleidoscope will work the same way on any target that it runs on. Many other -languages have this property, e.g. lisp, java, haskell, javascript, python, etc -(note that while these languages are portable, not all their libraries are).

- -

One nice aspect of LLVM is that it is often capable of preserving target -independence in the IR: you can take the LLVM IR for a Kaleidoscope-compiled -program and run it on any target that LLVM supports, even emitting C code and -compiling that on targets that LLVM doesn't support natively. You can trivially -tell that the Kaleidoscope compiler generates target-independent code because it -never queries for any target-specific information when generating code.

- -

The fact that LLVM provides a compact, target-independent, representation for -code gets a lot of people excited. Unfortunately, these people are usually -thinking about C or a language from the C family when they are asking questions -about language portability. I say "unfortunately", because there is really no -way to make (fully general) C code portable, other than shipping the source code -around (and of course, C source code is not actually portable in general -either - ever port a really old application from 32- to 64-bits?).

- -

The problem with C (again, in its full generality) is that it is heavily -laden with target specific assumptions. As one simple example, the preprocessor -often destructively removes target-independence from the code when it processes -the input text:

- -
-
-#ifdef __i386__
-  int X = 1;
-#else
-  int X = 42;
-#endif
-
-
- -

While it is possible to engineer more and more complex solutions to problems -like this, it cannot be solved in full generality in a way that is better than shipping -the actual source code.

- -

That said, there are interesting subsets of C that can be made portable. If -you are willing to fix primitive types to a fixed size (say int = 32-bits, -and long = 64-bits), don't care about ABI compatibility with existing binaries, -and are willing to give up some other minor features, you can have portable -code. This can make sense for specialized domains such as an -in-kernel language.

- -
- - -

Safety Guarantees

- - -
- -

Many of the languages above are also "safe" languages: it is impossible for -a program written in Java to corrupt its address space and crash the process -(assuming the JVM has no bugs). -Safety is an interesting property that requires a combination of language -design, runtime support, and often operating system support.

- -

It is certainly possible to implement a safe language in LLVM, but LLVM IR -does not itself guarantee safety. The LLVM IR allows unsafe pointer casts, -use after free bugs, buffer over-runs, and a variety of other problems. Safety -needs to be implemented as a layer on top of LLVM and, conveniently, several -groups have investigated this. Ask on the llvmdev mailing -list if you are interested in more details.

- -
- - -

Language-Specific Optimizations

- - -
- -

One thing about LLVM that turns off many people is that it does not solve all -the world's problems in one system (sorry 'world hunger', someone else will have -to solve you some other day). One specific complaint is that people perceive -LLVM as being incapable of performing high-level language-specific optimization: -LLVM "loses too much information".

- -

Unfortunately, this is really not the place to give you a full and unified -version of "Chris Lattner's theory of compiler design". Instead, I'll make a -few observations:

- -

First, you're right that LLVM does lose information. For example, as of this -writing, there is no way to distinguish in the LLVM IR whether an SSA-value came -from a C "int" or a C "long" on an ILP32 machine (other than debug info). Both -get compiled down to an 'i32' value and the information about what it came from -is lost. The more general issue here, is that the LLVM type system uses -"structural equivalence" instead of "name equivalence". Another place this -surprises people is if you have two types in a high-level language that have the -same structure (e.g. two different structs that have a single int field): these -types will compile down into a single LLVM type and it will be impossible to -tell what it came from.

- -

Second, while LLVM does lose information, LLVM is not a fixed target: we -continue to enhance and improve it in many different ways. In addition to -adding new features (LLVM did not always support exceptions or debug info), we -also extend the IR to capture important information for optimization (e.g. -whether an argument is sign or zero extended, information about pointers -aliasing, etc). Many of the enhancements are user-driven: people want LLVM to -include some specific feature, so they go ahead and extend it.

- -

Third, it is possible and easy to add language-specific -optimizations, and you have a number of choices in how to do it. As one trivial -example, it is easy to add language-specific optimization passes that -"know" things about code compiled for a language. In the case of the C family, -there is an optimization pass that "knows" about the standard C library -functions. If you call "exit(0)" in main(), it knows that it is safe to -optimize that into "return 0;" because C specifies what the 'exit' -function does.

- -

In addition to simple library knowledge, it is possible to embed a variety of -other language-specific information into the LLVM IR. If you have a specific -need and run into a wall, please bring the topic up on the llvmdev list. At the -very worst, you can always treat LLVM as if it were a "dumb code generator" and -implement the high-level optimizations you desire in your front-end, on the -language-specific AST. -

- -
- -
- - -

Tips and Tricks

- - -
- -

There is a variety of useful tips and tricks that you come to know after -working on/with LLVM that aren't obvious at first glance. Instead of letting -everyone rediscover them, this section talks about some of these issues.

- - -

Implementing portable offsetof/sizeof

- - -
- -

One interesting thing that comes up, if you are trying to keep the code -generated by your compiler "target independent", is that you often need to know -the size of some LLVM type or the offset of some field in an llvm structure. -For example, you might need to pass the size of a type into a function that -allocates memory.

- -

Unfortunately, this can vary widely across targets: for example the width of -a pointer is trivially target-specific. However, there is a clever -way to use the getelementptr instruction that allows you to compute this -in a portable way.

- -
- - -

Garbage Collected Stack Frames

- - -
- -

Some languages want to explicitly manage their stack frames, often so that -they are garbage collected or to allow easy implementation of closures. There -are often better ways to implement these features than explicit stack frames, -but LLVM -does support them, if you want. It requires your front-end to convert the -code into Continuation -Passing Style and the use of tail calls (which LLVM also supports).

- -
- -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/Makefile b/cpp/llvm/docs/tutorial/Makefile deleted file mode 100644 index fdf1bb68..00000000 --- a/cpp/llvm/docs/tutorial/Makefile +++ /dev/null @@ -1,30 +0,0 @@ -##===- docs/tutorial/Makefile ------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../.. -include $(LEVEL)/Makefile.common - -HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) -PNG := $(wildcard $(PROJ_SRC_DIR)/*.png) -EXTRA_DIST := $(HTML) index.html -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/tutorial - -install-local:: $(HTML) - $(Echo) Installing HTML Tutorial Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PNG) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/index.html $(HTML_DIR) - -uninstall-local:: - $(Echo) Uninstalling Tutorial Documentation - $(Verb) $(RM) -rf $(HTML_DIR) - -printvars:: - $(Echo) "HTML : " '$(HTML)' diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl1.html b/cpp/llvm/docs/tutorial/OCamlLangImpl1.html deleted file mode 100644 index fb9821a1..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl1.html +++ /dev/null @@ -1,365 +0,0 @@ - - - - - Kaleidoscope: Tutorial Introduction and the Lexer - - - - - - - - -

Kaleidoscope: Tutorial Introduction and the Lexer

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Tutorial Introduction

- - -
- -

Welcome to the "Implementing a language with LLVM" tutorial. This tutorial -runs through the implementation of a simple language, showing how fun and -easy it can be. This tutorial will get you up and started as well as help to -build a framework you can extend to other languages. The code in this tutorial -can also be used as a playground to hack on other LLVM specific things. -

- -

-The goal of this tutorial is to progressively unveil our language, describing -how it is built up over time. This will let us cover a fairly broad range of -language design and LLVM-specific usage issues, showing and explaining the code -for it all along the way, without overwhelming you with tons of details up -front.

- -

It is useful to point out ahead of time that this tutorial is really about -teaching compiler techniques and LLVM specifically, not about teaching -modern and sane software engineering principles. In practice, this means that -we'll take a number of shortcuts to simplify the exposition. For example, the -code leaks memory, uses global variables all over the place, doesn't use nice -design patterns like visitors, etc... but it -is very simple. If you dig in and use the code as a basis for future projects, -fixing these deficiencies shouldn't be hard.

- -

I've tried to put this tutorial together in a way that makes chapters easy to -skip over if you are already familiar with or are uninterested in the various -pieces. The structure of the tutorial is: -

- -
    -
  • Chapter #1: Introduction to the Kaleidoscope -language, and the definition of its Lexer - This shows where we are going -and the basic functionality that we want it to do. In order to make this -tutorial maximally understandable and hackable, we choose to implement -everything in Objective Caml instead of using lexer and parser generators. -LLVM obviously works just fine with such tools, feel free to use one if you -prefer.
  • -
  • Chapter #2: Implementing a Parser and -AST - With the lexer in place, we can talk about parsing techniques and -basic AST construction. This tutorial describes recursive descent parsing and -operator precedence parsing. Nothing in Chapters 1 or 2 is LLVM-specific, -the code doesn't even link in LLVM at this point. :)
  • -
  • Chapter #3: Code generation to LLVM -IR - With the AST ready, we can show off how easy generation of LLVM IR -really is.
  • -
  • Chapter #4: Adding JIT and Optimizer -Support - Because a lot of people are interested in using LLVM as a JIT, -we'll dive right into it and show you the 3 lines it takes to add JIT support. -LLVM is also useful in many other ways, but this is one simple and "sexy" way -to shows off its power. :)
  • -
  • Chapter #5: Extending the Language: -Control Flow - With the language up and running, we show how to extend it -with control flow operations (if/then/else and a 'for' loop). This gives us a -chance to talk about simple SSA construction and control flow.
  • -
  • Chapter #6: Extending the Language: -User-defined Operators - This is a silly but fun chapter that talks about -extending the language to let the user program define their own arbitrary -unary and binary operators (with assignable precedence!). This lets us build a -significant piece of the "language" as library routines.
  • -
  • Chapter #7: Extending the Language: -Mutable Variables - This chapter talks about adding user-defined local -variables along with an assignment operator. The interesting part about this -is how easy and trivial it is to construct SSA form in LLVM: no, LLVM does -not require your front-end to construct SSA form!
  • -
  • Chapter #8: Conclusion and other -useful LLVM tidbits - This chapter wraps up the series by talking about -potential ways to extend the language, but also includes a bunch of pointers to -info about "special topics" like adding garbage collection support, exceptions, -debugging, support for "spaghetti stacks", and a bunch of other tips and -tricks.
  • - -
- -

By the end of the tutorial, we'll have written a bit less than 700 lines of -non-comment, non-blank, lines of code. With this small amount of code, we'll -have built up a very reasonable compiler for a non-trivial language including -a hand-written lexer, parser, AST, as well as code generation support with a JIT -compiler. While other systems may have interesting "hello world" tutorials, -I think the breadth of this tutorial is a great testament to the strengths of -LLVM and why you should consider it if you're interested in language or compiler -design.

- -

A note about this tutorial: we expect you to extend the language and play -with it on your own. Take the code and go crazy hacking away at it, compilers -don't need to be scary creatures - it can be a lot of fun to play with -languages!

- -
- - -

The Basic Language

- - -
- -

This tutorial will be illustrated with a toy language that we'll call -"Kaleidoscope" (derived -from "meaning beautiful, form, and view"). -Kaleidoscope is a procedural language that allows you to define functions, use -conditionals, math, etc. Over the course of the tutorial, we'll extend -Kaleidoscope to support the if/then/else construct, a for loop, user defined -operators, JIT compilation with a simple command line interface, etc.

- -

Because we want to keep things simple, the only datatype in Kaleidoscope is a -64-bit floating point type (aka 'float' in O'Caml parlance). As such, all -values are implicitly double precision and the language doesn't require type -declarations. This gives the language a very nice and simple syntax. For -example, the following simple example computes Fibonacci numbers:

- -
-
-# Compute the x'th fibonacci number.
-def fib(x)
-  if x < 3 then
-    1
-  else
-    fib(x-1)+fib(x-2)
-
-# This expression will compute the 40th number.
-fib(40)
-
-
- -

We also allow Kaleidoscope to call into standard library functions (the LLVM -JIT makes this completely trivial). This means that you can use the 'extern' -keyword to define a function before you use it (this is also useful for mutually -recursive functions). For example:

- -
-
-extern sin(arg);
-extern cos(arg);
-extern atan2(arg1 arg2);
-
-atan2(sin(.4), cos(42))
-
-
- -

A more interesting example is included in Chapter 6 where we write a little -Kaleidoscope application that displays -a Mandelbrot Set at various levels of magnification.

- -

Lets dive into the implementation of this language!

- -
- - -

The Lexer

- - -
- -

When it comes to implementing a language, the first thing needed is -the ability to process a text file and recognize what it says. The traditional -way to do this is to use a "lexer" (aka 'scanner') -to break the input up into "tokens". Each token returned by the lexer includes -a token code and potentially some metadata (e.g. the numeric value of a number). -First, we define the possibilities: -

- -
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-
- -

Each token returned by our lexer will be one of the token variant values. -An unknown character like '+' will be returned as Token.Kwd '+'. If -the curr token is an identifier, the value will be Token.Ident s. If -the current token is a numeric literal (like 1.0), the value will be -Token.Number 1.0. -

- -

The actual implementation of the lexer is a collection of functions driven -by a function named Lexer.lex. The Lexer.lex function is -called to return the next token from standard input. We will use -Camlp4 -to simplify the tokenization of the standard input. Its definition starts -as:

- -
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-
- -

-Lexer.lex works by recursing over a char Stream.t to read -characters one at a time from the standard input. It eats them as it recognizes -them and stores them in in a Token.token variant. The first thing that -it has to do is ignore whitespace between tokens. This is accomplished with the -recursive call above.

- -

The next thing Lexer.lex needs to do is recognize identifiers and -specific keywords like "def". Kaleidoscope does this with a pattern match -and a helper function.

- -

-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-...
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-
- -

Numeric values are similar:

- -
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-...
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-
- -

This is all pretty straight-forward code for processing input. When reading -a numeric value from input, we use the ocaml float_of_string function -to convert it to a numeric value that we store in Token.Number. Note -that this isn't doing sufficient error checking: it will raise Failure -if the string "1.23.45.67". Feel free to extend it :). Next we handle -comments: -

- -
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-...
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -

We handle comments by skipping to the end of the line and then return the -next token. Finally, if the input doesn't match one of the above cases, it is -either an operator character like '+' or the end of the file. These are handled -with this code:

- -
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-
- -

With this, we have the complete lexer for the basic Kaleidoscope language -(the full code listing for the Lexer is -available in the next chapter of the -tutorial). Next we'll build a simple parser that -uses this to build an Abstract Syntax Tree. When we have that, we'll -include a driver so that you can use the lexer and parser together. -

- -Next: Implementing a Parser and AST -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl2.html b/cpp/llvm/docs/tutorial/OCamlLangImpl2.html deleted file mode 100644 index 73abab23..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl2.html +++ /dev/null @@ -1,1043 +0,0 @@ - - - - - Kaleidoscope: Implementing a Parser and AST - - - - - - - - -

Kaleidoscope: Implementing a Parser and AST

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 2 Introduction

- - -
- -

Welcome to Chapter 2 of the "Implementing a language -with LLVM in Objective Caml" tutorial. This chapter shows you how to use -the lexer, built in Chapter 1, to build a -full parser for our -Kaleidoscope language. Once we have a parser, we'll define and build an Abstract Syntax -Tree (AST).

- -

The parser we will build uses a combination of Recursive Descent -Parsing and Operator-Precedence -Parsing to parse the Kaleidoscope language (the latter for -binary expressions and the former for everything else). Before we get to -parsing though, lets talk about the output of the parser: the Abstract Syntax -Tree.

- -
- - -

The Abstract Syntax Tree (AST)

- - -
- -

The AST for a program captures its behavior in such a way that it is easy for -later stages of the compiler (e.g. code generation) to interpret. We basically -want one object for each construct in the language, and the AST should closely -model the language. In Kaleidoscope, we have expressions, a prototype, and a -function object. We'll start with expressions first:

- -
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-
- -

The code above shows the definition of the base ExprAST class and one -subclass which we use for numeric literals. The important thing to note about -this code is that the Number variant captures the numeric value of the -literal as an instance variable. This allows later phases of the compiler to -know what the stored numeric value is.

- -

Right now we only create the AST, so there are no useful functions on -them. It would be very easy to add a function to pretty print the code, -for example. Here are the other expression AST node definitions that we'll use -in the basic form of the Kaleidoscope language: -

- -
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-
- -

This is all (intentionally) rather straight-forward: variables capture the -variable name, binary operators capture their opcode (e.g. '+'), and calls -capture a function name as well as a list of any argument expressions. One thing -that is nice about our AST is that it captures the language features without -talking about the syntax of the language. Note that there is no discussion about -precedence of binary operators, lexical structure, etc.

- -

For our basic language, these are all of the expression nodes we'll define. -Because it doesn't have conditional control flow, it isn't Turing-complete; -we'll fix that in a later installment. The two things we need next are a way -to talk about the interface to a function, and a way to talk about functions -themselves:

- -
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto = Prototype of string * string array
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -

In Kaleidoscope, functions are typed with just a count of their arguments. -Since all values are double precision floating point, the type of each argument -doesn't need to be stored anywhere. In a more aggressive and realistic -language, the "expr" variants would probably have a type field.

- -

With this scaffolding, we can now talk about parsing expressions and function -bodies in Kaleidoscope.

- -
- - -

Parser Basics

- - -
- -

Now that we have an AST to build, we need to define the parser code to build -it. The idea here is that we want to parse something like "x+y" (which is -returned as three tokens by the lexer) into an AST that could be generated with -calls like this:

- -
-
-  let x = Variable "x" in
-  let y = Variable "y" in
-  let result = Binary ('+', x, y) in
-  ...
-
-
- -

-The error handling routines make use of the builtin Stream.Failure and -Stream.Errors. Stream.Failure is raised when the parser is -unable to find any matching token in the first position of a pattern. -Stream.Error is raised when the first token matches, but the rest do -not. The error recovery in our parser will not be the best and is not -particular user-friendly, but it will be enough for our tutorial. These -exceptions make it easier to handle errors in routines that have various return -types.

- -

With these basic types and exceptions, we can implement the first -piece of our grammar: numeric literals.

- -
- - -

Basic Expression Parsing

- - -
- -

We start with numeric literals, because they are the simplest to process. -For each production in our grammar, we'll define a function which parses that -production. We call this class of expressions "primary" expressions, for -reasons that will become more clear -later in the tutorial. In order to parse an arbitrary primary expression, -we need to determine what sort of expression it is. For numeric literals, we -have:

- -
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr *)
-parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-
- -

This routine is very simple: it expects to be called when the current token -is a Token.Number token. It takes the current number value, creates -a Ast.Number node, advances the lexer to the next token, and finally -returns.

- -

There are some interesting aspects to this. The most important one is that -this routine eats all of the tokens that correspond to the production and -returns the lexer buffer with the next token (which is not part of the grammar -production) ready to go. This is a fairly standard way to go for recursive -descent parsers. For a better example, the parenthesis operator is defined like -this:

- -
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-
- -

This function illustrates a number of interesting things about the -parser:

- -

-1) It shows how we use the Stream.Error exception. When called, this -function expects that the current token is a '(' token, but after parsing the -subexpression, it is possible that there is no ')' waiting. For example, if -the user types in "(4 x" instead of "(4)", the parser should emit an error. -Because errors can occur, the parser needs a way to indicate that they -happened. In our parser, we use the camlp4 shortcut syntax token ?? "parse -error", where if the token before the ?? does not match, then -Stream.Error "parse error" will be raised.

- -

2) Another interesting aspect of this function is that it uses recursion by -calling Parser.parse_primary (we will soon see that -Parser.parse_primary can call Parser.parse_primary). This is -powerful because it allows us to handle recursive grammars, and keeps each -production very simple. Note that parentheses do not cause construction of AST -nodes themselves. While we could do it this way, the most important role of -parentheses are to guide the parser and provide grouping. Once the parser -constructs the AST, parentheses are not needed.

- -

The next simple production is for handling variable references and function -calls:

- -
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-
- -

This routine follows the same style as the other routines. (It expects to be -called if the current token is a Token.Ident token). It also has -recursion and error handling. One interesting aspect of this is that it uses -look-ahead to determine if the current identifier is a stand alone -variable reference or if it is a function call expression. It handles this by -checking to see if the token after the identifier is a '(' token, constructing -either a Ast.Variable or Ast.Call node as appropriate. -

- -

We finish up by raising an exception if we received a token we didn't -expect:

- -
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-
- -

Now that basic expressions are handled, we need to handle binary expressions. -They are a bit more complex.

- -
- - -

Binary Expression Parsing

- - -
- -

Binary expressions are significantly harder to parse because they are often -ambiguous. For example, when given the string "x+y*z", the parser can choose -to parse it as either "(x+y)*z" or "x+(y*z)". With common definitions from -mathematics, we expect the later parse, because "*" (multiplication) has -higher precedence than "+" (addition).

- -

There are many ways to handle this, but an elegant and efficient way is to -use Operator-Precedence -Parsing. This parsing technique uses the precedence of binary operators to -guide recursion. To start with, we need a table of precedences:

- -
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-...
-
-let main () =
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-  ...
-
-
- -

For the basic form of Kaleidoscope, we will only support 4 binary operators -(this can obviously be extended by you, our brave and intrepid reader). The -Parser.precedence function returns the precedence for the current -token, or -1 if the token is not a binary operator. Having a Hashtbl.t -makes it easy to add new operators and makes it clear that the algorithm doesn't -depend on the specific operators involved, but it would be easy enough to -eliminate the Hashtbl.t and do the comparisons in the -Parser.precedence function. (Or just use a fixed-size array).

- -

With the helper above defined, we can now start parsing binary expressions. -The basic idea of operator precedence parsing is to break down an expression -with potentially ambiguous binary operators into pieces. Consider ,for example, -the expression "a+b+(c+d)*e*f+g". Operator precedence parsing considers this -as a stream of primary expressions separated by binary operators. As such, -it will first parse the leading primary expression "a", then it will see the -pairs [+, b] [+, (c+d)] [*, e] [*, f] and [+, g]. Note that because parentheses -are primary expressions, the binary expression parser doesn't need to worry -about nested subexpressions like (c+d) at all. -

- -

-To start, an expression is a primary expression potentially followed by a -sequence of [binop,primaryexpr] pairs:

- -
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
-
-
- -

Parser.parse_bin_rhs is the function that parses the sequence of -pairs for us. It takes a precedence and a pointer to an expression for the part -that has been parsed so far. Note that "x" is a perfectly valid expression: As -such, "binoprhs" is allowed to be empty, in which case it returns the expression -that is passed into it. In our example above, the code passes the expression for -"a" into Parser.parse_bin_rhs and the current token is "+".

- -

The precedence value passed into Parser.parse_bin_rhs indicates the -minimal operator precedence that the function is allowed to eat. For -example, if the current pair stream is [+, x] and Parser.parse_bin_rhs -is passed in a precedence of 40, it will not consume any tokens (because the -precedence of '+' is only 20). With this in mind, Parser.parse_bin_rhs -starts with:

- -
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-
-
- -

This code gets the precedence of the current token and checks to see if if is -too low. Because we defined invalid tokens to have a precedence of -1, this -check implicitly knows that the pair-stream ends when the token stream runs out -of binary operators. If this check succeeds, we know that the token is a binary -operator and that it will be included in this expression:

- -
-
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-
-
- -

As such, this code eats (and remembers) the binary operator and then parses -the primary expression that follows. This builds up the whole pair, the first of -which is [+, b] for the running example.

- -

Now that we parsed the left-hand side of an expression and one pair of the -RHS sequence, we have to decide which way the expression associates. In -particular, we could have "(a+b) binop unparsed" or "a + (b binop unparsed)". -To determine this, we look ahead at "binop" to determine its precedence and -compare it to BinOp's precedence (which is '+' in this case):

- -
-
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-
-
- -

If the precedence of the binop to the right of "RHS" is lower or equal to the -precedence of our current operator, then we know that the parentheses associate -as "(a+b) binop ...". In our example, the current operator is "+" and the next -operator is "+", we know that they have the same precedence. In this case we'll -create the AST node for "a+b", and then continue parsing:

- -
-
-          ... if body omitted ...
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-
-
- -

In our example above, this will turn "a+b+" into "(a+b)" and execute the next -iteration of the loop, with "+" as the current token. The code above will eat, -remember, and parse "(c+d)" as the primary expression, which makes the -current pair equal to [+, (c+d)]. It will then evaluate the 'if' conditional above with -"*" as the binop to the right of the primary. In this case, the precedence of "*" is -higher than the precedence of "+" so the if condition will be entered.

- -

The critical question left here is "how can the if condition parse the right -hand side in full"? In particular, to build the AST correctly for our example, -it needs to get all of "(c+d)*e*f" as the RHS expression variable. The code to -do this is surprisingly simple (code from the above two blocks duplicated for -context):

- -
-
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              if token_prec < precedence c2
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-
-
- -

At this point, we know that the binary operator to the RHS of our primary -has higher precedence than the binop we are currently parsing. As such, we know -that any sequence of pairs whose operators are all higher precedence than "+" -should be parsed together and returned as "RHS". To do this, we recursively -invoke the Parser.parse_bin_rhs function specifying "token_prec+1" as -the minimum precedence required for it to continue. In our example above, this -will cause it to return the AST node for "(c+d)*e*f" as RHS, which is then set -as the RHS of the '+' expression.

- -

Finally, on the next iteration of the while loop, the "+g" piece is parsed -and added to the AST. With this little bit of code (14 non-trivial lines), we -correctly handle fully general binary expression parsing in a very elegant way. -This was a whirlwind tour of this code, and it is somewhat subtle. I recommend -running through it with a few tough examples to see how it works. -

- -

This wraps up handling of expressions. At this point, we can point the -parser at an arbitrary token stream and build an expression from it, stopping -at the first token that is not part of the expression. Next up we need to -handle function definitions, etc.

- -
- - -

Parsing the Rest

- - -
- -

-The next thing missing is handling of function prototypes. In Kaleidoscope, -these are used both for 'extern' function declarations as well as function body -definitions. The code to do this is straight-forward and not very interesting -(once you've survived expressions): -

- -
-
-(* prototype
- *   ::= id '(' id* ')' *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-
- -

Given this, a function definition is very simple, just a prototype plus -an expression to implement the body:

- -
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-
- -

In addition, we support 'extern' to declare functions like 'sin' and 'cos' as -well as to support forward declaration of user functions. These 'extern's are just -prototypes with no body:

- -
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -

Finally, we'll also let the user type in arbitrary top-level expressions and -evaluate them on the fly. We will handle this by defining anonymous nullary -(zero argument) functions for them:

- -
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-
- -

Now that we have all the pieces, let's build a little driver that will let us -actually execute this code we've built!

- -
- - -

The Driver

- - -
- -

The driver for this simply invokes all of the parsing pieces with a top-level -dispatch loop. There isn't much interesting here, so I'll just include the -top-level loop. See below for full code in the "Top-Level -Parsing" section.

- -
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            ignore(Parser.parse_definition stream);
-            print_endline "parsed a function definition.";
-        | Token.Extern ->
-            ignore(Parser.parse_extern stream);
-            print_endline "parsed an extern.";
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            ignore(Parser.parse_toplevel stream);
-            print_endline "parsed a top-level expr";
-        with Stream.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop stream
-
-
- -

The most interesting part of this is that we ignore top-level semicolons. -Why is this, you ask? The basic reason is that if you type "4 + 5" at the -command line, the parser doesn't know whether that is the end of what you will type -or not. For example, on the next line you could type "def foo..." in which case -4+5 is the end of a top-level expression. Alternatively you could type "* 6", -which would continue the expression. Having top-level semicolons allows you to -type "4+5;", and the parser will know you are done.

- -
- - -

Conclusions

- - -
- -

With just under 300 lines of commented code (240 lines of non-comment, -non-blank code), we fully defined our minimal language, including a lexer, -parser, and AST builder. With this done, the executable will validate -Kaleidoscope code and tell us if it is grammatically invalid. For -example, here is a sample interaction:

- -
-
-$ ./toy.byte
-ready> def foo(x y) x+foo(y, 4.0);
-Parsed a function definition.
-ready> def foo(x y) x+y y;
-Parsed a function definition.
-Parsed a top-level expr
-ready> def foo(x y) x+y );
-Parsed a function definition.
-Error: unknown token when expecting an expression
-ready> extern sin(a);
-ready> Parsed an extern
-ready> ^D
-$
-
-
- -

There is a lot of room for extension here. You can define new AST nodes, -extend the language in many ways, etc. In the -next installment, we will describe how to generate LLVM Intermediate -Representation (IR) from the AST.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for this and the previous chapter. -Note that it is fully self-contained: you don't need LLVM or any external -libraries at all for this. (Besides the ocaml standard libraries, of -course.) To build this, just compile with:

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto = Prototype of string * string array
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the primary expression after the binary operator. *)
-        let rhs = parse_primary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')' *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            ignore(Parser.parse_definition stream);
-            print_endline "parsed a function definition.";
-        | Token.Extern ->
-            ignore(Parser.parse_extern stream);
-            print_endline "parsed an extern.";
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            ignore(Parser.parse_toplevel stream);
-            print_endline "parsed a top-level expr";
-        with Stream.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-let main () =
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop stream;
-;;
-
-main ()
-
-
-
- -Next: Implementing Code Generation to LLVM IR -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner - Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl3.html b/cpp/llvm/docs/tutorial/OCamlLangImpl3.html deleted file mode 100644 index d4647cbe..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl3.html +++ /dev/null @@ -1,1093 +0,0 @@ - - - - - Kaleidoscope: Implementing code generation to LLVM IR - - - - - - - - -

Kaleidoscope: Code generation to LLVM IR

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 3 Introduction

- - -
- -

Welcome to Chapter 3 of the "Implementing a language -with LLVM" tutorial. This chapter shows you how to transform the Abstract Syntax Tree, built in Chapter 2, into -LLVM IR. This will teach you a little bit about how LLVM does things, as well -as demonstrate how easy it is to use. It's much more work to build a lexer and -parser than it is to generate LLVM IR code. :) -

- -

Please note: the code in this chapter and later require LLVM 2.3 or -LLVM SVN to work. LLVM 2.2 and before will not work with it.

- -
- - -

Code Generation Setup

- - -
- -

-In order to generate LLVM IR, we want some simple setup to get started. First -we define virtual code generation (codegen) methods in each AST class:

- -
-
-let rec codegen_expr = function
-  | Ast.Number n -> ...
-  | Ast.Variable name -> ...
-
-
- -

The Codegen.codegen_expr function says to emit IR for that AST node -along with all the things it depends on, and they all return an LLVM Value -object. "Value" is the class used to represent a "Static Single -Assignment (SSA) register" or "SSA value" in LLVM. The most distinct aspect -of SSA values is that their value is computed as the related instruction -executes, and it does not get a new value until (and if) the instruction -re-executes. In other words, there is no way to "change" an SSA value. For -more information, please read up on Static Single -Assignment - the concepts are really quite natural once you grok them.

- -

The -second thing we want is an "Error" exception like we used for the parser, which -will be used to report errors found during code generation (for example, use of -an undeclared parameter):

- -
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-
- -

The static variables will be used during code generation. -Codgen.the_module is the LLVM construct that contains all of the -functions and global variables in a chunk of code. In many ways, it is the -top-level structure that the LLVM IR uses to contain code.

- -

The Codegen.builder object is a helper object that makes it easy to -generate LLVM instructions. Instances of the IRBuilder -class keep track of the current place to insert instructions and has methods to -create new instructions.

- -

The Codegen.named_values map keeps track of which values are defined -in the current scope and what their LLVM representation is. (In other words, it -is a symbol table for the code). In this form of Kaleidoscope, the only things -that can be referenced are function parameters. As such, function parameters -will be in this map when generating code for their function body.

- -

-With these basics in place, we can start talking about how to generate code for -each expression. Note that this assumes that the Codgen.builder has -been set up to generate code into something. For now, we'll assume -that this has already been done, and we'll just use it to emit code.

- -
- - -

Expression Code Generation

- - -
- -

Generating LLVM code for expression nodes is very straightforward: less -than 30 lines of commented code for all four of our expression nodes. First -we'll do numeric literals:

- -
-
-  | Ast.Number n -> const_float double_type n
-
-
- -

In the LLVM IR, numeric constants are represented with the -ConstantFP class, which holds the numeric value in an APFloat -internally (APFloat has the capability of holding floating point -constants of Arbitrary Precision). This code basically just -creates and returns a ConstantFP. Note that in the LLVM IR -that constants are all uniqued together and shared. For this reason, the API -uses "the foo::get(..)" idiom instead of "new foo(..)" or "foo::Create(..)".

- -
-
-  | Ast.Variable name ->
-      (try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name"))
-
-
- -

References to variables are also quite simple using LLVM. In the simple -version of Kaleidoscope, we assume that the variable has already been emitted -somewhere and its value is available. In practice, the only values that can be -in the Codegen.named_values map are function arguments. This code -simply checks to see that the specified name is in the map (if not, an unknown -variable is being referenced) and returns the value for it. In future chapters, -we'll add support for loop induction variables -in the symbol table, and for local -variables.

- -
-
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_fadd lhs_val rhs_val "addtmp" builder
-        | '-' -> build_fsub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_fmul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ -> raise (Error "invalid binary operator")
-      end
-
-
- -

Binary operators start to get more interesting. The basic idea here is that -we recursively emit code for the left-hand side of the expression, then the -right-hand side, then we compute the result of the binary expression. In this -code, we do a simple switch on the opcode to create the right LLVM instruction. -

- -

In the example above, the LLVM builder class is starting to show its value. -IRBuilder knows where to insert the newly created instruction, all you have to -do is specify what instruction to create (e.g. with Llvm.create_add), -which operands to use (lhs and rhs here) and optionally -provide a name for the generated instruction.

- -

One nice thing about LLVM is that the name is just a hint. For instance, if -the code above emits multiple "addtmp" variables, LLVM will automatically -provide each one with an increasing, unique numeric suffix. Local value names -for instructions are purely optional, but it makes it much easier to read the -IR dumps.

- -

LLVM instructions are constrained by -strict rules: for example, the Left and Right operators of -an add instruction must have the same -type, and the result type of the add must match the operand types. Because -all values in Kaleidoscope are doubles, this makes for very simple code for add, -sub and mul.

- -

On the other hand, LLVM specifies that the fcmp instruction always returns an 'i1' value -(a one bit integer). The problem with this is that Kaleidoscope wants the value to be a 0.0 or 1.0 value. In order to get these semantics, we combine the fcmp instruction with -a uitofp instruction. This instruction -converts its input integer into a floating point value by treating the input -as an unsigned value. In contrast, if we used the sitofp instruction, the Kaleidoscope '<' -operator would return 0.0 and -1.0, depending on the input value.

- -
-
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-
-
- -

Code generation for function calls is quite straightforward with LLVM. The -code above initially does a function name lookup in the LLVM Module's symbol -table. Recall that the LLVM Module is the container that holds all of the -functions we are JIT'ing. By giving each function the same name as what the -user specifies, we can use the LLVM symbol table to resolve function names for -us.

- -

Once we have the function to call, we recursively codegen each argument that -is to be passed in, and create an LLVM call -instruction. Note that LLVM uses the native C calling conventions by -default, allowing these calls to also call into standard library functions like -"sin" and "cos", with no additional effort.

- -

This wraps up our handling of the four basic expressions that we have so far -in Kaleidoscope. Feel free to go in and add some more. For example, by -browsing the LLVM language reference you'll find -several other interesting instructions that are really easy to plug into our -basic framework.

- -
- - -

Function Code Generation

- - -
- -

Code generation for prototypes and functions must handle a number of -details, which make their code less beautiful than expression code -generation, but allows us to illustrate some important points. First, lets -talk about code generation for prototypes: they are used both for function -bodies and external function declarations. The code starts with:

- -
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-
-
- -

This code packs a lot of power into a few lines. Note first that this -function returns a "Function*" instead of a "Value*" (although at the moment -they both are modeled by llvalue in ocaml). Because a "prototype" -really talks about the external interface for a function (not the value computed -by an expression), it makes sense for it to return the LLVM Function it -corresponds to when codegen'd.

- -

The call to Llvm.function_type creates the Llvm.llvalue -that should be used for a given Prototype. Since all function arguments in -Kaleidoscope are of type double, the first line creates a vector of "N" LLVM -double types. It then uses the Llvm.function_type method to create a -function type that takes "N" doubles as arguments, returns one double as a -result, and that is not vararg (that uses the function -Llvm.var_arg_function_type). Note that Types in LLVM are uniqued just -like Constants are, so you don't "new" a type, you "get" it.

- -

The final line above checks if the function has already been defined in -Codegen.the_module. If not, we will create it.

- -
-
-        | None -> declare_function name ft the_module
-
-
- -

This indicates the type and name to use, as well as which module to insert -into. By default we assume a function has -Llvm.Linkage.ExternalLinkage. "external -linkage" means that the function may be defined outside the current module -and/or that it is callable by functions outside the module. The "name" -passed in is the name the user specified: this name is registered in -"Codegen.the_module"s symbol table, which is used by the function call -code above.

- -

In Kaleidoscope, I choose to allow redefinitions of functions in two cases: -first, we want to allow 'extern'ing a function more than once, as long as the -prototypes for the externs match (since all arguments have the same type, we -just have to check that the number of arguments match). Second, we want to -allow 'extern'ing a function and then defining a body for it. This is useful -when defining mutually recursive functions.

- -
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if Array.length (basic_blocks f) == 0 then () else
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if Array.length (params f) == Array.length args then () else
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-
- -

In order to verify the logic above, we first check to see if the pre-existing -function is "empty". In this case, empty means that it has no basic blocks in -it, which means it has no body. If it has no body, it is a forward -declaration. Since we don't allow anything after a full definition of the -function, the code rejects this case. If the previous reference to a function -was an 'extern', we simply verify that the number of arguments for that -definition and this one match up. If not, we emit an error.

- -
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-
- -

The last bit of code for prototypes loops over all of the arguments in the -function, setting the name of the LLVM Argument objects to match, and registering -the arguments in the Codegen.named_values map for future use by the -Ast.Variable variant. Once this is set up, it returns the Function -object to the caller. Note that we don't check for conflicting -argument names here (e.g. "extern foo(a b a)"). Doing so would be very -straight-forward with the mechanics we have already used above.

- -
-
-let codegen_func = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-
- -

Code generation for function definitions starts out simply enough: we just -codegen the prototype (Proto) and verify that it is ok. We then clear out the -Codegen.named_values map to make sure that there isn't anything in it -from the last function we compiled. Code generation of the prototype ensures -that there is an LLVM Function object that is ready to go for us.

- -
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        let ret_val = codegen_expr body in
-
-
- -

Now we get to the point where the Codegen.builder is set up. The -first line creates a new -basic block (named -"entry"), which is inserted into the_function. The second line then -tells the builder that new instructions should be inserted into the end of the -new basic block. Basic blocks in LLVM are an important part of functions that -define the Control Flow Graph. -Since we don't have any control flow, our functions will only contain one -block at this point. We'll fix this in Chapter -5 :).

- -
-
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        the_function
-
-
- -

Once the insertion point is set up, we call the Codegen.codegen_func -method for the root expression of the function. If no error happens, this emits -code to compute the expression into the entry block and returns the value that -was computed. Assuming no error, we then create an LLVM ret instruction, which completes the function. -Once the function is built, we call -Llvm_analysis.assert_valid_function, which is provided by LLVM. This -function does a variety of consistency checks on the generated code, to -determine if our compiler is doing everything right. Using this is important: -it can catch a lot of bugs. Once the function is finished and validated, we -return it.

- -
-
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -

The only piece left here is handling of the error case. For simplicity, we -handle this by merely deleting the function we produced with the -Llvm.delete_function method. This allows the user to redefine a -function that they incorrectly typed in before: if we didn't delete it, it -would live in the symbol table, with a body, preventing future redefinition.

- -

This code does have a bug, though. Since the Codegen.codegen_proto -can return a previously defined forward declaration, our code can actually delete -a forward declaration. There are a number of ways to fix this bug, see what you -can come up with! Here is a testcase:

- -
-
-extern foo(a b);     # ok, defines foo.
-def foo(a b) c;      # error, 'c' is invalid.
-def bar() foo(1, 2); # error, unknown function "foo"
-
-
- -
- - -

Driver Changes and Closing Thoughts

- - -
- -

-For now, code generation to LLVM doesn't really get us much, except that we can -look at the pretty IR calls. The sample code inserts calls to Codegen into the -"Toplevel.main_loop", and then dumps out the LLVM IR. This gives a -nice way to look at the LLVM IR for simple functions. For example: -

- -
-
-ready> 4+5;
-Read top-level expression:
-define double @""() {
-entry:
-        %addtmp = fadd double 4.000000e+00, 5.000000e+00
-        ret double %addtmp
-}
-
-
- -

Note how the parser turns the top-level expression into anonymous functions -for us. This will be handy when we add JIT -support in the next chapter. Also note that the code is very literally -transcribed, no optimizations are being performed. We will -add optimizations explicitly -in the next chapter.

- -
-
-ready> def foo(a b) a*a + 2*a*b + b*b;
-Read function definition:
-define double @foo(double %a, double %b) {
-entry:
-        %multmp = fmul double %a, %a
-        %multmp1 = fmul double 2.000000e+00, %a
-        %multmp2 = fmul double %multmp1, %b
-        %addtmp = fadd double %multmp, %multmp2
-        %multmp3 = fmul double %b, %b
-        %addtmp4 = fadd double %addtmp, %multmp3
-        ret double %addtmp4
-}
-
-
- -

This shows some simple arithmetic. Notice the striking similarity to the -LLVM builder calls that we use to create the instructions.

- -
-
-ready> def bar(a) foo(a, 4.0) + bar(31337);
-Read function definition:
-define double @bar(double %a) {
-entry:
-        %calltmp = call double @foo(double %a, double 4.000000e+00)
-        %calltmp1 = call double @bar(double 3.133700e+04)
-        %addtmp = fadd double %calltmp, %calltmp1
-        ret double %addtmp
-}
-
-
- -

This shows some function calls. Note that this function will take a long -time to execute if you call it. In the future we'll add conditional control -flow to actually make recursion useful :).

- -
-
-ready> extern cos(x);
-Read extern:
-declare double @cos(double)
-
-ready> cos(1.234);
-Read top-level expression:
-define double @""() {
-entry:
-        %calltmp = call double @cos(double 1.234000e+00)
-        ret double %calltmp
-}
-
-
- -

This shows an extern for the libm "cos" function, and a call to it.

- - -
-
-ready> ^D
-; ModuleID = 'my cool jit'
-
-define double @""() {
-entry:
-        %addtmp = fadd double 4.000000e+00, 5.000000e+00
-        ret double %addtmp
-}
-
-define double @foo(double %a, double %b) {
-entry:
-        %multmp = fmul double %a, %a
-        %multmp1 = fmul double 2.000000e+00, %a
-        %multmp2 = fmul double %multmp1, %b
-        %addtmp = fadd double %multmp, %multmp2
-        %multmp3 = fmul double %b, %b
-        %addtmp4 = fadd double %addtmp, %multmp3
-        ret double %addtmp4
-}
-
-define double @bar(double %a) {
-entry:
-        %calltmp = call double @foo(double %a, double 4.000000e+00)
-        %calltmp1 = call double @bar(double 3.133700e+04)
-        %addtmp = fadd double %calltmp, %calltmp1
-        ret double %addtmp
-}
-
-declare double @cos(double)
-
-define double @""() {
-entry:
-        %calltmp = call double @cos(double 1.234000e+00)
-        ret double %calltmp
-}
-
-
- -

When you quit the current demo, it dumps out the IR for the entire module -generated. Here you can see the big picture with all the functions referencing -each other.

- -

This wraps up the third chapter of the Kaleidoscope tutorial. Up next, we'll -describe how to add JIT codegen and optimizer -support to this so we can actually start running code!

- -
- - - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -LLVM code generator. Because this uses the LLVM libraries, we need to link -them in. To do this, we use the llvm-config tool to inform -our makefile/command line about which options to use:

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
-
-
- -
myocamlbuild.ml:
-
-
-open Ocamlbuild_plugin;;
-
-ocaml_lib ~extern:true "llvm";;
-ocaml_lib ~extern:true "llvm_analysis";;
-
-flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto = Prototype of string * string array
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the primary expression after the binary operator. *)
-        let rhs = parse_primary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')' *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
codegen.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Code Generation
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-let rec codegen_expr = function
-  | Ast.Number n -> const_float double_type n
-  | Ast.Variable name ->
-      (try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name"))
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_add lhs_val rhs_val "addtmp" builder
-        | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_mul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ -> raise (Error "invalid binary operator")
-      end
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-        | None -> declare_function name ft the_module
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if block_begin f <> At_end f then
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if element_type (type_of f) <> ft then
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-let codegen_func = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        the_function
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            let e = Parser.parse_definition stream in
-            print_endline "parsed a function definition.";
-            dump_value (Codegen.codegen_func e);
-        | Token.Extern ->
-            let e = Parser.parse_extern stream in
-            print_endline "parsed an extern.";
-            dump_value (Codegen.codegen_proto e);
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            dump_value (Codegen.codegen_func e);
-        with Stream.Error s | Codegen.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-let main () =
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop stream;
-
-  (* Print out all the generated code. *)
-  dump_module Codegen.the_module
-;;
-
-main ()
-
-
-
- -Next: Adding JIT and Optimizer Support -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-07-15 13:03:30 -0700 (Fri, 15 Jul 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl4.html b/cpp/llvm/docs/tutorial/OCamlLangImpl4.html deleted file mode 100644 index 64c11167..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl4.html +++ /dev/null @@ -1,1027 +0,0 @@ - - - - - Kaleidoscope: Adding JIT and Optimizer Support - - - - - - - - -

Kaleidoscope: Adding JIT and Optimizer Support

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 4 Introduction

- - -
- -

Welcome to Chapter 4 of the "Implementing a language -with LLVM" tutorial. Chapters 1-3 described the implementation of a simple -language and added support for generating LLVM IR. This chapter describes -two new techniques: adding optimizer support to your language, and adding JIT -compiler support. These additions will demonstrate how to get nice, efficient code -for the Kaleidoscope language.

- -
- - -

Trivial Constant Folding

- - -
- -

Note: the default IRBuilder now always includes the constant -folding optimisations below.

- -

-Our demonstration for Chapter 3 is elegant and easy to extend. Unfortunately, -it does not produce wonderful code. For example, when compiling simple code, -we don't get obvious optimizations:

- -
-
-ready> def test(x) 1+2+x;
-Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 1.000000e+00, 2.000000e+00
-        %addtmp1 = fadd double %addtmp, %x
-        ret double %addtmp1
-}
-
-
- -

This code is a very, very literal transcription of the AST built by parsing -the input. As such, this transcription lacks optimizations like constant folding -(we'd like to get "add x, 3.0" in the example above) as well as other -more important optimizations. Constant folding, in particular, is a very common -and very important optimization: so much so that many language implementors -implement constant folding support in their AST representation.

- -

With LLVM, you don't need this support in the AST. Since all calls to build -LLVM IR go through the LLVM builder, it would be nice if the builder itself -checked to see if there was a constant folding opportunity when you call it. -If so, it could just do the constant fold and return the constant instead of -creating an instruction. This is exactly what the LLVMFoldingBuilder -class does. - -

All we did was switch from LLVMBuilder to -LLVMFoldingBuilder. Though we change no other code, we now have all of our -instructions implicitly constant folded without us having to do anything -about it. For example, the input above now compiles to:

- -
-
-ready> def test(x) 1+2+x;
-Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 3.000000e+00, %x
-        ret double %addtmp
-}
-
-
- -

Well, that was easy :). In practice, we recommend always using -LLVMFoldingBuilder when generating code like this. It has no -"syntactic overhead" for its use (you don't have to uglify your compiler with -constant checks everywhere) and it can dramatically reduce the amount of -LLVM IR that is generated in some cases (particular for languages with a macro -preprocessor or that use a lot of constants).

- -

On the other hand, the LLVMFoldingBuilder is limited by the fact -that it does all of its analysis inline with the code as it is built. If you -take a slightly more complex example:

- -
-
-ready> def test(x) (1+2+x)*(x+(1+2));
-ready> Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double 3.000000e+00, %x
-        %addtmp1 = fadd double %x, 3.000000e+00
-        %multmp = fmul double %addtmp, %addtmp1
-        ret double %multmp
-}
-
-
- -

In this case, the LHS and RHS of the multiplication are the same value. We'd -really like to see this generate "tmp = x+3; result = tmp*tmp;" instead -of computing "x*3" twice.

- -

Unfortunately, no amount of local analysis will be able to detect and correct -this. This requires two transformations: reassociation of expressions (to -make the add's lexically identical) and Common Subexpression Elimination (CSE) -to delete the redundant add instruction. Fortunately, LLVM provides a broad -range of optimizations that you can use, in the form of "passes".

- -
- - -

LLVM Optimization Passes

- - -
- -

LLVM provides many optimization passes, which do many different sorts of -things and have different tradeoffs. Unlike other systems, LLVM doesn't hold -to the mistaken notion that one set of optimizations is right for all languages -and for all situations. LLVM allows a compiler implementor to make complete -decisions about what optimizations to use, in which order, and in what -situation.

- -

As a concrete example, LLVM supports both "whole module" passes, which look -across as large of body of code as they can (often a whole file, but if run -at link time, this can be a substantial portion of the whole program). It also -supports and includes "per-function" passes which just operate on a single -function at a time, without looking at other functions. For more information -on passes and how they are run, see the How -to Write a Pass document and the List of LLVM -Passes.

- -

For Kaleidoscope, we are currently generating functions on the fly, one at -a time, as the user types them in. We aren't shooting for the ultimate -optimization experience in this setting, but we also want to catch the easy and -quick stuff where possible. As such, we will choose to run a few per-function -optimizations as the user types the function in. If we wanted to make a "static -Kaleidoscope compiler", we would use exactly the code we have now, except that -we would defer running the optimizer until the entire file has been parsed.

- -

In order to get per-function optimizations going, we need to set up a -Llvm.PassManager to hold and -organize the LLVM optimizations that we want to run. Once we have that, we can -add a set of optimizations to run. The code looks like this:

- -
-
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combining the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-  (* Eliminate Common SubExpressions. *)
-  add_gvn the_fpm;
-
-  (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
-  add_cfg_simplification the_fpm;
-
-  ignore (PassManager.initialize the_fpm);
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop the_fpm the_execution_engine stream;
-
-
- -

The meat of the matter here, is the definition of "the_fpm". It -requires a pointer to the the_module to construct itself. Once it is -set up, we use a series of "add" calls to add a bunch of LLVM passes. The -first pass is basically boilerplate, it adds a pass so that later optimizations -know how the data structures in the program are laid out. The -"the_execution_engine" variable is related to the JIT, which we will -get to in the next section.

- -

In this case, we choose to add 4 optimization passes. The passes we chose -here are a pretty standard set of "cleanup" optimizations that are useful for -a wide variety of code. I won't delve into what they do but, believe me, -they are a good starting place :).

- -

Once the Llvm.PassManager. is set up, we need to make use of it. -We do this by running it after our newly created function is constructed (in -Codegen.codegen_func), but before it is returned to the client:

- -
-
-let codegen_func the_fpm = function
-      ...
-      try
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        (* Optimize the function. *)
-        let _ = PassManager.run_function the_function the_fpm in
-
-        the_function
-
-
- -

As you can see, this is pretty straightforward. The the_fpm -optimizes and updates the LLVM Function* in place, improving (hopefully) its -body. With this in place, we can try our test above again:

- -
-
-ready> def test(x) (1+2+x)*(x+(1+2));
-ready> Read function definition:
-define double @test(double %x) {
-entry:
-        %addtmp = fadd double %x, 3.000000e+00
-        %multmp = fmul double %addtmp, %addtmp
-        ret double %multmp
-}
-
-
- -

As expected, we now get our nicely optimized code, saving a floating point -add instruction from every execution of this function.

- -

LLVM provides a wide variety of optimizations that can be used in certain -circumstances. Some documentation about the various -passes is available, but it isn't very complete. Another good source of -ideas can come from looking at the passes that llvm-gcc or -llvm-ld run to get started. The "opt" tool allows you to -experiment with passes from the command line, so you can see if they do -anything.

- -

Now that we have reasonable code coming out of our front-end, lets talk about -executing it!

- -
- - -

Adding a JIT Compiler

- - -
- -

Code that is available in LLVM IR can have a wide variety of tools -applied to it. For example, you can run optimizations on it (as we did above), -you can dump it out in textual or binary forms, you can compile the code to an -assembly file (.s) for some target, or you can JIT compile it. The nice thing -about the LLVM IR representation is that it is the "common currency" between -many different parts of the compiler. -

- -

In this section, we'll add JIT compiler support to our interpreter. The -basic idea that we want for Kaleidoscope is to have the user enter function -bodies as they do now, but immediately evaluate the top-level expressions they -type in. For example, if they type in "1 + 2;", we should evaluate and print -out 3. If they define a function, they should be able to call it from the -command line.

- -

In order to do this, we first declare and initialize the JIT. This is done -by adding a global variable and a call in main:

- -
-
-...
-let main () =
-  ...
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  ...
-
-
- -

This creates an abstract "Execution Engine" which can be either a JIT -compiler or the LLVM interpreter. LLVM will automatically pick a JIT compiler -for you if one is available for your platform, otherwise it will fall back to -the interpreter.

- -

Once the Llvm_executionengine.ExecutionEngine.t is created, the JIT -is ready to be used. There are a variety of APIs that are useful, but the -simplest one is the "Llvm_executionengine.ExecutionEngine.run_function" -function. This method JIT compiles the specified LLVM Function and returns a -function pointer to the generated machine code. In our case, this means that we -can change the code that parses a top-level expression to look like this:

- -
-
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            let the_function = Codegen.codegen_func the_fpm e in
-            dump_value the_function;
-
-            (* JIT the function, returning a function pointer. *)
-            let result = ExecutionEngine.run_function the_function [||]
-              the_execution_engine in
-
-            print_string "Evaluated to ";
-            print_float (GenericValue.as_float Codegen.double_type result);
-            print_newline ();
-
-
- -

Recall that we compile top-level expressions into a self-contained LLVM -function that takes no arguments and returns the computed double. Because the -LLVM JIT compiler matches the native platform ABI, this means that you can just -cast the result pointer to a function pointer of that type and call it directly. -This means, there is no difference between JIT compiled code and native machine -code that is statically linked into your application.

- -

With just these two changes, lets see how Kaleidoscope works now!

- -
-
-ready> 4+5;
-define double @""() {
-entry:
-        ret double 9.000000e+00
-}
-
-Evaluated to 9.000000
-
-
- -

Well this looks like it is basically working. The dump of the function -shows the "no argument function that always returns double" that we synthesize -for each top level expression that is typed in. This demonstrates very basic -functionality, but can we do more?

- -
-
-ready> def testfunc(x y) x + y*2; 
-Read function definition:
-define double @testfunc(double %x, double %y) {
-entry:
-        %multmp = fmul double %y, 2.000000e+00
-        %addtmp = fadd double %multmp, %x
-        ret double %addtmp
-}
-
-ready> testfunc(4, 10);
-define double @""() {
-entry:
-        %calltmp = call double @testfunc(double 4.000000e+00, double 1.000000e+01)
-        ret double %calltmp
-}
-
-Evaluated to 24.000000
-
-
- -

This illustrates that we can now call user code, but there is something a bit -subtle going on here. Note that we only invoke the JIT on the anonymous -functions that call testfunc, but we never invoked it -on testfunc itself. What actually happened here is that the JIT -scanned for all non-JIT'd functions transitively called from the anonymous -function and compiled all of them before returning -from run_function.

- -

The JIT provides a number of other more advanced interfaces for things like -freeing allocated machine code, rejit'ing functions to update them, etc. -However, even with this simple code, we get some surprisingly powerful -capabilities - check this out (I removed the dump of the anonymous functions, -you should get the idea by now :) :

- -
-
-ready> extern sin(x);
-Read extern:
-declare double @sin(double)
-
-ready> extern cos(x);
-Read extern:
-declare double @cos(double)
-
-ready> sin(1.0);
-Evaluated to 0.841471
-
-ready> def foo(x) sin(x)*sin(x) + cos(x)*cos(x);
-Read function definition:
-define double @foo(double %x) {
-entry:
-        %calltmp = call double @sin(double %x)
-        %multmp = fmul double %calltmp, %calltmp
-        %calltmp2 = call double @cos(double %x)
-        %multmp4 = fmul double %calltmp2, %calltmp2
-        %addtmp = fadd double %multmp, %multmp4
-        ret double %addtmp
-}
-
-ready> foo(4.0);
-Evaluated to 1.000000
-
-
- -

Whoa, how does the JIT know about sin and cos? The answer is surprisingly -simple: in this example, the JIT started execution of a function and got to a -function call. It realized that the function was not yet JIT compiled and -invoked the standard set of routines to resolve the function. In this case, -there is no body defined for the function, so the JIT ended up calling -"dlsym("sin")" on the Kaleidoscope process itself. Since -"sin" is defined within the JIT's address space, it simply patches up -calls in the module to call the libm version of sin directly.

- -

The LLVM JIT provides a number of interfaces (look in the -llvm_executionengine.mli file) for controlling how unknown functions -get resolved. It allows you to establish explicit mappings between IR objects -and addresses (useful for LLVM global variables that you want to map to static -tables, for example), allows you to dynamically decide on the fly based on the -function name, and even allows you to have the JIT compile functions lazily the -first time they're called.

- -

One interesting application of this is that we can now extend the language -by writing arbitrary C code to implement operations. For example, if we add: -

- -
-
-/* putchard - putchar that takes a double and returns 0. */
-extern "C"
-double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-
- -

Now we can produce simple output to the console by using things like: -"extern putchard(x); putchard(120);", which prints a lowercase 'x' on -the console (120 is the ASCII code for 'x'). Similar code could be used to -implement file I/O, console input, and many other capabilities in -Kaleidoscope.

- -

This completes the JIT and optimizer chapter of the Kaleidoscope tutorial. At -this point, we can compile a non-Turing-complete programming language, optimize -and JIT compile it in a user-driven way. Next up we'll look into extending the language with control flow -constructs, tackling some interesting LLVM IR issues along the way.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -LLVM JIT and optimizer. To build this example, use: -

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
-<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
-<*.{byte,native}>: use_llvm_scalar_opts, use_bindings
-
-
- -
myocamlbuild.ml:
-
-
-open Ocamlbuild_plugin;;
-
-ocaml_lib ~extern:true "llvm";;
-ocaml_lib ~extern:true "llvm_analysis";;
-ocaml_lib ~extern:true "llvm_executionengine";;
-ocaml_lib ~extern:true "llvm_target";;
-ocaml_lib ~extern:true "llvm_scalar_opts";;
-
-flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
-dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto = Prototype of string * string array
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the primary expression after the binary operator. *)
-        let rhs = parse_primary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')' *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
codegen.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Code Generation
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-let rec codegen_expr = function
-  | Ast.Number n -> const_float double_type n
-  | Ast.Variable name ->
-      (try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name"))
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_add lhs_val rhs_val "addtmp" builder
-        | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_mul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ -> raise (Error "invalid binary operator")
-      end
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-        | None -> declare_function name ft the_module
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if block_begin f <> At_end f then
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if element_type (type_of f) <> ft then
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-let codegen_func the_fpm = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        (* Optimize the function. *)
-        let _ = PassManager.run_function the_function the_fpm in
-
-        the_function
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop the_fpm the_execution_engine stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop the_fpm the_execution_engine stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            let e = Parser.parse_definition stream in
-            print_endline "parsed a function definition.";
-            dump_value (Codegen.codegen_func the_fpm e);
-        | Token.Extern ->
-            let e = Parser.parse_extern stream in
-            print_endline "parsed an extern.";
-            dump_value (Codegen.codegen_proto e);
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            let the_function = Codegen.codegen_func the_fpm e in
-            dump_value the_function;
-
-            (* JIT the function, returning a function pointer. *)
-            let result = ExecutionEngine.run_function the_function [||]
-              the_execution_engine in
-
-            print_string "Evaluated to ";
-            print_float (GenericValue.as_float Codegen.double_type result);
-            print_newline ();
-        with Stream.Error s | Codegen.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop the_fpm the_execution_engine stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-open Llvm_target
-open Llvm_scalar_opts
-
-let main () =
-  ignore (initialize_native_target ());
-
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combination the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-  (* Eliminate Common SubExpressions. *)
-  add_gvn the_fpm;
-
-  (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
-  add_cfg_simplification the_fpm;
-
-  ignore (PassManager.initialize the_fpm);
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop the_fpm the_execution_engine stream;
-
-  (* Print out all the generated code. *)
-  dump_module Codegen.the_module
-;;
-
-main ()
-
-
- -
bindings.c
-
-
-#include <stdio.h>
-
-/* putchard - putchar that takes a double and returns 0. */
-extern double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-
-
- -Next: Extending the language: control flow -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl5.html b/cpp/llvm/docs/tutorial/OCamlLangImpl5.html deleted file mode 100644 index d0912e22..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl5.html +++ /dev/null @@ -1,1560 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: Control Flow - - - - - - - - -

Kaleidoscope: Extending the Language: Control Flow

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 5 Introduction

- - -
- -

Welcome to Chapter 5 of the "Implementing a language -with LLVM" tutorial. Parts 1-4 described the implementation of the simple -Kaleidoscope language and included support for generating LLVM IR, followed by -optimizations and a JIT compiler. Unfortunately, as presented, Kaleidoscope is -mostly useless: it has no control flow other than call and return. This means -that you can't have conditional branches in the code, significantly limiting its -power. In this episode of "build that compiler", we'll extend Kaleidoscope to -have an if/then/else expression plus a simple 'for' loop.

- -
- - -

If/Then/Else

- - -
- -

-Extending Kaleidoscope to support if/then/else is quite straightforward. It -basically requires adding lexer support for this "new" concept to the lexer, -parser, AST, and LLVM code emitter. This example is nice, because it shows how -easy it is to "grow" a language over time, incrementally extending it as new -ideas are discovered.

- -

Before we get going on "how" we add this extension, lets talk about "what" we -want. The basic idea is that we want to be able to write this sort of thing: -

- -
-
-def fib(x)
-  if x < 3 then
-    1
-  else
-    fib(x-1)+fib(x-2);
-
-
- -

In Kaleidoscope, every construct is an expression: there are no statements. -As such, the if/then/else expression needs to return a value like any other. -Since we're using a mostly functional form, we'll have it evaluate its -conditional, then return the 'then' or 'else' value based on how the condition -was resolved. This is very similar to the C "?:" expression.

- -

The semantics of the if/then/else expression is that it evaluates the -condition to a boolean equality value: 0.0 is considered to be false and -everything else is considered to be true. -If the condition is true, the first subexpression is evaluated and returned, if -the condition is false, the second subexpression is evaluated and returned. -Since Kaleidoscope allows side-effects, this behavior is important to nail down. -

- -

Now that we know what we "want", lets break this down into its constituent -pieces.

- - -

Lexer Extensions for If/Then/Else

- - - -
- -

The lexer extensions are straightforward. First we add new variants -for the relevant tokens:

- -
-
-  (* control *)
-  | If | Then | Else | For | In
-
-
- -

Once we have that, we recognize the new keywords in the lexer. This is pretty simple -stuff:

- -
-
-      ...
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | "if" -> [< 'Token.If; stream >]
-      | "then" -> [< 'Token.Then; stream >]
-      | "else" -> [< 'Token.Else; stream >]
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-
- -
- - -

AST Extensions for If/Then/Else

- - -
- -

To represent the new expression we add a new AST variant for it:

- -
-
-type expr =
-  ...
-  (* variant for if/then/else. *)
-  | If of expr * expr * expr
-
-
- -

The AST variant just has pointers to the various subexpressions.

- -
- - -

Parser Extensions for If/Then/Else

- - -
- -

Now that we have the relevant tokens coming from the lexer and we have the -AST node to build, our parsing logic is relatively straightforward. First we -define a new parsing function:

- -
-
-let rec parse_primary = parser
-  ...
-  (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
-  | [< 'Token.If; c=parse_expr;
-       'Token.Then ?? "expected 'then'"; t=parse_expr;
-       'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
-      Ast.If (c, t, e)
-
-
- -

Next we hook it up as a primary expression:

- -
-
-let rec parse_primary = parser
-  ...
-  (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
-  | [< 'Token.If; c=parse_expr;
-       'Token.Then ?? "expected 'then'"; t=parse_expr;
-       'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
-      Ast.If (c, t, e)
-
-
- -
- - -

LLVM IR for If/Then/Else

- - -
- -

Now that we have it parsing and building the AST, the final piece is adding -LLVM code generation support. This is the most interesting part of the -if/then/else example, because this is where it starts to introduce new concepts. -All of the code above has been thoroughly described in previous chapters. -

- -

To motivate the code we want to produce, lets take a look at a simple -example. Consider:

- -
-
-extern foo();
-extern bar();
-def baz(x) if x then foo() else bar();
-
-
- -

If you disable optimizations, the code you'll (soon) get from Kaleidoscope -looks like this:

- -
-
-declare double @foo()
-
-declare double @bar()
-
-define double @baz(double %x) {
-entry:
-  %ifcond = fcmp one double %x, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:    ; preds = %entry
-  %calltmp = call double @foo()
-  br label %ifcont
-
-else:    ; preds = %entry
-  %calltmp1 = call double @bar()
-  br label %ifcont
-
-ifcont:    ; preds = %else, %then
-  %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
-  ret double %iftmp
-}
-
-
- -

To visualize the control flow graph, you can use a nifty feature of the LLVM -'opt' tool. If you put this LLVM IR -into "t.ll" and run "llvm-as < t.ll | opt -analyze -view-cfg", a window will pop up and you'll -see this graph:

- -
Example CFG
- -

Another way to get this is to call "Llvm_analysis.view_function_cfg -f" or "Llvm_analysis.view_function_cfg_only f" (where f -is a "Function") either by inserting actual calls into the code and -recompiling or by calling these in the debugger. LLVM has many nice features -for visualizing various graphs.

- -

Getting back to the generated code, it is fairly simple: the entry block -evaluates the conditional expression ("x" in our case here) and compares the -result to 0.0 with the "fcmp one" -instruction ('one' is "Ordered and Not Equal"). Based on the result of this -expression, the code jumps to either the "then" or "else" blocks, which contain -the expressions for the true/false cases.

- -

Once the then/else blocks are finished executing, they both branch back to the -'ifcont' block to execute the code that happens after the if/then/else. In this -case the only thing left to do is to return to the caller of the function. The -question then becomes: how does the code know which expression to return?

- -

The answer to this question involves an important SSA operation: the -Phi -operation. If you're not familiar with SSA, the wikipedia -article is a good introduction and there are various other introductions to -it available on your favorite search engine. The short version is that -"execution" of the Phi operation requires "remembering" which block control came -from. The Phi operation takes on the value corresponding to the input control -block. In this case, if control comes in from the "then" block, it gets the -value of "calltmp". If control comes from the "else" block, it gets the value -of "calltmp1".

- -

At this point, you are probably starting to think "Oh no! This means my -simple and elegant front-end will have to start generating SSA form in order to -use LLVM!". Fortunately, this is not the case, and we strongly advise -not implementing an SSA construction algorithm in your front-end -unless there is an amazingly good reason to do so. In practice, there are two -sorts of values that float around in code written for your average imperative -programming language that might need Phi nodes:

- -
    -
  1. Code that involves user variables: x = 1; x = x + 1;
  2. -
  3. Values that are implicit in the structure of your AST, such as the Phi node -in this case.
  4. -
- -

In Chapter 7 of this tutorial ("mutable -variables"), we'll talk about #1 -in depth. For now, just believe me that you don't need SSA construction to -handle this case. For #2, you have the choice of using the techniques that we will -describe for #1, or you can insert Phi nodes directly, if convenient. In this -case, it is really really easy to generate the Phi node, so we choose to do it -directly.

- -

Okay, enough of the motivation and overview, lets generate code!

- -
- - -

Code Generation for If/Then/Else

- - -
- -

In order to generate code for this, we implement the Codegen method -for IfExprAST:

- -
-
-let rec codegen_expr = function
-  ...
-  | Ast.If (cond, then_, else_) ->
-      let cond = codegen_expr cond in
-
-      (* Convert condition to a bool by comparing equal to 0.0 *)
-      let zero = const_float double_type 0.0 in
-      let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
-
-
- -

This code is straightforward and similar to what we saw before. We emit the -expression for the condition, then compare that value to zero to get a truth -value as a 1-bit (bool) value.

- -
-
-      (* Grab the first block so that we might later add the conditional branch
-       * to it at the end of the function. *)
-      let start_bb = insertion_block builder in
-      let the_function = block_parent start_bb in
-
-      let then_bb = append_block context "then" the_function in
-      position_at_end then_bb builder;
-
-
- -

-As opposed to the C++ tutorial, we have to build -our basic blocks bottom up since we can't have dangling BasicBlocks. We start -off by saving a pointer to the first block (which might not be the entry -block), which we'll need to build a conditional branch later. We do this by -asking the builder for the current BasicBlock. The fourth line -gets the current Function object that is being built. It gets this by the -start_bb for its "parent" (the function it is currently embedded -into).

- -

Once it has that, it creates one block. It is automatically appended into -the function's list of blocks.

- -
-
-      (* Emit 'then' value. *)
-      position_at_end then_bb builder;
-      let then_val = codegen_expr then_ in
-
-      (* Codegen of 'then' can change the current block, update then_bb for the
-       * phi. We create a new name because one is used for the phi node, and the
-       * other is used for the conditional branch. *)
-      let new_then_bb = insertion_block builder in
-
-
- -

We move the builder to start inserting into the "then" block. Strictly -speaking, this call moves the insertion point to be at the end of the specified -block. However, since the "then" block is empty, it also starts out by -inserting at the beginning of the block. :)

- -

Once the insertion point is set, we recursively codegen the "then" expression -from the AST.

- -

The final line here is quite subtle, but is very important. The basic issue -is that when we create the Phi node in the merge block, we need to set up the -block/value pairs that indicate how the Phi will work. Importantly, the Phi -node expects to have an entry for each predecessor of the block in the CFG. Why -then, are we getting the current block when we just set it to ThenBB 5 lines -above? The problem is that the "Then" expression may actually itself change the -block that the Builder is emitting into if, for example, it contains a nested -"if/then/else" expression. Because calling Codegen recursively could -arbitrarily change the notion of the current block, we are required to get an -up-to-date value for code that will set up the Phi node.

- -
-
-      (* Emit 'else' value. *)
-      let else_bb = append_block context "else" the_function in
-      position_at_end else_bb builder;
-      let else_val = codegen_expr else_ in
-
-      (* Codegen of 'else' can change the current block, update else_bb for the
-       * phi. *)
-      let new_else_bb = insertion_block builder in
-
-
- -

Code generation for the 'else' block is basically identical to codegen for -the 'then' block.

- -
-
-      (* Emit merge block. *)
-      let merge_bb = append_block context "ifcont" the_function in
-      position_at_end merge_bb builder;
-      let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
-      let phi = build_phi incoming "iftmp" builder in
-
-
- -

The first two lines here are now familiar: the first adds the "merge" block -to the Function object. The second block changes the insertion point so that -newly created code will go into the "merge" block. Once that is done, we need -to create the PHI node and set up the block/value pairs for the PHI.

- -
-
-      (* Return to the start block to add the conditional branch. *)
-      position_at_end start_bb builder;
-      ignore (build_cond_br cond_val then_bb else_bb builder);
-
-
- -

Once the blocks are created, we can emit the conditional branch that chooses -between them. Note that creating new blocks does not implicitly affect the -IRBuilder, so it is still inserting into the block that the condition -went into. This is why we needed to save the "start" block.

- -
-
-      (* Set a unconditional branch at the end of the 'then' block and the
-       * 'else' block to the 'merge' block. *)
-      position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
-      position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
-
-      (* Finally, set the builder to the end of the merge block. *)
-      position_at_end merge_bb builder;
-
-      phi
-
-
- -

To finish off the blocks, we create an unconditional branch -to the merge block. One interesting (and very important) aspect of the LLVM IR -is that it requires all basic blocks -to be "terminated" with a control flow -instruction such as return or branch. This means that all control flow, -including fall throughs must be made explicit in the LLVM IR. If you -violate this rule, the verifier will emit an error. - -

Finally, the CodeGen function returns the phi node as the value computed by -the if/then/else expression. In our example above, this returned value will -feed into the code for the top-level function, which will create the return -instruction.

- -

Overall, we now have the ability to execute conditional code in -Kaleidoscope. With this extension, Kaleidoscope is a fairly complete language -that can calculate a wide variety of numeric functions. Next up we'll add -another useful expression that is familiar from non-functional languages...

- -
- -
- - -

'for' Loop Expression

- - -
- -

Now that we know how to add basic control flow constructs to the language, -we have the tools to add more powerful things. Lets add something more -aggressive, a 'for' expression:

- -
-
- extern putchard(char);
- def printstar(n)
-   for i = 1, i < n, 1.0 in
-     putchard(42);  # ascii 42 = '*'
-
- # print 100 '*' characters
- printstar(100);
-
-
- -

This expression defines a new variable ("i" in this case) which iterates from -a starting value, while the condition ("i < n" in this case) is true, -incrementing by an optional step value ("1.0" in this case). If the step value -is omitted, it defaults to 1.0. While the loop is true, it executes its -body expression. Because we don't have anything better to return, we'll just -define the loop as always returning 0.0. In the future when we have mutable -variables, it will get more useful.

- -

As before, lets talk about the changes that we need to Kaleidoscope to -support this.

- - -

Lexer Extensions for the 'for' Loop

- - -
- -

The lexer extensions are the same sort of thing as for if/then/else:

- -
-
-  ... in Token.token ...
-  (* control *)
-  | If | Then | Else
-  | For | In
-
-  ... in Lexer.lex_ident...
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | "if" -> [< 'Token.If; stream >]
-      | "then" -> [< 'Token.Then; stream >]
-      | "else" -> [< 'Token.Else; stream >]
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-
- -
- - -

AST Extensions for the 'for' Loop

- - -
- -

The AST variant is just as simple. It basically boils down to capturing -the variable name and the constituent expressions in the node.

- -
-
-type expr =
-  ...
-  (* variant for for/in. *)
-  | For of string * expr * expr * expr option * expr
-
-
- -
- - -

Parser Extensions for the 'for' Loop

- - -
- -

The parser code is also fairly standard. The only interesting thing here is -handling of the optional step value. The parser code handles it by checking to -see if the second comma is present. If not, it sets the step value to null in -the AST node:

- -
-
-let rec parse_primary = parser
-  ...
-  (* forexpr
-        ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
-  | [< 'Token.For;
-       'Token.Ident id ?? "expected identifier after for";
-       'Token.Kwd '=' ?? "expected '=' after for";
-       stream >] ->
-      begin parser
-        | [<
-             start=parse_expr;
-             'Token.Kwd ',' ?? "expected ',' after for";
-             end_=parse_expr;
-             stream >] ->
-            let step =
-              begin parser
-              | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
-              | [< >] -> None
-              end stream
-            in
-            begin parser
-            | [< 'Token.In; body=parse_expr >] ->
-                Ast.For (id, start, end_, step, body)
-            | [< >] ->
-                raise (Stream.Error "expected 'in' after for")
-            end stream
-        | [< >] ->
-            raise (Stream.Error "expected '=' after for")
-      end stream
-
-
- -
- - -

LLVM IR for the 'for' Loop

- - -
- -

Now we get to the good part: the LLVM IR we want to generate for this thing. -With the simple example above, we get this LLVM IR (note that this dump is -generated with optimizations disabled for clarity): -

- -
-
-declare double @putchard(double)
-
-define double @printstar(double %n) {
-entry:
-        ; initial value = 1.0 (inlined into phi)
-  br label %loop
-
-loop:    ; preds = %loop, %entry
-  %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
-        ; body
-  %calltmp = call double @putchard(double 4.200000e+01)
-        ; increment
-  %nextvar = fadd double %i, 1.000000e+00
-
-        ; termination test
-  %cmptmp = fcmp ult double %i, %n
-  %booltmp = uitofp i1 %cmptmp to double
-  %loopcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %loopcond, label %loop, label %afterloop
-
-afterloop:    ; preds = %loop
-        ; loop always returns 0.0
-  ret double 0.000000e+00
-}
-
-
- -

This loop contains all the same constructs we saw before: a phi node, several -expressions, and some basic blocks. Lets see how this fits together.

- -
- - -

Code Generation for the 'for' Loop

- - -
- -

The first part of Codegen is very simple: we just output the start expression -for the loop value:

- -
-
-let rec codegen_expr = function
-  ...
-  | Ast.For (var_name, start, end_, step, body) ->
-      (* Emit the start code first, without 'variable' in scope. *)
-      let start_val = codegen_expr start in
-
-
- -

With this out of the way, the next step is to set up the LLVM basic block -for the start of the loop body. In the case above, the whole loop body is one -block, but remember that the body code itself could consist of multiple blocks -(e.g. if it contains an if/then/else or a for/in expression).

- -
-
-      (* Make the new basic block for the loop header, inserting after current
-       * block. *)
-      let preheader_bb = insertion_block builder in
-      let the_function = block_parent preheader_bb in
-      let loop_bb = append_block context "loop" the_function in
-
-      (* Insert an explicit fall through from the current block to the
-       * loop_bb. *)
-      ignore (build_br loop_bb builder);
-
-
- -

This code is similar to what we saw for if/then/else. Because we will need -it to create the Phi node, we remember the block that falls through into the -loop. Once we have that, we create the actual block that starts the loop and -create an unconditional branch for the fall-through between the two blocks.

- -
-
-      (* Start insertion in loop_bb. *)
-      position_at_end loop_bb builder;
-
-      (* Start the PHI node with an entry for start. *)
-      let variable = build_phi [(start_val, preheader_bb)] var_name builder in
-
-
- -

Now that the "preheader" for the loop is set up, we switch to emitting code -for the loop body. To begin with, we move the insertion point and create the -PHI node for the loop induction variable. Since we already know the incoming -value for the starting value, we add it to the Phi node. Note that the Phi will -eventually get a second value for the backedge, but we can't set it up yet -(because it doesn't exist!).

- -
-
-      (* Within the loop, the variable is defined equal to the PHI node. If it
-       * shadows an existing variable, we have to restore it, so save it
-       * now. *)
-      let old_val =
-        try Some (Hashtbl.find named_values var_name) with Not_found -> None
-      in
-      Hashtbl.add named_values var_name variable;
-
-      (* Emit the body of the loop.  This, like any other expr, can change the
-       * current BB.  Note that we ignore the value computed by the body, but
-       * don't allow an error *)
-      ignore (codegen_expr body);
-
-
- -

Now the code starts to get more interesting. Our 'for' loop introduces a new -variable to the symbol table. This means that our symbol table can now contain -either function arguments or loop variables. To handle this, before we codegen -the body of the loop, we add the loop variable as the current value for its -name. Note that it is possible that there is a variable of the same name in the -outer scope. It would be easy to make this an error (emit an error and return -null if there is already an entry for VarName) but we choose to allow shadowing -of variables. In order to handle this correctly, we remember the Value that -we are potentially shadowing in old_val (which will be None if there is -no shadowed variable).

- -

Once the loop variable is set into the symbol table, the code recursively -codegen's the body. This allows the body to use the loop variable: any -references to it will naturally find it in the symbol table.

- -
-
-      (* Emit the step value. *)
-      let step_val =
-        match step with
-        | Some step -> codegen_expr step
-        (* If not specified, use 1.0. *)
-        | None -> const_float double_type 1.0
-      in
-
-      let next_var = build_add variable step_val "nextvar" builder in
-
-
- -

Now that the body is emitted, we compute the next value of the iteration -variable by adding the step value, or 1.0 if it isn't present. -'next_var' will be the value of the loop variable on the next iteration -of the loop.

- -
-
-      (* Compute the end condition. *)
-      let end_cond = codegen_expr end_ in
-
-      (* Convert condition to a bool by comparing equal to 0.0. *)
-      let zero = const_float double_type 0.0 in
-      let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
-
-
- -

Finally, we evaluate the exit value of the loop, to determine whether the -loop should exit. This mirrors the condition evaluation for the if/then/else -statement.

- -
-
-      (* Create the "after loop" block and insert it. *)
-      let loop_end_bb = insertion_block builder in
-      let after_bb = append_block context "afterloop" the_function in
-
-      (* Insert the conditional branch into the end of loop_end_bb. *)
-      ignore (build_cond_br end_cond loop_bb after_bb builder);
-
-      (* Any new code will be inserted in after_bb. *)
-      position_at_end after_bb builder;
-
-
- -

With the code for the body of the loop complete, we just need to finish up -the control flow for it. This code remembers the end block (for the phi node), then creates the block for the loop exit ("afterloop"). Based on the value of the -exit condition, it creates a conditional branch that chooses between executing -the loop again and exiting the loop. Any future code is emitted in the -"afterloop" block, so it sets the insertion position to it.

- -
-
-      (* Add a new entry to the PHI node for the backedge. *)
-      add_incoming (next_var, loop_end_bb) variable;
-
-      (* Restore the unshadowed variable. *)
-      begin match old_val with
-      | Some old_val -> Hashtbl.add named_values var_name old_val
-      | None -> ()
-      end;
-
-      (* for expr always returns 0.0. *)
-      const_null double_type
-
-
- -

The final code handles various cleanups: now that we have the -"next_var" value, we can add the incoming value to the loop PHI node. -After that, we remove the loop variable from the symbol table, so that it isn't -in scope after the for loop. Finally, code generation of the for loop always -returns 0.0, so that is what we return from Codegen.codegen_expr.

- -

With this, we conclude the "adding control flow to Kaleidoscope" chapter of -the tutorial. In this chapter we added two control flow constructs, and used -them to motivate a couple of aspects of the LLVM IR that are important for -front-end implementors to know. In the next chapter of our saga, we will get -a bit crazier and add user-defined operators -to our poor innocent language.

- -
- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -if/then/else and for expressions.. To build this example, use: -

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
-<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
-<*.{byte,native}>: use_llvm_scalar_opts, use_bindings
-
-
- -
myocamlbuild.ml:
-
-
-open Ocamlbuild_plugin;;
-
-ocaml_lib ~extern:true "llvm";;
-ocaml_lib ~extern:true "llvm_analysis";;
-ocaml_lib ~extern:true "llvm_executionengine";;
-ocaml_lib ~extern:true "llvm_target";;
-ocaml_lib ~extern:true "llvm_scalar_opts";;
-
-flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
-dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-  (* control *)
-  | If | Then | Else
-  | For | In
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | "if" -> [< 'Token.If; stream >]
-      | "then" -> [< 'Token.Then; stream >]
-      | "else" -> [< 'Token.Else; stream >]
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-  (* variant for if/then/else. *)
-  | If of expr * expr * expr
-
-  (* variant for for/in. *)
-  | For of string * expr * expr * expr option * expr
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto = Prototype of string * string array
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr
- *   ::= ifexpr
- *   ::= forexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
-  | [< 'Token.If; c=parse_expr;
-       'Token.Then ?? "expected 'then'"; t=parse_expr;
-       'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
-      Ast.If (c, t, e)
-
-  (* forexpr
-        ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
-  | [< 'Token.For;
-       'Token.Ident id ?? "expected identifier after for";
-       'Token.Kwd '=' ?? "expected '=' after for";
-       stream >] ->
-      begin parser
-        | [<
-             start=parse_expr;
-             'Token.Kwd ',' ?? "expected ',' after for";
-             end_=parse_expr;
-             stream >] ->
-            let step =
-              begin parser
-              | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
-              | [< >] -> None
-              end stream
-            in
-            begin parser
-            | [< 'Token.In; body=parse_expr >] ->
-                Ast.For (id, start, end_, step, body)
-            | [< >] ->
-                raise (Stream.Error "expected 'in' after for")
-            end stream
-        | [< >] ->
-            raise (Stream.Error "expected '=' after for")
-      end stream
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the primary expression after the binary operator. *)
-        let rhs = parse_primary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')' *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
codegen.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Code Generation
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-let rec codegen_expr = function
-  | Ast.Number n -> const_float double_type n
-  | Ast.Variable name ->
-      (try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name"))
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_add lhs_val rhs_val "addtmp" builder
-        | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_mul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ -> raise (Error "invalid binary operator")
-      end
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-  | Ast.If (cond, then_, else_) ->
-      let cond = codegen_expr cond in
-
-      (* Convert condition to a bool by comparing equal to 0.0 *)
-      let zero = const_float double_type 0.0 in
-      let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
-
-      (* Grab the first block so that we might later add the conditional branch
-       * to it at the end of the function. *)
-      let start_bb = insertion_block builder in
-      let the_function = block_parent start_bb in
-
-      let then_bb = append_block context "then" the_function in
-
-      (* Emit 'then' value. *)
-      position_at_end then_bb builder;
-      let then_val = codegen_expr then_ in
-
-      (* Codegen of 'then' can change the current block, update then_bb for the
-       * phi. We create a new name because one is used for the phi node, and the
-       * other is used for the conditional branch. *)
-      let new_then_bb = insertion_block builder in
-
-      (* Emit 'else' value. *)
-      let else_bb = append_block context "else" the_function in
-      position_at_end else_bb builder;
-      let else_val = codegen_expr else_ in
-
-      (* Codegen of 'else' can change the current block, update else_bb for the
-       * phi. *)
-      let new_else_bb = insertion_block builder in
-
-      (* Emit merge block. *)
-      let merge_bb = append_block context "ifcont" the_function in
-      position_at_end merge_bb builder;
-      let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
-      let phi = build_phi incoming "iftmp" builder in
-
-      (* Return to the start block to add the conditional branch. *)
-      position_at_end start_bb builder;
-      ignore (build_cond_br cond_val then_bb else_bb builder);
-
-      (* Set a unconditional branch at the end of the 'then' block and the
-       * 'else' block to the 'merge' block. *)
-      position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
-      position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
-
-      (* Finally, set the builder to the end of the merge block. *)
-      position_at_end merge_bb builder;
-
-      phi
-  | Ast.For (var_name, start, end_, step, body) ->
-      (* Emit the start code first, without 'variable' in scope. *)
-      let start_val = codegen_expr start in
-
-      (* Make the new basic block for the loop header, inserting after current
-       * block. *)
-      let preheader_bb = insertion_block builder in
-      let the_function = block_parent preheader_bb in
-      let loop_bb = append_block context "loop" the_function in
-
-      (* Insert an explicit fall through from the current block to the
-       * loop_bb. *)
-      ignore (build_br loop_bb builder);
-
-      (* Start insertion in loop_bb. *)
-      position_at_end loop_bb builder;
-
-      (* Start the PHI node with an entry for start. *)
-      let variable = build_phi [(start_val, preheader_bb)] var_name builder in
-
-      (* Within the loop, the variable is defined equal to the PHI node. If it
-       * shadows an existing variable, we have to restore it, so save it
-       * now. *)
-      let old_val =
-        try Some (Hashtbl.find named_values var_name) with Not_found -> None
-      in
-      Hashtbl.add named_values var_name variable;
-
-      (* Emit the body of the loop.  This, like any other expr, can change the
-       * current BB.  Note that we ignore the value computed by the body, but
-       * don't allow an error *)
-      ignore (codegen_expr body);
-
-      (* Emit the step value. *)
-      let step_val =
-        match step with
-        | Some step -> codegen_expr step
-        (* If not specified, use 1.0. *)
-        | None -> const_float double_type 1.0
-      in
-
-      let next_var = build_add variable step_val "nextvar" builder in
-
-      (* Compute the end condition. *)
-      let end_cond = codegen_expr end_ in
-
-      (* Convert condition to a bool by comparing equal to 0.0. *)
-      let zero = const_float double_type 0.0 in
-      let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
-
-      (* Create the "after loop" block and insert it. *)
-      let loop_end_bb = insertion_block builder in
-      let after_bb = append_block context "afterloop" the_function in
-
-      (* Insert the conditional branch into the end of loop_end_bb. *)
-      ignore (build_cond_br end_cond loop_bb after_bb builder);
-
-      (* Any new code will be inserted in after_bb. *)
-      position_at_end after_bb builder;
-
-      (* Add a new entry to the PHI node for the backedge. *)
-      add_incoming (next_var, loop_end_bb) variable;
-
-      (* Restore the unshadowed variable. *)
-      begin match old_val with
-      | Some old_val -> Hashtbl.add named_values var_name old_val
-      | None -> ()
-      end;
-
-      (* for expr always returns 0.0. *)
-      const_null double_type
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-        | None -> declare_function name ft the_module
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if block_begin f <> At_end f then
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if element_type (type_of f) <> ft then
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-let codegen_func the_fpm = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        (* Optimize the function. *)
-        let _ = PassManager.run_function the_function the_fpm in
-
-        the_function
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop the_fpm the_execution_engine stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop the_fpm the_execution_engine stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            let e = Parser.parse_definition stream in
-            print_endline "parsed a function definition.";
-            dump_value (Codegen.codegen_func the_fpm e);
-        | Token.Extern ->
-            let e = Parser.parse_extern stream in
-            print_endline "parsed an extern.";
-            dump_value (Codegen.codegen_proto e);
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            let the_function = Codegen.codegen_func the_fpm e in
-            dump_value the_function;
-
-            (* JIT the function, returning a function pointer. *)
-            let result = ExecutionEngine.run_function the_function [||]
-              the_execution_engine in
-
-            print_string "Evaluated to ";
-            print_float (GenericValue.as_float Codegen.double_type result);
-            print_newline ();
-        with Stream.Error s | Codegen.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop the_fpm the_execution_engine stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-open Llvm_target
-open Llvm_scalar_opts
-
-let main () =
-  ignore (initialize_native_target ());
-
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combination the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-  (* Eliminate Common SubExpressions. *)
-  add_gvn the_fpm;
-
-  (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
-  add_cfg_simplification the_fpm;
-
-  ignore (PassManager.initialize the_fpm);
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop the_fpm the_execution_engine stream;
-
-  (* Print out all the generated code. *)
-  dump_module Codegen.the_module
-;;
-
-main ()
-
-
- -
bindings.c
-
-
-#include <stdio.h>
-
-/* putchard - putchar that takes a double and returns 0. */
-extern double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-
-
- -Next: Extending the language: user-defined -operators -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl6.html b/cpp/llvm/docs/tutorial/OCamlLangImpl6.html deleted file mode 100644 index 2bf5c677..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl6.html +++ /dev/null @@ -1,1574 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: User-defined Operators - - - - - - - - -

Kaleidoscope: Extending the Language: User-defined Operators

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 6 Introduction

- - -
- -

Welcome to Chapter 6 of the "Implementing a language -with LLVM" tutorial. At this point in our tutorial, we now have a fully -functional language that is fairly minimal, but also useful. There -is still one big problem with it, however. Our language doesn't have many -useful operators (like division, logical negation, or even any comparisons -besides less-than).

- -

This chapter of the tutorial takes a wild digression into adding user-defined -operators to the simple and beautiful Kaleidoscope language. This digression now -gives us a simple and ugly language in some ways, but also a powerful one at the -same time. One of the great things about creating your own language is that you -get to decide what is good or bad. In this tutorial we'll assume that it is -okay to use this as a way to show some interesting parsing techniques.

- -

At the end of this tutorial, we'll run through an example Kaleidoscope -application that renders the Mandelbrot set. This gives -an example of what you can build with Kaleidoscope and its feature set.

- -
- - -

User-defined Operators: the Idea

- - -
- -

-The "operator overloading" that we will add to Kaleidoscope is more general than -languages like C++. In C++, you are only allowed to redefine existing -operators: you can't programatically change the grammar, introduce new -operators, change precedence levels, etc. In this chapter, we will add this -capability to Kaleidoscope, which will let the user round out the set of -operators that are supported.

- -

The point of going into user-defined operators in a tutorial like this is to -show the power and flexibility of using a hand-written parser. Thus far, the parser -we have been implementing uses recursive descent for most parts of the grammar and -operator precedence parsing for the expressions. See Chapter 2 for details. Without using operator -precedence parsing, it would be very difficult to allow the programmer to -introduce new operators into the grammar: the grammar is dynamically extensible -as the JIT runs.

- -

The two specific features we'll add are programmable unary operators (right -now, Kaleidoscope has no unary operators at all) as well as binary operators. -An example of this is:

- -
-
-# Logical unary not.
-def unary!(v)
-  if v then
-    0
-  else
-    1;
-
-# Define > with the same precedence as <.
-def binary> 10 (LHS RHS)
-  RHS < LHS;
-
-# Binary "logical or", (note that it does not "short circuit")
-def binary| 5 (LHS RHS)
-  if LHS then
-    1
-  else if RHS then
-    1
-  else
-    0;
-
-# Define = with slightly lower precedence than relationals.
-def binary= 9 (LHS RHS)
-  !(LHS < RHS | LHS > RHS);
-
-
- -

Many languages aspire to being able to implement their standard runtime -library in the language itself. In Kaleidoscope, we can implement significant -parts of the language in the library!

- -

We will break down implementation of these features into two parts: -implementing support for user-defined binary operators and adding unary -operators.

- -
- - -

User-defined Binary Operators

- - -
- -

Adding support for user-defined binary operators is pretty simple with our -current framework. We'll first add support for the unary/binary keywords:

- -
-
-type token =
-  ...
-  (* operators *)
-  | Binary | Unary
-
-...
-
-and lex_ident buffer = parser
-  ...
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | "binary" -> [< 'Token.Binary; stream >]
-      | "unary" -> [< 'Token.Unary; stream >]
-
-
- -

This just adds lexer support for the unary and binary keywords, like we -did in previous chapters. One nice -thing about our current AST, is that we represent binary operators with full -generalisation by using their ASCII code as the opcode. For our extended -operators, we'll use this same representation, so we don't need any new AST or -parser support.

- -

On the other hand, we have to be able to represent the definitions of these -new operators, in the "def binary| 5" part of the function definition. In our -grammar so far, the "name" for the function definition is parsed as the -"prototype" production and into the Ast.Prototype AST node. To -represent our new user-defined operators as prototypes, we have to extend -the Ast.Prototype AST node like this:

- -
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto =
-  | Prototype of string * string array
-  | BinOpPrototype of string * string array * int
-
-
- -

Basically, in addition to knowing a name for the prototype, we now keep track -of whether it was an operator, and if it was, what precedence level the operator -is at. The precedence is only used for binary operators (as you'll see below, -it just doesn't apply for unary operators). Now that we have a way to represent -the prototype for a user-defined operator, we need to parse it:

- -
-
-(* prototype
- *   ::= id '(' id* ')'
- *   ::= binary LETTER number? (id, id)
- *   ::= unary LETTER number? (id) *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-  let parse_operator = parser
-    | [< 'Token.Unary >] -> "unary", 1
-    | [< 'Token.Binary >] -> "binary", 2
-  in
-  let parse_binary_precedence = parser
-    | [< 'Token.Number n >] -> int_of_float n
-    | [< >] -> 30
-  in
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-  | [< (prefix, kind)=parse_operator;
-       'Token.Kwd op ?? "expected an operator";
-       (* Read the precedence if present. *)
-       binary_precedence=parse_binary_precedence;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-        args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      let name = prefix ^ (String.make 1 op) in
-      let args = Array.of_list (List.rev args) in
-
-      (* Verify right number of arguments for operator. *)
-      if Array.length args != kind
-      then raise (Stream.Error "invalid number of operands for operator")
-      else
-        if kind == 1 then
-          Ast.Prototype (name, args)
-        else
-          Ast.BinOpPrototype (name, args, binary_precedence)
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-
- -

This is all fairly straightforward parsing code, and we have already seen -a lot of similar code in the past. One interesting part about the code above is -the couple lines that set up name for binary operators. This builds -names like "binary@" for a newly defined "@" operator. This then takes -advantage of the fact that symbol names in the LLVM symbol table are allowed to -have any character in them, including embedded nul characters.

- -

The next interesting thing to add, is codegen support for these binary -operators. Given our current structure, this is a simple addition of a default -case for our existing binary operator node:

- -
-
-let codegen_expr = function
-  ...
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_add lhs_val rhs_val "addtmp" builder
-        | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_mul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ ->
-            (* If it wasn't a builtin binary operator, it must be a user defined
-             * one. Emit a call to it. *)
-            let callee = "binary" ^ (String.make 1 op) in
-            let callee =
-              match lookup_function callee the_module with
-              | Some callee -> callee
-              | None -> raise (Error "binary operator not found!")
-            in
-            build_call callee [|lhs_val; rhs_val|] "binop" builder
-      end
-
-
- -

As you can see above, the new code is actually really simple. It just does -a lookup for the appropriate operator in the symbol table and generates a -function call to it. Since user-defined operators are just built as normal -functions (because the "prototype" boils down to a function with the right -name) everything falls into place.

- -

The final piece of code we are missing, is a bit of top level magic:

- -
-
-let codegen_func the_fpm = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* If this is an operator, install it. *)
-      begin match proto with
-      | Ast.BinOpPrototype (name, args, prec) ->
-          let op = name.[String.length name - 1] in
-          Hashtbl.add Parser.binop_precedence op prec;
-      | _ -> ()
-      end;
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-      ...
-
-
- -

Basically, before codegening a function, if it is a user-defined operator, we -register it in the precedence table. This allows the binary operator parsing -logic we already have in place to handle it. Since we are working on a -fully-general operator precedence parser, this is all we need to do to "extend -the grammar".

- -

Now we have useful user-defined binary operators. This builds a lot -on the previous framework we built for other operators. Adding unary operators -is a bit more challenging, because we don't have any framework for it yet - lets -see what it takes.

- -
- - -

User-defined Unary Operators

- - -
- -

Since we don't currently support unary operators in the Kaleidoscope -language, we'll need to add everything to support them. Above, we added simple -support for the 'unary' keyword to the lexer. In addition to that, we need an -AST node:

- -
-
-type expr =
-  ...
-  (* variant for a unary operator. *)
-  | Unary of char * expr
-  ...
-
-
- -

This AST node is very simple and obvious by now. It directly mirrors the -binary operator AST node, except that it only has one child. With this, we -need to add the parsing logic. Parsing a unary operator is pretty simple: we'll -add a new function to do it:

- -
-
-(* unary
- *   ::= primary
- *   ::= '!' unary *)
-and parse_unary = parser
-  (* If this is a unary operator, read it. *)
-  | [< 'Token.Kwd op when op != '(' && op != ')'; operand=parse_expr >] ->
-      Ast.Unary (op, operand)
-
-  (* If the current token is not an operator, it must be a primary expr. *)
-  | [< stream >] -> parse_primary stream
-
-
- -

The grammar we add is pretty straightforward here. If we see a unary -operator when parsing a primary operator, we eat the operator as a prefix and -parse the remaining piece as another unary operator. This allows us to handle -multiple unary operators (e.g. "!!x"). Note that unary operators can't have -ambiguous parses like binary operators can, so there is no need for precedence -information.

- -

The problem with this function, is that we need to call ParseUnary from -somewhere. To do this, we change previous callers of ParsePrimary to call -parse_unary instead:

- -
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-        ...
-        (* Parse the unary expression after the binary operator. *)
-        let rhs = parse_unary stream in
-        ...
-
-...
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_unary; stream >] -> parse_bin_rhs 0 lhs stream
-
-
- -

With these two simple changes, we are now able to parse unary operators and build the -AST for them. Next up, we need to add parser support for prototypes, to parse -the unary operator prototype. We extend the binary operator code above -with:

- -
-
-(* prototype
- *   ::= id '(' id* ')'
- *   ::= binary LETTER number? (id, id)
- *   ::= unary LETTER number? (id) *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-  let parse_operator = parser
-    | [< 'Token.Unary >] -> "unary", 1
-    | [< 'Token.Binary >] -> "binary", 2
-  in
-  let parse_binary_precedence = parser
-    | [< 'Token.Number n >] -> int_of_float n
-    | [< >] -> 30
-  in
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-  | [< (prefix, kind)=parse_operator;
-       'Token.Kwd op ?? "expected an operator";
-       (* Read the precedence if present. *)
-       binary_precedence=parse_binary_precedence;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-        args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      let name = prefix ^ (String.make 1 op) in
-      let args = Array.of_list (List.rev args) in
-
-      (* Verify right number of arguments for operator. *)
-      if Array.length args != kind
-      then raise (Stream.Error "invalid number of operands for operator")
-      else
-        if kind == 1 then
-          Ast.Prototype (name, args)
-        else
-          Ast.BinOpPrototype (name, args, binary_precedence)
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-
- -

As with binary operators, we name unary operators with a name that includes -the operator character. This assists us at code generation time. Speaking of, -the final piece we need to add is codegen support for unary operators. It looks -like this:

- -
-
-let rec codegen_expr = function
-  ...
-  | Ast.Unary (op, operand) ->
-      let operand = codegen_expr operand in
-      let callee = "unary" ^ (String.make 1 op) in
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown unary operator")
-      in
-      build_call callee [|operand|] "unop" builder
-
-
- -

This code is similar to, but simpler than, the code for binary operators. It -is simpler primarily because it doesn't need to handle any predefined operators. -

- -
- - -

Kicking the Tires

- - -
- -

It is somewhat hard to believe, but with a few simple extensions we've -covered in the last chapters, we have grown a real-ish language. With this, we -can do a lot of interesting things, including I/O, math, and a bunch of other -things. For example, we can now add a nice sequencing operator (printd is -defined to print out the specified value and a newline):

- -
-
-ready> extern printd(x);
-Read extern: declare double @printd(double)
-ready> def binary : 1 (x y) 0;  # Low-precedence operator that ignores operands.
-..
-ready> printd(123) : printd(456) : printd(789);
-123.000000
-456.000000
-789.000000
-Evaluated to 0.000000
-
-
- -

We can also define a bunch of other "primitive" operations, such as:

- -
-
-# Logical unary not.
-def unary!(v)
-  if v then
-    0
-  else
-    1;
-
-# Unary negate.
-def unary-(v)
-  0-v;
-
-# Define > with the same precedence as <.
-def binary> 10 (LHS RHS)
-  RHS < LHS;
-
-# Binary logical or, which does not short circuit.
-def binary| 5 (LHS RHS)
-  if LHS then
-    1
-  else if RHS then
-    1
-  else
-    0;
-
-# Binary logical and, which does not short circuit.
-def binary& 6 (LHS RHS)
-  if !LHS then
-    0
-  else
-    !!RHS;
-
-# Define = with slightly lower precedence than relationals.
-def binary = 9 (LHS RHS)
-  !(LHS < RHS | LHS > RHS);
-
-
-
- - -

Given the previous if/then/else support, we can also define interesting -functions for I/O. For example, the following prints out a character whose -"density" reflects the value passed in: the lower the value, the denser the -character:

- -
-
-ready>
-
-extern putchard(char)
-def printdensity(d)
-  if d > 8 then
-    putchard(32)  # ' '
-  else if d > 4 then
-    putchard(46)  # '.'
-  else if d > 2 then
-    putchard(43)  # '+'
-  else
-    putchard(42); # '*'
-...
-ready> printdensity(1): printdensity(2): printdensity(3) :
-          printdensity(4): printdensity(5): printdensity(9): putchard(10);
-*++..
-Evaluated to 0.000000
-
-
- -

Based on these simple primitive operations, we can start to define more -interesting things. For example, here's a little function that solves for the -number of iterations it takes a function in the complex plane to -converge:

- -
-
-# determine whether the specific location diverges.
-# Solve for z = z^2 + c in the complex plane.
-def mandleconverger(real imag iters creal cimag)
-  if iters > 255 | (real*real + imag*imag > 4) then
-    iters
-  else
-    mandleconverger(real*real - imag*imag + creal,
-                    2*real*imag + cimag,
-                    iters+1, creal, cimag);
-
-# return the number of iterations required for the iteration to escape
-def mandleconverge(real imag)
-  mandleconverger(real, imag, 0, real, imag);
-
-
- -

This "z = z2 + c" function is a beautiful little creature that is the basis -for computation of the Mandelbrot Set. Our -mandelconverge function returns the number of iterations that it takes -for a complex orbit to escape, saturating to 255. This is not a very useful -function by itself, but if you plot its value over a two-dimensional plane, -you can see the Mandelbrot set. Given that we are limited to using putchard -here, our amazing graphical output is limited, but we can whip together -something using the density plotter above:

- -
-
-# compute and plot the mandlebrot set with the specified 2 dimensional range
-# info.
-def mandelhelp(xmin xmax xstep   ymin ymax ystep)
-  for y = ymin, y < ymax, ystep in (
-    (for x = xmin, x < xmax, xstep in
-       printdensity(mandleconverge(x,y)))
-    : putchard(10)
-  )
-
-# mandel - This is a convenient helper function for ploting the mandelbrot set
-# from the specified position with the specified Magnification.
-def mandel(realstart imagstart realmag imagmag)
-  mandelhelp(realstart, realstart+realmag*78, realmag,
-             imagstart, imagstart+imagmag*40, imagmag);
-
-
- -

Given this, we can try plotting out the mandlebrot set! Lets try it out:

- -
-
-ready> mandel(-2.3, -1.3, 0.05, 0.07);
-*******************************+++++++++++*************************************
-*************************+++++++++++++++++++++++*******************************
-**********************+++++++++++++++++++++++++++++****************************
-*******************+++++++++++++++++++++.. ...++++++++*************************
-*****************++++++++++++++++++++++.... ...+++++++++***********************
-***************+++++++++++++++++++++++.....   ...+++++++++*********************
-**************+++++++++++++++++++++++....     ....+++++++++********************
-*************++++++++++++++++++++++......      .....++++++++*******************
-************+++++++++++++++++++++.......       .......+++++++******************
-***********+++++++++++++++++++....                ... .+++++++*****************
-**********+++++++++++++++++.......                     .+++++++****************
-*********++++++++++++++...........                    ...+++++++***************
-********++++++++++++............                      ...++++++++**************
-********++++++++++... ..........                        .++++++++**************
-*******+++++++++.....                                   .+++++++++*************
-*******++++++++......                                  ..+++++++++*************
-*******++++++.......                                   ..+++++++++*************
-*******+++++......                                     ..+++++++++*************
-*******.... ....                                      ...+++++++++*************
-*******.... .                                         ...+++++++++*************
-*******+++++......                                    ...+++++++++*************
-*******++++++.......                                   ..+++++++++*************
-*******++++++++......                                   .+++++++++*************
-*******+++++++++.....                                  ..+++++++++*************
-********++++++++++... ..........                        .++++++++**************
-********++++++++++++............                      ...++++++++**************
-*********++++++++++++++..........                     ...+++++++***************
-**********++++++++++++++++........                     .+++++++****************
-**********++++++++++++++++++++....                ... ..+++++++****************
-***********++++++++++++++++++++++.......       .......++++++++*****************
-************+++++++++++++++++++++++......      ......++++++++******************
-**************+++++++++++++++++++++++....      ....++++++++********************
-***************+++++++++++++++++++++++.....   ...+++++++++*********************
-*****************++++++++++++++++++++++....  ...++++++++***********************
-*******************+++++++++++++++++++++......++++++++*************************
-*********************++++++++++++++++++++++.++++++++***************************
-*************************+++++++++++++++++++++++*******************************
-******************************+++++++++++++************************************
-*******************************************************************************
-*******************************************************************************
-*******************************************************************************
-Evaluated to 0.000000
-ready> mandel(-2, -1, 0.02, 0.04);
-**************************+++++++++++++++++++++++++++++++++++++++++++++++++++++
-***********************++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-*********************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.
-*******************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++...
-*****************+++++++++++++++++++++++++++++++++++++++++++++++++++++++++.....
-***************++++++++++++++++++++++++++++++++++++++++++++++++++++++++........
-**************++++++++++++++++++++++++++++++++++++++++++++++++++++++...........
-************+++++++++++++++++++++++++++++++++++++++++++++++++++++..............
-***********++++++++++++++++++++++++++++++++++++++++++++++++++........        .
-**********++++++++++++++++++++++++++++++++++++++++++++++.............
-********+++++++++++++++++++++++++++++++++++++++++++..................
-*******+++++++++++++++++++++++++++++++++++++++.......................
-******+++++++++++++++++++++++++++++++++++...........................
-*****++++++++++++++++++++++++++++++++............................
-*****++++++++++++++++++++++++++++...............................
-****++++++++++++++++++++++++++......   .........................
-***++++++++++++++++++++++++.........     ......    ...........
-***++++++++++++++++++++++............
-**+++++++++++++++++++++..............
-**+++++++++++++++++++................
-*++++++++++++++++++.................
-*++++++++++++++++............ ...
-*++++++++++++++..............
-*+++....++++................
-*..........  ...........
-*
-*..........  ...........
-*+++....++++................
-*++++++++++++++..............
-*++++++++++++++++............ ...
-*++++++++++++++++++.................
-**+++++++++++++++++++................
-**+++++++++++++++++++++..............
-***++++++++++++++++++++++............
-***++++++++++++++++++++++++.........     ......    ...........
-****++++++++++++++++++++++++++......   .........................
-*****++++++++++++++++++++++++++++...............................
-*****++++++++++++++++++++++++++++++++............................
-******+++++++++++++++++++++++++++++++++++...........................
-*******+++++++++++++++++++++++++++++++++++++++.......................
-********+++++++++++++++++++++++++++++++++++++++++++..................
-Evaluated to 0.000000
-ready> mandel(-0.9, -1.4, 0.02, 0.03);
-*******************************************************************************
-*******************************************************************************
-*******************************************************************************
-**********+++++++++++++++++++++************************************************
-*+++++++++++++++++++++++++++++++++++++++***************************************
-+++++++++++++++++++++++++++++++++++++++++++++**********************************
-++++++++++++++++++++++++++++++++++++++++++++++++++*****************************
-++++++++++++++++++++++++++++++++++++++++++++++++++++++*************************
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++**********************
-+++++++++++++++++++++++++++++++++.........++++++++++++++++++*******************
-+++++++++++++++++++++++++++++++....   ......+++++++++++++++++++****************
-+++++++++++++++++++++++++++++.......  ........+++++++++++++++++++**************
-++++++++++++++++++++++++++++........   ........++++++++++++++++++++************
-+++++++++++++++++++++++++++.........     ..  ...+++++++++++++++++++++**********
-++++++++++++++++++++++++++...........        ....++++++++++++++++++++++********
-++++++++++++++++++++++++.............       .......++++++++++++++++++++++******
-+++++++++++++++++++++++.............        ........+++++++++++++++++++++++****
-++++++++++++++++++++++...........           ..........++++++++++++++++++++++***
-++++++++++++++++++++...........                .........++++++++++++++++++++++*
-++++++++++++++++++............                  ...........++++++++++++++++++++
-++++++++++++++++...............                 .............++++++++++++++++++
-++++++++++++++.................                 ...............++++++++++++++++
-++++++++++++..................                  .................++++++++++++++
-+++++++++..................                      .................+++++++++++++
-++++++........        .                               .........  ..++++++++++++
-++............                                         ......    ....++++++++++
-..............                                                    ...++++++++++
-..............                                                    ....+++++++++
-..............                                                    .....++++++++
-.............                                                    ......++++++++
-...........                                                     .......++++++++
-.........                                                       ........+++++++
-.........                                                       ........+++++++
-.........                                                           ....+++++++
-........                                                             ...+++++++
-.......                                                              ...+++++++
-                                                                    ....+++++++
-                                                                   .....+++++++
-                                                                    ....+++++++
-                                                                    ....+++++++
-                                                                    ....+++++++
-Evaluated to 0.000000
-ready> ^D
-
-
- -

At this point, you may be starting to realize that Kaleidoscope is a real -and powerful language. It may not be self-similar :), but it can be used to -plot things that are!

- -

With this, we conclude the "adding user-defined operators" chapter of the -tutorial. We have successfully augmented our language, adding the ability to -extend the language in the library, and we have shown how this can be used to -build a simple but interesting end-user application in Kaleidoscope. At this -point, Kaleidoscope can build a variety of applications that are functional and -can call functions with side-effects, but it can't actually define and mutate a -variable itself.

- -

Strikingly, variable mutation is an important feature of some -languages, and it is not at all obvious how to add -support for mutable variables without having to add an "SSA construction" -phase to your front-end. In the next chapter, we will describe how you can -add variable mutation without building SSA in your front-end.

- -
- - - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with the -if/then/else and for expressions.. To build this example, use: -

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
-<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
-<*.{byte,native}>: use_llvm_scalar_opts, use_bindings
-
-
- -
myocamlbuild.ml:
-
-
-open Ocamlbuild_plugin;;
-
-ocaml_lib ~extern:true "llvm";;
-ocaml_lib ~extern:true "llvm_analysis";;
-ocaml_lib ~extern:true "llvm_executionengine";;
-ocaml_lib ~extern:true "llvm_target";;
-ocaml_lib ~extern:true "llvm_scalar_opts";;
-
-flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"; A"-cclib"; A"-rdynamic"]);;
-dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-  (* control *)
-  | If | Then | Else
-  | For | In
-
-  (* operators *)
-  | Binary | Unary
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | "if" -> [< 'Token.If; stream >]
-      | "then" -> [< 'Token.Then; stream >]
-      | "else" -> [< 'Token.Else; stream >]
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | "binary" -> [< 'Token.Binary; stream >]
-      | "unary" -> [< 'Token.Unary; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a unary operator. *)
-  | Unary of char * expr
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-  (* variant for if/then/else. *)
-  | If of expr * expr * expr
-
-  (* variant for for/in. *)
-  | For of string * expr * expr * expr option * expr
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto =
-  | Prototype of string * string array
-  | BinOpPrototype of string * string array * int
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr
- *   ::= ifexpr
- *   ::= forexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
-  | [< 'Token.If; c=parse_expr;
-       'Token.Then ?? "expected 'then'"; t=parse_expr;
-       'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
-      Ast.If (c, t, e)
-
-  (* forexpr
-        ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
-  | [< 'Token.For;
-       'Token.Ident id ?? "expected identifier after for";
-       'Token.Kwd '=' ?? "expected '=' after for";
-       stream >] ->
-      begin parser
-        | [<
-             start=parse_expr;
-             'Token.Kwd ',' ?? "expected ',' after for";
-             end_=parse_expr;
-             stream >] ->
-            let step =
-              begin parser
-              | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
-              | [< >] -> None
-              end stream
-            in
-            begin parser
-            | [< 'Token.In; body=parse_expr >] ->
-                Ast.For (id, start, end_, step, body)
-            | [< >] ->
-                raise (Stream.Error "expected 'in' after for")
-            end stream
-        | [< >] ->
-            raise (Stream.Error "expected '=' after for")
-      end stream
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* unary
- *   ::= primary
- *   ::= '!' unary *)
-and parse_unary = parser
-  (* If this is a unary operator, read it. *)
-  | [< 'Token.Kwd op when op != '(' && op != ')'; operand=parse_expr >] ->
-      Ast.Unary (op, operand)
-
-  (* If the current token is not an operator, it must be a primary expr. *)
-  | [< stream >] -> parse_primary stream
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the unary expression after the binary operator. *)
-        let rhs = parse_unary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_unary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')'
- *   ::= binary LETTER number? (id, id)
- *   ::= unary LETTER number? (id) *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-  let parse_operator = parser
-    | [< 'Token.Unary >] -> "unary", 1
-    | [< 'Token.Binary >] -> "binary", 2
-  in
-  let parse_binary_precedence = parser
-    | [< 'Token.Number n >] -> int_of_float n
-    | [< >] -> 30
-  in
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-  | [< (prefix, kind)=parse_operator;
-       'Token.Kwd op ?? "expected an operator";
-       (* Read the precedence if present. *)
-       binary_precedence=parse_binary_precedence;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-        args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      let name = prefix ^ (String.make 1 op) in
-      let args = Array.of_list (List.rev args) in
-
-      (* Verify right number of arguments for operator. *)
-      if Array.length args != kind
-      then raise (Stream.Error "invalid number of operands for operator")
-      else
-        if kind == 1 then
-          Ast.Prototype (name, args)
-        else
-          Ast.BinOpPrototype (name, args, binary_precedence)
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
codegen.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Code Generation
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-let rec codegen_expr = function
-  | Ast.Number n -> const_float double_type n
-  | Ast.Variable name ->
-      (try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name"))
-  | Ast.Unary (op, operand) ->
-      let operand = codegen_expr operand in
-      let callee = "unary" ^ (String.make 1 op) in
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown unary operator")
-      in
-      build_call callee [|operand|] "unop" builder
-  | Ast.Binary (op, lhs, rhs) ->
-      let lhs_val = codegen_expr lhs in
-      let rhs_val = codegen_expr rhs in
-      begin
-        match op with
-        | '+' -> build_add lhs_val rhs_val "addtmp" builder
-        | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-        | '*' -> build_mul lhs_val rhs_val "multmp" builder
-        | '<' ->
-            (* Convert bool 0/1 to double 0.0 or 1.0 *)
-            let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-            build_uitofp i double_type "booltmp" builder
-        | _ ->
-            (* If it wasn't a builtin binary operator, it must be a user defined
-             * one. Emit a call to it. *)
-            let callee = "binary" ^ (String.make 1 op) in
-            let callee =
-              match lookup_function callee the_module with
-              | Some callee -> callee
-              | None -> raise (Error "binary operator not found!")
-            in
-            build_call callee [|lhs_val; rhs_val|] "binop" builder
-      end
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-  | Ast.If (cond, then_, else_) ->
-      let cond = codegen_expr cond in
-
-      (* Convert condition to a bool by comparing equal to 0.0 *)
-      let zero = const_float double_type 0.0 in
-      let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
-
-      (* Grab the first block so that we might later add the conditional branch
-       * to it at the end of the function. *)
-      let start_bb = insertion_block builder in
-      let the_function = block_parent start_bb in
-
-      let then_bb = append_block context "then" the_function in
-
-      (* Emit 'then' value. *)
-      position_at_end then_bb builder;
-      let then_val = codegen_expr then_ in
-
-      (* Codegen of 'then' can change the current block, update then_bb for the
-       * phi. We create a new name because one is used for the phi node, and the
-       * other is used for the conditional branch. *)
-      let new_then_bb = insertion_block builder in
-
-      (* Emit 'else' value. *)
-      let else_bb = append_block context "else" the_function in
-      position_at_end else_bb builder;
-      let else_val = codegen_expr else_ in
-
-      (* Codegen of 'else' can change the current block, update else_bb for the
-       * phi. *)
-      let new_else_bb = insertion_block builder in
-
-      (* Emit merge block. *)
-      let merge_bb = append_block context "ifcont" the_function in
-      position_at_end merge_bb builder;
-      let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
-      let phi = build_phi incoming "iftmp" builder in
-
-      (* Return to the start block to add the conditional branch. *)
-      position_at_end start_bb builder;
-      ignore (build_cond_br cond_val then_bb else_bb builder);
-
-      (* Set a unconditional branch at the end of the 'then' block and the
-       * 'else' block to the 'merge' block. *)
-      position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
-      position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
-
-      (* Finally, set the builder to the end of the merge block. *)
-      position_at_end merge_bb builder;
-
-      phi
-  | Ast.For (var_name, start, end_, step, body) ->
-      (* Emit the start code first, without 'variable' in scope. *)
-      let start_val = codegen_expr start in
-
-      (* Make the new basic block for the loop header, inserting after current
-       * block. *)
-      let preheader_bb = insertion_block builder in
-      let the_function = block_parent preheader_bb in
-      let loop_bb = append_block context "loop" the_function in
-
-      (* Insert an explicit fall through from the current block to the
-       * loop_bb. *)
-      ignore (build_br loop_bb builder);
-
-      (* Start insertion in loop_bb. *)
-      position_at_end loop_bb builder;
-
-      (* Start the PHI node with an entry for start. *)
-      let variable = build_phi [(start_val, preheader_bb)] var_name builder in
-
-      (* Within the loop, the variable is defined equal to the PHI node. If it
-       * shadows an existing variable, we have to restore it, so save it
-       * now. *)
-      let old_val =
-        try Some (Hashtbl.find named_values var_name) with Not_found -> None
-      in
-      Hashtbl.add named_values var_name variable;
-
-      (* Emit the body of the loop.  This, like any other expr, can change the
-       * current BB.  Note that we ignore the value computed by the body, but
-       * don't allow an error *)
-      ignore (codegen_expr body);
-
-      (* Emit the step value. *)
-      let step_val =
-        match step with
-        | Some step -> codegen_expr step
-        (* If not specified, use 1.0. *)
-        | None -> const_float double_type 1.0
-      in
-
-      let next_var = build_add variable step_val "nextvar" builder in
-
-      (* Compute the end condition. *)
-      let end_cond = codegen_expr end_ in
-
-      (* Convert condition to a bool by comparing equal to 0.0. *)
-      let zero = const_float double_type 0.0 in
-      let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
-
-      (* Create the "after loop" block and insert it. *)
-      let loop_end_bb = insertion_block builder in
-      let after_bb = append_block context "afterloop" the_function in
-
-      (* Insert the conditional branch into the end of loop_end_bb. *)
-      ignore (build_cond_br end_cond loop_bb after_bb builder);
-
-      (* Any new code will be inserted in after_bb. *)
-      position_at_end after_bb builder;
-
-      (* Add a new entry to the PHI node for the backedge. *)
-      add_incoming (next_var, loop_end_bb) variable;
-
-      (* Restore the unshadowed variable. *)
-      begin match old_val with
-      | Some old_val -> Hashtbl.add named_values var_name old_val
-      | None -> ()
-      end;
-
-      (* for expr always returns 0.0. *)
-      const_null double_type
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) | Ast.BinOpPrototype (name, args, _) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-        | None -> declare_function name ft the_module
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if block_begin f <> At_end f then
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if element_type (type_of f) <> ft then
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-let codegen_func the_fpm = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* If this is an operator, install it. *)
-      begin match proto with
-      | Ast.BinOpPrototype (name, args, prec) ->
-          let op = name.[String.length name - 1] in
-          Hashtbl.add Parser.binop_precedence op prec;
-      | _ -> ()
-      end;
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        (* Optimize the function. *)
-        let _ = PassManager.run_function the_function the_fpm in
-
-        the_function
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop the_fpm the_execution_engine stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop the_fpm the_execution_engine stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            let e = Parser.parse_definition stream in
-            print_endline "parsed a function definition.";
-            dump_value (Codegen.codegen_func the_fpm e);
-        | Token.Extern ->
-            let e = Parser.parse_extern stream in
-            print_endline "parsed an extern.";
-            dump_value (Codegen.codegen_proto e);
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            let the_function = Codegen.codegen_func the_fpm e in
-            dump_value the_function;
-
-            (* JIT the function, returning a function pointer. *)
-            let result = ExecutionEngine.run_function the_function [||]
-              the_execution_engine in
-
-            print_string "Evaluated to ";
-            print_float (GenericValue.as_float Codegen.double_type result);
-            print_newline ();
-        with Stream.Error s | Codegen.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop the_fpm the_execution_engine stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-open Llvm_target
-open Llvm_scalar_opts
-
-let main () =
-  ignore (initialize_native_target ());
-
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combination the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-  (* Eliminate Common SubExpressions. *)
-  add_gvn the_fpm;
-
-  (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
-  add_cfg_simplification the_fpm;
-
-  ignore (PassManager.initialize the_fpm);
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop the_fpm the_execution_engine stream;
-
-  (* Print out all the generated code. *)
-  dump_module Codegen.the_module
-;;
-
-main ()
-
-
- -
bindings.c
-
-
-#include <stdio.h>
-
-/* putchard - putchar that takes a double and returns 0. */
-extern double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-/* printd - printf that takes a double prints it as "%f\n", returning 0. */
-extern double printd(double X) {
-  printf("%f\n", X);
-  return 0;
-}
-
-
-
- -Next: Extending the language: mutable variables / -SSA construction -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- Erick Tryzelaar
- The LLVM Compiler Infrastructure
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl7.html b/cpp/llvm/docs/tutorial/OCamlLangImpl7.html deleted file mode 100644 index 79d1a81f..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl7.html +++ /dev/null @@ -1,1904 +0,0 @@ - - - - - Kaleidoscope: Extending the Language: Mutable Variables / SSA - construction - - - - - - - - -

Kaleidoscope: Extending the Language: Mutable Variables

- - - -
-

- Written by Chris Lattner - and Erick Tryzelaar -

-
- - -

Chapter 7 Introduction

- - -
- -

Welcome to Chapter 7 of the "Implementing a language -with LLVM" tutorial. In chapters 1 through 6, we've built a very -respectable, albeit simple, functional -programming language. In our journey, we learned some parsing techniques, -how to build and represent an AST, how to build LLVM IR, and how to optimize -the resultant code as well as JIT compile it.

- -

While Kaleidoscope is interesting as a functional language, the fact that it -is functional makes it "too easy" to generate LLVM IR for it. In particular, a -functional language makes it very easy to build LLVM IR directly in SSA form. -Since LLVM requires that the input code be in SSA form, this is a very nice -property and it is often unclear to newcomers how to generate code for an -imperative language with mutable variables.

- -

The short (and happy) summary of this chapter is that there is no need for -your front-end to build SSA form: LLVM provides highly tuned and well tested -support for this, though the way it works is a bit unexpected for some.

- -
- - -

Why is this a hard problem?

- - -
- -

-To understand why mutable variables cause complexities in SSA construction, -consider this extremely simple C example: -

- -
-
-int G, H;
-int test(_Bool Condition) {
-  int X;
-  if (Condition)
-    X = G;
-  else
-    X = H;
-  return X;
-}
-
-
- -

In this case, we have the variable "X", whose value depends on the path -executed in the program. Because there are two different possible values for X -before the return instruction, a PHI node is inserted to merge the two values. -The LLVM IR that we want for this example looks like this:

- -
-
-@G = weak global i32 0   ; type of @G is i32*
-@H = weak global i32 0   ; type of @H is i32*
-
-define i32 @test(i1 %Condition) {
-entry:
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-  br label %cond_next
-
-cond_next:
-  %X.2 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
-  ret i32 %X.2
-}
-
-
- -

In this example, the loads from the G and H global variables are explicit in -the LLVM IR, and they live in the then/else branches of the if statement -(cond_true/cond_false). In order to merge the incoming values, the X.2 phi node -in the cond_next block selects the right value to use based on where control -flow is coming from: if control flow comes from the cond_false block, X.2 gets -the value of X.1. Alternatively, if control flow comes from cond_true, it gets -the value of X.0. The intent of this chapter is not to explain the details of -SSA form. For more information, see one of the many online -references.

- -

The question for this article is "who places the phi nodes when lowering -assignments to mutable variables?". The issue here is that LLVM -requires that its IR be in SSA form: there is no "non-ssa" mode for it. -However, SSA construction requires non-trivial algorithms and data structures, -so it is inconvenient and wasteful for every front-end to have to reproduce this -logic.

- -
- - -

Memory in LLVM

- - -
- -

The 'trick' here is that while LLVM does require all register values to be -in SSA form, it does not require (or permit) memory objects to be in SSA form. -In the example above, note that the loads from G and H are direct accesses to -G and H: they are not renamed or versioned. This differs from some other -compiler systems, which do try to version memory objects. In LLVM, instead of -encoding dataflow analysis of memory into the LLVM IR, it is handled with Analysis Passes which are computed on -demand.

- -

-With this in mind, the high-level idea is that we want to make a stack variable -(which lives in memory, because it is on the stack) for each mutable object in -a function. To take advantage of this trick, we need to talk about how LLVM -represents stack variables. -

- -

In LLVM, all memory accesses are explicit with load/store instructions, and -it is carefully designed not to have (or need) an "address-of" operator. Notice -how the type of the @G/@H global variables is actually "i32*" even though the -variable is defined as "i32". What this means is that @G defines space -for an i32 in the global data area, but its name actually refers to the -address for that space. Stack variables work the same way, except that instead of -being declared with global variable definitions, they are declared with the -LLVM alloca instruction:

- -
-
-define i32 @example() {
-entry:
-  %X = alloca i32           ; type of %X is i32*.
-  ...
-  %tmp = load i32* %X       ; load the stack value %X from the stack.
-  %tmp2 = add i32 %tmp, 1   ; increment it
-  store i32 %tmp2, i32* %X  ; store it back
-  ...
-
-
- -

This code shows an example of how you can declare and manipulate a stack -variable in the LLVM IR. Stack memory allocated with the alloca instruction is -fully general: you can pass the address of the stack slot to functions, you can -store it in other variables, etc. In our example above, we could rewrite the -example to use the alloca technique to avoid using a PHI node:

- -
-
-@G = weak global i32 0   ; type of @G is i32*
-@H = weak global i32 0   ; type of @H is i32*
-
-define i32 @test(i1 %Condition) {
-entry:
-  %X = alloca i32           ; type of %X is i32*.
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-        store i32 %X.0, i32* %X   ; Update X
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-        store i32 %X.1, i32* %X   ; Update X
-  br label %cond_next
-
-cond_next:
-  %X.2 = load i32* %X       ; Read X
-  ret i32 %X.2
-}
-
-
- -

With this, we have discovered a way to handle arbitrary mutable variables -without the need to create Phi nodes at all:

- -
    -
  1. Each mutable variable becomes a stack allocation.
  2. -
  3. Each read of the variable becomes a load from the stack.
  4. -
  5. Each update of the variable becomes a store to the stack.
  6. -
  7. Taking the address of a variable just uses the stack address directly.
  8. -
- -

While this solution has solved our immediate problem, it introduced another -one: we have now apparently introduced a lot of stack traffic for very simple -and common operations, a major performance problem. Fortunately for us, the -LLVM optimizer has a highly-tuned optimization pass named "mem2reg" that handles -this case, promoting allocas like this into SSA registers, inserting Phi nodes -as appropriate. If you run this example through the pass, for example, you'll -get:

- -
-
-$ llvm-as < example.ll | opt -mem2reg | llvm-dis
-@G = weak global i32 0
-@H = weak global i32 0
-
-define i32 @test(i1 %Condition) {
-entry:
-  br i1 %Condition, label %cond_true, label %cond_false
-
-cond_true:
-  %X.0 = load i32* @G
-  br label %cond_next
-
-cond_false:
-  %X.1 = load i32* @H
-  br label %cond_next
-
-cond_next:
-  %X.01 = phi i32 [ %X.1, %cond_false ], [ %X.0, %cond_true ]
-  ret i32 %X.01
-}
-
-
- -

The mem2reg pass implements the standard "iterated dominance frontier" -algorithm for constructing SSA form and has a number of optimizations that speed -up (very common) degenerate cases. The mem2reg optimization pass is the answer -to dealing with mutable variables, and we highly recommend that you depend on -it. Note that mem2reg only works on variables in certain circumstances:

- -
    -
  1. mem2reg is alloca-driven: it looks for allocas and if it can handle them, it -promotes them. It does not apply to global variables or heap allocations.
  2. - -
  3. mem2reg only looks for alloca instructions in the entry block of the -function. Being in the entry block guarantees that the alloca is only executed -once, which makes analysis simpler.
  4. - -
  5. mem2reg only promotes allocas whose uses are direct loads and stores. If -the address of the stack object is passed to a function, or if any funny pointer -arithmetic is involved, the alloca will not be promoted.
  6. - -
  7. mem2reg only works on allocas of first class -values (such as pointers, scalars and vectors), and only if the array size -of the allocation is 1 (or missing in the .ll file). mem2reg is not capable of -promoting structs or arrays to registers. Note that the "scalarrepl" pass is -more powerful and can promote structs, "unions", and arrays in many cases.
  8. - -
- -

-All of these properties are easy to satisfy for most imperative languages, and -we'll illustrate it below with Kaleidoscope. The final question you may be -asking is: should I bother with this nonsense for my front-end? Wouldn't it be -better if I just did SSA construction directly, avoiding use of the mem2reg -optimization pass? In short, we strongly recommend that you use this technique -for building SSA form, unless there is an extremely good reason not to. Using -this technique is:

- -
    -
  • Proven and well tested: llvm-gcc and clang both use this technique for local -mutable variables. As such, the most common clients of LLVM are using this to -handle a bulk of their variables. You can be sure that bugs are found fast and -fixed early.
  • - -
  • Extremely Fast: mem2reg has a number of special cases that make it fast in -common cases as well as fully general. For example, it has fast-paths for -variables that are only used in a single block, variables that only have one -assignment point, good heuristics to avoid insertion of unneeded phi nodes, etc. -
  • - -
  • Needed for debug info generation: -Debug information in LLVM relies on having the address of the variable -exposed so that debug info can be attached to it. This technique dovetails -very naturally with this style of debug info.
  • -
- -

If nothing else, this makes it much easier to get your front-end up and -running, and is very simple to implement. Lets extend Kaleidoscope with mutable -variables now! -

- -
- - -

Mutable Variables in Kaleidoscope

- - -
- -

Now that we know the sort of problem we want to tackle, lets see what this -looks like in the context of our little Kaleidoscope language. We're going to -add two features:

- -
    -
  1. The ability to mutate variables with the '=' operator.
  2. -
  3. The ability to define new variables.
  4. -
- -

While the first item is really what this is about, we only have variables -for incoming arguments as well as for induction variables, and redefining those only -goes so far :). Also, the ability to define new variables is a -useful thing regardless of whether you will be mutating them. Here's a -motivating example that shows how we could use these:

- -
-
-# Define ':' for sequencing: as a low-precedence operator that ignores operands
-# and just returns the RHS.
-def binary : 1 (x y) y;
-
-# Recursive fib, we could do this before.
-def fib(x)
-  if (x < 3) then
-    1
-  else
-    fib(x-1)+fib(x-2);
-
-# Iterative fib.
-def fibi(x)
-  var a = 1, b = 1, c in
-  (for i = 3, i < x in
-     c = a + b :
-     a = b :
-     b = c) :
-  b;
-
-# Call it.
-fibi(10);
-
-
- -

-In order to mutate variables, we have to change our existing variables to use -the "alloca trick". Once we have that, we'll add our new operator, then extend -Kaleidoscope to support new variable definitions. -

- -
- - -

Adjusting Existing Variables for Mutation

- - -
- -

-The symbol table in Kaleidoscope is managed at code generation time by the -'named_values' map. This map currently keeps track of the LLVM -"Value*" that holds the double value for the named variable. In order to -support mutation, we need to change this slightly, so that it -named_values holds the memory location of the variable in -question. Note that this change is a refactoring: it changes the structure of -the code, but does not (by itself) change the behavior of the compiler. All of -these changes are isolated in the Kaleidoscope code generator.

- -

-At this point in Kaleidoscope's development, it only supports variables for two -things: incoming arguments to functions and the induction variable of 'for' -loops. For consistency, we'll allow mutation of these variables in addition to -other user-defined variables. This means that these will both need memory -locations. -

- -

To start our transformation of Kaleidoscope, we'll change the -named_values map so that it maps to AllocaInst* instead of Value*. -Once we do this, the C++ compiler will tell us what parts of the code we need to -update:

- -

Note: the ocaml bindings currently model both Value*s and -AllocInst*s as Llvm.llvalues, but this may change in the -future to be more type safe.

- -
-
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-
-
- -

Also, since we will need to create these alloca's, we'll use a helper -function that ensures that the allocas are created in the entry block of the -function:

- -
-
-(* Create an alloca instruction in the entry block of the function. This
- * is used for mutable variables etc. *)
-let create_entry_block_alloca the_function var_name =
-  let builder = builder_at (instr_begin (entry_block the_function)) in
-  build_alloca double_type var_name builder
-
-
- -

This funny looking code creates an Llvm.llbuilder object that is -pointing at the first instruction of the entry block. It then creates an alloca -with the expected name and returns it. Because all values in Kaleidoscope are -doubles, there is no need to pass in a type to use.

- -

With this in place, the first functionality change we want to make is to -variable references. In our new scheme, variables live on the stack, so code -generating a reference to them actually needs to produce a load from the stack -slot:

- -
-
-let rec codegen_expr = function
-  ...
-  | Ast.Variable name ->
-      let v = try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name")
-      in
-      (* Load the value. *)
-      build_load v name builder
-
-
- -

As you can see, this is pretty straightforward. Now we need to update the -things that define the variables to set up the alloca. We'll start with -codegen_expr Ast.For ... (see the full code listing -for the unabridged code):

- -
-
-  | Ast.For (var_name, start, end_, step, body) ->
-      let the_function = block_parent (insertion_block builder) in
-
-      (* Create an alloca for the variable in the entry block. *)
-      let alloca = create_entry_block_alloca the_function var_name in
-
-      (* Emit the start code first, without 'variable' in scope. *)
-      let start_val = codegen_expr start in
-
-      (* Store the value into the alloca. *)
-      ignore(build_store start_val alloca builder);
-
-      ...
-
-      (* Within the loop, the variable is defined equal to the PHI node. If it
-       * shadows an existing variable, we have to restore it, so save it
-       * now. *)
-      let old_val =
-        try Some (Hashtbl.find named_values var_name) with Not_found -> None
-      in
-      Hashtbl.add named_values var_name alloca;
-
-      ...
-
-      (* Compute the end condition. *)
-      let end_cond = codegen_expr end_ in
-
-      (* Reload, increment, and restore the alloca. This handles the case where
-       * the body of the loop mutates the variable. *)
-      let cur_var = build_load alloca var_name builder in
-      let next_var = build_add cur_var step_val "nextvar" builder in
-      ignore(build_store next_var alloca builder);
-      ...
-
-
- -

This code is virtually identical to the code before we allowed mutable variables. -The big difference is that we no longer have to construct a PHI node, and we use -load/store to access the variable as needed.

- -

To support mutable argument variables, we need to also make allocas for them. -The code for this is also pretty simple:

- -
-
-(* Create an alloca for each argument and register the argument in the symbol
- * table so that references to it will succeed. *)
-let create_argument_allocas the_function proto =
-  let args = match proto with
-    | Ast.Prototype (_, args) | Ast.BinOpPrototype (_, args, _) -> args
-  in
-  Array.iteri (fun i ai ->
-    let var_name = args.(i) in
-    (* Create an alloca for this variable. *)
-    let alloca = create_entry_block_alloca the_function var_name in
-
-    (* Store the initial value into the alloca. *)
-    ignore(build_store ai alloca builder);
-
-    (* Add arguments to variable symbol table. *)
-    Hashtbl.add named_values var_name alloca;
-  ) (params the_function)
-
-
- -

For each argument, we make an alloca, store the input value to the function -into the alloca, and register the alloca as the memory location for the -argument. This method gets invoked by Codegen.codegen_func right after -it sets up the entry block for the function.

- -

The final missing piece is adding the mem2reg pass, which allows us to get -good codegen once again:

- -
-
-let main () =
-  ...
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Promote allocas to registers. *)
-  add_memory_to_register_promotion the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combining the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-
- -

It is interesting to see what the code looks like before and after the -mem2reg optimization runs. For example, this is the before/after code for our -recursive fib function. Before the optimization:

- -
-
-define double @fib(double %x) {
-entry:
-  %x1 = alloca double
-  store double %x, double* %x1
-  %x2 = load double* %x1
-  %cmptmp = fcmp ult double %x2, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:    ; preds = %entry
-  br label %ifcont
-
-else:    ; preds = %entry
-  %x3 = load double* %x1
-  %subtmp = fsub double %x3, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %x4 = load double* %x1
-  %subtmp5 = fsub double %x4, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  br label %ifcont
-
-ifcont:    ; preds = %else, %then
-  %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
-  ret double %iftmp
-}
-
-
- -

Here there is only one variable (x, the input argument) but you can still -see the extremely simple-minded code generation strategy we are using. In the -entry block, an alloca is created, and the initial input value is stored into -it. Each reference to the variable does a reload from the stack. Also, note -that we didn't modify the if/then/else expression, so it still inserts a PHI -node. While we could make an alloca for it, it is actually easier to create a -PHI node for it, so we still just make the PHI.

- -

Here is the code after the mem2reg pass runs:

- -
-
-define double @fib(double %x) {
-entry:
-  %cmptmp = fcmp ult double %x, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp one double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %then, label %else
-
-then:
-  br label %ifcont
-
-else:
-  %subtmp = fsub double %x, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %subtmp5 = fsub double %x, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  br label %ifcont
-
-ifcont:    ; preds = %else, %then
-  %iftmp = phi double [ 1.000000e+00, %then ], [ %addtmp, %else ]
-  ret double %iftmp
-}
-
-
- -

This is a trivial case for mem2reg, since there are no redefinitions of the -variable. The point of showing this is to calm your tension about inserting -such blatent inefficiencies :).

- -

After the rest of the optimizers run, we get:

- -
-
-define double @fib(double %x) {
-entry:
-  %cmptmp = fcmp ult double %x, 3.000000e+00
-  %booltmp = uitofp i1 %cmptmp to double
-  %ifcond = fcmp ueq double %booltmp, 0.000000e+00
-  br i1 %ifcond, label %else, label %ifcont
-
-else:
-  %subtmp = fsub double %x, 1.000000e+00
-  %calltmp = call double @fib(double %subtmp)
-  %subtmp5 = fsub double %x, 2.000000e+00
-  %calltmp6 = call double @fib(double %subtmp5)
-  %addtmp = fadd double %calltmp, %calltmp6
-  ret double %addtmp
-
-ifcont:
-  ret double 1.000000e+00
-}
-
-
- -

Here we see that the simplifycfg pass decided to clone the return instruction -into the end of the 'else' block. This allowed it to eliminate some branches -and the PHI node.

- -

Now that all symbol table references are updated to use stack variables, -we'll add the assignment operator.

- -
- - -

New Assignment Operator

- - -
- -

With our current framework, adding a new assignment operator is really -simple. We will parse it just like any other binary operator, but handle it -internally (instead of allowing the user to define it). The first step is to -set a precedence:

- -
-
-let main () =
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '=' 2;
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  ...
-
-
- -

Now that the parser knows the precedence of the binary operator, it takes -care of all the parsing and AST generation. We just need to implement codegen -for the assignment operator. This looks like:

- -
-
-let rec codegen_expr = function
-      begin match op with
-      | '=' ->
-          (* Special case '=' because we don't want to emit the LHS as an
-           * expression. *)
-          let name =
-            match lhs with
-            | Ast.Variable name -> name
-            | _ -> raise (Error "destination of '=' must be a variable")
-          in
-
-
- -

Unlike the rest of the binary operators, our assignment operator doesn't -follow the "emit LHS, emit RHS, do computation" model. As such, it is handled -as a special case before the other binary operators are handled. The other -strange thing is that it requires the LHS to be a variable. It is invalid to -have "(x+1) = expr" - only things like "x = expr" are allowed. -

- - -
-
-          (* Codegen the rhs. *)
-          let val_ = codegen_expr rhs in
-
-          (* Lookup the name. *)
-          let variable = try Hashtbl.find named_values name with
-          | Not_found -> raise (Error "unknown variable name")
-          in
-          ignore(build_store val_ variable builder);
-          val_
-      | _ ->
-			...
-
-
- -

Once we have the variable, codegen'ing the assignment is straightforward: -we emit the RHS of the assignment, create a store, and return the computed -value. Returning a value allows for chained assignments like "X = (Y = Z)".

- -

Now that we have an assignment operator, we can mutate loop variables and -arguments. For example, we can now run code like this:

- -
-
-# Function to print a double.
-extern printd(x);
-
-# Define ':' for sequencing: as a low-precedence operator that ignores operands
-# and just returns the RHS.
-def binary : 1 (x y) y;
-
-def test(x)
-  printd(x) :
-  x = 4 :
-  printd(x);
-
-test(123);
-
-
- -

When run, this example prints "123" and then "4", showing that we did -actually mutate the value! Okay, we have now officially implemented our goal: -getting this to work requires SSA construction in the general case. However, -to be really useful, we want the ability to define our own local variables, lets -add this next! -

- -
- - -

User-defined Local Variables

- - -
- -

Adding var/in is just like any other other extensions we made to -Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. -The first step for adding our new 'var/in' construct is to extend the lexer. -As before, this is pretty trivial, the code looks like this:

- -
-
-type token =
-  ...
-  (* var definition *)
-  | Var
-
-...
-
-and lex_ident buffer = parser
-      ...
-      | "in" -> [< 'Token.In; stream >]
-      | "binary" -> [< 'Token.Binary; stream >]
-      | "unary" -> [< 'Token.Unary; stream >]
-      | "var" -> [< 'Token.Var; stream >]
-      ...
-
-
- -

The next step is to define the AST node that we will construct. For var/in, -it looks like this:

- -
-
-type expr =
-  ...
-  (* variant for var/in. *)
-  | Var of (string * expr option) array * expr
-  ...
-
-
- -

var/in allows a list of names to be defined all at once, and each name can -optionally have an initializer value. As such, we capture this information in -the VarNames vector. Also, var/in has a body, this body is allowed to access -the variables defined by the var/in.

- -

With this in place, we can define the parser pieces. The first thing we do -is add it as a primary expression:

- -
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr
- *   ::= ifexpr
- *   ::= forexpr
- *   ::= varexpr *)
-let rec parse_primary = parser
-  ...
-  (* varexpr
-   *   ::= 'var' identifier ('=' expression?
-   *             (',' identifier ('=' expression)?)* 'in' expression *)
-  | [< 'Token.Var;
-       (* At least one variable name is required. *)
-       'Token.Ident id ?? "expected identifier after var";
-       init=parse_var_init;
-       var_names=parse_var_names [(id, init)];
-       (* At this point, we have to have 'in'. *)
-       'Token.In ?? "expected 'in' keyword after 'var'";
-       body=parse_expr >] ->
-      Ast.Var (Array.of_list (List.rev var_names), body)
-
-...
-
-and parse_var_init = parser
-  (* read in the optional initializer. *)
-  | [< 'Token.Kwd '='; e=parse_expr >] -> Some e
-  | [< >] -> None
-
-and parse_var_names accumulator = parser
-  | [< 'Token.Kwd ',';
-       'Token.Ident id ?? "expected identifier list after var";
-       init=parse_var_init;
-       e=parse_var_names ((id, init) :: accumulator) >] -> e
-  | [< >] -> accumulator
-
-
- -

Now that we can parse and represent the code, we need to support emission of -LLVM IR for it. This code starts out with:

- -
-
-let rec codegen_expr = function
-  ...
-  | Ast.Var (var_names, body)
-      let old_bindings = ref [] in
-
-      let the_function = block_parent (insertion_block builder) in
-
-      (* Register all variables and emit their initializer. *)
-      Array.iter (fun (var_name, init) ->
-
-
- -

Basically it loops over all the variables, installing them one at a time. -For each variable we put into the symbol table, we remember the previous value -that we replace in OldBindings.

- -
-
-        (* Emit the initializer before adding the variable to scope, this
-         * prevents the initializer from referencing the variable itself, and
-         * permits stuff like this:
-         *   var a = 1 in
-         *     var a = a in ...   # refers to outer 'a'. *)
-        let init_val =
-          match init with
-          | Some init -> codegen_expr init
-          (* If not specified, use 0.0. *)
-          | None -> const_float double_type 0.0
-        in
-
-        let alloca = create_entry_block_alloca the_function var_name in
-        ignore(build_store init_val alloca builder);
-
-        (* Remember the old variable binding so that we can restore the binding
-         * when we unrecurse. *)
-
-        begin
-          try
-            let old_value = Hashtbl.find named_values var_name in
-            old_bindings := (var_name, old_value) :: !old_bindings;
-          with Not_found > ()
-        end;
-
-        (* Remember this binding. *)
-        Hashtbl.add named_values var_name alloca;
-      ) var_names;
-
-
- -

There are more comments here than code. The basic idea is that we emit the -initializer, create the alloca, then update the symbol table to point to it. -Once all the variables are installed in the symbol table, we evaluate the body -of the var/in expression:

- -
-
-      (* Codegen the body, now that all vars are in scope. *)
-      let body_val = codegen_expr body in
-
-
- -

Finally, before returning, we restore the previous variable bindings:

- -
-
-      (* Pop all our variables from scope. *)
-      List.iter (fun (var_name, old_value) ->
-        Hashtbl.add named_values var_name old_value
-      ) !old_bindings;
-
-      (* Return the body computation. *)
-      body_val
-
-
- -

The end result of all of this is that we get properly scoped variable -definitions, and we even (trivially) allow mutation of them :).

- -

With this, we completed what we set out to do. Our nice iterative fib -example from the intro compiles and runs just fine. The mem2reg pass optimizes -all of our stack variables into SSA registers, inserting PHI nodes where needed, -and our front-end remains simple: no "iterated dominance frontier" computation -anywhere in sight.

- -
- - -

Full Code Listing

- - -
- -

-Here is the complete code listing for our running example, enhanced with mutable -variables and var/in support. To build this example, use: -

- -
-
-# Compile
-ocamlbuild toy.byte
-# Run
-./toy.byte
-
-
- -

Here is the code:

- -
-
_tags:
-
-
-<{lexer,parser}.ml>: use_camlp4, pp(camlp4of)
-<*.{byte,native}>: g++, use_llvm, use_llvm_analysis
-<*.{byte,native}>: use_llvm_executionengine, use_llvm_target
-<*.{byte,native}>: use_llvm_scalar_opts, use_bindings
-
-
- -
myocamlbuild.ml:
-
-
-open Ocamlbuild_plugin;;
-
-ocaml_lib ~extern:true "llvm";;
-ocaml_lib ~extern:true "llvm_analysis";;
-ocaml_lib ~extern:true "llvm_executionengine";;
-ocaml_lib ~extern:true "llvm_target";;
-ocaml_lib ~extern:true "llvm_scalar_opts";;
-
-flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"; A"-cclib"; A"-rdynamic"]);;
-dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
-
-
- -
token.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer Tokens
- *===----------------------------------------------------------------------===*)
-
-(* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
- * these others for known things. *)
-type token =
-  (* commands *)
-  | Def | Extern
-
-  (* primary *)
-  | Ident of string | Number of float
-
-  (* unknown *)
-  | Kwd of char
-
-  (* control *)
-  | If | Then | Else
-  | For | In
-
-  (* operators *)
-  | Binary | Unary
-
-  (* var definition *)
-  | Var
-
-
- -
lexer.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Lexer
- *===----------------------------------------------------------------------===*)
-
-let rec lex = parser
-  (* Skip any whitespace. *)
-  | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream
-
-  (* identifier: [a-zA-Z][a-zA-Z0-9] *)
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-
-  (* number: [0-9.]+ *)
-  | [< ' ('0' .. '9' as c); stream >] ->
-      let buffer = Buffer.create 1 in
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-
-  (* Comment until end of line. *)
-  | [< ' ('#'); stream >] ->
-      lex_comment stream
-
-  (* Otherwise, just return the character as its ascii value. *)
-  | [< 'c; stream >] ->
-      [< 'Token.Kwd c; lex stream >]
-
-  (* end of stream. *)
-  | [< >] -> [< >]
-
-and lex_number buffer = parser
-  | [< ' ('0' .. '9' | '.' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_number buffer stream
-  | [< stream=lex >] ->
-      [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >]
-
-and lex_ident buffer = parser
-  | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] ->
-      Buffer.add_char buffer c;
-      lex_ident buffer stream
-  | [< stream=lex >] ->
-      match Buffer.contents buffer with
-      | "def" -> [< 'Token.Def; stream >]
-      | "extern" -> [< 'Token.Extern; stream >]
-      | "if" -> [< 'Token.If; stream >]
-      | "then" -> [< 'Token.Then; stream >]
-      | "else" -> [< 'Token.Else; stream >]
-      | "for" -> [< 'Token.For; stream >]
-      | "in" -> [< 'Token.In; stream >]
-      | "binary" -> [< 'Token.Binary; stream >]
-      | "unary" -> [< 'Token.Unary; stream >]
-      | "var" -> [< 'Token.Var; stream >]
-      | id -> [< 'Token.Ident id; stream >]
-
-and lex_comment = parser
-  | [< ' ('\n'); stream=lex >] -> stream
-  | [< 'c; e=lex_comment >] -> e
-  | [< >] -> [< >]
-
-
- -
ast.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Abstract Syntax Tree (aka Parse Tree)
- *===----------------------------------------------------------------------===*)
-
-(* expr - Base type for all expression nodes. *)
-type expr =
-  (* variant for numeric literals like "1.0". *)
-  | Number of float
-
-  (* variant for referencing a variable, like "a". *)
-  | Variable of string
-
-  (* variant for a unary operator. *)
-  | Unary of char * expr
-
-  (* variant for a binary operator. *)
-  | Binary of char * expr * expr
-
-  (* variant for function calls. *)
-  | Call of string * expr array
-
-  (* variant for if/then/else. *)
-  | If of expr * expr * expr
-
-  (* variant for for/in. *)
-  | For of string * expr * expr * expr option * expr
-
-  (* variant for var/in. *)
-  | Var of (string * expr option) array * expr
-
-(* proto - This type represents the "prototype" for a function, which captures
- * its name, and its argument names (thus implicitly the number of arguments the
- * function takes). *)
-type proto =
-  | Prototype of string * string array
-  | BinOpPrototype of string * string array * int
-
-(* func - This type represents a function definition itself. *)
-type func = Function of proto * expr
-
-
- -
parser.ml:
-
-
-(*===---------------------------------------------------------------------===
- * Parser
- *===---------------------------------------------------------------------===*)
-
-(* binop_precedence - This holds the precedence for each binary operator that is
- * defined *)
-let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
-
-(* precedence - Get the precedence of the pending binary operator token. *)
-let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1
-
-(* primary
- *   ::= identifier
- *   ::= numberexpr
- *   ::= parenexpr
- *   ::= ifexpr
- *   ::= forexpr
- *   ::= varexpr *)
-let rec parse_primary = parser
-  (* numberexpr ::= number *)
-  | [< 'Token.Number n >] -> Ast.Number n
-
-  (* parenexpr ::= '(' expression ')' *)
-  | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e
-
-  (* identifierexpr
-   *   ::= identifier
-   *   ::= identifier '(' argumentexpr ')' *)
-  | [< 'Token.Ident id; stream >] ->
-      let rec parse_args accumulator = parser
-        | [< e=parse_expr; stream >] ->
-            begin parser
-              | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e
-              | [< >] -> e :: accumulator
-            end stream
-        | [< >] -> accumulator
-      in
-      let rec parse_ident id = parser
-        (* Call. *)
-        | [< 'Token.Kwd '(';
-             args=parse_args [];
-             'Token.Kwd ')' ?? "expected ')'">] ->
-            Ast.Call (id, Array.of_list (List.rev args))
-
-        (* Simple variable ref. *)
-        | [< >] -> Ast.Variable id
-      in
-      parse_ident id stream
-
-  (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
-  | [< 'Token.If; c=parse_expr;
-       'Token.Then ?? "expected 'then'"; t=parse_expr;
-       'Token.Else ?? "expected 'else'"; e=parse_expr >] ->
-      Ast.If (c, t, e)
-
-  (* forexpr
-        ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
-  | [< 'Token.For;
-       'Token.Ident id ?? "expected identifier after for";
-       'Token.Kwd '=' ?? "expected '=' after for";
-       stream >] ->
-      begin parser
-        | [<
-             start=parse_expr;
-             'Token.Kwd ',' ?? "expected ',' after for";
-             end_=parse_expr;
-             stream >] ->
-            let step =
-              begin parser
-              | [< 'Token.Kwd ','; step=parse_expr >] -> Some step
-              | [< >] -> None
-              end stream
-            in
-            begin parser
-            | [< 'Token.In; body=parse_expr >] ->
-                Ast.For (id, start, end_, step, body)
-            | [< >] ->
-                raise (Stream.Error "expected 'in' after for")
-            end stream
-        | [< >] ->
-            raise (Stream.Error "expected '=' after for")
-      end stream
-
-  (* varexpr
-   *   ::= 'var' identifier ('=' expression?
-   *             (',' identifier ('=' expression)?)* 'in' expression *)
-  | [< 'Token.Var;
-       (* At least one variable name is required. *)
-       'Token.Ident id ?? "expected identifier after var";
-       init=parse_var_init;
-       var_names=parse_var_names [(id, init)];
-       (* At this point, we have to have 'in'. *)
-       'Token.In ?? "expected 'in' keyword after 'var'";
-       body=parse_expr >] ->
-      Ast.Var (Array.of_list (List.rev var_names), body)
-
-  | [< >] -> raise (Stream.Error "unknown token when expecting an expression.")
-
-(* unary
- *   ::= primary
- *   ::= '!' unary *)
-and parse_unary = parser
-  (* If this is a unary operator, read it. *)
-  | [< 'Token.Kwd op when op != '(' && op != ')'; operand=parse_expr >] ->
-      Ast.Unary (op, operand)
-
-  (* If the current token is not an operator, it must be a primary expr. *)
-  | [< stream >] -> parse_primary stream
-
-(* binoprhs
- *   ::= ('+' primary)* *)
-and parse_bin_rhs expr_prec lhs stream =
-  match Stream.peek stream with
-  (* If this is a binop, find its precedence. *)
-  | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c ->
-      let token_prec = precedence c in
-
-      (* If this is a binop that binds at least as tightly as the current binop,
-       * consume it, otherwise we are done. *)
-      if token_prec < expr_prec then lhs else begin
-        (* Eat the binop. *)
-        Stream.junk stream;
-
-        (* Parse the primary expression after the binary operator. *)
-        let rhs = parse_unary stream in
-
-        (* Okay, we know this is a binop. *)
-        let rhs =
-          match Stream.peek stream with
-          | Some (Token.Kwd c2) ->
-              (* If BinOp binds less tightly with rhs than the operator after
-               * rhs, let the pending operator take rhs as its lhs. *)
-              let next_prec = precedence c2 in
-              if token_prec < next_prec
-              then parse_bin_rhs (token_prec + 1) rhs stream
-              else rhs
-          | _ -> rhs
-        in
-
-        (* Merge lhs/rhs. *)
-        let lhs = Ast.Binary (c, lhs, rhs) in
-        parse_bin_rhs expr_prec lhs stream
-      end
-  | _ -> lhs
-
-and parse_var_init = parser
-  (* read in the optional initializer. *)
-  | [< 'Token.Kwd '='; e=parse_expr >] -> Some e
-  | [< >] -> None
-
-and parse_var_names accumulator = parser
-  | [< 'Token.Kwd ',';
-       'Token.Ident id ?? "expected identifier list after var";
-       init=parse_var_init;
-       e=parse_var_names ((id, init) :: accumulator) >] -> e
-  | [< >] -> accumulator
-
-(* expression
- *   ::= primary binoprhs *)
-and parse_expr = parser
-  | [< lhs=parse_unary; stream >] -> parse_bin_rhs 0 lhs stream
-
-(* prototype
- *   ::= id '(' id* ')'
- *   ::= binary LETTER number? (id, id)
- *   ::= unary LETTER number? (id) *)
-let parse_prototype =
-  let rec parse_args accumulator = parser
-    | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e
-    | [< >] -> accumulator
-  in
-  let parse_operator = parser
-    | [< 'Token.Unary >] -> "unary", 1
-    | [< 'Token.Binary >] -> "binary", 2
-  in
-  let parse_binary_precedence = parser
-    | [< 'Token.Number n >] -> int_of_float n
-    | [< >] -> 30
-  in
-  parser
-  | [< 'Token.Ident id;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-       args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      (* success. *)
-      Ast.Prototype (id, Array.of_list (List.rev args))
-  | [< (prefix, kind)=parse_operator;
-       'Token.Kwd op ?? "expected an operator";
-       (* Read the precedence if present. *)
-       binary_precedence=parse_binary_precedence;
-       'Token.Kwd '(' ?? "expected '(' in prototype";
-        args=parse_args [];
-       'Token.Kwd ')' ?? "expected ')' in prototype" >] ->
-      let name = prefix ^ (String.make 1 op) in
-      let args = Array.of_list (List.rev args) in
-
-      (* Verify right number of arguments for operator. *)
-      if Array.length args != kind
-      then raise (Stream.Error "invalid number of operands for operator")
-      else
-        if kind == 1 then
-          Ast.Prototype (name, args)
-        else
-          Ast.BinOpPrototype (name, args, binary_precedence)
-  | [< >] ->
-      raise (Stream.Error "expected function name in prototype")
-
-(* definition ::= 'def' prototype expression *)
-let parse_definition = parser
-  | [< 'Token.Def; p=parse_prototype; e=parse_expr >] ->
-      Ast.Function (p, e)
-
-(* toplevelexpr ::= expression *)
-let parse_toplevel = parser
-  | [< e=parse_expr >] ->
-      (* Make an anonymous proto. *)
-      Ast.Function (Ast.Prototype ("", [||]), e)
-
-(*  external ::= 'extern' prototype *)
-let parse_extern = parser
-  | [< 'Token.Extern; e=parse_prototype >] -> e
-
-
- -
codegen.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Code Generation
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-
-exception Error of string
-
-let context = global_context ()
-let the_module = create_module context "my cool jit"
-let builder = builder context
-let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
-let double_type = double_type context
-
-(* Create an alloca instruction in the entry block of the function. This
- * is used for mutable variables etc. *)
-let create_entry_block_alloca the_function var_name =
-  let builder = builder_at context (instr_begin (entry_block the_function)) in
-  build_alloca double_type var_name builder
-
-let rec codegen_expr = function
-  | Ast.Number n -> const_float double_type n
-  | Ast.Variable name ->
-      let v = try Hashtbl.find named_values name with
-        | Not_found -> raise (Error "unknown variable name")
-      in
-      (* Load the value. *)
-      build_load v name builder
-  | Ast.Unary (op, operand) ->
-      let operand = codegen_expr operand in
-      let callee = "unary" ^ (String.make 1 op) in
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown unary operator")
-      in
-      build_call callee [|operand|] "unop" builder
-  | Ast.Binary (op, lhs, rhs) ->
-      begin match op with
-      | '=' ->
-          (* Special case '=' because we don't want to emit the LHS as an
-           * expression. *)
-          let name =
-            match lhs with
-            | Ast.Variable name -> name
-            | _ -> raise (Error "destination of '=' must be a variable")
-          in
-
-          (* Codegen the rhs. *)
-          let val_ = codegen_expr rhs in
-
-          (* Lookup the name. *)
-          let variable = try Hashtbl.find named_values name with
-          | Not_found -> raise (Error "unknown variable name")
-          in
-          ignore(build_store val_ variable builder);
-          val_
-      | _ ->
-          let lhs_val = codegen_expr lhs in
-          let rhs_val = codegen_expr rhs in
-          begin
-            match op with
-            | '+' -> build_add lhs_val rhs_val "addtmp" builder
-            | '-' -> build_sub lhs_val rhs_val "subtmp" builder
-            | '*' -> build_mul lhs_val rhs_val "multmp" builder
-            | '<' ->
-                (* Convert bool 0/1 to double 0.0 or 1.0 *)
-                let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
-                build_uitofp i double_type "booltmp" builder
-            | _ ->
-                (* If it wasn't a builtin binary operator, it must be a user defined
-                 * one. Emit a call to it. *)
-                let callee = "binary" ^ (String.make 1 op) in
-                let callee =
-                  match lookup_function callee the_module with
-                  | Some callee -> callee
-                  | None -> raise (Error "binary operator not found!")
-                in
-                build_call callee [|lhs_val; rhs_val|] "binop" builder
-          end
-      end
-  | Ast.Call (callee, args) ->
-      (* Look up the name in the module table. *)
-      let callee =
-        match lookup_function callee the_module with
-        | Some callee -> callee
-        | None -> raise (Error "unknown function referenced")
-      in
-      let params = params callee in
-
-      (* If argument mismatch error. *)
-      if Array.length params == Array.length args then () else
-        raise (Error "incorrect # arguments passed");
-      let args = Array.map codegen_expr args in
-      build_call callee args "calltmp" builder
-  | Ast.If (cond, then_, else_) ->
-      let cond = codegen_expr cond in
-
-      (* Convert condition to a bool by comparing equal to 0.0 *)
-      let zero = const_float double_type 0.0 in
-      let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
-
-      (* Grab the first block so that we might later add the conditional branch
-       * to it at the end of the function. *)
-      let start_bb = insertion_block builder in
-      let the_function = block_parent start_bb in
-
-      let then_bb = append_block context "then" the_function in
-
-      (* Emit 'then' value. *)
-      position_at_end then_bb builder;
-      let then_val = codegen_expr then_ in
-
-      (* Codegen of 'then' can change the current block, update then_bb for the
-       * phi. We create a new name because one is used for the phi node, and the
-       * other is used for the conditional branch. *)
-      let new_then_bb = insertion_block builder in
-
-      (* Emit 'else' value. *)
-      let else_bb = append_block context "else" the_function in
-      position_at_end else_bb builder;
-      let else_val = codegen_expr else_ in
-
-      (* Codegen of 'else' can change the current block, update else_bb for the
-       * phi. *)
-      let new_else_bb = insertion_block builder in
-
-      (* Emit merge block. *)
-      let merge_bb = append_block context "ifcont" the_function in
-      position_at_end merge_bb builder;
-      let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
-      let phi = build_phi incoming "iftmp" builder in
-
-      (* Return to the start block to add the conditional branch. *)
-      position_at_end start_bb builder;
-      ignore (build_cond_br cond_val then_bb else_bb builder);
-
-      (* Set a unconditional branch at the end of the 'then' block and the
-       * 'else' block to the 'merge' block. *)
-      position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
-      position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
-
-      (* Finally, set the builder to the end of the merge block. *)
-      position_at_end merge_bb builder;
-
-      phi
-  | Ast.For (var_name, start, end_, step, body) ->
-      (* Output this as:
-       *   var = alloca double
-       *   ...
-       *   start = startexpr
-       *   store start -> var
-       *   goto loop
-       * loop:
-       *   ...
-       *   bodyexpr
-       *   ...
-       * loopend:
-       *   step = stepexpr
-       *   endcond = endexpr
-       *
-       *   curvar = load var
-       *   nextvar = curvar + step
-       *   store nextvar -> var
-       *   br endcond, loop, endloop
-       * outloop: *)
-
-      let the_function = block_parent (insertion_block builder) in
-
-      (* Create an alloca for the variable in the entry block. *)
-      let alloca = create_entry_block_alloca the_function var_name in
-
-      (* Emit the start code first, without 'variable' in scope. *)
-      let start_val = codegen_expr start in
-
-      (* Store the value into the alloca. *)
-      ignore(build_store start_val alloca builder);
-
-      (* Make the new basic block for the loop header, inserting after current
-       * block. *)
-      let loop_bb = append_block context "loop" the_function in
-
-      (* Insert an explicit fall through from the current block to the
-       * loop_bb. *)
-      ignore (build_br loop_bb builder);
-
-      (* Start insertion in loop_bb. *)
-      position_at_end loop_bb builder;
-
-      (* Within the loop, the variable is defined equal to the PHI node. If it
-       * shadows an existing variable, we have to restore it, so save it
-       * now. *)
-      let old_val =
-        try Some (Hashtbl.find named_values var_name) with Not_found -> None
-      in
-      Hashtbl.add named_values var_name alloca;
-
-      (* Emit the body of the loop.  This, like any other expr, can change the
-       * current BB.  Note that we ignore the value computed by the body, but
-       * don't allow an error *)
-      ignore (codegen_expr body);
-
-      (* Emit the step value. *)
-      let step_val =
-        match step with
-        | Some step -> codegen_expr step
-        (* If not specified, use 1.0. *)
-        | None -> const_float double_type 1.0
-      in
-
-      (* Compute the end condition. *)
-      let end_cond = codegen_expr end_ in
-
-      (* Reload, increment, and restore the alloca. This handles the case where
-       * the body of the loop mutates the variable. *)
-      let cur_var = build_load alloca var_name builder in
-      let next_var = build_add cur_var step_val "nextvar" builder in
-      ignore(build_store next_var alloca builder);
-
-      (* Convert condition to a bool by comparing equal to 0.0. *)
-      let zero = const_float double_type 0.0 in
-      let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
-
-      (* Create the "after loop" block and insert it. *)
-      let after_bb = append_block context "afterloop" the_function in
-
-      (* Insert the conditional branch into the end of loop_end_bb. *)
-      ignore (build_cond_br end_cond loop_bb after_bb builder);
-
-      (* Any new code will be inserted in after_bb. *)
-      position_at_end after_bb builder;
-
-      (* Restore the unshadowed variable. *)
-      begin match old_val with
-      | Some old_val -> Hashtbl.add named_values var_name old_val
-      | None -> ()
-      end;
-
-      (* for expr always returns 0.0. *)
-      const_null double_type
-  | Ast.Var (var_names, body) ->
-      let old_bindings = ref [] in
-
-      let the_function = block_parent (insertion_block builder) in
-
-      (* Register all variables and emit their initializer. *)
-      Array.iter (fun (var_name, init) ->
-        (* Emit the initializer before adding the variable to scope, this
-         * prevents the initializer from referencing the variable itself, and
-         * permits stuff like this:
-         *   var a = 1 in
-         *     var a = a in ...   # refers to outer 'a'. *)
-        let init_val =
-          match init with
-          | Some init -> codegen_expr init
-          (* If not specified, use 0.0. *)
-          | None -> const_float double_type 0.0
-        in
-
-        let alloca = create_entry_block_alloca the_function var_name in
-        ignore(build_store init_val alloca builder);
-
-        (* Remember the old variable binding so that we can restore the binding
-         * when we unrecurse. *)
-        begin
-          try
-            let old_value = Hashtbl.find named_values var_name in
-            old_bindings := (var_name, old_value) :: !old_bindings;
-          with Not_found -> ()
-        end;
-
-        (* Remember this binding. *)
-        Hashtbl.add named_values var_name alloca;
-      ) var_names;
-
-      (* Codegen the body, now that all vars are in scope. *)
-      let body_val = codegen_expr body in
-
-      (* Pop all our variables from scope. *)
-      List.iter (fun (var_name, old_value) ->
-        Hashtbl.add named_values var_name old_value
-      ) !old_bindings;
-
-      (* Return the body computation. *)
-      body_val
-
-let codegen_proto = function
-  | Ast.Prototype (name, args) | Ast.BinOpPrototype (name, args, _) ->
-      (* Make the function type: double(double,double) etc. *)
-      let doubles = Array.make (Array.length args) double_type in
-      let ft = function_type double_type doubles in
-      let f =
-        match lookup_function name the_module with
-        | None -> declare_function name ft the_module
-
-        (* If 'f' conflicted, there was already something named 'name'. If it
-         * has a body, don't allow redefinition or reextern. *)
-        | Some f ->
-            (* If 'f' already has a body, reject this. *)
-            if block_begin f <> At_end f then
-              raise (Error "redefinition of function");
-
-            (* If 'f' took a different number of arguments, reject. *)
-            if element_type (type_of f) <> ft then
-              raise (Error "redefinition of function with different # args");
-            f
-      in
-
-      (* Set names for all arguments. *)
-      Array.iteri (fun i a ->
-        let n = args.(i) in
-        set_value_name n a;
-        Hashtbl.add named_values n a;
-      ) (params f);
-      f
-
-(* Create an alloca for each argument and register the argument in the symbol
- * table so that references to it will succeed. *)
-let create_argument_allocas the_function proto =
-  let args = match proto with
-    | Ast.Prototype (_, args) | Ast.BinOpPrototype (_, args, _) -> args
-  in
-  Array.iteri (fun i ai ->
-    let var_name = args.(i) in
-    (* Create an alloca for this variable. *)
-    let alloca = create_entry_block_alloca the_function var_name in
-
-    (* Store the initial value into the alloca. *)
-    ignore(build_store ai alloca builder);
-
-    (* Add arguments to variable symbol table. *)
-    Hashtbl.add named_values var_name alloca;
-  ) (params the_function)
-
-let codegen_func the_fpm = function
-  | Ast.Function (proto, body) ->
-      Hashtbl.clear named_values;
-      let the_function = codegen_proto proto in
-
-      (* If this is an operator, install it. *)
-      begin match proto with
-      | Ast.BinOpPrototype (name, args, prec) ->
-          let op = name.[String.length name - 1] in
-          Hashtbl.add Parser.binop_precedence op prec;
-      | _ -> ()
-      end;
-
-      (* Create a new basic block to start insertion into. *)
-      let bb = append_block context "entry" the_function in
-      position_at_end bb builder;
-
-      try
-        (* Add all arguments to the symbol table and create their allocas. *)
-        create_argument_allocas the_function proto;
-
-        let ret_val = codegen_expr body in
-
-        (* Finish off the function. *)
-        let _ = build_ret ret_val builder in
-
-        (* Validate the generated code, checking for consistency. *)
-        Llvm_analysis.assert_valid_function the_function;
-
-        (* Optimize the function. *)
-        let _ = PassManager.run_function the_function the_fpm in
-
-        the_function
-      with e ->
-        delete_function the_function;
-        raise e
-
-
- -
toplevel.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Top-Level parsing and JIT Driver
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-
-(* top ::= definition | external | expression | ';' *)
-let rec main_loop the_fpm the_execution_engine stream =
-  match Stream.peek stream with
-  | None -> ()
-
-  (* ignore top-level semicolons. *)
-  | Some (Token.Kwd ';') ->
-      Stream.junk stream;
-      main_loop the_fpm the_execution_engine stream
-
-  | Some token ->
-      begin
-        try match token with
-        | Token.Def ->
-            let e = Parser.parse_definition stream in
-            print_endline "parsed a function definition.";
-            dump_value (Codegen.codegen_func the_fpm e);
-        | Token.Extern ->
-            let e = Parser.parse_extern stream in
-            print_endline "parsed an extern.";
-            dump_value (Codegen.codegen_proto e);
-        | _ ->
-            (* Evaluate a top-level expression into an anonymous function. *)
-            let e = Parser.parse_toplevel stream in
-            print_endline "parsed a top-level expr";
-            let the_function = Codegen.codegen_func the_fpm e in
-            dump_value the_function;
-
-            (* JIT the function, returning a function pointer. *)
-            let result = ExecutionEngine.run_function the_function [||]
-              the_execution_engine in
-
-            print_string "Evaluated to ";
-            print_float (GenericValue.as_float Codegen.double_type result);
-            print_newline ();
-        with Stream.Error s | Codegen.Error s ->
-          (* Skip token for error recovery. *)
-          Stream.junk stream;
-          print_endline s;
-      end;
-      print_string "ready> "; flush stdout;
-      main_loop the_fpm the_execution_engine stream
-
-
- -
toy.ml:
-
-
-(*===----------------------------------------------------------------------===
- * Main driver code.
- *===----------------------------------------------------------------------===*)
-
-open Llvm
-open Llvm_executionengine
-open Llvm_target
-open Llvm_scalar_opts
-
-let main () =
-  ignore (initialize_native_target ());
-
-  (* Install standard binary operators.
-   * 1 is the lowest precedence. *)
-  Hashtbl.add Parser.binop_precedence '=' 2;
-  Hashtbl.add Parser.binop_precedence '<' 10;
-  Hashtbl.add Parser.binop_precedence '+' 20;
-  Hashtbl.add Parser.binop_precedence '-' 20;
-  Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
-
-  (* Prime the first token. *)
-  print_string "ready> "; flush stdout;
-  let stream = Lexer.lex (Stream.of_channel stdin) in
-
-  (* Create the JIT. *)
-  let the_execution_engine = ExecutionEngine.create Codegen.the_module in
-  let the_fpm = PassManager.create_function Codegen.the_module in
-
-  (* Set up the optimizer pipeline.  Start with registering info about how the
-   * target lays out data structures. *)
-  TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
-
-  (* Promote allocas to registers. *)
-  add_memory_to_register_promotion the_fpm;
-
-  (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
-  add_instruction_combination the_fpm;
-
-  (* reassociate expressions. *)
-  add_reassociation the_fpm;
-
-  (* Eliminate Common SubExpressions. *)
-  add_gvn the_fpm;
-
-  (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
-  add_cfg_simplification the_fpm;
-
-  ignore (PassManager.initialize the_fpm);
-
-  (* Run the main "interpreter loop" now. *)
-  Toplevel.main_loop the_fpm the_execution_engine stream;
-
-  (* Print out all the generated code. *)
-  dump_module Codegen.the_module
-;;
-
-main ()
-
-
- -
bindings.c
-
-
-#include <stdio.h>
-
-/* putchard - putchar that takes a double and returns 0. */
-extern double putchard(double X) {
-  putchar((char)X);
-  return 0;
-}
-
-/* printd - printf that takes a double prints it as "%f\n", returning 0. */
-extern double printd(double X) {
-  printf("%f\n", X);
-  return 0;
-}
-
-
-
- -Next: Conclusion and other useful LLVM tidbits -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Erick Tryzelaar
- Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $ -
- - diff --git a/cpp/llvm/docs/tutorial/OCamlLangImpl8.html b/cpp/llvm/docs/tutorial/OCamlLangImpl8.html deleted file mode 100644 index eed8c03d..00000000 --- a/cpp/llvm/docs/tutorial/OCamlLangImpl8.html +++ /dev/null @@ -1,359 +0,0 @@ - - - - - Kaleidoscope: Conclusion and other useful LLVM tidbits - - - - - - - -

Kaleidoscope: Conclusion and other useful LLVM tidbits

- - - - -
-

Written by Chris Lattner

-
- - -

Tutorial Conclusion

- - -
- -

Welcome to the the final chapter of the "Implementing a -language with LLVM" tutorial. In the course of this tutorial, we have grown -our little Kaleidoscope language from being a useless toy, to being a -semi-interesting (but probably still useless) toy. :)

- -

It is interesting to see how far we've come, and how little code it has -taken. We built the entire lexer, parser, AST, code generator, and an -interactive run-loop (with a JIT!) by-hand in under 700 lines of -(non-comment/non-blank) code.

- -

Our little language supports a couple of interesting features: it supports -user defined binary and unary operators, it uses JIT compilation for immediate -evaluation, and it supports a few control flow constructs with SSA construction. -

- -

Part of the idea of this tutorial was to show you how easy and fun it can be -to define, build, and play with languages. Building a compiler need not be a -scary or mystical process! Now that you've seen some of the basics, I strongly -encourage you to take the code and hack on it. For example, try adding:

- -
    -
  • global variables - While global variables have questional value in -modern software engineering, they are often useful when putting together quick -little hacks like the Kaleidoscope compiler itself. Fortunately, our current -setup makes it very easy to add global variables: just have value lookup check -to see if an unresolved variable is in the global variable symbol table before -rejecting it. To create a new global variable, make an instance of the LLVM -GlobalVariable class.
  • - -
  • typed variables - Kaleidoscope currently only supports variables of -type double. This gives the language a very nice elegance, because only -supporting one type means that you never have to specify types. Different -languages have different ways of handling this. The easiest way is to require -the user to specify types for every variable definition, and record the type -of the variable in the symbol table along with its Value*.
  • - -
  • arrays, structs, vectors, etc - Once you add types, you can start -extending the type system in all sorts of interesting ways. Simple arrays are -very easy and are quite useful for many different applications. Adding them is -mostly an exercise in learning how the LLVM getelementptr instruction works: it -is so nifty/unconventional, it has its own FAQ! If you add support -for recursive types (e.g. linked lists), make sure to read the section in the LLVM -Programmer's Manual that describes how to construct them.
  • - -
  • standard runtime - Our current language allows the user to access -arbitrary external functions, and we use it for things like "printd" and -"putchard". As you extend the language to add higher-level constructs, often -these constructs make the most sense if they are lowered to calls into a -language-supplied runtime. For example, if you add hash tables to the language, -it would probably make sense to add the routines to a runtime, instead of -inlining them all the way.
  • - -
  • memory management - Currently we can only access the stack in -Kaleidoscope. It would also be useful to be able to allocate heap memory, -either with calls to the standard libc malloc/free interface or with a garbage -collector. If you would like to use garbage collection, note that LLVM fully -supports Accurate Garbage Collection -including algorithms that move objects and need to scan/update the stack.
  • - -
  • debugger support - LLVM supports generation of DWARF Debug info which is understood by -common debuggers like GDB. Adding support for debug info is fairly -straightforward. The best way to understand it is to compile some C/C++ code -with "llvm-gcc -g -O0" and taking a look at what it produces.
  • - -
  • exception handling support - LLVM supports generation of zero cost exceptions which interoperate -with code compiled in other languages. You could also generate code by -implicitly making every function return an error value and checking it. You -could also make explicit use of setjmp/longjmp. There are many different ways -to go here.
  • - -
  • object orientation, generics, database access, complex numbers, -geometric programming, ... - Really, there is -no end of crazy features that you can add to the language.
  • - -
  • unusual domains - We've been talking about applying LLVM to a domain -that many people are interested in: building a compiler for a specific language. -However, there are many other domains that can use compiler technology that are -not typically considered. For example, LLVM has been used to implement OpenGL -graphics acceleration, translate C++ code to ActionScript, and many other -cute and clever things. Maybe you will be the first to JIT compile a regular -expression interpreter into native code with LLVM?
  • - -
- -

-Have fun - try doing something crazy and unusual. Building a language like -everyone else always has, is much less fun than trying something a little crazy -or off the wall and seeing how it turns out. If you get stuck or want to talk -about it, feel free to email the llvmdev mailing -list: it has lots of people who are interested in languages and are often -willing to help out. -

- -

Before we end this tutorial, I want to talk about some "tips and tricks" for generating -LLVM IR. These are some of the more subtle things that may not be obvious, but -are very useful if you want to take advantage of LLVM's capabilities.

- -
- - -

Properties of the LLVM IR

- - -
- -

We have a couple common questions about code in the LLVM IR form - lets just -get these out of the way right now, shall we?

- - -

Target Independence

- - -
- -

Kaleidoscope is an example of a "portable language": any program written in -Kaleidoscope will work the same way on any target that it runs on. Many other -languages have this property, e.g. lisp, java, haskell, javascript, python, etc -(note that while these languages are portable, not all their libraries are).

- -

One nice aspect of LLVM is that it is often capable of preserving target -independence in the IR: you can take the LLVM IR for a Kaleidoscope-compiled -program and run it on any target that LLVM supports, even emitting C code and -compiling that on targets that LLVM doesn't support natively. You can trivially -tell that the Kaleidoscope compiler generates target-independent code because it -never queries for any target-specific information when generating code.

- -

The fact that LLVM provides a compact, target-independent, representation for -code gets a lot of people excited. Unfortunately, these people are usually -thinking about C or a language from the C family when they are asking questions -about language portability. I say "unfortunately", because there is really no -way to make (fully general) C code portable, other than shipping the source code -around (and of course, C source code is not actually portable in general -either - ever port a really old application from 32- to 64-bits?).

- -

The problem with C (again, in its full generality) is that it is heavily -laden with target specific assumptions. As one simple example, the preprocessor -often destructively removes target-independence from the code when it processes -the input text:

- -
-
-#ifdef __i386__
-  int X = 1;
-#else
-  int X = 42;
-#endif
-
-
- -

While it is possible to engineer more and more complex solutions to problems -like this, it cannot be solved in full generality in a way that is better than shipping -the actual source code.

- -

That said, there are interesting subsets of C that can be made portable. If -you are willing to fix primitive types to a fixed size (say int = 32-bits, -and long = 64-bits), don't care about ABI compatibility with existing binaries, -and are willing to give up some other minor features, you can have portable -code. This can make sense for specialized domains such as an -in-kernel language.

- -
- - -

Safety Guarantees

- - -
- -

Many of the languages above are also "safe" languages: it is impossible for -a program written in Java to corrupt its address space and crash the process -(assuming the JVM has no bugs). -Safety is an interesting property that requires a combination of language -design, runtime support, and often operating system support.

- -

It is certainly possible to implement a safe language in LLVM, but LLVM IR -does not itself guarantee safety. The LLVM IR allows unsafe pointer casts, -use after free bugs, buffer over-runs, and a variety of other problems. Safety -needs to be implemented as a layer on top of LLVM and, conveniently, several -groups have investigated this. Ask on the llvmdev mailing -list if you are interested in more details.

- -
- - -

Language-Specific Optimizations

- - -
- -

One thing about LLVM that turns off many people is that it does not solve all -the world's problems in one system (sorry 'world hunger', someone else will have -to solve you some other day). One specific complaint is that people perceive -LLVM as being incapable of performing high-level language-specific optimization: -LLVM "loses too much information".

- -

Unfortunately, this is really not the place to give you a full and unified -version of "Chris Lattner's theory of compiler design". Instead, I'll make a -few observations:

- -

First, you're right that LLVM does lose information. For example, as of this -writing, there is no way to distinguish in the LLVM IR whether an SSA-value came -from a C "int" or a C "long" on an ILP32 machine (other than debug info). Both -get compiled down to an 'i32' value and the information about what it came from -is lost. The more general issue here, is that the LLVM type system uses -"structural equivalence" instead of "name equivalence". Another place this -surprises people is if you have two types in a high-level language that have the -same structure (e.g. two different structs that have a single int field): these -types will compile down into a single LLVM type and it will be impossible to -tell what it came from.

- -

Second, while LLVM does lose information, LLVM is not a fixed target: we -continue to enhance and improve it in many different ways. In addition to -adding new features (LLVM did not always support exceptions or debug info), we -also extend the IR to capture important information for optimization (e.g. -whether an argument is sign or zero extended, information about pointers -aliasing, etc). Many of the enhancements are user-driven: people want LLVM to -include some specific feature, so they go ahead and extend it.

- -

Third, it is possible and easy to add language-specific -optimizations, and you have a number of choices in how to do it. As one trivial -example, it is easy to add language-specific optimization passes that -"know" things about code compiled for a language. In the case of the C family, -there is an optimization pass that "knows" about the standard C library -functions. If you call "exit(0)" in main(), it knows that it is safe to -optimize that into "return 0;" because C specifies what the 'exit' -function does.

- -

In addition to simple library knowledge, it is possible to embed a variety of -other language-specific information into the LLVM IR. If you have a specific -need and run into a wall, please bring the topic up on the llvmdev list. At the -very worst, you can always treat LLVM as if it were a "dumb code generator" and -implement the high-level optimizations you desire in your front-end, on the -language-specific AST. -

- -
- -
- - -

Tips and Tricks

- - -
- -

There is a variety of useful tips and tricks that you come to know after -working on/with LLVM that aren't obvious at first glance. Instead of letting -everyone rediscover them, this section talks about some of these issues.

- - -

Implementing portable offsetof/sizeof

- - -
- -

One interesting thing that comes up, if you are trying to keep the code -generated by your compiler "target independent", is that you often need to know -the size of some LLVM type or the offset of some field in an llvm structure. -For example, you might need to pass the size of a type into a function that -allocates memory.

- -

Unfortunately, this can vary widely across targets: for example the width of -a pointer is trivially target-specific. However, there is a clever -way to use the getelementptr instruction that allows you to compute this -in a portable way.

- -
- - -

Garbage Collected Stack Frames

- - -
- -

Some languages want to explicitly manage their stack frames, often so that -they are garbage collected or to allow easy implementation of closures. There -are often better ways to implement these features than explicit stack frames, -but LLVM -does support them, if you want. It requires your front-end to convert the -code into Continuation -Passing Style and the use of tail calls (which LLVM also supports).

- -
- -
- - -
-
- Valid CSS! - Valid HTML 4.01! - - Chris Lattner
- The LLVM Compiler Infrastructure
- Last modified: $Date$ -
- - diff --git a/cpp/llvm/docs/tutorial/index.html b/cpp/llvm/docs/tutorial/index.html deleted file mode 100644 index 0a8cae2c..00000000 --- a/cpp/llvm/docs/tutorial/index.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - LLVM Tutorial: Table of Contents - - - - - - - - -

LLVM Tutorial: Table of Contents

- -
    -
  1. Kaleidoscope: Implementing a Language with LLVM -
      -
    1. Tutorial Introduction and the Lexer
    2. -
    3. Implementing a Parser and AST
    4. -
    5. Implementing Code Generation to LLVM IR
    6. -
    7. Adding JIT and Optimizer Support
    8. -
    9. Extending the language: control flow
    10. -
    11. Extending the language: user-defined operators
    12. -
    13. Extending the language: mutable variables / SSA construction
    14. -
    15. Conclusion and other useful LLVM tidbits
    16. -
  2. -
  3. Kaleidoscope: Implementing a Language with LLVM in Objective Caml -
      -
    1. Tutorial Introduction and the Lexer
    2. -
    3. Implementing a Parser and AST
    4. -
    5. Implementing Code Generation to LLVM IR
    6. -
    7. Adding JIT and Optimizer Support
    8. -
    9. Extending the language: control flow
    10. -
    11. Extending the language: user-defined operators
    12. -
    13. Extending the language: mutable variables / SSA construction
    14. -
    15. Conclusion and other useful LLVM tidbits
    16. -
  4. -
  5. Advanced Topics -
      -
    1. Writing - an Optimization for LLVM
    2. -
  6. -
- - - diff --git a/cpp/llvm/examples/BrainF/Makefile b/cpp/llvm/examples/BrainF/Makefile deleted file mode 100644 index 2c3e0662..00000000 --- a/cpp/llvm/examples/BrainF/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/BrainF/Makefile ----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../.. -TOOLNAME = BrainF -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := jit bitwriter nativecodegen interpreter - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/ExceptionDemo/Makefile b/cpp/llvm/examples/ExceptionDemo/Makefile deleted file mode 100644 index 48074473..00000000 --- a/cpp/llvm/examples/ExceptionDemo/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- examples/ExceptionDemo/Makefile --------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===---------------------------------------------------------------------===## -LEVEL = ../.. -TOOLNAME = ExceptionDemo -EXAMPLE_TOOL = 1 -REQUIRES_EH = 1 - -LINK_COMPONENTS := jit interpreter nativecodegen - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Fibonacci/Makefile b/cpp/llvm/examples/Fibonacci/Makefile deleted file mode 100644 index 71f6ba0e..00000000 --- a/cpp/llvm/examples/Fibonacci/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- examples/Fibonacci/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -TOOLNAME = Fibonacci -EXAMPLE_TOOL = 1 - -# Link in JIT support -LINK_COMPONENTS := jit interpreter nativecodegen - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/HowToUseJIT/Makefile b/cpp/llvm/examples/HowToUseJIT/Makefile deleted file mode 100644 index c8919db9..00000000 --- a/cpp/llvm/examples/HowToUseJIT/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/HowToUseJIT/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../.. -TOOLNAME = HowToUseJIT -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := jit interpreter nativecodegen - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter2/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter2/Makefile deleted file mode 100644 index 1a9b94ce..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter2/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- examples/Kaleidoscope/Chapter2/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch2 -EXAMPLE_TOOL = 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter3/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter3/Makefile deleted file mode 100644 index 4cc6948d..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter3/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/Kaleidoscope/Chapter3/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch3 -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := core - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter4/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter4/Makefile deleted file mode 100644 index 30162d94..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter4/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/Kaleidoscope/Chapter4/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch4 -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := core jit native - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter5/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter5/Makefile deleted file mode 100644 index d1f5e203..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter5/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/Kaleidoscope/Chapter5/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch5 -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := core jit native - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter6/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter6/Makefile deleted file mode 100644 index a5fbcbdf..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter6/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/Kaleidoscope/Chapter6/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch6 -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := core jit native - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Chapter7/Makefile b/cpp/llvm/examples/Kaleidoscope/Chapter7/Makefile deleted file mode 100644 index 6cec323e..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Chapter7/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- examples/Kaleidoscope/Chapter7/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -TOOLNAME = Kaleidoscope-Ch7 -EXAMPLE_TOOL = 1 -REQUIRES_RTTI := 1 - -LINK_COMPONENTS := core jit native - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Kaleidoscope/Makefile b/cpp/llvm/examples/Kaleidoscope/Makefile deleted file mode 100644 index bd0c252c..00000000 --- a/cpp/llvm/examples/Kaleidoscope/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/Kaleidoscope/Makefile ----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL=../.. - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS:= Chapter2 Chapter3 Chapter4 Chapter5 Chapter6 Chapter7 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/Makefile b/cpp/llvm/examples/Makefile deleted file mode 100644 index 50a6db76..00000000 --- a/cpp/llvm/examples/Makefile +++ /dev/null @@ -1,32 +0,0 @@ -##===- examples/Makefile -----------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL=.. - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS:= BrainF Fibonacci HowToUseJIT Kaleidoscope ModuleMaker - -ifeq ($(HAVE_PTHREAD),1) -PARALLEL_DIRS += ParallelJIT -endif - -ifeq ($(LLVM_ON_UNIX),1) - ifeq ($(ARCH),x86) - PARALLEL_DIRS += ExceptionDemo - endif - ifeq ($(ARCH),x86_64) - PARALLEL_DIRS += ExceptionDemo - endif -endif - -ifeq ($(filter $(BINDINGS_TO_BUILD),ocaml),ocaml) - PARALLEL_DIRS += OCaml-Kaleidoscope -endif - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/ModuleMaker/Makefile b/cpp/llvm/examples/ModuleMaker/Makefile deleted file mode 100644 index 9454cf51..00000000 --- a/cpp/llvm/examples/ModuleMaker/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- examples/ModuleMaker/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL=../.. -TOOLNAME=ModuleMaker -EXAMPLE_TOOL = 1 -LINK_COMPONENTS := bitwriter - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter2/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter2/Makefile deleted file mode 100644 index 8fc03da0..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter2/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter2/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 2. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch2 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm - -OCAMLCFLAGS += -pp camlp4of - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter3/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter3/Makefile deleted file mode 100644 index fdbcd519..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter3/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter3/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 3. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch3 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm llvm_analysis - -OCAMLCFLAGS += -pp camlp4of - -ExcludeSources = $(PROJ_SRC_DIR)/myocamlbuild.ml - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter4/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter4/Makefile deleted file mode 100644 index d9c3f49b..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter4/Makefile +++ /dev/null @@ -1,25 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter4/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 4. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch4 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm llvm_analysis llvm_executionengine llvm_target \ - llvm_scalar_opts - -OCAMLCFLAGS += -pp camlp4of - -ExcludeSources = $(PROJ_SRC_DIR)/myocamlbuild.ml - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter5/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter5/Makefile deleted file mode 100644 index f31c10d3..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter5/Makefile +++ /dev/null @@ -1,25 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter5/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 5. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch5 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm llvm_analysis llvm_executionengine llvm_target \ - llvm_scalar_opts - -OCAMLCFLAGS += -pp camlp4of - -ExcludeSources = $(PROJ_SRC_DIR)/myocamlbuild.ml - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter6/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter6/Makefile deleted file mode 100644 index 21f0c53d..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter6/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter6/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 6. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch6 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm llvm_analysis llvm_executionengine llvm_target \ - llvm_scalar_opts - -OCAMLCFLAGS += -pp camlp4of - -OcamlSources1 = \ - $(PROJ_SRC_DIR)/ast.ml \ - $(PROJ_SRC_DIR)/parser.ml \ - $(PROJ_SRC_DIR)/codegen.ml \ - $(PROJ_SRC_DIR)/lexer.ml \ - $(PROJ_SRC_DIR)/token.ml \ - $(PROJ_SRC_DIR)/toplevel.ml \ - $(PROJ_SRC_DIR)/toy.ml - -ExcludeSources = $(PROJ_SRC_DIR)/myocamlbuild.ml - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter7/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter7/Makefile deleted file mode 100644 index 99686e17..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Chapter7/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Chapter7/Makefile -------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This is the makefile for the Objective Caml kaleidoscope tutorial, chapter 7. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../../.. -TOOLNAME := OCaml-Kaleidoscope-Ch7 -EXAMPLE_TOOL := 1 -UsedComponents := core -UsedOcamLibs := llvm llvm_analysis llvm_executionengine llvm_target \ - llvm_scalar_opts - -OCAMLCFLAGS += -pp camlp4of - -OcamlSources1 = \ - $(PROJ_SRC_DIR)/ast.ml \ - $(PROJ_SRC_DIR)/parser.ml \ - $(PROJ_SRC_DIR)/codegen.ml \ - $(PROJ_SRC_DIR)/lexer.ml \ - $(PROJ_SRC_DIR)/token.ml \ - $(PROJ_SRC_DIR)/toplevel.ml \ - $(PROJ_SRC_DIR)/toy.ml - -ExcludeSources = $(PROJ_SRC_DIR)/myocamlbuild.ml - -include $(LEVEL)/bindings/ocaml/Makefile.ocaml diff --git a/cpp/llvm/examples/OCaml-Kaleidoscope/Makefile b/cpp/llvm/examples/OCaml-Kaleidoscope/Makefile deleted file mode 100644 index 5342b940..00000000 --- a/cpp/llvm/examples/OCaml-Kaleidoscope/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- examples/OCaml-Kaleidoscope/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL=../.. - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS:= Chapter2 Chapter3 Chapter4 Chapter5 Chapter6 Chapter7 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/examples/ParallelJIT/Makefile b/cpp/llvm/examples/ParallelJIT/Makefile deleted file mode 100644 index 8a49d427..00000000 --- a/cpp/llvm/examples/ParallelJIT/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- examples/ParallelJIT/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../.. -TOOLNAME = ParallelJIT -EXAMPLE_TOOL = 1 - -LINK_COMPONENTS := jit interpreter nativecodegen - -include $(LEVEL)/Makefile.common - -LIBS += -lpthread diff --git a/cpp/llvm/lib/Analysis/IPA/Makefile b/cpp/llvm/lib/Analysis/IPA/Makefile deleted file mode 100644 index b850c9ff..00000000 --- a/cpp/llvm/lib/Analysis/IPA/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Analysis/IPA/Makefile ---------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMipa -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Analysis/Makefile b/cpp/llvm/lib/Analysis/Makefile deleted file mode 100644 index 4af6d350..00000000 --- a/cpp/llvm/lib/Analysis/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Analysis/Makefile -------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMAnalysis -DIRS = IPA -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Archive/Makefile b/cpp/llvm/lib/Archive/Makefile deleted file mode 100644 index da978040..00000000 --- a/cpp/llvm/lib/Archive/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- lib/Archive/Makefile --------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMArchive - -# We only want an archive so only those modules actually used by a tool are -# included. -BUILD_ARCHIVE := 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/AsmParser/Makefile b/cpp/llvm/lib/AsmParser/Makefile deleted file mode 100644 index 995bb0e1..00000000 --- a/cpp/llvm/lib/AsmParser/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- lib/AsmParser/Makefile ------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME := LLVMAsmParser -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Bitcode/Makefile b/cpp/llvm/lib/Bitcode/Makefile deleted file mode 100644 index 2d6b5ad1..00000000 --- a/cpp/llvm/lib/Bitcode/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- lib/Bitcode/Makefile --------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -PARALLEL_DIRS = Reader Writer - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Bitcode/Reader/Makefile b/cpp/llvm/lib/Bitcode/Reader/Makefile deleted file mode 100644 index 59af8d53..00000000 --- a/cpp/llvm/lib/Bitcode/Reader/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Bitcode/Reader/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMBitReader -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Bitcode/Writer/Makefile b/cpp/llvm/lib/Bitcode/Writer/Makefile deleted file mode 100644 index 7b0bd721..00000000 --- a/cpp/llvm/lib/Bitcode/Writer/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Bitcode/Reader/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMBitWriter -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/CodeGen/AsmPrinter/Makefile b/cpp/llvm/lib/CodeGen/AsmPrinter/Makefile deleted file mode 100644 index 60aa6cbc..00000000 --- a/cpp/llvm/lib/CodeGen/AsmPrinter/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- lib/CodeGen/AsmPrinter/Makefile ---------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMAsmPrinter - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/CodeGen/Makefile b/cpp/llvm/lib/CodeGen/Makefile deleted file mode 100644 index 4ab3e3c0..00000000 --- a/cpp/llvm/lib/CodeGen/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -##===- lib/CodeGen/Makefile --------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMCodeGen -PARALLEL_DIRS = SelectionDAG AsmPrinter -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - -# Xcode prior to 2.4 generates an error in -pedantic mode with use of HUGE_VAL -# in this directory. Disable -pedantic for this broken compiler. -ifneq ($(HUGE_VAL_SANITY),yes) -CompileCommonOpts := $(filter-out -pedantic, $(CompileCommonOpts)) -endif - diff --git a/cpp/llvm/lib/CodeGen/SelectionDAG/Makefile b/cpp/llvm/lib/CodeGen/SelectionDAG/Makefile deleted file mode 100644 index ea716fda..00000000 --- a/cpp/llvm/lib/CodeGen/SelectionDAG/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- lib/CodeGen/SelectionDAG/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMSelectionDAG - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/DebugInfo/Makefile b/cpp/llvm/lib/DebugInfo/Makefile deleted file mode 100644 index 1292b572..00000000 --- a/cpp/llvm/lib/DebugInfo/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- lib/DebugInfo/Makefile ------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMDebugInfo -BUILD_ARCHIVE := 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/ExecutionEngine/IntelJITEvents/Makefile b/cpp/llvm/lib/ExecutionEngine/IntelJITEvents/Makefile deleted file mode 100644 index ba75ac6f..00000000 --- a/cpp/llvm/lib/ExecutionEngine/IntelJITEvents/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- lib/ExecutionEngine/JITProfile/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -LIBRARYNAME = LLVMIntelJITEvents - -include $(LEVEL)/Makefile.config - -SOURCES := IntelJITEventListener.cpp -CPPFLAGS += -I$(INTEL_JITEVENTS_INCDIR) -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LLVM_SRC_ROOT)/Makefile.rules diff --git a/cpp/llvm/lib/ExecutionEngine/Interpreter/Makefile b/cpp/llvm/lib/ExecutionEngine/Interpreter/Makefile deleted file mode 100644 index 5def1365..00000000 --- a/cpp/llvm/lib/ExecutionEngine/Interpreter/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- lib/ExecutionEngine/Interpreter/Makefile ------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMInterpreter - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/ExecutionEngine/JIT/Makefile b/cpp/llvm/lib/ExecutionEngine/JIT/Makefile deleted file mode 100644 index aafa3d9d..00000000 --- a/cpp/llvm/lib/ExecutionEngine/JIT/Makefile +++ /dev/null @@ -1,38 +0,0 @@ -##===- lib/ExecutionEngine/JIT/Makefile --------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMJIT - -# Get the $(ARCH) setting -include $(LEVEL)/Makefile.config - -# Enable the X86 JIT if compiling on X86 -ifeq ($(ARCH), x86) - ENABLE_X86_JIT = 1 -endif - -# This flag can also be used on the command line to force inclusion -# of the X86 JIT on non-X86 hosts -ifdef ENABLE_X86_JIT - CPPFLAGS += -DENABLE_X86_JIT -endif - -# Enable the Sparc JIT if compiling on Sparc -ifeq ($(ARCH), Sparc) - ENABLE_SPARC_JIT = 1 -endif - -# This flag can also be used on the command line to force inclusion -# of the Sparc JIT on non-Sparc hosts -ifdef ENABLE_SPARC_JIT - CPPFLAGS += -DENABLE_SPARC_JIT -endif - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/ExecutionEngine/MCJIT/Makefile b/cpp/llvm/lib/ExecutionEngine/MCJIT/Makefile deleted file mode 100644 index 967efbc0..00000000 --- a/cpp/llvm/lib/ExecutionEngine/MCJIT/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- lib/ExecutionEngine/MCJIT/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMMCJIT - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/ExecutionEngine/Makefile b/cpp/llvm/lib/ExecutionEngine/Makefile deleted file mode 100644 index c26e0ada..00000000 --- a/cpp/llvm/lib/ExecutionEngine/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- lib/ExecutionEngine/Makefile ------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../.. -LIBRARYNAME = LLVMExecutionEngine - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS = Interpreter JIT MCJIT RuntimeDyld - -ifeq ($(USE_INTEL_JITEVENTS), 1) -PARALLEL_DIRS += IntelJITEvents -endif - -ifeq ($(USE_OPROFILE), 1) -PARALLEL_DIRS += OProfileJIT -endif - -include $(LLVM_SRC_ROOT)/Makefile.rules diff --git a/cpp/llvm/lib/ExecutionEngine/OProfileJIT/Makefile b/cpp/llvm/lib/ExecutionEngine/OProfileJIT/Makefile deleted file mode 100644 index fd3adce2..00000000 --- a/cpp/llvm/lib/ExecutionEngine/OProfileJIT/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- lib/ExecutionEngine/OProfileJIT/Makefile ------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -LIBRARYNAME = LLVMOProfileJIT - -include $(LEVEL)/Makefile.config - -SOURCES += OProfileJITEventListener.cpp \ - OProfileWrapper.cpp -CPPFLAGS += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LLVM_SRC_ROOT)/Makefile.rules diff --git a/cpp/llvm/lib/ExecutionEngine/RuntimeDyld/Makefile b/cpp/llvm/lib/ExecutionEngine/RuntimeDyld/Makefile deleted file mode 100644 index 5d6f26d9..00000000 --- a/cpp/llvm/lib/ExecutionEngine/RuntimeDyld/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- lib/ExecutionEngine/MCJIT/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMRuntimeDyld - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Linker/Makefile b/cpp/llvm/lib/Linker/Makefile deleted file mode 100644 index 19e646b7..00000000 --- a/cpp/llvm/lib/Linker/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Linker/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMLinker -BUILD_ARCHIVE := 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/MC/MCDisassembler/Makefile b/cpp/llvm/lib/MC/MCDisassembler/Makefile deleted file mode 100644 index 7d71cd38..00000000 --- a/cpp/llvm/lib/MC/MCDisassembler/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- lib/MC/MCDisassembler/Makefile ----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMMCDisassembler - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/MC/MCParser/Makefile b/cpp/llvm/lib/MC/MCParser/Makefile deleted file mode 100644 index 44777576..00000000 --- a/cpp/llvm/lib/MC/MCParser/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/MC/MCParser/Makefile ----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMMCParser -BUILD_ARCHIVE := 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/MC/Makefile b/cpp/llvm/lib/MC/Makefile deleted file mode 100644 index bf8b7c0e..00000000 --- a/cpp/llvm/lib/MC/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/MC/Makefile -------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMMC -BUILD_ARCHIVE := 1 -PARALLEL_DIRS := MCParser MCDisassembler - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Makefile b/cpp/llvm/lib/Makefile deleted file mode 100644 index fd575cd1..00000000 --- a/cpp/llvm/lib/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- lib/Makefile ----------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = .. - -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS := VMCore AsmParser Bitcode Archive Analysis Transforms CodeGen \ - Target ExecutionEngine Linker MC Object DebugInfo - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Object/Makefile b/cpp/llvm/lib/Object/Makefile deleted file mode 100644 index 79388dc9..00000000 --- a/cpp/llvm/lib/Object/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- lib/Object/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMObject -BUILD_ARCHIVE := 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Support/Makefile b/cpp/llvm/lib/Support/Makefile deleted file mode 100644 index d68e500c..00000000 --- a/cpp/llvm/lib/Support/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -##===- lib/Support/Makefile --------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMSupport -BUILD_ARCHIVE = 1 - -## FIXME: This only requires RTTI because tblgen uses it. Fix that. -REQUIRES_RTTI = 1 - -EXTRA_DIST = Unix Win32 README.txt - -include $(LEVEL)/Makefile.common - -CompileCommonOpts := $(filter-out -pedantic,$(CompileCommonOpts)) -CompileCommonOpts := $(filter-out -Wno-long-long,$(CompileCommonOpts)) diff --git a/cpp/llvm/lib/TableGen/Makefile b/cpp/llvm/lib/TableGen/Makefile deleted file mode 100644 index 44724389..00000000 --- a/cpp/llvm/lib/TableGen/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- lib/TableGen/Makefile -------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMTableGen -BUILD_ARCHIVE = 1 - -## FIXME: This only requires RTTI because tblgen uses it. Fix that. -REQUIRES_RTTI = 1 -REQUIRES_EH = 1 - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/AsmParser/Makefile b/cpp/llvm/lib/Target/ARM/AsmParser/Makefile deleted file mode 100644 index 841516ff..00000000 --- a/cpp/llvm/lib/Target/ARM/AsmParser/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/ARM/AsmParser/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMARMAsmParser - -# Hack: we need to include 'main' ARM target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/Disassembler/Makefile b/cpp/llvm/lib/Target/ARM/Disassembler/Makefile deleted file mode 100644 index 031b6aca..00000000 --- a/cpp/llvm/lib/Target/ARM/Disassembler/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/ARM/Disassembler/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMARMDisassembler - -# Hack: we need to include 'main' arm target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/InstPrinter/Makefile b/cpp/llvm/lib/Target/ARM/InstPrinter/Makefile deleted file mode 100644 index 65d372e4..00000000 --- a/cpp/llvm/lib/Target/ARM/InstPrinter/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/ARM/AsmPrinter/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMARMAsmPrinter - -# Hack: we need to include 'main' arm target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/ARM/MCTargetDesc/Makefile deleted file mode 100644 index 448ed9df..00000000 --- a/cpp/llvm/lib/Target/ARM/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/ARM/TargetDesc/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMARMDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/Makefile b/cpp/llvm/lib/Target/ARM/Makefile deleted file mode 100644 index 3e48ed11..00000000 --- a/cpp/llvm/lib/Target/ARM/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- lib/Target/ARM/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMARMCodeGen -TARGET = ARM - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = ARMGenRegisterInfo.inc ARMGenInstrInfo.inc \ - ARMGenAsmWriter.inc ARMGenAsmMatcher.inc \ - ARMGenDAGISel.inc ARMGenSubtargetInfo.inc \ - ARMGenCodeEmitter.inc ARMGenCallingConv.inc \ - ARMGenEDInfo.inc ARMGenFastISel.inc ARMGenMCCodeEmitter.inc \ - ARMGenMCPseudoLowering.inc ARMGenDisassemblerTables.inc - -DIRS = InstPrinter AsmParser Disassembler TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/ARM/TargetInfo/Makefile b/cpp/llvm/lib/Target/ARM/TargetInfo/Makefile deleted file mode 100644 index 6292ab14..00000000 --- a/cpp/llvm/lib/Target/ARM/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/ARM/TargetInfo/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMARMInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/CellSPU/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/CellSPU/MCTargetDesc/Makefile deleted file mode 100644 index 10d9a422..00000000 --- a/cpp/llvm/lib/Target/CellSPU/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/CellSPU/TargetDesc/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMCellSPUDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/CellSPU/Makefile b/cpp/llvm/lib/Target/CellSPU/Makefile deleted file mode 100644 index d7a8247f..00000000 --- a/cpp/llvm/lib/Target/CellSPU/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -##===- lib/Target/CellSPU/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMCellSPUCodeGen -TARGET = SPU -BUILT_SOURCES = SPUGenInstrInfo.inc SPUGenRegisterInfo.inc \ - SPUGenAsmWriter.inc SPUGenCodeEmitter.inc \ - SPUGenDAGISel.inc \ - SPUGenSubtargetInfo.inc SPUGenCallingConv.inc - -DIRS = TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/CellSPU/TargetInfo/Makefile b/cpp/llvm/lib/Target/CellSPU/TargetInfo/Makefile deleted file mode 100644 index 9cb6827b..00000000 --- a/cpp/llvm/lib/Target/CellSPU/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/CellSPU/TargetInfo/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMCellSPUInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/CppBackend/Makefile b/cpp/llvm/lib/Target/CppBackend/Makefile deleted file mode 100644 index efc7463f..00000000 --- a/cpp/llvm/lib/Target/CppBackend/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/CppBackend/Makefile --- ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMCppBackendCodeGen -DIRS = TargetInfo - -include $(LEVEL)/Makefile.common - -CompileCommonOpts += -Wno-format diff --git a/cpp/llvm/lib/Target/CppBackend/TargetInfo/Makefile b/cpp/llvm/lib/Target/CppBackend/TargetInfo/Makefile deleted file mode 100644 index 6e682838..00000000 --- a/cpp/llvm/lib/Target/CppBackend/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/CppBackend/TargetInfo/Makefile -----------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMCppBackendInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Hexagon/InstPrinter/Makefile b/cpp/llvm/lib/Target/Hexagon/InstPrinter/Makefile deleted file mode 100644 index 20331d88..00000000 --- a/cpp/llvm/lib/Target/Hexagon/InstPrinter/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/Hexagon/InstPrinter/Makefile ----------------------------===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMHexagonAsmPrinter - -# Hack: we need to include 'main' Hexagon target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Hexagon/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/Hexagon/MCTargetDesc/Makefile deleted file mode 100644 index 885be2dd..00000000 --- a/cpp/llvm/lib/Target/Hexagon/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/Hexagon/TargetDesc/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMHexagonDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Hexagon/Makefile b/cpp/llvm/lib/Target/Hexagon/Makefile deleted file mode 100644 index dc387c54..00000000 --- a/cpp/llvm/lib/Target/Hexagon/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/Hexagon/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -LIBRARYNAME = LLVMHexagonCodeGen -TARGET = Hexagon - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = HexagonGenRegisterInfo.inc \ - HexagonGenInstrInfo.inc \ - HexagonGenAsmWriter.inc \ - HexagonGenDAGISel.inc HexagonGenSubtargetInfo.inc \ - HexagonGenCallingConv.inc \ - HexagonGenDFAPacketizer.inc - -DIRS = InstPrinter TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Hexagon/TargetInfo/Makefile b/cpp/llvm/lib/Target/Hexagon/TargetInfo/Makefile deleted file mode 100644 index 494cca11..00000000 --- a/cpp/llvm/lib/Target/Hexagon/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/Hexagon/TargetInfo/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMHexagonInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MBlaze/AsmParser/Makefile b/cpp/llvm/lib/Target/MBlaze/AsmParser/Makefile deleted file mode 100644 index 1e68766a..00000000 --- a/cpp/llvm/lib/Target/MBlaze/AsmParser/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/MBlaze/AsmParser/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMBlazeAsmParser - -# Hack: we need to include 'main' MBlaze target directory for private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MBlaze/Disassembler/Makefile b/cpp/llvm/lib/Target/MBlaze/Disassembler/Makefile deleted file mode 100644 index 0530b328..00000000 --- a/cpp/llvm/lib/Target/MBlaze/Disassembler/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/MBlaze/Disassembler/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMBlazeDisassembler - -# Hack: we need to include 'main' MBlaze target directory to grab headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MBlaze/InstPrinter/Makefile b/cpp/llvm/lib/Target/MBlaze/InstPrinter/Makefile deleted file mode 100644 index 9fb6e869..00000000 --- a/cpp/llvm/lib/Target/MBlaze/InstPrinter/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/MBlaze/AsmPrinter/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMBlazeAsmPrinter - -# Hack: we need to include 'main' MBlaze target directory to grab -# private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MBlaze/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/MBlaze/MCTargetDesc/Makefile deleted file mode 100644 index 71075ffb..00000000 --- a/cpp/llvm/lib/Target/MBlaze/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/MBlaze/TargetDesc/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMBlazeDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MBlaze/Makefile b/cpp/llvm/lib/Target/MBlaze/Makefile deleted file mode 100644 index 83c2a7d3..00000000 --- a/cpp/llvm/lib/Target/MBlaze/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- lib/Target/MBlaze/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../.. -LIBRARYNAME = LLVMMBlazeCodeGen -TARGET = MBlaze - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = MBlazeGenRegisterInfo.inc MBlazeGenInstrInfo.inc \ - MBlazeGenAsmWriter.inc \ - MBlazeGenDAGISel.inc MBlazeGenAsmMatcher.inc \ - MBlazeGenCodeEmitter.inc MBlazeGenCallingConv.inc \ - MBlazeGenSubtargetInfo.inc MBlazeGenIntrinsics.inc \ - MBlazeGenEDInfo.inc - -DIRS = InstPrinter AsmParser Disassembler TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/MBlaze/TargetInfo/Makefile b/cpp/llvm/lib/Target/MBlaze/TargetInfo/Makefile deleted file mode 100644 index fb7ea118..00000000 --- a/cpp/llvm/lib/Target/MBlaze/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/MBlaze/TargetInfo/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMBlazeInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MSP430/InstPrinter/Makefile b/cpp/llvm/lib/Target/MSP430/InstPrinter/Makefile deleted file mode 100644 index a5293ab8..00000000 --- a/cpp/llvm/lib/Target/MSP430/InstPrinter/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/MSP430/AsmPrinter/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMSP430AsmPrinter - -# Hack: we need to include 'main' MSP430 target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MSP430/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/MSP430/MCTargetDesc/Makefile deleted file mode 100644 index bb857998..00000000 --- a/cpp/llvm/lib/Target/MSP430/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/MSP430/TargetDesc/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMSP430Desc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/MSP430/Makefile b/cpp/llvm/lib/Target/MSP430/Makefile deleted file mode 100644 index 82216edd..00000000 --- a/cpp/llvm/lib/Target/MSP430/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/MSP430/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMMSP430CodeGen -TARGET = MSP430 - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = MSP430GenRegisterInfo.inc MSP430GenInstrInfo.inc \ - MSP430GenAsmWriter.inc \ - MSP430GenDAGISel.inc MSP430GenCallingConv.inc \ - MSP430GenSubtargetInfo.inc - -DIRS = InstPrinter TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/MSP430/TargetInfo/Makefile b/cpp/llvm/lib/Target/MSP430/TargetInfo/Makefile deleted file mode 100644 index abb08f25..00000000 --- a/cpp/llvm/lib/Target/MSP430/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/MSP430/TargetInfo/Makefile ---------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMSP430Info - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Makefile b/cpp/llvm/lib/Target/Makefile deleted file mode 100644 index 50a360f1..00000000 --- a/cpp/llvm/lib/Target/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -#===- lib/Target/Makefile ----------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -LIBRARYNAME = LLVMTarget -BUILD_ARCHIVE = 1 - -# We include this early so we can access the value of TARGETS_TO_BUILD as the -# value for PARALLEL_DIRS which must be set before Makefile.rules is included -include $(LEVEL)/Makefile.config - -PARALLEL_DIRS := $(TARGETS_TO_BUILD) - -include $(LLVM_SRC_ROOT)/Makefile.rules diff --git a/cpp/llvm/lib/Target/Mips/AsmParser/Makefile b/cpp/llvm/lib/Target/Mips/AsmParser/Makefile deleted file mode 100644 index 679acee9..00000000 --- a/cpp/llvm/lib/Target/Mips/AsmParser/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/Mips/AsmParser/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMipsAsmParser - -# Hack: we need to include 'main' mips target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Mips/Disassembler/Makefile b/cpp/llvm/lib/Target/Mips/Disassembler/Makefile deleted file mode 100644 index a78feba1..00000000 --- a/cpp/llvm/lib/Target/Mips/Disassembler/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/Mips/Disassembler/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMipsDisassembler - -# Hack: we need to include 'main' Mips target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Mips/InstPrinter/Makefile b/cpp/llvm/lib/Target/Mips/InstPrinter/Makefile deleted file mode 100644 index f07f3ed3..00000000 --- a/cpp/llvm/lib/Target/Mips/InstPrinter/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/Mips/AsmPrinter/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMipsAsmPrinter - -# Hack: we need to include 'main' mips target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Mips/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/Mips/MCTargetDesc/Makefile deleted file mode 100644 index 7fe2086a..00000000 --- a/cpp/llvm/lib/Target/Mips/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/Mips/TargetDesc/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMMipsDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Mips/Makefile b/cpp/llvm/lib/Target/Mips/Makefile deleted file mode 100644 index 596f0714..00000000 --- a/cpp/llvm/lib/Target/Mips/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/Mips/Makefile ----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMMipsCodeGen -TARGET = Mips - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = MipsGenRegisterInfo.inc MipsGenInstrInfo.inc \ - MipsGenAsmWriter.inc MipsGenCodeEmitter.inc \ - MipsGenDAGISel.inc MipsGenCallingConv.inc \ - MipsGenSubtargetInfo.inc MipsGenMCCodeEmitter.inc \ - MipsGenEDInfo.inc MipsGenDisassemblerTables.inc -DIRS = InstPrinter Disassembler AsmParser TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/Mips/TargetInfo/Makefile b/cpp/llvm/lib/Target/Mips/TargetInfo/Makefile deleted file mode 100644 index 32f4e169..00000000 --- a/cpp/llvm/lib/Target/Mips/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/Mips/TargetInfo/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMMipsInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PTX/InstPrinter/Makefile b/cpp/llvm/lib/Target/PTX/InstPrinter/Makefile deleted file mode 100644 index 0ccfe440..00000000 --- a/cpp/llvm/lib/Target/PTX/InstPrinter/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/PTX/AsmPrinter/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMPTXAsmPrinter - -# Hack: we need to include 'main' ptx target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/PTX/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/PTX/MCTargetDesc/Makefile deleted file mode 100644 index 35f5a7b2..00000000 --- a/cpp/llvm/lib/Target/PTX/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/PTX/TargetDesc/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMPTXDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PTX/Makefile b/cpp/llvm/lib/Target/PTX/Makefile deleted file mode 100644 index fa096349..00000000 --- a/cpp/llvm/lib/Target/PTX/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/PTX/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMPTXCodeGen -TARGET = PTX - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = PTXGenAsmWriter.inc \ - PTXGenDAGISel.inc \ - PTXGenInstrInfo.inc \ - PTXGenRegisterInfo.inc \ - PTXGenSubtargetInfo.inc - -DIRS = InstPrinter TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PTX/TargetInfo/Makefile b/cpp/llvm/lib/Target/PTX/TargetInfo/Makefile deleted file mode 100644 index 86197858..00000000 --- a/cpp/llvm/lib/Target/PTX/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/PTX/TargetInfo/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMPTXInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PowerPC/InstPrinter/Makefile b/cpp/llvm/lib/Target/PowerPC/InstPrinter/Makefile deleted file mode 100644 index f097e842..00000000 --- a/cpp/llvm/lib/Target/PowerPC/InstPrinter/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/PowerPC/AsmPrinter/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMPowerPCAsmPrinter - -# Hack: we need to include 'main' powerpc target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PowerPC/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/PowerPC/MCTargetDesc/Makefile deleted file mode 100644 index 9db66622..00000000 --- a/cpp/llvm/lib/Target/PowerPC/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/PowerPC/TargetDesc/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMPowerPCDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PowerPC/Makefile b/cpp/llvm/lib/Target/PowerPC/Makefile deleted file mode 100644 index 1617b26c..00000000 --- a/cpp/llvm/lib/Target/PowerPC/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/PowerPC/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMPowerPCCodeGen -TARGET = PPC - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = PPCGenRegisterInfo.inc \ - PPCGenAsmWriter.inc PPCGenCodeEmitter.inc \ - PPCGenInstrInfo.inc PPCGenDAGISel.inc \ - PPCGenSubtargetInfo.inc PPCGenCallingConv.inc \ - PPCGenMCCodeEmitter.inc - -DIRS = InstPrinter TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/PowerPC/TargetInfo/Makefile b/cpp/llvm/lib/Target/PowerPC/TargetInfo/Makefile deleted file mode 100644 index a101aa4a..00000000 --- a/cpp/llvm/lib/Target/PowerPC/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/PowerPC/TargetInfo/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMPowerPCInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Sparc/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/Sparc/MCTargetDesc/Makefile deleted file mode 100644 index abcbe2da..00000000 --- a/cpp/llvm/lib/Target/Sparc/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/Sparc/TargetDesc/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMSparcDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/Sparc/Makefile b/cpp/llvm/lib/Target/Sparc/Makefile deleted file mode 100644 index 4b81ada9..00000000 --- a/cpp/llvm/lib/Target/Sparc/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -##===- lib/Target/Sparc/Makefile ---------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMSparcCodeGen -TARGET = Sparc - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = SparcGenRegisterInfo.inc SparcGenInstrInfo.inc \ - SparcGenAsmWriter.inc SparcGenDAGISel.inc \ - SparcGenSubtargetInfo.inc SparcGenCallingConv.inc - -DIRS = TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/Sparc/TargetInfo/Makefile b/cpp/llvm/lib/Target/Sparc/TargetInfo/Makefile deleted file mode 100644 index 641ed871..00000000 --- a/cpp/llvm/lib/Target/Sparc/TargetInfo/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/Sparc/TargetInfo/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMSparcInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/AsmParser/Makefile b/cpp/llvm/lib/Target/X86/AsmParser/Makefile deleted file mode 100644 index fb976079..00000000 --- a/cpp/llvm/lib/Target/X86/AsmParser/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/X86/AsmParser/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86AsmParser - -# Hack: we need to include 'main' x86 target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/Disassembler/Makefile b/cpp/llvm/lib/Target/X86/Disassembler/Makefile deleted file mode 100644 index 8669fd8f..00000000 --- a/cpp/llvm/lib/Target/X86/Disassembler/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/X86/Disassembler/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86Disassembler - -# Hack: we need to include 'main' x86 target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/InstPrinter/Makefile b/cpp/llvm/lib/Target/X86/InstPrinter/Makefile deleted file mode 100644 index c82aa330..00000000 --- a/cpp/llvm/lib/Target/X86/InstPrinter/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/X86/AsmPrinter/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86AsmPrinter - -# Hack: we need to include 'main' x86 target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/X86/MCTargetDesc/Makefile deleted file mode 100644 index b19774ee..00000000 --- a/cpp/llvm/lib/Target/X86/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/X86/TargetDesc/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86Desc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/Makefile b/cpp/llvm/lib/Target/X86/Makefile deleted file mode 100644 index 949661eb..00000000 --- a/cpp/llvm/lib/Target/X86/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- lib/Target/X86/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMX86CodeGen -TARGET = X86 - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = X86GenRegisterInfo.inc X86GenInstrInfo.inc \ - X86GenAsmWriter.inc X86GenAsmMatcher.inc \ - X86GenAsmWriter1.inc X86GenDAGISel.inc \ - X86GenDisassemblerTables.inc X86GenFastISel.inc \ - X86GenCallingConv.inc X86GenSubtargetInfo.inc \ - X86GenEDInfo.inc - -DIRS = InstPrinter AsmParser Disassembler TargetInfo MCTargetDesc Utils - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/TargetInfo/Makefile b/cpp/llvm/lib/Target/X86/TargetInfo/Makefile deleted file mode 100644 index ee91982d..00000000 --- a/cpp/llvm/lib/Target/X86/TargetInfo/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/X86/TargetInfo/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86Info - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/X86/Utils/Makefile b/cpp/llvm/lib/Target/X86/Utils/Makefile deleted file mode 100644 index 1df6f0f5..00000000 --- a/cpp/llvm/lib/Target/X86/Utils/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Target/X86/Utils/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../../../.. -LIBRARYNAME = LLVMX86Utils - -# Hack: we need to include 'main' x86 target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/XCore/MCTargetDesc/Makefile b/cpp/llvm/lib/Target/XCore/MCTargetDesc/Makefile deleted file mode 100644 index de61543b..00000000 --- a/cpp/llvm/lib/Target/XCore/MCTargetDesc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/XCore/TargetDesc/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMXCoreDesc - -# Hack: we need to include 'main' target directory to grab private headers -CPP.Flags += -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Target/XCore/Makefile b/cpp/llvm/lib/Target/XCore/Makefile deleted file mode 100644 index b823c4ed..00000000 --- a/cpp/llvm/lib/Target/XCore/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- lib/Target/XCore/Makefile ---------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMXCoreCodeGen -TARGET = XCore - -# Make sure that tblgen is run, first thing. -BUILT_SOURCES = XCoreGenRegisterInfo.inc XCoreGenInstrInfo.inc \ - XCoreGenAsmWriter.inc \ - XCoreGenDAGISel.inc XCoreGenCallingConv.inc \ - XCoreGenSubtargetInfo.inc - -DIRS = TargetInfo MCTargetDesc - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Target/XCore/TargetInfo/Makefile b/cpp/llvm/lib/Target/XCore/TargetInfo/Makefile deleted file mode 100644 index f8a40951..00000000 --- a/cpp/llvm/lib/Target/XCore/TargetInfo/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Target/XCore/TargetInfo/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../../.. -LIBRARYNAME = LLVMXCoreInfo - -# Hack: we need to include 'main' target directory to grab private headers -CPPFLAGS = -I$(PROJ_OBJ_DIR)/.. -I$(PROJ_SRC_DIR)/.. - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Transforms/Hello/Makefile b/cpp/llvm/lib/Transforms/Hello/Makefile deleted file mode 100644 index f1e31489..00000000 --- a/cpp/llvm/lib/Transforms/Hello/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- lib/Transforms/Hello/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMHello -LOADABLE_MODULE = 1 -USEDLIBS = - -# If we don't need RTTI or EH, there's no reason to export anything -# from the hello plugin. -ifneq ($(REQUIRES_RTTI), 1) -ifneq ($(REQUIRES_EH), 1) -EXPORTED_SYMBOL_FILE = $(PROJ_SRC_DIR)/Hello.exports -endif -endif - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/IPO/Makefile b/cpp/llvm/lib/Transforms/IPO/Makefile deleted file mode 100644 index 5c423741..00000000 --- a/cpp/llvm/lib/Transforms/IPO/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/IPO/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMipo -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/InstCombine/Makefile b/cpp/llvm/lib/Transforms/InstCombine/Makefile deleted file mode 100644 index 0c488e78..00000000 --- a/cpp/llvm/lib/Transforms/InstCombine/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/InstCombine/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMInstCombine -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/Instrumentation/Makefile b/cpp/llvm/lib/Transforms/Instrumentation/Makefile deleted file mode 100644 index 6cbc7a9c..00000000 --- a/cpp/llvm/lib/Transforms/Instrumentation/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/Instrumentation/Makefile -------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMInstrumentation -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/Makefile b/cpp/llvm/lib/Transforms/Makefile deleted file mode 100644 index 8b1df92f..00000000 --- a/cpp/llvm/lib/Transforms/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -##===- lib/Transforms/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -PARALLEL_DIRS = Utils Instrumentation Scalar InstCombine IPO Vectorize Hello - -include $(LEVEL)/Makefile.config - -# No support for plugins on windows targets -ifeq ($(HOST_OS), $(filter $(HOST_OS), Cygwin MingW Minix)) - PARALLEL_DIRS := $(filter-out Hello, $(PARALLEL_DIRS)) -endif - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/lib/Transforms/Scalar/Makefile b/cpp/llvm/lib/Transforms/Scalar/Makefile deleted file mode 100644 index cc42fd00..00000000 --- a/cpp/llvm/lib/Transforms/Scalar/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/Scalar/Makefile ----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMScalarOpts -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/Utils/Makefile b/cpp/llvm/lib/Transforms/Utils/Makefile deleted file mode 100644 index d1e9336d..00000000 --- a/cpp/llvm/lib/Transforms/Utils/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/Utils/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMTransformUtils -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/Transforms/Vectorize/Makefile b/cpp/llvm/lib/Transforms/Vectorize/Makefile deleted file mode 100644 index 86c36585..00000000 --- a/cpp/llvm/lib/Transforms/Vectorize/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- lib/Transforms/Vectorize/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../../.. -LIBRARYNAME = LLVMVectorize -BUILD_ARCHIVE = 1 - -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/lib/VMCore/Makefile b/cpp/llvm/lib/VMCore/Makefile deleted file mode 100644 index 2b9b0f25..00000000 --- a/cpp/llvm/lib/VMCore/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -##===- lib/VMCore/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -LEVEL = ../.. -LIBRARYNAME = LLVMCore -BUILD_ARCHIVE = 1 -REQUIRES_RTTI = 1 - -BUILT_SOURCES = $(PROJ_OBJ_ROOT)/include/llvm/Intrinsics.gen - -include $(LEVEL)/Makefile.common - -GENFILE:=$(PROJ_OBJ_ROOT)/include/llvm/Intrinsics.gen - -INTRINSICTD := $(PROJ_SRC_ROOT)/include/llvm/Intrinsics.td -INTRINSICTDS := $(wildcard $(PROJ_SRC_ROOT)/include/llvm/Intrinsics*.td) - -$(ObjDir)/Intrinsics.gen.tmp: $(ObjDir)/.dir $(INTRINSICTDS) $(LLVM_TBLGEN) - $(Echo) Building Intrinsics.gen.tmp from Intrinsics.td - $(Verb) $(LLVMTableGen) $(call SYSPATH, $(INTRINSICTD)) -o $(call SYSPATH, $@) -gen-intrinsic - -$(GENFILE): $(ObjDir)/Intrinsics.gen.tmp - $(Verb) $(CMP) -s $@ $< || ( $(CP) $< $@ && \ - $(EchoCmd) Updated Intrinsics.gen because Intrinsics.gen.tmp \ - changed significantly. ) - -install-local:: $(GENFILE) - $(Echo) Installing $(DESTDIR)$(PROJ_includedir)/llvm/Intrinsics.gen - $(Verb) $(DataInstall) $(GENFILE) $(DESTDIR)$(PROJ_includedir)/llvm/Intrinsics.gen diff --git a/cpp/llvm/projects/sample/Makefile b/cpp/llvm/projects/sample/Makefile deleted file mode 100644 index f96f1aba..00000000 --- a/cpp/llvm/projects/sample/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- projects/sample/Makefile ----------------------------*- Makefile -*-===## -# -# This is a sample Makefile for a project that uses LLVM. -# -##===----------------------------------------------------------------------===## - -# -# Indicates our relative path to the top of the project's root directory. -# -LEVEL = . -DIRS = lib tools -EXTRA_DIST = include - -# -# Include the Master Makefile that knows how to build all. -# -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/projects/sample/lib/Makefile b/cpp/llvm/projects/sample/lib/Makefile deleted file mode 100644 index 959038b7..00000000 --- a/cpp/llvm/projects/sample/lib/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- projects/sample/lib/Makefile ------------------------*- Makefile -*-===## - -# -# Relative path to the top of the source tree. -# -LEVEL=.. - -# -# List all of the subdirectories that we will compile. -# -DIRS=sample - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/projects/sample/lib/sample/Makefile b/cpp/llvm/projects/sample/lib/sample/Makefile deleted file mode 100644 index af63399d..00000000 --- a/cpp/llvm/projects/sample/lib/sample/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- projects/sample/lib/sample/Makefile -----------------*- Makefile -*-===## - -# -# Indicate where we are relative to the top of the source tree. -# -LEVEL=../.. - -# -# Give the name of a library. This will build a dynamic version. -# -LIBRARYNAME=sample - -# -# Include Makefile.common so we know what to do. -# -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/projects/sample/tools/Makefile b/cpp/llvm/projects/sample/tools/Makefile deleted file mode 100644 index 00ff52b4..00000000 --- a/cpp/llvm/projects/sample/tools/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- projects/sample/tools/Makefile ----------------------*- Makefile -*-===## - -# -# Relative path to the top of the source tree. -# -LEVEL=.. - -# -# List all of the subdirectories that we will compile. -# -DIRS=sample - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/projects/sample/tools/sample/Makefile b/cpp/llvm/projects/sample/tools/sample/Makefile deleted file mode 100644 index 324030c5..00000000 --- a/cpp/llvm/projects/sample/tools/sample/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- projects/sample/tools/sample/Makefile ---------------*- Makefile -*-===## - -# -# Indicate where we are relative to the top of the source tree. -# -LEVEL=../.. - -# -# Give the name of the tool. -# -TOOLNAME=Sample - -# -# List libraries that we'll need -# We use LIBS because sample is a dynamic library. -# -USEDLIBS = sample.a - -# -# Include Makefile.common so we know what to do. -# -include $(LEVEL)/Makefile.common - diff --git a/cpp/llvm/runtime/Makefile b/cpp/llvm/runtime/Makefile deleted file mode 100644 index d0e85d58..00000000 --- a/cpp/llvm/runtime/Makefile +++ /dev/null @@ -1,31 +0,0 @@ -##===- runtime/Makefile ------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = .. -include $(LEVEL)/Makefile.config - -ifndef NO_RUNTIME_LIBS - -PARALLEL_DIRS := libprofile - -# Disable libprofile: a faulty libtool is generated by autoconf which breaks the -# build on Sparc -ifeq ($(ARCH), Sparc) -PARALLEL_DIRS := $(filter-out libprofile, $(PARALLEL_DIRS)) -endif - -ifeq ($(TARGET_OS), $(filter $(TARGET_OS), Cygwin MingW Minix)) -PARALLEL_DIRS := $(filter-out libprofile, $(PARALLEL_DIRS)) -endif - -endif - -include $(LEVEL)/Makefile.common - -install:: diff --git a/cpp/llvm/runtime/libprofile/Makefile b/cpp/llvm/runtime/libprofile/Makefile deleted file mode 100644 index d8511495..00000000 --- a/cpp/llvm/runtime/libprofile/Makefile +++ /dev/null @@ -1,51 +0,0 @@ -##===- runtime/libprofile/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL = ../.. -include $(LEVEL)/Makefile.config - -ifneq ($(strip $(LLVMCC)),) -BYTECODE_LIBRARY = 1 -endif -LIBRARYNAME = profile_rt -LINK_LIBS_IN_SHARED = 1 -SHARED_LIBRARY = 1 -EXTRA_DIST = libprofile.exports -EXPORTED_SYMBOL_FILE = $(PROJ_SRC_DIR)/libprofile.exports - -# Build and install this archive. -BUILD_ARCHIVE = 1 -override NO_INSTALL_ARCHIVES = - -include $(LEVEL)/Makefile.common - -ifeq ($(HOST_OS),Darwin) - # Special hack to allow libprofile_rt to have an offset version number. - PROFILE_RT_LIBRARY_VERSION := $(LLVM_SUBMIT_VERSION) - - # Set dylib internal version number to llvmCore submission number. - ifdef LLVM_SUBMIT_VERSION - LLVMLibsOptions := $(LLVMLibsOptions) -Wl,-current_version \ - -Wl,$(PROFILE_RT_LIBRARY_VERSION).$(LLVM_SUBMIT_SUBVERSION) \ - -Wl,-compatibility_version -Wl,1 - endif - # Extra options to override libtool defaults. - LLVMLibsOptions := $(LLVMLibsOptions) \ - -Wl,-dead_strip \ - -Wl,-seg1addr -Wl,0xE0000000 - - # Mac OS X 10.4 and earlier tools do not allow a second -install_name on - # command line. - DARWIN_VERS := $(shell echo $(TARGET_TRIPLE) | sed 's/.*darwin\([0-9]*\).*/\1/') - ifneq ($(DARWIN_VERS),8) - LLVMLibsOptions := $(LLVMLibsOptions) \ - -Wl,-install_name \ - -Wl,"@executable_path/../lib/lib$(LIBRARYNAME)$(SHLIBEXT)" - endif -endif diff --git a/cpp/llvm/test/Archive/GNU.a b/cpp/llvm/test/Archive/GNU.a deleted file mode 100644 index 4c09881eb39dc513184462952d414396b3f4a0c0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4210 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 F{{`)U>mUFC diff --git a/cpp/llvm/test/Archive/xpg4.a b/cpp/llvm/test/Archive/xpg4.a deleted file mode 100644 index b2bdb51188fecf14fcabd08515a2251b30ca3951..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4214 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 D&r$0x diff --git a/cpp/llvm/test/CodeGen/Generic/Makefile b/cpp/llvm/test/CodeGen/Generic/Makefile deleted file mode 100644 index 26ebc316..00000000 --- a/cpp/llvm/test/CodeGen/Generic/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -# Makefile for running ad-hoc custom LLVM tests -# -%.bc: %.ll - llvm-as $< - -%.llc.s: %.bc - llc $< -o $@ - -%.gcc.s: %.c - gcc -O0 -S $< -o $@ - -%.nat: %.s - gcc -O0 -lm $< -o $@ - -%.cbe.out: %.cbe.nat - ./$< > $@ - -%.out: %.nat - ./$< > $@ - -%.clean: - rm -f $(patsubst %.clean,%.bc,$@) $(patsubst %.clean,%.*.s,$@) \ - $(patsubst %.clean,%.*.nat,$@) $(patsubst %.clean,%.*.out,$@) diff --git a/cpp/llvm/test/Makefile b/cpp/llvm/test/Makefile deleted file mode 100644 index a4e53f8d..00000000 --- a/cpp/llvm/test/Makefile +++ /dev/null @@ -1,188 +0,0 @@ -#===- test/Makefile ----------------------------------------*- Makefile -*--===# -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -#===------------------------------------------------------------------------===# - -LEVEL = .. -DIRS = - -all:: check-local - -# 'lit' is the default test runner. -check-local:: check-local-lit - -# Include other test rules -include Makefile.tests - -#===------------------------------------------------------------------------===# -# DejaGNU testing support -#===------------------------------------------------------------------------===# - -ifneq ($(GREP_OPTIONS),) -$(warning GREP_OPTIONS environment variable may interfere with test results) -endif - -ifdef VERBOSE -RUNTESTFLAGS := $(VERBOSE) -LIT_ARGS := -v -else -LIT_ARGS := -s -v -endif - -# -jN causes crash on Cygwin's python. -ifneq (,$(filter $(HOST_OS),Cygwin)) - LIT_ARGS += -j1 -endif - -ifdef TESTSUITE -LIT_TESTSUITE := $(TESTSUITE) -CLEANED_TESTSUITE := $(patsubst %/,%,$(TESTSUITE)) -CLEANED_TESTSUITE := $(patsubst test/%,%,$(CLEANED_TESTSUITE)) -RUNTESTFLAGS += --tool $(CLEANED_TESTSUITE) -else -LIT_TESTSUITE := . -endif - -ifdef VG -VALGRIND := valgrind --tool=memcheck --quiet --trace-children=yes --error-exitcode=3 --leak-check=full $(VALGRIND_EXTRA_ARGS) -endif - -# Check what to run for -all. -LIT_ALL_TESTSUITES := $(LIT_TESTSUITE) - -extra-lit-site-cfgs:: -.PHONY: extra-lit-site-cfgs - -ifneq ($(strip $(filter check-local-all,$(MAKECMDGOALS))),) -ifndef TESTSUITE -ifeq ($(shell test -f $(PROJ_OBJ_DIR)/../tools/clang/Makefile && echo OK), OK) -LIT_ALL_TESTSUITES += $(PROJ_OBJ_DIR)/../tools/clang/test - -# Force creation of Clang's lit.site.cfg. -clang-lit-site-cfg: FORCE - $(MAKE) -C $(PROJ_OBJ_DIR)/../tools/clang/test lit.site.cfg Unit/lit.site.cfg -extra-lit-site-cfgs:: clang-lit-site-cfg -endif -endif -endif - -IGNORE_TESTS := - -ifndef RUNLLVM2CPP -IGNORE_TESTS += llvm2cpp.exp -endif - -ifdef IGNORE_TESTS -RUNTESTFLAGS += --ignore "$(strip $(IGNORE_TESTS))" -endif - -# ulimits like these are redundantly enforced by the buildbots, so -# just removing them here won't work. -# Both AuroraUX & Solaris do not have the -m flag for ulimit -ifeq ($(HOST_OS),SunOS) -ULIMIT=ulimit -t 600 ; ulimit -d 512000 ; ulimit -v 512000 ; -else # !SunOS -ifeq ($(HOST_OS),AuroraUX) -ULIMIT=ulimit -t 600 ; ulimit -d 512000 ; ulimit -v 512000 ; -else # !AuroraUX -# Fedora 13 x86-64 python fails with -v 76800 -ULIMIT=ulimit -t 600 ; ulimit -d 512000 ; ulimit -m 512000 ; ulimit -v 1024000 ; -endif # AuroraUX -endif # SunOS - -ifneq ($(RUNTEST),) -check-local-dg:: site.exp - ( $(ULIMIT) \ - PATH="$(LLVMToolDir):$(LLVM_SRC_ROOT)/test/Scripts:$(LLVMGCCDIR)/bin:$(PATH)" \ - $(RUNTEST) $(RUNTESTFLAGS) ) -else -check-local-dg:: site.exp - @echo "*** dejagnu not found. Make sure 'runtest' is in your PATH, then reconfigure LLVM." -endif - -check-local-lit:: lit.site.cfg Unit/lit.site.cfg - ( $(ULIMIT) \ - $(LLVM_SRC_ROOT)/utils/lit/lit.py $(LIT_ARGS) $(LIT_TESTSUITE) ) - -check-local-all:: lit.site.cfg Unit/lit.site.cfg extra-lit-site-cfgs - ( $(ULIMIT) \ - $(LLVM_SRC_ROOT)/utils/lit/lit.py $(LIT_ARGS) $(LIT_ALL_TESTSUITES) ) - -clean:: - $(RM) -rf `find $(LLVM_OBJ_ROOT)/test -name Output -type d -print` - -# dsymutil is used on the Darwin to manipulate DWARF debugging information. -ifeq ($(TARGET_OS),Darwin) -DSYMUTIL=dsymutil -else -DSYMUTIL=true -endif - -ifneq ($(OCAMLOPT),) -CC_FOR_OCAMLOPT := $(shell $(OCAMLOPT) -config | grep native_c_compiler | sed -e 's/native_c_compiler: //') -CXX_FOR_OCAMLOPT := $(subst gcc,g++,$(CC_FOR_OCAMLOPT)) -endif - -FORCE: - -site.exp: FORCE - @echo 'Making a new site.exp file...' - @echo '## Autogenerated by LLVM configuration.' > site.tmp - @echo '# Do not edit!' >> site.tmp - @echo 'set target_triplet "$(TARGET_TRIPLE)"' >> site.tmp - @echo 'set TARGETS_TO_BUILD "$(TARGETS_TO_BUILD)"' >> site.tmp - @echo 'set llvmshlibdir "$(SharedLibDir)"' >>site.tmp - @echo 'set llvm_bindings "$(BINDINGS_TO_BUILD)"' >> site.tmp - @echo 'set srcroot "$(LLVM_SRC_ROOT)"' >>site.tmp - @echo 'set objroot "$(LLVM_OBJ_ROOT)"' >>site.tmp - @echo 'set srcdir "$(LLVM_SRC_ROOT)/test"' >>site.tmp - @echo 'set objdir "$(LLVM_OBJ_ROOT)/test"' >>site.tmp - @echo 'set link "' $(CXX) $(CPP.Flags) $(CXX.Flags) $(TargetCommonOpts) $(CompileCommonOpts) $(LD.Flags) '"' >>site.tmp - @echo 'set shlibext "$(SHLIBEXT)"' >> site.tmp - @echo 'set ocamlopt "$(OCAMLOPT) -cc \"$(CXX_FOR_OCAMLOPT)\" -I $(LibDir)/ocaml"' >> site.tmp - @echo 'set valgrind "$(VALGRIND)"' >> site.tmp - @echo 'set grep "$(GREP)"' >>site.tmp - @echo 'set gas "$(GAS)"' >>site.tmp - @echo '## All variables above are generated by configure. Do Not Edit ## ' >>site.tmp - @test ! -f site.exp || \ - sed '1,/^## All variables above are.*##/ d' site.exp >> site.tmp - @-rm -f site.bak - @test ! -f site.exp || mv site.exp site.bak - @mv site.tmp site.exp - -ifeq ($(DISABLE_ASSERTIONS),1) -ENABLE_ASSERTIONS=0 -else -ENABLE_ASSERTIONS=1 -endif - -lit.site.cfg: site.exp - @echo "Making LLVM 'lit.site.cfg' file..." - @$(ECHOPATH) s=@LLVM_SOURCE_DIR@=$(LLVM_SRC_ROOT)=g > lit.tmp - @$(ECHOPATH) s=@LLVM_BINARY_DIR@=$(LLVM_OBJ_ROOT)=g >> lit.tmp - @$(ECHOPATH) s=@LLVM_TOOLS_DIR@=$(ToolDir)=g >> lit.tmp - @$(ECHOPATH) s=@LLVMGCCDIR@=$(LLVMGCCDIR)=g >> lit.tmp - @$(ECHOPATH) s=@PYTHON_EXECUTABLE@=python=g >> lit.tmp - @$(ECHOPATH) s=@ENABLE_SHARED@=$(ENABLE_SHARED)=g >> lit.tmp - @$(ECHOPATH) s=@ENABLE_ASSERTIONS@=$(ENABLE_ASSERTIONS)=g >> lit.tmp - @$(ECHOPATH) s=@TARGETS_TO_BUILD@=$(TARGETS_TO_BUILD)=g >> lit.tmp - @$(ECHOPATH) s=@LLVM_BINDINGS@=$(BINDINGS_TO_BUILD)=g >> lit.tmp - @sed -f lit.tmp $(PROJ_SRC_DIR)/lit.site.cfg.in > $@ - @-rm -f lit.tmp - -Unit/lit.site.cfg: $(PROJ_OBJ_DIR)/Unit/.dir FORCE - @echo "Making LLVM unittest 'lit.site.cfg' file..." - @$(ECHOPATH) s=@LLVM_SOURCE_DIR@=$(LLVM_SRC_ROOT)=g > unit.tmp - @$(ECHOPATH) s=@LLVM_BINARY_DIR@=$(LLVM_OBJ_ROOT)=g >> unit.tmp - @$(ECHOPATH) s=@LLVM_TOOLS_DIR@=$(ToolDir)=g >> unit.tmp - @$(ECHOPATH) s=@LLVMGCCDIR@=$(LLVMGCCDIR)=g >> unit.tmp - @$(ECHOPATH) s=@LLVM_BUILD_MODE@=$(BuildMode)=g >> unit.tmp - @$(ECHOPATH) s=@ENABLE_SHARED@=$(ENABLE_SHARED)=g >> unit.tmp - @$(ECHOPATH) s=@SHLIBDIR@=$(SharedLibDir)=g >> unit.tmp - @$(ECHOPATH) s=@SHLIBPATH_VAR@=$(SHLIBPATH_VAR)=g >> unit.tmp - @sed -f unit.tmp $(PROJ_SRC_DIR)/Unit/lit.site.cfg.in > $@ - @-rm -f unit.tmp diff --git a/cpp/llvm/tools/Makefile b/cpp/llvm/tools/Makefile deleted file mode 100644 index 8bf091a7..00000000 --- a/cpp/llvm/tools/Makefile +++ /dev/null @@ -1,74 +0,0 @@ -##===- tools/Makefile --------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := .. - -include $(LEVEL)/Makefile.config - -# Build clang if present. - -ifneq ($(CLANG_SRC_ROOT),) - OPTIONAL_PARALLEL_DIRS := $(CLANG_SRC_ROOT) -else - OPTIONAL_PARALLEL_DIRS := clang -endif - -# Build LLDB if present. Note LLDB must be built last as it depends on the -# wider LLVM infrastructure (including Clang). -OPTIONAL_DIRS := lldb - -# NOTE: The tools are organized into five groups of four consisting of one -# large and three small executables. This is done to minimize memory load -# in parallel builds. Please retain this ordering. -DIRS := llvm-config -PARALLEL_DIRS := opt llvm-as llvm-dis \ - llc llvm-ranlib llvm-ar llvm-nm \ - llvm-ld llvm-prof llvm-link \ - lli llvm-extract llvm-mc \ - bugpoint llvm-bcanalyzer llvm-stub \ - llvm-diff macho-dump llvm-objdump llvm-readobj \ - llvm-rtdyld llvm-dwarfdump llvm-cov \ - llvm-size llvm-stress - -# Let users override the set of tools to build from the command line. -ifdef ONLY_TOOLS - OPTIONAL_PARALLEL_DIRS := - OPTIONAL_DIRS := $(findstring lldb,$(ONLY_TOOLS)) - PARALLEL_DIRS := $(filter-out lldb,$(ONLY_TOOLS)) -endif - -# These libraries build as dynamic libraries (.dylib /.so), they can only be -# built if ENABLE_PIC is set. -ifndef ONLY_TOOLS -ifeq ($(ENABLE_PIC),1) - # gold only builds if binutils is around. It requires "lto" to build before - # it so it is added to DIRS. - ifdef BINUTILS_INCDIR - DIRS += lto gold - else - PARALLEL_DIRS += lto - endif - - PARALLEL_DIRS += bugpoint-passes -endif - -ifdef LLVM_HAS_POLLY - PARALLEL_DIRS += polly -endif -endif - -# On Win32, loadable modules can be built with ENABLE_SHARED. -ifneq ($(ENABLE_SHARED),1) - ifneq (,$(filter $(HOST_OS), Cygwin MingW)) - PARALLEL_DIRS := $(filter-out bugpoint-passes, \ - $(PARALLEL_DIRS)) - endif -endif - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/tools/bugpoint-passes/Makefile b/cpp/llvm/tools/bugpoint-passes/Makefile deleted file mode 100644 index 61f96bc3..00000000 --- a/cpp/llvm/tools/bugpoint-passes/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -##===- tools/bugpoint-passes/Makefile -- -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../.. -LIBRARYNAME := BugpointPasses -LOADABLE_MODULE := 1 -USEDLIBS := - -# If we don't need RTTI or EH, there's no reason to export anything -# from this plugin. -ifneq ($(REQUIRES_RTTI), 1) -ifneq ($(REQUIRES_EH), 1) -EXPORTED_SYMBOL_FILE = $(PROJ_SRC_DIR)/bugpoint.exports -endif -endif - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/tools/bugpoint/Makefile b/cpp/llvm/tools/bugpoint/Makefile deleted file mode 100644 index 34f4bddb..00000000 --- a/cpp/llvm/tools/bugpoint/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -##===- tools/bugpoint/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -LEVEL := ../.. -TOOLNAME := bugpoint -LINK_COMPONENTS := asmparser instrumentation scalaropts ipo linker bitreader \ - bitwriter vectorize - -include $(LEVEL)/Makefile.common diff --git a/cpp/llvm/tools/clang/Makefile b/cpp/llvm/tools/clang/Makefile deleted file mode 100644 index bf1a7721..00000000 --- a/cpp/llvm/tools/clang/Makefile +++ /dev/null @@ -1,111 +0,0 @@ -##===- Makefile --------------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -# If CLANG_LEVEL is not set, then we are the top-level Makefile. Otherwise, we -# are being included from a subdirectory makefile. - -ifndef CLANG_LEVEL - -IS_TOP_LEVEL := 1 -CLANG_LEVEL := . -DIRS := utils/TableGen include lib tools runtime docs unittests - -PARALLEL_DIRS := - -ifeq ($(BUILD_EXAMPLES),1) - PARALLEL_DIRS += examples -endif -endif - -ifeq ($(MAKECMDGOALS),libs-only) - DIRS := $(filter-out tools docs, $(DIRS)) - OPTIONAL_DIRS := -endif - -### -# Common Makefile code, shared by all Clang Makefiles. - -# Set LLVM source root level. -LEVEL := $(CLANG_LEVEL)/../.. - -# Include LLVM common makefile. -include $(LEVEL)/Makefile.common - -ifneq ($(ENABLE_DOCS),1) - DIRS := $(filter-out docs, $(DIRS)) -endif - -# Set common Clang build flags. -CPP.Flags += -I$(PROJ_SRC_DIR)/$(CLANG_LEVEL)/include -I$(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include -ifdef CLANG_VENDOR -CPP.Flags += -DCLANG_VENDOR='"$(CLANG_VENDOR) "' -endif -ifdef CLANG_REPOSITORY_STRING -CPP.Flags += -DCLANG_REPOSITORY_STRING='"$(CLANG_REPOSITORY_STRING)"' -endif - -# Disable -fstrict-aliasing. Darwin disables it by default (and LLVM doesn't -# work with it enabled with GCC), Clang/llvm-gcc don't support it yet, and newer -# GCC's have false positive warnings with it on Linux (which prove a pain to -# fix). For example: -# http://gcc.gnu.org/PR41874 -# http://gcc.gnu.org/PR41838 -# -# We can revisit this when LLVM/Clang support it. -CXX.Flags += -fno-strict-aliasing - -# Set up Clang's tblgen. -ifndef CLANG_TBLGEN - ifeq ($(LLVM_CROSS_COMPILING),1) - CLANG_TBLGEN := $(BuildLLVMToolDir)/clang-tblgen$(BUILD_EXEEXT) - else - CLANG_TBLGEN := $(LLVMToolDir)/clang-tblgen$(EXEEXT) - endif -endif -ClangTableGen = $(CLANG_TBLGEN) $(TableGen.Flags) - -### -# Clang Top Level specific stuff. - -ifeq ($(IS_TOP_LEVEL),1) - -ifneq ($(PROJ_SRC_ROOT),$(PROJ_OBJ_ROOT)) -$(RecursiveTargets):: - $(Verb) for dir in test unittests; do \ - if [ -f $(PROJ_SRC_DIR)/$${dir}/Makefile ] && [ ! -f $${dir}/Makefile ]; then \ - $(MKDIR) $${dir}; \ - $(CP) $(PROJ_SRC_DIR)/$${dir}/Makefile $${dir}/Makefile; \ - fi \ - done -endif - -test:: - @ $(MAKE) -C test - -report:: - @ $(MAKE) -C test report - -clean:: - @ $(MAKE) -C test clean - -libs-only: all - -tags:: - $(Verb) etags `find . -type f -name '*.h' -or -name '*.cpp' | \ - grep -v /lib/Headers | grep -v /test/` - -cscope.files: - find tools lib include -name '*.cpp' \ - -or -name '*.def' \ - -or -name '*.td' \ - -or -name '*.h' > cscope.files - -.PHONY: test report clean cscope.files - -endif diff --git a/cpp/llvm/tools/clang/docs/Makefile b/cpp/llvm/tools/clang/docs/Makefile deleted file mode 100644 index 2608046f..00000000 --- a/cpp/llvm/tools/clang/docs/Makefile +++ /dev/null @@ -1,97 +0,0 @@ -##===- docs/Makefile ---------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := .. -DIRS := tools - -ifdef BUILD_FOR_WEBSITE -PROJ_OBJ_DIR = . -DOXYGEN = doxygen - -$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in - cat $< | sed \ - -e 's/@abs_srcdir@/./g' \ - -e 's/@DOT@/dot/g' \ - -e 's/@PACKAGE_VERSION@/mainline/' \ - -e 's/@abs_builddir@/./g' > $@ -endif - -include $(CLANG_LEVEL)/Makefile - -HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \ - $(wildcard $(PROJ_SRC_DIR)/*.css) -#IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*) -DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \ - doxygen.intro -EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img - -.PHONY: install-html install-doxygen doxygen generated - -install_targets := -ifndef ONLY_MAN_DOCS -install_targets += install-html -endif -ifeq ($(ENABLE_DOXYGEN),1) -install_targets += install-doxygen -endif -install-local:: $(install_targets) - -# Live documentation is generated for the web site using this target: -# 'make generated BUILD_FOR_WEBSITE=1' -generated:: doxygen - -install-html: $(PROJ_OBJ_DIR)/html.tar.gz - $(Echo) Installing HTML documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html -# $(Verb) $(DataInstall) $(IMAGES) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir) - -$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) - $(Echo) Packaging HTML documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar - $(Verb) cd $(PROJ_SRC_DIR) && \ - $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html - $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar - -install-doxygen: doxygen - $(Echo) Installing doxygen documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir) - $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \ - $(FIND) . -type f -exec \ - $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \; - -doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz - -regendoc: - $(Echo) Building doxygen documentation - $(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \ - $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \ - fi - $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg - -$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg - $(Echo) Packaging doxygen documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen - $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/ - -userloc: $(LLVM_SRC_ROOT)/docs/userloc.html - -$(LLVM_SRC_ROOT)/docs/userloc.html: - $(Echo) Making User LOC Table - $(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \ - -html lib include tools runtime utils examples autoconf test > docs/userloc.html - -uninstall-local:: - $(Echo) Uninstalling Documentation - $(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir) diff --git a/cpp/llvm/tools/clang/docs/tools/Makefile b/cpp/llvm/tools/clang/docs/tools/Makefile deleted file mode 100644 index 5521d6b7..00000000 --- a/cpp/llvm/tools/clang/docs/tools/Makefile +++ /dev/null @@ -1,116 +0,0 @@ -##===- docs/tools/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 - -# FIXME: This was copied from the CommandGuide makefile. Figure out -# how to get this stuff on the 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/ -CLANG_VERSION := trunk - -# 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. -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/Makefile - -CLANG_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ - $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) - -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)) - -ifdef ONLY_MAN_DOCS -INSTALL_TARGETS := install-man -else -INSTALL_TARGETS := install-html install-man install-ps -endif - -.SUFFIXES: -.SUFFIXES: .html .pod .1 .ps - -$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir - pod2html --css=manpage.css --htmlroot=. \ - --podpath=. --infile=$< --outfile=$@ --title=$* - -$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release "clang $(CLANG_VERSION)" --center="Clang Tools Documentation" $< $@ - -$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir - groff -Tps -man $< > $@ - - -html: $(HTML) -man: $(MAN) -ps: $(PS) - -EXTRA_DIST := $(POD) - -clean-local:: - $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/clang -MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1 -PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps - -install-html:: $(HTML) - $(Echo) Installing HTML Clang Tools Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) - -install-man:: $(MAN) - $(Echo) Installing MAN Clang Tools Documentation - $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) - -install-ps:: $(PS) - $(Echo) Installing PS Clang Tools Documentation - $(Verb) $(MKDIR) $(PS_DIR) - $(Verb) $(DataInstall) $(PS) $(PS_DIR) - -install-local:: $(INSTALL_TARGETS) - -uninstall-local:: - $(Echo) Uninstalling Clang Tools Documentation - $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR) - -printvars:: - $(Echo) "POD : " '$(POD)' - $(Echo) "HTML : " '$(HTML)' diff --git a/cpp/llvm/tools/clang/examples/Makefile b/cpp/llvm/tools/clang/examples/Makefile deleted file mode 100644 index d8d90287..00000000 --- a/cpp/llvm/tools/clang/examples/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- examples/Makefile -----------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := .. - -PARALLEL_DIRS := analyzer-plugin clang-interpreter PrintFunctionNames - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/examples/PrintFunctionNames/Makefile b/cpp/llvm/tools/clang/examples/PrintFunctionNames/Makefile deleted file mode 100644 index 23a53054..00000000 --- a/cpp/llvm/tools/clang/examples/PrintFunctionNames/Makefile +++ /dev/null @@ -1,28 +0,0 @@ -##===- examples/PrintFunctionNames/Makefile ----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME = PrintFunctionNames - -# If we don't need RTTI or EH, there's no reason to export anything -# from the plugin. -ifneq ($(REQUIRES_RTTI), 1) -ifneq ($(REQUIRES_EH), 1) -EXPORTED_SYMBOL_FILE = $(PROJ_SRC_DIR)/PrintFunctionNames.exports -endif -endif - -LINK_LIBS_IN_SHARED = 0 -SHARED_LIBRARY = 1 - -include $(CLANG_LEVEL)/Makefile - -ifeq ($(OS),Darwin) - LDFLAGS=-Wl,-undefined,dynamic_lookup -endif diff --git a/cpp/llvm/tools/clang/examples/analyzer-plugin/Makefile b/cpp/llvm/tools/clang/examples/analyzer-plugin/Makefile deleted file mode 100644 index 8b83bef9..00000000 --- a/cpp/llvm/tools/clang/examples/analyzer-plugin/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -##===- examples/analyzer-plugin/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME = SampleAnalyzerPlugin - -LINK_LIBS_IN_SHARED = 0 -LOADABLE_MODULE = 1 - -include $(CLANG_LEVEL)/Makefile - -ifeq ($(OS),Darwin) - LDFLAGS=-Wl,-undefined,dynamic_lookup -endif diff --git a/cpp/llvm/tools/clang/examples/clang-interpreter/Makefile b/cpp/llvm/tools/clang/examples/clang-interpreter/Makefile deleted file mode 100644 index 420a066c..00000000 --- a/cpp/llvm/tools/clang/examples/clang-interpreter/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -##===- examples/clang-interpreter/Makefile -----------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. - -TOOLNAME = clang-interpreter -NO_INSTALL = 1 - -# No plugins, optimize startup time. -TOOL_NO_EXPORTS = 1 - -LINK_COMPONENTS := jit interpreter nativecodegen bitreader bitwriter ipo \ - linker selectiondag asmparser instrumentation -USEDLIBS = clangFrontend.a clangSerialization.a clangDriver.a clangCodeGen.a \ - clangParse.a clangSema.a clangStaticAnalyzerFrontend.a \ - clangStaticAnalyzerCheckers.a clangStaticAnalyzerCore.a \ - clangAnalysis.a clangRewrite.a \ - clangEdit.a clangAST.a clangLex.a clangBasic.a - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/include/Makefile b/cpp/llvm/tools/clang/include/Makefile deleted file mode 100644 index 79b9adfb..00000000 --- a/cpp/llvm/tools/clang/include/Makefile +++ /dev/null @@ -1,4 +0,0 @@ -CLANG_LEVEL := .. -DIRS := clang clang-c - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/include/clang-c/Makefile b/cpp/llvm/tools/clang/include/clang-c/Makefile deleted file mode 100644 index b29e29ea..00000000 --- a/cpp/llvm/tools/clang/include/clang-c/Makefile +++ /dev/null @@ -1,38 +0,0 @@ -CLANG_LEVEL := ../.. -DIRS := - -include $(CLANG_LEVEL)/Makefile - -IntIncludeDir = $(DESTDIR)$(PROJ_internal_prefix)/include - -install-local:: - $(Echo) Installing Clang C API include files - $(Verb) $(MKDIR) $(IntIncludeDir) - $(Verb) if test -d "$(PROJ_SRC_DIR)" ; then \ - cd $(PROJ_SRC_DIR)/.. && \ - for hdr in `find clang-c -type f '!' '(' -name '*~' \ - -o -name '.#*' -o -name '*.in' -o -name '*.txt' \ - -o -name 'Makefile' -o -name '*.td' ')' -print \ - | grep -v CVS | grep -v .svn | grep -v .dir` ; do \ - instdir=`dirname "$(IntIncludeDir)/$$hdr"` ; \ - if test \! -d "$$instdir" ; then \ - $(EchoCmd) Making install directory $$instdir ; \ - $(MKDIR) $$instdir ;\ - fi ; \ - $(DataInstall) $$hdr $(IntIncludeDir)/$$hdr ; \ - done ; \ - fi -ifneq ($(PROJ_SRC_ROOT),$(PROJ_OBJ_ROOT)) - $(Verb) if test -d "$(PROJ_OBJ_ROOT)/tools/clang/include/clang-c" ; then \ - cd $(PROJ_OBJ_ROOT)/tools/clang/include && \ - for hdr in `find clang-c -type f '!' '(' -name 'Makefile' ')' -print \ - | grep -v CVS | grep -v .tmp | grep -v .dir` ; do \ - instdir=`dirname "$(IntIncludeDir)/$$hdr"` ; \ - if test \! -d "$$instdir" ; then \ - $(EchoCmd) Making install directory $$instdir ; \ - $(MKDIR) $$instdir ;\ - fi ; \ - $(DataInstall) $$hdr $(IntIncludeDir)/$$hdr ; \ - done ; \ - fi -endif diff --git a/cpp/llvm/tools/clang/include/clang/AST/Makefile b/cpp/llvm/tools/clang/include/clang/AST/Makefile deleted file mode 100644 index 2854b7f4..00000000 --- a/cpp/llvm/tools/clang/include/clang/AST/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -CLANG_LEVEL := ../../.. -TD_SRC_DIR = $(PROJ_SRC_DIR)/../Basic -BUILT_SOURCES = Attrs.inc AttrImpl.inc StmtNodes.inc DeclNodes.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/Attrs.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang attribute classes with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-classes -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< - -$(ObjDir)/AttrImpl.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang attribute implementations with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-impl -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< - -$(ObjDir)/StmtNodes.inc.tmp : $(TD_SRC_DIR)/StmtNodes.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang statement node tables with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-stmt-nodes -o $(call SYSPATH, $@) $< - -$(ObjDir)/DeclNodes.inc.tmp : $(TD_SRC_DIR)/DeclNodes.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang declaration node tables with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-decl-nodes -o $(call SYSPATH, $@) $< diff --git a/cpp/llvm/tools/clang/include/clang/Basic/Makefile b/cpp/llvm/tools/clang/include/clang/Basic/Makefile deleted file mode 100644 index 702afac1..00000000 --- a/cpp/llvm/tools/clang/include/clang/Basic/Makefile +++ /dev/null @@ -1,61 +0,0 @@ -CLANG_LEVEL := ../../.. -BUILT_SOURCES = \ - DiagnosticAnalysisKinds.inc DiagnosticASTKinds.inc \ - DiagnosticCommonKinds.inc DiagnosticDriverKinds.inc \ - DiagnosticFrontendKinds.inc DiagnosticLexKinds.inc \ - DiagnosticParseKinds.inc DiagnosticSemaKinds.inc \ - DiagnosticSerializationKinds.inc \ - DiagnosticIndexName.inc DiagnosticGroups.inc AttrList.inc arm_neon.inc \ - Version.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -INPUT_TDS = $(wildcard $(PROJ_SRC_DIR)/Diagnostic*.td) - -# Compute the Clang version from the LLVM version, unless specified explicitly. -ifndef CLANG_VERSION -CLANG_VERSION := $(subst svn,,$(LLVMVersion)) -CLANG_VERSION := $(subst rc,,$(CLANG_VERSION)) -endif - -CLANG_VERSION_COMPONENTS := $(subst ., ,$(CLANG_VERSION)) -CLANG_VERSION_MAJOR := $(word 1,$(CLANG_VERSION_COMPONENTS)) -CLANG_VERSION_MINOR := $(word 2,$(CLANG_VERSION_COMPONENTS)) -CLANG_VERSION_PATCHLEVEL := $(word 3,$(CLANG_VERSION_COMPONENTS)) -ifeq ($(CLANG_VERSION_PATCHLEVEL),) -CLANG_HAS_VERSION_PATCHLEVEL := 0 -else -CLANG_HAS_VERSION_PATCHLEVEL := 1 -endif - -$(ObjDir)/Diagnostic%Kinds.inc.tmp : Diagnostic.td $(INPUT_TDS) $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang $(patsubst Diagnostic%Kinds.inc.tmp,%,$(@F)) diagnostic tables with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-diags-defs -clang-component=$(patsubst Diagnostic%Kinds.inc.tmp,%,$(@F)) -o $(call SYSPATH, $@) $< - -$(ObjDir)/DiagnosticIndexName.inc.tmp : Diagnostic.td $(INPUT_TDS) $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang diagnostic name index with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-diags-index-name -o $(call SYSPATH, $@) $< - -$(ObjDir)/DiagnosticGroups.inc.tmp : Diagnostic.td DiagnosticGroups.td $(INPUT_TDS) $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang diagnostic groups with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-diag-groups -o $(call SYSPATH, $@) $< - -$(ObjDir)/AttrList.inc.tmp : Attr.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang attribute list with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-list -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../.. $< - -$(ObjDir)/arm_neon.inc.tmp : arm_neon.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang arm_neon.inc with tblgen" - $(Verb) $(ClangTableGen) -gen-arm-neon-sema -o $(call SYSPATH, $@) $< - -$(ObjDir)/Version.inc.tmp : Version.inc.in Makefile $(LLVM_OBJ_ROOT)/Makefile.config $(ObjDir)/.dir - $(Echo) "Updating Clang version info." - $(Verb)sed -e "s#@CLANG_VERSION@#$(CLANG_VERSION)#g" \ - -e "s#@CLANG_VERSION_MAJOR@#$(CLANG_VERSION_MAJOR)#g" \ - -e "s#@CLANG_VERSION_MINOR@#$(CLANG_VERSION_MINOR)#g" \ - -e "s#@CLANG_VERSION_PATCHLEVEL@#$(CLANG_VERSION_PATCHLEVEL)#g" \ - -e "s#@CLANG_HAS_VERSION_PATCHLEVEL@#$(CLANG_HAS_VERSION_PATCHLEVEL)#g" \ - $< > $@ diff --git a/cpp/llvm/tools/clang/include/clang/Driver/Makefile b/cpp/llvm/tools/clang/include/clang/Driver/Makefile deleted file mode 100644 index 45bc40f3..00000000 --- a/cpp/llvm/tools/clang/include/clang/Driver/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -CLANG_LEVEL := ../../.. -BUILT_SOURCES = Options.inc CC1Options.inc CC1AsOptions.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/Options.inc.tmp : Options.td OptParser.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang Driver Option tables with tblgen" - $(Verb) $(ClangTableGen) -gen-opt-parser-defs -o $(call SYSPATH, $@) $< - -$(ObjDir)/CC1Options.inc.tmp : CC1Options.td OptParser.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang CC1 Option tables with tblgen" - $(Verb) $(ClangTableGen) -gen-opt-parser-defs -o $(call SYSPATH, $@) $< - -$(ObjDir)/CC1AsOptions.inc.tmp : CC1AsOptions.td OptParser.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang CC1 Assembler Option tables with tblgen" - $(Verb) $(ClangTableGen) -gen-opt-parser-defs -o $(call SYSPATH, $@) $< diff --git a/cpp/llvm/tools/clang/include/clang/Lex/Makefile b/cpp/llvm/tools/clang/include/clang/Lex/Makefile deleted file mode 100644 index 762b9a25..00000000 --- a/cpp/llvm/tools/clang/include/clang/Lex/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -CLANG_LEVEL := ../../.. -TD_SRC_DIR = $(PROJ_SRC_DIR)/../Basic -BUILT_SOURCES = AttrSpellings.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/AttrSpellings.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang attribute spellings with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-spelling-list -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< diff --git a/cpp/llvm/tools/clang/include/clang/Makefile b/cpp/llvm/tools/clang/include/clang/Makefile deleted file mode 100644 index 5f2077d2..00000000 --- a/cpp/llvm/tools/clang/include/clang/Makefile +++ /dev/null @@ -1,44 +0,0 @@ -CLANG_LEVEL := ../.. -DIRS := AST Basic Driver Lex Parse Sema Serialization - -include $(CLANG_LEVEL)/Makefile - -install-local:: - $(Echo) Installing Clang include files - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_includedir) - $(Verb) if test -d "$(PROJ_SRC_DIR)" ; then \ - cd $(PROJ_SRC_DIR)/.. && \ - for hdr in `find clang -type f \ - '(' -name LICENSE.TXT \ - -o -name '*.def' \ - -o -name '*.h' \ - -o -name '*.inc' \ - ')' -print \ - | grep -v CVS | grep -v .svn | grep -v .dir` ; do \ - instdir=$(DESTDIR)`dirname "$(PROJ_includedir)/$$hdr"` ; \ - if test \! -d "$$instdir" ; then \ - $(EchoCmd) Making install directory $$instdir ; \ - $(MKDIR) $$instdir ;\ - fi ; \ - $(DataInstall) $$hdr $(DESTDIR)$(PROJ_includedir)/$$hdr ; \ - done ; \ - fi -ifneq ($(PROJ_SRC_ROOT),$(PROJ_OBJ_ROOT)) - $(Verb) if test -d "$(PROJ_OBJ_ROOT)/tools/clang/include/clang" ; then \ - cd $(PROJ_OBJ_ROOT)/tools/clang/include && \ - for hdr in `find clang -type f \ - '(' -name LICENSE.TXT \ - -o -name '*.def' \ - -o -name '*.h' \ - -o -name '*.inc' \ - ')' -print \ - | grep -v CVS | grep -v .tmp | grep -v .dir` ; do \ - instdir=$(DESTDIR)`dirname "$(PROJ_includedir)/$$hdr"` ; \ - if test \! -d "$$instdir" ; then \ - $(EchoCmd) Making install directory $$instdir ; \ - $(MKDIR) $$instdir ;\ - fi ; \ - $(DataInstall) $$hdr $(DESTDIR)$(PROJ_includedir)/$$hdr ; \ - done ; \ - fi -endif diff --git a/cpp/llvm/tools/clang/include/clang/Parse/Makefile b/cpp/llvm/tools/clang/include/clang/Parse/Makefile deleted file mode 100644 index 296892c5..00000000 --- a/cpp/llvm/tools/clang/include/clang/Parse/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -CLANG_LEVEL := ../../.. -TD_SRC_DIR = $(PROJ_SRC_DIR)/../Basic -BUILT_SOURCES = AttrLateParsed.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/AttrLateParsed.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang attribute late-parsed table with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-late-parsed-list -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< \ No newline at end of file diff --git a/cpp/llvm/tools/clang/include/clang/Sema/Makefile b/cpp/llvm/tools/clang/include/clang/Sema/Makefile deleted file mode 100644 index f6662d6b..00000000 --- a/cpp/llvm/tools/clang/include/clang/Sema/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -CLANG_LEVEL := ../../.. -TD_SRC_DIR = $(PROJ_SRC_DIR)/../Basic -BUILT_SOURCES = AttrTemplateInstantiate.inc AttrParsedAttrList.inc AttrParsedAttrKinds.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/AttrTemplateInstantiate.inc.tmp : $(TD_SRC_DIR)/Attr.td \ - $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang attribute template instantiate code with tablegen" - $(Verb) $(ClangTableGen) -gen-clang-attr-template-instantiate -o \ - $(call SYSPATH, $@) -I $(PROJ_SRC_DIR)/../../ $< - -$(ObjDir)/AttrParsedAttrList.inc.tmp : $(TD_SRC_DIR)/Attr.td \ - $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang parsed attribute list with tablegen" - $(Verb) $(ClangTableGen) -gen-clang-attr-parsed-attr-list -o \ - $(call SYSPATH, $@) -I $(PROJ_SRC_DIR)/../../ $< - -$(ObjDir)/AttrParsedAttrKinds.inc.tmp : $(TD_SRC_DIR)/Attr.td \ - $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang parsed attribute kinds with tablegen" - $(Verb) $(ClangTableGen) -gen-clang-attr-parsed-attr-kinds -o \ - $(call SYSPATH, $@) -I $(PROJ_SRC_DIR)/../../ $< - - diff --git a/cpp/llvm/tools/clang/include/clang/Serialization/Makefile b/cpp/llvm/tools/clang/include/clang/Serialization/Makefile deleted file mode 100644 index 386f4537..00000000 --- a/cpp/llvm/tools/clang/include/clang/Serialization/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -CLANG_LEVEL := ../../.. -TD_SRC_DIR = $(PROJ_SRC_DIR)/../Basic -BUILT_SOURCES = AttrPCHRead.inc AttrPCHWrite.inc - -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/AttrPCHRead.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang PCH reader with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-pch-read -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< - -$(ObjDir)/AttrPCHWrite.inc.tmp : $(TD_SRC_DIR)/Attr.td $(CLANG_TBLGEN) \ - $(ObjDir)/.dir - $(Echo) "Building Clang PCH writer with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-attr-pch-write -o $(call SYSPATH, $@) \ - -I $(PROJ_SRC_DIR)/../../ $< diff --git a/cpp/llvm/tools/clang/lib/ARCMigrate/Makefile b/cpp/llvm/tools/clang/lib/ARCMigrate/Makefile deleted file mode 100644 index 5232c5e5..00000000 --- a/cpp/llvm/tools/clang/lib/ARCMigrate/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/ARCMigrate/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements code transformation to ARC mode. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangARCMigrate - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/AST/Makefile b/cpp/llvm/tools/clang/lib/AST/Makefile deleted file mode 100644 index 65383c55..00000000 --- a/cpp/llvm/tools/clang/lib/AST/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/AST/Makefile ------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the AST library for the C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangAST - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Analysis/Makefile b/cpp/llvm/tools/clang/lib/Analysis/Makefile deleted file mode 100644 index fbbb83d7..00000000 --- a/cpp/llvm/tools/clang/lib/Analysis/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/Analysis/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements analyses built on top of source-level CFGs. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangAnalysis - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Basic/Makefile b/cpp/llvm/tools/clang/lib/Basic/Makefile deleted file mode 100644 index fe2c5156..00000000 --- a/cpp/llvm/tools/clang/lib/Basic/Makefile +++ /dev/null @@ -1,40 +0,0 @@ -##===- clang/lib/Basic/Makefile ----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the Basic library for the C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangBasic - -include $(CLANG_LEVEL)/Makefile - -SVN_REVISION := $(strip \ - $(shell $(LLVM_SRC_ROOT)/utils/GetSourceVersion $(PROJ_SRC_DIR)/../..)) - -SVN_REPOSITORY := $(strip \ - $(shell $(LLVM_SRC_ROOT)/utils/GetRepositoryPath $(PROJ_SRC_DIR)/../..)) - -LLVM_REVISION := $(strip \ - $(shell $(LLVM_SRC_ROOT)/utils/GetSourceVersion $(LLVM_SRC_ROOT))) - -LLVM_REPOSITORY := $(strip \ - $(shell $(LLVM_SRC_ROOT)/utils/GetRepositoryPath $(LLVM_SRC_ROOT))) - -CPP.Defines += -I$(PROJ_SRC_DIR)/../../include -I$(PROJ_OBJ_DIR)/../../include \ - -DSVN_REVISION='"$(SVN_REVISION)"' -DSVN_REPOSITORY='"$(SVN_REPOSITORY)"' \ - -DLLVM_REVISION='"$(LLVM_REVISION)"' -DLLVM_REPOSITORY='"$(LLVM_REPOSITORY)"' - -$(ObjDir)/.ver-svn .ver: $(ObjDir)/.dir - @if [ '$(SVN_REVISION) $(LLVM_REVISION)' != '$(shell cat $(ObjDir)/.ver-svn 2>/dev/null)' ]; then\ - echo '$(SVN_REVISION) $(LLVM_REVISION)' > $(ObjDir)/.ver-svn; \ - fi -$(ObjDir)/.ver-svn: .ver -$(ObjDir)/Version.o: $(ObjDir)/.ver-svn diff --git a/cpp/llvm/tools/clang/lib/CodeGen/Makefile b/cpp/llvm/tools/clang/lib/CodeGen/Makefile deleted file mode 100644 index 6032dffe..00000000 --- a/cpp/llvm/tools/clang/lib/CodeGen/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- clang/lib/CodeGen/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the AST -> LLVM code generation library for the -# C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangCodeGen - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Driver/Makefile b/cpp/llvm/tools/clang/lib/Driver/Makefile deleted file mode 100644 index 454ab862..00000000 --- a/cpp/llvm/tools/clang/lib/Driver/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- clang/lib/Driver/Makefile ---------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangDriver - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/lib/Edit/Makefile b/cpp/llvm/tools/clang/lib/Edit/Makefile deleted file mode 100644 index 92a67ebc..00000000 --- a/cpp/llvm/tools/clang/lib/Edit/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- clang/lib/Edit/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangEdit - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Frontend/Makefile b/cpp/llvm/tools/clang/lib/Frontend/Makefile deleted file mode 100644 index 3c13ad69..00000000 --- a/cpp/llvm/tools/clang/lib/Frontend/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -##===- clang/lib/Frontend/Makefile -------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangFrontend - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/FrontendTool/Makefile b/cpp/llvm/tools/clang/lib/FrontendTool/Makefile deleted file mode 100644 index c43213ff..00000000 --- a/cpp/llvm/tools/clang/lib/FrontendTool/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- clang/lib/FrontendTool/Makefile ---------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangFrontendTool - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/lib/Headers/Makefile b/cpp/llvm/tools/clang/lib/Headers/Makefile deleted file mode 100644 index 42219c40..00000000 --- a/cpp/llvm/tools/clang/lib/Headers/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -##===- clang/lib/Headers/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. - -BUILT_SOURCES = arm_neon.h.inc -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -CLANG_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ - $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) - -HeaderDir := $(PROJ_OBJ_ROOT)/$(BuildMode)/lib/clang/$(CLANG_VERSION)/include - -HEADERS := $(notdir $(wildcard $(PROJ_SRC_DIR)/*.h)) - -OBJHEADERS := $(addprefix $(HeaderDir)/, $(HEADERS)) - - -$(OBJHEADERS): $(HeaderDir)/%.h: $(PROJ_SRC_DIR)/%.h $(HeaderDir)/.dir $(HeaderDir)/arm_neon.h - $(Verb) cp $< $@ - $(Echo) Copying $(notdir $<) to build dir - -$(HeaderDir)/arm_neon.h: $(BUILT_SOURCES) $(HeaderDir)/.dir - $(Verb) cp $< $@ - $(Echo) Copying $(notdir $<) to build dir - -$(HeaderDir)/module.map: $(PROJ_SRC_DIR)/module.map $(HeaderDir)/.dir - $(Verb) cp $< $@ - $(Echo) Copying $(notdir $<) to build dir - - -# Hook into the standard Makefile rules. -all-local:: $(OBJHEADERS) $(HeaderDir)/module.map - -PROJ_headers := $(DESTDIR)$(PROJ_prefix)/lib/clang/$(CLANG_VERSION)/include - -INSTHEADERS := $(addprefix $(PROJ_headers)/, $(HEADERS)) -INSTHEADERS += $(PROJ_headers)/arm_neon.h - -$(PROJ_headers): - $(Verb) $(MKDIR) $@ - -$(INSTHEADERS): $(PROJ_headers)/%.h: $(HeaderDir)/%.h | $(PROJ_headers) - $(Verb) $(DataInstall) $< $(PROJ_headers) - $(Echo) Installing compiler include file: $(notdir $<) - -$(PROJ_headers)/module.map: $(HeaderDir)/module.map | $(PROJ_headers) - $(Verb) $(DataInstall) $< $(PROJ_headers) - $(Echo) Installing compiler module map file: $(notdir $<) - - -install-local:: $(INSTHEADERS) $(PROJ_headers)/module.map - -$(ObjDir)/arm_neon.h.inc.tmp : $(CLANG_LEVEL)/include/clang/Basic/arm_neon.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang arm_neon.h.inc with tblgen" - $(Verb) $(ClangTableGen) -gen-arm-neon -o $(call SYSPATH, $@) $< diff --git a/cpp/llvm/tools/clang/lib/Lex/Makefile b/cpp/llvm/tools/clang/lib/Lex/Makefile deleted file mode 100644 index d80fb55c..00000000 --- a/cpp/llvm/tools/clang/lib/Lex/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- clang/lib/Lex/Makefile ------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the Lexer library for the C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/../../Makefile.config - -LIBRARYNAME := clangLex - -ifeq ($(ARCH),PowerPC) -CXX.Flags += -maltivec -endif - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Makefile b/cpp/llvm/tools/clang/lib/Makefile deleted file mode 100755 index 2eb72a91..00000000 --- a/cpp/llvm/tools/clang/lib/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -##===- lib/Makefile ----------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -CLANG_LEVEL := .. - -PARALLEL_DIRS = Headers Basic Lex Parse AST Sema CodeGen Analysis \ - StaticAnalyzer Edit Rewrite ARCMigrate Serialization Frontend \ - FrontendTool Tooling Driver - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Parse/Makefile b/cpp/llvm/tools/clang/lib/Parse/Makefile deleted file mode 100644 index 5ec7c333..00000000 --- a/cpp/llvm/tools/clang/lib/Parse/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/Parse/Makefile ----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the Parser library for the C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangParse - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Rewrite/Makefile b/cpp/llvm/tools/clang/lib/Rewrite/Makefile deleted file mode 100644 index 5fef9b2c..00000000 --- a/cpp/llvm/tools/clang/lib/Rewrite/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/Rewrite/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements code transformation / rewriting facilities. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangRewrite - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Sema/Makefile b/cpp/llvm/tools/clang/lib/Sema/Makefile deleted file mode 100644 index 2c02739d..00000000 --- a/cpp/llvm/tools/clang/lib/Sema/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- clang/lib/Sema/Makefile -----------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the semantic analyzer and AST builder library for the -# C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangSema - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/Serialization/Makefile b/cpp/llvm/tools/clang/lib/Serialization/Makefile deleted file mode 100644 index e89ddc38..00000000 --- a/cpp/llvm/tools/clang/lib/Serialization/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- clang/lib/Serialization/Makefile --------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements the semantic analyzer and AST builder library for the -# C-Language front-end. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangSerialization - -include $(CLANG_LEVEL)/Makefile - diff --git a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Checkers/Makefile b/cpp/llvm/tools/clang/lib/StaticAnalyzer/Checkers/Makefile deleted file mode 100644 index 2582908b..00000000 --- a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Checkers/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -##===- clang/lib/Checker/Makefile --------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements analyses built on top of source-level CFGs. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../../.. -LIBRARYNAME := clangStaticAnalyzerCheckers - -BUILT_SOURCES = Checkers.inc -TABLEGEN_INC_FILES_COMMON = 1 - -include $(CLANG_LEVEL)/Makefile - -$(ObjDir)/Checkers.inc.tmp : Checkers.td $(PROJ_SRC_DIR)/$(CLANG_LEVEL)/include/clang/StaticAnalyzer/Checkers/CheckerBase.td $(CLANG_TBLGEN) $(ObjDir)/.dir - $(Echo) "Building Clang SA Checkers tables with tblgen" - $(Verb) $(ClangTableGen) -gen-clang-sa-checkers -I $(PROJ_SRC_DIR)/$(CLANG_LEVEL)/include -o $(call SYSPATH, $@) $< diff --git a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Core/Makefile b/cpp/llvm/tools/clang/lib/StaticAnalyzer/Core/Makefile deleted file mode 100644 index 4aebc163..00000000 --- a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Core/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -##===- clang/lib/StaticAnalyzer/Core/Makefile --------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements analyses built on top of source-level CFGs. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../../.. -LIBRARYNAME := clangStaticAnalyzerCore - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Frontend/Makefile b/cpp/llvm/tools/clang/lib/StaticAnalyzer/Frontend/Makefile deleted file mode 100644 index 2698120d..00000000 --- a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Frontend/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -##===- clang/lib/StaticAnalyzer/Frontend/Makefile ----------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# Starting point into the static analyzer land for the driver. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../../.. -LIBRARYNAME := clangStaticAnalyzerFrontend - -CPP.Flags += -I${PROJ_OBJ_DIR}/../Checkers - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Makefile b/cpp/llvm/tools/clang/lib/StaticAnalyzer/Makefile deleted file mode 100644 index c166f063..00000000 --- a/cpp/llvm/tools/clang/lib/StaticAnalyzer/Makefile +++ /dev/null @@ -1,18 +0,0 @@ -##===- clang/lib/StaticAnalyzer/Makefile -------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This implements analyses built on top of source-level CFGs. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -DIRS := Checkers Frontend -PARALLEL_DIRS := Core - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/lib/Tooling/Makefile b/cpp/llvm/tools/clang/lib/Tooling/Makefile deleted file mode 100644 index 0d2e7a29..00000000 --- a/cpp/llvm/tools/clang/lib/Tooling/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -##===- clang/lib/Tooling/Makefile ---------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -LIBRARYNAME := clangTooling - -include $(CLANG_LEVEL)/Makefile diff --git a/cpp/llvm/tools/clang/runtime/Makefile b/cpp/llvm/tools/clang/runtime/Makefile deleted file mode 100644 index 4b0625d4..00000000 --- a/cpp/llvm/tools/clang/runtime/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -##===- runtime/Makefile ------------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := .. -include $(CLANG_LEVEL)/../../Makefile.config - -ifndef NO_RUNTIME_LIBS - -PARALLEL_DIRS := compiler-rt libcxx - -endif - -include $(CLANG_LEVEL)/Makefile - -install:: - diff --git a/cpp/llvm/tools/clang/runtime/compiler-rt/Makefile b/cpp/llvm/tools/clang/runtime/compiler-rt/Makefile deleted file mode 100644 index 534168b4..00000000 --- a/cpp/llvm/tools/clang/runtime/compiler-rt/Makefile +++ /dev/null @@ -1,163 +0,0 @@ -##===- clang/runtime/compiler-rt/Makefile ------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This file defines support for building the Clang runtime libraries (which are -# implemented by compiler-rt) and placing them in the proper locations in the -# Clang resources directory (i.e., where the driver expects them). -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/Makefile - -CLANG_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ - $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) - -ResourceDir := $(PROJ_OBJ_ROOT)/$(BuildMode)/lib/clang/$(CLANG_VERSION) -PROJ_resources := $(DESTDIR)$(PROJ_prefix)/lib/clang/$(CLANG_VERSION) - -ResourceLibDir := $(ResourceDir)/lib -PROJ_resources_lib := $(PROJ_resources)/lib - -# Expect compiler-rt to be in llvm/projects/compiler-rt -COMPILERRT_SRC_ROOT := $(LLVM_SRC_ROOT)/projects/compiler-rt - -# We don't currently support building runtime libraries when we are -# cross-compiling. The issue is that we really want to be set up so that the -# available compiler targets are independent of the current build. -# -# Since we have to build the runtime libraries for the target, it requires we -# have a cross compiler from the build machine to the target. Although in the -# case where for the current build (host == target), we do have such a cross -# compiler, but not defined in a way that is easy for us to reuse. Regardless, -# that also wouldn't help for other possible compiler configurations. -# -# Thus, the simple set up we currently use is to assume that we will be using -# the just built Clang to compile the compiler-rt libraries. As we grow better -# cross compilation support inside Clang and tool support in LLVM, this makes it -# easier for us to achieve the goal of having the compiler targets be easily -# selected at configure time. However, this design does currently preclude the -# building of compiler-rt libraries when the Clang itself is being cross -# compiled. -# -# There are three possible solutions: -# 1. Require building a build-target version of Clang when cross compiling. This -# is simplest, but als greatly increases the build time of cross builds. -# -# 2. Require cross builds have a build-target version of Clang available for -# use. This is a reasonable compromise on #1, as the compiler-rt libraries -# are simple enough that there is not a strong desire to ensure they are -# built with the exact version of Clang being used. Similarly, as Clang -# becomes a better cross compiler it is also increasingly more likely that -# the cross compiler being used will already be a version of Clang. -# -# 3. Come up with an alternate mechanism to define all the toolchain -# information that compiler-rt would need to build libraries for all the -# requested targets. This might be a simple short term solution, but is -# likely to be unwieldly and irritating to maintain in the long term. -ifneq ($(LLVM_CROSS_COMPILING),1) -ifneq ($(CLANG_NO_RUNTIME),1) -ifeq ($(shell test -d $(COMPILERRT_SRC_ROOT) && echo OK),OK) - -# Select the compiler-rt configuration to use, and install directory. -# -# FIXME: Eventually, we want some kind of configure support for this. We want to -# build/install runtime libraries for as many targets as clang was configured to -# support. -RuntimeDirs := -ifeq ($(OS),Darwin) -RuntimeDirs += darwin -RuntimeLibrary.darwin.Configs := \ - eprintf 10.4 osx ios cc_kext \ - asan_osx profile_osx profile_ios -endif - -# On Linux, include a library which has all the runtime functions. -ifeq ($(OS),Linux) -RuntimeDirs += linux -RuntimeLibrary.linux.Configs := - -# We currently only try to generate runtime libraries on x86. -ifeq ($(ARCH),x86) -RuntimeLibrary.linux.Configs += \ - full-i386 profile-i386 asan-i386 -endif -ifeq ($(ARCH),x86_64) -RuntimeLibrary.linux.Configs += \ - full-x86_64 profile-x86_64 asan-x86_64 -endif - -endif - -#### -# The build rules below are designed to be generic and should only need to be -# modified based on changes in the compiler-rt layout or build system. -#### - -# Rule to build the compiler-rt libraries we need. -# -# We build all the libraries in a single shot to avoid recursive make as much as -# possible. -BuildRuntimeLibraries: - $(Verb) $(MAKE) -C $(COMPILERRT_SRC_ROOT) \ - ProjSrcRoot=$(COMPILERRT_SRC_ROOT) \ - ProjObjRoot=$(PROJ_OBJ_DIR) \ - CC="$(ToolDir)/clang" \ - $(RuntimeDirs:%=clang_%) -.PHONY: BuildRuntimeLibraries -CleanRuntimeLibraries: - $(Verb) $(MAKE) -C $(COMPILERRT_SRC_ROOT) \ - ProjSrcRoot=$(COMPILERRT_SRC_ROOT) \ - ProjObjRoot=$(PROJ_OBJ_DIR) \ - clean -.PHONY: CleanRuntimeLibraries - -$(PROJ_resources_lib): - $(Verb) $(MKDIR) $@ - -# Expand rules for copying/installing each individual library. We can't use -# implicit rules here because we need to match against multiple things. -define RuntimeLibraryTemplate -$(PROJ_OBJ_DIR)/clang_$1/%/libcompiler_rt.a: BuildRuntimeLibraries - @true -.PRECIOUS: $(PROJ_OBJ_DIR)/clang_$1/%/libcompiler_rt.a - -# Rule to copy the libraries to their resource directory location. -$(ResourceLibDir)/$1/libclang_rt.%.a: \ - $(PROJ_OBJ_DIR)/clang_$1/%/libcompiler_rt.a \ - $(ResourceLibDir)/$1/.dir - $(Echo) Copying runtime library $1/$$* to build dir - $(Verb) cp $(PROJ_OBJ_DIR)/clang_$1/$$*/libcompiler_rt.a $$@ -RuntimeLibrary.$1: \ - $(RuntimeLibrary.$1.Configs:%=$(ResourceLibDir)/$1/libclang_rt.%.a) -.PHONY: RuntimeLibrary.$1 - -$(PROJ_resources_lib)/$1: $(PROJ_resources_lib) - $(Verb) $(MKDIR) $$@ - -$(PROJ_resources_lib)/$1/libclang_rt.%.a: \ - $(ResourceLibDir)/$1/libclang_rt.%.a | $(PROJ_resources_lib)/$1 - $(Echo) Installing compiler runtime library: $1/$$* - $(Verb) $(DataInstall) $$< $(PROJ_resources_lib)/$1 - -# Rule to install runtime libraries. -RuntimeLibraryInstall.$1: \ - $(RuntimeLibrary.$1.Configs:%=$(PROJ_resources_lib)/$1/libclang_rt.%.a) -.PHONY: RuntimeLibraryInstall.$1 -endef -$(foreach lib,$(RuntimeDirs), $(eval $(call RuntimeLibraryTemplate,$(lib)))) - -# Hook into the standard Makefile rules. -all-local:: $(RuntimeDirs:%=RuntimeLibrary.%) -install-local:: $(RuntimeDirs:%=RuntimeLibraryInstall.%) -clean-local:: CleanRuntimeLibraries - -endif -endif -endif diff --git a/cpp/llvm/tools/clang/runtime/libcxx/Makefile b/cpp/llvm/tools/clang/runtime/libcxx/Makefile deleted file mode 100644 index 42322dc8..00000000 --- a/cpp/llvm/tools/clang/runtime/libcxx/Makefile +++ /dev/null @@ -1,31 +0,0 @@ -##===- clang/runtime/libcxx/Makefile -----------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## -# -# This file defines support for installing a copy of the libcxx headers where -# the driver expects them. -# -##===----------------------------------------------------------------------===## - -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/Makefile - -PROJ_libcxx_hdrs := $(DESTDIR)$(PROJ_prefix)/lib - -# Expect libcxx to be in llvm/projects/libcxx -LIBCXX_SRC_ROOT := $(LLVM_SRC_ROOT)/projects/libcxx - -ifneq ($(CLANG_NO_RUNTIME),1) -ifeq ($(shell test -d $(LIBCXX_SRC_ROOT) && echo OK),OK) - -install-local:: - $(MAKE) -C $(LIBCXX_SRC_ROOT) \ - HEADER_DIR=$(PROJ_libcxx_hdrs) installheaders - -endif -endif diff --git a/cpp/llvm/tools/clang/test/CXX/over/over.match/over.match.best/over.best.ics/over.ics.user/p3-0x.cpp b/cpp/llvm/tools/clang/test/CXX/over/over.match/over.match.best/over.best.ics/over.ics.user/p3-0x.cpp deleted file mode 100644 index 1c71468e..00000000 --- a/cpp/llvm/tools/clang/test/CXX/over/over.match/over.match.best/over.best.ics/over.ics.user/p3-0x.cpp +++ /dev/null @@ -1,14 +0,0 @@ -// RUN: %clang_cc1 -fsyntax-only -std=c++11 -verify %s - -namespace PR6285 { - template struct identity - { typedef T type; }; - - struct D { - template - operator typename identity::type(); // expected-note{{candidate}} - }; - - int f() { return D(); } // expected-error{{no viable conversion}} -} - diff --git a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.class/p1.cpp b/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.class/p1.cpp deleted file mode 100644 index b65e1d01..00000000 --- a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.class/p1.cpp +++ /dev/null @@ -1,27 +0,0 @@ -// RUN: %clang_cc1 -fsyntax-only -verify %s - -template -struct X0 { - struct Inner; -}; - -template -struct X0::Inner { - T x; - U y; - - void f() { x = y; } // expected-error{{incompatible}} -}; - - -void test(int i, float f) { - X0::Inner inner; - inner.x = 5; - inner.y = 3.4; - inner.f(); - - X0::Inner inner2; - inner2.x = &i; - inner2.y = &f; - inner2.f(); // expected-note{{instantiation}} -} diff --git a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.enum/p1.cpp b/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.enum/p1.cpp deleted file mode 100644 index f8cc0094..00000000 --- a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.enum/p1.cpp +++ /dev/null @@ -1,152 +0,0 @@ -// RUN: %clang_cc1 -std=c++11 -verify %s - -template struct A { - enum E : T; // expected-note {{here}} - E v; - E f() { return A::e1; } // expected-error {{no member named 'e1' in 'A'}} - E g() { return E::e1; } - E h(); -}; - -A a; -A::E a0 = A().v; -int n = A::E::e1; // expected-error {{implicit instantiation of undefined member}} - -template enum A::E : T { e1, e2 }; - -// FIXME: Now that A::E is defined, we are supposed to inject its enumerators -// into the already-instantiated class A. This seems like a really bad idea, -// though, so we don't implement that, but what we do implement is inconsistent. -// -// Either do as the standard says, or only include enumerators lexically defined -// within the class in its scope. -A::E a1 = A::e1; // expected-error {{no member named 'e1' in 'A'}} - -A::E a2 = A::e2; - -template typename A::E A::h() { return e2; } -A::E a3 = A().h(); - - -template struct B { - enum class E; - E v; - E f() { return E::e1; } - E g(); -}; - -B b; -B::E b0 = B().v; - -template enum class B::E { e1, e2 }; -B::E b1 = B::E::e1; - -B::E b2 = B::E::e2; - -template typename B::E B::g() { return e2; } -B::E b3 = B().g(); - - -// Enumeration members of class templates can be explicitly specialized. For -// unscoped enumerations, specializations must be defined before the primary -// template is, since otherwise the primary template will be implicitly -// instantiated when we parse the nested name specifier. -template<> enum A::E : long long { e3, e4 }; // expected-error {{explicit specialization of 'E' after instantiation}} expected-note {{first required here}} - -template<> enum class B::E { e3, e4 }; -B::E b4 = B::E::e4; - -B::E b5; -template<> enum class B::E { e5 }; -void fb5() { b5 = decltype(b5)::e5; } -B::E b6 = B::E::e5; - - -template struct C { - enum class E : T; -}; - -template<> enum class C::E : long long { e3, e4 }; -C::E c0 = C::E::e3; - -C::E c1; -template<> enum class C::E : long { e5 }; -void fc1() { c1 = decltype(c1)::e5; } -C::E c2 = C::E::e5; - -template<> enum class C::E : int { e6 }; -template enum class C::E : T { e0 }; -C::E c3 = C::E::e6; -C::E c4 = C::E::e0; // expected-error {{no member named 'e0' in 'C::E'}} - - -// Enumeration members can't be partially-specialized. -template enum class B::E { e5, e6 }; // expected-error {{nested name specifier for a declaration cannot depend on a template parameter}} - - -// Explicit specializations can be forward-declared. -template -struct D { - enum class E { e1 }; -}; -template<> enum class D::E; -D::E d1 = D::E::e1; // expected-error {{incomplete type 'D::E'}} -template<> enum class D::E { e2 }; -D::E d2 = D::E::e2; -D::E d3 = D::E::e1; // expected-note {{first required here}} -D::E d4 = D::E::e2; // expected-error {{no member named 'e2'}} -template<> enum class D::E { e3 }; // expected-error {{explicit specialization of 'E' after instantiation}} - -template<> enum class D::E; -struct F { - // Per C++11 [class.friend]p3, these friend declarations have no effect. - // Only classes and functions can be friends. - template friend enum D::E; - template<> friend enum D::E; - - template<> friend enum D::E { e3 }; // expected-error {{cannot define a type in a friend declaration}} - -private: - static const int n = 1; // expected-note {{private here}} -}; -template<> enum class D::E { - e = F::n // expected-error {{private member}} -}; - -class Access { - friend class X; - - template - class Priv { - friend class X; - - enum class E : T; - }; - - class S { - typedef int N; // expected-note {{here}} - static const int k = 3; // expected-note {{here}} - - friend class Priv; - }; - - static const int k = 5; -}; - -template<> enum class Access::Priv::E - : Access::S::N { // expected-error {{private member}} - a = Access::k, // ok - b = Access::S::k // expected-error {{private member}} -}; - -template enum class Access::Priv::E : T { - c = Access::k, - d = Access::S::k -}; - -class X { - Access::Priv::E a = Access::Priv::E::a; - Access::Priv::E c = Access::Priv::E::d; - // FIXME: We should see an access error for this enumerator. - Access::Priv::E b = Access::Priv::E::d; -}; diff --git a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1-retmem.cpp b/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1-retmem.cpp deleted file mode 100644 index 4c05c622..00000000 --- a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1-retmem.cpp +++ /dev/null @@ -1,28 +0,0 @@ -// RUN: %clang_cc1 -fsyntax-only -verify %s - -template struct X1 { }; - -template -struct X0 { - typedef int size_type; - typedef T value_type; - - size_type f0() const; - value_type *f1(); - X1 f2(); -}; - -template -typename X0::size_type X0::f0() const { - return 0; -} - -template -typename X0::value_type *X0::f1() { - return 0; -}; - -template -X1::value_type*> X0::f2() { - return 0; -}; diff --git a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1.cpp b/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1.cpp deleted file mode 100644 index 17645639..00000000 --- a/cpp/llvm/tools/clang/test/CXX/temp/temp.decls/temp.class/temp.mem.func/p1.cpp +++ /dev/null @@ -1,100 +0,0 @@ -// RUN: %clang_cc1 -fsyntax-only -verify %s -template // expected-note{{previous template}} -class X0 { -public: - typedef int size_type; - - X0(int); - ~X0(); - - void f0(const T&, const U&); - - T& operator[](int i) const; - - void f1(size_type) const; - void f2(size_type) const; - void f3(size_type) const; - void f4() ; - - operator T*() const; - - T value; -}; - -template -void X0::f0(const T&, const U&) { // expected-note{{previous definition}} -} - -template -X& X0::operator[](int i) const { - (void)i; - return value; -} - -template -void X0::f1(int) const { } - -template -void X0::f2(size_type) const { } - -template // expected-error{{too many template parameters}} -void X0::f3(size_type) const { -} - -template -void X0::f4() { } // expected-error{{does not refer}} - -// FIXME: error message should probably say, "redefinition of 'X0::f0'" -// rather than just "redefinition of 'f0'" -template -void X0::f0(const T&, const U&) { // expected-error{{redefinition}} -} - -// Test out-of-line constructors, destructors -template -X0::X0(int x) : value(x) { } - -template -X0::~X0() { } - -// Test out-of-line conversion functions. -template -X0::operator T*() const { - return &value; -} - -namespace N { template class A {void a();}; } -namespace N { template void A::a() {} } - -// PR5566 -template -struct X1 { - template - struct B { void f(); }; -}; - -template -template -void X1::template B::f() { } - -// PR5527 -template

operation never modifies the archive. - -=item q[Rfz] - -Quickly append files to the end of the archive. The F, F, and F -modifiers apply to this operation. This operation quickly adds the -F to the archive without checking for duplicates that should be -removed first. If no F are specified, the archive is not modified. -Because of the way that B constructs the archive file, its dubious -whether the F operation is any faster than the F operation. - -=item r[Rabfuz] - -Replace or insert file members. The F, F, F, F, F, and F -modifiers apply to this operation. This operation will replace existing -F or insert them at the end of the archive if they do not exist. If no -F 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 modifier, -B 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 are specified, the listing is only for -those files. If no F are specified, the table of contents for the -whole archive is printed. - -=item x[oP] - -Extract archive members back to files. The F modifier applies to this -operation. This operation retrieves the indicated F from the archive -and writes them back to the operating system's file system. If no -F 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 Cfter the F member. If F 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 Cefore the F member. If F is not -found, the files are placed at the end of the archive. This modifier is -identical to the the F modifier. - -=item [f] - -Normally, B 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 but may also -thwart correct extraction of the files (duplicates may overwrite). If used with -the F option, the directory recursion will be performed but the file names -will all be Clattened to simple file names. - -=item [i] - -A synonym for the F option. - -=item [k] - -Normally, B will not print the contents of bitcode files when the -F