Written by the LLVM Team
-
THIS IS A WORK IN PROGRESS FOR LLVM 2.3 (currently in -progress on SVN HEAD)
+This is the fourteenth public release of the LLVM Compiler Infrastructure. -It includes many features and refinements from LLVM 2.2.
+It includes a large number of features and refinements from LLVM 2.2.LLVM 2.2 was the last LLVM release to support llvm-gcc 4.0 and llvm-upgrade. -llvm-gcc 4.0 has been replaced with llvm-gcc 4.2. llvm-upgrade was useful for -upgrading llvm 1.9 files to llvm 2.x syntax, but you can always use a previous -llvm release to do this.
+LLVM 2.3 no longer supports llvm-gcc 4.0, it has been replaced with + llvm-gcc 4.2.
+LLVM 2.3 no longer includes the llvm-upgrade tool. It was useful + for upgrading LLVM 1.9 files to LLVM 2.x syntax, but you can always use a + previous LLVM release to do this. One nice impact of this is that the LLVM + regression test suite no longer depends on llvm-upgrade, which makes it run + faster.
+ +The llvm2cpp tool has been folded into llc, use + llc -march=cpp instead of llvm2cpp.
+ +LLVM API Changes:
+ +-
+
- Several core LLVM IR classes have migrated to use the + 'FOOCLASS::Create(...)' pattern instead of 'new + FOOCLASS(...)' (e.g. where FOOCLASS=BasicBlock). We hope to + standardize on FOOCLASS::Create for all IR classes in the future, + but not all of them have been moved over yet. +
- LLVM 2.3 renames the LLVMBuilder and LLVMFoldingBuilder classes to + IRBuilder. + +
- MRegisterInfo was renamed to + + TargetRegisterInfo. +
- The MappedFile class is gone, please use + + MemoryBuffer instead. +
- The '-enable-eh' flag to llc has been removed. Now code should + encode whether it is safe to omit unwind information for a function by + tagging the Function object with the 'nounwind' attribute. +
- The ConstantFP::get method that uses APFloat now takes one argument + instead of two. The type argument has been removed, and the type is + now inferred from the size of the given APFloat value. + +
+The core LLVM 2.3 distribution currently consists of code from the core LLVM +repository (which roughly contains the LLVM optimizer, code generators and +supporting tools) and the llvm-gcc repository. In addition to this code, the +LLVM Project includes other sub-projects that are in development. The two which +are the most actively developed are the new vmkit Project +and the Clang Project. +
++The "vmkit" project is a new addition to the LLVM family. It is an +implementation of a JVM and a CLI Virtual Machines (Microsoft .NET is an +implementation of the CLI) using the Just-In-Time compiler of LLVM.
+ +The JVM, called JnJVM, executes real-world applications such as Apache +projects (e.g. Felix and Tomcat) and the SpecJVM98 benchmark. It uses the GNU +Classpath project for the base classes. The CLI implementation, called N3, is +its in early stages but can execute simple applications and the "pnetmark" +benchmark. It uses the pnetlib project as its core library.
+ +The 'vmkit' VMs compare in performance with industrial and top open-source +VMs on scientific applications. Besides the JIT, the VMs use many features of +the LLVM framework, including the standard set of optimizations, atomic +operations, custom function provider and memory manager for JITed methods, and +specific virtual machine optimizations. vmkit is not an official part of LLVM +2.3 release. It is publicly available under the LLVM license and can be +downloaded from: +
+ ++svn co http://llvm.org/svn/llvm-project/vmkit/trunk vmkit +
-LLVM 2.3 fully supports llvm-gcc 4.2 front-end.
+The Clang project is an effort to build +a set of new 'LLVM native' front-end technologies for the LLVM optimizer +and code generator. Clang is continuing to make major strides forward in all +areas. Its C and Objective-C parsing support is very solid, and the code +generation support is far enough along to build many C applications. While not +yet production quality, it is progressing very nicely. In addition, C++ +front-end work has started to make significant progress.
+ +At this point, Clang is most useful if you are interested in source-to-source +transformations (such as refactoring) and other source-level tools for C and +Objective-C. Clang now also includes tools for turning C code into pretty HTML, +and includes a new static +analysis tool in development. This tool focuses on automatically finding +bugs in C and Objective-C code.
+ +The clang project is an effort to build -a set of new 'llvm native' front-end technologies for the LLVM optimizer -and code generator. Currently, its C and Objective-C support is maturing -nicely, and it has advanced source-to-source analysis and transformation -capabilities. If you are interested in building source-level tools for C and -Objective-C (and eventually C++), you should take a look. However, note that -clang is not an official part of the LLVM 2.3 release. If you are interested in -this project, please see its web site.
+LLVM 2.3 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. +
LLVM 2.3 includes several major new capabilities:
-
+
The biggest change in LLVM 2.3 is Multiple Return Value (MRV) support. + MRVs allow LLVM IR to directly represent functions that return multiple + values without having to pass them "by reference" in the LLVM IR. This + allows a front-end to generate more efficient code, as MRVs are generally + returned in registers if a target supports them. See the LLVM IR Reference for more details.
+ +MRVs are fully supported in the LLVM IR, but are not yet fully supported in + on all targets. However, it is generally safe to return up to 2 values from + a function: most targets should be able to handle at least that. MRV + support is a critical requirement for X86-64 ABI support, as X86-64 requires + the ability to return multiple registers from functions, and we use MRVs to + accomplish this in a direct way.
+
+LLVM 2.3 includes a complete reimplementation of the "llvmc" + tool. It is designed to overcome several problems with the original + llvmc and to provide a superset of the features of the + 'gcc' driver.
+ +The main features of llvmc2 are: +
-
+
- Extended handling of command line options and smart rules for + dispatching them to different tools. +
- Flexible (and extensible) rules for defining different tools. +
- The different intermediate steps performed by tools are represented + as edges in the abstract graph. +
- The 'language' for driver behavior definition is tablegen and thus + it's relatively easy to add new features. +
- The definition of driver is transformed into set of C++ classes, thus + no runtime interpretation is needed. +
+
+LLVM 2.3 includes a completely rewritten interface for Link Time Optimization. This interface + is written in C, which allows for easier integration with C code bases, and + incorporates improvements we learned about from the first incarnation of the + interface.
+
+The Kaleidoscope tutorial now + includes a "port" of the tutorial that uses the Ocaml bindings to implement + the Kaleidoscope language.
+
LLVM 2.3 fully supports the llvm-gcc 4.2 front-end, and includes support +for the C, C++, Objective-C, Ada, and Fortran front-ends.
+ ++
-
+
- llvm-gcc 4.2 includes numerous fixes to better support the Objective-C +front-end. Objective-C now works very well on Mac OS/X. + +
- Fortran EQUIVALENCEs are now supported by the gfortran front-end. + +
- llvm-gcc 4.2 includes many other fixes which improve conformance with the +relevant parts of the GCC testsuite. + +
-
+
- LLVM IR now directly represents "common" linkage, instead of representing it +as a form of weak linkage. +
- LLVM IR now has support for atomic operations, and this functionality can +be accessed through the llvm-gcc "__sync_synchronize", +"__sync_val_compare_and_swap", and related builtins. Support for atomics are +available in the Alpha, X86, X86-64, and PowerPC backends. + +
- The C and Ocaml bindings have extended to cover pass managers, several +transformation passes, iteration over the LLVM IR, target data, and parameter +attribute lists.
In addition to a huge array of bug fixes and minor performance tweaks, the +LLVM 2.3 optimizers support a few major enhancements:
+ +-
+
+
Loop index set splitting on by default. +This transformation hoists conditions from loop bodies and reduces a loop's +iteration space to improve performance. For example,
+ ++for (i = LB; i < UB; ++i) + if (i <= NV) + LOOP_BODY +
+ +is transformed into:
+ ++NUB = min(NV+1, UB) +for (i = LB; i < NUB; ++i) + LOOP_BODY +
+
+
+- LLVM now includes a new memcpy optimization pass which removes +dead memcpy calls, unneeded copies of aggregates, and performs +return slot optimization. The LLVM optimizer now notices long sequences of +consecutive stores and merges them into memcpy's where profitable. + +
- Alignment detection for vector memory references and for memcpy and +memset is now more aggressive. + +
- The Aggressive Dead Code Elimination (ADCE) optimization has been rewritten +to make it both faster and safer in the presence of code containing infinite +loops. Some of its prior functionality has been factored out into the loop +deletion pass, which is safe for infinite loops. The new ADCE pass is +no longer based on control dependence, making it run faster. + +
- The 'SimplifyLibCalls' pass, which optimizes calls to libc and libm + functions for C-based languages, has been rewritten to be a FunctionPass + instead a ModulePass. This allows it to be run more often and to be + included at -O1 in llvm-gcc. It was also extended to include more + optimizations and several corner case bugs were fixed. + +
- LLVM now includes a simple 'Jump Threading' pass, which attempts to simplify + conditional branches using information about predecessor blocks, simplifying + the control flow graph. This pass is pretty basic at this point, but + catches some important cases and provides a foundation to build on. + +
- Several corner case bugs which could lead to deleting volatile memory + accesses have been fixed. + +
- Several optimizations have been sped up, leading to faster code generation + with the same code quality. + +
-
-
- MemOperand in the code generator. +
- The code generator now has support for carrying information about memory + references throughout the entire code generation process, via the + + MachineMemOperand class. In the future this will be used to improve + both pre-pass and post-pass scheduling, and to improve compiler-debugging + output. + +
- The target-independent code generator infrastructure now uses LLVM's + APInt + class to handle integer values, which allows it to support integer types + larger than 64 bits (for example i128). Note that support for such types is + also dependent on target-specific support. Use of APInt is also a step + toward support for non-power-of-2 integer sizes. + +
- LLVM 2.3 includes several compile time speedups for code with large basic + blocks, particularly in the instruction selection phase, register + allocation, scheduling, and tail merging/jump threading. + +
- LLVM 2.3 includes several improvements which make llc's + --view-sunit-dags visualization of scheduling dependency graphs + easier to understand. + +
- The code generator allows targets to write patterns that generate subreg + references directly in .td files now. + +
- memcpy lowering in the backend is more aggressive, particularly for + memcpy calls introduced by the code generator when handling + pass-by-value structure argument copies. + +
- Inline assembly with multiple register results now returns those results + directly in the appropriate registers, rather than going through memory. + Inline assembly that uses constraints like "ir" with immediates now use the + 'i' form when possible instead of always loading the value in a register. + This saves an instruction and reduces register use. + +
- Added support for PIC/GOT style tail calls on X86/32 and initial + support for tail calls on PowerPC 32 (it may also work on PowerPC 64 but is + not thoroughly tested).
In addition to a huge array of bug fixes and minor performance tweaks, the -LLVM 2.3 optimizers support a few major enhancements:
+New target-specific features include: +
-
+
- llvm-gcc's X86-64 ABI conformance is far improved, particularly in the + area of passing and returning structures by value. llvm-gcc compiled code + now interoperates very well on X86-64 systems with other compilers. + +
- Support for Win64 was added. This includes code generation itself, JIT + support, and necessary changes to llvm-gcc. + +
- The LLVM X86 backend now supports the support SSE 4.1 instruction set, and + the llvm-gcc 4.2 front-end supports the SSE 4.1 compiler builtins. Various + generic vector operations (insert/extract/shuffle) are much more efficient + when SSE 4.1 is enabled. The JIT automatically takes advantage of these + instructions, but llvm-gcc must be explicitly told to use them, e.g. with + -march=penryn. + +
- The X86 backend now does a number of optimizations that aim to avoid + converting numbers back and forth from SSE registers to the X87 floating + point stack. This is important because most X86 ABIs require return values + to be on the X87 Floating Point stack, but most CPUs prefer computation in + the SSE units. + +
- The X86 backend supports stack realignment, which is particularly useful for + vector code on OS's without 16-byte aligned stacks, such as Linux and + Windows. + +
- The X86 backend now supports the "sseregparm" options in GCC, which allow + functions to be tagged as passing floating point values in SSE + registers. + +
- Trampolines (taking the address of a nested function) now work on + Linux/X86-64. + +
- __builtin_prefetch is now compiled into the appropriate prefetch + instructions instead of being ignored. -
- Index set splitting on by default. +
- 128-bit integers are now supported on X86-64 targets. This can be used + through __attribute__((TImode)) in llvm-gcc. -
-
+
- The LLVM C backend now supports vector code. +
- The Cell SPU backend includes a number of improvements. It generates better + code and its stability/completeness is improving.
-
+
- LLVM now builds with GCC 4.3. +
- Bugpoint now supports running custom scripts (with the -run-custom + option) to determine how to execute the command and whether it is making + forward process.
LLVM is known to work on the following platforms:
-
-
- Intel and AMD machines running Red Hat Linux, Fedora Core and FreeBSD +
- Intel and AMD machines (IA32) running Red Hat Linux, Fedora Core and FreeBSD (and probably other unix-like systems).
- PowerPC and X86-based Mac OS X systems, running 10.3 and above in 32-bit and 64-bit modes.
- Intel and AMD machines running on Win32 using MinGW libraries (native).
- Intel and AMD machines running on Win32 with the Cygwin libraries (limited support is available for native builds with Visual C++). -
- Sun UltraSPARC workstations running Solaris 8. +
- Sun UltraSPARC workstations running Solaris 10.
- Alpha-based machines running Debian GNU/Linux. -
- Itanium-based machines running Linux and HP-UX. +
- Itanium-based (IA64) machines running Linux and HP-UX.
The core LLVM infrastructure uses -GNU autoconf to adapt itself +
The core LLVM infrastructure uses GNU autoconf to adapt itself to the machine and operating system on which it is built. However, minor porting may be required to get LLVM to work on new platforms. We welcome your portability patches and reports of successful builds or error messages.
@@ -263,9 +593,8 @@- The MSIL, IA64, Alpha, SPU, and MIPS backends are experimental. -
- The LLC "-filetype=asm" (the default) is the only supported +
- The llc "-filetype=asm" (the default) is the only supported value for this option. -
- The llvmc tool is not supported.
-
-
- The X86 backend does not yet support inline - assembly that uses the X86 floating point stack. -
- The X86 backend occasionally has alignment - problems on operating systems that don't require 16-byte stack alignment - (including most non-darwin OS's like linux). -
- The X86 backend generates inefficient floating point code when configured to - generate code for systems that don't have SSE2. +
- The X86 backend does not yet support + all inline assembly that uses the X86 + floating point stack. It supports the 'f' and 't' constraints, but not + 'u'. +
- The X86 backend generates inefficient floating point code when configured + to generate code for systems that don't have SSE2. +
- Win64 code generation wasn't widely tested. Everything should work, but we + expect small issues to happen. Also, llvm-gcc cannot build mingw64 runtime + currently due + to several + bugs due to lack of support for the + 'u' inline assembly constraint and X87 floating point inline assembly. +
- The X86-64 backend does not yet support position-independent code (PIC) + generation on Linux targets. +
- The X86-64 backend does not yet support the LLVM IR instruction + va_arg. Currently, the llvm-gcc front-end supports variadic + argument constructs on X86-64 by lowering them manually.
-
-
-
- C++ programs are likely to fail on IA64, as calls to setjmp are -made where the argument is not 16-byte aligned, as required on IA64. (Strictly -speaking this is not a bug in the IA64 back-end; it will also be encountered -when building C++ programs using the C back-end.) - -
- The C++ front-end does not use IA64 -ABI compliant layout of v-tables. In particular, it just stores function -pointers instead of function descriptors in the vtable. This bug prevents -mixing C++ code compiled with LLVM with C++ objects compiled by other C++ -compilers. - -
- There are a few ABI violations which will lead to problems when mixing LLVM -output with code built with other compilers, particularly for floating-point -programs. - -
- Defining vararg functions is not supported (but calling them is ok). - -
- The Itanium backend has bitrotted somewhat. +
- The Itanium backend is highly experimental, and has a number of known + issues. We are looking for a maintainer for the Itanium backend. If you + are interested, please contact the llvmdev mailing list.
-
-
- The C backend does not support inline - assembly code. -
- The C backend does not support vectors - yet. +
- The C backend has only basic support for + inline assembly code.
- The C backend violates the ABI of common C++ programs, preventing intermixing between C++ compiled by the CBE and - C++ code compiled with LLC or native compilers. + C++ code compiled with llc or native compilers.
- The C backend does not support all exception handling constructs.
llvm-gcc does not currently support Link-Time Optimization on most platforms "out-of-the-box". Please inquire on the llvmdev mailing list if you are interested.
-The only major language feature of GCC not supported by llvm-gcc is + the __builtin_apply family of builtins. However, some extensions + are only supported on some targets. For example, trampolines are only + supported on some targets (these are used when you take the address of a + nested function).
--
-
-
llvm-gcc does not support __builtin_apply yet. - See Constructing Calls: Dispatching a call to another function.
-
-
-llvm-gcc partially supports these GCC extensions:
--
-
- Nested Functions: - - As in Algol and Pascal, lexical scoping of functions. - Nested functions are supported, but llvm-gcc does not support - taking the address of a nested function (except on X86 targets) - or non-local gotos. - -
- Function Attributes:
-
- Declaring that functions have no side effects or that they can never
- return.
- - Supported: alias, always_inline, cdecl, - const, constructor, destructor, - deprecated, fastcall, format, - format_arg, non_null, noinline, - noreturn, nothrow, pure, regparm - section, stdcall, unused, used, - visibility, warn_unused_result, weak
- - Ignored: malloc, - no_instrument_function
-
-
-
If you run into GCC extensions which have not been included in any of these -lists, please let us know (also including whether or not they work).
+If you run into GCC extensions which are not supported, please let us know. +
-
-
- Exception handling only works well on the X86 and PowerPC targets. -It works well for x86-64 darwin but not x86-64 linux. +
- Exception handling works well on the X86 and PowerPC targets, including +X86-64 darwin. This works when linking to a libstdc++ compiled by GCC. It is +supported on X86-64 linux, but that is disabled by default in this release.
-
-
- The Ada front-end currently only builds on x86-32. This is mainly due +
- The Ada front-end currently only builds on X86-32. This is mainly due to lack of trampoline support (pointers to nested functions) on other platforms, -however it also fails to build on x86-64 +however it also fails to build on X86-64 which does support trampolines.
- The Ada front-end fails to bootstrap. Workaround: configure with --disable-bootstrap.
- The c380004 and c393010 ACATS tests -fail (c380004 also fails with gcc-4.2 mainline). -
- Many gcc specific Ada tests continue to crash the compiler. +fail (c380004 also fails with gcc-4.2 mainline). When built at -O3, the +cxg2021 ACATS test also fails. +
- Some gcc specific Ada tests continue to crash the compiler. The testsuite +reports most tests as having failed even though they pass.
- The -E binder option (exception backtraces) does not work and will result in programs crashing if an exception is raised. Workaround: do not use -E. @@ -509,29 +794,15 @@ or finish at a non-byte offset in a record. Workaround: do not pack records or use representation clauses that result in a field of a non-discrete type starting or finishing in the middle of a byte. -
- The lli interpreter considers 'main' -as generated by the Ada binder to be invalid. -Workaround: hand edit the file to use pointers for argv and envp rather than -integers. -
- The -fstack-check option is ignored. -
-
-
- The llvm-gcc 4.2 gfortran front-end supports a broad range of Fortran code, but does -not support EQUIVALENCE yet. +
- The lli interpreter considers +'main' as generated by the Ada binder to be invalid. +Workaround: hand edit the file to use pointers for argv and +envp rather than integers. +
- The -fstack-check option is +ignored.
-
+
- Tail call optimization
- The X86 backend
- The PowerPC backend
-
@@ -1620,7 +1621,51 @@
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. +
- 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.
+On x86 and x86-64 one register is reserved for indirect tail calls (e.g via a function pointer). So there is one less register for integer argument passing. For x86 this means 2 registers (if inreg parameter attribute is used) and for x86-64 this means 5 register are used.
+NOTE: This document is a work in progress!
--
-
- Abstract -
- Introduction - - -
- Configuration
-
-
-
- Overview -
- Configuration Files -
- Syntax -
- Substitutions -
- Sample Config File -
- Glossary -
This document describes the requirements, design, and configuration of the - LLVM compiler driver, llvmc. The compiler driver knows about LLVM's - tool set and can be configured to know about a variety of compilers for - source languages. It uses this knowledge to execute the tools necessary - to accomplish general compilation, optimization, and linking tasks. The main - purpose of llvmc is to provide a simple and consistent interface to - all compilation tasks. This reduces the burden on the end user who can just - learn to use llvmc instead of the entire LLVM tool set and all the - source language compilers compatible with LLVM.
-The llvmc tool is a configurable compiler - driver. As such, it isn't a compiler, optimizer, - or a linker itself but it drives (invokes) other software that perform those - tasks. If you are familiar with the GNU Compiler Collection's gcc - tool, llvmc is very similar.
-The following introductory sections will help you understand why this tool - is necessary and what it does.
-llvmc was invented to make compilation of user programs with - LLVM-based tools easier. To accomplish this, llvmc strives to:
--
-
- Be the single point of access to most of the LLVM tool set. -
- Hide the complexities of the LLVM tools through a single interface. -
- Provide a consistent interface for compiling all languages. -
Additionally, llvmc makes it easier to write a compiler for use - with LLVM, because it:
--
-
- Makes integration of existing non-LLVM tools simple. -
- Extends the capabilities of minimal compiler tools by optimizing their - output. -
- Reduces the number of interfaces a compiler writer must know about - before a working compiler can be completed (essentially only the VMCore - interfaces need to be understood). -
- Supports source language translator invocation via both dynamically - loadable shared objects and invocation of an executable. -
At a high level, llvmc operation is very simple. The basic action - taken by llvmc is to simply invoke some tool or set of tools to fill - the user's request for compilation. Every execution of llvmctakes the - following sequence of steps:
--
-
- Collect Command Line Options -
- The command line options provide the marching orders to llvmc - on what actions it should perform. This is the request the user is making - of llvmc and it is interpreted first. See the llvmc - manual page for details on the - options. -
- Read Configuration Files -
- Based on the options and the suffixes of the filenames presented, a set - of configuration files are read to configure the actions llvmc will - take. Configuration files are provided by either LLVM or the - compiler tools that llvmc invokes. These files determine what - actions llvmc will take in response to the user's request. See - the section on configuration for more details. - -
- Determine Phases To Execute -
- Based on the command line options and configuration files, - llvmc determines the compilation phases that - must be executed by the user's request. This is the primary work of - llvmc. -
- Determine Actions To Execute -
- Each phase to be executed can result in the - invocation of one or more actions. An action is - either a whole program or a function in a dynamically linked shared library. - In this step, llvmc determines the sequence of actions that must be - executed. Actions will always be executed in a deterministic order. -
- Execute Actions -
- The actions necessary to support the user's - original request are executed sequentially and deterministically. All - actions result in either the invocation of a whole program to perform the - action or the loading of a dynamically linkable shared library and invocation - of a standard interface function within that library. -
- Termination -
- If any action fails (returns a non-zero result code), llvmc - also fails and returns the result code from the failing action. If - everything succeeds, llvmc will return a zero result code. -
llvmc's operation must be simple, regular and predictable. - Developers need to be able to rely on it to take a consistent approach to - compilation. For example, the invocation:
-
- llvmc -O2 x.c y.c z.c -o xyz
- must produce exactly the same results as:
-- llvmc -O2 x.c -o x.o - llvmc -O2 y.c -o y.o - llvmc -O2 z.c -o z.o - llvmc -O2 x.o y.o z.o -o xyz-
To accomplish this, llvmc uses a very simple goal oriented - procedure to do its work. The overall goal is to produce a functioning - executable. To accomplish this, llvmc always attempts to execute a - series of compilation phases in the same sequence. - However, the user's options to llvmc can cause the sequence of phases - to start in the middle or finish early.
-llvmc breaks every compilation task into the following five - distinct phases:
-- Preprocessing
- Not all languages support preprocessing; - but for those that do, this phase can be invoked. This phase is for - languages that provide combining, filtering, or otherwise altering with the - source language input before the translator parses it. Although C and C++ - are the most common users of this phase, other languages may provide their - own preprocessor (whether its the C pre-processor or not). -
- Translation
- The translation phase converts the source - language input into something that LLVM can interpret and use for - downstream phases. The translation is essentially from "non-LLVM form" to - "LLVM form". -
- Optimization
- Once an LLVM Module has been obtained from - the translation phase, the program enters the optimization phase. This phase - attempts to optimize all of the input provided on the command line according - to the options provided. -
- Linking
- The inputs are combined to form a complete - program. -
The following table shows the inputs, outputs, and command line options - applicable to each phase.
-| Phase | -Inputs | -Outputs | -Options | -
|---|---|---|---|
| Preprocessing | -
|
-
|
-
|
-
| Translation | -
|
-
|
-
|
-
| Optimization | -
|
-
|
-
|
-
| Linking | -
|
-
|
-
|
-
An action, with regard to llvmc is a basic operation that it takes - in order to fulfill the user's request. Each phase of compilation will invoke - zero or more actions in order to accomplish that phase.
-Actions come in two forms:
--
-
- Invokable Executables -
- Functions in a shared library -
This section of the document describes the configuration files used by - llvmc. Configuration information is relatively static for a - given release of LLVM and a compiler tool. However, the details may - change from release to release of either. Users are encouraged to simply use - the various options of the llvmc command and ignore the configuration - of the tool. These configuration files are for compiler writers and LLVM - developers. Those wishing to simply use llvmc don't need to understand - this section but it may be instructive on how the tool works.
-llvmc is highly configurable both on the command line and in -configuration files. The options it understands are generic, consistent and -simple by design. Furthermore, the llvmc options apply to the -compilation of any LLVM enabled programming language. To be enabled as a -supported source language compiler, a compiler writer must provide a -configuration file that tells llvmc how to invoke the compiler -and what its capabilities are. The purpose of the configuration files then -is to allow compiler writers to specify to llvmc how the compiler -should be invoked. Users may but are not advised to alter the compiler's -llvmc configuration.
- -Because llvmc just invokes other programs, it must deal with the -available command line options for those programs regardless of whether they -were written for LLVM or not. Furthermore, not all compiler tools will -have the same capabilities. Some compiler tools will simply generate LLVM assembly -code, others will be able to generate fully optimized bitcode. In general, -llvmc doesn't make any assumptions about the capabilities or command -line options of a sub-tool. It simply uses the details found in the -configuration files and leaves it to the compiler writer to specify the -configuration correctly.
- -This approach means that new compiler tools can be up and working very -quickly. As a first cut, a tool can simply compile its source to raw -(unoptimized) bitcode or LLVM assembly and llvmc can be configured -to pick up the slack (translate LLVM assembly to bitcode, optimize the -bitcode, generate native assembly, link, etc.). In fact, the compiler tools -need not use any LLVM libraries, and it could be written in any language -(instead of C++). The configuration data will allow the full range of -optimization, assembly, and linking capabilities that LLVM provides to be added -to these kinds of tools. Enabling the rapid development of front-ends is one -of the primary goals of llvmc.
- -As a compiler tool matures, it may utilize the LLVM libraries and tools -to more efficiently produce optimized bitcode directly in a single compilation -and optimization program. In these cases, multiple tools would not be needed -and the configuration data for the compiler would change.
- -Configuring llvmc to the needs and capabilities of a source language -compiler is relatively straight-forward. A compiler writer must provide a -definition of what to do for each of the five compilation phases for each of -the optimization levels. The specification consists simply of prototypical -command lines into which llvmc can substitute command line -arguments and file names. Note that any given phase can be completely blank if -the source language's compiler combines multiple phases into a single program. -For example, quite often pre-processing, translation, and optimization are -combined into a single program. The specification for such a compiler would have -blank entries for pre-processing and translation but a full command line for -optimization.
-Each configuration file provides the details for a single source language - that is to be compiled. This configuration information tells llvmc - how to invoke the language's pre-processor, translator, optimizer, assembler - and linker. Note that a given source language needn't provide all these tools - as many of them exist in llvm currently.
-llvmc always looks for files of a specific name. It uses the
- first file with the name its looking for by searching directories in the
- following order:
-
-
-
- Any directory specified by the -config-dir option will be - checked first. -
- If the environment variable LLVM_CONFIG_DIR is set, and it contains - the name of a valid directory, that directory will be searched next. -
- If the user's home directory (typically /home/user contains - a sub-directory named .llvm and that directory contains a - sub-directory named etc then that directory will be tried - next. -
- If the LLVM installation directory (typically /usr/local/llvm - contains a sub-directory named etc then that directory will be - tried last. -
- A standard "system" directory will be searched next. This is typically - /etc/llvm on UNIX™ and C:\WINNT on Microsoft - Windows™. -
- If the configuration file sought still can't be found, llvmc - will print an error message and exit. -
The first file found in this search will be used. Other files with the - same name will be ignored even if they exist in one of the subsequent search - locations.
-In the directories searched, each configuration file is given a specific - name to foster faster lookup (so llvmc doesn't have to do directory searches). - The name of a given language specific configuration file is simply the same - as the suffix used to identify files containing source in that language. - For example, a configuration file for C++ source might be named - cpp, C, or cxx. For languages that support multiple - file suffixes, multiple (probably identical) files (or symbolic links) will - need to be provided.
-Which configuration files are read depends on the command line options and - the suffixes of the file names provided on llvmc's command line. Note - that the -x LANGUAGE option alters the language that llvmc - uses for the subsequent files on the command line. Only the configuration - files actually needed to complete llvmc's task are read. Other - language specific files will be ignored.
-The syntax of the configuration files is very simple and somewhat - compatible with Java's property files. Here are the syntax rules:
--
-
- The file encoding is ASCII. -
- The file is line oriented. There should be one configuration definition - per line. Lines are terminated by the newline (0x0A) and/or carriage return - characters (0x0D) -
- A backslash (\) before a newline causes the newline to be - ignored. This is useful for line continuation of long definitions. A - backslash anywhere else is recognized as a backslash. -
- A configuration item consists of a name, an = and a value. -
- A name consists of a sequence of identifiers separated by period. -
- An identifier consists of specific keywords made up of only lower case - and upper case letters (e.g. lang.name). -
- Values come in four flavors: booleans, integers, commands and - strings. -
- Valid "false" boolean values are false False FALSE no No NO - off Off and OFF. -
- Valid "true" boolean values are true True TRUE yes Yes YES - on On and ON. -
- Integers are simply sequences of digits. -
- Commands start with a program name and are followed by a sequence of - words that are passed to that program as command line arguments. Program - arguments that begin and end with the % sign will have their value - substituted. Program names beginning with / are considered to be - absolute. Otherwise the PATH will be applied to find the program to - execute. -
- Strings are composed of multiple sequences of characters from the - character class [-A-Za-z0-9_:%+/\\|,] separated by white - space. -
- White space on a line is folded. Multiple blanks or tabs will be - reduced to a single blank. -
- White space before the configuration item's name is ignored. -
- White space on either side of the = is ignored. -
- White space in a string value is used to separate the individual - components of the string value but otherwise ignored. -
- Comments are introduced by the # character. Everything after a - # and before the end of line is ignored. -
The table below provides definitions of the allowed configuration items - that may appear in a configuration file. Every item has a default value and - does not need to appear in the configuration file. Missing items will have the - default value. Each identifier may appear as all lower case, first letter - capitalized or all upper case.
-| Name | -Value Type | -Description | -Default | -
|---|---|---|---|
LLVMC ITEMS | |||
| version | -string | -Provides the version string for the contents of this - configuration file. What is accepted as a legal configuration file - will change over time and this item tells llvmc which version - should be expected. | -b | -
LANG ITEMS | |||
| lang.name | -string | -Provides the common name for a language definition. - For example "C++", "Pascal", "FORTRAN", etc. | -blank | -
| lang.opt1 | -string | -Specifies the parameters to give the optimizer when - -O1 is specified on the llvmc command line. | --simplifycfg -instcombine -mem2reg | -
| lang.opt2 | -string | -Specifies the parameters to give the optimizer when - -O2 is specified on the llvmc command line. | -TBD | -
| lang.opt3 | -string | -Specifies the parameters to give the optimizer when - -O3 is specified on the llvmc command line. | -TBD | -
| lang.opt4 | -string | -Specifies the parameters to give the optimizer when - -O4 is specified on the llvmc command line. | -TBD | -
| lang.opt5 | -string | -Specifies the parameters to give the optimizer when - -O5 is specified on the llvmc command line. | -TBD | -
PREPROCESSOR ITEMS | |||
| preprocessor.command | -command | -This provides the command prototype that will be used - to run the preprocessor. This is generally only used with the - -E option. | -<blank> | -
| preprocessor.required | -boolean | -This item specifies whether the pre-processing phase - is required by the language. If the value is true, then the - preprocessor.command value must not be blank. With this option, - llvmc will always run the preprocessor as it assumes that the - translation and optimization phases don't know how to pre-process their - input. | -false | -
TRANSLATOR ITEMS | |||
| translator.command | -command | -This provides the command prototype that will be used - to run the translator. Valid substitutions are %in% for the - input file and %out% for the output file. | -<blank> | -
| translator.output | -bitcode or assembly | -This item specifies the kind of output the language's - translator generates. | -bitcode | -
| translator.preprocesses | -boolean | -Indicates that the translator also preprocesses. If - this is true, then llvmc will skip the pre-processing phase - whenever the final phase is not pre-processing. | -false | -
OPTIMIZER ITEMS | |||
| optimizer.command | -command | -This provides the command prototype that will be used - to run the optimizer. Valid substitutions are %in% for the - input file and %out% for the output file. | -<blank> | -
| optimizer.output | -bitcode or assembly | -This item specifies the kind of output the language's - optimizer generates. Valid values are "assembly" and "bitcode" | -bitcode | -
| optimizer.preprocesses | -boolean | -Indicates that the optimizer also preprocesses. If - this is true, then llvmc will skip the pre-processing phase - whenever the final phase is optimization or later. | -false | -
| optimizer.translates | -boolean | -Indicates that the optimizer also translates. If - this is true, then llvmc will skip the translation phase - whenever the final phase is optimization or later. | -false | -
ASSEMBLER ITEMS | |||
| assembler.command | -command | -This provides the command prototype that will be used - to run the assembler. Valid substitutions are %in% for the - input file and %out% for the output file. | -<blank> | -
On any configuration item that ends in command, you must - specify substitution tokens. Substitution tokens begin and end with a percent - sign (%) and are replaced by the corresponding text. Any substitution - token may be given on any command line but some are more useful than - others. In particular each command should have both an %in% - and an %out% substitution. The table below provides definitions of - each of the allowed substitution tokens.
-| Substitution Token | -Replacement Description | -
|---|---|
| %args% | -Replaced with all the tool-specific arguments given - to llvmc via the -T set of options. This just allows - you to place these arguments in the correct place on the command line. - If the %args% option does not appear on your command line, - then you are explicitly disallowing the -T option for your - tool. - | -
| %force% | -Replaced with the -f option if it was - specified on the llvmc command line. This is intended to tell - the compiler tool to force the overwrite of output files. - | -
| %in% | -Replaced with the full path of the input file. You - needn't worry about the cascading of file names. llvmc will - create temporary files and ensure that the output of one phase is the - input to the next phase. | -
| %opt% | -Replaced with the optimization options for the - tool. If the tool understands the -O options then that will - be passed. Otherwise, the lang.optN series of configuration - items will specify which arguments are to be given. | -
| %out% | -Replaced with the full path of the output file. - Note that this is not necessarily the output file specified with the - -o option on llvmc's command line. It might be a - temporary file that will be passed to a subsequent phase's input. - | -
| %stats% | -If your command accepts the -stats option, - use this substitution token. If the user requested -stats - from the llvmc command line then this token will be replaced - with -stats, otherwise it will be ignored. - | -
| %target% | -Replaced with the name of the target "machine" for - which code should be generated. The value used here is taken from the - llvmc option -march. - | -
| %time% | -If your command accepts the -time-passes - option, use this substitution token. If the user requested - -time-passes from the llvmc command line then this - token will be replaced with -time-passes, otherwise it will - be ignored. - | -
Since an example is always instructive, here's how the Stacker language - configuration file looks.
--# Stacker Configuration File For llvmc - -########################################################## -# Language definitions -########################################################## - lang.name=Stacker - lang.opt1=-simplifycfg -instcombine -mem2reg - lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \ - -gcse -dse -scalarrepl -sccp - lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \ - -gcse -dse -scalarrepl -sccp -branch-combine -adce \ - -globaldce -inline -licm - lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \ - -gcse -dse -scalarrepl -sccp -ipconstprop \ - -branch-combine -adce -globaldce -inline -licm - lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \ - -gcse -dse scalarrepl -sccp -ipconstprop \ - -branch-combine -adce -globaldce -inline -licm \ - -block-placement - -########################################################## -# Pre-processor definitions -########################################################## - - # Stacker doesn't have a preprocessor but the following - # allows the -E option to be supported - preprocessor.command=cp %in% %out% - preprocessor.required=false - -########################################################## -# Translator definitions -########################################################## - - # To compile stacker source, we just run the stacker - # compiler with a default stack size of 2048 entries. - translator.command=stkrc -s 2048 %in% -o %out% %time% \ - %stats% %force% %args% - - # stkrc doesn't preprocess but we set this to true so - # that we don't run the cp command by default. - translator.preprocesses=true - - # The translator is required to run. - translator.required=true - - # stkrc doesn't handle the -On options - translator.output=bitcode - -########################################################## -# Optimizer definitions -########################################################## - - # For optimization, we use the LLVM "opt" program - optimizer.command=opt %in% -o %out% %opt% %time% %stats% \ - %force% %args% - - optimizer.required = true - - # opt doesn't translate - optimizer.translates = no - - # opt doesn't preprocess - optimizer.preprocesses=no - - # opt produces bitcode - optimizer.output = bc - -########################################################## -# Assembler definitions -########################################################## - assembler.command=llc %in% -o %out% %target% %time% %stats% --
This document uses precise terms in reference to the various artifacts and - concepts related to compilation. The terms used throughout this document are - defined below.
--
-
- assembly -
- A compilation phase in which LLVM bitcode or - LLVM assembly code is assembled to a native code format (either target - specific aseembly language or the platform's native object file format). - - -
- compiler -
- Refers to any program that can be invoked by llvmc to accomplish - the work of one or more compilation phases. - -
- driver -
- Refers to llvmc itself. - -
- linking -
- A compilation phase in which LLVM bitcode files - and (optionally) native system libraries are combined to form a complete - executable program. - -
- optimization -
- A compilation phase in which LLVM bitcode is - optimized. - -
- phase -
- Refers to any one of the five compilation phases that that - llvmc supports. The five phases are: - preprocessing, - translation, - optimization, - assembly, - linking. - -
- source language -
- Any common programming language (e.g. C, C++, Java, Stacker, ML, - FORTRAN). These languages are distinguished from any of the lower level - languages (such as LLVM or native assembly), by the fact that a - translation phase - is required before LLVM can be applied. +
- tool -
- Refers to any program in the LLVM tool set. +
- translation -
- A compilation phase in which - source language code is translated into - either LLVM assembly language or LLVM bitcode. - -
- Compiling with LLVMC +
- Predefined options +
- Customizing LLVMC: the compilation graph +
- Writing a tool description +
- Option list - specifying all options in a single place +
- Using hooks and environment variables in the cmd_line property +
- Conditional evaluation: the case expression +
- Language map +
- References +
- -o FILE - Output file name. +
- -x LANGUAGE - Specify the language of the following input files +until the next -x option. +
- -v - Enable verbose mode, i.e. print out all executed commands. +
- --view-graph - Show a graphical representation of the compilation +graph. Requires that you have dot and gv commands +installed. Hidden option, useful for debugging. +
- --write-graph - Write a compilation-graph.dot file in the +current directory with the compilation graph description in the +Graphviz format. Hidden option, useful for debugging. +
- --save-temps - Write temporary files to the current directory +and do not delete them on exit. Hidden option, useful for debugging. +
- --help, --help-hidden, --version - These options have +their standard meaning. +
- Possible tool properties:
-
+
- in_language - input language name. +
- out_language - output language name. +
- output_suffix - output file suffix. +
- cmd_line - the actual command used to run the tool. You can +use $INFILE and $OUTFILE variables, output redirection +with >, hook invocations ($CALL), environment variables +(via $ENV) and the case construct (more on this below). +
- join - this tool is a "join node" in the graph, i.e. it gets a +list of input files and joins them together. Used for linkers. +
- sink - all command-line options that are not handled by other +tools are passed to this tool. +
+ Possible option types:
++
+-
+
- switch_option - a simple boolean switch, for example -time. +
- parameter_option - option that takes an argument, for example +-std=c99; +
- parameter_list_option - same as the above, but more than one +occurence of the option is allowed. +
- prefix_option - same as the parameter_option, but the option name +and parameter value are not separated. +
- prefix_list_option - same as the above, but more than one +occurence of the option is allowed; example: -lm -lpthread. +
- alias_option - a special option type for creating +aliases. Unlike other option types, aliases are not allowed to +have any properties besides the aliased option name. Usage +example: (alias_option "preprocess", "E") +
+Possible option properties:
++
+-
+
- append_cmd - append a string to the tool invocation command. +
- forward - forward this option unchanged. +
- output_suffix - modify the output suffix of this +tool. Example : (switch "E", (output_suffix "i"). +
- stop_compilation - stop compilation after this phase. +
- unpack_values - used for for splitting and forwarding +comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is +converted to -foo=bar -baz and appended to the tool invocation +command. +
- help - help string associated with this option. Used for +--help output. +
- required - this option is obligatory. +
+- Possible tests are:
-
+
- switch_on - Returns true if a given command-line option is +provided by the user. Example: (switch_on "opt"). Note that +you have to define all possible command-line options separately in +the tool descriptions. See the next doc_text for the discussion of +different kinds of command-line options. +
- parameter_equals - Returns true if a command-line parameter equals +a given value. Example: (parameter_equals "W", "all"). +
- element_in_list - Returns true if a command-line parameter list +includes a given value. Example: (parameter_in_list "l", "pthread"). +
- input_languages_contain - Returns true if a given language +belongs to the current input language set. Example: +`(input_languages_contain "c++"). +
- in_language - Evaluates to true if the language of the input +file equals to the argument. Valid only when using case +expression in a cmd_line tool property. Example: +`(in_language "c++"). +
- not_empty - Returns true if a given option (which should be +either a parameter or a parameter list) is set by the +user. Example: `(not_empty "o"). +
- default - Always evaluates to true. Should always be the last +test in the case expression. +
- and - A standard logical combinator that returns true iff all +of its arguments return true. Used like this: (and (test1), +(test2), ... (testN)). Nesting of and and or is allowed, +but not encouraged. +
- or - Another logical combinator that returns true only if any +one of its arguments returns true. Example: (or (test1), +(test2), ... (testN)). +
+
-
-The LLVM Compiler Infrastructure
-Last modified: $Date$ +
Note: This document is a work-in-progress. Additions and clarifications + are welcome.
+LLVMC is a generic compiler driver, designed to be customizable and +extensible. It plays the same role for LLVM as the gcc program +does for GCC - LLVMC's job is essentially to transform a set of input +files into a set of targets depending on configuration rules and user +options. What makes LLVMC different is that these transformation rules +are completely customizable - in fact, LLVMC knows nothing about the +specifics of transformation (even the command-line options are mostly +not hard-coded) and regards the transformation structure as an +abstract graph. This makes it possible to adapt LLVMC for other +purposes - for example, as a build tool for game resources.
+Because LLVMC employs TableGen [1] as its configuration language, you +need to be familiar with it to customize LLVMC.
+-
+
LLVMC tries hard to be as compatible with gcc as possible, +although there are some small differences. Most of the time, however, +you shouldn't be able to notice them:
++$ # This works as expected: +$ llvmc2 -O3 -Wall hello.cpp +$ ./a.out +hello ++
One nice feature of LLVMC is that one doesn't have to distinguish +between different compilers for different languages (think g++ and +gcc) - the right toolchain is chosen automatically based on input +language names (which are, in turn, determined from file +extensions). If you want to force files ending with ".c" to compile as +C++, use the -x option, just like you would do it with gcc:
++$ llvmc2 -x c hello.cpp +$ # hello.cpp is really a C file +$ ./a.out +hello ++
On the other hand, when using LLVMC as a linker to combine several C++ +object files you should provide the --linker option since it's +impossible for LLVMC to choose the right linker in that case:
++$ llvmc2 -c hello.cpp +$ llvmc2 hello.o +[A lot of link-time errors skipped] +$ llvmc2 --linker=c++ hello.o +$ ./a.out +hello ++
LLVMC has some built-in options that can't be overridden in the +configuration files:
+-
+
At the time of writing LLVMC does not support on-the-fly reloading of +configuration, so to customize LLVMC you'll have to recompile the +source code (which lives under $LLVM_DIR/tools/llvmc2). The +default configuration files are Common.td (contains common +definitions, don't forget to include it in your configuration +files), Tools.td (tool descriptions) and Graph.td (compilation +graph definition).
+To compile LLVMC with your own configuration file (say,``MyGraph.td``), +run make like this:
++$ cd $LLVM_DIR/tools/llvmc2 +$ make GRAPH=MyGraph.td TOOLNAME=my_llvmc ++
This will build an executable named my_llvmc. There are also +several sample configuration files in the llvmc2/examples +subdirectory that should help to get you started.
+Internally, LLVMC stores information about possible source +transformations in form of a graph. Nodes in this graph represent +tools, and edges between two nodes represent a transformation path. A +special "root" node is used to mark entry points for the +transformations. LLVMC also assigns a weight to each edge (more on +this later) to choose between several alternative edges.
+The definition of the compilation graph (see file Graph.td) is +just a list of edges:
++def CompilationGraph : CompilationGraph<[ + Edge<root, llvm_gcc_c>, + Edge<root, llvm_gcc_assembler>, + ... + + Edge<llvm_gcc_c, llc>, + Edge<llvm_gcc_cpp, llc>, + ... + + OptionalEdge<llvm_gcc_c, opt, [(switch_on "opt")]>, + OptionalEdge<llvm_gcc_cpp, opt, [(switch_on "opt")]>, + ... + + OptionalEdge<llvm_gcc_assembler, llvm_gcc_cpp_linker, + (case (input_languages_contain "c++"), (inc_weight), + (or (parameter_equals "linker", "g++"), + (parameter_equals "linker", "c++")), (inc_weight))>, + ... + + ]>; ++
As you can see, the edges can be either default or optional, where +optional edges are differentiated by sporting a case expression +used to calculate the edge's weight.
+The default edges are assigned a weight of 1, and optional edges get a +weight of 0 + 2*N where N is the number of tests that evaluated to +true in the case expression. It is also possible to provide an +integer parameter to inc_weight and dec_weight - in this case, +the weight is increased (or decreased) by the provided value instead +of the default 2.
+When passing an input file through the graph, LLVMC picks the edge +with the maximum weight. To avoid ambiguity, there should be only one +default edge between two nodes (with the exception of the root node, +which gets a special treatment - there you are allowed to specify one +default edge per language).
+To get a visual representation of the compilation graph (useful for +debugging), run llvmc2 --view-graph. You will need dot and +gsview installed for this to work properly.
+As was said earlier, nodes in the compilation graph represent tools, +which are described separately. A tool definition looks like this +(taken from the Tools.td file):
++def llvm_gcc_cpp : Tool<[ + (in_language "c++"), + (out_language "llvm-assembler"), + (output_suffix "bc"), + (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"), + (sink) + ]>; ++
This defines a new tool called llvm_gcc_cpp, which is an alias for +llvm-g++. As you can see, a tool definition is just a list of +properties; most of them should be self-explanatory. The sink +property means that this tool should be passed all command-line +options that lack explicit descriptions.
+The complete list of the currently implemented tool properties follows:
+-
+
The next tool definition is slightly more complex:
++def llvm_gcc_linker : Tool<[ + (in_language "object-code"), + (out_language "executable"), + (output_suffix "out"), + (cmd_line "llvm-gcc $INFILE -o $OUTFILE"), + (join), + (prefix_list_option "L", (forward), + (help "add a directory to link path")), + (prefix_list_option "l", (forward), + (help "search a library when linking")), + (prefix_list_option "Wl", (unpack_values), + (help "pass options to linker")) + ]>; ++
This tool has a "join" property, which means that it behaves like a +linker. This tool also defines several command-line options: -l, +-L and -Wl which have their usual meaning. An option has two +attributes: a name and a (possibly empty) list of properties. All +currently implemented option types and properties are described below:
+-
+
It can be handy to have all information about options gathered in a +single place to provide an overview. This can be achieved by using a +so-called OptionList:
++def Options : OptionList<[ +(switch_option "E", (help "Help string")), +(alias_option "quiet", "q") +... +]>; ++
OptionList is also a good place to specify option aliases.
+Tool-specific option properties like append_cmd have (obviously) +no meaning in the context of OptionList, so the only properties +allowed there are help and required.
+Option lists are used at the file scope. See file +examples/Clang.td for an example of OptionList usage.
+Normally, LLVMC executes programs from the system PATH. Sometimes, +this is not sufficient: for example, we may want to specify tool names +in the configuration file. This can be achieved via the mechanism of +hooks - to compile LLVMC with your hooks, just drop a .cpp file into +tools/llvmc2 directory. Hooks should live in the hooks +namespace and have the signature std::string hooks::MyHookName +(void). They can be used from the cmd_line tool property:
++(cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)") ++
It is also possible to use environment variables in the same manner:
++(cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)") ++
To change the command line string based on user-provided options use +the case expression (documented below):
++(cmd_line + (case + (switch_on "E"), + "llvm-g++ -E -x c $INFILE -o $OUTFILE", + (default), + "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) ++
The 'case' construct can be used to calculate weights of the optional +edges and to choose between several alternative command line strings +in the cmd_line tool property. It is designed after the +similarly-named construct in functional languages and takes the form +(case (test_1), statement_1, (test_2), statement_2, ... (test_N), +statement_N). The statements are evaluated only if the corresponding +tests evaluate to true.
+Examples:
++// Increases edge weight by 5 if "-A" is provided on the +// command-line, and by 5 more if "-B" is also provided. +(case + (switch_on "A"), (inc_weight 5), + (switch_on "B"), (inc_weight 5)) + +// Evaluates to "cmdline1" if option "-A" is provided on the +// command line, otherwise to "cmdline2" +(case + (switch_on "A"), "cmdline1", + (switch_on "B"), "cmdline2", + (default), "cmdline3") ++
Note the slight difference in 'case' expression handling in contexts +of edge weights and command line specification - in the second example +the value of the "B" switch is never checked when switch "A" is +enabled, and the whole expression always evaluates to "cmdline1" in +that case.
+Case expressions can also be nested, i.e. the following is legal:
++(case (switch_on "E"), (case (switch_on "o"), ..., (default), ...) + (default), ...) ++
You should, however, try to avoid doing that because it hurts +readability. It is usually better to split tool descriptions and/or +use TableGen inheritance instead.
+-
+
One last thing that you will need to modify when adding support for a +new language to LLVMC is the language map, which defines mappings from +file extensions to language names. It is used to choose the proper +toolchain(s) for a given input file set. Language map definition is +located in the file Tools.td and looks like this:
++def LanguageMap : LanguageMap< + [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, + LangToSuffixes<"c", ["c"]>, + ... + ]>; ++
| [1] | TableGen Fundamentals +http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html |
+ +
+ + Last modified: $Date$ - Modified: llvm/branches/release_23/docs/LangRef.html URL: http://llvm.org/viewvc/llvm-project/llvm/branches/release_23/docs/LangRef.html?rev=52125&r1=52124&r2=52125&view=diff ============================================================================== --- llvm/branches/release_23/docs/LangRef.html (original) +++ llvm/branches/release_23/docs/LangRef.html Mon Jun 9 01:11:58 2008 @@ -578,9 +578,11 @@ (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. Implementations of - this convention should allow arbitrary tail call optimization to be supported. - This calling convention does not support varargs and requires the prototype of - all callees to exactly match the prototype of the function definition. + this convention should allow arbitrary + tail call optimization to be + supported. This calling convention does not support varargs and requires the + prototype of all callees to exactly match the prototype of the function + definition.
The main features of llvmc2 are: +
The main features of llvmc2 are:
- Extended handling of command line options and smart rules for dispatching them to different tools. @@ -246,8 +246,8 @@ it's relatively easy to add new features.
- The definition of driver is transformed into set of C++ classes, thus no runtime interpretation is needed. -
LLVM 2.3 includes a completely rewritten interface for Link Time Optimization. This interface @@ -285,7 +285,7 @@
-svn co http://llvm.org/svn/llvm-project/vmkit/trunk vmkit -
+svn co http://llvm.org/svn/llvm-project/vmkit/trunk vmkit+
for (i = LB; i < UB; ++i)
if (i <= NV)
LOOP_BODY
+is transformed into:
+NUB = min(NV+1, UB) for (i = LB; i < NUB; ++i) LOOP_BODY+
-
+
- Introduction + +
- AliasAnalysis Class Overview + + + +
- Writing a new AliasAnalysis Implementation + + + +
- Using alias analysis results + + + +
- Existing alias analysis implementations and clients + + +
- Memory Dependence Analysis +
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.
+ +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.
+ +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.
+ +An Alias Analysis implementation can return one of three responses: + MustAlias, MayAlias, and NoAlias. The No and May alias results are obvious: if + the two pointers can never equal each other, return NoAlias, if they might, + return MayAlias.
+ +The MustAlias response is trickier though. In LLVM, the Must Alias response + may only be returned if the two memory objects are guaranteed to always start at + exactly the same location. If two memory objects overlap, but do not start at + the same location, return MayAlias.
+ +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 the two calls refer to disjoint + memory locations, 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 + accessed by CS2. Note that this relation is not commutative. Clients that use + this method should be predicated on the hasNoModRefInfoForCalls() + method, which indicates whether or not an analysis can provide mod/ref + information for function call pairs (most can not). If this predicate is false, + the client shouldn't waste analysis time querying the getModRefInfo + method many times.
+ ++ Several other tidbits of information are often collected by various alias + analysis implementations and can be put to good use by various clients. +
+ +The getMustAliases method returns all values that are known to + always must alias a pointer. This information can be provided in some cases for + important objects like the null pointer and global values. Knowing that a + pointer always points to a particular function allows indirect calls to be + turned into direct calls, for example.
+ +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.
+ +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 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.
+ +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:
+ +-
+
- If you require interprocedural analysis, it should be a + Pass. +
- If you are a function-local analysis, subclass FunctionPass. +
- If you don't need to look at the program at all, subclass + ImmutablePass. +
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.
+ +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;
+ }
+
+ 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.
+ +With only two special exceptions (the basicaa and no-aa + passes) every alias analysis pass chains to another alias analysis + implementation (for example, the user can specify "-basicaa -ds-aa + -anders-aa -licm" to get the maximum benefit from the three 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.
+ ++ 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 two 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. +
+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).
+ +There are several different ways to use alias analysis results. In order of + preference, these are...
+ +The load-vn pass uses alias analysis to provide value numbering + information for load instructions and pointer values. If your analysis + or transformation can be modeled in a form that uses value numbering + information, you don't have to do anything special to handle load instructions: + just use the load-vn pass, which uses alias analysis.
+ +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 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.
+ +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.
+ +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.
+ +This section lists the various implementations of the AliasAnalysis + interface. With the exception of the -no-aa and + -basicaa implementations, all of these chain to other alias analysis implementations.
+ +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 is the default LLVM alias analysis. It 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). +
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. GCSE) 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 -anders-aa pass implements the well-known "Andersen's algorithm" + for interprocedural alias analysis. This algorithm is a subset-based, + flow-insensitive, context-insensitive, and field-insensitive alias analysis that + is widely believed to be fairly precise. Unfortunately, this algorithm is also + O(N3). The LLVM implementation currently does not implement any of + the refinements (such as "online cycle elimination" or "offline variable + substitution") to improve its efficiency, so it can be quite slow in common + cases. +
+ +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 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 -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 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 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 -load-vn pass uses alias analysis to "value + number" loads and pointers values, which is used by the GCSE pass to + eliminate instructions. The -load-vn pass relies on alias information + and must-alias information. This combination of passes can make the following + transformations:
+ +-
+
- Redundant load instructions are eliminated. +
- Load instructions that follow a store to the same location are replaced with + the stored value ("store forwarding"). +
- Pointers values (e.g. formal arguments) that must-alias simpler expressions + (e.g. global variables or the null pointer) are replaced. Note that this + implements transformations like "virtual method resolution", turning indirect + calls into direct calls. +
These passes are useful for evaluating the various alias analysis + implementations. You can use them with commands like 'opt -anders-aa -ds-aa + -aa-eval foo.bc -disable-output -stats'.
+ +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 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 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).
+ +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.
+ ++ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/BitCodeFormat.html diff -c /dev/null llvm-www/releases/2.3/docs/BitCodeFormat.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/BitCodeFormat.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,653 ---- + + + + +
-
+
- Abstract +
- Overview +
- Bitstream Format
+
-
+
- Magic Numbers +
- Primitives +
- Abbreviation IDs +
- Blocks +
- Data Records +
- Abbreviations +
- Standard Blocks +
+ - LLVM IR Encoding
+
-
+
- Basics +
+
This document describes the LLVM bitstream file format and the encoding of + the LLVM IR into it.
+ ++ 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.
+ +This document first describes the LLVM bitstream format, then describes the + record structure used by LLVM IR files. +
+ ++ The bitstream format is literally a stream of bits, with a very simple + structure. This structure consists of the following concepts: +
+ +-
+
- A "magic number" that identifies the contents of + the stream. +
- Encoding primitives like variable bit-rate + integers. +
- Blocks, which define nested content. +
- Data Records, which describe entities within the + file. +
- Abbreviations, which specify compression optimizations for the file. +
Note that the llvm-bcanalyzer tool can be + used to dump and inspect arbitrary bitstreams, which is very useful for + understanding the encoding.
+ +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.
+ ++ 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 are encoded in two ways: either as Fixed + Width Integers or as Variable 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 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 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.
+ +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.
+ ++ 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 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 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 hierachical 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 they do 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: +
+ +-
+
- A current abbrev id width. This value starts at 2, and is set every time a + block record is entered. The block entry specifies the abbrev id width for + the body of the block. + +
- 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. + +
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, blockidvbr8, newabbrevlenvbr4, + <align32bits>, blocklen32]
+ ++ The ENTER_SUBBLOCK abbreviation ID specifies the start of a new block record. + The blockid value is encoded as a 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 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, <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 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 + there are multiple different ways to encode a record (with 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, codevbr6, numopsvbr6, + op0vbr6, op1vbr6, ...]
+ +An UNABBREV_RECORD provides a default fallback encoding, which is both + completely general and also 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. Since there are no + letters with value 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.
+ +[<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. +
+ ++ 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. Since the + abbreviations are stored in the bitstream itself, different streams of the same + format can contain different sets of abbreviations if the specific stream does + not need it. 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, 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 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).
+ +-
+
- 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. +
- Encoding info without data - [01, encoding3] + - Operand encodings that do not have extra data are just emitted as their code. + +
- Encoding info with data - [01, encoding3, + valuevbr5] - Operand encodings that do have extra data are + emitted as their code, followed by the extra data. + +
The possible operand encodings are:
+ +-
+
- 1 - Fixed - The field should be emitted as a fixed-width value, whose width + is specified by the operand's extra data. +
- 2 - VBR - The field should be emitted as a variable-width value, whose width + is specified by the operand's extra data. +
- 3 - Array - This field is an array of values. The array operand has no + extra data, but expects another operand to follow it which indicates 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). +
- 4 - Char6 - This field should be emitted as a char6-encoded + value. This operand type takes no extra data. +
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:
+ +-
+
- The first value, 4, is the abbreviation ID for this abbreviation. +
- The second value, 2, is the code for TRIPLE in LLVM IR files. +
- The third value, 4, is the length of the array. +
- The rest of the values are the char6 encoded values for "abcd". +
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, since the TRIPLE value is not + emitted as a literal in the abbreviation, the abbreviation can also be used for + any other string value. +
+ ++ In addition to the basic block structure and record encodings, the bitstream + also defines specific builtin 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. +
+ +The BLOCKINFO block allows the description of metadata for other blocks. The + currently specified records are:
+ +-
+
- [SETBID (#1), blockid] +
- [DEFINE_ABBREV, ...] +
+ The SETBID record 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. +
+ ++ 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. +
+ +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.
+ ++ 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".
+ ++ Variable Width Integers are an efficient way to + encode arbitrary sized unsigned values, but is an extremely inefficient way to + encode 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.
+ ++ 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. +
+
+ ++
+ + The LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/Bugpoint.html diff -c /dev/null llvm-www/releases/2.3/docs/Bugpoint.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/Bugpoint.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,244 ---- + + + +
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.
+ +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.
+ +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.
+ +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.
+ +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.
+ +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.
+ ++ +
-
+
- 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. + +
- 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. + +
- 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. + +
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.
+ +- 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. + +
- If your program is supposed to crash, bugpoint will be + confused. One way to deal with this is to cause bugpoint to ignore the exit + code from your program, by giving it the -check-exit-code=false + option. + +
- 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. + +
+ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/CFEBuildInstrs.html diff -c /dev/null llvm-www/releases/2.3/docs/CFEBuildInstrs.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CFEBuildInstrs.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,29 ---- + + + + + +
+ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/CodeGenerator.html diff -c /dev/null llvm-www/releases/2.3/docs/CodeGenerator.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CodeGenerator.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,2006 ---- + + + + +
-
+
- Introduction + + +
- Target description classes + + +
- Machine code description classes + + +
- Target-independent code generation algorithms
+
-
+
- Instruction Selection
+
-
+
- Introduction to SelectionDAGs +
- SelectionDAG Code Generation + Process +
- Initial SelectionDAG + Construction +
- SelectionDAG Legalize Phase +
- SelectionDAG Optimization + Phase: the DAG Combiner +
- SelectionDAG Select Phase +
- SelectionDAG Scheduling and Formation + Phase +
- Future directions for the + SelectionDAG +
+ - Live Intervals + +
- Register Allocation + +
- Code Emission + +
+ - Instruction Selection
+
- Target-specific Implementation Notes + + +
Warning: This is a work in progress.
+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 five main + components:
+ +-
+
- 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/. + +
- Classes used to represent the machine 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/. + +
- 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/. + +
- 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/. + +
- 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. + +
+ 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. +
+ +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 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:
+ +-
+
- 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. + +
- 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. + + +
- 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. + + +
- 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. + +
- 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. + +
- Late Machine Code Optimizations - Optimizations + that operate on "final" machine code can go here, such as spill code scheduling + and peephole optimizations. + +
- Code Emission - The final stage actually + puts out the code for the current function, either in the target assembler + format or in machine code. + +
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.
+ +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.
+ +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 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 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 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 +
- various high-level characteristics, like whether it is profitable to turn + division by a constant into a multiplication sequence +
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 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 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 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 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.
+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.
+ +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.
+ +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, MachineOperand::Def); ++
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:
+ +
+ int %test(int %X, int %Y) {
+ %Z = div int %X, %Y
+ ret int %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.
+ +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 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 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.
+ +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 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.
+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 SDOperand 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::ValueType indicating what type 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 phase is responsible for turning + an illegal DAG into a legal DAG.
+ +SelectionDAG-based instruction selection consists of the following steps:
+ +-
+
- Build initial DAG - This stage + performs a simple translation from the input LLVM code to an illegal + SelectionDAG. +
- 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. +
- Legalize SelectionDAG - This stage + converts the illegal SelectionDAG to a legal SelectionDAG by eliminating + unsupported operations and data types. +
- Optimize SelectionDAG (#2) - This + second run of the SelectionDAG optimizes the newly legalized DAG to + eliminate inefficiencies introduced by legalization. +
- 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. +
- 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. +
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. In particular, the -view-isel-dags + option pops up a window with the SelectionDAG input to the Select phase for all + of the code compiled (if you only get errors printed to the console while using + this, you probably need to configure + your system to add support for it). The -view-sched-dags option + views the SelectionDAG output from the Select phase and input to the Scheduler + phase. The -view-sunit-dags option views the ScheduleDAG, which is + based on the final SelectionDAG, with nodes that must be scheduled as a unit + bundled together into a single node, and with immediate operands and other + nodes that aren't relevent for scheduling omitted. +
+ +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 geteelementptr 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.
+ +The Legalize phase is in charge of converting a DAG to only use the types and + operations that are natively supported by the target. This involves two major + tasks:
+ +-
+
Convert values of unsupported types to values of supported types.
+There are two main ways of doing this: 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 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.
+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.
+
+
+ Eliminate operations that are not 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 existance of the Legalize pass, 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 phase allows all of the cannonicalization patterns to be shared + across targets, and makes it very easy to optimize the cannonicalized code + because it is still in the form of a DAG.
+ +The SelectionDAG optimization phase is run twice for code generation: once + immediately after the DAG is built and once after 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). The second run of the pass cleans up the messy code generated by the + Legalize pass, 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.
+
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 = add float %W, %X + %t2 = mul float %t1, %Y + %t3 = add 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 lib/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. ADD_PARTS, 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!
+ +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.
+ +-
+
- Optional function-at-a-time selection. +
- Auto-generate entire selector from .td file. +
To Be Written
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.
+ +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 encounted, 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.
+ +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...
+ +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.
+ +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/X86GenRegisterNames.inc we see that the 32-bit + register EAX is denoted by 15, and the MMX register + MM0 is mapped to 48.
+ +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 + TargetRegisterInfo::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 + GR register class in + lib/Target/IA64/IA64RegisterInfo.td for an example of this + (e.g., numReservedRegs registers are hidden.)
+ +Virtual registers are also denoted by integer numbers. Contrary to + physical registers, different virtual registers never share the same + number. The smallest virtual register is normally assigned the number + 1024. This may change, so, in order to know which is the first virtual + register, you should access + TargetRegisterInfo::FirstVirtualRegister. Any register whose + number is greater than or equal to + TargetRegisterInfo::FirstVirtualRegister is considered a virtual + register. 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 + virtual register with the highest code. +
+ +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 is been + overwritten by the values of virtual registers while still alive.
+ +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 + TargetRegisterInfo::storeRegToStackSlot(...), and to insert a load + instruction, use TargetRegisterInfo::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.
+ +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 %b ++
Notice that, internally, the second instruction is represented as + ADD %a[def/use] %b. I.e., the register operand %a is + both used and defined by the instruction.
+ +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 nlib/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 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.
+ +The LLVM infrastructure provides the application developer with + three different register allocators:
+ +-
+
- Simple - This is a very simple implementation that does + not keep values in registers across instructions. This register + allocator immediately spills every value right after it is + computed, and reloads all used operands from memory to temporary + registers before each instruction. +
- Local - This register allocator is an improvement on the + Simple implementation. It allocates registers on a basic + block level, attempting to keep values in registers and reusing + registers as appropriate. +
- Linear Scan - The default allocator. This is the + well-know linear scan register allocator. Whereas the + Simple and Local algorithms use a direct mapping + implementation technique, the Linear Scan implementation + uses a spiller in order to place load and stores. +
The type of register allocator used in llc can be chosen with the + command line option -regalloc=...:
+ ++ $ llc -f -regalloc=simple file.bc -o sp.s; + $ llc -f -regalloc=local file.bc -o lc.s; + $ llc -f -regalloc=linearscan file.bc -o ln.s; ++
To Be Written
To Be Written
To Be Written
To Be Written
For the JIT or .o file writer
+This section of the document explains features or design decisions that + are specific to the code generator for a particular target.
+ +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. +
- 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.
+On x86 and x86-64 one register is reserved for indirect tail calls (e.g via a function pointer). So there is one less register for integer argument passing. For x86 this means 2 registers (if inreg parameter attribute is used) and for x86-64 this means 5 register are used.
+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. +
+ +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 +
The folowing 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). +
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):
+ ++ Base + [1,2,4,8] * IndexReg + Disp32 ++
In order to represent this, LLVM tracks no less than 4 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 + Meaning: DestReg, | BaseReg, Scale, IndexReg, Displacement + OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm ++ +
Stores, and all other instructions, treat the four memory operands in the + same way and in the same order.
+ +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 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 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.
+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 layed 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
+| 0 | +Saved SP (r1) | +
| 4 | +Saved CR | +
| 8 | +Saved LR | +
| 12 | +Reserved | +
| 16 | +Reserved | +
| 20 | +Saved FP (r31) | +
64 bit linkage area
+| 0 | +Saved SP (r1) | +
| 8 | +Saved CR | +
| 16 | +Saved LR | +
| 24 | +Reserved | +
| 32 | +Reserved | +
| 40 | +Saved 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 mimimally 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 aligment.
+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.
+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.
+TODO - More to come.
++ +
+ + The LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/CodingStandards.html diff -c /dev/null llvm-www/releases/2.3/docs/CodingStandards.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CodingStandards.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,767 ---- + + + + +
-
+
- Introduction +
- Mechanical Source Issues + +
- Style Issues
+
-
+
- The High Level Issues + +
- The Low Level Issues + +
+ - See Also +
This document attempts to describe a few coding standards that are being used + in the LLVM source tree. Although no coding standards should be regarded as + absolute requirements to be followed in all instances, coding standards can be + useful.
+ +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:
+ ++ + + ++ +
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.
+ +Comments are one critical part of readability and maintainability. Everyone + knows they should comment, so should you. Although we all should probably + comment our code more than we do, there are a few very critical places that + documentation is very useful:
+ + 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 Subversion. Most source trees will probably have a standard + file header format. The standard format for the LLVM source tree 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... if it's not obvious. If it's so completely obvious your grandma + could figure it out, it's probably safe to leave it out. Naming classes + something sane goes a long ways towards avoiding writing documentation.
+ + + 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 any a description of the + borderline behaviour is all that is necessary here (unless something + particularly tricky or insideous is going on). The hope is that people can + figure out how to use your interfaces without reading the code itself... that is + the goal metric.
+ +Good things to talk about here are what happens when something unexpected + happens: does the method return null? Abort? Format your hard disk?
+ +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:
+ +-
+
- When writing a C code: Obviously if you are writing C code, use C style + comments. +
- When writing a header file that may be #included by a C source + file. +
- When writing a source file that is used by a tool that only accepts C + style comments. +
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.
+ +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:
+ +-
+
- Main Module header +
- Local/Private Headers +
- llvm/* +
- llvm/Analysis/* +
- llvm/Assembly/* +
- llvm/Bytecode/* +
- llvm/CodeGen/* +
- ... +
- Support/* +
- Config/* +
- System #includes +
... and each catagory should be sorted by name.
+ +The "Main Module Header" file applies to .cpp file + 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.
+ +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.
+ +In all cases, prefer spaces to tabs in source files. People have different + prefered indentation levels, and different styles of indentation that they + like... this is fine. What isn't is that different editors/viewers expand tabs + out to different tab stops. This can cause your code to look completely + unreadable, and it is not worth dealing with.
+ +As always, follow the Golden Rule above: follow the + style of existing code if your 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.
+ +Okay, 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.
+ +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 them. 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, an 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.
+ +These are the gcc warnings that I prefer to enable: -Wall + -Winline -W -Wwrite-strings -Wno-unused
+ +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, including its support for "high tech" features like partial + specialization of templates. In fact, Visual C++ 6 could be an important target + for our work in the future, and we don't want to have to rewrite all of our code + to support it.
+ +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, in which case struct is allowed.
+ +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 with one or more .cpp + files. Each of these .cpp files should include the header that defines + their interface first. This ensure 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 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 + accidently 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...
+ +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 a public + class itself... just make them private (or protected), and all is well.
+ +The use of #include <iostream> in library files is + hereby forbidden. The primary reason for doing this is to + support clients using LLVM libraries as part of larger systems. In particular, + we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, + the static c'tors are run whenever an application start up that uses the dynamic + library. There are two problems with this:
+ +-
+
- The time to run the static c'tors impacts startup time of + applications—a critical time for GUI apps. +
- The static c'tors cause the app to pull many extra pages of memory off the + disk: both the code for the static c'tors in each .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. +
| Old Way | +New Way | +
|---|---|
#include <iostream> |
+ #include "llvm/Support/Streams.h" |
+
DEBUG(std::cerr << ...); + DEBUG(dump(std::cerr)); |
+ DOUT << ...; + DEBUG(dump(DOUT)); |
+
std::cerr << "Hello world\n"; |
+ llvm::cerr << "Hello world\n"; |
+
std::cout << "Hello world\n"; |
+ llvm::cout << "Hello world\n"; |
+
std::cin >> Var; |
+ llvm::cin >> Var; |
+
std::ostream |
+ llvm::OStream |
+
std::istream |
+ llvm::IStream |
+
std::stringstream |
+ llvm::StringStream |
+
void print(std::ostream &Out); + // ... + print(std::cerr); |
+ void print(llvm::OStream Out);1 + // ... + print(llvm::cerr);+ + |
1llvm::OStream is a light-weight class so it should never + be passed by reference. This is important because in some configurations, + DOUT is an rvalue.
+Use the "assert" function to its fullest. Check all of your + preconditions and assumptions, you never know when a bug (not neccesarily 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 debugging 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 some 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...
+ +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 their top, after the #includes. 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.
+ +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. +
+ +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.
+ +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'.
+ +A lot of these comments and recommendations have been culled for other + sources. Two particularly important books for our work are:
+ +-
+
+
- Effective + C++ by Scott Meyers. Also + interesting and useful are "More Effective C++" and "Effective STL" by the same + author. + +
- Large-Scale C++ Software Design by John Lakos + +
If you get some free time, and you haven't read them: do so, you might learn + something.
+ ++ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/CommandLine.html diff -c /dev/null llvm-www/releases/2.3/docs/CommandLine.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CommandLine.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,1970 ---- + + + + +
-
+
- Introduction + +
- Quick Start Guide + + +
- Reference Guide
+
-
+
- Positional Arguments + + +
- Internal vs External Storage + +
- Option Attributes + +
- Option Modifiers + + +
- Top-Level Classes and Functions + + +
- Builtin parsers + +
+ - Extension Guide + +
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:
+ +-
+
- 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). + +
- 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. + +
- 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. + +
- 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. + +
- 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. + +
- 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... + +
- 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. + +
- 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. + +
- 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. + +
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.
+ +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.
+ +In addition to input and output filenames, we would like the compiler example + to support three boolean flags: "-f" to force overwriting of the output + file, "--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("Overwrite output files")); + 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 - Overwrite output files + -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 - Overwrite output files + -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.
+ +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.
+ +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:
+ +-
+
- 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. + +
- We would have to test 4 different variables to see which ones are set. + +
- This doesn't map to the numeric levels that we want... so we cannot easily + see if some level >= "-O1" is enabled. + +
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 - Overwrite output files + -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.
+ +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 - Overwrite output files + -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.
+ +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.
+ +Instead of collecting sets of options in a list, it is also possible to + gather information for enum values in a bit vector. The represention 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.
+ +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 +
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 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.
+ +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... +
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 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.
+ +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 accessable (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.
+ +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 + inital 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:
+
+
-
+
+
- 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. + +
- 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. + +
+
+
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 catagories:
+ +-
+
- Hiding an option from --help output +
- Controlling the number of occurrences + required and allowed +
- Controlling whether or not a value must be + specified +
- Controlling other formatting options +
- Miscellaneous option modifiers +
It is not possible to specify two options from the same catagory (you'll get + a runtime error) to a single option, except for options in the miscellaneous + catagory. 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.
+ +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. + +
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.
+ +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.
+ +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:
+ +-
+
- string input = OrigInput; +
- if (isOption(input)) return getOption(input).parse(); // Normal option +
- while (!isOption(input) && !input.empty()) input.pop_back(); // Remove the last letter +
- if (input.empty()) return error(); // No matching option +
- if (getOption(input).isPrefix())
+ return getOption(input).parse(input); + - 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();
+ } + - if (!OrigInput.empty()) error(); +
}
+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.
+ +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. +
+ +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 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 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 reponse 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 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 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 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 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 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 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");
+ 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. + + +
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.
+ +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:
+ +-
+
+
-
+
+
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.
+ +
+
+ -
+
+
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.
+ +
+
+
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.
+ +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
+ +TODO: fill in this section
+ ++ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/CompilerDriver.html diff -c /dev/null llvm-www/releases/2.3/docs/CompilerDriver.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CompilerDriver.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,420 ---- + + + + + + +
Note: This document is a work-in-progress. Additions and clarifications + are welcome.
+LLVMC is a generic compiler driver, designed to be customizable and + extensible. It plays the same role for LLVM as the gcc program + does for GCC - LLVMC's job is essentially to transform a set of input + files into a set of targets depending on configuration rules and user + options. What makes LLVMC different is that these transformation rules + are completely customizable - in fact, LLVMC knows nothing about the + specifics of transformation (even the command-line options are mostly + not hard-coded) and regards the transformation structure as an + abstract graph. This makes it possible to adapt LLVMC for other + purposes - for example, as a build tool for game resources.
+Because LLVMC employs TableGen [1] as its configuration language, you + need to be familiar with it to customize LLVMC.
+-
+
- Compiling with LLVMC +
- Predefined options +
- Customizing LLVMC: the compilation graph +
- Writing a tool description +
- Option list - specifying all options in a single place +
- Using hooks and environment variables in the cmd_line property +
- Conditional evaluation: the case expression +
- Language map +
- References +
LLVMC tries hard to be as compatible with gcc as possible, + although there are some small differences. Most of the time, however, + you shouldn't be able to notice them:
++ $ # This works as expected: + $ llvmc2 -O3 -Wall hello.cpp + $ ./a.out + hello ++
One nice feature of LLVMC is that one doesn't have to distinguish + between different compilers for different languages (think g++ and + gcc) - the right toolchain is chosen automatically based on input + language names (which are, in turn, determined from file + extensions). If you want to force files ending with ".c" to compile as + C++, use the -x option, just like you would do it with gcc:
++ $ llvmc2 -x c hello.cpp + $ # hello.cpp is really a C file + $ ./a.out + hello ++
On the other hand, when using LLVMC as a linker to combine several C++ + object files you should provide the --linker option since it's + impossible for LLVMC to choose the right linker in that case:
++ $ llvmc2 -c hello.cpp + $ llvmc2 hello.o + [A lot of link-time errors skipped] + $ llvmc2 --linker=c++ hello.o + $ ./a.out + hello ++
LLVMC has some built-in options that can't be overridden in the + configuration files:
+-
+
- -o FILE - Output file name. +
- -x LANGUAGE - Specify the language of the following input files + until the next -x option. +
- -v - Enable verbose mode, i.e. print out all executed commands. +
- --view-graph - Show a graphical representation of the compilation + graph. Requires that you have dot and gv commands + installed. Hidden option, useful for debugging. +
- --write-graph - Write a compilation-graph.dot file in the + current directory with the compilation graph description in the + Graphviz format. Hidden option, useful for debugging. +
- --save-temps - Write temporary files to the current directory + and do not delete them on exit. Hidden option, useful for debugging. +
- --help, --help-hidden, --version - These options have + their standard meaning. +
At the time of writing LLVMC does not support on-the-fly reloading of + configuration, so to customize LLVMC you'll have to recompile the + source code (which lives under $LLVM_DIR/tools/llvmc2). The + default configuration files are Common.td (contains common + definitions, don't forget to include it in your configuration + files), Tools.td (tool descriptions) and Graph.td (compilation + graph definition).
+To compile LLVMC with your own configuration file (say,``MyGraph.td``), + run make like this:
++ $ cd $LLVM_DIR/tools/llvmc2 + $ make GRAPH=MyGraph.td TOOLNAME=my_llvmc ++
This will build an executable named my_llvmc. There are also + several sample configuration files in the llvmc2/examples + subdirectory that should help to get you started.
+Internally, LLVMC stores information about possible source + transformations in form of a graph. Nodes in this graph represent + tools, and edges between two nodes represent a transformation path. A + special "root" node is used to mark entry points for the + transformations. LLVMC also assigns a weight to each edge (more on + this later) to choose between several alternative edges.
+The definition of the compilation graph (see file Graph.td) is + just a list of edges:
++ def CompilationGraph : CompilationGraph<[ + Edge<root, llvm_gcc_c>, + Edge<root, llvm_gcc_assembler>, + ... + + Edge<llvm_gcc_c, llc>, + Edge<llvm_gcc_cpp, llc>, + ... + + OptionalEdge<llvm_gcc_c, opt, [(switch_on "opt")]>, + OptionalEdge<llvm_gcc_cpp, opt, [(switch_on "opt")]>, + ... + + OptionalEdge<llvm_gcc_assembler, llvm_gcc_cpp_linker, + (case (input_languages_contain "c++"), (inc_weight), + (or (parameter_equals "linker", "g++"), + (parameter_equals "linker", "c++")), (inc_weight))>, + ... + + ]>; ++
As you can see, the edges can be either default or optional, where + optional edges are differentiated by sporting a case expression + used to calculate the edge's weight.
+The default edges are assigned a weight of 1, and optional edges get a + weight of 0 + 2*N where N is the number of tests that evaluated to + true in the case expression. It is also possible to provide an + integer parameter to inc_weight and dec_weight - in this case, + the weight is increased (or decreased) by the provided value instead + of the default 2.
+When passing an input file through the graph, LLVMC picks the edge + with the maximum weight. To avoid ambiguity, there should be only one + default edge between two nodes (with the exception of the root node, + which gets a special treatment - there you are allowed to specify one + default edge per language).
+To get a visual representation of the compilation graph (useful for + debugging), run llvmc2 --view-graph. You will need dot and + gsview installed for this to work properly.
+As was said earlier, nodes in the compilation graph represent tools, + which are described separately. A tool definition looks like this + (taken from the Tools.td file):
++ def llvm_gcc_cpp : Tool<[ + (in_language "c++"), + (out_language "llvm-assembler"), + (output_suffix "bc"), + (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"), + (sink) + ]>; ++
This defines a new tool called llvm_gcc_cpp, which is an alias for + llvm-g++. As you can see, a tool definition is just a list of + properties; most of them should be self-explanatory. The sink + property means that this tool should be passed all command-line + options that lack explicit descriptions.
+The complete list of the currently implemented tool properties follows:
+-
+
- Possible tool properties:
-
+
- in_language - input language name. +
- out_language - output language name. +
- output_suffix - output file suffix. +
- cmd_line - the actual command used to run the tool. You can + use $INFILE and $OUTFILE variables, output redirection + with >, hook invocations ($CALL), environment variables + (via $ENV) and the case construct (more on this below). +
- join - this tool is a "join node" in the graph, i.e. it gets a + list of input files and joins them together. Used for linkers. +
- sink - all command-line options that are not handled by other + tools are passed to this tool. +
+
The next tool definition is slightly more complex:
++ def llvm_gcc_linker : Tool<[ + (in_language "object-code"), + (out_language "executable"), + (output_suffix "out"), + (cmd_line "llvm-gcc $INFILE -o $OUTFILE"), + (join), + (prefix_list_option "L", (forward), + (help "add a directory to link path")), + (prefix_list_option "l", (forward), + (help "search a library when linking")), + (prefix_list_option "Wl", (unpack_values), + (help "pass options to linker")) + ]>; ++
This tool has a "join" property, which means that it behaves like a + linker. This tool also defines several command-line options: -l, + -L and -Wl which have their usual meaning. An option has two + attributes: a name and a (possibly empty) list of properties. All + currently implemented option types and properties are described below:
+-
+
Possible option types:
++
+-
+
- switch_option - a simple boolean switch, for example -time. +
- parameter_option - option that takes an argument, for example + -std=c99; +
- parameter_list_option - same as the above, but more than one + occurence of the option is allowed. +
- prefix_option - same as the parameter_option, but the option name + and parameter value are not separated. +
- prefix_list_option - same as the above, but more than one + occurence of the option is allowed; example: -lm -lpthread. +
- alias_option - a special option type for creating + aliases. Unlike other option types, aliases are not allowed to + have any properties besides the aliased option name. Usage + example: (alias_option "preprocess", "E") +
+ Possible option properties:
++
+-
+
- append_cmd - append a string to the tool invocation command. +
- forward - forward this option unchanged. +
- output_suffix - modify the output suffix of this + tool. Example : (switch "E", (output_suffix "i"). +
- stop_compilation - stop compilation after this phase. +
- unpack_values - used for for splitting and forwarding + comma-separated lists of options, e.g. -Wa,-foo=bar,-baz is + converted to -foo=bar -baz and appended to the tool invocation + command. +
- help - help string associated with this option. Used for + --help output. +
- required - this option is obligatory. +
+
It can be handy to have all information about options gathered in a + single place to provide an overview. This can be achieved by using a + so-called OptionList:
++ def Options : OptionList<[ + (switch_option "E", (help "Help string")), + (alias_option "quiet", "q") + ... + ]>; ++
OptionList is also a good place to specify option aliases.
+Tool-specific option properties like append_cmd have (obviously) + no meaning in the context of OptionList, so the only properties + allowed there are help and required.
+Option lists are used at the file scope. See file + examples/Clang.td for an example of OptionList usage.
+Normally, LLVMC executes programs from the system PATH. Sometimes, + this is not sufficient: for example, we may want to specify tool names + in the configuration file. This can be achieved via the mechanism of + hooks - to compile LLVMC with your hooks, just drop a .cpp file into + tools/llvmc2 directory. Hooks should live in the hooks + namespace and have the signature std::string hooks::MyHookName + (void). They can be used from the cmd_line tool property:
++ (cmd_line "$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)") ++
It is also possible to use environment variables in the same manner:
++ (cmd_line "$ENV(VAR1)/path/to/file -o $ENV(VAR2)") ++
To change the command line string based on user-provided options use + the case expression (documented below):
++ (cmd_line + (case + (switch_on "E"), + "llvm-g++ -E -x c $INFILE -o $OUTFILE", + (default), + "llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm")) ++
The 'case' construct can be used to calculate weights of the optional + edges and to choose between several alternative command line strings + in the cmd_line tool property. It is designed after the + similarly-named construct in functional languages and takes the form + (case (test_1), statement_1, (test_2), statement_2, ... (test_N), + statement_N). The statements are evaluated only if the corresponding + tests evaluate to true.
+Examples:
++ // Increases edge weight by 5 if "-A" is provided on the + // command-line, and by 5 more if "-B" is also provided. + (case + (switch_on "A"), (inc_weight 5), + (switch_on "B"), (inc_weight 5)) + + // Evaluates to "cmdline1" if option "-A" is provided on the + // command line, otherwise to "cmdline2" + (case + (switch_on "A"), "cmdline1", + (switch_on "B"), "cmdline2", + (default), "cmdline3") ++
Note the slight difference in 'case' expression handling in contexts + of edge weights and command line specification - in the second example + the value of the "B" switch is never checked when switch "A" is + enabled, and the whole expression always evaluates to "cmdline1" in + that case.
+Case expressions can also be nested, i.e. the following is legal:
++ (case (switch_on "E"), (case (switch_on "o"), ..., (default), ...) + (default), ...) ++
You should, however, try to avoid doing that because it hurts + readability. It is usually better to split tool descriptions and/or + use TableGen inheritance instead.
+-
+
- Possible tests are:
-
+
- switch_on - Returns true if a given command-line option is + provided by the user. Example: (switch_on "opt"). Note that + you have to define all possible command-line options separately in + the tool descriptions. See the next doc_text for the discussion of + different kinds of command-line options. +
- parameter_equals - Returns true if a command-line parameter equals + a given value. Example: (parameter_equals "W", "all"). +
- element_in_list - Returns true if a command-line parameter list + includes a given value. Example: (parameter_in_list "l", "pthread"). +
- input_languages_contain - Returns true if a given language + belongs to the current input language set. Example: + `(input_languages_contain "c++"). +
- in_language - Evaluates to true if the language of the input + file equals to the argument. Valid only when using case + expression in a cmd_line tool property. Example: + `(in_language "c++"). +
- not_empty - Returns true if a given option (which should be + either a parameter or a parameter list) is set by the + user. Example: `(not_empty "o"). +
- default - Always evaluates to true. Should always be the last + test in the case expression. +
- and - A standard logical combinator that returns true iff all + of its arguments return true. Used like this: (and (test1), + (test2), ... (testN)). Nesting of and and or is allowed, + but not encouraged. +
- or - Another logical combinator that returns true only if any + one of its arguments returns true. Example: (or (test1), + (test2), ... (testN)). +
+
One last thing that you will need to modify when adding support for a + new language to LLVMC is the language map, which defines mappings from + file extensions to language names. It is used to choose the proper + toolchain(s) for a given input file set. Language map definition is + located in the file Tools.td and looks like this:
++ def LanguageMap : LanguageMap< + [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>, + LangToSuffixes<"c", ["c"]>, + ... + ]>; ++
| [1] | TableGen Fundamentals + http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html |
+ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/CompilerWriterInfo.html diff -c /dev/null llvm-www/releases/2.3/docs/CompilerWriterInfo.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/CompilerWriterInfo.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,261 ---- + + + + +
Note: This document is a work-in-progress. Additions and clarifications + are welcome.
+-
+
- Alpha manuals + +
-
+
- ARM documentation + (Processor + Cores) +
- ABI +
-
+
- Itanium documentation + +
-
+
- PowerPC
+ Architecture Book
+
-
+
- Book I: PowerPC + User Instruction Set Architecture +
- Book II: PowerPC + Virtual Environment Architecture +
- Book III: PowerPC + Operating Environment Architecture +
+ - PowerPC + Compiler Writer's Guide +
- PowerPC + Processor Manuals +
- Intro to + PowerPC architecture +
- IBM AIX/5L for POWER Assembly reference +
-
+
- GCC reading list +
-
+
- Executable + File Format library +
- GCC prefetch project + page has a good survey of the prefetching capabilities of a variety of modern + processors. +
+ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/DeveloperPolicy.html diff -c /dev/null llvm-www/releases/2.3/docs/DeveloperPolicy.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/DeveloperPolicy.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,555 ---- + + + +
-
+
- Introduction +
- Developer Policies + +
- Copyright, License, and Patents
+
-
+
- Copyright +
- License +
- Patents +
- Developer Agreements +
+
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 mis-communication, 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 is also designed to accomplish the following objectives:
+-
+
- Attract both users and developers to the LLVM project. +
- Make life as simple and easy for contributors as possible. +
- Keep the top of Subversion trees as stable as possible. +
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.
+ +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.
+
Developers should stay informed by reading at least the + llvmdev + email list. If you are doing anything more than just casual work on LLVM, + it is suggested that you also subscribe to the + llvm-commits + list and pay attention to changes being made by others.
+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.
+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:
+-
+
- 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. + +
- 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. + +
- Patches should be made with this command:
+
svn diff -x -u
+ or with the utility utils/mkpatch, which makes it easy to read the + diff.
+
+ - Patches should not include differences in generated code such as the + code generated by flex, bison or tblgen. The + utils/mkpatch utility takes care of this for you. + +
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).
+LLVM has a code review policy. Code review is one way to increase the + quality of software. We generally follow these policies:
+-
+
- All developers are required to have significant changes reviewed + before they are committed to the repository. +
- Code reviews are conducted by email, usually on the llvm-commits + list. +
- 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. +
- The developer responsible for a code change is also responsible for + making all necessary review-related changes. +
- Code review can be an iterative process, which continues until the patch + is ready to be committed. +
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.
+ +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:
+ +-
+
- Anton Korobeynikov: Exception handling, debug information, and + Windows codegen. +
- Duncan Sands: llvm-gcc 4.2. +
- Evan Cheng: Code generator and all targets. +
- Chris Lattner: Everything else. +
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. +
+ +Developers are required to create test cases for any bugs fixed and any new + features added. Some tips for getting your testcase approved:
+-
+
- 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). +
- 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++). +
- 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. +
Note that llvm/test is 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.
+The minimum quality standards that any change must satisfy before being + committed to the main development branch are:
+-
+
- Code must adhere to the + LLVM Coding Standards. +
- Code must compile cleanly (no errors, no warnings) on at least one + platform. +
- Bug fixes and new features should include a + testcase so we know if the fix/feature ever regresses in the + future. +
- Code must pass the dejagnu (llvm/test) test suite. +
- 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 is "llvm-test/MultiSource/Benchmarks". +
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 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.
+ +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.
++ 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:
+ +-
+
- The user name you want to commit with, e.g. "sabre". +
- The full name and email address you want message to llvm-commits to come + from, e.g. "Chris Lattner <sabre at nondot.org>". +
- 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. +
Once you've been granted commit access, you should be able to check out an + LLVM tree with an SVN URL of "https://username at 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:
+ +-
+
- 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. +
- 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. +
- 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. +
- Multiple violations of these policies or a single egregious violation + may cause commit access to be revoked. +
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.
+ +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: +
-
+
- keep the community informed about future changes to LLVM, +
- avoid duplication of effort by preventing multiple parties working on + the same thing and not knowing about it, and +
- ensure that any technical issues around the proposed work are + discussed and resolved before any significant work is done. +
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.
+ +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:
+ +-
+
- 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. +
- Other people in the community tend to ignore work on branches. +
- Huge changes (produced when a branch is merged back onto mainline) are + extremely difficult to code review. +
- Branches are not routinely tested by our nightly tester + infrastructure. +
- 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. +
+ 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.
+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 Guy" (this is noisy + and distracting. In practice, the revision control system keeps a perfect + history of who change what, and the CREDITS.txt file describes higher-level + contributions.
+ +Overall, please do not add contributor names to the source base.
+This section addresses the issues of copyright, license and patents for + the LLVM project. + Currently, the University of Illinois is the LLVM copyright holder and the + terms of its license to LLVM users and developers is the + University of + Illinois/NCSA Open Source License.
+ +NOTE: This section deals with legal matters but does not provide + legal advice. We are not lawyers, please seek legal counsel from an + attorney.
++
For consistency and ease of management, the project requires the + copyright for all LLVM software to be held by a single copyright holder: + the University of Illinois (UIUC).
+ ++ Although UIUC may eventually reassign the copyright of the software to another + entity (e.g. a dedicated non-profit "LLVM Organization", or something) + the intent for the project is to always have a single entity hold the + copyrights to LLVM at any given time.
+ +We believe that having a single copyright + holder is in the best interests of all developers and users as it greatly + reduces the managerial burden for any kind of administrative or technical + decisions about LLVM. The goal of the LLVM project is to always keep the code + open and licensed under a very liberal license.
+We intend to keep LLVM perpetually open source + and to use a liberal open source license. The current license is 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. +
- 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.
+ +Note that the LLVM Project does distribute llvm-gcc, which is 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 does not affect code generated by llvm-gcc. It may be a + problem if you intend to base commercial development on llvm-gcc without + redistributing your source code.
+ +We have no plans to change the license of LLVM. If you have questions + or comments about the license, please contact the LLVM Oversight Group.
+ +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. If you own the rights to a + patent and would like to contribute code to LLVM that relies on it, we + require that you sign an agreement that allows any other user of LLVM to + freely use your patent. Please contact the oversight group for more + details.
+With regards to the LLVM copyright and licensing, developers agree to + assign their copyrights to UIUC for any contribution made so that + the entire software base can be managed by a single copyright holder. This + implies that any contributions can be licensed under the license that the + project uses.
++ +
+ + The LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/ExceptionHandling.html diff -c /dev/null llvm-www/releases/2.3/docs/ExceptionHandling.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/ExceptionHandling.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,478 ---- + + + +
+
|
+
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 + C/C++.
+ +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 + specification at Dwarf 3 + Standard. A description for the C++ exception table formats can be found at + Exception Handling + Tables.
+ +When an exception is thrown in llvm code, the runtime does a best effort to + find a handler suited to process the circumstance.
+ +The runtime first attempts to find an exception frame corresponding to + the function where the exception was thrown. If the programming language (ex. + C++) supports exception handling, the exception frame contains a reference to an + exception table describing how to process the exception. If the language (ex. + C) does not support exception handling 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.
+ +Since 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 (ex. for C++ __gxx_personality_v0) 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 to the code found in the catch portion of a + try/catch sequence. When execution resumes at a landing pad, it receives the + exception structure and a selector corresponding to the type of exception + thrown. The selector is then used to determine which catch should actually + process the exception.
+ +At the time of this writing, only C++ exception handling support is available + in LLVM. So the remainder of this document will be somewhat C++-centric.
+ +From the C++ developers 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.
+ +Languages that support exception handling typically provide a throw + operation to initiate the exception process. Internally, a throw operation + breaks down into two steps. First, 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. Second, a call is made to the runtime to raise the + exception, passing the exception structure as an argument.
+ +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 type info structure.
+ +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; where to continue when the call succeeds as per normal, and + where to continue if the call raises an exception, either by a throw or the + unwinding of a throw.
+ +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 a 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.
+ +Two llvm intrinsic functions are used convey information about the landing + pad to the back end.
+ +llvm.eh.exception takes no + arguments and returns the exception structure reference. The backend replaces + this intrinsic with the code that accesses the first argument of a call. The + LLVM C++ front end generates code to save this value in an alloca location for + further use in the landing pad and catch code.
+ +llvm.eh.selector takes a minimum of + three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function to be + used for this try catch sequence. Each of the remaining arguments is either a + reference to the type info for a catch statement, + a filter expression, + or the number zero representing a cleanup. + The exception is tested against the arguments sequentially from first to last. + The result of the llvm.eh.selector 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 behaviour of + the program is undefined. + The LLVM C++ front end generates code to save the selector value in an alloca + location for further use in the landing pad and catch code. + 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 info have been gathered in the backend, + the catch code will 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. Note: Since the landing + pad will not be used if there is no match in the list of type info on the call + to llvm.eh.selector, then neither the + last catch nor catch all need to perform the the check against the + selector.
+ +Finally, the entry and exit of catch code is bracketed with calls to + __cxa_begin_catch and __cxa_end_catch. + __cxa_begin_catch takes a exception structure reference as an argument + and returns the value of the exception object. __cxa_end_catch + takes a exception structure reference as an argument. This function clears the + exception from the exception space. Note: a rethrow from within the catch may + replace this call with a __cxa_rethrow.
+ +To handle destructors and cleanups in try code, control may not run directly + from a landing pad to the first catch. Control may actually flow from the + landing pad to clean up code and then to the first catch. Since the required + clean up for each invoke in a try may be different (ex., intervening + constructor), there may be several landing pads for a given try. If cleanups + need to be run, the number zero should be passed as the last + llvm.eh.selector argument. + However for C++ a null i8* must be passed + instead. +
+ +C++ allows the specification of which exception types that can 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 landing pad will call llvm.eh.selector. The arguments are the + length of the filter expression (the number of type infos plus one), followed by + the type infos themselves. + llvm.eh.selector 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 require a reference to the + exception structure.
+ +The semantics of the invoke instruction require that any exception that + unwinds through an invoke call should result in a branch to the invoke's unwind + label. However such a branch will only happen if the + llvm.eh.selector matches. + Thus in order to ensure correct operation, the front-end must only generate + llvm.eh.selector calls that are + guaranteed to always match whatever exception unwinds through the invoke. + For most languages it is enough to pass zero, indicating the presence of + a cleanup, as the last + llvm.eh.selector argument. + However for C++ this is not sufficient, because the C++ personality function + will terminate the program if it detects that unwinding the exception only + results in matches with cleanups. For C++ a null i8* should + be passed as the last + llvm.eh.selector argument instead. + This is interpreted as a catch-all by the C++ personality function, and will + always match. +
+ +LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to + provide exception handling information at various points in generated code.
+ ++ i8* %llvm.eh.exception( ) ++ +
This intrinsic indicates that the exception structure is available at this + point in the code. The backend will replace this intrinsic with code to fetch + the first argument of a call. The effect is that the intrinsic result is the + exception structure reference.
+ ++ i32 %llvm.eh.selector.i32(i8*, i8*, i8*, ...) + i64 %llvm.eh.selector.i64(i8*, i8*, i8*, ...) ++ +
This intrinsic indicates that the exception selector is available at this + point in the code. The backend will replace this intrinsic with code to fetch + the second argument of a call. The effect is that the intrinsic result is the + exception selector.
+ +llvm.eh.selector takes a minimum of + three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function to be + used for this try catch sequence. Each of the remaining arguments is either a + reference to the type info for a catch statement, + a filter expression, + or the number zero representing a cleanup. + The exception is tested against the arguments sequentially from first to last. + The result of the llvm.eh.selector 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 behaviour 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.
+ ++ i32 %llvm.eh.typeid.for.i32(i8*) + i64 %llvm.eh.typeid.for.i64(i8*) ++ +
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 llvm.eh.selector. The single argument is + a reference to a type info.
+ +There are two tables that are used by the exception handling runtime to + determine which actions should take place when an exception is thrown.
+ +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.
+ +Todo - Table details here.
+ +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 routines and functions that have + only calls to non-throwing functions will not need an exception table.
+ +Todo - Table details here.
+ +-
+
+
Testing/Testing/Testing.
+
+
+ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/ExtendingLLVM.html diff -c /dev/null llvm-www/releases/2.3/docs/ExtendingLLVM.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/ExtendingLLVM.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,391 ---- + + + +
-
+
- Introduction and Warning +
- Adding a new intrinsic function +
- Adding a new instruction +
- Adding a new SelectionDAG node +
- Adding a new type + +
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 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.
+ +-
+
- 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. + +
- 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. + +
- llvm/lib/Analysis/ConstantFolding.cpp: If it is possible to + constant fold your intrinsic, add support to it in the + canConstantFoldCallTo and ConstantFoldCall functions. + +
- llvm/test/Regression/*: Add test cases for your test cases to the + test suite +
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 C backend in lib/Target/CBackend/ + +
- Depending on the intrinsic, there are a few ways to implement this. For + most intrinsics, it makes sense to add code to lower your intrinsic in + LowerIntrinsicCall in lib/CodeGen/IntrinsicLowering.cpp. + Second, if it makes sense to lower the intrinsic to an expanded sequence of + C code in all cases, just emit the expansion in visitCallInst in + Writer.cpp. If the intrinsic has some way to express it with GCC + (or any other compiler) extensions, it can be conditionally supported based + on the compiler compiling the CBE output (see llvm.prefetch for an + example). Third, if the intrinsic really has no way to be lowered, just + have the code generator emit code that prints an error message and calls + abort if executed. + +
- 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. +
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).
+ +-
+
- include/llvm/CodeGen/SelectionDAGNodes.h: + Add an enum value for the new SelectionDAG node. +
- 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. +
- 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. +
- 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. +
- 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. +
- 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. + +
- 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. +
- 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. +
- 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. +
- TODO: document complex patterns. +
- 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. +
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.
+ +-
+
+
- llvm/include/llvm/Instruction.def: + add a number for your instruction and an enum name + +
- llvm/include/llvm/Instructions.h: + add a definition for the class that will represent your instruction + +
- llvm/include/llvm/Support/InstVisitor.h: + add a prototype for a visitor to your new instruction type + +
- llvm/lib/AsmParser/Lexer.l: + add a new token to parse your instruction from assembly text file + +
- llvm/lib/AsmParser/llvmAsmParser.y: + add the grammar on how your instruction can be read and what it will + construct as a result + +
- llvm/lib/Bitcode/Reader/Reader.cpp: + add a case for your instruction and how it will be parsed from bitcode + +
- llvm/lib/VMCore/Instruction.cpp: + add a case for how your instruction will be printed out to assembly + +
- llvm/lib/VMCore/Instructions.cpp: + implement the class you defined in + llvm/include/llvm/Instructions.h + +
- Test your instruction + +
- llvm/lib/Target/*: + Add support for your instruction to code generators, or add a lowering + pass. + +
- llvm/test/Regression/*: add your test cases to the test suite. + +
Also, you need to implement (or modify) any analyses or passes that you want + to understand this new instruction.
+ +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.
+ +-
+
+
- llvm/include/llvm/Type.h: + add enum for the new type; add static Type* for this type + +
- llvm/lib/VMCore/Type.cpp: + add mapping from TypeID => Type*; + initialize the static Type* + +
- llvm/lib/AsmReader/Lexer.l: + add ability to parse in the type from text assembly + +
- llvm/lib/AsmReader/llvmAsmParser.y: + add a token for that type + +
-
+
- llvm/include/llvm/Type.h: + add enum for the new type; add a forward declaration of the type + also + +
- llvm/include/llvm/DerivedTypes.h: + add new class to represent new class in the hierarchy; add forward + declaration to the TypeMap value type + +
- llvm/lib/VMCore/Type.cpp:
+ add support for derived type to:
+ ++ add necessary member functions for type, and factory methods
+ 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) +
+
+
+ - llvm/lib/AsmReader/Lexer.l: + add ability to parse in the type from text assembly + +
- llvm/lib/BitCode/Writer/Writer.cpp: + modify void BitcodeWriter::outputType(const Type *T) to serialize + your type + +
- llvm/lib/BitCode/Reader/Reader.cpp: + modify const Type *BitcodeReader::ParseType() to read your data + type + +
- llvm/lib/VMCore/AsmWriter.cpp:
+ modify
+ ++ to output the new derived type +
+ void calcTypeName(const Type *Ty, + std::vector<const Type*> &TypeStack, + std::map<const Type*,std::string> &TypeNames, + std::string & Result) +
+
+
+
+
+ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/FAQ.html diff -c /dev/null llvm-www/releases/2.3/docs/FAQ.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/FAQ.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,737 ---- + + + +
-
+
- License
+
-
+
- Why are the LLVM source code and the front-end distributed under different + licenses? +
- Does the University of Illinois Open Source License really qualify as an + "open source" license? +
- Can I modify LLVM source code and redistribute the modified source? +
- Can I modify LLVM source code and redistribute binaries or other tools + based on it, without redistributing the source? +
+
+ - Source code
+
-
+
- In what language is LLVM written? +
- How portable is the LLVM source code? +
+
+ - Build Problems
+
-
+
- When I run configure, it finds the wrong C compiler. +
- The configure script finds the right C compiler, but it uses the + LLVM linker from a previous build. What do I do? +
- When creating a dynamic library, I get a strange GLIBC error. +
- I've updated my source tree from Subversion, and now my build is trying + to use a file/directory that doesn't exist. +
- I've modified a Makefile in my source tree, but my build tree keeps using + the old version. What do I do? +
- I've upgraded to a new version of LLVM, and I get strange build + errors. +
- I've built LLVM and am testing it, but the tests freeze. +
- Why do test results differ when I perform different types of builds? +
- Compiling LLVM with GCC 3.3.2 fails, what should I do? +
- When I use the test suite, all of the C Backend tests fail. What is + wrong? +
- After Subversion update, rebuilding gives the error "No rule to make + target". +
- The llvmc program gives me errors/doesn't + work. +
+
+ - Source Languages
+
-
+
- What source languages are supported? +
- 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? +
- What support is there for higher level source + language constructs for building a compiler? +
- I don't understand the GetElementPtr + instruction. Help! +
- 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? + + +
- + When I compile code using the LLVM GCC front end, it complains that it + cannot find libcrtend.a. + + +
- + How can I disable all optimizations when compiling code using the LLVM GCC front end? + + +
- Can I use LLVM to convert C++ code to C code? + +
+
+ - Questions about code generated by the GCC front-end + + +
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.
+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. +
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:
+ +-
+
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.
+
+ 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.
+
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.
+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.
+llvmc is experimental and isn't really supported. We suggest + using llvm-gcc instead.
+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.
+In the stacker module is a compiler and runtime + library for the Stacker language, a "toy" language loosely based on Forth.
+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. There is, however, a mostly + implemented configuration-driven + compiler driver which simplifies the task + of running optimizations, linking, and executable generation.
++ 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: +
+-
+
- Make sure the CC and CXX environment variables contains the full path to + the LLVM GCC front end. + +
- Make sure that the regular C compiler is first in your PATH. + +
- Add the string "-Wl,-native" to your CFLAGS environment variable. +
+ 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. However, this is a good way to add + C++ support for a processor that does not otherwise have a C++ compiler. +
+ +Use commands like this:
+ +-
+
Compile your program as normal with llvm-g++:
+ +++ ++ % llvm-g++ x.cpp -o program +
+or:
+ +++ ++ % llvm-g++ a.cpp -c + % llvm-g++ b.cpp -c + % llvm-g++ a.o b.o -o program +
+With llvm-gcc3, this will generate program and program.bc. The .bc + file is the LLVM version of the program all linked together.
+
+ Convert the LLVM code to C code, using the LLC tool with the C + backend:
+ +++ % llc -march=c program.bc -o program.c +
+
+
+ Finally, compile the C file:
+ +++ % cc x.c +
+
+
+
Note that, by default, the C backend 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 correct but relatively + slow.
+ +Also note: this specific sequence of commands won't work if you use a + function defined in the C++ runtime library (or any other C++ library). To + access an external C++ library, you must 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 can compile the + libraries and your application into two different chunks of C code and link + them.
+ +What is this llvm.global_ctors and + _GLOBAL__I__tmp_webcompile... stuff that happens when I #include + <iostream>?
+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.
++ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html diff -c /dev/null llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/GCCFEBuildInstrs.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,284 ---- + + + + + +
This section describes how to acquire and build llvm-gcc 4.0 and 4.2, which are + based on the GCC 4.0.1/4.2.1 front-ends respectively. Both front-ends support C, + C++, Objective-C and Objective-C++. The 4.2 front-end also supports Ada and + Fortran to some extent. Note that the instructions for building these front-ends + are completely different (and much easier!) than those for building llvm-gcc3 in + the past.
+ +-
+
Retrieve the appropriate llvm-gcc4.x-y.z.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.0 code + for first time use:
+ +++ ++ svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk dst-directory +
+To check out the 4.2 code 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.
+
+ - 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 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:
+ +-
+
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.
+ 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.2 release + are gcc-4.2 and the + 2005 GNAT GPL Edition. + LLVM from subversion + also works with the + 2006 and 2007 GNAT GPL Editions. + 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 + 2005 GNAT GPL Edition) + and another which supports C++, see below.
+ 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).
+
Supposing appropriate compilers are available, llvm-gcc with Ada support can + be built on an x86-32 linux box using the following recipe:
+ +-
+
Download the LLVM source + and unpack it:
+ +++ +wget http://llvm.org/releases/2.2/llvm-2.2.tar.gz + tar xzf llvm-2.2.tar.gz + mv llvm-2.2 llvm
+or check out the + latest version from subversion:
+ +++svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
+
+
+ Download the + llvm-gcc-4.2 source + and unpack it:
+ +++ +wget http://llvm.org/releases/2.2/llvm-gcc4.2-2.2.source.tar.gz + tar xzf llvm-gcc4.2-2.2.source.tar.gz + mv llvm-gcc4.2-2.2.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
+
+
+ Make a build directory llvm-objects for llvm and make it the + current directory:
+ +++mkdir llvm-objects + cd llvm-objects
+
+
+ Configure LLVM (here it is configured to install into /usr/local):
+ +++ +../llvm/configure --prefix=/usr/local
+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
+
+
+ Build LLVM with checking enabled (use ENABLE_OPTIMIZED=1 to + build without checking):
+ +++make ENABLE_OPTIMIZED=0
+
+
+ Install LLVM (optional):
+ +++make install
+
+
+ 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
+
+
+ Configure llvm-gcc (here it is configured to install into /usr/local). + The --enable-checking flag turns on sanity checks inside the compiler. + If you omit it then LLVM must be built with make ENABLE_OPTIMIZED=1. + 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-shared --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-shared --disable-bootstrap --disable-multilib
+
+
+ Build and install the compiler:
+ +++make + make install
+
+
+ To build with support for Fortran, follow the directions in the top-level + README.LLVM file, adding ",fortran" to EXTRALANGS, for example:
+ ++ EXTRALANGS=,fortran ++
+ 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. +
++ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/GarbageCollection.html diff -c /dev/null llvm-www/releases/2.3/docs/GarbageCollection.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/GarbageCollection.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,1419 ---- + + + + +
-
+
- Introduction + + + +
- Using the collectors + + + +
- Core support + + + +
- Recommended runtime interface + + + +
- Implementing a collector plugin + + + +
- Implementing a collector runtime + + + +
- References + +
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 allocation + techniques dominates any low-level losses.
+ +This document describes the mechanisms and interfaces provided by LLVM to + support accurate garbage collection.
+ +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 implement a garbage collector. This is because + collectors are tightly coupled to object models, and LLVM is agnostic to object + models. Since LLVM is agnostic to object models, it would be inappropriate for + LLVM to dictate any particular collector. Instead, LLVM provides a framework for + garbage collector implementations in two manners:
+ +-
+
- At compile time with collector plugins for + the compiler. Collector plugins have ready access to important garbage + collector algorithms. Leveraging these tools, it is straightforward to + emit type-accurate stack maps for your runtime in as little as ~100 lines of + C++ code. + +
- At runtime with suggested runtime + interfaces, which allow front-end compilers to support a range of + collection runtimes. +
In general, using a collector implies:
+ +-
+
- Emitting compatible code, including initialization in the main + program if necessary. +
- Loading a compiler plugin if the collector is not statically linked with + your compiler. For llc, use the -load option. +
- Selecting the collection algorithm by applying the gc "..." + attribute to your garbage collected functions, or equivalently with + the setCollector method. +
- Linking your final executable with the garbage collector runtime. +
This table summarizes the available runtimes.
+ +| Collector | +gc attribute | +Linkage | +gcroot | +gcread | +gcwrite | +
|---|---|---|---|---|---|
| SemiSpace | +gc "shadow-stack" | +TODO FIXME | +required | +optional | +optional | +
| Ocaml | +gc "ocaml" | +provided by ocamlopt | +required | +optional | +optional | +
The sections for Collection intrinsics and + Recommended runtime interface detail the interfaces that + collectors may require user programs to utilize.
+ +The ShadowStack backend is invoked with the gc "shadow-stack" + function attribute. + Unlike many collectors which rely on a cooperative code generator to generate + stack maps, this algorithm carefully maintains a linked list of stack root + descriptors [Henderson2002]. This so-called "shadow + stack" mirrors the machine stack. Maintaining this data structure is slower + than using stack maps, but has a significant portability advantage because it + requires no special support from the target code generator.
+ +The ShadowStack collector does not use read or write barriers, so the user + program may use load and store instead of llvm.gcread + and llvm.gcwrite.
+ +ShadowStack is a code generator plugin only. It must be paired with a + compatible runtime.
+ +The SemiSpace runtime implements the suggested + runtime interface and is compatible with the ShadowStack backend.
+ +SemiSpace is a very simple copying collector. When it starts up, it + allocates two blocks of memory for the heap. It uses a simple bump-pointer + allocator to allocate memory from the first block until it runs out of space. + When it runs out of space, it traces through all of the roots of the program, + copying blocks to the other half of the memory space.
+ +This runtime is highly experimental and has not been used in a real project. + Enhancements would be welcomed.
+ +The ocaml backend is invoked with the gc "ocaml" function attribute. + It supports the + Objective Caml language runtime by emitting + a type-accurate stack map in the form of an ocaml 3.10.0-compatible frametable. + The linkage requirements are satisfied automatically by the ocamlopt + compiler when linking an executable.
+ +The ocaml collector does not use read or write barriers, so the user program + may use load and store instead of llvm.gcread and + llvm.gcwrite.
+ +This section describes the garbage collection facilities provided by the + LLVM intermediate representation.
+ +These facilities are limited to those strictly necessary for compilation. + They are not intended to be a complete interface to any garbage collector. + Notably, heap allocation is not among the supplied primitives. A user program + will also need to interface with the runtime, using either the + suggested runtime interface or another interface + specified by the runtime.
+ +The gc function attribute is used to specify the desired collector + algorithm to the compiler. It is equivalent to specifying the collector name + programmatically using the setCollector method of + Function.
+ +Specifying the collector on a per-function basis allows LLVM to link together + programs that use different garbage collection algorithms.
+ +The llvm.gcroot intrinsic is used to inform LLVM of a pointer + variable on the stack. 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.
+ +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 + ... ++ +
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 %nFor 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).
+ +Many important algorithms require write barriers, including generational + and concurrent collectors. Additionally, write barriers could be used to + implement reference counting.
+ +The use of this intrinsic is optional if the target collector does use + write barriers. If so, the collector will replace it with the corresponding + store.
+ ++
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).
+ +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.
+ +As with llvm.gcwrite, a target collector might not require the use + of this intrinsic.
+ +LLVM specifies the following recommended runtime interface to the garbage + collection at runtime. A program should use these interfaces to accomplish the + tasks not supported by the intrinsics.
+ +Unlike the intrinsics, which are integral to LLVM's code generator, there is + nothing unique about these interfaces; a front-end compiler and runtime are free + to agree to a different specification.
+ +Note: This interface is a work in progress.
+ ++ The llvm_gc_initialize function should be called once before any other + garbage collection functions are called. This gives the garbage collector the + chance to initialize itself and allocate the heap. The initial heap size to + allocate should be specified as an argument. +
+ +The llvm_gc_allocate function is a global function defined by the + garbage collector implementation to allocate memory. It returns a + zeroed-out block of memory of the specified size, sufficiently aligned to store + any object.
+ ++ The llvm_gc_collect function is exported by the garbage collector + implementations to provide a full collection, even when the heap is not + exhausted. This can be used by end-user code as a hint, and may be ignored by + the garbage collector. +
+ ++ The llvm_cg_walk_gcroots function is a function provided by the code + generator that iterates through all of the GC roots on the stack, calling the + specified function pointer with each record. For each GC root, the address of + the pointer and the meta-data (from the llvm.gcroot intrinsic) are provided. +
+User code specifies which collector plugin to use with the gc + function attribute or, equivalently, with the setCollector method of + Function.
+ +To implement a collector plugin, it is necessary to subclass + llvm::Collector, 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 emit + the assembly code for the collector's unique stack map data structure, which + might be accomplished in as few as 100 LOC.
+ +To subclass llvm::Collector and register a collector:
+ +// lib/MyGC/MyGC.cpp - Example LLVM collector plugin
+
+ #include "llvm/CodeGen/Collector.h"
+ #include "llvm/CodeGen/Collectors.h"
+ #include "llvm/CodeGen/CollectorMetadata.h"
+ #include "llvm/Support/Compiler.h"
+
+ using namespace llvm;
+
+ namespace {
+ class VISIBILITY_HIDDEN MyCollector : public Collector {
+ public:
+ MyCollector() {}
+ };
+
+ CollectorRegistry::Add<MyCollector>
+ X("mygc", "My bespoke garbage collector.");
+ }Using the LLVM makefiles (like the sample + project), this can be built into 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.soIt is also possible to statically link the collector plugin into tools, such + as a language-specific compiler front-end.
+ +The boilerplate collector above 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 stack map is emitted, and no safe points are added. +
Collector provides a range of features through which a plugin + collector may do useful work. This matrix summarizes the supported (and planned) + features and correlates them with the collection techniques which typically + require them.
+ +| Algorithm | +Done | +shadow stack | +refcount | +mark-sweep | +copying | +incremental | +threaded | +concurrent | +|
|---|---|---|---|---|---|---|---|---|---|
| stack map | +✔ | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| initialize roots | +✔ | +✘ | +✘ | +✘ | +✘ | +✘ | +✘ | +✘ | +|
| derived pointers | +NO | ++ | + | + | + | + | ✘* | +✘* | +|
| custom lowering | +✔ | ++ | + | + | + | + | + | + | |
| gcroot | +✔ | +✘ | +✘ | ++ | + | + | + | + | |
| gcwrite | +✔ | ++ | ✘ | ++ | + | ✘ | ++ | ✘ | +|
| gcread | +✔ | ++ | + | + | + | + | + | ✘ | +|
| safe points | ++ | + | + | + | + | + | + | + | |
| in calls | +✔ | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| before calls | +✔ | ++ | + | + | + | + | ✘ | +✘ | +|
| for loops | +NO | ++ | + | + | + | + | ✘ | +✘ | +|
| before escape | +✔ | ++ | + | + | + | + | ✘ | +✘ | +|
| emit code at safe points | +NO | ++ | + | + | + | + | ✘ | +✘ | +|
| output | ++ | + | + | + | + | + | + | + | |
| assembly | +✔ | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| JIT | +NO | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| obj | +NO | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| live analysis | +NO | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
| register map | +NO | ++ | + | ✘ | +✘ | +✘ | +✘ | +✘ | +|
|
+ * 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 root + descriptors. +
- 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.
+ +for (iterator I = begin(), E = end(); I != E; ++I) {
+ CollectorMetadata *MD = *I;
+ unsigned FrameSize = MD->getFrameSize();
+ size_t RootCount = MD->roots_size();
+
+ for (CollectorMetadata::roots_iterator RI = MD->roots_begin(),
+ RE = MD->roots_end();
+ RI != RE; ++RI) {
+ int RootNum = RI->Num;
+ int RootStackOffset = RI->StackOffset;
+ Constant *RootMetadata = RI->Metadata;
+ }
+ }LLVM automatically computes a stack map. All a Collector needs to do + is access it using CollectorMetadata::roots_begin() and + -end(). If the llvm.gcroot intrinsic is eliminated before code + generation by a custom lowering pass, LLVM's stack map will be empty.
+ +MyCollector::MyCollector() {
+ InitRoots = true;
+ }When set, LLVM will automatically initialize each root to null upon + entry to the function. This prevents the reachability analysis from finding + uninitialized values in stack roots at runtime, which will almost certainly + cause it to segfault. This initialization occurs before custom lowering, so the + two may be used together.
+ +Since LLVM does not yet compute liveness information, this feature should be + used by all collectors which do not custom lower llvm.gcroot, and even + some that do.
+ +For collectors with barriers or unusual treatment of stack roots, these + flags allow the collector to perform any required transformation on the LLVM + IR:
+ +class MyCollector : public Collector {
+ public:
+ MyCollector() {
+ 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 passes them on to a custom lowering + pass specified by the collector.
+ +LLVM's default action for each intrinsic is as follows:
+ +-
+
- llvm.gcroot: Pass through to the code generator to generate a + stack map. +
- 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 runOnFunction, and + that initializeCustomLowering has the same semantics as doInitialization(Module + &).
+ +The following can be used as a template:
+ +#include "llvm/Module.h"
+ #include "llvm/IntrinsicInst.h"
+
+ bool MyCollector::initializeCustomLowering(Module &M) {
+ return false;
+ }
+
+ bool MyCollector::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;
+ }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:
+ +MyCollector::MyCollector() {
+ 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) {
+ CollectorMetadata *MD = *I;
+ size_t PointCount = MD->size();
+
+ for (CollectorMetadata::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).
+ +LLVM allows a collector to print arbitrary assembly code before and after + the rest of a module's assembly code. From the latter callback, the collector + can print stack maps built by the code generator.
+ +Note that LLVM does not currently have analogous APIs to support code + generation in the JIT, nor using the object writers.
+ +class MyCollector : public Collector {
+ public:
+ virtual void beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+
+ virtual void finishAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI);
+ }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 + CollectorMetadata 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 MyCollector::beginAssembly(std::ostream &OS, AsmPrinter &AP,
+ const TargetAsmInfo &TAI) {
+ // Nothing to do.
+ }
+
+ void MyCollector::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) {
+ CollectorMetadata &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 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 (CollectorMetadata::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 (CollectorMetadata::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");
+ }
+ }
+ }
+ }
+ Implementing a garbage collector for LLVM is fairly straightforward. The + LLVM garbage collectors are provided in a form that makes them easy to link into + the language-specific runtime that a language front-end would use. They require + functionality from the language-specific runtime to get information about where pointers are located in heap objects.
+ +The implementation must include the + llvm_gc_allocate and + llvm_gc_collect functions. To do this, it will + probably have to trace through the roots + from the stack and understand the GC descriptors + for heap objects. Luckily, there are some example + implementations available. +
++ The three most common ways to keep track of where pointers live in heap objects + are (listed in order of space overhead required):
+ +-
+
- In languages with polymorphic objects, pointers from an object header are + usually used to identify the GC pointers in the heap object. This is common for + object-oriented languages like Self, Smalltalk, Java, or C#. + +
- If heap objects are not polymorphic, often the "shape" of the heap can be + determined from the roots of the heap or from some other meta-data [Appel89, Goldberg91, Tolmach94]. In this case, the garbage collector can + propagate the information around from meta data stored with the roots. This + often eliminates the need to have a header on objects in the heap. This is + common in the ML family. + +
- If all heap objects have pointers in the same locations, or pointers can be + distinguished just by looking at them (e.g., the low order bit is clear), no + book-keeping is needed at all. This is common for Lisp-like languages. +
The LLVM garbage collectors are capable of supporting all of these styles of + language, including ones that mix various implementations. To do this, it + allows the source-language to associate meta-data with the stack roots, and the heap tracing routines can propagate the + information. In addition, LLVM allows the front-end to extract GC information + in any form from a specific object pointer (this supports situations #1 and #3). +
+ +[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.
+ ++ +
+ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + + Index: llvm-www/releases/2.3/docs/GetElementPtr.html diff -c /dev/null llvm-www/releases/2.3/docs/GetElementPtr.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/GetElementPtr.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,370 ---- + + + + +
-
+
- Introduction +
- The Questions + +
- Summary +
This document seeks to dispel the mystery and confusion surrounding LLVM's + GetElementPtr (GEP) instruction. Questions about the wiley GEP instruction are + probably the most frequently occuring 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. +
+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. However, GEP is a little different and + this leads to the following questions; all of which are answered in the + following sections.
+ +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, indexs + 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 = unintialized 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.
+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 dispell the confusion:
+-
+
- 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. +
- Point #1 is evidenced by noticing the type of the first operand of + the GEP instruction (%MyStruct) which is + { float*, i32 }*. +
- 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. +
- The second index, i32 1 selects the second field of the + structure (the i32). +
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.
+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 = getlementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+ %idx2 = getlementptr { [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.
+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 = getlementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+ %idx2 = getlementptr { [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] }*.
+In summary, here's some things to always remember about the GetElementPtr + instruction:
+-
+
- The GEP instruction never accesses memory, it only provides pointer + computations. +
- The first operand to the GEP instruction is always a pointer and it must + be indexed. +
- There are no superfluous indices for the GEP instruction. +
- Trailing zero indices are superfluous for pointer aliasing, but not for + the types of the pointers. +
- Leading zero indices are not superfluous for pointer aliasing nor the + types of the pointers. +
+ +
+ + Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/GettingStarted.html diff -c /dev/null llvm-www/releases/2.3/docs/GettingStarted.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/GettingStarted.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,1649 ---- + + + + +
-
+
- Overview +
- Getting Started Quickly (A Summary) +
- Requirements + + +
- Getting Started with LLVM
+
-
+
- Terminology and Notation +
- Setting Up Your Environment +
- Unpacking the LLVM Archives +
- Checkout LLVM from Subversion +
- Install the GCC Front End +
- Local LLVM Configuration +
- Compiling the LLVM Suite Source Code +
- Cross-Compiling LLVM +
- The Location of LLVM Object Files +
- Optional Configuration Items +
+
+ - Program layout
+
-
+
- llvm/examples +
- llvm/include +
- llvm/lib +
- llvm/projects +
- llvm/runtime +
- llvm/test +
- llvm-test +
- llvm/tools +
- llvm/utils +
- llvm/win32 +
+
+ - An Example Using the LLVM Tool Chain + +
- Common Problems +
- Links +
Welcome to LLVM! In order to get started, you first need to know some + basic information.
+ +First, LLVM comes in two pieces. The first piece is the LLVM suite. This + contains all of the tools, libraries, and header files needed to use the low + level virtual machine. It contains an assembler, disassembler, bitcode + analyzer and bitcode optimizer. It also contains a test suite that can be + used to test the LLVM tools and the GCC front end.
+ +The second piece is the GCC front end. This component provides a version of + GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front + end uses the GCC parser to convert code to LLVM. Once + compiled into LLVM bitcode, a program can be manipulated with the LLVM tools + from the LLVM suite.
+ ++ There is a third, optional piece called llvm-test. It is a suite of programs + with a testing harness that can be used to further test LLVM's functionality + and performance. +
+ +Here's the short story for getting up and running quickly with LLVM:
+ +-
+
- Read the documentation. +
- Read the documentation. +
- Remember that you were warned twice about reading the documentation. +
- Install the llvm-gcc4.2 front end if you intend to compile C or C++:
+
-
+
- cd where-you-want-the-C-front-end-to-live +
- gunzip --stdout llvm-gcc.platform.tar.gz | tar -xvf - + +
- If the binary extension is ".bz" use bunzip2 instead of gunzip. +
- Add llvm-gcc's "bin" directory to your PATH variable. +
+
+ - Get the LLVM Source Code
+
-
+
- With the distributed files (or use SVN):
+
-
+
- cd where-you-want-llvm-to-live +
- gunzip --stdout llvm-version.tar.gz | tar -xvf - +
+
+
+
+ - With the distributed files (or use SVN):
+
- [Optional] Get the Test Suite Source Code
+
-
+
- With the distributed files (or use SVN):
+
-
+
- cd where-you-want-llvm-to-live +
- cd llvm/projects +
- gunzip --stdout llvm-test-version.tar.gz | tar -xvf - +
+
+
+
+
+ - With the distributed files (or use SVN):
+
- Configure the LLVM Build Environment
+
-
+
- cd where-you-want-to-build-llvm +
- /path/to/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).
+ - --with-llvmgccdir=directory
+
Optionally, specify for directory the full pathname of the + C/C++ front end installation to use with this LLVM configuration. If + not specified, the PATH will be searched.
+ - --enable-spec2000=directory
+
Enable the SPEC2000 benchmarks for testing. The SPEC2000 + benchmarks should be available in + directory.
+
- --prefix=directory
+
+
+ - Build the LLVM Suite:
+
-
+
- gmake -k |& tee gnumake.out + # this is csh or tcsh syntax +
- If you get an "internal compiler error (ICE)" or test failures, see + below. +
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 GCC front end and LLVM tools. Go to Program + Layout to learn about the layout of the source code tree.
+ +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.
+ +LLVM is known to work on the following platforms:
+ +| OS | +Arch | +Compilers | +
|---|---|---|
| Linux | +x861 | +GCC | +
| Solaris | +V9 (Ultrasparc) | +GCC | +
| FreeBSD | +x861 | +GCC | +
| MacOS X2 | +PowerPC | +GCC | +
| MacOS X2,9 | +x86 | +GCC | + +
| Cygwin/Win32 | +x861,8 | +GCC 3.4.X, binutils 2.15 | +
| MinGW/Win32 | +x861,6,8 | +GCC 3.4.X, binutils 2.15 | +
| Linux | +amd643 | +GCC | +
LLVM has partial support for the following platforms:
+ +| OS | +Arch | +Compilers | +
|---|---|---|
| Windows | +x861 | +Visual Studio .NET4,5 | +
| AIX3,4 | +PowerPC | +GCC | +
| Linux3,5 | +PowerPC | +GCC | +
| Linux7 | +Alpha | +GCC | +
| Linux7 | +Itanium (IA-64) | +GCC | +
| HP-UX7 | +Itanium (IA-64) | +HP aCC | +
Notes:
+ +-
+
- Code generation supported for Pentium processors and + up +
- Code generation supported for 32-bit ABI only +
- No native code generation +
- Build is not complete: one or more tools don't link +
- The GCC-based C/C++ frontend does not build +
- The port is done using the MSYS shell. + Download and install + bison (excl. M4.exe) and flex in that order. Build binutils-2.15 from source, + if necessary. Bison & flex can be also grabbed from GNUWin32 sf.net + project. +
- Native code generation exists but is not complete. +
- Binutils up to post-2.17 has bug in bfd/cofflink.c + preventing LLVM from building correctly. Several workarounds have been + introduced into LLVM build system, but the bug can occur anytime in the + future. We highly recommend that you rebuild your current binutils with the + patch from + Binutils bugzilla, if it wasn't already applied. +
- XCode 2.5 and gcc 4.0.1 (Apple Build 5370) will trip + internal LLVM assert messages when compiled for Release at optimization + levels greater than 0 (i.e., “-O1” and higher). + Add OPTIMIZE_OPTION="-O0" to the build command line + if compiling for LLVM Release or bootstrapping the LLVM toolchain. +
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 disable them individually in llvm/tools/Makefile. 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.
+ +The GCC front end is not very portable at the moment. If you want to get it + to work on another platform, you can download a copy of the source and try to compile it on your platform.
+ +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.
+| Package | Version | Notes |
|---|---|---|
| GNU Make | +3.79, 3.79.1 | +Makefile/build processor | +
| GCC | +3.4.2 | +C/C++ compiler1 | +
| TeXinfo | +4.5 | +For building the CFE | +
| Flex | +2.5.4 | +LEX compiler | +
| Bison | +1.28, 1.35, 1.75, 1.875d, 2.0, or 2.1 (not 1.85 or 1.875) |
+ YACC compiler | +
| SVN | +≥1.3 | +Subversion access to LLVM2 | +
| DejaGnu | +1.4.2 | +Automated test suite3 | +
| tcl | +8.3, 8.4 | +Automated test suite3 | +
| expect | +5.38.0 | +Automated test suite3 | +
| perl | +≥5.6.0 | +Nightly tester, utilities | +
| GNU M4 + | 1.4 | +Macro processor for configuration4 | +
| GNU Autoconf | +2.59 | +Configuration script builder4 | +
| GNU Automake | +1.9.2 | +aclocal macro generator4 | +
| libtool | +1.5.10 | +Shared library manager4 | +
Notes:
+-
+
- Only the C and C++ languages are needed so there's no + need to build the other languages for LLVM's purposes. See + below for specific version info. +
- You only need Subversion if you intend to build from the + latest LLVM sources. If you're working from a release distribution, you + don't need Subversion. +
- Only needed if you want to run the automated test + suite in the llvm/test directory. +
- If you want to make changes to the configure scripts, + you will need GNU autoconf (2.59), and consequently, GNU M4 (version 1.4 + or higher). You will also need automake (1.9.2). We only use aclocal + from that package. +
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 +
LLVM is very demanding of the host C++ compiler, and as such tends to expose + bugs in the compiler. In particular, several versions of GCC crash when trying + to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1 + successfully with them (however, see important notes below). Other versions + of GCC will probably work as well. GCC versions listed + here are known to not work. If you are using one of these versions, please try + to upgrade your GCC to something more recent. If you run into a problem with a + version of GCC not listed here, please 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. Please upgrade + to a newer version if possible.
+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.
+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).
+ +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.
+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).
+
+ + - LLVMGCCDIR +
-
+ This is where the LLVM GCC Front End is installed.
+
+ For the pre-built GCC front end binaries, the LLVMGCCDIR is + llvm-gcc/platform/llvm-gcc. +
+ 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. +
+ 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-gcc4-x.y.source.tar.gz +
- Source release of the llvm-gcc4 front end. See README.LLVM in the root
+ directory for build instructions.
- llvm-gcc4-x.y-platform.tar.gz +
- Binary release of the llvm-gcc4 front end for a specific platform.
It is also possible to download the sources of the llvm-gcc4 front end from a + read-only subversion mirror at + svn://anonsvn.opensource.apple.com/svn/llvm/trunk.
+ +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 Subvresion 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 at 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.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 llvm-test ++
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.
+ +If you would like to get the GCC front end source code, you can also get it + and build it yourself. Please follow these + instructions to successfully get and build the LLVM GCC front-end.
+ +Before configuring and compiling the LLVM suite, you can optionally extract the + LLVM GCC front end from the binary distribution. It is used for running the + llvm-test testsuite and for compiling C/C++ programs. Note that you can optionally + build llvm-gcc yourself after building the + main LLVM repository.
+ +To install the GCC front end, do the following:
+ +-
+
- cd where-you-want-the-front-end-to-live +
- gunzip --stdout llvmgcc-version.platform.tar.gz | tar -xvf + - +
Once the binary is uncompressed, you should add a symlink for llvm-gcc and + llvm-g++ to some directory in your path. When you configure LLVM, it will + automatically detect llvm-gcc's presence (if it is in your path) enabling its + use in llvm-test. Note that you can always build or install llvm-gcc at any + pointer after building the main LLVM repository: just reconfigure llvm and + llvm-test will pick it up. +
+ +The binary versions of the GCC front end may not suit all of your needs. For + example, the binary distribution may include an old version of a system header + file, not "fix" a header file that needs to be fixed for GCC, or it may be + linked with libraries not available on your system.
+ +In cases like these, you may want to try building the GCC front end from source. This is + much easier now than it was in the past.
+ +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:
+ +| Variable | Purpose |
|---|---|
| CC | +Tells 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. | +
| CXX | +Tells 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:
+ +-
+
- --with-llvmgccdir +
- Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration. + The value of this option should specify the full pathname of the C/C++ Front + End to be used. If this option is not provided, the PATH will be searched for + a program named llvm-gcc and the C/C++ FrontEnd install directory will + be inferred from the path found. If the option is not given, and no llvm-gcc + can be found in the path then a warning will be produced by + configure indicating this situation. LLVM may still be built with + the tools-only target but attempting to build the runtime libraries + will fail as these libraries require llvm-gcc and llvm-g++. See + Install the GCC Front End for details on installing + the C/C++ Front End. See + Bootstrapping the LLVM C/C++ Front-End + for details on building the C/C++ Front End. +
- --with-tclinclude +
- Path to the tcl include directory under which tclsh can be
+ found. Use this if you have multiple tcl installations on your machine and you
+ want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the
+ dejagnu based test suite in llvm/test. If you don't specify this
+ option, the LLVM configure script will search for the tcl 8.4 and 8.3
+ releases.
+
+
+ - --enable-optimized +
-
+ Enables optimized compilation by default (debugging symbols are removed
+ and GCC optimization flags are enabled). The default 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:
+ alpha, ia64, powerpc, skeleton, sparc, x86. +
+ - --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:
+ +-
+
Change directory into the object root directory:
+ +% cd OBJ_ROOT
+
+ Run the configure script located in the LLVM source + tree:
+ ++% SRC_ROOT/configure --prefix=/install/path [other options]
+
+
Once you have configured LLVM, you can build it. There are three types of + builds:
+ +-
+
- Debug Builds +
-
+ These builds are the default when one types gmake (unless the
+ --enable-optimized option was used during configuration). The
+ build system will compile the tools and libraries with debugging
+ information.
+
+ + - 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.
+
+ + - 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_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.
+ +It is possible to cross-compile LLVM. That is, you can create LLVM + executables and libraries for a platform different than the one one which you + are compiling. To do this, a few additional steps are + required. 1 To cross-compile LLVM, use + these instructions:
+-
+
- Configure and build LLVM as a native compiler. You will need
+ just TableGen from that build.
+
-
+
- If you have $LLVM_OBJ_ROOT=$LLVM_SRC_ROOT just execute + make -C utils/TableGen after configuring. +
- Otherwise you will need to monitor building process and terminate + it just after TableGen was built. +
+ - Copy the TableGen binary to somewhere safe (out of your build tree). + +
- Configure LLVM to build with a cross-compiler. To do this, 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. +
- Put the saved TableGen executable into the + into $LLVM_OBJ_ROOT/{BUILD_TYPE}/bin directory (e.g. into + .../Release/bin for a Release build). +
- Build LLVM as usual. +
The result of such a build will produce executables that are not executable + on your build host (--build option) but can be executed on your compile host + (--host option).
+Notes:
+-
+
- Cross-compiling was tested only with Linux as + build platform and Windows as host using mingw32 cross-compiler. Other + combinations have not been tested. +
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 +
-
+
-
+
- Tools +
- OBJ_ROOT/Debug/bin +
- Libraries +
- OBJ_ROOT/Debug/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 +
+ 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::llvm::/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. Thanks to Jack + Cummings for pointing this out! +
+ +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:
+ +This directory contains some simple examples of how to use the LLVM IR and + JIT.
+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. +
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/CBackend implements the LLVM-to-C converter. + +
- llvm/lib/CodeGen/ +
- This directory contains the major parts of the code generator: Instruction + Selector, Instruction Scheduling, and Register Allocation. + +
- 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/Support/. + +
- llvm/lib/System/ +
- This directory contains the operating system abstraction layer that + shields LLVM from platform-specific coding. +
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. See llvm/projects/Stacker for a fully + functional example of a compiler front end.
+This directory contains libraries which are compiled into LLVM bitcode and + used when linking programs with the GCC front end. Most of these libraries are + skeleton versions of real libraries; for example, libc is a stripped down + version of glibc.
+ +Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front + end to compile.
+ +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.
+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.
+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. + +
- llvmc +
- The LLVM Compiler Driver. This program can + be configured to utilize both LLVM and non-LLVM compilation tools to enable + pre-processing, translation, optimization, assembly, and linking of programs + all from one command line. llvmc also takes care of processing the + dependent libraries found in bitcode. This reduces the need to get the + traditional -l<name> options right on the command line. Please + note that this tool, while functional, is still experimental and not feature + complete. + +
- 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. + This is the linker invoked by llvmc. It performsn 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.
+
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.
+ + - NewNightlyTest.pl and + NightlyTestTemplate.html
- These files are used in a
+ cron script to generate nightly status reports of the functionality of
+ tools, and the results can be seen by following the appropriate link on
+ the LLVM homepage.
+ + - 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.
+ +
This directory contains build scripts and project files for use with + Visual C++. This allows developers on Windows to build LLVM without the need + for Cygwin. The contents of this directory should be considered experimental + at this time. +
+This section gives an example of using LLVM. llvm-gcc3 is now obsolete, + so we only include instructiosn for llvm-gcc4. +
+ +Note: The gcc4 frontend's invocation is considerably different + from the previous gcc3 frontend. In particular, the gcc4 frontend does not + create bitcode by default: gcc4 produces native code. As the example below illustrates, + the '--emit-llvm' flag is needed to produce LLVM bitcode output. For makefiles and + configure scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode + output.
+-
+
First, create a simple C file, name it 'hello.c':
+ +++ #include <stdio.h> + + int main() { + printf("hello world\n"); + return 0; + } +
+
+ Next, compile the C file into a native executable:
+ ++ +% llvm-gcc hello.c -o hello
Note that llvm-gcc works just like GCC by default. The standard -S and + -c arguments work as usual (producing a native .s or .o file, + respectively).
+
+ Next, compile the C file into a LLVM bitcode file:
+ +++ +% llvm-gcc -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.
+ +Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. +
+
+ 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.
+
+ Use the llvm-dis utility to take a look at the LLVM assembly + code:
+ ++llvm-dis < hello.bc | less
+
+
+ Compile the program to native assembly using the LLC code + generator:
+ +% llc hello.bc -o hello.s
+
+ 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 +
+
+
+ Execute the native code program:
+ ++ +% ./hello.native
Note that using llvm-gcc to compile directly to native code (i.e. when + the -emit-llvm option is not present) does steps 6/7/8 for you.
+
+
+
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.
+ +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:
+ + + ++ +
+ + Reid Spencer
+ The LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/GettingStartedVS.html diff -c /dev/null llvm-www/releases/2.3/docs/GettingStartedVS.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/GettingStartedVS.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,380 ---- + + + + +
-
+
- Overview +
- Getting Started Quickly (A Summary) +
- Requirements + + +
- Getting Started with LLVM + + +
- An Example Using the LLVM Tool Chain +
- Common Problems +
- Links +
The Visual Studio port at this time is experimental. It is suitable for + use only if you are writing your own compiler front end or otherwise have a + need to dynamically generate machine code. The JIT and interpreter are + functional, but it is currently not possible to generate assembly code which + is then assembled into an executable. You can indirectly create executables + by using the C back end.
+ +To emphasize, there is no C/C++ front end currently available. + llvm-gcc is based on GCC, which cannot be bootstrapped using VC++. + Eventually there should be a llvm-gcc based on Cygwin or MinGW that + is usable. There is also the option of generating bitcode files on Unix and + copying them over to Windows. But be aware the odds of linking C++ code + compiled with llvm-gcc with code compiled with VC++ is essentially + zero.
+ +The LLVM test suite cannot be run on the Visual Studio port at this + time.
+ +Most of the tools build and work. llvm-db does not build at this + time. 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.
+ +Here's the short story for getting up and running quickly with LLVM:
+ +-
+
- Read the documentation. +
- Seriously, read the documentation. +
- Remember that you were warned twice about reading the documentation. + +
- Get the Source Code
+
-
+
- With the distributed files:
+
-
+
- cd where-you-want-llvm-to-live +
- gunzip --stdout llvm-version.tar.gz | tar -xvf - + or use WinZip +
- cd llvm +
+
+ - With anonymous Subversion access:
+
-
+
- cd where-you-want-llvm-to-live +
- svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top + +
- make checkout MODULE=llvm +
- cd llvm +
+
+
+ - With the distributed files:
+
- Start Visual Studio
+
-
+
- Simply double click on the solution file llvm/win32/llvm.sln. + +
+
+ - Build the LLVM Suite:
+
-
+
- Simply build the solution. +
- The Fibonacci project is a sample program that uses the JIT. Modify + the project's debugging properties to provide a numeric command line + argument. The program will print the corresponding fibonacci value. +
+
+
It is strongly encouraged that you get the latest version from Subversion as + changes are continually making the VS support better.
+ +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.
+ +Any system that can adequately run Visual Studio .NET 2003 is fine. The + LLVM source tree and object files, libraries and executables will consume + approximately 3GB.
+ +You will need Visual Studio .NET 2003. Earlier versions cannot open the + solution/project files. The VS 2005 beta can, but will migrate these files + to its own format in the process. While it should work with the VS 2005 + beta, there are no guarantees and there is no support for it at this time. + It has been reported that VC++ Express also works.
+ +If you plan to modify any .y or .l files, you will need to have bison + and/or flex installed where Visual Studio can find them. Otherwise, you do + not need them and the pre-generated files that come with the source tree + will be used.
+ ++ Do not install the LLVM directory tree into a path containing spaces (e.g. + C:\Documents and Settings\...) as the configure step will fail.
+ +The remainder of this guide is meant to get you up and running with + LLVM using Visual Studio and to give you some basic information about the LLVM + environment.
+ +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 is + fixed at SRC_ROOT/win32).
+
The object files are placed under OBJ_ROOT/Debug for debug builds + and OBJ_ROOT/Release for release (optimized) builds. These include + both executables and libararies that your application can link against.
+ +The files that configure would create when building on Unix are + created by the Configure project and placed in + OBJ_ROOT/llvm. You application must have OBJ_ROOT in its include + search path just before SRC_ROOT/include.
+ +-
+
First, create a simple C file, name it 'hello.c':
+ +++ #include <stdio.h> + int main() { + printf("hello world\n"); + return 0; + } +
+
+ Next, compile the C file into a LLVM bitcode file:
+ +++ ++ % llvm-gcc -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.
+ +Note: while you cannot do this step on Windows, you can do it on a + Unix system and transfer hello.bc to Windows. Important: + transfer as a binary file!
+
+ Run the program using the just-in-time compiler:
+ +++ ++ % lli hello.bc +
+Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that + won't be satisfied by the Microsoft runtime libraries.
+
+ Use the llvm-dis utility to take a look at the LLVM assembly + code:
+ +++ % llvm-dis < hello.bc | more +
+
+
+ Compile the program to C using the LLC code generator:
+ +++ % llc -march=c hello.bc +
+
+
+ Compile to binary using Microsoft C:
+ +++ ++ % cl hello.cbe.c +
+Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that + won't be satisfied by the Microsoft runtime libraries.
+
+ Execute the native code program:
+ +++ % hello.cbe.exe +
+
+
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.
+ +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:
+ + + ++ +
+ + The LLVM Compiler Infrastructure
+ Last modified: $Date: 2008/06/09 08:20:32 $ + + + Index: llvm-www/releases/2.3/docs/HowToReleaseLLVM.html diff -c /dev/null llvm-www/releases/2.3/docs/HowToReleaseLLVM.html:1.1 *** /dev/null Mon Jun 9 03:21:47 2008 --- llvm-www/releases/2.3/docs/HowToReleaseLLVM.html Mon Jun 9 03:20:32 2008 *************** *** 0 **** --- 1,608 ---- + + + +
+ This document collects information about successfully releasing LLVM to the + public. It is the release manager's guide to ensuring that a high quality + build of LLVM is released. +
+ ++ The following is the basic criteria for releasing LLVM: +
+ +-
+
- Successful configure and build. +
- Clean 'make check'. +
- No regressions in the testsuite from the previous release. This may + include performance regressions for major benchmarks. +
-
+
- Set code freeze and branch creation date for 3 months after last release + date. Announce release schedule to the LLVM community and update the website. +
- Create release branch and begin release process. +
- Send out pre-release for first round of testing. Testing will last 7-10 days. + During the first round of testing, regressions should be found and fixed. Patches + are merged from mainline to the release branch. +
- Generate and send out second pre-release. Bugs found during this time will + not be fixed unless absolutely critical. Bugs introduce by patches merged in + will be fixed and if so, a 3rd round of testing is needed. +
- The release notes should be updated during the first and second round of + pre-release testing. +
- Finally, release! +
-
+
- Create Release Branch +
- Update LLVM Version +
- Build the LLVM Source Distributions +
- Build LLVM +
- Build the LLVM GCC Binary Distribution +
- Build RPM Packages (optional) +
- Run 'make check' +
- Run LLVM Test Suite +
- Pre-Release Testing +
- Tag the LLVM Release Branch +
- Update Documentation +
- Update the LLVM Demo Page +
- Update the LLVM Website +
- Announce the Release + +
Branch the Subversion HEAD using the following procedure:
+-
+
-
+
Verify that the current Subversion HEAD is in decent shape by examining nightly + tester results.
+ -
+
Request all developers to refrain from committing. Offenders get commit + rights taken away (temporarily).
+ -
+
Create the release branch for llvm, llvm-gcc4.0, + llvm-gcc4.2, and the test-suite. The + branch name will be release_XX, where XX is the major and + minor release numbers. These branches can be created without checking out + anything from subversion. +
+ +++ ++ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \ + https://llvm.org/svn/llvm-project/llvm/branches/release_XX + svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk \ + https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX + svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \ + https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX + svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ + https://llvm.org/svn/llvm-project/test-suite/branches/release_XX +
+ -
+
Advise developers they can work on Subversion HEAD again.
+
+ -
+
The Release Manager should switch to the release branch (as all changes + to the release will now be done in the branch). The easiest way to do this + is to grab another working copy using the following commands:
+ +++ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XX + svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX + svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX + svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX +
+
+
+
+